@bluecopa/harness 0.0.1 → 0.1.0-snapshot.10

package/src/arc/arc-types.ts

@@ -0,0 +1,215 @@
+import type { AgentMessage, AgentAction } from '../agent/types';
+import type { ToolProvider } from '../interfaces/tool-provider';
+import type { SandboxProvider } from '../interfaces/sandbox-provider';
+import type { Tool } from 'ai';
+import type { HarnessTelemetry } from '../observability/otel';
+import type { HookRunner } from '../hooks/hook-runner';
+import type { PermissionManager } from '../permissions/permission-manager';
+import type { SkillManager } from '../skills/skill-manager';
+import type { ToolCallAction } from '../agent/types';
+import type { ToolResult } from '../interfaces/tool-provider';
+
+// ── Episode types ──
+
+export interface Episode {
+  id: string;
+  taskId: string;
+  sessionId: string;
+  index: number;
+  threadAction: string;
+  summary: string;
+  toolCalls: string[];
+  filesRead: string[];
+  filesModified: string[];
+  model: string;
+  steps: number;
+  success: boolean;
+  createdAt: number;
+  parentEpisodeIds: string[];
+}
+
+export interface EpisodeTrace {
+  episodeId: string;
+  messages: AgentMessage[];
+  createdAt: number;
+  ttl?: number;
+}
+
+// ── Session memo types ──
+
+export interface SessionMemo {
+  id: string;
+  sessionId: string;
+  content: string;
+  sourceEpisodeIds: string[];
+  createdAt: number;
+}
+
+// ── Long-term memory types ──
+
+export interface LongTermMemory {
+  id: string;
+  content: string;
+  category: string;
+  sourceSessionMemoIds: string[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ── Store interfaces ──
+
+export interface EpisodeStore {
+  addEpisode(episode: Episode): Promise<void>;
+  addTrace(trace: EpisodeTrace): Promise<void>;
+  getEpisode(id: string): Promise<Episode | null>;
+  getTrace(episodeId: string): Promise<EpisodeTrace | null>;
+  getEpisodesByTask(taskId: string): Promise<Episode[]>;
+  getEpisodesBySession(sessionId: string): Promise<Episode[]>;
+  getRecentEpisodes(limit: number): Promise<Episode[]>;
+  evictTraces(olderThan: number): Promise<number>;
+}
+
+export interface SessionMemoStore {
+  addMemo(memo: SessionMemo): Promise<void>;
+  getMemo(id: string): Promise<SessionMemo | null>;
+  getMemosBySession(sessionId: string): Promise<SessionMemo[]>;
+  getRecentMemos(limit: number): Promise<SessionMemo[]>;
+}
+
+export interface LongTermStore {
+  addMemory(memory: LongTermMemory): Promise<void>;
+  getMemory(id: string): Promise<LongTermMemory | null>;
+  getAllMemories(): Promise<LongTermMemory[]>;
+  getMemoriesByCategory(category: string): Promise<LongTermMemory[]>;
+  updateMemory(id: string, updates: Partial<Pick<LongTermMemory, 'content' | 'category' | 'updatedAt'>>): Promise<void>;
+  deleteMemory(id: string): Promise<void>;
+}
+
+// ── Thread types ──
+
+export interface ThreadRequest {
+  action: string;
+  contextEpisodeIds?: string[];
+  model?: string;
+  maxSteps?: number;
+}
+
+export interface ThreadResult {
+  episode: Episode;
+  success: boolean;
+  error?: string;
+  /** Actual wall-clock duration of this individual thread in ms. */
+  durationMs?: number;
+  /** Resolved model ID (e.g. 'claude-haiku-4-5'). */
+  resolvedModel?: string;
+}
+
+// ── Model tiers ──
+
+export type ModelTier = 'fast' | 'medium' | 'strong';
+
+/** Default model IDs for each tier. Override via ArcLoopConfig.modelMap. */
+export const DEFAULT_MODEL_MAP: Record<ModelTier, string> = {
+  fast: 'claude-haiku-4-5',
+  medium: 'claude-sonnet-4-5',
+  strong: 'claude-opus-4-5',
+};
+
+/** Resolve a model tier name or raw model ID to a concrete model ID. */
+export function resolveModel(modelOrTier: string | undefined, modelMap: Record<ModelTier, string>, fallback: string): string {
+  if (!modelOrTier) return fallback;
+  if (modelOrTier in modelMap) return modelMap[modelOrTier as ModelTier];
+  return modelOrTier; // raw model ID passthrough
+}
+
+// ── ArcLoop config ──
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyTool = Tool<any, any>;
+
+export interface ArcLoopConfig {
+  /** Orchestrator model (default: 'claude-opus-4-6'). Accepts a model ID or tier name. */
+  model?: string;
+  /** Custom orchestrator system prompt */
+  systemPrompt?: string;
+  /** Anthropic API key */
+  apiKey?: string;
+  /** Default model for threads (default: 'medium' → claude-sonnet-4-6). Accepts a model ID or tier name. */
+  threadModel?: string;
+  /** Model tier mapping. Override to use different models for fast/medium/strong. */
+  modelMap?: Record<ModelTier, string>;
+  /** Tools available to threads (default: builtinTools) */
+  threadTools?: Record<string, AnyTool>;
+  /** Thread concurrency limit (default: 3) */
+  maxConcurrency?: number;
+  /** Max orchestrator turns before stopping (default: 20) */
+  maxOrchestratorTurns?: number;
+  /** Per-thread timeout in ms (default: 120000) */
+  threadTimeout?: number;
+  /** Per-thread max steps (default: 20) */
+  threadMaxSteps?: number;
+
+  // Store dependencies
+  episodeStore: EpisodeStore;
+  sessionMemoStore: SessionMemoStore;
+  longTermStore: LongTermStore;
+
+  // Task/session context
+  taskId: string;
+  sessionId: string;
+
+  /** Episode compression strategy (default: 'template') */
+  compressor?: 'template' | 'llm';
+
+  /** Extra orchestrator tools beyond Thread (for dynadocs Task compatibility) */
+  extraOrchestratorTools?: Record<string, AnyTool>;
+  /** Handler for extra orchestrator tools. Return an AgentAction (typically FinalAction with directive). */
+  onOrchestratorTool?: (name: string, args: Record<string, unknown>) => Promise<AgentAction>;
+
+  /** Tool provider for thread execution (default — local filesystem, sandbox in browser) */
+  toolProvider: ToolProvider;
+  /** Tool provider for skill-matched threads (sandbox with packages pre-installed). If not set, all threads use toolProvider. */
+  skillToolProvider?: ToolProvider;
+  /** E2B executor instance — needed for binary file transfers (CopyToLocal for docx, xlsx, etc.) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  executor?: any;
+  /** Local directory to sync sandbox output artifacts to (default: './outputs') */
+  localOutputDir?: string;
+
+  // ── Thread runtime extras (passed through to each thread's createAgent) ──
+
+  /** Sandbox provider for skill execution within threads */
+  sandboxProvider?: SandboxProvider;
+  /** Skill manager for thread agents */
+  skillManager?: SkillManager;
+  /** Path to skill index JSON */
+  skillIndexPath?: string;
+  /** Callback for threads to ask the user a question */
+  askUser?: (question: string, options?: string[]) => Promise<string>;
+  /** Callback for threads to display a message to the user */
+  tellUser?: (message: string) => Promise<void>;
+  /** Callback for threads to download a file from sandbox */
+  downloadRawFile?: (path: string) => Promise<string>;
+  /** OpenTelemetry-style tracing for thread agents */
+  telemetry?: HarnessTelemetry;
+  /** Lifecycle hooks for thread tool calls */
+  hookRunner?: HookRunner;
+  /** Permission manager for thread tool access */
+  permissionManager?: PermissionManager;
+  /** Custom tool executor for threads. Return null to fall through to built-in dispatch. */
+  executeToolAction?: (action: ToolCallAction) => Promise<ToolResult | null>;
+  /** Progress callback fired for each tool call inside threads (tool_start/tool_end with thread context). */
+  onThreadToolProgress?: (event: { threadIndex: number; threadAction: string } & ({ type: 'tool_start'; name: string; args: Record<string, unknown> } | { type: 'tool_end'; name: string; success: boolean; durationMs: number })) => void;
+}
+
+// ── Debug export ──
+
+export interface DebugExport {
+  taskId?: string;
+  sessionId?: string;
+  exportedAt: number;
+  episodes: Episode[];
+  traces: EpisodeTrace[];
+  sessionMemos: SessionMemo[];
+  longTermMemories: LongTermMemory[];
+}

package/src/arc/bridge-tools.ts

@@ -0,0 +1,170 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import type { ToolProvider, ToolResult } from '../interfaces/tool-provider';
+import type { ToolCallAction } from '../agent/types';
+
+// ── Bridge tool definitions (LLM-facing schemas) ──
+
+export const bridgeTools = {
+  ReadSandbox: tool({
+    description: 'Read a file from the sandbox filesystem (where code execution happens)',
+    inputSchema: z.object({
+      path: z.string().describe('Absolute path in the sandbox filesystem'),
+    }),
+  }),
+  WriteSandbox: tool({
+    description: 'Write content to a file in the sandbox filesystem',
+    inputSchema: z.object({
+      path: z.string().describe('Absolute path in the sandbox filesystem'),
+      content: z.string().describe('Content to write'),
+    }),
+  }),
+  CopyToSandbox: tool({
+    description: 'Copy a file from the local project to the sandbox. Use this to stage files for processing by sandbox tools (e.g. data files for a Python script).',
+    inputSchema: z.object({
+      localPath: z.string().describe('Path on the local filesystem (source)'),
+      sandboxPath: z.string().describe('Path in the sandbox (destination)'),
+    }),
+  }),
+  CopyToLocal: tool({
+    description: 'Copy a file from the sandbox to the local project. Use this to retrieve generated output files (docx, xlsx, pdf, images, etc.).',
+    inputSchema: z.object({
+      sandboxPath: z.string().describe('Path in the sandbox (source)'),
+      localPath: z.string().describe('Path on the local filesystem (destination)'),
+    }),
+  }),
+};
+
+// ── Bridge tool executor ──
+
+export interface BridgeExecutorConfig {
+  localProvider: ToolProvider;
+  sandboxProvider: ToolProvider;
+  /** E2B executor with readFileBytes/writeFileBytes for binary transfers */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  executor?: any;
+}
+
+/**
+ * Creates an executeToolAction handler for bridge tools.
+ * Returns null for non-bridge tools (falls through to built-in dispatch).
+ */
+export function createBridgeExecutor(config: BridgeExecutorConfig) {
+  return async (action: ToolCallAction): Promise<ToolResult | null> => {
+    if (action.name === 'ReadSandbox') {
+      return config.sandboxProvider.readFile(String(action.args.path ?? ''));
+    }
+
+    if (action.name === 'WriteSandbox') {
+      return config.sandboxProvider.writeFile(
+        String(action.args.path ?? ''),
+        String(action.args.content ?? ''),
+      );
+    }
+
+    if (action.name === 'CopyToSandbox') {
+      const localPath = String(action.args.localPath ?? '');
+      const sandboxPath = String(action.args.sandboxPath ?? '');
+      try {
+        // Read from local
+        const localResult = await config.localProvider.readFile(localPath);
+        if (!localResult.success) {
+          return { success: false, output: '', error: `Failed to read local file: ${localResult.error}` };
+        }
+        // Write to sandbox
+        const writeResult = await config.sandboxProvider.writeFile(sandboxPath, localResult.output);
+        if (!writeResult.success) {
+          return { success: false, output: '', error: `Failed to write to sandbox: ${writeResult.error}` };
+        }
+        return { success: true, output: `Copied ${localPath} → sandbox:${sandboxPath} (${localResult.output.length} chars)` };
+      } catch (error) {
+        return { success: false, output: '', error: `CopyToSandbox failed: ${error instanceof Error ? error.message : String(error)}` };
+      }
+    }
+
+    if (action.name === 'CopyToLocal') {
+      const sandboxPath = String(action.args.sandboxPath ?? '');
+      const localPath = String(action.args.localPath ?? '');
+      try {
+        // Try binary transfer if executor supports readFileBytes
+        if (config.executor?.readFileBytes) {
+          const bytes: Uint8Array = await config.executor.readFileBytes(sandboxPath);
+          await mkdir(dirname(localPath), { recursive: true });
+          await writeFile(localPath, Buffer.from(bytes));
+          return { success: true, output: `Copied sandbox:${sandboxPath} → ${localPath} (${bytes.byteLength} bytes)` };
+        }
+
+        // Fallback: text-based transfer via provider
+        const sandboxResult = await config.sandboxProvider.readFile(sandboxPath);
+        if (!sandboxResult.success) {
+          return { success: false, output: '', error: `Failed to read sandbox file: ${sandboxResult.error}` };
+        }
+        await mkdir(dirname(localPath), { recursive: true });
+        await writeFile(localPath, sandboxResult.output, 'utf-8');
+        return { success: true, output: `Copied sandbox:${sandboxPath} → ${localPath} (${sandboxResult.output.length} chars)` };
+      } catch (error) {
+        return { success: false, output: '', error: `CopyToLocal failed: ${error instanceof Error ? error.message : String(error)}` };
+      }
+    }
+
+    // Not a bridge tool — fall through to built-in dispatch
+    return null;
+  };
+}
+
+// ── Auto-sync: copy output artifacts from sandbox to local after thread completes ──
+
+const ARTIFACT_EXTENSIONS = /\.(docx|xlsx|pptx|csv|pdf|png|jpg|jpeg|gif|zip|tar|gz)$/i;
+
+/**
+ * Scan sandbox output directory and copy any artifact files to local.
+ * Called after a skill thread completes.
+ */
+export async function syncArtifactsToLocal(
+  sandboxProvider: ToolProvider,
+  localOutputDir: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  executor?: any,
+  sandboxOutputDir = '/outputs',
+): Promise<string[]> {
+  const copied: string[] = [];
+
+  try {
+    // List files in sandbox output directory
+    const listResult = await sandboxProvider.bash(
+      `find ${sandboxOutputDir} -maxdepth 1 -type f 2>/dev/null | head -50`,
+    );
+    if (!listResult.success || !listResult.output.trim()) return copied;
+
+    const files = listResult.output.trim().split('\n').filter(Boolean);
+
+    for (const sandboxPath of files) {
+      const filename = sandboxPath.split('/').pop();
+      if (!filename || !ARTIFACT_EXTENSIONS.test(filename)) continue;
+
+      const localPath = `${localOutputDir}/${filename}`;
+      try {
+        if (executor?.readFileBytes) {
+          const bytes: Uint8Array = await executor.readFileBytes(sandboxPath);
+          await mkdir(localOutputDir, { recursive: true });
+          await writeFile(localPath, Buffer.from(bytes));
+        } else {
+          // Text fallback
+          const result = await sandboxProvider.readFile(sandboxPath);
+          if (!result.success) continue;
+          await mkdir(localOutputDir, { recursive: true });
+          await writeFile(localPath, result.output, 'utf-8');
+        }
+        copied.push(localPath);
+      } catch {
+        // Skip files that fail to copy
+      }
+    }
+  } catch {
+    // Non-critical — artifacts are bonus
+  }
+
+  return copied;
+}

package/src/arc/bridged-tool-provider.ts

@@ -0,0 +1,80 @@
+import type {
+  BashOptions,
+  GlobOptions,
+  GrepOptions,
+  ReadOptions,
+  ToolProvider,
+  ToolProviderCapabilities,
+  ToolResult,
+  WebFetchOptions,
+  BatchOp,
+  BatchResult,
+} from '../interfaces/tool-provider';
+
+/**
+ * A tool provider that routes operations to two underlying providers:
+ * - Local provider: Read, Write, Edit, Glob, Grep (project filesystem)
+ * - Sandbox provider: Bash (code execution in sandbox VM)
+ *
+ * Used for skill threads where code runs in sandbox (packages pre-installed)
+ * but file operations target the local project.
+ */
+export class BridgedToolProvider implements ToolProvider {
+  constructor(
+    private readonly local: ToolProvider,
+    private readonly sandbox: ToolProvider,
+  ) {}
+
+  capabilities(): ToolProviderCapabilities {
+    const localCaps = this.local.capabilities();
+    const sandboxCaps = this.sandbox.capabilities();
+    return {
+      bash: sandboxCaps.bash,
+      fileSystem: localCaps.fileSystem,
+      webFetch: localCaps.webFetch || sandboxCaps.webFetch,
+      webSearch: localCaps.webSearch || sandboxCaps.webSearch,
+      codeExecution: sandboxCaps.codeExecution,
+      sandboxed: false, // mixed — not fully sandboxed
+    };
+  }
+
+  // Bash → sandbox (where packages are installed)
+  bash(command: string, options?: BashOptions): Promise<ToolResult> {
+    return this.sandbox.bash(command, options);
+  }
+
+  // File operations → local project
+  readFile(path: string, options?: ReadOptions): Promise<ToolResult> {
+    return this.local.readFile(path, options);
+  }
+
+  writeFile(path: string, content: string): Promise<ToolResult> {
+    return this.local.writeFile(path, content);
+  }
+
+  editFile(path: string, oldText: string, newText: string): Promise<ToolResult> {
+    return this.local.editFile(path, oldText, newText);
+  }
+
+  glob(pattern: string, options?: GlobOptions): Promise<ToolResult> {
+    return this.local.glob(pattern, options);
+  }
+
+  grep(pattern: string, path?: string, options?: GrepOptions): Promise<ToolResult> {
+    return this.local.grep(pattern, path, options);
+  }
+
+  // Web operations → whichever provider has them
+  get webFetch(): ((options: WebFetchOptions) => Promise<ToolResult>) | undefined {
+    return this.local.webFetch ?? this.sandbox.webFetch;
+  }
+
+  get webSearch(): ((query: string) => Promise<ToolResult>) | undefined {
+    return this.local.webSearch ?? this.sandbox.webSearch;
+  }
+
+  // No batch — mixed providers can't batch together
+  get batch(): undefined {
+    return undefined;
+  }
+}

package/src/arc/consolidation.ts

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+import type { Episode, SessionMemo, LongTermMemory, EpisodeStore, SessionMemoStore, LongTermStore } from './arc-types';
+
+/**
+ * Consolidate episodes into a session memo.
+ * Called at task boundaries (async, non-blocking).
+ * Distills key learnings from a set of episodes into a compact memo.
+ */
+export async function consolidateEpisodes(
+  episodes: Episode[],
+  sessionId: string,
+  sessionMemoStore: SessionMemoStore,
+): Promise<SessionMemo> {
+  if (episodes.length === 0) {
+    throw new Error('Cannot consolidate zero episodes');
+  }
+
+  // Template-based consolidation: extract key patterns from episodes
+  const filesModified = new Set<string>();
+  const toolsUsed = new Set<string>();
+  const actions: string[] = [];
+  let successCount = 0;
+
+  for (const ep of episodes) {
+    for (const f of ep.filesModified) filesModified.add(f);
+    for (const t of ep.toolCalls) toolsUsed.add(t);
+    actions.push(`${ep.index}. ${ep.threadAction} (${ep.success ? 'ok' : 'failed'})`);
+    if (ep.success) successCount++;
+  }
+
+  const parts: string[] = [
+    `Task summary (${episodes.length} threads, ${successCount} succeeded):`,
+    ...actions,
+  ];
+
+  if (filesModified.size > 0) {
+    parts.push(`Files modified: ${[...filesModified].join(', ')}`);
+  }
+  if (toolsUsed.size > 0) {
+    parts.push(`Tools used: ${[...toolsUsed].join(', ')}`);
+  }
+
+  const memo: SessionMemo = {
+    id: randomUUID(),
+    sessionId,
+    content: parts.join('\n'),
+    sourceEpisodeIds: episodes.map(e => e.id),
+    createdAt: Date.now(),
+  };
+
+  await sessionMemoStore.addMemo(memo);
+  return memo;
+}
+
+/**
+ * Consolidate session memos into long-term memories.
+ * Called at session boundaries (async, non-blocking).
+ * Extracts durable patterns/learnings from session work.
+ */
+export async function consolidateMemos(
+  memos: SessionMemo[],
+  longTermStore: LongTermStore,
+): Promise<LongTermMemory[]> {
+  if (memos.length === 0) return [];
+
+  // Check for duplicate consolidation
+  const existingMemories = await longTermStore.getAllMemories();
+  const existingSourceIds = new Set<string>();
+  for (const mem of existingMemories) {
+    for (const id of mem.sourceSessionMemoIds) {
+      existingSourceIds.add(id);
+    }
+  }
+
+  // Filter out already-consolidated memos
+  const newMemos = memos.filter(m => !existingSourceIds.has(m.id));
+  if (newMemos.length === 0) return [];
+
+  // Template-based: create one long-term memory summarizing the session
+  const now = Date.now();
+  const sessionContent = newMemos.map(m => m.content).join('\n---\n');
+
+  const memory: LongTermMemory = {
+    id: randomUUID(),
+    content: `Session work:\n${sessionContent}`,
+    category: 'session-summary',
+    sourceSessionMemoIds: newMemos.map(m => m.id),
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  await longTermStore.addMemory(memory);
+  return [memory];
+}
+
+/**
+ * Full consolidation pipeline: episodes → memo → long-term.
+ * Designed to be called as fire-and-forget at task/session boundaries.
+ */
+export async function runConsolidation(
+  taskId: string,
+  sessionId: string,
+  episodeStore: EpisodeStore,
+  sessionMemoStore: SessionMemoStore,
+  longTermStore: LongTermStore,
+): Promise<void> {
+  // 1. Consolidate task episodes into session memo
+  const episodes = await episodeStore.getEpisodesByTask(taskId);
+  if (episodes.length > 0) {
+    await consolidateEpisodes(episodes, sessionId, sessionMemoStore);
+  }
+
+  // 2. Consolidate session memos into long-term memory
+  const memos = await sessionMemoStore.getMemosBySession(sessionId);
+  if (memos.length > 0) {
+    await consolidateMemos(memos, longTermStore);
+  }
+}

package/src/arc/create-arc-agent.ts

@@ -0,0 +1,80 @@
+import { createAgent, type AgentRuntime } from '../agent/create-agent';
+import type { AgentMessage, AgentStreamEvent } from '../agent/types';
+import type { ArcLoopConfig } from './arc-types';
+import { ArcLoop } from './arc-loop';
+import { runConsolidation } from './consolidation';
+
+export interface ArcAgentConfig extends ArcLoopConfig {
+  /** Max steps for the outer agent loop (default: 1, since ArcLoop runs internally) */
+  maxOuterSteps?: number;
+}
+
+/**
+ * Create an agent powered by the ArcLoop orchestrator.
+ *
+ * The returned agent has the same interface as a regular `createAgent()` agent
+ * (run/stream), but internally uses the orchestrator → thread architecture.
+ *
+ * Consolidation runs automatically in the background after each run() completes.
+ *
+ * Note: `stream()` drives ArcLoop.streamAction() directly rather than going
+ * through createAgent's stream(), because ArcLoop executes Thread tool calls
+ * internally — createAgent would try to re-execute them via the toolProvider.
+ */
+export function createArcAgent(config: ArcAgentConfig) {
+  const arcLoop = new ArcLoop(config);
+
+  const runtime: AgentRuntime = {
+    toolProvider: config.toolProvider,
+    loop: arcLoop,
+    // ArcLoop.nextAction() runs the full orchestration internally,
+    // so the outer agent only needs 1 step.
+    maxSteps: config.maxOuterSteps ?? 1,
+  };
+
+  // run() uses createAgent which calls arcLoop.nextAction() → returns FinalAction. Works.
+  const agent = createAgent(runtime);
+
+  function fireConsolidation(): void {
+    runConsolidation(
+      config.taskId,
+      config.sessionId,
+      config.episodeStore,
+      config.sessionMemoStore,
+      config.longTermStore,
+    ).catch(() => {
+      // Consolidation failure is non-critical
+    });
+  }
+
+  return {
+    async run(prompt: string, options?: { history?: AgentMessage[] }) {
+      const result = await agent.run(prompt, options);
+      fireConsolidation();
+      return result;
+    },
+
+    /**
+     * Stream orchestration events directly from ArcLoop.
+     *
+     * Yields the standard AgentStreamEvent types:
+     * - text_delta: orchestrator reasoning
+     * - tool_start/tool_end: thread dispatch & completion (name='Thread')
+     * - step_start/step_end: orchestrator turns
+     * - done: orchestration complete
+     */
+    async *stream(
+      prompt: string,
+      options?: { history?: AgentMessage[] },
+    ): AsyncGenerator<AgentStreamEvent> {
+      const history = options?.history ?? [];
+      const messages: AgentMessage[] = [
+        ...history,
+        { role: 'user', content: prompt },
+      ];
+
+      yield* arcLoop.streamAction(messages);
+      fireConsolidation();
+    },
+  };
+}