@namzu/sdk 42.0.2 → 44.0.0

package/src/types/run/config.ts

@@ -1,221 +0,0 @@
-import type { TokenBudget } from '../../run/token-budget.js'
-import type { ModelPricing } from '../../utils/cost.js'
-import type { Logger } from '../../utils/logger.js'
-import type { RunId, SessionId, TenantId } from '../ids/index.js'
-import type { PermissionMode } from '../permission/index.js'
-import type { ProjectId, TopicId } from '../session/ids.js'
-import type { CheckpointStore } from './checkpoint-store.js'
-
-export interface AgentRunConfig {
-	model: string
-	/** Total run duration in milliseconds; 0 disables the run deadline. */
-	timeoutMs: number
-	/**
-	 * Maximum silence between provider stream chunks, in milliseconds.
-	 *
-	 * Defaults to five minutes at the `query()` boundary. This is distinct
-	 * from `timeoutMs`, which is checked between agent iterations and cannot
-	 * settle a provider iterator whose pending `next()` never returns. Set
-	 * `0` to retain unbounded stream silence. Positive values must be integer
-	 * milliseconds accepted by the platform timer.
-	 */
-	streamIdleTimeoutMs?: number
-	/**
-	 * Maximum accumulated inline image/document payload on one provider request.
-	 *
-	 * Defaults to 24 MiB. The budget is shared by user attachments and rich
-	 * tool-result blocks. When history exceeds it, the provider-bound projection
-	 * replaces the oldest values with model-visible omission markers; the run's
-	 * canonical messages and durable evidence remain unchanged. Set `0` to keep
-	 * the prior unbounded behaviour.
-	 */
-	maxRequestRichContentBytes?: 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
-
-	/**
-	 * How much work the model should spend on each call in the run.
-	 *
-	 * A SIBLING of {@link AgentRunConfig.thinking}, not a field inside it.
-	 * On some models the two are independent controls that apply together —
-	 * effort shapes the answer while a budget sets thinking depth — so
-	 * nesting one inside the other would make that combination unsayable.
-	 *
-	 * The failure this closes is the one this codebase keeps finding: the
-	 * field existed on the provider params, a driver already read it and
-	 * wrote it to the wire, and nothing in the kernel ever set it. So a
-	 * caller could not reach it at all, and the symptom — every request
-	 * going out at the model's default — reads as "this model ignores
-	 * effort" rather than "nobody plumbed it through".
-	 *
-	 * Run-level rather than per-step, deliberately. It is a property of what
-	 * the run is FOR, and a value that moves between steps buys a different
-	 * answer shape at the cost of the prompt-cache prefix on every step that
-	 * changes it.
-	 *
-	 * A driver that cannot honour it REFUSES rather than dropping it, on the
-	 * same reasoning as `thinking`: paying for a run you believe was
-	 * high-effort and silently was not is worse than a startup error.
-	 */
-	effort?: import('../provider/index.js').ReasoningEffort
-	/** Provider-hosted search for this run. Explicit opt-in; no local network permission. */
-	webSearch?: import('../provider/index.js').ChatCompletionParams['webSearch']
-	/** Cumulative parent-and-descendant tokens; 0 is unlimited with usage accounting. */
-	tokenBudget: number
-	costLimitUsd?: number
-	/** Main-loop iterations; 0 disables this guard. Omitted defaults depend on the entry point. */
-	maxIterations?: number
-	temperature?: number
-	env?: Record<string, string>
-	permissionMode?: PermissionMode
-	sandbox?: {
-		timeoutMs?: number
-		memoryLimitMb?: number
-		maxProcesses?: number
-		/**
-		 * What the sandbox is rooted at — see `SandboxConfigSchema.workspace`.
-		 * Absent means `'ephemeral'`: a fresh temp directory, which is the
-		 * behaviour every sandboxed run had before this existed.
-		 */
-		workspace?: 'ephemeral' | 'working-directory'
-	}
-
-	/**
-	 * Iteration-checkpoint cadence: create a checkpoint on every Nth
-	 * tool-call iteration (iterations 1, 1+N, 1+2N, …). Default `1` —
-	 * a checkpoint per iteration, today's behavior. Values < 1 are
-	 * treated as 1. Off-cadence iterations also skip the HITL
-	 * `iteration_checkpoint` park (there is no checkpoint id to park on).
-	 * Tool-review and plan-approval checkpoints are unaffected — those
-	 * exist to anchor a pending HITL decision, not for growth control.
-	 */
-	checkpointEvery?: number
-
-	/**
-	 * After creating an iteration checkpoint, prune the run's checkpoint
-	 * 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
-
-	/**
-	 * 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
-
-	/**
-	 * Override the logger a run's log lines derive from.
-	 *
-	 * This is an override of the SOURCE, not a substitute for correlation:
-	 * `RunContextFactory.buildLogger` always calls `.child()` on whichever
-	 * logger this resolves to, so a host-supplied logger still gains
-	 * `namzu.run.id`, `sessionId`, `threadId`, `projectId` and `tenantId` —
-	 * the same binding the process default gets. A host that wants its own
-	 * sink, format or destination threaded through every record a run
-	 * produces sets this once; a host that wants the process default
-	 * (`getRootLogger()`) sets nothing, which is what absent has always
-	 * meant.
-	 */
-	logger?: Logger
-}
-
-/**
- * Config for {@link RunPersistence}. `sessionId`, `topicId`, `tenantId`,
- * and `projectId` are required — every Run is attributed across the full
- * five-layer scope (Tenant → Project → Topic → Session → Run,
- * Convention #17).
- */
-export interface RunPersistenceConfig {
-	/** Shared account for this invocation and its delegated descendants. */
-	budget?: TokenBudget
-	runId: RunId
-	agentId: string
-	agentName: string
-	runConfig: AgentRunConfig
-	providerId: string
-	outputDir: string
-	pricing?: ModelPricing
-	log: Logger
-
-	sessionId: SessionId
-	topicId: TopicId
-	tenantId: TenantId
-	projectId: ProjectId
-
-	parentRunId?: RunId
-
-	depth?: number
-
-	/**
-	 * Optional checkpoint persistence override. Defaults to the disk
-	 * layout under `outputDir` (a
-	 * {@link import('../../store/run/checkpoint-disk.js').DiskCheckpointStore});
-	 * hosts inject a scope-keyed backend (e.g. Postgres) here.
-	 */
-	checkpointStore?: CheckpointStore
-
-	/**
-	 * Optional run-evidence persistence override. Defaults to the disk layout
-	 * under `outputDir` (a
-	 * {@link import('../../store/run/disk.js').RunDiskStore}); hosts inject
-	 * their own backend here.
-	 *
-	 * The sibling of `checkpointStore`, and it should have been one from the
-	 * start: checkpoints got an injectable seam while the run record, its
-	 * messages, its transcript and its report did not, so the evidence was
-	 * the one part of a run that could not leave the local filesystem.
-	 */
-	runStore?: import('./store.js').RunStore
-}
-
-export interface RunStoreConfig {
-	baseDir: string
-	logger?: Logger
-}
-
-export interface LimitCheckerConfig {
-	tokenBudget: number
-	timeoutMs: number
-	costLimitUsd?: number
-	maxIterations: number
-	budgetWarningThreshold: number
-}

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

@@ -1,62 +0,0 @@
-import type { RunExecutionStatus } 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 RunExecutionStatus} — 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: RunExecutionStatus
-	/** 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/emergency.ts

@@ -1,28 +0,0 @@
-import { z } from 'zod'
-import type { TokenUsage } from '../common/index.js'
-import type { EmergencySaveId, RunId } from '../ids/index.js'
-import type { Message } from '../message/index.js'
-import type { TokenBudgetBinding } from './token-budget-store.js'
-
-export interface EmergencySaveData {
-	/** Reference to the canonical tree ledger; a checkpoint never resets it. */
-	readonly budgetBinding?: TokenBudgetBinding
-	/** Also present for non-durable accounts; those require the live authority on resume. */
-	readonly budgetAccountId?: string
-	id: EmergencySaveId
-	runId: RunId
-	messages: Message[]
-	tokenUsage: TokenUsage
-	currentIteration: number
-	startedAt: number
-	savedAt: number
-	processSignal: string
-	lastError?: string
-}
-
-export const EmergencySaveConfigSchema = z.object({
-	enabled: z.boolean().default(true),
-	emergencyDir: z.string().optional(),
-})
-
-export type EmergencySaveConfig = z.infer<typeof EmergencySaveConfigSchema>

package/src/types/run/entity.ts

@@ -1,161 +0,0 @@
-import type { TokenBudgetSummary } from '../../run/token-budget.js'
-import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
-import type { RunId } from '../ids/index.js'
-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'
-import type { TokenBudgetBinding } from './token-budget-store.js'
-
-export interface RunStateMetadata {
-	/** This invocation's owner, independent of a shared ancestor token account. */
-	readonly scope?: {
-		readonly tenantId: string
-		readonly projectId: string
-		readonly sessionId: string
-		readonly runId: string
-	}
-	agentId: string
-	agentName: string
-	config: AgentRunConfig
-	/**
-	 * The provider the run was CONFIGURED with — the head of the chain, and
-	 * the counterpart of `config.model` beside it.
-	 *
-	 * It is a declaration, not an observation, and it stays one. After a
-	 * provider chain falls over it still names the head, which is correct for
-	 * a field that answers "what was asked for"; it was only ever misleading
-	 * because nothing else answered "what served". See {@link servingProvider}
-	 * for the run-level answer and `steps[].servedBy` for the per-step one.
-	 */
-	provider: string
-	/**
-	 * The chain member the run was routed to at the end, when that is not the
-	 * one it was configured with.
-	 *
-	 * Absent means the declared provider served every call. That reading holds
-	 * for stored records too, with one bounded exception: the sdk major that
-	 * shipped the chain could fall over without recording it, so a run from
-	 * that release reads as "no swap" whether or not there was one. Its
-	 * transcript still carries the `provider_fallback` events. The exception
-	 * is one release wide and it is stated rather than migrated away, because
-	 * a migration would have to invent the answer for exactly the records that
-	 * do not have it.
-	 *
-	 * **This is the durable half.** `RunDiskStore.writeRunMeta` writes
-	 * `metadata` and not `steps`, so on the built-in store this field is the
-	 * whole of what survives the process. `steps[].servedBy` is the finer
-	 * record — the one to read for "which member answered turn 4" — and it
-	 * reaches a host only on the returned `Run`.
-	 *
-	 * It also covers the case no step ledger can: a run that falls over and
-	 * then dies before a single step is recorded still has to be able to say
-	 * whose failure ended it. That is why the wording is "routed to" and not
-	 * "served by" — this member was asked, and on that path it answered with
-	 * an error. It is never a member that was merely selected: the chain
-	 * announces a replacement when it issues its request, not when it picks
-	 * it, so a run cancelled at the swap notice does not name one.
-	 */
-	servingProvider?: string
-}
-
-/**
- * Domain Run entity — the persistence record for a single agent invocation
- * under a {@link import('../session/entity.js').Session}. Renamed from
- * `AgentRun` on 2026-04-21 (ses_010 commit 7) to match the 5-layer hierarchy
- * (`Project → Thread → Session → SubSession → Run`) ratified in ses_001.
- *
- * The wire counterpart is `WireRun` under `contracts/api.ts` — the two stay
- * decoupled so the HTTP field shape can evolve independently from this
- * persistence record.
- */
-export interface Run {
-	id: RunId
-	status: RunExecutionStatus
-	metadata: RunStateMetadata
-	messages: Message[]
-	/** Usage of this invocation only; descendant spend is in budget. */
-	tokenUsage: TokenUsage
-	budget?: TokenBudgetSummary
-	budgetBinding?: TokenBudgetBinding
-	costInfo: CostInfo
-	currentIteration: number
-	startedAt: number
-	endedAt?: number
-	stopReason?: StopReason
-	lastError?: string
-	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
-
-	/**
-	 * Delegated tasks that were still running when this run ended.
-	 *
-	 * A run can settle while a worker it launched is still going — the model
-	 * answered, a terminal tool decided the result, a `stopWhen` fired. The
-	 * worker is NOT cancelled: giving up on a wait is a statement about the
-	 * waiter, not about the work, and killing a child that may be mid-write
-	 * because its parent finished early is a policy only the host can judge.
-	 * A host that wants them stopped has `cancel_task` and the run controller.
-	 *
-	 * What the kernel owes instead is not pretending the results arrived.
-	 * These ids are the honest form of that: the run says which work it walked
-	 * away from, so a host can reconcile, cancel, or wait on them itself.
-	 * Absent when a run ended with nothing outstanding.
-	 */
-	abandonedTaskIds?: readonly string[]
-
-	/**
-	 * Background jobs the model was waiting on that were still running when
-	 * this run ended.
-	 *
-	 * Only jobs `wait_for_job` named: a dev server nobody awaited is not work
-	 * this run walked away from, it is work it deliberately left behind. The
-	 * run holds itself open for these, bounded, and names the ones the bound
-	 * ran out on — the same honesty `abandonedTaskIds` owes for a delegated
-	 * worker, and with the same limit: naming a job is not stopping it. A
-	 * run-owned job is still stopped by the run's own teardown; one bound to
-	 * the host's session keeps running, which is what it was started for.
-	 */
-	abandonedJobIds?: readonly string[]
-
-	parentRunId?: RunId
-
-	depth?: number
-
-	/**
-	 * Present when this run was produced by {@link replay}. `undefined` for
-	 * original runs. See `ses_005-deterministic-replay` for the primitive.
-	 */
-	replayOf?: ReplayAttribution
-}
-
-/**
- * @deprecated Use {@link Run}. Alias retained for the 0.4.x compatibility
- * window; scheduled for removal in a later session.
- */
-export type AgentRun = Run
-
-/**
- * @deprecated Use {@link Run}. Alias retained for the 0.4.x compatibility
- * window; scheduled for removal in a later session.
- */
-export type AgentSession = Run

package/src/types/run/event-cursor.ts

@@ -1,118 +0,0 @@
-/**
- * Where a reconnecting consumer left off, and whether the kernel can honour it.
- *
- * The shortfall is a VALUE here, not a sentence in a document. A consumer that
- * asks for everything after sequence 400 and silently receives a splice from a
- * different generation of the run is wrong and has no way to find out; a
- * consumer handed `{ status: 'unavailable', reason: 'cursor_ahead' }` re-derives
- * from the transcript and is right. That is refuse-do-not-degrade applied to a
- * subscription rather than to a capability.
- */
-
-import type { FencingToken } from './checkpoint-store.js'
-import type { PersistedRunEvent } from './events.js'
-
-/** What a consumer holds when it comes back. */
-export interface RunEventCursor {
-	/**
-	 * The last `seq` the consumer actually received, from the envelope. Zero —
-	 * or the field absent — means "from the beginning".
-	 */
-	readonly sinceSeq: number
-	/**
-	 * The `generation` carried on the events the consumer received, when they
-	 * carried one.
-	 *
-	 * Compared for equality only. Absent on both sides is not a match and not a
-	 * mismatch: it is an unfenced run, where the sequence is the only evidence
-	 * available and the log persisting is the assumption.
-	 */
-	readonly generation?: FencingToken
-}
-
-/** Why a cursor could not be honoured. */
-export type RunEventReplayRefusal =
-	/**
-	 * The consumer claims to have seen more than the log holds.
-	 *
-	 * The ordinary cause is not a lying client: it is a log that did not
-	 * survive. An in-memory run store on a restarted process seeds at zero
-	 * while the consumer still holds 400, and this is the verdict that says so
-	 * instead of reporting a serene "you are up to date".
-	 */
-	| 'cursor_ahead'
-	/**
-	 * The run has been taken over since. The consumer's sequence numbers were
-	 * minted under an older claim and address a different sequence space, so
-	 * they are not comparable — not merely stale.
-	 */
-	| 'generation_changed'
-	/**
-	 * The store answered, and its oldest available event is above the one after
-	 * the cursor. A pruning or windowed backend, caught at the boundary rather
-	 * than delivered as a continuous stream with a hole in it.
-	 */
-	| 'gap'
-
-/** What came of a cursor. */
-export type RunEventReplay =
-	/** The cursor is already at the log's head. Nothing was missed. */
-	| { readonly status: 'complete' }
-	/** Contiguous from `sinceSeq + 1`, oldest first. */
-	| { readonly status: 'replayed'; readonly events: readonly PersistedRunEvent[] }
-	/** Nothing is delivered. The consumer re-derives from the transcript. */
-	| { readonly status: 'unavailable'; readonly reason: RunEventReplayRefusal }
-
-/** The log's present state, as the store reports it. */
-export interface RunEventLogHead {
-	/** Highest sequence in the log; zero when it is empty. */
-	readonly lastSeq: number
-	/** The fence the run is being written under, when it holds a claim. */
-	readonly generation?: FencingToken
-}
-
-/**
- * Decide what a cursor is owed, given what the log holds.
- *
- * Pure, and ordered deliberately: a takeover invalidates the sequence space, so
- * comparing sequences across generations would be arithmetic on two different
- * scales. The generation check therefore runs FIRST, before the numbers are
- * allowed to mean anything.
- *
- * `events` is what the store returned for `{ sinceSeq: cursor.sinceSeq }`. It is
- * passed in rather than fetched here so this stays a function of its arguments
- * — the property "no gap, no duplicate" is decidable from the three inputs, and
- * a test can drive every branch without a store.
- */
-export function resolveRunEventReplay(
-	cursor: RunEventCursor,
-	head: RunEventLogHead,
-	events: readonly PersistedRunEvent[],
-): RunEventReplay {
-	// Both sides must carry one for a mismatch to mean anything. An unfenced run
-	// has no generation to disagree with, and treating "absent" as a distinct
-	// value would refuse every run that never took a claim — which is most of
-	// them.
-	if (
-		cursor.generation !== undefined &&
-		head.generation !== undefined &&
-		cursor.generation !== head.generation
-	) {
-		return { status: 'unavailable', reason: 'generation_changed' }
-	}
-
-	if (cursor.sinceSeq > head.lastSeq) {
-		return { status: 'unavailable', reason: 'cursor_ahead' }
-	}
-
-	if (cursor.sinceSeq === head.lastSeq) return { status: 'complete' }
-
-	// The log says there is something above the cursor, so an empty answer is
-	// the store contradicting its own head rather than "nothing to send".
-	const first = events[0]
-	if (!first || first.seq !== cursor.sinceSeq + 1) {
-		return { status: 'unavailable', reason: 'gap' }
-	}
-
-	return { status: 'replayed', events }
-}