[Init] Initial commit - NetMesh terminal manager

infrastructure/ai/harness/capabilityTools.ts

@@ -0,0 +1,788 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import type { ExecutorContext, NetcattyBridge } from '../cattyAgent/executor';
+import type { TerminalContextReadRange } from '../../../domain/terminalContextRead';
+import type { AIPermissionMode } from '../types';
+import type { WebSearchConfig } from '../types';
+import { isWebSearchReady } from '../types';
+import {
+  executeTerminalExecute,
+  executeWorkspaceGetInfo,
+  executeWorkspaceGetSessionInfo,
+  executeWebSearch,
+  executeUrlFetch,
+  type ToolDeps,
+  type ToolExecResult,
+} from '../shared/toolExecutors';
+import { reserveSessionSlot } from '../shared/sessionExecutionQueue';
+import { fitTerminalExecuteResultForModel } from './terminalCompression';
+import { fitLargeToolResultForModel } from './toolResultFitting';
+import { redactSecretsForModel } from './modelSecretRedaction';
+import {
+  globalTerminalMonitorGuard,
+  isStreamingMonitorCommand,
+} from './terminalMonitorGuard';
+import type { ToolOutputStore } from './toolOutputStore';
+import { TOOL_OUTPUT_READ_MAX_CHARS } from './toolOutputStore';
+import {
+  buildTerminalWriteFingerprint,
+  hashScopeKey,
+  hashToolResult,
+  previewToolResult,
+  type ToolResultDedup,
+} from './toolResultDedup';
+import cattyToolSpecs from './generated/cattyToolSpecs.json';
+import {
+  cattyToolContextSchema,
+  toolDepsFromContext,
+  type CattyToolContext,
+} from './cattyRuntimeContext';
+
+type FieldShape = {
+  type: string;
+  optional?: boolean;
+  description?: string;
+};
+
+type CattyToolSpec = {
+  capabilityId: string;
+  toolName: string;
+  rpcMethod: string | null;
+  localExecution?: boolean;
+  description: string;
+  inputShape: Record<string, FieldShape>;
+  policy: {
+    write: boolean;
+    bypassesApproval: boolean;
+  };
+};
+
+export type CattyToolsBundle = {
+  tools: Record<string, ReturnType<typeof tool>>;
+  toolsContext: Record<string, CattyToolContext>;
+};
+
+function buildZodObject(shape: Record<string, FieldShape>): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const entries: Record<string, z.ZodTypeAny> = {};
+  for (const [key, field] of Object.entries(shape)) {
+    let schema: z.ZodTypeAny = field.type === 'number' ? z.number() : z.string();
+    if (field.description) {
+      schema = schema.describe(field.description);
+    }
+    entries[key] = field.optional ? schema.optional() : schema;
+  }
+  return z.object(entries);
+}
+
+function unwrap<T>(r: ToolExecResult<T>): T | { error: string } {
+  if (r.ok === false) return { error: r.error };
+  return r.data;
+}
+
+async function invokeCapabilityRpc(
+  bridge: NetcattyBridge,
+  rpcMethod: string,
+  params: Record<string, unknown>,
+  chatSessionId?: string,
+): Promise<unknown> {
+  if (!bridge.aiCapability) {
+    return { error: 'Capability bridge is unavailable in this environment.' };
+  }
+  const result = await bridge.aiCapability(rpcMethod, params, chatSessionId);
+  if (result && typeof result === 'object' && 'ok' in result && (result as { ok: boolean }).ok === false) {
+    return { error: (result as { error?: string }).error || 'Capability call failed.' };
+  }
+  return result;
+}
+
+async function tryFetchHostEnvironment(
+  bridge: NetcattyBridge,
+  chatSessionId?: string,
+): Promise<Record<string, unknown> | null> {
+  if (!bridge.aiCapability || !chatSessionId) return null;
+  try {
+    const environment = await invokeCapabilityRpc(
+      bridge,
+      'netcatty/getContext',
+      {},
+      chatSessionId,
+    );
+    if (environment && typeof environment === 'object' && !('error' in environment)) {
+      return environment as Record<string, unknown>;
+    }
+  } catch {
+    // IPC failures must not block read-only harness tools.
+  }
+  return null;
+}
+
+function applyToolDedup(
+  toolName: string,
+  fingerprint: string,
+  result: unknown,
+  dedup?: ToolResultDedup,
+): unknown {
+  if (!dedup) return result;
+  const cached = dedup.check(fingerprint);
+  if (cached) {
+    return dedup.buildCachedNotice(cached);
+  }
+  dedup.remember(toolName, fingerprint, previewToolResult(result));
+  return result;
+}
+
+function fitCapabilityResultForModel(
+  result: unknown,
+  spec: CattyToolSpec,
+  chatSessionId?: string,
+  toolOutputStore?: ToolOutputStore,
+  args?: Record<string, unknown>,
+  toolResultDedup?: ToolResultDedup,
+): unknown {
+  if (spec.capabilityId === 'harness.tool_output.read') {
+    return result;
+  }
+
+  const resultRecord = result && typeof result === 'object'
+    ? result as Record<string, unknown>
+    : undefined;
+  const jobId = typeof args?.jobId === 'string'
+    ? args.jobId
+    : typeof resultRecord?.jobId === 'string' ? resultRecord.jobId : undefined;
+  const terminalSessionId = typeof args?.sessionId === 'string'
+    ? args.sessionId
+    : typeof resultRecord?.sessionId === 'string'
+      ? resultRecord.sessionId
+      : jobId ? toolResultDedup?.terminalSessionForJob(jobId) : undefined;
+
+  return fitLargeToolResultForModel({
+    result,
+    capabilityId: spec.capabilityId,
+    chatSessionId,
+    toolOutputStore,
+    terminalSessionId,
+    normalizeStrings: spec.capabilityId.startsWith('terminal.')
+      || spec.capabilityId === 'harness.terminal.read_context',
+  });
+}
+
+export function applyMonitorStopResult(
+  poll: Record<string, unknown>,
+  stopResult: unknown,
+  suppressedCount: number,
+): Record<string, unknown> {
+  const stopFailed = Boolean(
+    stopResult && typeof stopResult === 'object'
+    && (
+      (stopResult as { ok?: boolean }).ok === false
+      || (
+        typeof (stopResult as { error?: unknown }).error === 'string'
+        && (stopResult as { error: string }).error.trim().length > 0
+      )
+    ),
+  );
+  return stopFailed
+    ? {
+        ...poll,
+        output: `[automatic monitor stop failed after sustained overload; ${suppressedCount} batches were suppressed. The job may still be running; poll/stop it explicitly and narrow the command before continuing.]`,
+      }
+    : {
+        ...poll,
+        status: 'stopping',
+        output: `[monitor stop requested after sustained overload; ${suppressedCount} batches were suppressed. Narrow the command with grep/awk before restarting it.]`,
+      };
+}
+
+interface LocalExecutionContext {
+  deps: ToolDeps;
+  spec: CattyToolSpec;
+  args: Record<string, unknown>;
+  toolOutputStore?: ToolOutputStore;
+  toolResultDedup?: ToolResultDedup;
+  chatSessionId?: string;
+}
+
+async function executeLocalCattyCapability(ctx: LocalExecutionContext): Promise<unknown> {
+  const { deps, spec, args, toolOutputStore, toolResultDedup, chatSessionId } = ctx;
+  const resolveContext = () => (typeof deps.context === 'function' ? deps.context() : deps.context);
+
+  switch (spec.capabilityId) {
+    case 'harness.tool_output.read': {
+      const { handleId, mode, maxChars, offset, query } = args as {
+        handleId: string;
+        mode?: 'head' | 'tail' | 'full' | 'range' | 'search';
+        maxChars?: number;
+        offset?: number;
+        query?: string;
+      };
+      if (!toolOutputStore || !chatSessionId) {
+        return { error: 'Tool output store is unavailable.' };
+      }
+      const requestedChars = Math.min(
+        TOOL_OUTPUT_READ_MAX_CHARS,
+        typeof maxChars === 'number' && Number.isFinite(maxChars)
+          ? Math.max(1, Math.floor(maxChars))
+          : TOOL_OUTPUT_READ_MAX_CHARS,
+      );
+      const grantedChars = toolResultDedup
+        ? toolResultDedup.takeBudget('tool-output-read', requestedChars, TOOL_OUTPUT_READ_MAX_CHARS * 2)
+        : requestedChars;
+      if (grantedChars <= 0) {
+        return {
+          error: `This turn has reached its ${TOOL_OUTPUT_READ_MAX_CHARS * 2}-character saved-output read budget. Continue in the next turn or narrow the search.`,
+        };
+      }
+      const result = await toolOutputStore.readChunkAsync(
+        { handleId, mode, maxChars: grantedChars, offset, query },
+        chatSessionId,
+      );
+      if (result == null) {
+        return { error: `Handle "${handleId}" was not found for this chat session.` };
+      }
+      return { ...result, content: redactSecretsForModel(result.content) };
+    }
+    case 'harness.workspace.get_info': {
+      const scopeCtx = resolveContext();
+      const fingerprint = toolResultDedup?.fingerprintFor(
+        spec.toolName,
+        hashScopeKey([chatSessionId, scopeCtx.workspaceId, String(scopeCtx.sessions?.length ?? 0)]),
+      );
+      const local = executeWorkspaceGetInfo(deps);
+      if (local.ok === false) {
+        return unwrap(local);
+      }
+      let merged: unknown = local.data;
+      const environment = await tryFetchHostEnvironment(deps.bridge, chatSessionId);
+      if (environment) {
+        const hosts = Array.isArray(environment.hosts)
+          ? (environment.hosts as Array<Record<string, unknown>>)
+          : [];
+        const hostBySessionId = new Map(hosts.map((host) => [String(host.sessionId), host]));
+        merged = {
+          ...local.data,
+          sessions: local.data.sessions.map((session) => ({
+            ...session,
+            ...(hostBySessionId.get(session.sessionId) ?? {}),
+          })),
+          activePortForwardTunnels: environment.activePortForwardTunnels,
+        };
+      }
+      if (fingerprint) {
+        return applyToolDedup(spec.toolName, fingerprint, merged, toolResultDedup);
+      }
+      return merged;
+    }
+    case 'harness.workspace.get_session_info': {
+      const { sessionId } = args as { sessionId: string };
+      const local = executeWorkspaceGetSessionInfo(deps, { sessionId });
+      if (local.ok === false) {
+        return unwrap(local);
+      }
+      const environment = await tryFetchHostEnvironment(deps.bridge, chatSessionId);
+      if (environment) {
+        const hosts = Array.isArray(environment.hosts)
+          ? (environment.hosts as Array<Record<string, unknown>>)
+          : [];
+        const match = hosts.find((host) => String(host.sessionId) === sessionId);
+        if (match) {
+          return { ...local.data, ...match };
+        }
+      }
+      return local.data;
+    }
+    case 'harness.terminal.read_context': {
+      const scopeCtx = resolveContext();
+      const sessions = scopeCtx.sessions ?? [];
+      const requestedSessionId = typeof args.sessionId === 'string' && args.sessionId.trim()
+        ? args.sessionId.trim()
+        : undefined;
+      const sessionId = requestedSessionId
+        ?? (sessions.length === 1 ? sessions[0].sessionId : undefined);
+
+      if (!sessionId) {
+        return {
+          ok: false,
+          error: 'sessionId is required because the current AI scope contains multiple terminal sessions.',
+        };
+      }
+
+      const session = sessions.find((entry) => entry.sessionId === sessionId);
+      if (!session) {
+        return {
+          ok: false,
+          error: `Terminal session "${sessionId}" is not in the current AI scope.`,
+        };
+      }
+
+      if (!scopeCtx.readTerminalContext) {
+        return {
+          ok: false,
+          error: 'Terminal context reader is unavailable for this AI scope.',
+        };
+      }
+
+      const result = await scopeCtx.readTerminalContext({
+        sessionId,
+        range: typeof args.range === 'string' ? args.range as TerminalContextReadRange : undefined,
+        startLine: typeof args.startLine === 'number' ? args.startLine : undefined,
+        maxLines: typeof args.maxLines === 'number' ? args.maxLines : undefined,
+      });
+      if (result.ok === false) return result;
+      const normalizedResult = result;
+      const fingerprint = toolResultDedup?.fingerprintFor(
+        spec.toolName,
+        hashScopeKey([
+          sessionId,
+          String(normalizedResult.startLine),
+          String(normalizedResult.endLine),
+          normalizedResult.range,
+          hashToolResult(normalizedResult.content),
+        ]),
+      );
+      return fingerprint
+        ? applyToolDedup(spec.toolName, fingerprint, normalizedResult, toolResultDedup)
+        : normalizedResult;
+    }
+    case 'harness.web.search': {
+      const { query, maxResults } = args as { query: string; maxResults?: number };
+      return unwrap(await executeWebSearch(deps, { query, maxResults }));
+    }
+    case 'harness.url.fetch': {
+      const { url, maxLength } = args as { url: string; maxLength?: number };
+      const fingerprint = toolResultDedup?.fingerprintFor(spec.toolName, url);
+      const raw = unwrap(await executeUrlFetch(deps, { url, maxLength }));
+      if (fingerprint) {
+        return applyToolDedup(spec.toolName, fingerprint, raw, toolResultDedup);
+      }
+      return raw;
+    }
+    case 'harness.skill.run': {
+      const { executeSkillRun } = await import('./builtinSkillRunner');
+      const result = await executeSkillRun(deps, args, { chatSessionId });
+      return unwrap(result);
+    }
+    default:
+      return { error: `No local executor registered for "${spec.capabilityId}".` };
+  }
+}
+
+function resolveSessionQueueKey(
+  spec: CattyToolSpec,
+  args: Record<string, unknown>,
+  chatSessionId?: string,
+): string | null {
+  if (spec.capabilityId.startsWith('harness.') && !spec.policy.write) {
+    return null;
+  }
+
+  const sessionId = typeof args.sessionId === 'string' ? args.sessionId : undefined;
+  if (sessionId) {
+    return `${chatSessionId ?? 'global'}:${sessionId}`;
+  }
+  return `${chatSessionId ?? 'global'}:${spec.toolName}`;
+}
+
+export function resolveSessionQueueKeyForTests(
+  spec: Pick<CattyToolSpec, 'capabilityId' | 'toolName' | 'policy'>,
+  args: Record<string, unknown>,
+  chatSessionId?: string,
+): string | null {
+  return resolveSessionQueueKey(spec as CattyToolSpec, args, chatSessionId);
+}
+
+function createCatalogTool(spec: CattyToolSpec) {
+  const inputSchema = buildZodObject(spec.inputShape);
+
+  return tool({
+    description: spec.description,
+    inputSchema,
+    contextSchema: cattyToolContextSchema,
+    execute: async (args, { toolCallId: _toolCallId, abortSignal, context }) => {
+      const toolContext = context as CattyToolContext;
+      const deps = toolDepsFromContext(toolContext);
+      const { toolOutputStore, toolResultDedup } = toolContext;
+
+      const queueKey = resolveSessionQueueKey(
+        spec,
+        args as Record<string, unknown>,
+        deps.chatSessionId,
+      );
+      const slot = queueKey ? reserveSessionSlot(queueKey) : null;
+
+      try {
+        const result = await (async () => {
+        if (abortSignal?.aborted) {
+          return { error: 'Tool call cancelled before it could start.' };
+        }
+
+        await slot?.ready;
+
+        if (spec.capabilityId === 'terminal.execute') {
+          const { sessionId: sid, command } = args as { sessionId: string; command: string };
+          const writeFingerprint = buildTerminalWriteFingerprint(
+            'terminal_execute',
+            deps.chatSessionId,
+            { sessionId: sid, command },
+          );
+          const replay = writeFingerprint
+            ? toolResultDedup?.replayCompletedWrite(writeFingerprint)
+            : undefined;
+          if (replay !== undefined) {
+            return {
+              ...(typeof replay === 'object' && replay !== null ? replay : { result: replay }),
+              replayedCompletedResult: true,
+              note: 'The command already executed before request compaction; its recorded result was replayed and the command was not executed again.',
+            };
+          }
+          const cancelOnAbort = () => {
+            if (deps.chatSessionId) {
+              void deps.bridge.aiCattyCancelExec?.(deps.chatSessionId);
+            }
+          };
+          abortSignal?.addEventListener('abort', cancelOnAbort, { once: true });
+          try {
+            const result = await executeTerminalExecute(deps, { sessionId: sid, command });
+            if (result.ok === false) {
+              if (!result.data) return unwrap(result);
+              const fittedFailure = {
+                error: fitLargeToolResultForModel({
+                  result: result.error,
+                  capabilityId: 'terminal.execute.error',
+                  chatSessionId: deps.chatSessionId,
+                  toolOutputStore,
+                  terminalSessionId: sid,
+                  normalizeStrings: true,
+                }),
+                ...fitTerminalExecuteResultForModel({
+                  ...result.data,
+                  command,
+                  sessionId: sid,
+                }, {
+                  chatSessionId: deps.chatSessionId,
+                  toolOutputStore,
+                }),
+              };
+              if (writeFingerprint) toolResultDedup?.rememberCompletedWrite(writeFingerprint, fittedFailure);
+              return fittedFailure;
+            }
+            const fitted = fitTerminalExecuteResultForModel({
+              ...result.data,
+              command,
+              sessionId: sid,
+            }, {
+              chatSessionId: deps.chatSessionId,
+              toolOutputStore,
+            });
+            if (writeFingerprint) toolResultDedup?.rememberCompletedWrite(writeFingerprint, fitted);
+            return fitted;
+          } finally {
+            abortSignal?.removeEventListener('abort', cancelOnAbort);
+          }
+        }
+
+        if (spec.localExecution || spec.capabilityId.startsWith('harness.')) {
+          const result = await executeLocalCattyCapability({
+            deps,
+            spec,
+            args: args as Record<string, unknown>,
+            toolOutputStore,
+            toolResultDedup,
+            chatSessionId: deps.chatSessionId,
+          });
+          return fitCapabilityResultForModel(
+            result,
+            spec,
+            deps.chatSessionId,
+            toolOutputStore,
+            args as Record<string, unknown>,
+            toolResultDedup,
+          );
+        }
+
+        if (!spec.rpcMethod) {
+          return { error: `Capability "${spec.capabilityId}" has no RPC binding.` };
+        }
+
+        const terminalStartFingerprint = spec.capabilityId === 'terminal.start'
+          ? buildTerminalWriteFingerprint(
+              'terminal_start',
+              deps.chatSessionId,
+              args as { sessionId?: unknown; command?: unknown },
+            )
+          : undefined;
+        const terminalStartReplay = terminalStartFingerprint
+          ? toolResultDedup?.replayCompletedWrite(terminalStartFingerprint)
+          : undefined;
+        if (terminalStartReplay !== undefined) {
+          return {
+            ...(typeof terminalStartReplay === 'object' && terminalStartReplay !== null
+              ? terminalStartReplay
+              : { result: terminalStartReplay }),
+            replayedCompletedResult: true,
+            note: 'The background command already started before request compaction; its recorded job was replayed and no second job was created.',
+          };
+        }
+
+        let raw = await invokeCapabilityRpc(
+          deps.bridge,
+          spec.rpcMethod,
+          args as Record<string, unknown>,
+          deps.chatSessionId,
+        );
+        if (
+          spec.capabilityId === 'terminal.start'
+          && raw && typeof raw === 'object'
+          && typeof (raw as { jobId?: unknown }).jobId === 'string'
+          && typeof (args as { sessionId?: unknown }).sessionId === 'string'
+        ) {
+          toolResultDedup?.rememberTerminalJobSession(
+            (raw as { jobId: string }).jobId,
+            (args as { sessionId: string }).sessionId,
+          );
+        }
+
+        if (
+          spec.capabilityId === 'terminal.poll'
+          && raw
+          && typeof raw === 'object'
+          && (raw as { ok?: boolean }).ok !== false
+        ) {
+          let poll = raw as Record<string, unknown>;
+          const monitorKey = `${deps.chatSessionId ?? 'global'}:${String(poll.jobId ?? args.jobId ?? '')}`;
+          if (
+            isStreamingMonitorCommand(poll.command)
+            && typeof poll.output === 'string'
+            && poll.output.trim().length > 0
+          ) {
+            const guarded = globalTerminalMonitorGuard.process(monitorKey, poll.output);
+            if (guarded.action === 'stop') {
+              const stopResult = await invokeCapabilityRpc(
+                deps.bridge,
+                'netcatty/jobStop',
+                { jobId: poll.jobId ?? args.jobId },
+                deps.chatSessionId,
+              );
+              poll = applyMonitorStopResult(poll, stopResult, guarded.suppressedCount);
+            } else if (guarded.action === 'suppress') {
+              poll = {
+                ...poll,
+                output: `[monitor batch suppressed by rate limit; suppressed=${guarded.suppressedCount}]`,
+              };
+            } else {
+              let output = guarded.content;
+              if (guarded.sourceTruncated && toolOutputStore && deps.chatSessionId) {
+                const jobId = String(poll.jobId ?? args.jobId ?? '');
+                const handle = toolOutputStore.store({
+                  chatSessionId: deps.chatSessionId,
+                  capabilityId: 'terminal.poll.monitor-batch',
+                  content: poll.output,
+                  sessionId: jobId ? toolResultDedup?.terminalSessionForJob(jobId) : undefined,
+                });
+                output += [
+                  '',
+                  `[monitor batch archived before shortening: rawChars=${poll.output.length} handleId=${handle.id}]`,
+                  'Use tool_output_read with this handleId to search/read omitted details; the terminal nextOffset already advances past the raw batch.',
+                  'This saved output is available only until the app closes. Read this handle before closing the app.',
+                ].join('\n');
+              }
+              poll = { ...poll, output };
+            }
+          }
+          if (poll.status !== 'running' && poll.status !== 'stopping') {
+            globalTerminalMonitorGuard.clear(monitorKey);
+          }
+          raw = poll;
+          const fingerprint = toolResultDedup?.fingerprintFor(
+            spec.toolName,
+            hashScopeKey([
+              String(poll.jobId ?? args.jobId ?? ''),
+              String(poll.outputBaseOffset ?? ''),
+              String(poll.nextOffset ?? ''),
+              String(poll.status ?? ''),
+              hashToolResult(poll.output ?? ''),
+            ]),
+          );
+          if (fingerprint) {
+            return fitCapabilityResultForModel(
+              applyToolDedup(spec.toolName, fingerprint, poll, toolResultDedup),
+              spec,
+              deps.chatSessionId,
+              toolOutputStore,
+              args as Record<string, unknown>,
+              toolResultDedup,
+            );
+          }
+        }
+
+        if (spec.toolName === 'get_environment' || spec.capabilityId === 'session.environment') {
+          const ctx = typeof deps.context === 'function' ? deps.context() : deps.context;
+          const fingerprint = toolResultDedup?.fingerprintFor(
+            spec.toolName,
+            hashScopeKey([deps.chatSessionId, ctx.workspaceId, String(ctx.sessions?.length ?? 0)]),
+          );
+          if (fingerprint) {
+            return fitCapabilityResultForModel(
+              applyToolDedup(spec.toolName, fingerprint, raw, toolResultDedup),
+              spec,
+              deps.chatSessionId,
+              toolOutputStore,
+              args as Record<string, unknown>,
+              toolResultDedup,
+            );
+          }
+        }
+
+        if (spec.capabilityId.includes('sftp') && spec.capabilityId.includes('read')) {
+          const { sessionId: sid, path } = args as { sessionId?: string; path?: string };
+          const fingerprint = toolResultDedup?.fingerprintFor(
+            spec.toolName,
+            hashScopeKey([sid, path]),
+          );
+          if (fingerprint) {
+            return fitCapabilityResultForModel(
+              applyToolDedup(spec.toolName, fingerprint, raw, toolResultDedup),
+              spec,
+              deps.chatSessionId,
+              toolOutputStore,
+              args as Record<string, unknown>,
+              toolResultDedup,
+            );
+          }
+
+          if (
+            raw
+            && typeof raw === 'object'
+            && 'content' in raw
+            && toolOutputStore
+            && deps.chatSessionId
+          ) {
+            const content = String((raw as { content?: string }).content ?? '');
+            const MAX_LIVE_SFTP_READ_CHARS = 24_000;
+            if (content.length > MAX_LIVE_SFTP_READ_CHARS) {
+              const handle = toolOutputStore.store({
+                chatSessionId: deps.chatSessionId,
+                capabilityId: spec.capabilityId,
+                content,
+                sessionId: sid,
+              });
+              return {
+                ok: true,
+                path: (raw as { path?: string }).path ?? path,
+                preview: handle.preview,
+                totalChars: handle.totalChars,
+                handleId: handle.id,
+                note: 'Full file content is available only until the app closes. Use tool_output_read now.',
+              };
+            }
+          }
+        }
+
+        const fittedRaw = fitCapabilityResultForModel(
+          raw,
+          spec,
+          deps.chatSessionId,
+          toolOutputStore,
+          args as Record<string, unknown>,
+          toolResultDedup,
+        );
+        if (
+          terminalStartFingerprint
+          && raw && typeof raw === 'object'
+          && (raw as { ok?: boolean }).ok !== false
+          && typeof (raw as { jobId?: unknown }).jobId === 'string'
+        ) {
+          toolResultDedup?.rememberCompletedWrite(terminalStartFingerprint, fittedRaw);
+        }
+        return fittedRaw;
+        })();
+        if (toolOutputStore && deps.chatSessionId) {
+          await toolOutputStore.flush(deps.chatSessionId);
+          return toolOutputStore.resolveRestartPersistenceNotices(result, deps.chatSessionId);
+        }
+        return result;
+      } finally {
+        slot?.release();
+      }
+    },
+  });
+}
+
+export function buildCattyToolContext(input: {
+  bridge: NetcattyBridge;
+  context: ToolDeps['context'];
+  commandBlocklist?: string[];
+  permissionMode: AIPermissionMode;
+  webSearchConfig?: WebSearchConfig;
+  chatSessionId?: string;
+  toolOutputStore?: ToolOutputStore;
+  toolResultDedup?: ToolResultDedup;
+}): CattyToolContext {
+  return {
+    bridge: input.bridge,
+    chatSessionId: input.chatSessionId,
+    permissionMode: input.permissionMode,
+    commandBlocklist: input.commandBlocklist,
+    webSearchConfig: input.webSearchConfig,
+    getExecutorContext: typeof input.context === 'function'
+      ? input.context as () => ExecutorContext
+      : () => input.context as ExecutorContext,
+    toolOutputStore: input.toolOutputStore,
+    toolResultDedup: input.toolResultDedup,
+  };
+}
+
+export function createCattyToolsFromCatalog(
+  bridge: NetcattyBridge,
+  context: ToolDeps['context'],
+  commandBlocklist?: string[],
+  permissionMode: AIPermissionMode = 'confirm',
+  webSearchConfig?: WebSearchConfig,
+  chatSessionId?: string,
+  toolOutputStore?: ToolOutputStore,
+  toolResultDedup?: ToolResultDedup,
+): CattyToolsBundle {
+  const sharedContext = buildCattyToolContext({
+    bridge,
+    context,
+    commandBlocklist,
+    permissionMode,
+    webSearchConfig,
+    chatSessionId,
+    toolOutputStore,
+    toolResultDedup,
+  });
+
+  const catalogTools: Record<string, ReturnType<typeof tool>> = {};
+  const toolsContext: Record<string, CattyToolContext> = {};
+
+  for (const rawSpec of cattyToolSpecs as CattyToolSpec[]) {
+    if (rawSpec.capabilityId === 'harness.web.search' && !isWebSearchReady(webSearchConfig)) {
+      continue;
+    }
+    catalogTools[rawSpec.toolName] = createCatalogTool(rawSpec);
+    toolsContext[rawSpec.toolName] = sharedContext;
+  }
+
+  return { tools: catalogTools, toolsContext };
+}
+
+/** Test helper: attach shared context when calling tool.execute directly. */
+export function withCattyToolContext<T extends { execute: (...args: never[]) => unknown }>(
+  toolInstance: T,
+  context: CattyToolContext,
+  toolCallId = 'test-call',
+): T {
+  const original = toolInstance.execute.bind(toolInstance);
+  return {
+    ...toolInstance,
+    execute: (input: Parameters<T['execute']>[0], options?: Partial<Parameters<T['execute']>[1]>) =>
+      original(input, {
+        toolCallId,
+        messages: [],
+        ...options,
+        context,
+      } as Parameters<T['execute']>[1]),
+  } as T;
+}
+
+export { tryFetchHostEnvironment };