Agent shapes
Reference agent designs Pleach is built for — each pairs a recurring production pattern with the runtime primitive that handles it and the team shape it shows up in.
Pleach is built for the multi-tenant production-agent shape. Below are the common shapes that show up in adopter conversations — pick the closest, then read the linked use case for the wiring.
Each section names the pattern (what hurts), the mechanism (the primitive that handles it), the team shape (where it typically shows up), and the sharpest vertical (where the pain is loudest).
01 — Provider migration
The pattern
Anthropic to OpenAI, OpenRouter to BYOK, native to gateway — mid-session, without breaking the tool-call dialect or refusal handling.
The mechanism
Family-lock freezes tokenizer, prompt-cache key, tool-call dialect,
and refusal pattern at session start. The cascade walks in-family
rungs only; permittedFamilies narrows it to a vetted set.
The team shape
SaaS adding in-product chat.
The sharpest vertical
Compliance-bound teams (HIPAA, SOC 2, PCI, FedRAMP, 21 CFR Part 11).
02 — Tool fan-out and subagent attribution
The pattern
One user message triggers a dozen tool calls and spawns three subagents that spawn their own. You need to know which tools ran, which subagents spawned, and where the tokens went.
The mechanism
Every row carries turnId, toolName, and subagentDepth. A typed
SpawnTreeState rolls child-session token spend back to the
parent turn instead of stranding it under the child sessionId.
The team shape
Internal platform teams exposing "AI for everything".
The sharpest vertical
Coding-agent shops (Cursor-class, terminal-native, autonomous-PR).
03 — Portable, replayable state
The pattern
Offline-first or sync-conflict-prone sessions — browser extensions, mobile-shaped web apps, multi-device editing. Two clients writing the same session can silently overwrite each other.
The mechanism
The session is one append-only event log. IndexedDB + checkpointer +
version-vector sync carry it across devices; conflicts surface at
write time. HarnessPlugin events are first-class log entries.
The team shape
Vertical AI startups (legal, radiology, accounting close, devtools security).
The sharpest vertical
Eval and research labs running deterministic replay across model swaps.
04 — Per-axis cost attribution
The pattern
A (family, callClass, model) call has to roll up to whichever
axis you're attributing on — your end customers in a SaaS, or your
own employees, teams, and cost centers when Pleach runs under one
Anthropic Workspace or OpenAI Project on an Enterprise contract.
The mechanism
Every AuditableCall row carries tenantId, turnId, toolName,
subagentDepth, modelId, and tokenUsage. tenantId is opaque —
customer-acme and cost-center-eng-platform partition the same
way. Finance reads the ledger directly — no parallel cost pipeline.
See Migrating from Anthropic Enterprise
and Migrating from OpenAI Enterprise
for the contract-composition walk-through.
The team shape
AI consultancies with per-engagement tenants; internal platform teams under one Enterprise contract attributing across business units.
The sharpest vertical
ISVs embedding agents in a downstream SaaS (customer → end-user nesting); internal-AI platform teams in 500-100,000-person enterprises rolling up to cost-center budgets.
05 — Regulator-facing audit
The pattern
A regulator, auditor, or court asks which tools the session invoked, which subagents it delegated to, and proof neither the answer nor the PII gate were altered after the fact.
The mechanism
Append-only ledger keyed by (turnId, toolName, subagentDepth)
answers the first two questions in one query. @pleach/compliance
ships four scrubbers (SSN-US, Luhn, US-DL, KeyedRegex) on
the persistence boundary plus inherited CI gates that fail an
untenanted write.
The team shape
Public-sector deployments (FedRAMP, FOIA-bound, often air-gapped).
The sharpest vertical
Edtech serving K-12 or higher-ed (FERPA-equivalent per-district isolation).
06 — Stuck-session debugging
The pattern
A user reports a bad turn. By the time you read the ticket, the session is twenty messages further along. You need to rewind to before the bad decision and try a different path.
The mechanism
Per-channel checkpoint() / restore() under
window.__HARNESS_DEVTOOLS__. Deterministic fingerprint stream
means a support ticket replays byte-identically locally; the bad
turn is a known offset, not a guess.
The team shape
Founder teams answering their own support email.
The sharpest vertical
Customer-support automation across thousands of live transcripts a day.
07 — Region-pinned routing under contract
The pattern
An enterprise already running AI in production needs procurement- visible routing discipline: region pinned per call class, family pinned per call class, failover constrained to a vetted list, and a parity-validation suite that proves the substitute behaves the same as the primary.
The mechanism
permittedFamilies scopes the cascade; a per-call-class family
pin keys on (family, callClass) against the resolution matrix.
@pleach/eval records a fixture run against the primary and
replays it against each family in the permitted list — the diff
is what proves the failover is safe to take.
The team shape
Direct-API enterprise buyers — Anthropic / OpenAI tier-4+ contracts with six-to-eight-figure annual spend, often with a named AI governance function.
The sharpest vertical
EU-resident enterprises preparing for AI Act Article 12 attestation; financial services with a stated provider-switch clause.
08 — Cloud-mediated transport
The pattern
API keys are forbidden by policy. Models must be reachable inside the customer's VPC. The buyer reaches Anthropic, OpenAI, or Google models through AWS Bedrock, Azure OpenAI Service, or Vertex AI — not the labs' direct APIs.
The mechanism
Family stays the model's identity (anthropic, openai,
google); transport names the route to it (bedrock,
azure-openai, vertex). The credential is an IAM role, a
managed identity, or a workload-identity binding — never a
long-lived key. The audit row records the principal, the cloud,
the region, and the model — joinable to the cloud invoice.
The team shape
1,000-100,000-person enterprises with $1M-$100M annual cloud commit, often with on-prem or VPC-mandate procurement policy.
The sharpest vertical
Regulated financial services and healthcare systems whose existing committed cloud spend is the procurement substrate.
09 — Bounded subagent swarms
The pattern
One user turn fans out into dozens or hundreds of subagents, each of which may spawn its own. Deep sequential loops, parallel fan-out, supervisor / worker topologies, recursive delegation — different shapes, same runaway-loop risk: a buggy fan-out can spend a five-figure budget in one user turn.
The mechanism
Every subagent inherits the originating turn's turnId and
carries its own subagentDepth. The whole tree is one recursive
CTE against the ledger. A per-root-turn cost ceiling aborts the
turn when cumulative spend across the tree crosses the line;
fan-out and depth caps bound the structural shape.
The team shape
Builders of coding agents, deep-research products, supervisor- worker platforms, and Claude Code-style recursive delegation — where the topology has already been chosen and what's needed is a substrate that doesn't force a different one.
The sharpest vertical
Agent-product builders adding governance after a runaway-loop incident; enterprise buyers wrapping an existing swarm consumer (Kimi, Deep Research, AutoGen) with cost ceilings and an audit walk.
Where to go next
Customer support
Ticket triage with interrupts, subagents, and per-tenant audit.
Research
Multi-step retrieval + synthesis with deterministic replay.
Coding agent
Sandboxed code execution + tool-loop pattern.
Internal knowledge
Org-wide retrieval with safety policies and citation guards.
Multi-tenant SaaS
Per-tenant isolation by construction — cache, storage, audit, OTel.
Regulated domain
Scrubbers + tamper-evident hash chain + RLS for HIPAA / finance shape.
Region-pinned
Per-call-class family pin + parity-validation suite for contract-driven routing.
Cloud-routed
IAM-federated inference through Bedrock, Azure OpenAI, or Vertex.
Swarm
Bounded subagent fan-out with root-turn cost ceilings and the session-tree audit walk.
CLI
The pleach binary ships three subcommands — dev boots a self-contained local playground; init scaffolds a route, page, and plugin stub for your framework; schema copies the Postgres bundle.
Agents
AgentRegistry — persistent per-spec profiles with a rolling 100-invocation window, derived stats, and a trend signal.