@namzu/sdk 2.0.0 → 3.1.0

package/src/types/run/__tests__/step.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest'
+
+import type { StepResult, StopConditionState } from '../step.js'
+import { anyOf, hasToolCall, stepCountIs } from '../step.js'
+
+/**
+ * The only halt before this was `GuardCoordinator`, which consumes
+ * `{aborted, totalTokens, totalCost, currentIteration, startTime}` and never
+ * sees messages, tool calls or results. So a terminal `submit_answer` tool
+ * could not end a run — the model had to be prompt-begged to stop, with
+ * `maxIterations: 200` or the token budget as the only backstop, which meant
+ * a finished task still burned its whole envelope.
+ */
+
+function step(n: number, toolNames: string[] = []): StepResult {
+	return {
+		stepNumber: n,
+		model: 'm',
+		messageId: `msg_${n}` as StepResult['messageId'],
+		content: null,
+		toolCalls: toolNames.map((name, i) => ({
+			id: `c${n}_${i}`,
+			type: 'function' as const,
+			function: { name, arguments: '{}' },
+		})),
+		toolResults: [],
+		finishReason: 'tool_calls',
+		usage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		costDelta: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
+		startedAt: 0,
+		durationMs: 0,
+		toolExecutionMs: 0,
+	}
+}
+
+function stateOf(steps: StepResult[]): StopConditionState {
+	const latestStep = steps[steps.length - 1]
+	if (!latestStep) throw new Error('need at least one step')
+	return {
+		steps,
+		latestStep,
+		totalUsage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		totalCost: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
+	}
+}
+
+describe('stepCountIs', () => {
+	it('is false before the count and true at it', async () => {
+		const condition = stepCountIs(3)
+		expect(await condition(stateOf([step(1), step(2)]))).toBe(false)
+		expect(await condition(stateOf([step(1), step(2), step(3)]))).toBe(true)
+	})
+
+	it('stays true past the count — it is a floor, not an equality', async () => {
+		expect(await stepCountIs(2)(stateOf([step(1), step(2), step(3)]))).toBe(true)
+	})
+})
+
+describe('hasToolCall', () => {
+	it('fires when the latest step called the named tool', async () => {
+		expect(await hasToolCall('submit_answer')(stateOf([step(1, ['submit_answer'])]))).toBe(true)
+	})
+
+	it('does not fire on an earlier step — only the latest one is examined', async () => {
+		const state = stateOf([step(1, ['submit_answer']), step(2, ['read'])])
+		expect(await hasToolCall('submit_answer')(state)).toBe(false)
+	})
+
+	it('accepts several names', async () => {
+		const condition = hasToolCall('submit_answer', 'give_up')
+		expect(await condition(stateOf([step(1, ['give_up'])]))).toBe(true)
+		expect(await condition(stateOf([step(1, ['read'])]))).toBe(false)
+	})
+
+	it('is false for a step with no tool calls at all', async () => {
+		expect(await hasToolCall('x')(stateOf([step(1)]))).toBe(false)
+	})
+})
+
+describe('anyOf', () => {
+	it('fires when any condition does', async () => {
+		const condition = anyOf(stepCountIs(99), hasToolCall('submit_answer'))
+		expect(await condition(stateOf([step(1, ['submit_answer'])]))).toBe(true)
+	})
+
+	it('is false when none fire', async () => {
+		const condition = anyOf(stepCountIs(99), hasToolCall('submit_answer'))
+		expect(await condition(stateOf([step(1, ['read'])]))).toBe(false)
+	})
+
+	it('short-circuits — a later condition is not consulted once one fires', async () => {
+		let consulted = false
+		const condition = anyOf(
+			() => true,
+			() => {
+				consulted = true
+				return false
+			},
+		)
+		expect(await condition(stateOf([step(1)]))).toBe(true)
+		expect(consulted).toBe(false)
+	})
+
+	it('awaits an async condition', async () => {
+		const condition = anyOf(async () => {
+			await Promise.resolve()
+			return true
+		})
+		expect(await condition(stateOf([step(1)]))).toBe(true)
+	})
+})

package/src/types/run/answer-review.ts

@@ -0,0 +1,51 @@
+import type { RunId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+
+/**
+ * A host's verdict on the answer a run is about to settle with.
+ *
+ * The halt predicate is only consulted after tools have run, so there was
+ * no seam at the point the model stops calling them: the run finalized
+ * with whatever it had produced. Verify-then-fix — run the build, feed the
+ * failure back, let it try again — meant starting a whole new run and
+ * re-supplying the context the first one had already assembled.
+ */
+export type AnswerReview =
+	| { readonly accept: true }
+	| {
+			readonly accept: false
+			/**
+			 * What to send back, as the user turn the model will read next.
+			 *
+			 * Prose rather than a code, because the model is the audience
+			 * and a code would have to be explained to it anyway. Say what
+			 * is wrong and what would satisfy the check — "the build fails
+			 * with X" gets a fix; "rejected" gets a paraphrase.
+			 */
+			readonly feedback: string
+	  }
+
+/** What the reviewer is told about the run it is judging. */
+export interface AnswerReviewContext {
+	readonly runId: RunId
+	readonly iteration: number
+	/** The full history, so a reviewer can see how the answer was reached. */
+	readonly messages: readonly Message[]
+}
+
+/**
+ * Judge a completed answer and either accept it or hand it back.
+ *
+ * Called only when the model stopped calling tools and the run is about to
+ * settle, and never on the forced-final turn — that one exists to extract
+ * a closing summary under pressure, and rejecting it would spend budget
+ * the run has already run out of.
+ *
+ * Bounded: see the run's answer-review limit. A reviewer that never
+ * accepts stops the run with a stop reason that names it, rather than
+ * looping until the token budget ends the run for an unrelated reason.
+ */
+export type ReviewAnswer = (
+	answer: string,
+	context: AnswerReviewContext,
+) => AnswerReview | Promise<AnswerReview>

package/src/types/run/config.ts

@@ -9,6 +9,15 @@ export interface AgentRunConfig {
 	model: string
 	timeoutMs: number
 	maxResponseTokens?: number
+
+	/**
+	 * Extended-thinking request, forwarded on every model call in the run.
+	 *
+	 * Drivers that do not support it ignore the field. Note that a provider
+	 * rejects temperature/top_p/top_k while thinking is enabled, so the
+	 * driver omits them rather than sending a request it knows will 400.
+	 */
+	thinking?: import('../provider/index.js').ThinkingConfig
 	tokenBudget: number
 	costLimitUsd?: number
 	maxIterations?: number
@@ -41,6 +50,32 @@ export interface AgentRunConfig {
 	 * history) without this.
 	 */
 	pruneKeepLast?: number
+
+	/**
+	 * How long a human-in-the-loop park stays worth serving, in ms.
+	 *
+	 * Written onto the park as an ABSOLUTE deadline, so it survives the
+	 * process that set it. Every timer in the SDK is an in-process
+	 * `setTimeout` and the park-record delay is deliberately `unref`'d, so
+	 * nothing in memory can outlive a redeploy: without this a run parks for
+	 * approval, the worker is replaced, nobody answers, and the checkpoint
+	 * stays outstanding forever — every approval-queue reader keeps serving
+	 * it and its workspace is never reclaimed.
+	 *
+	 * The run timeout does not cover this. It is only checked between
+	 * iterations and a park suspends mid-iteration, so a long-lived process
+	 * hard-stops the run immediately *after* the human finally approves,
+	 * while across a restart the restored elapsed clock excludes parked time
+	 * entirely — the same configuration producing two opposite outcomes.
+	 *
+	 * Expiry is enforced on READ (`findPendingCheckpoint` skips an expired
+	 * park) and by a host sweep (`listExpiredParks` + `CheckpointManager
+	 * .expire`). An out-of-process timer stays a host concern, consistent
+	 * with the same decision made for retention.
+	 *
+	 * Default `undefined` — no deadline, today's behaviour.
+	 */
+	hitlParkTtlMs?: number
 }
 
 /**

package/src/types/run/derive-status.ts

@@ -0,0 +1,62 @@
+import type { AgentStatus } from '../common/index.js'
+import type { PendingDecision } from '../hitl/index.js'
+import type { RunStatus } from './status.js'
+
+/**
+ * Project what the SDK records about a run onto the session-layer
+ * {@link RunStatus}.
+ *
+ * `Run.status` is an {@link AgentStatus} — six values, none of which can
+ * say "a human owes this run an answer". `RunStatus` has the vocabulary for
+ * that and is consumed by session-status derivation and by handoff gating,
+ * but nothing in the repo ever produced it: a host implementing a resolver
+ * had to invent the projection, and the two `awaiting_hitl*` variants in
+ * particular had no producer at all. `awaiting_hitl_resolution` documented
+ * a "persisted wait after a HITL timeout" for a timeout nothing could
+ * raise.
+ *
+ * The park record is the missing input. It is durable, it is what an
+ * approval queue already reads, and it carries the deadline that separates
+ * "waiting" from "waited too long".
+ */
+export function deriveRunStatus(input: {
+	/** What the run itself recorded. */
+	readonly status: AgentStatus
+	/** The run's outstanding park, if it has one. */
+	readonly park?: PendingDecision
+	/** Injectable for tests; defaults to now. */
+	readonly now?: number
+}): RunStatus {
+	const { status, park } = input
+	const now = input.now ?? Date.now()
+
+	// Terminal beats parked. A run that finished, failed or was cancelled
+	// is not waiting for anyone, whatever a stale park record says.
+	switch (status) {
+		case 'completed':
+			return 'succeeded'
+		case 'failed':
+			return 'failed'
+		case 'cancelled':
+			return 'cancelled'
+		case 'idle':
+		case 'pending':
+		case 'running':
+			break
+		default: {
+			const _exhaustive: never = status
+			throw new Error(`Unmapped agent status: ${_exhaustive as string}`)
+		}
+	}
+
+	if (park && park.resolvedAt === undefined) {
+		// A deadline that has passed means the window closed with nobody
+		// answering. The work is not lost and the run stays resumable from
+		// its checkpoint, so this is a persisted wait rather than a terminal
+		// state — which is exactly what the reserved variant describes.
+		const expired = park.deadlineAt !== undefined && now >= park.deadlineAt
+		return expired ? 'awaiting_hitl_resolution' : 'awaiting_hitl'
+	}
+
+	return status === 'running' ? 'running' : 'queued'
+}

package/src/types/run/entity.ts

@@ -4,6 +4,7 @@ import type { Message } from '../message/index.js'
 import type { ProviderErrorInfo } from '../provider/index.js'
 import type { AgentRunConfig } from './config.js'
 import type { ReplayAttribution } from './replay.js'
+import type { StepResult } from './step.js'
 import type { StopReason } from './stop-reason.js'
 
 export interface RunStateMetadata {
@@ -41,6 +42,23 @@ export interface Run {
 	lastProviderError?: ProviderErrorInfo
 	result?: string
 
+	/**
+	 * Per-iteration record of what the loop did. Absent on a run that
+	 * never entered the loop.
+	 *
+	 * A host that persists the returned `Run` used to lose all per-step
+	 * attribution: "which step cost the most" required correlating raw
+	 * RunEvents by iteration and diffing cumulative counters.
+	 */
+	steps?: readonly StepResult[]
+
+	/**
+	 * Schema-validated final output, when `structuredOutput` was requested
+	 * and the model produced one. Absent otherwise — check `stopReason`
+	 * for `structured_output_failed`.
+	 */
+	structuredOutput?: unknown
+
 	parentRunId?: RunId
 
 	depth?: number

package/src/types/run/events.ts

@@ -1,6 +1,6 @@
 import type { ActivityStatus, ActivityType } from '../activity/index.js'
 import type { BaseAgentResult } from '../agent/base.js'
-import type { CostInfo, TokenUsage } from '../common/index.js'
+import type { CostInfo, PlatformError, TokenUsage } from '../common/index.js'
 import type { CheckpointId, ToolCallSummary } from '../hitl/index.js'
 import type {
 	ActivityId,
@@ -14,7 +14,6 @@ import type {
 } from '../ids/index.js'
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
-import type { ProviderErrorInfo } from '../provider/index.js'
 import type { TaskStatus } from '../task/index.js'
 import type { Lineage } from './lineage.js'
 import type { MessageStopReason } from './stop-reason.js'
@@ -55,6 +54,37 @@ type CoreRunEvent =
 			iteration: number
 			hasToolCalls: boolean
 	  }
+	/**
+	 * A compaction pass replaced a span of history with a summary.
+	 *
+	 * Compaction deletes messages irrecoverably and previously emitted
+	 * nothing at all — a host could not show the user that context was
+	 * dropped, and `transcript.jsonl` recorded a conversation that silently
+	 * lost its middle. Every field here is measured, not estimated, where
+	 * the provider reported it (`measuredBy`).
+	 */
+	| {
+			type: 'compaction_completed'
+			runId: RunId
+			iteration: number
+			/** Messages before and after the pass. */
+			messagesBefore: number
+			messagesAfter: number
+			/** Context size in tokens before and after. */
+			tokensBefore: number
+			tokensAfter: number
+			/** Whether `tokensBefore` came from the provider or a heuristic. */
+			measuredBy: 'provider' | 'estimate'
+			/** The window the trigger measured against, and where it came from. */
+			contextWindowTokens: number
+			windowSource: 'config' | 'model-table' | 'default'
+			/**
+			 * False when the pass could not get the context below
+			 * `resetThreshold` — the trigger is still armed, and a host may
+			 * want to surface that the run is running tight.
+			 */
+			reachedResetThreshold?: boolean
+	  }
 	| {
 			type: 'tool_executing'
 			runId: RunId
@@ -62,6 +92,58 @@ type CoreRunEvent =
 			toolName: string
 			input: unknown
 	  }
+	/**
+	 * A tool saying how far along it is.
+	 *
+	 * Ephemeral — excluded from `transcript.jsonl`, like `text_delta`. It is
+	 * for a host rendering a live view, not part of the conversation, and a
+	 * chatty tool must not be able to bloat the durable record.
+	 *
+	 * Tools get a deadline of up to two minutes by default, so before this
+	 * a build, a test run or a long fetch was simply silent for its whole
+	 * duration: the host could show that a tool had started and then nothing
+	 * at all until it either finished or timed out. The model never sees
+	 * these; they answer "is it still working?", which is a question only a
+	 * human asks.
+	 */
+	| {
+			type: 'tool_progress'
+			runId: RunId
+			toolUseId: ToolUseId
+			toolName: string
+			/** Human-readable, e.g. "compiled 40/120 files". */
+			message: string
+			/** Optional completion in [0,1] when the tool genuinely knows it. */
+			fraction?: number
+	  }
+	/**
+	 * A model call failed transiently and is being retried after a backoff.
+	 *
+	 * Answers the same question `tool_progress` answers — "is it still
+	 * working?" — for the other half of a run's wall clock. With the default
+	 * policy, or a server-directed delay up to the cap, a run can sit silent
+	 * for the better part of a minute between `iteration_started` and the
+	 * next event. A host saw literally nothing and no keepalive, so a
+	 * backoff was indistinguishable from a hang and a watchdog would cancel
+	 * a run that was about to succeed.
+	 *
+	 * Emitted before the sleep, so the delay it names is the one still
+	 * ahead.
+	 */
+	| {
+			type: 'provider_retry'
+			runId: RunId
+			iteration: number
+			/** 1-based attempt that just failed. */
+			attempt: number
+			maxRetries: number
+			delayMs: number
+			/** Classified failure code, as the boundary classifier reports it. */
+			code: string
+			status?: number
+			/** The delay came from the server's own `Retry-After`. */
+			serverDirected: boolean
+	  }
 	| {
 			type: 'tool_completed'
 			runId: RunId
@@ -69,6 +151,63 @@ type CoreRunEvent =
 			toolName: string
 			result: string
 			isError: boolean
+			/**
+			 * Wall-clock the tool took. Computed since the first version of
+			 * the executor but only ever logged; a host asking "which tool
+			 * was slow" had to reconstruct it from event timestamps.
+			 */
+			durationMs?: number
+			/**
+			 * Size of the tool's output BEFORE the model-visible budget was
+			 * applied, so a host can report "returned 2.1 MB" even though
+			 * `result` is a preview.
+			 */
+			outputLength?: number
+			/** True when `result` is a preview rather than the whole output. */
+			outputTruncated?: boolean
+			/** Where the full output was written, when it was spilled. */
+			outputSpillPath?: string
+	  }
+	/**
+	 * A tool asked the user a question and the run is parked on it.
+	 *
+	 * The question used to park through the raw handler under a synthetic
+	 * checkpoint id that was never written, so a remote host could not
+	 * observe it at all — the in-process callback was the only channel, and
+	 * a tool review with the same shape had an event, a bridge mapping and
+	 * a durable record. This is that surface, for the other kind of park.
+	 */
+	| {
+			type: 'user_question_asked'
+			runId: RunId
+			checkpointId: CheckpointId
+			/** The asking `tool_use_id`, so an answer can be matched back. */
+			questionId: string
+			question: string
+	  }
+	/**
+	 * The question was resolved.
+	 *
+	 * `answered: false` covers a decline and a non-response. Distinguished
+	 * because the asking tool refuses to invent consent from either, and a
+	 * host rendering the card needs the same distinction.
+	 */
+	| {
+			type: 'user_question_answered'
+			runId: RunId
+			checkpointId: CheckpointId
+			/**
+			 * Which question, when the resolution named one.
+			 *
+			 * Its sibling `user_question_asked` carries this and the answer
+			 * did not, so a client that keyed on the question id — the
+			 * natural key, since it is what routes an answer back on resume
+			 * — could not match the two halves without also having stored
+			 * the checkpoint id. Absent when the pause was resolved without
+			 * an answer.
+			 */
+			questionId?: string
+			answered: boolean
 	  }
 	| {
 			type: 'tool_review_requested'
@@ -98,12 +237,58 @@ type CoreRunEvent =
 			runId: RunId
 			fromCheckpointId: CheckpointId
 	  }
+	/**
+	 * A guardrail blocked or rewrote the run.
+	 *
+	 * Emitted so a host can show WHY a run refused, and — for a rewrite —
+	 * so a consumer that already rendered `text_delta` events knows the
+	 * text it displayed has been corrected.
+	 */
+	| {
+			type: 'guardrail_triggered'
+			runId: RunId
+			stage: 'input' | 'output'
+			action: 'block' | 'rewrite'
+			guardrail?: string
+			reason?: string
+	  }
 	| { type: 'run_completed'; runId: RunId; result: string }
+	/**
+	 * The run failed.
+	 *
+	 * `error` is the flattened message, kept for every consumer that only
+	 * ever rendered a string. `failure` is the structured projection, and
+	 * it is the point: namzu already classifies at the provider boundary —
+	 * over status, errno, `Retry-After` and the whole cause chain — so a
+	 * fully-populated error genuinely arrived here and was flattened one
+	 * line later, discarding `code`, `status`, `retryAfterMs`, `retryable`
+	 * and `details`.
+	 *
+	 * The damage was self-inflicted downstream: one consumer substring-
+	 * matched the flattened message to decide whether an error had
+	 * occurred, and the iteration loop re-ran the classifier to recover
+	 * structure that had already been computed upstream.
+	 */
 	| {
 			type: 'run_failed'
 			runId: RunId
 			error: string
-			providerError?: ProviderErrorInfo
+			failure?: PlatformError
+			/**
+			 * The driver's own classification, when it produced one. Carried
+			 * beside `failure` rather than folded into it: this is the
+			 * provider's first-hand statement, and a consumer deciding whether
+			 * to retry reads it directly.
+			 */
+			providerError?: import('../provider/error.js').ProviderErrorInfo
+			/**
+			 * Operator-facing explanation, when a catalog rule claims this
+			 * failure: a stable `id` to grep for, and `hint` saying what to
+			 * change. Absent when no rule matched — inventing advice for an
+			 * uncharacterised failure is worse than saying nothing, because
+			 * it sends the reader somewhere specific and wrong.
+			 */
+			explanation?: { id: string; message: string; hint: string }
 	  }
 	// Additive 2026-07 (provider capability negotiation): emitted once per
 	// run when the request asks for something the provider DRIVER declared
@@ -239,6 +424,41 @@ type CoreRunEvent =
 			iteration: number
 			messageId: MessageId
 	  }
+	/**
+	 * The model began emitting a reasoning block.
+	 *
+	 * Without these, extended thinking looked to a streaming UI like a
+	 * multi-second stall with no events at all — the run was working, and
+	 * the host had no way to say so.
+	 */
+	| {
+			type: 'reasoning_started'
+			runId: RunId
+			iteration: number
+			messageId: MessageId
+			blockIndex: number
+			reasoningType: 'thinking' | 'redacted_thinking'
+	  }
+	/** Ephemeral — excluded from `transcript.jsonl`, like `text_delta`. */
+	| {
+			type: 'reasoning_delta'
+			runId: RunId
+			iteration: number
+			messageId: MessageId
+			blockIndex: number
+			text: string
+	  }
+	| {
+			type: 'reasoning_completed'
+			runId: RunId
+			iteration: number
+			messageId: MessageId
+			blockIndex: number
+			/** Present only when the provider returned readable thinking. */
+			text?: string
+			/** True when the block carried a signature that must be replayed. */
+			signed: boolean
+	  }
 	| {
 			type: 'text_delta'
 			runId: RunId
@@ -326,6 +546,13 @@ export type RunEventListener = (event: RunEvent) => void | Promise<void>
 const EPHEMERAL_EVENT_TYPES: ReadonlySet<RunEvent['type']> = new Set<RunEvent['type']>([
 	'text_delta',
 	'tool_input_delta',
+	// The completed block carries the full text; the deltas would only
+	// duplicate it into the transcript at scale.
+	'reasoning_delta',
+	// Answers "is it still working?", which only a live view asks. A tool
+	// reporting every file it compiles must not be able to write thousands
+	// of lines into the durable record.
+	'tool_progress',
 ])
 
 export function isEphemeralEvent(event: RunEvent): boolean {

package/src/types/run/index.ts

@@ -1,3 +1,5 @@
+export * from './step.js'
+export * from './prepare-step.js'
 export * from './stop-reason.js'
 export * from './config.js'
 export * from './checkpoint-store.js'
@@ -11,6 +13,7 @@ export * from './status.js'
 export * from './events.js'
 export * from './metadata.js'
 export * from './emergency.js'
+export * from './state.js'
 export type { Lineage } from './lineage.js'
 export type {
 	SubsessionIdledEvent,
@@ -20,3 +23,5 @@ export type {
 } from './subsession-events.js'
 export { RUN_EVENT_SCHEMA_VERSION } from './schema-version.js'
 export type { RunEventSchemaVersion } from './schema-version.js'
+export type { AnswerReview, AnswerReviewContext, ReviewAnswer } from './answer-review.js'
+export type { PromoteMemory, RunMemoryCandidate } from './memory-promotion.js'