Packages
The @pleach/* package matrix — what each SKU does and how they compose.
Every sibling package plugs into @pleach/core's HarnessPlugin
contract. @pleach/core is the lattice; the siblings are
branches grafted onto it through one shared contract — none of
them rewrite the substrate, none of them slip past the audit
gates. Each one adds a specific capability (compliance scrub,
hash-chain verification, OTel destinations, recipe factories)
without altering the four-stage shape or the row keyed by
turnId.
The first-wave publish ceremony cuts every shipping
package at the same 0.1.0 floor under FSL-1.1-Apache-2.0 — uniform
version, uniform license, one row per package. The reader signal
that used to live in the version number now lives in the Notes
column: which packages are substrate-complete, which expose a
typed contract with one method still throwing a sentinel, and
which aren't in the first wave yet — @pleach/observe (contract
locked, scoped at 0.1.0-alpha.0, not yet on npm) and
@pleach/trust-pack (reserved placeholder, no contract).
Pin 0.1.0 exactly. The 0.0.x → 0.1.0 jump and the
0.1.x → 1.0.0 jump are both non-caretable, and ^0.1.0 will
not pick up later 0.x releases either. Use
"@pleach/<name>": "0.1.0" in your dependencies — not
^0.1.0.
Each sibling fills a specific subset of the slots documented
in Plugin contract: @pleach/compliance
ships scrubbers and the ComplianceRuntime contract substrate
today, with attestation + hash-chain verifier + GDPR erasure landing
in later versions. @pleach/eval reads the AuditableCall ledger
via the split lifecycle hooks (onToolCompleted / onMessageAdded)
and consumes @pleach/replay's ReplayClient via DI.
@pleach/gateway wraps @pleach/core's model-family substrate
through a typed GatewayClient. None of them can add an
out-of-lattice edge or bypass the singleton synthesize seam —
those are CI gates on the core repo, not optional discipline.
| Package | Role | Status / notes |
|---|---|---|
@pleach/core | Runtime substrate — sessions, graph, channels, audit ledger, checkpointing, sync, storage adapters. | 0.1.0 · source · substrate complete |
@pleach/tools | Substrate tool-calling primitives — UnifiedToolDefinition contract, queryable registry, Zod schema helpers, form-config + hints surfaces. Ships shapes only; bring your own concrete tool definitions. | 0.1.0 · npm · substrate complete |
@pleach/react | React-binding primitives — runtime acquisition, message stream, event-log facade, interrupt UI, correction dedup, plus a Vercel AI SDK migration adapter. The lower-level surface that @pleach/core/react composes. | 0.1.0 · npm · substrate complete |
@pleach/base-tools | Domain-agnostic tool primitives: math, datetime, scratchpad, unit_convert, text_search, opt-in url_fetch, plus a markdown citation extractor. Now ships inside @pleach/core at the opt-in subpath @pleach/core/base-tools; the standalone SKU is a thin re-export shim. | 0.1.0 · npm · ships in @pleach/core |
@pleach/replay | ReplayClient walks the canonical event log via runtime.events.iterate/fold. createReplayRuntime factory ships replayTurn, fromSnapshot, fork, and aggregateMultiTenant bodies (Pack 258 Slice 5 — zero throw sites remain). PACK_148_FIRST_SLICE_NOT_IMPLEMENTED_MESSAGE stays exported for back-compat detection only. | 0.1.0 · npm |
@pleach/sandbox | Vendor-neutral SandboxProvider contract for @pleach/core runtimes. Contract + in-memory fixture today; canonical name SandboxProvider with the legacy SandboxAdapter retained as a @deprecated alias. Anchors third-party @pleach/sandbox-<vendor> adapters. | 0.1.0 · npm · contract |
@pleach/langchain | Bidirectional LangChain / LangGraph adapter — tools, agents, and message history bridged into the Pleach event log. Surface still moving — pin tight. | 0.1.0 · npm |
@pleach/compliance | PII / PHI scrubbers (SsnUsScrubber, CreditCardScrubber (Luhn-validated), UsDriverLicenseScrubber, KeyedRegexScrubber), event-chain attestation, and verification utilities for HIPAA / GDPR / PCI-DSS / SOC 2 deployments. Implements the Scrubber contract from @pleach/core/scrubbers. Re-exports the ComplianceRuntime + ComplianceProfile types from @pleach/compliance-contract. | 0.1.0 · npm |
@pleach/compliance-contract | Zero-dependency contract sub-SKU carving out the ComplianceRuntime interface + ComplianceProfile literal union + structural Scrubber mirror. Breaks the @pleach/core ↔ @pleach/compliance type-graph cycle: both packages depend one-way on this contract; neither needs the other at the type layer. No runtime code. | 0.1.0 · npm · type-only contract |
@pleach/eval | EvalSuite + EvalCase discriminated union + EvalReport. Subpaths under ./scorers, ./replay, ./report for built-ins, replay coupling, and report formatters. Deterministic fixture grading, custom scorers, LLM-as-judge ensembles, event-log replay. | 0.1.0 · npm |
@pleach/gateway | GatewayClient — thin SKU wrapper over @pleach/core's model-family substrate. Per-tenant BYOK key routing, family-strict cascade pivot, per-call cost emission (domain.gateway.cost.recorded), OTel llm.invocation span emission. Routing math, family matrix, and BYOK resolution stay in core. | 0.1.0 · npm |
@pleach/mcp | Concrete MCPServer class wrapping SessionRuntime — tools, resources (pleach://artifact/*, pleach://sandbox/*), and prompts surfaced over MCP. Pluggable MCPTransport with stdio, SSE, and WebSocket implementations. Multi-tenant routing via registerSession({ tenantId? }) for composition with @pleach/gateway. | 0.1.0 · npm |
@pleach/coding-agent | SWE-bench-shaped coding-agent runtime opt-in for @pleach/core. All three async methods have real bodies (Pack 270 D1 / D2 / D3): start() composes the underlying SessionRuntime, stop() drains it, executeStep() drives one turn through SessionRuntime.executeMessage. The body throws PACK_270_D3_EXECUTE_STEP_NOT_STARTED_MESSAGE only when called before start() — no auto-start, by design. LRU CodingContextManager for file-context budget management. | 0.1.0 · npm |
@pleach/observe | Destination-flexible observability SDK — a thin facade (init + per-turn recorder + destination plug) that hooks into existing AI SDK / LangChain / custom loops and writes one AuditableCall v7 subset row per LLM call. Destinations: Postgres, Supabase, OTel, memory, and Pleach Hosted. | 0.1.0-alpha.0 · scoped, not yet on npm |
@pleach/recipes | Composable one-line factories over @pleach/core — simpleChatbot, ragChatbot, observableChatbot, compliantChatbot, instrumentedCodingAgent. Each subpath pulls only the @pleach/* peers its recipe needs; peer deps for observe, compliance, coding-agent, and sandbox are optional. | 0.1.0 · npm |
@pleach/trust-pack | Reserved npm name. No scoped contract, no shipping code, no upstream packages/trust-pack/ directory. The placeholder stays at 0.0.1 · UNLICENSED until a future cut. | 0.0.1 · placeholder · UNLICENSED |
Subpath exports per package
Every @pleach/* package uses a dir-style entry convention: the
root export is the public API, with named subpaths under it for
narrower surfaces (/react, /server, /testing, and similar).
Each exports map orders conditions types-first per Node's
resolution spec, so TypeScript sees the .d.ts before the
runtime entry.
The per-subpath inventory lives in Subpath exports — one table per package, listing every documented entry and what it's for.
The full packaging conventions — exports ordering rules,
sideEffects discipline, and engines floors — live in
Publishing contract.
Language-agnostic contract
The runtime contract — sessions, checkpoints, storage, tools, sync,
SSE wire — is language-agnostic by design. The TypeScript
distribution is the reference implementation, in production today.
A Go implementation has been built against the same contract and
round-trips a shared corpus of recorded turns — that's the test
that catches anything TypeScript-flavored leaking into the wire.
The Go implementation isn't published as a SKU yet; an official
@pleach Go runtime is the next planned published implementation.
The five contract shapes a non-TS consumer implements (HTTP+SSE
wire, StreamEvent union, AuditableCall row, Checkpoint
envelope, version vector) are enumerated on the Language-agnostic contract page.
If a claim in these docs only holds in JavaScript, that's a documentation bug. Issues welcome on the relevant package's repo.
Licensing
Every shipping @pleach/* package — substrate, adapter, and SDK
alike — publishes under FSL-1.1-Apache-2.0 (Functional Source
License with Apache 2.0 as the future license). Source-available,
usable in production, free of charge during the FSL window; the
only restriction is on competing offerings. Each package auto-
transitions to permissive Apache 2.0 two years after first stable
publish. The single exception is @pleach/trust-pack: a reserved
npm name with no shipping code, kept at 0.0.1 · UNLICENSED until
a future cut. See Pricing for commercial-use guidance.
Where to go next
Architecture
The six pieces of the substrate and how the planned siblings plug into them.
Plugin contract
The HarnessPlugin extension surface every sibling SKU will use.
Language-agnostic contract
The five wire shapes that define the substrate. A Go implementation round-trips them; the official @pleach Go SKU is the next planned published implementation.
Versioning policy
Semver, deprecation, and per-SKU release cadence.
Facet accessors
runtime.* / TurnOrchestrator.* / graph.* — a discoverable, typed surface designed to be read by humans and LLM agents. Stable shape, audited for coverage.
@pleach/base-tools
Domain-agnostic tool primitives — math, datetime, scratchpad, unit_convert, text_search, and opt-in url_fetch with a citation extractor.