patchwork-os 0.2.0-beta.0 → 0.2.0-beta.10

package/dist/recipes/yamlRunner.d.ts

@@ -14,13 +14,20 @@
  *   file.read     — read file into `into` variable (optional: true ok)
  *   git.log_since — run git log --oneline --since=<since> (injected for tests)
  *   git.stale_branches — list branches with no activity in N days
- *   diagnostics.get — stub: returns empty string (bridge not required)
+ *   diagnostics.get — returns the bridge's LSP diagnostics; in CLI runs
+ *                     (no bridge available) returns a JSON {ok:false,error}
+ *                     payload that the step-error detector flags so the
+ *                     recipe halts rather than silently succeeding.
  *
  * Supported trigger types (for `patchwork recipe run`):
  *   manual, cron — both run immediately via CLI
  *   git_hook, on_file_save — also runnable manually; trigger context injected
  */
+import path from "node:path";
 import type { RecipeRunLog } from "../runLog.js";
+import { type AgentResult } from "./agentExecutor.js";
+import { type HaltCategory } from "./haltCategory.js";
+import { WriteEffectLedger } from "./idempotencyKey.js";
 import type { ErrorPolicy } from "./schema.js";
 import "./tools/index.js";
 export interface YamlStep {
@@ -30,6 +37,32 @@ export interface YamlStep {
         model?: string;
         into?: string;
         driver?: string;
+        /**
+         * Opt-in: inject bridge MCP tools (getAnalyticsReport, ctxQueryTraces, etc.)
+         * into the spawned `claude -p` subprocess via `--mcp-config`. Default off.
+         * Only honored by the subprocess driver path. Recursion risk: the subprocess
+         * could itself call `runClaudeTask` and chain into another bridge spawn —
+         * keep this off unless the prompt is read-only (telemetry summaries,
+         * trace queries, etc.).
+         */
+        mcpAccess?: boolean;
+        /**
+         * PR3a — judge step (cold-eyes review). When `kind: "judge"` the
+         * runner appends a structured-verdict instruction to the prompt and
+         * parses the model's response into a `JudgeVerdict`
+         * (approve / request_changes / unparseable). The verdict is
+         * attached to the step result but **never gates the run** — judge
+         * steps always finish with `status: "ok"` regardless of the
+         * verdict. This is the augment-only invariant: judges add signal,
+         * they don't block.
+         *
+         * Pair with `reviews: <stepId>` to point the judge at the output
+         * of a prior step; the runner injects that step's `output` into
+         * the prompt under an `<artefact>` section.
+         */
+        kind?: "agent" | "judge";
+        /** Step id whose output the judge should review. Required when `kind: "judge"`. */
+        reviews?: string;
     };
     into?: string;
     optional?: boolean;
@@ -46,8 +79,48 @@ export interface YamlStep {
      * legitimately returns one of those shapes as a successful result.
      */
     silentFailDetection?: boolean;
+    /**
+     * Per-step assertion block (agentic-workflow slice 2). Evaluated against
+     * the step's output value AFTER `transform` is applied and BEFORE `into`
+     * commits to ctx — so a failed expect halts the run with the offending
+     * value still visible in the step result, but never propagates a bad
+     * value downstream. `on_fail: judge` is intentionally NOT supported in
+     * v1 — synthesizing a judge to gate a step would violate the
+     * augment-only invariant in judgeVerdict.ts.
+     */
+    expect?: StepExpect;
+    /**
+     * Per-step wall-clock timeout in milliseconds. When set, the step's
+     * `executeStep` call is wrapped in `Promise.race` against a timer; if
+     * the timer wins the step halts with category `step_timeout`. Note:
+     * the underlying tool is NOT aborted — it continues running to
+     * completion in the background. This is a halt signal, not a process
+     * kill; pair with `optional: true` / `on_error.fallback` for fail-open
+     * behavior. Agent steps are not currently subject to this timeout.
+     */
+    timeout_ms?: number;
     [key: string]: unknown;
 }
+/**
+ * Per-step assertion block. Exactly one of `schema|equals|matches|contains`
+ * should be set in v1; multiple set are AND-composed (all must pass).
+ */
+export interface StepExpect {
+    /** JSON Schema validated via AJV. Step output is JSON.parse'd first; non-JSON output fails with `expect_failed: not JSON`. */
+    schema?: object;
+    /** Deep-equal comparison. Strings compared verbatim; objects/arrays compared via JSON canonical form. */
+    equals?: unknown;
+    /** Regex (string source, no flags) matched against the stringified output. */
+    matches?: string;
+    /** Substring(s) that must appear in the stringified output. Array → all must be present. */
+    contains?: string | string[];
+    /**
+     * What to do when an assertion fails. `halt` (default) flips the step to
+     * status:error with haltReason `expect_failed: ...`. `warn` keeps status
+     * but attaches the failure list to `stepResult.expectWarnings`.
+     */
+    on_fail?: "halt" | "warn";
+}
 export interface YamlTrigger {
     type: string;
     at?: string;
@@ -68,6 +141,15 @@ export interface AssertionFailure {
     message: string;
 }
 export declare function evaluateExpect(result: Pick<RunResult, "stepsRun" | "outputs" | "context" | "errorMessage">, expect: YamlRecipeExpect): AssertionFailure[];
+/**
+ * Evaluate a per-step `expect` block against the step's output value.
+ * Returns the list of failure messages (empty = all assertions passed).
+ *
+ * Slice 2 of the agentic-workflow primitives. v1 supports
+ * schema/equals/matches/contains; `on_fail: judge` deliberately omitted —
+ * see comment on `StepExpect`.
+ */
+export declare function evaluateStepExpect(expect: StepExpect, value: unknown): Promise<string[]>;
 export interface YamlRecipe {
     name: string;
     description?: string;
@@ -79,7 +161,15 @@ export interface YamlRecipe {
     };
     /** Plugin specs (npm package name or local path) to load before running steps. */
     servers?: string[];
+    /**
+     * Acknowledge write-tool steps so preflight does not flag them. Each entry
+     * is a tool id (e.g. "file.write") or a namespace (e.g. "slack"). Merged
+     * with any --allow-write CLI flags at preflight time.
+     */
+    allowWrites?: string[];
     on_error?: ErrorPolicy;
+    /** PR2b — per-recipe token budget (see `BudgetPolicy` in schema.ts). */
+    budget?: import("./schema.js").BudgetPolicy;
 }
 export type RunContext = Record<string, string>;
 export type FetchFn = (url: string, init?: {
@@ -118,24 +208,55 @@ export interface RunnerDeps {
      * (they fall back to constructing a local log + `appendDirect`).
      */
     runLog?: RecipeRunLog;
-    /** Optional Anthropic API caller for agent steps. Defaults to fetch-based impl. */
-    claudeFn?: (prompt: string, model: string) => Promise<string>;
+    /**
+     * Live-tail broadcaster for recipe + step lifecycle events. When
+     * supplied, the runner emits `recipe_started`, `recipe_step_start`,
+     * `recipe_step_done`, and `recipe_done` lifecycle events to the
+     * activity log, which the bridge proxies to dashboard SSE
+     * subscribers via /stream. Previously only `chainedRunner` emitted
+     * step events; flat YAML recipes (the common case) ran silent.
+     * Pass `bridge.activityLog`.
+     */
+    activityLog?: import("../activityLog.js").ActivityLog;
+    /**
+     * Optional Anthropic API caller for agent steps. Defaults to fetch-based
+     * impl. May return either a raw string (legacy / tests) or `AgentResult`
+     * carrying usage tokens (bridge wrappers, real adapters). The runner
+     * normalises at the executor boundary — see PR2a.
+     */
+    claudeFn?: (prompt: string, model: string) => Promise<string | AgentResult>;
     /** Optional Claude Code CLI caller for agent steps with driver: claude-code. */
-    claudeCodeFn?: (prompt: string) => Promise<string>;
+    claudeCodeFn?: (prompt: string, opts?: {
+        mcpAccess?: boolean;
+    }) => Promise<string | AgentResult>;
     /** Optional local LLM caller (Ollama / LM Studio) for agent steps with driver: local or model: local. */
-    localFn?: (prompt: string, model: string) => Promise<string>;
+    localFn?: (prompt: string, model: string) => Promise<string | AgentResult>;
     /**
      * Optional provider driver invoker for agent steps with driver: openai|grok|gemini.
      * Dispatches to src/drivers/* under the hood. If not provided, the runner will
      * lazily construct a driver via createDriver() from drivers/index.js.
      */
-    providerDriverFn?: (driverName: "openai" | "grok" | "gemini", prompt: string, model: string | undefined) => Promise<string>;
+    providerDriverFn?: (driverName: "openai" | "grok" | "gemini", prompt: string, model: string | undefined) => Promise<string | AgentResult>;
     /** Mock connector replays used by `patchwork recipe test`. */
     mockConnectors?: Partial<Record<string, MockToolConnector>>;
     /** Directory to store recorded connector fixtures for `patchwork recipe record`. */
     recordFixturesDir?: string;
     /** Suppress run logs / notifications for mocked recipe test execution. */
     testMode?: boolean;
+    /**
+     * PR5b — when set, write-effect dedup persists to
+     * `${ledgerDir}/effect_ledger.jsonl` and is rehydrated on construction
+     * for the scope `${recipe.name}:${manualRunId}`. Requires `manualRunId`
+     * to actually go to disk; without it the ledger stays in-memory.
+     */
+    ledgerDir?: string;
+    /**
+     * PR5b — stable id for one *logical* user-initiated execution attempt.
+     * Composed with `recipe.name` into the disk-ledger scope key so a
+     * retry of the same attempt re-uses prior dedup records (resume
+     * semantics). Caller-supplied; left unset for cron / webhook runs.
+     */
+    manualRunId?: string;
 }
 export interface RunResult {
     recipe: string;
@@ -151,6 +272,13 @@ export type StepResult = {
     tool?: string;
     status: "ok" | "skipped" | "error";
     error?: string;
+    /**
+     * PR3a — judge-step verdict, present only when `step.agent.kind ===
+     * "judge"`. Augment-only: a `request_changes` verdict still
+     * produces `status: "ok"`. Surfaced separately in dashboard panels
+     * and `bridge_recipe_judgments` metrics (forthcoming PR3b/c).
+     */
+    judgeVerdict?: import("./judgeVerdict.js").JudgeVerdict;
     /**
      * Structured error code propagated from a thrown step error. Currently
      * populated for `recipe_path_jail_escape` (G-security A-PR1) so tests
@@ -158,15 +286,58 @@ export type StepResult = {
      * (R2 M-4). Other codes may follow.
      */
     errorCode?: string;
+    /**
+     * One-sentence, human-actionable halt reason — what stopped the step and
+     * why, phrased so a tired human at 7am can act on it without reading the
+     * raw `error` stack/message. Populated only for `status: "error"` rows.
+     * Categories: agent silent-fail, agent narration-only, agent threw, tool
+     * threw, tool reported error. Foundation for the inbox morning-summary
+     * (Val "halt cleanly with reason" idea, refined per plan review).
+     */
+    haltReason?: string;
+    /**
+     * Pre-tagged category for this halt — set at the throw site so
+     * `summariseHalts` / the emit path don't need to re-derive it via
+     * free-text regex. Falls back to `categoriseHaltReason(haltReason)`
+     * when absent (e.g. legacy persisted run-log rows).
+     */
+    haltCategory?: HaltCategory;
+    /**
+     * Slice 2 — per-step `expect` block warnings when `on_fail: warn` is set.
+     * Each entry is a one-line failure message (assertion that did not pass).
+     * Populated only when the step's status remains `ok` despite an expect
+     * mismatch. For `on_fail: halt` the failures are folded into `haltReason`
+     * instead and this stays undefined.
+     */
+    expectWarnings?: string[];
     durationMs: number;
 };
-export type StepDeps = Required<Omit<RunnerDeps, "now" | "logDir" | "recordFixturesDir" | "runLog">> & {
+export type StepDeps = Required<Omit<RunnerDeps, "now" | "logDir" | "recordFixturesDir" | "runLog" | "ledgerDir" | "manualRunId" | "activityLog">> & {
     workdir: string;
     logDir?: string;
     recordFixturesDir?: string;
     runLog?: RecipeRunLog;
     testMode: boolean;
+    /**
+     * PR5a — per-run idempotency ledger. When present, `executeTool`
+     * short-circuits duplicate write-tool calls (same toolId + params)
+     * within the run, returning the cached output instead of re-invoking
+     * the tool. Constructed at run start in `runYamlRecipe` /
+     * `runChainedRecipe`; discarded when the run completes.
+     */
+    writeEffectLedger?: WriteEffectLedger;
 };
+/**
+ * Phase 0β — separator-agnostic inbox-path detector. Extracted so the
+ * Windows path-separator behaviour can be unit-tested by injecting
+ * `path.win32` / `path.posix` without booting a real recipe runner.
+ *
+ * Returns true when `candidate` resolves to a direct child of
+ * `inboxDirAbs`, isn't a dotfile, and lives in (not above) the inbox
+ * dir. Both arguments must already be platform-appropriate absolute
+ * paths (resolve them with the same path module before calling).
+ */
+export declare function isInboxPathFor(candidate: string, inboxDirAbs: string, pathMod: typeof path): boolean;
 export declare function loadYamlRecipe(filePath: string): YamlRecipe;
 export declare function validateYamlRecipe(raw: unknown): YamlRecipe;
 /**
@@ -180,6 +351,20 @@ export declare function executeStep(step: YamlStep, ctx: RunContext, deps: StepD
 export declare function render(template: string, ctx: RunContext): string;
 export declare function defaultGitLogSince(since: string, workdir?: string): string;
 export declare function defaultGitStaleBranches(days: number, workdir?: string): string;
+/**
+ * Resolve the `claude` binary path with override precedence:
+ *   1. PATCHWORK_CLAUDE_BINARY env var (set by the bridge LaunchAgent
+ *      or any wrapper script)
+ *   2. `~/.patchwork/config.json` `claudeBinary` field
+ *   3. plain `"claude"` (PATH lookup — pre-existing default)
+ *
+ * Resolved per-call, not memoised, so config edits + env-var changes
+ * take effect on the next agent step without a bridge restart.
+ */
+export declare function resolveClaudeBinary(): string;
+export declare function defaultClaudeCodeFn(prompt: string, opts?: {
+    mcpAccess?: boolean;
+}): Promise<string>;
 /**
  * Build ExecutionDeps for ChainedRecipeRunner backed by the yamlRunner step
  * handlers. This lets chained recipes use the same tool set (file.*, git.*,
@@ -188,7 +373,9 @@ export declare function defaultGitStaleBranches(days: number, workdir?: string):
  * Pass the result as `chainedDeps` when calling `dispatchRecipe` or
  * `runChainedRecipe` so that `executeTool` is properly wired.
  */
-export declare function buildChainedDeps(runnerDeps: RunnerDeps, claudeCodeFnOverride?: (prompt: string) => Promise<string>): import("./chainedRunner.js").ExecutionDeps;
+export declare function buildChainedDeps(runnerDeps: RunnerDeps, claudeCodeFnOverride?: (prompt: string, opts?: {
+    mcpAccess?: boolean;
+}) => Promise<string | AgentResult>): import("./chainedRunner.js").ExecutionDeps;
 /**
  * Dispatch a loaded recipe to the appropriate runner.
  *