{
  "id": "page:docs-user-guide-architecture",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/architecture.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/architecture.md",
    "sourceKind": "repo-docs",
    "title": "Architecture & How It Fits Together",
    "displayName": "Architecture & How It Fits Together",
    "slug": "docs/user-guide/architecture",
    "articlePath": "wiki/docs/user-guide/architecture.md",
    "article": "\n[Docs](./index.md) › Architecture\n\n# Architecture & How It Fits Together\n\n**Babysitter's thesis is enforcement, not assistance: deterministic process execution of complex agentic workflows, with policy/process adherence — obedience — guaranteed by a hook-enforced mandatory stop after every step. This page shows how the pieces of the ecosystem cooperate to deliver that.**\n\n---\n\n## On this page\n\n- [The vision](#the-vision)\n- [The component diagram](#the-component-diagram)\n- [The runtime flow](#the-runtime-flow)\n- [How the layers cooperate](#how-the-layers-cooperate)\n- [Maturity boundaries](#maturity-boundaries)\n- [Next steps](#next-steps)\n\n---\n\n## The vision\n\nBabysitter began as a single SDK for orchestrating Claude Code. v6 reframes it as a **universal orchestration platform**: run the same Babysitter processes on *any* AI coding harness, on every surface (CLI, TUI, web, mobile, K8s). The unifying design principle is the **adapter pattern** — \"every integration surface is defined once in a central catalog and multiplexed to N adapters or targets through generated code.\" Adding a harness, target, or specialization is a **data change, not a code change.**\n\nThe value proposition is a triad:\n\n1. **Deterministic process execution** — your workflow is real JavaScript (`async function process(inputs, ctx)`); the orchestrator can only do what that code permits; state is event-sourced in an immutable journal for deterministic replay and resume.\n2. **Complex agentic workflows** — tasks, breakpoints, sleeps, parallel dispatch, dependencies, and sub-agent delegation across harnesses from a single entry point.\n3. **Policy / process adherence (obedience)** — a hook-enforced **mandatory stop** after each step, a process check (\"what does the process permit next?\"), and a decision (permit / halt until a gate passes). Gates block progression; they are not suggestions.\n\nQuality convergence is one capability that falls out of code-defined gates — one of roughly five differentiators (process enforcement, deterministic replay, quality convergence, human-in-the-loop breakpoints, parallel execution), not the headline.\n\n---\n\n## The component diagram\n\n```mermaid\nflowchart TB\n    subgraph Authority[\"AUTHORITY — your code\"]\n        PROC[\"PROCESS (JavaScript)<br/>ctx.task · ctx.breakpoint · parallel · sleep<br/>the orchestrator can ONLY do what this permits\"]\n    end\n\n    subgraph Core[\"Core engine\"]\n        SDK[\"@a5c-ai/babysitter-sdk<br/>defineTask · effect/journal engine<br/>built-in Pi engine · token compression<br/>immutable JOURNAL (~/.a5c/runs)<br/>deterministic replay/resume<br/>MANDATORY STOP + gate enforcement\"]\n    end\n\n    subgraph Catalog[\"Catalog\"]\n        ATLAS[\"@a5c-ai/atlas<br/>knowledge graph: harness metadata,<br/>discovery, plugin targets, topology<br/>(data, not code)\"]\n    end\n\n    subgraph Adapters[\"@a5c-ai/adapters — the family (20 packages)\"]\n        ADP[\"sdk = unified dispatch · core(comm) · codecs(per-harness)<br/>cli (adapters) · launch (PTY spawn) · config (host detect)<br/>transport · proxy (LiteLLM, 140+ providers)<br/>hooks (canonical lifecycle, MANDATORY STOP cross-harness)<br/>tasks (durable breakpoints) · tools · observability<br/>triggers (CI / GitHub Action) · extensions (1 manifest → 9 plugin formats)\"]\n    end\n\n    subgraph Runtime[\"Agent runtime\"]\n        GENTY[\"@a5c-ai/genty (binary 'genty')<br/>L4 genty-core (loop, tools, context)<br/>L5 genty-runtime (daemon, session, cost)<br/>L6 genty-platform (harness integ., governance, storage)<br/>genty call|yolo|plan|resume · --harness internal|claude-code<br/>+ UI/TUI/web/mobile/tv/watch surfaces\"]\n    end\n\n    subgraph Harnesses[\"Harnesses\"]\n        HARN[\"Claude Code · Codex · Gemini · Copilot · Cursor<br/>Pi · OMP · OpenCode · OpenClaw · Hermes · …\"]\n    end\n\n    OBS[\"@a5c-ai/babysitter-observer-dashboard<br/>real-time run observability<br/>Next.js · SSE · virtualized journals · /babysitter:observe\"]\n\n    KRADLE[\"@a5c-ai/kradle (adjacent · MVP)<br/>K8s-native Git forge: CRDs + Argo CD + Gitea<br/>per-org dispatchable assistant<br/>kradle serve · kradle mcp\"]\n\n    KIP[\"kip-sdk — packages/kip-sdk (SPEC-ONLY · no published package · not implemented)<br/>intended MEMORY SUBSTRATE<br/>git-substrate, bitemporal, signed-fact graph<br/>every component is a producer/consumer/client\"]\n\n    PROC -->|governs| SDK\n    SDK -->|reads metadata| ATLAS\n    SDK -->|delegates tasks via| ADP\n    ATLAS -.->|catalog drives adapters/hooks/plugins<br/>data, not code| ADP\n    ADP --> GENTY\n    GENTY --> HARN\n    ADP --> HARN\n    SDK -->|emits event-sourced journal SSE| OBS\n    GENTY -.-> OBS\n    KRADLE -.->|hosting / agent-dispatch substrate| ADP\n    KIP -.->|design-stage seams| SDK\n```\n\n> **Rendering note:** The Mermaid block above renders as a diagram on GitHub and GitBook. The rendered Docusaurus site does not currently load the Mermaid theme, so the same relationships are repeated below as an ASCII map — no information is lost on any surface.\n\n```\n   AUTHORITY (your code)\n   ┌────────────────────────────────────────────────────────────┐\n   │ PROCESS (JavaScript): ctx.task / ctx.breakpoint / parallel / │\n   │ sleep — the orchestrator can ONLY do what this code permits  │\n   └───────────────────────────────┬──────────────────────────────┘\n                                    │ governs\n                                    ▼\n   @a5c-ai/babysitter-sdk  ── core engine: effects, immutable JOURNAL (~/.a5c/runs),\n    (defineTask, Pi engine,    deterministic replay/resume, MANDATORY STOP + gate\n     compression, MCP)         enforcement, 4-layer token compression\n        │            │            │\n        │ reads      │ uses        │ delegates tasks to harnesses\n        ▼            ▼             ▼\n   @a5c-ai/atlas   @a5c-ai/adapters (FAMILY — 20 packages) ───────────────────────┐\n   (catalog graph: │  sdk = unified dispatch; core(comm) + codecs(per-harness)    │\n    harness meta,  │  + cli(`adapters`); launch(PTY spawn) + config(host detect)  │\n    discovery,     │  + transport + proxy(LiteLLM, 140+ providers)                │\n    plugin targets,│  + hooks(canonical lifecycle, MANDATORY STOP cross-harness)  │\n    topology) ◄────┘  + tasks(durable breakpoints) + tools + observability        │\n        ▲               + triggers(CI/GitHub Action) + extensions(plugin compile) │\n        │  catalog drives adapters/hooks/plugins (data, not code)                 │\n        │                                                                          ▼\n   @a5c-ai/genty (CLI `genty`) ── unified agent product:                    Harnesses:\n     L4 genty-core (loop, tools, context)    `genty call|yolo|plan|resume`  Claude, Codex,\n     L5 genty-runtime (daemon, session, cost) `--harness internal|claude…`  Gemini, Copilot,\n     L6 genty-platform (harness integ.,        start-server (MCP), tui,     Cursor, Pi, OMP,\n        governance, interaction, storage)      retrospect, doctor          OpenCode, OpenClaw,\n        + UI/TUI/web/mobile/tv/watch surfaces                              Hermes, …\n        │ emits event-sourced journal (SSE)\n        ▼\n   @a5c-ai/babysitter-observer-dashboard ── real-time run observability\n                                            (Next.js, SSE, virtualized journals, /babysitter:observe)\n\n   @a5c-ai/kradle   ── (adjacent · MVP) K8s-native Git forge: CRDs + Argo CD + Gitea,\n                        per-org dispatchable assistant, `kradle serve` + `kradle mcp`\n   kip-sdk          ── packages/kip-sdk (SPEC-ONLY · no published package · not implemented) intended MEMORY SUBSTRATE;\n                        every other component is a producer/consumer/client of its seams\n```\n\n---\n\n## The runtime flow\n\nA typical interactive run:\n\n1. **You invoke** `/babysitter:call` (or `genty call`).\n2. **The SDK creates a run + journal** under `~/.a5c/runs/<runId>/`.\n3. **The SDK delegates each task to a harness** via `@a5c-ai/adapters` — dispatch → codec → `launch` spawns a PTY session; an optional **proxy** gives backend freedom across 140+ providers.\n4. **After each step the hooks adapter enforces a MANDATORY STOP.**\n5. **The process code decides what is permitted next** — permit the next task, or halt until a gate passes.\n6. **At a breakpoint the tasks adapter parks a durable human-approval request** (e.g. a GitHub Issue) that survives cold starts.\n7. **Every event is appended to the immutable journal.**\n8. **The Observer Dashboard streams the journal over SSE** for real-time visibility.\n\n[Atlas](./ecosystem/atlas.md) supplies all harness/plugin/discovery metadata as generated catalog data, so none of this is hand-wired. In CI, the **triggers adapter** (a GitHub Action) normalizes the event and launches the same flow non-interactively (`--bridge-hooks`).\n\n---\n\n## How the layers cooperate\n\n| Layer | Component | Role in the flow |\n|-------|-----------|------------------|\n| Authority | Your process code | Defines what is permitted — the source of obedience. |\n| Engine | [babysitter-sdk](./ecosystem/babysitter-sdk.md) | Runs the process, journals every event, enforces the mandatory stop and gates. |\n| Catalog | [atlas](./ecosystem/atlas.md) | Supplies harness/plugin/topology metadata as data. |\n| Multiplexer | [adapters](./ecosystem/adapters.md) family | Dispatches tasks to harnesses; normalizes hooks; bridges providers; parks durable breakpoints; triggers CI; compiles plugins. |\n| Agent runtime | [genty](./ecosystem/genty.md) | Packages the agent loop/daemon/platform and the internal (Pi) harness; surfaces the CLI/TUI/UI. |\n| Harnesses | Claude Code, Codex, … | Do the adaptive work, under enforcement. |\n| Observability | [observer-dashboard](./ecosystem/observer-dashboard.md) | Streams the journal live. |\n| Adjacent | [kradle](./ecosystem/kradle.md) | A hosting/forge + agent-dispatch substrate (MVP). |\n| Design-stage | [kip-sdk](./ecosystem/kip-sdk.md) | The intended memory substrate — **spec only, no code.** |\n\n---\n\n## Maturity boundaries\n\nThe diagram mixes shipping and forward-looking pieces deliberately, so be clear which is which:\n\n- **GA / runtime:** babysitter-sdk, atlas, genty, observer-dashboard, the adapters family.\n- **MVP:** kradle (its own README's word).\n- **Spec only — not implemented:** kip-sdk (entirely Markdown; nothing to install).\n\n---\n\n## Next steps\n\n- **Tour each component:** [Ecosystem Overview](./ecosystem/overview.md)\n- **The enforcement layer up close:** [Adapter Types reference](./reference/adapter-types.md)\n- **The model in depth:** [Two-Loops Architecture](./features/two-loops-architecture.md)\n- **Run it:** [Quickstart](./getting-started/quickstart.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-architecture",
      "kind": "contains_page"
    }
  ]
}