octoflow-core 1.0.0

package/dist/adapters/agents/backends/claude-code-cli.js

@@ -0,0 +1,146 @@
+import crypto from "node:crypto";
+import { buildPromptEnvelope } from "../../../prompts/envelope.js";
+import { sanitizePath } from "../../../utils/sanitize.js";
+import { APPROVAL_POSTURE_CLAUDE_CODE_CLI } from "../approval-posture.js";
+import { buildCliExecutionPlan } from "./cli-runner.js";
+import {
+  buildClaudeSettings,
+  getAdditionalAccessibleRoots,
+  mapClaudePermissionMode
+} from "./security-flags.js";
+import {
+  BACKEND_METADATA,
+  createCliBackendBase,
+  getCliVersion,
+  isCliInstalledAsync,
+  readCliConfigModel
+} from "./shared.js";
+const META = BACKEND_METADATA["claude-code-cli"];
+const CLI_CMD = META.cli ?? "claude";
+const CAPABILITIES = {
+  streaming: true,
+  sessionPersistence: true,
+  workingDirectory: true,
+  forceMode: true,
+  systemPrompt: true,
+  planning: true,
+  tools: true,
+  structuredOutput: true,
+  mcp: true,
+  approvalCallback: APPROVAL_POSTURE_CLAUDE_CODE_CLI
+};
+const permission = ({ request, policy }) => {
+  const mode = request.readOnly ? "plan" : mapClaudePermissionMode(policy);
+  return mode ? { args: ["--permission-mode", mode] } : void 0;
+};
+const session = ({ request, sessionId }) => {
+  if (request.isResume && request.sessionId) {
+    return {
+      args: ["--resume", request.sessionId],
+      stdinOverride: buildPromptEnvelope({
+        systemPrompt: request.systemPrompt,
+        userMessage: request.prompt
+      })
+    };
+  }
+  const args = ["--session-id", sessionId];
+  if (request.systemPrompt) args.push("--system-prompt", request.systemPrompt);
+  return { args, stdinOverride: request.prompt };
+};
+const appendSystemPrompt = ({ request }) => request.appendSystemPrompt ? { args: ["--append-system-prompt", request.appendSystemPrompt] } : void 0;
+const excludeDynamicSystemPromptSections = ({ request }) => request.excludeDynamicSystemPromptSections ? { args: ["--exclude-dynamic-system-prompt-sections"] } : void 0;
+const model = ({ request }) => {
+  const m = request.requestedModel || request.configModel;
+  return m ? { args: ["--model", m] } : void 0;
+};
+const effort = ({ request }) => request.effort ? { args: ["--effort", request.effort] } : void 0;
+const worktree = ({ request }) => {
+  if (!request.worktree) return void 0;
+  const args = ["--worktree"];
+  if (typeof request.worktree === "string") args.push(request.worktree);
+  return { args };
+};
+const allowedTools = ({ request }) => request.allowedTools && request.allowedTools.length > 0 ? { args: ["--allowedTools", ...request.allowedTools] } : void 0;
+const disallowedTools = ({ request }) => request.disallowedTools && request.disallowedTools.length > 0 ? { args: ["--disallowedTools", ...request.disallowedTools] } : void 0;
+const extraDirs = ({ policy }) => {
+  const args = [];
+  for (const directory of getAdditionalAccessibleRoots(policy)) {
+    const sanitized = sanitizePath(directory);
+    if (sanitized) args.push("--add-dir", sanitized);
+  }
+  return args.length > 0 ? { args } : void 0;
+};
+const sandbox = ({ policy }) => {
+  const settings = buildClaudeSettings(policy);
+  return settings ? { args: ["--settings", settings] } : void 0;
+};
+const mcp = ({ request }) => request.mcpConfigPath ? { args: ["--mcp-config", request.mcpConfigPath] } : void 0;
+const strictMcp = ({ request }) => request.strictMcpConfig ? { args: ["--strict-mcp-config"] } : void 0;
+const outputSchema = ({ request }) => {
+  if (request.outputSchema === void 0) return void 0;
+  const serialized = typeof request.outputSchema === "string" ? request.outputSchema : JSON.stringify(request.outputSchema);
+  return { args: ["--json-schema", serialized] };
+};
+const maxBudgetUsd = ({ request }) => request.maxBudgetUsd && request.maxBudgetUsd > 0 ? { args: ["--max-budget-usd", String(request.maxBudgetUsd)] } : void 0;
+const bare = ({ request }) => request.bare ? { args: ["--bare"] } : void 0;
+const CLAUDE_DESCRIPTOR = {
+  name: "claude-code-cli",
+  streamParserName: "claude",
+  prelude: ["-p"],
+  tail: [
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--include-partial-messages"
+  ],
+  defaultStdinIsEnvelope: false,
+  planSessionIdStrategy: "preserve-on-resume",
+  capabilities: CAPABILITIES,
+  features: {
+    permission,
+    sandbox,
+    extraDirs,
+    session,
+    appendSystemPrompt,
+    excludeDynamicSystemPromptSections,
+    model,
+    effort,
+    worktree,
+    allowedTools,
+    disallowedTools,
+    mcp,
+    strictMcp,
+    outputSchema,
+    maxBudgetUsd,
+    bare
+  }
+};
+function createClaudeCodeBackend() {
+  return {
+    ...createCliBackendBase(META, CAPABILITIES, "claude", {
+      resolveInstalled: () => isCliInstalledAsync(CLI_CMD),
+      resolveVersion: () => getCliVersion(`${CLI_CMD} --version`),
+      // Read model from ~/.claude/settings.json when the user has configured
+      // a non-default model. Falls back to META.defaultModel ('sonnet') when
+      // the settings file has no model key.
+      resolveConfigModel: () => readCliConfigModel("claude-code-cli")
+    }),
+    validateModel(modelName) {
+      return META.models.includes(modelName);
+    },
+    generateSessionId() {
+      return crypto.randomUUID();
+    },
+    buildExecutionPlan(request) {
+      return buildCliExecutionPlan(CLI_CMD, CLAUDE_DESCRIPTOR, request);
+    },
+    extractSessionId(_output) {
+      return null;
+    }
+  };
+}
+export {
+  CLAUDE_DESCRIPTOR,
+  createClaudeCodeBackend
+};
+//# sourceMappingURL=claude-code-cli.js.map

package/dist/adapters/agents/backends/claude-code-cli.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/adapters/agents/backends/claude-code-cli.ts"],
+  "sourcesContent": ["import crypto from 'node:crypto';\n\nimport type {\n  Backend,\n  BackendCapabilities,\n} from '../../../domain/contracts/backends.js';\nimport type {\n  CliBackendDescriptor,\n  CliFeatureHandler,\n} from '../../../domain/contracts/cli-backends.js';\nimport { buildPromptEnvelope } from '../../../prompts/envelope.js';\nimport { sanitizePath } from '../../../utils/sanitize.js';\nimport { APPROVAL_POSTURE_CLAUDE_CODE_CLI } from '../approval-posture.js';\nimport { buildCliExecutionPlan } from './cli-runner.js';\nimport {\n  buildClaudeSettings,\n  getAdditionalAccessibleRoots,\n  mapClaudePermissionMode,\n} from './security-flags.js';\nimport {\n  BACKEND_METADATA,\n  createCliBackendBase,\n  getCliVersion,\n  isCliInstalledAsync,\n  readCliConfigModel,\n} from './shared.js';\n\nconst META = BACKEND_METADATA['claude-code-cli'];\nconst CLI_CMD = META.cli ?? 'claude';\n\nconst CAPABILITIES: BackendCapabilities = {\n  streaming: true,\n  sessionPersistence: true,\n  workingDirectory: true,\n  forceMode: true,\n  systemPrompt: true,\n  planning: true,\n  tools: true,\n  structuredOutput: true,\n  mcp: true,\n  approvalCallback: APPROVAL_POSTURE_CLAUDE_CODE_CLI,\n};\n\nconst permission: CliFeatureHandler = ({ request, policy }) => {\n  const mode = request.readOnly ? 'plan' : mapClaudePermissionMode(policy);\n  return mode ? { args: ['--permission-mode', mode] } : undefined;\n};\n\nconst session: CliFeatureHandler = ({ request, sessionId }) => {\n  if (request.isResume && request.sessionId) {\n    return {\n      args: ['--resume', request.sessionId],\n      stdinOverride: buildPromptEnvelope({\n        systemPrompt: request.systemPrompt,\n        userMessage: request.prompt,\n      }),\n    };\n  }\n  const args = ['--session-id', sessionId];\n  if (request.systemPrompt) args.push('--system-prompt', request.systemPrompt);\n  return { args, stdinOverride: request.prompt };\n};\n\nconst appendSystemPrompt: CliFeatureHandler = ({ request }) =>\n  request.appendSystemPrompt\n    ? { args: ['--append-system-prompt', request.appendSystemPrompt] }\n    : undefined;\n\nconst excludeDynamicSystemPromptSections: CliFeatureHandler = ({ request }) =>\n  request.excludeDynamicSystemPromptSections\n    ? { args: ['--exclude-dynamic-system-prompt-sections'] }\n    : undefined;\n\n// Model resolution priority:\n//   1. requestedModel \u2014 set by the caller via createAgent({ model }) or sendMessage({ model })\n//   2. configModel    \u2014 read from ~/.claude/settings.json at backend creation time\n//   3. (no flag)      \u2014 let the claude CLI use its own current default\n//\n// Omitting --model when no model is known lets claude pick its own latest\n// default rather than pinning a hardcoded alias that may lag behind releases.\nconst model: CliFeatureHandler = ({ request }) => {\n  const m = request.requestedModel || request.configModel;\n  return m ? { args: ['--model', m] } : undefined;\n};\n\nconst effort: CliFeatureHandler = ({ request }) =>\n  request.effort ? { args: ['--effort', request.effort] } : undefined;\n\nconst worktree: CliFeatureHandler = ({ request }) => {\n  if (!request.worktree) return undefined;\n  const args = ['--worktree'];\n  if (typeof request.worktree === 'string') args.push(request.worktree);\n  return { args };\n};\n\nconst allowedTools: CliFeatureHandler = ({ request }) =>\n  request.allowedTools && request.allowedTools.length > 0\n    ? { args: ['--allowedTools', ...request.allowedTools] }\n    : undefined;\n\nconst disallowedTools: CliFeatureHandler = ({ request }) =>\n  request.disallowedTools && request.disallowedTools.length > 0\n    ? { args: ['--disallowedTools', ...request.disallowedTools] }\n    : undefined;\n\nconst extraDirs: CliFeatureHandler = ({ policy }) => {\n  const args: string[] = [];\n  for (const directory of getAdditionalAccessibleRoots(policy)) {\n    const sanitized = sanitizePath(directory);\n    if (sanitized) args.push('--add-dir', sanitized);\n  }\n  return args.length > 0 ? { args } : undefined;\n};\n\nconst sandbox: CliFeatureHandler = ({ policy }) => {\n  const settings = buildClaudeSettings(policy);\n  return settings ? { args: ['--settings', settings] } : undefined;\n};\n\nconst mcp: CliFeatureHandler = ({ request }) =>\n  request.mcpConfigPath\n    ? { args: ['--mcp-config', request.mcpConfigPath] }\n    : undefined;\n\nconst strictMcp: CliFeatureHandler = ({ request }) =>\n  request.strictMcpConfig ? { args: ['--strict-mcp-config'] } : undefined;\n\nconst outputSchema: CliFeatureHandler = ({ request }) => {\n  if (request.outputSchema === undefined) return undefined;\n  const serialized =\n    typeof request.outputSchema === 'string'\n      ? request.outputSchema\n      : JSON.stringify(request.outputSchema);\n  return { args: ['--json-schema', serialized] };\n};\n\nconst maxBudgetUsd: CliFeatureHandler = ({ request }) =>\n  request.maxBudgetUsd && request.maxBudgetUsd > 0\n    ? { args: ['--max-budget-usd', String(request.maxBudgetUsd)] }\n    : undefined;\n\nconst bare: CliFeatureHandler = ({ request }) =>\n  request.bare ? { args: ['--bare'] } : undefined;\n\nexport const CLAUDE_DESCRIPTOR: CliBackendDescriptor = {\n  name: 'claude-code-cli',\n  streamParserName: 'claude',\n  prelude: ['-p'],\n  tail: [\n    '--output-format',\n    'stream-json',\n    '--verbose',\n    '--include-partial-messages',\n  ],\n  defaultStdinIsEnvelope: false,\n  planSessionIdStrategy: 'preserve-on-resume',\n  capabilities: CAPABILITIES,\n  features: {\n    permission,\n    sandbox,\n    extraDirs,\n    session,\n    appendSystemPrompt,\n    excludeDynamicSystemPromptSections,\n    model,\n    effort,\n    worktree,\n    allowedTools,\n    disallowedTools,\n    mcp,\n    strictMcp,\n    outputSchema,\n    maxBudgetUsd,\n    bare,\n  },\n};\n\nexport function createClaudeCodeBackend(): Backend {\n  return {\n    ...createCliBackendBase(META, CAPABILITIES, 'claude', {\n      resolveInstalled: () => isCliInstalledAsync(CLI_CMD),\n      resolveVersion: () => getCliVersion(`${CLI_CMD} --version`),\n      // Read model from ~/.claude/settings.json when the user has configured\n      // a non-default model. Falls back to META.defaultModel ('sonnet') when\n      // the settings file has no model key.\n      resolveConfigModel: () => readCliConfigModel('claude-code-cli'),\n    }),\n\n    validateModel(modelName: string): boolean {\n      return META.models.includes(modelName);\n    },\n\n    generateSessionId(): string {\n      return crypto.randomUUID();\n    },\n\n    buildExecutionPlan(request) {\n      return buildCliExecutionPlan(CLI_CMD, CLAUDE_DESCRIPTOR, request);\n    },\n\n    extractSessionId(_output: string): string | null {\n      return null;\n    },\n  };\n}\n"],
+  "mappings": "AAAA,OAAO,YAAY;AAUnB,SAAS,2BAA2B;AACpC,SAAS,oBAAoB;AAC7B,SAAS,wCAAwC;AACjD,SAAS,6BAA6B;AACtC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,MAAM,OAAO,iBAAiB,iBAAiB;AAC/C,MAAM,UAAU,KAAK,OAAO;AAE5B,MAAM,eAAoC;AAAA,EACxC,WAAW;AAAA,EACX,oBAAoB;AAAA,EACpB,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,cAAc;AAAA,EACd,UAAU;AAAA,EACV,OAAO;AAAA,EACP,kBAAkB;AAAA,EAClB,KAAK;AAAA,EACL,kBAAkB;AACpB;AAEA,MAAM,aAAgC,CAAC,EAAE,SAAS,OAAO,MAAM;AAC7D,QAAM,OAAO,QAAQ,WAAW,SAAS,wBAAwB,MAAM;AACvE,SAAO,OAAO,EAAE,MAAM,CAAC,qBAAqB,IAAI,EAAE,IAAI;AACxD;AAEA,MAAM,UAA6B,CAAC,EAAE,SAAS,UAAU,MAAM;AAC7D,MAAI,QAAQ,YAAY,QAAQ,WAAW;AACzC,WAAO;AAAA,MACL,MAAM,CAAC,YAAY,QAAQ,SAAS;AAAA,MACpC,eAAe,oBAAoB;AAAA,QACjC,cAAc,QAAQ;AAAA,QACtB,aAAa,QAAQ;AAAA,MACvB,CAAC;AAAA,IACH;AAAA,EACF;AACA,QAAM,OAAO,CAAC,gBAAgB,SAAS;AACvC,MAAI,QAAQ,aAAc,MAAK,KAAK,mBAAmB,QAAQ,YAAY;AAC3E,SAAO,EAAE,MAAM,eAAe,QAAQ,OAAO;AAC/C;AAEA,MAAM,qBAAwC,CAAC,EAAE,QAAQ,MACvD,QAAQ,qBACJ,EAAE,MAAM,CAAC,0BAA0B,QAAQ,kBAAkB,EAAE,IAC/D;AAEN,MAAM,qCAAwD,CAAC,EAAE,QAAQ,MACvE,QAAQ,qCACJ,EAAE,MAAM,CAAC,0CAA0C,EAAE,IACrD;AASN,MAAM,QAA2B,CAAC,EAAE,QAAQ,MAAM;AAChD,QAAM,IAAI,QAAQ,kBAAkB,QAAQ;AAC5C,SAAO,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI;AACxC;AAEA,MAAM,SAA4B,CAAC,EAAE,QAAQ,MAC3C,QAAQ,SAAS,EAAE,MAAM,CAAC,YAAY,QAAQ,MAAM,EAAE,IAAI;AAE5D,MAAM,WAA8B,CAAC,EAAE,QAAQ,MAAM;AACnD,MAAI,CAAC,QAAQ,SAAU,QAAO;AAC9B,QAAM,OAAO,CAAC,YAAY;AAC1B,MAAI,OAAO,QAAQ,aAAa,SAAU,MAAK,KAAK,QAAQ,QAAQ;AACpE,SAAO,EAAE,KAAK;AAChB;AAEA,MAAM,eAAkC,CAAC,EAAE,QAAQ,MACjD,QAAQ,gBAAgB,QAAQ,aAAa,SAAS,IAClD,EAAE,MAAM,CAAC,kBAAkB,GAAG,QAAQ,YAAY,EAAE,IACpD;AAEN,MAAM,kBAAqC,CAAC,EAAE,QAAQ,MACpD,QAAQ,mBAAmB,QAAQ,gBAAgB,SAAS,IACxD,EAAE,MAAM,CAAC,qBAAqB,GAAG,QAAQ,eAAe,EAAE,IAC1D;AAEN,MAAM,YAA+B,CAAC,EAAE,OAAO,MAAM;AACnD,QAAM,OAAiB,CAAC;AACxB,aAAW,aAAa,6BAA6B,MAAM,GAAG;AAC5D,UAAM,YAAY,aAAa,SAAS;AACxC,QAAI,UAAW,MAAK,KAAK,aAAa,SAAS;AAAA,EACjD;AACA,SAAO,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI;AACtC;AAEA,MAAM,UAA6B,CAAC,EAAE,OAAO,MAAM;AACjD,QAAM,WAAW,oBAAoB,MAAM;AAC3C,SAAO,WAAW,EAAE,MAAM,CAAC,cAAc,QAAQ,EAAE,IAAI;AACzD;AAEA,MAAM,MAAyB,CAAC,EAAE,QAAQ,MACxC,QAAQ,gBACJ,EAAE,MAAM,CAAC,gBAAgB,QAAQ,aAAa,EAAE,IAChD;AAEN,MAAM,YAA+B,CAAC,EAAE,QAAQ,MAC9C,QAAQ,kBAAkB,EAAE,MAAM,CAAC,qBAAqB,EAAE,IAAI;AAEhE,MAAM,eAAkC,CAAC,EAAE,QAAQ,MAAM;AACvD,MAAI,QAAQ,iBAAiB,OAAW,QAAO;AAC/C,QAAM,aACJ,OAAO,QAAQ,iBAAiB,WAC5B,QAAQ,eACR,KAAK,UAAU,QAAQ,YAAY;AACzC,SAAO,EAAE,MAAM,CAAC,iBAAiB,UAAU,EAAE;AAC/C;AAEA,MAAM,eAAkC,CAAC,EAAE,QAAQ,MACjD,QAAQ,gBAAgB,QAAQ,eAAe,IAC3C,EAAE,MAAM,CAAC,oBAAoB,OAAO,QAAQ,YAAY,CAAC,EAAE,IAC3D;AAEN,MAAM,OAA0B,CAAC,EAAE,QAAQ,MACzC,QAAQ,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI;AAEjC,MAAM,oBAA0C;AAAA,EACrD,MAAM;AAAA,EACN,kBAAkB;AAAA,EAClB,SAAS,CAAC,IAAI;AAAA,EACd,MAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,wBAAwB;AAAA,EACxB,uBAAuB;AAAA,EACvB,cAAc;AAAA,EACd,UAAU;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEO,SAAS,0BAAmC;AACjD,SAAO;AAAA,IACL,GAAG,qBAAqB,MAAM,cAAc,UAAU;AAAA,MACpD,kBAAkB,MAAM,oBAAoB,OAAO;AAAA,MACnD,gBAAgB,MAAM,cAAc,GAAG,OAAO,YAAY;AAAA;AAAA;AAAA;AAAA,MAI1D,oBAAoB,MAAM,mBAAmB,iBAAiB;AAAA,IAChE,CAAC;AAAA,IAED,cAAc,WAA4B;AACxC,aAAO,KAAK,OAAO,SAAS,SAAS;AAAA,IACvC;AAAA,IAEA,oBAA4B;AAC1B,aAAO,OAAO,WAAW;AAAA,IAC3B;AAAA,IAEA,mBAAmB,SAAS;AAC1B,aAAO,sBAAsB,SAAS,mBAAmB,OAAO;AAAA,IAClE;AAAA,IAEA,iBAAiB,SAAgC;AAC/C,aAAO;AAAA,IACT;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/adapters/agents/backends/cli-feature-matrix.d.ts

@@ -0,0 +1,39 @@
+import type { BackendRunRequest } from '../../../domain/contracts/backends.js';
+import type { CliBackendDescriptor, CliFeatureKey } from '../../../domain/contracts/cli-backends.js';
+/**
+ * Snapshot of which backends declare a handler for which feature. Feeds the
+ * `octoflow inspect` view, the `UNSUPPORTED_FEATURE_FOR_BACKEND` warning, and
+ * the contract test that gates GAP-5 (capabilities ↔ handler agreement).
+ */
+export interface CliFeatureMatrix {
+    backends: readonly string[];
+    features: readonly CliFeatureKey[];
+    /** `true` when the descriptor for `backend` registers a handler under `feature`. */
+    supports(backend: string, feature: CliFeatureKey): boolean;
+    /** Features this descriptor does not honor (silently dropped today). */
+    unsupportedFor(backend: string): readonly CliFeatureKey[];
+}
+export declare function buildCliFeatureMatrix(descriptors: readonly CliBackendDescriptor[]): CliFeatureMatrix;
+/**
+ * Returns request-field/feature pairs that the chosen backend will silently
+ * drop given the current request. Callers can map each pair into a
+ * `bridge:warn` (`UNSUPPORTED_FEATURE_FOR_BACKEND`) emission.
+ */
+export declare function findUnsupportedRequestFields(matrix: CliFeatureMatrix, backend: string, request: BackendRunRequest): Array<{
+    field: keyof BackendRunRequest;
+    feature: CliFeatureKey;
+}>;
+/** Built-in CLI descriptors. Used by the runtime warning + inspect command. */
+export declare const BUILT_IN_CLI_DESCRIPTORS: readonly CliBackendDescriptor[];
+/**
+ * Lazily-built matrix over the built-in CLI descriptors. Cached for the
+ * process lifetime — descriptors are immutable singletons.
+ */
+export declare function getDefaultCliFeatureMatrix(): CliFeatureMatrix;
+/**
+ * `true` when `backendName` is a built-in CLI backend covered by the matrix.
+ * The matrix only applies to CLI backends; API/local backends translate
+ * features via different paths.
+ */
+export declare function isCliBackendCoveredByMatrix(backendName: string): boolean;
+//# sourceMappingURL=cli-feature-matrix.d.ts.map

package/dist/adapters/agents/backends/cli-feature-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-feature-matrix.d.ts","sourceRoot":"","sources":["../../../../src/adapters/agents/backends/cli-feature-matrix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACd,MAAM,2CAA2C,CAAC;AAMnD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAC3D,wEAAwE;IACxE,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE,CAAC;CAC3D;AAED,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAC3C,gBAAgB,CAuBlB;AA8BD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,iBAAiB,GACzB,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC,CAYnE;AAED,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,EAAE,SAAS,oBAAoB,EAKnE,CAAC;AAIF;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,gBAAgB,CAK7D;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAExE"}

package/dist/adapters/agents/backends/cli-feature-matrix.js

@@ -0,0 +1,83 @@
+import { CLAUDE_DESCRIPTOR } from "./claude-code-cli.js";
+import { CODEX_DESCRIPTOR } from "./codex-cli.js";
+import { CURSOR_DESCRIPTOR } from "./cursor-cli.js";
+import { GEMINI_CLI_DESCRIPTOR } from "./gemini-cli.js";
+function buildCliFeatureMatrix(descriptors) {
+  const featureSet = /* @__PURE__ */ new Set();
+  for (const d of descriptors) {
+    for (const k of Object.keys(d.features)) {
+      featureSet.add(k);
+    }
+  }
+  const features = [...featureSet];
+  const byName = new Map(descriptors.map((d) => [d.name, d]));
+  return {
+    backends: descriptors.map((d) => d.name),
+    features,
+    supports(backend, feature) {
+      const desc = byName.get(backend);
+      return Boolean(desc && feature in desc.features);
+    },
+    unsupportedFor(backend) {
+      const desc = byName.get(backend);
+      if (!desc) return features;
+      return features.filter((f) => !(f in desc.features));
+    }
+  };
+}
+const REQUEST_FIELD_TO_FEATURE = {
+  readOnly: "permission",
+  appendSystemPrompt: "appendSystemPrompt",
+  excludeDynamicSystemPromptSections: "excludeDynamicSystemPromptSections",
+  systemPromptParts: "structuredSystemPrompt",
+  cache: "promptCache",
+  cacheControl: "promptCache",
+  effort: "effort",
+  worktree: "worktree",
+  allowedTools: "allowedTools",
+  disallowedTools: "disallowedTools",
+  mcpConfigPath: "mcp",
+  strictMcpConfig: "strictMcp",
+  outputSchema: "outputSchema",
+  maxBudgetUsd: "maxBudgetUsd",
+  bare: "bare",
+  ephemeral: "ephemeral",
+  skipGitRepoCheck: "skipGitRepoCheck",
+  policyFiles: "policy"
+};
+function findUnsupportedRequestFields(matrix, backend, request) {
+  const out = [];
+  for (const [field, feature] of Object.entries(
+    REQUEST_FIELD_TO_FEATURE
+  )) {
+    const value = request[field];
+    if (value === void 0 || value === null || value === false) continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    if (!matrix.supports(backend, feature)) out.push({ field, feature });
+  }
+  return out;
+}
+const BUILT_IN_CLI_DESCRIPTORS = [
+  CLAUDE_DESCRIPTOR,
+  CODEX_DESCRIPTOR,
+  CURSOR_DESCRIPTOR,
+  GEMINI_CLI_DESCRIPTOR
+];
+let _defaultMatrix;
+function getDefaultCliFeatureMatrix() {
+  if (!_defaultMatrix) {
+    _defaultMatrix = buildCliFeatureMatrix(BUILT_IN_CLI_DESCRIPTORS);
+  }
+  return _defaultMatrix;
+}
+function isCliBackendCoveredByMatrix(backendName) {
+  return BUILT_IN_CLI_DESCRIPTORS.some((d) => d.name === backendName);
+}
+export {
+  BUILT_IN_CLI_DESCRIPTORS,
+  buildCliFeatureMatrix,
+  findUnsupportedRequestFields,
+  getDefaultCliFeatureMatrix,
+  isCliBackendCoveredByMatrix
+};
+//# sourceMappingURL=cli-feature-matrix.js.map

package/dist/adapters/agents/backends/cli-feature-matrix.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/adapters/agents/backends/cli-feature-matrix.ts"],
+  "sourcesContent": ["import type { BackendRunRequest } from '../../../domain/contracts/backends.js';\nimport type {\n  CliBackendDescriptor,\n  CliFeatureKey,\n} from '../../../domain/contracts/cli-backends.js';\nimport { CLAUDE_DESCRIPTOR } from './claude-code-cli.js';\nimport { CODEX_DESCRIPTOR } from './codex-cli.js';\nimport { CURSOR_DESCRIPTOR } from './cursor-cli.js';\nimport { GEMINI_CLI_DESCRIPTOR } from './gemini-cli.js';\n\n/**\n * Snapshot of which backends declare a handler for which feature. Feeds the\n * `octoflow inspect` view, the `UNSUPPORTED_FEATURE_FOR_BACKEND` warning, and\n * the contract test that gates GAP-5 (capabilities \u2194 handler agreement).\n */\nexport interface CliFeatureMatrix {\n  backends: readonly string[];\n  features: readonly CliFeatureKey[];\n  /** `true` when the descriptor for `backend` registers a handler under `feature`. */\n  supports(backend: string, feature: CliFeatureKey): boolean;\n  /** Features this descriptor does not honor (silently dropped today). */\n  unsupportedFor(backend: string): readonly CliFeatureKey[];\n}\n\nexport function buildCliFeatureMatrix(\n  descriptors: readonly CliBackendDescriptor[]\n): CliFeatureMatrix {\n  const featureSet = new Set<CliFeatureKey>();\n  for (const d of descriptors) {\n    for (const k of Object.keys(d.features) as CliFeatureKey[]) {\n      featureSet.add(k);\n    }\n  }\n  const features = [...featureSet];\n  const byName = new Map(descriptors.map((d) => [d.name, d]));\n\n  return {\n    backends: descriptors.map((d) => d.name),\n    features,\n    supports(backend, feature) {\n      const desc = byName.get(backend);\n      return Boolean(desc && feature in desc.features);\n    },\n    unsupportedFor(backend) {\n      const desc = byName.get(backend);\n      if (!desc) return features;\n      return features.filter((f) => !(f in desc.features));\n    },\n  };\n}\n\n/**\n * Maps each `BackendRunRequest` field to the feature key whose handler is\n * responsible for honoring it. Used to emit a single warning per request\n * field that a chosen backend does not support, instead of silent drops.\n */\nconst REQUEST_FIELD_TO_FEATURE: Partial<\n  Record<keyof BackendRunRequest, CliFeatureKey>\n> = {\n  readOnly: 'permission',\n  appendSystemPrompt: 'appendSystemPrompt',\n  excludeDynamicSystemPromptSections: 'excludeDynamicSystemPromptSections',\n  systemPromptParts: 'structuredSystemPrompt',\n  cache: 'promptCache',\n  cacheControl: 'promptCache',\n  effort: 'effort',\n  worktree: 'worktree',\n  allowedTools: 'allowedTools',\n  disallowedTools: 'disallowedTools',\n  mcpConfigPath: 'mcp',\n  strictMcpConfig: 'strictMcp',\n  outputSchema: 'outputSchema',\n  maxBudgetUsd: 'maxBudgetUsd',\n  bare: 'bare',\n  ephemeral: 'ephemeral',\n  skipGitRepoCheck: 'skipGitRepoCheck',\n  policyFiles: 'policy',\n};\n\n/**\n * Returns request-field/feature pairs that the chosen backend will silently\n * drop given the current request. Callers can map each pair into a\n * `bridge:warn` (`UNSUPPORTED_FEATURE_FOR_BACKEND`) emission.\n */\nexport function findUnsupportedRequestFields(\n  matrix: CliFeatureMatrix,\n  backend: string,\n  request: BackendRunRequest\n): Array<{ field: keyof BackendRunRequest; feature: CliFeatureKey }> {\n  const out: Array<{ field: keyof BackendRunRequest; feature: CliFeatureKey }> =\n    [];\n  for (const [field, feature] of Object.entries(\n    REQUEST_FIELD_TO_FEATURE\n  ) as Array<[keyof BackendRunRequest, CliFeatureKey]>) {\n    const value = request[field];\n    if (value === undefined || value === null || value === false) continue;\n    if (Array.isArray(value) && value.length === 0) continue;\n    if (!matrix.supports(backend, feature)) out.push({ field, feature });\n  }\n  return out;\n}\n\n/** Built-in CLI descriptors. Used by the runtime warning + inspect command. */\nexport const BUILT_IN_CLI_DESCRIPTORS: readonly CliBackendDescriptor[] = [\n  CLAUDE_DESCRIPTOR,\n  CODEX_DESCRIPTOR,\n  CURSOR_DESCRIPTOR,\n  GEMINI_CLI_DESCRIPTOR,\n];\n\nlet _defaultMatrix: CliFeatureMatrix | undefined;\n\n/**\n * Lazily-built matrix over the built-in CLI descriptors. Cached for the\n * process lifetime \u2014 descriptors are immutable singletons.\n */\nexport function getDefaultCliFeatureMatrix(): CliFeatureMatrix {\n  if (!_defaultMatrix) {\n    _defaultMatrix = buildCliFeatureMatrix(BUILT_IN_CLI_DESCRIPTORS);\n  }\n  return _defaultMatrix;\n}\n\n/**\n * `true` when `backendName` is a built-in CLI backend covered by the matrix.\n * The matrix only applies to CLI backends; API/local backends translate\n * features via different paths.\n */\nexport function isCliBackendCoveredByMatrix(backendName: string): boolean {\n  return BUILT_IN_CLI_DESCRIPTORS.some((d) => d.name === backendName);\n}\n"],
+  "mappings": "AAKA,SAAS,yBAAyB;AAClC,SAAS,wBAAwB;AACjC,SAAS,yBAAyB;AAClC,SAAS,6BAA6B;AAgB/B,SAAS,sBACd,aACkB;AAClB,QAAM,aAAa,oBAAI,IAAmB;AAC1C,aAAW,KAAK,aAAa;AAC3B,eAAW,KAAK,OAAO,KAAK,EAAE,QAAQ,GAAsB;AAC1D,iBAAW,IAAI,CAAC;AAAA,IAClB;AAAA,EACF;AACA,QAAM,WAAW,CAAC,GAAG,UAAU;AAC/B,QAAM,SAAS,IAAI,IAAI,YAAY,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAE1D,SAAO;AAAA,IACL,UAAU,YAAY,IAAI,CAAC,MAAM,EAAE,IAAI;AAAA,IACvC;AAAA,IACA,SAAS,SAAS,SAAS;AACzB,YAAM,OAAO,OAAO,IAAI,OAAO;AAC/B,aAAO,QAAQ,QAAQ,WAAW,KAAK,QAAQ;AAAA,IACjD;AAAA,IACA,eAAe,SAAS;AACtB,YAAM,OAAO,OAAO,IAAI,OAAO;AAC/B,UAAI,CAAC,KAAM,QAAO;AAClB,aAAO,SAAS,OAAO,CAAC,MAAM,EAAE,KAAK,KAAK,SAAS;AAAA,IACrD;AAAA,EACF;AACF;AAOA,MAAM,2BAEF;AAAA,EACF,UAAU;AAAA,EACV,oBAAoB;AAAA,EACpB,oCAAoC;AAAA,EACpC,mBAAmB;AAAA,EACnB,OAAO;AAAA,EACP,cAAc;AAAA,EACd,QAAQ;AAAA,EACR,UAAU;AAAA,EACV,cAAc;AAAA,EACd,iBAAiB;AAAA,EACjB,eAAe;AAAA,EACf,iBAAiB;AAAA,EACjB,cAAc;AAAA,EACd,cAAc;AAAA,EACd,MAAM;AAAA,EACN,WAAW;AAAA,EACX,kBAAkB;AAAA,EAClB,aAAa;AACf;AAOO,SAAS,6BACd,QACA,SACA,SACmE;AACnE,QAAM,MACJ,CAAC;AACH,aAAW,CAAC,OAAO,OAAO,KAAK,OAAO;AAAA,IACpC;AAAA,EACF,GAAsD;AACpD,UAAM,QAAQ,QAAQ,KAAK;AAC3B,QAAI,UAAU,UAAa,UAAU,QAAQ,UAAU,MAAO;AAC9D,QAAI,MAAM,QAAQ,KAAK,KAAK,MAAM,WAAW,EAAG;AAChD,QAAI,CAAC,OAAO,SAAS,SAAS,OAAO,EAAG,KAAI,KAAK,EAAE,OAAO,QAAQ,CAAC;AAAA,EACrE;AACA,SAAO;AACT;AAGO,MAAM,2BAA4D;AAAA,EACvE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,IAAI;AAMG,SAAS,6BAA+C;AAC7D,MAAI,CAAC,gBAAgB;AACnB,qBAAiB,sBAAsB,wBAAwB;AAAA,EACjE;AACA,SAAO;AACT;AAOO,SAAS,4BAA4B,aAA8B;AACxE,SAAO,yBAAyB,KAAK,CAAC,MAAM,EAAE,SAAS,WAAW;AACpE;",
+  "names": []
+}

package/dist/adapters/agents/backends/cli-helpers.d.ts

@@ -0,0 +1,12 @@
+export declare function isCliInstalled(cli: string): boolean;
+export declare function isCliInstalledAsync(cli: string): Promise<boolean>;
+export declare function getCliVersion(versionCmd: string): string | null;
+export declare function clearCliCache(): void;
+export type CliConfigKey = 'codex-cli' | 'claude-code-cli' | 'cursor-cli' | 'gemini-cli';
+/**
+ * Read the user-configured default model for a CLI backend from its config
+ * file. Returns `null` when the config file does not exist or contains no
+ * model key — indicating the caller should let the CLI choose.
+ */
+export declare function readCliConfigModel(cli: CliConfigKey): string | null;
+//# sourceMappingURL=cli-helpers.d.ts.map

package/dist/adapters/agents/backends/cli-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-helpers.d.ts","sourceRoot":"","sources":["../../../../src/adapters/agents/backends/cli-helpers.ts"],"names":[],"mappings":"AAkBA,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAcnD;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcvE;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM/D;AAED,wBAAgB,aAAa,IAAI,IAAI,CAGpC;AAoBD,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,iBAAiB,GACjB,YAAY,GACZ,YAAY,CAAC;AAejB;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAqCnE"}

package/dist/adapters/agents/backends/cli-helpers.js

@@ -0,0 +1,102 @@
+import { execFile, execSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const BACKEND_EXEC_OPTS = { encoding: "utf8", timeout: 1e4 };
+const BACKEND_VERSION_EXEC_OPTS = { encoding: "utf8", timeout: 1500 };
+const CLI_CACHE_TTL_MS = 6e4;
+const installedCache = /* @__PURE__ */ new Map();
+const IS_WINDOWS = process.platform === "win32";
+const WHICH_CMD = IS_WINDOWS ? "where" : "which";
+function isCliInstalled(cli) {
+  const cached = installedCache.get(cli);
+  if (cached !== void 0 && Date.now() - cached.ts < CLI_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  try {
+    execSync(`${WHICH_CMD} ${cli}`, BACKEND_EXEC_OPTS);
+    installedCache.set(cli, { value: true, ts: Date.now() });
+    return true;
+  } catch {
+    installedCache.set(cli, { value: false, ts: Date.now() });
+    return false;
+  }
+}
+async function isCliInstalledAsync(cli) {
+  const cached = installedCache.get(cli);
+  if (cached !== void 0 && Date.now() - cached.ts < CLI_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  try {
+    await execFileAsync(WHICH_CMD, [cli], { encoding: "utf8", timeout: 1e4 });
+    installedCache.set(cli, { value: true, ts: Date.now() });
+    return true;
+  } catch {
+    installedCache.set(cli, { value: false, ts: Date.now() });
+    return false;
+  }
+}
+function getCliVersion(versionCmd) {
+  try {
+    return execSync(versionCmd, BACKEND_VERSION_EXEC_OPTS).trim();
+  } catch {
+    return null;
+  }
+}
+function clearCliCache() {
+  installedCache.clear();
+  configModelCache.clear();
+}
+const CONFIG_MODEL_TTL_MS = 5 * 6e4;
+const configModelCache = /* @__PURE__ */ new Map();
+const CLI_CONFIG_PATHS = {
+  "codex-cli": [
+    path.join(os.homedir(), ".codex", "config.toml"),
+    path.join(os.homedir(), ".config", "codex", "config.toml")
+  ],
+  "claude-code-cli": [path.join(os.homedir(), ".claude", "settings.json")],
+  "cursor-cli": [
+    path.join(os.homedir(), ".cursor", "settings.json"),
+    path.join(os.homedir(), ".cursor", "config.json")
+  ],
+  "gemini-cli": [path.join(os.homedir(), ".gemini", "settings.json")]
+};
+function readCliConfigModel(cli) {
+  const cached = configModelCache.get(cli);
+  if (cached !== void 0 && Date.now() - cached.ts < CONFIG_MODEL_TTL_MS) {
+    return cached.value;
+  }
+  const set = (v) => {
+    configModelCache.set(cli, { value: v, ts: Date.now() });
+    return v;
+  };
+  for (const filePath of CLI_CONFIG_PATHS[cli]) {
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, "utf8");
+    } catch {
+      continue;
+    }
+    const tomlMatch = raw.match(/^\s*model\s*=\s*"([^"]+)"/m);
+    if (tomlMatch?.[1]) return set(tomlMatch[1]);
+    try {
+      const json = JSON.parse(raw);
+      if (typeof json.model === "string" && json.model.length > 0) {
+        return set(json.model);
+      }
+    } catch {
+    }
+  }
+  return set(null);
+}
+export {
+  clearCliCache,
+  getCliVersion,
+  isCliInstalled,
+  isCliInstalledAsync,
+  readCliConfigModel
+};
+//# sourceMappingURL=cli-helpers.js.map

package/dist/adapters/agents/backends/cli-helpers.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/adapters/agents/backends/cli-helpers.ts"],
+  "sourcesContent": ["import { execFile, execSync } from 'node:child_process';\nimport fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\nimport process from 'node:process';\nimport { promisify } from 'node:util';\n\nconst execFileAsync = promisify(execFile);\n\nconst BACKEND_EXEC_OPTS = { encoding: 'utf8' as const, timeout: 10000 };\nconst BACKEND_VERSION_EXEC_OPTS = { encoding: 'utf8' as const, timeout: 1500 };\n\nconst CLI_CACHE_TTL_MS = 60_000;\nconst installedCache = new Map<string, { value: boolean; ts: number }>();\n\nconst IS_WINDOWS = process.platform === 'win32';\nconst WHICH_CMD = IS_WINDOWS ? 'where' : 'which';\n\nexport function isCliInstalled(cli: string): boolean {\n  const cached = installedCache.get(cli);\n  if (cached !== undefined && Date.now() - cached.ts < CLI_CACHE_TTL_MS) {\n    return cached.value;\n  }\n\n  try {\n    execSync(`${WHICH_CMD} ${cli}`, BACKEND_EXEC_OPTS);\n    installedCache.set(cli, { value: true, ts: Date.now() });\n    return true;\n  } catch {\n    installedCache.set(cli, { value: false, ts: Date.now() });\n    return false;\n  }\n}\n\nexport async function isCliInstalledAsync(cli: string): Promise<boolean> {\n  const cached = installedCache.get(cli);\n  if (cached !== undefined && Date.now() - cached.ts < CLI_CACHE_TTL_MS) {\n    return cached.value;\n  }\n\n  try {\n    await execFileAsync(WHICH_CMD, [cli], { encoding: 'utf8', timeout: 10000 });\n    installedCache.set(cli, { value: true, ts: Date.now() });\n    return true;\n  } catch {\n    installedCache.set(cli, { value: false, ts: Date.now() });\n    return false;\n  }\n}\n\nexport function getCliVersion(versionCmd: string): string | null {\n  try {\n    return execSync(versionCmd, BACKEND_VERSION_EXEC_OPTS).trim();\n  } catch {\n    return null;\n  }\n}\n\nexport function clearCliCache(): void {\n  installedCache.clear();\n  configModelCache.clear();\n}\n\n// Reads each CLI's user-level config file to discover the account-configured\n// default model. Cached for 5 minutes so rapid calls (multiple createAgent\n// calls in one process) don't re-stat the disk.\n//\n// Supported config locations:\n//   codex-cli  : ~/.codex/config.toml  | ~/.config/codex/config.toml  (TOML: model = \"...\")\n//   claude-code: ~/.claude/settings.json                               (JSON: { \"model\": \"...\" })\n//   cursor-cli : ~/.cursor/settings.json | ~/.cursor/config.json       (JSON: { \"model\": \"...\" })\n//\n// Returns null when the CLI is not installed, config not found, or no model\n// key is present \u2014 signalling \"let the CLI use its own account default\".\n\nconst CONFIG_MODEL_TTL_MS = 5 * 60_000;\nconst configModelCache = new Map<\n  string,\n  { value: string | null; ts: number }\n>();\n\nexport type CliConfigKey =\n  | 'codex-cli'\n  | 'claude-code-cli'\n  | 'cursor-cli'\n  | 'gemini-cli';\n\nconst CLI_CONFIG_PATHS: Record<CliConfigKey, string[]> = {\n  'codex-cli': [\n    path.join(os.homedir(), '.codex', 'config.toml'),\n    path.join(os.homedir(), '.config', 'codex', 'config.toml'),\n  ],\n  'claude-code-cli': [path.join(os.homedir(), '.claude', 'settings.json')],\n  'cursor-cli': [\n    path.join(os.homedir(), '.cursor', 'settings.json'),\n    path.join(os.homedir(), '.cursor', 'config.json'),\n  ],\n  'gemini-cli': [path.join(os.homedir(), '.gemini', 'settings.json')],\n};\n\n/**\n * Read the user-configured default model for a CLI backend from its config\n * file. Returns `null` when the config file does not exist or contains no\n * model key \u2014 indicating the caller should let the CLI choose.\n */\nexport function readCliConfigModel(cli: CliConfigKey): string | null {\n  const cached = configModelCache.get(cli);\n  if (cached !== undefined && Date.now() - cached.ts < CONFIG_MODEL_TTL_MS) {\n    return cached.value;\n  }\n\n  const set = (v: string | null): string | null => {\n    configModelCache.set(cli, { value: v, ts: Date.now() });\n    return v;\n  };\n\n  for (const filePath of CLI_CONFIG_PATHS[cli]) {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(filePath, 'utf8');\n    } catch {\n      continue;\n    }\n\n    // TOML: model = \"value\" (codex config.toml)\n    const tomlMatch = raw.match(/^\\s*model\\s*=\\s*\"([^\"]+)\"/m);\n    if (tomlMatch?.[1]) return set(tomlMatch[1]);\n\n    // JSON: { \"model\": \"value\" }\n    try {\n      // JSON.parse returns `any`; cast to a known index shape so we can safely\n      // narrow `json.model` with a typeof guard immediately after.\n      const json = JSON.parse(raw) as Record<string, unknown>;\n      if (typeof json.model === 'string' && json.model.length > 0) {\n        return set(json.model);\n      }\n    } catch {\n      /* not JSON */\n    }\n  }\n\n  return set(null);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/adapters/agents/backends/cli-runner.d.ts

@@ -0,0 +1,9 @@
+import type { BackendExecutionPlan, BackendRunRequest } from '../../../domain/contracts/backends.js';
+import type { CliBackendDescriptor } from '../../../domain/contracts/cli-backends.js';
+/**
+ * Generic CLI execution-plan builder. Walks the descriptor's feature handlers
+ * in `CLI_FEATURE_ORDER`, accumulates flag emissions, and assembles the final
+ * plan. Per-backend quirks live in handlers — this function stays neutral.
+ */
+export declare function buildCliExecutionPlan(command: string, descriptor: CliBackendDescriptor, request: BackendRunRequest): BackendExecutionPlan;
+//# sourceMappingURL=cli-runner.d.ts.map

package/dist/adapters/agents/backends/cli-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-runner.d.ts","sourceRoot":"","sources":["../../../../src/adapters/agents/backends/cli-runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,2CAA2C,CAAC;AAuBnD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,iBAAiB,GACzB,oBAAoB,CAyEtB"}

package/dist/adapters/agents/backends/cli-runner.js

@@ -0,0 +1,76 @@
+import crypto from "node:crypto";
+import { CLI_FEATURE_ORDER } from "../../../domain/contracts/cli-backends.js";
+import { buildPromptEnvelope } from "../../../prompts/envelope.js";
+import { sanitizePath } from "../../../utils/sanitize.js";
+function resolveCliWorkspace(request) {
+  const requested = request.runtimePolicy?.workspace ?? request.cwd ?? null;
+  if (!requested) return void 0;
+  return sanitizePath(requested) || void 0;
+}
+function resolveSessionId(request) {
+  if (request.sessionId) return request.sessionId;
+  return crypto.randomUUID();
+}
+function buildCliExecutionPlan(command, descriptor, request) {
+  const workspace = resolveCliWorkspace(request);
+  const cwd = request.cwd ? sanitizePath(request.cwd) || void 0 : void 0;
+  const sessionId = resolveSessionId(request);
+  const ctx = {
+    request,
+    policy: request.runtimePolicy,
+    workspace,
+    sessionId,
+    cwd
+  };
+  const globalArgs = [];
+  const args = [];
+  const cleanups = [];
+  let resolvedCwd = workspace ?? cwd;
+  let stdin;
+  for (const key of CLI_FEATURE_ORDER) {
+    const handler = descriptor.features[key];
+    if (!handler) continue;
+    const emission = handler(ctx);
+    if (!emission) continue;
+    if (emission.globalArgs?.length) globalArgs.push(...emission.globalArgs);
+    if (emission.args?.length) args.push(...emission.args);
+    if (emission.cwdOverride !== void 0) resolvedCwd = emission.cwdOverride;
+    if (emission.stdinOverride !== void 0) stdin = emission.stdinOverride;
+    if (emission.cleanup) cleanups.push(emission.cleanup);
+  }
+  const finalArgs = [
+    ...descriptor.prelude ?? [],
+    ...globalArgs,
+    ...descriptor.subcommand ? [descriptor.subcommand] : [],
+    ...args,
+    ...descriptor.tail ?? []
+  ];
+  if (stdin === void 0) {
+    stdin = descriptor.defaultStdinIsEnvelope ? buildPromptEnvelope({
+      systemPrompt: request.systemPrompt,
+      userMessage: request.prompt
+    }) : request.prompt;
+  }
+  const cleanup = cleanups.length > 0 ? async () => {
+    for (const fn of cleanups) await fn();
+  } : void 0;
+  let planSessionId;
+  if (descriptor.planSessionIdStrategy === "preserve-on-resume") {
+    planSessionId = request.isResume ? request.sessionId ?? void 0 : sessionId;
+  }
+  return {
+    command,
+    args: finalArgs,
+    env: request.env ?? {},
+    stdin,
+    cwd: resolvedCwd,
+    parser: descriptor.streamParserName,
+    timeoutMs: request.timeoutMs,
+    ...planSessionId !== void 0 ? { sessionId: planSessionId } : {},
+    ...cleanup ? { cleanup } : {}
+  };
+}
+export {
+  buildCliExecutionPlan
+};
+//# sourceMappingURL=cli-runner.js.map

package/dist/adapters/agents/backends/cli-runner.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/adapters/agents/backends/cli-runner.ts"],
+  "sourcesContent": ["import crypto from 'node:crypto';\n\nimport type {\n  BackendExecutionPlan,\n  BackendRunRequest,\n} from '../../../domain/contracts/backends.js';\nimport type {\n  CliBackendDescriptor,\n  CliFeatureContext,\n} from '../../../domain/contracts/cli-backends.js';\nimport { CLI_FEATURE_ORDER } from '../../../domain/contracts/cli-backends.js';\nimport { buildPromptEnvelope } from '../../../prompts/envelope.js';\nimport { sanitizePath } from '../../../utils/sanitize.js';\n\n/**\n * Resolves the effective workspace path applied to a CLI request.\n * Mirrors the historical `policy.workspace ?? request.cwd ?? null` precedence\n * shared by Cursor and Codex.\n */\nfunction resolveCliWorkspace(\n  request: BackendRunRequest\n): string | undefined {\n  const requested = request.runtimePolicy?.workspace ?? request.cwd ?? null;\n  if (!requested) return undefined;\n  return sanitizePath(requested) || undefined;\n}\n\nfunction resolveSessionId(request: BackendRunRequest): string {\n  if (request.sessionId) return request.sessionId;\n  return crypto.randomUUID();\n}\n\n/**\n * Generic CLI execution-plan builder. Walks the descriptor's feature handlers\n * in `CLI_FEATURE_ORDER`, accumulates flag emissions, and assembles the final\n * plan. Per-backend quirks live in handlers \u2014 this function stays neutral.\n */\nexport function buildCliExecutionPlan(\n  command: string,\n  descriptor: CliBackendDescriptor,\n  request: BackendRunRequest\n): BackendExecutionPlan {\n  const workspace = resolveCliWorkspace(request);\n  const cwd = request.cwd ? sanitizePath(request.cwd) || undefined : undefined;\n  const sessionId = resolveSessionId(request);\n\n  const ctx: CliFeatureContext = {\n    request,\n    policy: request.runtimePolicy,\n    workspace,\n    sessionId,\n    cwd,\n  };\n\n  const globalArgs: string[] = [];\n  const args: string[] = [];\n  const cleanups: Array<() => Promise<void>> = [];\n  let resolvedCwd: string | undefined = workspace ?? cwd;\n  let stdin: string | undefined;\n\n  for (const key of CLI_FEATURE_ORDER) {\n    const handler = descriptor.features[key];\n    if (!handler) continue;\n    const emission = handler(ctx);\n    if (!emission) continue;\n    if (emission.globalArgs?.length) globalArgs.push(...emission.globalArgs);\n    if (emission.args?.length) args.push(...emission.args);\n    if (emission.cwdOverride !== undefined) resolvedCwd = emission.cwdOverride;\n    if (emission.stdinOverride !== undefined) stdin = emission.stdinOverride;\n    if (emission.cleanup) cleanups.push(emission.cleanup);\n  }\n\n  const finalArgs: string[] = [\n    ...(descriptor.prelude ?? []),\n    ...globalArgs,\n    ...(descriptor.subcommand ? [descriptor.subcommand] : []),\n    ...args,\n    ...(descriptor.tail ?? []),\n  ];\n\n  if (stdin === undefined) {\n    stdin = descriptor.defaultStdinIsEnvelope\n      ? buildPromptEnvelope({\n          systemPrompt: request.systemPrompt,\n          userMessage: request.prompt,\n        })\n      : request.prompt;\n  }\n\n  const cleanup =\n    cleanups.length > 0\n      ? async () => {\n          for (const fn of cleanups) await fn();\n        }\n      : undefined;\n\n  let planSessionId: string | undefined;\n  if (descriptor.planSessionIdStrategy === 'preserve-on-resume') {\n    planSessionId = request.isResume\n      ? (request.sessionId ?? undefined)\n      : sessionId;\n  }\n\n  return {\n    command,\n    args: finalArgs,\n    env: request.env ?? {},\n    stdin,\n    cwd: resolvedCwd,\n    parser: descriptor.streamParserName,\n    timeoutMs: request.timeoutMs,\n    ...(planSessionId !== undefined ? { sessionId: planSessionId } : {}),\n    ...(cleanup ? { cleanup } : {}),\n  };\n}\n"],
+  "mappings": "AAAA,OAAO,YAAY;AAUnB,SAAS,yBAAyB;AAClC,SAAS,2BAA2B;AACpC,SAAS,oBAAoB;AAO7B,SAAS,oBACP,SACoB;AACpB,QAAM,YAAY,QAAQ,eAAe,aAAa,QAAQ,OAAO;AACrE,MAAI,CAAC,UAAW,QAAO;AACvB,SAAO,aAAa,SAAS,KAAK;AACpC;AAEA,SAAS,iBAAiB,SAAoC;AAC5D,MAAI,QAAQ,UAAW,QAAO,QAAQ;AACtC,SAAO,OAAO,WAAW;AAC3B;AAOO,SAAS,sBACd,SACA,YACA,SACsB;AACtB,QAAM,YAAY,oBAAoB,OAAO;AAC7C,QAAM,MAAM,QAAQ,MAAM,aAAa,QAAQ,GAAG,KAAK,SAAY;AACnE,QAAM,YAAY,iBAAiB,OAAO;AAE1C,QAAM,MAAyB;AAAA,IAC7B;AAAA,IACA,QAAQ,QAAQ;AAAA,IAChB;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,QAAM,aAAuB,CAAC;AAC9B,QAAM,OAAiB,CAAC;AACxB,QAAM,WAAuC,CAAC;AAC9C,MAAI,cAAkC,aAAa;AACnD,MAAI;AAEJ,aAAW,OAAO,mBAAmB;AACnC,UAAM,UAAU,WAAW,SAAS,GAAG;AACvC,QAAI,CAAC,QAAS;AACd,UAAM,WAAW,QAAQ,GAAG;AAC5B,QAAI,CAAC,SAAU;AACf,QAAI,SAAS,YAAY,OAAQ,YAAW,KAAK,GAAG,SAAS,UAAU;AACvE,QAAI,SAAS,MAAM,OAAQ,MAAK,KAAK,GAAG,SAAS,IAAI;AACrD,QAAI,SAAS,gBAAgB,OAAW,eAAc,SAAS;AAC/D,QAAI,SAAS,kBAAkB,OAAW,SAAQ,SAAS;AAC3D,QAAI,SAAS,QAAS,UAAS,KAAK,SAAS,OAAO;AAAA,EACtD;AAEA,QAAM,YAAsB;AAAA,IAC1B,GAAI,WAAW,WAAW,CAAC;AAAA,IAC3B,GAAG;AAAA,IACH,GAAI,WAAW,aAAa,CAAC,WAAW,UAAU,IAAI,CAAC;AAAA,IACvD,GAAG;AAAA,IACH,GAAI,WAAW,QAAQ,CAAC;AAAA,EAC1B;AAEA,MAAI,UAAU,QAAW;AACvB,YAAQ,WAAW,yBACf,oBAAoB;AAAA,MAClB,cAAc,QAAQ;AAAA,MACtB,aAAa,QAAQ;AAAA,IACvB,CAAC,IACD,QAAQ;AAAA,EACd;AAEA,QAAM,UACJ,SAAS,SAAS,IACd,YAAY;AACV,eAAW,MAAM,SAAU,OAAM,GAAG;AAAA,EACtC,IACA;AAEN,MAAI;AACJ,MAAI,WAAW,0BAA0B,sBAAsB;AAC7D,oBAAgB,QAAQ,WACnB,QAAQ,aAAa,SACtB;AAAA,EACN;AAEA,SAAO;AAAA,IACL;AAAA,IACA,MAAM;AAAA,IACN,KAAK,QAAQ,OAAO,CAAC;AAAA,IACrB;AAAA,IACA,KAAK;AAAA,IACL,QAAQ,WAAW;AAAA,IACnB,WAAW,QAAQ;AAAA,IACnB,GAAI,kBAAkB,SAAY,EAAE,WAAW,cAAc,IAAI,CAAC;AAAA,IAClE,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,EAC/B;AACF;",
+  "names": []
+}

package/dist/adapters/agents/backends/codex-cli.d.ts

@@ -0,0 +1,5 @@
+import type { Backend } from '../../../domain/contracts/backends.js';
+import type { CliBackendDescriptor } from '../../../domain/contracts/cli-backends.js';
+export declare const CODEX_DESCRIPTOR: CliBackendDescriptor;
+export declare function createCodexBackend(): Backend;
+//# sourceMappingURL=codex-cli.d.ts.map

package/dist/adapters/agents/backends/codex-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-cli.d.ts","sourceRoot":"","sources":["../../../../src/adapters/agents/backends/codex-cli.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,OAAO,EAER,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,2CAA2C,CAAC;AAwMnD,eAAO,MAAM,gBAAgB,EAAE,oBAuB9B,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,OAAO,CA0B5C"}