patchwork-os 0.2.0-beta.9.canary.92 → 1.1.0-beta.1

package/dist/recipes/agentExecutor.js

@@ -7,21 +7,94 @@
  * CHANGELOG: chained users with model:local in ~/.patchwork/config now route to
  * localFn (Ollama/LM Studio) instead of Anthropic API — opt-in behaviour change.
  */
-const DEFAULT_MODEL = "claude-haiku-4-5-20251001";
+/**
+ * Model the anthropic/local agent paths fall back to when a step omits `model`.
+ * Exported so RunBudget.quoteUsd prices the same model executeAgent will run
+ * (keeps cost-routing quotes in parity with actual reconcile billing).
+ */
+export const DEFAULT_MODEL = "claude-haiku-4-5-20251001";
+/**
+ * Will `executeAgent` route this call to the subprocess (`claude -p`) driver —
+ * the ONLY driver that enforces `--disallowed-tools`? Mirrors the dispatch in
+ * `executeAgent` exactly (explicit driver, then pwCfg, then auto-detect) so the
+ * worker-sandbox guard agrees with where the call actually lands. `probeClaudeCli`
+ * / `loadPatchworkConfig` are cheap + idempotent, so calling them here too is fine.
+ */
+function resolvesToSubprocessDriver(driver, deps) {
+    if (driver === "subprocess" || driver === "claude-code")
+        return true;
+    if (driver !== undefined)
+        return false; // anthropic/claude/openai/grok/gemini*/local
+    const pwCfg = deps.loadPatchworkConfig();
+    if (pwCfg.model === "local")
+        return false;
+    if (pwCfg.driver === "subprocess" || pwCfg.driver === "claude-code")
+        return true;
+    if (process.env.ANTHROPIC_API_KEY)
+        return false; // auto-detect → anthropic API
+    return deps.probeClaudeCli(); // CLI present → subprocess; else falls back to API
+}
 export async function executeAgent(input, deps) {
-    const { prompt, driver, model, mcpAccess } = input;
-    const cliOpts = mcpAccess !== undefined ? { mcpAccess } : undefined;
+    const { prompt, driver, model, mcpAccess, sandbox, allowedTools, disallowedTools, providerOptions, enforceSandbox, } = input;
+    // NEVER-WIDEN guard. A worker-mandated sandbox is enforceable only on the
+    // subprocess driver; on any other driver the deny list is silently dropped and
+    // the worker's agent step could perform exactly the risky action the gate
+    // believed it sandboxed. Fail closed: refuse to run rather than run un-gated.
+    // The "[agent step failed:" prefix is the marker the runners already treat as a
+    // step failure (halting non-optional steps), so the agent never executes.
+    if (enforceSandbox && !resolvesToSubprocessDriver(driver, deps)) {
+        return {
+            text: "[agent step failed: worker autonomy requires the subprocess driver to enforce its tool sandbox — set the agent step (or recipe) driver to `subprocess`/`claude-code`; refusing to run un-sandboxed]",
+            servedBy: { driver: driver ?? "auto" },
+        };
+    }
+    const cliOpts = mcpAccess !== undefined ||
+        sandbox !== undefined ||
+        allowedTools !== undefined ||
+        disallowedTools !== undefined
+        ? {
+            ...(mcpAccess !== undefined && { mcpAccess }),
+            ...(sandbox !== undefined && { sandbox }),
+            ...(allowedTools !== undefined && { allowedTools }),
+            ...(disallowedTools !== undefined && { disallowedTools }),
+        }
+        : undefined;
+    // Stamp the driver that ACTUALLY ran onto the result. This is the single
+    // place driver auto-detection is resolved, so it is the only place that
+    // knows the true answer — callers (RunBudget.reconcile, future cost
+    // accounting) must not re-guess from the configured `driver` string.
+    // Additive and idempotent: never overwrites a servedBy a dep already set.
+    const stamp = async (resolvedDriver, resolvedModel, p) => {
+        const r = await p;
+        if (r.servedBy)
+            return r;
+        return {
+            ...r,
+            servedBy: {
+                driver: resolvedDriver,
+                ...(resolvedModel !== undefined ? { model: resolvedModel } : {}),
+            },
+        };
+    };
     if (driver === "anthropic" || driver === "claude") {
-        return deps.anthropicFn(prompt, model ?? DEFAULT_MODEL);
+        return stamp("anthropic", model ?? DEFAULT_MODEL, deps.anthropicFn(prompt, model ?? DEFAULT_MODEL));
     }
-    if (driver === "openai" || driver === "grok" || driver === "gemini") {
-        return deps.providerDriverFn(driver, prompt, model);
+    if (driver === "openai" ||
+        driver === "grok" ||
+        driver === "gemini" ||
+        driver === "gemini-api") {
+        return stamp(driver, model, 
+        // Only pass the 4th arg when set so the common (unconstrained) call keeps
+        // its 3-arg shape — backward-compatible with callers/mocks.
+        providerOptions
+            ? deps.providerDriverFn(driver, prompt, model, providerOptions)
+            : deps.providerDriverFn(driver, prompt, model));
     }
     if (driver === "subprocess" || driver === "claude-code") {
-        return deps.claudeCliFn(prompt, cliOpts);
+        return stamp("subprocess", model, deps.claudeCliFn(prompt, cliOpts));
     }
     if (driver === "local") {
-        return deps.localFn(prompt, model ?? DEFAULT_MODEL);
+        return stamp("local", model ?? DEFAULT_MODEL, deps.localFn(prompt, model ?? DEFAULT_MODEL));
     }
     if (driver !== undefined) {
         throw new Error(`Unknown driver: "${driver}"`);
@@ -29,22 +102,22 @@ export async function executeAgent(input, deps) {
     // No driver — check pwCfg for local model preference (THE MISSING BRANCH).
     const pwCfg = deps.loadPatchworkConfig();
     if (pwCfg.model === "local") {
-        return deps.localFn(prompt, model ?? DEFAULT_MODEL);
+        return stamp("local", model ?? DEFAULT_MODEL, deps.localFn(prompt, model ?? DEFAULT_MODEL));
     }
     // Explicit subprocess driver config → skip API key check entirely.
     if (pwCfg.driver === "subprocess" || pwCfg.driver === "claude-code") {
-        return deps.claudeCliFn(prompt, cliOpts);
+        return stamp("subprocess", model, deps.claudeCliFn(prompt, cliOpts));
     }
     // Auto-detect: prefer API key, otherwise probe for claude CLI.
     if (process.env.ANTHROPIC_API_KEY) {
-        return deps.anthropicFn(prompt, model ?? DEFAULT_MODEL);
+        return stamp("anthropic", model ?? DEFAULT_MODEL, deps.anthropicFn(prompt, model ?? DEFAULT_MODEL));
     }
     if (deps.probeClaudeCli()) {
-        return deps.claudeCliFn(prompt, cliOpts);
+        return stamp("subprocess", model, deps.claudeCliFn(prompt, cliOpts));
     }
     // Probe failed and no API key — fall back to anthropicFn so the caller
     // surfaces a clear "[agent step skipped: ANTHROPIC_API_KEY not set]" message
     // (and so test overrides of claudeFn/anthropicFn are honored).
-    return deps.anthropicFn(prompt, model ?? DEFAULT_MODEL);
+    return stamp("anthropic", model ?? DEFAULT_MODEL, deps.anthropicFn(prompt, model ?? DEFAULT_MODEL));
 }
 //# sourceMappingURL=agentExecutor.js.map

package/dist/recipes/agentExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentExecutor.js","sourceRoot":"","sources":["../../src/recipes/agentExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwDH,MAAM,aAAa,GAAG,2BAA2B,CAAC;AAElD,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAyB,EACzB,IAAuB;IAEvB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IACnD,MAAM,OAAO,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAEpE,IAAI,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,IAAI,aAAa,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACpE,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,MAAM,KAAK,YAAY,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;QACxD,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,aAAa,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,GAAG,CAAC,CAAC;IACjD,CAAC;IAED,2EAA2E;IAC3E,MAAM,KAAK,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;IACzC,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,aAAa,CAAC,CAAC;IACtD,CAAC;IAED,mEAAmE;IACnE,IAAI,KAAK,CAAC,MAAM,KAAK,YAAY,IAAI,KAAK,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QACpE,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED,+DAA+D;IAC/D,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,IAAI,aAAa,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,uEAAuE;IACvE,6EAA6E;IAC7E,+DAA+D;IAC/D,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,IAAI,aAAa,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"agentExecutor.js","sourceRoot":"","sources":["../../src/recipes/agentExecutor.ts"],"names":[],"mappings":"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"}

package/dist/recipes/chainedRunner.d.ts

@@ -6,9 +6,14 @@
  *   - Conditional step execution (when)
  *   - Dry-run mode
  */
+import { type RiskTier } from "../riskTier.js";
+import type { AgentResult } from "./agentExecutor.js";
 import type { NestedRecipeConfig } from "./nestedRecipeStep.js";
 import type { OutputRegistry } from "./outputRegistry.js";
-import type { ErrorPolicy } from "./schema.js";
+import type { RouteCandidate } from "./pricing/costRouter.js";
+import { type PriceTable } from "./pricing/priceTable.js";
+import { RunBudget } from "./runBudget.js";
+import type { BudgetPolicy, ErrorPolicy } from "./schema.js";
 import type { TemplateContext, TemplateError } from "./templateEngine.js";
 import type { StepExpect } from "./yamlRunner.js";
 export interface ChainedStep {
@@ -18,6 +23,15 @@ export interface ChainedStep {
         prompt: string;
         model?: string;
         driver?: string;
+        /** Cost-aware routing fallbacks (Phase 4) — mirrors the flat path. */
+        downshift?: RouteCandidate[];
+        mcpAccess?: boolean;
+        /** Tool allowlist enforced via --allowed-tools when `sandbox` is true. */
+        tools?: string[];
+        /** Opt-in tool sandbox — drop --dangerously-skip-permissions, enforce allowlist. */
+        sandbox?: boolean;
+        /** Deny rules via --disallowed-tools in any mode. */
+        disallowedTools?: string[];
     };
     recipe?: NestedRecipeConfig["recipe"];
     chain?: NestedRecipeConfig["recipe"];
@@ -33,6 +47,13 @@ export interface ChainedStep {
     retry?: number;
     /** Delay in ms between retries (default 1000). */
     retryDelay?: number;
+    /**
+     * Per-step wall-clock timeout (ms). When >0, the tool/agent dispatch is raced
+     * against a timer; on expiry the step fails with `step_timeout` (the
+     * underlying call keeps running but its result is ignored). Mirrors the flat
+     * yamlRunner's `timeout_ms` — audit 2026-06-08 (recipe-chained-4).
+     */
+    timeout_ms?: number;
     transform?: string;
     expect?: StepExpect;
     [key: string]: unknown;
@@ -46,6 +67,14 @@ export interface ChainedRecipe {
     /** Plugin specs (npm package name or local path) to load before running steps. */
     servers?: string[];
     on_error?: ErrorPolicy;
+    /**
+     * Per-recipe token / USD budget. Mirrors the flat (yamlRunner) path: one
+     * `RunBudget` is constructed per top-level run, agent steps consult it
+     * before dispatch (admission) and reconcile actual consumption after. Absent
+     * → no enforcement, no overhead. SECURITY: without this thread a chained
+     * recipe ran UNBOUNDED API calls (S1 finding).
+     */
+    budget?: BudgetPolicy;
 }
 export interface RunOptions {
     env: Record<string, string | undefined>;
@@ -53,6 +82,13 @@ export interface RunOptions {
     maxDepth: number;
     dryRun: boolean;
     sourcePath?: string;
+    /**
+     * Run-level cancellation. Nested recipes inherit the parent's signal; the
+     * top-level run also registers its own AbortController via the run registry
+     * (keyed by RunLog seq) so `POST /runs/:seq/cancel` can abort it. When it
+     * fires, not-yet-started steps are skipped and the run drains. (run-cancel)
+     */
+    signal?: AbortSignal;
     onStepStart?: (stepId: string) => void;
     onStepComplete?: (stepId: string, error?: Error) => void;
     /**
@@ -99,6 +135,19 @@ export interface RunOptions {
      * run log entry so the dashboard can render the causal chain.
      */
     parentSeq?: number;
+    /**
+     * Shared per-run budget. Constructed once by the top-level
+     * `runChainedRecipe` from `recipe.budget` and threaded into nested recipe
+     * calls so the whole tree shares one cap (mirrors the flat path's single
+     * `RunBudget` per run). Internal — callers don't set this.
+     */
+    budget?: RunBudget;
+    /**
+     * Price table loaded once per top-level run and inherited by nested recipe
+     * calls (same lifetime as `budget`) so per-step usage costing avoids a
+     * synchronous disk round-trip. Internal — callers don't set this.
+     */
+    priceTable?: PriceTable;
 }
 export interface StepExecutionContext {
     registry: OutputRegistry;
@@ -106,9 +155,28 @@ export interface StepExecutionContext {
     options: RunOptions;
     recipe: ChainedRecipe;
     depth: number;
+    /** Shared per-run budget (admit before dispatch, reconcile after). */
+    budget?: RunBudget;
+    /**
+     * Price table loaded ONCE per run and threaded through so each agent step's
+     * `computeAgentCallUsage` call avoids a synchronous existsSync/readFileSync
+     * round-trip (mirrors the flat runner, which loads it once at run start).
+     */
+    priceTable?: PriceTable;
 }
 export type ToolExecutor = (tool: string, params: Record<string, unknown>) => Promise<unknown>;
-export type AgentExecutor = (prompt: string, model?: string, driver?: string) => Promise<string>;
+/**
+ * Agent dispatch closure. Returns either a bare string (legacy / simple test
+ * mocks) or an `AgentResult` carrying `usage` + `servedBy` so the chained
+ * runner can reconcile real spend against the run budget (alignment with the
+ * flat path — previously the yamlRunner closure discarded `.usage`).
+ */
+export type AgentExecutor = (prompt: string, model?: string, driver?: string, opts?: {
+    mcpAccess?: boolean;
+    sandbox?: boolean;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+}) => Promise<string | AgentResult>;
 export interface ExecutionDeps {
     executeTool: ToolExecutor;
     executeAgent: AgentExecutor;
@@ -116,11 +184,34 @@ export interface ExecutionDeps {
         recipe: ChainedRecipe;
         sourcePath?: string;
     } | null>;
+    /**
+     * Tier-1 #4 (audit 2026-06-22) — approval gate, mirroring the flat runner's
+     * `RunnerDeps.requireApprovalFn`. Injected by the bridge ONLY when
+     * `approvalGate != "off"`. When present, `executeChainedStep` calls it before
+     * dispatching each agent/tool step of the TOP-LEVEL run (depth 0) and HALTS
+     * the step (and, via the dependency graph, its dependents) if it resolves
+     * `false`. Gating is depth-scoped rather than trigger-scoped because a
+     * chained recipe's `trigger.type` is always `"chained"` (never "manual"/
+     * "cron") — cron/webhook route to the flat runner, so a top-level chained run
+     * is the interactive case. Nested chained recipes (depth > 0) are not
+     * re-gated. The fn itself applies the gate threshold (high/all) against the
+     * step's tier and returns `true` for steps that don't need sign-off, so the
+     * runner only acts on an explicit rejection. Per-recipe opt-out via
+     * `requireApproval: false`.
+     */
+    requireApprovalFn?: (input: {
+        toolId: string;
+        tier: RiskTier;
+        summary?: string;
+        params?: Record<string, unknown>;
+        /** Run AbortSignal — cancels the approval wait promptly on run abort (L1). */
+        signal?: AbortSignal;
+    }) => Promise<boolean>;
 }
 /** Build template context from registry and env */
 export declare function buildTemplateContext(registry: OutputRegistry, env: Record<string, string | undefined>): TemplateContext;
 /** Resolve all template strings in a step */
-export declare function resolveStepTemplates(step: ChainedStep, context: TemplateContext): {
+export declare function resolveStepTemplates(step: ChainedStep, context: TemplateContext, secretKeys?: ReadonlySet<string>): {
     resolved: Record<string, unknown>;
     conditionResult: boolean;
     errors: TemplateError[];
@@ -134,6 +225,23 @@ export declare function executeChainedStep(ctx: StepExecutionContext, deps: Exec
     /** VD-2: resolved params after template substitution — captured by the
      *  runner for the dashboard's per-step view. */
     resolvedParams?: unknown;
+    /**
+     * P1 cost/token corpus — agent token usage for this step (chained steps
+     * make exactly one agent call). Absent for tool steps and unmeasured
+     * drivers. `costUsd` set only for a priceable billable model (never 0).
+     */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd?: number;
+    };
+    /**
+     * `expect` assertion failures recorded when `on_fail: "warn"` — the step
+     * still succeeds (the run continues) but the warnings are surfaced on the
+     * persisted step row / dashboard. Mirrors the flat runner's
+     * `last.expectWarnings`. Absent when there are no warn-mode failures.
+     */
+    expectWarnings?: string[];
 }>;
 export interface ChainedStepRunResult {
     success: boolean;