@agentproto/driver-agent-cli 0.3.0 → 1.0.0

package/dist/{chunk-KHHRPQ2Q.mjs → chunk-XTZNZ7MA.mjs}

@@ -150,6 +150,11 @@ var authSchema = z.object({
     grace_s: z.number().int().nonnegative().optional()
   }).strict().optional()
 }).strict();
+var authSubscriptionSchema = z.object({
+  setEnv: z.string().min(1),
+  conflictEnv: z.array(z.string()).optional(),
+  unsetEnvAdd: z.array(z.string()).optional()
+}).strict();
 var sessionSchema = z.object({
   mode: z.enum(["ephemeral", "persistent", "resumable"]).default("ephemeral"),
   idle_timeout_ms: z.number().int().min(1e3).default(6e5),
@@ -164,6 +169,10 @@ var sessionSchema = z.object({
 var modelsSchema = z.object({
   default: z.string().optional(),
   allowed: z.array(z.string()).optional(),
+  // Model-id patterns the adapter must never route to (case-insensitive,
+  // trailing `*` = prefix match). Enforced at compose time — see
+  // AgentCliModels.deny. Reserves premium providers for dedicated adapters.
+  deny: z.array(z.string()).optional(),
   env: z.record(z.string(), z.string()).optional(),
   // How a model is selected at session start: "config" (ACP
   // set_config_option, default) | "command" (a `/model <id>` control turn,
@@ -190,8 +199,21 @@ var capabilitiesSchema = z.object({
 var modeSchema = z.object({
   id: z.string().regex(MODE_ID_PATTERN),
   description: z.string().optional(),
+  bin_args_prepend: z.array(z.string()).optional(),
   bin_args_append: z.array(z.string()).optional(),
-  env: z.record(z.string(), z.string()).optional()
+  env: z.record(z.string(), z.string()).optional(),
+  // Env keys to DELETE from the spawn env (auth hygiene for gateway
+  // modes — see AgentCliMode.env_unset). Applied at the runtime merge
+  // point, not as a static set.
+  env_unset: z.array(z.string()).optional(),
+  // Honest support status surfaced to clients. Absent ⇒ "active".
+  status: z.enum(["active", "noop", "planned"]).optional(),
+  status_note: z.string().optional(),
+  // How the host activates this mode: "bin_args" (default, argv/env
+  // composed at spawn) | "config" (no CLI surface — forwarded to the ACP
+  // arm's connect({mode}) and applied via session/set_config_option
+  // configId:"mode", e.g. opencode).
+  apply: z.enum(["bin_args", "config"]).optional()
 }).strict();
 var optionSchema = z.object({
   id: z.string().regex(OPTION_ID_PATTERN),
@@ -201,9 +223,14 @@ var optionSchema = z.object({
   default: z.union([z.boolean(), z.number(), z.string()]).optional(),
   min: z.number().int().optional(),
   max: z.number().int().optional(),
+  bin_args_prepend: z.array(z.string()).optional(),
   bin_args_template: z.array(z.string()).optional(),
   bin_args_append_when_true: z.array(z.string()).optional(),
-  env: z.record(z.string(), z.string()).optional()
+  env: z.record(z.string(), z.string()).optional(),
+  // Env keys to DELETE from the spawn env when this option is active
+  // (auth hygiene for value-bearing gateway options — see
+  // AgentCliOption.env_unset). Symmetric with modeSchema.env_unset.
+  env_unset: z.array(z.string()).optional()
 }).strict().refine(
   // type === "enum" REQUIRES an `enum` array. The JSON Schema enforces
   // this via `if/then`; the zod side mirrors with a refine so both
@@ -211,6 +238,17 @@ var optionSchema = z.object({
   (o) => o.type !== "enum" || Array.isArray(o.enum) && o.enum.length > 0,
   { message: "option.type === 'enum' requires a non-empty `enum` array" }
 );
+var presetSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  description: z.string().optional(),
+  schemaFlavor: z.enum(["anthropic", "openai"]),
+  baseUrl: z.string().min(1),
+  keyEnv: z.string().min(1),
+  scrubEnv: z.array(z.string()).optional(),
+  defaultModel: z.string().optional(),
+  homepage: z.string().optional()
+}).strict();
 var continuationStrategyIdSchema = z.enum(CONTINUATION_STRATEGY_IDS);
 var continuationSchema = z.object({
   default: continuationStrategyIdSchema,
@@ -250,10 +288,19 @@ var agentCliFrontmatterSchema = z.object({
   version: z.string().regex(SEMVER_PATTERN),
   bin: z.string().regex(BIN_PATTERN),
   bin_args: z.array(z.string()).optional(),
+  // Always-on spawn env (merged before mode/option env, which can
+  // override). See AgentCliDefinition.env — used by generic ACP agents.
+  env: z.record(z.string(), z.string()).optional(),
   install: z.array(installMethodSchema).min(1),
   version_check: versionCheckSchema,
   setup: z.array(setupStepSchema).optional(),
   auth: authSchema.optional(),
+  // Billing-auth resolver inputs (DECISION 3). `provider` is a CatalogProvider
+  // id (validated against the catalog by the runtime resolver, not here, to
+  // keep this generic doctype decoupled from @agentproto/model-catalog).
+  provider: z.string().min(1).optional(),
+  authSubscription: authSubscriptionSchema.optional(),
+  authEnforce: z.enum(["always", "when-configured"]).optional(),
   sandbox: z.union([z.string(), z.record(z.string(), z.unknown())]),
   runner: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
   protocol: z.enum(["acp", "mcp", "proprietary", "print"]),
@@ -266,6 +313,9 @@ var agentCliFrontmatterSchema = z.object({
   capabilities: capabilitiesSchema.optional(),
   modes: z.array(modeSchema).optional(),
   options: z.array(optionSchema).optional(),
+  // AIP-45 gateway presets this adapter can drive (merged into the
+  // provider-preset catalog; built-in wins on id collision).
+  presets: z.array(presetSchema).optional(),
   continuation: continuationSchema.optional(),
   requires: z.object({
     os: z.array(z.enum(["darwin", "linux", "windows"])).optional(),
@@ -386,11 +436,17 @@ function createAcpProtocolArm(options) {
         },
         onActivity: opts.onActivity,
         turnIdleTimeoutMs: opts.turnIdleTimeoutMs,
+        // Permission-hold mode: surface + park requests for the daemon inbox
+        // instead of auto-answering them in-arm (see AcpProtocolOptions).
+        ...options.permissionHold ? { permissionHold: true } : {},
         // Wire the permission handler so the agent's `session/request_permission`
         // callbacks get a real answer instead of bubbling up as
         // "AcpClient.requestPermission: no handler configured" → which
         // surfaces in the chat as an opaque "Internal error" when the
         // agent tries to Write / Bash anything gated.
+        // `params` is contextually typed as the SDK's `RequestPermissionRequest`
+        // (via `AcpClientOptions.handlers`), which is assignable to
+        // `AcpPermissionRequestParams` — so no cast is needed on either side.
         handlers: {
           requestPermission: async (params) => permissionHandler(params)
         }
@@ -406,7 +462,8 @@ function createAcpProtocolArm(options) {
           cwd,
           mcpServers: opts.mcpServers,
           ...opts.model ? { model: opts.model } : {},
-          ...opts.effort ? { effort: opts.effort } : {}
+          ...opts.effort ? { effort: opts.effort } : {},
+          ...opts.mode ? { mode: opts.mode } : {}
         });
       }
     },
@@ -425,6 +482,9 @@ function createAcpProtocolArm(options) {
       if (!session) return;
       await session.cancel();
     },
+    respondPermission(requestId, resolution) {
+      return client?.respondPermission(requestId, resolution) ?? false;
+    },
     async close() {
       if (session) await session.close();
       if (client) await client.close();
@@ -493,22 +553,26 @@ function createPrintSession(opts) {
       try {
         if (!child.stdout)
           throw new Error("print-arm: child has no stdout pipe");
-        const rl = createInterface({ input: child.stdout, crlfDelay: Infinity });
         let capturedSessionId = "";
         const mastraState = eventSchema === "mastra-jsonl" ? createMastraMapperState() : void 0;
-        for await (const line of rl) {
-          if (!line.trim()) continue;
+        const rl = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        const queue = new EventQueue();
+        rl.on("line", (line) => {
+          if (!line.trim()) return;
           let evt;
           try {
             evt = JSON.parse(line);
           } catch {
-            continue;
+            return;
           }
           const csid = captureSessionId(evt, eventSchema);
           if (csid) capturedSessionId = csid;
           const sid = capturedSessionId || sessionId || "";
           const mapped = mapEvent(evt, sid, stderrLines, eventSchema, mastraState);
-          if (!mapped) continue;
+          if (mapped) queue.push(mapped);
+        });
+        rl.once("close", () => queue.end());
+        for await (const mapped of queue) {
           yield mapped;
         }
         const exitCode = await waitForExit(child);
@@ -774,6 +838,37 @@ function mapMastraEvent(evt, sessionId, stderrLines, state) {
         }
       };
     }
+    // ── Token usage ─────────────────────────────────────────────
+    // Mastra Code DOES expose usage: its `AgentController` emits a native
+    // `usage_update` event ({ type: "usage_update", usage: TokenUsage })
+    // on every model step-finish — verified against @mastra/core 1.48.0's
+    // AgentControllerEvent union and its emit site
+    // (`this.#session.emit({ type: "usage_update", usage: stepUsage })`).
+    // `TokenUsage` carries `{ promptTokens, completionTokens, totalTokens }`.
+    // Map it to this repo's `usage_update` StreamEvent (the SAME shape
+    // claude-code emits over ACP) so mastracode sessions — both the print
+    // arm and the in-process arm, which share this mapper — carry token
+    // telemetry in the transcript. mastracode reports these cumulatively
+    // (its own headless `runMC` result-usage is last-write-wins over these
+    // events), and last-write-wins on the descriptor matches that. It
+    // carries no context-window size/used or per-turn cost here, so those
+    // stay 0 / absent (projectEvent guards on >0, never clobbering a real
+    // size).
+    case "usage_update": {
+      const usage = evt.usage;
+      const promptTokens = typeof usage?.promptTokens === "number" ? usage.promptTokens : void 0;
+      const completionTokens = typeof usage?.completionTokens === "number" ? usage.completionTokens : void 0;
+      if (promptTokens === void 0 && completionTokens === void 0)
+        return null;
+      return {
+        kind: "usage_update",
+        sessionId,
+        size: 0,
+        used: 0,
+        ...promptTokens !== void 0 ? { tokensIn: promptTokens } : {},
+        ...completionTokens !== void 0 ? { tokensOut: completionTokens } : {}
+      };
+    }
     // ── Shell output (tool-like) ────────────────────────────────
     case "shell_output":
       return typeof evt.output === "string" ? {
@@ -794,6 +889,45 @@ function mapMastraEvent(evt, sessionId, stderrLines, state) {
       return null;
   }
 }
+var QUEUE_HIGH_WATER_MARK = 1e4;
+var EventQueue = class {
+  buffer = [];
+  resolveNext = null;
+  ended = false;
+  highWaterWarned = false;
+  push(evt) {
+    this.buffer.push(evt);
+    if (this.buffer.length > QUEUE_HIGH_WATER_MARK && !this.highWaterWarned) {
+      this.highWaterWarned = true;
+      console.warn(
+        `print-arm: event backlog exceeded ${QUEUE_HIGH_WATER_MARK} buffered events \u2014 downstream consumer is not keeping up. The child's stdout is still being drained (no ENOBUFS), but memory will grow until the consumer catches up.`
+      );
+    }
+    const resolve = this.resolveNext;
+    this.resolveNext = null;
+    resolve?.();
+  }
+  /** Signal that no further events will be pushed. */
+  end() {
+    this.ended = true;
+    const resolve = this.resolveNext;
+    this.resolveNext = null;
+    resolve?.();
+  }
+  async *[Symbol.asyncIterator]() {
+    for (; ; ) {
+      const evt = this.buffer.shift();
+      if (evt !== void 0) {
+        yield evt;
+        continue;
+      }
+      if (this.ended) return;
+      await new Promise((resolve) => {
+        this.resolveNext = resolve;
+      });
+    }
+  }
+};
 function mapMastraFinishReason(raw) {
   switch (raw) {
     case "complete":
@@ -847,9 +981,16 @@ var RuntimeConfigError = class extends Error {
   }
 };
 function composeSpawn(handle, config) {
-  const binArgs = [...handle.bin_args ?? []];
-  const env = {};
-  if (!config) return { binArgs, env };
+  if (!config)
+    return {
+      binArgs: [...handle.bin_args ?? []],
+      env: { ...handle.env ?? {} },
+      envUnset: []
+    };
+  const prepend = [];
+  const append = [];
+  const env = { ...handle.env ?? {} };
+  const envUnset = [];
   if (config.mode !== void 0) {
     const mode = (handle.modes ?? []).find((m) => m.id === config.mode);
     if (!mode) {
@@ -860,8 +1001,12 @@ function composeSpawn(handle, config) {
         `Mode '${config.mode}' is not declared by manifest '${handle.id}'. Known modes: ${known}`
       );
     }
-    if (mode.bin_args_append) binArgs.push(...mode.bin_args_append);
-    if (mode.env) Object.assign(env, mode.env);
+    if ((mode.apply ?? "bin_args") === "bin_args") {
+      if (mode.bin_args_prepend) prepend.push(...mode.bin_args_prepend);
+      if (mode.bin_args_append) append.push(...mode.bin_args_append);
+      if (mode.env) Object.assign(env, mode.env);
+      if (mode.env_unset) envUnset.push(...mode.env_unset);
+    }
   }
   if (config.options && Object.keys(config.options).length > 0) {
     const declared = handle.options ?? [];
@@ -881,8 +1026,23 @@ function composeSpawn(handle, config) {
       const value = config.options[option.id];
       validateOptionValue(option, value);
       const patch = renderOptionPatch(option, value);
-      binArgs.push(...patch.binArgs);
+      prepend.push(...patch.prepend);
+      append.push(...patch.append);
       Object.assign(env, patch.env);
+      if (patch.envUnset.length) envUnset.push(...patch.envUnset);
+    }
+  }
+  const requestedModel = config.options?.model;
+  if (typeof requestedModel === "string" && handle.models?.deny?.length) {
+    const denyHit = handle.models.deny.find(
+      (pattern) => matchesModelPattern(pattern, requestedModel)
+    );
+    if (denyHit) {
+      throw new RuntimeConfigError(
+        "model_denied",
+        "config.options.model",
+        `Model '${requestedModel}' is denied by manifest '${handle.id}' (matches deny pattern '${denyHit}'). This adapter deliberately does not route to that provider \u2014 use a permitted model or a different adapter.`
+      );
     }
   }
   if (config.continuation !== void 0 && handle.continuation) {
@@ -894,12 +1054,21 @@ function composeSpawn(handle, config) {
       );
     }
   }
-  return { binArgs, env };
+  return {
+    binArgs: [...prepend, ...handle.bin_args ?? [], ...append],
+    env,
+    envUnset
+  };
 }
 function resolveContinuationStrategy(handle, config) {
   if (config?.continuation) return config.continuation;
   return handle.continuation?.default ?? "none";
 }
+function matchesModelPattern(pattern, modelId) {
+  const p = pattern.toLowerCase();
+  const m = modelId.toLowerCase();
+  return p.endsWith("*") ? m.startsWith(p.slice(0, -1)) : m === p;
+}
 function validateOptionValue(option, value) {
   const path = `config.options.${option.id}`;
   switch (option.type) {
@@ -965,17 +1134,23 @@ function validateOptionValue(option, value) {
 function renderOptionPatch(option, value) {
   const stringValue = String(value);
   if (option.type === "boolean") {
-    if (value !== true) return { binArgs: [], env: {} };
+    if (value !== true) return { prepend: [], append: [], env: {}, envUnset: [] };
     return {
-      binArgs: option.bin_args_append_when_true ? [...option.bin_args_append_when_true] : [],
-      env: option.env ? interpolateEnv(option.env, stringValue) : {}
+      prepend: [],
+      append: option.bin_args_append_when_true ? [...option.bin_args_append_when_true] : [],
+      env: option.env ? interpolateEnv(option.env, stringValue) : {},
+      envUnset: option.env_unset ? [...option.env_unset] : []
     };
   }
   return {
-    binArgs: option.bin_args_template ? option.bin_args_template.map(
+    prepend: option.bin_args_prepend ? option.bin_args_prepend.map(
+      (token) => token.replace(/\{value\}/g, stringValue)
+    ) : [],
+    append: option.bin_args_template ? option.bin_args_template.map(
       (token) => token.replace(/\{value\}/g, stringValue)
     ) : [],
-    env: option.env ? interpolateEnv(option.env, stringValue) : {}
+    env: option.env ? interpolateEnv(option.env, stringValue) : {},
+    envUnset: option.env_unset ? [...option.env_unset] : []
   };
 }
 function interpolateEnv(env, value) {
@@ -1032,9 +1207,26 @@ function createAgentCliRuntime(definition) {
       const composed = composeSpawn(definition, opts?.config);
       const env = {
         ...filterStringEnv(process.env),
-        ...composed.env,
-        ...opts?.env ?? {}
+        ...composed.env
       };
+      for (const k of composed.envUnset) delete env[k];
+      const authSpec = opts?.auth;
+      const hasGatewayAuthToken = "ANTHROPIC_AUTH_TOKEN" in composed.env;
+      const engageAuth = !!authSpec && !hasGatewayAuthToken && (authSpec.enforce === "always" || authSpec.explicit === true);
+      if (authSpec && engageAuth) {
+        for (const key of authSpec.unsetEnv) {
+          if (!(key in composed.env)) delete env[key];
+        }
+        if (!authSpec.credential) {
+          throw new RuntimeConfigError(
+            "missing_auth_credential",
+            "opts.auth.credential",
+            `agent-cli '${definition.id}': auth mode "${authSpec.mode}" requires an explicit credential (resolved from a named config/store ref), but none was provided.` + (authSpec.mode === "subscription" ? ` Mint one via \`claude setup-token\` (bills the Max/Pro subscription, not API credits) and configure it \u2014 never inherited from the shell.` : ` Configure an API key (\`agentproto auth provider set \u2026\` or per-spawn) \u2014 never inherited from the shell.`)
+          );
+        }
+        env[authSpec.setEnv] = authSpec.credential;
+      }
+      Object.assign(env, opts?.env ?? {});
       const permissionMode = resolveClaudeCodePermissionMode(
         definition,
         opts?.config?.mode
@@ -1079,7 +1271,13 @@ function createAgentCliRuntime(definition) {
           }
         });
       }
-      const arm = await buildProtocolArm(definition, child, cwd, opts?.config?.mode);
+      const arm = await buildProtocolArm(
+        definition,
+        child,
+        cwd,
+        opts?.config?.mode,
+        opts?.permissionHold ?? false
+      );
       arm._stderrTail = () => stderrBuf.join("\n");
       const abortController = new AbortController();
       if (opts?.signal) {
@@ -1091,6 +1289,9 @@ function createAgentCliRuntime(definition) {
       const optEffort = opts?.config?.options?.effort;
       const modelApply = definition.models?.apply ?? "config";
       const configModel = optModel && modelApply === "config" ? String(optModel) : void 0;
+      const requestedModeId = opts?.config?.mode;
+      const requestedModeDecl = requestedModeId ? (definition.modes ?? []).find((m) => m.id === requestedModeId) : void 0;
+      const configMode = requestedModeDecl?.apply === "config" ? requestedModeId : void 0;
       const turnIdleTimeoutMs = opts?.turnIdleTimeoutMs ?? definition.session?.turn_idle_timeout_ms;
       await arm.connect({
         cwd,
@@ -1100,8 +1301,10 @@ function createAgentCliRuntime(definition) {
         ...opts?.mcpServers ? { mcpServers: opts.mcpServers } : {},
         ...configModel ? { model: configModel } : {},
         ...optEffort ? { effort: String(optEffort) } : {},
+        ...configMode ? { mode: configMode } : {},
         ...opts?.onActivity ? { onActivity: opts.onActivity } : {},
-        ...turnIdleTimeoutMs !== void 0 ? { turnIdleTimeoutMs } : {}
+        ...turnIdleTimeoutMs !== void 0 ? { turnIdleTimeoutMs } : {},
+        ...opts?.permissionHold ? { permissionHold: true } : {}
       });
       if (optModel && modelApply === "command") {
         await applyModelCommand(arm, String(optModel));
@@ -1117,6 +1320,11 @@ function createAgentCliRuntime(definition) {
         async cancel() {
           abortController.abort();
         },
+        ...arm.respondPermission ? {
+          respondPermission(requestId, resolution) {
+            return arm.respondPermission(requestId, resolution);
+          }
+        } : {},
         async close() {
           await arm.close();
           if (child && !child.killed) child.kill("SIGTERM");
@@ -1162,7 +1370,7 @@ async function* promptTurn(arm, turnId, message) {
     yield evt;
   }
 }
-async function buildProtocolArm(def, child, cwd, requestedMode) {
+async function buildProtocolArm(def, child, cwd, requestedMode, permissionHold) {
   switch (def.protocol) {
     case "acp":
       if (!child) {
@@ -1172,7 +1380,8 @@ async function buildProtocolArm(def, child, cwd, requestedMode) {
         child,
         cwd,
         clientInfo: { name: def.id, version: def.version },
-        requestedMode
+        requestedMode,
+        ...permissionHold ? { permissionHold: true } : {}
       });
     case "mcp":
       throw new Error("createAgentCliRuntime: mcp protocol arm not yet implemented");
@@ -1204,5 +1413,5 @@ function filterStringEnv(env) {
 }
 
 export { RuntimeConfigError, agentCliFrontmatterSchema, autoAllowPermissionHandler, composeSpawn, createAcpProtocolArm, createAgentCliRuntime, createMastraMapperState, createPrintSession, createProprietaryProtocolArm, defineAgentCli, mapMastraEvent, planModePermissionHandler, resolveContinuationStrategy, runtimeConfigSchema, toFileBasedMcpServers };
-//# sourceMappingURL=chunk-KHHRPQ2Q.mjs.map
-//# sourceMappingURL=chunk-KHHRPQ2Q.mjs.map
+//# sourceMappingURL=chunk-XTZNZ7MA.mjs.map
+//# sourceMappingURL=chunk-XTZNZ7MA.mjs.map