@namzu/sdk 20.4.0 → 21.1.0

package/src/run/drain.ts

@@ -0,0 +1,393 @@
+/**
+ * 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 type { NamzuErrorCode } from '../types/errors/index.js'
+import { NamzuError } from '../types/errors/index.js'
+import type { RunId } from '../types/ids/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointStore,
+	DurableRunEntry,
+	ParkState,
+	RunClaim,
+} from '../types/run/checkpoint-store.js'
+
+/** Runs handled per pass when the caller names no page size. */
+export const DEFAULT_DRAIN_PAGE_SIZE = 100
+
+/**
+ * What a drainer does with one run it successfully took.
+ *
+ * Receives the claim, not just its fence, because the holder and expiry are
+ * what a worker needs to decide whether it still has time to start — and
+ * because a caller that only ever sees a number tends to forget the lease
+ * can lapse under it.
+ *
+ * The intended body is a resume:
+ *
+ * ```ts
+ * onRun: (entry, claim) =>
+ *   resumeRun({
+ *     ...yourQueryParams,
+ *     scope: { ...entry, threadId },
+ *     checkpointStore: store,
+ *     claimFence: claim.fence,
+ *   })
+ * ```
+ *
+ * `claimFence` is the whole reason the claim is handed over: a write that
+ * does not carry it is unfenced, so a worker stalled past its lease would
+ * still be able to overwrite the record of whoever took the run over.
+ *
+ * A throw is recorded against that run and the pass continues. A drainer
+ * that died on the first bad run would leave the rest of the queue
+ * untouched, which is the failure a queue exists to spread out.
+ */
+export type DrainRun = (entry: DurableRunEntry, claim: RunClaim) => void | Promise<void>
+
+export interface DrainRunsParams {
+	/** Backend to list, claim and release against. Must support all three. */
+	readonly store: CheckpointStore
+	/** Contiguous prefix — `tenantId` required. See {@link CheckpointListingScope}. */
+	readonly scope: CheckpointListingScope
+	/**
+	 * Who is taking the runs. Per-PROCESS, never per-deployment: `holder` is
+	 * the only thing that distinguishes a renewal from a theft, so two
+	 * drainers sharing a string take live claims from each other instantly.
+	 */
+	readonly holder: string
+	/** Lease length in ms. Long enough that the slowest run finishes inside it. */
+	readonly ttlMs: number
+	/** The work. See {@link DrainRun}. */
+	readonly onRun: DrainRun
+
+	/**
+	 * Keep only runs whose park is in one of these states.
+	 *
+	 * **Absent means every run with durable state, parked or not**, and that
+	 * is not a placeholder default — it is what a crash sweep wants, because
+	 * a run that died mid-flight never parked and would be invisible under
+	 * any park filter. An approval inbox passes `['outstanding']`; a
+	 * reclamation sweep passes `['expired']`.
+	 */
+	readonly park?: readonly ParkState[]
+
+	/**
+	 * Stop taking new runs. Work already in flight is NOT interrupted — this
+	 * module owns no run and cannot cancel one; a caller that needs to abort
+	 * the work itself passes the same signal into whatever `onRun` starts.
+	 */
+	readonly signal?: AbortSignal
+
+	/**
+	 * How many runs may be in flight at once. Defaults to 1.
+	 *
+	 * Bounded on purpose. The obvious implementation — claim everything, then
+	 * `Promise.all` — holds N leases while doing one run's worth of work, so
+	 * the runs at the back of the batch expire before they are started and
+	 * are taken by somebody else mid-flight.
+	 */
+	readonly maxConcurrent?: number
+
+	/** Listing page size. See {@link DEFAULT_DRAIN_PAGE_SIZE}. */
+	readonly pageSize?: number
+
+	/**
+	 * Clock for expiry, so one pass judges every claim against one instant
+	 * and a test does not have to wait out a lease.
+	 */
+	readonly now?: number
+}
+
+/** A run a pass could not finish, and why. */
+export interface DrainFailure {
+	readonly runId: RunId
+	readonly error: string
+}
+
+/** What one pass did. */
+export interface DrainRunsResult {
+	/** Rows the listing returned, before any of them were contended for. */
+	readonly listed: number
+	/** Runs whose `onRun` returned. */
+	readonly drained: readonly RunId[]
+	/**
+	 * Runs another worker held. Not failures: "somebody got there first" is
+	 * the ordinary outcome of a queue with more than one reader.
+	 */
+	readonly skipped: readonly RunId[]
+	/**
+	 * Runs that stopped matching {@link DrainRunsParams.park} between the
+	 * listing and the claim, and were given straight back.
+	 *
+	 * Separate from {@link DrainRunsResult.skipped} because the cause is
+	 * different and so is what an operator should do about a lot of them: a
+	 * skip means another drainer is holding runs right now, a stale entry
+	 * means another drainer already FINISHED one. Empty on a pass with no
+	 * park filter, which has nothing to re-check against.
+	 */
+	readonly stale: readonly RunId[]
+	/** Runs whose `onRun` threw. */
+	readonly failed: readonly DrainFailure[]
+	/**
+	 * Runs that finished but whose lease could not be handed back.
+	 *
+	 * Separate from {@link DrainRunsResult.failed} because it is a different
+	 * fact with a different consequence: the work is done and the record is
+	 * written; the run is merely unavailable to the next reader until the
+	 * lease lapses. Reported rather than swallowed — a release that quietly
+	 * did nothing is how a queue silently loses throughput.
+	 */
+	readonly unreleased: readonly DrainFailure[]
+	/** Whether the pass stopped early because the signal aborted. */
+	readonly stopped: boolean
+}
+
+function refuse(code: NamzuErrorCode, message: string, details: Record<string, unknown>): never {
+	throw new NamzuError({ code, message, details })
+}
+
+function toMessage(err: unknown): string {
+	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: CheckpointStore): void {
+	const missing = (['listDurableRuns', 'claimRun', 'releaseRun'] as const).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: DrainRunsParams): Promise<DrainRunsResult> {
+	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: RunId[] = []
+	const skipped: RunId[] = []
+	const stale: RunId[] = []
+	const failed: DrainFailure[] = []
+	const unreleased: DrainFailure[] = []
+	let listed = 0
+	let stopped = false
+
+	const giveBack = async (entry: DurableRunEntry, fence: number): Promise<void> => {
+		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: DurableRunEntry): Promise<boolean> => {
+		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: DurableRunEntry): Promise<void> => {
+		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: string | undefined
+	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 }
+}

package/src/run/index.ts

@@ -5,5 +5,25 @@ 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'

package/src/run/memory-promoter.ts

@@ -0,0 +1,155 @@
+/**
+ * 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, RunMemoryCandidate } from '../types/run/memory-promotion.js'
+
+/**
+ * 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'],
+] as const satisfies readonly (readonly [keyof RunMemoryCandidate, string])[]
+
+/** Tag every record this promoter writes, so a host can find or prune them. */
+export 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
+}
+
+/** Everything the candidate knows, as `[heading, items]`, empties dropped. */
+function knowledge(
+	candidate: RunMemoryCandidate,
+	cap: number,
+): readonly (readonly [string, readonly string[]])[] {
+	const out: (readonly [string, readonly string[]])[] = []
+	for (const [key, heading] of KNOWLEDGE) {
+		const items = candidate[key] as readonly string[]
+		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: readonly (readonly [string, readonly string[]])[]): string {
+	return sections.map(([heading, items]) => `${heading.toLowerCase()} (${items.length})`).join(', ')
+}
+
+function render(
+	candidate: RunMemoryCandidate,
+	sections: readonly (readonly [string, readonly string[]])[],
+): string {
+	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: MemoryPromoterOptions): PromoteMemory {
+	const cap = options.maxPerCategory ?? 20
+	const tags = [RUN_MEMORY_TAG, ...(options.tags ?? [])]
+
+	return async (candidate: RunMemoryCandidate): Promise<void> => {
+		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 },
+		})
+	}
+}