{
  "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 agent-mux 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/babysitter-agent` provide the operational CLI and runtime surfaces.\n- `packages/agent-mux/*` provide the dispatch layer for harness-facing agent execution.\n- `@a5c-ai/hooks-mux`, `@a5c-ai/agent-plugins-mux`, and `@a5c-ai/breakpoints-mux` 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-mux<br/>canonical hook model]\n  CLI[babysitter CLI and runtime<br/>@a5c-ai/babysitter<br/>@a5c-ai/babysitter-agent]\n  SDK[babysitter-sdk<br/>runs, replay, storage, tasks]\n  LIB[Process library and project processes<br/>library/, .a5c/processes, ~/.a5c]\n  BP[breakpoints-mux<br/>human approval routing]\n  APM[agent-plugins-mux<br/>plugin compilation]\n  AMUX[agent-mux 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 --> AMUX\n  AMUX --> 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/sdk`\n- `packages/babysitter`\n- `packages/babysitter-agent`\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/agent-mux/core`\n- `packages/agent-mux/adapters`\n- `packages/agent-mux/cli`\n- `packages/agent-mux/sdk`\n- `packages/agent-mux/gateway`\n- `packages/agent-mux/harness-mock`\n- `packages/agent-mux/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; agent-mux dispatches and normalizes harness interaction.\n\n### 3. Cross-Harness Support Systems\n\nOwned primarily by:\n\n- `packages/hooks-mux/*`\n- `packages/agent-plugins-mux`\n- `packages/breakpoints-mux`\n\nThese packages solve cross-cutting problems:\n\n- `hooks-mux` normalizes hook events and adapter wiring.\n- `agent-plugins-mux` compiles one canonical plugin description into harness-specific outputs.\n- `breakpoints-mux` 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. `agent-plugins-mux` 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/agent-mux/tui`\n- `packages/agent-mux/webui`\n- `packages/agent-mux/ui`\n- `packages/agent-mux/mobile-*`\n- `packages/agent-mux/tv-*`\n- `packages/agent-mux/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/sdk`, `packages/babysitter`, `packages/babysitter-agent` | Run lifecycle, replay, storage, task dispatch, CLI/runtime surfaces | A future forced split into many more top-level runtime packages |\n| Dispatch family | `packages/agent-mux/*` | Harness invocation, adapter normalization, gateway, shared interaction contracts | Replacement of Babysitter orchestration |\n| Support mux family | `packages/hooks-mux/*`, `packages/agent-plugins-mux`, `packages/breakpoints-mux` | 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/agent-mux/ui`, `packages/agent-mux/webui`, `packages/agent-mux/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/agent-plugins-mux`, with `packages/hooks-mux/*` normalizing hook behavior where the harness model requires it.\n3. The installed bundle reaches the operational runtime in `packages/babysitter` and `packages/babysitter-agent`.\n4. That runtime delegates the core orchestration work to `packages/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/breakpoints-mux` 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/agent-mux/*` 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-mux`, and harness-specific install surfaces matter.\n\n### Babysitter ↔ Agent-Mux\n\nThe key boundary is orchestration versus dispatch:\n\n- Babysitter owns process execution, runs, replay, and effect lifecycles.\n- agent-mux 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. `breakpoints-mux` 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, agent-mux, hooks-mux, agent-plugins-mux, and breakpoints-mux.\n- `packages/sdk` is still the main center of gravity.\n- agent-mux 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 `agent-plugins-mux` 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 mux 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-mux` 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-mux/README.md` and `packages/transport-mux/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-Mux Integration](agent-mux-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"
    }
  ]
}