Skip to content

protocol.md

Latest commit

 

History

History
388 lines (219 loc) · 8.8 KB

protocol.md

File metadata and controls

388 lines (219 loc) · 8.8 KB

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.2.0", "manifest_version": "0.2" }

agentcli.schema

Params:

  • target - defaults to "manifest" when omitted. Valid targets: manifest, workflow, task, schedulerJob, standalonePlan, rpcRequest, rpcResponse. Also accepts kebab-case aliases: scheduler-job, standalone-plan, rpc-request, rpc-response.

Result:

  • { "ok": true, "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.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.

Result:

  • { "ok": true, "target": "openclaw-scheduler", "dry_run": <boolean>, "scheduler": { "command": "...", "db_path": "..." }, "capabilities": { "source": "static|runtime", "negotiated": <boolean>, "handoff_version": "..." }, "handoff": { "field_version": "1|2", "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.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.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.

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.