protocol.md

Protocol

Scope

This document defines the draft agentcli JSON-RPC protocol served over stdio.

The implementation lives in src/jsonrpc.js.

Transport

Transport is line-delimited JSON over stdin/stdout.

Rules:

• each request MUST be a single JSON object on one line
• each response MUST be a single JSON object on one line
• batch requests (JSON arrays) are not supported and return an error
• server startup notifications MAY be ignored by clients
• parse failures return JSON-RPC parse errors when possible

On startup, the server emits a readiness notification before processing requests:

{"jsonrpc":"2.0","method":"agentcli.ready","params":{"ok":true,"manifest_version":"0.2"}}

Clients MAY ignore this notification, but it provides a clean synchronization point for process-spawn integrations. Clients can discover the current method and notification surface programmatically with agentcli.describe and target: "rpc".

Envelope

Requests MUST follow JSON-RPC 2.0.

Example request:

{"jsonrpc":"2.0","id":"1","method":"agentcli.validate","params":{"manifest":{"version":"0.1","workflows":[{"id":"w1","name":"W","tasks":[{"id":"t1","name":"T","prompt":"hello","target":{"session_target":"isolated"},"schedule":{"cron":"0 9 * * *"}}]}]}}}

Example response:

{"jsonrpc":"2.0","id":"1","result":{"ok":true,"errors":[],"warnings":[]}}

Methods

agentcli.ping

Purpose:

• health check

Result:

• { "ok": true, "pong": true }

agentcli.version

Purpose:

• version discovery for agent integrations

Result:

• { "ok": true, "package_version": "0.5.0", "manifest_version": "0.2" }

agentcli.schema

Params:

• target - defaults to "manifest" when omitted. Valid targets: manifest, workflow, task, schedulerJob, standalonePlan, handoffV4, rpcRequest, rpcResponse. Also accepts kebab-case aliases: scheduler-job, standalone-plan, handoff-v4, rpc-request, rpc-response.
• legacy - boolean, defaults to false. When false, returns JSON Schema Draft 2020-12. When true, returns the legacy agentcli descriptor.

Result:

• { "ok": true, "schema_format": "json-schema-draft-2020-12|agentcli-legacy", "schema": <schema-fragment> }

agentcli.describe

Params:

• target - defaults to "commands" when omitted. Valid targets: manifest, workflow, task, targets, commands, rpc.

Result:

• { "ok": true, "description": <metadata> }
• for target: "rpc", description contains separate methods[] and notifications[] arrays

agentcli.targets

Purpose:

• discover compile targets and their declared static capabilities

Result:

• { "ok": true, "targets": [{ "name": "...", "description": "...", "capabilities": [...], "features": {...} }] }

agentcli.paths

Purpose:

• resolve local agentcli home, manifest, output, registry, state, audit, approval, and allowed-signers paths

Result:

• { "ok": true, "paths": {...} }

agentcli.validate

Params:

• manifest

Result:

• { "ok": <boolean>, "errors": [...], "warnings": [...] }
• validation failures are returned in result, not as JSON-RPC errors

agentcli.compile

Params:

• manifest
• target
• explain

Result:

• { "ok": true, "target": "<target-name>", "output": <compiled-artifact> }
• output includes an explain array when the explain param is true

agentcli.apply

Params:

• manifest
• dbPath
• schedulerPrefix
• schedulerBin
• dryRun - boolean, defaults to false. When true, no scheduler writes are executed (preview mode).
• explain
• adoptBy - "id" (default) or "name". Use "name" for one-time migration of existing scheduler jobs to agentcli management. See README for the migration workflow.
• allowProofCommand - boolean, defaults to false. Explicitly permits value_from.command while locally verifying a proof for a runtime that cannot verify it. Keep false for untrusted manifests.

Result:

• { "ok": true, "target": "openclaw-scheduler", "dry_run": <boolean>, "scheduler": { "command": "...", "db_path": "..." }, "capabilities": { "source": "static|runtime", "negotiated": <boolean>, "handoff_version": "...", "schema_version": <integer|null>, "handoff_contract": <object|null> }, "handoff": { "field_version": "1|2|3|4", "projected_fields": <int>, "v02_fields_included": <boolean> }, "job_count": <int>, "actions": [{ "action": "created|updated|adopted", "job_id": "...", "adopted_from_job_id": "...", "name": "...", "invocation_mode": "schedule|trigger", "authorization_proof_verification": { ... } }], "authorization_proof_verifications": [{ ... }], "explain": [...] }
• adopted_from_job_id is present only when action is "adopted"
• capabilities summarizes runtime capability negotiation for the selected scheduler
• handoff summarizes which scheduler field version was projected during apply
• authorization_proof_verification is present on an action when local proof verification was performed for that compiled execution unit
• authorization_proof_verifications is present only when apply performed local proof verification because the target backend does not advertise authorization_proof_verification
• explain is present only when the explain param is true
• intended for the openclaw-scheduler backend

agentcli.inspect

Params:

• dbPath
• entity
• limit
• fields - array of field names, or a comma-delimited string for CLI-style parity
• sanitize

Result:

• { "ok": true, "target": "openclaw-scheduler", "entity": "...", "count": <int>, "items": [...] }

agentcli.audit

Params:

• limit - optional positive integer

Result:

• { "ok": true, "count": <int>, "records": [...], "warnings": [{ "line_number": <int>, "message": "malformed audit record skipped" }] }

Records are sanitized. Malformed JSONL lines are skipped and surfaced as warnings instead of aborting the read.

agentcli.approvals.list

Params:

• status - optional pending, consumed, expired, revoked, or all
• workflowId - optional workflow filter
• taskId - optional task filter

Result:

• { "ok": true, "count": <int>, "records": [...] }

agentcli.registry.list

Result:

• { "ok": true, "entries": [...] }

agentcli.registry.show

Params:

• name - required registry entry name

Result:

• { "ok": true, "name": "...", "manifest": {...} }

agentcli.convert

v0.2

Purpose:

• convert a v0.1 manifest to v0.2 format

Params:

• manifest -- a valid v0.1 manifest object

Result:

• { "ok": true, "manifest": <converted-v0.2-manifest> }

The converted manifest preserves all existing fields and adds v0.2 defaults where applicable. The version field is updated to "0.2".

agentcli.identity.providers

v0.2

Purpose:

• list registered identity providers

Params:

• none

Result:

• { "ok": true, "providers": [{ "name": "...", "capabilities": {...} }] }

agentcli.identity.schema

v0.2

Purpose:

• get identity provider metadata and capabilities

Params:

• provider -- provider name (string)

Result:

• { "ok": true, "provider": "...", "capabilities": {...} }

agentcli.identity.resolve

v0.2

Purpose:

• resolve the effective identity for a manifest and task, applying the three-stage merge (profile, workflow, task)

Params:

• manifest -- a valid manifest object
• taskId -- the task id to resolve identity for
• workflowId -- (optional) the workflow id; required when the manifest contains multiple workflows

Result:

• { "ok": true, "declared_identity": {...}, "resolved_identity": {...}, "principal_used": "..." }

agentcli.identity.validateDelegation

v0.2

Purpose:

• validate the delegation chain for a task's identity

Params:

• manifest -- a valid manifest object
• taskId -- the task id to validate
• workflowId -- (optional) the workflow id

Result:

• { "ok": true, "delegation": {...} }

agentcli.authorizationProof.methods

v0.2

Purpose:

• list available authorization proof verifier methods

Params:

• none

Result:

• { "ok": true, "methods": [{ "name": "...", "capabilities": {...} }] }

agentcli.authorizationProof.schema

v0.2

Purpose:

• get authorization proof verifier metadata

Params:

• method -- verifier method name (string)

Result:

• { "ok": true, "method": "...", "verifier": "..." }

agentcli.authorizationProof.verify

v0.2

Purpose:

• explicitly verify a task's resolved authorization proof without executing the target command

Params:

• manifest -- a valid manifest object
• taskId -- task id whose resolved proof is verified
• workflowId -- optional workflow id

Result:

• { "ok": true, "authorization_proof": {...} }

This is a live governance inspection, not dry-run. It may resolve value_from, execute an explicitly declared proof command, or fetch configured JWKS trust material. It does not resolve identity, spawn the target command, generate evidence, or write an execution audit record.

agentcli.authorization.providers

v0.2

Purpose:

• list registered authorization providers (e.g., OPA, Cedar, Topaz)

Params:

• none

Result:

• { "ok": true, "providers": [{ "name": "...", "capabilities": {...} }] }

agentcli.authorization.schema

v0.2

Purpose:

• get authorization provider metadata and capabilities

Params:

• provider -- provider name (string)

Result:

• { "ok": true, "provider": "...", "capabilities": {...} }

agentcli.authorization.evaluate

v0.2

Purpose:

• evaluate authorization for a task given its resolved identity and contract

Params:

• manifest -- a valid manifest object
• taskId -- the task id to evaluate
• workflowId -- (optional) the workflow id

Result:

• { "ok": true, "decision": { "allowed": <boolean>, "reason": "..." } }

agentcli.evidence.providers

v0.2

Purpose:

• list registered evidence providers

Params:

• none

Result:

• { "ok": true, "providers": [{ "name": "...", "capabilities": {...} }] }

agentcli.evidence.schema

v0.2

Purpose:

• get evidence provider metadata

Params:

• provider -- provider name (string)

Result:

• { "ok": true, "provider": "...", "methods": ["..."] }

Notifications

agentcli.ready

Purpose:

• announce that the server is ready to process requests
• surface the current manifest contract version for clients that want to gate behavior

Params:

• ok
• manifest_version

Error Model

Current error classes:

• -32700: parse error
• -32600: invalid request
• -32602: invalid params
• -32601: method not found
• -32000: application error

Implementations SHOULD include machine-readable data for richer failures when available. Caller-fixable request shape and argument issues SHOULD use -32602, including unknown schema targets, unknown description topics, unsupported compile targets, and invalid inspect arguments.

Error responses use this envelope:

{"jsonrpc":"2.0","id":"1","error":{"code":-32602,"message":"...","data":{"code":"invalid_argument","error_type":"invalid_argument"}}}

Validation errors add data.validation. Internal failures use -32603 and a generic public message. Application failures use -32000 with their stable machine-readable code and one of the documented error types.

Stability

The following are intended to be stable within manifest spec versions 0.1 and 0.2:

• method names
• request envelope shape
• response envelope shape
• top-level result.ok convention

All v0.1 methods remain stable in v0.2. The v0.2 identity, authorization proof, authorization, and evidence methods are additive and do not alter existing method signatures.

Future protocol additions SHOULD be additive.