agent-contracts-runtime
Version:
Runtime bridge for executing agent-contracts workflows on Agent SDKs
1,923 lines (1,634 loc) • 71.2 kB
Markdown
# agent-runtime CLI
Runtime bridge for executing agent-contracts workflows on Agent SDKs.
Generates typed contracts, handoff validators, and guardrail hooks from DSL,
then runs workflows through pluggable SDK adapters.
**Version:** 0.36.0
## Table of Contents
- [agent-runtime](#agent-runtime)
- [init](#agent-runtime-init)
- [generate](#agent-runtime-generate)
- [run](#agent-runtime-run)
- [list](#agent-runtime-list)
- [show-prompt](#agent-runtime-show-prompt)
- [implement](#agent-runtime-implement)
- [audit-implementation](#agent-runtime-audit-implementation)
- [agents](#agent-runtime-agents)
- [doctor](#agent-runtime-doctor)
- [navigation-index](#agent-runtime-navigation-index)
---
## agent-runtime
CLI for agent-contracts-runtime — generate, run, and manage agent workflows.
### Global Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--config` | -c | No | `"./agents.conf.yaml"` | Path to agents.conf.yaml (project runtime config). |
| `--verbose` | -v | No | `false` | Enable verbose output. |
| `--quiet` | -q | No | `false` | Suppress non-error output. |
### init
Initialize runtime scaffolding for a project.
Generates the initial directory structure and configuration files
for using agent-contracts-runtime in a project.
Creates agents.conf.yaml and agent/src/ user code templates.
**Usage:**
```
agent-runtime init [--adapter] [--output] [--force]
```
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--adapter` | -a | No | `"mock"` | Default SDK adapter to configure. |
| `--output` | -o | No | `"."` | Output directory for generated scaffolding. |
| `--force` | -f | No | `false` | Overwrite existing files without prompting. |
#### Exit Codes
**Exit 0:** Scaffolding generated successfully.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `files_created` | `string[]` | Yes | List of files created by init. |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"files_created"
],
"properties": {
"files_created": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of files created by init."
}
}
}
```
</details>
**Exit 1:** Initialization failed (existing files, permission error, etc.).
- **stderr:** format=`text`
#### Extensions
```yaml
x-agent:
riskLevel: low
requiresConfirmation: false
idempotent: false
sideEffects:
- filesystem_write
safeDryRunOption:
```
---
### generate
Generate runtime contracts and hooks from DSL.
Reads agent-contracts.yaml, resolves the DSL, validates it,
and generates typed contracts, handoff schemas, guardrail hooks,
and a runtime manifest into the configured generated_dir.
Each generated file includes a DO NOT EDIT header.
**Usage:**
```
agent-runtime generate [--clean] [--check] [--templates]
```
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--clean` | | No | `false` | Delete generated_dir before regenerating.
Removes stale files that may remain from previous generations.
|
| `--check` | | No | `false` | Dry-run mode for CI. Does not write files.
Compares current generated output with what would be regenerated.
Exits with code 1 if any differences are found.
|
| `--templates` | -t | No | | Custom templates directory. Overrides built-in templates. |
#### Exit Codes
**Exit 0:** Generation completed successfully (or --check found no differences).
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `files_generated` | `string[]` | Yes | List of generated file paths. |
| `dsl_hash` | `string` | Yes | SHA-256 hash of the resolved DSL (canonical stringify). |
| `generation_input_hash` | `string` | Yes | SHA-256 hash of all generation inputs. |
| `cleaned` | `boolean` | No | Whether --clean was used. |
| `check_mode` | `boolean` | No | Whether --check was used. |
| `has_differences` | `boolean` | No | In --check mode, whether differences were found. |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"files_generated",
"dsl_hash",
"generation_input_hash"
],
"properties": {
"files_generated": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of generated file paths."
},
"dsl_hash": {
"type": "string",
"description": "SHA-256 hash of the resolved DSL (canonical stringify)."
},
"generation_input_hash": {
"type": "string",
"description": "SHA-256 hash of all generation inputs."
},
"cleaned": {
"type": "boolean",
"description": "Whether --clean was used."
},
"check_mode": {
"type": "boolean",
"description": "Whether --check was used."
},
"has_differences": {
"type": "boolean",
"description": "In --check mode, whether differences were found."
}
}
}
```
</details>
**Exit 1:** Generation failed, or --check detected differences between
current generated files and expected output.
- **stderr:** format=`text`
**Exit 2:** DSL validation error. The input DSL has structural or semantic issues.
- **stderr:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `errors` | `object[]` | Yes | |
| `errors[].code` | `string` | Yes | |
| `errors[].message` | `string` | Yes | |
| `errors[].path` | `string` | No | JSON path to the invalid element. |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"path": {
"type": "string",
"description": "JSON path to the invalid element."
}
}
}
}
}
}
```
</details>
#### Extensions
```yaml
x-agent:
riskLevel: low
requiresConfirmation: false
idempotent: true
sideEffects:
- filesystem_write
safeDryRunOption: check
```
---
### run
Execute a workflow.
Loads generated contracts, creates an SDK adapter, registers user plugins,
and executes the specified workflow with the given user request.
The workflow runner orchestrates task delegation, retry, gate handling,
and handoff validation mechanically.
**Usage:**
```
agent-runtime run [workflow-id] [user-request] [--adapter] [--max-retries] [--max-follow-ups] [--dry-run] [--auto-approve-gates] [--file] [--log-file]
```
#### Arguments
| Name | Required | Description |
|---|---|---|
| `workflow-id` | No | ID of the workflow to execute. Required unless --file is used. |
| `user-request` | No | Natural language description of what to do. Required unless --file is used. |
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--adapter` | -a | No | | SDK adapter to use. Overrides config. |
| `--max-retries` | -r | No | | Override default max retries per step. |
| `--max-follow-ups` | -f | No | | Override default max follow-ups per step. |
| `--dry-run` | -n | No | `false` | Simulate execution without calling the SDK adapter. |
| `--auto-approve-gates` | | No | `false` | Automatically approve all gate steps. |
| `--file` | | No | | Path to a YAML invocation file. When provided, workflow-id and
user-request arguments are read from the file instead of CLI args.
|
| `--log-file` | -l | No | | Write agent progress log to this file. Overrides config logging.progress_log. |
#### Exit Codes
**Exit 0:** Workflow completed successfully.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `workflow_id` | `string` | Yes | |
| `status` | `"completed" \| "escalated" \| "gate_rejected" \| "error"` | Yes | |
| `steps` | `object[]` | Yes | |
| `steps[].step_index` | `integer (min: 0)` | Yes | |
| `steps[].task_id` | `string` | No | |
| `steps[].gate_kind` | `string` | No | |
| `steps[].outcome` | `object` | Yes | |
| `steps[].outcome.status` | `enum(7 values)` | Yes | |
| `steps[].retries_used` | `integer (min: 0)` | Yes | |
| `steps[].elapsed_ms` | `integer (min: 0)` | Yes | |
| `total_elapsed_ms` | `integer (min: 0)` | Yes | |
| `escalation_reason` | `string` | No | |
| `error_message` | `string` | No | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"workflow_id",
"status",
"steps",
"total_elapsed_ms"
],
"properties": {
"workflow_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"completed",
"escalated",
"gate_rejected",
"error"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"step_index",
"retries_used",
"elapsed_ms",
"outcome"
],
"properties": {
"step_index": {
"type": "integer",
"minimum": 0
},
"task_id": {
"type": "string"
},
"gate_kind": {
"type": "string"
},
"outcome": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"validation_error",
"escalation",
"error",
"gate_approved",
"gate_rejected",
"skipped"
]
}
}
},
"retries_used": {
"type": "integer",
"minimum": 0
},
"elapsed_ms": {
"type": "integer",
"minimum": 0
}
}
}
},
"total_elapsed_ms": {
"type": "integer",
"minimum": 0
},
"escalation_reason": {
"type": "string"
},
"error_message": {
"type": "string"
}
}
}
```
</details>
**Exit 1:** Workflow failed (escalation, error, or gate rejection).
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `workflow_id` | `string` | Yes | |
| `status` | `"completed" \| "escalated" \| "gate_rejected" \| "error"` | Yes | |
| `steps` | `object[]` | Yes | |
| `steps[].step_index` | `integer (min: 0)` | Yes | |
| `steps[].task_id` | `string` | No | |
| `steps[].gate_kind` | `string` | No | |
| `steps[].outcome` | `object` | Yes | |
| `steps[].outcome.status` | `enum(7 values)` | Yes | |
| `steps[].retries_used` | `integer (min: 0)` | Yes | |
| `steps[].elapsed_ms` | `integer (min: 0)` | Yes | |
| `total_elapsed_ms` | `integer (min: 0)` | Yes | |
| `escalation_reason` | `string` | No | |
| `error_message` | `string` | No | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"workflow_id",
"status",
"steps",
"total_elapsed_ms"
],
"properties": {
"workflow_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"completed",
"escalated",
"gate_rejected",
"error"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"step_index",
"retries_used",
"elapsed_ms",
"outcome"
],
"properties": {
"step_index": {
"type": "integer",
"minimum": 0
},
"task_id": {
"type": "string"
},
"gate_kind": {
"type": "string"
},
"outcome": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"validation_error",
"escalation",
"error",
"gate_approved",
"gate_rejected",
"skipped"
]
}
}
},
"retries_used": {
"type": "integer",
"minimum": 0
},
"elapsed_ms": {
"type": "integer",
"minimum": 0
}
}
}
},
"total_elapsed_ms": {
"type": "integer",
"minimum": 0
},
"escalation_reason": {
"type": "string"
},
"error_message": {
"type": "string"
}
}
}
```
</details>
- **stderr:** format=`text`
**Exit 3:** Input validation failed (invalid arguments, unknown workflow/adapter, or generated files outdated).
- **stderr:** format=`text`
**Exit 12:** Adapter initialization error (missing API key, etc.).
- **stderr:** format=`text`
#### Extensions
```yaml
x-agent:
riskLevel: high
requiresConfirmation: true
idempotent: false
sideEffects:
- sdk_call
- filesystem_write
safeDryRunOption: dry-run
expectedDurationMs: 300000
recommendedBeforeUse:
- Run `agent-runtime generate --check` to ensure contracts are up to date.
- Run `agent-runtime doctor` to verify SDK configuration.
```
---
### list
List available workflows, tasks, or agents.
Reads generated contracts and displays available resources.
Useful for discovering what workflows, tasks, and agents
are defined in the current project.
**Usage:**
```
agent-runtime list <resource> [--format]
```
#### Arguments
| Name | Required | Description |
|---|---|---|
| `resource` | Yes | Type of resource to list. |
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--format` | | No | `"table"` | Output format. |
#### Exit Codes
**Exit 0:** Resources listed successfully.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `resource` | `"workflows" \| "tasks" \| "agents"` | Yes | |
| `items` | `object[]` | Yes | |
| `items[].id` | `string` | Yes | |
| `items[].description` | `string` | Yes | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"resource",
"items"
],
"properties": {
"resource": {
"type": "string",
"enum": [
"workflows",
"tasks",
"agents"
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"description"
],
"properties": {
"id": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
}
```
</details>
**Exit 1:** Failed to load contracts.
- **stderr:** format=`text`
#### Extensions
```yaml
x-agent:
riskLevel: low
requiresConfirmation: false
idempotent: true
sideEffects:
```
---
### show-prompt
Display the generated prompt for a task.
Builds and displays the full prompt that would be sent to an SDK agent
for a given task. Useful for inspecting, debugging, and validating
prompt content before execution.
Shows the agent role, responsibilities, constraints, task details,
completion criteria, handoff schema fields, and output format example.
**Usage:**
```
agent-runtime show-prompt <task-id> [--user-request] [--format] [--with-plugins]
```
#### Arguments
| Name | Required | Description |
|---|---|---|
| `task-id` | Yes | ID of the task to show the prompt for (e.g. plan-and-implement, audit-tests). |
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--user-request` | -u | No | `"(preview)"` | User request text to include in the prompt preview. |
| `--format` | | No | `"markdown"` | Output format. |
| `--with-plugins` | | No | `false` | Apply registered plugin prompt enhancers to the output. |
#### Exit Codes
**Exit 0:** Prompt displayed successfully.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `task_id` | `string` | Yes | The task ID used to build the prompt. |
| `agent_id` | `string` | Yes | The target agent ID for this task. |
| `prompt` | `string` | Yes | The full generated prompt text. |
| `handoff_schema` | `string` | No | The handoff schema ID for the task result. |
| `plugins_applied` | `boolean` | No | Whether plugin prompt enhancers were applied. |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"task_id",
"agent_id",
"prompt"
],
"properties": {
"task_id": {
"type": "string",
"description": "The task ID used to build the prompt."
},
"agent_id": {
"type": "string",
"description": "The target agent ID for this task."
},
"prompt": {
"type": "string",
"description": "The full generated prompt text."
},
"handoff_schema": {
"type": "string",
"description": "The handoff schema ID for the task result."
},
"plugins_applied": {
"type": "boolean",
"description": "Whether plugin prompt enhancers were applied."
}
}
}
```
</details>
**Exit 1:** Failed to build prompt (unknown task, missing contracts, etc.).
- **stderr:** format=`text`
#### Extensions
```yaml
x-agent:
riskLevel: low
requiresConfirmation: false
idempotent: true
sideEffects:
```
---
### implement
Implement LLM-powered commands in a CLI tool.
Uses an agentic LLM adapter (Claude, etc.) to analyze the
target project and implement LLM-powered commands following the
agent-contracts + agent-contracts-runtime + cli-contracts stack.
The agent reads the project structure, cli-contract.yaml, and existing
code, then generates DSL definitions, TypeScript modules (orchestrator,
context-builder, formatter), CLI command handlers, and updates the
CLI contract with x-agent metadata.
Requires an agentic adapter that supports tool use (file read/write).
**Usage:**
```
agent-runtime implement <description> [--adapter] [--project-dir] [--dry-run] [--model] [--output] [--report-format] [--log-file]
```
#### Arguments
| Name | Required | Description |
|---|---|---|
| `description` | Yes | Natural language description of the LLM feature(s) to implement. Examples: "Add an audit command for migration safety", "Add propose and explain commands for SQL optimization". |
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--adapter` | -a | No | `"claude"` | SDK adapter to use. Must be an agentic adapter (claude). |
| `--project-dir` | -p | No | `"."` | Path to the target project directory. |
| `--dry-run` | -n | No | `false` | Output the prompt context without calling the LLM. |
| `--model` | | No | | Model name override for the selected adapter. |
| `--output` | -o | No | | Write the result to a file instead of stdout. |
| `--report-format` | | No | `"text"` | Output format for the result. |
| `--log-file` | -l | No | | Write agent progress log to this file. |
#### Exit Codes
**Exit 0:** Implementation completed successfully.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `files_created` | `string[]` | Yes | List of new files created. |
| `files_modified` | `string[]` | Yes | List of existing files modified. |
| `summary` | `string` | Yes | Human-readable summary of what was implemented. |
| `commands_added` | `object[]` | No | |
| `commands_added[].name` | `string` | Yes | |
| `commands_added[].type` | `"audit" \| "propose" \| "explain"` | Yes | |
| `commands_added[].description` | `string` | No | |
| `next_steps` | `string[]` | No | Recommended next steps for the developer. |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"files_created",
"files_modified",
"summary"
],
"properties": {
"files_created": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of new files created."
},
"files_modified": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of existing files modified."
},
"summary": {
"type": "string",
"description": "Human-readable summary of what was implemented."
},
"commands_added": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"audit",
"propose",
"explain"
]
},
"description": {
"type": "string"
}
}
}
},
"next_steps": {
"type": "array",
"items": {
"type": "string"
},
"description": "Recommended next steps for the developer."
}
}
}
```
</details>
**Exit 1:** Implementation failed.
- **stderr:** format=`text`
**Exit 3:** Input validation failed (e.g. project directory not found).
- **stderr:** format=`text`
**Exit 12:** Adapter initialization error.
- **stderr:** format=`text`
#### Extensions
```yaml
x-agent:
riskLevel: high
requiresConfirmation: true
idempotent: false
sideEffects:
- sdk_call
- filesystem_write
safeDryRunOption: dry-run
expectedDurationMs: 300000
retryableExitCodes:
- 1
- 12
recommendedBeforeUse:
- Ensure the target project has a cli-contract.yaml or plan to create one.
- Run in a clean git working tree so changes can be reviewed.
```
---
### audit-implementation
Audit an LLM command integration for pattern conformance.
Analyzes a target project's LLM command integration to verify it
correctly follows the agent-contracts + agent-contracts-runtime +
cli-contracts stack conventions.
Checks all three layers:
1. DSL definitions (agents, tasks, workflows, handoff schemas)
2. Runtime integration (adapter usage, runTask/runWorkflow, registries)
3. CLI contract (standard options, x-agent metadata, exit codes)
Produces structured findings with severity, category, and
concrete remediation steps. Read-only — does not modify files.
**Usage:**
```
agent-runtime audit-implementation [project-dir] [--adapter] [--focus] [--dry-run] [--fail-on] [--model] [--output] [--report-format] [--log-file]
```
#### Arguments
| Name | Required | Description |
|---|---|---|
| `project-dir` | No | Path to the project directory to audit. Defaults to current directory. |
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--adapter` | -a | No | `"claude"` | SDK adapter to use for the audit agent. |
| `--focus` | | No | `"all"` | Limit audit to a specific layer. Defaults to all layers. |
| `--dry-run` | -n | No | `false` | Output the prompt context without calling the LLM. |
| `--fail-on` | | No | `"error"` | Minimum finding severity that causes a non-zero exit. |
| `--model` | | No | | Model name override for the selected adapter. |
| `--output` | -o | No | | Write the result to a file instead of stdout. |
| `--report-format` | | No | `"text"` | Output format for the audit report. |
| `--log-file` | -l | No | | Write agent progress log to this file. |
#### Exit Codes
**Exit 0:** Audit completed with no findings above threshold.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `summary` | `string` | Yes | One-paragraph overall assessment. |
| `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | Derived from worst finding severity. |
| `findings` | `object[]` | Yes | |
| `findings[].id` | `string` | No | Unique finding identifier (e.g. F-001). |
| `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
| `findings[].category` | `string` | Yes | Domain vocabulary category (e.g. cli-contract-options, runtime-adapter). |
| `findings[].target` | `string` | No | File path or resource the finding applies to. |
| `findings[].location` | `string` | No | Line range or specific location within the target. |
| `findings[].message` | `string` | Yes | Human-readable description of the finding. |
| `findings[].recommendation` | `string` | No | Concrete remediation step. |
| `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0–1) for the finding. |
| `findings[].evidence` | `object[]` | No | |
| `findings[].evidence[].type` | `string` | Yes | Evidence type (e.g. code_snippet, file_excerpt, lint_output). |
| `findings[].evidence[].content` | `string` | Yes | The evidence content. |
| `findings[].evidence[].source` | `string` | No | Source file path or URL for the evidence. |
| `findings[].details` | `object` | No | Additional structured details specific to the finding category. |
| `recommendedActions` | `object[]` | No | |
| `recommendedActions[].kind` | `enum(6 values)` | Yes | |
| `recommendedActions[].title` | `string` | Yes | Short human-readable title for the action. |
| `recommendedActions[].command` | `string` | No | Shell command to run (when kind is run_command). |
| `recommendedActions[].target` | `string` | No | File path to edit (when kind is edit_file). |
| `recommendedActions[].rationale` | `string` | No | Explanation of why this action is recommended. |
| `metadata` | `object` | No | |
| `metadata.tool` | `string` | No | |
| `metadata.command` | `string` | No | |
| `metadata.version` | `string` | No | |
| `metadata.generatedAt` | `string` | No | |
| `metadata.adapter` | `string` | No | |
| `metadata.model` | `string` | No | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"summary",
"riskLevel",
"findings"
],
"properties": {
"summary": {
"type": "string",
"description": "One-paragraph overall assessment."
},
"riskLevel": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
],
"description": "Derived from worst finding severity."
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"severity",
"category",
"message"
],
"properties": {
"id": {
"type": "string",
"description": "Unique finding identifier (e.g. F-001)."
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"error",
"critical"
]
},
"category": {
"type": "string",
"description": "Domain vocabulary category (e.g. cli-contract-options, runtime-adapter)."
},
"target": {
"type": "string",
"description": "File path or resource the finding applies to."
},
"location": {
"type": "string",
"description": "Line range or specific location within the target."
},
"message": {
"type": "string",
"description": "Human-readable description of the finding."
},
"recommendation": {
"type": "string",
"description": "Concrete remediation step."
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Confidence score (0–1) for the finding."
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"content"
],
"properties": {
"type": {
"type": "string",
"description": "Evidence type (e.g. code_snippet, file_excerpt, lint_output)."
},
"content": {
"type": "string",
"description": "The evidence content."
},
"source": {
"type": "string",
"description": "Source file path or URL for the evidence."
}
}
}
},
"details": {
"type": "object",
"description": "Additional structured details specific to the finding category."
}
}
}
},
"recommendedActions": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"title"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"run_command",
"edit_file",
"review",
"confirm",
"block",
"ignore"
]
},
"title": {
"type": "string",
"description": "Short human-readable title for the action."
},
"command": {
"type": "string",
"description": "Shell command to run (when kind is run_command)."
},
"target": {
"type": "string",
"description": "File path to edit (when kind is edit_file)."
},
"rationale": {
"type": "string",
"description": "Explanation of why this action is recommended."
}
}
}
},
"metadata": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"command": {
"type": "string"
},
"version": {
"type": "string"
},
"generatedAt": {
"type": "string"
},
"adapter": {
"type": "string"
},
"model": {
"type": "string"
}
}
}
}
}
```
</details>
**Exit 1:** Audit failed (agent error, unexpected failure).
- **stderr:** format=`text`
**Exit 3:** Input validation failed (e.g. project directory not found).
- **stderr:** format=`text`
**Exit 10:** Audit completed with findings above --fail-on threshold.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `summary` | `string` | Yes | One-paragraph overall assessment. |
| `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | Derived from worst finding severity. |
| `findings` | `object[]` | Yes | |
| `findings[].id` | `string` | No | Unique finding identifier (e.g. F-001). |
| `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
| `findings[].category` | `string` | Yes | Domain vocabulary category (e.g. cli-contract-options, runtime-adapter). |
| `findings[].target` | `string` | No | File path or resource the finding applies to. |
| `findings[].location` | `string` | No | Line range or specific location within the target. |
| `findings[].message` | `string` | Yes | Human-readable description of the finding. |
| `findings[].recommendation` | `string` | No | Concrete remediation step. |
| `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0–1) for the finding. |
| `findings[].evidence` | `object[]` | No | |
| `findings[].evidence[].type` | `string` | Yes | Evidence type (e.g. code_snippet, file_excerpt, lint_output). |
| `findings[].evidence[].content` | `string` | Yes | The evidence content. |
| `findings[].evidence[].source` | `string` | No | Source file path or URL for the evidence. |
| `findings[].details` | `object` | No | Additional structured details specific to the finding category. |
| `recommendedActions` | `object[]` | No | |
| `recommendedActions[].kind` | `enum(6 values)` | Yes | |
| `recommendedActions[].title` | `string` | Yes | Short human-readable title for the action. |
| `recommendedActions[].command` | `string` | No | Shell command to run (when kind is run_command). |
| `recommendedActions[].target` | `string` | No | File path to edit (when kind is edit_file). |
| `recommendedActions[].rationale` | `string` | No | Explanation of why this action is recommended. |
| `metadata` | `object` | No | |
| `metadata.tool` | `string` | No | |
| `metadata.command` | `string` | No | |
| `metadata.version` | `string` | No | |
| `metadata.generatedAt` | `string` | No | |
| `metadata.adapter` | `string` | No | |
| `metadata.model` | `string` | No | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"summary",
"riskLevel",
"findings"
],
"properties": {
"summary": {
"type": "string",
"description": "One-paragraph overall assessment."
},
"riskLevel": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
],
"description": "Derived from worst finding severity."
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"severity",
"category",
"message"
],
"properties": {
"id": {
"type": "string",
"description": "Unique finding identifier (e.g. F-001)."
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"error",
"critical"
]
},
"category": {
"type": "string",
"description": "Domain vocabulary category (e.g. cli-contract-options, runtime-adapter)."
},
"target": {
"type": "string",
"description": "File path or resource the finding applies to."
},
"location": {
"type": "string",
"description": "Line range or specific location within the target."
},
"message": {
"type": "string",
"description": "Human-readable description of the finding."
},
"recommendation": {
"type": "string",
"description": "Concrete remediation step."
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Confidence score (0–1) for the finding."
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"content"
],
"properties": {
"type": {
"type": "string",
"description": "Evidence type (e.g. code_snippet, file_excerpt, lint_output)."
},
"content": {
"type": "string",
"description": "The evidence content."
},
"source": {
"type": "string",
"description": "Source file path or URL for the evidence."
}
}
}
},
"details": {
"type": "object",
"description": "Additional structured details specific to the finding category."
}
}
}
},
"recommendedActions": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"title"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"run_command",
"edit_file",
"review",
"confirm",
"block",
"ignore"
]
},
"title": {
"type": "string",
"description": "Short human-readable title for the action."
},
"command": {
"type": "string",
"description": "Shell command to run (when kind is run_command)."
},
"target": {
"type": "string",
"description": "File path to edit (when kind is edit_file)."
},
"rationale": {
"type": "string",
"description": "Explanation of why this action is recommended."
}
}
}
},
"metadata": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"command": {
"type": "string"
},
"version": {
"type": "string"
},
"generatedAt": {
"type": "string"
},
"adapter": {
"type": "string"
},
"model": {
"type": "string"
}
}
}
}
}
```
</details>
**Exit 12:** Adapter initialization error.
- **stderr:** format=`text`
#### Extensions
```yaml
x-agent:
riskLevel: low
requiresConfirmation: false
idempotent: true
sideEffects:
- network
sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write only when --output is specified.
safeDryRunOption: dry-run
expectedDurationMs: 180000
retryableExitCodes:
- 1
- 12
```
---
### agents
Output the full resolved DSL as structured data.
Outputs the complete resolved DSL (agents, tasks, workflows,
handoff_types, etc.) embedded in this CLI binary.
Useful for debugging, external tooling integration, and DSL
inspection. Unlike `list`, which shows tabular summaries,
this command outputs the full DSL structure.
**Usage:**
```
agent-runtime agents [--format]
```
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--format` | -F | No | `"yaml"` | Output format. |
#### Exit Codes
**Exit 0:** DSL output successfully.
- **stdout:** format=`text`
**Exit 1:** Failed to load embedded DSL.
- **stderr:** format=`text`
#### Extensions
```yaml
x-agent:
riskLevel: low
requiresConfirmation: false
idempotent: true
sideEffects:
```
---
### doctor
Verify configuration, generated files, and SDK connectivity.
Runs a series of diagnostic checks to verify that the project
is correctly configured for agent-runtime execution.
Checks: config existence, DSL existence, generated manifest freshness,
adapter configuration, API key environment variables, plugin entrypoint.
**Usage:**
```
agent-runtime doctor
```
#### Exit Codes
**Exit 0:** All checks passed.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `checks` | `object[]` | Yes | |
| `checks[].name` | `string` | Yes | Check name (e.g. config_exists, dsl_exists, manifest_fresh). |
| `checks[].status` | `"pass" \| "fail" \| "warn"` | Yes | |
| `checks[].message` | `string` | No | Human-readable detail. |
| `all_passed` | `boolean` | Yes | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"checks",
"all_passed"
],
"properties": {
"checks": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"status"
],
"properties": {
"name": {
"type": "string",
"description": "Check name (e.g. config_exists, dsl_exists, manifest_fresh)."
},
"status": {
"type": "string",
"enum": [
"pass",
"fail",
"warn"
]
},
"message": {
"type": "string",
"description": "Human-readable detail."
}
}
}
},
"all_passed": {
"type": "boolean"
}
}
}
```
</details>
**Exit 1:** One or more checks failed.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `checks` | `object[]` | Yes | |
| `checks[].name` | `string` | Yes | Check name (e.g. config_exists, dsl_exists, manifest_fresh). |
| `checks[].status` | `"pass" \| "fail" \| "warn"` | Yes | |
| `checks[].message` | `string` | No | Human-readable detail. |
| `all_passed` | `boolean` | Yes | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"checks",
"all_passed"
],
"properties": {
"checks": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"status"
],
"properties": {
"name": {
"type": "string",
"description": "Check name (e.g. config_exists, dsl_exists, manifest_fresh)."
},
"status": {
"type": "string",
"enum": [
"pass",
"fail",
"warn"
]
},
"message": {
"type": "string",
"description": "Human-readable detail."
}
}
}
},
"all_passed": {
"type": "boolean"
}
}
}
```
</details>
#### Extensions
```yaml
x-agent:
riskLevel: low
requiresConfirmation: false
idempotent: true
sideEffects:
```
---
### navigation-index
Build artifact navigation index from resolved DSL.
Resolves the embedded DSL (merged with project overlay if configured),
applies artifact binding, and builds a navigation index showing
artifact-to-tool-to-agent mappings.
The output is a JSON/YAML structure suitable for IDE integration,
routing rules, and artifact coverage analysis.
**Usage:**
```
agent-runtime navigation-index [--format] [--artifact] [--output]
```
#### Options
| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--format` | -F | No | `"json"` | Output format. |
| `--artifact` | | No | | Filter output to a single artifact by ID. |
| `--output` | -o | No | | Write output to a file instead of stdout. |
#### Exit Codes
**Exit 0:** Navigation index built successfully.
- **stdout:** format=`json`
| Property | Type | Required | Description |
|---|---|---|---|
| `version` | `string` | Yes | |
| `generated_at` | `string` | Yes | |
| `system` | `object` | Yes | |
| `system.id` | `string` | Yes | |
| `system.name` | `string` | Yes | |
| `artifacts` | `Record<string, any>` | Yes | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"version",
"generated_at",
"system",
"artifacts"
],
"properties": {
"version": {
"type": "string"
},
"generated_at": {
"type": "string"
},
"system": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"artifacts": {
"type": "object",
"additionalProperties": true
}
}
}
```
</details>
**Exit 1:** Failed to build navigation index.
- **stderr:** format=`text`
#### Extensions
```yaml
x-agent:
riskLevel: low
requiresConfirmation: false
idempotent: true
sideEffects:
```
---
---
## Schemas
### InitResult
Type: `object`
| Property | Type | Required | Description |
|---|---|---|---|
| `files_created` | `string[]` | Yes | List of files created by init. |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"files_created"
],
"properties": {
"files_created": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of files created by init."
}
}
}
```
</details>
### GenerateResult
Type: `object`
| Property | Type | Required | Description |
|---|---|---|---|
| `files_generated` | `string[]` | Yes | List of generated file paths. |
| `dsl_hash` | `string` | Yes | SHA-256 hash of the resolved DSL (canonical stringify). |
| `generation_input_hash` | `string` | Yes | SHA-256 hash of all generation inputs. |
| `cleaned` | `boolean` | No | Whether --clean was used. |
| `check_mode` | `boolean` | No | Whether --check was used. |
| `has_differences` | `boolean` | No | In --check mode, whether differences were found. |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"files_generated",
"dsl_hash",
"generation_input_hash"
],
"properties": {
"files_generated": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of generated file paths."
},
"dsl_hash": {
"type": "string",
"description": "SHA-256 hash of the resolved DSL (canonical stringify)."
},
"generation_input_hash": {
"type": "string",
"description": "SHA-256 hash of all generation inputs."
},
"cleaned": {
"type": "boolean",
"description": "Whether --clean was used."
},
"check_mode": {
"type": "boolean",
"description": "Whether --check was used."
},
"has_differences": {
"type": "boolean",
"description": "In --check mode, whether differences were found."
}
}
}
```
</details>
### ValidationError
Type: `object`
| Property | Type | Required | Description |
|---|---|---|---|
| `errors` | `object[]` | Yes | |
| `errors[].code` | `string` | Yes | |
| `errors[].message` | `string` | Yes | |
| `errors[].path` | `string` | No | JSON path to the invalid element. |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"path": {
"type": "string",
"description": "JSON path to the invalid element."
}
}
}
}
}
}
```
</details>
### WorkflowResult
Type: `object`
| Property | Type | Required | Description |
|---|---|---|---|
| `workflow_id` | `string` | Yes | |
| `status` | `"completed" \| "escalated" \| "gate_rejected" \| "error"` | Yes | |
| `steps` | `object[]` | Yes | |
| `steps[].step_index` | `integer (min: 0)` | Yes | |
| `steps[].task_id` | `string` | No | |
| `steps[].gate_kind` | `string` | No | |
| `steps[].outcome` | `object` | Yes | |
| `steps[].outcome.status` | `enum(7 values)` | Yes | |
| `steps[].retries_used` | `integer (min: 0)` | Yes | |
| `steps[].elapsed_ms` | `integer (min: 0)` | Yes | |
| `total_elapsed_ms` | `integer (min: 0)` | Yes | |
| `escalation_reason` | `string` | No | |
| `error_message` | `string` | No | |
<details>
<summary>JSON Schema</summary>
```json
{
"type": "object",
"required": [
"workflow_id",
"status",
"steps",
"total_elapsed_ms"
],
"properties": {
"workflow_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"completed",
"escalated",
"gate_rejected",
"error"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"step_index",
"retries_used",
"elapsed_ms",
"outcome"
],
"properties": {
"step_index": {
"type": "integer",