@namzu/sdk 59.0.0 → 60.0.0

package/dist/execution/workflow/resume.js

@@ -0,0 +1,273 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+/** The key version. A change to how keys are made bumps it, so old keys simply never match. */
+const KEY_VERSION = 'k1';
+function sha256Hex(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+/** JSON with every object's keys sorted and `__proto__` dropped, so equal values give equal text. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const record = value;
+        const keys = Object.keys(record)
+            .filter((key) => key !== '__proto__' && record[key] !== undefined)
+            .sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/**
+ * The key a call is saved and looked up under: the prompt, the options that
+ * change what the agent does (schema, model, effort, agent type) and how many
+ * identical calls came before it in the same pass. Each part is length-prefixed
+ * so one cannot be read as part of another.
+ */
+export function workflowCallKey(prompt, call, ordinal) {
+    return `${KEY_VERSION}:${sha256Hex(`${workflowCallContent(prompt, call)}${ordinal}`)}`;
+}
+/**
+ * What makes two calls the same call: the prompt and the options that change
+ * the agent, in a form where key order and `undefined` do not matter. The
+ * runtime counts repeats of this text to give identical calls distinct slots,
+ * and the key hashes the same text, so the two can never disagree.
+ */
+export function workflowCallContent(prompt, call) {
+    const options = canonicalJson({
+        schema: call.schema,
+        model: call.model,
+        effort: call.effort,
+        agentType: call.agentType,
+    });
+    return `${prompt.length}:${prompt}${options.length}:${options}`;
+}
+/** The hash the first line of a run's journal chains from. It binds the file to its run id. */
+export function workflowJournalSeed(runId) {
+    return sha256Hex(`namzu-workflow-journal\0${runId}`);
+}
+/** The hash a line contributes to the next one: its exact bytes, newline included. */
+export function workflowJournalLineHash(line) {
+    return sha256Hex(`${line}\n`);
+}
+/** The line `record` is written as. With a key, a `mac` over the rest of the line is added last. */
+export function formatWorkflowJournalLine(record, seq, prev, key) {
+    const body = { seq, prev, ...record };
+    if (key === undefined)
+        return JSON.stringify(body);
+    const mac = createHmac('sha256', key).update(JSON.stringify(body)).digest('hex');
+    return JSON.stringify({ ...body, mac });
+}
+function macMatches(record, key) {
+    const { mac, ...rest } = record;
+    if (typeof mac !== 'string')
+        return false;
+    const expected = createHmac('sha256', key).update(JSON.stringify(rest)).digest();
+    const actual = Buffer.from(mac, 'hex');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+function parseLine(line) {
+    try {
+        const value = JSON.parse(line);
+        return typeof value === 'object' && value !== null && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Reads a journal's text and keeps only the records that can be trusted.
+ *
+ * Every line carries `seq` (counting trusted lines from 1) and `prev` (the hash
+ * of the line before; the first chains from a seed bound to the run id). A
+ * line that does not chain, a line that does not parse, and anything after
+ * one is dropped until a `run_started` of a resumed pass picks the chain up
+ * again at the last trusted line. A last line without its newline that is not
+ * whole JSON is a torn write and is ignored; one that is whole JSON is read
+ * like any other line. The file is never rewritten.
+ *
+ * The chain alone cannot notice an edit to the final line (nothing chains from
+ * it yet). With `key`, every line must also carry a `mac` made with that
+ * secret, which closes that gap against anyone who does not hold the key.
+ */
+export function readWorkflowJournalChecked(text, runId, options = {}) {
+    const endsWithNewline = text === '' || text.endsWith('\n');
+    const pieces = text.split('\n');
+    const fragment = endsWithNewline ? undefined : pieces.pop();
+    if (endsWithNewline)
+        pieces.pop();
+    // A last line without its newline that is whole JSON was only missing the newline: it is
+    // judged like any other line (the writer adds the newline before the next record, so the
+    // hash it contributes is the one of the line with its newline). Anything else is a torn write.
+    const wholeFragment = fragment !== undefined && fragment !== '' && parseLine(fragment) !== undefined;
+    if (wholeFragment)
+        pieces.push(fragment);
+    const tornTail = fragment !== undefined && fragment !== '' && !wholeFragment;
+    const parsed = pieces.map((line) => parseLine(line));
+    const firstRecord = parsed.find((record) => record !== undefined);
+    if (firstRecord !== undefined && typeof firstRecord.seq !== 'number') {
+        return {
+            records: [],
+            legacy: true,
+            tornTail,
+            lastSeq: 0,
+            lastHash: workflowJournalSeed(runId),
+            endsWithNewline,
+            untrusted: parsed.filter((record) => record !== undefined),
+        };
+    }
+    const records = [];
+    let lastSeq = 0;
+    let lastHash = workflowJournalSeed(runId);
+    let gapStart;
+    let gapLines = 0;
+    let gapParsed = false;
+    let brokenAt;
+    const closeGap = () => {
+        if (gapStart !== undefined && (gapLines > 1 || gapParsed))
+            brokenAt ??= gapStart;
+        gapStart = undefined;
+        gapLines = 0;
+        gapParsed = false;
+    };
+    for (let i = 0; i < pieces.length; i++) {
+        const line = pieces[i];
+        const record = parsed[i];
+        const chains = record !== undefined &&
+            record.seq === lastSeq + 1 &&
+            record.prev === lastHash &&
+            (options.key === undefined || macMatches(record, options.key));
+        const first = records.length === 0;
+        const acceptable = chains &&
+            (first
+                ? record.type === 'run_started' && record.runId === runId
+                : gapStart === undefined || record.type === 'run_started');
+        if (acceptable) {
+            closeGap();
+            records.push(record);
+            lastSeq = record.seq;
+            lastHash = workflowJournalLineHash(line);
+            continue;
+        }
+        if (gapStart === undefined)
+            gapStart = i + 1;
+        gapLines++;
+        if (record !== undefined)
+            gapParsed = true;
+    }
+    // A gap that runs to the end is a change, except a single line that does not parse
+    // (what a torn write leaves once the next pass closed it with a newline).
+    closeGap();
+    return {
+        records,
+        legacy: false,
+        tornTail,
+        ...(brokenAt !== undefined ? { brokenAt } : {}),
+        lastSeq,
+        lastHash,
+        endsWithNewline,
+        untrusted: [],
+    };
+}
+function hasResult(record) {
+    return Object.hasOwn(record, 'result') && record.result !== undefined && record.result !== null;
+}
+/**
+ * Folds a checked journal into what a resumed pass needs.
+ *
+ * The last saved result for a key wins. An agent that was asked for again
+ * after a result was saved gives that result up until it finishes again. A
+ * failed or skipped outcome removes the result and marks the key failed; an
+ * outcome the run recorded as interrupted (stopped, not failed) leaves the key
+ * as seen but unfinished. Lines marked `cached` repeat an earlier result and
+ * are skipped, and so is any agent record from a pass older than the latest
+ * `run_started`, which a slow agent of an earlier pass can still write.
+ */
+export function loadWorkflowResume(checked) {
+    const results = new Map();
+    const seen = new Set();
+    const failed = new Set();
+    const demoted = new Set();
+    const problems = [];
+    const keysByIndex = new Map();
+    let currentPass = 0;
+    let scriptSha256;
+    let previousFinish = 'unfinished';
+    for (const record of checked.records) {
+        if (record.type === 'run_started') {
+            currentPass = record.resume?.pass ?? 1;
+            scriptSha256 = record.scriptSha256;
+            previousFinish = 'unfinished';
+            keysByIndex.clear();
+            continue;
+        }
+        if (record.type === 'run_finished') {
+            previousFinish = record.status;
+            continue;
+        }
+        if (record.type !== 'agent_request' && record.type !== 'agent_outcome')
+            continue;
+        const pass = record.pass ?? 1;
+        if (pass < currentPass || record.cached === true)
+            continue;
+        if (record.type === 'agent_request') {
+            if (record.key === undefined)
+                continue;
+            keysByIndex.set(`${pass}:${record.index}`, record.key);
+            seen.add(record.key);
+            if (results.delete(record.key))
+                demoted.add(record.key);
+            continue;
+        }
+        const key = record.key ?? keysByIndex.get(`${pass}:${record.index}`);
+        if (key === undefined)
+            continue;
+        seen.add(key);
+        if (record.state === 'done' && hasResult(record)) {
+            results.set(key, {
+                value: record.result,
+                pass,
+                index: record.index,
+                ...(record.childSessionId !== undefined ? { childSessionId: record.childSessionId } : {}),
+            });
+            failed.delete(key);
+            demoted.delete(key);
+        }
+        else if (record.state === 'done' && record.unsaved === true) {
+            results.delete(key);
+            demoted.add(key);
+        }
+        else if (record.interrupted === true) {
+            // Stopped, not failed: the agent runs again and the cache stays open.
+            results.delete(key);
+        }
+        else {
+            results.delete(key);
+            demoted.delete(key);
+            failed.add(key);
+        }
+    }
+    if (checked.legacy) {
+        problems.push('This run was saved before resuming was possible, so its agents cannot be reused.');
+    }
+    if (checked.brokenAt !== undefined) {
+        problems.push(`The journal was changed or cut short at line ${checked.brokenAt}. Results after that point are not trusted and those agents will run again.`);
+    }
+    const started = checked.records.some((record) => record.type === 'run_started');
+    if (!checked.legacy && !started)
+        problems.push('The journal has no usable record of the run.');
+    return {
+        pass: currentPass + 1,
+        results,
+        seen,
+        failed,
+        demoted,
+        ...(scriptSha256 !== undefined ? { scriptSha256 } : {}),
+        previousFinish,
+        problems,
+        resumable: !checked.legacy && started,
+        ...(checked.brokenAt !== undefined ? { brokenAt: checked.brokenAt } : {}),
+    };
+}
+//# sourceMappingURL=resume.js.map

package/dist/execution/workflow/resume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.js","sourceRoot":"","sources":["../../../src/execution/workflow/resume.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAUrE,+FAA+F;AAC/F,MAAM,WAAW,GAAG,IAAI,CAAA;AAExB,SAAS,SAAS,CAAC,IAAY;IAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACvD,CAAC;AAED,qGAAqG;AACrG,SAAS,aAAa,CAAC,KAAc;IACpC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;IAC1F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACjD,MAAM,MAAM,GAAG,KAAgC,CAAA;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;aAC9B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,WAAW,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;aACjE,IAAI,EAAE,CAAA;QACR,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;IAClG,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAA;AACvC,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAc,EACd,IAA0B,EAC1B,OAAe;IAEf,OAAO,GAAG,WAAW,IAAI,SAAS,CAAC,GAAG,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,CAAA;AACvF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,IAA0B;IAC7E,MAAM,OAAO,GAAG,aAAa,CAAC;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,SAAS,EAAE,IAAI,CAAC,SAAS;KACzB,CAAC,CAAA;IACF,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,EAAE,CAAA;AAChE,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAChD,OAAO,SAAS,CAAC,2BAA2B,KAAK,EAAE,CAAC,CAAA;AACrD,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,uBAAuB,CAAC,IAAY;IACnD,OAAO,SAAS,CAAC,GAAG,IAAI,IAAI,CAAC,CAAA;AAC9B,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,yBAAyB,CACxC,MAA6B,EAC7B,GAAW,EACX,IAAY,EACZ,GAAyB;IAEzB,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAA;IACrC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAClD,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAChF,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,CAAA;AACxC,CAAC;AAED,SAAS,UAAU,CAAC,MAA+B,EAAE,GAAwB;IAC5E,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAA;IAC/B,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAA;IAChF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACtC,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;AAC9E,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC9B,IAAI,CAAC;QACJ,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAC1E,CAAC,CAAE,KAAiC;YACpC,CAAC,CAAC,SAAS,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAA;IACjB,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,0BAA0B,CACzC,IAAY,EACZ,KAAa,EACb,UAAkD,EAAE;IAEpD,MAAM,eAAe,GAAG,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC/B,MAAM,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,CAAA;IAC3D,IAAI,eAAe;QAAE,MAAM,CAAC,GAAG,EAAE,CAAA;IACjC,yFAAyF;IACzF,yFAAyF;IACzF,+FAA+F;IAC/F,MAAM,aAAa,GAClB,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAA;IAC/E,IAAI,aAAa;QAAE,MAAM,CAAC,IAAI,CAAC,QAAkB,CAAC,CAAA;IAClD,MAAM,QAAQ,GAAG,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,IAAI,CAAC,aAAa,CAAA;IAE5E,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;IACpD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAA;IACjE,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;QACtE,OAAO;YACN,OAAO,EAAE,EAAE;YACX,MAAM,EAAE,IAAI;YACZ,QAAQ;YACR,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE,mBAAmB,CAAC,KAAK,CAAC;YACpC,eAAe;YACf,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,SAAS,CAA4B;SACrF,CAAA;IACF,CAAC;IAED,MAAM,OAAO,GAAmC,EAAE,CAAA;IAClD,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,QAAQ,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAA;IACzC,IAAI,QAA4B,CAAA;IAChC,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,IAAI,SAAS,GAAG,KAAK,CAAA;IACrB,IAAI,QAA4B,CAAA;IAChC,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC3B,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,SAAS,CAAC;YAAE,QAAQ,KAAK,QAAQ,CAAA;QAChF,QAAQ,GAAG,SAAS,CAAA;QACpB,QAAQ,GAAG,CAAC,CAAA;QACZ,SAAS,GAAG,KAAK,CAAA;IAClB,CAAC,CAAA;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAW,CAAA;QAChC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;QACxB,MAAM,MAAM,GACX,MAAM,KAAK,SAAS;YACpB,MAAM,CAAC,GAAG,KAAK,OAAO,GAAG,CAAC;YAC1B,MAAM,CAAC,IAAI,KAAK,QAAQ;YACxB,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;QAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAA;QAClC,MAAM,UAAU,GACf,MAAM;YACN,CAAC,KAAK;gBACL,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,aAAa,IAAI,MAAM,CAAC,KAAK,KAAK,KAAK;gBACzD,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,CAAA;QAC5D,IAAI,UAAU,EAAE,CAAC;YAChB,QAAQ,EAAE,CAAA;YACV,OAAO,CAAC,IAAI,CAAC,MAAiD,CAAC,CAAA;YAC/D,OAAO,GAAG,MAAM,CAAC,GAAa,CAAA;YAC9B,QAAQ,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;YACxC,SAAQ;QACT,CAAC;QACD,IAAI,QAAQ,KAAK,SAAS;YAAE,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAA;QAC5C,QAAQ,EAAE,CAAA;QACV,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS,GAAG,IAAI,CAAA;IAC3C,CAAC;IACD,mFAAmF;IACnF,0EAA0E;IAC1E,QAAQ,EAAE,CAAA;IAEV,OAAO;QACN,OAAO;QACP,MAAM,EAAE,KAAK;QACb,QAAQ;QACR,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,OAAO;QACP,QAAQ;QACR,eAAe;QACf,SAAS,EAAE,EAAE;KACb,CAAA;AACF,CAAC;AAED,SAAS,SAAS,CAAC,MAAqC;IACvD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAA;AAChG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA+B;IACjE,MAAM,OAAO,GAAG,IAAI,GAAG,EAGpB,CAAA;IACH,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;IAChC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IACjC,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAA;IAC7C,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,IAAI,YAAgC,CAAA;IACpC,IAAI,cAAc,GAAwC,YAAY,CAAA;IAEtE,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACnC,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,CAAA;YACtC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;YAClC,cAAc,GAAG,YAAY,CAAA;YAC7B,WAAW,CAAC,KAAK,EAAE,CAAA;YACnB,SAAQ;QACT,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACpC,cAAc,GAAG,MAAM,CAAC,MAAM,CAAA;YAC9B,SAAQ;QACT,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe;YAAE,SAAQ;QAChF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAA;QAC7B,IAAI,IAAI,GAAG,WAAW,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI;YAAE,SAAQ;QAC1D,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACrC,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;gBAAE,SAAQ;YACtC,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;YACtD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACpB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACvD,SAAQ;QACT,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;QACpE,IAAI,GAAG,KAAK,SAAS;YAAE,SAAQ;QAC/B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,IAAI,MAAM,CAAC,KAAK,KAAK,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;gBAChB,KAAK,EAAE,MAAM,CAAC,MAAM;gBACpB,IAAI;gBACJ,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,GAAG,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzF,CAAC,CAAA;YACF,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAClB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACpB,CAAC;aAAM,IAAI,MAAM,CAAC,KAAK,KAAK,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC/D,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACnB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACjB,CAAC;aAAM,IAAI,MAAM,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;YACxC,sEAAsE;YACtE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACpB,CAAC;aAAM,CAAC;YACP,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACnB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACnB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAChB,CAAC;IACF,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB,QAAQ,CAAC,IAAI,CACZ,kFAAkF,CAClF,CAAA;IACF,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACpC,QAAQ,CAAC,IAAI,CACZ,gDAAgD,OAAO,CAAC,QAAQ,6EAA6E,CAC7I,CAAA;IACF,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,CAAA;IAC/E,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO;QAAE,QAAQ,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAA;IAE9F,OAAO;QACN,IAAI,EAAE,WAAW,GAAG,CAAC;QACrB,OAAO;QACP,IAAI;QACJ,MAAM;QACN,OAAO;QACP,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,cAAc;QACd,QAAQ;QACR,SAAS,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO;QACrC,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzE,CAAA;AACF,CAAC"}

package/dist/execution/workflow/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/execution/workflow/runtime.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,WAAW,EAAkB,MAAM,0BAA0B,CAAA;AAQtF,OAAO,KAAK,EAQX,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EAEjB,MAAM,YAAY,CAAA;AAEnB,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,UAAU,CAAA;AAoBzC,sHAAsH;AACtH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGvE;AASD,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,cAAmB,GAAG,sBAAsB,CAmCzF;AA+GD,MAAM,WAAW,sBAAsB;IACtC,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;IAClC,oCAAoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,qGAAqG;IACrG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAC/B;AAkCD;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAGf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAEL,OAAO,GAAE,sBAA2B;IAI3D,GAAG,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA6gBlE"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/execution/workflow/runtime.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,WAAW,EAAkB,MAAM,0BAA0B,CAAA;AAStF,OAAO,KAAK,EAQX,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EAEjB,MAAM,YAAY,CAAA;AAEnB,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,UAAU,CAAA;AAoBzC,sHAAsH;AACtH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGvE;AASD,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,cAAmB,GAAG,sBAAsB,CAqCzF;AAuHD,MAAM,WAAW,sBAAsB;IACtC,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;IAClC,oCAAoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,qGAAqG;IACrG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAC/B;AAkCD;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAGf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAEL,OAAO,GAAE,sBAA2B;IAI3D,GAAG,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAwnBlE"}

package/dist/execution/workflow/runtime.js

@@ -7,6 +7,7 @@ import { preview, sha256 } from './journal.js';
 import { splitWorkflowScript } from './meta.js';
 import { PhaseRegistry, summarizeWorkflowPhases } from './phases.js';
 import { buildPrelude, preludeLineCount } from './prelude.js';
+import { workflowCallContent, workflowCallKey } from './resume.js';
 import { parseJsonText, validateAgainstSchema } from './schema.js';
 /** The one capability a script has. */
 export const WORKFLOW_HOST_CALL = 'agent';
@@ -47,7 +48,9 @@ export function resolveWorkflowLimits(limits = {}) {
         memoryLimitBytes: integer('memoryLimitBytes', limits.memoryLimitBytes ?? 64 * 1024 * 1024, 16 * 1024 * 1024, 256 * 1024 * 1024),
         maxValueBytes: integer('maxValueBytes', limits.maxValueBytes ?? 1024 * 1024, 1, 16 * 1024 * 1024),
         ...(limits.tokenBudget !== undefined
-            ? { tokenBudget: integer('tokenBudget', limits.tokenBudget, 1, Number.MAX_SAFE_INTEGER) }
+            ? {
+                tokenBudget: integer('tokenBudget', limits.tokenBudget, 1, Number.MAX_SAFE_INTEGER),
+            }
             : {}),
         maxDurationMs: integer('maxDurationMs', limits.maxDurationMs ?? 6 * 3_600_000, 1, 2_147_483_647),
         cpuSliceMs: integer('cpuSliceMs', limits.cpuSliceMs ?? 2_000, 1, 2_147_483_647),
@@ -176,6 +179,10 @@ export class WorkflowRuntime {
         const now = this.now;
         const runId = options.runId ?? `w${[...randomBytes(8)].map((b) => (b % 36).toString(36)).join('')}`;
         const startedAt = now();
+        const pass = options.resume?.pass ?? 1;
+        const resume = options.resume;
+        let latch = false;
+        const seenContent = new Map();
         const phases = new PhaseRegistry();
         const agents = new Map();
         const inFlight = new Set();
@@ -232,7 +239,13 @@ export class WorkflowRuntime {
                     declared,
                     at,
                 });
-                journal({ type: 'phase', at, index: phase.index, title: phase.title, declared });
+                journal({
+                    type: 'phase',
+                    at,
+                    index: phase.index,
+                    title: phase.title,
+                    declared,
+                });
             }
             return phase;
         };
@@ -258,6 +271,7 @@ export class WorkflowRuntime {
             ...(agent.resultPreview !== undefined ? { resultPreview: agent.resultPreview } : {}),
             ...(agent.error !== undefined ? { error: agent.error } : {}),
             ...(agent.skipped ? { skipped: true } : {}),
+            ...(agent.cached !== undefined ? { cached: true } : {}),
         });
         // FIFO admission: an agent starts when fewer than maxConcurrency run.
         const acquire = (agent) => {
@@ -333,11 +347,26 @@ export class WorkflowRuntime {
                 value = null;
             }
             emit(agentEvent(agent));
+            const finalState = agent.state === 'error' ? 'error' : agent.skipped ? 'skipped' : 'done';
+            let saved;
+            if (finalState === 'done' && value !== null && agent.cached === undefined) {
+                try {
+                    saved = { result: JSON.parse(JSON.stringify(value)) };
+                }
+                catch {
+                    saved = { unsaved: true };
+                    journal({
+                        type: 'log',
+                        at,
+                        message: "An agent's result could not be saved, so a resume will run it again.",
+                    });
+                }
+            }
             journal({
                 type: 'agent_outcome',
                 at,
                 index: agent.index,
-                state: agent.state === 'error' ? 'error' : agent.skipped ? 'skipped' : 'done',
+                state: finalState,
                 tokens: agent.tokens,
                 toolCalls: agent.toolCalls,
                 queuedAt: agent.queuedAt,
@@ -345,12 +374,30 @@ export class WorkflowRuntime {
                 finishedAt: at,
                 ...(agent.resultPreview !== undefined ? { resultPreview: agent.resultPreview } : {}),
                 ...(agent.error !== undefined ? { error: agent.error } : {}),
+                ...(agent.key !== undefined ? { key: agent.key } : {}),
+                pass,
+                ...(agent.cached !== undefined
+                    ? {
+                        cached: true,
+                        resultFrom: {
+                            pass: agent.cached.pass,
+                            index: agent.cached.index,
+                        },
+                    }
+                    : {}),
+                ...(saved ?? {}),
+                ...(outcome.interrupted === true && finalState === 'error'
+                    ? { interrupted: true }
+                    : {}),
+                ...(agent.childSessionId !== undefined ? { childSessionId: agent.childSessionId } : {}),
             });
             return { ok: true, value: { v: value, t: totalTokens() } };
         };
         const interpret = (agent, call, outcome) => {
             agent.tokens = count(outcome.tokens);
             agent.toolCalls = count(outcome.toolCalls);
+            if (outcome.sessionId !== undefined)
+                agent.childSessionId = outcome.sessionId;
             if (agent.userSkipped || outcome.state === 'skipped') {
                 return settle(agent, { state: 'done', skipped: true });
             }
@@ -358,10 +405,14 @@ export class WorkflowRuntime {
                 return settle(agent, {
                     state: 'error',
                     error: 'The workflow was stopped before this agent finished.',
+                    interrupted: true,
                 });
             }
             if (outcome.state === 'error') {
-                return settle(agent, { state: 'error', error: outcome.error ?? 'The agent failed.' });
+                return settle(agent, {
+                    state: 'error',
+                    error: outcome.error ?? 'The agent failed.',
+                });
             }
             if (call.schema === undefined) {
                 return settle(agent, { state: 'done', value: outcome.text ?? '' });
@@ -396,6 +447,16 @@ export class WorkflowRuntime {
                 return { ok: false, error: reason };
             }
             const index = ++requested;
+            const contentId = workflowCallContent(call.prompt, call);
+            const ordinal = seenContent.get(contentId) ?? 0;
+            seenContent.set(contentId, ordinal + 1);
+            const key = workflowCallKey(call.prompt, call, ordinal);
+            const hit = latch ? undefined : resume?.results.get(key);
+            if (resume !== undefined &&
+                hit === undefined &&
+                !(resume.seen.has(key) && !resume.failed.has(key) && !resume.demoted.has(key))) {
+                latch = true;
+            }
             const phaseTitle = call.phase ?? call.cursor;
             const phase = phaseTitle?.trim() ? announce(phaseTitle, false) : undefined;
             const queuedAt = now();
@@ -414,13 +475,27 @@ export class WorkflowRuntime {
                 toolCalls: 0,
                 skipped: false,
                 userSkipped: false,
+                key,
             };
             agents.set(index, agent);
+            if (hit !== undefined) {
+                agent.cached = {
+                    pass: hit.pass,
+                    index: hit.index,
+                    ...(hit.childSessionId !== undefined ? { childSessionId: hit.childSessionId } : {}),
+                };
+                if (hit.childSessionId !== undefined)
+                    agent.childSessionId = hit.childSessionId;
+                agent.startedAt = queuedAt;
+            }
             emit(agentEvent(agent));
             journal({
                 type: 'agent_request',
                 at: queuedAt,
                 index,
+                key,
+                pass,
+                ...(hit !== undefined ? { cached: true } : {}),
                 label: agent.label,
                 ...(phase ? { phaseIndex: phase.index, phaseTitle: phase.title } : {}),
                 promptPreview: preview(call.prompt),
@@ -432,6 +507,12 @@ export class WorkflowRuntime {
                     schema: call.schema !== undefined,
                 },
             });
+            if (hit !== undefined) {
+                return settle(agent, {
+                    state: 'done',
+                    value: structuredClone(hit.value),
+                });
+            }
             const admitted = await acquire(agent);
             if (!admitted) {
                 return agent.userSkipped
@@ -439,6 +520,7 @@ export class WorkflowRuntime {
                     : settle(agent, {
                         state: 'error',
                         error: 'The workflow was stopped before this agent started.',
+                        interrupted: true,
                     });
             }
             try {
@@ -446,6 +528,7 @@ export class WorkflowRuntime {
                     return settle(agent, {
                         state: 'error',
                         error: `Not started: the token budget for this workflow (${limits.tokenBudget} tokens) is spent.`,
+                        interrupted: true,
                     });
                 }
                 if (controller.signal.aborted || agent.userSkipped) {
@@ -454,6 +537,7 @@ export class WorkflowRuntime {
                         : settle(agent, {
                             state: 'error',
                             error: 'The workflow was stopped before this agent started.',
+                            interrupted: true,
                         });
                 }
                 agent.startedAt = now();
@@ -526,7 +610,7 @@ export class WorkflowRuntime {
         // --- start ---
         if (options.journal?.writeScript) {
             try {
-                await options.journal.writeScript(options.script, sha256(options.script));
+                await options.journal.writeScript(options.script, sha256(options.script), pass);
             }
             catch (error) {
                 journalError = error instanceof Error ? error.message : String(error);
@@ -541,6 +625,16 @@ export class WorkflowRuntime {
             meta,
             args,
             limits,
+            ...(resume !== undefined
+                ? {
+                    resume: {
+                        pass,
+                        previousFinish: resume.previousFinish,
+                        scriptSha256Changed: resume.scriptSha256 !== undefined && resume.scriptSha256 !== sha256(options.script),
+                    },
+                }
+                : {}),
+            ...(options.scriptPath !== undefined ? { scriptPath: options.scriptPath } : {}),
         });
         emit({
             type: 'workflow_started',
@@ -560,7 +654,11 @@ export class WorkflowRuntime {
                 maxHostCalls: limits.maxAgents + 100,
                 maxPendingHostCalls: limits.maxAgents + 100,
             });
-        const preludeConfig = { args, tokenLimit: limits.tokenBudget ?? null };
+        const preludeConfig = {
+            args,
+            tokenLimit: limits.tokenBudget ?? null,
+            deterministic: options.deterministic === true,
+        };
         const runResult = await codeRuntime.run({
             source: `${buildPrelude(preludeConfig)}\n${body}`,
             allowedCalls: [WORKFLOW_HOST_CALL],
@@ -571,7 +669,10 @@ export class WorkflowRuntime {
             onOutput,
             onHostCall: (request) => {
                 if (request.name !== WORKFLOW_HOST_CALL) {
-                    return Promise.resolve({ ok: false, error: `Unknown host call "${request.name}".` });
+                    return Promise.resolve({
+                        ok: false,
+                        error: `Unknown host call "${request.name}".`,
+                    });
                 }
                 let call;
                 try {
@@ -634,7 +735,7 @@ export class WorkflowRuntime {
             const failedAgents = begun.filter((a) => a.state === 'error').length;
             const progress = begun.length === 0
                 ? 'No agent had started.'
-                : `Before it failed: ${begun.length} agent${begun.length === 1 ? '' : 's'} started, ${finished} finished, ${failedAgents} failed. A rerun starts the whole script again, so finished agents run again.`;
+                : `Before it failed: ${begun.length} agent${begun.length === 1 ? '' : 's'} started, ${finished} finished, ${failedAgents} failed. ${options.canResume === true ? 'Resume the run to continue: agents whose prompt and options are unchanged return their saved results.' : 'A rerun starts the whole script again, so finished agents run again.'}`;
             error = `${describeScriptFailure(outcome, body, preludeLineCount(preludeConfig))}\n${progress}${scriptPhase !== undefined ? ` Last phase: "${scriptPhase}".` : ''}`;
         }
         const all = [...agents.values()];
@@ -646,6 +747,9 @@ export class WorkflowRuntime {
             tokens: all.reduce((sum, a) => sum + a.tokens, 0),
             toolCalls: all.reduce((sum, a) => sum + a.toolCalls, 0),
             elapsedMs: Math.max(0, now() - startedAt),
+            ...(all.some((a) => a.cached !== undefined)
+                ? { cachedAgents: all.filter((a) => a.cached !== undefined).length }
+                : {}),
         };
         const at = now();
         emit({