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

package/dist/schemas/recipe.v1.json

@@ -18,8 +18,8 @@
   "properties": {
     "name": {
       "type": "string",
-      "description": "Recipe name (kebab-case recommended)",
-      "pattern": "^[a-z0-9-]+$"
+      "description": "Recipe name (kebab-case, 1-64 chars). Scoped names like @scope/name are accepted for registry recipes.",
+      "pattern": "^(@[a-z0-9-]+/)?[a-z0-9][a-z0-9-]{0,63}$"
     },
     "description": {
       "type": "string",
@@ -87,7 +87,63 @@
         },
         "filter": {
           "type": "string",
-          "description": "File filter pattern (for file_watch trigger)"
+          "description": "File filter pattern (for file_watch trigger). For on_test_run triggers, one of: any | failure | pass-after-fail."
+        },
+        "vars": {
+          "type": "array",
+          "description": "Declared input variables resolvable as {{name}} in steps. Place declared variables here (NOT at recipe root — top-level vars are ignored at runtime).",
+          "items": {
+            "type": "object",
+            "required": [
+              "name"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
+                "description": "Variable name (letter/underscore start; letters, digits, underscores; max 64 chars)."
+              },
+              "required": {
+                "type": "boolean",
+                "description": "Whether the variable must be supplied."
+              },
+              "default": {
+                "description": "Default value when not supplied."
+              },
+              "description": {
+                "type": "string",
+                "description": "Human-readable description of the variable."
+              }
+            }
+          }
+        },
+        "inputs": {
+          "type": "array",
+          "description": "Alias for trigger.vars — declared input variables resolvable as {{name}} in steps.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
+                "description": "Variable name (letter/underscore start; letters, digits, underscores; max 64 chars)."
+              },
+              "required": {
+                "type": "boolean",
+                "description": "Whether the variable must be supplied."
+              },
+              "default": {
+                "description": "Default value when not supplied."
+              },
+              "description": {
+                "type": "string",
+                "description": "Human-readable description of the variable."
+              }
+            }
+          }
         },
         "eventSource": {
           "type": "string",
@@ -267,7 +323,8 @@
                       "openai",
                       "grok",
                       "gemini",
-                      "anthropic"
+                      "anthropic",
+                      "local"
                     ],
                     "description": "Driver for agent execution"
                   },
@@ -279,12 +336,101 @@
                     "type": "boolean",
                     "description": "When true, grants the agent step access to MCP tools registered on the bridge. Defaults to false for subprocess driver steps."
                   },
+                  "tools": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Tool allowlist. When `sandbox` is true, enforced via --allowed-tools on the spawned claude -p."
+                  },
+                  "sandbox": {
+                    "type": "boolean",
+                    "description": "Opt-in tool sandbox: enforce the `tools` allowlist by running claude -p with --permission-mode dontAsk + --allowed-tools (drops --dangerously-skip-permissions). Default off. Pure pass-through with mcpAccess: when both are set, MCP tool names must be listed in `tools` or they will be blocked (no auto-injection)."
+                  },
+                  "disallowedTools": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Deny rules applied via --disallowed-tools regardless of sandbox mode."
+                  },
                   "kind": {
                     "type": "string",
                     "enum": [
                       "judge"
                     ],
                     "description": "When set to 'judge', the agent step emits a structured verdictReason and stores the verdict in the run log."
+                  },
+                  "reviews": {
+                    "type": "string",
+                    "description": "Step output key the judge reviews (its `into`, default 'agent_output'). Required for the judge→refine loop."
+                  },
+                  "max_revisions": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "OPT-IN judge→refine loop. Max revise→re-judge cycles when the verdict is 'request_changes' (0/absent = augment-only, no loop). Requires kind:judge + reviews."
+                  },
+                  "on_exhausted": {
+                    "type": "string",
+                    "enum": [
+                      "halt",
+                      "proceed"
+                    ],
+                    "description": "When the revision budget is exhausted and the judge still requests changes: 'halt' (default) fails the run; 'proceed' continues with the last draft."
+                  },
+                  "downshift": {
+                    "type": "array",
+                    "description": "OPT-IN cost-aware routing (Phase 4). Ordered cheaper fallbacks tried when budget.usdMax is set and the remaining budget is too tight for the preferred driver/model. Each entry overrides driver and/or model. Absent → preferred model always used.",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "minProperties": 1,
+                      "properties": {
+                        "driver": {
+                          "type": "string",
+                          "enum": [
+                            "claude",
+                            "claude-code",
+                            "api",
+                            "openai",
+                            "grok",
+                            "gemini",
+                            "anthropic",
+                            "local"
+                          ]
+                        },
+                        "model": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  },
+                  "escalate": {
+                    "type": "array",
+                    "description": "OPT-IN quality-aware escalation (dual of downshift). Ordered MORE-capable fallbacks. In a judge→refine loop (reviews + max_revisions>0), the Nth request_changes revision re-runs the reviewed step with escalate[N-1] instead of the base model — start local/cheap, escalate to a stronger model only when output fails judgment. Each entry overrides driver and/or model.",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "minProperties": 1,
+                      "properties": {
+                        "driver": {
+                          "type": "string",
+                          "enum": [
+                            "claude",
+                            "claude-code",
+                            "api",
+                            "openai",
+                            "grok",
+                            "gemini",
+                            "anthropic",
+                            "local"
+                          ]
+                        },
+                        "model": {
+                          "type": "string"
+                        }
+                      }
+                    }
                   }
                 }
               }
@@ -631,10 +777,12 @@
                               "description": "Agent step configuration",
                               "properties": {
                                 "prompt": {
-                                  "type": "string"
+                                  "type": "string",
+                                  "description": "Prompt to send to the AI (supports {{templates}})"
                                 },
                                 "model": {
-                                  "type": "string"
+                                  "type": "string",
+                                  "description": "Model to use for the agent step"
                                 },
                                 "driver": {
                                   "type": "string",
@@ -645,22 +793,114 @@
                                     "openai",
                                     "grok",
                                     "gemini",
-                                    "anthropic"
-                                  ]
+                                    "anthropic",
+                                    "local"
+                                  ],
+                                  "description": "Driver for agent execution"
                                 },
                                 "into": {
-                                  "type": "string"
+                                  "type": "string",
+                                  "description": "Variable name to store output in context"
                                 },
                                 "mcpAccess": {
                                   "type": "boolean",
                                   "description": "When true, grants the agent step access to MCP tools registered on the bridge. Defaults to false for subprocess driver steps."
                                 },
+                                "tools": {
+                                  "type": "array",
+                                  "items": {
+                                    "type": "string"
+                                  },
+                                  "description": "Tool allowlist. When `sandbox` is true, enforced via --allowed-tools on the spawned claude -p."
+                                },
+                                "sandbox": {
+                                  "type": "boolean",
+                                  "description": "Opt-in tool sandbox: enforce the `tools` allowlist by running claude -p with --permission-mode dontAsk + --allowed-tools (drops --dangerously-skip-permissions). Default off. Pure pass-through with mcpAccess: when both are set, MCP tool names must be listed in `tools` or they will be blocked (no auto-injection)."
+                                },
+                                "disallowedTools": {
+                                  "type": "array",
+                                  "items": {
+                                    "type": "string"
+                                  },
+                                  "description": "Deny rules applied via --disallowed-tools regardless of sandbox mode."
+                                },
                                 "kind": {
                                   "type": "string",
                                   "enum": [
                                     "judge"
                                   ],
                                   "description": "When set to 'judge', the agent step emits a structured verdictReason and stores the verdict in the run log."
+                                },
+                                "reviews": {
+                                  "type": "string",
+                                  "description": "Step output key the judge reviews (its `into`, default 'agent_output'). Required for the judge→refine loop."
+                                },
+                                "max_revisions": {
+                                  "type": "integer",
+                                  "minimum": 0,
+                                  "description": "OPT-IN judge→refine loop. Max revise→re-judge cycles when the verdict is 'request_changes' (0/absent = augment-only, no loop). Requires kind:judge + reviews."
+                                },
+                                "on_exhausted": {
+                                  "type": "string",
+                                  "enum": [
+                                    "halt",
+                                    "proceed"
+                                  ],
+                                  "description": "When the revision budget is exhausted and the judge still requests changes: 'halt' (default) fails the run; 'proceed' continues with the last draft."
+                                },
+                                "downshift": {
+                                  "type": "array",
+                                  "description": "OPT-IN cost-aware routing (Phase 4). Ordered cheaper fallbacks tried when budget.usdMax is set and the remaining budget is too tight for the preferred driver/model. Each entry overrides driver and/or model. Absent → preferred model always used.",
+                                  "items": {
+                                    "type": "object",
+                                    "additionalProperties": false,
+                                    "minProperties": 1,
+                                    "properties": {
+                                      "driver": {
+                                        "type": "string",
+                                        "enum": [
+                                          "claude",
+                                          "claude-code",
+                                          "api",
+                                          "openai",
+                                          "grok",
+                                          "gemini",
+                                          "anthropic",
+                                          "local"
+                                        ]
+                                      },
+                                      "model": {
+                                        "type": "string"
+                                      }
+                                    }
+                                  }
+                                },
+                                "escalate": {
+                                  "type": "array",
+                                  "description": "OPT-IN quality-aware escalation (dual of downshift). Ordered MORE-capable fallbacks. In a judge→refine loop (reviews + max_revisions>0), the Nth request_changes revision re-runs the reviewed step with escalate[N-1] instead of the base model — start local/cheap, escalate to a stronger model only when output fails judgment. Each entry overrides driver and/or model.",
+                                  "items": {
+                                    "type": "object",
+                                    "additionalProperties": false,
+                                    "minProperties": 1,
+                                    "properties": {
+                                      "driver": {
+                                        "type": "string",
+                                        "enum": [
+                                          "claude",
+                                          "claude-code",
+                                          "api",
+                                          "openai",
+                                          "grok",
+                                          "gemini",
+                                          "anthropic",
+                                          "local"
+                                        ]
+                                      },
+                                      "model": {
+                                        "type": "string"
+                                      }
+                                    }
+                                  }
                                 }
                               }
                             }
@@ -1006,10 +1246,12 @@
                                   "description": "Agent step configuration",
                                   "properties": {
                                     "prompt": {
-                                      "type": "string"
+                                      "type": "string",
+                                      "description": "Prompt to send to the AI (supports {{templates}})"
                                     },
                                     "model": {
-                                      "type": "string"
+                                      "type": "string",
+                                      "description": "Model to use for the agent step"
                                     },
                                     "driver": {
                                       "type": "string",
@@ -1020,22 +1262,114 @@
                                         "openai",
                                         "grok",
                                         "gemini",
-                                        "anthropic"
-                                      ]
+                                        "anthropic",
+                                        "local"
+                                      ],
+                                      "description": "Driver for agent execution"
                                     },
                                     "into": {
-                                      "type": "string"
+                                      "type": "string",
+                                      "description": "Variable name to store output in context"
                                     },
                                     "mcpAccess": {
                                       "type": "boolean",
                                       "description": "When true, grants the agent step access to MCP tools registered on the bridge. Defaults to false for subprocess driver steps."
                                     },
+                                    "tools": {
+                                      "type": "array",
+                                      "items": {
+                                        "type": "string"
+                                      },
+                                      "description": "Tool allowlist. When `sandbox` is true, enforced via --allowed-tools on the spawned claude -p."
+                                    },
+                                    "sandbox": {
+                                      "type": "boolean",
+                                      "description": "Opt-in tool sandbox: enforce the `tools` allowlist by running claude -p with --permission-mode dontAsk + --allowed-tools (drops --dangerously-skip-permissions). Default off. Pure pass-through with mcpAccess: when both are set, MCP tool names must be listed in `tools` or they will be blocked (no auto-injection)."
+                                    },
+                                    "disallowedTools": {
+                                      "type": "array",
+                                      "items": {
+                                        "type": "string"
+                                      },
+                                      "description": "Deny rules applied via --disallowed-tools regardless of sandbox mode."
+                                    },
                                     "kind": {
                                       "type": "string",
                                       "enum": [
                                         "judge"
                                       ],
                                       "description": "When set to 'judge', the agent step emits a structured verdictReason and stores the verdict in the run log."
+                                    },
+                                    "reviews": {
+                                      "type": "string",
+                                      "description": "Step output key the judge reviews (its `into`, default 'agent_output'). Required for the judge→refine loop."
+                                    },
+                                    "max_revisions": {
+                                      "type": "integer",
+                                      "minimum": 0,
+                                      "description": "OPT-IN judge→refine loop. Max revise→re-judge cycles when the verdict is 'request_changes' (0/absent = augment-only, no loop). Requires kind:judge + reviews."
+                                    },
+                                    "on_exhausted": {
+                                      "type": "string",
+                                      "enum": [
+                                        "halt",
+                                        "proceed"
+                                      ],
+                                      "description": "When the revision budget is exhausted and the judge still requests changes: 'halt' (default) fails the run; 'proceed' continues with the last draft."
+                                    },
+                                    "downshift": {
+                                      "type": "array",
+                                      "description": "OPT-IN cost-aware routing (Phase 4). Ordered cheaper fallbacks tried when budget.usdMax is set and the remaining budget is too tight for the preferred driver/model. Each entry overrides driver and/or model. Absent → preferred model always used.",
+                                      "items": {
+                                        "type": "object",
+                                        "additionalProperties": false,
+                                        "minProperties": 1,
+                                        "properties": {
+                                          "driver": {
+                                            "type": "string",
+                                            "enum": [
+                                              "claude",
+                                              "claude-code",
+                                              "api",
+                                              "openai",
+                                              "grok",
+                                              "gemini",
+                                              "anthropic",
+                                              "local"
+                                            ]
+                                          },
+                                          "model": {
+                                            "type": "string"
+                                          }
+                                        }
+                                      }
+                                    },
+                                    "escalate": {
+                                      "type": "array",
+                                      "description": "OPT-IN quality-aware escalation (dual of downshift). Ordered MORE-capable fallbacks. In a judge→refine loop (reviews + max_revisions>0), the Nth request_changes revision re-runs the reviewed step with escalate[N-1] instead of the base model — start local/cheap, escalate to a stronger model only when output fails judgment. Each entry overrides driver and/or model.",
+                                      "items": {
+                                        "type": "object",
+                                        "additionalProperties": false,
+                                        "minProperties": 1,
+                                        "properties": {
+                                          "driver": {
+                                            "type": "string",
+                                            "enum": [
+                                              "claude",
+                                              "claude-code",
+                                              "api",
+                                              "openai",
+                                              "grok",
+                                              "gemini",
+                                              "anthropic",
+                                              "local"
+                                            ]
+                                          },
+                                          "model": {
+                                            "type": "string"
+                                          }
+                                        }
+                                      }
                                     }
                                   }
                                 }
@@ -1345,19 +1679,29 @@
     },
     "budget": {
       "type": "object",
-      "description": "Per-recipe token budget (PR2b). When set, the runner tracks cumulative tokens across API driver calls; on breach the run halts with budget_exceeded. Subscription drivers (Claude CLI) don't report token counts and are skipped.",
+      "description": "Per-recipe budget. Set tokensMax and/or usdMax; on breach the run halts with budget_exceeded (or warns). Enforced for API drivers that report token usage and (for usdMax) have a price-table entry; subscription drivers (Claude CLI) report no tokens and are skipped (fail-open with a one-time warning).",
       "properties": {
         "tokensMax": {
           "type": "number",
+          "exclusiveMinimum": 0,
           "description": "Cumulative input + output tokens allowed across the whole run"
         },
+        "usdMax": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Cumulative USD allowed across the whole run, priced from token usage via the model price table. Unpriced models / subscription drivers fail open (never halt on them)."
+        },
+        "estimateUnmeasured": {
+          "type": "boolean",
+          "description": "OPT-IN (default false). Estimate the notional list-price USD an unmeasured/subscription call would have cost and surface a ≈$ figure. Label only — never counted toward usdMax, never halts. Requires usdMax."
+        },
         "onBreach": {
           "type": "string",
           "enum": [
             "halt",
             "warn"
           ],
-          "description": "halt (default): stop run on next admission check. warn: continue but record the breach in the run log.",
+          "description": "halt (default): stop run on next admission check. warn: continue but record the breach in the run log. Applies to both tokensMax and usdMax.",
           "default": "halt"
         }
       }

package/dist/server.d.ts

@@ -12,6 +12,21 @@ interface ServerEvents {
 }
 import { corsOrigin } from "./cors.js";
 export { corsOrigin };
+/**
+ * H6 (audit 2026-06-19): the webhook auth gate must treat the
+ * `X-Hub-Signature-256` header identically at the bearer-bypass decision
+ * and at the HMAC verification step. A multi-valued header (duplicate
+ * lines collapsed to a `string[]` by an upstream proxy / HTTP-2 layer, or
+ * Node's comma-join) is NOT a usable single signature and must be rejected,
+ * never silently skipped. This returns the lone string only when exactly
+ * one usable value is present; otherwise `null`.
+ *
+ * - `undefined`        → null (absent)
+ * - single string      → that string
+ * - comma-joined string (Node merge of duplicates) → null (multi-valued)
+ * - `string[]`         → null (multi-valued)
+ */
+export declare function readSingleSignatureHeader(value: string | string[] | undefined): string | null;
 export interface SessionSummary {
     id: string;
     connectedAt: string;
@@ -183,6 +198,42 @@ export declare class Server extends EventEmitter<ServerEvents> {
     }) => import("./recipes/judgeSummary.js").JudgeSummary) | null;
     /** Patchwork: set by bridge to generate a dry-run plan for a recipe by name. */
     runPlanFn: ((recipeName: string) => Promise<Record<string, unknown>>) | null;
+    /** Patchwork: set by bridge to generate a What-If Preview simulation for a
+     *  recipe by name (static counterfactual; superset of the dry-run plan). */
+    simulateFn: ((recipeName: string) => Promise<Record<string, unknown>>) | null;
+    /** Patchwork: read-only worker trust dial (shadow) — replays run + decision
+     *  logs through the (worker × action-class) ramp. Backs GET /workers/shadow. */
+    workerShadowFn: (() => Promise<Record<string, unknown>>) | null;
+    /** Patchwork: read-only query over the persisted Decision Record
+     *  (worker_gate_decisions.jsonl). Backs GET /gate/decisions and the
+     *  `patchwork gate explain` CLI command — "why did the worker
+     *  allow/gate THIS action" without grepping the JSONL by hand. */
+    gateDecisionsFn: ((opts?: {
+        workerId?: string;
+        classKey?: string;
+        limit?: number;
+    }) => import("./workerGateDecisionLog.js").GateDecisionRecord[]) | null;
+    /** Patchwork: record a Decision Record trace over HTTP. Backs
+     *  POST /traces/decision — the HTTP twin of the `ctxSaveTrace` MCP tool,
+     *  wired directly to `DecisionTraceLog.record()` so both paths persist
+     *  through the same JSONL writer. Throws on invalid input (caller maps
+     *  to 400); null when no bridge-side DecisionTraceLog is configured. */
+    saveDecisionTraceFn: ((input: {
+        ref: string;
+        problem: string;
+        solution: string;
+        workspace?: string;
+        tags?: string[];
+        sessionId?: string;
+        source?: string;
+    }) => import("./decisionTraceLog.js").DecisionTrace) | null;
+    /** Patchwork: operator outcome dispositions (~/.patchwork/outcome-log.jsonl).
+     *  Backs GET/POST /outcomes and the dashboard confirm/reject panel; mirrors
+     *  the `patchwork outcomes` CLI. Never exposed as a recipe step / MCP tool. */
+    outcomeStoreFn: (() => import("./workers/outcomeStore.js").OutcomeStore) | null;
+    /** Patchwork: the confirm queue — worker filings awaiting an operator
+     *  disposition. Backs GET /outcomes/pending + `patchwork outcomes pending`. */
+    pendingConfirmationsFn: (() => import("./workers/runWorkerShadow.js").PendingConfirmation[]) | null;
     /** Patchwork (VD-4): mocked replay of an existing run. Returns the new
      *  run's seq plus any unmocked steps the caller may want to surface. */
     runReplayFn: ((seq: number) => Promise<{
@@ -361,12 +412,21 @@ export declare class Server extends EventEmitter<ServerEvents> {
         tag?: string;
         since?: number;
         limit?: number;
+        semantic?: boolean;
     }) => Promise<Record<string, unknown>>) | null;
     /** Set by bridge to handle CC hook notify events via POST /notify */
     notifyFn: ((event: string, args: Record<string, string>) => {
         ok: boolean;
         error?: string;
     }) | null;
+    /**
+     * Patchwork: the configured workspace root (set by bridge from --workspace).
+     * Routes that resolve workspace-relative state — decision-replay and CC
+     * permission attribution, approval routing — must use this, NOT process.cwd():
+     * the bridge can be started with --workspace pointing elsewhere, and a
+     * launchd/systemd cwd is unrelated to the workspace (audit 2026-06-08 server-3).
+     */
+    workspace: string;
     /** Patchwork: set by bridge to list active agent sessions for the dashboard. */
     sessionsFn: (() => SessionSummary[]) | null;
     /** Patchwork: set by bridge to answer GET /sessions/:id with per-session event stream + approvals. */