@graphorin/agent 0.6.1 → 0.7.0

package/src/runtime/tool-wiring.ts

@@ -0,0 +1,218 @@
+/**
+ * Warm-up tool wiring for the agent runtime: registration of the
+ * built-in `tool_search` / `read_result` tools, code-mode meta-tool
+ * wiring, result-reader composition, and the `tool_search` promotion
+ * fold. Extracted verbatim from `factory.ts` (issue #23).
+ *
+ * @packageDocumentation
+ */
+
+import type { Tool } from '@graphorin/core';
+import { createReadResultTool, createToolSearchTool } from '@graphorin/tools/built-in';
+import {
+  type CodeExecuteBridge,
+  createCodeExecuteTool,
+  createCodeSearchTool,
+  type ProjectableTool,
+  projectToolApi,
+} from '@graphorin/tools/code-mode';
+import type { ToolExecutor } from '@graphorin/tools/executor';
+import type { ToolRegistry } from '@graphorin/tools/registry';
+import type { ResultReader } from '@graphorin/tools/result';
+import { newId } from '../internal/ids.js';
+
+/** The built-in deferred-discovery tool's stable name (WI-05 / P0-3). */
+export const TOOL_SEARCH_NAME = 'tool_search';
+
+/**
+ * Register the built-in `tool_search` into `registry` when - and only
+ * when - the registry holds at least one deferred tool
+ * (`defer_loading: true`). `tool_search` is itself eager (so it is
+ * always advertised while a deferred pool exists) and resolvable by the
+ * executor like any other tool, so a model can both *see* it in the
+ * per-step catalogue and *call* it.
+ *
+ * No-op when nothing defers (zero overhead - the tool never appears) or
+ * when a user tool already occupies the name (the user's tool wins; we
+ * never clobber it). Because deferral is decided at registration time
+ * (`normaliseTool`), the deferred set is fixed for the life of the
+ * registry - this runs once per registry, not per step.
+ */
+export function registerToolSearch(
+  registry: ToolRegistry,
+  availability?: 'next-step' | 'next-run',
+): void {
+  if (registry.listDeferred().length === 0) return;
+  if (registry.get(TOOL_SEARCH_NAME) !== undefined) return;
+  registry.register(
+    createToolSearchTool({ registry, ...(availability !== undefined ? { availability } : {}) }),
+    {
+      kind: 'built-in',
+      subsystem: 'tool-discovery',
+    },
+  );
+}
+
+/** The built-in result-handle reader tool's stable name (WI-10 / P1-4). */
+export const READ_RESULT_NAME = 'read_result';
+
+/**
+ * Register the built-in `read_result` into `registry` when at least one
+ * registered tool opts into the `'spill-to-file'` truncation strategy
+ * (the sole producer of spill handles today) - or when `force` is set,
+ * which the agent passes when an operator wires external result readers
+ * (e.g. an MCP `resource_link` reader; WI-13). The tool is eager, so it
+ * is advertised alongside the producing tool and the model can fetch a
+ * handle back on demand instead of inlining the full blob. No-op when
+ * nothing produces handles (zero overhead) or when a user tool already
+ * occupies the name (the user's tool wins).
+ */
+export function registerReadResult(
+  registry: ToolRegistry,
+  reader: ResultReader,
+  opts?: { readonly force?: boolean },
+): void {
+  if (
+    opts?.force !== true &&
+    !registry.list().some((entry) => entry.truncationStrategy === 'spill-to-file')
+  ) {
+    return;
+  }
+  if (registry.get(READ_RESULT_NAME) !== undefined) return;
+  registry.register(createReadResultTool({ reader }), {
+    kind: 'built-in',
+    subsystem: 'result-handle',
+  });
+}
+
+/**
+ * Compose result readers into one that tries each in order, returning
+ * the first that resolves the handle (WI-13). The spill-file reader is
+ * placed first so `graphorin-spill:` handles resolve locally; operator
+ * readers (e.g. an MCP resource reader) resolve the rest. Each reader
+ * rejects handles it does not own, so resolution falls through cleanly.
+ */
+export function composeResultReaders(readers: ReadonlyArray<ResultReader>): ResultReader {
+  return {
+    async read(uri, range) {
+      let lastError: unknown;
+      for (const r of readers) {
+        try {
+          return await r.read(uri, range);
+        } catch (err) {
+          lastError = err;
+        }
+      }
+      throw lastError instanceof Error
+        ? lastError
+        : new Error(`No result reader resolved handle ${JSON.stringify(uri)}.`);
+    },
+  };
+}
+
+/** The code-mode meta-tools' stable names (WI-11 / P1-2). */
+export const CODE_EXECUTE_NAME = 'code_execute';
+export const CODE_SEARCH_NAME = 'code_search';
+
+/** Structural check: is this tool approval-gated (static or predicate form)? */
+export const isApprovalGated = (t: { readonly needsApproval?: unknown }): boolean =>
+  t.needsApproval === true || typeof t.needsApproval === 'function';
+
+/**
+ * Wire code-mode (P1-2) into `registry`: register the `code_search` /
+ * `code_execute` meta-tools and return them as the tools to advertise in
+ * place of the full catalogue. The model reaches every other tool through
+ * `code_execute`, whose in-script `tools.<name>(args)` calls route back
+ * through `quietExecutor.executeOne(...)` under the calling step's
+ * `runContext` - so per-tool ACL / sanitization / truncation still apply,
+ * exactly as in direct mode. `quietExecutor` carries no `streamingSink`,
+ * so the inner calls do not interleave `tool.execute.*` events into the
+ * outer stream.
+ *
+ * Excluded from the code API (`reservedNames`): the meta-tools, the
+ * discovery / handle built-ins, handoff tools (which stay first-class
+ * provider tools), and - supplied by the caller - any approval-gated
+ * tool, since code-mode has no durable-HITL path to suspend mid-script.
+ *
+ * Returns `[]` (registering nothing) when no real tool is exposable.
+ */
+export function registerCodeMode(
+  registry: ToolRegistry,
+  quietExecutor: ToolExecutor,
+  reservedNames: ReadonlySet<string>,
+  getRunCapability?: () => 'read-only' | undefined,
+): ReadonlyArray<Tool<unknown, unknown, unknown>> {
+  if (registry.get(CODE_EXECUTE_NAME) !== undefined) return []; // already wired
+  const codeTools = registry
+    .list()
+    .filter((entry) => !reservedNames.has(entry.name) && !isApprovalGated(entry));
+  if (codeTools.length === 0) return [];
+
+  // TL-8: gated tools cannot suspend for HITL mid-script, so they are
+  // excluded from the code API - but VISIBLY: they appear in the
+  // catalogue/search with a call-directly marker, and a bridged call
+  // fails with the same hint instead of an opaque unknown-tool error.
+  const approvalGatedTools = registry
+    .list()
+    .filter((entry) => !reservedNames.has(entry.name) && isApprovalGated(entry))
+    .map((entry) => entry.name);
+  const approvalGatedSet = new Set(approvalGatedTools);
+
+  const allowedTools = [...codeTools.map((entry) => entry.name), ...approvalGatedTools];
+  const allowedSet = new Set(codeTools.map((entry) => entry.name));
+  const eagerProjectable = codeTools.filter(
+    (entry) => entry.__effectiveDeferLoading !== true,
+  ) as unknown as ReadonlyArray<ProjectableTool>;
+  const projection = projectToolApi(eagerProjectable);
+
+  const executeTool: CodeExecuteBridge = async (call, ctx) => {
+    if (approvalGatedSet.has(call.name)) {
+      throw new Error(
+        `${call.name} requires human approval and cannot run inside code_execute - call it directly as a standalone tool call so the run can suspend for the approval.`,
+      );
+    }
+    const runCapability = getRunCapability?.();
+    const completed = await quietExecutor.executeOne({
+      call: { toolCallId: newId('codecall'), toolName: call.name, args: call.args },
+      runContext: ctx.runContext,
+      stepNumber: ctx.runContext.stepNumber,
+      // D2: in-script calls inherit the active run's capability.
+      ...(runCapability !== undefined ? { capability: runCapability } : {}),
+    });
+    const { outcome } = completed;
+    if ('kind' in outcome) throw new Error(`${call.name}: ${outcome.message}`);
+    return outcome.output;
+  };
+
+  const codeSearch = createCodeSearchTool({
+    projection,
+    approvalGatedTools,
+    searchDeferred: async (query, k) =>
+      (await registry.searchDeferred(query, k)).filter((match) => allowedSet.has(match.name)),
+  });
+  const codeExecute = createCodeExecuteTool({
+    projection,
+    allowedTools,
+    executeTool,
+    approvalGatedTools,
+  });
+  registry.register(codeSearch, { kind: 'built-in', subsystem: 'code-mode' });
+  registry.register(codeExecute, { kind: 'built-in', subsystem: 'code-mode' });
+  return [codeSearch, codeExecute] as ReadonlyArray<Tool<unknown, unknown, unknown>>;
+}
+
+/**
+ * Fold a completed `tool_search` result into the per-run promotion set:
+ * every matched tool name becomes advertised (and thus callable) on the
+ * next step. Tolerant of unexpected shapes (e.g. a user-shadowed
+ * `tool_search`) - only string `name`s inside a `matches` array promote.
+ */
+export function recordToolSearchPromotions(output: unknown, promoted: Set<string>): void {
+  if (typeof output !== 'object' || output === null) return;
+  const matches = (output as { readonly matches?: unknown }).matches;
+  if (!Array.isArray(matches)) return;
+  for (const match of matches) {
+    const name = (match as { readonly name?: unknown } | null)?.name;
+    if (typeof name === 'string') promoted.add(name);
+  }
+}

package/src/testing/replay-provider.ts

@@ -0,0 +1,121 @@
+/**
+ * `createReplayProvider(state)` - a Provider that replays the model
+ * responses journaled on `RunState.steps[].providerResponse` (C3, opt-in
+ * via `AgentConfig.recordProviderResponses`). Re-running the same input
+ * against a replay provider reproduces the original run deterministically
+ * with zero live model calls - the mocked-completion harness that gives
+ * agent loops reproducible integration tests.
+ *
+ * The provider is strict by design: it throws when the state carries no
+ * journaled responses, and emits an error event when the replayed run
+ * asks for more steps than were recorded (a divergence, not a fixture
+ * gap - fail loudly instead of hallucinating a response).
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  Provider,
+  ProviderEvent,
+  ProviderRequest,
+  ProviderResponse,
+  RunState,
+  RunStepProviderResponse,
+} from '@graphorin/core';
+
+/** Options for {@link createReplayProvider}. */
+export interface ReplayProviderOptions {
+  /** Provider name for spans/logs. Default `'replay'`. */
+  readonly name?: string;
+}
+
+/**
+ * Build a Provider that serves the journaled step responses in order.
+ *
+ * @stable
+ */
+export function createReplayProvider(
+  state: RunState,
+  options: ReplayProviderOptions = {},
+): Provider {
+  const recorded: RunStepProviderResponse[] = [];
+  for (const step of state.steps) {
+    if (step.providerResponse !== undefined) recorded.push(step.providerResponse);
+  }
+  if (recorded.length === 0) {
+    throw new TypeError(
+      'createReplayProvider: RunState carries no journaled provider responses - ' +
+        'run the original agent with recordProviderResponses: true.',
+    );
+  }
+  let cursor = 0;
+  const modelId = recorded[0]?.modelId ?? 'replay';
+
+  function nextRecorded(): RunStepProviderResponse | undefined {
+    const entry = recorded[cursor];
+    cursor += 1;
+    return entry;
+  }
+
+  return {
+    name: options.name ?? 'replay',
+    modelId,
+    capabilities: {
+      streaming: true,
+      toolCalling: true,
+      parallelToolCalls: true,
+      multimodal: false,
+      structuredOutput: true,
+      reasoning: false,
+      contextWindow: 1_000_000,
+      maxOutput: 1_000_000,
+    },
+    async *stream(_req: ProviderRequest): AsyncIterable<ProviderEvent> {
+      const entry = nextRecorded();
+      if (entry === undefined) {
+        yield {
+          type: 'error',
+          error: {
+            kind: 'unknown',
+            message: `replay exhausted after ${recorded.length} recorded step(s) - the replayed run diverged from the original`,
+          },
+        };
+        return;
+      }
+      yield { type: 'stream-start', metadata: { providerName: 'replay', modelId: entry.modelId } };
+      if (entry.text !== undefined && entry.text.length > 0) {
+        yield { type: 'text-delta', delta: entry.text };
+      }
+      for (const call of entry.toolCalls ?? []) {
+        yield { type: 'tool-call-start', toolCallId: call.toolCallId, toolName: call.toolName };
+        yield {
+          type: 'tool-call-input-delta',
+          toolCallId: call.toolCallId,
+          argsDelta: JSON.stringify(call.args),
+        };
+        yield { type: 'tool-call-end', toolCallId: call.toolCallId, finalArgs: call.args };
+      }
+      yield {
+        type: 'finish',
+        finishReason: (entry.toolCalls?.length ?? 0) > 0 ? 'tool-calls' : 'stop',
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      };
+    },
+    async generate(_req: ProviderRequest): Promise<ProviderResponse> {
+      const entry = nextRecorded();
+      if (entry === undefined) {
+        throw new Error(
+          `replay exhausted after ${recorded.length} recorded step(s) - the replayed run diverged from the original`,
+        );
+      }
+      return {
+        ...(entry.text !== undefined ? { text: entry.text } : {}),
+        ...(entry.toolCalls !== undefined && entry.toolCalls.length > 0
+          ? { toolCalls: entry.toolCalls.map((c) => ({ ...c })) }
+          : {}),
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        finishReason: (entry.toolCalls?.length ?? 0) > 0 ? 'tool-calls' : 'stop',
+      };
+    },
+  };
+}