@bluecopa/harness 0.1.0-snapshot.20 → 0.1.0-snapshot.22

package/README.md

@@ -2,9 +2,17 @@
 
 Provider-agnostic TypeScript agent framework with Claude-code-compatible tool semantics.
 
-The harness provides the core loop that drives an AI agent: send messages to an LLM, execute the tool calls it returns, feed results back, and repeat until the LLM produces a final text response.
+Published on npm as **`@bluecopa/harness`**.
 
-## Quickstart
+Two execution modes: a simple single-agent loop (`createAgent` + `VercelAgentLoop`) and a process-based orchestrator (`ArcLoop`) that dispatches parallel processes with context management, memory, and resilience.
+
+## Install
+
+```bash
+pnpm add @bluecopa/harness
+```
+
+## Development
 
 ```bash
 pnpm install
@@ -13,9 +21,11 @@ pnpm test
 
 ## Architecture
 
+### Single-Agent Loop
+
 ```
 ┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
-│  createAgent │────▶│  AgentLoop   │────▶│  LLM (Claude)    │
+│  createAgent │────►│  AgentLoop   │────►│  LLM (Claude)    │
 │  (turn loop) │     │  (nextAction)│     │                  │
 └──────┬───────┘     └──────────────┘     └──────────────────┘
        │                                           │
@@ -27,20 +37,82 @@ pnpm test
 └──────────────┘
 ```
 
-1. `createAgent` drives a deterministic step loop
-2. Each step calls `loop.nextAction(messages)` to get the LLM's decision
-3. If it's a tool call, the harness executes it via `ToolProvider` and appends the result
-4. If it's a final action, the loop ends and returns the result
+### ArcLoop Orchestrator
 
-## Using with the sandbox
+```
+Orchestrator (ArcLoop — Opus 4.6 by default)
+  │  tools: Thread, Check, Cancel, Remember, ReadEpisode
+  │
+  │  Turn 1 (parallel):
+  ├──► Process 0 ("read auth", model=fast)        ─┐
+  ├──► Process 1 ("read routes", model=fast)       ─┼──► Episodes
+  ├──► Process 2 ("read tests", model=fast)        ─┘
+  │
+  │  Turn 2 (dispatch dependent work):
+  ├──► Thread("fix bug", context=[ep0,ep1,ep2])    ──► Episode
+  │
+  │  Turn 3 (parallel):
+  ├──► Thread("run tests", context=[ep3])          ─┐
+  ├──► Thread("update docs", context=[ep3])        ─┘
+  │
+  └──► Final text response
+```
 
-The most common setup connects the harness to a running sandbox service via `ControlPlaneE2BExecutor`:
+Full architecture doc: [`docs/arc.md`](../docs/arc.md)
 
-```ts
-import { createAgent } from './src/agent/create-agent';
-import { E2BToolProvider } from './src/providers/e2b-tool-provider';
+---
+
+## ToolProvider
+
+The contract for tool execution. All agent modes use this interface.
+
+```typescript
+interface ToolProvider {
+  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>;
+  webFetch?(options: WebFetchOptions): Promise<ToolResult>;
+  webSearch?(query: string): Promise<ToolResult>;
+  capabilities(): ToolProviderCapabilities;
+}
+
+interface ToolResult {
+  success: boolean;
+  output: string;
+  error?: string;
+}
+```
+
+Built-in implementations:
+
+| Provider | Description |
+|----------|-------------|
+| `LocalToolProvider` | Runs tools on the local filesystem |
+| `E2BToolProvider` | Routes tools to a sandbox VM via `ControlPlaneE2BExecutor` |
+| `CompositeToolProvider` | Combines multiple providers (e.g. local filesystem + sandbox bash) |
+
+## SandboxProvider
+
+Higher-level sandbox operations beyond basic tool calls:
+
+```typescript
+interface SandboxProvider {
+  exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
+  readSandboxFile(path: string): Promise<SandboxFileBlob>;
+  writeSandboxFile(path: string, content: SandboxFileBlob): Promise<void>;
+}
+```
+
+Used by `SkillManager` for executing skill scripts in isolated VMs.
+
+## Connecting to a Sandbox
+
+```typescript
 import { ControlPlaneE2BExecutor } from './src/providers/control-plane-e2b-executor';
-import { VercelAgentLoop } from './src/loop/vercel-agent-loop';
+import { E2BToolProvider } from './src/providers/e2b-tool-provider';
 
 // Connect to sandbox service
 const executor = new ControlPlaneE2BExecutor({
@@ -50,187 +122,172 @@ const executor = new ControlPlaneE2BExecutor({
 });
 await executor.initialize();  // creates a Firecracker VM
 
-// Build and run the agent
-const agent = createAgent({
-  toolProvider: new E2BToolProvider(executor),
-  loop: new VercelAgentLoop(),  // needs ANTHROPIC_API_KEY
-});
+const toolProvider = new E2BToolProvider(executor);
 
-const result = await agent.run('create a bar chart of sales data');
-console.log(result.output);   // LLM's final response
-console.log(result.steps);    // number of tool steps
+// ... use with createAgent or ArcLoop
 
-await executor.destroy();     // tears down the VM
+await executor.destroy();  // tears down the VM
 ```
 
-For a complete working example, see [`examples/chat-assistant/src/chat.ts`](../examples/chat-assistant/src/chat.ts).
-
-### From environment variables
+From environment variables: `ControlPlaneE2BExecutor.fromEnv()` reads `SAMYX_BASE_URL` and `SAMYX_API_KEY`.
 
-`ControlPlaneE2BExecutor.fromEnv()` reads `SAMYX_BASE_URL` and `SAMYX_API_KEY` automatically:
+---
 
-```ts
-const executor = ControlPlaneE2BExecutor.fromEnv();
-```
-
-## Using locally (no sandbox)
+## Single-Agent Mode (`createAgent`)
 
-For development without a sandbox service, use `LocalToolProvider` which runs tools on the local machine:
+For simple tasks that don't need orchestration:
 
-```ts
+```typescript
 import { createAgent } from './src/agent/create-agent';
 import { LocalToolProvider } from './src/providers/local-tool-provider';
 
 const agent = createAgent({
   toolProvider: new LocalToolProvider(process.cwd()),
-  loop: new VercelAgentLoop(),
+  loop: new VercelAgentLoop(),  // needs ANTHROPIC_API_KEY
 });
 
 const result = await agent.run('list all TypeScript files');
+console.log(result.output);
 ```
 
-## Key modules
-
-### Agent creation (`src/agent/create-agent.ts`)
+### Configuration
 
-`createAgent(options)` returns an agent with a `.run(prompt, options?)` method. Options:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `toolProvider` | `ToolProvider` | required | Executes tool calls |
+| `loop` | `AgentLoop` | `VercelAgentLoop` | LLM decision loop |
+| `sandboxProvider` | `SandboxProvider` | — | Higher-level sandbox operations |
+| `maxSteps` | `number` | 30 | Max tool steps per run |
+| `telemetry` | `HarnessTelemetry` | — | OpenTelemetry-style tracing |
+| `skillIndexPath` | `string` | — | Path to skill index JSON for routing |
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `toolProvider` | `ToolProvider` | Required. Executes tool calls |
-| `loop` | `AgentLoop` | LLM decision loop (default: `VercelAgentLoop`) |
-| `sandboxProvider` | `SandboxProvider` | Optional. Higher-level sandbox ops (file download, exec with env) |
-| `maxSteps` | `number` | Max tool steps per run (default: 30) |
-| `telemetry` | `HarnessTelemetry` | Optional. OpenTelemetry-style tracing |
-| `skillIndexPath` | `string` | Optional. Path to skill index JSON |
+### VercelAgentLoop
 
-### Agent loop (`src/loop/vercel-agent-loop.ts`)
+Calls Claude via the Vercel AI SDK. Supports parallel tool calls and configurable system prompt.
 
-`VercelAgentLoop` calls Claude via the Vercel AI SDK. It supports:
-- Parallel tool calls (returns `ToolBatchAction` when the LLM requests multiple tools at once)
-- Configurable system prompt
-- Model selection via `HARNESS_MODEL` env var (default: `claude-sonnet-4-5`)
-
-```ts
+```typescript
 const loop = new VercelAgentLoop({
   systemPrompt: 'You are a helpful coding assistant.',
+  model: 'claude-sonnet-4-5',  // or HARNESS_MODEL env var
 });
 ```
 
-### Tool provider (`src/interfaces/tool-provider.ts`)
+### LCMToolLoop
 
-The contract for tool execution:
+Wraps another loop to add Lossless Context Management and optional REPL orchestration:
 
-```ts
-interface ToolProvider {
-  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>;
-  webFetch?(options: WebFetchOptions): Promise<ToolResult>;
-  webSearch?(query: string): Promise<ToolResult>;
-  capabilities(): ToolProviderCapabilities;
-}
+```typescript
+import { LCMToolLoop } from './src/loop/lcm-tool-loop';
+import { VercelAgentLoop } from './src/loop/vercel-agent-loop';
 
-interface ToolResult {
-  success: boolean;
-  output: string;
-  error?: string;
-}
+const loop = new LCMToolLoop({
+  innerLoop: new VercelAgentLoop(),
+  toolProvider: mySandboxProvider,
+  enableRepl: true,           // default: true
+  bridgeDir: '/var/run/bridge',
+  onActivity: (entry) => console.log(entry),
+  onLlmRequest: async (prompt) => callLLM(prompt),
+  onWebFetchRequest: async (url) => fetch(url),
+});
 ```
 
-Built-in implementations:
+**Standard mode**: Lossless context trimming — the LLM always sees a coherent, budget-fitting view of the full conversation.
 
-| Provider | Description |
-|----------|-------------|
-| `LocalToolProvider` | Runs tools on the local filesystem |
-| `E2BToolProvider` | Routes tools to an E2B-compatible executor over HTTP |
-| `CompositeToolProvider` | Combines multiple providers (e.g. sandbox + web) |
+**REPL mode**: When the LLM returns a Bash action with the REPL marker, the loop writes a Python script into the sandbox, injects the bridge module, runs the script, and polls for sub-requests (LLM, web_fetch, ask_user) that the harness fulfills.
 
-### Action types (`src/agent/types.ts`)
+---
 
-The LLM returns one of these action types each turn:
+## ArcLoop (Orchestrator Mode)
 
-```ts
-// Single tool call
-interface ToolCallAction {
-  type: 'tool';
-  name: 'Bash' | 'Read' | 'Write' | 'Edit' | 'Glob' | 'Grep' | ...;
-  args: Record<string, unknown>;
-}
+For complex tasks that benefit from parallel processes, context management, and memory:
 
-// Multiple independent tool calls (executed in parallel)
-interface ToolBatchAction {
-  type: 'tool_batch';
-  calls: ToolCallAction[];
-}
-
-// Final text response (ends the loop)
-interface FinalAction {
-  type: 'final';
-  content: string;
-}
-```
-
-### LCM tool loop (`src/loop/lcm-tool-loop.ts`)
-
-`LCMToolLoop` wraps another loop to add LCM-based tool routing, REPL script execution, and bridge-based tool dispatch. Used in the chat-assistant example.
-
-### Sandbox provider (`src/interfaces/sandbox-provider.ts`)
+```typescript
+import { createArcAgent } from './src/arc/create-arc-agent';
 
-Higher-level sandbox operations beyond basic tool calls:
+const agent = await createArcAgent({
+  toolProvider: myToolProvider,
+  episodeStore: myEpisodeStore,       // required
+  sessionMemoStore: mySessionMemoStore, // required
+  longTermStore: myLongTermStore,       // required
+  taskId: 'task-1',
+  sessionId: 'session-1',
+});
 
-```ts
-interface SandboxProvider {
-  exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
-  readSandboxFile(path: string): Promise<SandboxFileBlob>;
-  writeSandboxFile(path: string, content: SandboxFileBlob): Promise<void>;
+// Streaming
+for await (const event of agent.stream(messages, signal)) {
+  if (event.type === 'text_delta') process.stdout.write(event.text);
+  if (event.type === 'process_dispatched') console.log(`  → ${event.action}`);
+  if (event.type === 'done') console.log(`Done in ${event.stats.durationMs}ms`);
 }
-```
-
-### Observability (`src/observability/otel.ts`)
-
-`HarnessTelemetry` provides OpenTelemetry-style spans and metrics for agent runs.
 
-### Arc: Orchestrator + Thread Architecture (`src/arc/`)
+// Non-streaming
+const result = await agent.run(messages, signal);
+```
 
-`ArcLoop` is an `AgentLoop` implementation where an orchestrator LLM dispatches bounded threads via a single `Thread` tool. Threads produce episodes (summary + full trace). The orchestrator only sees summaries, keeping its context small.
+### ArcLoopConfig
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `string` | `'claude-opus-4-6'` | Orchestrator model (ID or tier name) |
+| `modelMap` | `Record<ModelTier, string>` | haiku/sonnet/opus | Maps fast/medium/strong to model IDs |
+| `apiKey` | `string` | — | Anthropic API key |
+| `systemPrompt` | `string` | built-in | Custom orchestrator system prompt |
+| `maxTurns` | `number` | 30 | Max orchestrator turns |
+| `processTimeout` | `number` | 120_000 | Per-process timeout (ms) |
+| `processMaxSteps` | `number` | 20 | Per-process max tool steps |
+| `contextWindowSize` | `number` | 200_000 | Context window in tokens |
+| `outputReserve` | `number` | 20_000 | Tokens reserved for output |
+| `autoMemory` | `boolean` | true | Auto-detect patterns from episodes |
+| `episodeStore` | `EpisodeStore` | required | Stores episode summaries + traces |
+| `sessionMemoStore` | `SessionMemoStore` | required | Stores session memos |
+| `longTermStore` | `LongTermStore` | required | Stores long-term memories |
+| `taskId` | `string` | required | Task identifier |
+| `sessionId` | `string` | required | Session identifier |
+| `toolProvider` | `ToolProvider` | required | Tool execution |
+| `processTools` | `Record<string, AnyTool>` | builtinTools | Tools available inside processes |
+| `extraOrchestratorTools` | `Record<string, AnyTool>` | — | Custom orchestrator tools |
+| `onOrchestratorTool` | `function` | — | Handler for custom orchestrator tools |
+| `resilience` | `ResiliencePolicy` | — | Composable resilience pipeline |
+| `traceWriter` | `function` | — | Callback for trace event emission |
+
+### Resilience
+
+```typescript
+import { resilience } from './src/arc/resilience';
+
+const pipeline = resilience()
+  .retry({ maxRetries: 2, baseDelay: 1000 })
+  .timeout({ durationMs: 30_000 })
+  .circuitBreaker({ failureThreshold: 5 })
+  .build();
+
+const agent = await createArcAgent({
+  // ...config
+  resilience: pipeline,
+});
+```
 
-```ts
-import { createArcAgent } from './src/arc/create-arc-agent';
-import { InMemoryEpisodeStore } from './src/arc/stores/episode-store';
-import { InMemorySessionMemoStore } from './src/arc/stores/session-memo-store';
-import { InMemoryLongTermStore } from './src/arc/stores/long-term-store';
+### Trace Emission
 
-const agent = createArcAgent({
-  toolProvider: new LocalToolProvider(process.cwd()),
-  episodeStore: new InMemoryEpisodeStore(),
-  sessionMemoStore: new InMemorySessionMemoStore(),
-  longTermStore: new InMemoryLongTermStore(),
-  taskId: 'task-1',
-  sessionId: 'session-1',
+```typescript
+const traces: TraceEvent[] = [];
+const agent = await createArcAgent({
+  // ...config
+  traceWriter: (event) => traces.push(event),
 });
-
-const result = await agent.run('Fix the authentication bug');
 ```
 
-Key features:
-- **Parallel threads**: orchestrator calls Thread N times in one turn → all run concurrently
-- **Four-tier memory**: thread context → episodes → session memos → long-term
-- **Per-thread models**: Haiku for reads, Sonnet for implementation
-- **Template compression**: zero-LLM-call episode summaries
-- **Async consolidation**: non-blocking background distillation
+Traces can be validated against the formal model: `cd verify && cargo run -- trace file.ndjson`
 
-Full architecture doc: [`docs/arc.md`](../docs/arc.md)
+---
 
-## Package layout
+## Package Layout
 
 ```
 src/
 ├── agent/          # createAgent, step executor, types
-├── arc/            # ArcLoop orchestrator, threads, memory hierarchy
+├── arc/            # ArcLoop orchestrator, processes, memory, resilience
+│   ├── resilience/ # Retry, circuit breaker, timeout, bulkhead, fallback
 │   ├── stores/     # RxDB + in-memory store implementations
 │   └── object-store/ # Pluggable cloud sync (fs, memory)
 ├── interfaces/     # ToolProvider, SandboxProvider, AgentLoop contracts
@@ -240,17 +297,20 @@ src/
 ├── hooks/          # Pre/post tool call hooks
 ├── permissions/    # Tool permission checks
 ├── sessions/       # Session persistence
-├── subagents/      # Subagent spawning and task tools
+├── subagents/      # Subagent spawning
 ├── skills/         # Skill index, routing, and management
 ├── optimization/   # Benchmark runner
 └── observability/  # OpenTelemetry integration
+
+verify/             # Rust formal verification (Stateright model checker)
+testing/            # Adversarial scenario replay harness
+tests/              # Vitest test suite
 ```
 
 ## Documentation
 
-- **Arc architecture**: [`docs/arc.md`](../docs/arc.md)
-- Provider guide: `docs/guides/providers.md`
-- Skills guide: `docs/guides/skills.md`
-- Observability guide: `docs/guides/observability.md`
-- Release process: `../docs/RELEASE.md`
-- Full example: [`../examples/chat-assistant/src/chat.ts`](../examples/chat-assistant/src/chat.ts)
+- [Arc architecture](../docs/arc.md) — process model, context window, memory, resilience, verification
+- [Testing](../docs/testing.md) — test layers, running tests, writing new tests
+- [Sandbox setup](../docs/PUBLIC_SANDBOX.md) — deploying the sandbox service
+- [Release process](../docs/RELEASE.md) — versioning and publishing
+- [Example](../examples/chat-assistant/src/chat.ts) — complete working chat assistant

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluecopa/harness",
-  "version": "0.1.0-snapshot.20",
+  "version": "0.1.0-snapshot.22",
   "description": "Provider-agnostic TypeScript agent framework",
   "license": "UNLICENSED",
   "scripts": {

package/src/arc/agent-runner.ts

@@ -364,6 +364,10 @@ export interface CreateProcessConfig {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   processTools: Record<string, any>;
   parentSignal: AbortSignal;
+  /** Custom system prompt for this process (overrides PROCESS_SYSTEM_PROMPT). */
+  processSystemPrompt?: string;
+  /** Async skill instructions to prepend to system prompt (resolved during process startup). */
+  skillPromptPromise?: Promise<string | null>;
 
   // Runtime extras
   hookRunner?: HookRunner;
@@ -419,12 +423,21 @@ export function createProcess(
       process.status = 'running';
       const seed = await seedPromise;
 
+      // Build system prompt: base + optional skill instructions
+      let systemPrompt = config.processSystemPrompt ?? PROCESS_SYSTEM_PROMPT;
+      if (config.skillPromptPromise) {
+        const skillInstructions = await config.skillPromptPromise;
+        if (skillInstructions) {
+          systemPrompt += '\n\n## Skill Instructions\n' + skillInstructions;
+        }
+      }
+
       const result = await Promise.race([
         runner.run({
           model,
           prompt: request.action,
           tools: config.processTools,
-          systemPrompt: PROCESS_SYSTEM_PROMPT,
+          systemPrompt,
           toolProvider: config.toolProvider,
           maxSteps,
           signal: ac.signal,

package/src/arc/arc-loop.ts

@@ -27,6 +27,9 @@ import { createProcess, firstEvent } from './agent-runner';
 import { EpisodeCompressor } from './episode-compressor';
 import { runConsolidation } from './consolidation';
 import { pickDefined } from './utils';
+import { SkillRouter } from '../skills/skill-router';
+import { loadSkillFromFile } from '../skills/skill-loader';
+import type { SkillSummary } from '../skills/skill-types';
 
 // ── Default orchestrator prompt ──
 
@@ -75,6 +78,9 @@ export class ArcLoop {
   private readonly traceWriter: ((event: TraceEvent) => void) | undefined;
   private readonly tracedRunning = new Set<string>();
   private readonly processListeners: Promise<void>[] = [];
+  private readonly skillRouter: SkillRouter | undefined;
+  private skillSummaries: SkillSummary[] | null = null;
+  private skillSummariesPromise: Promise<SkillSummary[]> | null = null;
 
   constructor(config: ArcLoopConfig) {
     this.config = config;
@@ -114,6 +120,15 @@ export class ArcLoop {
 
     this.resilience = config.resilience;
     this.traceWriter = (config as ArcLoopConfig & { traceWriter?: (event: TraceEvent) => void }).traceWriter;
+
+    if (config.skillIndexPath) {
+      this.skillRouter = new SkillRouter();
+      // Lazy-load skill summaries on first dispatch
+      this.skillSummariesPromise = import('node:fs/promises')
+        .then(fs => fs.readFile(config.skillIndexPath!, 'utf-8'))
+        .then(raw => JSON.parse(raw) as SkillSummary[])
+        .catch(() => []);
+    }
   }
 
   private trace(kind: TraceEvent['kind']): void {
@@ -449,7 +464,20 @@ export class ArcLoop {
   // ── Process dispatch ──
 
   private dispatch(request: ProcessRequest, parentSignal: AbortSignal): Process {
-    const defaultModel = resolveModel('medium', this.modelMap, this.modelMap.medium);
+    const profile = request.profile
+      ? this.config.processProfiles?.[request.profile]
+      : undefined;
+    const defaultModel = resolveModel(
+      profile?.model ?? 'medium',
+      this.modelMap,
+      this.modelMap.medium,
+    );
+
+    // Resolve skill instructions only when skills are configured
+    const skillPromptPromise = this.skillRouter
+      ? this.resolveSkillPrompt(request.action)
+      : undefined;
+
     const proc = createProcess(request, {
       toolProvider: this.config.toolProvider,
       episodeStore: this.config.episodeStore,
@@ -457,10 +485,12 @@ export class ArcLoop {
       sessionId: this.config.sessionId,
       modelMap: this.modelMap,
       defaultModel,
-      processMaxSteps: this.config.processMaxSteps ?? 20,
+      processMaxSteps: profile?.maxSteps ?? this.config.processMaxSteps ?? 20,
       processTimeout: this.config.processTimeout ?? 120_000,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      processTools: this.config.processTools ?? builtinTools as any,
+      processTools: (profile?.tools ?? this.config.processTools ?? builtinTools) as any,
+      processSystemPrompt: profile?.systemPrompt ?? this.config.processSystemPrompt,
+      skillPromptPromise,
       parentSignal,
       ...pickDefined(this.config, [
         'hookRunner',
@@ -475,6 +505,28 @@ export class ArcLoop {
     return proc;
   }
 
+  /** Resolve skill instructions for a process action. Returns null if no skill matched. */
+  private async resolveSkillPrompt(action: string): Promise<string | null> {
+    if (!this.skillRouter || !this.skillSummariesPromise) return null;
+
+    // Ensure summaries are loaded
+    if (!this.skillSummaries) {
+      this.skillSummaries = await this.skillSummariesPromise;
+    }
+    if (this.skillSummaries.length === 0) return null;
+
+    // Fast match only (keyword + alias, no LLM call)
+    const matched = await this.skillRouter.selectSkill(action, this.skillSummaries);
+    if (!matched) return null;
+
+    try {
+      const skill = await loadSkillFromFile(matched.path);
+      return skill.instructions || null;
+    } catch {
+      return null;
+    }
+  }
+
   private traceProcessRunning(procId: string): void {
     if (!this.tracedRunning.has(procId)) {
       this.tracedRunning.add(procId);
@@ -546,6 +598,9 @@ export class ArcLoop {
     if (typeof args.label === 'string') {
       req.label = args.label;
     }
+    if (typeof args.profile === 'string') {
+      req.profile = args.profile;
+    }
     return req;
   }
 

package/src/arc/tools.ts

@@ -11,6 +11,7 @@ export const Thread = tool({
     model: z.enum(['fast', 'medium', 'strong']).optional().describe('Model tier (default: medium)'),
     maxSteps: z.number().optional().describe('Max tool-call steps'),
     label: z.string().optional().describe('Human-readable label'),
+    profile: z.string().optional().describe('Named process profile (e.g. "researcher", "builder")'),
   }),
 });
 

package/src/arc/types.ts

@@ -63,6 +63,10 @@ export interface ArcLoopConfig {
   processTimeout?: number;
   /** Per-process max steps (default: 20) */
   processMaxSteps?: number;
+  /** Default system prompt for all processes (overrides the built-in default) */
+  processSystemPrompt?: string;
+  /** Named process profiles. The orchestrator selects a profile via the Thread tool's `profile` param. */
+  processProfiles?: Record<string, ProcessProfile>;
 
   // Context
   /** Context window size in tokens (default: 200_000) */
@@ -148,6 +152,20 @@ export interface ProcessRequest {
   model?: import('./arc-types').ModelTier;
   maxSteps?: number;
   label?: string;
+  /** Named profile to use for this process (looked up from ArcLoopConfig.processProfiles). */
+  profile?: string;
+}
+
+/** A named process profile — provides defaults for system prompt, tools, model, and step limit. */
+export interface ProcessProfile {
+  /** System prompt for processes using this profile. */
+  systemPrompt: string;
+  /** Tools available to processes using this profile (overrides processTools). */
+  tools?: Record<string, import('./arc-types').AnyTool>;
+  /** Default model tier for this profile (Thread tool's explicit model overrides this). */
+  model?: import('./arc-types').ModelTier;
+  /** Max steps for this profile (Thread tool's explicit maxSteps overrides this). */
+  maxSteps?: number;
 }
 
 export type Activity =

package/tests/arc/process-profiles.test.ts

@@ -0,0 +1,364 @@
+/**
+ * Tests for process profiles.
+ *
+ * Verifies that:
+ * 1. A process dispatched with a named profile uses the profile's system prompt
+ * 2. A process dispatched with a named profile uses the profile's tools/maxSteps/model
+ * 3. The default processSystemPrompt is used when no profile is specified
+ * 4. Profile model is overridden by explicit Thread model param
+ * 5. Unknown profile names fall back to defaults
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ToolProvider, ToolResult } from '../../src/interfaces/tool-provider';
+import type { Episode, EpisodeTrace, SessionMemo, LongTermMemory } from '../../src/arc/arc-types';
+
+// ── Capture what system prompt each process receives ──
+
+const capturedSystemPrompts: string[] = [];
+const capturedModels: string[] = [];
+let orchestratorCallCount = 0;
+let processCallCount = 0;
+
+// Orchestrator (streamText): dispatches Thread calls based on test scenario
+let orchestratorScript: Array<() => unknown> = [];
+
+function mockStreamText() {
+  const callNum = orchestratorCallCount++;
+  if (callNum < orchestratorScript.length) {
+    return orchestratorScript[callNum]();
+  }
+  // Default: final text
+  return {
+    fullStream: (async function* () {
+      yield { type: 'text-delta', text: 'Done.' };
+    })(),
+  };
+}
+
+// Process (generateText): captures system prompt, returns immediate completion
+function mockGenerateText(opts: Record<string, unknown>) {
+  processCallCount++;
+  // Capture the system prompt passed to this process
+  const system = opts.system as Array<{ content: string }> | undefined;
+  if (system?.[0]?.content) {
+    capturedSystemPrompts.push(system[0].content);
+  }
+  // Capture the model
+  capturedModels.push(String(opts.model ?? ''));
+
+  // Immediate completion — no tool calls
+  return Promise.resolve({
+    text: 'Process done.',
+    toolCalls: [],
+  });
+}
+
+vi.mock('ai', () => ({
+  streamText: (opts: Record<string, unknown>) => mockStreamText(),
+  generateText: (opts: Record<string, unknown>) => mockGenerateText(opts),
+  tool: (def: Record<string, unknown>) => def,
+}));
+
+vi.mock('@ai-sdk/anthropic', () => ({
+  anthropic: (model: string) => model,
+}));
+
+// ── In-memory stores ──
+
+function createInMemoryStores() {
+  const episodes: Episode[] = [];
+  const traces: EpisodeTrace[] = [];
+  const memos: SessionMemo[] = [];
+  const memories: LongTermMemory[] = [];
+
+  return {
+    episodeStore: {
+      async addEpisode(ep: Episode) { episodes.push(ep); },
+      async addTrace(tr: EpisodeTrace) { traces.push(tr); },
+      async getEpisode(id: string) { return episodes.find(e => e.id === id) ?? null; },
+      async getTrace(id: string) { return traces.find(t => t.episodeId === id) ?? null; },
+      async getEpisodesByTask(taskId: string) { return episodes.filter(e => e.taskId === taskId); },
+      async getEpisodesBySession(sid: string) { return episodes.filter(e => e.sessionId === sid); },
+      async getRecentEpisodes(n: number) { return episodes.slice(-n); },
+      async evictTraces() { return 0; },
+    },
+    sessionMemoStore: {
+      async addMemo(memo: SessionMemo) { memos.push(memo); },
+      async getMemo(id: string) { return memos.find(m => m.id === id) ?? null; },
+      async getMemosBySession(sid: string) { return memos.filter(m => m.sessionId === sid); },
+      async getRecentMemos(n: number) { return memos.slice(-n); },
+    },
+    longTermStore: {
+      async addMemory(mem: LongTermMemory) { memories.push(mem); },
+      async getMemory(id: string) { return memories.find(m => m.id === id) ?? null; },
+      async getAllMemories() { return [...memories]; },
+      async getMemoriesByCategory(cat: string) { return memories.filter(m => m.category === cat); },
+      async updateMemory(id: string, updates: Partial<Pick<LongTermMemory, 'content' | 'category' | 'updatedAt'>>) {
+        const mem = memories.find(m => m.id === id);
+        if (mem) Object.assign(mem, updates);
+      },
+      async deleteMemory(id: string) {
+        const idx = memories.findIndex(m => m.id === id);
+        if (idx >= 0) memories.splice(idx, 1);
+      },
+    },
+  };
+}
+
+function createMockToolProvider(): ToolProvider {
+  const ok = (output: string): ToolResult => ({ success: true, output });
+  return {
+    async bash() { return ok('output'); },
+    async readFile() { return ok('content'); },
+    async writeFile() { return ok('written'); },
+    async editFile() { return ok('edited'); },
+    async glob() { return ok('files'); },
+    async grep() { return ok('matches'); },
+    capabilities() {
+      return { bash: true, fileSystem: true, webFetch: false, webSearch: false, codeExecution: false, sandboxed: false };
+    },
+  };
+}
+
+// Helper: create a streamText response that dispatches Thread tool calls
+function threadCalls(...calls: Array<Record<string, unknown>>) {
+  return () => ({
+    fullStream: (async function* () {
+      for (const call of calls) {
+        yield { type: 'tool-call', toolName: 'Thread', toolCallId: `tc-${Math.random()}`, args: call };
+      }
+    })(),
+  });
+}
+
+// Helper: create a final text response
+function finalText(text: string) {
+  return () => ({
+    fullStream: (async function* () {
+      yield { type: 'text-delta', text };
+    })(),
+  });
+}
+
+// ── Import after mocks ──
+import { ArcLoop } from '../../src/arc/arc-loop';
+
+beforeEach(() => {
+  capturedSystemPrompts.length = 0;
+  capturedModels.length = 0;
+  orchestratorCallCount = 0;
+  processCallCount = 0;
+  orchestratorScript = [];
+});
+
+describe('Process Profiles', () => {
+  it('uses the profile system prompt when a named profile is specified', async () => {
+    orchestratorScript = [
+      threadCalls({ action: 'Do research', profile: 'researcher' }),
+      finalText('Done.'),
+    ];
+
+    const stores = createInMemoryStores();
+    const loop = new ArcLoop({
+      ...stores,
+      taskId: 'test-1',
+      sessionId: 'sess-1',
+      toolProvider: createMockToolProvider(),
+      processProfiles: {
+        researcher: {
+          systemPrompt: 'You are a research specialist. Search the web and compile findings.',
+        },
+      },
+    });
+
+    const events = [];
+    for await (const e of loop.stream([{ role: 'user', content: 'Research X' }], AbortSignal.timeout(10_000))) {
+      events.push(e);
+    }
+
+    expect(capturedSystemPrompts).toHaveLength(1);
+    expect(capturedSystemPrompts[0]).toBe('You are a research specialist. Search the web and compile findings.');
+  });
+
+  it('uses processSystemPrompt as default when no profile is specified', async () => {
+    orchestratorScript = [
+      threadCalls({ action: 'Do something' }),
+      finalText('Done.'),
+    ];
+
+    const stores = createInMemoryStores();
+    const loop = new ArcLoop({
+      ...stores,
+      taskId: 'test-2',
+      sessionId: 'sess-2',
+      toolProvider: createMockToolProvider(),
+      processSystemPrompt: 'You are a custom default agent.',
+    });
+
+    const events = [];
+    for await (const e of loop.stream([{ role: 'user', content: 'Do X' }], AbortSignal.timeout(10_000))) {
+      events.push(e);
+    }
+
+    expect(capturedSystemPrompts).toHaveLength(1);
+    expect(capturedSystemPrompts[0]).toBe('You are a custom default agent.');
+  });
+
+  it('falls back to built-in PROCESS_SYSTEM_PROMPT when no profile or default is set', async () => {
+    orchestratorScript = [
+      threadCalls({ action: 'Do something' }),
+      finalText('Done.'),
+    ];
+
+    const stores = createInMemoryStores();
+    const loop = new ArcLoop({
+      ...stores,
+      taskId: 'test-3',
+      sessionId: 'sess-3',
+      toolProvider: createMockToolProvider(),
+    });
+
+    const events = [];
+    for await (const e of loop.stream([{ role: 'user', content: 'Do X' }], AbortSignal.timeout(10_000))) {
+      events.push(e);
+    }
+
+    expect(capturedSystemPrompts).toHaveLength(1);
+    expect(capturedSystemPrompts[0]).toContain('focused execution thread');
+  });
+
+  it('uses profile model as default but Thread explicit model overrides it', async () => {
+    orchestratorScript = [
+      // First thread: no explicit model → should use profile's 'strong'
+      // Second thread: explicit 'fast' → should override profile's 'strong'
+      threadCalls(
+        { action: 'Synthesize report', profile: 'synthesizer' },
+        { action: 'Quick lookup', profile: 'synthesizer', model: 'fast' },
+      ),
+      finalText('Done.'),
+    ];
+
+    const stores = createInMemoryStores();
+    const loop = new ArcLoop({
+      ...stores,
+      taskId: 'test-4',
+      sessionId: 'sess-4',
+      toolProvider: createMockToolProvider(),
+      processProfiles: {
+        synthesizer: {
+          systemPrompt: 'You are a synthesis expert.',
+          model: 'strong',
+        },
+      },
+    });
+
+    const events = [];
+    for await (const e of loop.stream([{ role: 'user', content: 'Do X' }], AbortSignal.timeout(10_000))) {
+      events.push(e);
+    }
+
+    expect(capturedSystemPrompts).toHaveLength(2);
+    expect(capturedSystemPrompts[0]).toBe('You are a synthesis expert.');
+    expect(capturedSystemPrompts[1]).toBe('You are a synthesis expert.');
+
+    // First process: profile default 'strong' → resolved to model ID
+    // Second process: explicit 'fast' → resolved to Haiku model ID
+    expect(capturedModels[0]).toBe('claude-opus-4-5'); // strong tier default
+    expect(capturedModels[1]).toBe('claude-haiku-4-5'); // fast tier default
+  });
+
+  it('unknown profile falls back to processSystemPrompt or built-in default', async () => {
+    orchestratorScript = [
+      threadCalls({ action: 'Do something', profile: 'nonexistent' }),
+      finalText('Done.'),
+    ];
+
+    const stores = createInMemoryStores();
+    const loop = new ArcLoop({
+      ...stores,
+      taskId: 'test-5',
+      sessionId: 'sess-5',
+      toolProvider: createMockToolProvider(),
+      processSystemPrompt: 'Custom default prompt.',
+      processProfiles: {
+        researcher: { systemPrompt: 'Research prompt.' },
+      },
+    });
+
+    const events = [];
+    for await (const e of loop.stream([{ role: 'user', content: 'Do X' }], AbortSignal.timeout(10_000))) {
+      events.push(e);
+    }
+
+    expect(capturedSystemPrompts).toHaveLength(1);
+    // Unknown profile → falls back to processSystemPrompt
+    expect(capturedSystemPrompts[0]).toBe('Custom default prompt.');
+  });
+
+  it('profile maxSteps overrides config processMaxSteps', async () => {
+    orchestratorScript = [
+      threadCalls({ action: 'Quick task', profile: 'fast_worker' }),
+      finalText('Done.'),
+    ];
+
+    const stores = createInMemoryStores();
+    const loop = new ArcLoop({
+      ...stores,
+      taskId: 'test-6',
+      sessionId: 'sess-6',
+      toolProvider: createMockToolProvider(),
+      processMaxSteps: 20,
+      processProfiles: {
+        fast_worker: {
+          systemPrompt: 'Be fast.',
+          maxSteps: 3,
+        },
+      },
+    });
+
+    const events = [];
+    for await (const e of loop.stream([{ role: 'user', content: 'Do X' }], AbortSignal.timeout(10_000))) {
+      events.push(e);
+    }
+
+    // The process completed in 1 step (immediate text, no tools).
+    // We can't directly observe maxSteps from outside, but we can verify
+    // the process dispatched and completed successfully with the profile.
+    const dispatched = events.filter(e => e.type === 'process_dispatched');
+    const completed = events.filter(e => e.type === 'process_completed');
+    expect(dispatched).toHaveLength(1);
+    expect(completed).toHaveLength(1);
+  });
+
+  it('different profiles in the same turn get different system prompts', async () => {
+    orchestratorScript = [
+      threadCalls(
+        { action: 'Search the web', profile: 'researcher' },
+        { action: 'Write the report', profile: 'writer' },
+      ),
+      finalText('Done.'),
+    ];
+
+    const stores = createInMemoryStores();
+    const loop = new ArcLoop({
+      ...stores,
+      taskId: 'test-7',
+      sessionId: 'sess-7',
+      toolProvider: createMockToolProvider(),
+      processProfiles: {
+        researcher: { systemPrompt: 'You are a web researcher.' },
+        writer: { systemPrompt: 'You are a technical writer.' },
+      },
+    });
+
+    const events = [];
+    for await (const e of loop.stream([{ role: 'user', content: 'Do X' }], AbortSignal.timeout(10_000))) {
+      events.push(e);
+    }
+
+    expect(capturedSystemPrompts).toHaveLength(2);
+    // Order may vary due to parallel execution, so check both are present
+    expect(capturedSystemPrompts).toContain('You are a web researcher.');
+    expect(capturedSystemPrompts).toContain('You are a technical writer.');
+  });
+});