gemi 0.60.0 → 0.62.0

package/dist/ai/client/index.js

@@ -0,0 +1,1053 @@
+import { t as useParams } from "../../chunks/useParams-BN3XXfmG.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+//#region ai/client/reducer.ts
+function initialChatState(init = {}) {
+	return {
+		messages: init.messages ? [...init.messages] : [],
+		pending: init.pending ? [...init.pending] : [],
+		error: null,
+		threadId: init.threadId,
+		seq: init.seq ?? -1,
+		cursorRunId: init.cursorRunId,
+		runMessageIds: [],
+		loadedTools: []
+	};
+}
+/**
+* Apply one frame.
+*
+* `now` is an argument rather than a `Date.now()` call so the reducer stays a
+* pure function of its inputs — it is only ever read when a frame arrives for a
+* message the list has not seen, which is precisely the mid-run-attach path a
+* test needs to pin down.
+*/
+function applyFrame(state, frame, now = (/* @__PURE__ */ new Date()).toISOString()) {
+	if (!(frame.event.type === "run-start" && frame.event.runId !== state.cursorRunId) && frame.seq <= state.seq) return state;
+	return {
+		...reduce(state, frame.event, now),
+		seq: frame.seq
+	};
+}
+function reduce(state, event, now) {
+	switch (event.type) {
+		case "run-start": return {
+			...state,
+			runId: event.runId,
+			cursorRunId: event.runId,
+			threadId: event.threadId ?? state.threadId,
+			runMessageIds: [],
+			loadedTools: [],
+			finishReason: void 0
+		};
+		case "message-start": return withMessage(state, event.messageId, now, (message) => ({
+			...message,
+			role: event.role
+		}));
+		case "text-delta":
+			if (isFinished(state, event.messageId)) return state;
+			return withMessage(state, event.messageId, now, (message) => ({
+				...message,
+				content: appendText(message.content, event.delta)
+			}));
+		case "reasoning-delta":
+			if (isFinished(state, event.messageId)) return state;
+			return withMessage(state, event.messageId, now, (message) => ({
+				...message,
+				content: appendReasoning(message.content, event.delta, event.id)
+			}));
+		case "output-delta": return withMessage(state, event.messageId, now, (message) => ({
+			...message,
+			content: upsert(message.content, {
+				type: "output",
+				value: event.snapshot,
+				partial: true
+			}, (part) => part.type === "output")
+		}));
+		case "tool-call": return withMessage(state, event.messageId, now, (message) => {
+			const index = message.content.findIndex((part) => part.type === "tool-call" && part.toolCallId === event.part.toolCallId);
+			const existing = index === -1 ? void 0 : message.content[index];
+			const progress = event.part.progress ?? existing?.progress;
+			const nested = event.part.nested ?? existing?.nested;
+			const part = {
+				...event.part,
+				...progress ? { progress } : {},
+				...nested ? { nested } : {}
+			};
+			const content = message.content.slice();
+			if (index === -1) content.push(part);
+			else content[index] = part;
+			return {
+				...message,
+				content
+			};
+		});
+		case "tool-search": {
+			const loaded = event.loaded.filter((name) => !state.loadedTools.includes(name));
+			if (loaded.length === 0) return state;
+			return {
+				...state,
+				loadedTools: [...state.loadedTools, ...loaded]
+			};
+		}
+		case "tool-progress": return withToolCall(state, event.toolCallId, (part) => ({
+			...part,
+			progress: [...part.progress ?? [], event.data]
+		}));
+		case "nested-event": {
+			const nestedEvent = event;
+			return withToolCall(state, event.toolCallId, (part) => {
+				const runs = part.nested ?? [];
+				const index = runs.findIndex((run) => run.runId === nestedEvent.runId);
+				const next = applyNested(runs[index] ?? {
+					runId: nestedEvent.runId,
+					agent: nestedEvent.agent,
+					messages: []
+				}, nestedEvent, now);
+				const nested = index === -1 ? [...runs, next] : runs.map((r, i) => i === index ? next : r);
+				return {
+					...part,
+					nested
+				};
+			});
+		}
+		case "tool-result": {
+			const next = withMessage(state, event.messageId, now, (message) => ({
+				...message,
+				content: upsert(message.content, event.part, (part) => part.type === "tool-result" && part.toolCallId === event.part.toolCallId)
+			}));
+			return {
+				...next,
+				pending: next.pending.filter((call) => call.toolCallId !== event.part.toolCallId)
+			};
+		}
+		case "awaiting-input": return {
+			...state,
+			runId: event.runId,
+			pending: [...event.pending]
+		};
+		case "message-end": return withMessage(state, event.messageId, now, (message) => ({
+			...message,
+			finishReason: event.finishReason,
+			content: message.content.map((part) => part.type === "output" && part.partial ? {
+				...part,
+				partial: false
+			} : part)
+		}));
+		case "usage": {
+			const index = lastIndexWhere(state.messages, (message) => message.role === "assistant");
+			if (index === -1) return state;
+			const messages = state.messages.slice();
+			messages[index] = {
+				...messages[index],
+				usage: event.usage
+			};
+			return {
+				...state,
+				messages
+			};
+		}
+		case "error": return {
+			...state,
+			error: event.error,
+			pending: []
+		};
+		case "run-end": return {
+			...state,
+			runId: void 0,
+			finishReason: event.finishReason,
+			messages: finishUnended(state, event.finishReason)
+		};
+		default: return state;
+	}
+}
+/**
+* The interrupted turn, kept.
+*
+* `stop()` calls this before the server has said anything, because the point of
+* stopping is that the UI reacts now. Whatever the assistant had produced stays
+* in the list marked `aborted` — dropping it would lose text the user already
+* read, and would leave the transcript unable to say it was cut short.
+*
+* `pending` is untouched: a question the conversation is holding survives a
+* stopped run, and clearing it would silently discard the answer the user still
+* owes.
+*/
+function markAborted(state) {
+	return {
+		...state,
+		runId: void 0,
+		finishReason: "aborted",
+		messages: finishUnended(state, "aborted")
+	};
+}
+/**
+* The messages this run wrote, finished off with `reason` if they never ended —
+* and, inside them, the sub-runs this run left mid-sentence.
+*
+* The nesting descent is not an extra: a `NestedRun` renders with the component
+* that renders `messages`, so a nested message with no `finishReason` draws a
+* live cursor inside a block that will never receive another frame. The parent
+* ending is the last word anything will say about it, and for `markAborted`
+* there is no other word available at all — `stop()` marks the transcript
+* optimistically, before the server has answered, so no forwarded nested
+* `run-end` can arrive in time.
+*
+* It recurses through `closeRun`, which builds a `ChatState` around the sub-run
+* and calls back here, so a sub-sub-run is closed by the same three lines that
+* close the top level — the same trick `applyNested` plays on the way in.
+*/
+function finishUnended(state, reason) {
+	return state.messages.map((message) => message.role === "assistant" && state.runMessageIds.includes(message.id) ? closeMessage(message, reason) : message);
+}
+/**
+* One message of this run, and the sub-runs hanging off its tool calls.
+*
+* The message's own finish reason is only filled in when it is missing, but the
+* descent happens either way: the message a run parks on is *finished* while the
+* sub-run underneath it is still live, and that is the case where the block
+* stuck streaming is easiest to hit.
+*/
+function closeMessage(message, reason) {
+	const content = message.content.map((part) => part.type === "tool-call" && part.nested?.some((run) => run.finishReason === void 0) ? {
+		...part,
+		nested: part.nested.map((run) => run.finishReason === void 0 ? closeRun(run, reason) : run)
+	} : part);
+	if (message.finishReason === void 0) return {
+		...message,
+		finishReason: reason,
+		content
+	};
+	return content.some((part, index) => part !== message.content[index]) ? {
+		...message,
+		content
+	} : message;
+}
+/** A sub-run the parent outlived, stamped with the parent's reason, recursively. */
+function closeRun(run, reason) {
+	const sub = {
+		messages: run.messages,
+		pending: [],
+		error: null,
+		seq: -1,
+		runMessageIds: run.messages.map((message) => message.id),
+		loadedTools: []
+	};
+	return {
+		...run,
+		finishReason: reason,
+		messages: finishUnended(sub, reason)
+	};
+}
+/**
+* Run one update over the tool-call part with this id, wherever it lives.
+*
+* `tool-progress` and `nested-event` are the only events that name a tool call
+* without naming a message, so the message has to be found rather than told —
+* a scan from the newest end, because the call being worked on is the one that
+* just arrived.
+*
+* **A frame for a tool call this transcript does not have is dropped.** That is
+* the mid-run `/attach` case the whole file is written for, and it is the one
+* place the usual answer — create it on the spot — is the wrong one: a
+* `ToolCallPart` needs a tool `name` and an `input`, and neither is on these
+* events. Inventing them would put a tool call the model never made into the
+* transcript, under a name that is not a key of the agent's tools, which breaks
+* the narrowing that is the reason the shapes are carried into the browser at
+* all. So the progress is lost and the transcript stays true, rather than the
+* other way round.
+*
+* In practice a client that has the cursor has the part: `useChat` documents
+* `cursor` and `initialMessages` as things to persist together, and a client
+* that persisted one without the other is already the case that doubles text.
+* Parking the orphans until their tool call shows up was considered and is not
+* worth it — the call is *earlier* in the stream, never later, so nothing would
+* ever drain the parking lot.
+*/
+function withToolCall(state, toolCallId, update) {
+	for (let i = state.messages.length - 1; i >= 0; i--) {
+		const message = state.messages[i];
+		const index = message.content.findIndex((part) => part.type === "tool-call" && part.toolCallId === toolCallId);
+		if (index === -1) continue;
+		if (message.finishReason !== void 0 && !isReenterable(state, message, toolCallId)) return state;
+		const content = message.content.slice();
+		content[index] = update(content[index]);
+		const messages = state.messages.slice();
+		messages[i] = {
+			...message,
+			content
+		};
+		const runMessageIds = state.runMessageIds.includes(message.id) ? state.runMessageIds : [...state.runMessageIds, message.id];
+		return {
+			...state,
+			runMessageIds,
+			messages
+		};
+	}
+	return state;
+}
+/**
+* One sub-run event, applied to the sub-run's own transcript.
+*
+* The sub-state is built and thrown away per event rather than kept, because
+* there is nowhere to keep it: `NestedRun` is a wire type and holds a
+* transcript, not a reducer state. Everything the inner `reduce` needs is
+* derivable from it.
+*
+*   - `seq` is `-1` and this calls `reduce`, not `applyFrame`. A nested event
+*     has no sequence of its own; it is numbered in the *parent's* stream, and
+*     the parent's cursor has already refused the duplicates.
+*   - `runMessageIds` is every message in the transcript, which for a nested
+*     run is exactly right and needs none of the parent's care. The parent
+*     scopes it because its list mixes runs; a `NestedRun` is keyed by `runId`
+*     and only ever written by events carrying that id, so every message in it
+*     belongs to the run that is ending.
+*   - `pending` is dropped. An escalated question reaches the user on the
+*     *parent's* `awaiting-input`, carrying the path that says which tool to
+*     re-enter; the copy inside the sub-run's own stream carries no path, so
+*     surfacing it would show the question twice and make one of them
+*     unanswerable.
+*/
+function applyNested(run, event, now) {
+	const next = reduce({
+		messages: run.messages,
+		pending: [],
+		error: null,
+		seq: -1,
+		runMessageIds: run.messages.map((message) => message.id),
+		loadedTools: [],
+		finishReason: run.finishReason
+	}, event.event, now);
+	return {
+		...run,
+		...event.label !== void 0 ? { label: event.label } : {},
+		messages: next.messages,
+		...next.finishReason !== void 0 ? { finishReason: next.finishReason } : {},
+		...event.event.type === "usage" ? { usage: event.event.usage } : {}
+	};
+}
+/**
+* Whether a finished message's tool call can still be written to.
+*
+* Exactly one message can say yes: the one a run parked on, holding a call
+* nobody has answered yet. That is the resume turn — the tool is re-entered
+* from the top and streams progress and sub-run events against a message that
+* closed on the previous turn.
+*
+* "Open" is the server's own test, `Agent.openCalls`: a tool call with no
+* `tool-result` for it anywhere in the transcript. The result is the thing that
+* says the re-entry finished, and it always arrives *after* the frames this
+* guards — `attachToHistory` emits it once `executeTool` returns.
+*/
+function isReenterable(state, message, toolCallId) {
+	if (message.finishReason !== "awaiting-input") return false;
+	return !state.messages.some((candidate) => candidate.content.some((part) => part.type === "tool-result" && part.toolCallId === toolCallId));
+}
+function isFinished(state, messageId) {
+	const message = state.messages.find((candidate) => candidate.id === messageId);
+	return message !== void 0 && message.finishReason !== void 0;
+}
+function lastIndexWhere(items, match) {
+	for (let i = items.length - 1; i >= 0; i--) if (match(items[i])) return i;
+	return -1;
+}
+function withMessage(state, messageId, now, update) {
+	const index = state.messages.findIndex((message) => message.id === messageId);
+	const runMessageIds = state.runMessageIds.includes(messageId) ? state.runMessageIds : [...state.runMessageIds, messageId];
+	if (index === -1) {
+		const blank = {
+			id: messageId,
+			role: "assistant",
+			content: [],
+			createdAt: now
+		};
+		return {
+			...state,
+			runMessageIds,
+			messages: [...state.messages, update(blank)]
+		};
+	}
+	const messages = state.messages.slice();
+	messages[index] = update(messages[index]);
+	return {
+		...state,
+		runMessageIds,
+		messages
+	};
+}
+function appendText(content, delta) {
+	const last = content[content.length - 1];
+	if (last && last.type === "text") return [...content.slice(0, -1), {
+		type: "text",
+		text: last.text + delta
+	}];
+	return [...content, {
+		type: "text",
+		text: delta
+	}];
+}
+/**
+* Mirrors `appendReasoning` in Agent.ts, including its merge rule: deltas join
+* the last part only when the reasoning-item id matches, so a step that
+* produced two items stays two parts instead of flattening into one under the
+* wrong id. The two implementations have to agree, because a stateless client
+* posts this content straight back and the provider matches on that id.
+*/
+function appendReasoning(content, delta, id) {
+	const last = content[content.length - 1];
+	if (last && last.type === "reasoning" && last.id === id) return [...content.slice(0, -1), {
+		...last,
+		text: (last.text ?? "") + delta
+	}];
+	return [...content, id ? {
+		type: "reasoning",
+		id,
+		text: delta
+	} : {
+		type: "reasoning",
+		text: delta
+	}];
+}
+function upsert(content, part, match) {
+	const index = content.findIndex(match);
+	if (index === -1) return [...content, part];
+	const next = content.slice();
+	next[index] = part;
+	return next;
+}
+//#endregion
+//#region ai/client/sse.ts
+/**
+* Bytes to frames.
+*
+* Split out of the hook because none of it is React: it is a byte-level parser,
+* and the interesting cases — a chunk boundary landing inside a `data:` line, a
+* multi-byte character split across two reads, a stream that dies mid-event —
+* are all reachable from a test with a string and no DOM.
+*
+* Deliberately not `EventSource`. The agent routes are POSTs carrying a turn,
+* `EventSource` can only GET, and reattachment wants the cursor in the request
+* body next to the thread id rather than in a header the browser owns.
+*/
+/**
+* Feed it chunks, get frames. Holds whatever is left over between calls, which
+* is the whole point: `push()` is called once per `reader.read()` and those
+* boundaries have nothing to do with event boundaries.
+*/
+var SSEFrameDecoder = class {
+	buffer = "";
+	textDecoder = new TextDecoder();
+	/**
+	* A `\r` at the very end of a chunk is ambiguous — the next chunk may open
+	* with the `\n` that completes a CRLF, or with the next line. Holding it back
+	* for one chunk is what keeps a boundary there from being read as a blank
+	* line and cutting an event in half.
+	*/
+	pendingCR = false;
+	lastSeq = -1;
+	/** The cursor to resume from: the highest `id:` seen. */
+	get cursor() {
+		return this.lastSeq;
+	}
+	push(chunk) {
+		this.append(typeof chunk === "string" ? chunk : this.textDecoder.decode(chunk, { stream: true }));
+		return this.drain();
+	}
+	/**
+	* End of stream. Anything still buffered is an event with no terminating
+	* blank line, which the SSE spec discards and so does this — a truncated tail
+	* is usually truncated JSON, and half a `text-delta` appended to a message is
+	* worse than a missing one.
+	*/
+	flush() {
+		this.append(this.textDecoder.decode());
+		const frames = this.drain();
+		this.buffer = "";
+		this.pendingCR = false;
+		return frames;
+	}
+	/** Normalises every line ending to `\n` so the rest of the parser only has to
+	*  know about one. */
+	append(text) {
+		if (text === "") return;
+		let rest = text;
+		if (this.pendingCR) {
+			this.buffer += "\n";
+			this.pendingCR = false;
+			if (rest.startsWith("\n")) rest = rest.slice(1);
+		}
+		if (rest.endsWith("\r")) {
+			rest = rest.slice(0, -1);
+			this.pendingCR = true;
+		}
+		this.buffer += rest.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	}
+	drain() {
+		const frames = [];
+		let boundary = this.buffer.indexOf("\n\n");
+		while (boundary !== -1) {
+			const block = this.buffer.slice(0, boundary);
+			this.buffer = this.buffer.slice(boundary + 2);
+			const frame = this.parse(block);
+			if (frame) frames.push(frame);
+			boundary = this.buffer.indexOf("\n\n");
+		}
+		return frames;
+	}
+	parse(block) {
+		let id;
+		const data = [];
+		for (const line of block.split("\n")) {
+			if (line === "" || line.startsWith(":")) continue;
+			const colon = line.indexOf(":");
+			const field = colon === -1 ? line : line.slice(0, colon);
+			let value = colon === -1 ? "" : line.slice(colon + 1);
+			if (value.startsWith(" ")) value = value.slice(1);
+			if (field === "data") data.push(value);
+			else if (field === "id") id = value;
+		}
+		if (data.length === 0) return null;
+		let event;
+		try {
+			event = JSON.parse(data.join("\n"));
+		} catch {
+			return null;
+		}
+		const parsed = id === void 0 || id === "" ? NaN : Number(id);
+		const seq = Number.isFinite(parsed) ? parsed : this.lastSeq + 1;
+		this.lastSeq = seq;
+		return {
+			seq,
+			event
+		};
+	}
+};
+/**
+* The same decoder over a `Response.body`.
+*
+* Cancels the reader when the caller stops consuming — a `break` out of the
+* `for await` is how the hook drops a stream on unmount, and without the cancel
+* the connection stays open behind it.
+*/
+async function* decodeSSE(stream) {
+	if (!stream) return;
+	const reader = stream.getReader();
+	const decoder = new SSEFrameDecoder();
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) {
+				yield* decoder.flush();
+				return;
+			}
+			if (value) yield* decoder.push(value);
+		}
+	} finally {
+		try {
+			await reader.cancel();
+		} catch {}
+	}
+}
+//#endregion
+//#region ai/useChat.tsx
+var localIdCounter = 0;
+/** Ids the client mints: messages it authored, and the correlation id it names a
+*  run by before the server has. Server-assigned ids are what keep a reattached
+*  stream from duplicating a message, so the two must not collide — hence the
+*  prefix, which also tells a server log which end invented an id. */
+function localId() {
+	return `local_${typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `${Date.now()}-${localIdCounter++}`}`;
+}
+/** The same substitution `useMutation` does, so a parameterised agent path
+*  behaves like every other route in the package. */
+function applyRouteParams(url, params) {
+	let out = url;
+	for (const [key, value] of Object.entries(params)) out = out.replace(`:${key}?`, value).replace(`:${key}`, value);
+	return out;
+}
+function isAbort(error) {
+	return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+}
+async function httpError(response) {
+	let message = response.statusText || `Request failed with status ${response.status}`;
+	let code = response.status === 429 ? "rate_limited" : "unknown";
+	try {
+		const data = await response.json();
+		message = data?.error?.message ?? data?.message ?? message;
+		if (data?.error?.code === "thread_not_found") code = "thread_not_found";
+	} catch {}
+	return {
+		code,
+		message,
+		retryable: response.status === 429 || response.status >= 500
+	};
+}
+function turnFrom(message) {
+	let text = "";
+	const files = [];
+	for (const part of message.content) {
+		if (part.type === "text") text += part.text;
+		if (part.type === "file") files.push({
+			fileId: part.fileId,
+			name: part.name,
+			mimeType: part.mimeType
+		});
+	}
+	return {
+		...text ? { text } : {},
+		...files.length > 0 ? { files } : {}
+	};
+}
+/**
+* The transcript as the server needs it, without the progress logs.
+*
+* In stateless mode `send` posts the whole history on *every* turn, so anything
+* that accumulates on a message is paid for again on each one. `progress` is
+* the only part of the transcript that grows without a bound the model imposes:
+* a generator tool yielding per chunk writes an entry per chunk, and a tool that
+* yielded five thousand times would put five thousand objects in the body of
+* turn 2, turn 3, and every turn after, forever.
+*
+* Nothing server-side reads it. It is not translated into a provider message,
+* `openCalls` matches on `toolCallId`, and the resume path replays a sub-agent
+* from `nested` — which is why `nested` is kept here, recursed into rather than
+* dropped, while `progress` is not. The client's own copy is untouched: this
+* shapes the request body only, so a UI still renders every yield it received.
+*/
+function forWire(messages) {
+	return messages.map((message) => {
+		if (!message.content.some((part) => part.type === "tool-call" && (part.progress || part.nested))) return message;
+		return {
+			...message,
+			content: message.content.map((part) => {
+				if (part.type !== "tool-call") return part;
+				const { progress: _progress, ...rest } = part;
+				return rest.nested ? {
+					...rest,
+					nested: rest.nested.map((run) => ({
+						...run,
+						messages: forWire(run.messages)
+					}))
+				} : rest;
+			})
+		};
+	});
+}
+/**
+* The path is the agent's route, exactly as mounted:
+*
+*   const { messages, sendMessage } = useChat("/chat")
+*
+* and a tool part inside `messages` narrows on `name`, giving `input` and
+* `output` their real types — which is the whole reason the tool tuple is
+* carried through `Agent`, `AgentRoute` and `RPC` instead of being erased at the
+* first boundary.
+*/
+function useChat(path, params = {}) {
+	const { threadId: initialThreadId, initialMessages, cursor: initialCursor, attach: attachOnMount = true, body: extraBody, headers, onFinish, onError, onAwaitingInput, onAttachMiss } = params;
+	const routeParams = useParams();
+	const base = useMemo(() => `/api${applyRouteParams(String(path).replace(/^[A-Z]+:/, ""), routeParams)}`, [path, routeParams]);
+	/**
+	* The state lives in a ref and is mirrored into `useState` for rendering.
+	*
+	* A stream applies frames faster than React commits, and the reducer needs
+	* the result of the previous frame, not the value captured when the loop
+	* started. The ref is the source of truth; `setState` is the notification.
+	*
+	* `any` inside, exact at the boundary: the wire carries erased tool shapes and
+	* the route's real ones are re-asserted once, in the returned object.
+	*/
+	const stateRef = useRef(null);
+	if (stateRef.current === null) stateRef.current = initialChatState({
+		messages: initialMessages,
+		threadId: initialThreadId,
+		seq: initialCursor?.seq,
+		cursorRunId: initialCursor?.runId
+	});
+	const [state, setState] = useState(stateRef.current);
+	const [phase, setPhase] = useState("idle");
+	const mountedRef = useRef(true);
+	const abortRef = useRef(null);
+	const handlers = useRef({
+		onFinish,
+		onError,
+		onAwaitingInput,
+		onAttachMiss
+	});
+	handlers.current = {
+		onFinish,
+		onError,
+		onAwaitingInput,
+		onAttachMiss
+	};
+	const requestRef = useRef({
+		base,
+		headers,
+		extraBody
+	});
+	requestRef.current = {
+		base,
+		headers,
+		extraBody
+	};
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+			abortRef.current?.controller.abort();
+			abortRef.current = null;
+		};
+	}, []);
+	const commit = useCallback((next) => {
+		stateRef.current = next;
+		if (mountedRef.current) setState(next);
+	}, []);
+	const setPhaseSafe = useCallback((next) => {
+		if (mountedRef.current) setPhase(next);
+	}, []);
+	/**
+	* Report a failure without touching the conversation.
+	*
+	* `pending` deliberately survives. Most of what fails here has nothing to do
+	* with the question the conversation is holding — an upload that 500s, an
+	* answer aimed at a call this client never had — and the pending calls carry
+	* the only signatures that can answer them, held nowhere else. Dropping them
+	* because an unrelated request failed would leave the user unable to approve
+	* anything at all, with a fresh turn (which the server reads as refusing
+	* everything) the only way out.
+	*
+	* The failures that really do end the turn clear `pending` where they happen:
+	* `send` clears it as the turn goes out, and the stream's own `error` event
+	* clears it in the reducer.
+	*/
+	const fail = useCallback((error) => {
+		commit({
+			...stateRef.current,
+			error
+		});
+		handlers.current.onError?.(error);
+	}, [commit]);
+	const post = useCallback((url, payload, signal) => {
+		const { headers: extraHeaders } = requestRef.current;
+		return fetch(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...extraHeaders
+			},
+			body: JSON.stringify(payload),
+			signal
+		});
+	}, []);
+	/**
+	* The server call that ends a run. Shared by `stop()` and by a `send` that
+	* supersedes one; what each does with a failure is its own, because a stop
+	* that did not land is a run still working through its tool loop and still
+	* billing, behind a transcript that says it was cut — and whose problem that
+	* is depends on who asked.
+	*/
+	const postStop = useCallback(async (body, report) => {
+		const { base: url } = requestRef.current;
+		try {
+			const response = await post(`${url}/stop`, body);
+			if (!response.ok) report(await httpError(response));
+		} catch (error) {
+			if (isAbort(error)) return;
+			report({
+				code: "unknown",
+				message: error instanceof Error ? error.message : String(error),
+				retryable: true
+			});
+		}
+	}, [post]);
+	const consume = useCallback(async (response, signal) => {
+		for await (const frame of decodeSSE(response.body)) {
+			if (!mountedRef.current || signal.aborted) return;
+			setPhaseSafe("streaming");
+			const previous = stateRef.current;
+			const next = applyFrame(previous, frame);
+			if (next === previous) continue;
+			commit(next);
+			const event = frame.event;
+			if (event.type === "message-end") {
+				const before = previous.messages.find((m) => m.id === event.messageId);
+				const message = next.messages.find((m) => m.id === event.messageId);
+				if (message && before?.finishReason === void 0) handlers.current.onFinish?.(message);
+			} else if (event.type === "awaiting-input") handlers.current.onAwaitingInput?.(event.pending);
+			else if (event.type === "error") handlers.current.onError?.(event.error);
+		}
+	}, [commit, setPhaseSafe]);
+	const send = useCallback(async (turn) => {
+		const { base: url, extraBody: body } = requestRef.current;
+		const superseded = abortRef.current;
+		superseded?.controller.abort();
+		const clientRunId = localId();
+		const controller = new AbortController();
+		abortRef.current = {
+			controller,
+			clientRunId
+		};
+		if (superseded) {
+			const { runId, threadId } = stateRef.current;
+			const body = {
+				...runId ? { runId } : {},
+				...superseded.clientRunId ? { clientRunId: superseded.clientRunId } : {}
+			};
+			if (Object.keys(body).length > 0) postStop(body, threadId ? () => {} : (error) => handlers.current.onError?.(error));
+		}
+		const previous = superseded ? markAborted(stateRef.current) : stateRef.current;
+		const history = previous.messages;
+		const authored = turn.text || turn.files?.length ? [{
+			id: localId(),
+			role: "user",
+			content: [...turn.text ? [{
+				type: "text",
+				text: turn.text
+			}] : [], ...(turn.files ?? []).map((file) => ({
+				type: "file",
+				...file
+			}))],
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		}] : [];
+		commit({
+			...previous,
+			messages: [...history, ...authored],
+			error: null,
+			pending: []
+		});
+		setPhaseSafe("submitted");
+		try {
+			const payload = {
+				turn,
+				clientRunId,
+				...stateRef.current.threadId ? { threadId: stateRef.current.threadId } : { messages: forWire(history) },
+				...body
+			};
+			const response = await post(url, payload, controller.signal);
+			if (!response.ok) {
+				fail(await httpError(response));
+				return;
+			}
+			await consume(response, controller.signal);
+		} catch (error) {
+			if (!isAbort(error)) fail({
+				code: "unknown",
+				message: error instanceof Error ? error.message : String(error),
+				retryable: true
+			});
+		} finally {
+			if (abortRef.current?.controller === controller) {
+				abortRef.current = null;
+				setPhaseSafe("idle");
+			}
+		}
+	}, [
+		commit,
+		consume,
+		fail,
+		post,
+		postStop,
+		setPhaseSafe
+	]);
+	const sendMessage = useCallback((turn) => send(typeof turn === "string" ? { text: turn } : turn), [send]);
+	/**
+	* Answers queued within one tick become one turn.
+	*
+	* This is not an optimisation. A turn that leaves a pending call unanswered
+	* denies it, so sending three approvals as three turns would have the first
+	* one refuse the other two — and the natural UI code, a loop over `pending`
+	* calling `approve` for each, is exactly that shape. Coalescing on the
+	* microtask is what makes the declared per-call signature safe to use the way
+	* it reads.
+	*/
+	const queued = useRef(null);
+	const queueResult = useCallback((result) => {
+		if (queued.current) {
+			queued.current.results.push(result);
+			return queued.current.flushed;
+		}
+		const results = [result];
+		const flushed = Promise.resolve().then(() => {
+			queued.current = null;
+			return send({ toolResults: results });
+		});
+		queued.current = {
+			results,
+			flushed
+		};
+		return flushed;
+	}, [send]);
+	/**
+	* The half of a `ClientToolResult` the app never writes: the id, the
+	* signature, and the path.
+	*
+	* All three are carried by the hook and handed back untouched, which is what
+	* makes a sub-agent's question answerable with the same two lines as a
+	* top-level one. `path` is absent for a call the parent's own tools made, so
+	* an app cannot tell from its own code where the question came from — the only
+	* difference is that `pending[i].path` is there to render if it wants to say
+	* which agent is asking.
+	*/
+	const resultFor = useCallback((toolCallId, build) => {
+		const matches = stateRef.current.pending.filter((candidate) => candidate.toolCallId === toolCallId);
+		const call = matches[0];
+		if (!call) {
+			fail({
+				code: "invalid_tool_result",
+				message: `No pending tool call ${toolCallId}`,
+				toolCallId,
+				retryable: false
+			});
+			return null;
+		}
+		if (matches.length > 1) {
+			fail({
+				code: "invalid_tool_result",
+				message: `Ambiguous tool call ${toolCallId}: ${matches.length} pending calls share it`,
+				toolCallId,
+				retryable: false
+			});
+			return null;
+		}
+		return build({
+			toolCallId,
+			signature: call.signature,
+			...call.path ? { path: call.path } : {}
+		});
+	}, [fail]);
+	const approve = useCallback(async (toolCallId, approved, reason) => {
+		const result = resultFor(toolCallId, (base) => ({
+			...base,
+			approve: approved,
+			...reason ? { reason } : {}
+		}));
+		if (result) await queueResult(result);
+	}, [queueResult, resultFor]);
+	const answer = useCallback(async (toolCallId, output) => {
+		const result = resultFor(toolCallId, (base) => ({
+			...base,
+			output
+		}));
+		if (result) await queueResult(result);
+	}, [queueResult, resultFor]);
+	const stop = useCallback(async () => {
+		const { runId, threadId } = stateRef.current;
+		const inFlight = abortRef.current;
+		inFlight?.controller.abort();
+		abortRef.current = null;
+		commit(markAborted(stateRef.current));
+		setPhaseSafe("idle");
+		if (!inFlight && !runId) return;
+		const body = {
+			...runId ? { runId } : {},
+			...threadId ? { threadId } : {},
+			...inFlight?.clientRunId ? { clientRunId: inFlight.clientRunId } : {}
+		};
+		await postStop(body, fail);
+	}, [
+		commit,
+		fail,
+		postStop,
+		setPhaseSafe
+	]);
+	const regenerate = useCallback(async () => {
+		const messages = stateRef.current.messages;
+		let assistantIndex = -1;
+		for (let i = messages.length - 1; i >= 0; i--) if (messages[i].role === "assistant") {
+			assistantIndex = i;
+			break;
+		}
+		if (assistantIndex === -1) return;
+		let userIndex = -1;
+		for (let i = assistantIndex - 1; i >= 0; i--) if (messages[i].role === "user") {
+			userIndex = i;
+			break;
+		}
+		if (userIndex === -1) return;
+		const turn = turnFrom(messages[userIndex]);
+		commit({
+			...stateRef.current,
+			messages: messages.slice(0, userIndex),
+			pending: [],
+			error: null
+		});
+		await send(turn);
+	}, [commit, send]);
+	const setMessages = useCallback((messages) => {
+		commit({
+			...stateRef.current,
+			messages
+		});
+	}, [commit]);
+	const uploadFile = useCallback(async (file) => {
+		const { base: url, headers: extraHeaders } = requestRef.current;
+		const form = new FormData();
+		form.append("file", file);
+		const response = await fetch(`${url}/files`, {
+			method: "POST",
+			headers: { ...extraHeaders },
+			body: form
+		});
+		if (!response.ok) {
+			const error = await httpError(response);
+			fail(error);
+			throw new Error(error.message);
+		}
+		const data = await response.json();
+		return {
+			fileId: data.fileId,
+			name: data.name ?? file.name,
+			mimeType: data.mimeType ?? file.type
+		};
+	}, [fail]);
+	useEffect(() => {
+		if (attachOnMount === false || !initialThreadId) return;
+		const controller = new AbortController();
+		abortRef.current = { controller };
+		(async () => {
+			try {
+				const body = {
+					threadId: initialThreadId,
+					cursor: stateRef.current.seq,
+					...stateRef.current.cursorRunId ? { runId: stateRef.current.cursorRunId } : {}
+				};
+				const response = await post(`${requestRef.current.base}/attach`, body, controller.signal);
+				if (!response.ok || response.status === 204 || !response.body) {
+					handlers.current.onAttachMiss?.({ threadId: initialThreadId });
+					return;
+				}
+				await consume(response, controller.signal);
+			} catch {} finally {
+				if (abortRef.current?.controller === controller) {
+					abortRef.current = null;
+					setPhaseSafe("idle");
+				}
+			}
+		})();
+		return () => controller.abort();
+	}, []);
+	const status = state.pending.length > 0 ? "awaiting-input" : phase !== "idle" ? phase : state.error ? "error" : "idle";
+	return {
+		messages: state.messages,
+		status,
+		error: state.error,
+		threadId: state.threadId,
+		runId: state.runId,
+		cursor: {
+			runId: state.cursorRunId,
+			seq: state.seq
+		},
+		sendMessage,
+		stop,
+		regenerate,
+		setMessages,
+		pending: state.pending,
+		loadedTools: state.loadedTools,
+		approve,
+		answer,
+		attach: uploadFile
+	};
+}
+//#endregion
+export { useChat };
+
+//# sourceMappingURL=index.js.map