@namzu/sdk 42.0.0 → 42.0.1

package/src/runtime/query/release-run.ts

@@ -0,0 +1,168 @@
+import type { Span } from '@opentelemetry/api'
+import type { WorkingStateManager } from '../../compaction/manager.js'
+import { NAMZU } from '../../constants/telemetry/index.js'
+import type { EmergencySaveManager } from '../../manager/run/emergency.js'
+import { recordRunDuration } from '../../telemetry/metrics.js'
+import type { RunEvent } from '../../types/run/index.js'
+import { type PromoteMemory, memoryCandidateFor } from '../../types/run/memory-promotion.js'
+import type { Sandbox } from '../../types/sandbox/index.js'
+import { errorAttributes } from '../../utils/log/exception.js'
+import type { AwaitedJobs } from '../jobs/awaited-jobs.js'
+import type { BackgroundJobRegistry } from '../jobs/registry.js'
+import type { RunContext } from './context.js'
+import type { EventTranslator } from './events.js'
+import type { QuestionParkBinding } from './question-park.js'
+import { teardownSandbox } from './sandbox-lifecycle.js'
+
+/**
+ * Everything a run borrows, handed back when it ends.
+ *
+ * A run attaches to process-wide things it does not own — crash handlers, a
+ * shared background-job registry, a question channel a tool outlived, a task
+ * store's listener, a sandbox — and every one of them has to be released on
+ * the way out, including the exits a `try` never reaches. So this is the body
+ * of `query()`'s `finally`: the keyword stays where it is, which is what makes
+ * abandonment run this just as settlement does.
+ *
+ * The order is the contract, and the awaits are in it: detach the emergency
+ * handlers, unsubscribe from job exits, close the wait-intent recorder, kill
+ * only this run's jobs, unbind the question channel, promote what the run
+ * learned, tear the sandbox down, unsubscribe from the task store, record the
+ * duration under the status the run actually settled with, and end the root
+ * span last.
+ */
+export interface RunResources {
+	readonly ctx: RunContext
+	readonly eventTranslator: EventTranslator
+	readonly emergencyManager: EmergencySaveManager | undefined
+	readonly unsubscribeJobExits: (() => void) | undefined
+	readonly unsubscribeTaskStore: (() => void) | undefined
+	readonly awaitedJobs: AwaitedJobs | undefined
+	/** Jobs a host bound to its session are the host's to stop, not this run's. */
+	readonly backgroundJobs: BackgroundJobRegistry | undefined
+	readonly backgroundJobOwner: string | undefined
+	readonly questionParks: QuestionParkBinding
+	readonly workingStateManager: WorkingStateManager | undefined
+	readonly promoteMemory: PromoteMemory | undefined
+	readonly sandbox: Sandbox | undefined
+	readonly sandboxTeardownTimeoutMs: number
+	readonly runStartedAt: number
+	readonly rootSpan: Span
+}
+
+/**
+ * Release them, in that order.
+ *
+ * A generator rather than a plain async function because the sandbox teardown
+ * reports `sandbox_destroyed`, and that event has to reach the host at the
+ * position it always did — `yield*` from the caller's `finally` keeps it
+ * exactly there.
+ */
+export async function* releaseRunResources(
+	resources: RunResources,
+): AsyncGenerator<RunEvent, void> {
+	const {
+		ctx,
+		eventTranslator,
+		emergencyManager,
+		unsubscribeJobExits,
+		unsubscribeTaskStore,
+		awaitedJobs,
+		backgroundJobs,
+		backgroundJobOwner,
+		questionParks,
+		workingStateManager,
+		promoteMemory,
+		sandbox,
+		sandboxTeardownTimeoutMs,
+		runStartedAt,
+		rootSpan,
+	} = resources
+
+	// Release the process's termination path as soon as this run is
+	// done with it. Leaving the handlers installed would keep a
+	// WeakRef'd, settled run as the crash target for the rest of the
+	// process's life.
+	emergencyManager?.detach()
+
+	// A background job outlives the tool call that started it — that
+	// is what it is for — so nothing but this stops it outliving the
+	// RUN. Scoped to this run's id: a shared registry serving several
+	// runs must not have one of them tear down another's work.
+	//
+	// Awaited, and its failure swallowed. A job that would not die is
+	// worth a log line, and is not worth retracting a run's answer.
+	unsubscribeJobExits?.()
+	// The wait-intent recorder listens on the same shared registry and
+	// leaks the same way if it is left attached.
+	awaitedJobs?.close()
+	// Only jobs bound to this run. Jobs a host bound to its session are
+	// the host's to stop, when the session ends.
+	if (backgroundJobs && (backgroundJobOwner ?? ctx.runId) === ctx.runId) {
+		try {
+			const stopped = await backgroundJobs.killOwner(ctx.runId)
+			if (stopped.length > 0) {
+				ctx.log.info('Background jobs stopped with the run', {
+					[NAMZU.RUN_ID]: ctx.runId,
+					'namzu.jobs.stopped': stopped.length,
+				})
+			}
+		} catch (jobErr) {
+			ctx.log.error('A background job did not stop cleanly', {
+				[NAMZU.RUN_ID]: ctx.runId,
+				...errorAttributes(jobErr),
+			})
+		}
+	}
+
+	// Same reasoning for the question channel: the tools outlive the
+	// run that bound them, so leaving it attached would have a later
+	// run's question written into this run's checkpoint store.
+	questionParks.unbind()
+
+	// Offer what the run learned to whoever decides what is worth
+	// keeping. In `finally` and awaited: a run that failed still
+	// discovered things, and a fire-and-forget write would race the
+	// process exiting on a one-shot CLI run. A throw here is
+	// swallowed — a memory that failed to form must not retract an
+	// answer that was already produced.
+	const candidate = memoryCandidateFor(ctx.runId, workingStateManager)
+	if (promoteMemory && candidate) {
+		try {
+			await promoteMemory(candidate)
+		} catch (promoteErr) {
+			ctx.log.error('Memory promotion threw — the run is unaffected', {
+				[NAMZU.RUN_ID]: ctx.runId,
+				'exception.message': promoteErr instanceof Error ? promoteErr.message : String(promoteErr),
+			})
+		}
+	}
+
+	// --- Sandbox lifecycle: destroy after run ---
+	if (sandbox) {
+		const sandboxId = sandbox.id
+		const teardown = await teardownSandbox(sandbox, sandboxTeardownTimeoutMs)
+		if (teardown.kind === 'destroyed') {
+			await eventTranslator.emitEvent({
+				type: 'sandbox_destroyed',
+				runId: ctx.runId,
+				sandboxId,
+			})
+			yield* eventTranslator.drainPending()
+			ctx.log.info('Sandbox destroyed', { 'namzu.sandbox.id': sandboxId })
+		} else {
+			ctx.log.error('Sandbox destroy failed', {
+				'namzu.sandbox.id': sandboxId,
+				...errorAttributes(teardown.error),
+			})
+		}
+	}
+
+	unsubscribeTaskStore?.()
+	// Keyed by HOW it settled, not just that it did: a run that was
+	// cancelled and a run that hit its budget have very different
+	// duration distributions, and averaging them together describes
+	// neither.
+	recordRunDuration(ctx.runMgr.getRun().status ?? 'unknown', Date.now() - runStartedAt)
+	rootSpan.end()
+}

package/src/runtime/query/resume-pending.ts

@@ -4,6 +4,7 @@ import type { RunPersistence } from '../../manager/run/persistence.js'
 import { ToolExecutionCollector } from '../../store/run/tool-executions.js'
 import type {
 	CheckpointId,
+	HITLDecisionRequest,
 	HITLResumeDecision,
 	IterationCheckpoint,
 	ToolCallSummary,
@@ -31,6 +32,19 @@ import { isPauseForCall } from './tool-pause.js'
  * keeps the existing repair-and-re-decide behavior.
  */
 export interface PendingResumePlan {
+	/**
+	 * What produced this plan, and therefore whether it carries the human's
+	 * decision out or stands in for it.
+	 *
+	 * `'decision'` — the answer, applied to the calls the park was about.
+	 * `'recovery'` — the checkpoint's recorded and explicitly unknown outcomes,
+	 * replayed so that nothing runs twice. The caller resolves the park in both
+	 * cases — recovery answering the batch is what makes the question moot —
+	 * but only the first may write the human's decision down as what ended it.
+	 * Recording a decision recovery stood in for says the run carried out
+	 * something it did not.
+	 */
+	readonly source: 'decision' | 'recovery'
 	/**
 	 * The checkpoint the park was recorded on, so the caller can clear it
 	 * once the decision has actually been applied. Leaving it outstanding
@@ -122,6 +136,7 @@ export function planPendingResume(
 	if (!denials) return null
 
 	return {
+		source: 'decision',
 		checkpointId: checkpoint.id,
 		assistant,
 		response: synthesizeResponse(assistant),
@@ -131,6 +146,144 @@ export function planPendingResume(
 	}
 }
 
+/**
+ * The stable marker `supersededByRecovery` puts at the head of its reason.
+ *
+ * `resolvedAt` says a park ENDED; it does not say HOW, and `pause` is the
+ * action both endings share — `CheckpointManager.expire` records one for a
+ * park that ran out of time, this one records another for a park whose
+ * question crash recovery answered instead. A reader that tests
+ * `pending.decision.action` alone can tell neither from a run still holding
+ * the park, and the reason is the only field left to carry the difference.
+ *
+ * A constant rather than a sentence written at the call site, and a PREFIX
+ * rather than the whole string, because the sentence names which decision was
+ * superseded — informative to a person, unstable to a comparison. A consumer
+ * tests this; the tail is prose.
+ *
+ * Exported for the SDK's own readers. It is not on the package's public
+ * surface: a new field on the recorded decision would be, and this branch
+ * ships as a `patch`.
+ */
+export const PARK_SUPERSEDED_BY_RECOVERY = 'crash-recovery-superseded'
+
+/** Whether a recorded decision is the supersede marker rather than an answer. */
+export function isSupersededByRecovery(decision: HITLResumeDecision | undefined): boolean {
+	return (
+		decision?.action === 'pause' && (decision.reason ?? '').startsWith(PARK_SUPERSEDED_BY_RECOVERY)
+	)
+}
+
+/**
+ * What to record on a park whose batch crash recovery answered instead of the
+ * decision.
+ *
+ * Neither half of the obvious record is honest. Writing the human's decision
+ * down would say the run carried it out, when the calls it named were answered
+ * with an explicitly UNKNOWN outcome and nothing they asked for happened —
+ * `planPendingResume` refused that decision in the first place, which is why
+ * recovery spoke at all. Writing nothing would lose the fact that somebody
+ * answered, and leave `pending.decision` meaning two different things.
+ *
+ * The vocabulary already has one shape for "this park ended and no decision
+ * was carried out": `CheckpointManager.expire` records a `pause` carrying the
+ * reason, and says why it is not an `abort` ("that would read as somebody
+ * having refused it"). This is that shape, with
+ * {@link PARK_SUPERSEDED_BY_RECOVERY} at the head of the reason so the fact is
+ * comparable rather than prose, and the decision it superseded after it so the
+ * answer a human gave is still on the record.
+ */
+export function supersededByRecovery(decision: HITLResumeDecision): HITLResumeDecision {
+	return {
+		action: 'pause',
+		reason: `${PARK_SUPERSEDED_BY_RECOVERY}: crash recovery answered the tool batch this park asked about, so the decision that was given (${decision.action}) was not applied.`,
+	}
+}
+
+/**
+ * Whether the ordinary continue path carries `decision` out for a park that
+ * has no batch of tool calls to apply it to.
+ *
+ * {@link planPendingResume} covers the two arms whose decision has to REACH
+ * something: the calls a `tool_review` park is about, and the tool a
+ * `user_question` park is inside. An `iteration_checkpoint` park has neither,
+ * so it produces no plan — and "no plan" must not be read as "nothing
+ * happened". For this arm the decision IS the run's next move, and the loop
+ * that resumes carries it out by continuing; the park it answered therefore
+ * has to be resolved exactly as the other arms' are.
+ *
+ * The set is `handleHITLDecision`'s continue arm, deliberately: these are the
+ * decisions a resumed run carries out by going on. `pause` is not among them
+ * — it is "hold this, I am not answering now", which the live path leaves the
+ * park standing for, and a resumed run does not honour it either. Neither are
+ * `abort` and `reject_plan`: nothing on the resume path acts on them, so
+ * recording one as the park's answer would say the run carried out something
+ * it did not.
+ */
+export function isCarriedOutByContinue(decision: HITLResumeDecision): boolean {
+	switch (decision.action) {
+		case 'continue':
+		case 'approve_tools':
+		case 'modify_tools':
+		case 'reject_tools':
+		case 'answer_question':
+			return true
+		default:
+			return false
+	}
+}
+
+/**
+ * Whether `decision` is a verdict on the question a `plan_approval` park asks.
+ *
+ * The plan arm was the one park `isCarriedOutByContinue` did not cover and
+ * nothing else did either, so a run resumed with `{action: 'approve_plan'}`
+ * completed with its park still outstanding: `findPendingCheckpoint` kept
+ * serving a plan nobody was waiting on, a second resume of the FINISHED run
+ * was refused `awaiting-decision`, and `prune`'s refusal to collect an
+ * unresolved park left the row uncollectable — with no `hitlParkTtlMs` there
+ * is no `deadlineAt`, so `expire` cannot reach it either.
+ *
+ * Both verdicts answer it, and that is the difference from `pause` (which
+ * HOLDS the park rather than answering it, on the live path and here) and
+ * from `abort` (which is not a verdict on the plan at all). What the resumed
+ * run can do about the answer afterwards is a separate question and not this
+ * predicate's: the record's `decision` is what the HUMAN answered, and a park
+ * is not made outstanding again by the new process having no plan to act on.
+ */
+export function isPlanVerdict(decision: HITLResumeDecision): boolean {
+	return decision.action === 'approve_plan' || decision.action === 'reject_plan'
+}
+
+/**
+ * Whether a park of `type` is ANSWERED by `decision` on the resume path.
+ *
+ * The map from park to the decision that answers it, in one place, because
+ * each arm was added by a different fix and the two that were missed were
+ * missed by being absent rather than wrong. `tool_review` and `user_question`
+ * are deliberately not here: their decisions have to REACH something —
+ * `planPendingResume` applies them to the parked batch — and their parks are
+ * resolved where that plan is applied, not by this predicate.
+ *
+ * "Answered" is the ordinary continue path carrying the decision out, which
+ * for the cadence arm means the loop going on and for the plan arm means the
+ * verdict having been given. It does not mean the run did everything the
+ * decision implies — see {@link isPlanVerdict}.
+ */
+export function answersParkOf(
+	parkType: HITLDecisionRequest['type'] | undefined,
+	decision: HITLResumeDecision,
+): boolean {
+	switch (parkType) {
+		case 'iteration_checkpoint':
+			return isCarriedOutByContinue(decision)
+		case 'plan_approval':
+			return isPlanVerdict(decision)
+		default:
+			return false
+	}
+}
+
 /**
  * Resume a batch that parked inside a tool asking the user a question.
  *
@@ -183,6 +336,7 @@ function planQuestionResume(
 	}
 
 	return {
+		source: 'decision',
 		checkpointId: checkpoint.id,
 		assistant,
 		response: synthesizeResponse(assistant),
@@ -228,6 +382,10 @@ export function planCrashResume(
 	})
 
 	return {
+		// Not the human's decision — recovery's own reading of the batch. The
+		// caller resolves the park either way and must not write the decision
+		// down as what ended it; see {@link supersededByRecovery}.
+		source: 'recovery',
 		checkpointId: checkpoint.id,
 		assistant,
 		response: synthesizeResponse(assistant),

package/src/types/run/config.ts

@@ -101,11 +101,18 @@ export interface AgentRunConfig {
 
 	/**
 	 * After creating an iteration checkpoint, prune the run's checkpoint
-	 * set down to the newest N (oldest-first deletion across ALL of the
-	 * run's checkpoints, including tool-review/plan ones). Default
-	 * `undefined` — never prune, today's behavior. Each checkpoint copies
-	 * the full message array, so long tool-heavy runs grow O(iterations ×
-	 * history) without this.
+	 * set down to the newest N. Default `undefined` — never prune, today's
+	 * behavior. Each checkpoint copies the full message array, so long
+	 * tool-heavy runs grow O(iterations × history) without this.
+	 *
+	 * Oldest-first by `createdAt`, across all of the run's checkpoints — but
+	 * a checkpoint whose park is UNRESOLVED is never collected, whatever its
+	 * age. Those rows are what `findPendingCheckpoint` serves to an approval
+	 * queue and what `listExpiredParks` enumerates for a sweep, so pruning
+	 * briefly holds more than N while a park is outstanding; the next prune
+	 * after the park resolves — by `unpark`, or by `expire` for one that ran
+	 * out of time — collects them. A host that needs the bound to hold
+	 * regardless should sweep expired parks itself.
 	 */
 	pruneKeepLast?: number