@namzu/sdk 27.0.0 → 28.0.0

package/src/types/guardrail/index.ts

@@ -1,10 +1,11 @@
 import type { RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
+import type { ToolProvenance } from '../tool/index.js'
 
 /**
  * Guardrails inspect what goes INTO a run and what comes OUT of it.
  *
- * namzu had three good gates on tool calls — probe veto, `VerificationGate`,
+ * namzu had three good gates on tool calls — probe veto, `AuthorizationGate`,
  * HITL review — and they all point the same way: they protect the world
  * from the agent. Nothing protected the user from the agent's own output,
  * and nothing looked at the prompt before the run started.
@@ -58,5 +59,75 @@ export interface NamedGuardrail<T> {
 	readonly check: T
 }
 
+/**
+ * What a guardrail sees when a tool has produced a result.
+ *
+ * The two above bracket the RUN. This one sits at the tool boundary, which
+ * is the only place a result can be examined before the model reads it:
+ * the registry returns to the executor, the executor applies the output
+ * budget and spills what is over it, and compaction summarises later still.
+ * So screening here is upstream of both by construction rather than by
+ * ordering — a summariser does not distinguish trusted from untrusted text,
+ * and content carried into a summary outlives the result it came from.
+ *
+ * `provenance` is the point. A connector's result is framed with the
+ * server's name (see `wrapUntrusted`), and a screen that can only read the
+ * value cannot tell a remote server's words from a first-party tool's.
+ */
+export interface ToolResultGuardrailContext {
+	/** The tool as the registry knows it. */
+	readonly toolName: string
+	/** Validated input the tool was called with. */
+	readonly input: unknown
+	/** The text the model would read. */
+	readonly output: string
+	/** Whether the tool itself reported success. */
+	readonly success: boolean
+	/**
+	 * Who produced the tool, when it was not this process. Absent means
+	 * host-defined; present names the connected server.
+	 */
+	readonly provenance?: ToolProvenance
+}
+
+/**
+ * What a guardrail decided about a tool result.
+ *
+ * Deliberately NOT {@link GuardrailVerdict}. There, `block` ends the run —
+ * it is the only thing it can mean when the subject is the run's input or
+ * its final answer. At a tool boundary the useful refusal is usually the
+ * other one: fail this call, tell the model why, and let it choose
+ * something else. Reusing the word would give one spelling two meanings
+ * across boundaries, and a host that shared a function between them would
+ * get the wrong one silently.
+ *
+ * Hence two refusals rather than one:
+ *
+ *  - `refuse` — recoverable. The `tool_use` fails with the reason in place
+ *    of the output. Not blank and not dropped: a model shown an empty
+ *    result concludes the tool found nothing, which is a different fact and
+ *    invites the retry loop the refusal was meant to prevent.
+ *  - `halt` — terminal, for what must not be survived.
+ *
+ * `rewrite` is for REDACTION — a credential or an account number that
+ * should not enter context — and this is the last boundary where it can be
+ * removed before it does. It is **not** for neutralising an injection:
+ * editing an attack presumes you understood the payload well enough to
+ * defang it, and the systems that screen for attacks block instead. The two
+ * are the same mechanism and only the discipline separates them, which is
+ * why it is written here rather than left to be inferred.
+ */
+export type ToolResultVerdict =
+	| { readonly action: 'pass' }
+	| { readonly action: 'refuse'; readonly reason: string }
+	| { readonly action: 'halt'; readonly reason: string }
+	| { readonly action: 'rewrite'; readonly output: string; readonly reason?: string }
+
+export type ToolResultGuardrail = (
+	ctx: ToolResultGuardrailContext,
+) => ToolResultVerdict | Promise<ToolResultVerdict>
+
+export type ToolResultGuardrailSpec = ToolResultGuardrail | NamedGuardrail<ToolResultGuardrail>
+
 export type InputGuardrailSpec = InputGuardrail | NamedGuardrail<InputGuardrail>
 export type OutputGuardrailSpec = OutputGuardrail | NamedGuardrail<OutputGuardrail>

package/src/types/hitl/policy.ts

@@ -0,0 +1,83 @@
+import type { RunId } from '../ids/index.js'
+import type { ResumeHandler } from './index.js'
+
+/**
+ * Who answers when the run asks a human, as a value rather than a closure.
+ *
+ * `ResumeHandler` was captured once at `query()` start and never read again
+ * from anywhere a host could reach — so switching from "ask me about every
+ * write" to "go ahead, I'm stepping out" meant ending the run and starting
+ * another. That is the same defect `permissionMode` had before it became a
+ * box the executor reads through, and it has the same cost: the fix
+ * discards the in-flight step and the context that step was built from.
+ *
+ * The `name` is not decoration. A durable log entry saying a policy changed
+ * is useless if the only thing it can print is `[Function (anonymous)]`,
+ * and this event exists to answer "who approved that, and under what rule"
+ * months later.
+ */
+export interface ApprovalPolicy {
+	/**
+	 * A stable name for this policy — `auto-approve`, `operator-tui`,
+	 * `deny-all`. Written to the durable log and shown to an operator.
+	 */
+	readonly name: string
+	readonly handler: ResumeHandler
+}
+
+/**
+ * The policy RIGHT NOW, plus the only supported way to change it.
+ *
+ * `set` is async because the change is durably recorded before it takes
+ * effect, and that ordering is deliberate: a policy that started approving
+ * writes before the record landed would leave a log where the approvals
+ * precede the decision that permitted them.
+ */
+export interface RunApprovalPolicy {
+	readonly current: ApprovalPolicy
+	/**
+	 * Swap the policy, recording who and why.
+	 *
+	 * `reason` is required rather than optional. Every field here is read by
+	 * somebody reconstructing an incident, and an optional reason is a field
+	 * that is absent exactly when it matters most — the change nobody
+	 * expected.
+	 */
+	set(policy: ApprovalPolicy, reason: string): Promise<void>
+
+	/**
+	 * The change the model has not been told about yet — and reading it is
+	 * what marks it told.
+	 *
+	 * The model plans around how closely it is being watched. A run that
+	 * silently stops asking a human, or silently starts, leaves the model
+	 * working from a supervision assumption that is no longer true: it will
+	 * keep batching destructive calls it expects to be reviewed, or keep
+	 * asking permission nobody is left to give.
+	 *
+	 * Read-and-clear rather than a flag somebody must remember to reset.
+	 * Told twice is worse than a plain notice: the second copy reads as a
+	 * second change, and the model will believe supervision moved again.
+	 * Only the LAST unannounced change is kept — three swaps between two
+	 * model calls are one fact by the time the model can act on it, and
+	 * replaying the intermediate ones would describe a history rather than
+	 * a state.
+	 */
+	takeUnannouncedChange(): ApprovalPolicyChange | undefined
+}
+
+/** A change the model has not yet been told about. */
+export interface ApprovalPolicyChange {
+	readonly from: string
+	readonly to: string
+	readonly reason: string
+}
+
+/** The durable record of a policy change. */
+export interface ApprovalPolicyChangedEvent {
+	readonly type: 'approval_policy_changed'
+	readonly runId: RunId
+	readonly from: string
+	readonly to: string
+	readonly reason: string
+}

package/src/types/ids/brand.ts

@@ -0,0 +1,58 @@
+/**
+ * Nominal-brand machinery for the id types — declared here, not yet applied.
+ *
+ * Today every id in `./index.ts` is a bare template-literal type, and
+ * TypeScript's assignability rule for those means
+ * `const x: RunId = 'run_totally-made-up'` compiles with no cast and no
+ * factory call. The result is indistinguishable at the type level from an id
+ * `generateRunId()` actually minted, so the compiler cannot tell a real id
+ * from a plausible-looking string.
+ *
+ * Applying this brand is a separate change, on purpose: flipping the
+ * declarations turns every existing bare literal into an error at once, and
+ * that is a `major` with a migration in front of it. This file ships the
+ * machinery and the runtime constructors that use it so the two can land
+ * independently — the constructors are useful on their own, since there is
+ * no runtime prefix validation in the tree at all today.
+ *
+ * **The prefix stays in the type, and that is the one place this diverges
+ * from a plain `Branded<B>`.** A brand alone would render as `RunId` in
+ * hovers and errors and tell a reader nothing about the shape. Keeping
+ * `` `${Prefix}_${string}` `` in the intersection means an editor hover still
+ * shows `run_${string}`, which is most of what makes these ids readable in
+ * a log line.
+ */
+
+declare const ID_BRAND: unique symbol
+
+/**
+ * An id with both its wire shape and a nominal tag.
+ *
+ * `B` is a string tag rather than the type's own name by convention — two
+ * ids with the same prefix but different meanings must not be mutually
+ * assignable, and only the tag can separate them.
+ */
+export type Id<Prefix extends string, B extends string> = `${Prefix}_${string}` & {
+	readonly [ID_BRAND]: B
+}
+
+/**
+ * The one way to produce a branded id without a runtime check.
+ *
+ * A brand cannot be constructed by writing it — `{ [ID_BRAND]: 'RunId' }` is
+ * not something a caller can type, since the symbol is not exported. So
+ * every id has to come from somewhere, and there are exactly three places:
+ * `generate*Id()` mints one, `as*Id()` checks a string into one, and this.
+ *
+ * Named `unsafeId` rather than `toId` because the name is the warning, and
+ * kept HERE rather than in `utils/id.ts` because this file has no imports —
+ * `types/ids/index.ts` needs it for `UNKNOWN_TENANT_ID` and cannot import
+ * from `utils/id.ts` without closing a cycle.
+ *
+ * Not exported from the package barrel. A consumer that needs an id from a
+ * string wants the checked constructor; one that wants to skip the check is
+ * asking for the thing the brand exists to prevent.
+ */
+export function unsafeId<T extends string>(value: string): T {
+	return value as unknown as T
+}

package/src/types/ids/index.ts

@@ -1,7 +1,23 @@
-export type RunId = `run_${string}`
-export type MessageId = `msg_${string}`
-export type SessionId = `ses_${string}`
-export type ToolCallId = `call_${string}`
+import { type Id, unsafeId } from './brand.js'
+
+/**
+ * Every id here is NOMINAL as of NZ-SURF-11: `Id<Prefix, Tag>` intersects the
+ * wire shape with a unique-symbol brand, so `const a: RunId = 'run_x'` no
+ * longer compiles and neither does handing a `SessionId` where a `RunId` was
+ * asked for. Ids are minted by `generate*Id()` or checked by `as*Id()` in
+ * `utils/id.ts`; fixtures use `test-support/ids.ts`.
+ *
+ * **What this does NOT stop, measured rather than assumed:** a type
+ * ASSERTION. `'run_x' as RunId` and `someString as RunId` both still compile,
+ * because TypeScript's assertion rule only asks that the two types be
+ * comparable and a string is comparable to a branded string. The brand makes
+ * a rule against `as <IdType>` enforceable — it does not replace one. See
+ * `__tests__/an-id-is-not-a-string.test.ts`, which pins both halves.
+ */
+export type RunId = Id<'run', 'RunId'>
+export type MessageId = Id<'msg', 'MessageId'>
+export type SessionId = Id<'ses', 'SessionId'>
+export type ToolCallId = Id<'call', 'ToolCallId'>
 /**
  * Provider-issued tool-use identifier surfaced on the streaming event bus.
  * Providers emit different prefixes (`toolu_*`, `call_*`,
@@ -12,52 +28,100 @@ export type ToolCallId = `call_${string}`
  * persisted assistant messages and replay records.
  */
 export type ToolUseId = string
-export type ActivityId = `act_${string}`
-export type TaskId = `task_${string}`
-export type PlanId = `plan_${string}`
-export type KnowledgeBaseId = `kb_${string}`
-export type DocumentId = `doc_${string}`
-export type ChunkId = `chk_${string}`
-export type ConnectorId = `conn_${string}`
-export type ConnectorInstanceId = `ci_${string}`
-export type TenantId = `tnt_${string}`
-export type CredentialId = `cred_${string}`
-export type ExecutionContextId = `ectx_${string}`
-export type MCPServerId = `mcp_${string}`
-export type MCPClientId = `mcpc_${string}`
-export type MCPSessionId = `mcps_${string}`
-export type EnvironmentId = `env_${string}`
-export type CheckpointId = `cp_${string}`
-export type LockId = `lock_${string}`
-export type AdvisoryId = `adv_${string}`
-export type AdvisoryCallId = `advc_${string}`
-export type EmergencySaveId = `esave_${string}`
-export type MemoryId = `mem_${string}`
-export type PluginId = `plg_${string}`
-export type SandboxId = `sbx_${string}`
+export type ActivityId = Id<'act', 'ActivityId'>
+export type TaskId = Id<'task', 'TaskId'>
+export type PlanId = Id<'plan', 'PlanId'>
+export type KnowledgeBaseId = Id<'kb', 'KnowledgeBaseId'>
+export type DocumentId = Id<'doc', 'DocumentId'>
+export type ChunkId = Id<'chk', 'ChunkId'>
+export type ConnectorId = Id<'conn', 'ConnectorId'>
+export type ConnectorInstanceId = Id<'ci', 'ConnectorInstanceId'>
+export type TenantId = Id<'tnt', 'TenantId'>
+export type CredentialId = Id<'cred', 'CredentialId'>
+export type ExecutionContextId = Id<'ectx', 'ExecutionContextId'>
+export type MCPServerId = Id<'mcp', 'MCPServerId'>
+export type MCPClientId = Id<'mcpc', 'MCPClientId'>
+export type MCPSessionId = Id<'mcps', 'MCPSessionId'>
+export type EnvironmentId = Id<'env', 'EnvironmentId'>
+export type CheckpointId = Id<'cp', 'CheckpointId'>
+export type LockId = Id<'lock', 'LockId'>
+export type AdvisoryId = Id<'adv', 'AdvisoryId'>
+export type AdvisoryCallId = Id<'advc', 'AdvisoryCallId'>
+export type EmergencySaveId = Id<'esave', 'EmergencySaveId'>
+export type MemoryId = Id<'mem', 'MemoryId'>
+export type PluginId = Id<'plg', 'PluginId'>
+export type SandboxId = Id<'sbx', 'SandboxId'>
+/** LOG-14: the audit trail's own record id — distinct from `RunEvent.seq`. */
+export type AuditEventId = Id<'aud', 'AuditEventId'>
 
-// Actor identifiers (Session Hierarchy §4.3). Branded so actor refs cannot be
-// constructed from bare strings.
-export type UserId = `usr_${string}`
-export type AgentId = `agt_${string}`
+// Actor identifiers (Session Hierarchy §4.3).
+//
+// This block used to say "branded so actor refs cannot be constructed from
+// bare strings" while the compiler enforced nothing. NZ-SURF-11 made that
+// true for `UserId`: `const a: UserId = 'usr_made-up'` is now an error.
+export type UserId = Id<'usr', 'UserId'>
+
+/**
+ * @deprecated An agent is identified by its REGISTRY KEY, and this type
+ * never described one. Removal is a later major.
+ *
+ * `ActorRef.agentId` was annotated `AgentId` and every value that ever
+ * reached it was a key an operator chose — `'worker'`, `'reviewer'`,
+ * `'supervisor'` — reaching the field through an `as AgentId` cast. There is
+ * no producer: nothing in this kernel has ever called `generateAgentId`
+ * (there isn't one), so an `agt_`-prefixed agent identifier has never
+ * existed. NZ-SURF-11 changed `ActorRef.agentId` to `string`, which is what
+ * it always held.
+ *
+ * Kept for one release rather than deleted, per the deprecate-before-remove
+ * rule: a consumer that annotated its own variable `AgentId` still compiles
+ * and gets a warning. `asAgentId` is deprecated for the same reason and
+ * would throw on every value the kernel actually produces.
+ */
+export type AgentId = Id<'agt', 'AgentId'>
 
 // Shared-store placeholder refs (Session Hierarchy §4.2 / §3.2). Full shapes
 // land in later phases; kept here as opaque branded IDs so ProjectConfig can
 // reference them today.
-export type MemoryStoreRef = `mms_${string}`
-export type VaultRef = `vlt_${string}`
-export type KnowledgeBaseRef = `kbs_${string}`
+export type MemoryStoreRef = Id<'mms', 'MemoryStoreRef'>
+export type VaultRef = Id<'vlt', 'VaultRef'>
+export type KnowledgeBaseRef = Id<'kbs', 'KnowledgeBaseRef'>
 
 // Session hierarchy IDs. Convention #2 branded IDs; prefixes mandated by the
 // five-layer hierarchy (Project → Thread → Session → SubSession → Run). The
 // `types/session/ids.ts` barrel re-exports these for co-location ergonomics.
-export type ProjectId = `prj_${string}`
-export type ThreadId = `thd_${string}`
-export type SubSessionId = `sub_${string}`
-export type HandoffId = `hof_${string}`
-export type WorkspaceId = `wsp_${string}`
-export type SummaryId = `sum_${string}`
-export type DeliverableId = `del_${string}`
+export type ProjectId = Id<'prj', 'ProjectId'>
+/**
+ * NZ-TOPIC-04: narrowed from the NZ-TOPIC-01 alias `type TopicId = ThreadId`
+ * (both `thd_${string}`) to its own prefix. `thd_` from here on means only
+ * the pre-0.2.0 top-level container (`session/migration/id-prefix.ts`,
+ * `session/migration/filesystem.ts`) -- a meaning `ThreadId` never carried;
+ * it was purely the deprecated name for THIS type. Deleted rather than
+ * repurposed to mean the legacy container instead: a name whose meaning
+ * silently changes under unmigrated callers is worse than a name that is
+ * gone (Convention #0, no silent long-lived compat).
+ */
+export type TopicId = Id<'top', 'TopicId'>
+/**
+ * @deprecated Use {@link TopicId}. Removal is NZ-TOPIC-05.
+ *
+ * NZ-TOPIC-01 introduced `TopicId` as an alias OF this name; NZ-TOPIC-04
+ * reverses the direction. So this alias now follows `TopicId` to the `top_`
+ * prefix instead of keeping `thd_` — a consumer still compiling against the
+ * old name gets the new prefix, which is exactly what the major announces.
+ *
+ * It is kept rather than deleted because the deprecation NZ-TOPIC-01 wrote
+ * has never reached a registry: `@namzu/sdk` on npm is 27.1.0, and the
+ * changeset that would publish it is still unconsumed in `.changeset/`. A
+ * removal here would be a rename with no alias wearing a major's clothes.
+ * This release is the one that carries the warning; the next may remove it.
+ */
+export type ThreadId = TopicId
+export type SubSessionId = Id<'sub', 'SubSessionId'>
+export type HandoffId = Id<'hof', 'HandoffId'>
+export type WorkspaceId = Id<'wsp', 'WorkspaceId'>
+export type SummaryId = Id<'sum', 'SummaryId'>
+export type DeliverableId = Id<'del', 'DeliverableId'>
 
 /**
  * Sentinel {@link TenantId} for legacy pre-0.2.0 runs rehomed by the
@@ -66,4 +130,7 @@ export type DeliverableId = `del_${string}`
  * real tenant is assigned — the kernel surfaces the sentinel but does not
  * prescribe policy (Convention #17).
  */
-export const UNKNOWN_TENANT_ID = 'tnt_unknown_legacy' as TenantId
+// `unsafeId`, not `asTenantId`: `utils/id.ts` imports this file, so reaching
+// for its constructor here would close a cycle. The prefix is pinned by
+// `__tests__/an-id-is-not-a-string.test.ts` instead.
+export const UNKNOWN_TENANT_ID = unsafeId<TenantId>('tnt_unknown_legacy')

package/src/types/message/index.ts

@@ -80,7 +80,31 @@ export interface Citation {
 }
 
 /** What a user message may carry alongside its text. */
-export type MessageAttachment = ImageAttachment | DocumentAttachment
+/**
+ * An attachment whose bytes are held by a store, not by the message.
+ *
+ * Structural rather than an import from `store/attachment`, so this types
+ * module keeps depending on nothing — the same reasoning `ToolRegistryRef`
+ * gives. `store/attachment` owns the resolution and its refusals; this is
+ * the shape a message may carry.
+ *
+ * Inline base64 puts the bytes in the durable transcript, in every
+ * checkpoint, in every compaction pass, and — because a conversation
+ * resends its history — on the wire once per turn. A 4 MB PDF attached once
+ * is 4 MB per request for the rest of the run.
+ */
+export interface StoredAttachmentRef {
+	readonly type: 'stored'
+	/** Opaque to the kernel. Meaningful to the store that minted it. */
+	readonly ref: string
+	readonly mediaType: string
+	/** Which kind of content block to build once the bytes arrive. */
+	readonly kind: 'image' | 'document'
+	readonly name?: string
+	readonly citations?: boolean
+}
+
+export type MessageAttachment = ImageAttachment | DocumentAttachment | StoredAttachmentRef
 
 export const isDocumentAttachment = (
 	attachment: MessageAttachment,

package/src/types/project/entity.ts

@@ -28,7 +28,7 @@ export interface ProjectConfig {
 }
 
 /**
- * Whether the workspace accepts new work.
+ * Whether the project accepts new work.
  *
  * Owner-managed, like the status it replaces: a project does not derive
  * `archived` from having no live sessions, because "empty right now" and
@@ -42,9 +42,13 @@ export type ProjectStatus = 'open' | 'archived'
  *
  * `status` is the gate the ingress paths read: an archived project accepts no
  * new session and no handoff. It lives here rather than on Thread because the
- * project is the thing a tenant actually closes — a workspace with its own
+ * project is the thing a tenant actually closes — a scope with its own
  * limits, its own environment, and its own memory — and closing it has to mean
  * something to the code, not only to a listing.
+ *
+ * "Workspace" is a different noun in this codebase and is already taken:
+ * see `WorkspaceRef`, which is per-run provisioning. This is the durable
+ * one, and the prose above used to say the other word.
  */
 export interface Project {
 	id: ProjectId
@@ -54,6 +58,22 @@ export interface Project {
 	status: ProjectStatus
 	/** CAS counter for status transitions. Mirrors `Session.ownerVersion`. */
 	ownerVersion: number
+	/**
+	 * The canonical directory this project's work happens in.
+	 *
+	 * Resolved through `realpath` at creation, so a symlink and a trailing
+	 * slash and the real path are one project rather than three records for
+	 * one directory.
+	 *
+	 * NOT `WorkspaceRef.meta.worktreePath`. That is per-RUN provisioning and
+	 * may be a different directory entirely — a git worktree cut for one
+	 * run and discarded after it. This is the durable binding a host uses to
+	 * answer "which project is this directory", across sessions and across
+	 * process restarts.
+	 *
+	 * Optional: a project need not be on disk at all.
+	 */
+	readonly rootPath?: string
 	createdAt: Date
 	updatedAt: Date
 }

package/src/types/provider/interface.ts

@@ -19,6 +19,22 @@ export interface LLMProvider {
 	 */
 	readonly capabilities?: ProviderCapabilities
 
+	/**
+	 * Retry behaviour this DRIVER wants, when the generic default is wrong
+	 * for the vendor behind it.
+	 *
+	 * One config was applied to every member of a chain, so an operator
+	 * running [expensive primary, cheap self-hosted backup] could not give
+	 * the backup a shorter budget — the two have different failure shapes
+	 * and different costs per attempt, and only the driver knows which.
+	 *
+	 * Merged UNDER a caller's config, never over it: the host asked for
+	 * something specific and the driver is expressing a default. Absent
+	 * means the generic default, which is what every driver had before this
+	 * existed.
+	 */
+	readonly retryDefaults?: Partial<import('../../provider/retry.js').ProviderRetryConfig>
+
 	/**
 	 * The single LLM entry point. Returns an async iterable of
 	 * {@link StreamChunk} carrying text deltas, tool-call argument
@@ -26,8 +42,8 @@ export interface LLMProvider {
 	 *
 	 * Consumers that need an aggregated response (legacy
 	 * `ChatCompletionResponse` shape) call
-	 * `collect(provider.chatStream(params))` from
-	 * `@namzu/sdk/provider/collect`. The kernel's iteration
+	 * `collectChatCompletion(provider.chatStream(params))` from
+	 * `@namzu/sdk/provider/collect-chat-completion`. The kernel's iteration
 	 * orchestrator consumes the stream directly so it can emit
 	 * per-delta `RunEvent`s.
 	 *
@@ -144,4 +160,31 @@ export interface LLMProvider {
 		model: string,
 		thinking?: import('./chat.js').ThinkingConfig,
 	): readonly import('./chat.js').ReasoningEffort[]
+
+	/**
+	 * How large a context this model actually has, if the vendor says.
+	 *
+	 * The kernel's only source below an explicit host config is a
+	 * hand-maintained prefix table, and its own header records what that
+	 * costs: one vendor family's entries all carried 200k including the
+	 * models whose window is 1M, so those runs compacted at roughly 14% full
+	 * and threw away the prompt-cache prefix to do it. Every model release drifts the table
+	 * again until somebody edits it. Meanwhile at least one driver already
+	 * parses a real per-model `context_length` off the vendor listing and
+	 * throws it away, because there was no member to return it through.
+	 *
+	 * Three states, exactly like {@link LLMProvider.effortLevelsFor}: the
+	 * member ABSENT means this driver cannot answer at all; a resolved
+	 * `undefined` means it asked and does not know; a number is the answer.
+	 * The three are different facts and collapsing any two of them turns
+	 * "I do not know" into a confident wrong number, which is the failure
+	 * the table already made once.
+	 *
+	 * Resolved ONCE per run, not per iteration — the two consumers are
+	 * synchronous and in the hot loop, so this must never become an await
+	 * inside it. A rejection or a hang here is not a run failure: the table
+	 * is still there, and a driver that cannot answer must not take down a
+	 * run that would otherwise work.
+	 */
+	resolveContextWindow?(model: string, signal?: AbortSignal): Promise<number | undefined>
 }

package/src/types/provider/model.ts

@@ -1,8 +1,22 @@
 export interface ModelInfo {
 	id: string
 	name: string
-	contextWindow: number
-	maxOutputTokens: number
+	/**
+	 * Tokens the model's context holds, when the driver knows.
+	 *
+	 * OPTIONAL, and the optionality is the fix. Four drivers filled this
+	 * with `0` where the vendor listing carries no value — and zero is not
+	 * a window, it is "I do not know" written as a number, which reads to
+	 * every consumer as a real measurement of a model that can hold
+	 * nothing. A caller dividing by it gets `Infinity`; one comparing
+	 * against it concludes every prompt is too long.
+	 *
+	 * Absent says the same thing honestly, and a consumer can then fall
+	 * back to its own table instead of trusting a zero.
+	 */
+	contextWindow?: number
+	/** Same, and absent for the same reason. */
+	maxOutputTokens?: number
 	inputPrice: number
 	outputPrice: number
 	supportsToolUse: boolean