@graphorin/agent 0.6.0 → 0.7.0

package/src/runtime/agent-surface.ts

@@ -0,0 +1,218 @@
+/**
+ * The agent's public call surface, built over the factory's run loop:
+ * `stream` / `run` (the AsyncIterable wrapper and the drained-run
+ * variant, AG-9), `compact` (queued into the loop, CE-3 / AG-13),
+ * `fanOut` (AG-7 lifecycle events onto the external queue), and the
+ * structured progress-artifact IO (AG-20). Extracted verbatim from
+ * `factory.ts` (issue #23); the factory's mutable `activeRunState`
+ * scratch is read through a live getter so event payloads observe
+ * exactly what the former closures observed.
+ *
+ * @packageDocumentation
+ */
+
+import type { AgentEvent, AgentResult, RunState } from '@graphorin/core';
+import type { Memory } from '@graphorin/memory';
+import {
+  type FanOutResult,
+  type FanOutOptions as RunFanOutOptions,
+  runFanOut,
+} from '../fanout/index.js';
+import { newId } from '../internal/ids.js';
+import type { ProgressIO, ProgressReadOptions, ProgressWriteOptions } from '../progress/index.js';
+import type {
+  AgentCallOptions,
+  AgentConfig,
+  AgentFanOutOptions,
+  AgentInput,
+  AgentProgressIO,
+  CompactionApiResult,
+  CompactOptions,
+} from '../types.js';
+import { noopCompactionResult, type PendingManualCompact } from './run-compaction.js';
+
+/** The factory's per-instance run entry point (concurrency-guarded). */
+export type RunLoopFn<TDeps, TOutput> = (
+  input: AgentInput | RunState,
+  options: AgentCallOptions<TDeps>,
+) => AsyncGenerator<AgentEvent<TOutput>, AgentResult<TOutput>, void>;
+
+/** Build the `stream` / `run` methods over the factory's run loop. */
+export function createRunMethods<TDeps, TOutput>(
+  runLoop: RunLoopFn<TDeps, TOutput>,
+): {
+  readonly stream: (
+    input: AgentInput | RunState,
+    options?: AgentCallOptions<TDeps>,
+  ) => AsyncIterable<AgentEvent<TOutput>>;
+  readonly run: (
+    input: AgentInput | RunState,
+    options?: AgentCallOptions<TDeps>,
+  ) => Promise<AgentResult<TOutput>>;
+} {
+  const stream = (
+    input: AgentInput | RunState,
+    options?: AgentCallOptions<TDeps>,
+  ): AsyncIterable<AgentEvent<TOutput>> => {
+    const opts = options ?? {};
+    return {
+      [Symbol.asyncIterator]: () => {
+        const gen = runLoop(input, opts);
+        return {
+          async next(): Promise<IteratorResult<AgentEvent<TOutput>, void>> {
+            const r = await gen.next();
+            if (r.done === true) {
+              return { done: true, value: undefined };
+            }
+            return { done: false, value: r.value };
+          },
+          async return(): Promise<IteratorResult<AgentEvent<TOutput>, void>> {
+            await gen.return(undefined as unknown as AgentResult<TOutput>);
+            return { done: true, value: undefined };
+          },
+        };
+      },
+    };
+  };
+
+  const run = async (
+    input: AgentInput | RunState,
+    options?: AgentCallOptions<TDeps>,
+  ): Promise<AgentResult<TOutput>> => {
+    const opts = options ?? {};
+    const gen = runLoop(input, opts);
+    let next = await gen.next();
+    while (next.done !== true) {
+      next = await gen.next();
+    }
+    // Every terminal path of the run loop returns `finalize(...)`; an
+    // undefined return value would mean the generator was torn down
+    // externally - an invariant violation, not a run outcome (AG-9).
+    const result = next.value;
+    if (result === undefined) {
+      throw new Error('unreachable: agent run loop ended without a result');
+    }
+    return result;
+  };
+
+  return { stream, run };
+}
+
+/** What the out-of-loop surface methods need from the factory scope. */
+export interface AgentSurfaceDeps<TDeps, TOutput> {
+  readonly config: Pick<AgentConfig<TDeps, TOutput>, 'sensitivity' | 'mergeGuard'>;
+  readonly memory: Memory | undefined;
+  readonly agentId: string;
+  readonly getActiveRunState: () => RunState | undefined;
+  readonly externalEventQueue: AgentEvent<TOutput>[];
+  readonly pendingManualCompacts: PendingManualCompact[];
+  readonly progressIO: ProgressIO;
+}
+
+/** Build the `compact` method (queued into the run loop, CE-3 / AG-13). */
+export function createCompactMethod<TDeps, TOutput>(
+  deps: AgentSurfaceDeps<TDeps, TOutput>,
+): (options?: CompactOptions) => Promise<CompactionApiResult> {
+  const { config, memory, getActiveRunState, pendingManualCompacts } = deps;
+  return async (options?: CompactOptions): Promise<CompactionApiResult> => {
+    // No memory wired - an explicit no-op (AG-13), intentionally
+    // forgiving so example apps that don't wire memory don't crash
+    // on `agent.compact()`.
+    if (memory === undefined) return noopCompactionResult('no-memory');
+    // Sensitivity gate (WI-09 step 2) applies to MANUAL compaction
+    // too: secret-tier history never ships to the summarizer.
+    if (config.sensitivity === 'secret') return noopCompactionResult('sensitivity-gated');
+    // Idle - there is no live buffer to splice (AG-13's explicit
+    // no-op marker, where the old surface silently reported zeros).
+    if (getActiveRunState() === undefined) return noopCompactionResult('no-active-run');
+    // CE-3/AG-13: the run loop owns the live buffer, so the splice
+    // happens there - enqueue and let `maybeAutoCompact` service the
+    // request at the next step boundary with the same prefix-pinned
+    // splice as auto-compaction. Don't await this from inside a tool
+    // handler: the loop can't reach the next step until the tool
+    // returns.
+    return await new Promise<CompactionApiResult>((resolve, reject) => {
+      pendingManualCompacts.push({ options, resolve, reject });
+    });
+  };
+}
+
+/** Build the `fanOut` method (AG-7: lifecycle events reach the stream). */
+export function createFanOutMethod<TDeps, TOutput>(
+  deps: AgentSurfaceDeps<TDeps, TOutput>,
+): <TFanOutOutput = unknown>(
+  options: AgentFanOutOptions<TFanOutOutput>,
+) => Promise<FanOutResult<TFanOutOutput>> {
+  const { config, agentId, getActiveRunState, externalEventQueue } = deps;
+  return async <TFanOutOutput = unknown>(
+    options: AgentFanOutOptions<TFanOutOutput>,
+  ): Promise<FanOutResult<TFanOutOutput>> => {
+    const activeRunState = getActiveRunState();
+    const runId = activeRunState?.id ?? `run_${newId()}`;
+    const sessionId = activeRunState?.sessionId ?? `session_${newId()}`;
+    const fanOutOptions: RunFanOutOptions<TFanOutOutput> = {
+      children: options.children,
+      ...(options.maxConcurrentChildren !== undefined
+        ? { maxConcurrentChildren: options.maxConcurrentChildren }
+        : {}),
+      ...(options.perBudget !== undefined ? { perBudget: options.perBudget } : {}),
+      ...(options.mergeStrategy !== undefined ? { mergeStrategy: options.mergeStrategy } : {}),
+      ...(options.signal !== undefined ? { signal: options.signal } : {}),
+      // AG-7: fanout lifecycle events reach the agent stream - queued
+      // on the external-event queue and drained into the active (or
+      // next consumed) run, like steer/follow-up/progress events.
+      emit: (event) => {
+        externalEventQueue.push(event as AgentEvent<TOutput>);
+      },
+      // AG-7: the configured sideways-injection merge guard finally
+      // applies to the judge-merge path.
+      ...(config.mergeGuard !== undefined ? { mergeGuard: config.mergeGuard } : {}),
+      runId,
+      sessionId,
+      agentId,
+    };
+    return runFanOut<TFanOutOutput>(fanOutOptions);
+  };
+}
+
+/** Build the structured progress-artifact IO surface (AG-20). */
+export function createProgressSurface<TDeps, TOutput>(
+  deps: AgentSurfaceDeps<TDeps, TOutput>,
+): AgentProgressIO {
+  const { agentId, getActiveRunState, externalEventQueue, progressIO } = deps;
+  // Stable fallback id so out-of-run `progress.write` → `progress.read`
+  // pairs resolve to the same artifact directory (a fresh id per call
+  // could never find what it just wrote).
+  const progressFallbackRunId = `run_${newId()}`;
+  const progress: AgentProgressIO = {
+    write: async (content: string, opts?: ProgressWriteOptions) => {
+      const runId = getActiveRunState()?.id ?? progressFallbackRunId;
+      const ref = await progressIO.write(runId, content, opts);
+      // AG-20: surface the documented `agent.progress.written` event -
+      // queued here and drained into the active (or next consumed) stream.
+      externalEventQueue.push({
+        type: 'agent.progress.written',
+        runId,
+        sessionId: getActiveRunState()?.sessionId ?? '',
+        agentId,
+        ref,
+      } as AgentEvent<TOutput>);
+      return ref;
+    },
+    read: async (opts?: ProgressReadOptions) => {
+      const queriedRunId = opts?.runId ?? getActiveRunState()?.id ?? progressFallbackRunId;
+      const refs = await progressIO.read(queriedRunId, opts);
+      externalEventQueue.push({
+        type: 'agent.progress.read',
+        runId: getActiveRunState()?.id ?? queriedRunId,
+        sessionId: getActiveRunState()?.sessionId ?? '',
+        agentId,
+        refs,
+        queriedRunId,
+        queriedRole: opts?.role,
+      } as AgentEvent<TOutput>);
+      return refs;
+    },
+  };
+  return progress;
+}

package/src/runtime/agent-to-tool.ts

@@ -0,0 +1,323 @@
+/**
+ * `agent.toTool()` - expose an agent as a callable sub-agent tool
+ * (AG-17 / D2): least-authority seeding from the parent history, the
+ * contextFold distillation of a completed child run, and the coarse
+ * child-taint propagation that re-arms the parent's data-flow ledger.
+ * Extracted verbatim from `factory.ts` (issue #23); the former factory
+ * closures now hang off {@link createToTool}'s deps.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AgentEvent,
+  AgentResult,
+  Message,
+  RunState,
+  Tool,
+  ToolExecutionContext,
+  UsageAccumulator,
+} from '@graphorin/core';
+import { toolReturn } from '@graphorin/core';
+import type { AgentCallOptions, AgentConfig, AgentInput, AgentToToolOptions } from '../types.js';
+import { foldChildRunUsage } from './messages.js';
+
+/**
+ * W-033: fold the child's usage into the parent run through the tool
+ * context. `RunContext.state` is typed as a readonly projection for
+ * user tools (W-047); this runtime-internal seam is the sanctioned
+ * mutation point - the runtime owns the state lifecycle.
+ */
+function foldIntoParent(
+  ctx: ToolExecutionContext<unknown> | undefined,
+  childState: RunState,
+  childName: string,
+): void {
+  if (ctx === undefined) return;
+  const parentState = ctx.runContext.state as unknown as RunState | undefined;
+  const usageAcc = ctx.runContext.usage as UsageAccumulator | undefined;
+  if (parentState !== undefined && typeof parentState.usage?.totalTokens === 'number') {
+    foldChildRunUsage(parentState, usageAcc, childState, childName);
+    return;
+  }
+  // A foreign harness mounting this tool outside the graphorin loop may
+  // hand a structurally-minimal context - fold into the accumulator only.
+  const byModel = childState.usageByModel;
+  if (byModel !== undefined && Object.keys(byModel).length > 0) {
+    for (const [modelId, usage] of Object.entries(byModel)) usageAcc?.add(modelId, usage);
+    return;
+  }
+  const aggregate = childState.usage;
+  if (aggregate.promptTokens > 0 || aggregate.completionTokens > 0 || aggregate.totalTokens > 0) {
+    usageAcc?.add(`sub-agent:${childName}`, aggregate);
+  }
+}
+
+/** What {@link createToTool} needs from the agent factory scope. */
+export interface ToToolDeps<TDeps, TOutput> {
+  readonly config: AgentConfig<TDeps, TOutput>;
+  readonly run: (
+    input: AgentInput | RunState,
+    options?: AgentCallOptions<TDeps>,
+  ) => Promise<AgentResult<TOutput>>;
+  readonly stream: (
+    input: AgentInput | RunState,
+    options?: AgentCallOptions<TDeps>,
+  ) => AsyncIterable<AgentEvent<TOutput>>;
+}
+
+/**
+ * W-001: well-known marker on every `toTool()` tool object. The
+ * graphorin tool-call walk detects it and executes the sub-agent
+ * INLINE (through the same seam as a handoff) so a child suspending on
+ * `awaiting_approval` parks on the parent instead of throwing from the
+ * executor; the resume router resolves parked toTool sub-runs through
+ * the same refs. `Symbol.for` so duplicate package copies agree.
+ * Foreign harnesses mounting the tool outside the graphorin loop keep
+ * the plain `execute()` behavior (a suspended child throws there).
+ */
+export const SUBAGENT_TOOL: unique symbol = Symbol.for('graphorin.SubAgentTool');
+
+/** Child taint flags carried across the toTool fold (D2). */
+export interface SubAgentFoldTaint {
+  readonly untrusted?: boolean;
+  readonly sensitive?: boolean;
+  readonly sourceKind?: string;
+}
+
+/**
+ * The live references {@link SUBAGENT_TOOL} carries (W-001). Typed
+ * loosely on purpose: the walk is generic over foreign TDeps/TOutput
+ * and only ever passes through values it received from the same
+ * factory instance.
+ */
+export interface SubAgentToolRefs {
+  readonly agentName: string;
+  readonly run: (
+    input: unknown,
+    options?: Record<string, unknown>,
+  ) => Promise<AgentResult<unknown>>;
+  readonly stream: (
+    input: unknown,
+    options?: Record<string, unknown>,
+  ) => AsyncIterable<AgentEvent<unknown>>;
+  /** D2 capability restriction from `AgentToToolOptions.capability`. */
+  readonly capability?: 'read-only';
+  /** W-036: forwarding policy from `AgentToToolOptions.forwardEvents`. */
+  readonly forwardEvents?: 'none' | 'lifecycle' | 'all';
+  /** Reproduce `execute()`'s seed semantics (inputFilter + input string). */
+  readonly buildSeed: (
+    input: { readonly input: string },
+    parentMessages: ReadonlyArray<Message>,
+  ) => AgentInput;
+  /** Reproduce `execute()`'s output shaping (exposeTurns/contextFold/taint). */
+  readonly shapeCompleted: (
+    result: AgentResult<unknown>,
+    turns: ReadonlyArray<string>,
+  ) => { readonly output: unknown; readonly taint?: SubAgentFoldTaint };
+}
+
+/** Read the {@link SUBAGENT_TOOL} refs off a (possibly wrapped) tool. */
+export function getSubAgentToolRefs(tool: unknown): SubAgentToolRefs | undefined {
+  if (typeof tool !== 'object' || tool === null) return undefined;
+  const refs = (tool as Record<PropertyKey, unknown>)[SUBAGENT_TOOL];
+  return refs === undefined ? undefined : (refs as SubAgentToolRefs);
+}
+
+/** Build the agent's `toTool` method over the factory's run surface. */
+export function createToTool<TDeps, TOutput>(
+  deps: ToToolDeps<TDeps, TOutput>,
+): (options?: AgentToToolOptions) => Tool<{ readonly input: string }, TOutput, TDeps> {
+  const { config, run, stream } = deps;
+
+  // D2: distil a completed child run into a compact, bounded outcome the
+  // parent folds into its context instead of the raw transcript/output.
+  const foldRunOutcome = (result: AgentResult<TOutput>, maxChars: number): string => {
+    const steps = result.state.steps;
+    const toolNames = [
+      ...new Set(steps.flatMap((step) => step.toolCalls.map((c) => c.call.toolName))),
+    ];
+    const header =
+      `[sub-agent '${config.name}' outcome] status=${result.status}; ` +
+      `steps=${steps.length}; toolCalls=${steps.reduce((n, st) => n + st.toolCalls.length, 0)}` +
+      (toolNames.length > 0 ? `; tools=${toolNames.join(', ')}` : '');
+    const text = typeof result.output === 'string' ? result.output : JSON.stringify(result.output);
+    const body =
+      text.length > maxChars
+        ? `${text.slice(0, maxChars)}\n[... ${text.length - maxChars} chars truncated by contextFold]`
+        : text;
+    return `${header}\n${body}`;
+  };
+
+  // D2: carry the child's coarse taint flags across the fold so the
+  // parent's data-flow ledger re-arms (widen-only; a no-op when the
+  // parent has no dataFlowPolicy).
+  const taintFromChildState = (
+    state: RunState,
+  ): { untrusted?: boolean; sensitive?: boolean; sourceKind?: string } | undefined => {
+    const summary = state.taintSummary;
+    if (summary === undefined || (!summary.untrustedSeen && !summary.sensitiveSeen)) {
+      return undefined;
+    }
+    return {
+      ...(summary.untrustedSeen ? { untrusted: true } : {}),
+      ...(summary.sensitiveSeen ? { sensitive: true } : {}),
+      sourceKind: 'sub-agent',
+    };
+  };
+
+  const toTool = (
+    options: AgentToToolOptions = {},
+  ): Tool<{ readonly input: string }, TOutput, TDeps> => {
+    const exposeTurns = options.exposeTurns ?? 'final';
+    const foldMaxChars =
+      options.contextFold === undefined || options.contextFold === false
+        ? null
+        : typeof options.contextFold === 'object'
+          ? (options.contextFold.maxChars ?? 2000)
+          : 2000;
+    const propagateTaint = options.propagateTaint !== false;
+    const toolName = options.name ?? `subagent_${config.name}`;
+    const description = options.description ?? `Invoke sub-agent '${config.name}'.`;
+
+    // Shared by `execute()` and the W-001 inline walk: seed semantics
+    // (least authority - input string only unless an inputFilter opts
+    // parent history in) and completed-result shaping.
+    const buildSeed = (
+      input: { readonly input: string },
+      parentMessages: ReadonlyArray<Message> | undefined,
+    ): AgentInput =>
+      options.inputFilter !== undefined && parentMessages !== undefined
+        ? ([
+            ...options.inputFilter(parentMessages),
+            { role: 'user' as const, content: input.input },
+          ] as Message[])
+        : input.input;
+    const shapeCompleted = (
+      result: AgentResult<TOutput>,
+      turns: ReadonlyArray<string>,
+    ): { readonly output: unknown; readonly taint?: SubAgentFoldTaint } => {
+      const taint = propagateTaint ? taintFromChildState(result.state) : undefined;
+      const output =
+        exposeTurns === 'all'
+          ? foldMaxChars !== null
+            ? foldRunOutcome(result, foldMaxChars)
+            : turns.join('\n\n')
+          : exposeTurns === 'none'
+            ? ''
+            : foldMaxChars !== null
+              ? foldRunOutcome(result, foldMaxChars)
+              : result.output;
+      return { output, ...(taint !== undefined ? { taint } : {}) };
+    };
+
+    const schema = {
+      parse: (v: unknown): { readonly input: string } => v as { readonly input: string },
+      safeParse: (v: unknown) => ({
+        success: true as const,
+        data: v as { readonly input: string },
+      }),
+      toJSON: (): Record<string, unknown> => ({
+        type: 'object',
+        properties: { input: { type: 'string' } },
+        required: ['input'],
+      }),
+    };
+    const tool: Tool<{ readonly input: string }, TOutput, TDeps> = {
+      name: toolName,
+      description,
+      inputSchema: schema as unknown as Tool<
+        { readonly input: string },
+        TOutput,
+        TDeps
+      >['inputSchema'],
+      sideEffectClass: 'side-effecting',
+      async execute(input, ctx) {
+        // AG-17: the parent ToolExecutionContext propagates - the
+        // parent's abort stops the sub-agent, deps/sessionId flow
+        // through, and the optional `inputFilter` shapes a seed from
+        // the parent history. Least authority by default: without a
+        // filter the sub-agent sees ONLY the input string, never the
+        // parent conversation.
+        const callOpts: AgentCallOptions<TDeps> = {
+          ...(ctx?.signal !== undefined ? { signal: ctx.signal } : {}),
+          ...(ctx?.runContext.deps !== undefined ? { deps: ctx.runContext.deps as TDeps } : {}),
+          ...(ctx?.runContext.sessionId !== undefined
+            ? { sessionId: ctx.runContext.sessionId }
+            : {}),
+          // D2: run the child under a restricted capability (read-only
+          // workers in an orchestrator-worker fan-out).
+          ...(options.capability !== undefined ? { capability: options.capability } : {}),
+          // W-036: the child's run span parents under the calling tool's
+          // span - one trace tree even through the executor path.
+          ...(ctx?.runContext.span !== undefined ? { parentSpan: ctx.runContext.span } : {}),
+        };
+        const seed = buildSeed(input, ctx?.runContext.messages);
+        if (exposeTurns === 'all') {
+          // Replay the streamed text completions as the result so
+          // the parent agent sees every turn the sub-agent
+          // produced. `exposeTurns: 'final'` (default) and
+          // `'none'` skip the per-turn assembly.
+          const turns: string[] = [];
+          let endResult: AgentResult<TOutput> | undefined;
+          for await (const ev of stream(seed, callOpts)) {
+            if (ev.type === 'text.complete') turns.push(ev.text);
+            else if (ev.type === 'agent.end') endResult = ev.result;
+          }
+          // W-033: fold BEFORE the non-completed throw - tokens were
+          // spent whether or not the child completed.
+          if (endResult !== undefined) {
+            foldIntoParent(
+              ctx as ToolExecutionContext<unknown> | undefined,
+              endResult.state,
+              config.name,
+            );
+          }
+          if (endResult !== undefined && endResult.status !== 'completed') {
+            throw new Error(
+              `sub-agent '${config.name}' ${endResult.status}${
+                endResult.error !== undefined ? `: ${endResult.error.message}` : ''
+              }`,
+            );
+          }
+          if (endResult === undefined) return turns.join('\n\n') as unknown as TOutput;
+          const shapedAll = shapeCompleted(endResult, turns);
+          return (shapedAll.taint !== undefined
+            ? toolReturn({ output: shapedAll.output, taint: shapedAll.taint })
+            : shapedAll.output) as unknown as TOutput;
+        }
+        const result = await run(seed, callOpts);
+        // W-033: fold BEFORE the non-completed throw (see 'all' branch).
+        foldIntoParent(ctx as ToolExecutionContext<unknown> | undefined, result.state, config.name);
+        // AG-17/AG-22 class: a non-completed sub-run is a TOOL ERROR,
+        // never an empty-string success.
+        if (result.status !== 'completed') {
+          throw new Error(
+            `sub-agent '${config.name}' ${result.status}${
+              result.error !== undefined ? `: ${result.error.message}` : ''
+            }`,
+          );
+        }
+        const shaped = shapeCompleted(result, []);
+        return (shaped.taint !== undefined
+          ? toolReturn({ output: shaped.output, taint: shaped.taint })
+          : shaped.output) as unknown as TOutput;
+      },
+    };
+    // W-001: attach the inline-walk refs (see SUBAGENT_TOOL). Symbol
+    // properties survive the registry's `{...tool}` normalization spread.
+    const refs: SubAgentToolRefs = {
+      agentName: config.name,
+      run: run as unknown as SubAgentToolRefs['run'],
+      stream: stream as unknown as SubAgentToolRefs['stream'],
+      ...(options.capability !== undefined ? { capability: options.capability } : {}),
+      ...(options.forwardEvents !== undefined ? { forwardEvents: options.forwardEvents } : {}),
+      buildSeed,
+      shapeCompleted: shapeCompleted as unknown as SubAgentToolRefs['shapeCompleted'],
+    };
+    (tool as unknown as Record<PropertyKey, unknown>)[SUBAGENT_TOOL] = refs;
+    return tool;
+  };
+
+  return toTool;
+}