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, versioned 0.1.0 in-tree, 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, a hash-chain verifier, GDPR erasure, and a
ComplianceRuntime (attestRun, verifyChain, produceAuditReport).
Attestation signing is beta: only the file-backed key-store signs
today, and the AWS KMS and Vault adapters are stubs (see
Attestation). @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. Now ships inside @pleach/core at the opt-in subpaths @pleach/core/tools and @pleach/core/tools/unified; the standalone SKU is a thin re-export shim. | 0.1.0 · npm · deprecated, ships in @pleach/core |
@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 · deprecated, 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_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. Ships the contract, an in-memory fixture, and adapters for an HTTP stream wire shape, HTTP polling, a local child process, and AWS ECS Fargate (subpaths @pleach/sandbox/adapters/httpStream, /httpPoll, /childProcess, and /awsFargate); canonical name SandboxProvider with the legacy SandboxAdapter retained as a @deprecated alias. Per-vendor packages aren't shipped; vendor coupling lives in your own gateway or adapter config. | 0.1.0 · npm · contract |
@pleach/langchain | Bidirectional LangChain / LangGraph adapter — a LangGraph checkpointer adapter, tool converters, a store adapter, and a LangChainProvider, plus reverse HarnessCheckpointSaver and HarnessEventLogCallback. 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/rbac-contract | Zero-dependency contract for role-based access control — a 2-method RbacRuntime interface (checkPermission, getRolesForActor) plus CheckPermissionInput / PermissionDecision shapes. Same cycle-break pattern as @pleach/compliance-contract, but authored fresh with no shipped implementer yet — deliberately not ga. @pleach/core/rbac adapts it into the existing approval-flow plugin hook. | 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. Concrete native transports aren't bundled: the host supplies a transports map, and createOpenAiCompatibleTransport ships from @pleach/gateway/transport. routeEmbedding, getProviderHealth, and getTrafficStats aren't implemented yet. | 0.1.0 · npm |
@pleach/mcp | Concrete MCPServer class wrapping SessionRuntime — tools (projected from runtime.tools.list(); native execution opt-in and approval-gated), resources (pleach://artifact/*, pleach://sandbox/*), and prompts surfaced over MCP. Transports: stdio, HTTP+SSE with optional Streamable HTTP, and WebSocket (optional ws peer), with loopback-default Host / Origin allowlists and connection, in-flight, and timeout limits. Fail-closed per-connection multi-tenant routing via tenantIdExtractor, registerSession({ tenantId }), or a resolveRuntime hook. | 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: start() composes the underlying SessionRuntime, stop() drains it, executeStep() drives one turn through SessionRuntime.executeMessage. The body throws a not-started error 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 v19 subset row per LLM call. Destinations: Postgres, Supabase, OTel, memory (Pleach Hosted: scaffold, not yet available). | 0.1.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, json_query, memory, and opt-in web_search, web_fetch, code_exec, ask_user, filesystem, and recall.