@namzu/sdk 52.0.0 → 52.2.0

package/src/types/code-analysis/index.ts

@@ -0,0 +1,325 @@
+/**
+ * The seam a semantic code index arrives on.
+ *
+ * Declared in the SDK and implemented in `@namzu/analysis`, the same split
+ * `CodeNavigationProvider` uses with `@namzu/lsp`: the kernel owns the shape a
+ * tool programs against, the optional package owns the parser and the store
+ * that answer. A host constructs one and puts it on the tool context — there
+ * is no discovery step.
+ *
+ * Kept here rather than imported from `@namzu/analysis` because the
+ * dependency direction forbids it: `sdk ← analysis`, never the other way.
+ *
+ * ## What this answers that `grep` and a language server do not
+ *
+ * `grep` finds a string and says nothing of the function around it. A
+ * language server resolves a symbol the project's own types can see, and has
+ * nothing to say about a 40 MB bundle with no types and a hundred
+ * single-letter names. This index is for the second case: *which function
+ * contains this literal, what is its exact source, and who calls it by name*,
+ * over code nobody wrote for you to read.
+ *
+ * ## Positions
+ *
+ * Lines and columns are ONE-based, and columns count UTF-16 code units, which
+ * is what a JavaScript string index is. A character outside the Basic
+ * Multilingual Plane therefore takes two columns. `start` / `end` are the
+ * same UTF-16 offsets into the file's text, half-open. A line ends at `\n`.
+ */
+
+/**
+ * How much of the question the answer covers.
+ *
+ * Two cases, and the second carries its reasons. `partial` is not a failure —
+ * the answer is true as far as it goes — but a caller deciding "nothing
+ * calls this" from a partial answer is guessing, and the reasons say what is
+ * missing (a file that did not parse, a file that changed since it was
+ * indexed, a page cut off by `limit`).
+ */
+export type AnalysisCoverage =
+	| { readonly status: 'complete' }
+	| { readonly status: 'partial'; readonly reasons: readonly string[] }
+
+/**
+ * The evidence behind an answer, in three parts.
+ *
+ * - `observed`: what the index read out of the files, stated as fact.
+ * - `inferred`: what was concluded rather than read. A callee matched by
+ *   its TEXT is an inference — the index does no scope analysis, so two
+ *   unrelated functions called `run` are the same callee to it.
+ * - `coverage`: whether the answer is the whole answer.
+ *
+ * Every successful result carries one. An answer without it reads as
+ * certain, and the cases this package exists for are the ones where it is
+ * not.
+ */
+export interface AnalysisEvidence {
+	readonly observed: readonly string[]
+	readonly inferred: readonly string[]
+	readonly coverage: AnalysisCoverage
+}
+
+/**
+ * What a query answers. Three cases, closed, as with `CodeNavigationResult`:
+ * `unsupported` is "this index does not do that", `failed` is "something
+ * broke", and neither is an empty page. An empty page means "I looked and
+ * there are none", the answer a deletion depends on.
+ */
+export type CodeAnalysisResult<T> =
+	| { readonly kind: 'ok'; readonly value: T; readonly evidence: AnalysisEvidence }
+	| { readonly kind: 'unsupported'; readonly reason: string }
+	| { readonly kind: 'failed'; readonly error: string }
+
+/**
+ * One page of a larger answer. `total` is the count across ALL pages, so a
+ * caller can tell a complete list from the first slice of a long one;
+ * `nextCursor` is absent on the last page and is opaque — pass it back
+ * unchanged.
+ */
+export interface AnalysisPage<T> {
+	readonly items: readonly T[]
+	readonly total: number
+	readonly nextCursor?: string
+}
+
+/**
+ * What every request may carry beyond its own fields.
+ *
+ * `signal` stops the call: an index run in progress is abandoned (what it had
+ * already committed stays, so the next call continues from there), and a call
+ * still queued behind another never starts. Without it nothing a user does,
+ * Esc included, can stop a multi-second index of a large tree.
+ */
+export interface AnalysisCallOptions {
+	readonly signal?: AbortSignal
+}
+
+/** The paging arguments every list-returning request takes. */
+export interface AnalysisPaging extends AnalysisCallOptions {
+	/** Items per page. The provider clamps it to its own maximum. */
+	readonly limit?: number
+	/** The previous page's `nextCursor`. */
+	readonly cursor?: string
+}
+
+export type AnalysisFunctionKind =
+	| 'declaration'
+	| 'expression'
+	| 'arrow'
+	| 'method'
+	| 'getter'
+	| 'setter'
+	| 'constructor'
+
+/**
+ * A function, located. `id` is valid until its file changes and is then
+ * re-issued: do not keep one across an `index` that re-read the file.
+ */
+export interface AnalysisFunction {
+	readonly id: number
+	/** `null` for an anonymous function with nothing to infer a name from. */
+	readonly name: string | null
+	readonly kind: AnalysisFunctionKind
+	/** Absolute path. */
+	readonly path: string
+	readonly line: number
+	readonly column: number
+	readonly endLine: number
+	readonly start: number
+	readonly end: number
+}
+
+/** A piece of a file's source, with the honesty about a cut. */
+export interface AnalysisSourceSlice {
+	readonly text: string
+	/** The full length in UTF-16 units, whether or not all of it is in `text`. */
+	readonly chars: number
+	/** `true` when `text` is shorter than `chars` because of the size cap. */
+	readonly truncated: boolean
+}
+
+export interface IndexRequest extends AnalysisCallOptions {
+	/** Absolute directory the index belongs to. */
+	readonly root: string
+	/**
+	 * Index only this file or directory under `root`, instead of all of it.
+	 *
+	 * The way to make progress on a root too big to index whole (a home
+	 * directory): a call that stops at its limits says so, and the next step is
+	 * a narrower `scope`. Work from earlier calls is kept.
+	 */
+	readonly scope?: string
+	/** Re-read every file, ignoring size / mtime / hash. */
+	readonly force?: boolean
+}
+
+export interface IndexSummary {
+	readonly root: string
+	/** Whether the index lives on disk; `false` for an in-memory fallback. */
+	readonly persisted: boolean
+	readonly files: {
+		readonly indexed: number
+		/** Parsed this call (new or changed). */
+		readonly parsed: number
+		/** Seen and left alone: same size and mtime, or same content hash. */
+		readonly unchanged: number
+		readonly removed: number
+		readonly skipped: number
+		readonly withParseErrors: number
+	}
+	/** Why files were skipped, as reason → count. */
+	readonly skippedReasons: Readonly<Record<string, number>>
+	readonly functions: number
+	readonly strings: number
+	readonly calls: number
+	readonly durationMs: number
+	/**
+	 * Why this call stopped before covering `scope`, when it did: a time or
+	 * directory limit. Present means the index is partial; the text names the
+	 * next step.
+	 */
+	readonly truncated?: string
+}
+
+export interface FindLiteralRequest extends AnalysisPaging {
+	readonly root: string
+	/** The substring to look for inside string and template literals. */
+	readonly text: string
+	/** Absolute file or directory to restrict the search to. */
+	readonly path?: string
+	/** Default `true`. */
+	readonly caseSensitive?: boolean
+}
+
+export interface AnalysisLiteralHit {
+	readonly path: string
+	readonly line: number
+	readonly column: number
+	readonly start: number
+	readonly end: number
+	readonly kind: 'string' | 'template' | 'key'
+	/** The literal's value, cut to a preview. */
+	readonly value: string
+	readonly valueTruncated: boolean
+	/** The innermost function around it; absent at the top level of a file. */
+	readonly function?: AnalysisFunction
+	/**
+	 * Present when the file this came from no longer matches the index: the
+	 * position may be off (`changed`) or the file may be gone (`deleted`).
+	 */
+	readonly stale?: 'changed' | 'deleted'
+}
+
+export interface EnclosingFunctionRequest extends AnalysisCallOptions {
+	readonly root: string
+	readonly path: string
+	readonly line: number
+	readonly column?: number
+	/** Cap on the source slice, in UTF-16 units. */
+	readonly maxChars?: number
+}
+
+export interface AnalysisEnclosingFunction {
+	/** `null` when the position is not inside any function — a real answer. */
+	readonly function: AnalysisFunction | null
+	/** The function's parents, innermost first. */
+	readonly parents: readonly AnalysisFunction[]
+	readonly source?: AnalysisSourceSlice
+}
+
+export interface FunctionSourceRequest extends AnalysisPaging {
+	readonly root: string
+	/** A function id from an earlier answer. */
+	readonly id?: number
+	/** Alternatively, a file and a name; several functions can share one. */
+	readonly path?: string
+	readonly name?: string
+	readonly maxChars?: number
+}
+
+export interface AnalysisFunctionSource {
+	readonly function: AnalysisFunction
+	readonly parents: readonly AnalysisFunction[]
+	readonly source: AnalysisSourceSlice
+}
+
+export interface CallersOfRequest extends AnalysisPaging {
+	readonly root: string
+	/** The callee text: `foo`, `obj.foo`, `this.foo`. */
+	readonly name: string
+	/**
+	 * `file` looks in `path` only and is the default, because a callee matched
+	 * by text is far more likely to be the one you mean inside one file than
+	 * across a bundle of unrelated modules that reuse short names.
+	 */
+	readonly scope?: 'file' | 'workspace'
+	readonly path?: string
+	/**
+	 * `exact` matches the callee text as written. `member` also matches any
+	 * `<expression>.name`, which finds method calls whose receiver is unknown.
+	 */
+	readonly match?: 'exact' | 'member'
+}
+
+export interface AnalysisCallSite {
+	readonly path: string
+	readonly line: number
+	readonly column: number
+	readonly callee: string
+	readonly kind: 'call' | 'new'
+	readonly argumentCount: number
+	/** The function the call sits in; absent at the top level of a file. */
+	readonly caller?: AnalysisFunction
+	/** See {@link AnalysisLiteralHit.stale}. */
+	readonly stale?: 'changed' | 'deleted'
+}
+
+export interface ImportsRequest extends AnalysisPaging {
+	readonly root: string
+	readonly path: string
+}
+
+export type AnalysisModuleEdge =
+	| {
+			readonly direction: 'import'
+			readonly kind: 'static' | 'type' | 'require' | 'dynamic'
+			readonly source: string
+			readonly names: readonly string[]
+			readonly line: number
+			readonly column: number
+	  }
+	| {
+			readonly direction: 'export'
+			readonly kind: 'named' | 'default' | 'reexport' | 'star'
+			readonly name: string
+			readonly source?: string
+			readonly line: number
+			readonly column: number
+	  }
+
+export interface CodeAnalysisProvider {
+	/**
+	 * Build or refresh the index for a directory. Incremental: a file whose
+	 * size and mtime are unchanged is not read, and one whose content hash is
+	 * unchanged is not parsed.
+	 */
+	index(request: IndexRequest): Promise<CodeAnalysisResult<IndexSummary>>
+	/** Where a string appears, and the function around each hit. */
+	findLiteral(
+		request: FindLiteralRequest,
+	): Promise<CodeAnalysisResult<AnalysisPage<AnalysisLiteralHit>>>
+	/** The function containing a position, with its source and parent chain. */
+	enclosingFunction(
+		request: EnclosingFunctionRequest,
+	): Promise<CodeAnalysisResult<AnalysisEnclosingFunction>>
+	/** A function's exact source, by id or by file and name. */
+	functionSource(
+		request: FunctionSourceRequest,
+	): Promise<CodeAnalysisResult<AnalysisPage<AnalysisFunctionSource>>>
+	/** Call sites of a name. Matched by text, not by scope; see the evidence. */
+	callersOf(request: CallersOfRequest): Promise<CodeAnalysisResult<AnalysisPage<AnalysisCallSite>>>
+	/** One file's imports and exports. */
+	imports(request: ImportsRequest): Promise<CodeAnalysisResult<AnalysisPage<AnalysisModuleEdge>>>
+	/** Close whatever backs it. Not optional: an open database is a held file. */
+	dispose(): Promise<void>
+}

package/src/types/provider/errors.ts

@@ -270,6 +270,14 @@ export function readOutputOverflow(err: unknown): OutputOverflowFigures | undefi
 	return undefined
 }
 
+/** Undici's `TypeError: terminated` anywhere on the chain: the body stream was cut. */
+function isUndiciTermination(err: unknown): boolean {
+	for (const link of causeChain(err)) {
+		if ((link as unknown) instanceof TypeError && link.message === 'terminated') return true
+	}
+	return false
+}
+
 /** Node/undici transport failures that mean "never reached the model". */
 const NETWORK_ERRNOS: ReadonlySet<string> = new Set([
 	'ECONNRESET',
@@ -304,12 +312,19 @@ function codeFromStatus(status: number): ProviderErrorCode {
 	return 'unknown'
 }
 
+function overflowWordingAllowed(status: number | undefined): boolean {
+	return status === undefined || status === 400 || status === 413
+}
+
+const CONTEXT_WINDOW_OVERFLOW =
+	/(?:exceed\w*|too (?:long|large|big)|larger than|longer than|over the|beyond|maximum|overflow\w*)\b[^.]{0,60}context window|context window[^.]{0,60}\b(?:exceed\w*|too (?:long|large|big)|larger than|longer than|over the|beyond|maximum|overflow\w*)/i
+
 /**
  * Message sniffing is the LAST resort, used only when there is no status
  * and no errno. Vendors that tunnel a 400 through a 200 body (several
  * gateways do) are only reachable this way.
  */
-function codeFromMessage(message: string): ProviderErrorCode | undefined {
+function codeFromMessage(message: string, status?: number): ProviderErrorCode | undefined {
 	const m = message.toLowerCase()
 	if (
 		m.includes('context length') ||
@@ -322,6 +337,13 @@ function codeFromMessage(message: string): ProviderErrorCode | undefined {
 		// overflow rescue tests for by exact equality. The turn died holding
 		// the remedy.
 		m.includes('too long for') ||
+		// The reference terminal's own wordings (its `context window` and
+		// `input length and max_tokens exceed context limit` matchers).
+		// Only where the status cannot say otherwise: a 429, 5xx or 401 that
+		// mentions the window is still a rate limit, a server fault or an auth
+		// failure, and must keep its retry and fallback behaviour.
+		(overflowWordingAllowed(status) &&
+			(CONTEXT_WINDOW_OVERFLOW.test(message) || m.includes('exceed context limit'))) ||
 		m.includes('maximum length') ||
 		m.includes('exceeds the maximum') ||
 		m.includes('input is too large') ||
@@ -498,7 +520,9 @@ export function classifyProviderError(
 	// usually generic ("request failed") — so matching only the outer text
 	// looks at the one string least likely to say anything.
 	const messages = chainMessages(err)
-	const fromMessage = messages.map(codeFromMessage).find((code) => code !== undefined)
+	const fromMessage = messages
+		.map((m) => codeFromMessage(m, status))
+		.find((code) => code !== undefined)
 	// A first-hand statement from whoever produced the failure, if there
 	// is one. It outranks the code's inference, not the code itself: the
 	// classification still says WHAT went wrong.
@@ -522,7 +546,7 @@ export function classifyProviderError(
 
 	// A 400 that is really a window overflow must not be filed as a plain
 	// invalid_request: the caller can recover from one and not the other.
-	if (messages.some((m) => codeFromMessage(m) === 'context_length_exceeded')) {
+	if (messages.some((m) => codeFromMessage(m, status) === 'context_length_exceeded')) {
 		return new ProviderError({
 			code: 'context_length_exceeded',
 			message,
@@ -566,8 +590,12 @@ export function classifyProviderError(
 		}
 	}
 
-	// `fetch` rejects with a bare TypeError on transport failure.
-	if (err instanceof TypeError && /fetch|network/i.test(message)) {
+	// `fetch` rejects with a bare TypeError on transport failure, and undici
+	// ends a response body the peer cut mid-stream with `TypeError:
+	// terminated`. Its socket error normally rides along as the cause and the
+	// errno walk above catches it, but a vendor SDK that re-wraps the stream
+	// error can drop that cause and leave only the bare word.
+	if ((err instanceof TypeError && /fetch|network/i.test(message)) || isUndiciTermination(err)) {
 		return new ProviderError({
 			code: 'network',
 			message,

package/src/types/provider/interface.ts

@@ -22,6 +22,19 @@ export interface LLMProvider {
 	/** Refine hosted search support for a model and mode. Absent uses the driver-wide declaration. */
 	supportsHostedWebSearchFor?(model: string, mode: 'live' | 'cached'): boolean
 
+	/**
+	 * Whether `model` reads images. `capabilities.supportsVision` is a statement
+	 * about the DRIVER (does it map image parts onto the wire); this is about the
+	 * MODEL behind it, which only the driver's catalogue can know: one driver
+	 * serves vision and text-only models side by side, and a text-only model
+	 * refuses the whole request when it finds an image in it.
+	 *
+	 * Answer `false` only when the model is known to be text-only. Absent, or
+	 * `true`, means "send images": the runtime also recovers from a refusal, so a
+	 * driver with no catalogue loses nothing by omitting this.
+	 */
+	supportsImageInputFor?(model: string): boolean
+
 	/**
 	 * Retry behaviour this DRIVER wants, when the generic default is wrong
 	 * for the vendor behind it.

package/src/types/provider/stream.ts

@@ -174,7 +174,7 @@ export interface ProviderRetryNotice {
 	/** The delay came from the server's own `Retry-After`, not backoff. */
 	readonly serverDirected: boolean
 	/**
-	 * The failed attempt had already streamed text or reasoning, and the request
+	 * The failed attempt had already streamed text or reasoning (reasoning alone is retried without any option), and the request
 	 * is being sent again from the start. Whatever that attempt produced is void
 	 * and the consumer must drop it before the next chunk.
 	 */

package/src/types/session/config.ts

@@ -88,6 +88,20 @@ export interface TurnConfig {
 		 * behaviour every sandboxed turn had before this existed.
 		 */
 		workspace?: 'ephemeral' | 'working-directory'
+		/**
+		 * When the turn acquires its sandbox. Absent means `'eager'`: acquired,
+		 * and waited for, before the input guardrails and the first model
+		 * request.
+		 *
+		 * `'concurrent'` starts at the same point but lets the first model
+		 * request go out while the provider allocates; the first tool call
+		 * waits for the handle. `'on-first-use'` does not start until the first
+		 * tool call. Either way `sandbox_created` is emitted when the handle
+		 * arrives, and a failure or timeout ends the turn with the stop reason
+		 * an eager acquisition would have produced, at the first tool call or
+		 * at turn end, whichever comes first.
+		 */
+		acquire?: 'eager' | 'concurrent' | 'on-first-use'
 	}
 
 	/**

package/src/types/session/events.ts

@@ -280,8 +280,11 @@ type CoreSessionEvent =
 			 *   a provider that rejects the pairing. A reducer bug, and one
 			 *   `findSafeTrimIndex` exists to prevent.
 			 * - `breaker_open` — only with `compactionConfig.circuitBreaker`:
-			 *   three passes in a row failed, so automatic compaction is off for
-			 *   the rest of the turn. Sent once. `messages` is the live count.
+			 *   three passes in a row failed, so proactive compaction is off for
+			 *   the rest of the turn; a context overflow the provider reports
+			 *   still runs the reactive relief. Sent once, without `error`: it is
+			 *   for a host's records, not a line for the person. `messages` is
+			 *   the live count.
 			 * - `refilling` — only with `compactionConfig.circuitBreaker`: the
 			 *   context filled back up within three iterations of a compaction,
 			 *   three times in a row, and the turn is stopping. Sent once.
@@ -289,7 +292,7 @@ type CoreSessionEvent =
 			cause: 'reducer_threw' | 'shed_nothing' | 'split_tool_pair' | 'breaker_open' | 'refilling'
 			/** Unchanged, and stated so a reader need not infer it. */
 			messages: number
-			/** For `reducer_threw`, the reducer's message; for `breaker_open` and `refilling`, the one line to show. */
+			/** For `reducer_threw`, the reducer's message; for `refilling`, the one line to show. */
 			error?: string
 	  }
 	| {
@@ -714,9 +717,26 @@ type CoreSessionEvent =
 			sessionId: SessionId
 			turnId?: TurnId
 			capability: 'tools' | 'vision' | 'documents'
-			/** Present when the mismatch was produced after a tool executed. */
-			contentSource?: 'tool-result'
+			/**
+			 * Present when the mismatch was not about the user's own message:
+			 * `'tool-result'` after a tool executed; `'history'` when the model
+			 * itself turned out not to read images (see `model`) and the images
+			 * already in the conversation were left out of the request;
+			 * `'media-removed'` when the provider rejected an image or document
+			 * and it was left out of the request that then went through;
+			 * `'media-removed-current'` when that included a file attached to the
+			 * latest user message; `'media-limit'` when the oldest files were left
+			 * out only to fit a count the provider accepts.
+			 */
+			contentSource?:
+				| 'tool-result'
+				| 'history'
+				| 'media-removed'
+				| 'media-removed-current'
+				| 'media-limit'
 			providerId: string
+			/** The model that cannot read images, when the warning is about one model rather than the driver. */
+			model?: string
 			message: string
 	  }
 	/**

package/src/types/tool/index.ts

@@ -1,5 +1,6 @@
 import type { ChildProcess } from 'node:child_process'
 import type { z } from 'zod'
+import type { CodeAnalysisProvider } from '../code-analysis/index.js'
 import type { CodeNavigationProvider } from '../code-navigation/index.js'
 // Type-only, and circular by design: a tool-result guardrail is described in
 // terms of the tool that produced the result, and the registry that holds
@@ -465,6 +466,14 @@ export interface ToolContext {
 	 * always says "unavailable" is worse than one that is not there.
 	 */
 	codeNavigation?: CodeNavigationProvider
+	/**
+	 * A semantic index of JavaScript/TypeScript, for the `code_analysis` tool.
+	 *
+	 * Same rule as `codeNavigation`: absent means the tool is not registered,
+	 * so a tool that is always present and always says "unavailable" never
+	 * exists. See `tools/builtins/code-analysis.ts`.
+	 */
+	codeAnalysis?: CodeAnalysisProvider
 	fileReadTracker?: FileReadTracker
 
 	/**