@namzu/sdk 43.0.0 → 44.0.0

package/src/types/run/index.ts

@@ -1,32 +0,0 @@
-export * from './step.js'
-export * from './cancel-cause.js'
-export * from './prepare-step.js'
-export * from './stop-reason.js'
-export * from './config.js'
-export * from './checkpoint-store.js'
-export * from './audit.js'
-export * from './store.js'
-export * from './event-cursor.js'
-export * from './entity.js'
-export * from './replay.js'
-// Domain `RunStatus` (session-hierarchy.md §4.6 state machine). Safe to
-// re-export via `export *` now — the former wire-side `RunStatus` alias was
-// renamed to `WireRunStatus` in ses_010 commit 7, so there is no longer a
-// collision to avoid.
-export * from './status.js'
-export * from './events.js'
-export * from './metadata.js'
-export * from './emergency.js'
-export * from './state.js'
-export * from './token-budget-store.js'
-export type { Lineage } from './lineage.js'
-export type {
-	SubsessionIdledEvent,
-	SubsessionLifecycleEvent,
-	SubsessionMessagedEvent,
-	SubsessionSpawnedEvent,
-} 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'

package/src/types/run/lineage.ts

@@ -1,15 +0,0 @@
-import type { SessionId } from '../ids/index.js'
-
-/**
- * Parent/root linkage carried on every sub-session event.
- *
- * Per session-hierarchy.md §10.4 every `RunEvent` emitted from a sub-session
- * carries a {@link Lineage} so consumers can reconstruct the delegation tree
- * without walking the store. `depth` is 0 at the root session and grows by 1
- * per delegation level.
- */
-export interface Lineage {
-	parentSessionId: SessionId
-	rootSessionId: SessionId
-	depth: number
-}

package/src/types/run/memory-promotion.ts

@@ -1,112 +0,0 @@
-import type { RunId } from '../ids/index.js'
-
-/**
- * What a run learned, offered to whoever decides what is worth keeping.
- *
- * namzu could store a memory and could not *form* one. `MemoryStore` and
- * its disk implementation have been here all along, and the only path
- * into them is the model calling `save_memory` — so a run that worked out
- * a durable fact and never thought to write it down lost it at settle,
- * along with everything the compaction pass had already extracted and
- * structured on the way.
- *
- * The extraction is the part that was already built: the compaction pass
- * distils the transcript into decisions, discoveries, constraints and
- * failures precisely because a summary of prose is worth less than a list
- * of facts. That structure was serialized into one system message and
- * then dropped on the floor when the run ended.
- */
-export interface RunMemoryCandidate {
-	readonly runId: RunId
-	/** What the run was asked to do, as the extractor recorded it. */
-	readonly task: string
-	/** Choices the run made and did not revisit. */
-	readonly decisions: readonly string[]
-	/** Things it found out — the shape of a codebase, the name of a table. */
-	readonly discoveries: readonly string[]
-	/** What the user said must hold. The most durable category of the four. */
-	readonly userRequirements: readonly string[]
-	/** Approaches that failed, so a later run does not pay for them again. */
-	readonly failures: readonly string[]
-	/** Facts about the machine, the toolchain, the environment. */
-	readonly environment: readonly string[]
-	/** Files the run touched, by path. */
-	readonly files: readonly string[]
-	/**
-	 * How many entries each capped list dropped during the run.
-	 *
-	 * Carried rather than hidden: a host deciding whether this is worth
-	 * storing should know it is looking at a truncated record.
-	 */
-	readonly evicted: Readonly<Record<string, number>>
-}
-
-/**
- * Decide what a finished run should leave behind.
- *
- * Called once, when the run settles, with everything the compaction pass
- * extracted. Deliberately a callback rather than a store the runtime
- * writes into: what is worth remembering is a policy question the host
- * owns, and a runtime that decided it would be writing a row for every
- * run whether or not anything happened.
- *
- * Never blocks and never fails the run. It runs after the answer is
- * settled, so a throw is logged and swallowed — a memory that failed to
- * form must not retract an answer that was already produced. A host that
- * needs the write to be part of the run's success should do it in its own
- * code, where it can fail loudly.
- */
-export type PromoteMemory = (candidate: RunMemoryCandidate) => void | Promise<void>
-
-/**
- * Project the compaction pass's working state into a promotion candidate.
- *
- * A projection rather than the state itself, for the same reason the
- * plugin hooks got one: the working state is an internal structure with
- * caps, eviction counters and slot objects that exist to serve
- * compaction, and handing it over would make every future field of it
- * part of a host-facing contract by accident.
- */
-export function toMemoryCandidate(
-	runId: RunId,
-	state: {
-		task: string
-		decisions: string[]
-		discoveries: string[]
-		userRequirements: string[]
-		failures: string[]
-		environment: string[]
-		files: Map<string, unknown>
-		evicted: Record<string, number>
-	},
-): RunMemoryCandidate {
-	return {
-		runId,
-		task: state.task,
-		decisions: [...state.decisions],
-		discoveries: [...state.discoveries],
-		userRequirements: [...state.userRequirements],
-		failures: [...state.failures],
-		environment: [...state.environment],
-		files: [...state.files.keys()],
-		evicted: { ...state.evicted },
-	}
-}
-
-/**
- * The candidate for this run, or `undefined` when there is nothing to
- * offer.
- *
- * A separate function because "was anything extracted?" is a decision,
- * and a decision inlined into a `try` is one a test cannot tell apart
- * from the catch that swallows its failure. Without an extractor there
- * is no working state, and inventing an empty candidate would ask a host
- * to store a record of nothing.
- */
-export function memoryCandidateFor(
-	runId: RunId,
-	manager: { getState(): Parameters<typeof toMemoryCandidate>[1] } | undefined,
-): RunMemoryCandidate | undefined {
-	if (!manager) return undefined
-	return toMemoryCandidate(runId, manager.getState())
-}

package/src/types/run/metadata.ts

@@ -1,51 +0,0 @@
-import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
-import type { RunId, TaskId, TenantId } from '../ids/index.js'
-import type { ProjectId } from '../session/ids.js'
-import type { StopReason } from './stop-reason.js'
-
-/**
- * Denormalized metadata for a run.
- *
- * `projectId` and `tenantId` are required per Convention #17 — every run is
- * attributed to a Project within a Tenant.
- */
-export interface RunMetadata {
-	id: RunId
-	/** Long-lived goal scope. Required. */
-	projectId: ProjectId
-	/** Isolation boundary (Convention #17). Required. */
-	tenantId: TenantId
-	agentId: string
-	agentName: string
-	status: RunExecutionStatus
-	config: RunConfigSnapshot
-	provider: string
-
-	parentRunId?: RunId
-	taskId?: TaskId
-	depth: number
-
-	tokenUsage: TokenUsage
-	costInfo: CostInfo
-	iterations: number
-	startedAt: number
-	endedAt?: number
-	durationMs?: number
-	stopReason?: StopReason
-	lastError?: string
-	result?: string
-
-	childRunIds?: RunId[]
-}
-
-export interface RunConfigSnapshot {
-	model: string
-	tokenBudget: number
-	timeoutMs: number
-	streamIdleTimeoutMs?: number
-	maxRequestRichContentBytes?: number
-	maxIterations?: number
-	temperature?: number
-	maxResponseTokens?: number
-	costLimitUsd?: number
-}

package/src/types/run/prepare-step.ts

@@ -1,292 +0,0 @@
-import type { TokenUsage } from '../common/index.js'
-import type { RunId } from '../ids/index.js'
-import type { Message, UserMessage } from '../message/index.js'
-import type { ToolChoice } from '../provider/chat.js'
-import type { Skill } from '../skills/index.js'
-import type { StepResult } from './step.js'
-import type { StepProvenance } from './step.js'
-
-/** @experimental Bounded, tool-free inference shared by preparation and answer review. */
-export interface PreparationTextRequest {
-	readonly system: string
-	readonly prompt: string
-	/** Default 256; maximum 1,024. A provider limit, not a hard billing ceiling. */
-	readonly maxTokens?: number
-	/**
-	 * Accepted and validated; no longer bounds the request.
-	 *
-	 * @deprecated An auxiliary request that ends without its final usage
-	 * receipt leaves the run's shared ledger with unresolved spend, which stops
-	 * the run — so a deadline short enough to fire in normal use does not bound
-	 * the call, it ends the run that made it. The call is bounded by the
-	 * provider's own request timeout and by the run's cancellation instead, the
-	 * same two bounds every other model request in the run has. Passing this
-	 * field changes nothing; it is retained so an existing caller keeps
-	 * compiling until it is removed in a later major.
-	 */
-	readonly timeoutMs?: number
-	readonly signal?: AbortSignal
-}
-
-/** @experimental Side-call usage also contributes to the owning run's totals. */
-export interface PreparationTextResult {
-	readonly text: string
-	readonly usage: TokenUsage
-	readonly servedBy: StepProvenance
-}
-
-/**
- * What the loop knows before it calls the model again.
- *
- * `stopWhen` (shipped earlier) let a run DECIDE TO STOP based on what the
- * steps produced. This is the other half of the same idea: deciding how
- * the next step should be shaped. Without it, a run's tool surface, model
- * and sampling parameters are fixed at `query()` time, so a phased agent —
- * research with search tools, then write with file tools, then verify with
- * a cheaper model — had to be built as three separate runs, each losing
- * the prior one's context.
- */
-export interface PrepareStepContext {
-	readonly runId: RunId
-	/**
-	 * Optional run-owned inference for context preparation. At most one call per
-	 * stage invocation; cannot be called after that stage returns. Uses the run's
-	 * metered provider/fallback chain and the model selected by preceding stages.
-	 * Only supplied text is sent (12,000 characters total); no tools or history
-	 * are implicitly attached. Returned text is bounded to 8,192 characters.
-	 * Absent in beforeStep and in hosts which do not supply this capability.
-	 */
-	readonly generateText?: (request: PreparationTextRequest) => Promise<PreparationTextResult>
-	/**
-	 * Optional writer-bound snapshot of this invocation's completed events.
-	 * Never discovers other runs or repeats tools. Unsupported stores return
-	 * undefined; cancellation or a settled invocation rejects capture. A local
-	 * signal can shorten, never extend, the run's lifetime.
-	 */
-	readonly captureRunEvidence?: (
-		maxReadBytes?: number,
-		signal?: AbortSignal,
-	) => Promise<import('../../store/evidence/types.js').RunTextEvidenceSource | undefined>
-	/** 1-based, matching the iteration number in events and traces. */
-	readonly stepNumber: number
-	/** Full history as it stands, so a decision can read what happened. */
-	readonly messages: readonly Message[]
-	/**
-	 * Latest operator, goal-round, or steering input accepted by this run,
-	 * retained even when compaction removes it from `messages`. Project
-	 * instructions and task-completion context do not replace operator intent.
-	 */
-	readonly latestUserMessage?: UserMessage
-	/** The run's cancellation signal, for bounded asynchronous preparation. */
-	readonly signal?: AbortSignal
-	/**
-	 * Estimated room for additional step context after existing messages,
-	 * earlier stages' system/skills/context, and a response reserve. Recomputed for
-	 * each stage and its selected model; not a billing limit or fit guarantee.
-	 * `beforeStep` observes its existing boundary before compaction runs.
-	 */
-	readonly contextBudget?: {
-		readonly remainingTokens: number
-		readonly windowTokens: number
-	}
-	/** Every completed step, in order. */
-	readonly steps: readonly StepResult[]
-
-	/**
-	 * What the stages before this one decided, when several were supplied.
-	 *
-	 * Empty for the first stage, and empty for a single `prepareStep`.
-	 * Reading it is how a later stage refines an earlier one — narrowing a
-	 * tool set that has already been narrowed, or leaving a model alone
-	 * because something upstream had a reason to change it.
-	 */
-	readonly prepared: Readonly<PrepareStepResult>
-}
-
-/**
- * Overrides for the NEXT step. Every field is optional; an omitted field
- * keeps the run's configured value, and returning nothing at all is the
- * same as not supplying a `prepareStep`.
- */
-export interface PrepareStepResult {
-	/**
-	 * Restrict which tools the model may call this step, by name. Names
-	 * that are not registered are dropped with a warning rather than
-	 * failing the run.
-	 *
-	 * **Dropping every name leaves the step able to call nothing**, and that
-	 * is deliberate rather than an accident of the filter. This list means
-	 * "only these": if a rename outlives a phase list, the only set
-	 * satisfying "only the tools that no longer exist" is the empty one, and
-	 * widening back to the run's list would grant precisely what the caller
-	 * did not ask for. The step is constrained, not crashed — the model
-	 * answers from what it has and the run continues.
-	 *
-	 * This changed meaning when the list started bounding what may RUN
-	 * rather than only what the model is shown. Before, an aged-out list hid
-	 * every tool from the model while leaving all of them callable, which
-	 * was neither reading.
-	 *
-	 * The warning is the part to watch: it goes to the logger, and a host
-	 * that silences its logger sees a phase quietly stop doing anything.
-	 *
-	 * **This costs a prompt-cache prefix.** Tools render at position 0, so
-	 * changing the set between steps invalidates the cached prefix for that
-	 * step. That is inherent to narrowing, not an implementation detail, so
-	 * it is worth doing when a phase boundary genuinely changes what the
-	 * agent should reach for — and not worth doing every step.
-	 *
-	 * Note it does NOT imply a `tool_choice`. Not every provider has an
-	 * `allowed_tools` parameter, and moving `tool_choice` invalidates cached
-	 * MESSAGE blocks as well — a strictly worse trade for the same effect.
-	 * When a step genuinely needs the model FORCED rather than narrowed, ask
-	 * for it explicitly through {@link PrepareStepResult.toolChoice} and pay
-	 * that cost knowingly.
-	 */
-	readonly activeTools?: readonly string[]
-
-	/**
-	 * Force this step's tool use: `'required'` to make the model call
-	 * something, `'none'` to forbid it, or a named function to demand that
-	 * one. Absent leaves the provider's default.
-	 *
-	 * **It applies to this step only, by construction.** That is the whole
-	 * reason it lives here rather than on the run config. A forced choice
-	 * that persists makes the model call a tool, see the result, and be
-	 * forced again — an agent that cannot stop. The one peer SDK that puts
-	 * `tool_choice` on persistent model settings has to undo it with a
-	 * tool-use tracker, an opt-out flag and a reset applied at two call
-	 * sites; the flag defaults to on precisely because turning it off hangs
-	 * the agent. Here there is nothing to reset and no flag to get wrong:
-	 * the next step is prepared fresh, so the force cannot outlive the step
-	 * that asked for it.
-	 *
-	 * **It costs more cache than `activeTools`.** Narrowing tools
-	 * invalidates the tool prefix; moving `tool_choice` invalidates cached
-	 * message blocks too. Worth it at a real phase boundary — "this step
-	 * must produce the structured answer" — and not worth it as a habit.
-	 */
-	readonly toolChoice?: ToolChoice
-
-	/**
-	 * Put these skills in front of the model for this step only.
-	 *
-	 * A run's skills are fixed at `query()` time and rendered into the cached
-	 * system prefix, so every skill a run might ever need is paid for on
-	 * every single turn. A phased agent rarely needs them all at once —
-	 * research wants the search skill, writing wants the style guide, and
-	 * neither benefits from carrying the other.
-	 *
-	 * Rendered into the same ephemeral system message `system` uses. Providers
-	 * may move that message before history, so changing skills can invalidate
-	 * reuse of the conversation prefix even though the run's prompt is unchanged.
-	 *
-	 * ADDITIVE to the run's skills, not a replacement. A skill the run
-	 * always carries is not something a step should be able to take away by
-	 * naming a different one — that would make every step's list a complete
-	 * restatement, and a phase that forgot one would silently lose it.
-	 *
-	 * Sub-agents are deliberately NOT per-step. Which agents `create_task`
-	 * can reach is baked into that tool's input schema, so varying it would
-	 * rebuild the tool catalogue every step — a worse prompt-cache trade
-	 * than moving tools, for a narrowing a step can already express by
-	 * withholding `create_task` through {@link PrepareStepResult.activeTools}.
-	 */
-	readonly skills?: readonly Skill[]
-
-	/** Use a different model for this step. */
-	readonly model?: string
-
-	/**
-	 * Guidance for this step ONLY, appended as a system message that is not
-	 * retained afterwards.
-	 *
-	 * Some providers collect all system messages before conversation history.
-	 * Changing this field can therefore invalidate reuse of the history prefix.
-	 * Use `context` for changing observations that do not require system authority.
-	 */
-	readonly system?: string
-
-	/**
-	 * Current observations for this request only, appended after history and any
-	 * step system guidance. Carried as a visibly labelled user-role message with
-	 * runtime provenance, not operator input or system authority. It never enters
-	 * durable conversation history or replaces `latestUserMessage`.
-	 *
-	 * Useful for changing inventories and retrieved data on providers that hoist
-	 * system messages. This preserves the history's placement, not a cache-hit
-	 * guarantee. Later stages may compose `prepared.context` or replace it; an
-	 * empty string clears it. The next step starts without it.
-	 */
-	readonly context?: string
-
-	readonly temperature?: number
-	readonly maxResponseTokens?: number
-}
-
-/**
- * Called before each model call, with everything the run has produced so
- * far.
- *
- * A throw fails OPEN — the step proceeds with the run's configured values.
- * Same reasoning as `stopWhen` and deliberately opposite to a guardrail: a
- * broken step-shaping hook should not kill an otherwise healthy run, and
- * unlike a safety check, nothing unsafe gets through when it is skipped.
- */
-export type PrepareStep = (
-	context: PrepareStepContext,
-) => PrepareStepResult | undefined | Promise<PrepareStepResult | undefined>
-
-/**
- * A refusal of the next model call, with the reason it happened.
- *
- * An object rather than a boolean, for two reasons that are both about the
- * reader. A bare boolean does not say which polarity means stop — `true`
- * is equally readable as "allowed" and as "veto" — and it carries nothing
- * into the run record, so an operator finds a run that stopped and no
- * account of why.
- */
-export interface StepVeto {
-	readonly reason: string
-}
-
-/**
- * Called before each model call, and able to refuse it.
- *
- * `prepareStep` can only RESHAPE a step — `activeTools`, `model`,
- * `system`, `temperature` — and cannot reject one. `StopCondition` reads
- * `steps`, so it fires after the step it disliked has already run and been
- * paid for. Neither is what a host with a live rate limit, a revoked
- * tenant or a spend ceiling needs, and the only remaining path was a
- * durable checkpoint built for human review of tool calls.
- *
- * A throw fails CLOSED, deliberately opposite to `prepareStep` above.
- * They are different kinds of hook: a broken step-SHAPER should not kill
- * an otherwise healthy run, because nothing unsafe gets through when it is
- * skipped. A broken step-REFUSER skipped is a refusal that did not happen,
- * which is the thing it exists to prevent.
- */
-export type BeforeStep = (
-	context: PrepareStepContext,
-) => StepVeto | undefined | Promise<StepVeto | undefined>
-
-/**
- * One shaping stage, or several applied in order.
- *
- * A single slot is enough for one concern and no help with two. A host
- * with a per-tenant system prefix AND a cost-based model downgrade had to
- * hand-compose them into one callback, which puts the ordering in the
- * host's code where nothing can see it and makes each concern's failure
- * the other's problem.
- *
- * An ARRAY is ordered by declaration, not by registration. That
- * distinction is the whole reason this is safe where a plugin-style
- * fan-out would not be: the author writes the order down, so "who wins"
- * is a line of their code rather than an accident of install history.
- * Each stage sees what the ones before it decided, and a later stage
- * overrides a field an earlier one set — last writer wins, visibly.
- *
- * A stage that throws is skipped and the rest still run, so one broken
- * concern cannot silently disable the others.
- */
-export type PrepareStepChain = PrepareStep | readonly PrepareStep[]

package/src/types/run/replay.ts

@@ -1,61 +0,0 @@
-import type { CheckpointId, RunId, ToolCallId } from '../ids/index.js'
-import type { ToolResult } from '../tool/index.js'
-
-/**
- * Controlled mutation applied at the fork point during {@link replay}.
- *
- * v1 ships a single variant: `injectToolResponse` — the 80% debugging use
- * case. Additional variants (`swapProvider`, `overrideBudget`, etc.) are
- * deferred; see ses_005-deterministic-replay §3.3.
- */
-export type Mutation = {
-	type: 'injectToolResponse'
-	toolCallId: ToolCallId
-	response: ToolResult
-}
-
-/**
- * Lightweight listing entry returned by {@link listCheckpoints}. Projected
- * from {@link import('../hitl/index.js').IterationCheckpoint} — not a full
- * checkpoint payload, just enough to pick a fork point.
- *
- * Named `CheckpointListEntry` (not `CheckpointSummary`) to avoid collision
- * with the pre-existing HITL `CheckpointSummary` shape at
- * `types/hitl/index.ts`.
- */
-export interface CheckpointListEntry {
-	id: CheckpointId
-	runId: RunId
-	iteration: number
-	createdAt: number
-	messageCount: number
-}
-
-/**
- * Attribution record stamped on a {@link Run} produced by {@link replay}.
- * Non-replay runs have `replayOf === undefined`. Shape mirrors voltagent's
- * `replayedFromExecutionId` / `replayFromStepId` pattern, folded into a
- * single optional rather than three parallel ones.
- */
-export interface ReplayAttribution {
-	sourceRunId: RunId
-	fromCheckpointId: CheckpointId
-	mutations: Mutation[]
-	replayedAt: number
-}
-
-/**
- * Thrown when a {@link Mutation} cannot be applied at the resolved fork
- * point. Currently raised by `injectToolResponse` when the supplied
- * `toolCallId` does not match any pending tool call in the checkpoint's
- * last assistant message.
- */
-export class MutationNotApplicableError extends Error {
-	constructor(
-		message: string,
-		public readonly availableToolCallIds: readonly ToolCallId[],
-	) {
-		super(message)
-		this.name = 'MutationNotApplicableError'
-	}
-}

package/src/types/run/schema-version.ts

@@ -1,19 +0,0 @@
-/**
- * RunEvent envelope schema version. Bumped on breaking envelope change.
- *
- * - v1: pre-0.2.0 (implicit; untagged events are treated as v1 by consumers).
- * - v2: 0.2.0+ — adds `schemaVersion`, `lineage`, and sub-session lifecycle
- *   events.
- * - v3: 2026-05-01 — removes `llm_response`; adds message + tool-input
- *   lifecycle variants (`message_started`, `text_delta`,
- *   `message_completed`, `tool_input_started`, `tool_input_delta`,
- *   `tool_input_completed`); `tool_executing`/`tool_completed` carry
- *   required `toolUseId`; `tool_completed` carries required `isError`.
- *   See ses_001-tool-stream-events.
- *
- * See session-hierarchy.md §10.1 (Event-schema evolution contract) and
- * §13.3.2 (`schemaVersion` back-compat).
- */
-export const RUN_EVENT_SCHEMA_VERSION = 3 as const
-
-export type RunEventSchemaVersion = typeof RUN_EVENT_SCHEMA_VERSION