@bluecopa/harness 0.0.0-snapshot.137 → 0.0.0-snapshot.138

package/dist/arc/index.d.ts

@@ -1,7 +1,90 @@
-import { A as AnyTool, T as ToolProvider, a as ToolResult, M as ModelFactory, b as ToolResultArtifact } from '../shared-types-DRxnerLT.js';
-export { c as ActionType, B as BashOptions, d as BatchOp, e as BatchResult, G as GlobOptions, f as GrepOptions, R as ReadOptions, g as TextEditorRequest, h as ThreadStatus, i as ToolProviderCapabilities, W as WebFetchOptions } from '../shared-types-DRxnerLT.js';
+import { A as AnyTool, T as ToolProvider, a as ToolResult, M as ModelFactory, b as ToolResultArtifact, c as ToolProviderCapabilities, B as BashOptions, R as ReadOptions, G as GlobOptions, d as GrepOptions, e as BatchOp, f as BatchResult } from '../shared-types-D89hqST8.js';
+export { g as ActionType, h as TextEditorRequest, i as ThreadStatus, W as WebFetchOptions } from '../shared-types-D89hqST8.js';
+import { HarnessTelemetry } from '../observability/otel.js';
+export { MetricRecord, SpanHandle, SpanRecord } from '../observability/otel.js';
 import 'ai';
 
+/** Long-running job orchestration primitives. Generic; no coding-agent assumptions. */
+type JobKind = "local" | "remote";
+/** Discriminated on `kind` so remote-only fields only exist on remote transports. */
+type JobTransport = {
+    kind: "local";
+} | {
+    kind: "remote";
+    host: string;
+    user?: string | undefined;
+    keyPath?: string | undefined;
+};
+interface JobSpec {
+    id: string;
+    label: string;
+    command: string;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+    transport: JobTransport;
+    startedAt: number;
+    startedBy?: {
+        tupleId?: string | undefined;
+        turn?: number | undefined;
+    } | undefined;
+}
+type JobState = "running" | "exited" | "failed" | "killed" | "unknown";
+interface JobStatus {
+    spec: JobSpec;
+    state: JobState;
+    /** Local supervisor PID. */
+    pid?: number | undefined;
+    /** Remote parent PID (only set when transport.kind === "remote"). */
+    remotePid?: number | undefined;
+    exitCode?: number | undefined;
+    /** Mirrors spec.startedAt; kept on the status for convenience when reading status without spec unpacking. */
+    startedAt: number;
+    endedAt?: number | undefined;
+    lastSeenAliveAt: number;
+    tailLines: string[];
+    bytesWritten: number;
+}
+type JobEvent = {
+    type: "job_started";
+    status: JobStatus;
+} | {
+    type: "job_output";
+    id: string;
+    chunk: string;
+    at: number;
+} | {
+    type: "job_exited";
+    status: JobStatus;
+} | {
+    type: "job_failed";
+    status: JobStatus;
+    error: string;
+} | {
+    type: "job_killed";
+    status: JobStatus;
+    reason: string;
+};
+interface JobStartOptions {
+    label: string;
+    command: string;
+    transport?: JobTransport | undefined;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+}
+interface JobRegistry {
+    start(opts: JobStartOptions, startedBy?: JobSpec["startedBy"]): Promise<JobStatus>;
+    check(id: string): Promise<JobStatus | null>;
+    cancel(id: string, signal?: "TERM" | "KILL"): Promise<JobStatus | null>;
+    list(): Promise<JobStatus[]>;
+    tail(id: string, lines?: number): Promise<string[]>;
+    waitFor(id: string, signal?: AbortSignal): Promise<JobStatus>;
+    subscribe(handler: (e: JobEvent) => void): () => void;
+    /** Cheap synchronous snapshot — suitable for orchestrator context each turn. */
+    snapshot(): JobStatus[];
+    /** Remove completed/killed/failed jobs older than `olderThanMs` (default 24h). Returns count removed. */
+    prune(olderThanMs?: number): Promise<number>;
+}
+
 interface ToolCallInfo {
     toolCallId: string;
     toolName: string;
@@ -40,15 +123,37 @@ interface AgentMessage {
  * (truecode). The harness only provides the Tool contract and helpers.
  */
 
+type ToolExecutionMode = "serial" | "parallel";
 /** 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;
+    /** Worker execution mode for batched tool calls. Defaults to serial. */
+    executionMode?: ToolExecutionMode | ((args: Record<string, unknown>) => ToolExecutionMode);
     /** 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>;
+    /**
+     * When true, this tool may yield the worker loop if the operation is incomplete.
+     * After execution, the worker checks if the target thread is still running.
+     * If it is and `waitForThread` is available on the ToolProvider, the worker
+     * suspends (does not count a step) until the thread completes.
+     * The tool args must include a `threadId` field for the worker to track.
+     */
+    yieldsOnIncomplete?: boolean | undefined;
 }
 
+/**
+ * Serialized attachment form suitable for JSON persistence. Unlike the in-flight
+ * `ContentPart` (which carries a `Buffer`), the stored form keeps image bytes
+ * base64-encoded so messages round-trip cleanly through session snapshots.
+ * Converted to a real `ContentPart` only when building AgentMessage[] for the model.
+ */
+interface StoredAttachment {
+    type: "image";
+    imageBase64: string;
+    mimeType: string;
+}
 interface StoredMessage {
     id: string;
     conversationId: string;
@@ -57,6 +162,8 @@ interface StoredMessage {
     content: string;
     toolCalls?: ToolCallInfo[];
     toolResults?: ToolResultInfo[];
+    /** Multimodal image attachments. Persisted as base64; converted to ContentPart[] at model-call time. */
+    attachments?: StoredAttachment[];
     timestamp: number;
 }
 interface GrepResult {
@@ -232,7 +339,7 @@ interface ExpectedOutputContract {
     description?: string | undefined;
 }
 /** Worker model tier for dispatch routing. */
-type DispatchTier = "fast" | "strong";
+type DispatchTier = "fast" | "medium" | "strong";
 /** Worker instruction tuple */
 interface Tuple {
     id: string;
@@ -243,12 +350,22 @@ interface Tuple {
     expectedOutput: ExpectedOutputContract;
     /** Tool names available to worker */
     tools: string[];
-    /** Step budget (1-10) */
+    /** Step budget */
     steps: number;
-    /** Worker model tier — 'fast' for simple tasks, 'strong' (default) for complex reasoning. */
+    /** Worker model tier. Omitted dispatches use the default step budget and strong worker model. */
     tier?: DispatchTier | undefined;
+    /** Semantic role label for this worker (e.g. "Debugger", "Researcher", "Sysadmin").
+     *  Shown in the TUI instead of the generic tier name to give the user a clear
+     *  mental model of what the worker is doing. */
+    role?: string | undefined;
     /** Public orchestrator rationale that preceded this dispatch */
     orchestratorContext?: string | undefined;
+    /** Prior tuple this dispatch is continuing from, when ARC resumes internally. */
+    continuationOf?: string | undefined;
+    /** Why ARC created this continuation dispatch. */
+    continuationReason?: "step_budget" | "user_steering" | undefined;
+    /** Compact user-facing checkpoint summary for continuation UI. */
+    continuationSummary?: string | undefined;
 }
 interface DispatchRecord {
     tuple: Tuple;
@@ -260,19 +377,6 @@ interface DispatchRecord {
     /** 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;
@@ -286,6 +390,16 @@ interface TraceToolCall {
     args: Record<string, unknown>;
 }
 type ArcTraceEvent = {
+    scope: "orchestrator";
+    phase: "context_assembled";
+    turn: number;
+    totalChars: number;
+    estimatedTokens: number;
+    sections: Record<string, {
+        chars: number;
+        estimatedTokens: number;
+    }>;
+} | {
     scope: "orchestrator";
     phase: "model_input";
     turn: number;
@@ -341,6 +455,12 @@ type ArcTraceEvent = {
     tupleId: string;
     step: number;
     toolNames: string[];
+} | {
+    scope: "worker";
+    phase: "textual_tool_call_rescued";
+    tupleId: string;
+    step: number;
+    toolNames: string[];
 } | {
     scope: "worker";
     phase: "tool_call";
@@ -374,6 +494,8 @@ interface VectorIndex {
     search(query: string, k: number): Promise<string[]>;
     load(): Promise<void>;
     save(): Promise<void>;
+    /** Number of documents currently indexed. Used to detect empty index on session resume. */
+    size(): Promise<number>;
 }
 interface ArtifactStore {
     set(id: string, artifact: Artifact): Promise<void>;
@@ -433,8 +555,6 @@ interface OrchestratorContext {
     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 */
@@ -443,6 +563,11 @@ interface OrchestratorContext {
 
 interface ArcConfig {
     task: string;
+    /**
+     * Image attachments to inject alongside the initial task when the orchestrator
+     * model is multimodal. Subsequent task attachments flow through pushTask instead.
+     */
+    initialAttachments?: StoredAttachment[] | undefined;
     workDir: string;
     /** Model ID for the orchestrator */
     model: string;
@@ -450,13 +575,15 @@ interface ArcConfig {
     workerModel: string;
     /** Optional per-tier worker model overrides. Falls back to workerModel when a tier is missing. */
     workerModelMap?: Partial<Record<DispatchTier, string>> | undefined;
+    /** Optional per-tier worker step budgets. Falls back to ARC defaults when unset. */
+    workerStepBudgets?: Partial<Record<DispatchTier, number>> | undefined;
     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) */
+    /** Max steps per untiered worker (default: 30). Explicit tiers use workerStepBudgets/default tier budgets. */
     maxStepsPerWorker?: number;
     /** Rolling window size for orchestrator context (default: 10) */
     orchestratorWindowSize?: number;
@@ -470,6 +597,8 @@ interface ArcConfig {
     transcriptStore?: TranscriptStore;
     /** Injected artifact store (default: in-memory) */
     artifactStore?: ArtifactStore;
+    /** Custom orchestrator system prompt (appended to default) */
+    orchestratorSystemPromptSuffix?: string | undefined;
     /** Custom worker system prompt (appended to default) */
     workerSystemPromptSuffix?: string | undefined;
     /** Custom messages after the core task/budget block */
@@ -478,12 +607,18 @@ interface ArcConfig {
     providerOptions?: Record<string, unknown> | undefined;
     /** Optional hook runner for PreToolUse/PostToolUse/BeforeWorker/AfterWorker events */
     hookRunner?: HookRunner | undefined;
+    /** Optional telemetry collector for profiling spans and metrics. */
+    telemetry?: HarnessTelemetry | undefined;
     /** Callback for AskUser orchestrator tool. If provided, AskUser is available to the orchestrator. */
     askUser?: ((question: string, options?: string[]) => Promise<string>) | undefined;
     /** Session store for persistence across restarts. */
     sessionStore?: SessionStore | undefined;
     /** Session ID to resume. If provided with sessionStore, loop hydrates from saved state. */
     sessionId?: string | undefined;
+    /** Job registry for long-running process orchestration. Default: MemoryJobRegistry. */
+    jobRegistry?: JobRegistry | undefined;
+    /** Per model-call timeout in milliseconds. Applied to both orchestrator and worker generateText. Default: 180000 (3 min). */
+    modelCallTimeoutMs?: number | undefined;
 }
 type ArcEvent = {
     type: "orchestrator_turn";
@@ -499,6 +634,12 @@ type ArcEvent = {
 } | {
     type: "dispatch_full";
     tuple: Tuple;
+} | {
+    type: "worker_continuation";
+    tupleId: string;
+    fromTupleId: string;
+    reason: "step_budget" | "user_steering";
+    summary: string;
 } | {
     type: "worker_progress";
     tupleId: string;
@@ -523,11 +664,20 @@ type ArcEvent = {
     type: "ask_user";
     question: string;
     options?: string[] | undefined;
+} | {
+    type: "interrupt_status";
+    summary: string;
 } | {
     type: "orchestrator_usage";
     turn: number;
     inputTokens?: number;
     outputTokens?: number;
+} | {
+    type: "model_heartbeat";
+    scope: "orchestrator" | "worker";
+    model: string;
+    elapsedMs: number;
+    tupleId?: string | undefined;
 } | {
     type: "done";
     output: string;
@@ -537,6 +687,20 @@ type ArcEvent = {
 } | {
     type: "text_delta";
     text: string;
+} | {
+    type: "reasoning_delta";
+    text: string;
+} | {
+    type: "job_event";
+    event: JobEvent;
+} | {
+    type: "interjection_queued";
+    position: number;
+    text: string;
+} | {
+    type: "interjection_delivered";
+    position: number;
+    turn: number;
 };
 type WorkerProgressEvent = {
     kind: "model_start";
@@ -573,7 +737,9 @@ type WorkerProgressEvent = {
     durationMs: number;
     outputSummary: string;
     output?: string | undefined;
+    artifact?: ToolResultArtifact | undefined;
     exitCode?: unknown;
+    metadata?: Record<string, unknown> | undefined;
 } | {
     kind: "tool_error";
     step: number;
@@ -586,6 +752,25 @@ type WorkerProgressEvent = {
     status: "complete" | "incomplete" | "failed" | "interrupted";
     stepsUsed: number;
     summary: string;
+} | {
+    kind: "message_appended";
+    message: AgentMessage;
+} | {
+    kind: "model_heartbeat";
+    step: number;
+    elapsedMs: number;
+} | {
+    kind: "yield_start";
+    step: number;
+    toolCallId: string;
+    toolName: string;
+    threadId: string;
+} | {
+    kind: "yield_resume";
+    step: number;
+    toolCallId: string;
+    toolName: string;
+    threadId: string;
 };
 interface RunWorkerConfig {
     /** Original top-level task */
@@ -608,6 +793,8 @@ interface RunWorkerConfig {
     signal?: AbortSignal | undefined;
     /** Extra text prefixed to worker system prompt */
     systemPromptPrefix?: string | undefined;
+    /** Semantic role label for TUI display (e.g. "Debugger", "Researcher"). */
+    role?: string | undefined;
     /** Extra text appended to worker system prompt */
     systemPromptSuffix?: string | undefined;
     /** Provider options passed to generateText (e.g. reasoning config). */
@@ -622,6 +809,18 @@ interface RunWorkerConfig {
     onTrace?: ((event: ArcTraceEvent) => void) | undefined;
     /** Optional hook runner for PreToolUse/PostToolUse events */
     hookRunner?: HookRunner | undefined;
+    /** Optional telemetry collector for profiling spans and metrics. */
+    telemetry?: HarnessTelemetry | undefined;
+    /** Current sub-dispatch depth (0 = top-level worker). Used to enforce max depth. */
+    dispatchDepth?: number | undefined;
+    /** Existing messages to resume from (for continuations). When set, the worker
+     *  appends `instruction` as a user message to these messages instead of building
+     *  a fresh initial prompt. */
+    resumeMessages?: AgentMessage[] | undefined;
+    /** Steps already consumed before this resume (for accurate step counting). */
+    stepsAlreadyUsed?: number | undefined;
+    /** Per model-call timeout in milliseconds. Default: 180000 (3 min). */
+    modelCallTimeoutMs?: number | undefined;
 }
 interface WorkerResult {
     transcript: AgentMessage[];
@@ -640,47 +839,109 @@ interface ArcRunResult {
     output: string;
     events: ArcEvent[];
 }
+type PushResult = {
+    delivered: "as_task";
+} | {
+    delivered: "as_interjection";
+    position: number;
+} | {
+    delivered: "dropped";
+    reason: "in_ask_user";
+};
+interface PushTaskOptions {
+    /** Multimodal attachments to attach to the resulting user message. */
+    attachments?: StoredAttachment[];
+}
 declare class ArcLoop {
     private config;
     private readonly transcriptStore;
     private readonly vectorIndex;
     private readonly scratchPad;
     private readonly artifactStore;
+    private readonly jobRegistry;
+    /** Non-output job events queued for orchestrator turn-boundary injection. */
+    private pendingJobEvents;
+    /** Events that need to flow out of the async generator stream (job events, interjection lifecycle). */
+    private pendingArcEvents;
+    private jobUnsubscribe;
+    private readonly telemetry;
     private messageStore;
     private summaryDAG;
     private readonly createModel;
     private readonly windowSize;
     private readonly model;
+    /** Full orchestrator system prompt (base + optional suffix). */
+    private readonly orchestratorSystem;
     /** Orchestrator tool schemas (for the model) */
     private readonly orchestratorToolSchemas;
     /** Orchestrator tool registry (for execute) — excludes dispatch/done (control flow) */
     private readonly orchestratorToolRegistry;
+    /** ARC framework tools that are always available to workers. */
+    private readonly workerArcTools;
     /** Dispatcher deps + mutable state — shared with dispatcher.ts functions */
     private readonly dispatchDeps;
     private readonly dispatchState;
     private orchestratorMessageIndex;
     private turn;
     private maxTurns;
+    private readonly inFlightDispatches;
+    private readonly historySearchesThisTask;
+    private readonly historyReadsThisTask;
+    private readonly historyExpansionsThisTask;
+    private readonly historyExpansionSummaryCache;
+    private lastSessionCheckpointAt;
     /** Per-turn abort controller — cancelled by interrupt(), refreshed each turn. */
     private turnController;
     /** Resolver for the next task — set when the loop is waiting between tasks. */
     private taskResolve;
+    private pendingInterjections;
+    /** Image attachments for the currently active task. Injected into orchestrator prompts. */
+    private currentTaskAttachments;
+    /** Consecutive dispatch rounds where every dispatch ended in failed/incomplete. Forces done at threshold. */
+    private consecutiveFailedDispatchRounds;
+    /** Turn refunds spent on env-only failed rounds within the current task. Bounded by MAX_ENV_TIMEOUT_REFUNDS. */
+    private envTimeoutRefundsThisTask;
+    private askUserPending;
+    private readonly modelCallTimeoutMs;
     constructor(config: ArcConfig);
+    /**
+     * Replace agent-provided worker tools for future dispatches.
+     * Already-running workers keep the tool set they started with.
+     */
+    refreshWorkerTools(tools: Map<string, Tool>): void;
+    /** Drain events from asynchronous sources (job registry, interjections) into the generator stream. */
+    private drainPendingArcEvents;
+    private drainPendingJobEvents;
+    private drainPendingInterjections;
+    /** Release subscriptions and free resources held by this loop. */
+    dispose(): void;
     /**
      * Interrupt the current turn — cancels in-flight model calls and workers.
      * The orchestrator loop stays alive and will prompt for user steering.
      */
     interrupt(): void;
+    private refreshTurnSignal;
     /** True when the loop is waiting for the next task (between done boundaries). */
     get idle(): boolean;
+    /** Serialize current loop state for UI-level checkpoints. */
+    getSessionSnapshot(): SessionSnapshot;
+    /** Restore loop state from a prior UI-level checkpoint. */
+    restoreSessionSnapshot(snapshot: SessionSnapshot | null): void;
     /**
-     * Push a follow-up task into the loop. The orchestrator sees it as
-     * a new user message with full conversational context from prior tasks.
+     * Deliver a message to the orchestrator regardless of loop state.
+     * - Idle (waiting for next task): resolves waitForNextTask → becomes next task.
+     * - Running: queued as [user interjection], drained at next turn boundary.
+     * - Inside askUser: dropped; caller should resolve the askUser promise directly.
      */
-    pushTask(task: string): boolean;
+    pushTask(msg: string, options?: PushTaskOptions): PushResult;
+    private wrappedAskUser;
     private waitForNextTask;
     /** Save session snapshot + update meta if a session store is configured. */
     private saveSession;
+    private buildSessionSnapshot;
+    private checkpointSession;
+    private checkpointAfterDispatchEvent;
+    private clearCompletedInFlightDispatches;
     /** Reset per-task state while keeping full conversation history. */
     private resetForNewTask;
     /**
@@ -692,17 +953,36 @@ declare class ArcLoop {
      * Breaks after the first `done` event — does not wait for follow-up tasks.
      */
     run(signal?: AbortSignal): Promise<ArcRunResult>;
+    private runDispatchCalls;
+    private continueStepBudgetDispatches;
+    private buildContinuationDispatchArgs;
+    private completeCurrentTask;
     /** Append a message to the LCM message store (single source of truth) */
     private appendOrchestratorMessage;
     private findEpisodeRecordBySummaryId;
+    private searchHistoryWithGuardrails;
+    private readHistoryWithGuardrails;
+    private expandHistoryWithGuardrails;
+    private summarizeHistoryExpansion;
     private buildContext;
     private buildOrchestratorMessages;
     private buildTaskContextText;
+    private buildAttachmentMessage;
     private readEpisode;
     /**
-     * Handle a turn interrupt: prompt user for steering, inject into context.
+     * Handle a turn interrupt without routing every follow-up through the
+     * orchestrator. Status questions are answered from the saved worker record;
+     * steering/continue become an internal worker continuation.
      */
     private handleInterrupt;
+    /**
+     * Ask the user whether to keep retrying after MAX_ENV_TIMEOUT_REFUNDS
+     * consecutive model-layer failures, or stop so they can give fresh
+     * instructions. Returns "retry" or "stop". Falls back to "stop" when no
+     * askUser callback is configured (e.g. headless runs).
+     */
+    private askRetryOrStop;
+    private formatInterruptStatus;
 }
 
 /**
@@ -720,6 +1000,73 @@ declare function formatDispatchForPrompt(record: DispatchRecord, options?: {
 
 declare function cloneForTrace<T>(value: T): T;
 
+/** Default budget for dispatches that do not request a tier. */
+declare const DEFAULT_MAX_STEPS_PER_WORKER = 30;
+/** Per-tier initial budgets. Strong is intentionally larger for implementation loops. */
+declare const DEFAULT_WORKER_STEP_BUDGETS: Record<DispatchTier, number>;
+/** Hard ceiling on worker steps after RequestMoreSteps extensions. */
+declare const ABSOLUTE_MAX_WORKER_STEPS = 60;
+/** Recommended extension size when workers need to keep their current context. */
+declare const REQUEST_MORE_STEPS_INCREMENT = 15;
+
+interface Episode {
+    id: string;
+    taskId: string;
+    sessionId: string;
+    tupleId?: string;
+    summary: string;
+    createdAt: number;
+    completedAt?: number;
+    /** Arbitrary metadata for routing/display */
+    metadata?: Record<string, unknown>;
+}
+interface EpisodeTrace {
+    episodeId: string;
+    messages: Array<{
+        role: string;
+        content: string;
+        [key: string]: unknown;
+    }>;
+    createdAt: number;
+}
+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>;
+}
+interface SessionMemo {
+    id: string;
+    sessionId: string;
+    content: string;
+    sourceEpisodeIds?: string[];
+    createdAt: number;
+}
+interface SessionMemoStore {
+    addMemo(memo: SessionMemo): Promise<void>;
+    getMemo(id: string): Promise<SessionMemo | null>;
+    getMemosBySession(sessionId: string): Promise<SessionMemo[]>;
+    getRecentMemos(limit: number): Promise<SessionMemo[]>;
+}
+interface LongTermMemory {
+    id: string;
+    content: string;
+    category: string;
+    createdAt: number;
+    updatedAt: number;
+}
+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>;
+}
 /** In-memory transcript store for testing */
 declare class MemoryTranscriptStore implements TranscriptStore {
     private transcripts;
@@ -735,6 +1082,7 @@ declare class MemoryVectorIndex implements VectorIndex {
     search(query: string, k: number): Promise<string[]>;
     load(): Promise<void>;
     save(): Promise<void>;
+    size(): Promise<number>;
 }
 /** In-memory scratch pad for testing */
 declare class MemoryScratchPad implements ScratchPad {
@@ -761,6 +1109,37 @@ declare class MemorySessionStore implements SessionStore {
     saveMeta(id: string, meta: SessionMeta): Promise<void>;
     list(): Promise<SessionMeta[]>;
 }
+/** In-memory episode store */
+declare class InMemoryEpisodeStore implements EpisodeStore {
+    private episodes;
+    private traces;
+    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>;
+}
+/** In-memory session memo store */
+declare class InMemorySessionMemoStore implements SessionMemoStore {
+    private memos;
+    addMemo(memo: SessionMemo): Promise<void>;
+    getMemo(id: string): Promise<SessionMemo | null>;
+    getMemosBySession(sessionId: string): Promise<SessionMemo[]>;
+    getRecentMemos(limit: number): Promise<SessionMemo[]>;
+}
+/** In-memory long-term store */
+declare class InMemoryLongTermStore implements LongTermStore {
+    private memories;
+    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>;
+}
 
 /**
  * File-based transcript store.
@@ -793,4 +1172,192 @@ declare class FsArtifactStore implements ArtifactStore {
     private save;
 }
 
-export { AnyTool, type ArcConfig, type ArcEvent, ArcLoop, type ArcRunResult, type ArcTraceEvent, type Artifact, type ArtifactStore, type DispatchRecord, type DispatchTier, type ExpectedArtifact, type ExpectedOutputContract, FsArtifactStore, FsTranscriptStore, MemoryArtifactStore, MemoryMessageStore, MemoryScratchPad, MemorySessionStore, MemorySummaryDAG, MemoryTranscriptStore, MemoryVectorIndex, type MessageStore, ModelFactory, type OodaSnapshot, type OrchestratorContext, type ReadEpisodeArgs, type ReadEpisodeDetail, type RunWorkerConfig, type ScratchPad, type SessionMeta, type SessionSnapshot, type SessionStore, type StoredMessage, type SummaryDAG, type SummaryNode, type Tool, ToolProvider, ToolResult, ToolResultArtifact, type TraceToolCall, type Transcript, type TranscriptStore, type Tuple, type VectorIndex, type WorkerProgressEvent, type WorkerResult, cloneForTrace, formatDispatchForPrompt };
+/**
+ * CompositeToolProvider delegates to the first provider with matching capabilities.
+ *
+ * Useful when multiple tool providers exist (e.g., a sandbox executor + a local
+ * file-system executor) and you want to route tool calls based on capability.
+ */
+declare class CompositeToolProvider implements ToolProvider {
+    private providers;
+    constructor(providers: ToolProvider[]);
+    capabilities(): ToolProviderCapabilities;
+    /** Pick the first provider that supports the requested capability. */
+    private pick;
+    bash(command: string, options?: BashOptions): Promise<ToolResult>;
+    readFile(path: string, options?: ReadOptions): Promise<ToolResult>;
+    writeFile(path: string, content: string): Promise<ToolResult>;
+    editFile(path: string, oldText: string, newText: string): Promise<ToolResult>;
+    glob(pattern: string, options?: GlobOptions): Promise<ToolResult>;
+    grep(pattern: string, path?: string, options?: GrepOptions): Promise<ToolResult>;
+}
+
+/**
+ * Executor interface for sandboxed code execution (e.g., E2B sandbox).
+ *
+ * Implementations wrap sandbox APIs into a uniform shape that
+ * E2BToolProvider can delegate to.
+ */
+interface E2BExecutor {
+    bash(command: string, options?: BashOptions): Promise<ToolResult>;
+    readFile(path: string, options?: ReadOptions): Promise<ToolResult>;
+    writeFile(path: string, content: string): Promise<ToolResult>;
+    editFile(path: string, oldText: string, newText: string): Promise<ToolResult>;
+    glob(pattern: string, options?: GlobOptions): Promise<ToolResult>;
+    grep(pattern: string, path?: string, options?: GrepOptions): Promise<ToolResult>;
+    batch?(ops: BatchOp[]): Promise<BatchResult[]>;
+    destroy(): Promise<void>;
+}
+/**
+ * E2BToolProvider wraps an E2BExecutor into a ToolProvider interface
+ * suitable for use with the harness agent loop.
+ */
+declare class E2BToolProvider {
+    private executor;
+    constructor(executor: E2BExecutor);
+    capabilities(): ToolProviderCapabilities;
+    bash(command: string, options?: BashOptions): Promise<ToolResult>;
+    readFile(path: string, options?: ReadOptions): Promise<ToolResult>;
+    writeFile(path: string, content: string): Promise<ToolResult>;
+    editFile(path: string, oldText: string, newText: string): Promise<ToolResult>;
+    glob(pattern: string, options?: GlobOptions): Promise<ToolResult>;
+    grep(pattern: string, path?: string, options?: GrepOptions): Promise<ToolResult>;
+}
+
+/** Options for constructing a ControlPlaneE2BExecutor. */
+interface ControlPlaneE2BExecutorOptions {
+    baseUrl: string;
+    apiKey: string;
+    templateId?: string;
+}
+/**
+ * Base class for control-plane E2B sandbox executors.
+ *
+ * Provides the configuration surface and stubs that concrete implementations
+ * (e.g., Samyx control-plane API) extend. Subclasses must override the
+ * tool-execution methods with actual sandbox API calls.
+ */
+declare class ControlPlaneE2BExecutor implements E2BExecutor {
+    protected baseUrl: string;
+    protected apiKey: string;
+    protected templateId: string;
+    constructor(options: ControlPlaneE2BExecutorOptions);
+    bash(_command: string, _options?: BashOptions): Promise<ToolResult>;
+    readFile(_path: string, _options?: ReadOptions): Promise<ToolResult>;
+    writeFile(_path: string, _content: string): Promise<ToolResult>;
+    editFile(_path: string, _oldText: string, _newText: string): Promise<ToolResult>;
+    glob(_pattern: string, _options?: GlobOptions): Promise<ToolResult>;
+    grep(_pattern: string, _path?: string, _options?: GrepOptions): Promise<ToolResult>;
+    writeFileBytes(_path: string, _data: Uint8Array): Promise<void>;
+    readFileBytes(_path: string): Promise<Uint8Array>;
+    get activeSandboxId(): string | undefined;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Permission request sent to the resolver for each tool call.
+ *
+ * The `toolName` key is always present. Additional tool arguments
+ * are forwarded as-is for context-sensitive permission decisions.
+ */
+interface PermissionRequest {
+    toolName: string;
+    [toolArg: string]: unknown;
+}
+/** Resolver function that decides whether a tool call is permitted. */
+type PermissionResolver = (request: PermissionRequest) => Promise<boolean>;
+/** Permission mode for the manager. */
+type PermissionMode = "deny_all" | "allow_all" | "ask";
+/**
+ * PermissionManager controls whether tool calls are allowed.
+ *
+ * Three modes:
+ * - `deny_all`: reject everything
+ * - `allow_all`: accept everything
+ * - `ask`: delegate to a resolver function
+ */
+declare class PermissionManager {
+    private mode;
+    private resolver;
+    constructor(mode: PermissionMode, resolver?: PermissionResolver);
+    /** Check whether a tool call is permitted. */
+    canExecute(request: PermissionRequest): Promise<boolean>;
+}
+
+interface ExecutionContext {
+    attempt: number;
+    totalAttempts: number;
+    startTime: number;
+    signal: AbortSignal;
+}
+interface PipelineOptions {
+    timeout?: number;
+    retryCount?: number;
+}
+declare class ResiliencePipeline {
+    private options;
+    constructor(options?: PipelineOptions);
+    /** Set a timeout in milliseconds for execution. */
+    timeout(ms: number): ResiliencePipeline;
+    /** Set retry count. */
+    retries(count: number): ResiliencePipeline;
+    /** Build the executable pipeline. */
+    build(): {
+        execute: <T>(fn: () => Promise<T>, ctx: ExecutionContext) => Promise<T>;
+    };
+}
+/** Create a new resilience pipeline builder. */
+declare function resilience(): ResiliencePipeline;
+
+/**
+ * Profile types for ArcLoop thread configuration.
+ *
+ * Profiles control which tools a worker thread can use and which
+ * model tier it runs at.
+ */
+/** Declaration of a worker profile — matched by name in process context. */
+interface ProfileDeclaration {
+    name: string;
+    /** Descriptive signature for the orchestrator (e.g., "question:string -> evidence:string[]") */
+    signature: string;
+    /** Tool names available to workers with this profile */
+    tools: string[];
+    /** Worker model tier */
+    model: "fast" | "medium" | "strong";
+    /** Worker step budget */
+    maxSteps: number;
+    /** Background/injection context for the worker system prompt */
+    background: string;
+}
+/** A profile bound to a process, with its declaration. */
+interface ProcessProfile {
+    name: string;
+    declaration: ProfileDeclaration;
+}
+
+/**
+ * In-memory reference implementation of JobRegistry.
+ *
+ * Jobs here never actually spawn processes — callers use `simulateExit` /
+ * `simulateOutput` / `simulateFailure` to drive state. Intended for tests
+ * and agents that don't need filesystem-backed persistence.
+ */
+declare class MemoryJobRegistry implements JobRegistry {
+    private jobs;
+    private handlers;
+    private seq;
+    start(opts: JobStartOptions, startedBy?: JobSpec["startedBy"]): Promise<JobStatus>;
+    check(id: string): Promise<JobStatus | null>;
+    cancel(id: string, _signal?: "TERM" | "KILL"): Promise<JobStatus | null>;
+    list(): Promise<JobStatus[]>;
+    tail(id: string, lines?: number): Promise<string[]>;
+    waitFor(id: string, signal?: AbortSignal): Promise<JobStatus>;
+    subscribe(handler: (e: JobEvent) => void): () => void;
+    snapshot(): JobStatus[];
+    prune(_olderThanMs?: number): Promise<number>;
+    simulateOutput(id: string, chunk: string): void;
+    simulateExit(id: string, exitCode: number): void;
+    private emit;
+}
+
+export { ABSOLUTE_MAX_WORKER_STEPS, AnyTool, type ArcConfig, type ArcEvent, ArcLoop, type ArcRunResult, type ArcTraceEvent, type Artifact, type ArtifactStore, BashOptions, BatchOp, BatchResult, CompositeToolProvider, ControlPlaneE2BExecutor, type ControlPlaneE2BExecutorOptions, DEFAULT_MAX_STEPS_PER_WORKER, DEFAULT_WORKER_STEP_BUDGETS, type DispatchRecord, type DispatchTier, type E2BExecutor, E2BToolProvider, type Episode, type EpisodeStore, type EpisodeTrace, type ExecutionContext, type ExpectedArtifact, type ExpectedOutputContract, FsArtifactStore, FsTranscriptStore, GlobOptions, GrepOptions, HarnessTelemetry, type HookCallback, type HookContext, type HookDecision, type HookEventName, HookRunner, InMemoryEpisodeStore, InMemoryLongTermStore, InMemorySessionMemoStore, type JobEvent, type JobKind, type JobRegistry, type JobSpec, type JobStartOptions, type JobState, type JobStatus, type JobTransport, type LongTermMemory, type LongTermStore, MemoryArtifactStore, MemoryJobRegistry, MemoryMessageStore, MemoryScratchPad, MemorySessionStore, MemorySummaryDAG, MemoryTranscriptStore, MemoryVectorIndex, type MessageStore, ModelFactory, type OrchestratorContext, PermissionManager, type PermissionMode, type PermissionRequest, type PermissionResolver, type ProcessProfile, type ProfileDeclaration, type PushResult, REQUEST_MORE_STEPS_INCREMENT, type ReadEpisodeArgs, type ReadEpisodeDetail, ReadOptions, type RunWorkerConfig, type ScratchPad, type SessionMemo, type SessionMemoStore, type SessionMeta, type SessionSnapshot, type SessionStore, type StoredAttachment, type StoredMessage, type SummaryDAG, type SummaryNode, type Tool, type ToolExecutionMode, ToolProvider, ToolProviderCapabilities, ToolResult, ToolResultArtifact, type TraceToolCall, type Transcript, type TranscriptStore, type Tuple, type VectorIndex, type WorkerProgressEvent, type WorkerResult, cloneForTrace, formatDispatchForPrompt, resilience };