{
  "id": "page:docs-v6-spec-and-roadmap-unified-stack-architecture",
  "_kind": "Page",
  "_file": "wiki/docs/v6-spec-and-roadmap/unified-stack-architecture.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/v6-spec-and-roadmap/unified-stack-architecture.md",
    "sourceKind": "repo-docs",
    "title": "Unified Stack Architecture",
    "displayName": "Unified Stack Architecture",
    "slug": "docs/v6-spec-and-roadmap/unified-stack-architecture",
    "articlePath": "wiki/docs/v6-spec-and-roadmap/unified-stack-architecture.md",
    "article": "\n# Unified Stack Architecture\n\n→ [Documentation Index](README.md) | Related: [Glossary](glossary.md) | [Stack Guide](stack-guide.md)\n\n## Purpose\n\nThis document explains how the already-unified Babysitter and adapters stack fits together in the current monorepo. It is a map of today's executable system, not a promise of a larger future decomposition.\n\n## Architecture Stance\n\nThe current stack has one strong center and several supporting seams:\n\n- `@a5c-ai/babysitter-sdk` remains the orchestration core.\n- `@a5c-ai/babysitter` and `@a5c-ai/genty-platform` provide the operational CLI and runtime surfaces.\n- `packages/adapters/*` provide the dispatch layer for harness-facing agent execution.\n- `@a5c-ai/hooks-adapter-cli`, `@a5c-ai/extensions-adapter`, and `@a5c-ai/tasks-adapter` are focused support subsystems that normalize hooks, compile plugins, and route human approvals.\n- `plugins/babysitter-unified/` is the canonical plugin source, while per-harness plugin bundles remain the user-installable outputs.\n\nThis is a unified executable stack with explicit package families, not a promise that every family must become its own larger platform.\n\n## End-To-End Shape\n\n```mermaid\nflowchart TD\n  H[Harness surfaces<br/>Codex, Claude Code, Cursor, Gemini, Copilot, Pi, OpenCode]\n  U[Unified plugin source<br/>plugins/babysitter-unified]\n  P[Per-harness plugin bundles<br/>plugins/babysitter-*]\n  HM[hooks-adapter<br/>canonical hook model]\n  CLI[babysitter CLI and runtime<br/>@a5c-ai/babysitter<br/>@a5c-ai/genty-platform]\n  SDK[babysitter-sdk<br/>runs, replay, storage, tasks]\n  LIB[Process library and project processes<br/>library/, .a5c/processes, ~/.a5c]\n  BP[tasks-adapter<br/>human approval routing]\n  APM[extensions-adapter<br/>plugin compilation]\n  ADAPTERS[adapters packages<br/>core, adapters, cli, sdk, gateway]\n  UI[User surfaces<br/>TUI, web UI, mobile, docs]\n\n  U --> APM\n  APM --> P\n  H --> P\n  P --> HM\n  P --> CLI\n  HM --> CLI\n  CLI --> SDK\n  SDK --> LIB\n  SDK --> BP\n  CLI --> ADAPTERS\n  ADAPTERS --> UI\n```\n\n## Responsibility Map\n\nThe architecture is easiest to reason about as five package families that meet at the orchestration core.\n\n### 1. Orchestration Core\n\nOwned primarily by:\n\n- `packages/babysitter-sdk`\n- `packages/babysitter`\n- `packages/genty/platform`\n\nThis layer owns runs, replay, task definitions, journal/state handling, hooks dispatch, profiles, process-library bindings, and the CLI commands that operate on those concepts.\n\n### 2. Dispatch Layer\n\nOwned primarily by:\n\n- `packages/adapters/core`\n- `packages/adapters/adapters`\n- `packages/adapters/cli`\n- `packages/adapters/sdk`\n- `packages/adapters/gateway`\n- `packages/adapters/harness-mock`\n- `packages/adapters/observability`\n\nThis layer knows how to talk to different harnesses and normalize them into a shared agent-running contract. It is complementary to Babysitter rather than a replacement for it: Babysitter orchestrates process execution; adapters dispatches and normalizes harness interaction.\n\n### 3. Cross-Harness Support Systems\n\nOwned primarily by:\n\n- `packages/adapters/hooks/*`\n- `packages/extensions-adapter`\n- `packages/tasks-adapter`\n\nThese packages solve cross-cutting problems:\n\n- `hooks-adapter` normalizes hook events and adapter wiring.\n- `extensions-adapter` compiles one canonical plugin description into harness-specific outputs.\n- `tasks-adapter` routes human approvals and structured breakpoint responses.\n\nThis support layer is part of the delivery path for metaplugins on legacy non-Babysitter agents, but it is not the metaplugin abstraction itself. Metaplugins sit one level higher: they package reusable capability concerns across plugin and hook surfaces. `extensions-adapter` emits the concrete bundles those concerns need, while unified plugin sources such as `plugins/babysitter-unified/` provide one first-party authoring surface for that delivery.\n\n### 4. Distribution And Installation Surfaces\n\nOwned primarily by:\n\n- `plugins/babysitter-unified`\n- `plugins/babysitter-*`\n\nThe important distinction is:\n\n- `plugins/babysitter-unified/` is the canonical authoring surface.\n- `plugins/babysitter-codex`, `plugins/babysitter-gemini`, and similar directories are the concrete installable bundles and compatibility surfaces.\n\n### 5. User Experience Surfaces\n\nOwned primarily by:\n\n- `packages/adapters/tui`\n- `packages/adapters/webui`\n- `packages/adapters/ui`\n- `packages/adapters/mobile-*`\n- `packages/adapters/tv-*`\n- `packages/adapters/watch-*`\n- `docs/`, `docs-site/`\n\nThese packages are consumers of the orchestration and dispatch layers. They are not the architectural center of V6, but they are part of the stack and need coherent ownership boundaries.\n\n## Package Family Map\n\n| Family | Primary paths | What it owns now | What it does not imply |\n|---|---|---|---|\n| Orchestration core | `packages/babysitter-sdk`, `packages/babysitter`, `packages/genty/platform` | Run lifecycle, replay, storage, task dispatch, CLI/runtime surfaces | A future forced split into many more top-level runtime packages |\n| Dispatch family | `packages/adapters/*` | Harness invocation, adapter normalization, gateway, shared interaction contracts | Replacement of Babysitter orchestration |\n| Support adapter family | `packages/adapters/hooks/*`, `packages/extensions-adapter`, `packages/tasks-adapter` | Hook normalization, bundle compilation, human approval routing | A formal \"platform layer\" that already has independent product boundaries |\n| Distribution surfaces | `plugins/babysitter-unified`, `plugins/babysitter-*` | Canonical plugin authoring plus harness-specific installable outputs | One single bundle format with no compatibility constraints |\n| User surfaces | `packages/adapters/ui`, `packages/adapters/webui`, `packages/adapters/tui`, `docs-site/` | Human-facing interaction, visualization, docs, and operator surfaces | Ownership of orchestration semantics |\n\n## Operational Path Through The Stack\n\nThe end-to-end diagram above is the shape. The live execution narrative is:\n\n1. A concrete harness installs or loads a plugin bundle under `plugins/babysitter-*`.\n2. Those bundles are compiled from `plugins/babysitter-unified/` by `packages/extensions-adapter`, with `packages/adapters/hooks/*` normalizing hook behavior where the harness model requires it.\n3. The installed bundle reaches the operational runtime in `packages/babysitter` and `packages/genty/platform`.\n4. That runtime delegates the core orchestration work to `packages/babysitter-sdk`, which owns run directories, journal/state replay, effect requests, process-library binding, and workflow execution.\n5. When a workflow requires a reusable process, the runtime reaches into `library/` or project-local `.a5c/processes/`.\n6. When a workflow requires human approval routing, `packages/tasks-adapter` handles that concern as a distinct subsystem instead of burying it inside generic hook language.\n7. When the system needs adapter-level dispatch or richer interaction surfaces, `packages/adapters/*` carries that responsibility without changing the orchestration center of gravity.\n\n## Integration Contracts That Matter\n\n### Babysitter ↔ Harnesses\n\nHarnesses are reached through plugin bundles, lifecycle hooks, and session binding behavior. This is where `plugins/*`, `hooks-adapter`, and harness-specific install surfaces matter.\n\n### Babysitter ↔ Agent-Adapter\n\nThe key boundary is orchestration versus dispatch:\n\n- Babysitter owns process execution, runs, replay, and effect lifecycles.\n- adapters owns adapter-level normalization, event streams, invocation modes, and harness interaction surfaces.\n\n### Unified Plugin ↔ Per-Harness Bundles\n\nThe unified plugin is the authoring source. Per-harness bundles are the compatibility outputs. V6 should describe both, not collapse them into one concept.\n\n### Orchestration ↔ Human Approval\n\nBreakpoint routing is a distinct concern. `tasks-adapter` should be discussed as a supporting subsystem for approvals rather than folded into generic hook or session language.\n\n### V6 ↔ Validation\n\nThe current executable seam contract is validated at the repo level through:\n\n- `npm run verify:v6:seams`\n\nThat command matters because V6 is supposed to promote real seams with active checks, not only naming changes in design docs.\n\n## What Is Normative Now\n\n- The monorepo already contains Babysitter, adapters, hooks-adapter, extensions-adapter, and tasks-adapter.\n- `packages/babysitter-sdk` is still the main center of gravity.\n- adapters is already integrated as repo content, workspace packages, and documentation.\n- Unified plugin authoring coexists with per-harness plugin bundles.\n- Metaplugins are a current capability-layer concept over plugin and hook surfaces, with `extensions-adapter` serving as the concrete bundle compiler for legacy non-Babysitter agents.\n- `npm run verify:v6:seams` is the active repo validation cue for the first executable V6 seam contract.\n\n## What Is Deferred\n\n- Any forced rename from current packages into a new runtime/platform/application stack.\n- Any claim that the adapter support packages must become a larger formal platform before their current seams are proven.\n- Any architectural story that assumes remote, distributed, or strongly isolated plugin execution by default.\n- Any claim that documented placeholder seams such as `packages/transport-adapter` are already cut over into the active runtime.\n\n## Validation And Honesty Cues\n\nWhen a section in this document makes a structural claim, check it against three concrete surfaces:\n\n- **Repo paths**: the relevant package or plugin directory must already exist.\n- **Validation commands**: the claim should connect to active checks such as `npm run verify:v6:seams` and, when broader package-boundary honesty matters, `npm run test:architecture`.\n- **Placeholder docs**: if a seam is still aspirational, its docs should say so explicitly, as `packages/transport-adapter/README.md` and `packages/transport-adapter/architecture.md` currently do.\n\n## Reading Rule\n\nIf a design discussion makes the stack sound cleaner than the current repo, check whether it is:\n\n1. a real package/path in this monorepo,\n2. a current V6 commitment, or\n3. only deferred vocabulary.\n\nIf the answer is only \"vocabulary\", it is not yet architecture.\n\n---\n\n**Related Documents**: [System Overview](system-overview.md) | [Package Specifications](package-specs.md) | [Agent-Adapter Integration](adapters-integration.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-v6-spec-and-roadmap",
      "to": "page:docs-v6-spec-and-roadmap-unified-stack-architecture",
      "kind": "contains_page"
    }
  ]
}