patchwork-os 0.2.0-beta.2 → 0.2.0-beta.3

package/dist/recipes/githubInstallSource.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Parses + allowlists the `github:<owner>/<repo>/(recipes|bundles)/<name>`
+ * source format used by `POST /recipes/install`.
+ *
+ * Before this module existed, the install handler hard-coded
+ * `github:patchworkos/recipes/...` everywhere — every URL, every
+ * prefix match. Third-party orgs / forks / private mirrors could not
+ * host recipe catalogs even though the rest of the install pipeline
+ * (SSRF guard, parser, scheduler) is org-agnostic.
+ *
+ * Allowlist policy:
+ *   - Always includes `patchworkos/recipes` (backward compat).
+ *   - Operator opts in additional `<owner>/<repo>` entries via the
+ *     `PATCHWORK_RECIPE_REPO_ALLOWLIST` env var (comma-separated).
+ *   - Allowlist matching is case-insensitive (GitHub itself is).
+ *   - Both owner and repo segments must match the strict regex
+ *     `[a-z0-9_.-]{1,100}` AFTER lowercasing — guards against
+ *     traversal segments smuggled into the source string.
+ *
+ * The default-only behaviour matches the audit recommendation: real
+ * multi-org support is opt-in, so existing single-org deployments
+ * don't see a behaviour change.
+ */
+export type GithubInstallKind = "recipe" | "bundle";
+export interface ParsedGithubInstallSource {
+    kind: GithubInstallKind;
+    owner: string;
+    repo: string;
+    /** Recipe name (single basename) or bundle name. */
+    name: string;
+}
+export type GithubInstallParseResult = {
+    ok: true;
+    parsed: ParsedGithubInstallSource;
+} | {
+    ok: false;
+    code: "bad_shape" | "bad_segment" | "not_allowlisted";
+    error: string;
+};
+/**
+ * Read the runtime allowlist. Combines the always-on default with
+ * whatever the operator has set in PATCHWORK_RECIPE_REPO_ALLOWLIST.
+ * Entries are lowercased + de-duplicated; trailing whitespace, empty
+ * fragments, and shapes that don't look like `owner/repo` are
+ * silently dropped (logging here is the install handler's job, not
+ * this pure helper's).
+ */
+export declare function loadAllowlist(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Parse a `github:owner/repo/(recipes|bundles)/name` source string
+ * against the active allowlist. Pure — does NOT fetch anything; the
+ * install handler is responsible for the network leg and the SSRF
+ * guard. Returns a discriminated union the caller can map to a 400
+ * (bad_shape / bad_segment) or 403 (not_allowlisted) response.
+ */
+export declare function parseGithubInstallSource(source: string, allowlist?: ReadonlyArray<string>): GithubInstallParseResult;
+/**
+ * Build the raw.githubusercontent URL for a parsed install source.
+ * Always pulls `main` branch HEAD — version pinning is on the
+ * deferred audit backlog.
+ */
+export declare function buildGithubRawUrl(parsed: ParsedGithubInstallSource): string;

package/dist/recipes/githubInstallSource.js

@@ -0,0 +1,125 @@
+/**
+ * Parses + allowlists the `github:<owner>/<repo>/(recipes|bundles)/<name>`
+ * source format used by `POST /recipes/install`.
+ *
+ * Before this module existed, the install handler hard-coded
+ * `github:patchworkos/recipes/...` everywhere — every URL, every
+ * prefix match. Third-party orgs / forks / private mirrors could not
+ * host recipe catalogs even though the rest of the install pipeline
+ * (SSRF guard, parser, scheduler) is org-agnostic.
+ *
+ * Allowlist policy:
+ *   - Always includes `patchworkos/recipes` (backward compat).
+ *   - Operator opts in additional `<owner>/<repo>` entries via the
+ *     `PATCHWORK_RECIPE_REPO_ALLOWLIST` env var (comma-separated).
+ *   - Allowlist matching is case-insensitive (GitHub itself is).
+ *   - Both owner and repo segments must match the strict regex
+ *     `[a-z0-9_.-]{1,100}` AFTER lowercasing — guards against
+ *     traversal segments smuggled into the source string.
+ *
+ * The default-only behaviour matches the audit recommendation: real
+ * multi-org support is opt-in, so existing single-org deployments
+ * don't see a behaviour change.
+ */
+const DEFAULT_ALLOWLIST = ["patchworkos/recipes"];
+const SEGMENT_RE = /^[a-z0-9_.-]{1,100}$/;
+/**
+ * Read the runtime allowlist. Combines the always-on default with
+ * whatever the operator has set in PATCHWORK_RECIPE_REPO_ALLOWLIST.
+ * Entries are lowercased + de-duplicated; trailing whitespace, empty
+ * fragments, and shapes that don't look like `owner/repo` are
+ * silently dropped (logging here is the install handler's job, not
+ * this pure helper's).
+ */
+export function loadAllowlist(env = process.env) {
+    const fromEnv = (env.PATCHWORK_RECIPE_REPO_ALLOWLIST ?? "")
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0 && s.includes("/"));
+    return Array.from(new Set([...DEFAULT_ALLOWLIST, ...fromEnv]));
+}
+/**
+ * Parse a `github:owner/repo/(recipes|bundles)/name` source string
+ * against the active allowlist. Pure — does NOT fetch anything; the
+ * install handler is responsible for the network leg and the SSRF
+ * guard. Returns a discriminated union the caller can map to a 400
+ * (bad_shape / bad_segment) or 403 (not_allowlisted) response.
+ */
+export function parseGithubInstallSource(source, allowlist = loadAllowlist()) {
+    if (!source.startsWith("github:")) {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "source must start with 'github:'",
+        };
+    }
+    // After the `github:` prefix we expect <owner>/<repo>/<kind>/<name>.
+    // We split into exactly 4 segments — extra trailing slashes or
+    // missing components are rejected with `bad_shape` so the response
+    // is actionable.
+    const tail = source.slice("github:".length);
+    const segments = tail.split("/");
+    if (segments.length !== 4) {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "source must match 'github:<owner>/<repo>/(recipes|bundles)/<name>'",
+        };
+    }
+    const [ownerRaw, repoRaw, kindRaw, nameRaw] = segments;
+    const owner = ownerRaw.toLowerCase();
+    const repo = repoRaw.toLowerCase();
+    if (!SEGMENT_RE.test(owner) || !SEGMENT_RE.test(repo)) {
+        return {
+            ok: false,
+            code: "bad_segment",
+            error: "owner and repo must match [a-z0-9_.-]{1,100}",
+        };
+    }
+    if (kindRaw !== "recipes" && kindRaw !== "bundles") {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "third path segment must be 'recipes' or 'bundles'",
+        };
+    }
+    // Reuse the strict basename predicate inline rather than importing
+    // recipeInstall.ts here (circular deps), but match its rules:
+    // single segment, no `..`, no slashes, conservative charset, ≤100.
+    if (!SEGMENT_RE.test(nameRaw.toLowerCase())) {
+        return {
+            ok: false,
+            code: "bad_segment",
+            error: "name must match [a-z0-9_.-]{1,100}",
+        };
+    }
+    const allowSet = new Set(allowlist.map((s) => s.toLowerCase()));
+    if (!allowSet.has(`${owner}/${repo}`)) {
+        return {
+            ok: false,
+            code: "not_allowlisted",
+            error: `'${owner}/${repo}' is not in the recipe-repo allowlist. Set PATCHWORK_RECIPE_REPO_ALLOWLIST=${owner}/${repo} to opt in.`,
+        };
+    }
+    return {
+        ok: true,
+        parsed: {
+            kind: kindRaw === "recipes" ? "recipe" : "bundle",
+            owner,
+            repo,
+            name: nameRaw,
+        },
+    };
+}
+/**
+ * Build the raw.githubusercontent URL for a parsed install source.
+ * Always pulls `main` branch HEAD — version pinning is on the
+ * deferred audit backlog.
+ */
+export function buildGithubRawUrl(parsed) {
+    if (parsed.kind === "recipe") {
+        return `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/main/recipes/${parsed.name}/${parsed.name}.yaml`;
+    }
+    return `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/main/bundles/${parsed.name}/patchwork-bundle.json`;
+}
+//# sourceMappingURL=githubInstallSource.js.map

package/dist/recipes/githubInstallSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"githubInstallSource.js","sourceRoot":"","sources":["../../src/recipes/githubInstallSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAoBH,MAAM,iBAAiB,GAA0B,CAAC,qBAAqB,CAAC,CAAC;AACzE,MAAM,UAAU,GAAG,sBAAsB,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,+BAA+B,IAAI,EAAE,CAAC;SACxD,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,iBAAiB,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAc,EACd,YAAmC,aAAa,EAAE;IAElD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,kCAAkC;SAC1C,CAAC;IACJ,CAAC;IACD,qEAAqE;IACrE,+DAA+D;IAC/D,mEAAmE;IACnE,iBAAiB;IACjB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,WAAW;YACjB,KAAK,EACH,oEAAoE;SACvE,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,QAK7C,CAAC;IACF,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE,8CAA8C;SACtD,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACnD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,mDAAmD;SAC3D,CAAC;IACJ,CAAC;IACD,mEAAmE;IACnE,8DAA8D;IAC9D,mEAAmE;IACnE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QAC5C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE,oCAAoC;SAC5C,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAChE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;QACtC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,iBAAiB;YACvB,KAAK,EAAE,IAAI,KAAK,IAAI,IAAI,8EAA8E,KAAK,IAAI,IAAI,aAAa;SACjI,CAAC;IACJ,CAAC;IACD,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;YACjD,KAAK;YACL,IAAI;YACJ,IAAI,EAAE,OAAO;SACd;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAiC;IACjE,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,qCAAqC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,iBAAiB,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,OAAO,CAAC;IAC5H,CAAC;IACD,OAAO,qCAAqC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,iBAAiB,MAAM,CAAC,IAAI,wBAAwB,CAAC;AAC9H,CAAC"}

package/dist/recipes/haltCategory.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Halt-category derivation.
+ *
+ * PR1c of the Val-inspired plan. PR1 attached a `haltReason` sentence to
+ * every error-status StepResult; this module categorises those sentences
+ * into a small bounded enum so the dashboard / metrics layer can count
+ * them over time. Foundation for "is the haltReason work actually
+ * surfacing useful signal, or is everything landing in `unknown`?"
+ *
+ * The mapping is intentionally pattern-based against the 5 phrases
+ * emitted by yamlRunner.ts. Keep this file and those phrases in sync.
+ * When a new error site is added, add a category here AND a test.
+ */
+export type HaltCategory = "agent_silent_fail" | "agent_narration_only" | "agent_threw" | "tool_threw" | "tool_error"
+/** Write blocked by the global kill-switch (#422). Distinct from a real tool failure. */
+ | "kill_switch"
+/** Recipe's `tokensMax` budget breached (PR2b). */
+ | "budget_exceeded"
+/** Whole-recipe failure (e.g. circular dependencies) — has no step row. */
+ | "run_level" | "unknown";
+export declare function categoriseHaltReason(reason: string | undefined): HaltCategory;
+export interface HaltSummary {
+    /** Total error-status step results scanned. */
+    total: number;
+    /** Per-category counts; categories with zero hits are omitted. */
+    byCategory: Partial<Record<HaltCategory, number>>;
+    /** Most recent 5 halt reasons (verbatim) for surfacing in the UI. */
+    recent: Array<{
+        reason: string;
+        category: HaltCategory;
+        runSeq: number;
+    }>;
+}
+interface HaltSummaryInputRun {
+    seq: number;
+    /** Top-level run status — `run_level` halts are runs with status === "error" but no error stepResults (e.g. circular-dep failure before any step ran). */
+    status?: "running" | "done" | "error" | "cancelled" | "interrupted";
+    /** Top-level errorMessage — surfaced as a `run_level` halt when no per-step halts cover it. */
+    errorMessage?: string;
+    stepResults?: Array<{
+        status: "ok" | "skipped" | "error";
+        haltReason?: string;
+    }>;
+}
+/**
+ * Aggregate halt categories across a set of runs. Runs are expected to be
+ * sorted newest-first so `recent` reflects the most recent halts.
+ *
+ * A run contributes:
+ * - one entry per error-status stepResult that has a `haltReason`
+ * - plus one `run_level` entry if `status === "error"` and there were no
+ *   per-step halts that already explained it (avoids double-counting).
+ */
+export declare function summariseHalts(runs: HaltSummaryInputRun[]): HaltSummary;
+/**
+ * Format a `HaltSummary` as Prometheus text-exposition lines for the
+ * `bridge_recipe_halts{category="..."} N` gauge. Returns an empty array
+ * when the summary is empty (no HELP/TYPE block emitted in that case so
+ * Prom scrapers don't see an orphan declaration).
+ *
+ * Surfaced via `/metrics` so users with their own observability stack
+ * can dashboard halts without using Patchwork's UI.
+ */
+export declare function haltSummaryToPrometheus(summary: HaltSummary): string[];
+/**
+ * Derive a one-sentence haltReason from a step's error-status + raw error
+ * string. Used by `chainedRunner` to mirror the convention emitted by
+ * `yamlRunner`. Returns `undefined` for non-error rows or missing error.
+ *
+ * Pattern-matches the same phrases `categoriseHaltReason` knows about,
+ * so chained-run haltReasons categorise into the same buckets.
+ */
+export declare function deriveHaltReasonFromError(opts: {
+    stepId: string;
+    toolName?: string;
+    isAgent?: boolean;
+    status: "ok" | "skipped" | "error";
+    error?: string;
+}): string | undefined;
+export {};

package/dist/recipes/haltCategory.js

@@ -0,0 +1,125 @@
+/**
+ * Halt-category derivation.
+ *
+ * PR1c of the Val-inspired plan. PR1 attached a `haltReason` sentence to
+ * every error-status StepResult; this module categorises those sentences
+ * into a small bounded enum so the dashboard / metrics layer can count
+ * them over time. Foundation for "is the haltReason work actually
+ * surfacing useful signal, or is everything landing in `unknown`?"
+ *
+ * The mapping is intentionally pattern-based against the 5 phrases
+ * emitted by yamlRunner.ts. Keep this file and those phrases in sync.
+ * When a new error site is added, add a category here AND a test.
+ */
+export function categoriseHaltReason(reason) {
+    if (!reason)
+        return "unknown";
+    // Order matters: more specific phrases (silent-fail, narration, kill
+    // switch) must match before the general "Agent step ... threw" /
+    // "Tool ... threw" patterns. The phrases below mirror
+    // yamlRunner.ts:558-606,677-684,693-708 and
+    // featureFlags.ts:assertWriteAllowed.
+    if (/silent-fail/i.test(reason))
+        return "agent_silent_fail";
+    if (/narration|whitespace|no content/i.test(reason))
+        return "agent_narration_only";
+    if (/kill[- _]?switch/i.test(reason))
+        return "kill_switch";
+    if (/budget[_ ]?exceeded|exceeded its token budget/i.test(reason))
+        return "budget_exceeded";
+    if (/^Agent step .* threw/i.test(reason))
+        return "agent_threw";
+    if (/^Tool .* threw/i.test(reason))
+        return "tool_threw";
+    if (/^Tool .* reported an error/i.test(reason))
+        return "tool_error";
+    return "unknown";
+}
+/**
+ * Aggregate halt categories across a set of runs. Runs are expected to be
+ * sorted newest-first so `recent` reflects the most recent halts.
+ *
+ * A run contributes:
+ * - one entry per error-status stepResult that has a `haltReason`
+ * - plus one `run_level` entry if `status === "error"` and there were no
+ *   per-step halts that already explained it (avoids double-counting).
+ */
+export function summariseHalts(runs) {
+    const byCategory = {};
+    const recent = [];
+    let total = 0;
+    for (const run of runs) {
+        let stepHaltsForRun = 0;
+        for (const step of run.stepResults ?? []) {
+            if (step.status !== "error" || !step.haltReason)
+                continue;
+            stepHaltsForRun++;
+            total++;
+            const cat = categoriseHaltReason(step.haltReason);
+            byCategory[cat] = (byCategory[cat] ?? 0) + 1;
+            if (recent.length < 5) {
+                recent.push({
+                    reason: step.haltReason,
+                    category: cat,
+                    runSeq: run.seq,
+                });
+            }
+        }
+        if (stepHaltsForRun === 0 && run.status === "error" && run.errorMessage) {
+            total++;
+            byCategory.run_level = (byCategory.run_level ?? 0) + 1;
+            if (recent.length < 5) {
+                recent.push({
+                    reason: run.errorMessage,
+                    category: "run_level",
+                    runSeq: run.seq,
+                });
+            }
+        }
+    }
+    return { total, byCategory, recent };
+}
+/**
+ * Format a `HaltSummary` as Prometheus text-exposition lines for the
+ * `bridge_recipe_halts{category="..."} N` gauge. Returns an empty array
+ * when the summary is empty (no HELP/TYPE block emitted in that case so
+ * Prom scrapers don't see an orphan declaration).
+ *
+ * Surfaced via `/metrics` so users with their own observability stack
+ * can dashboard halts without using Patchwork's UI.
+ */
+export function haltSummaryToPrometheus(summary) {
+    if (summary.total === 0)
+        return [];
+    const lines = [
+        "# HELP bridge_recipe_halts Recipe halts in the in-memory run-log window, by category",
+        "# TYPE bridge_recipe_halts gauge",
+    ];
+    for (const [category, count] of Object.entries(summary.byCategory)) {
+        lines.push(`bridge_recipe_halts{category="${category}"} ${count}`);
+    }
+    return lines;
+}
+/**
+ * Derive a one-sentence haltReason from a step's error-status + raw error
+ * string. Used by `chainedRunner` to mirror the convention emitted by
+ * `yamlRunner`. Returns `undefined` for non-error rows or missing error.
+ *
+ * Pattern-matches the same phrases `categoriseHaltReason` knows about,
+ * so chained-run haltReasons categorise into the same buckets.
+ */
+export function deriveHaltReasonFromError(opts) {
+    if (opts.status !== "error" || !opts.error)
+        return undefined;
+    if (/silent-fail/i.test(opts.error)) {
+        return `Step "${opts.stepId}" returned no usable output (silent-fail).`;
+    }
+    if (/narration|whitespace|no content/i.test(opts.error)) {
+        return `Step "${opts.stepId}" returned only narration or whitespace — no content.`;
+    }
+    if (opts.isAgent) {
+        return `Agent step "${opts.stepId}" threw before completing: ${opts.error}`;
+    }
+    return `Tool "${opts.toolName ?? "?"}" in step "${opts.stepId}" reported an error: ${opts.error}`;
+}
+//# sourceMappingURL=haltCategory.js.map

package/dist/recipes/haltCategory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"haltCategory.js","sourceRoot":"","sources":["../../src/recipes/haltCategory.ts"],"names":[],"mappings":"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"}

package/dist/recipes/idempotencyKey.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Idempotency keys for write-tool calls.
+ *
+ * PR5a of the Val-inspired plan. Foundation for safe retry + safe resume.
+ *
+ * Two pieces:
+ *
+ *   `deriveIdempotencyKey(toolId, params)`
+ *     A stable, deterministic hash over `(toolId, canonicalised params)`.
+ *     Canonicalisation = JSON.stringify with sorted keys, recursive — so
+ *     `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` hash identically. Returns a
+ *     hex SHA-256 prefix (first 16 chars; collisions vanishingly small
+ *     within a single run scope).
+ *
+ *   `WriteEffectLedger`
+ *     Per-run in-memory map of key → cached output. The runner constructs
+ *     one per recipe run and threads it through `StepDeps` / `ToolContext`.
+ *     `toolRegistry.executeTool` checks the ledger before invoking write
+ *     tools; if the key is present, returns the cached output instead of
+ *     re-executing — preventing duplicate side effects when two parallel
+ *     branches of a chained recipe both call the same write tool with the
+ *     same params.
+ *
+ * Scope of this PR (deliberately narrow):
+ *   - In-run dedup only (Map lives for one recipe run, discarded after).
+ *   - Records only on successful execution; errors don't pollute the
+ *     ledger, so retry-after-failure still re-executes (correct: if the
+ *     tool errored, we can't assume the side effect happened).
+ *   - No cross-run persistence — that's PR5b (disk-backed effect ledger).
+ *   - No retry-time idempotency on partial-failure cases (Slack posted
+ *     but HTTP timed out); that needs tool-side support and is a future
+ *     PR.
+ *
+ * The protection this DOES provide today: a `parallel:` block (or a
+ * recipe that calls a write tool from two different chained steps with
+ * identical params) cannot duplicate the side effect. Concretely, this
+ * was a footgun that pre-dated PR5a: `chainedRunner.ts` schedules steps
+ * with dependency-graph parallelism; if two branches happen to call
+ * `slack.postMessage` with the same payload, the message went twice.
+ */
+import type { Logger } from "../logger.js";
+/**
+ * Derive a stable idempotency key for a write-tool invocation. 16 hex
+ * chars is 64 bits of entropy — far more than enough for in-run dedup
+ * (a single recipe with even 10⁵ steps has ~5×10⁻¹⁰ collision risk).
+ */
+export declare function deriveIdempotencyKey(toolId: string, params: Record<string, unknown>): string;
+/**
+ * Compose a collision-safe scope key from `(recipeName, manualRunId)`.
+ *
+ * Naive `${recipeName}:${manualRunId}` is ambiguous: recipe `a:b` +
+ * attempt `c` and recipe `a` + attempt `b:c` both produce `a:b:c` and
+ * would share a ledger scope, letting one attempt read another's
+ * cached write-tool outputs. We hash both fields separately as a JSON
+ * array so the encoding is unambiguous regardless of either field's
+ * contents.
+ *
+ * Returned as a 32-hex-char SHA-256 prefix — long enough that
+ * collisions across a realistic ledger are effectively impossible
+ * (~2^128 birthday bound), short enough to scan in a JSONL row.
+ */
+export declare function deriveScopeKey(recipeName: string, manualRunId: string): string;
+export declare function assertValidManualRunId(id: string): string;
+/**
+ * In-memory per-run ledger of executed write-tool calls. Maps idempotency
+ * keys to the cached output the tool returned, so a duplicate call can
+ * be short-circuited to the same result the first call produced.
+ *
+ * The ledger is single-threaded by design — runners are single-process
+ * and a per-run ledger has no cross-thread access. Concurrency safety
+ * within a run is provided by the dependency graph (parallel-only steps
+ * with no shared params hash by construction); the ledger catches
+ * accidental same-params calls.
+ */
+/**
+ * Optional disk-backed persistence for the ledger.
+ *
+ * PR5b — extends in-memory dedup so a *retry* of the same logical
+ * `(recipeName, manualRunId)` attempt won't replay side effects. The
+ * ledger stays per-attempt; cron/webhook runs and recipes without a
+ * manualRunId stay purely in memory (no scope key = nothing to write).
+ *
+ * File layout: a single JSONL at `${dir}/effect_ledger.jsonl`. Each row
+ * is `{scopeKey, idemKey, output, recordedAt}`. On construction, the
+ * ledger streams the file and rehydrates entries whose `scopeKey`
+ * matches the configured scope; everything else is left alone for the
+ * other attempts' ledgers to pick up.
+ *
+ * Failure mode: any IO error falls back to in-memory operation and logs
+ * a warning. A partially-replayed attempt with an unreadable ledger
+ * degrades to "re-execute side effects" — louder than "silently dedup
+ * something we can't audit".
+ */
+export interface DiskLedgerOptions {
+    /** Directory holding `effect_ledger.jsonl`. Created if missing. */
+    dir: string;
+    /** `${recipeName}:${manualRunId}` — composed by the caller. */
+    scopeKey: string;
+    logger?: Logger;
+}
+export declare class WriteEffectLedger {
+    private readonly cache;
+    private readonly disk;
+    private readonly file;
+    constructor(disk?: DiskLedgerOptions);
+    has(key: string): boolean;
+    /**
+     * Return the previously-cached output for `key`, or `undefined` if not
+     * recorded. `null` is a legitimate cached value (= the tool returned
+     * `null` originally), so callers must use `has()` to distinguish "not
+     * present" from "present and null".
+     */
+    get(key: string): string | null | undefined;
+    record(key: string, output: string | null): void;
+    /** Test-only inspection of the current key set. */
+    keys(): string[];
+    size(): number;
+    private loadExisting;
+    private append;
+    /**
+     * Trim `effect_ledger.jsonl` to the most recent MAX_PERSIST_LINES.
+     * Best-effort — failure logs and the next append proceeds against the
+     * un-rotated file. Same pattern as RecipeRunLog / DecisionTraceLog.
+     */
+    private rotate;
+}