@juno-ai/bind 2.0.0 → 4.0.0

package/README.md

@@ -3,88 +3,1181 @@
 **`@juno-ai/bind` — an agent harness.**
 
 The agent loop is a bind chain: each turn sequences a model completion into
-tool effects into the next turn's context. `bind` is the harness that runs
-that chain — the runtime-agnostic core of a production agent loop, extracted
-from [Monad](https://onmonad.ai).
+tool effects into the next turn's context. `bind` is the harness that runs that
+chain — the runtime-agnostic core of a production agent loop, extracted from
+[Monad](https://onmonad.ai).
 
-## Versioning
+This document is organised on the [Diátaxis](https://diataxis.fr) axes.
+**Tutorial** and **How-to** are practical; **Reference** and **Explanation** are
+theoretical. If you are a coding agent working against this package, read the
+exported types for signatures — they are the specification — and use
+[Reference](#reference) for the contracts those types cannot express,
+[Usage scenarios](#usage-scenarios) for porting shapes, and
+[Rules for automated contributors](#rules-for-automated-contributors) for the
+constraints that will fail CI if you break them.
 
-**Versioning is not semver.** Each published release increments the major and
-resets the rest — `1.0.0`, `2.0.0`, `3.0.0` — so the major is a release
-counter, not a compatibility signal, and a bump does not by itself mean the
-surface changed. Pin an exact version and read the changes between releases
-until this stabilizes.
-
-## What's here today: provider routing
-
-Expand one canonical model selection (OpenRouter-style `vendor/model-slug`
-ids) into an ordered, immutable, secret-free **route plan** across providers,
-then drive attempts over it with a normative failure policy:
-
-- **`ProviderPolicy`** — ordered provider preference per model, or a hard
-  `only` fence that pins a model to a single provider (useful for evals and
-  compliance).
-- **`buildRoutePlan`** — deterministic planner: policy order is the only
-  ordering input; capability mismatches and configuration gaps become
-  recorded skips, never network attempts.
-- **`executeRoutePlan`** — the attempt loop: model stage → provider candidate
-  → bounded same-endpoint retries, with an exhaustive failure-disposition
-  matrix (`failureDisposition`) deciding retry / next-provider /
-  fallback-model / propagate.
-- **Circuit breaker** — per `(provider, invocation model, credential source)`
-  endpoint, with half-open probes, bounded Retry-After cooldowns, and an
-  injectable clock.
-
-Transports (the actual HTTP clients), credentials, pricing policy, and
-persistence stay with the host application — the harness never reads the
-environment, never touches a filesystem, and holds no secrets, which is what
-keeps it portable across Bun, Node, and edge runtimes such as Cloudflare
-workerd.
+| I want to… | Go to |
+|---|---|
+| Understand what this is and whether I need it | [Explanation](#explanation) |
+| Get something running end to end | [Tutorial](#tutorial-route-one-completion) |
+| Solve one specific problem | [How-to guides](#how-to-guides) |
+| Know which entry point to use, and what holds between calls | [Reference](#reference) |
+| Know how versions work before installing | [Versioning](#versioning) |
+| Port an existing agent runtime onto this | [Usage scenarios](#usage-scenarios) |
+| Know what is deliberately not here yet | [Roadmap](#roadmap) |
+| Change this package safely | [Rules for automated contributors](#rules-for-automated-contributors) |
+
+---
+
+## Explanation
+
+*Understanding-oriented. Read this to know why the package is shaped the way it
+is; you do not need it to use the package.*
+
+### What a harness is, and what it is not
+
+A harness owns the parts of an agent loop that are the same for everyone: the
+iteration itself — call the model, run what it asked for, repeat — plus
+deciding which provider to call and what to do when it fails, bounding a run in
+wall-clock time, keeping a transcript in a shape providers accept, rewriting
+tool schemas that strict validators reject, and tracking which tools are
+currently loaded.
+
+A *runtime* owns the parts that are yours: identity, authorization, persistence,
+transports, prompt voice, and product behaviour. `bind` deliberately contains
+none of that. It never reads the environment, never touches a filesystem, and
+holds no secrets — which is what lets the same code run on Bun, Node, and edge
+runtimes such as Cloudflare workerd.
+
+### The fences, and why they exist
+
+Four constraints, enforced by lint:
+
+- **No `@/*` application imports.** Anything the harness needs from the host
+  arrives through an injected function or value — a port — never a direct
+  import.
+- **No Node builtins, no `process`.** No filesystem, no environment reads.
+  Configuration is explicit input. Clocks are injectable, with a `Date.now`
+  default as the one sanctioned exception.
+- **No framework imports.**
+- **Peer dependencies only** (`zod`, plus `openai` as an optional *type-only*
+  peer). The host supplies the instances, so schemas never split across
+  duplicate copies — a failure that stays invisible until two zod instances
+  disagree about the same schema at runtime.
+
+The fences are not stylistic. They are the reason a Cloudflare Worker and a
+long-lived Node server can share this code unmodified.
+
+### Why the plugin types are generic
+
+`ToolPlugin` is generic over the invocation context (`TCtx`) rather than
+shipping a concrete one. Almost nothing in a real tool context is common: the
+abort signal is, and the rest is the host's own identity model, its
+authorization, and its product features. Two applications comparing notes here
+will typically find they share one field. A concrete context would therefore be
+either a lowest-common-denominator or the union of several products' identity
+models — so the context is a type parameter you supply, and you add your own
+plugin fields by ordinary interface extension.
+
+`ToolResult` is separately generic over the content-part type for a smaller
+reason: the wire shape is the provider's, but turning bytes into a multimodal
+part needs runtime-specific APIs that differ between Node and the edge. The
+harness carries parts through without interpreting them, which keeps those APIs
+— and the dependencies they imply — out of a package that must run on workerd.
+
+### Why the registry is a factory
+
+`createToolRegistry` returns an instance rather than exposing a module-level
+map. Module state is per-isolate on edge runtimes and its lifetime is not the
+host's; it also makes tests share state implicitly. A host that wants singleton
+ergonomics wraps one instance in a module — the choice belongs to the host.
+
+### Why a restored activation set is a hint
+
+Progressive tool disclosure persists plugin **names**; implementations resolve
+at load time. Between two runs a plugin can be renamed, gated off, or (if it is
+dynamically connected) fail to reconnect. `rehydrateActivation` therefore
+re-validates every persisted entry against current reality and **drops** what no
+longer resolves, returning the drops with a reason rather than failing the run.
+Reporting a plugin as active when its tools cannot be called is worse than
+losing it.
+
+### What stays with your application
+
+Transports' request construction and wire-error classification, credentials and
+environment parsing, your routing policy configuration, billing accounting
+(persistence and charging), inference logging, authorization, prompt rendering,
+and run orchestration — the queue a run is scheduled on, and the enqueuing and
+storage behind any child runs it spawns. The harness decides whether a child is
+*allowed*; putting it on a queue is yours (see
+[Spawning child runs](#spawning-child-runs-sub-agents)).
+
+The loop is here, but the **driver** around it is not: starting a run, recording
+what it did, delivering its output, and deciding when to run it again. That is
+where a runtime's identity, storage, and product behaviour live, and it is why
+`runToolLoop` takes a dozen observers instead of doing any of it.
+
+---
+
+## Tutorial: route one completion
+
+*Learning-oriented. Follow these steps in order on a scratch file; the goal is a
+working mental model, not production code.*
+
+You will plan a route across two providers, execute it against a fake
+transport, and watch the failure policy fall over to the second provider.
+
+**1. Install.** `zod` is a peer dependency — bring your own v4 instance. Add
+`openai` too if you use `/run`, `/transcript`, `/contracts`, or the package
+root: they reference its message types (type-only, erased at runtime).
+
+```sh
+bun add @juno-ai/bind zod openai
+```
+
+**2. Describe your providers.** A `PlannerTransport` answers two questions:
+are you available, and can you serve this model? It returns a candidate, a
+recorded skip, or `unserved`.
 
 ```ts
 import {
-  buildRoutePlan,
-  executeRoutePlan,
-  createCircuitBreaker,
   canonicalModelIdSchema,
+  providerIdSchema,
+  type PlannerTransport,
 } from "@juno-ai/bind/routing";
 
+const model = canonicalModelIdSchema.parse("openai/gpt-example");
+const primaryId = providerIdSchema.parse("primary");
+const backupId = providerIdSchema.parse("backup");
+
+function fakeTransport(id: typeof primaryId): PlannerTransport {
+  return {
+    id,
+    getAvailability: () => ({ available: true }),
+    resolveCandidate: () => ({
+      kind: "candidate",
+      candidate: {
+        providerId: id,
+        canonicalModelId: model,
+        providerInvocationModel: "gpt-example",
+        credentialSource: "platform",
+        creditEligible: true,
+        capabilities: new Set(["chat_completions"]),
+        maxCompletionTokens: null,
+        pricingBasis: { kind: "provider_reported" },
+        bindingFingerprint: `${id}:gpt-example`,
+      },
+    }),
+  };
+}
+```
+
+**3. Build the plan.** Policy order is the only ordering input. The result is
+frozen, secret-free, and safe to log or snapshot in a test.
+
+```ts
+import { buildRoutePlan } from "@juno-ai/bind/routing";
+
 const { plan, skips } = buildRoutePlan({
-  primaryModel: canonicalModelIdSchema.parse("openai/gpt-example"),
+  primaryModel: model,
   fallbackModel: null,
-  requirements: { capabilities: new Set(["chat_completions", "streaming"]), requestedMaxCompletionTokens: null },
-  policyFor: (model) => resolveMyPolicy(model),
-  transports: myTransportMap, // availability + endpoint resolution per provider
+  requirements: {
+    capabilities: new Set(["chat_completions"]),
+    requestedMaxCompletionTokens: null,
+  },
+  policyFor: () => ({ mode: "ordered", providers: [primaryId, backupId] }),
+  transports: new Map([
+    [primaryId, fakeTransport(primaryId)],
+    [backupId, fakeTransport(backupId)],
+  ]),
 });
 
+console.log(plan.stages[0].candidates.map((c) => c.providerId)); // primary, backup
+console.log(skips); // [] — nothing was filtered out
+```
+
+**4. Execute it.** Your `attempt` function performs the real call and
+classifies any failure into facts. It never decides route order — that is the
+executor's job.
+
+```ts
+import { executeRoutePlan, createCircuitBreaker } from "@juno-ai/bind/routing";
+
 const result = await executeRoutePlan({
   plan,
   breaker: createCircuitBreaker(),
-  attempt: async (candidate, cursor) => myTransportAttempt(candidate, cursor),
+  attempt: async (candidate, cursor) => {
+    if (candidate.providerId === primaryId) {
+      return {
+        kind: "failure",
+        error: {
+          kind: "http",
+          category: "server_error",
+          statusCode: 503,
+          retryAfterMs: null,
+          target: {
+            cursor,
+            providerId: candidate.providerId,
+            canonicalModelId: candidate.canonicalModelId,
+            providerInvocationModel: candidate.providerInvocationModel,
+            durationMs: 12,
+          },
+          cause: new Error("upstream unavailable"),
+        },
+      };
+    }
+    return { kind: "success", value: "hello from backup" };
+  },
 });
+
+if (result.ok) {
+  console.log(result.value);           // "hello from backup"
+  console.log(result.served.providerId); // backup
+  console.log(result.fallbackKind);      // "provider"
+}
 ```
 
-## Design rules
+**What you just saw.** A 503 classifies as a retriable transport failure, so the
+disposition table allows traversal to the next provider and records a breaker
+failure against the first endpoint. You did not write that logic, and you cannot
+accidentally reorder it from inside a transport.
+
+**5. Next.** Add a wall-clock budget with
+[`createRunDeadline`](#how-to-bound-a-run-in-wall-clock-time), or add
+progressive tool disclosure with
+[`createToolRegistry`](#how-to-add-progressive-tool-disclosure).
+
+---
+
+## How-to guides
+
+*Goal-oriented. Each answers one question and assumes you know roughly what you
+are doing.*
+
+### How to run the loop
+
+`runToolLoop` is the engine: it calls the model, runs the tools the model asks
+for, and repeats until the model stops asking, a tool suspends the run, a caller
+stops it, or `maxIterations` is reached. Everything that *happens* as a result is
+a callback you supply.
+
+```ts
+import { runToolLoop, type ToolLoopState } from "@juno-ai/bind/loop";
+
+const state: ToolLoopState = {
+  messages: [systemMessage, userMessage],
+  inputTokens: 0,
+  outputTokens: 0,
+  costCents: 0,
+  lastPromptTokens: 0,
+  lastOutputTokens: 0,
+  hasFreshTokenCount: false,
+  toolCalls: 0,
+};
+
+await runToolLoop({
+  state,
+  activePlugins,
+  maxIterations: 30,
+
+  callModel: (messages, tools) => llm.complete({ messages, tools }),
+  buildTools: () => registry.toolDefinitions([...activePlugins]),
+  runToolCall: (call) => dispatch(call),
+  activatePlugins: (names) => names.forEach((n) => activePlugins.add(n)),
+  activateSkills: (refs) => loadInstructions(refs),
+});
+
+// `state` is mutated in place — read totals off it after, or mid-run from a
+// heartbeat.
+console.log(state.inputTokens, state.outputTokens, state.toolCalls);
+```
+
+`state` is mutated rather than returned so a heartbeat can read live totals while
+the run is still going; a returned result could not report anything until the
+run ended.
+
+### How to make a tool take effect mid-batch
+
+A model can request several tools at once, and one of them may change what the
+others can do — activating a plugin, loading an instruction module. Those must
+run first, alone, or a dependent call in the same batch executes against the old
+tool surface.
+
+```ts
+runsSerially: (call) =>
+  call.type === "function" && ACTIVATION_TOOLS.has(call.function.name),
+```
+
+The loop runs those one at a time, applies each outcome immediately, then fans
+the rest out concurrently (pooled per tool name). Outcomes are reassembled in the
+model's original order either way — every `tool_call_id` gets its answer in the
+sequence the provider expects.
+
+Unwired, nothing is serial. That is correct for a host whose tools do not reshape
+the tool surface, and wrong the moment one does.
+
+### How to decide which tool failures kill the run
+
+By default a thrown tool becomes a tool error the model can read and recover
+from, which is what you want for an isolated failure. Two kinds are not that:
+
+```ts
+isFatalToolError: (error) =>
+  error instanceof RunCancelledError ||   // must abort, not be answered
+  error instanceof PersistenceError,      // we could not RECORD the outcome
+```
+
+Cancellation has to propagate even when no `ensureNotCancelled` observer is
+wired. A persistence failure matters for a subtler reason: synthesizing "the tool
+failed" over a write you could not record tells the model a lie about work that
+may well have happened.
+
+Everything not fatal is answered and observed:
+
+```ts
+onToolCallRejected: (toolCallId, error) => log.warn("tool rejected", { toolCallId, error }),
+```
+
+Wire it. The model sees these failures either way; without the observer, nothing
+else does.
+
+### How to pin a model to one provider
+
+Use a hard `only` fence. Plan-time filtering and runtime traversal both respect
+it — a pinned provider that fails at request time is never retried elsewhere.
+
+```ts
+policyFor: () => ({ mode: "only", provider: complianceProviderId });
+```
+
+Useful for evals (reproducible plans) and for compliance routing.
+
+### How to bound a run in wall-clock time
+
+Create the deadline where you classify the outcome, and dispose it in a
+`finally`.
+
+```ts
+import { createRunDeadline, classifyRunFailure } from "@juno-ai/bind/run";
+
+const deadline = createRunDeadline({ timeoutMs: 60 * 60 * 1000, label: "agent run" });
+try {
+  for (;;) {
+    deadline.throwIfTimedOut();
+    await callModel({ signal: deadline.withExternal(cancellationSignal) });
+  }
+} catch (error) {
+  const status = classifyRunFailure(deadline, error); // "timed_out" | "failed"
+} finally {
+  deadline.dispose();
+}
+```
+
+**Ownership rule:** whoever needs to read `deadline.timedOut` must create and
+own the deadline. A loop handed one must not dispose it; a loop given none
+should mint its own, so a turn is never unbounded. Handle caller-driven
+cancellation *before* calling `classifyRunFailure` — a cancellation is not a
+timeout, and `timedOut` stays false when only a combined external signal fires.
+
+### How to stop a run's progress writes from stampeding
+
+```ts
+import { createCoalescedHeartbeat } from "@juno-ai/bind/run";
+
+const heartbeat = createCoalescedHeartbeat({
+  coalesceMs: 10_000,
+  flush: () => db.bumpRunRow(runId),
+  onError: (error) => log.warn("heartbeat flush failed", { error }),
+});
+
+await heartbeat.beat();                 // coalesced
+await heartbeat.beat({ force: true });  // always flushes, resolves after the write
+```
+
+Flush errors go to `onError` and are swallowed, so a transient database hiccup
+never aborts a run. Flushes drain one at a time, so two overlapping writes can
+never land out of order.
+
+### How to keep a provider from rejecting your whole tool list
+
+Strict validators reject the **entire** request — every tool — on the first
+schema violation. Run each tool's JSON Schema through the sanitizer before it
+reaches the model.
+
+```ts
+import { sanitizeToolSchema } from "@juno-ai/bind/tools";
+
+const wireTools = tools.map((tool) => ({
+  type: "function",
+  function: {
+    name: tool.name,
+    description: tool.description,
+    parameters: sanitizeToolSchema(tool.inputSchema),
+  },
+}));
+```
+
+Every transform is correctness-preserving and was bisected against live
+inference. It fixes, among others: a `type` array where a provider requires a
+scalar; `enum` on a non-string type; `required` entries with no matching
+property; a boolean `additionalProperties: false` on a nested object; and a
+parameter literally named `properties`. Run it on third-party (e.g. MCP) tool
+schemas too — those are where the violations usually come from.
+
+### How to repair a transcript before sending it
+
+```ts
+import { validateAndHealMessages } from "@juno-ai/bind/transcript";
+
+const { messages, issues } = validateAndHealMessages(transcript);
+if (issues.length > 0) log.warn("healed transcript", { issues });
+```
+
+Detects and repairs orphan tool results, dangling unanswered tool calls, empty
+assistant messages mid-conversation, and a trailing assistant turn — which is
+prefill on one provider's native API and a hard rejection through another.
+
+### How to add progressive tool disclosure
+
+Model tool-selection accuracy degrades past a few dozen tools, and every tool's
+schema is resent on every turn. Load a small core set, announce the rest as a
+catalog, and activate on demand.
+
+```ts
+import {
+  createToolRegistry,
+  initialActivePlugins,
+  partitionPluginCatalog,
+} from "@juno-ai/bind/plugins";
+
+const registry = createToolRegistry<MyPlugin>({
+  corePlugins: ["messaging", "memory"],
+  aliases: { "old-name": "new-name" },
+  onRegister: (plugin) => indexPluginSkills(plugin),
+});
+
+registry.register(myPlugin);
+
+const active = new Set(initialActivePlugins(registry.corePlugins()));
+const { active: shown, loadable } = partitionPluginCatalog(active, registry.summaries());
+```
+
+`aliases` are permanent: persisted activation state stores names, so an alias is
+how a rename avoids silently stripping capabilities from live sessions without a
+data migration.
+
+`partitionPluginCatalog` returns **data, not prose** — catalog wording is your
+system prompt's business, and re-rendering it byte-identically for unchanged
+inputs is what preserves a provider's prompt-cache prefix.
+
+### How to restore a persisted activation set
+
+```ts
+import { rehydrateActivation } from "@juno-ai/bind/plugins";
+
+const { active, dropped } = await rehydrateActivation(persistedNames, {
+  canonicalizeName: (name) => registry.canonicalizeName(name),
+  resolve: async (name) => {
+    if (isGatedOffThisRun(name)) return "unavailable";
+    if (!isDynamic(name)) return registry.get(name) ? true : "unknown";
+    return (await connect(name)) ? true : "unreachable";
+  },
+});
+
+for (const drop of dropped) log.warn("activation dropped", drop);
+```
+
+The walk canonicalizes, de-duplicates (two legacy names collapsing to one plugin
+resolve **once**, so a reconnect is not paid twice), and drops rather than
+throws. `resolve` is async precisely so a reconnect can happen inside it.
+
+### How to scope the circuit breaker per tenant
+
+Pass a non-secret `credentialScope`. Without it, one tenant's revoked
+bring-your-own key opens the circuit for every tenant sharing the same
+`credentialSource`.
+
+```ts
+breaker.recordFailure({
+  providerId,
+  invocationModel,
+  credentialSource: "tenant",
+  credentialScope: tenantTag, // opaque, non-secret — it lands in state keys
+});
+```
+
+If a half-open probe ends without a recordable outcome (an abort, a propagated
+client error), call `releaseProbe` so the slot cannot stick.
+
+---
+
+## Reference
+
+*Information-oriented. The exported types are the specification — read them in
+your editor. This section covers what the types cannot say: which entry point
+to reach for, and the contracts that hold between calls.*
+
+Every export is re-exported from the package root, but prefer the subpath — it
+keeps a consumer who only wants routing from pulling in the rest.
+
+| Import | Owns | Reach for it when |
+|---|---|---|
+| `@juno-ai/bind/routing` | Route plans, the planner, the failure taxonomy, the plan executor, the circuit breaker, billing-basis arithmetic, config degradation | You call more than one provider or model, or you want retries and fallback governed by one table |
+| `@juno-ai/bind/contracts` | Turn vocabulary — `TurnFn`, `ModelTurnResult`, `StopReason`, `RunStats` and its folds | You want one seam between your loop and any LLM client, and comparable per-run metrics |
+| `@juno-ai/bind/loop` | `runToolLoop` — the iteration engine: model turn, two-phase tool batch, activation, compaction, interrupts, suspend | You want the agent loop itself, not just the pieces to build one |
+| `@juno-ai/bind/run` | Wall-clock deadline, failure classification, coalesced heartbeat, tool-batch pooling, child-run lineage and admission, poll backoff | A run must be bounded, observable, and able to say *why* it stopped — or it can spawn runs of its own |
+| `@juno-ai/bind/transcript` | `validateAndHealMessages` | You send transcripts to more than one provider, or you build them across turns |
+| `@juno-ai/bind/tools` | `sanitizeToolSchema` | Any tool schema reaches a provider — especially third-party ones |
+| `@juno-ai/bind/plugins` | Tool/plugin vocabulary, the registry factory, progressive-disclosure activation | You have more tools than fit comfortably in one prompt |
+
+### Contracts the types do not carry
+
+**Routing — attempt order is fixed.** Structured-output attempt → model stage →
+provider candidate → same-endpoint retry. Nothing else reorders it: not
+transport registration order, not map iteration, not the clock.
+
+**Routing — transports classify, they never decide.** An `AttemptFn` reports a
+fact (`aborted` / `completion_defect` / `network` / `http` + category);
+`failureDisposition` alone decides retry, next-provider, fallback-model, or
+propagate. Putting routing logic in a transport is the one way to break the
+guarantee that identical inputs produce identical plans.
+
+**Routing — a healthy endpoint must not be punished for a bad request.**
+Request-shaped rejections (a 400, a moderation refusal) traverse to another
+provider but record **no** breaker failure. Otherwise one caller's malformed or
+flagged prompt degrades a shared endpoint for everyone.
+
+**Routing — a fallback model equal to the primary is ignored**, so you can pass
+a configured fallback through unconditionally without producing a duplicate
+stage.
+
+**Routing — breaker keys must stay secret-free.** `credentialScope` lands in
+state keys; pass an opaque tag, never key material. Omitting it means one
+tenant's revoked key opens the circuit for every tenant sharing that
+`credentialSource`. Defaults: open after 3 consecutive failures, 60 s cooldown,
+60 s ceiling including `Retry-After` extensions. Resolve a half-open probe that
+ended without a recordable outcome via `releaseProbe`, or the slot sticks.
+
+**Run — a child is admitted before it exists, never after.** `admitChildRun`
+judges counts you supply; call it ahead of enqueuing. A chain bounded only once
+its runs are on the queue is not bounded, it is billed. A rule whose measurement
+is `NaN` or `Infinity` refuses rather than admits — every comparison is false
+against `NaN`, so the naive reading of a broken count is an unbounded chain.
 
-- **Pure by construction.** No `process`, no Node builtins, no framework
-  imports, no I/O except through injected functions. Enforced by lint in the
-  source-of-truth repository.
-- **Deterministic.** Identical inputs produce identical plans; nothing about
-  registration order, map iteration, or wall-clock time reorders candidates.
-- **Explicit failure policy.** Every classified failure maps through one
-  exhaustive disposition table; transports classify facts, they never decide
-  route order.
-- **zod is a peer dependency** — bring your own instance (v4+).
+**Run — chain lineage is "null means me".** A root run's `rootRunId` and
+`parentRunId` are both `null`, because a chain's origin has no id to point at
+until its own row exists. Read any chain's root as `chain.rootRunId ?? runId`;
+`descendChain` does that when it hands the id down, so every descendant carries
+a concrete root. Adopting the parent's id at *every* level instead makes each
+generation a fresh chain, and every per-chain bound then counts the wrong set
+and silently never fires.
+
+**Run — whoever classifies the outcome owns the deadline.** `timedOut` reflects
+*that* deadline firing, and stays false when only a combined external signal
+aborts — which is what separates a timeout from a cancellation. Handle
+cancellation before calling `classifyRunFailure`. A loop handed a deadline must
+not dispose it; a loop given none should mint its own, so a turn is never
+unbounded.
+
+**Run — pooling preserves input order and answers everything.**
+`runToolCallsPooledByTool` caps concurrent calls to the *same* tool at 5 while
+different tools fan out fully, and returns `PromiseSettledResult`s in input
+order. A rejection still needs a synthesized error tool message, or the next
+request carries an unanswered `tool_call_id`.
+
+**Routing — a policy that names a provider you have not configured degrades,
+it does not fail.** `buildRoutePlanWithConfigDegradation` drops such a stage at
+*plan time* and records why, so a missing key costs you that provider rather
+than making the model unavailable. Runtime failures keep the fence: a configured
+`only` provider that errors at request time is still never retried elsewhere.
+
+**Run — heartbeat flushes drain one at a time**, so two overlapping writes
+cannot land out of order. Flush errors go to `onError` and are swallowed; a
+transient storage failure never aborts a run.
+
+**Contracts — model time and tool time stay separate.** Task wall-clock
+conflates provider inference speed with tool execution. `RunStats` reports both,
+plus a per-tool breakdown; field shapes follow the [StirrupJS](https://github.com/stirrupjs/stirrup)
+`speedStats` methodology, so numbers stay comparable with published benchmarks
+and a slow tool never reads as a slow model.
+
+**Transcript — the second argument is an assertion, not a silence.** Ids passed
+as `allowedOpenToolCallIds` are *legitimately* open (a suspended call awaiting a
+human answer). Because this is the universal heal site and a correct transcript
+never reaches it with a suspended call unpaired, an allowed id arriving unpaired
+means resume failed — and it fails loudly rather than being quietly kept.
+
+**Tools — sanitize third-party schemas too.** Strict validators reject the
+*entire* request, every tool, on the first violation, and third-party schemas
+are where violations usually originate. Every transform is
+correctness-preserving and was bisected against live inference.
+
+**Plugins — `rawJsonSchema` overrides, it does not replace.** `parameters` is
+always required; a host authoring tools as raw JSON Schema supplies a
+placeholder there and puts the real schema on `rawJsonSchema`, which is what
+reaches the model.
+
+**Plugins — availability is evaluated per call.** `get()` returns `undefined`
+for an unavailable plugin while `all()` still includes it, so a plugin can stay
+registered for configuration purposes while being gated off for a run. A
+connection going unhealthy mid-process takes its tools out of the catalog with
+no re-registration.
+
+**Plugins — aliases are permanent.** Activation state persists *names*, so an
+alias is how a rename avoids stripping capabilities from live sessions without a
+data migration. Removing one silently downgrades every session that still stores
+the old name.
+
+**Plugins — `hidden: true` keeps a tool callable but unadvertised**, for resumed
+sessions whose history references a tool you have retired from the prompt.
+
+**Plugins — rehydration drops, it never throws.** `resolve` returns `true` to
+keep or a drop reason to discard, and may be async so a reconnect can happen
+inside it. The walk canonicalizes and de-duplicates first, so two legacy names
+collapsing to one plugin resolve once — a reconnect is not paid twice.
+
+**Plugins — catalog partitioning returns data, not prose.** Wording belongs to
+your system prompt, where re-rendering byte-identically for unchanged inputs is
+what preserves a provider's prompt-cache prefix.
+
+### Suspend semantics
+
+A first-party tool returns a `SuspendDirective` on a **successful** result to end
+the run with its call recorded as awaiting resolution. The resume kind decides
+what happens to the tool message:
+
+- `"answer"` — the reply becomes this call's `role:"tool"` result, so the loop
+  **withholds** the message. At most one may be open per run.
+- `"wake"` — a time or event resume that re-enters via a prompt and **keeps** the
+  message.
+
+`request` is an opaque render/route payload, validated by the consumer and never
+inspected by the loop.
+
+---
+
+## Usage scenarios
+
+*Sketches, not runnable files — they name types loosely and omit imports. Each
+shows the shape of one migration an existing agent runtime typically has to
+make. Read the [Reference](#reference) for exact signatures.*
+
+### Tools authored as raw JSON Schema, not zod
+
+`ToolDef.parameters` is a zod schema, but a host whose tools are already JSON
+Schema does not need to rewrite them — set `rawJsonSchema` and it is used
+verbatim. Keep `parameters` as a permissive placeholder if you validate
+elsewhere.
+
+```ts
+const toolDef: ToolDef = {
+  name: "search",
+  description: "Search one page of results.",
+  parameters: z.unknown(),           // unused when rawJsonSchema is present
+  rawJsonSchema: existingJsonSchema,  // your hand-written schema, as-is
+  annotations: { readOnlyHint: true },
+};
+
+// Sanitize on the way to the model, regardless of which form it came from.
+const wire = {
+  type: "function",
+  function: {
+    name: toolDef.name,
+    description: toolDef.description,
+    parameters: sanitizeToolSchema(toolDef.rawJsonSchema ?? z.toJSONSchema(toolDef.parameters)),
+  },
+};
+```
+
+### One plugin per integration
+
+A natural plugin boundary is the external system a group of tools talks to.
+
+`isAvailable` gates *whether the deployment has this integration at all* — a
+build flag, a missing binding, an edition that does not ship it. It must return
+the same answer for the whole life of the process: the catalog is re-rendered
+several times per run, and a value that flips mid-run changes the system prompt
+between turns, which costs the prompt-cache prefix and can strand a tool call
+the model already issued.
+
+Health that changes at runtime belongs at *invocation* instead. Let the call
+fail, and return the reason:
+
+```ts
+function integrationPlugin(adapter: Adapter, conn: Connection): ToolPlugin<Ctx> {
+  return {
+    name: adapter.id,                       // "calendar", "issues", "docs", …
+    description: adapter.catalogLine,       // one line; it lands in the prompt catalog
+    isAvailable: () => adapter.installed,   // constant for this process
+    tools: adapter.tools.filter((t) => conn.grants.has(t.capability)),
+    execute: async (toolName, args, ctx) => {
+      if (conn.status !== "healthy") {
+        // The model can retry, or route around it — a dropped catalog entry
+        // tells it nothing.
+        return { content: `${adapter.id} is unreachable right now.`, isError: true };
+      }
+      return adapter.invoke(toolName, args, ctx);
+    },
+  };
+}
+
+for (const conn of connections) {
+  registry.register(integrationPlugin(adapterFor(conn), conn));
+}
+```
+
+For a plugin whose *connection* is established per run rather than per process,
+restoring a persisted activation is where the reconnect belongs — see
+[How to restore a persisted activation set](#how-to-restore-a-persisted-activation-set).
+
+Splitting one large integration into several plugins (`mail`, `calendar`,
+`files`) is usually worth it: the unit of activation should match the unit of
+intent, and a 20-tool plugin is a large thing to load for one call.
+
+### A per-request registry on an edge runtime
+
+Module-level state is per-isolate and outlives a single request unpredictably.
+Build the registry inside the request instead — the factory is cheap.
+
+```ts
+export default {
+  async fetch(request: Request, env: Env) {
+    const registry = createToolRegistry<MyPlugin>({
+      corePlugins: ["core", "discovery"],
+    });
+    for (const plugin of await loadPluginsFor(env, request)) {
+      registry.register(plugin);
+    }
+    return handle(request, registry);
+  },
+};
+```
+
+### A single-provider transport
+
+You do not need multiple providers to benefit from the plan/execute split — one
+transport still gets you the failure taxonomy, the retry budget, and the
+breaker.
+
+```ts
+const transport: PlannerTransport = {
+  id: providerIdSchema.parse("openrouter"),
+  getAvailability: () =>
+    env.API_KEY ? { available: true } : { available: false, reason: "no key" },
+  resolveCandidate: (model, requirements) => {
+    if (!supports(model, requirements.capabilities)) {
+      return { kind: "skip", skip: { canonicalModelId: model, providerId: id, reason: "capability_mismatch" } };
+    }
+    return { kind: "candidate", candidate: candidateFor(model) };
+  },
+};
+```
+
+### Replacing a hand-rolled retry/fallback loop
+
+A typical hand-rolled loop is `for (model) for (attempt)` with an ad-hoc
+`retry | fallback | terminal` decision. Move the decision to the taxonomy: your
+transport reports **facts**, the executor decides order.
+
+```ts
+// Before: the transport decided what to do next.
+//   if (status === 429 || status >= 500) retry();
+//   else if (status === 401) throw;
+//   else tryNextModel();
+
+// After: the transport only classifies.
+const attempt: AttemptFn<Completion> = async (candidate, cursor) => {
+  const startedAt = performance.now();
+  try {
+    return { kind: "success", value: await callProvider(candidate) };
+  } catch (cause) {
+    const target = {
+      cursor,
+      providerId: candidate.providerId,
+      canonicalModelId: candidate.canonicalModelId,
+      providerInvocationModel: candidate.providerInvocationModel,
+      durationMs: Math.round(performance.now() - startedAt),
+    };
+    if (isAbort(cause)) return { kind: "failure", error: { kind: "aborted", target, cause } };
+    if (!cause.status) return { kind: "failure", error: { kind: "network", target, cause } };
+    return {
+      kind: "failure",
+      error: {
+        kind: "http",
+        category: categorizeHttpStatus(cause.status),
+        statusCode: cause.status,
+        retryAfterMs: parseRetryAfter(cause),
+        target,
+        cause,
+      },
+    };
+  }
+};
+```
+
+Two behaviours you get for free and probably did not have: a request-shaped
+rejection (a 400, a moderation refusal) traverses to another provider **without**
+opening the breaker, and an empty or truncated completion is retried on the same
+endpoint before any fallback.
+
+### Adapting a non-SDK client to `TurnFn`
+
+`TurnFn` is the seam between a loop and any client. If you hand-roll SSE, adapt
+at this boundary and the rest of the harness does not care.
+
+```ts
+const turn: TurnFn = async (messages, tools, signal) => {
+  const startedAt = performance.now();
+  let ttftMs: number | null = null;
+
+  const { message, usage } = await streamCompletion({
+    messages, tools, signal,
+    onFirstToken: () => { ttftMs ??= Math.round(performance.now() - startedAt); },
+  });
+
+  return {
+    message,
+    usage: {
+      inputTokens: usage.prompt_tokens ?? 0,
+      outputTokens: usage.completion_tokens ?? 0,
+      cachedInputTokens: usage.cached_tokens ?? null,
+      costCents: usage.cost != null ? usage.cost * 100 : null,
+    },
+    timings: { ttftMs, generationMs: Math.round(performance.now() - startedAt) },
+  };
+};
+```
+
+### Accumulating run statistics
+
+Fold each turn and each tool call as they complete; `RunStats` keeps model time
+and tool time separate so a slow tool never looks like a slow model.
+
+```ts
+let stats = emptyRunStats();
+
+for (const turn of turns) {
+  const result = await turnFn(messages, tools, signal);
+  stats = accumulateTurn(stats, result);
+
+  for (const call of result.message.tool_calls ?? []) {
+    const startedAt = performance.now();
+    await dispatch(call);
+    stats = accumulateToolCall(stats, call.function.name, performance.now() - startedAt);
+  }
+}
+
+await persistRun({ ...stats, stopReason: "done" satisfies StopReason });
+```
+
+### Batching a turn's tool calls
+
+Reads can overlap; writes usually should not. Pool the reads and keep the
+transcript in the model's original call order.
+
+```ts
+const reads  = calls.filter((c) => isReadOnly(c));
+const writes = calls.filter((c) => !isReadOnly(c));
+
+const readResults = await runToolCallsPooledByTool(reads, (call) => dispatch(call));
+
+const writeResults: Outcome[] = [];
+for (const call of writes) writeResults.push(await dispatch(call));
+
+// Re-emit in the order the model asked for, so every tool_call_id is answered.
+for (const call of calls) {
+  messages.push(toolMessageFor(call, resultFor(call, readResults, writeResults)));
+}
+```
+
+`runToolCallsPooledByTool` returns `PromiseSettledResult`s — a rejection still
+needs a synthesized error tool message, or the next request has an unanswered
+call.
+
+### Pausing a run for human input
+
+A tool that needs an answer returns a `suspend` directive on a **successful**
+result. Pick the resume kind by whether the answer becomes the tool's result.
+
+```ts
+// The run resumes later via a prompt; the tool message is kept.
+return {
+  success: true,
+  data: { askedAt: nowIso },
+  suspend: { reason: "awaiting user selection", resumeKind: "wake", request: formSpec },
+};
+
+// The human's reply IS this call's tool result; the loop withholds the message.
+return {
+  success: true,
+  data: null,
+  suspend: { reason: "awaiting answer", resumeKind: "answer", request: formSpec },
+};
+```
+
+If your runtime ends the whole run and starts a fresh one on reply, `wake` is
+the kind you want — `answer` only pays off when you thread the reply back into
+the same transcript as the matching `role:"tool"` message.
+
+### Carrying disclosure across a run boundary
+
+When a run ends and a later one continues the same conversation, persist the
+**names** and re-validate on the way back in.
+
+```ts
+// End of run: names only, never plugin objects.
+await db.saveActivation(conversationId, [...activePlugins]);
+
+// Start of the next run.
+const persisted = await db.loadActivation(conversationId);
+const { active, dropped } = await rehydrateActivation(persisted, {
+  canonicalizeName: (n) => registry.canonicalizeName(n),
+  resolve: async (n) => (registry.get(n) ? true : "unknown"),
+});
+// Seed core, then add what survived — core plugins load unconditionally.
+const activePlugins = new Set([...initialActivePlugins(registry.corePlugins()), ...active]);
+for (const drop of dropped) log.info("plugin not restored", drop);
+```
+
+Without this, every boundary silently resets the agent to core-only and it
+re-discovers from scratch — which costs a round-trip per resumption.
+
+### Assembling a bounded run
+
+The pieces compose; nothing here knows about the others.
+
+```ts
+const deadline = createRunDeadline({ timeoutMs: RUN_BUDGET_MS, label: "run" });
+const heartbeat = createCoalescedHeartbeat({
+  coalesceMs: 10_000,
+  flush: () => db.touchRun(runId),
+});
+let stats = emptyRunStats();
+let stopReason: StopReason = "done";
+
+try {
+  for (let i = 0; i < maxIterations; i++) {
+    deadline.throwIfTimedOut();
+    const { messages: healed } = validateAndHealMessages(transcript);
+    const result = await turnFn(healed, wireTools, deadline.withExternal(cancelSignal));
+    stats = accumulateTurn(stats, result);
+    await heartbeat.beat();
+    if (!result.message.tool_calls?.length) break;
+    if (await runToolBatch(result.message.tool_calls)) { stopReason = "suspended"; break; }
+  }
+} catch (error) {
+  stopReason = classifyRunFailure(deadline, error) === "timed_out" ? "deadline" : "aborted";
+} finally {
+  await heartbeat.beat({ force: true });
+  deadline.dispose();
+}
+```
+
+### Spawning child runs (sub-agents)
+
+A sub-agent is not a special kind of thing. It is **a run that another run
+asked for**, so everything the harness already gives a run applies unchanged:
+its own deadline, its own heartbeat, its own `RunStats`, its own route plan.
+Three things are genuinely new — lineage, admission, and waiting — and
+`@juno-ai/bind/run` owns the decision in each. It owns none of the measuring:
+counting runs in a chain needs your database, and judging whether a count is
+too high does not.
+
+**1. The spawn tool is an ordinary plugin.** Nothing special is needed here —
+the tool vocabulary is already shared.
+
+```ts
+const orchestration: ToolPlugin<Ctx> = {
+  name: "orchestration",
+  description: "Delegate focused work to a child run.",
+  icon: "share",
+  tools: [
+    {
+      name: "spawn",
+      description: "Run one focused objective as a child and return its id.",
+      parameters: spawnArgsSchema, // z.object({ objective: z.string(), plugins: z.array(z.string()) })
+    },
+  ],
+  async execute(toolName, args, ctx) {
+    const { objective, plugins } = spawnArgsSchema.parse(args);
+
+    const admission = admitChildRun([
+      { kind: "depth", parentDepth: ctx.chain.depth, maxDepth: 5 },
+      { kind: "chain_budget", runsInChain: await countRuns(ctx.chain), maxRuns: 50 },
+    ]);
+    if (!admission.admitted) {
+      return { success: false, kind: "validation", error: admission.reason };
+    }
+
+    const childRunId = await queue.enqueueRun({
+      objective,
+      plugins,
+      chain: descendChain(ctx.runId, ctx.chain),
+    });
+    return { success: true, data: { childRunId } };
+  },
+};
+```
+
+**2. Admission is the part worth getting right.** An agent that can spawn can
+spawn agents that spawn. Bound it *before* enqueuing, not after — an unbounded
+chain is a runaway spend, and the failure mode is silent.
+
+Each rule carries its limit **and** the measurement it judges, so a bound you
+configure but never wired a count for is not expressible. That shape exists
+because the alternative fails quietly: a bounds object beside a facts object
+lets a limit sit in config and never fire, and nothing looks wrong.
+
+```ts
+import { admitChildRun, descendChain, type ChainRule } from "@juno-ai/bind/run";
+
+const rules: ChainRule[] = [
+  { kind: "depth", parentDepth: chain.depth, maxDepth: 5 },
+  { kind: "chain_budget", runsInChain: await countRunsInChain(chain), maxRuns: 50 },
+  { kind: "pair_cooldown", msSinceLastSpawn: await msSinceLastSpawn(runId), cooldownMs: 30_000 },
+  { kind: "tenant_ceiling", activeRuns: await countActiveRuns(tenantId), maxActiveRuns: 200 },
+];
+
+const admission = admitChildRun(rules);
+if (!admission.admitted) {
+  log.warn("child run refused", { rule: admission.rule });
+  return { success: false, kind: "validation", error: admission.reason };
+}
+```
+
+Rules are evaluated in order and the first refusal wins, so you choose which
+reason the model sees. Pick the set against your own cost model: depth caps
+runaway recursion, a chain budget caps a chain that stays shallow but keeps
+fanning out, a pair cooldown stops two runs ping-ponging, and a tenant ceiling
+covers what none of the chain rules can — someone starting a thousand
+independent chains. A broken measurement (`NaN`, `Infinity`) refuses rather
+than admits: every comparison is false against `NaN`, so the naive reading
+would turn a broken count into an unbounded chain.
+
+`descendChain` handles the lineage arithmetic, including the root-id fallback
+that is easy to get backwards — a first-generation child adopts its parent's
+*id* as the chain root, later generations keep the root the parent already
+carries. Getting that wrong makes every generation its own chain, and every
+per-chain bound then counts the wrong set and never fires.
+
+**3. Waiting.** Two shapes work. Suspend the parent and let child completion
+wake it, which frees the worker slot:
+
+```ts
+return {
+  success: true,
+  data: { childRunIds },
+  suspend: { reason: "awaiting child runs", resumeKind: "wake", request: { childRunIds } },
+};
+```
+
+…or poll inside the tool, which keeps the parent's transcript intact but holds
+its slot — so budget the poll well under the parent's own deadline.
+`createPollSchedule` is a doubling backoff bounded by that budget; it clamps
+the final delay so a sleep can never overshoot the deadline you promised.
+
+```ts
+import { createPollSchedule } from "@juno-ai/bind/run";
+
+const startedAt = Date.now();
+const poll = createPollSchedule({
+  initialDelayMs: 500,
+  maxDelayMs: 30_000,
+  budgetMs: 10 * 60_000,
+});
+
+while (true) {
+  const children = await loadChildRuns(childRunIds);
+  if (children.every((c) => c.finished)) return { success: true, data: { children } };
+
+  const step = poll.next(Date.now() - startedAt);
+  if (step.kind === "expired") {
+    return { success: true, data: { children, timedOut: true } };
+  }
+  await sleep(step.delayMs, signal);
+}
+```
+
+Elapsed time is an argument rather than something the schedule reads off a
+clock, so a test can drive the whole backoff without waiting for any of it.
+
+**4. Rolling results up.** `accumulateTurn` and `accumulateToolCall` fold a
+run's *own* activity; `accumulateRun` folds one whole run into another, which
+is what a chain's totals are made of.
+
+```ts
+import { accumulateRun, emptyRunStats } from "@juno-ai/bind/contracts";
+
+const chainTotals = childStats.reduce(accumulateRun, parentStats);
+```
+
+The fold is associative, so a chain reduces in whatever order its children
+finish. Two properties are worth expecting rather than debugging: `modelTimeMs`
+will exceed the chain's wall-clock once children run in parallel (the sum is
+what the chain *cost*, not how long it took), and `outputTokensPerSecond` is
+recomputed from the merged totals rather than averaged across runs — averaging
+two rates weights a 10-token run like a 10,000-token one.
+
+---
+
+## Roadmap
+
+Named, not scheduled. Listed so a consumer can tell a deliberate omission from
+an oversight.
+
+- **One `RunStats` per turn.** The loop accounts usage with `ToolLoopTurn`
+  (tokens and cost) while `ModelTurnResult` carries timings too. They converge
+  when the loop folds `RunStats` directly; today a host that wants throughput
+  metrics accumulates them alongside.
+- **A streaming turn contract.** `callModel` reports an output-token estimate
+  mid-stream; the assistant message itself still arrives whole.
+
+---
+
+## Rules for automated contributors
+
+*Invariants of this package. Read this before changing anything under `src/`;
+each is enforced by lint, typecheck, or CI where it is developed.*
+
+1. **Never import `@/*`, a Node builtin, `process`, or a framework.** Take a
+   port instead. An ESLint block scoped to `packages/bind/**` enforces this.
+2. **Never add a runtime dependency.** New third-party code must be a peer
+   dependency, and only with a strong reason. `openai` is type-only.
+3. **Keep every module I/O-free.** If a change needs a clock, a random source,
+   the environment, or a network call, take it as an explicit input. A
+   `Date.now` default on an injectable clock is the only sanctioned exception.
+4. **Stay deterministic.** Identical inputs must produce identical plans.
+   Nothing about registration order, map iteration, or wall-clock time may
+   reorder candidates.
+5. **Do not add module-level mutable state.** Export a factory. Module state is
+   per-isolate on edge runtimes and leaks between tests.
+6. **Do not collapse a generic into a concrete host type.** `TCtx` and
+   `TContentPart` are parameters because hosts genuinely diverge there; binding
+   them to one application's types would fork the package.
+7. **Version the policy, do not mutate it.** If routing order or meaning
+   changes, bump `ROUTE_POLICY_VERSION`.
+8. **Put tests in `src/**/__tests__/`.** They run under bare `bun test` with no
+   DOM and no database. Anything needing either belongs in the host.
+9. **Do not edit `version` in `package.json`.** It is a placeholder; the
+   published version is stamped at release time.
+
+---
+
+## Versioning
+
+**Versioning is not semver.** Each published release increments the major and
+resets the rest — `1.0.0`, `2.0.0`, `3.0.0` — so the major is a release counter,
+not a compatibility signal, and a bump does not by itself mean the surface
+changed. Pin an exact version and read the changes between releases until this
+stabilizes.
 
 ## Development
 
-This repository is a read-only **archive mirror** of the `packages/bind`
-workspace in Monad's canonical repository, exported via Copybara. npm
-releases of `@juno-ai/bind` are published from the canonical repository, not
-from here — the manifest here stays `"private": true` so it cannot be
-published by accident, though the version it carries is the one the matching
-npm release has. Issues are welcome here; code changes land in the canonical
-repo and flow out with the next export.
+The source lives in Monad's canonical repository. `juno-ai-labs/agent-harness`
+on GitHub is a read-only **archive mirror** of it, exported via Copybara, and
+npm releases are published from the canonical repository rather than from either
+mirror. Issues are welcome on the GitHub mirror; code changes land in the
+canonical repo and flow out with the next export.
 
 Run the tests with [Bun](https://bun.sh):