`adapter-command/v1` — A2A Extension for Bounded Adapter Execution

URI: `https://agentic-sandbox.aiwg.io/extensions/adapter-command/v1`

Purpose

This extension lets an orchestrator request a narrow, allowlisted adapter command through A2A `messages:send` without changing the default text-message behavior.

The first supported adapter is `sandbox-agent-runner` in `plan` and `assess` modes. This is intended for supervised dry runs where the orchestrator needs the backing runtime to execute a bounded wrapper and report truthful task state.

Request Envelope

Clients place the envelope under `Message.metadata` using the extension URI as the key:

{
  "message": {
    "role": "user",
    "parts": [{ "kind": "text", "text": "Run the bounded plan adapter." }],
    "metadata": {
      "https://agentic-sandbox.aiwg.io/extensions/adapter-command/v1": {
        "adapter": "sandbox-agent-runner",
        "mode": "plan",
        "command": [
          "node",
          ".aiwg/ops/adapters/sandbox-agent-runner/runner.mjs",
          "--request",
          ".aiwg/ops/adapters/sandbox-agent-runner/examples/cycle-005-request.json"
        ],
        "working_dir": "/workspace",
        "timeout_seconds": 300
      }
    }
  }
}

Semantics

• If the envelope is absent, `messages:send` preserves the default echo-backed

text dispatch behavior.

• If the envelope is present, the server validates it before dispatch.
• `mode` must be one of `plan` or `assess`; the selected value is exposed to

the command as `AIWG_A2A_ADAPTER_MODE`.

• The only supported command shape in v1 is:

node .aiwg/ops/adapters/sandbox-agent-runner/runner.mjs --request <relative-request-path>

• `<relative-request-path>` must stay under

`.aiwg/ops/adapters/sandbox-agent-runner/` or `.aiwg/ops/runs/`.

• `timeout_seconds` defaults to `300` and must be between `1` and `900`.
• Unsupported or unsafe envelopes fail truthfully; they must not be downgraded

to echo success.

Task State

Task terminal state follows the dispatched command result:

• exit code `0` transitions the task to `completed`;
• non-zero exit transitions the task to `failed` with application failure;
• dispatch/runtime failures transition the task to `failed` with infrastructure

failure.

Stdout and stderr chunks are captured as task artifacts by the existing `messages:send` observer.

Optional text input

Activate `hitl-prompt/v1` in the `A2A-Extensions` header and set `input_mode` to `"text-line"` to opt a bounded adapter command into runtime input detection. Without this field, output is never treated as an input request. High-confidence interactive prompts (for example `[y/N]`) on the last output line are exposed as an A2A `input-required` task with the `hitl-prompt/v1` envelope. Detection retains at most 8 KiB of recent output.

The response payload is `{"text":"answer"}`. The runtime appends one newline; text is limited to 4096 bytes and cannot contain control characters. The prompt ID, instance, task and context must match; the command's deadline applies. Responses claim the current prompt atomically and deliver input to that exact running command. A successful response means the agent transport accepted the input; subsequent output and the command exit determine task completion. Duplicate or stale replies are rejected. A failed delivery restores the prompt only if the task has not changed or terminated. A later prompt receives a new ID.

This mode is heuristic text interaction, not an authenticated restricted-responder channel. Restricted responder prompts are rejected on this route. Live command bindings are process-local; management restart cannot silently reattach input to a different process and instead rejects delivery without a matching live binding.