@sweny-ai/core 0.1.163 → 0.1.165

package/dist/journal.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Run journal (#363): an append-only log of one workflow run, enough to resume
+ * a killed or failed run without re-running the nodes that already finished.
+ *
+ * File: `.sweny/runs/<run-id>/journal.ndjson`, one JSON record per line. Every
+ * record carries the format version (`v`), a sequence number (`seq`) and a
+ * checksum (`h`, sha256 of the record without `h`). Each append is written and
+ * fsync'd before the executor moves on, so a record on disk is a fact.
+ *
+ * Records, in run order:
+ *   run:start        workflow / instruction / input / tool hashes, harness id, input (redacted)
+ *   run:resume       one per `sweny workflow resume`
+ *   node:start       a node visit began (node + iteration)
+ *   node:checkpoint  the agent finished a node with outputs, its result and
+ *                    write intents, written before the write stage runs
+ *   output:intent    a write is about to be applied (idempotency key + tool)
+ *   output:applied   the write returned (key + the ids it produced)
+ *   node:end         final result of the visit and the write-stage counters
+ *   route            the edge taken after the visit (null = the run ended)
+ *   run:end          success | failed | crashed
+ *
+ * Recovery: a torn or corrupt tail (power loss mid-append) is truncated back to
+ * the last valid record. Corruption in the middle of the file is refused.
+ *
+ * Privacy: the journal is local and holds what the run needs to continue (node
+ * data, eval verdicts, safe-output intents). It never holds environment values:
+ * secret-looking keys, known token shapes, and the values of secret env vars
+ * and skill credentials are replaced with `[redacted]` before anything is
+ * written. Tool call inputs and outputs are not journaled.
+ *
+ * Writes: the write stage's skill handlers are wrapped. Each write gets an
+ * idempotency key (node, iteration, tool, canonical arguments), an
+ * `output:intent` before the call and an `output:applied` after it. On resume a
+ * key with a receipt is not re-applied, and a key with an intent but no receipt
+ * (the process died between the API call and the receipt) is looked up on the
+ * provider by a marker embedded in the body before anything is re-sent.
+ */
+import type { Logger, NodeResult, Skill, Workflow } from "./types.js";
+import type { SafeOutputIntent, WriteStageState } from "./safe-outputs.js";
+export declare const JOURNAL_SCHEMA_VERSION = 1;
+export declare const JOURNAL_DIR: string;
+export declare const JOURNAL_FILE = "journal.ndjson";
+/** Journals kept on disk; the oldest beyond this are deleted when a new run starts. */
+export declare const JOURNAL_KEEP = 20;
+export declare const REDACTED = "[redacted]";
+/** sha256 (hex) of `value` as canonical JSON: keys sorted, undefined dropped. Same as run history's workflow hash. */
+export declare function canonicalHash(value: unknown): string;
+/**
+ * Hash of the workflow a journal is bound to: the canonical workflow plus its
+ * effective `spec_version` (#469), so a file that only changes spec version
+ * (and therefore migrations) is a different workflow for resume.
+ */
+export declare function workflowHashOf(workflow: Workflow): string;
+/** Hash of what the nodes were told: every resolved instruction, rule and context Source. */
+export declare function instructionHash(sources: Record<string, {
+    content: string;
+}>): string;
+/** Hash of the tools the run could call: skill ids, tool names and access, MCP presence, sweny version. */
+export declare function toolsHash(skills: Map<string, Skill>, swenyVersion?: string, harnessId?: string): string;
+/** True for keys like `GITHUB_TOKEN`, `apiKey`, `client-secret`, `Authorization`. */
+export declare function isSecretKey(key: string): boolean;
+/** Values of secret-named env vars / config entries, longest first (8+ chars, so short words never match). */
+export declare function collectSecretValues(...maps: Array<Record<string, string | undefined> | undefined>): string[];
+/**
+ * Deep copy of `value` with secrets replaced by `[redacted]`: string values
+ * under secret-looking keys, known token shapes, and any occurrence of a value
+ * in `secrets`. Numbers and booleans are kept (`inputTokens` is a count).
+ */
+export declare function redact(value: unknown, secrets?: string[]): {
+    value: unknown;
+    redacted: boolean;
+};
+export interface JournalRecord {
+    v: number;
+    seq: number;
+    type: string;
+    at: string;
+    [field: string]: unknown;
+}
+export interface RunStartRecord extends JournalRecord {
+    type: "run:start";
+    run_id: string;
+    workflow_id: string;
+    workflow_entry: string;
+    workflow_file?: string;
+    workflow_hash: string;
+    instruction_hash: string;
+    input_hash: string;
+    tools_hash: string;
+    harness?: {
+        id: string;
+    };
+    sweny_version?: string;
+    input: unknown;
+    input_redacted: boolean;
+}
+export interface WriteStateSnapshot {
+    counts: Array<[string, number]>;
+    total: number;
+    seen: string[];
+}
+interface CheckpointRecord extends JournalRecord {
+    node: string;
+    iteration: number;
+    result: NodeResult;
+    intents: SafeOutputIntent[];
+    agent_failed: boolean;
+    attempt: number;
+}
+interface EndRecord extends JournalRecord {
+    node: string;
+    iteration: number;
+    result: NodeResult;
+    write_state: WriteStateSnapshot;
+}
+interface OutputRecord extends JournalRecord {
+    node: string;
+    iteration: number;
+    key: string;
+    tool: string;
+    output?: unknown;
+    recovered?: boolean;
+}
+/** Thrown when the journal was written by a newer sweny. */
+export declare class JournalVersionError extends Error {
+    constructor(version: unknown);
+}
+/** Thrown at resume when what the run depends on changed since it was journaled (and `force` is off). */
+export declare class JournalMismatchError extends Error {
+    readonly what: string[];
+    constructor(what: string[]);
+}
+/** Thrown when another live process holds the run's journal. */
+export declare class JournalLockedError extends Error {
+    constructor(pid: number);
+}
+export interface JournalRead {
+    file: string;
+    records: JournalRecord[];
+    /** Bytes dropped from a torn / corrupt tail (0 when the file was clean). */
+    truncatedBytes: number;
+    /** Set when an invalid record sits before valid ones: not a torn tail, so not repairable. */
+    corruptAtLine?: number;
+}
+/**
+ * Read a journal. With `repair`, a torn or corrupt tail is truncated on disk
+ * back to the last valid record. Throws {@link JournalVersionError} for a
+ * newer format.
+ */
+export declare function readJournal(file: string, opts?: {
+    repair?: boolean;
+}): JournalRead;
+export type VisitAction = "replay" | "write-stage" | "rerun";
+export interface PlannedVisit {
+    node: string;
+    iteration: number;
+    action: VisitAction;
+    /** Final status in the journal, for replayed visits. */
+    status?: NodeResult["status"];
+    /** Route taken after the visit: a node id, null for run end, undefined when not journaled. */
+    next?: string | null;
+    /** Writes the checkpointed write stage already applied (receipts in the journal). */
+    applied: number;
+    /** Writes with an intent but no receipt: checked on the provider before anything is re-sent. */
+    unconfirmed: number;
+}
+export interface ResumePlan {
+    runId: string;
+    start: RunStartRecord;
+    /** 1 for the first run, +1 per resume so far. */
+    attempts: number;
+    /** Last `run:end` status, if the journal has one. */
+    lastStatus?: string;
+    visits: PlannedVisit[];
+    /** Node the resumed run continues at, if it was routed to but never started. */
+    freshNode?: string;
+    /** Every journaled visit is complete and the last route ended the run. */
+    finished: boolean;
+    /** Write-stage counters after the last replayed visit. */
+    writeState?: WriteStateSnapshot;
+    checkpoints: Map<string, CheckpointRecord>;
+    ends: Map<string, EndRecord>;
+    intents: Map<string, OutputRecord>;
+    receipts: Map<string, OutputRecord>;
+}
+/** Work out what a resume replays and where it picks up. */
+export declare function buildResumePlan(records: JournalRecord[]): ResumePlan;
+/**
+ * Nodes a resume would run again that may repeat a write outside safe outputs:
+ * the visit had started, was not read-only (no `permissions: read`, no
+ * `outputs`, not a dry run), and has no checkpoint. Its agent could have
+ * called a write tool, pushed, or edited files before the crash.
+ */
+export declare function mayRepeatWrites(plan: ResumePlan, workflow: Workflow, input: unknown): string[];
+/** Short, single-token marker the provider's search can find. */
+export declare function markerToken(key: string): string;
+/** What the executor tells the journal once sources are resolved. */
+export interface JournalBeginInfo {
+    workflow: Workflow;
+    input: unknown;
+    sources: Record<string, {
+        content: string;
+    }>;
+    skills: Map<string, Skill>;
+    config: Record<string, string>;
+    writeState: WriteStageState;
+    harnessId?: string;
+}
+export interface JournalCheckpoint {
+    result: NodeResult;
+    intents: SafeOutputIntent[];
+    agentRunFailed: boolean;
+    attempt: number;
+}
+export type JournalReplay = {
+    kind: "complete";
+    result: NodeResult;
+    next?: string | null;
+} | ({
+    kind: "checkpoint";
+} & JournalCheckpoint);
+/**
+ * The executor's view of a journal (`ExecuteOptions.journal`). Every hook is
+ * best effort except at resume, where `begin` refuses a changed run.
+ */
+export interface ExecutionJournal {
+    begin(info: JournalBeginInfo): void;
+    /** A visit an earlier attempt finished (or checkpointed); undefined = run it. */
+    replay(node: string, iteration: number): JournalReplay | undefined;
+    nodeStart(node: string, iteration: number): void;
+    checkpoint(node: string, iteration: number, cp: JournalCheckpoint): void;
+    /** The skill map the write stage applies through: write tools journaled and made idempotent. */
+    wrapWrites(node: string, iteration: number, skills: Map<string, Skill>): Map<string, Skill>;
+    nodeEnd(node: string, iteration: number, result: NodeResult, writeState: WriteStageState): void;
+    route(from: string, to: string | null): void;
+}
+/** Test seam: called before each append; a throw simulates the process dying there. */
+export interface JournalFaults {
+    beforeAppend?(record: JournalRecord): void;
+}
+export interface RunJournalOptions {
+    runId: string;
+    /** Base directory; the journal goes in `<cwd>/.sweny/runs/<run-id>/`. Default: process.cwd(). */
+    cwd?: string;
+    /** Workflow file the run came from, so `resume` can load it again. */
+    workflowFile?: string;
+    swenyVersion?: string;
+    /** Environment whose secret-named values are redacted. Never written. */
+    env?: Record<string, string | undefined>;
+    logger?: Logger;
+    faults?: JournalFaults;
+    /** Journals kept on disk (default {@link JOURNAL_KEEP}). */
+    keep?: number;
+}
+export interface ResumeJournalOptions extends RunJournalOptions {
+    read: JournalRead;
+    plan: ResumePlan;
+    /** Resume even though the workflow, instructions, input or tools changed. */
+    force?: boolean;
+    /** Re-send writes whose outcome cannot be confirmed on the provider. */
+    allowRepeatWrites?: boolean;
+}
+export declare function journalDir(cwd: string, runId: string): string;
+/** Run ids with a journal on disk, oldest first. */
+export declare function listJournalRuns(cwd?: string): string[];
+/** Exact run id, or a unique prefix. */
+export declare function findJournalRun(ref: string, cwd?: string): string | undefined;
+/** Delete the oldest journals beyond `keep`, never `except`. Never throws. */
+export declare function pruneJournals(cwd: string, keep?: number, except?: string): number;
+export declare class RunJournal implements ExecutionJournal {
+    readonly runId: string;
+    readonly dir: string;
+    readonly file: string;
+    private readonly cwd;
+    private readonly opts;
+    private readonly logger;
+    private readonly resume?;
+    private fd;
+    private seq;
+    private dead;
+    private began;
+    private secrets;
+    private consumed;
+    private constructor();
+    /** A journal for a new run. Nothing touches disk until the executor calls `begin`. */
+    static create(opts: RunJournalOptions): RunJournal;
+    /** A journal that continues `opts.read` (already repaired) under the resume plan. */
+    static openForResume(opts: ResumeJournalOptions): RunJournal;
+    /** False once an append failed: the rest of the run is not journaled. */
+    get active(): boolean;
+    private takeLock;
+    private releaseLock;
+    private append;
+    private closeFd;
+    private clean;
+    begin(info: JournalBeginInfo): void;
+    replay(node: string, iteration: number): JournalReplay | undefined;
+    nodeStart(node: string, iteration: number): void;
+    checkpoint(node: string, iteration: number, cp: JournalCheckpoint): void;
+    nodeEnd(node: string, iteration: number, result: NodeResult, writeState: WriteStageState): void;
+    route(from: string, to: string | null): void;
+    /** Close the run: `run:end`, then release the lock. Safe to call twice. */
+    end(status: "success" | "failed" | "crashed"): void;
+    wrapWrites(node: string, iteration: number, skills: Map<string, Skill>): Map<string, Skill>;
+    private wrapTool;
+}
+export {};