octoflow-core 1.0.0

package/dist/config/env-registry.js

@@ -0,0 +1,163 @@
+const ENV_REGISTRY = {
+  OPENAI_API_KEY: {
+    key: "OPENAI_API_KEY",
+    backends: ["openai-api", "codex-cli", "vercel-ai:openai"],
+    category: "api-key",
+    required: false,
+    description: "OpenAI API key"
+  },
+  OPENAI_API_HOST_KEY: {
+    key: "OPENAI_API_HOST_KEY",
+    backends: ["openai-api"],
+    category: "api-key",
+    required: false,
+    description: "OpenAI-compatible API key alias normalized by OctoFlow config"
+  },
+  ANTHROPIC_API_KEY: {
+    key: "ANTHROPIC_API_KEY",
+    backends: ["anthropic-api", "claude-code-cli", "vercel-ai:anthropic"],
+    category: "api-key",
+    required: false,
+    description: "Anthropic API key"
+  },
+  ANTHROPIC_API_HOST_KEY: {
+    key: "ANTHROPIC_API_HOST_KEY",
+    backends: ["anthropic-api"],
+    category: "api-key",
+    required: false,
+    description: "Anthropic-compatible API key alias normalized by OctoFlow config"
+  },
+  GEMINI_API_KEY: {
+    key: "GEMINI_API_KEY",
+    backends: ["vercel-ai:google"],
+    category: "api-key",
+    required: false,
+    description: "Google Gemini API key"
+  },
+  OPENAI_BASE_URL: {
+    key: "OPENAI_BASE_URL",
+    backends: ["openai-api"],
+    category: "host",
+    required: false,
+    description: "OpenAI API base URL"
+  },
+  ANTHROPIC_BASE_URL: {
+    key: "ANTHROPIC_BASE_URL",
+    backends: ["anthropic-api"],
+    category: "host",
+    required: false,
+    description: "Anthropic API base URL"
+  },
+  OPENAI_HOST: {
+    key: "OPENAI_HOST",
+    backends: ["openai-api"],
+    category: "host",
+    required: false,
+    description: "OpenAI-compatible API host alias normalized by OctoFlow config"
+  },
+  ANTHROPIC_HOST: {
+    key: "ANTHROPIC_HOST",
+    backends: ["anthropic-api"],
+    category: "host",
+    required: false,
+    description: "Anthropic-compatible API host alias normalized by OctoFlow config"
+  },
+  OLLAMA_API_KEY: {
+    key: "OLLAMA_API_KEY",
+    backends: ["ollama"],
+    category: "api-key",
+    required: false,
+    description: "Ollama API key (Bearer auth)"
+  },
+  OLLAMA_HOST: {
+    key: "OLLAMA_HOST",
+    backends: ["ollama"],
+    category: "host",
+    required: false,
+    description: "Ollama server host URL"
+  },
+  OLLAMA_MODEL: {
+    key: "OLLAMA_MODEL",
+    backends: ["ollama"],
+    category: "model",
+    required: false,
+    description: "Default Ollama model name"
+  },
+  OCTOFLOW_CONFIG: {
+    key: "OCTOFLOW_CONFIG",
+    backends: [],
+    category: "config",
+    required: false,
+    description: "Path to octoflow config file"
+  },
+  OCTOFLOW_IGNORE_CONFIG: {
+    key: "OCTOFLOW_IGNORE_CONFIG",
+    backends: [],
+    category: "config",
+    required: false,
+    description: "Skip all octoflow config file discovery when truthy"
+  },
+  OCTOFLOW_MAX_CONCURRENT: {
+    key: "OCTOFLOW_MAX_CONCURRENT",
+    backends: [],
+    category: "runtime",
+    required: false,
+    description: "Max concurrent CLI processes"
+  },
+  OCTOFLOW_PROFILE: {
+    key: "OCTOFLOW_PROFILE",
+    backends: [],
+    category: "metadata",
+    required: false,
+    description: "Injected into child env: active profile name"
+  },
+  OCTOFLOW_WORKSPACE: {
+    key: "OCTOFLOW_WORKSPACE",
+    backends: [],
+    category: "metadata",
+    required: false,
+    description: "Injected into child env: resolved workspace path"
+  },
+  OCTOFLOW_EXECUTION_MODE: {
+    key: "OCTOFLOW_EXECUTION_MODE",
+    backends: [],
+    category: "metadata",
+    required: false,
+    description: "Injected into child env: execution mode"
+  },
+  OCTOFLOW_APPROVAL_MODE: {
+    key: "OCTOFLOW_APPROVAL_MODE",
+    backends: [],
+    category: "metadata",
+    required: false,
+    description: "Injected into child env: approval mode"
+  },
+  OCTOFLOW_NETWORK: {
+    key: "OCTOFLOW_NETWORK",
+    backends: [],
+    category: "metadata",
+    required: false,
+    description: "Injected into child env: network policy"
+  }
+};
+function discoverEnv(baseEnv = process.env) {
+  return Object.values(ENV_REGISTRY).map((descriptor) => ({
+    ...descriptor,
+    value: typeof baseEnv[descriptor.key] === "string" ? baseEnv[descriptor.key] : null,
+    source: typeof baseEnv[descriptor.key] === "string" ? "process.env" : "unset"
+  }));
+}
+const PROVIDER_ENV_KEYS = [
+  "OPENAI_API_KEY",
+  "OPENAI_API_HOST_KEY",
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_API_HOST_KEY",
+  "GEMINI_API_KEY",
+  "OLLAMA_API_KEY"
+];
+export {
+  ENV_REGISTRY,
+  PROVIDER_ENV_KEYS,
+  discoverEnv
+};
+//# sourceMappingURL=env-registry.js.map

package/dist/config/env-registry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/config/env-registry.ts"],
+  "sourcesContent": ["import type { BackendName } from '../domain/core-client.js';\n\nexport type EnvVarCategory =\n  | 'api-key'\n  | 'host'\n  | 'model'\n  | 'runtime'\n  | 'config'\n  | 'metadata';\n\nexport interface EnvVarDescriptor {\n  key: string;\n  backends: BackendName[];\n  category: EnvVarCategory;\n  required: boolean;\n  description: string;\n  deprecated?: boolean;\n}\n\nexport interface DiscoveredEnvVar extends EnvVarDescriptor {\n  value: string | null;\n  source: 'process.env' | 'unset';\n}\n\nexport const ENV_REGISTRY: Record<string, EnvVarDescriptor> = {\n  OPENAI_API_KEY: {\n    key: 'OPENAI_API_KEY',\n    backends: ['openai-api', 'codex-cli', 'vercel-ai:openai'],\n    category: 'api-key',\n    required: false,\n    description: 'OpenAI API key',\n  },\n  OPENAI_API_HOST_KEY: {\n    key: 'OPENAI_API_HOST_KEY',\n    backends: ['openai-api'],\n    category: 'api-key',\n    required: false,\n    description:\n      'OpenAI-compatible API key alias normalized by OctoFlow config',\n  },\n  ANTHROPIC_API_KEY: {\n    key: 'ANTHROPIC_API_KEY',\n    backends: ['anthropic-api', 'claude-code-cli', 'vercel-ai:anthropic'],\n    category: 'api-key',\n    required: false,\n    description: 'Anthropic API key',\n  },\n  ANTHROPIC_API_HOST_KEY: {\n    key: 'ANTHROPIC_API_HOST_KEY',\n    backends: ['anthropic-api'],\n    category: 'api-key',\n    required: false,\n    description:\n      'Anthropic-compatible API key alias normalized by OctoFlow config',\n  },\n  GEMINI_API_KEY: {\n    key: 'GEMINI_API_KEY',\n    backends: ['vercel-ai:google'],\n    category: 'api-key',\n    required: false,\n    description: 'Google Gemini API key',\n  },\n  OPENAI_BASE_URL: {\n    key: 'OPENAI_BASE_URL',\n    backends: ['openai-api'],\n    category: 'host',\n    required: false,\n    description: 'OpenAI API base URL',\n  },\n  ANTHROPIC_BASE_URL: {\n    key: 'ANTHROPIC_BASE_URL',\n    backends: ['anthropic-api'],\n    category: 'host',\n    required: false,\n    description: 'Anthropic API base URL',\n  },\n  OPENAI_HOST: {\n    key: 'OPENAI_HOST',\n    backends: ['openai-api'],\n    category: 'host',\n    required: false,\n    description:\n      'OpenAI-compatible API host alias normalized by OctoFlow config',\n  },\n  ANTHROPIC_HOST: {\n    key: 'ANTHROPIC_HOST',\n    backends: ['anthropic-api'],\n    category: 'host',\n    required: false,\n    description:\n      'Anthropic-compatible API host alias normalized by OctoFlow config',\n  },\n  OLLAMA_API_KEY: {\n    key: 'OLLAMA_API_KEY',\n    backends: ['ollama'],\n    category: 'api-key',\n    required: false,\n    description: 'Ollama API key (Bearer auth)',\n  },\n  OLLAMA_HOST: {\n    key: 'OLLAMA_HOST',\n    backends: ['ollama'],\n    category: 'host',\n    required: false,\n    description: 'Ollama server host URL',\n  },\n  OLLAMA_MODEL: {\n    key: 'OLLAMA_MODEL',\n    backends: ['ollama'],\n    category: 'model',\n    required: false,\n    description: 'Default Ollama model name',\n  },\n  OCTOFLOW_CONFIG: {\n    key: 'OCTOFLOW_CONFIG',\n    backends: [],\n    category: 'config',\n    required: false,\n    description: 'Path to octoflow config file',\n  },\n  OCTOFLOW_IGNORE_CONFIG: {\n    key: 'OCTOFLOW_IGNORE_CONFIG',\n    backends: [],\n    category: 'config',\n    required: false,\n    description: 'Skip all octoflow config file discovery when truthy',\n  },\n  OCTOFLOW_MAX_CONCURRENT: {\n    key: 'OCTOFLOW_MAX_CONCURRENT',\n    backends: [],\n    category: 'runtime',\n    required: false,\n    description: 'Max concurrent CLI processes',\n  },\n  OCTOFLOW_PROFILE: {\n    key: 'OCTOFLOW_PROFILE',\n    backends: [],\n    category: 'metadata',\n    required: false,\n    description: 'Injected into child env: active profile name',\n  },\n  OCTOFLOW_WORKSPACE: {\n    key: 'OCTOFLOW_WORKSPACE',\n    backends: [],\n    category: 'metadata',\n    required: false,\n    description: 'Injected into child env: resolved workspace path',\n  },\n  OCTOFLOW_EXECUTION_MODE: {\n    key: 'OCTOFLOW_EXECUTION_MODE',\n    backends: [],\n    category: 'metadata',\n    required: false,\n    description: 'Injected into child env: execution mode',\n  },\n  OCTOFLOW_APPROVAL_MODE: {\n    key: 'OCTOFLOW_APPROVAL_MODE',\n    backends: [],\n    category: 'metadata',\n    required: false,\n    description: 'Injected into child env: approval mode',\n  },\n  OCTOFLOW_NETWORK: {\n    key: 'OCTOFLOW_NETWORK',\n    backends: [],\n    category: 'metadata',\n    required: false,\n    description: 'Injected into child env: network policy',\n  },\n};\n\n/**\n * Discover all recognized env vars and their current values from the host process.\n */\nexport function discoverEnv(\n  baseEnv: NodeJS.ProcessEnv = process.env\n): DiscoveredEnvVar[] {\n  return Object.values(ENV_REGISTRY).map((descriptor) => ({\n    ...descriptor,\n    value: (typeof baseEnv[descriptor.key] === 'string'\n      ? baseEnv[descriptor.key]\n      : null) as string | null,\n    source:\n      typeof baseEnv[descriptor.key] === 'string' ? 'process.env' : 'unset',\n  }));\n}\n\n/**\n * Provider API key env var names that receive special stripping treatment.\n * Keys in this list are removed from inherited process.env unless explicitly\n * provided in the execution plan's env (tiers 1-4).\n */\nexport const PROVIDER_ENV_KEYS = [\n  'OPENAI_API_KEY',\n  'OPENAI_API_HOST_KEY',\n  'ANTHROPIC_API_KEY',\n  'ANTHROPIC_API_HOST_KEY',\n  'GEMINI_API_KEY',\n  'OLLAMA_API_KEY',\n] as const;\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/config/env-resolver.d.ts

@@ -0,0 +1,36 @@
+import type { BackendName } from '../domain/core-client.js';
+import type { ResolvedOctoFlowProfile } from './config.js';
+export interface EnvResolutionContext {
+    /** Tier 1 — per-call env overrides (highest priority). */
+    callEnv?: Record<string, string>;
+    /** Tier 2 — per-client env (constructor-level). */
+    clientEnv?: Record<string, string>;
+    /** Tier 3 — config apiKeys mapped to env var names. */
+    apiKeyEnv?: Record<string, string>;
+    /** Tier 4 — entries loaded from a .env file. */
+    dotEnv?: Record<string, string>;
+    /** Tier 5 — host process.env (filtered by profile allow/deny). */
+    processEnv?: NodeJS.ProcessEnv;
+    /** Resolved profile with allow/deny rules. */
+    profile: ResolvedOctoFlowProfile;
+    /** Which backend this env is being built for. */
+    backend: BackendName;
+    /** Resolved workspace path (injected as OCTOFLOW_WORKSPACE). */
+    workspace: string;
+}
+/**
+ * Build the final child-process env by merging six tiers:
+ *
+ *   1. Per-call env       (callEnv)
+ *   2. Per-client env     (clientEnv)
+ *   3. Config apiKeys     (apiKeyEnv)
+ *   4. .env file          (dotEnv)
+ *   5. process.env        (filtered by profile allow/deny)
+ *   6. Built-in defaults  (OCTOFLOW_* metadata)
+ *
+ * Lower-numbered tiers override higher-numbered ones.
+ * Provider API keys from process.env (tier 5) are stripped unless
+ * explicitly provided at tiers 1-4.
+ */
+export declare function resolveChildEnv(ctx: EnvResolutionContext): Record<string, string>;
+//# sourceMappingURL=env-resolver.d.ts.map

package/dist/config/env-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-resolver.d.ts","sourceRoot":"","sources":["../../src/config/env-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG3D,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC/B,8CAA8C;IAC9C,OAAO,EAAE,uBAAuB,CAAC;IACjC,iDAAiD;IACjD,OAAO,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,oBAAoB,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsDxB"}

package/dist/config/env-resolver.js

@@ -0,0 +1,51 @@
+import { PROVIDER_ENV_KEYS } from "./env-registry.js";
+function matchesPattern(value, pattern) {
+  if (!pattern.includes("*")) return value === pattern;
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`, "i").test(value);
+}
+function resolveChildEnv(ctx) {
+  const { profile } = ctx;
+  const baseEnv = ctx.processEnv ?? process.env;
+  const result = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (typeof value !== "string") continue;
+    const allowed = profile.security.credentials.allowedEnvVars.some(
+      (p) => matchesPattern(key, p)
+    );
+    const denied = profile.security.credentials.denyEnvVars.some(
+      (p) => matchesPattern(key, p)
+    );
+    if (allowed && !denied) {
+      result[key] = value;
+    }
+  }
+  if (ctx.dotEnv) {
+    for (const [key, value] of Object.entries(ctx.dotEnv)) {
+      if (!(key in result)) {
+        result[key] = value;
+      }
+    }
+  }
+  const explicitEnv = {
+    ...ctx.apiKeyEnv ?? {},
+    ...ctx.clientEnv ?? {},
+    ...ctx.callEnv ?? {}
+  };
+  for (const providerKey of PROVIDER_ENV_KEYS) {
+    if (!(providerKey in explicitEnv)) {
+      delete result[providerKey];
+    }
+  }
+  Object.assign(result, explicitEnv);
+  result.OCTOFLOW_PROFILE = profile.name;
+  result.OCTOFLOW_WORKSPACE = ctx.workspace;
+  result.OCTOFLOW_EXECUTION_MODE = profile.runtime.executionMode;
+  result.OCTOFLOW_APPROVAL_MODE = profile.security.approvalMode;
+  result.OCTOFLOW_NETWORK = profile.security.network;
+  return result;
+}
+export {
+  resolveChildEnv
+};
+//# sourceMappingURL=env-resolver.js.map

package/dist/config/env-resolver.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/config/env-resolver.ts"],
+  "sourcesContent": ["import type { BackendName } from '../domain/core-client.js';\nimport type { ResolvedOctoFlowProfile } from './config.js';\nimport { PROVIDER_ENV_KEYS } from './env-registry.js';\n\nexport interface EnvResolutionContext {\n  /** Tier 1 \u2014 per-call env overrides (highest priority). */\n  callEnv?: Record<string, string>;\n  /** Tier 2 \u2014 per-client env (constructor-level). */\n  clientEnv?: Record<string, string>;\n  /** Tier 3 \u2014 config apiKeys mapped to env var names. */\n  apiKeyEnv?: Record<string, string>;\n  /** Tier 4 \u2014 entries loaded from a .env file. */\n  dotEnv?: Record<string, string>;\n  /** Tier 5 \u2014 host process.env (filtered by profile allow/deny). */\n  processEnv?: NodeJS.ProcessEnv;\n  /** Resolved profile with allow/deny rules. */\n  profile: ResolvedOctoFlowProfile;\n  /** Which backend this env is being built for. */\n  backend: BackendName;\n  /** Resolved workspace path (injected as OCTOFLOW_WORKSPACE). */\n  workspace: string;\n}\n\nfunction matchesPattern(value: string, pattern: string): boolean {\n  if (!pattern.includes('*')) return value === pattern;\n  const escaped = pattern\n    .replace(/[.+?^${}()|[\\]\\\\]/g, '\\\\$&')\n    .replace(/\\*/g, '.*');\n  return new RegExp(`^${escaped}$`, 'i').test(value);\n}\n\n/**\n * Build the final child-process env by merging six tiers:\n *\n *   1. Per-call env       (callEnv)\n *   2. Per-client env     (clientEnv)\n *   3. Config apiKeys     (apiKeyEnv)\n *   4. .env file          (dotEnv)\n *   5. process.env        (filtered by profile allow/deny)\n *   6. Built-in defaults  (OCTOFLOW_* metadata)\n *\n * Lower-numbered tiers override higher-numbered ones.\n * Provider API keys from process.env (tier 5) are stripped unless\n * explicitly provided at tiers 1-4.\n */\nexport function resolveChildEnv(\n  ctx: EnvResolutionContext\n): Record<string, string> {\n  const { profile } = ctx;\n  const baseEnv = ctx.processEnv ?? process.env;\n\n  // Tier 5: filter process.env by profile allow/deny\n  const result: Record<string, string> = {};\n  for (const [key, value] of Object.entries(baseEnv)) {\n    if (typeof value !== 'string') continue;\n    const allowed = profile.security.credentials.allowedEnvVars.some((p) =>\n      matchesPattern(key, p)\n    );\n    const denied = profile.security.credentials.denyEnvVars.some((p) =>\n      matchesPattern(key, p)\n    );\n    if (allowed && !denied) {\n      result[key] = value;\n    }\n  }\n\n  // Tier 4: .env file entries (only fills gaps not already set)\n  if (ctx.dotEnv) {\n    for (const [key, value] of Object.entries(ctx.dotEnv)) {\n      if (!(key in result)) {\n        result[key] = value;\n      }\n    }\n  }\n\n  // Collect all explicitly-provided env from tiers 1-3\n  const explicitEnv: Record<string, string> = {\n    ...(ctx.apiKeyEnv ?? {}),\n    ...(ctx.clientEnv ?? {}),\n    ...(ctx.callEnv ?? {}),\n  };\n\n  // Strip provider keys from inherited env unless explicitly provided\n  for (const providerKey of PROVIDER_ENV_KEYS) {\n    if (!(providerKey in explicitEnv)) {\n      delete result[providerKey];\n    }\n  }\n\n  // Tiers 3\u21922\u21921: merge explicit env on top (call-level wins)\n  Object.assign(result, explicitEnv);\n\n  // Tier 6: inject OCTOFLOW_* metadata (always set, lowest conceptual priority\n  // but injected last so they're always present)\n  result.OCTOFLOW_PROFILE = profile.name;\n  result.OCTOFLOW_WORKSPACE = ctx.workspace;\n  result.OCTOFLOW_EXECUTION_MODE = profile.runtime.executionMode;\n  result.OCTOFLOW_APPROVAL_MODE = profile.security.approvalMode;\n  result.OCTOFLOW_NETWORK = profile.security.network;\n\n  return result;\n}\n"],
+  "mappings": "AAEA,SAAS,yBAAyB;AAqBlC,SAAS,eAAe,OAAe,SAA0B;AAC/D,MAAI,CAAC,QAAQ,SAAS,GAAG,EAAG,QAAO,UAAU;AAC7C,QAAM,UAAU,QACb,QAAQ,sBAAsB,MAAM,EACpC,QAAQ,OAAO,IAAI;AACtB,SAAO,IAAI,OAAO,IAAI,OAAO,KAAK,GAAG,EAAE,KAAK,KAAK;AACnD;AAgBO,SAAS,gBACd,KACwB;AACxB,QAAM,EAAE,QAAQ,IAAI;AACpB,QAAM,UAAU,IAAI,cAAc,QAAQ;AAG1C,QAAM,SAAiC,CAAC;AACxC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,OAAO,UAAU,SAAU;AAC/B,UAAM,UAAU,QAAQ,SAAS,YAAY,eAAe;AAAA,MAAK,CAAC,MAChE,eAAe,KAAK,CAAC;AAAA,IACvB;AACA,UAAM,SAAS,QAAQ,SAAS,YAAY,YAAY;AAAA,MAAK,CAAC,MAC5D,eAAe,KAAK,CAAC;AAAA,IACvB;AACA,QAAI,WAAW,CAAC,QAAQ;AACtB,aAAO,GAAG,IAAI;AAAA,IAChB;AAAA,EACF;AAGA,MAAI,IAAI,QAAQ;AACd,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,MAAM,GAAG;AACrD,UAAI,EAAE,OAAO,SAAS;AACpB,eAAO,GAAG,IAAI;AAAA,MAChB;AAAA,IACF;AAAA,EACF;AAGA,QAAM,cAAsC;AAAA,IAC1C,GAAI,IAAI,aAAa,CAAC;AAAA,IACtB,GAAI,IAAI,aAAa,CAAC;AAAA,IACtB,GAAI,IAAI,WAAW,CAAC;AAAA,EACtB;AAGA,aAAW,eAAe,mBAAmB;AAC3C,QAAI,EAAE,eAAe,cAAc;AACjC,aAAO,OAAO,WAAW;AAAA,IAC3B;AAAA,EACF;AAGA,SAAO,OAAO,QAAQ,WAAW;AAIjC,SAAO,mBAAmB,QAAQ;AAClC,SAAO,qBAAqB,IAAI;AAChC,SAAO,0BAA0B,QAAQ,QAAQ;AACjD,SAAO,yBAAyB,QAAQ,SAAS;AACjD,SAAO,mBAAmB,QAAQ,SAAS;AAE3C,SAAO;AACT;",
+  "names": []
+}

package/dist/config/model-budget.d.ts

@@ -0,0 +1,26 @@
+import type { BackendName } from '../domain/core-client.js';
+/**
+ * Resolved token budget for a (backend, model) pair.
+ *
+ * Sourced from the model matrix plus safe defaults so that compaction,
+ * microcompact, and backend clients all see the same numbers instead of each
+ * maintaining its own literal fallback.
+ */
+export interface ModelBudget {
+    /** Max input tokens the model accepts. */
+    contextTokens: number;
+    /** Max output tokens per call. */
+    outputTokens: number;
+    /** Safe compaction trigger (default: `contextTokens * 0.8`). */
+    compactAt: number;
+    /** Safe per-tool-output cap (default: `outputTokens * 0.2`). */
+    maxToolOutputTokens: number;
+}
+/**
+ * Resolve the token budget for a (backend, model) pair.
+ *
+ * The model matrix is the source of truth; overrides win over every derived
+ * default. Never performs a runtime HTTP lookup.
+ */
+export declare function resolveModelBudget(backend: BackendName, model: string | undefined, overrides?: Partial<ModelBudget>): ModelBudget;
+//# sourceMappingURL=model-budget.d.ts.map

package/dist/config/model-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-budget.d.ts","sourceRoot":"","sources":["../../src/config/model-budget.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAkBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC/B,WAAW,CAiBb"}

package/dist/config/model-budget.js

@@ -0,0 +1,31 @@
+import {
+  DEFAULT_MAX_CONTEXT_TOKENS,
+  getDefaultModelForBackend,
+  resolveContextTokens,
+  resolveOutputTokens
+} from "../adapters/agents/backends/model-matrix.js";
+const API_BACKEND_DEFAULT_CONTEXT_WINDOWS = {
+  "anthropic-api": 2e5,
+  "custom-api": DEFAULT_MAX_CONTEXT_TOKENS,
+  ollama: 2e5,
+  "openai-api": 2e5,
+  "vercel-ai:anthropic": 2e5,
+  "vercel-ai:google": 2e5,
+  "vercel-ai:openai": 2e5
+};
+const BACKEND_OUTPUT_FALLBACK = 4096;
+const COMPACT_AT_RATIO = 0.8;
+const MAX_TOOL_OUTPUT_RATIO = 0.2;
+function resolveModelBudget(backend, model, overrides) {
+  const backendContextDefault = API_BACKEND_DEFAULT_CONTEXT_WINDOWS[backend] ?? DEFAULT_MAX_CONTEXT_TOKENS;
+  const resolvedModel = model ?? getDefaultModelForBackend(backend);
+  const contextTokens = overrides?.contextTokens ?? resolveContextTokens(void 0, resolvedModel, backendContextDefault);
+  const outputTokens = overrides?.outputTokens ?? resolveOutputTokens(void 0, resolvedModel, BACKEND_OUTPUT_FALLBACK);
+  const compactAt = overrides?.compactAt ?? Math.floor(contextTokens * COMPACT_AT_RATIO);
+  const maxToolOutputTokens = overrides?.maxToolOutputTokens ?? Math.floor(outputTokens * MAX_TOOL_OUTPUT_RATIO);
+  return { contextTokens, outputTokens, compactAt, maxToolOutputTokens };
+}
+export {
+  resolveModelBudget
+};
+//# sourceMappingURL=model-budget.js.map

package/dist/config/model-budget.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/config/model-budget.ts"],
+  "sourcesContent": ["import {\n  DEFAULT_MAX_CONTEXT_TOKENS,\n  getDefaultModelForBackend,\n  resolveContextTokens,\n  resolveOutputTokens,\n} from '../adapters/agents/backends/model-matrix.js';\nimport type { BackendName } from '../domain/core-client.js';\n\n/**\n * Resolved token budget for a (backend, model) pair.\n *\n * Sourced from the model matrix plus safe defaults so that compaction,\n * microcompact, and backend clients all see the same numbers instead of each\n * maintaining its own literal fallback.\n */\nexport interface ModelBudget {\n  /** Max input tokens the model accepts. */\n  contextTokens: number;\n  /** Max output tokens per call. */\n  outputTokens: number;\n  /** Safe compaction trigger (default: `contextTokens * 0.8`). */\n  compactAt: number;\n  /** Safe per-tool-output cap (default: `outputTokens * 0.2`). */\n  maxToolOutputTokens: number;\n}\n\nconst API_BACKEND_DEFAULT_CONTEXT_WINDOWS: Partial<\n  Record<BackendName, number>\n> = {\n  'anthropic-api': 200_000,\n  'custom-api': DEFAULT_MAX_CONTEXT_TOKENS,\n  ollama: 200_000,\n  'openai-api': 200_000,\n  'vercel-ai:anthropic': 200_000,\n  'vercel-ai:google': 200_000,\n  'vercel-ai:openai': 200_000,\n};\n\nconst BACKEND_OUTPUT_FALLBACK = 4_096;\nconst COMPACT_AT_RATIO = 0.8;\nconst MAX_TOOL_OUTPUT_RATIO = 0.2;\n\n/**\n * Resolve the token budget for a (backend, model) pair.\n *\n * The model matrix is the source of truth; overrides win over every derived\n * default. Never performs a runtime HTTP lookup.\n */\nexport function resolveModelBudget(\n  backend: BackendName,\n  model: string | undefined,\n  overrides?: Partial<ModelBudget>\n): ModelBudget {\n  const backendContextDefault =\n    API_BACKEND_DEFAULT_CONTEXT_WINDOWS[backend] ?? DEFAULT_MAX_CONTEXT_TOKENS;\n  const resolvedModel = model ?? getDefaultModelForBackend(backend);\n  const contextTokens =\n    overrides?.contextTokens ??\n    resolveContextTokens(undefined, resolvedModel, backendContextDefault);\n  const outputTokens =\n    overrides?.outputTokens ??\n    resolveOutputTokens(undefined, resolvedModel, BACKEND_OUTPUT_FALLBACK);\n  const compactAt =\n    overrides?.compactAt ?? Math.floor(contextTokens * COMPACT_AT_RATIO);\n  const maxToolOutputTokens =\n    overrides?.maxToolOutputTokens ??\n    Math.floor(outputTokens * MAX_TOOL_OUTPUT_RATIO);\n\n  return { contextTokens, outputTokens, compactAt, maxToolOutputTokens };\n}\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAqBP,MAAM,sCAEF;AAAA,EACF,iBAAiB;AAAA,EACjB,cAAc;AAAA,EACd,QAAQ;AAAA,EACR,cAAc;AAAA,EACd,uBAAuB;AAAA,EACvB,oBAAoB;AAAA,EACpB,oBAAoB;AACtB;AAEA,MAAM,0BAA0B;AAChC,MAAM,mBAAmB;AACzB,MAAM,wBAAwB;AAQvB,SAAS,mBACd,SACA,OACA,WACa;AACb,QAAM,wBACJ,oCAAoC,OAAO,KAAK;AAClD,QAAM,gBAAgB,SAAS,0BAA0B,OAAO;AAChE,QAAM,gBACJ,WAAW,iBACX,qBAAqB,QAAW,eAAe,qBAAqB;AACtE,QAAM,eACJ,WAAW,gBACX,oBAAoB,QAAW,eAAe,uBAAuB;AACvE,QAAM,YACJ,WAAW,aAAa,KAAK,MAAM,gBAAgB,gBAAgB;AACrE,QAAM,sBACJ,WAAW,uBACX,KAAK,MAAM,eAAe,qBAAqB;AAEjD,SAAO,EAAE,eAAe,cAAc,WAAW,oBAAoB;AACvE;",
+  "names": []
+}

package/dist/config/runtime.d.ts

@@ -0,0 +1,50 @@
+import type { BackendExecutionPlan, ExecutionRuntimePolicy } from '../domain/contracts/backends.js';
+import type { BackendName } from '../domain/core-client.js';
+import type { BridgeApprovalMode, BridgeExecutionMode } from '../domain/core-task.js';
+import type { OctoFlowConfig } from './config.js';
+export interface PreparedExecutionPlan {
+    metadata: {
+        approvalMode: BridgeApprovalMode;
+        executionMode: BridgeExecutionMode;
+        profile: string;
+        workspace: string;
+    };
+    plan: BackendExecutionPlan;
+}
+export interface ResolvedContextPolicy {
+    approvalMode: BridgeApprovalMode;
+    createdAt: string;
+    executionMode: BridgeExecutionMode;
+    filesystem: {
+        denyPaths: string[];
+        readableRoots: string[];
+        writableRoots: string[];
+    };
+    network: string;
+    profile: string;
+    runtimeTarget: string;
+    sandbox: string;
+    workspace: string;
+}
+export declare function resolveWorkspace(cwd: string | undefined, profileName?: string, config?: OctoFlowConfig): string;
+export declare function resolveContextPolicy(options?: {
+    approvalMode?: BridgeApprovalMode;
+    config?: OctoFlowConfig;
+    createdAt?: string;
+    cwd?: string;
+    profile?: string;
+}): ResolvedContextPolicy;
+export declare function toExecutionRuntimePolicy(context: ResolvedContextPolicy, backend: BackendName): ExecutionRuntimePolicy;
+/**
+ * Validates a built execution plan for common issues before spawn.
+ * Throws if the plan has structural problems that would cause CLI failures.
+ * Plans using the `execute` function path (API backends) skip CLI-level checks.
+ */
+export declare function validateExecutionPlan(plan: BackendExecutionPlan, backend: BackendName): void;
+export declare function prepareExecutionPlan(backend: BackendName, plan: BackendExecutionPlan, options?: {
+    approvalMode?: BridgeApprovalMode;
+    config?: OctoFlowConfig;
+    cwd?: string;
+    profile?: string;
+}): PreparedExecutionPlan;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/config/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/config/runtime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE;QACR,YAAY,EAAE,kBAAkB,CAAC;QACjC,aAAa,EAAE,mBAAmB,CAAC;QACnC,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,IAAI,EAAE,oBAAoB,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,kBAAkB,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,mBAAmB,CAAC;IACnC,UAAU,EAAE;QACV,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;IACF,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAuED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,cAAc,GACtB,MAAM,CAUR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CACb,GACL,qBAAqB,CA4BvB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,WAAW,GACnB,sBAAsB,CAexB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,WAAW,GACnB,IAAI,CA0CN;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CACb,GACL,qBAAqB,CA+BvB"}

package/dist/config/runtime.js

@@ -0,0 +1,175 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { nowIso } from "../utils/time.js";
+import { resolveConfig, resolveProfile } from "./config.js";
+import { resolveChildEnv } from "./env-resolver.js";
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function expandTemplate(value, workspace) {
+  return value.replaceAll("${workspace}", workspace).replaceAll("${home}", homedir());
+}
+function sanitizeEnvironment(baseEnv, planEnv, input) {
+  const profile = resolveProfile(
+    input.profileName,
+    input.config ? resolveConfig(input.config) : void 0
+  );
+  return resolveChildEnv({
+    callEnv: planEnv,
+    processEnv: baseEnv,
+    profile,
+    backend: input.backend,
+    workspace: input.workspace
+  });
+}
+function validateWorkspace(workspace, profileName, config) {
+  const profile = resolveProfile(
+    profileName,
+    config ? resolveConfig(config) : void 0
+  );
+  const readableRoots = profile.security.filesystem.readableRoots.map(
+    (value) => expandTemplate(value, workspace)
+  );
+  const denyPaths = profile.security.filesystem.denyPaths.map(
+    (value) => expandTemplate(value, workspace)
+  );
+  if (denyPaths.some((denyPath) => isWithin(denyPath, workspace))) {
+    throw new Error(
+      `Workspace is denied by profile ${profile.name}: ${workspace}`
+    );
+  }
+  if (readableRoots.length > 0 && !readableRoots.some((root) => isWithin(root, workspace))) {
+    throw new Error(
+      `Workspace is outside readable roots for profile ${profile.name}: ${workspace}`
+    );
+  }
+}
+function resolveWorkspace(cwd, profileName, config) {
+  const profile = resolveProfile(
+    profileName,
+    config ? resolveConfig(config) : void 0
+  );
+  const workspace = path.resolve(
+    cwd ?? profile.defaults.cwd ?? profile.runtime.workspace ?? process.cwd()
+  );
+  validateWorkspace(workspace, profile.name, config);
+  return workspace;
+}
+function resolveContextPolicy(options = {}) {
+  const resolvedConfig = options.config ? resolveConfig(options.config) : void 0;
+  const profile = resolveProfile(options.profile, resolvedConfig);
+  const workspace = resolveWorkspace(options.cwd, profile.name, options.config);
+  return {
+    profile: profile.name,
+    workspace,
+    createdAt: options.createdAt ?? nowIso(),
+    executionMode: profile.runtime.executionMode,
+    runtimeTarget: profile.runtime.target,
+    approvalMode: options.approvalMode ?? profile.security.approvalMode,
+    network: profile.security.network,
+    sandbox: profile.security.sandbox,
+    filesystem: {
+      readableRoots: profile.security.filesystem.readableRoots.map(
+        (value) => expandTemplate(value, workspace)
+      ),
+      writableRoots: profile.security.filesystem.writableRoots.map(
+        (value) => expandTemplate(value, workspace)
+      ),
+      denyPaths: profile.security.filesystem.denyPaths.map(
+        (value) => expandTemplate(value, workspace)
+      )
+    }
+  };
+}
+function toExecutionRuntimePolicy(context, backend) {
+  return {
+    backend,
+    profile: context.profile,
+    workspace: context.workspace,
+    executionMode: context.executionMode,
+    approvalMode: context.approvalMode,
+    sandbox: context.sandbox,
+    network: context.network,
+    filesystem: {
+      readableRoots: [...context.filesystem.readableRoots],
+      writableRoots: [...context.filesystem.writableRoots],
+      denyPaths: [...context.filesystem.denyPaths]
+    }
+  };
+}
+function validateExecutionPlan(plan, backend) {
+  if (plan.execute || !plan.command) return;
+  if (plan.args) {
+    for (let i = 0; i < plan.args.length; i++) {
+      const arg = plan.args[i];
+      if (arg === "" && i > 0 && plan.args[i - 1].startsWith("-")) {
+        throw new Error(
+          `[${backend}] Empty argument value at index ${i} after flag "${plan.args[i - 1]}".`
+        );
+      }
+    }
+    const flagCounts = /* @__PURE__ */ new Map();
+    const uniqueFlags = [
+      "--permission-mode",
+      "--sandbox",
+      "--approval-mode",
+      "--model",
+      "--output-format"
+    ];
+    for (const arg of plan.args) {
+      if (uniqueFlags.includes(arg)) {
+        flagCounts.set(arg, (flagCounts.get(arg) ?? 0) + 1);
+        const count = flagCounts.get(arg);
+        if (count > 1) {
+          throw new Error(
+            `[${backend}] Duplicate flag "${arg}" in execution plan args.`
+          );
+        }
+      }
+    }
+  }
+  if (plan.runtimePolicy) {
+    const policy = plan.runtimePolicy;
+    if (policy.approvalMode === "off" && policy.sandbox !== "off") {
+    }
+  }
+}
+function prepareExecutionPlan(backend, plan, options = {}) {
+  const context = resolveContextPolicy({
+    approvalMode: options.approvalMode,
+    config: options.config,
+    cwd: options.cwd ?? plan.cwd,
+    profile: options.profile
+  });
+  const workspace = context.workspace;
+  const prepared = {
+    metadata: {
+      profile: context.profile,
+      workspace,
+      executionMode: context.executionMode,
+      approvalMode: context.approvalMode
+    },
+    plan: {
+      ...plan,
+      cwd: workspace,
+      env: sanitizeEnvironment(process.env, plan.env, {
+        backend,
+        config: options.config,
+        profileName: context.profile,
+        workspace
+      }),
+      runtimePolicy: toExecutionRuntimePolicy(context, backend)
+    }
+  };
+  validateExecutionPlan(prepared.plan, backend);
+  return prepared;
+}
+export {
+  prepareExecutionPlan,
+  resolveContextPolicy,
+  resolveWorkspace,
+  toExecutionRuntimePolicy,
+  validateExecutionPlan
+};
+//# sourceMappingURL=runtime.js.map

package/dist/config/runtime.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/config/runtime.ts"],
+  "sourcesContent": ["import { homedir } from 'node:os';\nimport path from 'node:path';\n\nimport type {\n  BackendExecutionPlan,\n  ExecutionRuntimePolicy,\n} from '../domain/contracts/backends.js';\nimport type { BackendName } from '../domain/core-client.js';\nimport type {\n  BridgeApprovalMode,\n  BridgeExecutionMode,\n} from '../domain/core-task.js';\nimport { nowIso } from '../utils/time.js';\nimport type { OctoFlowConfig } from './config.js';\nimport { resolveConfig, resolveProfile } from './config.js';\nimport { resolveChildEnv } from './env-resolver.js';\n\nexport interface PreparedExecutionPlan {\n  metadata: {\n    approvalMode: BridgeApprovalMode;\n    executionMode: BridgeExecutionMode;\n    profile: string;\n    workspace: string;\n  };\n  plan: BackendExecutionPlan;\n}\n\nexport interface ResolvedContextPolicy {\n  approvalMode: BridgeApprovalMode;\n  createdAt: string;\n  executionMode: BridgeExecutionMode;\n  filesystem: {\n    denyPaths: string[];\n    readableRoots: string[];\n    writableRoots: string[];\n  };\n  network: string;\n  profile: string;\n  runtimeTarget: string;\n  sandbox: string;\n  workspace: string;\n}\n\nfunction isWithin(root: string, candidate: string): boolean {\n  const relative = path.relative(root, candidate);\n  return (\n    relative === '' ||\n    (!relative.startsWith('..') && !path.isAbsolute(relative))\n  );\n}\n\nfunction expandTemplate(value: string, workspace: string): string {\n  return value\n    .replaceAll('${workspace}', workspace)\n    .replaceAll('${home}', homedir());\n}\n\nfunction sanitizeEnvironment(\n  baseEnv: NodeJS.ProcessEnv,\n  planEnv: Record<string, string> | undefined,\n  input: {\n    backend: BackendName;\n    config?: OctoFlowConfig;\n    profileName: string;\n    workspace: string;\n  }\n): Record<string, string> {\n  const profile = resolveProfile(\n    input.profileName,\n    input.config ? resolveConfig(input.config) : undefined\n  );\n  return resolveChildEnv({\n    callEnv: planEnv,\n    processEnv: baseEnv,\n    profile,\n    backend: input.backend,\n    workspace: input.workspace,\n  });\n}\n\nfunction validateWorkspace(\n  workspace: string,\n  profileName: string,\n  config?: OctoFlowConfig\n): void {\n  const profile = resolveProfile(\n    profileName,\n    config ? resolveConfig(config) : undefined\n  );\n  const readableRoots = profile.security.filesystem.readableRoots.map((value) =>\n    expandTemplate(value, workspace)\n  );\n  const denyPaths = profile.security.filesystem.denyPaths.map((value) =>\n    expandTemplate(value, workspace)\n  );\n\n  if (denyPaths.some((denyPath) => isWithin(denyPath, workspace))) {\n    throw new Error(\n      `Workspace is denied by profile ${profile.name}: ${workspace}`\n    );\n  }\n\n  if (\n    readableRoots.length > 0 &&\n    !readableRoots.some((root) => isWithin(root, workspace))\n  ) {\n    throw new Error(\n      `Workspace is outside readable roots for profile ${profile.name}: ${workspace}`\n    );\n  }\n}\n\nexport function resolveWorkspace(\n  cwd: string | undefined,\n  profileName?: string,\n  config?: OctoFlowConfig\n): string {\n  const profile = resolveProfile(\n    profileName,\n    config ? resolveConfig(config) : undefined\n  );\n  const workspace = path.resolve(\n    cwd ?? profile.defaults.cwd ?? profile.runtime.workspace ?? process.cwd()\n  );\n  validateWorkspace(workspace, profile.name, config);\n  return workspace;\n}\n\nexport function resolveContextPolicy(\n  options: {\n    approvalMode?: BridgeApprovalMode;\n    config?: OctoFlowConfig;\n    createdAt?: string;\n    cwd?: string;\n    profile?: string;\n  } = {}\n): ResolvedContextPolicy {\n  const resolvedConfig = options.config\n    ? resolveConfig(options.config)\n    : undefined;\n  const profile = resolveProfile(options.profile, resolvedConfig);\n  const workspace = resolveWorkspace(options.cwd, profile.name, options.config);\n\n  return {\n    profile: profile.name,\n    workspace,\n    createdAt: options.createdAt ?? nowIso(),\n    executionMode: profile.runtime.executionMode,\n    runtimeTarget: profile.runtime.target,\n    approvalMode: options.approvalMode ?? profile.security.approvalMode,\n    network: profile.security.network,\n    sandbox: profile.security.sandbox,\n    filesystem: {\n      readableRoots: profile.security.filesystem.readableRoots.map((value) =>\n        expandTemplate(value, workspace)\n      ),\n      writableRoots: profile.security.filesystem.writableRoots.map((value) =>\n        expandTemplate(value, workspace)\n      ),\n      denyPaths: profile.security.filesystem.denyPaths.map((value) =>\n        expandTemplate(value, workspace)\n      ),\n    },\n  };\n}\n\nexport function toExecutionRuntimePolicy(\n  context: ResolvedContextPolicy,\n  backend: BackendName\n): ExecutionRuntimePolicy {\n  return {\n    backend,\n    profile: context.profile,\n    workspace: context.workspace,\n    executionMode: context.executionMode,\n    approvalMode: context.approvalMode,\n    sandbox: context.sandbox,\n    network: context.network,\n    filesystem: {\n      readableRoots: [...context.filesystem.readableRoots],\n      writableRoots: [...context.filesystem.writableRoots],\n      denyPaths: [...context.filesystem.denyPaths],\n    },\n  };\n}\n\n/**\n * Validates a built execution plan for common issues before spawn.\n * Throws if the plan has structural problems that would cause CLI failures.\n * Plans using the `execute` function path (API backends) skip CLI-level checks.\n */\nexport function validateExecutionPlan(\n  plan: BackendExecutionPlan,\n  backend: BackendName\n): void {\n  // API backends use plan.execute, and some inline plans omit command entirely.\n  if (plan.execute || !plan.command) return;\n\n  if (plan.args) {\n    for (let i = 0; i < plan.args.length; i++) {\n      const arg = plan.args[i]!;\n      if (arg === '' && i > 0 && plan.args[i - 1]!.startsWith('-')) {\n        throw new Error(\n          `[${backend}] Empty argument value at index ${i} after flag \"${plan.args[i - 1]}\".`\n        );\n      }\n    }\n\n    // Flag-level sanity: permission/sandbox flags should not appear more than once.\n    const flagCounts = new Map<string, number>();\n    const uniqueFlags = [\n      '--permission-mode',\n      '--sandbox',\n      '--approval-mode',\n      '--model',\n      '--output-format',\n    ];\n    for (const arg of plan.args) {\n      if (uniqueFlags.includes(arg)) {\n        flagCounts.set(arg, (flagCounts.get(arg) ?? 0) + 1);\n        const count = flagCounts.get(arg)!;\n        if (count > 1) {\n          throw new Error(\n            `[${backend}] Duplicate flag \"${arg}\" in execution plan args.`\n          );\n        }\n      }\n    }\n  }\n\n  if (plan.runtimePolicy) {\n    const policy = plan.runtimePolicy;\n    if (policy.approvalMode === 'off' && policy.sandbox !== 'off') {\n      // Allowed \u2014 approval off with sandbox on is \"auto but sandboxed\".\n    }\n  }\n}\n\nexport function prepareExecutionPlan(\n  backend: BackendName,\n  plan: BackendExecutionPlan,\n  options: {\n    approvalMode?: BridgeApprovalMode;\n    config?: OctoFlowConfig;\n    cwd?: string;\n    profile?: string;\n  } = {}\n): PreparedExecutionPlan {\n  const context = resolveContextPolicy({\n    approvalMode: options.approvalMode,\n    config: options.config,\n    cwd: options.cwd ?? plan.cwd,\n    profile: options.profile,\n  });\n  const workspace = context.workspace;\n\n  const prepared: PreparedExecutionPlan = {\n    metadata: {\n      profile: context.profile,\n      workspace,\n      executionMode: context.executionMode,\n      approvalMode: context.approvalMode,\n    },\n    plan: {\n      ...plan,\n      cwd: workspace,\n      env: sanitizeEnvironment(process.env, plan.env, {\n        backend,\n        config: options.config,\n        profileName: context.profile,\n        workspace,\n      }),\n      runtimePolicy: toExecutionRuntimePolicy(context, backend),\n    },\n  };\n\n  validateExecutionPlan(prepared.plan, backend);\n  return prepared;\n}\n"],
+  "mappings": "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",
+  "names": []
+}