{
  "id": "page:docs-user-guide-features-architecture-overview",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/features/architecture-overview.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/features/architecture-overview.md",
    "sourceKind": "repo-docs",
    "title": "Architecture Overview",
    "displayName": "Architecture Overview",
    "slug": "docs/user-guide/features/architecture-overview",
    "articlePath": "wiki/docs/user-guide/features/architecture-overview.md",
    "article": "\n[Docs](../index.md) › [Features](./index.md) › Architecture Overview\n\n# Architecture Overview\n\n**Version:** 6.0.0 (v6)\n**Last Updated:** 2026-06-22\n**Category:** Feature Guide\n\n---\n\n## In Plain English\n\n**Babysitter v6 is built around one headline subsystem: Adapters - the harness-agnostic runtime that lets the same orchestration run on any supported AI coding harness.**\n\nThink of it like this:\n- **Adapters** is the universal adapter plug - it lets Babysitter speak to Claude Code, Codex, Cursor, Gemini, and the rest through one common interface\n- **The SDK** is the operations team - it actually runs the process\n- **The Journal** is the filing cabinet - it keeps a replayable record of everything\n- **Breakpoints** are the approval desk - they pause for human review when needed\n- **Atlas** is the directory - the catalog the runtime reads to discover each harness's capabilities\n\n**Tip for beginners:** You don't need to understand the architecture to use Babysitter. This document is for those who want to understand how it works under the hood, or who are building custom processes.\n\n**Related:** [Adapters](./adapters.md) for the headline subsystem, and [Two-Loops Architecture](./two-loops-architecture.md) for the conceptual model of orchestration and AI working together.\n\n---\n\n## On this page\n\n- [Overview](#overview)\n- [High-Level Architecture](#high-level-architecture)\n- [Core Components](#core-components)\n- [Data Flow](#data-flow)\n- [State Management](#state-management)\n- [Extensibility](#extensibility)\n- [Design Patterns](#design-patterns)\n\n---\n\n## Overview\n\nBabysitter v6 uses a modular, **harness-agnostic** architecture designed for reliability, debuggability, and extensibility. The system combines a deterministic orchestration engine with adaptive AI capabilities, runs on top of the **Adapters** runtime so it is not tied to any single harness, and is backed by an event-sourced persistence layer.\n\nThe central change from the prior (Claude-only) design: orchestration no longer assumes one harness and one continuation hook. The Adapters runtime - together with the [Hooks Adapter](./hooks.md), [Breakpoints Adapter](./breakpoints.md), Transport Adapter, and the Atlas catalog - makes [harness](../reference/glossary.md)-agnosticism the core story.\n\n---\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n    subgraph Entry[\"Entry Points\"]\n        ADP[\"adapters CLI (host-side)\"]\n        SES[\"/babysitter:* (in-session, varies by harness)\"]\n    end\n\n    subgraph Runtime[\"Adapters Runtime (harness-agnostic core)\"]\n        ENGINE[\"Process Engine + SDK\"]\n        HOOKS[\"Hooks Adapter (canonical session store + merge engine)\"]\n        BP[\"Breakpoints Adapter\"]\n        TRANS[\"Transport Adapter + Triggers\"]\n        OBS[\"Observability\"]\n    end\n\n    ATLAS[\"Atlas (capability + adapter catalog)\"]\n\n    subgraph Store[\"Run Store: .a5c/runs/&lt;runId&gt;/\"]\n        J[\"journal/ (event log)\"]\n        ST[\"state/state.json\"]\n        ART[\"artifacts/ · tasks/&lt;effectId&gt;/\"]\n    end\n\n    subgraph Harnesses\n        H[\"Claude Code · Codex · Cursor · Gemini · Copilot · ...\"]\n    end\n\n    ADP --> ENGINE\n    SES --> ENGINE\n    ENGINE --> HOOKS\n    ENGINE --> BP\n    ENGINE --> TRANS\n    ENGINE --> OBS\n    ENGINE --> Store\n    ENGINE --> ATLAS\n    ATLAS --> Harnesses\n    HOOKS --> Harnesses\n```\n\n---\n\n## Core Components\n\n### 1. Adapters Runtime\n\n**Package family:** `@a5c-ai/*-adapter` (formerly the `-mux` / Agent Mux packages) under `packages/adapters/*`\n\n**Responsibilities:**\n- Presents a harness-agnostic run/session/options model to the orchestration engine\n- Normalizes each harness's distinct hook/continuation model via the [Hooks Adapter](./hooks.md)\n- Routes runs to providers via the Transport Adapter and the proxy used by `adapters launch`\n- Reads the Atlas catalog to discover harness capabilities\n\n**Technology:** Node.js, TypeScript. See [Adapters](./adapters.md) and the [Adapters CLI Reference](../reference/adapters-cli.md).\n\n---\n\n### 2. Babysitter Skill / Plugin (per harness)\n\n**Location:** `plugins/babysitter-unified/skills/babysit/` (and the per-harness plugin packages)\n\n**Responsibilities:**\n- Parses natural language commands into process inputs\n- Orchestrates the run loop via the SDK/CLI on top of the Adapters runtime\n- Manages iteration lifecycle and resumption\n- Reports progress back to the harness\n\n**Technology:** The harness's plugin/skill system (JavaScript/TypeScript). The in-session command surface and continuation model **vary by harness** - see [Hooks](./hooks.md) and the [Install Matrix](../harnesses/install-matrix.md).\n\n---\n\n### 3. Babysitter SDK\n\n**Package:** `@a5c-ai/babysitter-sdk`\n\n**Core Modules:**\n\n| Module | Purpose | Key Functions |\n|--------|---------|--------------|\n| **Process Engine** | Executes process definitions | `runProcess()`, `iterate()` |\n| **Journal Manager** | Event-sourced persistence | `append()`, `replay()`, `getState()` |\n| **Task Executor** | Runs tasks (agent, skill, node) | `executeTask()`, `parallel.all()` |\n| **State Manager** | Maintains run state cache | `saveState()`, `loadState()` |\n| **Hook System** | Extensibility points | `registerHook()`, `trigger()` |\n\n**Technology:** Node.js, TypeScript\n\n---\n\n### 4. Event-Sourced Journal\n\n**Format:** Individual JSON files in `journal/` directory, one per event, named `{SEQ}.{ULID}.json` (e.g. `000001.01ARZ3NDEKTSV4RRFFQ69G5FAV.json`)\n\n**Event Types:**\n\n```typescript\ntype JournalEvent =\n  | { type: 'RUN_CREATED', recordedAt: string, data: { runId: string, inputs: any }, checksum: string }\n  | { type: 'EFFECT_REQUESTED', recordedAt: string, data: { effectId: string, kind: string, args: any }, checksum: string }\n  | { type: 'EFFECT_RESOLVED', recordedAt: string, data: { effectId: string, result: any }, checksum: string }\n  | { type: 'RUN_COMPLETED', recordedAt: string, data: { status: string }, checksum: string }\n  | { type: 'RUN_FAILED', recordedAt: string, data: { error: string }, checksum: string }\n\n// Note: seq is derived from the filename, not stored in the event body.\n// Breakpoints use EFFECT_REQUESTED with kind: 'breakpoint' and EFFECT_RESOLVED.\n```\n\n**Benefits:**\n- **Deterministic replay**: Reconstruct exact state at any point\n- **Audit trail**: Complete history of all actions\n- **Debugging**: Trace execution flow and identify issues\n- **Resumability**: Continue from last event after interruption\n\n**Implementation:**\n```javascript\n// Write individual JSON file per event\nfunction appendEvent(event, seq) {\n  const filename = `${String(seq).padStart(6, '0')}.${ulid()}.json`;\n  fs.writeFileSync(path.join(journalDir, filename), JSON.stringify(event, null, 2));\n}\n\n// Replay by reading all JSON files from journal/ directory\nfunction replayJournal() {\n  const files = fs.readdirSync(journalDir)\n    .filter(f => f.endsWith('.json'))\n    .sort(); // lexicographic sort preserves sequence order\n\n  const events = files.map(f =>\n    JSON.parse(fs.readFileSync(path.join(journalDir, f), 'utf-8'))\n  );\n\n  return events.reduce(applyEvent, initialState);\n}\n```\n\nFor more details on the journal system, see [Journal System](./journal-system.md).\n\n---\n\n### 5. Process Definitions\n\n**Format:** JavaScript/TypeScript functions\n\n**Execution Model:**\n\n```\n+----------------------------------------------------------+\n| Process Definition (JavaScript)                          |\n|                                                          |\n|  export async function process(inputs, ctx) {           |\n|    // User-defined orchestration logic                  |\n|    const result = await ctx.task(someTask, args);       |\n|    await ctx.breakpoint({ question: '...' });           |\n|    return result;                                        |\n|  }                                                       |\n+----------------------------------------------------------+\n                          |\n                          v\n+----------------------------------------------------------+\n| Context API (ctx)                                        |\n|                                                          |\n|  - ctx.task(task, args, opts)       Execute task        |\n|  - ctx.breakpoint(opts)             Wait for approval   |\n|    Returns BreakpointResult: { approved, feedback, ... }|\n|  - ctx.parallel.all([...])          Run in parallel     |\n|  - ctx.hook(name, data)             Trigger hooks       |\n|  - ctx.log(msg, data)               Log to journal      |\n|  - ctx.getState(key)                Access state        |\n|  - ctx.setState(key, value)         Update state        |\n+----------------------------------------------------------+\n```\n\n**Process Lifecycle:**\n\n1. **Load**: Process definition loaded from file or default\n2. **Initialize**: Context created with state and journal access\n3. **Execute**: Process function called with inputs and context\n4. **Iterate**: Process may loop internally or be called multiple times\n5. **Complete**: Process returns final result\n\nFor more details on creating processes, see [Process Definitions](./process-definitions.md).\n\n---\n\n### 6. Task Execution System\n\n**Task Types:**\n\n| Type | Executor | Use Case | Example |\n|------|----------|----------|---------|\n| **Agent** | LLM API | Planning, analysis, scoring | Any supported harness |\n| **Skill** | Harness skill | Code operations | Refactoring, search |\n| **Node** | Node.js | Scripts and tools | Build, test, deploy |\n| **Shell** | System shell | Commands | git, npm, docker |\n\n**Execution Flow:**\n\n```\n+---------------------------------------------------------+\n| Task Request                                            |\n| ctx.task(taskDef, args, opts)                           |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Task Validation                                         |\n| - Validate arguments                                    |\n| - Check dependencies                                    |\n| - Generate task ID                                      |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Journal Event: EFFECT_REQUESTED                         |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Execute Task                                            |\n| - Agent: Call LLM API                                   |\n| - Skill: Invoke the harness skill                       |\n| - Node: Run JavaScript function                         |\n| - Shell: Execute command                                |\n| - Breakpoint: Wait for approval (kind: breakpoint)      |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Journal Event: EFFECT_RESOLVED                          |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Return Result                                           |\n| - Success: Return task output                           |\n| - Failure: Throw error or return error object           |\n+---------------------------------------------------------+\n```\n\n**Parallel Execution:**\n\n```javascript\n// Tasks run concurrently with Promise.all\nawait ctx.parallel.all([\n  () => ctx.task(task1, args1),\n  () => ctx.task(task2, args2),\n  () => ctx.task(task3, args3)\n]);\n\n// All results returned when all complete\n// If any fails, entire parallel group fails\n```\n\nFor more details on parallel execution, see [Parallel Execution](./parallel-execution.md).\n\n---\n\n## Data Flow\n\n**Complete Request Flow:**\n\n```\n1. User Command\n   |\n   +--> Harness (Claude Code, Codex, Cursor, ...)\n        |\n        +--> Babysitter Skill\n             |\n             +-- Parse intent\n             +-- Load/create run\n             +--> CLI: babysitter run:iterate (on the Adapters runtime)\n                  |\n                  +--> SDK Process Engine\n                       |\n                       +-- Load process definition\n                       +-- Replay journal -> restore state\n                       +-- Execute process function\n                       |    |\n                       |    +-- ctx.task() -> Execute tasks\n                       |    |    |\n                       |    |    +-- Append EFFECT_REQUESTED\n                       |    |    +-- Run executor (agent/skill/node/shell)\n                       |    |    +-- Append EFFECT_RESOLVED\n                       |    |\n                       |    +--> ctx.breakpoint() -> Wait for approval\n                       |         |\n                       |         +-- Append EFFECT_REQUESTED (kind: breakpoint)\n                       |         +-- Poll for response\n                       |         +-- Append EFFECT_RESOLVED\n                       |\n                       +-- Append iteration events to journal\n                       +-- Save state cache\n                       +--> Return results to skill\n                            |\n                            +--> Report to the harness\n                                 |\n                                 +--> Display to user\n```\n\n---\n\n## State Management\n\n**Two-Layer State System:**\n\n1. **Journal (source of truth)**:\n   - Append-only event log\n   - Immutable history\n   - Replayed to reconstruct state\n\n2. **State Cache (performance)**:\n   - Snapshot of current state\n   - Rebuilt from journal if missing\n   - Fast access without replay\n\n**State Structure:**\n\n```typescript\ninterface RunState {\n  runId: string;\n  status: 'running' | 'paused' | 'completed' | 'failed';\n  iteration: number;\n  inputs: any;\n  outputs?: any;\n  processState: Map<string, any>;  // Process-specific state\n  taskResults: Map<string, any>;    // Cached task results\n  metrics: {\n    startTime: number;\n    endTime?: number;\n    iterations: number;\n    qualityScores: number[];\n  };\n}\n```\n\n---\n\n## Extensibility\n\n**Hook System:**\n\n```javascript\n// Register custom hooks\nctx.hook('task:completed', async (taskResult) => {\n  await sendMetricsToDatadog(taskResult);\n});\n\nctx.hook('quality:score', async (score) => {\n  if (score < 70) {\n    await sendAlert('Low quality score');\n  }\n});\n\n// Built-in hook points\n- 'run:started'\n- 'run:completed'\n- 'iteration:started'\n- 'iteration:completed'\n- 'task:started'\n- 'task:completed'\n- 'breakpoint:requested'\n- 'breakpoint:resolved'\n- 'quality:score'\n```\n\n**Custom Task Types:**\n\n```javascript\n// Define custom task executor\nfunction registerCustomTask(type, executor) {\n  taskExecutors.set(type, executor);\n}\n\n// Use custom task\nawait ctx.task({ type: 'custom', fn: myExecutor }, args);\n```\n\nFor more details on hooks, see [Hooks](./hooks.md).\n\n---\n\n## Technology Stack\n\n| Component | Technology | Purpose |\n|-----------|-----------|---------|\n| **Adapters Runtime** | TypeScript + Node.js | Harness-agnostic run/session model |\n| **Plugin** | JavaScript/TypeScript | Per-harness integration (12 harnesses) |\n| **SDK** | TypeScript + Node.js | Core orchestration engine |\n| **Process Definitions** | JavaScript/TypeScript | User workflow logic |\n| **Journal** | Individual JSON files | Event persistence |\n| **CLI** | Commander.js | Command-line interface |\n\n---\n\n## Design Patterns\n\n**Event Sourcing:**\n- All state changes recorded as events\n- State derived from event replay\n- Time-travel debugging possible\n\n**Command Query Responsibility Segregation (CQRS):**\n- Write: Append events to journal\n- Read: Query state cache or replay\n\n**Saga Pattern:**\n- Long-running workflows with compensation\n- Breakpoints as decision points\n- Resumable across sessions\n\n**Plugin Architecture:**\n- Extensible via hooks\n- Custom task types\n- Process definitions as plugins\n\n---\n\n## Related Documentation\n\n- [Adapters](./adapters.md) - The headline v6 runtime and harness-agnosticism\n- [Hooks](./hooks.md) - The Hooks Adapter and per-harness continuation models\n- [Two-Loops Architecture](./two-loops-architecture.md) - Conceptual model of orchestration and AI loops\n- [Process Definitions](./process-definitions.md) - Creating custom processes\n- [Journal System](./journal-system.md) - Event sourcing and replay\n- [Breakpoints](./breakpoints.md) - Human-in-the-loop approval\n- [Parallel Execution](./parallel-execution.md) - Running tasks concurrently\n\n---\n\n## Summary\n\nBabysitter's v6 architecture is built on these key principles:\n\n- **Harness-agnostic by default**: The Adapters runtime lets the same process run on any supported harness\n- **Modular Design**: Each component has a clear, single responsibility\n- **Event Sourcing**: The journal provides a complete, replayable audit trail\n- **Two-Layer State**: Journal for truth, cache for performance\n- **Extensibility**: Hooks and custom tasks enable integration with any system\n- **Human-in-the-Loop**: Breakpoints enable approval workflows\n\nThis architecture enables reliable, debuggable, and auditable AI-powered workflows that can run on any harness and be paused, resumed, and replayed at any point.\n\n---\n\n## Next steps\n\n- **Next:** [Two-Loops Architecture](./two-loops-architecture.md)\n- **Related:** [Adapters](./adapters.md), [Journal System](./journal-system.md), [Hooks](./hooks.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-features",
      "to": "page:docs-user-guide-features-architecture-overview",
      "kind": "contains_page"
    }
  ]
}