@demlik/tea 0.18.0 → 0.20.0

package/README.md

@@ -9,21 +9,23 @@ pnpm add @demlik/tea
 ```
 
 The one runtime dependency is `@standard-schema/spec`, a types-only package
-installed for you. `Cmd.define` takes any Standard Schema, so bring the schema
+installed for you. [`Cmd.define`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#cmd) takes any Standard Schema, so bring the schema
 library you already use (zod, or Effect Schema through
 `Schema.toStandardSchemaV1`). The host and
 testing adapters ride on optional peers you add only for the surface you use:
 `react` / `react-dom` (the `./react` hooks), `ws` (Node WebSocket subs),
 `fast-check` (the `./pbt` property-testing helpers), `vitest` (the testing
-utilities), and `effect` (the `./effect` engine).
+utilities), `effect` (the `./effect` engine), and `@opentelemetry/api` (the
+`./otel` spans).
 
 ## Quickstart
 
-A machine is plain data: an `init` and an `update` map keyed by `Msg` type.
-`run` drives it, and when it has effects you hand `run` the `interpret` map
-that performs them; `dispatch` folds a `Msg`; `getState` reads the current
-Model. You name the Model and the `Msg` union
-once, under `types`; everything else is inferred from the machine itself.
+A [machine](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#machine) is plain data: an `init` and an [`update`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#update) map keyed by [`Msg`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#msg) type.
+[`run`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#run) drives it, and when it has effects you hand `run` the [`interpret`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#interpret) map
+that performs them; [`dispatch`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#dispatch) folds a `Msg`; `getState` reads the current
+[Model](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#model). You name the Model and the `Msg` union
+once, under `types`; everything else is inferred from the machine itself. Each of
+these words has an entry in the [glossary](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md).
 
 ```ts
 import { defineMachine } from "@demlik/tea";
@@ -41,38 +43,43 @@ const counter = defineMachine({
   },
 });
 
-const runtime = await run(counter, { ctx: {} }).ready;
+const runtime = await run(counter, {}).ready;
 await runtime.dispatch({ type: "increment" });
 runtime.getState(); // { count: 1 }
 ```
 
 ## Two engines, one machine
 
-The core is `@demlik/tea`, and each engine has its own entry point. A machine
+The core is `@demlik/tea`, and each [engine](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md#engine) has its own entry point. A machine
 file imports only the core, so it runs unchanged on either engine.
 
 - `@demlik/tea` — the core: `defineMachine`, `Cmd`, `replay` and the types. It
   imports no engine.
 - `@demlik/tea/promise` — the Promise engine. Handlers return Promises.
-- `@demlik/tea/effect` — the Effect engine (`experimental`, Effect v4). Handlers
+- `@demlik/tea/effect` — the Effect engine (`stable`, Effect v4). Handlers
   return Effects, services come from your Layers, the handle's verbs return
   Effects with typed errors, and closing the scope interrupts whatever is in
   flight.
 
-[Run a machine on the Promise engine](https://github.com/kamp-us/demlik/blob/main/docs/how-to/run-on-the-promise-engine.md)
-and [on the Effect engine](https://github.com/kamp-us/demlik/blob/main/docs/how-to/run-on-the-effect-engine.md)
-build on the same machine file. Coming from 0.15?
-[The migration guide](https://github.com/kamp-us/demlik/blob/main/docs/how-to/migrate-from-0-15.md)
+[Run a machine on the Promise engine](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/how-to/run-on-the-promise-engine.md)
+and [on the Effect engine](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/how-to/run-on-the-effect-engine.md)
+build on the same machine file.
+[Run many machines under one parent](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/how-to/run-many-machines.md)
+starts child machines on the Effect engine with `spawn`, `tell` and `stop`.
+Coming from 0.15?
+[The migration guide](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/how-to/migrate-from-0-15.md)
 shows every removed or reshaped API, before and after.
 
 ## Documentation
 
-The four Diátaxis quadrants live in [`docs/`](https://github.com/kamp-us/demlik/blob/main/docs/README.md):
+The four Diátaxis quadrants live in [`docs/`](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/README.md):
 
-- [Tutorials](https://github.com/kamp-us/demlik/blob/main/docs/tutorial/index.md) — learning-oriented lessons that take you through the library by building a real machine.
-- [How-to guides](https://github.com/kamp-us/demlik/blob/main/docs/how-to/index.md) — goal-oriented directions for getting a specific job done.
-- [Reference](https://github.com/kamp-us/demlik/blob/main/docs/reference/index.md) — information-oriented API description, generated per public module.
-- [Explanation](https://github.com/kamp-us/demlik/blob/main/docs/explanation/index.md) — understanding-oriented discussion of how it works and why it is shaped this way.
+- [Tutorials](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/tutorial/index.md) — learning-oriented lessons that take you through the library by building a real machine.
+- [How-to guides](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/how-to/index.md) — goal-oriented directions for getting a specific job done.
+- [Reference](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/reference/index.md) — information-oriented API description, generated per public module.
+- [Explanation](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/explanation/index.md) — understanding-oriented discussion of how it works and why it is shaped this way.
+
+The [glossary](https://github.com/kamp-us/demlik/blob/main/packages/tea/docs/glossary.md) defines each word those pages use: Model, Msg, Cmd, Sub, Store and the rest.
 
 Two more surfaces sit behind those, for people working on the library rather than using it:
 [`.patterns/`](https://github.com/kamp-us/demlik/blob/main/.patterns/index.md) is how the code is shaped, and

package/dist/agent/index.d.ts

@@ -1,19 +1,19 @@
-import { M as Machine, I as Interpret, S as Subscribe, H as HandlerCtx, C as Cmd } from '../core-Ce9ncpuv.js';
-import { b as DeadlinesSub } from '../index-e36uEyl4.js';
-export { a as DeadlineSub, m as deadlineSub, o as deadlinesSub, s as subscribeDeadline } from '../index-e36uEyl4.js';
-import { M as MessageContent, T as ToolCall, a as ToolOutcome, C as ContentPart, b as Conversation, c as AnyToolDef, d as ToolsCtx, e as AgentState, f as AgentTurn, g as ToolResult, A as AgentEvent, h as TurnChunk, i as AgentMachineMsg, W as WiredToolMsg, j as AgentCmd, k as ToolCmd, P as PlainModel, S as StreamingModel, l as ToolFailureOf, m as AgentTerminalFailure, N as NotReserved, n as ToolDef, o as ToolThrown, p as AgentEndedStatus, q as AgentConfigCore, r as CompactionPolicy, s as AgentKnob } from '../machine-CuojfZup.js';
-export { t as AGENT_EVENT_TYPES, u as AgentBootMsg, v as AgentCancelMsg, w as AgentCompactErrMsg, x as AgentCompactOkMsg, y as AgentCompactRunCmd, z as AgentCompactionConfig, B as AgentConfig, D as AgentEventHead, E as AgentFailure, F as AgentLifecycleNote, G as AgentLlmErrMsg, H as AgentLlmOkMsg, I as AgentLlmRunCmd, J as AgentSnapshotConfig, K as AgentStatus, L as AgentTimerMsg, O as AgentToMachine, Q as Awaiting, R as COMPACTION_PURPOSE, U as CompactInterpret, V as CompactionOutputs, X as CompactionPurpose, Y as CompactionSummary, Z as FILE_OMITTED, _ as FilePart, $ as IMAGE_OMITTED, a0 as ImagePart, a1 as Llm, a2 as LlmCall, a3 as LlmErr, a4 as LlmFailMsg, a5 as LlmOk, a6 as LlmRunCmd, a7 as LlmSucceedMsg, a8 as MediaSource, a9 as MessageLoader, aa as ModelFactory, ab as ModelPort, ac as ModelStream, ad as PLAIN_MODEL_MISROUTE_REASON, ae as ReservedToolName, af as Schema, ag as SnapshotInterpret, ah as TOOL_RETRY_EXHAUSTED_TAG, ai as TOOL_TIMEOUT_TAG, aj as TaggedFailure, ak as TextPart, al as ToolConstructors, am as ToolError, an as ToolFail, ao as ToolFailure, ap as ToolHandler, aq as ToolInput, ar as ToolMsg, as as ToolOk, at as ToolRecord, au as ToolRejectedCmd, av as ToolRejection, aw as ToolResilience, ax as ToolResilienceError, ay as ToolRetryExhausted, az as ToolRouter, aA as ToolSettlement, aB as ToolTimedOut, aC as TurnUsage, aD as WiredToolCmd, aE as agentBootMsg, aF as agentCancelMsg, aG as agentEvents, aH as agentTurnSchema, aI as compactionSummarySchema, aJ as contentParts, aK as fanOutInterpret, aL as isAgentTurn, aM as isCompactionSummary, aN as isReservedToolName, aO as isStreamingModel, aP as isTurnUsage, aQ as liftAgent, aR as mergeInterpret, aS as omitMedia, aT as plainModel, aU as status, aV as tool, aW as toolErrorReason, aX as toolRouter } from '../machine-CuojfZup.js';
+import { M as Machine, I as Interpret, c as Subscribe, H as HandlerCtx, C as Cmd } from '../core-CtvAyPpH.js';
+import { b as DeadlinesSub } from '../index-CVU7SK3a.js';
+export { a as DeadlineSub, m as deadlineSub, o as deadlinesSub, s as subscribeDeadline } from '../index-CVU7SK3a.js';
+import { M as MessageContent, T as ToolCall, a as ToolOutcome, C as ContentPart, b as Conversation, c as AnyToolDef, d as ToolsCtx, e as AgentState, f as AgentTurn, g as ToolResult, A as AgentEvent, h as TurnChunk, i as AgentMachineMsg, W as WiredToolMsg, j as AgentCmd, k as ToolCmd, P as PlainModel, S as StreamingModel, l as ToolFailureOf, m as AgentTerminalFailure, N as NotReserved, n as ToolDef, o as ToolThrown, p as AgentEndedStatus, q as AgentConfigCore, r as CompactionPolicy, s as AgentKnob } from '../machine-Dtre2TmN.js';
+export { t as AGENT_EVENT_TYPES, u as AgentBootMsg, v as AgentCancelMsg, w as AgentCompactErrMsg, x as AgentCompactOkMsg, y as AgentCompactRunCmd, z as AgentCompactionConfig, B as AgentConfig, D as AgentEventHead, E as AgentFailure, F as AgentLifecycleNote, G as AgentLlmErrMsg, H as AgentLlmOkMsg, I as AgentLlmRunCmd, J as AgentSnapshotConfig, K as AgentStatus, L as AgentTimerMsg, O as AgentToMachine, Q as Awaiting, R as COMPACTION_PURPOSE, U as CompactInterpret, V as CompactionOutputs, X as CompactionPurpose, Y as CompactionSummary, Z as FILE_OMITTED, _ as FilePart, $ as IMAGE_OMITTED, a0 as ImagePart, a1 as Llm, a2 as LlmCall, a3 as LlmErr, a4 as LlmFailMsg, a5 as LlmOk, a6 as LlmRunCmd, a7 as LlmSucceedMsg, a8 as MediaSource, a9 as MessageLoader, aa as ModelFactory, ab as ModelPort, ac as ModelStream, ad as PLAIN_MODEL_MISROUTE_REASON, ae as ReservedToolName, af as Schema, ag as SnapshotInterpret, ah as TOOL_RETRY_EXHAUSTED_TAG, ai as TOOL_TIMEOUT_TAG, aj as TaggedFailure, ak as TextPart, al as ToolConstructors, am as ToolError, an as ToolFail, ao as ToolFailure, ap as ToolHandler, aq as ToolInput, ar as ToolMsg, as as ToolOk, at as ToolRecord, au as ToolRejectedCmd, av as ToolRejection, aw as ToolResilience, ax as ToolResilienceError, ay as ToolRetryExhausted, az as ToolRouter, aA as ToolSettlement, aB as ToolTimedOut, aC as TurnUsage, aD as WiredToolCmd, aE as agentBootMsg, aF as agentCancelMsg, aG as agentEvents, aH as agentTurnSchema, aI as compactionSummarySchema, aJ as contentParts, aK as fanOutInterpret, aL as isAgentTurn, aM as isCompactionSummary, aN as isReservedToolName, aO as isStreamingModel, aP as isTurnUsage, aQ as liftAgent, aR as mergeInterpret, aS as omitMedia, aT as plainModel, aU as status, aV as tool, aW as toolErrorReason, aX as toolRouter } from '../machine-Dtre2TmN.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { C as CtxArg, S as Store } from '../runtime-types-BKg2CGMx.js';
-import { E as EndedRun } from '../index-Dy3379ve.js';
-export { M as MonitoredRunCmd, R as RunFailure } from '../index-Dy3379ve.js';
+import { C as CtxArg, S as Store } from '../runtime-types-DEluQgGO.js';
+import { E as EndedRun } from '../index-CZZ3HI-Z.js';
+export { M as MonitoredRunCmd, R as RunFailure } from '../index-CZZ3HI-Z.js';
 import { RetryPolicy } from '../retry-backoff/index.js';
-import '../types-SzNSHKlV.js';
-import '../index-2kNxy6az.js';
+import '../types-CXNzlbAg.js';
+import '../index-CKtEKGyp.js';
 import '../protocol-ClRZBhHQ.js';
-import '../index-Ce5GYAuI.js';
-import '../index-DWdg7R1l.js';
-import '../index-D8sYVzCI.js';
+import '../index-CrcoVfd_.js';
+import '../index-D3NY3VCN.js';
+import '../index-Bk2hBUdK.js';
 
 /**
  * @demlik/tea/agent — `defineAgent`, the convenience layer over `createAgent`.
@@ -181,6 +181,14 @@ interface DefineAgentConfig<T extends AnyToolDef> {
      * Stops a run that keeps going: the maximum number of model round-trips it
      * may take. Once the completed-turn count reaches it the run fails rather
      * than calling the model again. Omit → no limit on turns.
+     *
+     * The count is COMPLETED model round-trips. A compaction pass is not one, and
+     * tool calls are not counted at all: a turn that asks for six tools is one
+     * turn.
+     *
+     * The failure is `{ reason: "turn_limit", at }` on the Model's own `failure`
+     * field. `run` rejects with a `DriveFailedError` whose `.state` is that final
+     * Model.
      */
     readonly maxTurns?: number;
     /**
@@ -188,6 +196,12 @@ interface DefineAgentConfig<T extends AnyToolDef> {
      * advancing before it fails. The budget is a no-progress watchdog, not a
      * total wall-clock cap — it restarts each time the run moves. Omit → no
      * watchdog.
+     *
+     * The failure is `{ reason: "deadline", at }` on the Model's `run.failure`,
+     * the monitored-run slice, and not on the agent's own `failure` field where
+     * `turn_limit` and `elapsed_limit` land. `at` is when the watchdog fired. A
+     * tool or model call already out runs to its own end first, so `run` can
+     * settle later than `at`.
      */
     readonly deadlineMs?: number;
     /**
@@ -199,6 +213,12 @@ interface DefineAgentConfig<T extends AnyToolDef> {
      * at the turn boundary, so like both of those it stops the run rather than
      * cancelling the work already in flight. Omit → no wall-clock cap.
      *
+     * Read at the turn boundary means the run ends at the first boundary past
+     * the budget, not at the millisecond it comes due: a run 10ms into a 400ms
+     * tool call under a 150ms budget fails when that tool settles. The failure
+     * is `{ reason: "elapsed_limit", at }` on the Model's own `failure` field,
+     * beside `turn_limit`.
+     *
      * The run's start time is on the durable Model, so a run killed and resumed
      * continues the ORIGINAL budget — the time it spent dead counts against it.
      *
@@ -218,6 +238,10 @@ interface DefineAgentConfig<T extends AnyToolDef> {
      * run's provider-reported total), an external flag, a condition on the turns
      * so far. Omit → no predicate.
      *
+     * A stop you asked for is not a failure, so `run` RESOLVES with the final
+     * Model where the other three guards make it reject, and `status(state)`
+     * answers `{ kind: "cancelled", at }`.
+     *
      * It must be PURE: the reducer calls it, so a replay hands it the same state
      * and must get the same answer. And it is config rather than Model — a
      * resumed run consults the predicate the config passed to THIS boot, exactly
@@ -279,6 +303,13 @@ interface DefineAgentConfig<T extends AnyToolDef> {
      * summarize round-trip that enforces it is wiring, so the lid takes the
      * former and supplies the latter from the `model` it already has.
      *
+     * `afterTurns: 20` folds once the conversation holds twenty turns.
+     * `afterContextTokens: 8_000` folds once the last brain turn's reported
+     * `inputTokens + outputTokens` reaches eight thousand; the number is yours,
+     * because tea knows no model's window size. Set both and the first one
+     * reached folds. `keepTurns` is how many of the newest turns survive the
+     * fold intact. It is not a guard: nothing fails, and the run goes on.
+     *
      * Omit → NO compaction, exactly as before: the transcript grows for as long
      * as the model keeps asking for tools. Nothing is defaulted on your behalf —
      * a silent budget would change the prompt every existing caller sends.

package/dist/agent/index.js

@@ -1,16 +1,16 @@
-export { AGENT_EVENT_TYPES, COMPACTION_PURPOSE, FILE_OMITTED, IMAGE_OMITTED, PLAIN_MODEL_MISROUTE_REASON, TOOL_RETRY_EXHAUSTED_TAG, TOOL_TIMEOUT_TAG, agentBootMsg, agentCancelMsg, agentEvents, agentTool, agentTurnSchema, compactionSummarySchema, contentParts, createAgent, defineAgent, fanOutInterpret, isAgentTurn, isCompactionSummary, isReservedToolName, isStreamingModel, isTurnUsage, liftAgent, mergeInterpret, omitMedia, plainModel, renderPrompt, status, tool, toolErrorReason, toolRouter, transcript } from '../chunk-PCJA2HTZ.js';
-import '../chunk-XVIKSRCK.js';
-import '../chunk-YIMOFXST.js';
+export { AGENT_EVENT_TYPES, COMPACTION_PURPOSE, FILE_OMITTED, IMAGE_OMITTED, PLAIN_MODEL_MISROUTE_REASON, TOOL_RETRY_EXHAUSTED_TAG, TOOL_TIMEOUT_TAG, agentBootMsg, agentCancelMsg, agentEvents, agentTool, agentTurnSchema, compactionSummarySchema, contentParts, createAgent, defineAgent, fanOutInterpret, isAgentTurn, isCompactionSummary, isReservedToolName, isStreamingModel, isTurnUsage, liftAgent, mergeInterpret, omitMedia, plainModel, renderPrompt, status, tool, toolErrorReason, toolRouter, transcript } from '../chunk-2774I242.js';
+import '../chunk-EA47MI5Q.js';
+import '../chunk-2R62Q5UK.js';
 import '../chunk-QNGYQMZB.js';
-import '../chunk-WTSOW2MD.js';
-export { deadlineSub, deadlinesSub, subscribeDeadline } from '../chunk-C3G2QFEZ.js';
+import '../chunk-72CN3VPY.js';
+export { deadlineSub, deadlinesSub, subscribeDeadline } from '../chunk-TAKPC6SD.js';
 import '../chunk-VBDU4JL6.js';
 import '../chunk-4LPY67E4.js';
 import '../chunk-TXN2KFHF.js';
-import '../chunk-H2ELKHI6.js';
-import '../chunk-AHW2CLPT.js';
-import '../chunk-JVE2LBFJ.js';
-import '../chunk-FNGZMVIT.js';
-import '../chunk-AIIXV4XB.js';
+import '../chunk-JAKM53JF.js';
+import '../chunk-UHAQ4PI6.js';
+import '../chunk-A73IJ27X.js';
+import '../chunk-DVNXEB7V.js';
+import '../chunk-RKVUVALV.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{chunk-PCJA2HTZ.js → chunk-2774I242.js}

@@ -1,10 +1,10 @@
-import { createMonitoredRun } from './chunk-XVIKSRCK.js';
+import { createMonitoredRun } from './chunk-EA47MI5Q.js';
 import { createFanOut, initFanOut } from './chunk-QNGYQMZB.js';
-import { createResilientCall } from './chunk-WTSOW2MD.js';
-import { deadlinesSub, subscribeDeadline } from './chunk-C3G2QFEZ.js';
+import { createResilientCall } from './chunk-72CN3VPY.js';
+import { deadlinesSub, subscribeDeadline } from './chunk-TAKPC6SD.js';
 import { rejectAll, unchecked } from './chunk-4LPY67E4.js';
-import { run, driveToDone } from './chunk-H2ELKHI6.js';
-import { Cmd, absurd, Outcome, cmdEdgeOf, detachWorkOf, defineMachine, validateSync, malformedResult, describeError, DriveFailedError } from './chunk-AIIXV4XB.js';
+import { run, driveToDone } from './chunk-JAKM53JF.js';
+import { Cmd, absurd, Outcome, cmdEdgeOf, detachWorkOf, defineMachine, validateSync, malformedResult, describeError, DriveFailedError } from './chunk-RKVUVALV.js';
 
 // src/internal/llm-call/index.ts
 function createLlmCall(config, rng = Math.random) {
@@ -1777,5 +1777,5 @@ function createAgent(config) {
 }
 
 export { AGENT_EVENT_TYPES, COMPACTION_PURPOSE, FILE_OMITTED, IMAGE_OMITTED, PLAIN_MODEL_MISROUTE_REASON, TOOL_RETRY_EXHAUSTED_TAG, TOOL_TIMEOUT_TAG, agentBootMsg, agentCancelMsg, agentEvents, agentTool, agentTurnSchema, compactionSummarySchema, contentParts, createAgent, defineAgent, fanOutInterpret, isAgentTurn, isCompactionSummary, isReservedToolName, isStreamingModel, isTurnUsage, liftAgent, mergeInterpret, omitMedia, plainModel, renderPrompt, status, tool, toolErrorReason, toolRouter, transcript };
-//# sourceMappingURL=chunk-PCJA2HTZ.js.map
-//# sourceMappingURL=chunk-PCJA2HTZ.js.map
+//# sourceMappingURL=chunk-2774I242.js.map
+//# sourceMappingURL=chunk-2774I242.js.map