@agentproto/driver-agent-cli 0.2.0 → 0.4.0

package/dist/{schema-CCSzIDMJ.d.ts → schema-L-2rEB1H.d.ts}

@@ -133,12 +133,36 @@ type AgentCliSetupStep = {
 interface AgentCliSession {
     mode?: AgentCliSessionMode;
     idle_timeout_ms?: number;
+    /**
+     * Per-turn silence watchdog (ms) — distinct from `idle_timeout_ms`,
+     * which bounds time BETWEEN turns. This bounds true silence DURING a
+     * single turn: if the adapter goes this long with no activity signal
+     * and its `prompt` call still hasn't resolved, the ACP client
+     * synthesizes a `turn-end` with `reason: "watchdog-timeout"` instead
+     * of hanging forever (see `@agentproto/acp/client`'s
+     * `AcpClientOptions.turnIdleTimeoutMs`). Undefined (the default)
+     * disables the watchdog — set this only for adapters known to
+     * sometimes drop the final `prompt` response (e.g. hermes).
+     */
+    turn_idle_timeout_ms?: number;
     max_turns?: number;
     context_carryover?: boolean;
 }
 interface AgentCliModels {
     default?: string;
     allowed?: string[];
+    /**
+     * Model-id patterns this adapter must NEVER route to, even when a caller
+     * passes the id explicitly (the `model` option is free-form, so `allowed`
+     * is only a curated menu and can't *prevent* an off-menu id). Each pattern
+     * matches case-insensitively against the requested model id and supports a
+     * single trailing `*` wildcard (prefix match); otherwise exact. A match is
+     * refused at compose time (`RuntimeConfigError`, code `model_denied`).
+     * Use to reserve a premium provider for a dedicated adapter — e.g. hermes
+     * denies `["anthropic/*", "claude-*"]` so Anthropic models stay exclusive
+     * to the claude-code adapter.
+     */
+    deny?: string[];
     env?: Record<string, string>;
     /**
      * How the host selects a model at session start:
@@ -170,6 +194,16 @@ interface AgentCliCapabilities {
      */
     file_attach?: boolean;
 }
+/**
+ * Support status for a declared mode. Absent ⇒ treated as `"active"`.
+ *   active  — the mode does what its description claims.
+ *   noop    — declared and accepted, but measured to have no effect
+ *             (argv/env compose fine, but the observable outcome is
+ *             identical to not passing it). Kept declared for honesty
+ *             and so a future fix can flip it back to `active`.
+ *   planned — declared as an intended surface but not wired yet.
+ */
+type AgentCliModeStatus = "active" | "noop" | "planned";
 /**
  * AIP-45 mode declaration — a mutually-exclusive operation profile
  * the CLI exposes. The host picks at most ONE mode per turn via
@@ -179,8 +213,51 @@ interface AgentCliCapabilities {
 interface AgentCliMode {
     id: string;
     description?: string;
+    /**
+     * Extra argv prepended BEFORE the manifest's default `bin_args` when
+     * this mode is active. Needed for CLIs whose global flags must
+     * precede a subcommand baked into `bin_args` (e.g. hermes'
+     * `--ignore-user-config` must come before `acp`, where
+     * `bin_args_append` would land it too late).
+     */
+    bin_args_prepend?: string[];
     bin_args_append?: string[];
     env?: Record<string, string>;
+    /**
+     * Env keys to DELETE from the spawn env when this mode is active.
+     * Applied at the runtime's env-merge point (after the ambient
+     * process.env + mode/option env are combined), so a mode can scrub a
+     * credential that must never reach a non-native endpoint — e.g. a
+     * gateway mode scrubbing `ANTHROPIC_API_KEY` so it can't leak to a
+     * third-party Anthropic-compatible host (it would both 401 and expose
+     * the real key). Unlike `env`, this can't be expressed as a static
+     * set (a key set to "" is still present); deletion is the only safe
+     * semantics. Mirrors the in-code scrub `claude-sdk` does in
+     * `buildQueryOptions`; surfaced here so CLI-adapter gateway modes
+     * get the same auth hygiene without per-adapter code.
+     */
+    env_unset?: string[];
+    /**
+     * Honest support status surfaced to clients (e.g. via `adapter_list`).
+     * Lets an adapter admit that a declared mode is a measured no-op or
+     * not-yet-wired instead of silently accepting it. Absent ⇒ `"active"`.
+     */
+    status?: AgentCliModeStatus;
+    /** Human-readable reason backing `status` (e.g. what was measured). */
+    status_note?: string;
+    /**
+     * How the host activates this mode at session start:
+     *   - "bin_args" (default) — apply via this mode's `bin_args_prepend` /
+     *     `bin_args_append` / `env`, composed into argv/env at spawn time.
+     *     Preserves every existing adapter's behavior unchanged.
+     *   - "config" — this CLI has no argv/env surface for mode selection;
+     *     instead the mode id is forwarded to the ACP arm's `connect({mode})`
+     *     and applied via `session/set_config_option` with `configId:"mode"`
+     *     after `newSession` (e.g. opencode). `bin_args_prepend` /
+     *     `bin_args_append` / `env` are ignored for a mode declaring this.
+     * Omit → "bin_args".
+     */
+    apply?: "bin_args" | "config";
 }
 type AgentCliOptionType = "boolean" | "integer" | "string" | "enum";
 /**
@@ -199,6 +276,14 @@ interface AgentCliOption {
     min?: number;
     /** Inclusive upper bound when type === "integer". */
     max?: number;
+    /**
+     * Argv template prepended BEFORE the manifest's default `bin_args`
+     * when the option has a non-default value. The literal token
+     * `{value}` is replaced with the option's value (stringified). Use
+     * for value-bearing global flags that must precede a subcommand
+     * (e.g. hermes' `--skills {value}`).
+     */
+    bin_args_prepend?: string[];
     /**
      * Argv template appended when the option has a non-default value.
      * The literal token `{value}` is replaced with the option's value
@@ -215,6 +300,63 @@ interface AgentCliOption {
      * may contain `{value}` for templating.
      */
     env?: Record<string, string>;
+    /**
+     * Env keys to DELETE from the spawn env when the option has a
+     * non-default value. Symmetric with `AgentCliMode.env_unset` and
+     * applied at the same runtime env-merge point. Lets a single option
+     * carry both the value it sets AND the credential it must displace —
+     * e.g. a `base_url` option pointing at a third-party Anthropic-
+     * compatible gateway should scrub the ambient `ANTHROPIC_API_KEY`
+     * so it can't leak, without forcing the operator to also pick a
+     * preset mode. The deletion runs before operator-supplied `opts.env`
+     * is merged, so a caller can still re-inject a specific key if they
+     * truly intend to.
+     */
+    env_unset?: string[];
+}
+/**
+ * AIP-45 gateway-preset declaration — a backend an Anthropic/OpenAI-
+ * compatible client can front, declared by the adapter that knows how to
+ * drive it. The manifest authoring shape; the runtime normalizes it to a
+ * `ProviderPreset` (via the catalog's merge seam) so adapter-declared
+ * presets appear in `agentproto presets list` / `list_provider_presets`
+ * alongside the built-in registry. Data-only — no adapter projection
+ * (`env`/`env_unset`/`bin_args`) here; that stays in the adapter's modes
+ * and options, same as the built-in presets are projected today.
+ */
+interface AgentCliPresetDeclaration {
+    /**
+     * Stable preset id. SHOULD equal the mode id if the adapter projects
+     * this preset as a mode (e.g. `moonshot`, `openrouter`). Catalog
+     * dedupes built-in vs adapter-declared by id; an adapter-declared id
+     * that collides with a built-in is ignored in favor of the built-in
+     * (the registry is the source of truth for canonical providers).
+     */
+    id: string;
+    /** Human label for the catalog UI ("Moonshot (Kimi)"). */
+    label: string;
+    /** Short description; surfaced in the catalog. */
+    description?: string;
+    /** API schema flavor — selects which adapter family can consume it. */
+    schemaFlavor: "anthropic" | "openai";
+    /** Base URL the client hits. */
+    baseUrl: string;
+    /**
+     * Conventional env var holding this provider's API key
+     * (e.g. MOONSHOT_API_KEY). Catalog status is derived from its presence
+     * in the daemon's environment ("ready" vs "available").
+     */
+    keyEnv: string;
+    /**
+     * Env vars to scrub when this preset is active. Optional at the
+     * manifest level — an adapter that scrubs in code (like claude-sdk)
+     * may omit it. The catalog does not surface `scrubEnv` to clients.
+     */
+    scrubEnv?: string[];
+    /** Conventional default model id for this provider, if any. */
+    defaultModel?: string;
+    /** Optional homepage/docs URL for the catalog UI. */
+    homepage?: string;
 }
 /**
  * Built-in continuation strategy ids. Future custom strategies require
@@ -266,6 +408,58 @@ interface AgentCliExample {
     prompt: string;
     note?: string;
 }
+/**
+ * AIP-45 § Print protocol configuration.
+ *
+ * When `protocol: "print"`, this block declares the CLI's one-shot
+ * headless surface so the print arm can construct the correct argv and
+ * map the CLI's wire events to {@link StreamEvent}. Omit to use
+ * Claude Code defaults (backward-compatible).
+ */
+interface AgentCliPrintConfig {
+    /**
+     * How the prompt text is passed to the binary.
+     * - absent / `"positional"` — appended as the last positional arg
+     *   (Claude: `claude --print ... <prompt>`).
+     * - a string — passed as `--<prompt_flag> <text>` before any trailing
+     *   positional args (Mastra Code: `--prompt`).
+     */
+    prompt_flag?: string;
+    /**
+     * Output format flags appended before the prompt. Defaults to
+     * `["--output-format", "stream-json"]` (Claude Code).
+     *
+     * Mastra Code uses `["--output", "jsonl"]`.
+     */
+    output_format?: string[];
+    /**
+     * Extra flags inserted between `output_format` and the prompt.
+     * Claude Code uses `["--no-interactive"]`; Mastra Code omits this.
+     */
+    pre_prompt?: string[];
+    /**
+     * Resume / continue flag for reattaching to a prior session.
+     *
+     * Claude:  `{ flag: "--resume", kind: "value" }`
+     * Mastra:  `{ flag: "--continue", kind: "boolean" }` — OR
+     *          `{ flag: "--thread", kind: "value" }` for explicit thread id
+     */
+    resume?: {
+        flag: string;
+        /** "value" = `--flag <sessionId>`, "boolean" = `--flag` (bare). */
+        kind: "value" | "boolean";
+    };
+    /**
+     * Which event taxonomy the CLI emits on stdout (JSONL / stream-json).
+     * The print arm picks the matching event mapper.
+     *
+     * - `"claude-stream-json"` (default) — Claude Code's
+     *   `--output-format stream-json` taxonomy.
+     * - `"mastra-jsonl"` — Mastra Code's `--output jsonl` taxonomy
+     *   (`AgentControllerEvent` shapes).
+     */
+    event_schema?: "claude-stream-json" | "mastra-jsonl";
+}
 interface AgentCliDefinition {
     name: string;
     id: string;
@@ -287,6 +481,8 @@ interface AgentCliDefinition {
     mcp?: AgentCliMcpBlock;
     /** REQUIRED when protocol=proprietary. NPM package implementing AgentCliClient. */
     adapter?: string;
+    /** OPTIONAL when protocol=print. Declares the one-shot CLI surface. */
+    print?: AgentCliPrintConfig;
     session?: AgentCliSession;
     models?: AgentCliModels;
     capabilities?: AgentCliCapabilities;
@@ -294,6 +490,15 @@ interface AgentCliDefinition {
     modes?: AgentCliMode[];
     /** AIP-45 options (independent typed knobs). */
     options?: AgentCliOption[];
+    /**
+     * AIP-45 gateway presets this adapter can drive. Adapter-declared
+     * presets are merged into the provider-preset catalog
+     * (`agentproto presets list` / `list_provider_presets`) alongside the
+     * built-in registry, deduped by id (built-in wins on collision). Lets
+     * an external adapter surface a gateway the built-in registry doesn't
+     * know about without patching `@agentproto/provider-presets`.
+     */
+    presets?: AgentCliPresetDeclaration[];
     /** AIP-45 continuation policy (how prior turns reach the CLI). */
     continuation?: AgentCliContinuation;
     requires?: AgentCliRequires;
@@ -350,6 +555,39 @@ interface AgentCliConnectOptions {
      * `session/set_config_option` with `configId:"effort"` on ACP arms.
      */
     effort?: string;
+    /**
+     * Mode to activate at session start, for ACP arms whose CLI models
+     * mode selection as a session config option rather than an argv/env
+     * surface (`AgentCliMode.apply === "config"`, e.g. opencode). Applied
+     * via `session/set_config_option` with `configId:"mode"` immediately
+     * after `newSession`, best-effort like `model`/`effort`. Adapters that
+     * apply mode via `bin_args`/`env` instead (claude-code) leave this
+     * unset and are unaffected.
+     */
+    mode?: string;
+    /**
+     * Called on ANY adapter-process activity observed by the protocol
+     * arm — incoming ACP `session/update` notifications (even ones that
+     * don't translate into a `StreamEvent`) and outbound RPC calls
+     * (`newSession`/`loadSession`/`prompt`/`cancel`/`setSessionConfigOption`).
+     * Distinct from ring-buffer output: fires during long internal
+     * tool-call chains where no `StreamEvent` reaches the host, so a
+     * supervisor can tell "still working" apart from "gone quiet."
+     * Arms that don't model a stdio JSON-RPC channel (proprietary
+     * one-shots) MAY ignore this field.
+     */
+    onActivity?: () => void;
+    /**
+     * Turn-idle watchdog, forwarded verbatim to the ACP arm's
+     * `createAcpClient({ turnIdleTimeoutMs })` (see
+     * `@agentproto/acp/client`'s `AcpClientOptions.turnIdleTimeoutMs` for
+     * the full contract). If a turn goes this many ms with no activity
+     * signal and the underlying adapter call still hasn't resolved, the
+     * arm synthesizes a `turn-end` event with `reason: "watchdog-timeout"`
+     * instead of hanging forever. Undefined disables the watchdog. Arms
+     * that don't model a stdio JSON-RPC channel MAY ignore this field.
+     */
+    turnIdleTimeoutMs?: number;
 }
 /**
  * Per-turn dispatch shape. Implemented by every protocol arm
@@ -422,6 +660,25 @@ interface AgentCliStartOptions {
      * (e.g. the daemon's orchestration gateway) at spawn time.
      */
     mcpServers?: AcpMcpServer[];
+    /**
+     * Called on any adapter-process activity (ACP JSON-RPC traffic in
+     * either direction). Forwarded verbatim to
+     * `protocolArm.connect({ onActivity })` — see
+     * {@link AgentCliConnectOptions.onActivity} for the full contract.
+     * Lets a host track session liveness independent of ring-buffer
+     * output, e.g. during a long internal tool-call chain.
+     */
+    onActivity?: () => void;
+    /**
+     * Turn-idle watchdog timeout in ms, forwarded to
+     * `protocolArm.connect({ turnIdleTimeoutMs })` — see
+     * {@link AgentCliConnectOptions.turnIdleTimeoutMs}. When omitted here,
+     * `createAgentCliRuntime(...).start()` falls back to the manifest's
+     * `session.turn_idle_timeout_ms` (if the adapter declares one), so a
+     * host doesn't have to opt in per-call for an adapter that always
+     * wants this protection.
+     */
+    turnIdleTimeoutMs?: number;
 }
 /**
  * Operator-side runtime configuration. Mirrors the `runtime.config`
@@ -452,6 +709,15 @@ interface TurnContext {
 }
 interface AgentCliRuntimeSession {
     readonly sessionId: string;
+    /**
+     * OS-level process id of the spawned child, when the runtime owns a
+     * real subprocess (every current arm — ACP, print — does). Lets a
+     * host compute a cheap `processAlive` liveness check
+     * (`process.kill(pid, 0)`) without adapter-specific forensics.
+     * Undefined for a future arm with no owned process (e.g. a
+     * WebSocket transport).
+     */
+    readonly pid?: number;
     send(message: unknown): AsyncIterable<StreamEvent>;
     cancel(): Promise<void>;
     close(): Promise<void>;
@@ -645,10 +911,10 @@ declare const agentCliFrontmatterSchema: z.ZodObject<{
     sandbox: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
     runner: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
     protocol: z.ZodEnum<{
+        print: "print";
         acp: "acp";
         mcp: "mcp";
         proprietary: "proprietary";
-        print: "print";
     }>;
     acp: z.ZodOptional<z.ZodString>;
     mcp: z.ZodOptional<z.ZodObject<{
@@ -662,6 +928,22 @@ declare const agentCliFrontmatterSchema: z.ZodObject<{
         url: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     adapter: z.ZodOptional<z.ZodString>;
+    print: z.ZodOptional<z.ZodObject<{
+        prompt_flag: z.ZodOptional<z.ZodString>;
+        output_format: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        pre_prompt: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        resume: z.ZodOptional<z.ZodObject<{
+            flag: z.ZodString;
+            kind: z.ZodEnum<{
+                boolean: "boolean";
+                value: "value";
+            }>;
+        }, z.core.$strict>>;
+        event_schema: z.ZodOptional<z.ZodEnum<{
+            "claude-stream-json": "claude-stream-json";
+            "mastra-jsonl": "mastra-jsonl";
+        }>>;
+    }, z.core.$strict>>;
     session: z.ZodOptional<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{
             ephemeral: "ephemeral";
@@ -669,12 +951,14 @@ declare const agentCliFrontmatterSchema: z.ZodObject<{
             resumable: "resumable";
         }>>;
         idle_timeout_ms: z.ZodDefault<z.ZodNumber>;
+        turn_idle_timeout_ms: z.ZodOptional<z.ZodNumber>;
         max_turns: z.ZodOptional<z.ZodNumber>;
         context_carryover: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     models: z.ZodOptional<z.ZodObject<{
         default: z.ZodOptional<z.ZodString>;
         allowed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         apply: z.ZodOptional<z.ZodEnum<{
             config: "config";
@@ -694,8 +978,20 @@ declare const agentCliFrontmatterSchema: z.ZodObject<{
     modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
+        bin_args_prepend: z.ZodOptional<z.ZodArray<z.ZodString>>;
         bin_args_append: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        env_unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            noop: "noop";
+            planned: "planned";
+        }>>;
+        status_note: z.ZodOptional<z.ZodString>;
+        apply: z.ZodOptional<z.ZodEnum<{
+            config: "config";
+            bin_args: "bin_args";
+        }>>;
     }, z.core.$strict>>>;
     options: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -710,9 +1006,25 @@ declare const agentCliFrontmatterSchema: z.ZodObject<{
         default: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString]>>;
         min: z.ZodOptional<z.ZodNumber>;
         max: z.ZodOptional<z.ZodNumber>;
+        bin_args_prepend: z.ZodOptional<z.ZodArray<z.ZodString>>;
         bin_args_template: z.ZodOptional<z.ZodArray<z.ZodString>>;
         bin_args_append_when_true: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        env_unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    presets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        schemaFlavor: z.ZodEnum<{
+            anthropic: "anthropic";
+            openai: "openai";
+        }>;
+        baseUrl: z.ZodString;
+        keyEnv: z.ZodString;
+        scrubEnv: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        defaultModel: z.ZodOptional<z.ZodString>;
+        homepage: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
     continuation: z.ZodOptional<z.ZodObject<{
         default: z.ZodEnum<{
@@ -774,4 +1086,4 @@ declare const runtimeConfigSchema: z.ZodObject<{
 }, z.core.$strict>;
 type RuntimeConfigInput = z.infer<typeof runtimeConfigSchema>;
 
-export { type AgentCliHandle as A, agentCliFrontmatterSchema as B, type ContinuationStrategyId as C, runtimeConfigSchema as D, type RuntimeConfig as R, type TurnContext as T, type AgentCliRuntime as a, type AgentCliDefinition as b, type AgentCliClient as c, type AgentCliRuntimeSession as d, type AgentCliStartOptions as e, type ContinuationKeyScope as f, type AgentCliAuth as g, type AgentCliCapabilities as h, type AgentCliConnectOptions as i, type AgentCliContinuation as j, type AgentCliFrontmatter as k, type AgentCliInstallMethod as l, type AgentCliMcpBlock as m, type AgentCliMode as n, type AgentCliModels as o, type AgentCliOption as p, type AgentCliOptionType as q, type AgentCliPinnedSessionTuning as r, type AgentCliProtocol as s, type AgentCliSession as t, type AgentCliSessionMode as u, type AgentCliSetupPersist as v, type AgentCliSetupSkipIf as w, type AgentCliSetupStep as x, type AgentCliVersionCheck as y, type RuntimeConfigInput as z };
+export { type AgentCliHandle as A, type AgentCliVersionCheck as B, type ContinuationStrategyId as C, type RuntimeConfigInput as D, agentCliFrontmatterSchema as E, runtimeConfigSchema as F, type RuntimeConfig as R, type TurnContext as T, type AgentCliRuntime as a, type AgentCliDefinition as b, type AgentCliClient as c, type AgentCliPrintConfig as d, type AgentCliRuntimeSession as e, type AgentCliStartOptions as f, type ContinuationKeyScope as g, type AgentCliAuth as h, type AgentCliCapabilities as i, type AgentCliConnectOptions as j, type AgentCliContinuation as k, type AgentCliFrontmatter as l, type AgentCliInstallMethod as m, type AgentCliMcpBlock as n, type AgentCliMode as o, type AgentCliModels as p, type AgentCliOption as q, type AgentCliOptionType as r, type AgentCliPinnedSessionTuning as s, type AgentCliPresetDeclaration as t, type AgentCliProtocol as u, type AgentCliSession as v, type AgentCliSessionMode as w, type AgentCliSetupPersist as x, type AgentCliSetupSkipIf as y, type AgentCliSetupStep as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentproto/driver-agent-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "@agentproto/driver-agent-cli — AIP-45 AGENT-CLI.md reference implementation. Multi-protocol runner that loads an AGENT-CLI.md manifest, spawns the binary, and dispatches turns through an ACP / MCP / proprietary arm. ACP arm delegates to @agentproto/acp; emits the canonical StreamEvent taxonomy regardless of underlying protocol.",
   "keywords": [
     "agentproto",
@@ -53,7 +53,7 @@
   "dependencies": {
     "gray-matter": "^4.0.3",
     "zod": "^4.4.3",
-    "@agentproto/acp": "0.2.0",
+    "@agentproto/acp": "0.4.0",
     "@agentproto/define-doctype": "0.1.0"
   },
   "devDependencies": {