agent-contracts-runtime/dist/cli/index.js

Runtime bridge for executing agent-contracts workflows on Agent SDKs

#!/usr/bin/env node
import {
  buildTaskPrompt,
  createProgressSink,
  loadPlugins,
  runWorkflow
} from "../chunk-DPJFPYJO.js";
import {
  createGuardrailHooksFromRules,
  pluginRegistry
} from "../chunk-MGRZBGQL.js";
import {
  checkFreshness,
  generate,
  loadConfig
} from "../chunk-PEHJ3J5C.js";
import "../chunk-LTZA6QWC.js";
import "../chunk-AWBHN3LI.js";

// src/cli/index.ts
import { existsSync as existsSync5, readFileSync as readFileSync2, writeFileSync } from "fs";
import { resolve as resolve4 } from "path";
import { register } from "tsx/esm/api";

// src/generated/cli/program.ts
import { Command } from "commander";

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