FAQ

What is @pleach/core?

A TypeScript-first agent runtime substrate published under the @pleach/* scope on npm. It treats every LLM call inside an agent as classifiable, auditable, and replayable — sessions, checkpointing, reactive channels, family-locked model routing, and an append-only per-call audit ledger.

The contract 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 — proof the wire shapes aren't TypeScript-flavored. The Go implementation isn't published as a SKU yet; an official @pleach Go runtime is the next planned published implementation.

How is this different from the Vercel AI SDK?

Pleach wraps the AI SDK; it doesn't replace it. AiSdkProvider keeps the AI SDK as your provider layer, and the runtime adds what sits around it: sessions, family-locked routing, the four-stage lattice, the audit ledger, replay determinism, and checkpointing.

If your app is "chat with tools and stream the response," reach for the AI SDK. If you need per-call audit, per-turn cost attribution, replay determinism, or family-locked routing, @pleach/core is doing structural work the AI SDK isn't built for. The concrete shape difference: an AI SDK streamText call returns a stream of text deltas and tool events with no shared identity tuple; an executeMessage call yields the same surface shape but every call beneath it lands as a row keyed on (sessionId, turnId, stageId, seqWithinTurn) — that's the join key the AI SDK doesn't ship.

See Comparison and Migrating from the AI SDK.

How does this compare to Claude Code, Goose, OpenHands, AutoGen, CrewAI?

Different category. Those are agent harnesses — complete running products you launch and use. @pleach/core is the substrate one layer below: the primitives a harness is built on. If you're the end user, install a harness. If you're shipping a customer-facing agent product where each tenant needs their own session, audit trail, and invoice, the harness's session log isn't the row shape you need.

See Comparison → Agent harnesses for the capability matrix.

Is this open source? What's the license?

Yes — every shipping @pleach/* package ships under FSL-1.1-Apache-2.0 (Functional Source License with Apache 2.0 as the future license). FSL is 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.

@pleach/trust-pack alone remains a 0.0.1 · UNLICENSED placeholder; it'll ship FSL-1.1-Apache-2.0 when its first cut lands.

Does Pleach replace my Anthropic or OpenAI Enterprise contract?

No — it composes underneath. SSO/SAML, ZDR, Workspaces or Projects, the Admin / Usage API, dedicated capacity, prompt caching, snapshot pinning all keep doing their job. Pleach adds the three things the vendor contract doesn't cover: per-axis rollup by tenantId inside one Workspace or Project (external customers in a SaaS, or employees, teams, and cost centers when used internally), a hash-chained AuditableCall row in your own Postgres, and replay-deterministic regression across model snapshots. No new vendor on the security questionnaire — npm install plus a table. See Migrating from Anthropic Enterprise and Migrating from OpenAI Enterprise.

Who's behind this?

@pleach/* is the public FSL-1.1-Apache-2.0 source-available ecosystem (auto-transitions to Apache 2.0 two years after first stable publish). The substrate was extracted from a production agent runtime and generalized; the upstream deployment is one private consumer of many possible. Contact for both general questions and security disclosures: getpleach@protonmail.com.

What can I build with this?

Anything that wants the structural guarantees:

• A multi-tenant AI product where finance needs per-customer invoicing.
• A regulated agent surface where a compliance team will ask "show me every decision this session made."
• A long-running agent with planning + tool loop + synthesis + safety review, where each step needs to be observable.
• An eval / regression-test loop replaying production failures.
• A product mid-migration between providers that can't break tool-call dialect mid-conversation.
• An offline-first browser app needing IndexedDB sync.
• Stuck-session debugging where you need to rewind and try a different path.

What you're probably not building if @pleach/core is overkill:

• A single-shot RAG bot (query → paragraph). Use the AI SDK.
• A static workflow with fixed branches. Use Temporal or Inngest.
• A chat UI with no tools and no audit needs. Use streamText.

See the README's "Who is this for?" table for the long version.

Is this designed for AI agents to use?

Yes — agents are first-class consumers, not bolted on. Every AuditableCall row is a typed record; turnId, toolName, subagentDepth, and tokenUsage are addressable from code the same way they're addressable in SQL. SpawnTreeState rolls nested-spawn cost back to the parent turnId, so an agent reading its own trace sees recursion as a tree, not a flattened log.

The runtime also lets an agent debug itself: the deterministic fingerprint stream replays last week's failure against this week's prompt byte-identically; per-channel checkpoint() / restore() under window.__HARNESS_DEVTOOLS__ rewinds from before a bad decision instead of escalating to a human. This site renders to /llms.txt and /llms-full.txt — an agent ingesting Pleach reads the docs themselves, not a stripped sitemap.

The reference distribution is TypeScript a developer can read. The same surface — typed rows, deterministic fingerprints, checkpoints — is what an agent reads from code. Agent-friendly first; usable by devs because devs read the same surface.

@pleach/core itself is written largely by agents under that surface. The four-stage lattice fails CI on out-of-lattice edges; the audit ledger makes the agent-written code reviewable in SQL. The runtime authored by agents is the same one auditable by humans.

Why does it require so many decisions up front?

It doesn't. With zero config, new SessionRuntime() wires in-memory adapters and runs. You add a provider, a storage adapter, plugins, and safety policies when you need them. Every SessionRuntimeConfig field except the implicit defaults is optional.

The reference docs surface the full config space because that's their job; the actual happy-path setup is small. The Getting started page is six lines of code.

Why the 4-stage lattice? Isn't it limiting?

The lattice is what makes cost allocation, observability, and time-travel structural instead of bolted on. Once stages are declared, you can budget a turn's synthesize calls independently from its tool-loop calls, slice the audit ledger by stage, and rewind to the start of synthesize to re-run. "Slice the audit ledger by stage" is a literal SQL move: every row in harness_auditable_calls carries a non-null stage_id drawn from the four lattice members, so GROUP BY stage_id gives you a real partition. There's no second source of truth for which stage a call belonged to.

If you don't need those properties, yes — the lattice is overhead. The substrate is overkill for "I want a chat shell with tools." See Architecture §1.

Why exactly one synthesize call per turn?

Because the user sees the synthesis. If the runtime fires two synthesize calls and shows one of them, the audit ledger and the rendered UI disagree on what the model said. Structurally capping at one means the rendered string and the audited string are the same string.

Sequential plan-then-verify chains land via an upcoming per-runtime synthesize policy; concurrent debate topologies (many synthesizers per turn, agent-handoff networks) are v1.1+ work.

Why family-locked routing?

Because tokenizer, prompt-cache key, tool-call dialect, and refusal pattern differ across families (Anthropic vs OpenAI vs Google). When a provider fails mid-conversation and the cascade silently widens to a different family, the tool dialect changes and tools that worked stop working. The lock makes the cascade walk in-family rungs only; cross-family widening is explicit and visible.

See Model resolution matrix.

Why a separate AuditableCall ledger from the event log?

Two distinct concerns. The event log is the broader stream of observable events (messages, tools, interrupts); the audit ledger records load-bearing decisions (which model fired, why, with what fingerprint, against which policy).

A regulator's "show me every decision this session made" question has a one-row-per-call answer from the ledger that doesn't require event-log archeology. See Event log and AuditableCall row.

Can I use this without Supabase?

Yes. MemoryAdapter and MemorySaver cover testing and dev; IndexedDBAdapter and IndexedDBSaver cover browser apps; SupabaseAdapter and SupabaseSaver cover server production.

Custom adapters are one interface away. See the SQLite recipe in Recipes for a complete custom-adapter example.

Can I use this with my own LLM provider?

Yes. AiSdkProvider covers any AI SDK provider (Anthropic, OpenAI, Google, Mistral, xAI, Groq, Bedrock, plus community providers); AnthropicSdkProvider wraps Anthropic's SDK directly; AgentProvider is the interface for everything else (local Ollama, a custom gateway, your own SDK wrapper).

See Providers.

Can I use this without React?

Yes. @pleach/core/react is one subpath; the rest of the runtime is framework-agnostic. Server-rendered apps, Svelte/Vue/Solid frontends, native mobile clients, and CLI tools all consume the runtime through its async-iterator stream and the HTTP+SSE wire contract.

See API routes for the wire shapes any language can implement.

Does it work with Edge runtimes?

Yes. The substrate avoids Node-only APIs in its hot path — fingerprint, channels, audit, prompt-builder are all isomorphic. Supabase + Anthropic SDKs both run on edge runtimes; the storage adapter uses Web Crypto explicitly. The fingerprint module reaches globalThis.crypto.subtle rather than Node's node:crypto, which is why a recorded turn under Node and the same turn replayed under Cloudflare Workers produce the same fingerprint stream — same hash function, same input canonicalization, same byte output.

See Deployment.

Why FSL-1.1-Apache-2.0?

Every shipping @pleach/* package publishes under FSL-1.1- Apache-2.0 — the 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. Pre-0.1.0 placeholder publishes (0.0.1) carried the FSL grant under the same posture. See the fair-source post-mortem for the reasoning behind the license-posture history.

Can I contribute?

Yes. The upstream source is at github.com/pleachhq/core. Bug reports, feature requests, and PRs are welcome. The upstream CONTRIBUTING.md documents the workflow.

For sibling SKUs that aren't published yet, the design is tracked in upstream planning docs; opening an issue with your use case helps prioritize the publish wave.

Where do I report security issues?

getpleach@protonmail.com. The upstream SECURITY.md documents the disclosure policy — initial acknowledgement within two business days, a fix-or-mitigation plan for confirmed reports, and a CVE filed when a published @pleach/* package needs one. No paid bug-bounty program today; reports get a real response, not a payout.

Is there a hosted version?

Not today; in development. @pleach/gateway@0.1.0 ships the self-hostable routing substrate — GatewayClient wraps @pleach/core's model-family substrate with per-tenant BYOK key routing, family-strict cascade pivot, per-call cost emission (domain.gateway.cost.recorded), and OTel llm.invocation span emission. See Gateway for the surface. @pleach/observe@0.1.0 ships as a destination-flexible brownfield SDK — buyers write AuditableCall rows to their own Postgres, Supabase, OTel collector, or any custom destination; the SDK layer stays free.

The hosted products on the roadmap are enterprise products:

• Hosted Gateway — multi-tenant routing, per-tenant cost caps, provider failover. Per-tenant subscription pricing with optional consolidated billing on dollars Pleach holds; no markup on inference (BYO-key buyers route through the gateway at provider list price).
• Hosted Observe at enterprise scope — SSO/SAML/SCIM, multi-seat dashboards, retention SLAs, SOC 2 wrapper, signed audit retention, per-tenant evidence pack export. The managed export bridge routes audit rows into the review surface your team already runs (Datadog, Splunk, Grafana, SIEM, or custom destination). Compliance attestation is bundled inside Hosted Observe Enterprise, not sold as a separate SKU — the agent-runtime-specific axes (AuditableCall row + subagentDepth + tenantId) are the wedge that makes it defensible alongside Vanta or Drata, but they don't carry a separate procurement line item.
• Marketplace bundles — AWS, Azure, GCP. Procurement-readable packaging of the hosted products on the buyer's preferred cloud contract surface.

Self-serve tiers for smaller teams are in development. Pricing specifics land on /pricing before they ship.

None of these gate runtime features. The runtime stays trust-protected: no telemetry phone-home, no remote license check, no account required to run, and no retro-paywall on a release that already shipped. FSL-1.1-Apache-2.0 is irrevocable per release — npm install @pleach/core@<version> works forever, and that version's two-year clock to Apache 2.0 keeps ticking independently.

How do I stay updated?

• The upstream CHANGELOG.md on every @pleach/* package.
• The pleachhq/core repo's releases page.
• Security: getpleach@protonmail.com for advisories.

There's no marketing list. The packages are the canonical broadcast surface.

Capabilities

Where to go next