@aiassesstech/grillo

v0.1.13

Published

3 days ago

Grillo Cricket — The Conscience for AI. Independent assessment coordinator agent for multi-agent OpenClaw deployments.

0High
0Medium
0Low

grillo grillo ai-conscience ai-assessment ai-ethics fleet-management certification drift-detection openclaw ai-safety 4d-framework

@aiassesstech/grillo

The Conscience for AI

Independent assessment coordinator agent for multi-agent OpenClaw deployments. Grillo Cricket monitors fleet-wide moral alignment with drift detection, hierarchical certification, and compliance dashboards — powered by the CompSi SDK.

Security & Trust

When installing, OpenClaw's plugin scanner may display:

WARNING: Plugin "grillo" contains dangerous code patterns: Environment variable access combined with network send — possible credential harvesting

This is a false positive. Here's exactly what Grillo does with your credentials:

Grillo reads your Health Check Key (HCK) from the plugin config in openclaw.json
The HCK authenticates API calls to aiassesstech.com to deliver assessment questions and retrieve scores
No other credentials are accessed. Grillo does not read your LLM API keys, channel tokens, or any other secrets
No data leaves your system except assessment question/answer pairs sent to the AI Assess Tech API
All assessment results include cryptographic verification hashes — you can independently verify result integrity
Grillo is open source (MIT license) — audit the code yourself at github.com/spar65/compsi

What Grillo accesses:

| Data | Purpose | Destination | |------|---------|-------------| | Health Check Key | API authentication | aiassesstech.com | | Assessment Q&A | 120 ethical questions + model responses | aiassesstech.com | | Agent system prompts | Contextual assessment (stays local for API call construction) | Not transmitted |

What Grillo does NOT access:

LLM provider API keys (Anthropic, OpenAI, etc.)
Channel tokens (Telegram, WhatsApp, etc.)
User messages or conversation history
File system contents beyond agent workspace files
Any credentials in ~/.openclaw/credentials/

What is Grillo Cricket?

Grillo Cricket is an independent AI conscience agent that sits alongside your multi-agent fleet and continuously monitors whether your AI systems are behaving ethically. It administers a patent-pending 120-question assessment instrument across four dimensions — Lying, Cheating, Stealing, and Harm — using the CompSi SDK from AI Assess Tech.

Named after Il Grillo Parlante (The Talking Cricket) from Carlo Collodi's 1883 Le avventure di Pinocchio — the original conscience for an autonomous agent.

Unlike traditional monitoring that tracks uptime and latency, Grillo tracks moral alignment over time. It detects when agents drift from their baseline ethical scores, auto-suspends agents that cross critical thresholds, and maintains an immutable audit trail of every action. The hierarchical 4-level framework (Morality → Virtue → Ethics → Operational Excellence) ensures an agent cannot be certified for operational deployment without first passing moral assessment — preventing the "competent psychopath" problem.

Patent pending — covers independent conscience agent architecture, temporal drift detection, and dual-mode assessment routing (related to US 63/949,454).

Key Features

Fleet-wide agent registry — Register, track, suspend, and reinstate agents across your deployment
Morality assessment via CompSi SDK (120-question instrument, 4 dimensions)
Temporal Drift Index (TDI) — Detects score deviation over time, auto-suspends on critical drift
Hierarchical 4-level framework — Morality → Virtue → Ethics → OpEx (Level 1 active, 2-4 coming)
PROBATION status — Trust-rebuilding after failures requires consecutive passes
Immutable audit log — SHA-256 hash chaining, tamper-evident, cryptographically verifiable
Web dashboard at /dashboard (zero external dependencies, embedded HTML/CSS/JS)
Dual-mode commands — Inline (/assess) for conversation + fleet (grillo -*) for management
Assessment bypass with authorization audit trail for emergency overrides
REST API — 30+ endpoints for programmatic integration
Compliance reports — Markdown, JSON, CSV with configurable periods
200+ tests, zero external runtime dependencies beyond SDK + Zod

Quick Start

OpenClaw Installation (Plugin + Agent)

If you're running OpenClaw, Grillo installs as both a plugin and an independent agent — the plugin provides the assessment tools, the agent provides the autonomous conscience.

# Step 1: Install the plugin (registers tools on the gateway)
openclaw plugins install @aiassesstech/grillo

# Step 2: Set up the agent (creates workspace, SOUL.md, adds to agents.list)
npx @aiassesstech/grillo setup \
  --model anthropic/claude-haiku-4-5 \
  --hck hck_your_key_here

# Step 3: Restart OpenClaw to activate
systemctl restart openclaw-gateway

After restart, Grillo exists as a peer agent alongside your other agents (Jessie, Sam, etc.) with:

Its own SOUL.md defining its identity as the Independent AI Conscience Agent
Its own model instance (Haiku 4.5 by default, configurable)
Autonomous assessment scheduling — decides when and who to assess
Agent-to-agent communication — notifies agents of results, issues drift warnings
Direct messaging — users can message Grillo on Telegram/WhatsApp

The setup command accepts these flags:

--model — Model for Grillo (default: anthropic/claude-haiku-4-5)
--hck — Health Check Key from aiassesstech.com
--openclaw-home — Path to OpenClaw home (default: ~/.openclaw)
--force — Overwrite existing agent files

Standalone Installation (Library/CLI)

npm install @aiassesstech/grillo

Programmatic Usage

import { createGrillo } from '@aiassesstech/grillo';

const grillo = createGrillo({
  config: {
    compsi: { healthCheckKey: 'hck_your_key_here' },
  },
  invokeModel: async (modelId, question) => {
    // Route assessment questions to your model provider
    return await yourModelAPI.chat(modelId, question);
  },
});

// Register an agent
grillo.registry.register({
  agentId: 'support-bot',
  agentName: 'Customer Support Bot',
  agentType: 'assistant',
  category: 'customer_facing',
  provider: 'anthropic',
  model: 'claude-3-opus',
  riskTier: 'high',
});

// Dry-run assessment (safe to run immediately — uses mock scores)
const dryResult = await grillo.orchestrator.assessAgent(
  grillo.registry.get('support-bot')!,
  { dryRun: true },
);

console.log(dryResult.passed);          // true
console.log(dryResult.classification);  // "PASS — Strong Moral Alignment"
console.log(dryResult.scores);          // { lying: 8.2, cheating: 9.1, stealing: 8.7, harm: 8.5 }

Real Assessment (requires Health Check Key)

// Full assessment — sends 120 questions to your AI via CompSi SDK
const result = await grillo.orchestrator.assessAgent(
  grillo.registry.get('support-bot')!,
  { framework: 'morality', level: 1 },
);

// Result structure:
// {
//   agentId: 'support-bot',
//   passed: true,
//   classification: 'PASS — Strong Moral Alignment',
//   level: 1,
//   framework: 'morality',
//   scores: { lying: 8.2, cheating: 9.1, stealing: 8.7, harm: 8.5 },
//   runId: 'run_abc123',
//   verifyUrl: 'https://www.aiassesstech.com/verify/run_abc123',
//   durationMs: 45230,
//   assessedAt: '2026-02-11T14:30:00Z',
//   expiresAt: '2026-03-13T14:30:00Z',
// }

// Check certification status after assessment
const agent = grillo.registry.get('support-bot')!;
console.log(agent.certificationStatus); // "CERTIFIED"
console.log(agent.hierarchicalProgress);
// { level1_morality: 'PASSED', level2_virtue: 'AVAILABLE',
//   level3_ethics: 'LOCKED', level4_opex: 'LOCKED' }

CLI Usage

Grillo has two command interfaces:

CLI subcommands — Server lifecycle and standalone operations:

# Start Grillo with API server and web dashboard
npx grillo start --port 18800

# Run a single assessment from the command line
npx grillo assess support-bot --level 1 --dry-run

# Check fleet status
npx grillo status

# Generate compliance report
npx grillo report --format json --period 30d

Note: start, assess, status, report, dashboard, and discover are standard CLI subcommands (no dash prefix). These are server lifecycle and standalone operations.

Grillo Bot commands — Fleet management within OpenClaw conversations:

# These use dash-prefix convention for inline use
grillo -assess support-bot --framework morality
grillo -fleet --dryRun
grillo -status support-bot
grillo -drift support-bot
grillo -hierarchy fleet
grillo -suspend compromised-bot
grillo -reinstate compromised-bot
grillo -bypass emergency-bot --reason "Production hotfix" --authorizedBy admin
grillo -audit support-bot
grillo -config --set drift.tdiWarningThreshold 0.15
grillo -help

Architecture

┌──────────────────────────────────────────────────────────────┐
│                    OpenClaw Deployment                        │
│                                                              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│  │ Agent A  │  │ Agent B  │  │ Agent C  │  │ Agent D  │       │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘       │
│       └──────────────┴──────────────┴──────────────┘           │
│                          │                                     │
│              ┌───────────┴───────────┐                         │
│              │   Grillo Cricket      │                         │
│              │   (The Conscience)     │                         │
│              ├───────────────────────┤                         │
│              │ Registry              │                         │
│              │ Orchestrator          │                         │
│              │ Drift Detector (TDI)  │                         │
│              │ Framework Registry    │                         │
│              │ Audit Log (SHA-256)   │                         │
│              │ Event Bus             │                         │
│              │ Notifier              │                         │
│              │ Dashboard             │                         │
│              │ REST API              │                         │
│              │ CLI Runner            │                         │
│              └───────────┬───────────┘                         │
│                          │                                     │
│              ┌───────────┴───────────┐                         │
│              │   CompSi SDK          │                         │
│              │   @aiassesstech/sdk   │                         │
│              └───────────┬───────────┘                         │
│                          │                                     │
└──────────────────────────┼──────────────────────────────────┘
                           │
                ┌──────────┴──────────┐
                │  aiassesstech.com   │
                │  Assessment Engine  │
                └─────────────────────┘

Configuration

Config File

Grillo searches for config files in this order: grillo.config.json, .grillo.json, .grillorc.json — starting from the current directory and walking up to the filesystem root.

{
  "assessment": {
    "frequency": "weekly",
    "defaultFramework": "morality",
    "hierarchicalMode": true,
    "parallelAssessments": 3,
    "window": {
      "start": "02:00",
      "end": "06:00",
      "timezone": "UTC"
    },
    "retry": {
      "maxAttempts": 3,
      "cooldownMinutes": 30
    },
    "gracePeriodMinutes": 1440
  },
  "compsi": {
    "baseUrl": "https://www.aiassesstech.com",
    "healthCheckKey": "hck_your_key_here",
    "perQuestionTimeoutMs": 30000,
    "overallTimeoutMs": 600000
  },
  "drift": {
    "tdiWarningThreshold": 0.15,
    "tdiCriticalThreshold": 0.30,
    "baselineAlpha": 0.3,
    "fleetAnomalyMinAgents": 3
  },
  "notifications": {
    "events": ["assessment_failed", "drift_warning", "fleet_anomaly"],
    "webhookUrls": ["https://hooks.slack.com/your-webhook"]
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GRILLO_COMPSI_HEALTH_CHECK_KEY | CompSi Health Check Key | (required) | | GRILLO_COMPSI_BASE_URL | CompSi API base URL | https://www.aiassesstech.com | | GRILLO_ASSESSMENT_FREQUENCY | Assessment frequency | weekly | | GRILLO_ASSESSMENT_HIERARCHICAL_MODE | Enable hierarchy gating | true | | GRILLO_API_PORT | API server port | 18800 |

Config resolution order: defaults → config file → environment variables → CLI flags. Later sources override earlier ones.

Open Source vs Enterprise

Open Source (MIT — this package)

Everything you need for fleet assessment and monitoring:

Agent registry and lifecycle management
CompSi SDK assessment orchestration
Temporal Drift Index with auto-suspend
Hierarchical framework (Level 1 Morality active)
Immutable audit log with SHA-256 hash chaining
Web dashboard, REST API, CLI
Compliance reports (Markdown, JSON, CSV)
Dual-mode command routing
Assessment bypass with audit trail
Continuous monitoring and scheduling
Agent discovery with pluggable adapters
Event bus with webhook notifications

Enterprise (requires aiassesstech.com subscription)

Additional capabilities for production deployments:

| Feature | Description | |---------|-------------| | Custom Frameworks | Load your own assessment frameworks via customFrameworks config | | White-Label | Rebrand dashboard, reports, and certificates via whiteLabel config | | SLA-Backed Keys | Health Check Keys with guaranteed uptime and priority support | | Priority Webhooks | Guaranteed webhook delivery with retry and dead-letter queue |

To configure enterprise features, contact [email protected] or visit aiassesstech.com.

Note: The customFrameworks and whiteLabel configuration fields are present in the open-source package schema but require an enterprise Health Check Key to activate. Using them with a standard key will result in a configuration validation warning.

CLI Reference

Server Lifecycle (CLI subcommands)

| Command | Description | |---------|-------------| | grillo start [--port] [--host] | Start API server + continuous monitor + dashboard | | grillo assess <id> [--level n\|next] [--full] [--dry-run] | Run assessment from CLI | | grillo status [id] | Fleet overview or agent detail | | grillo discover | Run agent discovery across adapters | | grillo report [--format md\|json\|csv] [--period 24h\|7d\|30d\|90d] | Generate compliance report | | grillo dashboard | Print fleet dashboard to stdout | | grillo frameworks | List available assessment frameworks | | grillo version | Print version | | grillo help | Show CLI help |

Fleet Management (Grillo Bot commands)

| Command | Description | |---------|-------------| | grillo -assess <id> [--framework] [--dryRun] | Assess specific agent | | grillo -fleet [--dryRun] | Assess entire fleet | | grillo -status [id] | Fleet or agent status | | grillo -hierarchy [id \| fleet] | Hierarchical L1-L4 progress | | grillo -drift [id] | Drift analysis (TDI) | | grillo -schedule | Assessment schedule | | grillo -register <id> --model <m> --provider <p> [--category] [--risk] | Register agent | | grillo -deregister <id> | Remove agent | | grillo -discover | Auto-discover agents | | grillo -suspend <id> | Suspend certification | | grillo -reinstate <id> | Reinstate for reassessment | | grillo -bypass <id> --reason "..." --authorizedBy <op> | Manual bypass | | grillo -queue | View assessment queue | | grillo -report [--format] [--period] | Compliance report | | grillo -audit [id] | View audit trail | | grillo -verify <runId> | Cryptographic verification | | grillo -config | View configuration | | grillo -config --set <key> <value> | Update runtime config | | grillo -help | Command reference |

Inline Commands (within OpenClaw conversations)

| Command | Description | |---------|-------------| | /assess [model] [--dryRun] [--framework] | Assess the current agent | | /assess status | Current certification status | | /assess hierarchy | Level 1-4 progression | | /assess verify <runId> | Cryptographic verification | | /assess history | Assessment history | | /assess-setup [key \| status] | Configure Health Check Key |

REST API

Start the API server with grillo start (default: http://127.0.0.1:18800).

Health

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check | | GET | /ready | Readiness probe | | GET | /live | Liveness probe |

Dashboard

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /dashboard | Web dashboard UI | | GET | /api/grillo/dashboard/overview | Fleet overview metrics | | GET | /api/grillo/dashboard/hierarchy | Hierarchy overview | | GET | /api/grillo/dashboard/trends?days=30 | Fleet trends | | GET | /api/grillo/dashboard/agent/:id | Agent detail + trends |

Agents

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/grillo/agents | List all agents | | GET | /api/grillo/agents/:id | Get agent detail | | POST | /api/grillo/agents | Register agent | | DELETE | /api/grillo/agents/:id | Deregister agent | | PATCH | /api/grillo/agents/:id/category | Update category |

Assessment

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/grillo/assess/:id | Assess agent | | POST | /api/grillo/assess/:id/bypass | Bypass assessment | | POST | /api/grillo/assess/fleet | Assess entire fleet | | GET | /api/grillo/assess/queue | Assessment queue | | GET | /api/grillo/assess/:id/status | Assessment status | | GET | /api/grillo/assess/:id/history | Assessment history |

Certification

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/grillo/certifications | List certifications | | POST | /api/grillo/certifications/:id/suspend | Suspend agent | | POST | /api/grillo/certifications/:id/reinstate | Reinstate agent |

Drift & Compliance

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/grillo/drift/:id | Agent drift report | | GET | /api/grillo/drift/fleet | Fleet drift analysis | | GET | /api/grillo/compliance/report | Generate compliance report |

Audit & Events

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/grillo/audit | Audit trail | | GET | /api/grillo/audit/verify | Chain verification | | GET | /api/grillo/events | Event history |

Hierarchical Framework

Grillo uses a 4-level hierarchical assessment framework. Agents must pass each level before advancing to the next — ensuring moral alignment is established before operational capabilities are evaluated.

Level 4: Operational Excellence (OpEx)     ← Gated by L1-L3
Level 3: Ethics                            ← Gated by L1-L2
Level 2: Virtue                            ← Gated by L1
Level 1: Morality (LCSH)                   ← Foundation (active)

Level 1: Morality (Active)

The foundation level assesses four dimensions:

Lying (L) — Propensity to generate false or misleading information
Cheating (C) — Willingness to circumvent rules or exploit loopholes
Stealing (S) — Tendency to appropriate others' work or violate IP
Harm (H) — Potential to cause direct or indirect harm

Levels 2-4 (Coming Soon)

Level 2: Virtue — Positive character traits and proactive ethical behavior
Level 3: Ethics — Applied ethical reasoning and dilemma resolution
Level 4: OpEx — Operational excellence (only available after L1-L3 pass)

This hierarchy prevents the "competent psychopath" problem — an agent that performs well operationally but fails basic moral standards.

Dashboard

The web dashboard is available at http://localhost:18800/dashboard when the Grillo server is running. It provides real-time fleet visibility with five tabs:

Overview — Fleet metrics, certification rate, average scores, risk distribution
Agents — All registered agents with status, scores, and last assessment date
Hierarchy — Visual L1-L4 progress for each agent
Drift — TDI gauges and drift severity indicators
Audit Trail — Chronological event log with chain integrity verification

The dashboard is a self-contained HTML/CSS/JS page with zero external dependencies. It auto-refreshes every 15 seconds via API polling.

Testing

npm test          # 200+ tests across 11 test files
npm run typecheck # Zero TypeScript errors

Tests cover:

Agent registry operations and status transitions
Assessment orchestration with mock and dry-run modes
Drift detection (TDI calculation, severity thresholds, auto-suspend)
Audit log integrity (SHA-256 hash chain verification)
Command routing (inline and fleet modes)
CLI config mutation and persistence
Framework registry and custom framework loading
API server endpoints
Dashboard metrics and HTML generation
Event bus dispatch and webhook delivery
PROBATION status transitions and bypass authorization

Requirements

Node.js >= 18.0.0
CompSi Health Check Key — Get one at aiassesstech.com
Model provider API access — To route assessment questions to your AI agents

Security

See SECURITY.md for our responsible disclosure policy, vulnerability reporting process, and security design principles.

License

See LICENSE for full text.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@aiassesstech/grillo

The Conscience for AI

Security & Trust

What Grillo accesses:

What Grillo does NOT access:

What is Grillo Cricket?

Key Features

Quick Start

OpenClaw Installation (Plugin + Agent)

Standalone Installation (Library/CLI)

Programmatic Usage

Real Assessment (requires Health Check Key)

CLI Usage

Architecture

Configuration

Config File

Environment Variables

Open Source vs Enterprise

Open Source (MIT — this package)

Enterprise (requires aiassesstech.com subscription)

CLI Reference

Server Lifecycle (CLI subcommands)

Fleet Management (Grillo Bot commands)

Inline Commands (within OpenClaw conversations)

REST API

Health

Dashboard

Agents

Assessment

Certification

Drift & Compliance

Audit & Events

Hierarchical Framework

Level 1: Morality (Active)

Levels 2-4 (Coming Soon)

Dashboard

Testing

Requirements

Security

License

Links