Unified Stack Architecture

→ Documentation Index | Related: Glossary | Stack Guide

Purpose

This 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.

Architecture Stance

The current stack has one strong center and several supporting seams:

• @a5c-ai/babysitter-sdk remains the orchestration core.
• @a5c-ai/babysitter and @a5c-ai/genty-platform provide the operational CLI and runtime surfaces.
• packages/adapters/* provide the dispatch layer for harness-facing agent execution.
• @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.
• plugins/babysitter-unified/ is the canonical plugin source, while per-harness plugin bundles remain the user-installable outputs.

This is a unified executable stack with explicit package families, not a promise that every family must become its own larger platform.

End-To-End Shape

Responsibility Map

The architecture is easiest to reason about as five package families that meet at the orchestration core.

1. Orchestration Core

Owned primarily by:

• packages/babysitter-sdk
• packages/babysitter
• packages/genty/platform

This layer owns runs, replay, task definitions, journal/state handling, hooks dispatch, profiles, process-library bindings, and the CLI commands that operate on those concepts.

2. Dispatch Layer

Owned primarily by:

• packages/adapters/core
• packages/adapters/adapters
• packages/adapters/cli
• packages/adapters/sdk
• packages/adapters/gateway
• packages/adapters/harness-mock
• packages/adapters/observability

This 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.

3. Cross-Harness Support Systems

Owned primarily by:

• packages/adapters/hooks/*
• packages/extensions-adapter
• packages/tasks-adapter

These packages solve cross-cutting problems:

• hooks-adapter normalizes hook events and adapter wiring.
• extensions-adapter compiles one canonical plugin description into harness-specific outputs.
• tasks-adapter routes human approvals and structured breakpoint responses.

This 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.

4. Distribution And Installation Surfaces

Owned primarily by:

• plugins/babysitter-unified
• plugins/babysitter-*

The important distinction is:

• plugins/babysitter-unified/ is the canonical authoring surface.
• plugins/babysitter-codex, plugins/babysitter-gemini, and similar directories are the concrete installable bundles and compatibility surfaces.

5. User Experience Surfaces

Owned primarily by:

• packages/adapters/tui
• packages/adapters/webui
• packages/adapters/ui
• packages/adapters/mobile-*
• packages/adapters/tv-*
• packages/adapters/watch-*
• docs/, docs-site/

These 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.

Package Family Map

Operational Path Through The Stack

The end-to-end diagram above is the shape. The live execution narrative is:

1. A concrete harness installs or loads a plugin bundle under plugins/babysitter-*. 2. 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. 3. The installed bundle reaches the operational runtime in packages/babysitter and packages/genty/platform. 4. 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. 5. When a workflow requires a reusable process, the runtime reaches into library/ or project-local .a5c/processes/. 6. 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. 7. When the system needs adapter-level dispatch or richer interaction surfaces, packages/adapters/* carries that responsibility without changing the orchestration center of gravity.

Integration Contracts That Matter

Babysitter ↔ Harnesses

Harnesses are reached through plugin bundles, lifecycle hooks, and session binding behavior. This is where plugins/*, hooks-adapter, and harness-specific install surfaces matter.

Babysitter ↔ Agent-Adapter

The key boundary is orchestration versus dispatch:

• Babysitter owns process execution, runs, replay, and effect lifecycles.
• adapters owns adapter-level normalization, event streams, invocation modes, and harness interaction surfaces.

Unified Plugin ↔ Per-Harness Bundles

The unified plugin is the authoring source. Per-harness bundles are the compatibility outputs. V6 should describe both, not collapse them into one concept.

Orchestration ↔ Human Approval

Breakpoint 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.

V6 ↔ Validation

The current executable seam contract is validated at the repo level through:

• npm run verify:v6:seams

That command matters because V6 is supposed to promote real seams with active checks, not only naming changes in design docs.

What Is Normative Now

• The monorepo already contains Babysitter, adapters, hooks-adapter, extensions-adapter, and tasks-adapter.
• packages/babysitter-sdk is still the main center of gravity.
• adapters is already integrated as repo content, workspace packages, and documentation.
• Unified plugin authoring coexists with per-harness plugin bundles.
• 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.
• npm run verify:v6:seams is the active repo validation cue for the first executable V6 seam contract.

What Is Deferred

• Any forced rename from current packages into a new runtime/platform/application stack.
• Any claim that the adapter support packages must become a larger formal platform before their current seams are proven.
• Any architectural story that assumes remote, distributed, or strongly isolated plugin execution by default.
• Any claim that documented placeholder seams such as packages/transport-adapter are already cut over into the active runtime.

Validation And Honesty Cues

When a section in this document makes a structural claim, check it against three concrete surfaces:

• **Repo paths**: the relevant package or plugin directory must already exist.
• **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.
• **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.

Reading Rule

If a design discussion makes the stack sound cleaner than the current repo, check whether it is:

1. a real package/path in this monorepo, 2. a current V6 commitment, or 3. only deferred vocabulary.

If the answer is only "vocabulary", it is not yet architecture.

---

**Related Documents**: System Overview | Package Specifications | Agent-Adapter Integration