@bluecopa/harness 0.1.0-snapshot.131 → 0.1.0-snapshot.133

package/dist/arc/index.d.ts

@@ -0,0 +1,969 @@
+import { A as AnyTool, T as ToolProvider, a as ToolResult, M as ModelFactory, b as ToolResultArtifact, c as ToolChoiceConfig } from '../shared-types-C6QKEEsw.js';
+export { d as ActionType, B as BashOptions, e as BatchOp, f as BatchResult, G as GlobOptions, g as GrepOptions, R as ReadOptions, h as TextEditorRequest, i as ThreadStatus, j as ToolChoiceValue, k as ToolProviderCapabilities, W as WebFetchOptions, r as resolveToolChoice } from '../shared-types-C6QKEEsw.js';
+import * as ai from 'ai';
+
+interface ToolCallInfo {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    /** Provider-specific metadata preserved across round-trips (e.g., Gemini thought signatures). */
+    providerMetadata?: Record<string, unknown>;
+}
+interface ToolResultInfo {
+    toolCallId: string;
+    toolName: string;
+    result: string;
+    isError?: boolean;
+    durationMs?: number;
+}
+type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    image: Buffer | Uint8Array;
+    mimeType: string;
+};
+interface AgentMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ContentPart[];
+    toolCalls?: ToolCallInfo[];
+    toolResults?: ToolResultInfo[];
+    /** Provider-specific metadata preserved across round-trips (e.g., Gemini thought signatures). */
+    providerMetadata?: Record<string, unknown>;
+}
+interface ToolCallAction {
+    type: "tool";
+    name: string;
+    args: Record<string, unknown>;
+    toolCallId?: string;
+    /** Provider-specific metadata preserved across round-trips (e.g., Gemini thought signatures). */
+    providerMetadata?: Record<string, unknown>;
+    /** Short user-visible rationale text emitted before the tool call. */
+    publicRationale?: string;
+}
+interface FinalAction {
+    type: "final";
+    content: string;
+}
+interface ToolBatchAction {
+    type: "tool_batch";
+    calls: ToolCallAction[];
+    /** Short user-visible rationale text emitted before the tool batch. */
+    publicRationale?: string;
+}
+type AgentAction = ToolCallAction | FinalAction | ToolBatchAction;
+/** Token usage breakdown for a single LLM step. */
+interface StepUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+type AgentStreamEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_start";
+    name: string;
+    args: Record<string, unknown>;
+    toolCallId?: string;
+} | {
+    type: "tool_end";
+    name: string;
+    result: {
+        success: boolean;
+        output: string;
+        error?: string;
+        [key: string]: unknown;
+    };
+} | {
+    type: "step_start";
+    step: number;
+} | {
+    type: "step_end";
+    step: number;
+    usage?: StepUsage;
+} | {
+    type: "done";
+    output: string;
+    steps: number;
+};
+interface AgentLoop {
+    nextAction(messages: AgentMessage[], signal?: AbortSignal): Promise<AgentAction>;
+    streamAction?(messages: AgentMessage[]): AsyncIterable<AgentStreamEvent>;
+}
+/** Context passed to `prepareStep` before each LLM call. */
+interface PrepareStepContext {
+    stepNumber: number;
+    toolCallHistory: string[];
+}
+/** Overrides returned by `prepareStep`. All fields optional — omit to keep defaults. */
+interface PrepareStepResult {
+    model?: string;
+    activeTools?: string[];
+}
+
+/**
+ * Tool registry: the Tool contract and schema extraction.
+ *
+ * Agent tool definitions (Bash, Read, Write, etc.) live in the consumer
+ * (truecode). The harness only provides the Tool contract and helpers.
+ */
+
+/** A registered tool: schema for the model, execute for the worker */
+interface Tool {
+    name: string;
+    /** AI SDK tool schema. Optional for ARC-internal tools (ReadEpisode, LCM_*, ScratchPad_*). */
+    schema?: AnyTool | undefined;
+    /** Execute using the ToolProvider. If not set, tool is handled externally (e.g. ARC tools). */
+    execute?: (provider: ToolProvider, args: Record<string, unknown>, workDir: string) => Promise<ToolResult>;
+}
+/** Get only the AI SDK tool schemas from a registry (skips tools without schemas) */
+declare function toolSchemasFromRegistry(registry: Map<string, Tool>): Record<string, AnyTool>;
+
+interface StoredMessage {
+    id: string;
+    conversationId: string;
+    index: number;
+    role: "user" | "assistant" | "tool";
+    content: string;
+    toolCalls?: ToolCallInfo[];
+    toolResults?: ToolResultInfo[];
+    timestamp: number;
+}
+interface GrepResult {
+    messageId: string;
+    conversationId: string;
+    messageIndex: number;
+    excerpt: string;
+    matchContext: string;
+}
+interface MessageStore {
+    append(message: StoredMessage): void;
+    getConversation(conversationId: string): StoredMessage[];
+    getMessage(conversationId: string, index: number): StoredMessage | null;
+    grep(pattern: string, opts?: {
+        conversationId?: string;
+        maxResults?: number;
+    }): GrepResult[];
+}
+declare class MemoryMessageStore implements MessageStore {
+    private messages;
+    private byConversation;
+    append(message: StoredMessage): void;
+    getConversation(conversationId: string): StoredMessage[];
+    getMessage(conversationId: string, index: number): StoredMessage | null;
+    grep(pattern: string, opts?: {
+        conversationId?: string;
+        maxResults?: number;
+    }): GrepResult[];
+}
+
+interface SummaryNode {
+    id: string;
+    depth: number;
+    sourceIds: string[];
+    sourceConversationIds: string[];
+    summary: string;
+    artifacts: string[];
+    operations: string[];
+    outcome: string;
+    tokenCount: number;
+    createdAt: number;
+}
+interface CompactionOpts {
+    /** Minimum number of uncovered children before compaction triggers (default: 4) */
+    minChildren?: number;
+    /** Soft token budget — compact when total tokens at a depth exceed this (default: 8000) */
+    softTokenBudget?: number;
+}
+interface SummaryDAG {
+    addLeaf(node: SummaryNode): void;
+    compact(opts?: CompactionOpts): SummaryNode[];
+    getNode(id: string): SummaryNode | undefined;
+    getLineage(id: string, visited?: Set<string>): string[];
+    getFrontier(budget: number): SummaryNode[];
+    getCoveredIds(frontier: SummaryNode[]): Set<string>;
+    getAllNodes(): SummaryNode[];
+}
+declare class MemorySummaryDAG implements SummaryDAG {
+    private nodes;
+    /** Tracks which source IDs have been covered by a parent node */
+    private coveredBy;
+    addLeaf(node: SummaryNode): void;
+    compact(opts?: CompactionOpts): SummaryNode[];
+    getNode(id: string): SummaryNode | undefined;
+    getLineage(id: string, visited?: Set<string>): string[];
+    getFrontier(budget: number): SummaryNode[];
+    /** Returns the coverage set of all node IDs transitively covered by frontier nodes */
+    getCoveredIds(frontier: SummaryNode[]): Set<string>;
+    getAllNodes(): SummaryNode[];
+}
+
+interface GhostCue {
+    summaryId: string;
+    conversationIds: string[];
+    depth: number;
+    label: string;
+}
+interface AssembledContext {
+    messages: AgentMessage[];
+    ghostCues: GhostCue[];
+    tokenEstimate: number;
+    /** Structured sections for downstream consumers (avoids string matching) */
+    frontierText?: string;
+    ghostCueText?: string;
+}
+interface AssembleContextOpts {
+    conversationId: string;
+    store: MessageStore;
+    dag: SummaryDAG;
+    budget: number;
+    freshTailSize: number;
+    taskContext: string;
+    ooda?: OodaSnapshot;
+}
+/**
+ * Budget-driven context assembly from MessageStore + SummaryDAG.
+ *
+ * Algorithm:
+ * 1. Always include: task context (task, workspace, budget info)
+ * 2. Fresh tail: last N raw messages from the conversation
+ * 3. Frontier: walk DAG from deepest summaries, adding within budget
+ * 4. Ghost cues: for any DAG region not expanded, insert a pointer
+ * 5. OODA snapshot if provided
+ */
+declare function assembleContext(opts: AssembleContextOpts): AssembledContext;
+interface AssembleWorkerContextOpts {
+    store: MessageStore;
+    dag: SummaryDAG;
+    budget: number;
+    taskContext: string;
+    instruction: string;
+    vectorIndex?: VectorIndex;
+    transcriptStore?: TranscriptStore;
+    scratchPad?: ScratchPad;
+}
+/**
+ * Assemble context specifically for a worker dispatch.
+ * Workers get: task context + relevant prior summaries + vector retrieval + scratch notes.
+ */
+declare function assembleWorkerContext(opts: AssembleWorkerContextOpts): Promise<AssembledContext>;
+
+type HookEventName = 'PreToolUse' | 'PostToolUse' | 'BeforeWorker' | 'AfterWorker';
+interface HookContext {
+    event: HookEventName;
+    toolName?: string;
+    input?: Record<string, unknown>;
+    output?: ToolResult;
+    metadata?: Record<string, unknown>;
+}
+interface HookDecision {
+    allow: boolean;
+    reason?: string;
+}
+type HookCallback = (context: HookContext) => Promise<HookDecision | void>;
+
+declare class HookRunner {
+    private readonly hooks;
+    register(event: HookContext['event'], callback: HookCallback): void;
+    run(context: HookContext): Promise<HookDecision>;
+}
+
+/** Raw worker transcript, append-only storage */
+interface Transcript {
+    id: string;
+    tupleId: string;
+    instruction: string;
+    messages: AgentMessage[];
+    timestamp: number;
+}
+/** Artifact produced by a worker dispatch */
+interface Artifact {
+    id: string;
+    tupleId: string;
+    /** File path or returned value */
+    output: string | null;
+    /** Full textual worker result, preserved even when expected file artifacts are missing */
+    textOutput?: string | undefined;
+    status: "complete" | "incomplete" | "failed" | "interrupted";
+    /** One-line summary from worker's final message */
+    summary: string;
+    stepsUsed: number;
+    /** Tool calls with results (for orchestrator reasoning) */
+    actions?: string[];
+    /** The dispatch instruction that produced this artifact */
+    instruction?: string;
+}
+interface ExpectedArtifact {
+    type: "file" | "directory" | "value" | "unknown";
+    path?: string | undefined;
+    description?: string | undefined;
+}
+interface ExpectedOutputContract {
+    artifacts: ExpectedArtifact[];
+    successCriteria?: string[] | undefined;
+    verification?: string | undefined;
+    description?: string | undefined;
+}
+/** Worker instruction tuple */
+interface Tuple {
+    id: string;
+    instruction: string;
+    /** Artifact IDs to provide as input */
+    inputs: string[];
+    /** Structured contract for what the worker should produce */
+    expectedOutput: ExpectedOutputContract;
+    /** Tool names available to worker */
+    tools: string[];
+    /** Step budget (1-10) */
+    steps: number;
+    /** Public orchestrator rationale that preceded this dispatch */
+    orchestratorContext?: string | undefined;
+}
+interface DispatchRecord {
+    tuple: Tuple;
+    artifact: Artifact;
+    transcript: Transcript;
+    progress: WorkerProgressEvent[];
+    completedAt: number;
+    /** Worker execution result (artifacts, actions, status) */
+    workerResult?: WorkerResult | undefined;
+}
+interface OodaSnapshot {
+    observations: string[];
+    beliefs: string[];
+    disprovenApproaches: string[];
+    blockers: string[];
+    decisionPressure: {
+        turn: number;
+        maxTurns: number;
+        turnsRemaining: number;
+        dispatchCount: number;
+        allIncomplete: boolean;
+    };
+}
+type ReadEpisodeDetail = "summary" | "trace" | "artifacts";
+interface ReadEpisodeArgs {
+    id: string;
+    detail?: ReadEpisodeDetail | undefined;
+    artifactKey?: string | undefined;
+    maxTokens?: number | undefined;
+}
+interface TraceToolCall {
+    toolName: string;
+    toolCallId?: string | undefined;
+    args: Record<string, unknown>;
+}
+type ArcTraceEvent = {
+    scope: "orchestrator";
+    phase: "model_input";
+    turn: number;
+    model: string;
+    system: string;
+    /** Full AgentMessage context before SDK conversion. */
+    messages: AgentMessage[];
+    /** Full SDK-facing messages after conversion. */
+    modelMessages: unknown[];
+    toolNames: string[];
+} | {
+    scope: "orchestrator";
+    phase: "model_output";
+    turn: number;
+    text: string;
+    toolCalls: TraceToolCall[];
+} | {
+    scope: "orchestrator";
+    phase: "public_rationale_missing";
+    turn: number;
+    toolCalls: TraceToolCall[];
+} | {
+    scope: "orchestrator";
+    phase: "tool_call";
+    turn: number;
+    toolName: string;
+    args: Record<string, unknown>;
+} | {
+    scope: "orchestrator";
+    phase: "tool_result";
+    turn: number;
+    toolName: string;
+    args: Record<string, unknown>;
+    result: unknown;
+} | {
+    scope: "worker";
+    phase: "model_input";
+    tupleId: string;
+    step: number;
+    model: string;
+    system: string;
+    messages: AgentMessage[];
+    toolNames: string[];
+} | {
+    scope: "worker";
+    phase: "model_output";
+    tupleId: string;
+    step: number;
+    action: unknown;
+} | {
+    scope: "worker";
+    phase: "public_rationale_missing";
+    tupleId: string;
+    step: number;
+    toolNames: string[];
+} | {
+    scope: "worker";
+    phase: "tool_call";
+    tupleId: string;
+    step: number;
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+} | {
+    scope: "worker";
+    phase: "tool_result";
+    tupleId: string;
+    step: number;
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    resultText: string;
+} | {
+    scope: "worker";
+    phase: "worker_result";
+    tupleId: string;
+    result: unknown;
+};
+interface TranscriptStore {
+    append(transcript: Transcript): Promise<void>;
+    getAll(): Promise<Transcript[]>;
+    get(id: string): Promise<Transcript | null>;
+}
+interface VectorIndex {
+    add(id: string, text: string): Promise<void>;
+    search(query: string, k: number): Promise<string[]>;
+    load(): Promise<void>;
+    save(): Promise<void>;
+}
+interface ArtifactStore {
+    set(id: string, artifact: Artifact): Promise<void>;
+    get(id: string): Promise<Artifact | null>;
+    getAll(): Promise<Record<string, Artifact>>;
+}
+interface ScratchPad {
+    write(key: string, content: string): Promise<void>;
+    read(key: string): Promise<string | null>;
+    list(): Promise<string[]>;
+}
+/** What the orchestrator sees each turn */
+interface OrchestratorContext {
+    task: string;
+    artifacts: Record<string, Artifact>;
+    lastResult: Artifact | null;
+    /** Rolling window of recent orchestrator messages */
+    recentTurns: AgentMessage[];
+    /** Current turn number */
+    turn: number;
+    /** Max turns allowed */
+    maxTurns: number;
+    /** Turns remaining after the current turn */
+    turnsRemaining: number;
+    /** Number of dispatches so far */
+    dispatchCount: number;
+    /** Number of dispatches since the orchestrator has not emitted done yet */
+    dispatchesWithoutFinalAnswer: number;
+    /** Artifact status counts across all completed dispatches */
+    artifactStatusCounts: Record<Artifact["status"], number>;
+    /** True while the orchestrator has not emitted the final done output */
+    noFinalAnswerYet: boolean;
+    /** True when no dispatch artifact has reached complete status */
+    allIncomplete: boolean;
+    /** Completed dispatches in chronological order */
+    dispatches: DispatchRecord[];
+    /** Current observe/orient state rendered into the orchestrator prompt */
+    ooda: OodaSnapshot;
+    /** LCM message store (all conversations) */
+    messageStore?: MessageStore | undefined;
+    /** LCM summary DAG */
+    summaryDAG?: SummaryDAG | undefined;
+    /** Ghost cues for compacted regions */
+    ghostCues?: GhostCue[] | undefined;
+}
+
+interface ArcConfig {
+    task: string;
+    workDir: string;
+    /** Model ID for the orchestrator */
+    model: string;
+    /** Model ID for workers */
+    workerModel: string;
+    createModel?: ModelFactory;
+    toolProvider: ToolProvider;
+    /** Agent-provided tool definitions (Bash, Read, Write, etc.) with schemas, execute, and artifact metadata. Harness adds ARC framework tools internally. */
+    tools?: Map<string, Tool> | undefined;
+    /** Max orchestrator turns before stopping (default: 12) */
+    maxTurns?: number;
+    /** Max steps per worker (default: 5, max: 10) */
+    maxStepsPerWorker?: number;
+    /** Rolling window size for orchestrator context (default: 10) */
+    orchestratorWindowSize?: number;
+    /** Directory where agent memory lives (default: workDir/.arc) */
+    memDir?: string;
+    /** Injected vector index (default: in-memory for tests) */
+    vectorIndex?: VectorIndex;
+    /** Injected scratch pad for inter-worker note sharing (default: in-memory for tests) */
+    scratchPad?: ScratchPad;
+    /** Injected transcript store (default: in-memory) */
+    transcriptStore?: TranscriptStore;
+    /** Injected artifact store (default: in-memory) */
+    artifactStore?: ArtifactStore;
+    /** Custom worker system prompt (appended to default) */
+    workerSystemPromptSuffix?: string | undefined;
+    /** Custom messages after the core task/budget block */
+    formatOrchestratorContext?: ((context: OrchestratorContext) => AgentMessage[]) | undefined;
+    /** Provider options passed to generateText (e.g. reasoningEffort for OpenAI). */
+    providerOptions?: Record<string, unknown> | undefined;
+    /** Optional hook runner for PreToolUse/PostToolUse/BeforeWorker/AfterWorker events */
+    hookRunner?: HookRunner | undefined;
+    /** Callback for AskUser orchestrator tool. If provided, AskUser is available to the orchestrator. */
+    askUser?: ((question: string, options?: string[]) => Promise<string>) | undefined;
+}
+type ArcEvent = {
+    type: "orchestrator_turn";
+    turn: number;
+    contextTokens: number;
+} | {
+    type: "trace";
+    trace: ArcTraceEvent;
+} | {
+    type: "dispatch";
+    tupleId: string;
+    instruction: string;
+} | {
+    type: "dispatch_full";
+    tuple: Tuple;
+} | {
+    type: "worker_progress";
+    tupleId: string;
+    progress: WorkerProgressEvent;
+} | {
+    type: "worker_complete";
+    tupleId: string;
+    status: Artifact["status"];
+    summary: string;
+    stepsUsed: number;
+    actions?: string[] | undefined;
+} | {
+    type: "recall";
+    query: string;
+    answer: string;
+} | {
+    type: "read_episode";
+    id: string;
+    detail: ReadEpisodeDetail;
+    output: string;
+} | {
+    type: "ask_user";
+    question: string;
+    options?: string[] | undefined;
+} | {
+    type: "done";
+    output: string;
+} | {
+    type: "text_delta";
+    text: string;
+};
+type WorkerProgressEvent = {
+    kind: "model_start";
+    step: number;
+    maxSteps: number;
+} | {
+    kind: "model_complete";
+    step: number;
+    actionType: "final" | "tool" | "tool_batch";
+    durationMs: number;
+    toolNames?: string[] | undefined;
+    publicRationale?: string | undefined;
+    missingPublicRationale?: boolean | undefined;
+    outputSummary?: string | undefined;
+} | {
+    kind: "model_error";
+    step: number;
+    durationMs: number;
+    error: string;
+} | {
+    kind: "tool_start";
+    step: number;
+    toolCallId: string;
+    toolName: string;
+    argsSummary?: string | undefined;
+} | {
+    kind: "tool_complete";
+    step: number;
+    toolCallId: string;
+    toolName: string;
+    success: boolean;
+    durationMs: number;
+    outputSummary: string;
+    output?: string | undefined;
+    exitCode?: unknown;
+} | {
+    kind: "tool_error";
+    step: number;
+    toolCallId: string;
+    toolName: string;
+    durationMs: number;
+    error: string;
+} | {
+    kind: "worker_result";
+    status: "complete" | "incomplete" | "failed" | "interrupted";
+    stepsUsed: number;
+    summary: string;
+};
+interface RunWorkerConfig {
+    /** Original top-level task */
+    task?: string | undefined;
+    instruction: string;
+    /** Structured contract for this dispatch */
+    expectedOutput?: ExpectedOutputContract | undefined;
+    /** LCM-assembled context for this worker */
+    lcmContext?: AssembledContext | undefined;
+    /** Artifact ID -> file content */
+    inputArtifacts: Map<string, string>;
+    tools: Record<string, AnyTool>;
+    /** Tool registry with execute/artifact metadata for dispatch and episode projection */
+    toolRegistry: Map<string, Tool>;
+    maxSteps: number;
+    toolProvider: ToolProvider;
+    createModel: ModelFactory;
+    model: string;
+    workDir: string;
+    signal?: AbortSignal | undefined;
+    /** Extra text prefixed to worker system prompt */
+    systemPromptPrefix?: string | undefined;
+    /** Extra text appended to worker system prompt */
+    systemPromptSuffix?: string | undefined;
+    /** Provider options passed to generateText (e.g. reasoning config). */
+    providerOptions?: Record<string, unknown> | undefined;
+    /** Public orchestrator rationale that preceded this dispatch */
+    orchestratorContext?: string | undefined;
+    /** Tuple id for full-fidelity trace events */
+    tupleId?: string | undefined;
+    /** Optional diagnostic hook for streaming worker internals to the caller */
+    onProgress?: ((event: WorkerProgressEvent) => void) | undefined;
+    /** Optional full-fidelity trace hook for raw model/tool IO */
+    onTrace?: ((event: ArcTraceEvent) => void) | undefined;
+    /** Optional hook runner for PreToolUse/PostToolUse events */
+    hookRunner?: HookRunner | undefined;
+}
+interface WorkerResult {
+    transcript: AgentMessage[];
+    output: string | null;
+    status: "complete" | "incomplete" | "failed" | "interrupted";
+    stepsUsed: number;
+    /** Last message content for summary */
+    lastMessage: string;
+    /** All tool calls with results for orchestrator visibility */
+    actions: string[];
+    /** Artifacts touched during execution (from ToolResult.artifact) */
+    artifacts: ToolResultArtifact[];
+}
+
+interface ArcRunResult {
+    output: string;
+    events: ArcEvent[];
+}
+declare class ArcLoop {
+    private readonly config;
+    private readonly transcriptStore;
+    private readonly vectorIndex;
+    private readonly scratchPad;
+    private readonly artifactStore;
+    private readonly messageStore;
+    private readonly summaryDAG;
+    private readonly createModel;
+    private readonly windowSize;
+    private readonly model;
+    /** Orchestrator tool schemas (for the model) */
+    private readonly orchestratorToolSchemas;
+    /** Orchestrator tool registry (for execute) — excludes dispatch/done (control flow) */
+    private readonly orchestratorToolRegistry;
+    /** Dispatcher deps + mutable state — shared with dispatcher.ts functions */
+    private readonly dispatchDeps;
+    private readonly dispatchState;
+    private orchestratorMessageIndex;
+    private turn;
+    /** Per-turn abort controller — cancelled by interrupt(), refreshed each turn. */
+    private turnController;
+    constructor(config: ArcConfig);
+    /**
+     * Interrupt the current turn — cancels in-flight model calls and workers.
+     * The orchestrator loop stays alive and will prompt for user steering.
+     */
+    interrupt(): void;
+    /**
+     * Stream events from the orchestration loop.
+     */
+    stream(signal?: AbortSignal): AsyncGenerator<ArcEvent>;
+    /**
+     * Run the orchestration loop to completion.
+     */
+    run(signal?: AbortSignal): Promise<ArcRunResult>;
+    /** Append a message to the LCM message store (single source of truth) */
+    private appendOrchestratorMessage;
+    private findEpisodeRecordBySummaryId;
+    private buildContext;
+    private buildOrchestratorMessages;
+    private buildTaskContextText;
+    private readEpisode;
+    /**
+     * Handle a turn interrupt: prompt user for steering, inject into context.
+     */
+    private handleInterrupt;
+}
+
+type ModelMessage = any;
+/**
+ * Convert AgentMessage[] to Vercel AI SDK ModelMessage[].
+ * Extracted from VercelAgentLoop — identical logic, standalone pure function.
+ *
+ * System messages that appear after user/assistant/tool messages are
+ * converted to user messages with a [System] prefix. The Anthropic API
+ * does not allow interleaved system messages; the actual system prompt
+ * is passed separately via the `system` parameter.
+ */
+declare function toModelMessages(messages: AgentMessage[]): ModelMessage[];
+
+/**
+ * Episode projection: minimal formatting for orchestrator context.
+ *
+ * The worker collects artifacts and actions during execution.
+ * This module just formats DispatchRecords for the orchestrator prompt.
+ */
+
+/** Format a single dispatch record for the orchestrator prompt */
+declare function formatDispatchForPrompt(record: DispatchRecord, options?: {
+    compact?: boolean;
+    maxChars?: number;
+}): string;
+/** Build OODA snapshot from dispatch records — reads WorkerResult directly */
+declare function buildOodaSnapshot(input: {
+    turn: number;
+    maxTurns: number;
+    turnsRemaining: number;
+    dispatchCount: number;
+    allIncomplete: boolean;
+    dispatches: DispatchRecord[];
+}): OodaSnapshot;
+declare function formatOodaSnapshotForPrompt(snapshot: OodaSnapshot): string;
+declare function formatReadEpisodeResult(record: DispatchRecord): string;
+declare function formatTranscriptTrace(messages: AgentMessage[], toolResultLimit: number): string;
+
+/** Dispatch a worker to accomplish a task */
+declare const dispatch: ai.Tool<{
+    instruction: string;
+    expectedOutput: string | {
+        artifacts?: {
+            type: "unknown" | "file" | "directory" | "value";
+            path?: string | undefined;
+            description?: string | undefined;
+        }[] | undefined;
+        successCriteria?: string[] | undefined;
+        verification?: string | undefined;
+        description?: string | undefined;
+        kind?: "unknown" | "file" | "value" | "files" | undefined;
+        path?: string | undefined;
+        paths?: string[] | undefined;
+    };
+    inputs?: string[] | undefined;
+}, never>;
+/** Mark task complete and return final output */
+declare const done: ai.Tool<{
+    output: string;
+}, never>;
+interface ArcToolDeps {
+    readEpisode?: (args: ReadEpisodeArgs) => Promise<string>;
+    historySearch?: (pattern: string, opts?: {
+        conversationId?: string;
+        maxResults?: number;
+    }) => GrepResult[];
+    historyExpand?: (summaryId: string, maxTokens?: number) => string;
+    historyOverview?: (summaryId?: string) => string;
+    historyRead?: (conversationId: string, messageIndex: number) => string | null;
+    scratchPad?: ScratchPad;
+    recall?: (query: string) => Promise<string>;
+    askUser?: (question: string, options?: string[]) => Promise<string>;
+}
+/** Build worker-facing ARC tools with execute closures */
+declare function buildWorkerToolEntries(deps: ArcToolDeps): Map<string, Tool>;
+/** Build orchestrator-facing ARC tools with execute closures (excludes dispatch/done which are control flow) */
+declare function buildOrchestratorToolEntries(deps: ArcToolDeps): Map<string, Tool>;
+
+/**
+ * Build a depth-0 (leaf) summary node from a completed dispatch record.
+ * Reads artifacts and actions directly from the worker result.
+ */
+declare function buildLeafSummary(record: DispatchRecord): SummaryNode;
+
+interface LcmToolDeps {
+    messageStore: MessageStore;
+    summaryDAG: SummaryDAG;
+    vectorIndex: VectorIndex;
+    transcriptStore: TranscriptStore;
+    /** Needed for expandSummary fallback when message store has no messages for a leaf */
+    findDispatchRecord: (summaryId: string) => DispatchRecord | undefined;
+}
+/** Expand a summary node — leaf nodes return source transcript, rollups return child summaries */
+declare function expandSummary(deps: LcmToolDeps, summaryId: string, maxTokens: number): string;
+/** Describe a summary node's metadata, or show DAG overview */
+declare function describeSummary(deps: LcmToolDeps, summaryId?: string): string;
+/** Direct vector search recall — returns matching transcript excerpts */
+declare function recallDirect(deps: LcmToolDeps, query: string): Promise<string>;
+/** Read a specific message from the message store at full fidelity */
+declare function historyRead(deps: LcmToolDeps, conversationId: string, messageIndex: number): string | null;
+/** Search across all stored messages from all conversations */
+declare const history_search: ai.Tool<{
+    pattern: string;
+    conversationId?: string | undefined;
+    maxResults?: number | undefined;
+}, never>;
+/** Expand a summary node back to its source messages or child summaries */
+declare const history_expand: ai.Tool<{
+    summaryId: string;
+    maxTokens?: number | undefined;
+}, never>;
+/** Show summary node metadata or history overview */
+declare const history_overview: ai.Tool<{
+    summaryId?: string | undefined;
+}, never>;
+/** Read a specific message from run history at full fidelity */
+declare const history_read: ai.Tool<{
+    conversationId: string;
+    messageIndex: number;
+}, never>;
+
+declare function cloneForTrace<T>(value: T): T;
+declare function normalizeReadEpisodeArgs(args: Record<string, unknown>): ReadEpisodeArgs;
+
+/** In-memory transcript store for testing */
+declare class MemoryTranscriptStore implements TranscriptStore {
+    private transcripts;
+    private byId;
+    append(transcript: Transcript): Promise<void>;
+    getAll(): Promise<Transcript[]>;
+    get(id: string): Promise<Transcript | null>;
+}
+/** In-memory vector index for testing (no actual embeddings) */
+declare class MemoryVectorIndex implements VectorIndex {
+    private entries;
+    add(id: string, text: string): Promise<void>;
+    search(query: string, k: number): Promise<string[]>;
+    load(): Promise<void>;
+    save(): Promise<void>;
+}
+/** In-memory scratch pad for testing */
+declare class MemoryScratchPad implements ScratchPad {
+    private entries;
+    write(key: string, content: string): Promise<void>;
+    read(key: string): Promise<string | null>;
+    list(): Promise<string[]>;
+}
+/** In-memory artifact store for testing */
+declare class MemoryArtifactStore implements ArtifactStore {
+    private artifacts;
+    set(id: string, artifact: Artifact): Promise<void>;
+    get(id: string): Promise<Artifact | null>;
+    getAll(): Promise<Record<string, Artifact>>;
+}
+
+/**
+ * File-based transcript store.
+ * Stores transcripts as individual JSON files in a directory.
+ */
+declare class FsTranscriptStore implements TranscriptStore {
+    private readonly dir;
+    private readonly indexPath;
+    private index;
+    private loaded;
+    constructor(dir: string);
+    append(transcript: Transcript): Promise<void>;
+    getAll(): Promise<Transcript[]>;
+    get(id: string): Promise<Transcript | null>;
+    private ensureLoaded;
+}
+/**
+ * File-based artifact store.
+ * Stores artifacts in a single JSON file.
+ */
+declare class FsArtifactStore implements ArtifactStore {
+    private readonly filePath;
+    private artifacts;
+    private loaded;
+    constructor(filePath: string);
+    set(id: string, artifact: Artifact): Promise<void>;
+    get(id: string): Promise<Artifact | null>;
+    getAll(): Promise<Record<string, Artifact>>;
+    private ensureLoaded;
+    private save;
+}
+
+/**
+ * Run a stateless worker with the given configuration.
+ * Workers see only: instruction, input artifacts, and tools.
+ */
+declare function runWorker(config: RunWorkerConfig): Promise<WorkerResult>;
+
+declare const ORCHESTRATOR_SYSTEM_PROMPT = "You accomplish tasks by dispatching workers and synthesizing results.\n\nDispatch workers for anything requiring tool use. Answer directly with done for questions you can answer from knowledge or prior results.\n\nWorkers are stateless \u2014 they see only their instruction, input artifacts, and tools. They also have access to history and scratch pad tools, so you don't need to repeat everything.\n\nOlder context gets compacted into summaries. Use history_search to find specific prior results, history_read for full content, and history_expand to restore compacted summaries.\n\nBefore dispatching, check what prior workers attempted. Do not repeat failed approaches \u2014 change strategy or decompose differently.\n\nExplain your reasoning before each tool call.\n\nCall done as soon as the task is satisfied. Re-dispatching costs turns \u2014 only follow up if the result is incomplete, failed, or clearly wrong.";
+declare const WORKER_SYSTEM_PROMPT = "Complete the instruction using the available tools. Workers are stateless and cannot interact with the user \u2014 assume reasonable defaults and proceed.\n\nBefore starting, check ScratchPad_List for notes from prior workers and use history_search to find relevant prior attempts.\n\nIf you are running low on steps, stop and write your progress to ScratchPad_Write \u2014 this is more valuable than one more attempt.\n\nBefore finishing, verify your work against the expected output contract. If verification fails, fix it.\n\nExplain your reasoning before each tool call.";
+
+/** A system prompt block with optional Anthropic cache control. */
+interface SystemPromptBlock {
+    text: string;
+    cacheControl?: {
+        type: "ephemeral";
+    };
+}
+interface VercelAgentLoopConfig {
+    model?: string;
+    /** System prompt — string or structured blocks with cache control markers. */
+    systemPrompt?: string | SystemPromptBlock[];
+    createModel?: ModelFactory;
+    /** @deprecated Prefer createModel. */
+    apiKey?: string;
+    /** Custom tool definitions. If provided, replaces built-in agentTools for LLM calls. */
+    tools?: Record<string, AnyTool>;
+    /** Tool choice for LLM calls. Supports per-turn callbacks. Default: 'auto'. */
+    toolChoice?: ToolChoiceConfig;
+    /** Provider options passed to generateText/streamText (e.g. anthropic thinking config). */
+    providerOptions?: Record<string, unknown>;
+    /** Per-step callback to override model and active tools before each LLM call. */
+    prepareStep?: (context: PrepareStepContext) => PrepareStepResult | void;
+}
+declare class VercelAgentLoop implements AgentLoop {
+    private readonly model;
+    private readonly createModel;
+    private readonly systemPrompt;
+    private readonly tools;
+    private readonly validToolNames;
+    private readonly toolChoiceConfig;
+    private readonly providerOptions;
+    private readonly prepareStep;
+    /** Track tool names called across steps for prepareStep context. */
+    private toolCallHistory;
+    private step;
+    /** Last step's token usage — read after nextAction/streamAction completes. */
+    lastUsage: StepUsage | undefined;
+    constructor(config?: VercelAgentLoopConfig);
+    /** Build the `system` parameter for generateText/streamText. */
+    private buildSystemParam;
+    /** Resolve model + tools for this step via prepareStep callback. */
+    private resolveStep;
+    /** Extract StepUsage from AI SDK usage object. */
+    private static extractUsage;
+    nextAction(messages: AgentMessage[], signal?: AbortSignal): Promise<AgentAction>;
+    streamAction(messages: AgentMessage[]): AsyncGenerator<AgentStreamEvent>;
+}
+
+export { AnyTool, type ArcConfig, type ArcEvent, ArcLoop, type ArcRunResult, type ArcToolDeps, type ArcTraceEvent, type Artifact, type ArtifactStore, type AssembleWorkerContextOpts, type AssembledContext, type CompactionOpts, type DispatchRecord, type ExpectedArtifact, type ExpectedOutputContract, FsArtifactStore, FsTranscriptStore, type GhostCue, type GrepResult, type HookCallback, type HookContext, type HookDecision, type HookEventName, HookRunner, type LcmToolDeps, MemoryArtifactStore, MemoryMessageStore, MemoryScratchPad, MemorySummaryDAG, MemoryTranscriptStore, MemoryVectorIndex, type MessageStore, ModelFactory, ORCHESTRATOR_SYSTEM_PROMPT, type OodaSnapshot, type OrchestratorContext, type ReadEpisodeArgs, type ReadEpisodeDetail, type RunWorkerConfig, type ScratchPad, type StoredMessage, type SummaryDAG, type SummaryNode, type SystemPromptBlock, type Tool, ToolChoiceConfig, ToolProvider, ToolResult, ToolResultArtifact, type TraceToolCall, type Transcript, type TranscriptStore, type Tuple, type VectorIndex, VercelAgentLoop, type VercelAgentLoopConfig, WORKER_SYSTEM_PROMPT, type WorkerProgressEvent, type WorkerResult, assembleContext, assembleWorkerContext, buildLeafSummary, buildOodaSnapshot, buildOrchestratorToolEntries, buildWorkerToolEntries, cloneForTrace, describeSummary, dispatch, done, expandSummary, formatDispatchForPrompt, formatOodaSnapshotForPrompt, formatReadEpisodeResult, formatTranscriptTrace, historyRead, history_expand, history_overview, history_read, history_search, normalizeReadEpisodeArgs, recallDirect, runWorker, toModelMessages, toolSchemasFromRegistry };