[{"data":1,"prerenderedAt":789},["ShallowReactive",2],{"navigation":3,"\u002Fcontributing\u002Fpackage-map":169,"\u002Fcontributing\u002Fpackage-map-surround":786},[4,28,85,127,157],{"title":5,"path":6,"stem":7,"children":8,"icon":27},"Getting Started","\u002Fgetting-started","1.getting-started\u002F1.index",[9,12,17,22],{"title":10,"path":6,"stem":7,"icon":11},"Introduction","i-lucide-house",{"title":13,"path":14,"stem":15,"icon":16},"Installation","\u002Fgetting-started\u002Finstallation","1.getting-started\u002F2.installation","i-lucide-download",{"title":18,"path":19,"stem":20,"icon":21},"Quick start","\u002Fgetting-started\u002Fquick-start","1.getting-started\u002F3.quick-start","i-lucide-zap",{"title":23,"path":24,"stem":25,"icon":26},"Architecture","\u002Fgetting-started\u002Farchitecture","1.getting-started\u002F4.architecture","i-lucide-layers","i-lucide-rocket",{"title":29,"icon":30,"path":31,"stem":32,"children":33,"page":84},"Concepts","i-lucide-lightbulb","\u002Fconcepts","2.concepts",[34,39,44,49,54,59,64,69,74,79],{"title":35,"path":36,"stem":37,"icon":38},"Durable agents","\u002Fconcepts\u002Fdurable-agents","2.concepts\u002F1.durable-agents","i-lucide-infinity",{"title":40,"path":41,"stem":42,"icon":43},"Glossary","\u002Fconcepts\u002Fglossary","2.concepts\u002F10.glossary","i-lucide-book-a",{"title":45,"path":46,"stem":47,"icon":48},"Restate in five minutes","\u002Fconcepts\u002Frestate-primer","2.concepts\u002F2.restate-primer","i-lucide-cpu",{"title":50,"path":51,"stem":52,"icon":53},"Entities & addressing","\u002Fconcepts\u002Fentities-addressing","2.concepts\u002F3.entities-addressing","i-lucide-at-sign",{"title":55,"path":56,"stem":57,"icon":58},"Timelines & events","\u002Fconcepts\u002Ftimelines-events","2.concepts\u002F4.timelines-events","i-lucide-list-ordered",{"title":60,"path":61,"stem":62,"icon":63},"Projections & the catalog","\u002Fconcepts\u002Fprojections-catalog","2.concepts\u002F5.projections-catalog","i-lucide-database",{"title":65,"path":66,"stem":67,"icon":68},"Workspaces & execution","\u002Fconcepts\u002Fworkspaces","2.concepts\u002F6.workspaces","i-lucide-terminal",{"title":70,"path":71,"stem":72,"icon":73},"Harnesses","\u002Fconcepts\u002Fharnesses","2.concepts\u002F7.harnesses","i-lucide-plug",{"title":75,"path":76,"stem":77,"icon":78},"Multi-agent patterns","\u002Fconcepts\u002Fmulti-agent","2.concepts\u002F8.multi-agent","i-lucide-network",{"title":80,"path":81,"stem":82,"icon":83},"Lifecycle & control","\u002Fconcepts\u002Flifecycle","2.concepts\u002F9.lifecycle","i-lucide-sliders-horizontal",false,{"title":86,"icon":87,"path":88,"stem":89,"children":90,"page":84},"Guides","i-lucide-book-open","\u002Fguides","3.guides",[91,106],{"title":92,"icon":93,"path":94,"stem":95,"children":96,"page":84},"Agents","i-lucide-bot","\u002Fguides\u002Fagents","3.guides\u002F1.agents",[97,101],{"title":98,"path":99,"stem":100,"icon":93},"Building agents","\u002Fguides\u002Fagents\u002Fbuilding-agents","3.guides\u002F1.agents\u002F1.building-agents",{"title":102,"path":103,"stem":104,"icon":105},"Frontend integration","\u002Fguides\u002Fagents\u002Ffrontend-integration","3.guides\u002F1.agents\u002F2.frontend-integration","i-lucide-monitor",{"title":107,"icon":108,"path":109,"stem":110,"children":111,"page":84},"Operations","i-lucide-server-cog","\u002Fguides\u002Foperations","3.guides\u002F2.operations",[112,117,122],{"title":113,"path":114,"stem":115,"icon":116},"Self-hosting","\u002Fguides\u002Foperations\u002Fself-hosting","3.guides\u002F2.operations\u002F1.self-hosting","i-lucide-server",{"title":118,"path":119,"stem":120,"icon":121},"Auth & API keys","\u002Fguides\u002Foperations\u002Fauth-api-keys","3.guides\u002F2.operations\u002F2.auth-api-keys","i-lucide-key-round",{"title":123,"path":124,"stem":125,"icon":126},"Backup & restore","\u002Fguides\u002Foperations\u002Fbackup-restore","3.guides\u002F2.operations\u002F3.backup-restore","i-lucide-database-backup",{"title":128,"icon":129,"path":130,"stem":131,"children":132,"page":84},"Reference","i-lucide-book-marked","\u002Freference","4.reference",[133,138,143,148,153],{"title":134,"path":135,"stem":136,"icon":137},"Event schema","\u002Freference\u002Fevents","4.reference\u002F1.events","i-lucide-list-tree",{"title":139,"path":140,"stem":141,"icon":142},"Addressing","\u002Freference\u002Faddressing","4.reference\u002F2.addressing","i-lucide-map-pin",{"title":144,"path":145,"stem":146,"icon":147},"Gateway HTTP API","\u002Freference\u002Fgateway-api","4.reference\u002F3.gateway-api","i-lucide-webhook",{"title":149,"path":150,"stem":151,"icon":152},"CLI","\u002Freference\u002Fcli","4.reference\u002F4.cli","i-lucide-square-terminal",{"title":154,"path":155,"stem":156,"icon":83},"Configuration","\u002Freference\u002Fconfiguration","4.reference\u002F5.configuration",{"title":158,"path":159,"stem":160,"children":161,"icon":163},"Contributing","\u002Fcontributing","5.contributing\u002F1.index",[162,164],{"title":158,"path":159,"stem":160,"icon":163},"i-lucide-git-pull-request",{"title":165,"path":166,"stem":167,"icon":168},"The package map","\u002Fcontributing\u002Fpackage-map","5.contributing\u002F2.package-map","i-lucide-boxes",{"id":170,"title":165,"body":171,"description":779,"extension":780,"links":781,"meta":782,"navigation":783,"path":166,"seo":784,"stem":167,"__hash__":785},"docs\u002F5.contributing\u002F2.package-map.md",{"type":172,"value":173,"toc":754},"minimark",[174,182,337,342,347,393,397,426,430,463,467,539,543,548,552,555,559,591,595,618,622,652,656,685,689,709,713,724,728,731,735,743,747],[175,176,177,178,181],"p",{},"teaspill is thirteen packages in one workspace. This page is the machine-room tour: what each package does, what it exports, and whether it's something you use to build agents or something you'd only open as a contributor. It goes one level deeper than ",[179,180,29],"a",{"href":36}," — naming the outbox, the reconciler, and the internal seams — so treat it as the map you keep open while reading the source.",[183,184,185,198],"table",{},[186,187,188],"thead",{},[189,190,191,195],"tr",{},[192,193,194],"th",{},"Package",[192,196,197],{},"In one line",[199,200,201,213,223,237,247,257,267,277,287,297,307,317,327],"tbody",{},[189,202,203,210],{},[204,205,206],"td",{},[207,208,209],"code",{},"agents-sdk",[204,211,212],{},"Define agents in TypeScript, serve them, register them.",[189,214,215,220],{},[204,216,217],{},[207,218,219],{},"frontend-sdk",[204,221,222],{},"Materialize timelines, watch the catalog, send commands from your app.",[189,224,225,230],{},[204,226,227],{},[207,228,229],{},"cli",[204,231,232,233,236],{},"The ",[207,234,235],{},"teaspill"," command — run the stack, drive agents, mint keys.",[189,238,239,244],{},[204,240,241],{},[207,242,243],{},"schema",[204,245,246],{},"The canonical event vocabulary and the addressing helpers everything shares.",[189,248,249,254],{},[204,250,251],{},[207,252,253],{},"reference-deployment",[204,255,256],{},"A working, copy-me deployment of the two planes you run.",[189,258,259,264],{},[204,260,261],{},[207,262,263],{},"gateway",[204,265,266],{},"The single front door: auth plus the proxy every client goes through.",[189,268,269,274],{},[204,270,271],{},[207,272,273],{},"coordination",[204,275,276],{},"The durable-agent engine on Restate — object, outbox, control, cron.",[189,278,279,284],{},[204,280,281],{},[207,282,283],{},"catalog",[204,285,286],{},"The Postgres registry of every entity, synced live via Electric.",[189,288,289,294],{},[204,290,291],{},[207,292,293],{},"executor",[204,295,296],{},"The workspace plane — sandboxed filesystems and shells for tools.",[189,298,299,304],{},[204,300,301],{},[207,302,303],{},"harness-native",[204,305,306],{},"The harness contract plus the native, teaspill-owned model loop.",[189,308,309,314],{},[204,310,311],{},[207,312,313],{},"harness-casdk",[204,315,316],{},"The Claude Agent SDK harness, with durable sessions.",[189,318,319,324],{},[204,320,321],{},[207,322,323],{},"conformance",[204,325,326],{},"A reusable suite asserting teaspill's durability guarantees.",[189,328,329,334],{},[204,330,331],{},[207,332,333],{},"chaos",[204,335,336],{},"Failure injection: kill services mid-run, re-check the invariants.",[338,339,341],"h2",{"id":340},"youll-use-these","You'll use these",[343,344,345],"h3",{"id":209},[207,346,209],{},[175,348,349,350,353,354,357,358,361,362,365,366,369,370,373,374,377,378,381,382,385,386,389,390,392],{},"The developer-facing surface for defining agents. Its primary export, ",[207,351,352],{},"defineAgent",", takes a typed definition — spawn\u002Fmessage schemas, durable state, tools, an optional ",[207,355,356],{},"onWake"," hook — and compiles it into a running ",[179,359,360],{"href":36},"durable agent",". You pick a ",[179,363,364],{"href":71},"harness"," with ",[207,367,368],{},"native(...)"," or ",[207,371,372],{},"claudeAgentSdk(...)","; swapping between them changes nothing else about the agent. ",[207,375,376],{},"serve(...)"," stands up the endpoint and ",[207,379,380],{},"registerDeployment(...)"," announces it to the gateway. The package also enforces the additive-only rule for ",[179,383,384],{"href":99},"state revisions"," at build time — a breaking schema change at an unchanged revision throws loudly rather than corrupting state at runtime — and exports ",[207,387,388],{},"mintReadToken"," for issuing browser read tokens. This is the first package a user touches; start with the ",[179,391,98],{"href":99}," guide.",[343,394,395],{"id":219},[207,396,219],{},[175,398,399,400,403,404,407,408,411,412,415,416,418,419,422,423,425],{},"The browser and app-facing SDK, framework-agnostic with optional React bindings. Three clients cover the three route families: ",[207,401,402],{},"createActionsClient"," sends spawn\u002Fsend\u002Fcontrol commands, ",[207,405,406],{},"createAgentTimeline"," folds an entity's ",[179,409,410],{"href":56},"timeline"," into rendered messages and live token deltas, and ",[207,413,414],{},"createAgentCatalog"," subscribes to ",[179,417,283],{"href":61}," rows over Electric shapes. The heart of it is a pure reducer you can also run on a server: it deduplicates events by ",[207,420,421],{},"seq",", joins a long timeline late from a snapshot (fast-join with a stream offset), and surfaces a forward gap as drift instead of silently dropping it. Writes always go through the gateway. Reach for it whenever you're putting agent activity on a screen — see ",[179,424,102],{"href":103},".",[343,427,428],{"id":229},[207,429,229],{},[175,431,232,432,434,435,438,439,442,443,442,446,442,449,442,452,455,456,459,460,425],{},[207,433,235],{}," binary — the dev loop plus entity inspection. It's a thin consumer of the SDKs, never reimplementing stream reading or the actions client. ",[207,436,437],{},"teaspill dev"," brings the compose stack up, waits on gateway health, and registers your local deployment with backoff (the fix for the register-before-ready race). The rest drive the platform: ",[207,440,441],{},"agents ls",", ",[207,444,445],{},"spawn",[207,447,448],{},"send",[207,450,451],{},"control",[207,453,454],{},"logs"," (follow a timeline, optionally with deltas or from a snapshot), and ",[207,457,458],{},"keys create|ls|revoke"," for API-key administration against the operator database. Every command body is a plain function over injected dependencies, so parsing and sequencing are unit-tested without a live stack. The full command surface is the ",[179,461,462],{"href":150},"CLI reference",[343,464,465],{"id":243},[207,466,243],{},[175,468,469,470,442,473,442,476,442,478,442,481,442,484,487,488,491,492,442,495,442,498,501,502,505,506,509,510,513,514,517,518,521,522,442,525,442,528,442,531,534,535,538],{},"The canonical event schema and token-delta framing — the frozen v1 contract every other package builds on. It defines the event envelope (",[207,471,472],{},"v",[207,474,475],{},"entityId",[207,477,421],{},[207,479,480],{},"ts",[207,482,483],{},"type",[207,485,486],{},"payload","), the fifteen event types (from ",[207,489,490],{},"entity_spawned"," at seq 0 through ",[207,493,494],{},"run_finished",[207,496,497],{},"child_finished",[207,499,500],{},"archived",", and the catch-all ",[207,503,504],{},"opaque","), and the sibling delta stream. ",[207,507,508],{},"finalizeEvent"," is the single seq allocator's stamp; ",[207,511,512],{},"checkSeqContiguity"," and ",[207,515,516],{},"checkTimelineInvariants"," are the structural guards. It's also the public home of the ",[179,519,520],{"href":140},"addressing"," helpers — ",[207,523,524],{},"entityUrl",[207,526,527],{},"parseEntityUrl",[207,529,530],{},"timelineStreamPath",[207,532,533],{},"workspaceKey",", and friends. You mostly meet it indirectly through the other SDKs, but you'll import its types and helpers directly the moment you handle raw events. The ",[179,536,537],{"href":135},"Event schema reference"," documents every type.",[343,540,541],{"id":253},[207,542,253],{},[175,544,545,546,425],{},"A complete, working deployment of the two planes you run yourself — an agent-loop service and an executor-host service — plus the compose overlay that adds them to the base stack. It plays three roles at once. It's the getting-started example: copy this package to bootstrap your own deployment, since every seam is wired from public package APIs and nothing internal. It's the stack the live conformance and chaos suites run against, serving the deterministic conformance agents. And it's the home of the deployment-side pieces the SDK leaves open — the ingress workspace client (with abort-to-kill), the ingress tool clients, and catalog-backed child listing. If you want a real example of loose-message normalization or reconciler wiring, read this package. See ",[179,547,113],{"href":114},[338,549,551],{"id":550},"the-platform","The platform",[175,553,554],{},"These are the services you deploy and run — you don't import them into your agent code. As a user you care that they're up and configured; as a contributor this is where the durability machinery lives.",[343,556,557],{"id":263},[207,558,263],{},[175,560,561,562,565,566,442,569,442,572,575,576,579,580,583,584,587,588,590],{},"The platform's single entrypoint. Every external caller — your app, a UI, the CLI, a developer service — talks to teaspill through the gateway; Restate, Postgres, Electric, and the durable streams server are never exposed directly. It authenticates with API keys (",[207,563,564],{},"Authorization: Bearer","), routes commands to Restate ingress (",[207,567,568],{},"\u002Fapi\u002Fspawn",[207,570,571],{},"\u002Fapi\u002F...\u002Fsend",[207,573,574],{},"\u002Fapi\u002F...\u002Fcontrol","), and byte-exact proxies the read paths — ",[207,577,578],{},"\u002Fstreams\u002F*"," for timelines and ",[207,581,582],{},"\u002Fshapes\u002F*"," for Electric — preserving long-poll parking, offsets, and caching headers so reads stay resumable. An optional short-lived JWT read path lets a browser read stream and shape routes directly without proxying every request, while writes never bypass your backend. Its full route table and error semantics are the ",[179,585,586],{"href":145},"Gateway HTTP API reference","; operators should read the ",[179,589,113],{"href":114}," networking rules before registering a service.",[343,592,593],{"id":273},[207,594,273],{},[175,596,597,598,600,601,605,606,608,609,612,613,513,615,617],{},"You only touch this package as a contributor — it's the durable-agent engine, and ",[207,599,352],{}," specializes it for you. It ships the agent virtual object template on Restate: one object per agent type, keyed by instance id, processing one wake at a time. Inside it are the mechanisms Concepts keeps behind plain language. The ",[602,603,604],"strong",{},"projection outbox"," is the system's only ",[207,607,421],{}," allocator — it stages events into durable state and flushes them to the stream through an idempotent producer, replaying in order from the first unconfirmed record and trimming only after a confirm, which is what makes projection exactly-once. The ",[602,610,611],{},"reconciler"," detects, alerts on, and requests recovery from outbox drift, while the agent object executes the actual repair. The interrupt seam, cron, and the archive tick live here too. This is the densest package in the repo; the ",[179,614,35],{"href":36},[179,616,60],{"href":61}," concepts are the gentle version.",[343,619,620],{"id":283},[207,621,283],{},[175,623,624,625,627,628,631,632,635,636,639,640,643,644,647,648,651],{},"Mostly a contributor and operator concern: the Postgres schema and migrations for the ",[179,626,283],{"href":61},". It owns three tables — ",[207,629,630],{},"entities"," (the registry: url, tenant, type, status, tags, parent, head sequence, and the archived snapshot that makes resurrection possible), ",[207,633,634],{},"entity_tags"," (a normalized index so Electric ",[207,637,638],{},"where"," clauses stay fast), and ",[207,641,642],{},"api_keys"," (the gateway's auth store). Coordination writes entity rows from inside agent handlers; the gateway reads keys and proxies Electric shapes over the entity tables. It uses Drizzle with checked-in SQL migrations, including the hand-written operational setup Electric requires (",[207,645,646],{},"REPLICA IDENTITY FULL"," and the ",[207,649,650],{},"updated_at"," trigger). You run its migrations when you stand up a stack; you edit it when you change what the catalog stores.",[343,653,654],{"id":293},[207,655,293],{},[175,657,658,659,662,663,666,667,670,671,674,675,678,679,682,683,425],{},"The workspace plane — the sandboxed environments where an agent's tools actually run commands. Each ",[179,660,661],{"href":66},"workspace"," is a Restate virtual object fronting a real environment, serialized per workspace, delegating to a stateless executor-host service behind a minimal ",[602,664,665],{},"adapter seam",". Three adapters ship behind that seam: a dev-only ",[207,668,669],{},"local",", a guarded ",[207,672,673],{},"local-unrestricted",", and ",[207,676,677],{},"docker"," — one container per workspace, a named volume that outlives the container, and idle teardown. The long-exec protocol uses durable awakeables so a command survives an agent-loop restart, with a host-unresponsive backstop and a concurrent ",[207,680,681],{},"kill"," escape hatch. The minimal seam is deliberate: it's what lets a remote VM adapter slot in later. Contributors work in the adapters and containment logic; operators must read the Docker socket trust boundary in ",[179,684,113],{"href":114},[343,686,687],{"id":303},[207,688,303],{},[175,690,691,692,695,696,699,700,702,703,706,707,425],{},"The harness contract itself, plus the native model loop teaspill owns end to end. As a contributor this is the frozen ",[207,693,694],{},"Harness"," interface every harness implements — ",[207,697,698],{},"run(...)"," returns timeline events (never allocating ",[207,701,421],{},", since the outbox is the sole allocator), a state delta, and usage. The load-bearing clauses live here: every side-effecting tool call goes through Restate ingress under an idempotency key so it's exactly-once under any retry, and ",[207,704,705],{},"emitDelta"," is fire-and-forget that never blocks a run. The native harness journals every model call and every tool call as its own durable step — the finest-grained durability of the two — and works with any provider. It's dependency-light on purpose so the other harness and the SDK can import the contract. The user-facing view is ",[179,708,70],{"href":71},[343,710,711],{"id":313},[207,712,313],{},[175,714,715,716,718,719,721,722,425],{},"The Claude Agent SDK harness — Claude Code semantics (sessions, compaction) for agents that want them. It implements the same frozen ",[207,717,694],{}," interface as the native loop through three layers: tools execute through an in-process MCP server bound to the same exactly-once idempotency key; a durable session per entity is persisted and can be repaired on load after a crash; and canonical timeline events remain the authority, with a cold rebuild that reconstructs the session from the timeline if it's ever lost. The Claude Agent SDK dependency is exact-pinned and loads lazily — selecting or compiling one of these agents never pulls it in. You select it with ",[207,720,372],{}," in your agent definition; as a contributor, this is where the durable-session translation lives. See ",[179,723,70],{"href":71},[338,725,727],{"id":726},"quality-kits","Quality kits",[175,729,730],{},"These two packages exist to prove teaspill keeps its promises. You'll meet them when you're contributing or hardening a deployment, rarely otherwise.",[343,732,733],{"id":323},[207,734,323],{},[175,736,737,738,742],{},"A reusable acceptance suite of named scenarios, each asserting one durability invariant of a running stack — spawn-and-respond, parallel fan-out (the dropped-parent-wake regression), crash-resume, projection continuity across a streams-server restart, and workspace-exec durability. Every scenario has a one-sentence invariant, a driver, and a pure check that returns violations rather than throwing, so other tooling can inspect exactly what broke. Each runs two ways: offline against the real coordination and executor primitives plus faithful fakes (these run in CI with no stack), and live end-to-end through the developer surfaces, gated on a stack URL. Ready-made implementations of the conformance agents ship in the ",[179,739,741],{"href":740},"\u002Fcontributing\u002Fpackage-map#reference-deployment","reference deployment"," — deploy that stack and point the suite at it. The chaos suite is built on top of this kit.",[343,744,745],{"id":333},[207,746,333],{},[175,748,749,750,753],{},"The failure-injection suite, and the acceptance test for teaspill's durability decisions. For each of five faults it drives a conformance scenario, injects the fault mid-flight — killing the agent-loop, the executor, the streams server, Restate, or the gateway — then re-asserts the mapped invariant. The point is stated in the package itself: assert the invariant, not just no-crash. Faults one through four have offline invariant tests that run in CI against the real primitives, so continuous integration exercises the exactly-once, seq-gapless, awakeable-timeout, and durable-resume logic rather than a skipped shell; the fifth is live-only, with its offline coverage living in the gateway package. Live runs shell out to ",[207,751,752],{},"docker compose"," to kill and restart real containers, so they're doubly gated and meant only for a disposable dev stack.",{"title":755,"searchDepth":756,"depth":757,"links":758},"",1,2,[759,767,775],{"id":340,"depth":757,"text":341,"children":760},[761,763,764,765,766],{"id":209,"depth":762,"text":209},3,{"id":219,"depth":762,"text":219},{"id":229,"depth":762,"text":229},{"id":243,"depth":762,"text":243},{"id":253,"depth":762,"text":253},{"id":550,"depth":757,"text":551,"children":768},[769,770,771,772,773,774],{"id":263,"depth":762,"text":263},{"id":273,"depth":762,"text":273},{"id":283,"depth":762,"text":283},{"id":293,"depth":762,"text":293},{"id":303,"depth":762,"text":303},{"id":313,"depth":762,"text":313},{"id":726,"depth":757,"text":727,"children":776},[777,778],{"id":323,"depth":762,"text":323},{"id":333,"depth":762,"text":333},"All thirteen teaspill packages — what each is for, its public surface, and whether you use it or only touch it as a contributor.","md",null,{},{"icon":168},{"title":165,"description":779},"wDPbe5yJaI1xYfIcyxTqNxnFJqbhdsckj_zOLuF_6cY",[787,781],{"title":158,"path":159,"stem":160,"description":788,"icon":163,"children":-1},"How to work on teaspill itself — the repo layout, the build and test bar, the conventions, and where the design history lives.",1784473424287]