@namzu/sdk 43.0.0 → 44.1.0

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

@@ -1,27 +1,29 @@
 import { isDeepStrictEqual } from 'node:util'
 
-import type { RunPersistence } from '../../manager/run/persistence.js'
-import { ToolExecutionCollector } from '../../store/run/tool-executions.js'
+import type { TurnRecorder } from '../../manager/session/turn-recorder.js'
 import type {
 	CheckpointId,
 	HITLDecisionRequest,
 	HITLResumeDecision,
-	IterationCheckpoint,
+	ToolCallEscalation,
 	ToolCallSummary,
 } from '../../types/hitl/index.js'
+import type { MessageId } from '../../types/ids/index.js'
 import type { AssistantMessage, Message, ToolCall } from '../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../types/provider/index.js'
-import type { ToolExecutionSnapshot } from '../../types/run/store.js'
+import type { ToolExecutionSnapshot } from '../../types/session/tool-execution.js'
 import type { Logger } from '../../utils/logger.js'
+import type { RestoredCheckpoint } from './checkpoint.js'
 import type { PriorToolResults, ToolCallDenials, ToolExecutor } from './executor.js'
 import { PendingAnswers } from './question-park.js'
+import { readToolExecutions } from './tool-executions.js'
 import { isPauseForCall } from './tool-pause.js'
 
 /**
- * Apply a decision collected out-of-band to the tool calls a run parked on.
+ * Apply a decision collected out-of-band to the tool calls a turn parked on.
  *
  * This is the half of durable HITL that actually pays off. Recording the
- * park makes the request survive a restart; without this, a resumed run
+ * park makes the request survive a restart; without this, a resumed turn
  * still threw the approval away — the restore path repairs the unanswered
  * `tool_use` blocks and lets the model re-decide, so a human's "yes, delete
  * that row" became "ask the model again and hope it asks for the same
@@ -41,7 +43,7 @@ export interface PendingResumePlan {
 	 * 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
+	 * Recording a decision recovery stood in for says the turn carried out
 	 * something it did not.
 	 */
 	readonly source: 'decision' | 'recovery'
@@ -61,6 +63,8 @@ export interface PendingResumePlan {
 	readonly reviewedCalls?: readonly ToolCallSummary[]
 	/** Calls whose raw input the human replaced in the durable decision. */
 	readonly modifiedCallIds?: ReadonlySet<string>
+	/** Calls whose sandbox escape the durable decision confirmed; see `HITLResumeDecision`. */
+	readonly confirmedEscalations?: readonly string[]
 	/**
 	 * Answers to deliver to tools that parked on a question, keyed by the
 	 * asking call's id. Present only on a question resume.
@@ -81,7 +85,7 @@ export interface PendingResumePlan {
  * here and says so rather than pretending.
  */
 export function planPendingResume(
-	checkpoint: IterationCheckpoint,
+	checkpoint: RestoredCheckpoint,
 	decision: HITLResumeDecision,
 	log: Logger,
 ): PendingResumePlan | null {
@@ -143,6 +147,10 @@ export function planPendingResume(
 		denials,
 		reviewedCalls: pending.request.toolCalls,
 		modifiedCallIds: modifiedCallIds(decision),
+		...((decision.action === 'approve_tools' || decision.action === 'modify_tools') &&
+		decision.confirmedEscalations
+			? { confirmedEscalations: decision.confirmedEscalations }
+			: {}),
 	}
 }
 
@@ -153,7 +161,7 @@ export function planPendingResume(
  * 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
+ * `pending.decision.action` alone can tell neither from a turn 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
@@ -179,7 +187,7 @@ export function isSupersededByRecovery(decision: HITLResumeDecision | undefined)
  * 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
+ * down would say the turn 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
@@ -208,16 +216,16 @@ export function supersededByRecovery(decision: HITLResumeDecision): HITLResumeDe
  * 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
+ * happened". For this arm the decision IS the turn'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
+ * decisions a resumed turn 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
+ * park standing for, and a resumed turn 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
+ * recording one as the park's answer would say the turn carried out something
  * it did not.
  */
 export function isCarriedOutByContinue(decision: HITLResumeDecision): boolean {
@@ -237,7 +245,7 @@ export function isCarriedOutByContinue(decision: HITLResumeDecision): boolean {
  * 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'}`
+ * nothing else did either, so a turn 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
@@ -267,7 +275,7 @@ export function isPlanVerdict(decision: HITLResumeDecision): boolean {
  *
  * "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
+ * verdict having been given. It does not mean the turn did everything the
  * decision implies — see {@link isPlanVerdict}.
  */
 export function answersParkOf(
@@ -301,7 +309,7 @@ export function answersParkOf(
  * on.
  */
 function planQuestionResume(
-	checkpoint: IterationCheckpoint,
+	checkpoint: RestoredCheckpoint,
 	decision: HITLResumeDecision,
 	questionId: string,
 	log: Logger,
@@ -355,7 +363,7 @@ function planQuestionResume(
  * outcome, not executed again. An untouched batch uses ordinary history repair.
  */
 export function planCrashResume(
-	checkpoint: IterationCheckpoint,
+	checkpoint: RestoredCheckpoint,
 	completed: ReadonlyMap<string, unknown>,
 	log: Logger,
 ): PendingResumePlan | null {
@@ -404,14 +412,15 @@ export function planCrashResume(
  */
 export async function applyPendingResume(
 	plan: PendingResumePlan,
-	runMgr: RunPersistence,
+	recorder: TurnRecorder,
 	executor: ToolExecutor,
 	prior?: PriorToolResults,
+	assistantMessageId?: MessageId,
 ): Promise<void> {
 	const denials = new Map(plan.denials)
 	const reviewedById = new Map(plan.reviewedCalls?.map((call) => [call.id, call]))
 
-	// A gate denial belongs to the run, not to the process that first evaluated
+	// A gate denial belongs to the turn, not to the process that first evaluated
 	// it. Restore it before preparation so denied calls do not even reach a
 	// pre-tool hook after restart.
 	for (const call of plan.reviewedCalls ?? []) {
@@ -440,7 +449,7 @@ export async function applyPendingResume(
 				const reason =
 					'The tool input changed after its durable review; the earlier approval cannot be reused.'
 				denials.set(call.id, reason)
-				await runMgr.recordAudit({
+				await recorder.recordAudit({
 					what: { action: 'tool_call', tool: call.name },
 					outcome: 'refused',
 					reason,
@@ -462,21 +471,79 @@ export async function applyPendingResume(
 				'The durable review predates bound authorization metadata; review this call again before execution.'
 		}
 
+		reason ??= escalationRefusal(
+			call.escalation,
+			reviewed,
+			wasModified,
+			plan.confirmedEscalations,
+			call.id,
+		)
+
 		if (reason) {
 			denials.set(call.id, reason)
-			await runMgr.recordAudit({
-				what: { action: 'tool_call', tool: call.name },
+			await recorder.recordAudit({
+				what: { action: call.escalation ? 'sandbox_escape' : 'tool_call', tool: call.name },
 				outcome: 'refused',
 				reason,
 			})
+			continue
+		}
+		if (call.escalation?.sandboxEscape) {
+			await recorder.recordAudit({
+				what: { action: 'sandbox_escape', tool: call.name },
+				outcome: 'approved',
+				reason: 'the reviewer confirmed this call by id, answered across a restart',
+			})
+		}
+		for (const path of call.escalation?.outsidePaths ?? []) {
+			await recorder.recordAudit({
+				what: { action: 'outside_root_access', tool: call.name, resource: path },
+				outcome: 'approved',
+				reason: "the turn's review approved this call, answered across a restart",
+			})
 		}
 	}
 
-	runMgr.pushMessage(plan.assistant)
+	// The parked assistant message is already in the log: it goes back into
+	// the context under its own record id, never as a second copy.
+	recorder.pushMessage(plan.assistant, assistantMessageId ? { messageId: assistantMessageId } : {})
 	const batch = await executor.executeBatch(plan.response, denials, prior, preparedBatch)
 	for (const msg of batch.messages) {
-		runMgr.pushMessage(msg)
+		recorder.pushMessage(msg)
+	}
+}
+
+/**
+ * Why a re-prepared call's escalation may not run on a durable decision, or
+ * `undefined` when the decision covers it.
+ *
+ * The approval was given to what the reviewer was SHOWN. A call re-prepared
+ * in this process may reach further than that — a directory was removed
+ * from the session, a hook rewrote the path — and the decision says nothing
+ * about the difference. So every path it reaches must have been in the
+ * reviewed escalation, an escape must have been shown AND confirmed by id,
+ * and a call nobody reviewed, or whose input was modified afterwards, gets
+ * no escalation at all.
+ */
+export function escalationRefusal(
+	escalation: ToolCallEscalation | undefined,
+	reviewed: ToolCallSummary | undefined,
+	wasModified: boolean,
+	confirmed: readonly string[] | undefined,
+	id: string,
+): string | undefined {
+	if (!escalation) return undefined
+	const refusal =
+		"Refused after resume: this call reaches past the turn's boundary, and the durable approval does not cover what it reaches now. Ask for the approval again."
+	if (!reviewed || wasModified) return refusal
+	const shown = reviewed.escalation
+	for (const path of escalation.outsidePaths ?? []) {
+		if (!shown?.outsidePaths?.includes(path)) return refusal
 	}
+	if (escalation.sandboxEscape && (!shown?.sandboxEscape || !confirmed?.includes(id))) {
+		return 'Refused after resume: running this command outside the sandbox needs a person to confirm it for this call, and the durable approval did not.'
+	}
+	return undefined
 }
 
 function modifiedCallIds(decision: HITLResumeDecision): ReadonlySet<string> {
@@ -495,7 +562,7 @@ function modifiedCallIds(decision: HITLResumeDecision): ReadonlySet<string> {
  * replay; an explicitly answered durable question may re-enter its own tool.
  */
 export async function recoverCompletedCalls(
-	runMgr: RunPersistence,
+	recorder: TurnRecorder,
 	toolCalls: readonly ToolCall[],
 	log: Logger,
 	options: { answers?: PendingAnswers; signal?: AbortSignal } = {},
@@ -503,23 +570,13 @@ export async function recoverCompletedCalls(
 	const recovered = new Map<string, { result: string; isError: boolean }>()
 	let snapshot: ToolExecutionSnapshot | undefined
 	try {
-		const store = runMgr.getRunStore()
-		if (store.readToolExecutions) {
-			snapshot = await store.readToolExecutions(
-				toolCalls.map((call) => call.id),
-				options.signal,
-			)
-		} else {
-			const collector = new ToolExecutionCollector(
-				runMgr.id,
-				toolCalls.map((call) => call.id),
-			)
-			for (const event of await store.readEvents({ integrity: 'strict' })) {
-				options.signal?.throwIfAborted()
-				collector.accept(event)
-			}
-			snapshot = collector.finish()
-		}
+		await recorder.flush()
+		snapshot = await readToolExecutions(
+			recorder.log,
+			recorder.turnId,
+			toolCalls.map((call) => call.id),
+			options.signal,
+		)
 	} catch (error) {
 		if (options.signal?.aborted) throw error
 		log.warn('Could not read the transcript to recover completed tool calls', {
@@ -611,7 +668,7 @@ function derriveDenials(
  * `executeBatch` consumes a provider response; on resume the response is
  * long gone and the checkpointed assistant turn is the surviving record of
  * it. Usage is zeroed rather than re-invented — those tokens were already
- * billed to the run that produced the turn, and the checkpoint restored
+ * billed to the turn that produced the turn, and the checkpoint restored
  * that total.
  */
 function synthesizeResponse(assistant: AssistantMessage): ChatCompletionResponse {

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

@@ -0,0 +1,153 @@
+import type { SessionCheckpointStore } from '../../store/checkpoint/index.js'
+import type { SessionLease, SessionLog } from '../../store/session-log/index.js'
+import { NamzuError } from '../../types/errors/index.js'
+import type { PendingDecision } from '../../types/hitl/index.js'
+import type {
+	SessionEventListener,
+	SessionLogReplay,
+	Turn,
+	TurnState,
+} from '../../types/session/index.js'
+import { type QueryParams, drainQueryWithSelectedResumeState } from './index.js'
+import { resolveSessionStorage } from './session-storage.js'
+import { type TurnStateScope, loadSelectedTurnContext } from './turn-state.js'
+
+/** What came of a {@link resumeSession} call. */
+export type ResumeOutcome =
+	| { readonly resumed: false; readonly reason: 'no-checkpoint' }
+	| {
+			readonly resumed: false
+			readonly reason: 'awaiting-decision'
+			/** What to put in front of a human. */
+			readonly pending: PendingDecision
+			readonly state: TurnState
+	  }
+	| {
+			readonly resumed: true
+			readonly turn: Turn
+			readonly state: TurnState
+			/** What became of `eventCursor`. Absent when no cursor was supplied. */
+			readonly replay?: SessionLogReplay
+	  }
+
+/**
+ * The half of a turn that cannot be serialized, plus where to look.
+ *
+ * `messages` is absent: on resume the context is the fold of the session log
+ * through the checkpoint. `turnId` and `resumeFromCheckpoint` come from the
+ * scope and the selected checkpoint.
+ */
+export interface ResumeSessionParams
+	extends Omit<QueryParams, 'messages' | 'turnId' | 'resumeFromCheckpoint'> {
+	/** Identifies the paused turn. */
+	readonly scope: TurnStateScope
+	/** The session log the turn lives in. */
+	readonly sessionLog: SessionLog
+	/**
+	 * Where the turn's checkpoints are; also threaded into the resumed turn.
+	 * Default: the store beside `sessionLog` — in memory for an in-memory
+	 * log, otherwise under `paths` (or the working directory's project under
+	 * `NAMZU_HOME`), the same store `query()` wrote them to.
+	 */
+	readonly checkpointStore?: SessionCheckpointStore
+	/** The lease this worker took with `claimSession` before resuming. */
+	readonly lease?: SessionLease
+	/**
+	 * Resume a specific checkpoint instead of the one the store would pick.
+	 * Absent means the checkpoint an open decision references, else the newest.
+	 */
+	readonly checkpointId?: TurnState['checkpointId']
+	/** Where to send the resumed turn's events. */
+	readonly listener?: SessionEventListener
+}
+
+/**
+ * Continue a paused or interrupted turn of a session, in this process: the
+ * SAME session and the SAME `turnId`. The outcomes are `no-checkpoint`,
+ * `awaiting-decision` and `resumed`.
+ *
+ * The caller brings what cannot be serialized — the provider, the tool
+ * registry, the sandbox, the working directory — and the log and the
+ * checkpoint store bring the state. A missing checkpoint does not silently
+ * become a fresh turn, and a park is not resumed past without the answer it
+ * is waiting for (`pendingDecision`).
+ */
+export async function resumeSession(params: ResumeSessionParams): Promise<ResumeOutcome> {
+	const { scope, sessionLog, checkpointId, pendingDecision, listener, onEventReplay, ...rest } =
+		params
+	const checkpointStore =
+		params.checkpointStore ??
+		(
+			await resolveSessionStorage({
+				sessionId: scope.sessionId,
+				...(scope.parentSessionId ? { parentSessionId: scope.parentSessionId } : {}),
+				sessionLog,
+				...(params.paths ? { paths: params.paths } : {}),
+				...(params.workingDirectory ? { workingDirectory: params.workingDirectory } : {}),
+			})
+		).checkpoints
+
+	const selected = await loadSelectedTurnContext(sessionLog, checkpointStore, scope, checkpointId)
+	const state = selected?.state
+	if (!state?.checkpointId || !selected) return { resumed: false, reason: 'no-checkpoint' }
+	assertResumeRequestAttribution(params, state)
+
+	// A park is outstanding until it is answered.
+	const outstanding = state.pending && !state.pending.resolvedAt ? state.pending : undefined
+	if (outstanding && !pendingDecision) {
+		return { resumed: false, reason: 'awaiting-decision', pending: outstanding, state }
+	}
+
+	let replay: SessionLogReplay | undefined
+	const turn = await drainQueryWithSelectedResumeState(
+		{
+			...rest,
+			messages: [],
+			turnId: state.turnId,
+			sessionId: state.sessionId,
+			topicId: state.topicId,
+			projectId: state.projectId,
+			tenantId: state.tenantId,
+			...(state.parentSessionId !== undefined ? { parentSessionId: state.parentSessionId } : {}),
+			...(state.parentTurnId !== undefined ? { parentTurnId: state.parentTurnId } : {}),
+			resumeFromCheckpoint: state.checkpointId,
+			sessionLog,
+			checkpointStore,
+			...(pendingDecision ? { pendingDecision } : {}),
+			onEventReplay: (verdict: SessionLogReplay) => {
+				replay = verdict
+				return onEventReplay?.(verdict)
+			},
+		} as QueryParams,
+		{
+			...state,
+			checkpointId: state.checkpointId,
+			...(selected.checkpoint.trace ? { traceContext: selected.checkpoint.trace } : {}),
+			messageIds: selected.messageIds,
+		},
+		listener,
+	)
+
+	return { resumed: true, turn, state, ...(replay !== undefined ? { replay } : {}) }
+}
+
+function assertResumeRequestAttribution(params: ResumeSessionParams, state: TurnState): void {
+	const mismatchedFields: string[] = []
+	if (params.scope.turnId !== state.turnId) mismatchedFields.push('turnId')
+	if (params.sessionId !== state.sessionId) mismatchedFields.push('sessionId')
+	if (params.sessionLog.sessionId !== state.sessionId) mismatchedFields.push('sessionLog')
+	if (params.topicId !== state.topicId) mismatchedFields.push('topicId')
+	if (params.projectId !== state.projectId) mismatchedFields.push('projectId')
+	if (params.tenantId !== state.tenantId) mismatchedFields.push('tenantId')
+	if (params.parentSessionId !== undefined && params.parentSessionId !== state.parentSessionId) {
+		mismatchedFields.push('parentSessionId')
+	}
+	if (mismatchedFields.length === 0) return
+
+	throw new NamzuError({
+		code: 'invalid_config',
+		message:
+			'The resume request attribution does not match the checkpoint scope selected for this turn.',
+		details: { fields: mismatchedFields },
+	})
+}