@sweny-ai/core 0.1.172 → 0.1.173

package/dist/journal.d.ts

@@ -2,10 +2,23 @@
  * 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.
+ * File: `.sweny/runs/<run-id>/journal.ndjson` (mode 0600), one JSON record per
+ * line. Every record carries the format version (`v`), a sequence number (`seq`)
+ * and an authentication code (`h`, HMAC-SHA256 of the record without `h`, under
+ * a per-run key). Each append is written and fsync'd before the executor moves
+ * on, so a record on disk is a fact.
+ *
+ * Integrity: the key is 32 random bytes made when the run starts and kept
+ * OUTSIDE the workspace, in the user's sweny state dir
+ * (`$SWENY_STATE_DIR`, else `$XDG_STATE_HOME/sweny`, else
+ * `~/.local/state/sweny`), under `run-keys/` (dir 0700, file 0600). Anything
+ * that can write the workspace but not that dir (an agent confined to the
+ * workspace, a checked-out branch, an artifact) cannot mint a record resume
+ * accepts. Both sandboxes deny reading the key dir; an unsandboxed agent
+ * running as the same OS user can still read it, which is why resume also
+ * checks the record sequence (see {@link buildResumePlan}) and every replayed
+ * route against the workflow's real edges. A resume on another machine needs
+ * the same state dir.
  *
  * Records, in run order:
  *   run:start        workflow / instruction / input / tool hashes, harness id, input (redacted)
@@ -17,8 +30,12 @@
  *   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)
+ *   usage            spend of one agent attempt (cumulative; live while it runs, final when it returns)
  *   run:end          success | failed | crashed
  *
+ * Spend: a resume seeds the run budget with every attempt's journaled usage,
+ * so a crash never resets the whole-run ceiling.
+ *
  * 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.
  *
@@ -35,9 +52,11 @@
  * (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 { Logger, NodeResult, NodeUsage, Skill, Workflow } from "./types.js";
 import type { SafeOutputIntent, WriteStageState } from "./safe-outputs.js";
-export declare const JOURNAL_SCHEMA_VERSION = 1;
+import { type Spend } from "./budget.js";
+/** v2: records are authenticated with a per-run HMAC key (v1 used a public checksum and is refused). */
+export declare const JOURNAL_SCHEMA_VERSION = 2;
 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. */
@@ -55,12 +74,39 @@ export declare function workflowHashOf(workflow: Workflow): string;
 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;
+/**
+ * Fingerprint of everything that decides what the run's tools do: per skill its
+ * id, name, description, category, instruction, config field names and env var
+ * NAMES, every tool's name, description, input schema, access class and a
+ * digest of its handler source, the MCP server's type, command, args, url,
+ * env var NAMES and header NAMES, and its tool aliases; plus the sweny version
+ * (which pins built-in skill code) and the harness. Secret values never enter
+ * it: MCP env and header values are dropped, and args are redacted first, so
+ * rotating a token neither changes the fingerprint nor leaves a hash of it.
+ */
+export declare function toolsHash(skills: Map<string, Skill>, swenyVersion?: string, harnessId?: string, secrets?: string[]): string;
+/** sweny's per-user state dir: `$SWENY_STATE_DIR`, else `$XDG_STATE_HOME/sweny`, else `~/.local/state/sweny`. */
+export declare function swenyStateDir(env?: Record<string, string | undefined>): string;
+/** Where run keys live. Never inside the workspace. */
+export declare function runKeyDir(env?: Record<string, string | undefined>): string;
+/** The key file for one run in one workspace (the workspace path is hashed, not stored). */
+export declare function runKeyFile(cwd: string, runId: string, keyDir?: string): string;
+/** Thrown when a journal's key is missing or unreadable: its records cannot be checked. */
+export declare class JournalKeyError extends Error {
+    constructor(file: string, why: string);
+}
+/** Read a run key. Throws {@link JournalKeyError}. */
+export declare function loadRunKey(file: string): Buffer;
 /** 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[];
+/**
+ * The secret values a run can see: secret-named env vars, plus skill config
+ * fields (resolved from their env vars) whose config key looks secret. The
+ * same set the journal redacts, for anything else that prints node output.
+ */
+export declare function runSecretValues(skills: Iterable<Skill> | undefined, env?: Record<string, string | 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
@@ -121,10 +167,14 @@ interface OutputRecord extends JournalRecord {
     output?: unknown;
     recovered?: boolean;
 }
-/** Thrown when the journal was written by a newer sweny. */
+/** Thrown when the journal was written by a newer sweny, or by an older one without record authentication. */
 export declare class JournalVersionError extends Error {
     constructor(version: unknown);
 }
+/** Thrown when the journal's records describe something the executor never writes: edited, spliced or forged. */
+export declare class JournalIntegrityError extends Error {
+    constructor(message: string);
+}
 /** 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[];
@@ -139,16 +189,25 @@ export interface JournalRead {
     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. */
+    /**
+     * Set when an invalid record sits before valid ones (not a torn tail), or when
+     * a whole record fails authentication (tampering, never a torn write). Not repairable.
+     */
     corruptAtLine?: number;
+    /** The line whose record failed authentication, when that is why the journal is refused. */
+    forgedAtLine?: 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.
+ * Read a journal. With `repair`, a torn tail is truncated on disk back to the
+ * last valid record. Records are authenticated with the run's key (`key`, else
+ * loaded from the state dir for the run the path names). Throws
+ * {@link JournalVersionError} for another format and {@link JournalKeyError}
+ * when the key is missing.
  */
 export declare function readJournal(file: string, opts?: {
     repair?: boolean;
+    key?: Buffer;
+    keyDir?: string;
 }): JournalRead;
 export type VisitAction = "replay" | "write-stage" | "rerun";
 export interface PlannedVisit {
@@ -182,8 +241,25 @@ export interface ResumePlan {
     ends: Map<string, EndRecord>;
     intents: Map<string, OutputRecord>;
     receipts: Map<string, OutputRecord>;
+    /** Spend every earlier attempt journaled: the run budget starts here on resume. */
+    priorSpend: Spend;
 }
-/** Work out what a resume replays and where it picks up. */
+/**
+ * Check that the records are a sequence the executor can write: one run:start
+ * first; nothing but run:resume after run:end; a visit starts only where the
+ * last route pointed (or the entry), or re-starts an unfinished or failed
+ * visit after a resume; checkpoints, writes, usage and node:end only inside
+ * the open visit; one route per finished visit, from that visit's node.
+ * Throws {@link JournalIntegrityError}.
+ */
+export declare function checkRecordSequence(records: JournalRecord[]): void;
+/**
+ * Check a journal against the workflow it is resumed with: every visited node
+ * exists, and every journaled route is a real edge that its `max_iterations`
+ * still allowed. Returns the first problem, or undefined.
+ */
+export declare function checkJournalAgainstWorkflow(records: JournalRecord[], workflow: Workflow): string | undefined;
+/** Work out what a resume replays and where it picks up. Throws {@link JournalIntegrityError} for an impossible sequence. */
 export declare function buildResumePlan(records: JournalRecord[]): ResumePlan;
 /**
  * Nodes a resume would run again that may repeat a write outside safe outputs:
@@ -233,7 +309,16 @@ export interface ExecutionJournal {
     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;
+    /**
+     * Spend of one agent attempt, cumulative for the attempt: `final` when the
+     * attempt returned, otherwise a live report (the journal may throttle those).
+     */
+    usage?(node: string, iteration: number, attempt: number, usage: NodeUsage, final: boolean): void;
+    /** Spend earlier attempts of this run already journaled (resume); the run budget starts from it. */
+    priorSpend?(): Spend | undefined;
 }
+/** Minimum gap between two live usage records of one attempt. Final reports are always written. */
+export declare const USAGE_JOURNAL_INTERVAL_MS = 2000;
 /** Test seam: called before each append; a throw simulates the process dying there. */
 export interface JournalFaults {
     beforeAppend?(record: JournalRecord): void;
@@ -251,6 +336,8 @@ export interface RunJournalOptions {
     faults?: JournalFaults;
     /** Journals kept on disk (default {@link JOURNAL_KEEP}). */
     keep?: number;
+    /** Where run keys live (default {@link runKeyDir}). Never inside the workspace. */
+    keyDir?: string;
 }
 export interface ResumeJournalOptions extends RunJournalOptions {
     read: JournalRead;
@@ -265,8 +352,8 @@ export declare function journalDir(cwd: string, runId: string): string;
 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;
+/** Delete the oldest journals (and their keys) beyond `keep`, never `except`. Never throws. */
+export declare function pruneJournals(cwd: string, keep?: number, except?: string, keyDir?: string): number;
 export declare class RunJournal implements ExecutionJournal {
     readonly runId: string;
     readonly dir: string;
@@ -279,8 +366,14 @@ export declare class RunJournal implements ExecutionJournal {
     private seq;
     private dead;
     private began;
+    private closed;
     private secrets;
     private consumed;
+    /** Per-run HMAC key; lives only here and in the key file outside the workspace. */
+    private key;
+    private readonly keyFile;
+    /** Last live usage record per attempt: time and spend, for throttling. */
+    private lastUsage;
     private constructor();
     /** A journal for a new run. Nothing touches disk until the executor calls `begin`. */
     static create(opts: RunJournalOptions): RunJournal;
@@ -289,6 +382,8 @@ export declare class RunJournal implements ExecutionJournal {
     /** False once an append failed: the rest of the run is not journaled. */
     get active(): boolean;
     private takeLock;
+    /** The run dir is private (0700); its parents are created as usual. */
+    private makeDir;
     private releaseLock;
     private append;
     private closeFd;
@@ -299,7 +394,9 @@ export declare class RunJournal implements ExecutionJournal {
     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. */
+    usage(node: string, iteration: number, attempt: number, usage: NodeUsage, final: boolean): void;
+    priorSpend(): Spend | undefined;
+    /** Close the run: `run:end`, then release the lock. Safe to call twice (one run:end). */
     end(status: "success" | "failed" | "crashed"): void;
     wrapWrites(node: string, iteration: number, skills: Map<string, Skill>): Map<string, Skill>;
     private wrapTool;