@code-yeongyu/senpi-codemode 2026.7.25-2

package/src/bridge/http-server.ts

@@ -0,0 +1,236 @@
+import { once } from "node:events";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo, Socket } from "node:net";
+import { type BridgeError, generateBridgeToken, verifyBridgeToken } from "./protocol.ts";
+
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const LOOPBACK_HOST = "127.0.0.1";
+
+export interface BridgeHttpCallRequest {
+	callId: string;
+	toolName: string;
+	args: unknown;
+	signal: AbortSignal;
+}
+
+export interface BridgeHttpCompletionRequest {
+	prompt: string;
+	opts?: unknown;
+	signal: AbortSignal;
+}
+
+export type BridgeHttpEmitEvent =
+	| { kind: "text"; stream: "stdout" | "stderr"; data: string }
+	| { kind: "display"; mimeType: string; dataBase64: string }
+	| { kind: "log"; message: string }
+	| { kind: "phase"; title: string };
+
+export interface BridgeServerOptions {
+	token?: string;
+	bodyLimitBytes?: number;
+	onCall: (request: BridgeHttpCallRequest) => Promise<unknown>;
+	onEmit: (event: BridgeHttpEmitEvent, signal: AbortSignal) => Promise<void>;
+	onCompletion: (request: BridgeHttpCompletionRequest) => Promise<unknown>;
+}
+
+export interface BridgeServerHandle {
+	port: number;
+	token: string;
+	close: () => Promise<void>;
+}
+
+type JsonReply = { ok: true; value: unknown } | { ok: false; error: BridgeError };
+type Route = "/call" | "/emit" | "/completion";
+
+export async function startBridgeServer(options: BridgeServerOptions): Promise<BridgeServerHandle> {
+	const token = options.token ?? generateBridgeToken();
+	const sockets = new Set<Socket>();
+	let closing: Promise<void> | undefined;
+	const server = createServer((request, response) => {
+		void handleRequest(request, response, token, options);
+	});
+	server.on("connection", (socket) => {
+		sockets.add(socket);
+		socket.on("close", () => sockets.delete(socket));
+	});
+	server.listen(0, LOOPBACK_HOST);
+	await once(server, "listening");
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("Bridge server did not bind to a TCP port");
+
+	return {
+		port: (address as AddressInfo).port,
+		token,
+		close: async () => {
+			closing ??= closeServer(server, sockets);
+			await closing;
+		},
+	};
+}
+
+async function handleRequest(
+	request: IncomingMessage,
+	response: ServerResponse,
+	token: string,
+	options: BridgeServerOptions,
+): Promise<void> {
+	const abortController = new AbortController();
+	request.on("close", () => abortController.abort());
+	if (request.method !== "POST") {
+		sendJson(response, 404, { ok: false, error: transportError("not_found", "Bridge route was not found") });
+		return;
+	}
+	const route = routeFromUrl(request.url ?? "");
+	if (!route) {
+		sendJson(response, 404, { ok: false, error: transportError("not_found", "Bridge route was not found") });
+		return;
+	}
+	const auth = parseBearerToken(request.headers.authorization);
+	if (!auth || !verifyBridgeToken(token, auth).ok) {
+		sendJson(response, 401, { ok: false, error: transportError("unauthorized", "Bridge authorization failed") });
+		return;
+	}
+
+	const parsed = await readJsonBody(request, options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES);
+	if (!parsed.ok) {
+		sendJson(response, parsed.status, { ok: false, error: transportError(parsed.code, parsed.message) });
+		return;
+	}
+
+	if (route === "/emit") {
+		const event = parseEmitEvent(parsed.value);
+		if (!event.ok) {
+			sendJson(response, 400, { ok: false, error: transportError("invalid_request", event.message) });
+			return;
+		}
+		try {
+			await options.onEmit(event.event, abortController.signal);
+			response.writeHead(204).end();
+		} catch (error) {
+			sendJson(response, 200, { ok: false, error: bridgeError(error) });
+		}
+		return;
+	}
+
+	const reply =
+		route === "/call"
+			? await dispatchCall(parsed.value, options, abortController.signal)
+			: await dispatchCompletion(parsed.value, options, abortController.signal);
+	sendJson(response, 200, reply);
+}
+
+async function dispatchCall(body: unknown, options: BridgeServerOptions, signal: AbortSignal): Promise<JsonReply> {
+	if (!isRecord(body) || typeof body.callId !== "string" || typeof body.toolName !== "string" || !("args" in body)) {
+		return { ok: false, error: transportError("invalid_request", "Bridge call request was invalid") };
+	}
+	try {
+		return {
+			ok: true,
+			value: await options.onCall({ callId: body.callId, toolName: body.toolName, args: body.args, signal }),
+		};
+	} catch (error) {
+		return { ok: false, error: bridgeError(error) };
+	}
+}
+
+async function dispatchCompletion(
+	body: unknown,
+	options: BridgeServerOptions,
+	signal: AbortSignal,
+): Promise<JsonReply> {
+	if (!isRecord(body) || typeof body.prompt !== "string") {
+		return { ok: false, error: transportError("invalid_request", "Bridge completion request was invalid") };
+	}
+	try {
+		return { ok: true, value: await options.onCompletion({ prompt: body.prompt, opts: body.opts, signal }) };
+	} catch (error) {
+		return { ok: false, error: bridgeError(error) };
+	}
+}
+
+async function readJsonBody(
+	request: IncomingMessage,
+	limit: number,
+): Promise<{ ok: true; value: unknown } | { ok: false; status: number; code: string; message: string }> {
+	let raw = "";
+	for await (const chunk of request) {
+		raw += String(chunk);
+		if (Buffer.byteLength(raw, "utf8") > limit) {
+			return {
+				ok: false,
+				status: 413,
+				code: "body_too_large",
+				message: `Bridge request body exceeds ${limit} bytes`,
+			};
+		}
+	}
+	try {
+		return { ok: true, value: JSON.parse(raw) as unknown };
+	} catch {
+		return { ok: false, status: 400, code: "invalid_json", message: "Bridge request body was not valid JSON" };
+	}
+}
+
+function parseEmitEvent(value: unknown): { ok: true; event: BridgeHttpEmitEvent } | { ok: false; message: string } {
+	if (!isRecord(value) || typeof value.kind !== "string")
+		return { ok: false, message: "Bridge emit request was invalid" };
+	if (
+		value.kind === "text" &&
+		(value.stream === "stdout" || value.stream === "stderr") &&
+		typeof value.data === "string"
+	) {
+		return { ok: true, event: { kind: value.kind, stream: value.stream, data: value.data } };
+	}
+	if (value.kind === "display" && typeof value.mimeType === "string" && typeof value.dataBase64 === "string") {
+		return { ok: true, event: { kind: value.kind, mimeType: value.mimeType, dataBase64: value.dataBase64 } };
+	}
+	if (value.kind === "log" && typeof value.message === "string") {
+		return { ok: true, event: { kind: value.kind, message: value.message } };
+	}
+	if (value.kind === "phase" && typeof value.title === "string") {
+		return { ok: true, event: { kind: value.kind, title: value.title } };
+	}
+	return { ok: false, message: "Bridge emit request was invalid" };
+}
+
+function routeFromUrl(rawUrl: string): Route | undefined {
+	const path = new URL(rawUrl, "http://127.0.0.1").pathname;
+	if (path === "/call" || path === "/emit" || path === "/completion") return path;
+	return undefined;
+}
+
+function parseBearerToken(header: string | undefined): string | undefined {
+	const prefix = "Bearer ";
+	if (!header?.startsWith(prefix)) return undefined;
+	return header.slice(prefix.length);
+}
+
+function sendJson(response: ServerResponse, status: number, body: JsonReply): void {
+	if (response.destroyed) return;
+	response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	response.end(JSON.stringify(body));
+}
+
+function bridgeError(error: unknown): BridgeError {
+	if (error instanceof Error) return { name: error.name, message: error.message, stack: error.stack };
+	return { message: String(error) };
+}
+
+function transportError(code: string, message: string): BridgeError {
+	return { code, message };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+async function closeServer(server: ReturnType<typeof createServer>, sockets: Set<Socket>): Promise<void> {
+	server.closeAllConnections?.();
+	for (const socket of sockets) socket.destroy();
+	await new Promise<void>((resolve, reject) => {
+		server.close((error) => {
+			if (error && "code" in error && error.code !== "ERR_SERVER_NOT_RUNNING") reject(error);
+			else resolve();
+		});
+	});
+}

package/src/bridge/protocol.ts

@@ -0,0 +1,198 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+export const BRIDGE_FRAME_MAX_BYTES = 10 * 1024 * 1024;
+
+const bridgeErrorSchema = Type.Object({
+	name: Type.Optional(Type.String()),
+	message: Type.String(),
+	stack: Type.Optional(Type.String()),
+	code: Type.Optional(Type.String()),
+});
+
+const statusEventSchema = Type.Object({ op: Type.String() }, { additionalProperties: true });
+
+const connectionConfigSchema = Type.Object({
+	port: Type.Integer({ minimum: 1, maximum: 65_535 }),
+	token: Type.String({ minLength: 1 }),
+	localRoots: Type.Optional(Type.Record(Type.String(), Type.String())),
+	artifactsDir: Type.Optional(Type.String()),
+	parallelPoolWidth: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+
+const hostToKernelMessageSchema = Type.Union([
+	Type.Object({
+		type: Type.Literal("init"),
+		sessionId: Type.String({ minLength: 1 }),
+		connection: connectionConfigSchema,
+	}),
+	Type.Object({
+		type: Type.Literal("run"),
+		cellId: Type.String({ minLength: 1 }),
+		code: Type.String(),
+		timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+	}),
+	Type.Object({
+		type: Type.Literal("tool-reply"),
+		callId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(true),
+		value: Type.Unknown(),
+	}),
+	Type.Object({
+		type: Type.Literal("tool-reply"),
+		callId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(false),
+		error: bridgeErrorSchema,
+	}),
+	Type.Object({
+		type: Type.Literal("interrupt"),
+		reason: Type.Optional(Type.String()),
+	}),
+	Type.Object({
+		type: Type.Literal("close"),
+	}),
+]);
+
+const kernelToHostMessageSchema = Type.Union([
+	Type.Object({ type: Type.Literal("ready") }),
+	Type.Object({ type: Type.Literal("init-failed"), error: bridgeErrorSchema }),
+	Type.Object({
+		type: Type.Literal("text"),
+		stream: Type.Union([Type.Literal("stdout"), Type.Literal("stderr")]),
+		data: Type.String(),
+	}),
+	Type.Object({
+		type: Type.Literal("display"),
+		mimeType: Type.String({ minLength: 1 }),
+		dataBase64: Type.String(),
+	}),
+	Type.Object({
+		type: Type.Literal("tool-call"),
+		callId: Type.String({ minLength: 1 }),
+		toolName: Type.String({ minLength: 1 }),
+		args: Type.Unknown(),
+	}),
+	Type.Object({ type: Type.Literal("log"), message: Type.String() }),
+	Type.Object({ type: Type.Literal("phase"), title: Type.String() }),
+	Type.Object({ type: Type.Literal("status"), event: statusEventSchema }),
+	Type.Object({
+		type: Type.Literal("result"),
+		cellId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(true),
+		valueRepr: Type.Optional(Type.String()),
+		durationMs: Type.Integer({ minimum: 0 }),
+	}),
+	Type.Object({
+		type: Type.Literal("result"),
+		cellId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(false),
+		error: bridgeErrorSchema,
+		durationMs: Type.Integer({ minimum: 0 }),
+	}),
+	Type.Object({ type: Type.Literal("closed") }),
+]);
+
+const bridgeMessageSchema = Type.Union([hostToKernelMessageSchema, kernelToHostMessageSchema]);
+
+export type EvalStatusEvent = { op: string } & Record<string, unknown>;
+export type BridgeError = Static<typeof bridgeErrorSchema>;
+export type BridgeConnectionConfig = Static<typeof connectionConfigSchema>;
+export type HostToKernelMessage = Static<typeof hostToKernelMessageSchema>;
+type KernelToHostMessageSchema = Static<typeof kernelToHostMessageSchema>;
+type BridgeMessageSchema = Static<typeof bridgeMessageSchema>;
+export type KernelToHostMessage =
+	| Exclude<KernelToHostMessageSchema, { type: "status" }>
+	| { type: "status"; event: EvalStatusEvent };
+export type BridgeMessage =
+	| Exclude<BridgeMessageSchema, { type: "status" }>
+	| { type: "status"; event: EvalStatusEvent };
+
+export type BridgeDecodeErrorCode =
+	| "empty_frame"
+	| "frame_too_large"
+	| "multiple_frames"
+	| "malformed_json"
+	| "invalid_message";
+
+export interface BridgeDecodeError {
+	code: BridgeDecodeErrorCode;
+	message: string;
+}
+
+export type BridgeDecodeResult<T> = { ok: true; value: T } | { ok: false; error: BridgeDecodeError };
+export type BridgeMessageDecodeResult = { ok: true; message: BridgeMessage } | { ok: false; error: BridgeDecodeError };
+
+export type BridgeActivityReply =
+	| { state: "active"; sessionId: string }
+	| { state: "inactive"; sessionId?: string }
+	| { state: "blocked"; reason: string }
+	| { state: "error"; error: BridgeError };
+
+export type BridgeTokenVerifyResult = { ok: true } | { ok: false; error: { code: "token_mismatch"; message: string } };
+
+export interface BridgeFrameOptions {
+	maxBytes?: number;
+}
+
+export function generateCorrelationId(): string {
+	return randomUUID();
+}
+
+export function generateBridgeToken(byteLength = 32): string {
+	return randomBytes(byteLength).toString("base64url");
+}
+
+export function verifyBridgeToken(expected: string, received: string): BridgeTokenVerifyResult {
+	const expectedHash = tokenHash(expected);
+	const receivedHash = tokenHash(received);
+	if (timingSafeEqual(expectedHash, receivedHash)) return { ok: true };
+	return { ok: false, error: { code: "token_mismatch", message: "Bridge bearer token did not match" } };
+}
+
+export function encodeBridgeFrame(message: BridgeMessage): string {
+	return `${JSON.stringify(message)}\n`;
+}
+
+export function parseBridgeJsonLine(line: string, options: BridgeFrameOptions = {}): BridgeDecodeResult<unknown> {
+	const maxBytes = options.maxBytes ?? BRIDGE_FRAME_MAX_BYTES;
+	const byteLength = Buffer.byteLength(line, "utf8");
+	if (byteLength > maxBytes) {
+		return { ok: false, error: { code: "frame_too_large", message: `Bridge frame exceeds ${maxBytes} bytes` } };
+	}
+	const trimmedLine = line.endsWith("\n") ? line.slice(0, -1) : line;
+	if (trimmedLine.length === 0) {
+		return { ok: false, error: { code: "empty_frame", message: "Bridge frame was empty" } };
+	}
+	if (trimmedLine.includes("\n")) {
+		return {
+			ok: false,
+			error: { code: "multiple_frames", message: "Bridge frame contained more than one LF record" },
+		};
+	}
+	try {
+		return { ok: true, value: JSON.parse(trimmedLine) };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Invalid JSON bridge frame";
+		return { ok: false, error: { code: "malformed_json", message } };
+	}
+}
+
+export function decodeBridgeFrame(line: string, options: BridgeFrameOptions = {}): BridgeMessageDecodeResult {
+	const parsed = parseBridgeJsonLine(line, options);
+	if (!parsed.ok) return parsed;
+	if (Value.Check(bridgeMessageSchema, parsed.value)) {
+		return { ok: true, message: parsed.value };
+	}
+	const firstError = Value.Errors(bridgeMessageSchema, parsed.value)[0];
+	const message = firstError ? `Invalid bridge message: ${firstError.message}` : "Invalid bridge message";
+	return { ok: false, error: { code: "invalid_message", message } };
+}
+
+export function isKernelToHostMessage(message: BridgeMessage): message is KernelToHostMessage {
+	return Value.Check(kernelToHostMessageSchema, message);
+}
+
+function tokenHash(token: string): Buffer {
+	return createHash("sha256").update(token, "utf8").digest();
+}

package/src/bridge/reserved.ts

@@ -0,0 +1,9 @@
+/** Cross-kernel bridge names shared by preludes and host adapters. */
+/** Canonical oh-my-pi agent bridge tool name. */
+export const RESERVED_AGENT_TOOL = "__agent__" as const;
+/** ADAPTATION: senpi delegates output through a reserved kernel-side tool name. */
+export const RESERVED_OUTPUT_TOOL = "__output__" as const;
+/** Canonical oh-my-pi eval-timeout pause operation. */
+export const TIMEOUT_PAUSE_OP = "timeout-pause" as const;
+/** Canonical oh-my-pi eval-timeout resume operation. */
+export const TIMEOUT_RESUME_OP = "timeout-resume" as const;

package/src/bridges/agent-bridge.ts

@@ -0,0 +1,197 @@
+import type { AgentToolResult } from "@code-yeongyu/senpi";
+import { type Static, Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+import type { EvalStatusEvent, ExecuteTool } from "../tool/types.ts";
+
+const agentArgsSchema = Type.Object(
+	{
+		prompt: Type.String({ minLength: 1 }),
+		agent: Type.Optional(Type.String({ minLength: 1 })),
+		model: Type.Optional(Type.String({ minLength: 1 })),
+		label: Type.Optional(Type.String()),
+		schema: Type.Optional(Type.Unknown()),
+		handle: Type.Optional(Type.Boolean()),
+		isolated: Type.Optional(Type.Boolean()),
+		apply: Type.Optional(Type.Boolean()),
+		merge: Type.Optional(Type.Boolean()),
+	},
+	{ additionalProperties: false },
+);
+
+const unsupportedIsolationWarning = "isolated/apply/merge unsupported (no isolation in task engine)";
+const taskIdPattern = /\bst_[A-Za-z0-9_-]+\b/;
+const droppedOptionNames = ["isolated", "apply", "merge"] as const;
+
+type AgentArgs = Static<typeof agentArgsSchema>;
+type TaskParams = {
+	readonly prompt: string;
+	readonly subagent_type?: string;
+	readonly model?: string;
+	readonly name?: string;
+	readonly run_in_background: boolean;
+};
+type ProgressContext = { readonly fallbackId: string; readonly warning?: string };
+
+export type AgentExecuteTool = ExecuteTool & {
+	readonly isToolAvailable?: (name: string) => boolean;
+};
+
+export interface RunEvalAgentOptions {
+	readonly callId: string;
+	readonly taskToolName: string;
+	readonly executeTool: AgentExecuteTool;
+	readonly signal?: AbortSignal;
+	readonly emitStatus?: (event: EvalStatusEvent) => void;
+}
+
+export type EvalAgentResult =
+	| { readonly text: string }
+	| { readonly text: string; readonly data: unknown }
+	| { readonly text: string; readonly parseError: string }
+	| { readonly text: string; readonly id: string; readonly handle: string };
+
+class AgentArgumentsError extends Error {
+	readonly name = "AgentArgumentsError";
+
+	constructor(summary: string) {
+		super(`agent() received invalid arguments: ${summary}`);
+	}
+}
+
+class AgentUnavailableError extends Error {
+	readonly name = "AgentUnavailableError";
+
+	constructor(toolName: string) {
+		super(`agent() unavailable: no "${toolName}" tool is registered in this session`);
+	}
+}
+
+class AgentHandleError extends Error {
+	readonly name = "AgentHandleError";
+
+	constructor() {
+		super("agent() background task result did not include a task id");
+	}
+}
+
+export async function runEvalAgent(args: unknown, options: RunEvalAgentOptions): Promise<EvalAgentResult> {
+	const parsed = parseAgentArgs(args);
+	const structured = Object.hasOwn(parsed, "schema");
+	const warning = droppedOptionsWarning(parsed);
+	const fallbackId = parsed.label ?? options.callId;
+	if (warning) options.emitStatus?.({ op: "agent", id: fallbackId, status: "running", warning });
+
+	// omp assertNotPlanMode intentionally dropped: senpi has no plan mode
+	// senpi-task children lose task tools, so recursion self-gates without a depth counter.
+	if (options.executeTool.isToolAvailable?.(options.taskToolName) === false) {
+		throw new AgentUnavailableError(options.taskToolName);
+	}
+
+	let result: AgentToolResult<unknown>;
+	try {
+		result = await options.executeTool(options.taskToolName, toTaskParams(parsed, structured), {
+			...(options.signal ? { signal: options.signal } : {}),
+			...(options.emitStatus
+				? {
+						onUpdate: (update: AgentToolResult<unknown>) =>
+							options.emitStatus?.(toProgressEvent(update, { fallbackId, ...(warning ? { warning } : {}) })),
+					}
+				: {}),
+		});
+	} catch (error) {
+		if (isUnavailableToolError(error)) throw new AgentUnavailableError(options.taskToolName);
+		throw error;
+	}
+
+	const text = resultText(result);
+	if (parsed.handle === true) {
+		const id = resultTaskId(result, text);
+		if (!id) throw new AgentHandleError();
+		return { text, id, handle: `agent://${id}` };
+	}
+	if (!structured) return { text };
+	return parseStructuredText(text);
+}
+
+function parseAgentArgs(value: unknown): AgentArgs {
+	if (Check(agentArgsSchema, value)) return value;
+	const summary = Errors(agentArgsSchema, value)
+		.map((error) => `${error.instancePath || "/"} ${error.message}`)
+		.join("; ");
+	throw new AgentArgumentsError(summary || "invalid value");
+}
+
+function toTaskParams(args: AgentArgs, structured: boolean): TaskParams {
+	return {
+		prompt: structured
+			? `${args.prompt}\n\nRespond ONLY with JSON matching this JSON-Schema:\n${JSON.stringify(args.schema)}`
+			: args.prompt,
+		...(args.agent === undefined ? {} : { subagent_type: args.agent }),
+		...(args.model === undefined ? {} : { model: args.model }),
+		...(args.label === undefined ? {} : { name: args.label }),
+		run_in_background: args.handle === true,
+	};
+}
+
+function parseStructuredText(text: string): EvalAgentResult {
+	try {
+		const data: unknown = JSON.parse(text);
+		return { text, data };
+	} catch (error) {
+		if (error instanceof SyntaxError) return { text, parseError: error.message };
+		throw error;
+	}
+}
+
+function droppedOptionsWarning(args: AgentArgs): string | undefined {
+	return droppedOptionNames.some((name) => Object.hasOwn(args, name)) ? unsupportedIsolationWarning : undefined;
+}
+
+function toProgressEvent(update: AgentToolResult<unknown>, context: ProgressContext): EvalStatusEvent {
+	const details = isRecord(update.details) ? update.details : undefined;
+	const id = firstString(details, ["task_id", "taskId", "id"]) ?? context.fallbackId;
+	const status = firstString(details, ["status"]) ?? "running";
+	const agent = firstString(details, ["subagent_type", "agent"]);
+	return {
+		op: "agent",
+		id,
+		status,
+		...(agent === undefined ? {} : { agent }),
+		...(context.warning === undefined ? {} : { warning: context.warning }),
+	};
+}
+
+function resultText(result: AgentToolResult<unknown>): string {
+	return result.content
+		.filter((part): part is Extract<(typeof result.content)[number], { type: "text" }> => part.type === "text")
+		.map((part) => part.text)
+		.join("\n");
+}
+
+function resultTaskId(result: AgentToolResult<unknown>, text: string): string | undefined {
+	const details = isRecord(result.details) ? result.details : undefined;
+	const detailId = firstString(details, ["task_id", "taskId", "id"]);
+	if (detailId) return detailId;
+	return text.match(taskIdPattern)?.[0];
+}
+
+function firstString(
+	record: Readonly<Record<string, unknown>> | undefined,
+	keys: readonly string[],
+): string | undefined {
+	if (!record) return undefined;
+	for (const key of keys) {
+		const value = record[key];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return undefined;
+}
+
+function isUnavailableToolError(error: unknown): boolean {
+	if (!isRecord(error)) return false;
+	return error.code === "unknown_tool" || error.code === "inactive_tool";
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}