Ownership boundaries
Per SKU, what the package owns, what you configure, and what you must supply. The single-page map of where the substrate ends and your code begins.
This page answers one question per row: if I want to change behavior X, whose surface is X, and is it a config field, a plugin hook, or a fork? It complements the other orientation docs without duplicating them — Packages describes what each SKU does, Which SKU do I need? maps tasks to install lists, and this page draws the boundary between the SKU's locked surface and your host code.
Every row sorts into one of three columns:
| Column | What it means |
|---|---|
| Owned by the SKU | Fixed by the package. The audit gates refuse builds that try to alter it. Your only path here is upstream contribution. |
| You configure | A typed config field, a plugin hook, or a registered registry. Supported, additive, no forking required. |
| You must supply | Required at construction. The SKU throws or short-circuits without it. |
Two structural pins hold across every SKU:
- The four-stage lattice —
anchor-plan → tool-loop → synthesize → post-turn. Every node in every SKU belongs to one of the four stages; see Graph for the gate and Node catalog + Edge catalog for the enumerated surface. - The audit row — one
AuditableCallrow per LLM call, keyed byturnId. Every SKU writes through the same row shape; seeAuditableCallrow for the schema.
You can't disable, replace, or bypass either pin from any extension path. They're substrate, not policy.
@pleach/core — the substrate
The lattice and the audit ledger. Every other SKU plugs in through HarnessPlugin; @pleach/core is the only package whose absence breaks the build.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Four-stage lattice | llmExecutor — your LLM provider call | At least one LLM provider |
| Channel kinds and reducers | toolExecutor — tool dispatch | A storage adapter (or the in-memory default) |
| Singleton synthesize seam | subagentExecutor — subagent runtime construction | The SessionRuntime config object |
AuditableCall row shape | plugins[] — a HarnessPlugin[] for extra graph nodes, tool registration, stream observers | |
| Checkpoint format | The 43-name Node catalog — register a subset by omitting the matching executor | |
StreamEvent shapes | storage — a StorageAdapter for session persistence | |
| Determinism contract — five substrate rules | metaToolNames — names the substrate should treat as meta-tools | |
| Family lock | setHarnessModuleLoader — host-adapter seam for hosts mid-migration |
The canonical decision tree: Runtime construction. The full plugin extension surface: Plugin contract.
@pleach/compliance — scrubbing, hash chain, GDPR
PII/PHI redaction, tamper-evident hash chain over the audit ledger, GDPR-style soft-delete (erasure tombstones).
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Hash-chain middleware — the chained-hash format | Per-turn scrubber set via ComplianceRuntime | A ComplianceRuntime instance |
| GDPR erasure — tombstone shape | Custom Scrubbers (PII, PHI, PCI patterns) | Storage that supports the tombstone write pattern |
| Attestation envelope shape (Attestation) | Detector regexes per data class | |
The @pleach/compliance-contract typed surface | The audit gates the hash chain enforces |
@pleach/compliance writes through the same audit row @pleach/core defines — it doesn't introduce a second ledger. See Compliance.
@pleach/gateway — multi-tenant routing + cost attribution
Per-tenant model routing, BYOK provider keys, rate limiting, cost event emission.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Cost event row shape | BYOK provider keys per tenant | A GatewayClient instance |
| Routing logic (cost-aware, family-locked) | Rate limits per tenant or per key | Tenant identifier on every request |
| Per-tenant tenant facet — Tenant facet | OTel destination for cost rollup | |
Migration from @pleach/core routing |
Per-tenant cost attribution rolls up through the same AuditableCall row — tenantId is a column, not a side-table. See Gateway and Multi-tenant.
@pleach/observe — hosted observability + Export Bridge
OTel-instrumented spans across the lattice. Read Observe for the SKU framing.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Span structure across the four stages | Destinations — Postgres, Supabase, OTel collector, custom webhook | An OTel collector, Postgres, or destination of your choice |
Trace ID propagation through AuditableCall | Per-tenant routing of spans | |
Cost rollup integration with @pleach/gateway | Retention rules at the destination |
@pleach/observe is destination-flexible. The library writes audit rows through existing @pleach/core ProviderDecisionLedger adapters; the destination is yours.
@pleach/eval — deterministic replay + diff
Regression testing against the audit ledger. Replays past turns through the same node graph and diffs the output.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Deterministic replay engine | Eval parity thresholds | A ReplayClient instance from @pleach/replay |
Diff format over AuditableCall rows | Replay-time seam binding | Source audit rows to replay against |
Lifecycle hook reads — onToolCompleted, onMessageAdded | Per-eval node-graph subset |
@pleach/eval consumes @pleach/replay's ReplayClient via DI. The split lifecycle hooks let it read the same ledger every SKU writes through. See @pleach/eval.
@pleach/replay — event-granular session forking
Forks a session from any checkpoint or any event. The substrate carrier for @pleach/eval but usable independently.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Fork algorithm (event-granular, not turn-granular) | Checkpoint storage backend (via core's StorageAdapter) | A source session to fork from |
| Lineage record format | Per-fork seam re-binding | |
| Replay determinism contract — node-level |
See Replay and Time travel.
@pleach/mcp — MCP server + client
Wraps Pleach sessions as Model Context Protocol servers, and consumes external MCP servers as Pleach tools.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
MCP transport (Streamable HTTP per protocol 2025-06-18) | Tool exposure — which Pleach tools become MCP tools | The session config that backs the server |
| Resource and prompt handlers | Resource list | |
| Tools/list, tools/call, ping, notifications handlers | External MCP servers to consume as tools |
See @pleach/mcp and MCP integration.
@pleach/tools + @pleach/base-tools — tool primitives
Generic tool primitives (@pleach/tools) and a curated base set (@pleach/base-tools).
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Tool interface — name, schema, executor | Tool registration through SessionRuntimeConfig.toolRegistry | The tool's executor function |
| Structured-parse and filesystem primitives | Per-tool seam binding | Permissions and sandbox boundaries for filesystem/shell tools |
| Tool result row shape — feeds the post-tool chain | Tool result post-processing through plugin nodes |
Pleach's tool contract is the same shape regardless of whether the tool comes from @pleach/base-tools, your own code, or an MCP server. See Tools.
@pleach/coding-agent + @pleach/sandbox — sandboxed code execution
A coding-agent recipe (@pleach/coding-agent) plus the sandbox primitives it sits on (@pleach/sandbox).
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Sandbox lifecycle — boot, exec, snapshot, teardown | Sandbox provider (Vercel Sandbox, Docker, custom) | Sandbox provider credentials |
| File tools — read, write, patch | Multi-synthesize parameters | The repo or workspace to mount |
| Long-session checkpointing | Per-task tool subset | |
| SWE-bench recipe — eval shape |
See @pleach/coding-agent.
@pleach/react — React hooks + components
Hook surface for client-side chat UI. Server-side runtime construction is in @pleach/core; this package owns the React-specific shape.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
useChat, useSession, useStream hook shapes | UI components, layout, styling | A backend route that proxies to the runtime (typically createPleachRoute) |
HarnessProvider context shape | Hook subscription behavior | |
| Building chat UI component patterns |
See @pleach/react.
@pleach/langchain — LangChain / LangGraph adapter
Adapter that lets a LangChain agent run as a Pleach node, and lets a Pleach session feed a LangGraph.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| Adapter shapes both directions | Per-call adapter wiring | A LangChain or LangGraph instance |
State-mapping between LangChain BaseMessage and Pleach Message | Tool-translation strategy |
See @pleach/langchain and Migrating from LangChain.
Transport packages — @pleach/transport-bedrock, @pleach/transport-azure-openai, @pleach/transport-vertex
Provider-side transport adapters for AWS Bedrock, Azure OpenAI, and Google Vertex.
| Owned by the SKU | You configure | You must supply |
|---|---|---|
| The transport's wire-shape translation | Per-region endpoints | Provider credentials |
| Provider-specific retry and backoff | Model identifier mapping | Account or project ID |
| Streaming envelope adaptation |
See @pleach/transport-bedrock, @pleach/transport-azure-openai, @pleach/transport-vertex.
Cross-SKU concerns
A few surfaces span multiple SKUs. The boundary on those is structural — the SKUs each own a slice but the contract is shared.
The audit ledger row
Every SKU writes through one AuditableCall row shape, keyed by turnId. See AuditableCall row.
| SKU | Writes | Reads |
|---|---|---|
@pleach/core | The row itself; nodeId, stageId, tokenUsage, toolName | — |
@pleach/compliance | hashChainPrev, hashChainSelf, scrubber tombstones | Self-validates the chain at read |
@pleach/gateway | tenantId, providerKey, costEvent | Per-tenant rollup |
@pleach/observe | OTel span IDs threaded onto the row | Whole row for span construction |
@pleach/eval | — | Whole row for replay |
@pleach/replay | lineageParent for forked sessions | Source row for the fork |
Cost rollup
Two SKUs participate. @pleach/core rolls token usage per turn; @pleach/gateway rolls cost per tenant by joining the AuditableCall row to its costEvent extension. See Cost events.
Storage
@pleach/core defines the StorageAdapter interface; every SKU that persists data uses it. See Storage for the adapter shape and the bundled implementations.
Determinism
The five substrate-level rules are in Determinism. Every SKU that registers a node must satisfy them — same input state, same partial-state output.
Quick lookup — "I want to change X"
| You want to | Surface | Path |
|---|---|---|
| Add a node to the canonical graph | @pleach/core | Plugin — HarnessPlugin.extraGraphNodes(). See Node catalog — plugin path |
| Remove a node from the canonical graph | @pleach/core | Config — omit the gated executor. See Node catalog — config omission |
| Wire a fully custom topology | @pleach/core | Custom builder — raw StateGraph. See Node catalog — custom builder |
| Add a new edge inside the lattice | @pleach/core | Plugin or custom builder; lattice gate still binds. See Edge catalog |
| Change the four-stage lattice itself | @pleach/core | Upstream contribution only. See Edge catalog — removing an allowed pattern |
| Swap the LLM provider | @pleach/core | Config — llmExecutor. See Providers |
| Add a tool | @pleach/core + @pleach/tools | Config — toolRegistry or contributeTools plugin hook. See Tools |
| Scrub PII from prompts | @pleach/compliance | Configured Scrubber set. See Scrubbers |
| Verify the audit chain hasn't been tampered with | @pleach/compliance | Hash-chain middleware |
| Route per-tenant on a different provider key | @pleach/gateway | BYOK |
| Send spans to Datadog / Honeycomb / your collector | @pleach/observe | Destination config — see Observe |
| Replay a past turn and diff | @pleach/eval + @pleach/replay | Lifecycle hooks. See Eval and replay |
| Fork a session at an event | @pleach/replay | ReplayClient.forkAt(eventId). See Replay |
| Expose Pleach as an MCP server | @pleach/mcp | MCP transport config. See @pleach/mcp |
| Run a coding agent against a repo | @pleach/coding-agent + @pleach/sandbox | Sandbox provider config. See @pleach/coding-agent |
| Build a chat UI in React | @pleach/react | Hook surface. See Building chat UI |
| Stream from AWS Bedrock / Azure OpenAI / Vertex | matching transport SKU | Transport package config. See Transport — Bedrock, Azure, Vertex |
| Migrate from LangChain | @pleach/langchain | Adapter. See Migrating from LangChain |
Change the AuditableCall row shape | @pleach/core | Upstream contribution only. The row shape is a cross-SKU contract |
| Change the determinism rules | @pleach/core | Upstream contribution only. See Determinism |
Where to go next
Which SKU do I need?
Task-to-install-list mapping. Pair this page with that one — this answers 'what do I own', that one answers 'what do I install'.
Packages
The package matrix — what each SKU does and how they compose.
Plugin contract
The full HarnessPlugin extension surface — every hook the substrate exposes to additive code.
Runtime construction
The construction APIs — createPleachRoute, createPleachRuntime, SessionRuntime, HarnessProvider.