amalgm 0.0.0 → 0.0.32

package/runtime/scripts/chat-core/runtime.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const { assertSameContract } = require('./contract');
+
+class RuntimeController {
+  constructor({ adapters }) {
+    this.adapters = adapters;
+    this.sessions = new Map();
+  }
+
+  async create(contract) {
+    const existing = this.sessions.get(contract.sessionId);
+    if (existing) await this.destroy(contract.sessionId);
+    const factory = this.adapters[contract.harness];
+    if (!factory) throw new Error(`No adapter for ${contract.harness}`);
+    const adapter = factory();
+    const runtimeSession = await adapter.create(contract);
+    const record = {
+      contract,
+      adapter,
+      runtimeSession,
+      providerSessionId: runtimeSession.providerSessionId || runtimeSession.sessionId || null,
+      state: 'ready',
+      createdAt: Date.now(),
+      lastUsedAt: Date.now(),
+    };
+    this.sessions.set(contract.sessionId, record);
+    return record;
+  }
+
+  async resume(contract) {
+    const existing = this.sessions.get(contract.sessionId);
+    if (!existing) return this.create(contract);
+    assertSameContract(existing.contract, contract);
+    if (typeof existing.adapter.resume === 'function') {
+      existing.runtimeSession = await existing.adapter.resume(existing.runtimeSession, contract);
+    }
+    existing.contract = contract;
+    existing.providerSessionId = existing.runtimeSession.providerSessionId || existing.providerSessionId;
+    existing.state = 'ready';
+    existing.lastUsedAt = Date.now();
+    return existing;
+  }
+
+  async prompt(contract, input) {
+    const record = await this.resume(contract);
+    record.state = 'running';
+    record.lastUsedAt = Date.now();
+    const source = await record.adapter.prompt(record.runtimeSession, input, contract);
+    const self = this;
+    return (async function* stream() {
+      try {
+        for await (const e of source) yield e;
+      } finally {
+        const current = self.sessions.get(contract.sessionId);
+        if (current && current.state === 'running') {
+          current.state = 'ready';
+          current.lastUsedAt = Date.now();
+        }
+      }
+    })();
+  }
+
+  async stop(sessionId) {
+    const record = this.sessions.get(sessionId);
+    if (!record) return false;
+    if (typeof record.adapter.stop === 'function') await record.adapter.stop(record.runtimeSession);
+    record.state = 'stopped';
+    record.lastUsedAt = Date.now();
+    return true;
+  }
+
+  async destroy(sessionId) {
+    const record = this.sessions.get(sessionId);
+    if (!record) return false;
+    if (typeof record.adapter.destroy === 'function') await record.adapter.destroy(record.runtimeSession);
+    this.sessions.delete(sessionId);
+    return true;
+  }
+
+  get(sessionId) {
+    return this.sessions.get(sessionId) || null;
+  }
+}
+
+module.exports = { RuntimeController };

package/runtime/scripts/chat-core/server.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const http = require('http');
+const { PORT, PROXY_BASE_URL, ensureFreshProxyToken } = require('../chat-server/config');
+const db = require('../chat-server/db');
+const { CodexAdapter } = require('./adapters/codex');
+const { ClaudeAdapter } = require('./adapters/claude');
+const { OpenCodeAdapter } = require('./adapters/opencode');
+const { ChatCore } = require('./engine');
+const { forwardEgress, parseEgressPath } = require('./egress');
+const { forwardMcpRelay, parseMcpRelayPath } = require('./tooling/mcp-relay');
+const { RuntimeController } = require('./runtime');
+const { writeSseHeaders } = require('./sse');
+const { TurnStore } = require('./stores');
+const { authorizeRuntimeHttp } = require('../runtime-auth');
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8').trim();
+      if (!raw) return resolve({});
+      try { resolve(JSON.parse(raw)); } catch (err) { reject(err); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache' });
+  res.end(JSON.stringify(payload));
+}
+
+function parseRoute(url) {
+  const u = new URL(url, 'http://localhost');
+  const parts = u.pathname.split('/').filter(Boolean);
+  if (parts[0] === 'chat' && parts.length === 1) return { handler: 'chat' };
+  if (parts[0] === 'raw-temp' && parts[1]) return { handler: 'raw-temp', id: parts[1], afterIndex: Number(u.searchParams.get('afterIndex') ?? -1) };
+  if (parts[0] === 'active' && parts[1]) return { handler: 'active', id: parts[1] };
+  if (parts[0] === 'stop' && parts[1]) return { handler: 'stop', id: parts[1] };
+  if (parts[0] === 'destroy' && parts[1]) return { handler: 'destroy', id: parts[1] };
+  if (parts[0] === 'egress' && parts[1]) {
+    const parsed = parseEgressPath(u.pathname);
+    return parsed ? { handler: 'egress', ...parsed, search: u.search } : null;
+  }
+  if (parts[0] === 'mcp-relay' && parts[1] && parts[2]) {
+    const parsed = parseMcpRelayPath(u.pathname);
+    return parsed ? { handler: 'mcp-relay', ...parsed, search: u.search } : null;
+  }
+  if (parts[0] === 'healthz') return { handler: 'healthz' };
+  return null;
+}
+
+function writeRawTemp(core, route, res) {
+  const entry = core.turns.latest(route.id) || core.turns.get(route.id);
+  if (!entry) return sendJson(res, 404, { error: 'No active stream', codeSessionId: route.id });
+  writeSseHeaders(res);
+  const chunks = entry.chunks.filter((chunk) => chunk.index > (Number.isFinite(route.afterIndex) ? route.afterIndex : -1));
+  if (chunks.length) {
+    res.write(`event: existing\ndata: ${JSON.stringify({ codeSessionId: entry.sessionId, assistantMessageId: entry.assistantMessageId, chunks, total: chunks.length })}\n\n`);
+  }
+  if (entry.status !== 'streaming') {
+    res.write(`event: complete\ndata: ${JSON.stringify({ codeSessionId: entry.sessionId, total: entry.chunks.length })}\n\n`);
+    res.end();
+    return;
+  }
+  const off = core.turns.subscribe(entry.turnId, (chunk, current) => {
+    if (chunk) res.write(`event: chunk\ndata: ${JSON.stringify({ codeSessionId: current.sessionId, chunk, total: current.chunks.length })}\n\n`);
+    else {
+      res.write(`event: complete\ndata: ${JSON.stringify({ codeSessionId: current.sessionId, total: current.chunks.length })}\n\n`);
+      res.end();
+    }
+  });
+  res.on('close', off);
+}
+
+function createCore(options = {}) {
+  const turns = new TurnStore();
+  const runtime = new RuntimeController({
+    adapters: {
+      claude_code: () => new ClaudeAdapter(),
+      codex: () => new CodexAdapter(),
+      opencode: () => new OpenCodeAdapter(),
+    },
+  });
+  return new ChatCore({ db, runtime, turns, options: { ...options, port: PORT } });
+}
+
+function createServer(core = createCore()) {
+  return http.createServer(async (req, res) => {
+    if (!authorizeRuntimeHttp(req, res, { exemptPrefixes: ['/egress/'] })) return;
+    const route = parseRoute(req.url);
+    if (!route) return sendJson(res, 404, { error: 'Not found' });
+    try {
+      if (route.handler === 'healthz') return sendJson(res, 200, { status: 'ok', runtime: 'chat-core', uptime: process.uptime() });
+      if (route.handler === 'active') return sendJson(res, 200, core.active(route.id));
+      if (route.handler === 'stop') {
+        if (req.method !== 'POST') return sendJson(res, 405, { error: 'Method not allowed' });
+        return sendJson(res, 200, { stopped: await core.stop(route.id), codeSessionId: route.id });
+      }
+      if (route.handler === 'destroy') {
+        if (req.method !== 'DELETE') return sendJson(res, 405, { error: 'Method not allowed' });
+        return sendJson(res, 200, { destroyed: await core.destroy(route.id), codeSessionId: route.id });
+      }
+      if (route.handler === 'raw-temp') return writeRawTemp(core, route, res);
+      if (route.handler === 'egress') {
+        const contract = core.contracts.get(route.sessionId);
+        if (!contract || contract.authMethod !== 'amalgm') return sendJson(res, 404, { error: 'No Amalgm egress session', sessionId: route.sessionId });
+        const proxyToken = await ensureFreshProxyToken();
+        return await forwardEgress({
+          req,
+          res,
+          contract,
+          turn: core.turns.active(route.sessionId),
+          proxyBaseUrl: PROXY_BASE_URL || 'https://amalgm-api-proxy-v2.fly.dev',
+          proxyToken,
+          upstreamPath: `${route.upstreamPath}${route.search || ''}`,
+        });
+      }
+      if (route.handler === 'mcp-relay') {
+        const contract = core.contracts.get(route.sessionId);
+        if (!contract) return sendJson(res, 404, { error: 'No MCP relay session', sessionId: route.sessionId });
+        return await forwardMcpRelay({ req, res, contract, serverName: route.serverName, search: route.search || '' });
+      }
+      if (route.handler === 'chat') {
+        if (req.method !== 'POST') return sendJson(res, 405, { error: 'Method not allowed' });
+        const payload = await readBody(req);
+        writeSseHeaders(res);
+        let open = true;
+        const heartbeat = setInterval(() => {
+          if (open && !res.writableEnded) res.write(': keep-alive\n\n');
+        }, 15_000);
+        heartbeat.unref?.();
+        res.on('close', () => { open = false; });
+        try {
+          await core.runTurn(payload, (frame) => {
+            if (open && !res.writableEnded) res.write(frame);
+          });
+        } finally {
+          clearInterval(heartbeat);
+        }
+        if (!res.writableEnded) res.end();
+      }
+    } catch (err) {
+      console.error('[ChatCore] error:', err);
+      if (!res.headersSent) sendJson(res, 500, { error: err.message || 'Internal server error' });
+      else {
+        res.write(`data: ${JSON.stringify({ _type: 'error', message: err.message || 'Internal server error' })}\n\n`);
+        res.write(`data: ${JSON.stringify({ _type: 'complete', stopReason: 'error' })}\n\n`);
+        res.end();
+      }
+    }
+  });
+}
+
+module.exports = {
+  createCore,
+  createServer,
+  parseRoute,
+  readBody,
+  sendJson,
+};

package/runtime/scripts/chat-core/sse.js

@@ -0,0 +1,196 @@
+'use strict';
+
+const { toolKind: canonicalToolKind } = require('./tool-shape');
+const { totalUsageTokens } = require('./usage');
+
+function toPromptUsage(usage) {
+  if (!usage) return undefined;
+  const totalTokens = totalUsageTokens(usage);
+  const tokenList = usage.tokenList || {
+    input: Number(usage.inputTokens || 0),
+    output: Number(usage.outputTokens || 0),
+    cacheRead: Number(usage.cacheReadTokens || 0),
+    cacheWrite: Number(usage.cacheWriteTokens || 0),
+    thought: Number(usage.thoughtTokens || 0),
+    total: totalTokens,
+  };
+  return {
+    tokenList,
+    cumulativeTokenList: usage.cumulativeTokenList ?? null,
+    previousCumulativeTokenList: usage.previousCumulativeTokenList ?? null,
+    inputTokens: Number(tokenList.input || 0),
+    outputTokens: Number(tokenList.output || 0),
+    cacheReadTokens: Number(tokenList.cacheRead || 0),
+    cacheWriteTokens: Number(tokenList.cacheWrite || 0),
+    thoughtTokens: Number(tokenList.thought || 0),
+    inputContextSize: usage.inputContextSize ?? tokenList.total ?? totalTokens,
+    totalTokens,
+    contextUsedTokens: usage.contextUsedTokens ?? usage.inputContextSize ?? tokenList.total ?? null,
+    contextLimit: usage.contextLimit ?? null,
+    usedTokens: usage.usedTokens ?? usage.contextUsedTokens ?? usage.inputContextSize ?? tokenList.total ?? null,
+    lastUsedTokens: usage.lastUsedTokens ?? usage.contextUsedTokens ?? usage.inputContextSize ?? tokenList.total ?? null,
+    maxTokens: usage.maxTokens ?? usage.contextLimit ?? null,
+    totalProcessedTokens: usage.totalProcessedTokens ?? null,
+    costUsd: usage.costUsd ?? null,
+    marketCostUsd: usage.marketCostUsd ?? null,
+    operation: usage.operation,
+    billable: usage.billable !== false,
+    source: usage.source,
+    exact: usage.exact === true,
+  };
+}
+
+function usageContextUsed(usage) {
+  const parsed = Number(usage?.inputContextSize ?? usage?.tokenList?.total ?? usage?.contextUsedTokens ?? usage?.usedTokens);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : 0;
+}
+
+function usageContextLimit(usage) {
+  const parsed = Number(usage?.contextLimit ?? usage?.maxTokens);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : 0;
+}
+
+function toolKind(name) {
+  const clean = String(name || '').toLowerCase();
+  const canonical = canonicalToolKind(name);
+  if (canonical && canonical !== 'unknown') return canonical;
+  if (clean.includes('bash') || clean.includes('command')) return 'execute';
+  if (clean.includes('read')) return 'read';
+  if (clean.includes('edit') || clean.includes('write') || clean.includes('file')) return 'edit';
+  if (clean.includes('grep') || clean.includes('glob') || clean.includes('search')) return 'search';
+  if (clean.includes('fetch')) return 'fetch';
+  return 'other';
+}
+
+function toAgentStreamEvent(e, context = {}) {
+  if (e.type === 'text.delta') {
+    return { _type: 'update', eventTimestamp: e.ts, sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: e.text || '' } };
+  }
+  if (e.type === 'reasoning.delta') {
+    return { _type: 'update', eventTimestamp: e.ts, sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: e.text || '' } };
+  }
+  if (e.type === 'tool.started') {
+    return {
+      _type: 'update',
+      eventTimestamp: e.ts,
+      sessionUpdate: 'tool_call',
+      toolCallId: e.toolCallId,
+      toolName: e.toolName || e.name,
+      title: e.title || e.toolName,
+      kind: e.kind || toolKind(e.toolName),
+      status: 'in_progress',
+      rawInput: e.input || {},
+      metadata: e.metadata || undefined,
+      timing: e.timing || undefined,
+    };
+  }
+  if (e.type === 'tool.updated') {
+    return {
+      _type: 'update',
+      eventTimestamp: e.ts,
+      sessionUpdate: 'tool_call_update',
+      toolCallId: e.toolCallId,
+      toolName: e.toolName || e.name,
+      title: e.title || null,
+      kind: e.kind || null,
+      status: e.status || 'in_progress',
+      rawInput: e.inputDelta || undefined,
+      rawOutput: e.outputDelta ?? e.output ?? undefined,
+      error: e.error || undefined,
+      metadata: e.metadata || undefined,
+      timing: e.timing || undefined,
+    };
+  }
+  if (e.type === 'tool.completed') {
+    return {
+      _type: 'update',
+      eventTimestamp: e.ts,
+      sessionUpdate: 'tool_call_update',
+      toolCallId: e.toolCallId,
+      toolName: e.toolName || e.name,
+      title: e.title || null,
+      kind: e.kind || null,
+      status: e.isError ? 'failed' : 'completed',
+      rawInput: e.input || undefined,
+      rawOutput: e.output ?? e.result ?? '',
+      error: e.error || undefined,
+      metadata: e.metadata || undefined,
+      timing: e.timing || undefined,
+    };
+  }
+  if (e.type === 'usage.final') {
+    const usage = toPromptUsage(e.usage);
+    const contextUsed = usageContextUsed(e.usage);
+    const contextLimit = usageContextLimit(e.usage);
+    const fallbackTotal = usage?.totalTokens || 0;
+    return {
+      _type: 'update',
+      eventTimestamp: e.ts,
+      sessionUpdate: 'usage_update',
+      used: contextUsed || fallbackTotal,
+      size: contextLimit || null,
+      inputContextSize: usage?.inputContextSize ?? undefined,
+      cost: usage?.costUsd != null ? { amount: usage.costUsd, currency: 'USD' } : null,
+      usage,
+    };
+  }
+  if (e.type === 'compaction.started') {
+    return {
+      _type: 'update',
+      eventTimestamp: e.ts,
+      sessionUpdate: 'compaction_boundary',
+      phase: 'started',
+      trigger: e.trigger || 'auto',
+    };
+  }
+  if (e.type === 'compaction.finished') {
+    return {
+      _type: 'update',
+      eventTimestamp: e.ts,
+      sessionUpdate: 'compaction_boundary',
+      phase: 'finished',
+      trigger: e.trigger || 'auto',
+      preTokens: e.preTokens ?? null,
+      postTokens: e.postTokens ?? null,
+      durationMs: e.durationMs ?? null,
+    };
+  }
+  if (e.type === 'warning') {
+    return {
+      _type: 'model_error',
+      error: e.message || 'Runtime warning',
+      requestedModel: e.requestedModel || '',
+      eventTimestamp: e.ts,
+    };
+  }
+  if (e.type === 'error') return { _type: 'error', message: e.message || 'Unknown error', eventTimestamp: e.ts };
+  if (e.type === 'done') {
+    return {
+      _type: 'complete',
+      codeSessionId: context.sessionId,
+      providerSessionId: e.providerSessionId || context.providerSessionId || null,
+      stopReason: e.stopReason || 'end_turn',
+      usage: toPromptUsage(context.usage || e.usage),
+      eventTimestamp: e.ts,
+    };
+  }
+  return { _type: 'update', eventTimestamp: e.ts, sessionUpdate: 'session_info_update' };
+}
+
+function frameFor(e, context) {
+  return `data: ${JSON.stringify(toAgentStreamEvent(e, context))}\n\n`;
+}
+
+function titleFrame({ sessionId, title }) {
+  return `data: ${JSON.stringify({ _type: 'title_generated', sessionId, title })}\n\n`;
+}
+
+function writeSseHeaders(res) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+  });
+}
+
+module.exports = { frameFor, titleFrame, toAgentStreamEvent, toPromptUsage, writeSseHeaders };

package/runtime/scripts/chat-core/stores.js

@@ -0,0 +1,100 @@
+'use strict';
+
+class TurnStore {
+  constructor() {
+    this.turns = new Map();
+    this.activeBySession = new Map();
+    this.latestBySession = new Map();
+    this.listeners = new Map();
+  }
+
+  start({ sessionId, turnId, assistantMessageId, userMessageId }) {
+    const previous = this.activeBySession.get(sessionId);
+    if (previous && previous !== turnId) this.mark(previous, 'aborted');
+    const entry = {
+      sessionId,
+      turnId,
+      assistantMessageId,
+      userMessageId,
+      status: 'streaming',
+      chunks: [],
+      parts: [],
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    this.turns.set(turnId, entry);
+    this.activeBySession.set(sessionId, turnId);
+    this.latestBySession.set(sessionId, turnId);
+    return entry;
+  }
+
+  active(sessionId) {
+    const turnId = this.activeBySession.get(sessionId);
+    return turnId ? this.turns.get(turnId) || null : null;
+  }
+
+  latest(sessionId) {
+    return this.active(sessionId) || this.get(this.latestBySession.get(sessionId));
+  }
+
+  get(turnId) {
+    return this.turns.get(turnId) || null;
+  }
+
+  addChunk(turnId, frame) {
+    const entry = this.turns.get(turnId);
+    if (!entry || !['streaming', 'cancelling'].includes(entry.status)) return null;
+    const chunk = { index: entry.chunks.length, data: frame, timestamp: Date.now() };
+    entry.chunks.push(chunk);
+    entry.updatedAt = Date.now();
+    this.emit(turnId, chunk, entry);
+    return chunk;
+  }
+
+  setParts(turnId, parts) {
+    const entry = this.turns.get(turnId);
+    if (entry) entry.parts = parts;
+  }
+
+  mark(turnId, status) {
+    const entry = this.turns.get(turnId);
+    if (!entry) return;
+    entry.status = status;
+    entry.updatedAt = Date.now();
+    if (status !== 'cancelling' && this.activeBySession.get(entry.sessionId) === turnId) this.activeBySession.delete(entry.sessionId);
+    this.emit(turnId, null, entry);
+  }
+
+  clear(turnId) {
+    const entry = this.turns.get(turnId);
+    if (entry && this.activeBySession.get(entry.sessionId) === turnId) this.activeBySession.delete(entry.sessionId);
+    if (entry && this.latestBySession.get(entry.sessionId) === turnId) this.latestBySession.delete(entry.sessionId);
+    this.turns.delete(turnId);
+    this.listeners.delete(turnId);
+  }
+
+  chunksAfter(turnId, afterIndex = -1) {
+    const entry = this.turns.get(turnId);
+    return entry ? entry.chunks.filter((chunk) => chunk.index > afterIndex) : [];
+  }
+
+  subscribe(turnId, callback) {
+    if (!this.listeners.has(turnId)) this.listeners.set(turnId, new Set());
+    const set = this.listeners.get(turnId);
+    set.add(callback);
+    return () => {
+      set.delete(callback);
+      if (set.size === 0) this.listeners.delete(turnId);
+    };
+  }
+
+  emit(turnId, chunk, entry) {
+    const set = this.listeners.get(turnId);
+    if (!set) return;
+    for (const callback of set) {
+      try { callback(chunk, entry); } catch {}
+    }
+  }
+}
+
+module.exports = { TurnStore };

package/runtime/scripts/chat-core/tool-display.js

@@ -0,0 +1,149 @@
+'use strict';
+
+function isRecord(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function trimText(value) {
+  if (typeof value !== 'string') return '';
+  return value.trim();
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    const text = trimText(value);
+    if (text) return text;
+  }
+  return '';
+}
+
+function compactText(value, max = 160) {
+  const text = trimText(String(value ?? '').replace(/\s+/g, ' '));
+  if (!text) return '';
+  return text.length > max ? `${text.slice(0, Math.max(0, max - 1)).trimEnd()}...` : text;
+}
+
+function withActionDescriptor(input, detail) {
+  const next = isRecord(input) ? { ...input } : {};
+  const cleanDetail = compactText(detail);
+  if (cleanDetail && typeof next.actionDescriptor !== 'string') {
+    next.actionDescriptor = cleanDetail;
+  }
+  return next;
+}
+
+function withOutputDescriptor(output, detail) {
+  if (!isRecord(output)) return output;
+  const cleanDetail = compactText(detail);
+  if (!cleanDetail || typeof output.actionDescriptor === 'string') return output;
+  return { ...output, actionDescriptor: cleanDetail };
+}
+
+function commandText(value) {
+  if (Array.isArray(value)) return value.map((part) => String(part)).join(' ').trim();
+  return trimText(value);
+}
+
+function summarizeToolRequest(toolName, input = {}, fallback = '') {
+  const args = isRecord(input) ? input : {};
+  const normalized = String(toolName || '').toLowerCase();
+  const explicit = firstString(
+    args.actionDescriptor,
+    args.description,
+    args.summary,
+    args.title,
+  );
+  if (explicit) return compactText(explicit);
+
+  if (normalized.includes('bash') || normalized.includes('command')) {
+    const command = commandText(args.command || args.rawCommand);
+    return command ? `$ ${command}` : compactText(fallback);
+  }
+
+  if (
+    normalized.includes('read') ||
+    normalized.includes('write') ||
+    normalized.includes('edit') ||
+    normalized.includes('file') ||
+    normalized.includes('path')
+  ) {
+    return compactText(firstString(args.path, args.filePath, args.file_path, args.file, fallback));
+  }
+
+  if (normalized.includes('grep') || normalized.includes('glob') || normalized.includes('search')) {
+    return compactText(firstString(args.query, args.pattern, args.url, args.path, fallback));
+  }
+
+  if (normalized.includes('fetch') || normalized.includes('web')) {
+    return compactText(firstString(args.url, args.query, fallback));
+  }
+
+  if (normalized.includes('mcp')) {
+    return compactText(firstString(args.toolName, args.name, args.serverName, fallback));
+  }
+
+  return compactText(firstString(
+    args.query,
+    args.prompt,
+    args.input,
+    args.url,
+    args.path,
+    args.filePath,
+    args.file_path,
+    args.pattern,
+    fallback,
+  ));
+}
+
+function summarizeToolOutput(output) {
+  if (output == null) return '';
+  if (typeof output === 'string') return summarizeTextOutput(output);
+  if (Array.isArray(output)) return output.length ? `${output.length} item${output.length === 1 ? '' : 's'}` : '';
+  if (!isRecord(output)) return compactText(output);
+
+  const explicit = firstString(output.actionDescriptor, output.summary, output.title, output.message, output.error);
+  if (explicit) return compactText(explicit);
+
+  const content = firstString(output.output, output.stdout, output.content, output.result, output.text);
+  if (content) return summarizeTextOutput(content);
+
+  if (Array.isArray(output.files)) {
+    return `${output.files.length} file${output.files.length === 1 ? '' : 's'}`;
+  }
+  if (Array.isArray(output.results)) {
+    return `${output.results.length} result${output.results.length === 1 ? '' : 's'}`;
+  }
+  if (Array.isArray(output.links)) {
+    return `${output.links.length} link${output.links.length === 1 ? '' : 's'}`;
+  }
+  return '';
+}
+
+function summarizeTextOutput(value) {
+  const lines = String(value || '')
+    .split(/\r?\n/)
+    .map((line) => compactText(line, 160))
+    .filter(Boolean);
+  if (lines[0]) return lines[0];
+  return '';
+}
+
+function stringifyResult(value) {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+module.exports = {
+  compactText,
+  isRecord,
+  stringifyResult,
+  summarizeToolOutput,
+  summarizeToolRequest,
+  withActionDescriptor,
+  withOutputDescriptor,
+};