@namzu/sdk 46.0.0 → 48.0.0

package/src/probe/errors.ts

@@ -1,10 +1,13 @@
+import { RegistryCollisionError } from '../registry/collision.js'
 import type { VetoableEventKind } from '../types/probe/index.js'
 
-export class ProbeNameCollisionError extends Error {
+export class ProbeNameCollisionError extends RegistryCollisionError {
 	readonly probeName: string
 
 	constructor(probeName: string) {
 		super(
+			'ProbeRegistry',
+			probeName,
 			`Probe name "${probeName}" is already registered. Pass { override: true } to replace, or pick a different name.`,
 		)
 		this.name = 'ProbeNameCollisionError'

package/src/prompt/coding-agent-doctrine.ts

@@ -97,14 +97,20 @@ When you have understood the task, reply with the plan: what you would change, i
 
 /**
  * Appended after {@link CODING_AGENT_DELEGATION_DOCTRINE} only for a host
- * session that has an orchestration mode turned on. See
- * {@link CodingAgentDoctrineOptions.orchestrate}: this text is a stronger
+ * session that has hypermode (its multi-agent mode) turned on. See
+ * {@link CodingAgentDoctrineOptions.hypermode}: this text is a stronger
  * restatement of the existing delegation rule, not a new capability — it
  * creates no roster, starts no work by itself, and names no tool the base
  * doctrine did not already name.
  */
-export const CODING_AGENT_ORCHESTRATE_DOCTRINE = `### Orchestrate mode
-This session has orchestrate mode on: treat delegation through \`Agent\` as the default for substantive work, not the exception. Before doing multi-step work yourself, ask whether an independent piece of it — a lookup, a draft, a check — could run as its own delegation, and prefer delegating it when the answer is yes. This changes only how eagerly you reach for \`Agent\` on work you would otherwise do inline; it does not mount a roster or start any delegation by itself. Agents in the same phase are launched in the same response, each with \`run_in_background: true\` when you mean to wait for them together; a phase is never started one agent at a time.`
+export const CODING_AGENT_HYPERMODE_DOCTRINE = `### Hypermode
+This session has hypermode on: treat delegation through \`Agent\` as the default for substantive work, not the exception. Before doing multi-step work yourself, ask whether an independent piece of it — a lookup, a draft, a check — could run as its own delegation, and prefer delegating it when the answer is yes. This changes only how eagerly you reach for \`Agent\` on work you would otherwise do inline; it does not mount a roster or start any delegation by itself. Agents in the same phase are launched in the same response, each with \`run_in_background: true\` when you mean to wait for them together; a phase is never started one agent at a time.`
+
+/**
+ * @deprecated Renamed {@link CODING_AGENT_HYPERMODE_DOCTRINE}; the mode it
+ * describes is now called hypermode. Same value. Removed in the next major.
+ */
+export const CODING_AGENT_ORCHESTRATE_DOCTRINE = CODING_AGENT_HYPERMODE_DOCTRINE
 
 export const CODING_AGENT_DOCTRINE_CONTRIBUTION_ID = 'namzu.coding-agent-doctrine'
 
@@ -116,15 +122,21 @@ export interface CodingAgentDoctrineOptions {
 	 */
 	delegation?: boolean
 	/**
-	 * Append {@link CODING_AGENT_ORCHESTRATE_DOCTRINE} after the delegation
-	 * rules, for a host session whose operator turned on an orchestration
-	 * mode. Default `false`, and ignored when `delegation` is `false` — a
-	 * sub-agent prompt never carries delegation guidance of any strength.
+	 * Append {@link CODING_AGENT_HYPERMODE_DOCTRINE} after the delegation
+	 * rules, for a host session whose operator turned hypermode on. Default
+	 * `false`, and ignored when `delegation` is `false` — a sub-agent prompt
+	 * never carries delegation guidance of any strength.
 	 * Display/prompt-only: it creates no scheduling, no roster and no kernel
 	 * behaviour change, the same guarantee the `workflow`/`phase` labels on
 	 * `agent_pending` make. With this left at its default the rendered text
 	 * is byte-identical to before this option existed.
 	 */
+	hypermode?: boolean
+	/**
+	 * @deprecated Renamed {@link CodingAgentDoctrineOptions.hypermode}. Still
+	 * honoured: either flag set to `true` appends the text. Removed in the
+	 * next major.
+	 */
 	orchestrate?: boolean
 }
 
@@ -140,8 +152,8 @@ export function codingAgentDoctrineContribution(
 	const text = [
 		CODING_AGENT_WORKING_DOCTRINE,
 		options.delegation === false ? undefined : CODING_AGENT_DELEGATION_DOCTRINE,
-		options.delegation !== false && options.orchestrate
-			? CODING_AGENT_ORCHESTRATE_DOCTRINE
+		options.delegation !== false && (options.hypermode || options.orchestrate)
+			? CODING_AGENT_HYPERMODE_DOCTRINE
 			: undefined,
 	]
 		.filter((part): part is string => Boolean(part))

package/src/prompt/contributions.ts

@@ -1,4 +1,5 @@
 import { renderSkillsSection } from '../persona/assembler.js'
+import { RegistryCollisionError } from '../registry/collision.js'
 import type { AgentRuntimeContext } from '../types/agent/base.js'
 import type { Skill } from '../types/skills/index.js'
 
@@ -112,11 +113,15 @@ export interface PromptContribution {
 }
 
 /** Two contributions claiming one id. */
-export class PromptContributionCollisionError extends Error {
+export class PromptContributionCollisionError extends RegistryCollisionError {
 	readonly details: { id: string }
 
 	constructor(details: { id: string }) {
-		super(`A prompt contribution with id "${details.id}" is already registered.`)
+		super(
+			'PromptContributionRegistry',
+			details.id,
+			`A prompt contribution with id "${details.id}" is already registered.`,
+		)
 		this.name = 'PromptContributionCollisionError'
 		this.details = details
 	}
@@ -145,6 +150,11 @@ export class PromptContributionRegistry {
 		this.byId.set(contribution.id, contribution)
 	}
 
+	/** Revoke one contribution when its owner is disabled or uninstalled. */
+	unregister(id: string): boolean {
+		return this.byId.delete(id)
+	}
+
 	has(id: string): boolean {
 		return this.byId.has(id)
 	}

package/src/prompt/index.ts

@@ -16,6 +16,7 @@ export type {
 export {
 	CODING_AGENT_DELEGATION_DOCTRINE,
 	CODING_AGENT_DOCTRINE_CONTRIBUTION_ID,
+	CODING_AGENT_HYPERMODE_DOCTRINE,
 	CODING_AGENT_ORCHESTRATE_DOCTRINE,
 	CODING_AGENT_WORKING_DOCTRINE,
 	PLAN_MODE_DOCTRINE,

package/src/provider/collect-chat-completion.ts

@@ -1,8 +1,33 @@
 import { mergeTokenUsage } from '../types/common/index.js'
-import type { ReasoningBlock } from '../types/message/index.js'
+import type { ReasoningBlock, ToolInputError } from '../types/message/index.js'
 import type { ChatCompletionResponse } from '../types/provider/chat.js'
 import type { StreamChunk } from '../types/provider/stream.js'
 import { StreamTextAccumulator } from './stream-text.js'
+import {
+	INTERLEAVED_TOOL_INPUT_PARSE_ERROR,
+	ToolCallIndexer,
+	describeToolCallFramingViolation,
+	isUnindexedFragment,
+	toolCallFramingViolation,
+} from './tool-call-framing.js'
+
+/**
+ * Whether a streamed argument buffer could still be receiving more of a
+ * call's arguments right now: empty, or not yet a complete JSON value. Used
+ * only by `ToolCallIndexer.placeUnindexedFragment` to tell which open calls
+ * could still be an id-less fragment's target — not to validate a finished
+ * call, so it does not need the offset-finding `parseToolArguments` the turn
+ * loop uses for the message a model is shown.
+ */
+function canAcceptMoreText(buffer: string): boolean {
+	if (!buffer) return true
+	try {
+		JSON.parse(buffer)
+		return false
+	} catch {
+		return true
+	}
+}
 
 /**
  * Drains a {@link StreamChunk} async iterable into the equivalent
@@ -18,7 +43,12 @@ import { StreamTextAccumulator } from './stream-text.js'
  * - ordinary text is concatenated in delta order; identified public text
  *   items are preserved and explicit final-answer items select the settled text;
  * - tool calls are bucketed by `index` into the existing
- *   `Array<{ id, function: { name, arguments } }>` shape;
+ *   `Array<{ id, function: { name, arguments } }>` shape. Arguments that
+ *   arrive before the call's id belong to the call at their index and are
+ *   kept; the id is filled in when it arrives. A stream that puts a second
+ *   call id on an index is refused with an error naming the violation, as
+ *   the turn loop refuses it: the second call's arguments used to be
+ *   appended to the first's, which left one call no tool could run;
  * - reasoning blocks are bucketed by `index` the same way, because the
  *   assembled message is the thing a caller replays and
  *   {@link ReasoningBlock} is documented as replayed verbatim. This was
@@ -41,6 +71,7 @@ export async function collectChatCompletion(
 	const text = new StreamTextAccumulator()
 	let replayState: unknown
 	let finishReason: ChatCompletionResponse['finishReason'] = 'stop'
+	let finishDetail: ChatCompletionResponse['finishDetail']
 	let usage: ChatCompletionResponse['usage'] = {
 		promptTokens: 0,
 		completionTokens: 0,
@@ -49,7 +80,12 @@ export async function collectChatCompletion(
 		cacheWriteTokens: 0,
 	}
 
-	const toolBuckets = new Map<number, { id: string; name: string; argsBuf: string }>()
+	const toolBuckets = new Map<
+		number,
+		{ id: string; name: string; argsBuf: string; unreadable?: boolean }
+	>()
+	// Places a fragment that came without an index; see `ToolCallIndexer`.
+	const toolIndexer = new ToolCallIndexer()
 	// Same bucketing rule the turn loop uses (`runtime/query/iteration/
 	// stream-turn.ts`), so a message assembled here and a message assembled
 	// there carry the same blocks in the same order.
@@ -81,18 +117,47 @@ export async function collectChatCompletion(
 		}
 
 		for (const tc of chunk.delta.toolCalls ?? []) {
-			const bucket = toolBuckets.get(tc.index) ?? {
-				id: '',
-				name: '',
-				argsBuf: '',
+			if (isUnindexedFragment(tc)) {
+				// Neither an id nor an index: never a guess. Evaluated fresh for
+				// THIS fragment, not decided once when some call opened.
+				const placement = toolIndexer.placeUnindexedFragment((i) =>
+					canAcceptMoreText(toolBuckets.get(i)?.argsBuf ?? ''),
+				)
+				if (typeof placement === 'number') {
+					const bucket = toolBuckets.get(placement) ?? { id: '', name: '', argsBuf: '' }
+					if (tc.function?.name) bucket.name = tc.function.name
+					if (tc.function?.arguments) bucket.argsBuf += tc.function.arguments
+					toolBuckets.set(placement, bucket)
+				} else {
+					// More than one open call could still have taken this
+					// fragment, or none could: every candidate is unreadable, and
+					// the fragment itself is attributed to none of them —
+					// appending it to a guess is exactly the splice this exists
+					// to refuse.
+					for (const candidate of placement.candidates) {
+						const bucket = toolBuckets.get(candidate.index)
+						if (bucket) bucket.unreadable = true
+					}
+				}
+				continue
 			}
-			if (tc.id) bucket.id = tc.id
+			const index = toolIndexer.indexOf(tc)
+			const open = toolBuckets.get(index)
+			const violation = toolCallFramingViolation(open, tc, index)
+			if (violation) {
+				throw new Error(`Provider stream error: ${describeToolCallFramingViolation(violation)}`)
+			}
+			const bucket = open ?? { id: '', name: '', argsBuf: '' }
+			if (tc.id && !bucket.id) bucket.id = tc.id
 			if (tc.function?.name) bucket.name = tc.function.name
 			if (tc.function?.arguments) bucket.argsBuf += tc.function.arguments
-			toolBuckets.set(tc.index, bucket)
+			toolBuckets.set(index, bucket)
 		}
 
-		if (chunk.finishReason) finishReason = chunk.finishReason
+		if (chunk.finishReason) {
+			finishReason = chunk.finishReason
+			finishDetail = chunk.finishReason === 'length' ? chunk.finishDetail : undefined
+		}
 		// Merge (per-field max), not last-write-wins: a late frame that omits
 		// input/cache tokens must not zero the counts captured earlier in the stream.
 		if (chunk.usage) usage = mergeTokenUsage(usage, chunk.usage)
@@ -103,7 +168,26 @@ export async function collectChatCompletion(
 		.map(([, b]) => ({
 			id: b.id,
 			type: 'function' as const,
-			function: { name: b.name, arguments: b.argsBuf },
+			// An interleaved call is never returned with the buffer it
+			// accumulated: that buffer may hold another call's spliced-in
+			// fragments, or may simply be missing whatever an id-less
+			// fragment carried elsewhere instead. Normalized to `{}`, exactly
+			// as the turn loop normalizes any other unreadable call.
+			function: { name: b.name, arguments: b.unreadable ? '{}' : b.argsBuf },
+			...(b.unreadable
+				? {
+						metadata: {
+							inputTruncated: true,
+							partialArguments: b.argsBuf,
+							inputError: {
+								reason: 'malformed',
+								parseError: INTERLEAVED_TOOL_INPUT_PARSE_ERROR,
+								length: b.argsBuf.length,
+								precedingLength: 0,
+							} satisfies ToolInputError,
+						},
+					}
+				: {}),
 		}))
 
 	const reasoningBlocks: ReasoningBlock[] = [...reasoningBuckets.entries()]
@@ -122,6 +206,7 @@ export async function collectChatCompletion(
 			...(replayState !== undefined ? { replayState } : {}),
 		},
 		finishReason,
+		...(finishDetail ? { finishDetail } : {}),
 		usage,
 	}
 }

package/src/provider/mock.ts

@@ -129,8 +129,15 @@ export class MockLLMProvider implements LLMProvider {
 			}
 
 			// Arguments arrive as JSON fragments, which is what forces the
-			// consumer's partial-JSON buffering to be exercised.
-			const args = call.rawArguments ?? JSON.stringify(call.args ?? {})
+			// consumer's partial-JSON buffering to be exercised. A truncated
+			// call stops halfway, as the output limit stops a real one: it
+			// used to send every fragment and only withhold the block close,
+			// so the arguments parsed and nothing was truncated at all.
+			const fullArgs = call.rawArguments ?? JSON.stringify(call.args ?? {})
+			const args =
+				call.truncateArguments === true
+					? fullArgs.slice(0, Math.max(1, Math.floor(fullArgs.length / 2)))
+					: fullArgs
 			const step = call.argChunkSize ?? Math.max(1, Math.ceil(args.length / 3))
 			for (let i = 0; i < args.length; i += step) {
 				yield {
@@ -143,15 +150,26 @@ export class MockLLMProvider implements LLMProvider {
 				throw new Error(call.throwAfterArguments)
 			}
 
-			if (call.truncateArguments !== true) {
-				yield { id, delta: { toolCallEnd: { index, id: callId } } }
-			}
+			// An output limit stops the response where it is, so nothing the
+			// script puts after a truncated call is streamed. It used to go on
+			// to the next call, which made the cut call one the model had
+			// moved on from: malformed, not truncated.
+			if (call.truncateArguments === true) break
+			yield { id, delta: { toolCallEnd: { index, id: callId } } }
 		}
 
 		yield {
 			id,
 			delta: {},
-			finishReason: turn.finishReason ?? (toolCalls.length > 0 ? 'tool_calls' : 'stop'),
+			finishReason:
+				turn.finishReason ??
+				// A call cut off mid-JSON is what the output limit does, and the
+				// finish reason is how a consumer tells that from malformed JSON.
+				(toolCalls.some((call) => call.truncateArguments === true)
+					? 'length'
+					: toolCalls.length > 0
+						? 'tool_calls'
+						: 'stop'),
 			usage: { ...EMPTY_USAGE, ...turn.usage },
 		}
 	}

package/src/provider/registry.ts

@@ -1,3 +1,4 @@
+import { RegistryCollisionError } from '../registry/collision.js'
 import type {
 	LLMProvider,
 	LLMProviderConstructor,
@@ -23,11 +24,13 @@ export class UnknownProviderError extends Error {
 	}
 }
 
-export class DuplicateProviderError extends Error {
+export class DuplicateProviderError extends RegistryCollisionError {
 	readonly providerType: string
 
 	constructor(providerType: string) {
 		super(
+			'ProviderRegistry',
+			providerType,
 			`Provider type "${providerType}" is already registered. Pass { replace: true } to override an existing registration.`,
 		)
 		this.name = 'DuplicateProviderError'

package/src/provider/tool-call-framing.ts

@@ -0,0 +1,226 @@
+import type { StreamChunk } from '../types/provider/stream.js'
+
+type ToolCallDelta = NonNullable<StreamChunk['delta']['toolCalls']>[number]
+
+/**
+ * A stream that broke tool-call framing: a second call id on an `index`
+ * another call holds.
+ *
+ * The index is what groups a call's fragments, so after this no buffer can be
+ * trusted to hold one call's arguments. The second call's arguments used to be
+ * appended to the first's; the buffer that reached `JSON.parse` was then not
+ * what the model sent, and the model was told its call had been cut off.
+ *
+ * Nothing else about a call's framing is a violation. Arguments that arrive
+ * before the call's id belong to the call at their index and are kept, and a
+ * call whose id never arrives is still one call.
+ */
+export interface ToolCallFramingViolation {
+	readonly kind: 'index_reused'
+	readonly index: number
+	readonly openId: string
+	readonly newId: string
+}
+
+/**
+ * Whether this tool-call delta puts a new call on an index another call
+ * holds, or `undefined` when it does not.
+ *
+ * The same id repeated on every fragment is fine: some wires send it each
+ * time. Only a different one is a second call.
+ */
+export function toolCallFramingViolation(
+	open: { readonly id: string } | undefined,
+	delta: ToolCallDelta,
+	/** The index the fragment was placed on, when it came without one. */
+	index: number = delta.index,
+): ToolCallFramingViolation | undefined {
+	if (open?.id && delta.id && delta.id !== open.id) {
+		return { kind: 'index_reused', index, openId: open.id, newId: delta.id }
+	}
+	return undefined
+}
+
+function hasIndex(index: number | undefined): index is number {
+	return typeof index === 'number' && Number.isInteger(index) && index >= 0
+}
+
+/**
+ * Whether a fragment carries neither an index nor an id — the one shape
+ * `ToolCallIndexer.indexOf` cannot place by itself, and the only shape
+ * {@link ToolCallIndexer.placeUnindexedFragment} is for. A fragment with
+ * either goes through `indexOf` instead, unaffected by anything below.
+ */
+export function isUnindexedFragment(delta: {
+	readonly index?: number
+	readonly id?: string
+}): boolean {
+	return !hasIndex(delta.index) && !delta.id
+}
+
+/**
+ * The index each tool-call fragment of one stream belongs to.
+ *
+ * A driver sets `index`, and the index is what groups a call's fragments.
+ * Some servers leave it out of their `tool_calls` fragments, and a driver
+ * that passes the wire value through then sends none. Every such fragment used
+ * to land on one `undefined` index: two parallel calls were refused as a
+ * reused index, and the turn paused on a stream that had nothing wrong with
+ * it but the missing field.
+ *
+ * A fragment that carries an id, with or without an index, is placed by
+ * {@link indexOf}: an id seen before continues its call; a new id names the
+ * call the latest fragment went to when that call has no id yet, and starts a
+ * call on the next free index otherwise. A fragment that carries an index
+ * keeps it, so a well-formed stream is read exactly as before and a real
+ * reuse of an index is still refused.
+ *
+ * A fragment with NEITHER an id nor an index — see
+ * {@link isUnindexedFragment} — goes through {@link placeUnindexedFragment}
+ * instead, which is never a guess: nothing in such a fragment says which call
+ * it continues, so the caller is asked, for every call opened so far,
+ * whether it could still be receiving more of its arguments right now, and
+ * the fragment is placed only when the answer says exactly one call.
+ */
+export class ToolCallIndexer {
+	private readonly byId = new Map<string, number>()
+	private readonly idOf = new Map<number, string>()
+	private readonly named = new Set<number>()
+	private readonly opened = new Set<number>()
+	private latest: number | undefined
+	private next = 0
+
+	/** The index this id- or index-bearing fragment belongs to. */
+	indexOf(delta: { readonly index?: number; readonly id?: string }): number {
+		const index = hasIndex(delta.index) ? delta.index : this.placed(delta.id)
+		if (delta.id && !this.byId.has(delta.id)) this.byId.set(delta.id, index)
+		if (delta.id) {
+			this.named.add(index)
+			this.idOf.set(index, delta.id)
+		}
+		this.opened.add(index)
+		if (index >= this.next) this.next = index + 1
+		this.latest = index
+		return index
+	}
+
+	private placed(id: string | undefined): number {
+		if (!id) return this.latest ?? this.next
+		const known = this.byId.get(id)
+		if (known !== undefined) return known
+		return this.latest !== undefined && !this.named.has(this.latest) ? this.latest : this.next
+	}
+
+	/**
+	 * Where a fragment with neither an id nor an index belongs — see
+	 * {@link isUnindexedFragment}.
+	 *
+	 * Evaluated fresh for every such fragment, never decided once and
+	 * remembered from when a call opened: a call's buffer can go from
+	 * accepting more text to not (once it completes) and stay that way, so
+	 * only the state right now, at each fragment, says which calls could
+	 * still be its target. `canAccept(index)` is asked for every call opened
+	 * so far and answers exactly that: true while its buffer is empty or is
+	 * not yet a complete JSON value (it could still be receiving more), false
+	 * once the buffer already parses as one complete value (nothing more is
+	 * missing from it).
+	 *
+	 * - No call has opened yet: this fragment starts the first one. An id
+	 *   for it, if the stream sends one, arrives on a later fragment and
+	 *   attaches to it — the ordinary "arguments before the id" case,
+	 *   unchanged.
+	 * - Exactly one open call can still accept: it is unambiguously that
+	 *   one.
+	 * - Zero, or more than one, open call can: there is no way to tell which
+	 *   one this fragment was for, or none could take it at all. Every call
+	 *   that could have is returned in `candidates` (empty when none could),
+	 *   and the fragment belongs to none of them — appending it to a guess
+	 *   is exactly the splice this method exists to refuse.
+	 */
+	placeUnindexedFragment(
+		canAccept: (index: number) => boolean,
+	):
+		| number
+		| { readonly candidates: ReadonlyArray<{ readonly index: number; readonly id?: string }> } {
+		if (this.opened.size === 0) {
+			const index = this.next
+			this.opened.add(index)
+			this.next = index + 1
+			this.latest = index
+			return index
+		}
+		const candidates = [...this.opened].filter(canAccept)
+		if (candidates.length === 1) {
+			const [index] = candidates as [number]
+			this.latest = index
+			return index
+		}
+		return {
+			candidates: candidates
+				.sort((a, b) => a - b)
+				.map((index) => ({ index, id: this.idOf.get(index) })),
+		}
+	}
+
+	/**
+	 * The index a block close belongs to: its own, or, when it has none, the
+	 * call its id names, or the call the latest fragment went to.
+	 */
+	closedIndex(end: { readonly index?: number; readonly id?: string }): number | undefined {
+		if (hasIndex(end.index)) return end.index
+		return (end.id ? this.byId.get(end.id) : undefined) ?? this.latest
+	}
+}
+
+/** One sentence naming the violation, for an error's detail. */
+export function describeToolCallFramingViolation(violation: ToolCallFramingViolation): string {
+	return `the stream reused tool-call index ${violation.index} for call "${violation.newId}" while call "${violation.openId}" held it`
+}
+
+/**
+ * A stream sent a fragment with neither an id nor an index while more than
+ * one open call could still have been its target, or while none could.
+ *
+ * {@link ToolCallIndexer.placeUnindexedFragment} places such a fragment only
+ * when exactly one open call can still accept more text right now (its
+ * buffer empty, or not yet a complete JSON value). Once two calls are both
+ * in that state — the ordinary shape of a chat-completions "open" fragment,
+ * name and id with empty arguments, sent for one call right after another,
+ * before either has streamed any argument text — a later fragment naming
+ * neither could belong to either, and there is no field in it that says
+ * which. Guessing (placing it on whichever call was merely most recently
+ * active) can splice one call's JSON into the other's, and the splice can
+ * still happen to parse, so the wrong call runs with no error at all.
+ *
+ * `candidates` names every call that could have accepted the fragment: more
+ * than one when ambiguous, empty when the fragment matched no open call
+ * (nothing to route it to, and nothing to blame for it either).
+ */
+export interface ToolCallInterleaving {
+	readonly kind: 'interleaved_without_index'
+	readonly candidates: ReadonlyArray<{ readonly index: number; readonly id?: string }>
+}
+
+/** One sentence naming the interleaving, for an error's detail or log line. */
+export function describeToolCallInterleaving(interleaving: ToolCallInterleaving): string {
+	if (interleaving.candidates.length === 0) {
+		return 'the stream sent a tool-call fragment with neither an index nor an id, and no open call could still have accepted it'
+	}
+	const names = interleaving.candidates
+		.map((c) => (c.id ? `"${c.id}"` : `index ${c.index} (not yet named)`))
+		.join(' and ')
+	return `the stream sent a tool-call fragment with neither an index nor an id while ${names} could each still have accepted it, with nothing to tell them apart`
+}
+
+/**
+ * The `ToolInputError.parseError` given to every call an interleaving names.
+ * Reported `reason: 'malformed'`, never `'truncated'`: nothing here says the
+ * response was cut off, and "the model moved on to more text, reasoning or
+ * another call" — the only other case {@link ToolInputError} models — is
+ * exactly what opening a second call means. A call this leaves open may
+ * genuinely have gone on to carry valid JSON, if by chance no ambiguous
+ * fragment ever decided its fate; it is still reported unreadable rather
+ * than risk having guessed right by luck on some other stream.
+ */
+export const INTERLEAVED_TOOL_INPUT_PARSE_ERROR =
+	"its fragments arrived interleaved with another call's, with neither carrying an index to tell them apart"