@graphorin/agent 0.6.0 → 0.7.0

package/src/runtime/dispatch.ts

@@ -0,0 +1,183 @@
+/**
+ * Tool-batch dispatch bridging for the agent runtime: routes a batch of
+ * (non-handoff) tool calls through the shared `@graphorin/tools`
+ * executor and surfaces the outcomes as the long-standing
+ * `tool.execute.*` agent events + tool messages (R10), including the
+ * WI-10 result-handle rendering and the WI-05 `tool_search` promotion
+ * fold. Extracted verbatim from `factory.ts` (issue #23); the former
+ * run-loop closure now takes an explicit {@link DispatchRunEnv}.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AgentEvent,
+  CompletedToolCall,
+  Message,
+  RunContext,
+  RunState,
+  ToolCall,
+} from '@graphorin/core';
+import type { ToolExecutor } from '@graphorin/tools/executor';
+import type { CausalityMonitor } from '../lateral-leak/causality-monitor.js';
+import { createExecutorEventBridge, type ExecutorEventBridge } from '../tooling/adapters.js';
+import { renderToolErrorMessage } from './messages.js';
+import type { MutableRunState } from './run-input.js';
+import { recordToolSearchPromotions, TOOL_SEARCH_NAME } from './tool-wiring.js';
+
+/**
+ * Shape of the run-bound `dispatchBatch` wrapper the factory threads
+ * into the resume-dispatch and tool-call-walk modules, so their call
+ * sites read exactly as the former in-loop closure calls did.
+ */
+export type DispatchBatchFn<TDeps, TOutput> = (
+  calls: ReadonlyArray<ToolCall>,
+  executor: ToolExecutor,
+  runContext: RunContext<TDeps>,
+  stepNum: number,
+  dispatchOpts?: { readonly disableRepair?: boolean },
+) => AsyncGenerator<AgentEvent<TOutput>, void, void>;
+
+/**
+ * The run-scoped context a batch dispatch operates on. Field names
+ * mirror the run-loop locals the former closure captured; the
+ * executor-bridge slot is the shared mutable cell the warm-up
+ * streaming sink reads while a batch is in flight.
+ */
+export interface DispatchRunEnv {
+  readonly state: MutableRunState & RunState;
+  readonly messages: Message[];
+  readonly causalityMonitor: CausalityMonitor | undefined;
+  readonly promotedDeferred: Set<string>;
+  readonly activeRunCapability: 'read-only' | undefined;
+  readonly executorBridgeSlot: { current: ExecutorEventBridge | undefined };
+}
+
+/**
+ * Dispatch a batch of (non-handoff) tool calls through the
+ * {@link ToolExecutor} and surface the results as `AgentEvent`s.
+ *
+ * The agent owns the `tool.execute.start` / `.end` / `.error`
+ * lifecycle (derived deterministically from the returned
+ * {@link CompletedToolCall} outcomes) so every outcome kind -
+ * success, unknown-tool, invalid-input, sanitization-blocked,
+ * execution error - yields a consistent event and tool message,
+ * preserving the pre-WI-03 stream shape (R10). The executor's
+ * genuinely-live streaming events (`tool.execute.progress` /
+ * `.partial`, emitted only by streaming-hint tools) are bridged
+ * through Adapter E while the batch runs and are purely additive.
+ *
+ * Parallelism (WI-04): the executor runs independent calls in this
+ * batch concurrently, bounded by `maxParallelTools`. `tool.execute.start`
+ * is emitted up-front in call order and `.end` / `.error` after the
+ * batch settles, also in call order - so result mapping and tool-message
+ * history are deterministic regardless of which call finishes first,
+ * while `.progress` / `.partial` events for concurrent calls interleave
+ * (keyed by `toolCallId`). Tools declaring `executionMode: 'sequential'`
+ * are serialised by the executor and never overlap.
+ */
+export async function* dispatchToolBatch<TDeps, TOutput>(
+  env: DispatchRunEnv,
+  calls: ReadonlyArray<ToolCall>,
+  executor: ToolExecutor,
+  runContext: RunContext<TDeps>,
+  stepNum: number,
+  dispatchOpts: { readonly disableRepair?: boolean } = {},
+): AsyncGenerator<AgentEvent<TOutput>, void, void> {
+  const { state, messages, causalityMonitor, promotedDeferred, activeRunCapability } = env;
+  const { executorBridgeSlot } = env;
+  if (calls.length === 0) return;
+  for (const call of calls) {
+    // W-049: toolName duplicated for subscriber convenience.
+    yield { type: 'tool.execute.start', toolCallId: call.toolCallId, toolName: call.toolName };
+  }
+
+  const bridge = createExecutorEventBridge();
+  executorBridgeSlot.current = bridge;
+  const resultsPromise = executor.executeBatch({
+    calls,
+    runContext,
+    stepNumber: stepNum,
+    ...(dispatchOpts.disableRepair !== undefined
+      ? { disableRepair: dispatchOpts.disableRepair }
+      : {}),
+    // D2: the run's capability restriction rides every batch.
+    ...(activeRunCapability !== undefined ? { capability: activeRunCapability } : {}),
+  });
+  // Close the bridge once the batch settles so `drain()` ends; the
+  // executor catches per-call errors, so the batch never rejects.
+  const closeOnSettle = resultsPromise.then(
+    () => bridge.close(),
+    () => bridge.close(),
+  );
+  for await (const event of bridge.drain()) {
+    if (event.type === 'tool.execute.progress' || event.type === 'tool.execute.partial') {
+      yield event as AgentEvent<TOutput>;
+    }
+  }
+  await closeOnSettle;
+  executorBridgeSlot.current = undefined;
+
+  const completed = await resultsPromise;
+  const byCallId = new Map(completed.map((c) => [c.outcome.toolCallId, c]));
+  const stepEntry = state.steps[state.steps.length - 1];
+  for (const call of calls) {
+    const result = byCallId.get(call.toolCallId);
+    if (result === undefined) continue;
+    if (stepEntry !== undefined) {
+      (stepEntry.toolCalls as CompletedToolCall[]).push(result);
+    }
+    const outcome = result.outcome;
+    if ('kind' in outcome) {
+      yield {
+        type: 'tool.execute.error',
+        toolCallId: call.toolCallId,
+        toolName: call.toolName,
+        error: outcome,
+      };
+      const text = renderToolErrorMessage(outcome);
+      messages.push({ role: 'tool', toolCallId: call.toolCallId, content: text });
+      state.messages.push({ role: 'tool', toolCallId: call.toolCallId, content: text });
+      causalityMonitor?.recordCall(`tool.error:${call.toolName}`);
+    } else {
+      const output = outcome.output;
+      yield {
+        type: 'tool.execute.end',
+        toolCallId: call.toolCallId,
+        toolName: call.toolName,
+        result: output,
+        durationMs: outcome.durationMs,
+      };
+      // WI-10 (P1-4): when the result spilled to a handle, inline only
+      // the bounded preview plus a retrieval hint so the full blob never
+      // enters the context window - the model fetches the rest on demand
+      // via `read_result`. Inlined results serialise exactly as before
+      // (preserves the happy-path message contract, R10).
+      const handle = outcome.resultHandle;
+      const rendered =
+        handle !== undefined
+          ? `${handle.preview}\n\n[Full result${
+              handle.bytes !== undefined ? ` (${handle.bytes} bytes)` : ''
+            } stored behind a handle. Call read_result with handle ${JSON.stringify(
+              handle.uri,
+            )} to retrieve it - optionally narrow with offset/length (bytes) or startLine/endLine.]`
+          : typeof output === 'string'
+            ? output
+            : JSON.stringify(output);
+      // C3 (ACI): an empty body reads as a glitch to models; say
+      // explicitly that the tool ran and simply had nothing to print.
+      const text =
+        rendered === undefined || rendered.trim().length === 0
+          ? '(tool ran successfully with no output)'
+          : rendered;
+      messages.push({ role: 'tool', toolCallId: call.toolCallId, content: text });
+      state.messages.push({ role: 'tool', toolCallId: call.toolCallId, content: text });
+      causalityMonitor?.recordCall(`tool:${call.toolName}`);
+      // WI-05: a successful `tool_search` promotes its matches so the
+      // catalogue advertises them on the next step.
+      if (call.toolName === TOOL_SEARCH_NAME) {
+        recordToolSearchPromotions(output, promotedDeferred);
+      }
+    }
+  }
+}

package/src/runtime/executor-wiring.ts

@@ -0,0 +1,331 @@
+/**
+ * Warm-up wiring of the agent's tool-execution stack: the spill
+ * writer / result-reader pair (WI-10 / WI-13), the memory guard,
+ * data-flow guard and Progent argument-policy hooks, the shared
+ * `ToolExecutor` factory (WI-03), and the opt-in code-mode meta-tool
+ * surface (WI-11). Extracted verbatim from `factory.ts` (issue #23).
+ *
+ * @packageDocumentation
+ */
+
+import type { RunState, Tool } from '@graphorin/core';
+import type { Memory } from '@graphorin/memory';
+import {
+  createToolExecutor,
+  type ExecutorOptions,
+  type ToolExecutor,
+} from '@graphorin/tools/executor';
+import type { ToolRegistry } from '@graphorin/tools/registry';
+import {
+  createDefaultSpillWriter,
+  createFileResultReader,
+  type ResultReader,
+} from '@graphorin/tools/result';
+import {
+  buildMemoryGuard,
+  buildSecretResolver,
+  buildToolTokenCounter,
+  createMemoryRegionReader,
+  type ExecutorEventBridge,
+} from '../tooling/adapters.js';
+import { buildDataFlowGuard } from '../tooling/dataflow.js';
+import { createPlanTool, PLAN_TOOL_NAME } from '../tooling/plan.js';
+import { buildToolArgumentPolicy } from '../tooling/policy.js';
+import { buildToolRegistry } from '../tooling/registry-build.js';
+import type { AgentConfig } from '../types.js';
+import {
+  CODE_EXECUTE_NAME,
+  CODE_SEARCH_NAME,
+  composeResultReaders,
+  READ_RESULT_NAME,
+  registerCodeMode,
+  registerReadResult,
+  registerToolSearch,
+  TOOL_SEARCH_NAME,
+} from './tool-wiring.js';
+
+/** What {@link wireToolExecution} needs from the agent factory scope. */
+export interface ExecutorWiringDeps<TDeps, TOutput> {
+  readonly config: AgentConfig<TDeps, TOutput>;
+  readonly memory: Memory | undefined;
+  readonly agentId: string;
+  /** The synthetic handoff tool names (reserved from the code API). */
+  readonly handoffToolNames: Iterable<string>;
+  /** Lazy view of the in-flight run (read mid-run by the memory guard). */
+  readonly getActiveRunState: () => RunState | undefined;
+  /** Lazy view of the active run's capability (read by the code bridge). */
+  readonly getActiveRunCapability: () => 'read-only' | undefined;
+  /** Shared cell the streaming sink reads while a batch is in flight. */
+  readonly executorBridgeSlot: { current: ExecutorEventBridge | undefined };
+}
+
+/** The executor stack {@link wireToolExecution} hands back to the factory. */
+export interface ExecutorWiring<TDeps> {
+  readonly toolRegistry: ToolRegistry;
+  readonly spillWriter: ReturnType<typeof createDefaultSpillWriter>;
+  readonly resultReader: ResultReader;
+  readonly makeToolExecutor: (
+    registry: ToolRegistry,
+    opts?: { readonly quiet?: boolean },
+  ) => ToolExecutor;
+  readonly toolExecutor: ToolExecutor;
+  readonly toolDataFlowGuard: ReturnType<typeof buildDataFlowGuard> | undefined;
+  readonly ruleOfTwoCapabilityFloor: 'read-only' | undefined;
+  readonly isCodeMode: boolean;
+  readonly codeModeAdvertised: ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+}
+
+/**
+ * Construct the unified ToolExecutor once at warm-up (WI-03 / P0-1),
+ * bound to the registry above. Routing tool execution through the
+ * executor activates the documented tool fields the inline loop
+ * bypassed: per-tool `secretsAllowed` ACL, result truncation
+ * (`maxResultTokens` / `truncationStrategy`), inbound sanitization,
+ * memory-guard, idempotency keys and single-round repair.
+ *
+ * Durable HITL stays in the agent: approval is pre-screened below and
+ * suspends the run, so the executor's `ApprovalGate` only ever sees
+ * no-approval / pre-approved calls - it auto-grants and never blocks
+ * the generator (Adapter G).
+ *
+ * Sandbox note: `config.tools` are inline `tool({...})` closures that
+ * cannot be serialised to an out-of-process sandbox, and
+ * `resolveSandbox` defaults user-defined tools to `worker-threads`.
+ * Wiring a resolver that returned a real sandbox for that kind would
+ * break every inline tool, so `sandboxResolver` is intentionally left
+ * unset (the executor then runs inline - its documented fallback).
+ * The resolved policy is still surfaced on the tool-execute span /
+ * audit; real isolation applies to module-loadable (skill / MCP)
+ * tools and is wired when those land.
+ */
+export function wireToolExecution<TDeps, TOutput>(
+  deps: ExecutorWiringDeps<TDeps, TOutput>,
+): ExecutorWiring<TDeps> {
+  const { config, memory, agentId, executorBridgeSlot } = deps;
+  const { getActiveRunState, getActiveRunCapability, handoffToolNames } = deps;
+
+  // Assemble the unified tool registry at warm-up (Principle #12): one
+  // registry across first-party + skill sources, with deterministic
+  // cross-source collision resolution. Exposed read-only as
+  // `agent.registry`; the run loop and `tool_search` consume it. The
+  // registry is the tool-validation authority, so a malformed tool
+  // fails fast here at construction.
+  const toolRegistry = buildToolRegistry({
+    ...(config.tools !== undefined
+      ? { tools: config.tools as ReadonlyArray<Tool<unknown, unknown, unknown>> }
+      : {}),
+    ...(config.skills !== undefined ? { skills: config.skills } : {}),
+  }).registry;
+
+  // WI-05 (deferred loading + tool_search / P0-3): if any registered
+  // tool sets `defer_loading: true`, register the built-in `tool_search`
+  // so the model can discover those tools on demand. Tools that defer are
+  // withheld from the per-step catalogue (see the loop below) until a
+  // `tool_search` match promotes them, keeping large tool sets out of the
+  // context window. When nothing defers this is a no-op.
+  registerToolSearch(
+    toolRegistry,
+    config.toolPromotion === 'run-boundary' ? 'next-run' : 'next-step',
+  );
+
+  // D6: opt-in structured plan tool (TodoWrite-style, journaled). It
+  // mutates the ACTIVE run's todos through a closure; attention
+  // recitation renders them back into each step's request copy.
+  if (config.plan === true && toolRegistry.get(PLAN_TOOL_NAME) === undefined) {
+    toolRegistry.register(
+      createPlanTool((todos) => {
+        const activeRunState = getActiveRunState();
+        if (activeRunState !== undefined) {
+          (activeRunState as { todos?: ReadonlyArray<import('@graphorin/core').TodoItem> }).todos =
+            todos;
+        }
+      }) as unknown as Parameters<typeof toolRegistry.register>[0],
+      { kind: 'built-in', subsystem: 'planning' },
+    );
+  }
+
+  // WI-10 (result references / handles / P1-4): construct one spill
+  // writer + reader pair at warm-up. The writer is handed to the executor
+  // so a tool's `'spill-to-file'` truncation strategy externalises large
+  // bodies to disk (0600, run-scoped); the reader - over the *same*
+  // artifact root - backs the built-in `read_result` tool so the model can
+  // page through a spilled artifact on demand instead of inlining the
+  // whole blob. `read_result` is registered only when some tool spills.
+  const spillWriter = createDefaultSpillWriter();
+  const fileResultReader = createFileResultReader({ artifactRoot: spillWriter.artifactRoot });
+  // WI-13 (P2-2): compose any operator-supplied result readers (e.g. an
+  // MCP resource reader from `createMcpResourceReader`, for resolving
+  // `resource_link` handles) after the spill-file reader. `read_result`
+  // then pages both `graphorin-spill:` artifacts and external handles,
+  // and is force-registered when external readers exist (even if no tool
+  // spills) so those handles are resolvable.
+  const externalResultReaders = config.resultReaders ?? [];
+  const resultReader: ResultReader =
+    externalResultReaders.length === 0
+      ? fileResultReader
+      : composeResultReaders([fileResultReader, ...externalResultReaders]);
+  registerReadResult(toolRegistry, resultReader, { force: externalResultReaders.length > 0 });
+
+  const toolApprovalGate: NonNullable<ExecutorOptions['approvalGate']> = {
+    request: async () => ({ granted: true }),
+  };
+  const toolSecretResolver = buildSecretResolver();
+  const toolTokenCounter = buildToolTokenCounter();
+  // SDF-1: when memory is wired, bind a scope-aware region reader so the
+  // executor's DEC-153 snapshot/verify cycle actually runs (the scope
+  // resolves lazily from the in-flight run - the executor only invokes
+  // the reader mid-run). Without memory the guard tiers stay skipped,
+  // and a one-time WARN below makes that silent no-op visible.
+  const memoryGuardWiring = buildMemoryGuard(
+    memory,
+    memory === undefined
+      ? {}
+      : {
+          regionReader: createMemoryRegionReader(['working'], async (region) => {
+            if (region !== 'working') return '';
+            const activeRunState = getActiveRunState();
+            const scope = {
+              userId: activeRunState?.userId ?? agentId,
+              ...(activeRunState?.sessionId !== undefined
+                ? { sessionId: activeRunState.sessionId }
+                : {}),
+              agentId,
+            };
+            // W-054: call the statically-typed `Memory.working.compile`
+            // directly - a signature change must break THIS build, not
+            // silently turn the DEC-153 guard into a no-op through an
+            // unchecked double cast returning ''.
+            try {
+              return await memory.working.compile(scope, agentId);
+            } catch {
+              // The reader is best-effort: a failed region read must not
+              // turn the guard step into a run failure.
+              return '';
+            }
+          }),
+        },
+  );
+  const toolMemoryGuardFactory = memoryGuardWiring.memoryGuardFactory;
+  if (memory === undefined) {
+    const guarded = (config.tools ?? []).filter((t) => t.memoryGuardTier !== undefined);
+    if (guarded.length > 0) {
+      console.warn(
+        `[graphorin/agent] ${guarded.length} tool(s) declare memoryGuardTier but no memory is wired - ` +
+          'the DEC-153 snapshot/verify guard is skipped (SDF-1). Wire `memory` to activate it.',
+      );
+    }
+  }
+  // Provenance / data-flow guard (WI-12 / P1-3, opt-in). Built once and
+  // shared by every executor (direct + code-mode quiet), so the sink gate
+  // and taint recording apply uniformly. Off unless configured with a
+  // non-`'off'` mode - zero overhead on the default path.
+  const toolDataFlowGuard =
+    config.dataFlowPolicy !== undefined && config.dataFlowPolicy.mode !== 'off'
+      ? buildDataFlowGuard(config.dataFlowPolicy)
+      : undefined;
+  // W-103: the lethal-trifecta leg arms only when some tool can classify
+  // as `sensitive` - by default that means `sensitivity: 'secret'`, and
+  // no built-in tool ships with that tag. An operator who enables the
+  // policy without tagging private-data tools silently gets only the
+  // best-effort verbatim probe. One deterministic warn at construction
+  // (mirrors the memoryGuardTier warn above); tools registered later are
+  // not scanned - this is a wiring aid, not a gate.
+  if (
+    toolDataFlowGuard !== undefined &&
+    (config.dataFlowPolicy?.guardTrifecta ?? true) &&
+    config.dataFlowPolicy?.treatPiiAsSensitive !== true
+  ) {
+    const effectiveTiers = config.dataFlowPolicy?.sensitiveTiers ?? (['secret'] as const);
+    const anySensitiveTool = (config.tools ?? []).some(
+      (t) => t.sensitivity !== undefined && effectiveTiers.includes(t.sensitivity),
+    );
+    if (!anySensitiveTool) {
+      console.warn(
+        '[graphorin/agent] dataFlowPolicy is enabled but no registered tool declares a ' +
+          "sensitivity within sensitiveTiers (default ['secret']) and treatPiiAsSensitive is " +
+          'off - the lethal-trifecta leg cannot arm; only the best-effort verbatim ' +
+          "untrusted-to-sink probe is active. Tag private-data tools (sensitivity: 'secret') " +
+          'or widen sensitiveTiers / treatPiiAsSensitive.',
+      );
+    }
+  }
+  // D4 Progent tool-argument policy + Rule-of-Two floor. `ruleOfTwo`
+  // compiles to a policy (+ a read-only capability floor when it denies
+  // external side effects); an explicit `toolPolicy` composes on top
+  // (its rules are appended, so an explicit forbid still wins). Built
+  // once, shared by every executor.
+  const { guard: toolArgumentPolicyGuard, capabilityFloor: ruleOfTwoCapabilityFloor } =
+    buildToolArgumentPolicy(config.toolPolicy, config.ruleOfTwo);
+  const toolStreamingSink: NonNullable<ExecutorOptions['streamingSink']> = (event) =>
+    executorBridgeSlot.current?.sink(event);
+  // `quiet` builds an executor without the streaming sink - used for
+  // code-mode's in-script tool calls (WI-11), whose `tool.execute.*`
+  // events must not interleave into the outer agent stream.
+  const makeToolExecutor = (
+    registry: ToolRegistry,
+    opts?: { readonly quiet?: boolean },
+  ): ToolExecutor =>
+    createToolExecutor({
+      registry,
+      approvalGate: toolApprovalGate,
+      secretResolver: toolSecretResolver,
+      tokenCounter: toolTokenCounter,
+      memoryGuardFactory: toolMemoryGuardFactory,
+      ...(memoryGuardWiring.memoryRegionReader !== undefined
+        ? { memoryRegionReader: memoryGuardWiring.memoryRegionReader }
+        : {}),
+      spill: spillWriter,
+      ...(toolDataFlowGuard !== undefined ? { dataFlowGuard: toolDataFlowGuard } : {}),
+      ...(toolArgumentPolicyGuard !== undefined ? { argumentPolicy: toolArgumentPolicyGuard } : {}),
+      ...(opts?.quiet === true ? {} : { streamingSink: toolStreamingSink }),
+      ...(config.maxParallelTools !== undefined
+        ? { maxParallelTools: config.maxParallelTools }
+        : {}),
+      ...(config.toolRetry !== undefined ? { retry: config.toolRetry } : {}),
+    });
+  const toolExecutor = makeToolExecutor(toolRegistry);
+
+  // Code-mode (WI-11 / P1-2, opt-in): advertise only the `code_search` /
+  // `code_execute` meta-tools and let the model orchestrate tools inside a
+  // sandbox, so intermediate results stay out of context. A quiet executor
+  // backs the in-script tool bridge (same per-tool governance as direct
+  // mode). `read_result` is registered after the meta-tools because
+  // `code_execute` opts into `'spill-to-file'`, so a large final result can
+  // be fetched back on demand. Default `'direct'` mode leaves all of this
+  // untouched - `codeModeAdvertised` stays empty and the loop is unchanged.
+  const isCodeMode = config.toolInvocation === 'code-mode';
+  let codeModeAdvertised: ReadonlyArray<Tool<unknown, unknown, TDeps>> = [];
+  if (isCodeMode) {
+    const reserved = new Set<string>([
+      CODE_EXECUTE_NAME,
+      CODE_SEARCH_NAME,
+      TOOL_SEARCH_NAME,
+      READ_RESULT_NAME,
+      ...handoffToolNames,
+    ]);
+    const metas = registerCodeMode(
+      toolRegistry,
+      makeToolExecutor(toolRegistry, { quiet: true }),
+      reserved,
+      getActiveRunCapability,
+    );
+    registerReadResult(toolRegistry, resultReader);
+    const readResult = toolRegistry.get(READ_RESULT_NAME);
+    codeModeAdvertised = [
+      ...metas,
+      ...(readResult !== undefined ? [readResult] : []),
+    ] as ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+  }
+
+  return {
+    toolRegistry,
+    spillWriter,
+    resultReader,
+    makeToolExecutor,
+    toolExecutor,
+    toolDataFlowGuard,
+    ruleOfTwoCapabilityFloor,
+    isCodeMode,
+    codeModeAdvertised,
+  };
+}