@jxburros/ai-nugget 0.3.1

package/nugget/src/adapters/engines/anthropic.ts

@@ -0,0 +1,260 @@
+import { AIError } from '../../errors.js';
+import { estimatedUsage } from '../../tokens.js';
+import { postResponse, sseLines } from '../../transport.js';
+import type { ChatMessage, ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
+import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
+import { streamError, streamTimeout } from './base.js';
+
+const JSON_MODE_TOOL = 'json_output';
+
+export class AnthropicAdapter implements ProviderAdapter {
+  readonly provider: string;
+  constructor(provider: string) {
+    this.provider = provider;
+  }
+
+  async chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult> {
+    let result: ChatResult | undefined;
+    for await (const event of this.stream(conn, req)) {
+      if (event.type === 'done') result = event.result;
+      if (event.type === 'error') throw event.error;
+    }
+    if (!result) throw new AIError('Anthropic stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+    return result;
+  }
+
+  async *stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent> {
+    const started = Date.now();
+    const jsonMode = req.responseFormat?.type === 'json' && !req.tools?.length;
+    let firstTokenMs: number | null = null;
+    let text = '';
+    let inputTokens: number | undefined;
+    let outputTokens: number | undefined;
+    let stopReason: string | undefined;
+    const emittedTools: ToolCall[] = [];
+    // Partial tool_use blocks keyed by content-block index (input_json_delta accumulation).
+    const blocks = new Map<number, { id: string; name: string; raw: string }>();
+    const timeout = streamTimeout(conn, req.signal);
+    yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+    try {
+      const res = await postResponse(`${conn.baseUrl}/v1/messages`, body(req, jsonMode), conn.headers, timeout.signal, conn.provider);
+      const contentType = res.headers.get('content-type') ?? '';
+      if (!contentType.includes('text/event-stream')) {
+        const data = await res.json() as unknown;
+        const parsed = parseResponse(data);
+        inputTokens = parsed.inputTokens;
+        outputTokens = parsed.outputTokens;
+        stopReason = parsed.stopReason;
+        if (jsonMode) {
+          text = jsonTextFrom(parsed.toolCalls, parsed.text);
+          if (text) yield { type: 'delta', text };
+        } else {
+          text = parsed.text;
+          if (text) yield { type: 'delta', text };
+          for (const call of parsed.toolCalls) {
+            emittedTools.push(call);
+            yield { type: 'tool_call', call };
+          }
+        }
+      } else {
+        for await (const line of sseLines(res)) {
+          const record = asRecord(safeParse(line));
+          if (!record) continue;
+          const type = asString(record.type);
+          if (type === 'message_start') {
+            const usage = asRecord(asRecord(record.message)?.usage);
+            inputTokens = asNumber(usage?.input_tokens) ?? inputTokens;
+            outputTokens = asNumber(usage?.output_tokens) ?? outputTokens;
+          } else if (type === 'content_block_start') {
+            const index = asNumber(record.index) ?? 0;
+            const block = asRecord(record.content_block);
+            if (block?.type === 'tool_use') {
+              blocks.set(index, { id: asString(block.id) ?? randomId(), name: asString(block.name) ?? 'unknown', raw: '' });
+            }
+          } else if (type === 'content_block_delta') {
+            const index = asNumber(record.index) ?? 0;
+            const delta = asRecord(record.delta);
+            if (delta?.type === 'text_delta') {
+              const piece = asString(delta.text) ?? '';
+              if (piece) {
+                if (firstTokenMs === null) firstTokenMs = Date.now() - started;
+                text += piece;
+                yield { type: 'delta', text: piece };
+              }
+            } else if (delta?.type === 'input_json_delta') {
+              const partial = blocks.get(index);
+              if (partial) partial.raw += asString(delta.partial_json) ?? '';
+            }
+          } else if (type === 'content_block_stop') {
+            const index = asNumber(record.index) ?? 0;
+            const partial = blocks.get(index);
+            if (partial) {
+              const call: ToolCall = { id: partial.id, name: partial.name, raw: partial.raw, arguments: parseArgs(partial.raw) };
+              blocks.delete(index);
+              if (jsonMode && call.name === JSON_MODE_TOOL) {
+                text = jsonTextFrom([call], text);
+                if (firstTokenMs === null) firstTokenMs = Date.now() - started;
+                yield { type: 'delta', text };
+              } else {
+                emittedTools.push(call);
+                yield { type: 'tool_call', call };
+              }
+            }
+          } else if (type === 'message_delta') {
+            const delta = asRecord(record.delta);
+            stopReason = asString(delta?.stop_reason) ?? stopReason;
+            const usage = asRecord(record.usage);
+            outputTokens = asNumber(usage?.output_tokens) ?? outputTokens;
+          }
+        }
+      }
+      const hasTools = emittedTools.length > 0;
+      yield { type: 'done', result: {
+        text,
+        toolCalls: hasTools ? emittedTools : undefined,
+        finishReason: mapStop(stopReason, hasTools),
+        usage: inputTokens !== undefined || outputTokens !== undefined ? { inputTokens, outputTokens, estimated: false } : estimatedUsage(textFromMessages(req.messages), text),
+        timing: { firstTokenMs, totalMs: Date.now() - started },
+        model: req.model,
+        source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+      } };
+    } catch (error) {
+      throw streamError(error, timeout, conn.provider);
+    } finally {
+      timeout.done();
+    }
+  }
+}
+
+function body(req: ChatRequest, jsonMode: boolean): Record<string, unknown> {
+  const system = req.messages.filter((m) => m.role === 'system').map((m) => textContent(m.content)).join('\n\n') || undefined;
+  const base: Record<string, unknown> = {
+    model: req.model,
+    max_tokens: req.maxTokens ?? 4096,
+    temperature: req.temperature,
+    top_p: req.topP,
+    stop_sequences: req.stopSequences,
+    system,
+    messages: toAnthropicMessages(req.messages.filter((m) => m.role !== 'system')),
+    stream: true,
+  };
+  if (jsonMode) {
+    // Forced-tool JSON mode: Anthropic has no response_format, so we make the
+    // model answer through a single required tool whose input is the JSON we want.
+    base.tools = [{ name: JSON_MODE_TOOL, description: 'Return the answer as a JSON object.', input_schema: schemaFor(req) }];
+    base.tool_choice = { type: 'tool', name: JSON_MODE_TOOL };
+  } else if (req.tools?.length) {
+    base.tools = req.tools.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.parameters }));
+    if (typeof req.toolChoice === 'object') base.tool_choice = { type: 'tool', name: req.toolChoice.name };
+    else if (req.toolChoice === 'auto') base.tool_choice = { type: 'auto' };
+    else if (req.toolChoice === 'none') base.tool_choice = { type: 'none' };
+  }
+  return base;
+}
+
+function toAnthropicMessages(messages: ChatMessage[]): Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = [];
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index]!;
+    if (message.role !== 'tool') {
+      out.push(toAnthropicMessage(message));
+      continue;
+    }
+    const content: unknown[] = [];
+    while (index < messages.length && messages[index]?.role === 'tool') {
+      const toolMessage = messages[index]!;
+      content.push({ type: 'tool_result', tool_use_id: toolMessage.toolCallId ?? '', content: textContent(toolMessage.content) });
+      index += 1;
+    }
+    index -= 1;
+    out.push({ role: 'user', content });
+  }
+  return out;
+}
+
+function toAnthropicMessage(m: ChatMessage): Record<string, unknown> {
+  // tool result messages map to a user turn carrying a tool_result content block.
+  if (m.role === 'tool') {
+    return {
+      role: 'user',
+      content: [{ type: 'tool_result', tool_use_id: m.toolCallId ?? '', content: typeof m.content === 'string' ? m.content : '' }],
+    };
+  }
+  // assistant turns that carried tool calls replay them as tool_use blocks.
+  if (m.role === 'assistant' && m.toolCalls?.length) {
+    const content: unknown[] = [];
+    if (typeof m.content === 'string' && m.content) content.push({ type: 'text', text: m.content });
+    for (const call of m.toolCalls) content.push({ type: 'tool_use', id: call.id, name: call.name, input: call.arguments ?? {} });
+    return { role: 'assistant', content };
+  }
+  return {
+    role: m.role === 'assistant' ? 'assistant' : 'user',
+    content: typeof m.content === 'string' ? m.content : m.content.map((part) => part.type === 'image'
+      ? { type: 'image', source: { type: 'base64', media_type: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
+      : { type: 'text', text: part.text ?? '' }),
+  };
+}
+
+function textContent(content: ChatMessage['content']): string {
+  if (typeof content === 'string') return content;
+  if (!content) return '';
+  return content.filter((part) => part.type === 'text').map((part) => part.text ?? '').join('\n');
+}
+
+function parseResponse(data: unknown): { text: string; inputTokens?: number; outputTokens?: number; stopReason?: string; toolCalls: ToolCall[] } {
+  const record = asRecord(data);
+  const content = Array.isArray(record?.content) ? record.content : [];
+  let text = '';
+  const toolCalls: ToolCall[] = [];
+  for (const blockValue of content) {
+    const block = asRecord(blockValue);
+    if (block?.type === 'text') text += asString(block.text) ?? '';
+    if (block?.type === 'tool_use') {
+      toolCalls.push({
+        id: asString(block.id) ?? randomId(),
+        name: asString(block.name) ?? 'unknown',
+        arguments: block.input ?? {},
+        raw: JSON.stringify(block.input ?? {}),
+      });
+    }
+  }
+  const usage = asRecord(record?.usage);
+  return { text, inputTokens: asNumber(usage?.input_tokens), outputTokens: asNumber(usage?.output_tokens), stopReason: asString(record?.stop_reason), toolCalls };
+}
+
+function schemaFor(req: ChatRequest): object {
+  const schema = req.responseFormat?.type === 'json' ? req.responseFormat.schema : undefined;
+  return schema ?? { type: 'object' };
+}
+
+function jsonTextFrom(toolCalls: ToolCall[], fallback: string): string {
+  const json = toolCalls.find((call) => call.name === JSON_MODE_TOOL) ?? toolCalls[0];
+  if (json) return json.raw && json.raw.trim() ? json.raw : JSON.stringify(json.arguments ?? {});
+  return fallback;
+}
+
+function mapStop(stop: string | undefined, hasTools: boolean): ChatResult['finishReason'] {
+  if (stop === 'tool_use' && hasTools) return 'tool';
+  if (stop === 'max_tokens') return 'length';
+  return 'stop';
+}
+
+function parseArgs(raw: string): unknown {
+  try {
+    return raw ? JSON.parse(raw) as unknown : {};
+  } catch {
+    return {};
+  }
+}
+
+function safeParse(line: string): unknown {
+  try {
+    return JSON.parse(line) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function randomId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}

package/nugget/src/adapters/engines/base.ts

@@ -0,0 +1,90 @@
+import { AIError, fromUnknown } from '../../errors.js';
+import { fetchJson, withTimeout } from '../../transport.js';
+import type { ModelInfo, ResolvedConnection } from '../../types.js';
+import { asRecord, asString } from '../../util.js';
+import type { ProviderProfile } from '../profiles.js';
+
+export const DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * Maps a raw streaming failure onto a typed {@link AIError}. A fired timeout is
+ * reported as `timeout` regardless of how the underlying `fetch` surfaced the
+ * abort; anything else is normalized through {@link fromUnknown} (which passes
+ * an existing {@link AIError} through untouched, preserving retryability).
+ */
+export function streamError(error: unknown, timeout: { timedOut(): boolean }, provider: string): AIError {
+  if (timeout.timedOut()) return new AIError('Request timed out', { kind: 'timeout', provider });
+  return fromUnknown(error, provider);
+}
+
+/** Create a timeout/abort scope covering the full stream lifetime. */
+export function streamTimeout(conn: ResolvedConnection, signal?: AbortSignal): ReturnType<typeof withTimeout> {
+  return withTimeout(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal);
+}
+
+export async function listOpenModels(conn: ResolvedConnection, profile: ProviderProfile): Promise<ModelInfo[]> {
+  if (!profile.listModelsPath) return [];
+  const { data } = await fetchJson(`${conn.baseUrl}${profile.listModelsPath}`, {
+    method: 'GET',
+    headers: conn.headers,
+    timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    provider: conn.provider,
+  });
+  const record = asRecord(data);
+  const items = Array.isArray(record?.data) ? record.data : Array.isArray(record?.models) ? record.models : [];
+  const models: ModelInfo[] = [];
+  for (const item of items) {
+    const row = asRecord(item);
+    const id = asString(row?.id) ?? asString(row?.name);
+    if (!id) continue;
+    const contextWindow = asContextWindow(row);
+    const capabilities = asCapabilities(row);
+    const model: ModelInfo = {
+      id,
+      source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+    };
+    if (contextWindow !== undefined) model.contextWindow = contextWindow;
+    if (capabilities) model.capabilities = capabilities;
+    models.push(model);
+  }
+  return models;
+}
+
+export async function health(conn: ResolvedConnection, profile: ProviderProfile): Promise<{ ok: boolean; detail?: string }> {
+  const path = profile.healthPath ?? profile.listModelsPath;
+  if (!path) return { ok: true };
+  try {
+    await fetchJson(`${conn.baseUrl}${path}`, {
+      method: 'GET',
+      headers: conn.headers,
+      timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 10_000),
+      provider: conn.provider,
+    });
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, detail: error instanceof Error ? error.message : 'Health check failed' };
+  }
+}
+
+export function requireResponse(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new AIError(message, { kind: 'invalid_response' });
+}
+
+/**
+ * Pulls a context-window figure out of the many shapes providers use for it
+ * (OpenRouter `context_length`, OpenAI-style `context_window`, Ollama
+ * `/api/show` `model_info` entries surfaced as `contextWindow`).
+ */
+function asContextWindow(row: Record<string, unknown> | undefined): number | undefined {
+  if (!row) return undefined;
+  const direct = row['context_length'] ?? row['context_window'] ?? row['contextWindow'];
+  return typeof direct === 'number' && Number.isFinite(direct) ? direct : undefined;
+}
+
+function asCapabilities(row: Record<string, unknown> | undefined): string[] | undefined {
+  if (!row) return undefined;
+  const value = row['capabilities'] ?? asRecord(row['architecture'])?.['modality'];
+  if (Array.isArray(value) && value.every((entry) => typeof entry === 'string')) return value as string[];
+  if (typeof value === 'string') return [value];
+  return undefined;
+}

package/nugget/src/adapters/engines/google.ts

@@ -0,0 +1,209 @@
+import { AIError } from '../../errors.js';
+import { estimatedUsage } from '../../tokens.js';
+import { postResponse, sseLines } from '../../transport.js';
+import type { ChatMessage, ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
+import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
+import { streamError, streamTimeout } from './base.js';
+
+export class GoogleAdapter implements ProviderAdapter {
+  readonly provider: string;
+  constructor(provider: string) {
+    this.provider = provider;
+  }
+
+  async chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult> {
+    let result: ChatResult | undefined;
+    for await (const event of this.stream(conn, req)) {
+      if (event.type === 'done') result = event.result;
+      if (event.type === 'error') throw event.error;
+    }
+    if (!result) throw new AIError('Google stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+    return result;
+  }
+
+  async *stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent> {
+    const started = Date.now();
+    let firstTokenMs: number | null = null;
+    let text = '';
+    let inputTokens: number | undefined;
+    let outputTokens: number | undefined;
+    let finish: string | undefined;
+    const toolCalls: ToolCall[] = [];
+    const timeout = streamTimeout(conn, req.signal);
+    yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+    try {
+      const streamUrl = `${conn.baseUrl}/v1beta/models/${encodeURIComponent(req.model)}:streamGenerateContent?alt=sse`;
+      const res = await postResponse(streamUrl, body(req), conn.headers, timeout.signal, conn.provider);
+      const contentType = res.headers.get('content-type') ?? '';
+      const chunks = contentType.includes('text/event-stream') ? sseLines(res) : singleJsonLine(res);
+      for await (const line of chunks) {
+        const parsed = safeParse(line);
+        const record = asRecord(parsed);
+        const promptFeedback = asRecord(record?.promptFeedback);
+        if (!firstCandidate(record) && promptFeedback?.blockReason) finish = 'SAFETY';
+        for (const part of candidateParts(record)) {
+          const partText = asString(asRecord(part)?.text);
+          if (partText) {
+            if (firstTokenMs === null) firstTokenMs = Date.now() - started;
+            text += partText;
+            yield { type: 'delta', text: partText };
+          }
+          const fnCall = asRecord(asRecord(part)?.functionCall);
+          if (fnCall) {
+            const call: ToolCall = {
+              id: randomId(),
+              name: asString(fnCall.name) ?? 'unknown',
+              arguments: fnCall.args ?? {},
+              raw: JSON.stringify(fnCall.args ?? {}),
+            };
+            toolCalls.push(call);
+            yield { type: 'tool_call', call };
+          }
+        }
+        finish = asString(asRecord(firstCandidate(record))?.finishReason) ?? finish;
+        const usage = asRecord(record?.usageMetadata);
+        inputTokens = asNumber(usage?.promptTokenCount) ?? inputTokens;
+        outputTokens = asNumber(usage?.candidatesTokenCount) ?? outputTokens;
+      }
+      const hasTools = toolCalls.length > 0;
+      yield { type: 'done', result: {
+        text,
+        toolCalls: hasTools ? toolCalls : undefined,
+        finishReason: mapFinish(finish, hasTools),
+        usage: inputTokens !== undefined || outputTokens !== undefined ? { inputTokens, outputTokens, estimated: false } : estimatedUsage(textFromMessages(req.messages), text),
+        timing: { firstTokenMs, totalMs: Date.now() - started },
+        model: req.model,
+        source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+      } };
+    } catch (error) {
+      throw streamError(error, timeout, conn.provider);
+    } finally {
+      timeout.done();
+    }
+  }
+}
+
+function body(req: ChatRequest): Record<string, unknown> {
+  const systemText = req.messages.filter((m) => m.role === 'system').map((m) => textContent(m.content)).join('\n\n');
+  const jsonMode = req.responseFormat?.type === 'json' && !req.tools?.length;
+  const responseSchema = req.responseFormat?.type === 'json' ? req.responseFormat.schema : undefined;
+  const payload: Record<string, unknown> = {
+    contents: toGoogleContents(req.messages.filter((m) => m.role !== 'system')),
+    generationConfig: {
+      temperature: req.temperature,
+      topP: req.topP,
+      maxOutputTokens: req.maxTokens,
+      stopSequences: req.stopSequences,
+      responseMimeType: jsonMode ? 'application/json' : undefined,
+      responseSchema: jsonMode ? responseSchema : undefined,
+    },
+  };
+  if (systemText) payload.systemInstruction = { parts: [{ text: systemText }] };
+  if (req.tools?.length) {
+    payload.tools = [{ functionDeclarations: req.tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters })) }];
+    const mode = req.toolChoice === 'none' ? 'NONE' : typeof req.toolChoice === 'object' ? 'ANY' : 'AUTO';
+    const config: Record<string, unknown> = { mode };
+    if (typeof req.toolChoice === 'object') config.allowedFunctionNames = [req.toolChoice.name];
+    payload.toolConfig = { functionCallingConfig: config };
+  }
+  return payload;
+}
+
+function toGoogleContents(messages: ChatMessage[]): Record<string, unknown>[] {
+  const contents: Record<string, unknown>[] = [];
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index]!;
+    if (message.role !== 'tool') {
+      contents.push(toGoogleContent(message));
+      continue;
+    }
+    const parts: unknown[] = [];
+    while (index < messages.length && messages[index]?.role === 'tool') {
+      const toolMessage = messages[index]!;
+      parts.push({ functionResponse: { name: toolMessage.name ?? 'unknown', response: toolResponseObject(toolMessage) } });
+      index += 1;
+    }
+    index -= 1;
+    contents.push({ role: 'user', parts });
+  }
+  return contents;
+}
+
+function toGoogleContent(m: ChatMessage): Record<string, unknown> {
+  if (m.role === 'tool') {
+    return {
+      role: 'user',
+      parts: [{ functionResponse: { name: m.name ?? 'unknown', response: toolResponseObject(m) } }],
+    };
+  }
+  if (m.role === 'assistant' && m.toolCalls?.length) {
+    const parts: unknown[] = [];
+    if (typeof m.content === 'string' && m.content) parts.push({ text: m.content });
+    for (const call of m.toolCalls) parts.push({ functionCall: { name: call.name, args: call.arguments ?? {} } });
+    return { role: 'model', parts };
+  }
+  return {
+    role: m.role === 'assistant' ? 'model' : 'user',
+    parts: typeof m.content === 'string'
+      ? [{ text: m.content }]
+      : m.content.map((part) => part.type === 'image'
+        ? { inlineData: { mimeType: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
+        : { text: part.text ?? '' }),
+  };
+}
+
+function textContent(content: ChatMessage['content']): string {
+  if (typeof content === 'string') return content;
+  if (!content) return '';
+  return content.filter((part) => part.type === 'text').map((part) => part.text ?? '').join('\n');
+}
+
+function toolResponseObject(message: ChatMessage): Record<string, unknown> {
+  if (typeof message.content !== 'string') return { content: textContent(message.content) };
+  try {
+    const parsed: unknown = JSON.parse(message.content);
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as Record<string, unknown>;
+  } catch {
+    // keep string fallback
+  }
+  return { content: message.content };
+}
+
+async function* singleJsonLine(res: Response): AsyncIterable<string> {
+  const data = await res.json() as unknown;
+  // Non-SSE responses may be a single object or an array of streamed chunks.
+  if (Array.isArray(data)) {
+    for (const item of data) yield JSON.stringify(item);
+  } else {
+    yield JSON.stringify(data);
+  }
+}
+
+function firstCandidate(record: Record<string, unknown> | undefined): unknown {
+  const candidates = Array.isArray(record?.candidates) ? record.candidates : [];
+  return candidates[0];
+}
+
+function candidateParts(record: Record<string, unknown> | undefined): unknown[] {
+  const content = asRecord(asRecord(firstCandidate(record))?.content);
+  return Array.isArray(content?.parts) ? content.parts : [];
+}
+
+function mapFinish(finish: string | undefined, hasTools: boolean): ChatResult['finishReason'] {
+  if (hasTools) return 'tool';
+  if (finish === 'MAX_TOKENS') return 'length';
+  if (finish === 'SAFETY' || finish === 'RECITATION' || finish === 'BLOCKLIST' || finish === 'PROHIBITED_CONTENT') return 'content_filter';
+  return 'stop';
+}
+
+function safeParse(line: string): unknown {
+  try {
+    return JSON.parse(line) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function randomId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}