# Package Layout

The system has three deployment contexts: a shared foundation consumed by everything, a control plane that runs as a server application, and an agent runtime that runs in many environments. Packages are organized into these three trees, which differ in versioning cadence, portability constraints, and consumers. The trees are not perfectly walled: the workflow-process migration gave the control plane and the agent-runtime host a shared repo substrate, so the control plane reaches directly into a small, enumerated set of agent-runtime packages. Those crossings are listed under Dependency Rules.

## Shared Foundation

Consumed by both the control plane and the agent runtime. Pure logic and type definitions. No environment assumptions, no I/O beyond what the caller provides.

| Package       | Purpose                                                                                                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@intx/types` | ArkType schemas, API contract, event protocol types, and the runtime interfaces (`ContextStore`, `CryptoProvider`, `MessageTransport`, `ToolRunner`). The stability contract between the two trees. |
| `@intx/authz` | Grant evaluation engine. Pattern matching, specificity ordering, condition evaluation. The hub uses it for API authorization; the harness uses it for tool-call gate enforcement.                   |
| `@intx/log`   | Logging abstraction.                                                                                                                                                                                |

Breaking changes to shared foundation packages cascade into both trees. These packages carry the strictest versioning discipline.

## Control Plane

A server application backed by Postgres. The hub packages and `db` are versioned and deployed together; `hub-client` is a browser library shipped separately to UI consumers.

| Package              | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------- |   |
| `@intx/hub-api`      | Hono app factory, context middleware, route group factories, per-request middleware, the better-auth wrapper, request/response helpers, the request context and session contract types, and the timeline read model.                                                                                                                                                                                                                                                                                                                                                                                               |
| `@intx/hub-sessions` | Sidecar websocket wire layer and typed event emitter, session service, event collector and registry, agent repository, hub session orchestrator, and the credential-push pipeline. Split into two layers: a db-free repo substrate (the `RepoStore`, workflow-run claim-check, event log, and kind-handler protocol) exported from `@intx/hub-sessions/substrate`, and the db-backed services exported from the package barrel. The `./substrate` subpath is the seam the agent-runtime host consumes to read and write the agent-state and workflow-run repos without linking the control plane's database layer. |
| `@intx/hub-common`   | Utilities genuinely shared across hub packages. Holds the id generator and its prefix table; see the package README for the rules that gate additions.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `@intx/hub-client`   | Browser/UI client library. API transport, SSE event stream transforms, instance session management. Consumed by the UI, not the hub itself.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `@intx/db`           | Drizzle schema, connection pooling, credential resolution, grant store, tenant hierarchy queries. Postgres-specific.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

`apps/hub` wires `hub-api` and `hub-sessions` together and starts the Hono server. `apps/admin-ui` is the browser SPA built against `hub-client`.

## Agent Runtime

Distributed across many environments: containers, VMs, local processes, Cloudflare Workers, browsers, mobile devices, embedded systems. `apps/sidecar` is the canonical host process for hub-orchestrated agents. Packages are split along two axes: portable core logic that runs everywhere, and environment-specific implementations that provide I/O capabilities.

### Portable Core

Uses `fetch` and `ReadableStream` exclusively. No Node APIs, no filesystem assumptions, no native bindings. Ships once, works everywhere.

| Package                | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@intx/inference`      | Provider adapters (Anthropic, OpenAI-compatible), streaming harness, reactor, director system, context management, compaction, error classification, token accounting, cross-provider message transformation, test provider, and the `transforms/` subpath (`createSizeCapTransform` and friends). The reasoning engine.                                                                                                                                                      |
| `@intx/harness`        | Agent lifecycle, event routing, tool dispatch, content safety, session channel logic. Composes inference and authz with environment-specific implementations injected at startup.                                                                                                                                                                                                                                                                                             |
| `@intx/agent`          | The code-driven agent composition surface (`createAgent`/`defineAgent`) over the `@intx/inference` reactor: send a message, stream events, project history, hot-swap inference sources. On the server runtime it is instantiated per workflow step inside a supervised workflow-process child (see `@intx/workflow-host`); it is also the peer surface to `@intx/harness`, which drives the same reactor from a mail transport. Bundles `storage-isogit` for context storage. |
| `@intx/workflow`       | Workflow state machine, definition surface, runtime, and the in-memory `runLocal` harness. Reconstructs run state from an append-only event log (`applyEvent`/`resumeFromLog`), schedules the step DAG, and drives the agent through per-step authz contexts. Depends only on `agent` and `inference`.                                                                                                                                                                        |
| `@intx/mime`           | MIME message construction, multipart assembly, PGP detached signature generation, RFC 2822 formatting, and MIME parsing. Used by message transports.                                                                                                                                                                                                                                                                                                                          |
| `@intx/pack-transport` | Git pack protocol chunking and reassembly. Transfers git object data between the hub and sidecars over WebSocket or HTTP.                                                                                                                                                                                                                                                                                                                                                     |

### Environment-Specific Implementations

Each package implements an interface defined in `@intx/types`. The harness accepts any conforming implementation. Different environments compose different implementations.

**Storage** (implements `ContextStore`):

| Package                | Environment                  | Implementation                                                                                 |
| ---------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| `@intx/storage-isogit` | Constrained (Worker/browser) | isomorphic-git with object storage (R2/S3/IndexedDB) for persistence. Pure JS, no native deps. |

**Cryptographic Identity** (implements `CryptoProvider`):

| Package        | Environment | Implementation                                                                                       |
| -------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `@intx/crypto` | Server      | Web Crypto (`subtle`). Ed25519 key generation, signing, verification. SSH/PGP/X.509 format handling. |

**Message Transport** (implements `MessageTransport`):

| Package             | Environment | Implementation                                                                                                                       |
| ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@intx/mail-memory` | Testing     | In-memory mail transport for single-process and test environments. Addresses register and exchange mail locally via local mailboxes. |

**Tool Sets**:

| Package             | Environment | What it provides                                                                                                                            |
| ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `@intx/tools-posix` | Server      | File read/write/edit, shell execution, git operations. Requires filesystem and process spawning.                                            |
| `@intx/tools-lsp`   | Server      | Language-server diagnostics. Composes with `tools-posix` and spawns LSP servers over JSON-RPC. Requires process spawning and `which` shell. |
| `@intx/tools-mail`  | Any         | Mail send/read/search/reply/wait operations on the agent's inbox. Composes with any `MessageTransport` implementation.                      |

### Server Runtime Host

Server-only packages that compose the portable core and environment-specific implementations into a running host process. They assume a Node filesystem and process; they do not ship to constrained environments. Their runtime dependencies are shared-foundation and agent-runtime packages, plus the db-free `@intx/hub-sessions/substrate` seam — the repo-substrate primitives the host needs to read and write the agent-state and workflow-run repos. They do not link the control plane's db-backed services barrel. (`hub-agent` additionally carries a test-only dev dependency on `@intx/hub-sessions` to contract-test the hub WebSocket link against the real hub wire types.)

| Package                 | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------- |   |
| `@intx/hub-agent`       | Sidecar-side orchestrator (`createSidecarOrchestrator`, the core seam `apps/sidecar` wires together). Wires the package-side pieces of the sidecar runtime — the per-agent key and repo stores, a session manager, and the hub WebSocket link — into a single start/close handle, applies deploy and asset packs received from the hub, and forwards a spawned child's verified inference events back to the hub. In-process harness construction and agent provisioning are retired: every agent runs as a supervised workflow-process child on the workflow-run substrate (see `@intx/workflow-host`). |
| `@intx/tool-packaging`  | Hub-side closure resolver and sidecar-side loader for the npm-distributed tool-package format. Resolves a manifest's dependency closure, materializes tarballs into a content-addressable cache, and lays out a per-instance nested `node_modules/` so a tool package and its transitives resolve bare-specifier imports against the manifest closure. Used by both `apps/hub` and `apps/sidecar`.                                                                                                                                                                                                       |
| `@intx/workflow-host`   | Supervisor and child orchestration for running agents as supervised workflow-process children: the dispatch loop, inbox claim-check, the `SubprocessSpawner`/`SubprocessHandle` spawn seam, the per-step step-invoker, and recycle/drain. Consumes the `@intx/hub-sessions/substrate` repo primitives and takes its spawner, mail bus, and step invoker as injected bindings. Intended to stay host-agnostic so an alternate host reuses it with a different tool/agent runtime — see the open item under Dependency Rules.                                                                              |
| `@intx/workflow-deploy` | Deploy orchestration over the workflow-run substrate: `createWorkflowDeployOrchestrator`, deployment-address and workflow-run repo-id derivation (`deriveDeploymentAddress`, `deriveWorkflowRunRepoId`), and `wrapHarnessAsSingleStepWorkflow`. An agent-runtime package (it depends on `@intx/agent`, `@intx/workflow`, and `@intx/tool-packaging`) consumed by `apps/sidecar` and `@intx/hub-sessions` on the host side and reached into by `@intx/hub-api` on the control-plane side — one of the enumerated crossings in the Dependency Rules.                                                       |

### Why the splits exist

A package that pulls in native git bindings has no business shipping to a Cloudflare Worker. A package that bundles isomorphic-git has no business shipping to a server with native git available. The environment splits exist because the dependency trees are genuinely different — different native modules, different APIs, different capabilities. These are not configuration differences. They are different code.

The portable core packages (`inference`, `harness`, `agent`) never import environment-specific code. They operate through interfaces defined in `@intx/types`. The harness is wired at startup with concrete implementations chosen by the embedder.

## Development and Testing

| Package                                  | Purpose                                                                                                                                                                                                                                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@intx/inference-testing`                | Deterministic test harness for the `@intx/inference` streaming pipeline. Virtual-clock-driven simulated fetch, scripted provider wire bytes, matcher suite. Used by tests across the agent runtime tree.                                                                                                  |
| `@intx/inference-discovery`              | Shared runtime for the wire-capture rig: provider plug-in contract, capture runner, capability catalog, support matrix, and the parser behind the `bin/discover.ts` CLI. Produces the session bundles that each provider plug-in package stores under its own `sessions/` tree for the harness to replay. |
| `@intx/inference-discovery-google-genai` | Google GenAI provider plug-in for the discovery rig. Captures Gemini wire responses (text, multimodal, function calling, code execution, grounding, files API) across streaming and non-streaming variants.                                                                                               |
| `@intx/inference-discovery-openai`       | OpenAI-protocol provider plug-in for the discovery rig. Carries the protocol layer plus per-deployment wiring; OpenCode Zen (Moonshot, Z.AI, DeepSeek, Alibaba, Xiaomi MiMo) is the first deployment.                                                                                                     |
| `@intx/inference-discovery-anthropic`    | Anthropic provider plug-in for the discovery rig. Captures Claude wire responses across streaming and non-streaming variants for the first-party `/v1/messages` and `/v1/files` surfaces, including extended thinking, redacted thinking, code execution, and web search.                                 |

## Applications

Deployable processes under `apps/`. Each wires packages from one deployment context into a runnable artifact; none is published as a library. See each app's README for its startup contract and environment variables.

| App             | Context       | Purpose                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/hub`      | Control plane | Bun server entry point. Wires `hub-api`, `hub-sessions`, and `db` into a Hono app, mounts the sidecar WebSocket, and exports the Bun `fetch`/`websocket` server. The control-plane process operators run.                                                                                                                                                                                      |
| `apps/sidecar`  | Agent runtime | Bun host process for hub-orchestrated agents. Boots the tarball cache and starts an `@intx/hub-agent` orchestrator whose deploy router, on each inbound deploy, creates an `@intx/workflow-host` supervisor for the deployment and spawns a supervised workflow-process child wired with the default server tool set (`@intx/tools-posix`/`tools-lsp`/`tools-mail`, `crypto`, isogit storage). |
| `apps/admin-ui` | Control plane | React 19 single-page admin UI built with Vite. Renders the TanStack Router tenant-management console (agents, principals, roles, grants, credentials, wallets, instances, offerings) against the hub API through `@intx/hub-client`.                                                                                                                                                           |

## Dependency Rules

1. Agent-runtime packages depend on control-plane packages only through the db-free `@intx/hub-sessions/substrate` seam — the repo-substrate primitives (`RepoStore`, workflow-run claim-check, event log, kind-handler protocol) the server runtime host needs to read and write the agent-state and workflow-run repos. They never link the control plane's db-backed services barrel. Test-only dev dependencies that exercise a cross-tree wire contract are also permitted (e.g. `hub-agent`'s dev dependency on `hub-sessions`).
2. The control plane reaches into the agent-runtime tree at a set of deliberate crossings introduced by the workflow-process migration: the hub is itself a git server and workflow deployer, so `@intx/hub-api` and `@intx/hub-sessions` value-import agent-runtime packages that implement that shared machinery — packages such as the git pack and timeline layers (`@intx/storage-isogit`, `@intx/pack-transport`), deployment-address and repo-id derivation (`@intx/workflow-deploy`), the agent and workflow runtimes the substrate drives (`@intx/agent`, `@intx/workflow`), and the message, crypto, and tool-packaging primitives the sidecar link shares (`@intx/mime`, `@intx/crypto`, `@intx/tool-packaging`). These are deliberate — the control plane co-owns the git/workflow substrate — not accidental layering rot. What stays out of bounds is the reverse and the database seam: the agent-runtime tree never links the control plane's db-backed services barrel (Rule 1), and no crossing pulls the hub's Postgres/database layer into a shipped agent-runtime artifact.
3. Both trees depend on the shared foundation (`types`, `authz`, `log`).
4. Environment-specific packages depend on `types` for interfaces, never on each other (`tools-lsp` on `tools-posix` is the documented exception — see the tool-set table).
5. The harness depends on `types` for interfaces and `inference` for portable logic. It does not depend on any environment-specific package.

> **Open item.** `@intx/workflow-host` is intended to be a portable orchestration core that an alternate host reuses with a different tool and agent runtime injected at the seam (see `docs/unified-execution-host-design.md` §3d). It currently value-imports concrete agent-runtime packages — such as `@intx/agent`, `@intx/workflow`, `@intx/storage-isogit`, and `@intx/crypto` — rather than reaching them only through injected bindings, which contradicts that portability claim. This document describes the dependency as it stands; resolving it — restore the invariant, or consciously downgrade the portability claim — is deliberately left open.
