@namzu/sdk 20.4.0 → 21.1.0

package/dist/run/drain.js

@@ -0,0 +1,228 @@
+/**
+ * One pass over a queue of durable runs: list what nobody holds, take it,
+ * hand it to a worker, give it back.
+ *
+ * Every primitive this composes already shipped —
+ * {@link import('../store/run/listing.js').listDurableRuns} enumerates runs
+ * above a run id, `claimRun` arbitrates between processes, `releaseRun`
+ * returns a run to the queue, and `resumeRun` carries a fence into every
+ * durable write. Nothing composed them, so the two things the claim was
+ * built for — an approval inbox and a crash sweeper — still required a host
+ * to write the loop, and writing it correctly means getting the release
+ * into a `finally` and the `null` claim out of the error path. Both are the
+ * kind of thing a host gets wrong once, quietly.
+ *
+ * ## What this deliberately is NOT
+ *
+ * A supervisor, a daemon, or a scheduler. There is no timer here, no
+ * process spawn, no retry backoff and no `while (true)`. `drainRuns` makes
+ * ONE bounded pass and returns what happened; running it again is the
+ * caller's decision, made wherever that caller already has a scheduler. A
+ * per-platform supervisor is the same trade the deployment-adapter matrix
+ * was rejected for: one seam beats N adapters.
+ *
+ * The unit of work is a callback, so this module never needs a provider, a
+ * tool registry or a sandbox — the half of a run that cannot be serialized
+ * stays with the caller, exactly as `resumeRun` already splits it.
+ */
+import { claimRun, listDurableRuns, releaseRun, summarizePark } from '../store/run/listing.js';
+import { NamzuError } from '../types/errors/index.js';
+/** Runs handled per pass when the caller names no page size. */
+export const DEFAULT_DRAIN_PAGE_SIZE = 100;
+function refuse(code, message, details) {
+    throw new NamzuError({ code, message, details });
+}
+function toMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Refuse a store that cannot do the whole job, BEFORE anything is listed.
+ *
+ * Checked up front rather than at the first call that needs each method, so
+ * that a store missing only `releaseRun` cannot resume half a queue and then
+ * discover it has no way to give the runs back. The optional-capability rule
+ * on `CheckpointStore` says a caller refuses rather than degrades; a drainer
+ * that degraded would be the worst instance of it, because "claimed by
+ * default" here means every worker proceeds on every run.
+ */
+function assertDrainable(store) {
+    const missing = ['listDurableRuns', 'claimRun', 'releaseRun'].filter((m) => typeof store[m] !== 'function');
+    if (missing.length === 0)
+        return;
+    refuse('capability_unavailable', `drainRuns: the injected checkpoint store does not implement ${missing.map((m) => `\`${m}\``).join(', ')}, so it cannot arbitrate a queue. Refusing before anything is claimed rather than draining what it can — a drainer that proceeded without a claim would let two workers restore one checkpoint, both execute its tools and both write under one run id. Supply a store that implements all three (the built-in disk and in-memory stores do), or run a single writer per run.`, { missing });
+}
+/**
+ * Take every unclaimed run under a scope, one bounded pass, and give each
+ * one back when its work returns.
+ *
+ * The shape is: list parked-and-unclaimed → claim → work → release in a
+ * `finally`. The `finally` is the part a host writes wrong: a worker that
+ * returns without releasing leaves the run stuck until the lease lapses,
+ * and a worker that releases only on success leaves a FAILED run stuck for
+ * the same duration — so a queue quietly loses its throughput to the runs
+ * that need retrying most.
+ *
+ * `claimed: false` is not a parameter. A drainer never wants work somebody
+ * else holds; that is what makes it a drainer rather than a listing. An
+ * expired claim counts as unheld, which is what makes a dead worker's runs
+ * recoverable at all.
+ *
+ * ## What "exactly once" does and does not mean here
+ *
+ * Two drainers never hold one run at the same time — that is the claim, and
+ * it is absolute. **Exactly-once over a whole pass is a weaker promise, and
+ * where it holds it comes from the FILTER, not from the claim.** A listing
+ * is a snapshot; between paging a row and claiming it, another drainer can
+ * finish that run and release it, and the claim then succeeds on work
+ * already done. So a claimed row is re-read against
+ * {@link DrainRunsParams.park} before any work starts, and one that no
+ * longer matches is given straight back as {@link DrainRunsResult.stale}.
+ * An inbox drain (`park: ['outstanding']`) whose work answers the park is
+ * therefore exactly-once, because doing the work is what removes the run
+ * from the queue.
+ *
+ * With NO park filter there is nothing to re-check, and two drainers can
+ * both process one run. That is not an omission: a checkpoint store holds no
+ * run STATUS by design — nothing in it distinguishes a run that finished
+ * from one that died — so "already done" is a fact only the host's own run
+ * records carry. A crash sweep intersects with those records inside
+ * `onRun`, which is the shape {@link DurableRunEntry} already prescribes.
+ *
+ * @throws NamzuError `capability_unavailable` when the store cannot list,
+ *   claim or release — before any run is touched.
+ * @throws NamzuError `invalid_config` on a lease or concurrency that cannot
+ *   mean what it says.
+ */
+export async function drainRuns(params) {
+    const { store, scope, holder, ttlMs, onRun, park, signal, now } = params;
+    assertDrainable(store);
+    if (holder.trim().length === 0) {
+        refuse('invalid_config', 'drainRuns: `holder` is empty. It is the only thing that distinguishes a renewal from a theft, so two drainers sharing one string take live claims from each other instantly. Use something per-process — a worker id, a pod name plus a pid.', { holder });
+    }
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        refuse('invalid_config', `drainRuns: ttlMs must be a positive number of milliseconds, got ${String(ttlMs)}. A lease that expires immediately is a lease every worker can take at once, which is the condition a claim exists to prevent.`, { ttlMs });
+    }
+    const maxConcurrent = params.maxConcurrent ?? 1;
+    if (!Number.isInteger(maxConcurrent) || maxConcurrent < 1) {
+        refuse('invalid_config', `drainRuns: maxConcurrent must be a positive integer, got ${String(params.maxConcurrent)}. Zero would drain nothing while reporting a successful pass.`, { maxConcurrent: params.maxConcurrent });
+    }
+    const pageSize = params.pageSize ?? DEFAULT_DRAIN_PAGE_SIZE;
+    const drained = [];
+    const skipped = [];
+    const stale = [];
+    const failed = [];
+    const unreleased = [];
+    let listed = 0;
+    let stopped = false;
+    const giveBack = async (entry, fence) => {
+        try {
+            await releaseRun(store, entry, fence);
+        }
+        catch (err) {
+            // Never rethrown: on the work path this runs inside a `finally`
+            // unwinding the caller's error, and replacing it would send the
+            // operator to debug the disk instead of the run.
+            unreleased.push({ runId: entry.runId, error: toMessage(err) });
+        }
+    };
+    /**
+     * Is this row still the row the listing described?
+     *
+     * A listing is a SNAPSHOT, and a claim taken against a stale snapshot is
+     * a claim on work somebody already did. The window is real and small:
+     * drainer B pages the queue, drainer A takes a run, finishes it, answers
+     * its park and releases — and B's claim then succeeds on a run that is no
+     * longer outstanding. Mutual exclusion cannot close that; only re-reading
+     * after the claim can, which is why this is here and not in the store.
+     *
+     * Only the park is re-checked, because it is the only predicate this loop
+     * was given. **Two drainers with no park filter can both process one
+     * run**, and no amount of claiming prevents it: a checkpoint store holds
+     * no run STATUS by design — see the note on {@link DurableRunEntry} — so
+     * "already done" is a fact only the host's own run records carry. A crash
+     * sweep intersects with those records inside `onRun`.
+     */
+    const stillMatches = async (entry) => {
+        if (!park)
+            return true;
+        const fresh = summarizePark(await store.listCheckpoints(entry), now ?? Date.now());
+        return fresh !== undefined && park.includes(fresh.state);
+    };
+    /**
+     * One run: take it, work it, give it back.
+     *
+     * **No cancellation check here, and its absence is deliberate.** One was
+     * written, and a mutation test found nothing could kill it: the batch
+     * below dispatches with `.map(handle)`, which calls every handler
+     * synchronously before any of them awaits, so a signal that aborts during
+     * a batch cannot be observed at the top of a handler that has already
+     * been entered — and a signal that aborts BETWEEN batches is caught by
+     * the check in the loop, which runs first. A branch nothing can reach is
+     * a declaration nothing drives, so it is gone rather than covered by a
+     * test that would have proved nothing
+     * (`docs/conventions/declared-but-undriven.md`).
+     */
+    const handle = async (entry) => {
+        const claim = await claimRun(store, entry, {
+            holder,
+            ttlMs,
+            ...(now !== undefined ? { now } : {}),
+        });
+        // `null` is not an error. Another worker got there first, which is the
+        // ordinary outcome of two readers on one queue.
+        if (!claim) {
+            skipped.push(entry.runId);
+            return;
+        }
+        // Checked with the claim in hand rather than before taking it: only
+        // under the claim is the answer stable, because nobody else can change
+        // it while this drainer holds the run.
+        if (!(await stillMatches(entry))) {
+            stale.push(entry.runId);
+            await giveBack(entry, claim.fence);
+            return;
+        }
+        try {
+            await onRun(entry, claim);
+            drained.push(entry.runId);
+        }
+        catch (err) {
+            failed.push({ runId: entry.runId, error: toMessage(err) });
+        }
+        finally {
+            await giveBack(entry, claim.fence);
+        }
+    };
+    let cursor;
+    do {
+        if (signal?.aborted) {
+            stopped = true;
+            break;
+        }
+        const page = await listDurableRuns(store, scope, {
+            // Not a parameter. See the note above.
+            claimed: false,
+            ...(park ? { park } : {}),
+            limit: pageSize,
+            ...(cursor !== undefined ? { cursor } : {}),
+            ...(now !== undefined ? { now } : {}),
+        });
+        listed += page.entries.length;
+        // Windowed rather than `Promise.all` over the page: the leases are taken
+        // as the work starts, so a page bigger than the pass can finish inside
+        // one TTL does not hand the tail of it to somebody else mid-flight.
+        for (let i = 0; i < page.entries.length; i += maxConcurrent) {
+            if (signal?.aborted) {
+                stopped = true;
+                break;
+            }
+            await Promise.all(page.entries.slice(i, i + maxConcurrent).map(handle));
+        }
+        // A drained run is released, so it is unclaimed again — but the cursor
+        // is a position in a total order and has already passed it, so the pass
+        // cannot see it twice and cannot fail to terminate.
+        cursor = stopped ? undefined : page.cursor;
+    } while (cursor !== undefined);
+    return { listed, drained, skipped, stale, failed, unreleased, stopped };
+}
+//# sourceMappingURL=drain.js.map

package/dist/run/drain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.js","sourceRoot":"","sources":["../../src/run/drain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAE9F,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAUrD,gEAAgE;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAA;AAkI1C,SAAS,MAAM,CAAC,IAAoB,EAAE,OAAe,EAAE,OAAgC;IACtF,MAAM,IAAI,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;AACjD,CAAC;AAED,SAAS,SAAS,CAAC,GAAY;IAC9B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;AACxD,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,eAAe,CAAC,KAAsB;IAC9C,MAAM,OAAO,GAAI,CAAC,iBAAiB,EAAE,UAAU,EAAE,YAAY,CAAW,CAAC,MAAM,CAC9E,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,CACrC,CAAA;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAChC,MAAM,CACL,wBAAwB,EACxB,+DAA+D,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,+WAA+W,EACvd,EAAE,OAAO,EAAE,CACX,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAuB;IACtD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAAA;IAExE,eAAe,CAAC,KAAK,CAAC,CAAA;IAEtB,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,CACL,gBAAgB,EAChB,8OAA8O,EAC9O,EAAE,MAAM,EAAE,CACV,CAAA;IACF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,CACL,gBAAgB,EAChB,mEAAmE,MAAM,CAAC,KAAK,CAAC,gIAAgI,EAChN,EAAE,KAAK,EAAE,CACT,CAAA;IACF,CAAC;IACD,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,CAAC,CAAA;IAC/C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QAC3D,MAAM,CACL,gBAAgB,EAChB,4DAA4D,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,+DAA+D,EACvJ,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE,CACvC,CAAA;IACF,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,uBAAuB,CAAA;IAE3D,MAAM,OAAO,GAAY,EAAE,CAAA;IAC3B,MAAM,OAAO,GAAY,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAY,EAAE,CAAA;IACzB,MAAM,MAAM,GAAmB,EAAE,CAAA;IACjC,MAAM,UAAU,GAAmB,EAAE,CAAA;IACrC,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,IAAI,OAAO,GAAG,KAAK,CAAA;IAEnB,MAAM,QAAQ,GAAG,KAAK,EAAE,KAAsB,EAAE,KAAa,EAAiB,EAAE;QAC/E,IAAI,CAAC;YACJ,MAAM,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,gEAAgE;YAChE,gEAAgE;YAChE,iDAAiD;YACjD,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QAC/D,CAAC;IACF,CAAC,CAAA;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,YAAY,GAAG,KAAK,EAAE,KAAsB,EAAoB,EAAE;QACvE,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAA;QACtB,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;QAClF,OAAO,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACzD,CAAC,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,MAAM,GAAG,KAAK,EAAE,KAAsB,EAAiB,EAAE;QAC9D,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE;YAC1C,MAAM;YACN,KAAK;YACL,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrC,CAAC,CAAA;QACF,uEAAuE;QACvE,gDAAgD;QAChD,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YACzB,OAAM;QACP,CAAC;QACD,oEAAoE;QACpE,uEAAuE;QACvE,uCAAuC;QACvC,IAAI,CAAC,CAAC,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YACvB,MAAM,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;YAClC,OAAM;QACP,CAAC;QACD,IAAI,CAAC;YACJ,MAAM,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;YACzB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC1B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QAC3D,CAAC;gBAAS,CAAC;YACV,MAAM,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;QACnC,CAAC;IACF,CAAC,CAAA;IAED,IAAI,MAA0B,CAAA;IAC9B,GAAG,CAAC;QACH,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACrB,OAAO,GAAG,IAAI,CAAA;YACd,MAAK;QACN,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE;YAChD,uCAAuC;YACvC,OAAO,EAAE,KAAK;YACd,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzB,KAAK,EAAE,QAAQ;YACf,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrC,CAAC,CAAA;QACF,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAA;QAE7B,yEAAyE;QACzE,uEAAuE;QACvE,oEAAoE;QACpE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,aAAa,EAAE,CAAC;YAC7D,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACrB,OAAO,GAAG,IAAI,CAAA;gBACd,MAAK;YACN,CAAC;YACD,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;QACxE,CAAC;QAED,uEAAuE;QACvE,wEAAwE;QACxE,oDAAoD;QACpD,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAA;IAC3C,CAAC,QAAQ,MAAM,KAAK,SAAS,EAAC;IAE9B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAA;AACxE,CAAC"}

package/dist/run/index.d.ts

@@ -2,6 +2,14 @@ export { RunPersistence } from '../manager/run/persistence.js';
 export { RunDiskStore } from '../store/run/disk.js';
 export { createRunReporter } from './reporter.js';
 export type { RunReporter } from './reporter.js';
+export { DEFAULT_DRAIN_PAGE_SIZE, drainRuns } from './drain.js';
+export type { DrainFailure, DrainRun, DrainRunsParams, DrainRunsResult } from './drain.js';
+export { DEFAULT_GATE_MAX_RETRIES, DEFAULT_GATE_OUTPUT_CHARS, DEFAULT_GATE_TIMEOUT_MS, clipOutput, createCommandGate, } from './command-gate.js';
+export type { CommandGateOptions, GateExec } from './command-gate.js';
+export { FINGERPRINT_MAX_BYTES, FINGERPRINT_TIMEOUT_MS, fingerprintWorkspace, } from './workspace-fingerprint.js';
+export type { FingerprintExec, WorkspaceFingerprintOptions } from './workspace-fingerprint.js';
 export { checkLimitsDetailed, buildLimitConfig } from './LimitChecker.js';
 export type { LimitCheckerState, LimitCheckResult } from './LimitChecker.js';
+export { RUN_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js';
+export type { MemoryPromoterOptions } from './memory-promoter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/run/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC1F,OAAO,EACN,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,GACjB,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACrE,OAAO,EACN,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACpB,MAAM,4BAA4B,CAAA;AACnC,YAAY,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAA;AAE9F,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAE5E,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/run/index.js

@@ -1,5 +1,9 @@
 export { RunPersistence } from '../manager/run/persistence.js';
 export { RunDiskStore } from '../store/run/disk.js';
 export { createRunReporter } from './reporter.js';
+export { DEFAULT_DRAIN_PAGE_SIZE, drainRuns } from './drain.js';
+export { DEFAULT_GATE_MAX_RETRIES, DEFAULT_GATE_OUTPUT_CHARS, DEFAULT_GATE_TIMEOUT_MS, clipOutput, createCommandGate, } from './command-gate.js';
+export { FINGERPRINT_MAX_BYTES, FINGERPRINT_TIMEOUT_MS, fingerprintWorkspace, } from './workspace-fingerprint.js';
 export { checkLimitsDetailed, buildLimitConfig } from './LimitChecker.js';
+export { RUN_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js';
 //# sourceMappingURL=index.js.map

package/dist/run/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGjD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGjD,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE/D,OAAO,EACN,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,GACjB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACN,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACpB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAGzE,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/run/memory-promoter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The default {@link PromoteMemory}: write what a run learned into a
+ * {@link MemoryStore}, or write nothing at all.
+ *
+ * `promoteMemory` is called once at settle with the compaction extractor's
+ * already-structured output — decisions, discoveries, user requirements,
+ * failures, environment facts — and **nothing shipped supplied the hook**.
+ * So the structure the compaction pass had spent tokens producing was
+ * serialized into one system message and dropped on the floor when the run
+ * ended, exactly as its own module comment says. This is the supplier, and
+ * it is mostly a filter: the hard part — extracting facts from a transcript
+ * — already happened.
+ *
+ * ## The filter, which is the only decision here
+ *
+ * **A run that learned nothing must leave nothing.** Not an empty record,
+ * not a record whose body says "no decisions" — nothing. A promoter that
+ * wrote a row per run would fill the store with the runs least worth
+ * remembering, and `search_memory` would then return them: the model reads
+ * that store on later runs, so noise here is not merely wasted disk, it is
+ * context spent on a run that did nothing.
+ *
+ * What counts as having learned something is the five KNOWLEDGE categories —
+ * decisions, discoveries, user requirements, failures, environment. Not
+ * `task`, which every run has because it is the prompt restated. Not
+ * `files`, which every run that opened anything has, and which says what was
+ * touched rather than what was learned. A run whose only trace is "it read
+ * six files" is the exact record this filter exists to refuse.
+ *
+ * ## What it does NOT do
+ *
+ * Deduplicate against what is already stored, merge with a previous run's
+ * record, or expire anything. Each is a policy with real trade-offs and a
+ * host that wants one owns it — `promoteMemory` is a callback precisely so
+ * that the runtime does not decide this. This is the obvious default, not
+ * the only possible one.
+ */
+import type { MemoryStore } from '../types/memory/index.js';
+import type { PromoteMemory } from '../types/run/memory-promotion.js';
+/** Tag every record this promoter writes, so a host can find or prune them. */
+export declare const RUN_MEMORY_TAG = "run-memory";
+export interface MemoryPromoterOptions {
+    /** Where records go. The same store `save_memory` writes through. */
+    readonly store: MemoryStore;
+    /**
+     * Extra tags on every record, beyond {@link RUN_MEMORY_TAG}.
+     *
+     * A host running several agents against one store uses this to tell whose
+     * memory is whose; without it a later search cannot.
+     */
+    readonly tags?: readonly string[];
+    /**
+     * Cap on entries rendered per category. Defaults to 20.
+     *
+     * The extractor already caps its lists, and this is the second cap for
+     * the same reason the first exists: a record nobody will read is a record
+     * that costs context every time it is retrieved.
+     */
+    readonly maxPerCategory?: number;
+}
+/**
+ * Build a promoter that writes one record per run that learned something.
+ *
+ * Never throws out to the runtime — but it does not swallow either: the
+ * runtime already catches and logs a promoter's failure at settle, and
+ * catching here as well would hide a broken store from the one place that
+ * reports it.
+ */
+export declare function createMemoryPromoter(options: MemoryPromoterOptions): PromoteMemory;
+//# sourceMappingURL=memory-promoter.d.ts.map

package/dist/run/memory-promoter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-promoter.d.ts","sourceRoot":"","sources":["../../src/run/memory-promoter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,kCAAkC,CAAA;AAkBzF,+EAA+E;AAC/E,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C,MAAM,WAAW,qBAAqB;IACrC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAChC;AA6CD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAuBlF"}

package/dist/run/memory-promoter.js

@@ -0,0 +1,117 @@
+/**
+ * The default {@link PromoteMemory}: write what a run learned into a
+ * {@link MemoryStore}, or write nothing at all.
+ *
+ * `promoteMemory` is called once at settle with the compaction extractor's
+ * already-structured output — decisions, discoveries, user requirements,
+ * failures, environment facts — and **nothing shipped supplied the hook**.
+ * So the structure the compaction pass had spent tokens producing was
+ * serialized into one system message and dropped on the floor when the run
+ * ended, exactly as its own module comment says. This is the supplier, and
+ * it is mostly a filter: the hard part — extracting facts from a transcript
+ * — already happened.
+ *
+ * ## The filter, which is the only decision here
+ *
+ * **A run that learned nothing must leave nothing.** Not an empty record,
+ * not a record whose body says "no decisions" — nothing. A promoter that
+ * wrote a row per run would fill the store with the runs least worth
+ * remembering, and `search_memory` would then return them: the model reads
+ * that store on later runs, so noise here is not merely wasted disk, it is
+ * context spent on a run that did nothing.
+ *
+ * What counts as having learned something is the five KNOWLEDGE categories —
+ * decisions, discoveries, user requirements, failures, environment. Not
+ * `task`, which every run has because it is the prompt restated. Not
+ * `files`, which every run that opened anything has, and which says what was
+ * touched rather than what was learned. A run whose only trace is "it read
+ * six files" is the exact record this filter exists to refuse.
+ *
+ * ## What it does NOT do
+ *
+ * Deduplicate against what is already stored, merge with a previous run's
+ * record, or expire anything. Each is a policy with real trade-offs and a
+ * host that wants one owns it — `promoteMemory` is a callback precisely so
+ * that the runtime does not decide this. This is the obvious default, not
+ * the only possible one.
+ */
+/**
+ * The categories that make a run worth remembering.
+ *
+ * Ordered as they are rendered. `userRequirements` first because it is the
+ * most durable of the five — a constraint the user stated outlives the run
+ * that heard it, whereas a discovery about a codebase expires when the
+ * codebase moves.
+ */
+const KNOWLEDGE = [
+    ['userRequirements', 'What the user requires'],
+    ['decisions', 'Decisions'],
+    ['discoveries', 'Discoveries'],
+    ['failures', 'What did not work'],
+    ['environment', 'Environment'],
+];
+/** Tag every record this promoter writes, so a host can find or prune them. */
+export const RUN_MEMORY_TAG = 'run-memory';
+/** Everything the candidate knows, as `[heading, items]`, empties dropped. */
+function knowledge(candidate, cap) {
+    const out = [];
+    for (const [key, heading] of KNOWLEDGE) {
+        const items = candidate[key];
+        if (items.length > 0)
+            out.push([heading, items.slice(0, cap)]);
+    }
+    return out;
+}
+/** A one-line summary naming what kind of knowledge the record holds. */
+function summarize(sections) {
+    return sections.map(([heading, items]) => `${heading.toLowerCase()} (${items.length})`).join(', ');
+}
+function render(candidate, sections) {
+    const body = sections.map(([heading, items]) => `## ${heading}\n\n${items.map((i) => `- ${i}`).join('\n')}`);
+    // The eviction counts, when there are any. Carried rather than hidden for
+    // the reason the candidate carries them: somebody reading this record
+    // should know they are reading a truncated account of the run, not a
+    // complete one.
+    const evicted = Object.entries(candidate.evicted).filter(([, n]) => n > 0);
+    if (evicted.length > 0) {
+        body.push(`## Dropped during the run\n\n${evicted
+            .map(([category, n]) => `- ${category}: ${n} entr${n === 1 ? 'y' : 'ies'} evicted`)
+            .join('\n')}`);
+    }
+    if (candidate.files.length > 0) {
+        body.push(`## Files touched\n\n${candidate.files.map((f) => `- ${f}`).join('\n')}`);
+    }
+    return `# ${candidate.task}\n\n${body.join('\n\n')}\n`;
+}
+/**
+ * Build a promoter that writes one record per run that learned something.
+ *
+ * Never throws out to the runtime — but it does not swallow either: the
+ * runtime already catches and logs a promoter's failure at settle, and
+ * catching here as well would hide a broken store from the one place that
+ * reports it.
+ */
+export function createMemoryPromoter(options) {
+    const cap = options.maxPerCategory ?? 20;
+    const tags = [RUN_MEMORY_TAG, ...(options.tags ?? [])];
+    return async (candidate) => {
+        const sections = knowledge(candidate, cap);
+        // Nothing learned, nothing written. Not an empty record: a store full
+        // of rows describing runs that discovered nothing is a store whose
+        // search results are mostly noise, and the model reads that store.
+        if (sections.length === 0)
+            return;
+        await options.store.create({
+            title: candidate.task.trim() || `Run ${candidate.runId}`,
+            summary: summarize(sections),
+            content: render(candidate, sections),
+            tags,
+            format: 'markdown',
+            // The run id, so a record can be traced back to the run that formed
+            // it. Evidence rather than decoration: without it a surprising
+            // memory cannot be checked against what actually happened.
+            metadata: { runId: candidate.runId, source: RUN_MEMORY_TAG },
+        });
+    };
+}
+//# sourceMappingURL=memory-promoter.js.map

package/dist/run/memory-promoter.js.map

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

package/dist/run/workspace-fingerprint.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A hash of everything a run could have changed in its working tree.
+ *
+ * It exists to answer one question, asked between two attempts at the same
+ * verification: **did anything happen since it last failed?** A verify-then-fix
+ * loop that re-runs the build after a turn which edited nothing spends a full
+ * command execution to learn what a comparison already knew, and does it once
+ * per remaining attempt — so a model that has stopped making progress burns
+ * the entire budget confirming the same failure.
+ *
+ * ## What is hashed, and why each part
+ *
+ * Three sources, because no one of them is complete:
+ *
+ *  1. **`git status --porcelain`** — which paths differ from the index at all.
+ *     Cheap, and it catches additions, deletions and mode changes. On its own
+ *     it is not enough: editing a tracked file that was ALREADY modified
+ *     leaves the status output byte-identical.
+ *  2. **`git diff --binary HEAD`** — the content of every tracked change.
+ *     `--binary` so an edit to a file git treats as binary is a real diff
+ *     rather than the constant line `Binary files … differ`, which would make
+ *     every edit to such a file invisible.
+ *  3. **Untracked file contents**, which no `git diff` covers. A new file is
+ *     named by `status` but its CONTENT is not, so successive edits to a
+ *     brand-new file would otherwise look like no change at all.
+ *
+ * ### Symlinks are recorded as their target, not read through
+ *
+ * Reading a link follows it, so a link repointed from one file to another
+ * with identical contents hashes the same — while the thing the workspace
+ * actually resolves has changed. The link's target path is the fact that
+ * moved, so that is what goes in.
+ *
+ * ## Failing open, on the cheap side
+ *
+ * Every uncertainty returns `null`, meaning *no fingerprint*, and a caller
+ * that cannot fingerprint re-runs its command. That is the correct direction:
+ * the cost of a wrong `null` is one command execution, and the cost of a
+ * wrong MATCH is a verification silently skipped — the loop would report
+ * "nothing changed" about a workspace that did change, and the model would be
+ * told to edit something it had already edited.
+ *
+ * So: a non-zero exit from any git invocation, a repository with no commits,
+ * a timeout, or output past the size cap all produce `null` rather than a
+ * partial hash. A truncated diff that hashed successfully would be the worst
+ * outcome available here, because two different workspaces truncated at the
+ * same point collide.
+ */
+import type { CommandOptions, CommandResult } from '../types/execution/index.js';
+/** How a fingerprint runs git. Injected so a test needs no repository. */
+export type FingerprintExec = (command: string, args: string[], options?: CommandOptions) => Promise<CommandResult>;
+/**
+ * The three filesystem reads an untracked entry needs.
+ *
+ * Injectable for one specific reason, written down because a seam that
+ * exists only for tests is usually a smell: **creating a symlink requires a
+ * privilege that is not granted by default on Windows**, so the symlink rule
+ * below — the one that says a repointed link changes the fingerprint even
+ * when the bytes behind it do not — cannot be exercised on a developer
+ * machine without it. A rule that can only be checked on some machines is a
+ * rule nobody checks.
+ *
+ * The default is `node:fs/promises` and every other test uses it against a
+ * real repository, so this is not a fixture standing in for production; it is
+ * one branch of one function reached without a privilege.
+ */
+export interface FingerprintFs {
+    lstat(path: string): Promise<{
+        isSymbolicLink(): boolean;
+        isFile(): boolean;
+    }>;
+    readlink(path: string): Promise<string>;
+    readFile(path: string): Promise<Buffer>;
+}
+/**
+ * Cap on the bytes any single git invocation may produce.
+ *
+ * Past it the fingerprint is abandoned rather than hashed. A diff big enough
+ * to hit this is a diff nobody is going to iterate on anyway, and hashing a
+ * clipped one would let two different trees agree.
+ */
+export declare const FINGERPRINT_MAX_BYTES: number;
+/** Default deadline per git invocation. */
+export declare const FINGERPRINT_TIMEOUT_MS = 20000;
+export interface WorkspaceFingerprintOptions {
+    /** Repository root, or any directory inside it. */
+    readonly cwd: string;
+    /** How to run git. */
+    readonly exec: FingerprintExec;
+    /** Per-invocation deadline. See {@link FINGERPRINT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** See {@link FINGERPRINT_MAX_BYTES}. */
+    readonly maxBytes?: number;
+    /** Filesystem reads. See {@link FingerprintFs}. */
+    readonly fs?: FingerprintFs;
+}
+/**
+ * A hash of the working tree's uncommitted state, or `null` when it cannot be
+ * established.
+ *
+ * **`null` is never "unchanged".** It means "I cannot tell", and the caller
+ * must treat it as a reason to do the work rather than to skip it.
+ */
+export declare function fingerprintWorkspace(options: WorkspaceFingerprintOptions): Promise<string | null>;
+//# sourceMappingURL=workspace-fingerprint.d.ts.map

package/dist/run/workspace-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-fingerprint.d.ts","sourceRoot":"","sources":["../../src/run/workspace-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAEhF,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,cAAc,KACpB,OAAO,CAAC,aAAa,CAAC,CAAA;AAE3B;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,cAAc,IAAI,OAAO,CAAC;QAAC,MAAM,IAAI,OAAO,CAAA;KAAE,CAAC,CAAA;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACvC;AAID;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAkB,CAAA;AAEpD,2CAA2C;AAC3C,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAE5C,MAAM,WAAW,2BAA2B;IAC3C,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,CAAC,EAAE,aAAa,CAAA;CAC3B;AAwBD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,2BAA2B,GAClC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmDxB"}