patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.95

package/dist/recipes/githubInstallSource.js

@@ -0,0 +1,206 @@
+/**
+ * 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"];
+export 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,
+        },
+    };
+}
+/**
+ * The repo-relative path of the file for a parsed install source.
+ * `recipes/<name>/<name>.yaml` or `bundles/<name>/patchwork-bundle.json`.
+ */
+function repoRelativePath(parsed) {
+    if (parsed.kind === "recipe") {
+        return `recipes/${parsed.name}/${parsed.name}.yaml`;
+    }
+    return `bundles/${parsed.name}/patchwork-bundle.json`;
+}
+/**
+ * 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) {
+    return `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/main/${repoRelativePath(parsed)}`;
+}
+/**
+ * Build the `api.github.com` Contents-API URL for a parsed install
+ * source. Used as a FALLBACK when `raw.githubusercontent.com` is
+ * unreachable — many corporate / proxied networks block the raw host
+ * even when `api.github.com` is allowed. Combined with the
+ * `Accept: application/vnd.github.raw` request header (see
+ * `fetchGithubInstallFile`), this endpoint returns the raw file bytes
+ * directly — no base64 decode needed. Public repos work unauthenticated.
+ */
+export function buildGithubApiUrl(parsed) {
+    return `https://api.github.com/repos/${parsed.owner}/${parsed.repo}/contents/${repoRelativePath(parsed)}?ref=main`;
+}
+export async function fetchGithubInstallFile(parsed, init = {}) {
+    const rawUrl = buildGithubRawUrl(parsed);
+    let rawResponse = null;
+    let rawNetworkError = null;
+    try {
+        rawResponse = await fetch(rawUrl, {
+            signal: init.signal,
+            redirect: "follow",
+        });
+    }
+    catch (err) {
+        rawNetworkError = err;
+    }
+    // Fast path: raw host returned a usable response.
+    if (rawResponse?.ok) {
+        return { ok: true, response: rawResponse };
+    }
+    // Raw host either threw OR returned non-ok → try the API fallback.
+    const apiUrl = buildGithubApiUrl(parsed);
+    let apiResponse = null;
+    let apiNetworkError = null;
+    try {
+        apiResponse = await fetch(apiUrl, {
+            signal: init.signal,
+            redirect: "follow",
+            headers: { Accept: "application/vnd.github.raw" },
+        });
+    }
+    catch (err) {
+        apiNetworkError = err;
+    }
+    if (apiResponse?.ok) {
+        return { ok: true, response: apiResponse };
+    }
+    // Neither host yielded an ok body. Decide which failure to surface.
+    //
+    // A non-404 HTTP failure (5xx / 403 rate-limit) is the most
+    // actionable signal — prefer it over a 404 from the other host, so a
+    // transient upstream problem isn't misreported as "recipe missing".
+    // The API response is the more authoritative of the two here (raw is
+    // a CDN; the API gives proper status codes), so check it first.
+    if (apiResponse && apiResponse.status !== 404) {
+        return { ok: false, kind: "upstream_error", response: apiResponse };
+    }
+    if (rawResponse && rawResponse.status !== 404) {
+        return { ok: false, kind: "upstream_error", response: rawResponse };
+    }
+    // Whatever is left is a genuine 404 from one or both hosts → keep
+    // the not-found distinction so the caller surfaces a 404, not a 502.
+    if (apiResponse && apiResponse.status === 404) {
+        return { ok: false, kind: "not_found", response: apiResponse };
+    }
+    if (rawResponse && rawResponse.status === 404) {
+        return { ok: false, kind: "not_found", response: rawResponse };
+    }
+    // Both hosts threw network errors.
+    return {
+        ok: false,
+        kind: "network_error",
+        error: apiNetworkError ?? rawNetworkError,
+    };
+}
+//# 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":"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"}

package/dist/recipes/haltCategory.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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"
+/** Per-step `expect` assertion failed (slice 2). */
+ | "expect_failed"
+/** Per-step wall-clock `timeout_ms` exceeded (sandbox-alternative slice). */
+ | "step_timeout"
+/**
+ * Connector returned 401/403 — token expired or scopes insufficient.
+ * Actionable: user should reconnect from /connections.
+ */
+ | "auth_failure"
+/**
+ * External service returned 429 / rate limit. Actionable: retry later
+ * or back off the cron cadence.
+ */
+ | "rate_limited"
+/**
+ * Transport failed before the request reached the service
+ * (ECONNREFUSED, ENOTFOUND, fetch failed). Distinct from a 4xx/5xx
+ * from the service itself — usually a local network / DNS issue.
+ */
+ | "network_error"
+/**
+ * Tool needed a connector that isn't configured for this workspace.
+ * Actionable: install/connect from /connections.
+ */
+ | "missing_connector"
+/** Whole-recipe failure (e.g. circular dependencies) — has no step row. */
+ | "run_level" | "unknown";
+/**
+ * Human-readable label per category. Shared by the `halts` CLI, the
+ * `recipe doctor` command, and (mirrored) the dashboard, so the wording
+ * stays consistent across surfaces.
+ */
+export declare const HALT_CATEGORY_LABELS: Record<HaltCategory, string>;
+/**
+ * Actionable one-liner per category — "what to do about it". Shared by
+ * the `halts` CLI and `recipe doctor` so SSH / mobile users get the fix
+ * hint without opening the dashboard.
+ */
+export declare const HALT_CATEGORY_HINTS: Record<HaltCategory, string>;
+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;
+        /** Pre-tagged category from yamlRunner throw site — avoids regex re-derivation when present. */
+        haltCategory?: HaltCategory;
+    }>;
+}
+/**
+ * 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,188 @@
+/**
+ * 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.
+ */
+/**
+ * Human-readable label per category. Shared by the `halts` CLI, the
+ * `recipe doctor` command, and (mirrored) the dashboard, so the wording
+ * stays consistent across surfaces.
+ */
+export const HALT_CATEGORY_LABELS = {
+    agent_silent_fail: "agent silent-fail",
+    agent_narration_only: "agent narration-only",
+    agent_threw: "agent threw",
+    tool_threw: "tool threw",
+    tool_error: "tool error",
+    kill_switch: "kill-switch blocked",
+    budget_exceeded: "budget exceeded",
+    expect_failed: "expect failed",
+    step_timeout: "step timeout",
+    auth_failure: "auth failure",
+    rate_limited: "rate limited",
+    network_error: "network error",
+    missing_connector: "missing connector",
+    run_level: "run-level halt",
+    unknown: "uncategorised",
+};
+/**
+ * Actionable one-liner per category — "what to do about it". Shared by
+ * the `halts` CLI and `recipe doctor` so SSH / mobile users get the fix
+ * hint without opening the dashboard.
+ */
+export const HALT_CATEGORY_HINTS = {
+    agent_silent_fail: "inspect prompt + check trace",
+    agent_narration_only: "tighten prompt or add `into:` target",
+    agent_threw: "open run trace",
+    tool_threw: "check inner error in trace",
+    tool_error: "check inner error in trace",
+    kill_switch: "run `patchwork kill-switch release`",
+    budget_exceeded: "raise tokensMax or shrink prompts",
+    expect_failed: "inspect assertion vs actual output",
+    step_timeout: "bump timeout_ms or speed up step",
+    auth_failure: "reconnect from /connections",
+    rate_limited: "back off cron cadence or wait",
+    network_error: "check connectivity to upstream",
+    missing_connector: "install/connect from /connections",
+    run_level: "check recipe for circular deps / parse errors",
+    unknown: "open run trace for raw error",
+};
+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 (/^expect_failed/i.test(reason))
+        return "expect_failed";
+    // Must precede the `^Tool ... threw` matcher: timeouts surface wrapped
+    // inside the tool-threw envelope (`Tool "x" in step "y" threw: step_timeout: ...`).
+    if (/step_timeout/i.test(reason))
+        return "step_timeout";
+    // Sub-categories that peek inside the wrapped `Tool "x" threw: <inner>` /
+    // `Tool "x" reported an error: <inner>` envelope. Must precede the
+    // generic `tool_threw` / `tool_error` matchers below. Patterns are
+    // deliberately narrow — e.g. "unreachable" alone stays in `tool_error`
+    // because too many tools use it as a generic phrase.
+    if (/\b(401|403)\b|unauthori[sz]ed|forbidden|invalid[_ -]?token|token[_ -]?expired|authentication[_ -]?failed/i.test(reason))
+        return "auth_failure";
+    if (/\b429\b|rate[_ -]?limit|too many requests/i.test(reason))
+        return "rate_limited";
+    if (/ECONNREFUSED|ENOTFOUND|ECONNRESET|ETIMEDOUT|EAI_AGAIN|fetch failed|network[_ -]?error|getaddrinfo/i.test(reason))
+        return "network_error";
+    if (/connector[_ -]?not[_ -]?configured|no[_ -]?(connector[_ -]?)?token|not[_ -]?connected|missing[_ -]?connector/i.test(reason))
+        return "missing_connector";
+    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 = step.haltCategory ?? 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,134 @@
+/**
+ * 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 inFlight;
+    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;
+    /**
+     * Atomically check cache + in-flight map, then execute `fn` at most once
+     * per key. Concurrent callers with the same key share a single Promise —
+     * fixing the TOCTOU window that existed between `has()` and `record()`.
+     * Failures are not cached so retry-after-failure still re-executes.
+     */
+    getOrExecute(key: string, fn: () => Promise<string | null>): Promise<string | null>;
+    /** 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;
+}