@juno-ai/bind 9.0.0 → 11.0.0

package/README.md

@@ -35,6 +35,85 @@ constraints that will fail CI if you break them.
 
 **Added**
 
+- **`@juno-ai/bind/skills`** — progressive disclosure for *instructions*, the
+  mirror of `@juno-ai/bind/plugins`. `createSkillRegistry` for what your source
+  ships, `partitionSkillCatalog` for the Tier-1 catalog and its token budget,
+  `resolveActiveSkillInstructions` for the bodies (live-head or pinned to a
+  completed run's hashes, over a batched `ExternalSkillSource` for skills your
+  users author), `createSkillActivation` to drive the loop's `activateSkills`
+  port, `admitSkillLoad` for the active-set bounds, `parseSkillMarkdown` /
+  `serializeSkillMarkdown` for the `SKILL.md` interchange format over your own
+  YAML, and `buildAgentSkillsDiscoveryIndex` for the Agent Skills Discovery RFC
+  v0.2.0 document. See "How to give an agent loadable skills".
+
+  Two notes for a host that already has something like this. The catalog
+  returns **data, not prose** — the wording is yours, for the same prompt-cache
+  reason `partitionPluginCatalog` gives. And the content digest is **the
+  package's**, not a port like the one `toolCallArgsHash` takes: a skill's hash
+  is computed at registration, which is synchronous, and it identifies build
+  content rather than being persisted across versions. `Sha256Hex` is still a
+  parameter if you would rather inject a native one.
+
+**Breaking**
+
+- `runToolLoop` now returns `ToolLoopResult` (`{ stopReason, stats }`) instead
+  of `void`. A caller that ignores the return value is unchanged, but a
+  wrapper *annotated* `Promise<void>` no longer typechecks — widen it to
+  `Promise<ToolLoopResult>`.
+- `RunStats` gained `cachedInputTokens`. `emptyRunStats()` and the folds set it;
+  code that hand-builds a `RunStats` literal must add the field. `ToolLoopTurn`
+  and `CompactionApplied` gained a matching optional `cachedInputTokens`, so
+  the loop can actually populate it — return it from `callModel` if your
+  transport reports one.
+- `MissingActivationPortError` — a tool outcome that asks the loop to activate
+  a plugin or skill while the matching port is unwired is now reported through
+  `onToolCallRejected` instead of being dropped in silence. The run still
+  completes; the wiring bug is no longer invisible.
+- `defineTool` no longer applies `normalizeArgs` inside `execute`.
+  Normalization is the dispatcher's step (it runs before the idempotency
+  hash), and applying it in both places applied it twice.
+- **`StopReason` no longer has `suspended`.** It split into
+  `waiting_for_reply` (a tool asked a human a question; nothing happens until
+  someone answers) and `resuming_later` (a tool scheduled its own resume).
+  Removing a union member breaks any exhaustive `switch`, so map both new
+  values wherever you handled `suspended` — and note that the old single value
+  could not tell them apart at all, which is why it was split.
+- **`@juno-ai/bind/plugins` now loads `zod` at runtime.** The barrel re-exports
+  `defineTool` / `pluginFromTools`, and `toolWireDefinition` needs
+  `z.toJSONSchema`. Every other module in the subpath was previously
+  runtime-zod-free, so a consumer importing only `createToolRegistry` while
+  ignoring the peer-dependency warning now fails to resolve. `zod` is a
+  required (non-optional) peer, so a correctly-installed consumer is
+  unaffected. `@juno-ai/bind/loop` is deliberately still zod-free — which is
+  why `toolResultMessage` lives in its own type-only module.
+
+**Added**
+
+- `ToolLoopResult.stopReason` — `done` / `waiting_for_reply` / `resuming_later`
+  / `iteration_limit` / `aborted`, one per exit, replacing the two or three
+  loop-state flags every host was combining differently. The two pause reasons
+  are separate values on purpose: one needs a person to act and the other does
+  not, and that is the distinction a host most needs to surface. `deadline` stays in the `StopReason` union
+  for a host classifying a thrown `RunTimeoutError`; the loop cannot return it,
+  and the type's doc comment says why.
+- `ToolLoopResult.stats` — a `RunStats` the loop folds itself: turns,
+  dispatched tool calls, tokens, cost, and the model-time/tool-time split with
+  a per-tool breakdown. A compaction contributes its spend but not a turn
+  (`accumulateAuxiliarySpend`, also new), so `stats.turns` stays comparable
+  with `maxIterations`. `ToolLoopParams.now` injects the clock.
+- `@juno-ai/bind/testing` — the scripted-model fixtures this package's own
+  cross-module suites use: `loopHarness`, `scriptedModel`, `toolCallTurn`,
+  `finalAnswer`, `toolCall`, `freshState`, `recordingSink`, `steppingClock`.
+  Credential-free multi-turn, multi-tool tests without mocking a chat client.
+- `defineTool` / `pluginFromTools` (`@juno-ai/bind/plugins`) — author a tool as
+  `{ name, description, schema, execute }` and get argument parsing, a
+  `validation` failure the model can act on, and typed `args` in `execute`.
+  Plus `toolWireDefinition` (zod → sanitized JSON Schema) and
+  `toolResultMessage` (the `role:"tool"` encoding the loop itself uses).
+- `ToolLoopParams.activePlugins`, `activatePlugins` and `activateSkills` are
+  now optional. A host with a fixed tool surface had been required to supply
+  empty functions; `activePlugins` was never read by the loop at all.
+
 - `runToolCallsPooledByTool` accepts an optional `signal`, and
   `AbortedToolCallError` / `ToolBatchOptions` are exported from
   `@juno-ai/bind/run`. Additive — a caller that passes nothing is unchanged, and
@@ -297,26 +376,165 @@ const state: ToolLoopState = {
   toolCalls: 0,
 };
 
-await runToolLoop({
+const { stopReason, stats } = await runToolLoop({
   state,
-  activePlugins,
   maxIterations: 30,
 
   callModel: (messages, tools) => llm.complete({ messages, tools }),
   buildTools: () => registry.toolDefinitions([...activePlugins]),
   runToolCall: (call) => dispatch(call),
+
+  // Only if your tools can change the tool surface mid-run:
   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.
+// `state` is mutated in place — read totals off it mid-run from a heartbeat.
 console.log(state.inputTokens, state.outputTokens, state.toolCalls);
+
+// The result is the run's conclusion, which only exists once it is over.
+await persistRun({ stopReason, ...stats });
+```
+
+The two halves are deliberate. `state` is mutated rather than returned so a
+heartbeat can read live totals while the run is still going; `ToolLoopResult`
+is what could not exist until the run ended.
+
+`stopReason` is the whole outcome, in one word:
+
+| Reason | The model | What a host should say |
+|---|---|---|
+| `done` | Stopped calling tools | It answered |
+| `waiting_for_reply` | A tool asked a human a question | It needs you to answer — nothing happens until you do |
+| `resuming_later` | A tool scheduled its own resume | It paused on purpose and will come back |
+| `iteration_limit` | Still calling tools at the ceiling | It ran out of room, mid-task |
+| `aborted` | Cut off by `shouldStop` or the batch `signal` | It was stopped |
+
+The two pause reasons are separate values because their consequences differ
+more than any other pair: one needs a person to act, the other needs nobody to.
+Collapsed into one `suspended`, a host that wanted to say which had to go back
+and read `state.suspended` — the loop-state-flag reconstruction this return
+value exists to replace.
+
+`deadline` is in the `StopReason` union but never returned: the wall-clock port
+(`throwIfTimedOut`) is throw-based, so an expired budget leaves the loop as a
+`RunTimeoutError` your catch block maps — `classifyRunFailure` recognises the
+same condition. The loop returns `aborted` for a fired signal because once a
+deadline and a cancellation are combined into one `AbortSignal` it genuinely
+cannot tell which one fired.
+
+`stats` is a `RunStats`: turns, dispatched tool calls, tokens (including
+provider-reported cached input, when your `callModel` returns a
+`cachedInputTokens`), cost, and model time vs tool time with a per-tool
+breakdown. Three things are worth reading carefully:
+
+- **`stats` is this invocation's contribution; `state` is whatever you seeded
+  plus that.** They match only if you seeded zeros. A host resuming a run seeds
+  `state` from the stored totals, and then `state.costCents` is the run's
+  lifetime cost while `stats.costCents` is this leg's — bill from whichever you
+  mean, and don't substitute one for the other.
+
+- **`stats.toolCalls` counts calls that *ran*; `state.toolCalls` counts calls
+  the model *requested*.** They differ by exactly the work an aborted batch
+  prevented, which is why they are two numbers.
+- **A compaction contributes tokens, cost and model time but not a turn**, so
+  `stats.turns` stays comparable with `maxIterations`.
+
+Both are lost if the loop throws: a deadline, a cancellation, or a fatal tool
+error leaves no return value, so `state` — mutated in place — is the only
+accounting that survives those exits.
+
+Pass `now` to make either measurement deterministic in a test; it defaults to
+`Date.now`.
+
+### How to test an agent without a provider
+
+`@juno-ai/bind/testing` ships the fixtures this package's own cross-module
+suites use. A scripted model is a queue of prepared turns, so a multi-turn,
+multi-tool test needs no credential, no network, and no mocked chat client.
+
+```ts
+import { runToolLoop } from "@juno-ai/bind/loop";
+import {
+  loopHarness, toolCall, toolCallTurn, finalAnswer,
+} from "@juno-ai/bind/testing";
+
+const h = loopHarness([
+  toolCallTurn([toolCall("search", { q: "bind" }), toolCall("read_file")]),
+  toolCallTurn([toolCall("write_file", { path: "out.md" })]),
+  finalAnswer("Done."),
+]);
+
+const { stopReason, stats } = await runToolLoop(h.params);
+
+expect(stopReason).toBe("done");
+expect(stats.turns).toBe(3);
+expect(h.ran).toEqual(["search", "read_file", "write_file"]);
+```
+
+Every field of `h.params` is overridable, which is how you reach the
+interesting states — `{ runToolCall }` to make one tool fail, `{ signal }` to
+abort mid-batch, `{ now }` to make the timing figures deterministic
+(`steppingClock()` for a fixed tick, or your own closure advanced inside
+`runToolCall` when you want to *choose* each interval).
+`h.ran` records what the loop *dispatched* and `h.sideEffects` what actually
+*completed*; the gap between them is the answer to every cancellation question.
+
+Two failure modes are deliberate. A script that runs out throws rather than
+returning an empty turn — otherwise `maxIterations` absorbs the mistake and the
+test passes while describing a run that never happened. And a duplicate
+tool-call id throws at construction, rather than producing a transcript the
+provider rejects ten frames deep in the loop.
+
+### How to author a tool without writing dispatch by hand
+
+A `ToolPlugin` dispatches by tool name, which is right for a bundle with shared
+setup and pure ceremony for a flat list of independent tools. `defineTool` does
+the mechanical half — parse the arguments, turn a parse failure into something
+the model can act on — and `pluginFromTools` bundles the result.
+
+```ts
+import { defineTool, pluginFromTools } from "@juno-ai/bind/plugins";
+
+const search = defineTool({
+  name: "search",
+  description: "Search the corpus.",
+  schema: z.object({ query: z.string().min(1), limit: z.number().default(10) }),
+  // `args` is typed from the schema; `limit` has already defaulted.
+  execute: async (args, ctx: Ctx) => ({
+    success: true,
+    data: await corpus.search(args.query, args.limit, ctx.tenantId),
+  }),
+});
+
+const plugin = pluginFromTools<Ctx>({
+  name: "corpus",
+  description: "Corpus tools.",
+  tools: [search],
+});
 ```
 
-`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.
+The schema is the single source of truth: it is converted to JSON Schema for
+the model *and* used to validate what comes back, so the two cannot drift.
+
+Bad arguments come back as `{ success: false, kind: "validation", error }`
+naming the offending path — **returned, not thrown**. That distinction is the
+bug this replaces: a thrown parse error turns a recoverable "you passed the
+wrong field" into a dead run. An unknown tool name is likewise a returned
+`not_found`, because a resumed session's history can reference a tool you have
+since retired.
+
+The validation lives on the tool, not on the bundle, so a host with its own
+dispatcher can call `search.execute(rawArgs, ctx)` directly and get the same
+guarantee — `pluginFromTools` only resolves names.
+
+Two encoders come with it. `toolWireDefinition(tool, wireName?)` converts a
+tool to what the provider is shown, through `sanitizeToolSchema` — `wireName`
+because tool naming is host policy (Monad encodes `plugin__tool` to route a
+call back to its plugin). `toolResultMessage(callId, result)` produces the
+`role:"tool"` message, using the same encoding the loop synthesizes for a
+failed or refused call — so a model never has to learn two error formats in one
+transcript.
 
 ### How to make a tool take effect mid-batch
 
@@ -876,6 +1094,130 @@ data migration.
 system prompt's business, and re-rendering it byte-identically for unchanged
 inputs is what preserves a provider's prompt-cache prefix.
 
+### How to give an agent loadable skills
+
+A *skill* is a markdown procedure or reference module the model can pull into
+its own instructions: a catalog line it always sees, a body injected into the
+system prompt once loaded, and resources it may read after that. It is the same
+progressive disclosure as tool activation, applied to knowledge — and it exists
+because the accumulated know-how of a real workspace does not fit in a context
+window, while a catalog line costs about fifty tokens.
+
+Register what your own source ships:
+
+```ts
+import { createSkillRegistry, partitionSkillCatalog } from "@juno-ai/bind/skills";
+
+const skills = createSkillRegistry({ onWarn: (message, fields) => log.warn(message, fields) });
+
+skills.registerPlatform({
+  name: "triaging-inbound-work",
+  description: "How this team triages inbound requests.",
+  whenToUse: "When asked to sort, rank, or route a queue of incoming work.",
+  render: () => TRIAGE_BODY,
+});
+// A skill contributed by a plugin is offered only to an agent that can load
+// that plugin — a recipe for tools it cannot call is noise.
+skills.registerPlugin("documents", DRAFTING_SKILL);
+```
+
+Render the catalog from a partition, in your own words:
+
+```ts
+const active = new Set<string>(session.activeSkills);
+const available = skills.summaries({ availablePlugins: agent.plugins });
+const { active: loaded, loadable, truncated } = partitionSkillCatalog(active, available);
+```
+
+`partitionSkillCatalog` returns **data, not prose**, exactly as
+`partitionPluginCatalog` does. It also enforces a token budget by marking the
+overflow `name_only` rather than dropping it — a name is still enough for the
+model to call `load_skill` and read the real description, whereas a skill it
+cannot see is one it can never ask for. Pass your own `cost` if your line format
+differs from `- name: description — whenToUse`; a budget is only as honest as
+its measurement.
+
+Then wire activation into the loop, and bound how much can be loaded:
+
+```ts
+import {
+  admitSkillLoad,
+  createSkillActivation,
+  estimateSkillBodyTokens,
+  resolveActiveSkillInstructions,
+} from "@juno-ai/bind/skills";
+
+const loadedSkillShas: Record<string, string> = {};
+const resolveActiveInstructions = (activeRefs: string[]) =>
+  resolveActiveSkillInstructions({ activeRefs, available, registry: skills });
+
+const activation = createSkillActivation({
+  availableSkills: available,
+  activeSkills: active,          // yours: seeded before the first turn, persisted after the last
+  loadedSkillShas,               // yours: hoist it so a failed run still records what it read
+  store: { resolveActiveInstructions },
+  applyInstructions: (instructions) => renderSystemPrompt({ instructions }),
+});
+
+await runToolLoop({ ...params, activateSkills: (refs) => activation.activateSkills(refs) });
+```
+
+Two details are worth knowing before you wire your own `load_skill` tool. The
+resolver renders in a **total order** (origin, then name) rather than the order
+skills were loaded, because these bodies sit high in the system prompt and a
+resumed session's persisted order would otherwise byte-shift the cacheable
+prefix. And `admitSkillLoad` is what keeps a looping model from loading its way
+into a context-limit error — you measure, it judges:
+
+```ts
+// Cheapest first. The count is a `Set.size`; the token bound needs the
+// resolver, which for a host-stored skill is a query plus the wrapping of every
+// active body. A model that has hit the cap keeps calling `load_skill`, so
+// folding these into one pass pays that cost on every call purely to refuse.
+const byCount = admitSkillLoad({ activeCount: active.size });
+if (!byCount.admitted) return { success: false, kind: "validation", error: byCount.reason };
+
+const { instructions } = await resolveActiveInstructions([...active, ref]);
+const byTokens = admitSkillLoad({ projectedBodyTokens: estimateSkillBodyTokens(instructions) });
+if (!byTokens.admitted) return { success: false, kind: "validation", error: byTokens.reason };
+```
+
+Omitting a measurement omits its bound, which is what makes the two-pass shape
+expressible — and a measurement that arrives broken (`NaN`, negative) refuses
+rather than admits, because a nonsense count is not evidence of room.
+
+Skills your *users* author live in your database, not the registry. Hand the
+resolver an `externalSource` and it routes any ref that is not `platform:<name>`
+to you — batched, so one activation stays one query:
+
+```ts
+resolveActiveSkillInstructions({
+  activeRefs,
+  available,
+  registry: skills,
+  externalSource: async (refs, pinnedShas) => loadWorkspaceSkills(workspaceId, refs, pinnedShas),
+});
+```
+
+`pinnedShas` is how a replay stays honest. Each resolution records the
+`contentSha` it actually rendered; feed a completed run's map back in and every
+skill resolves to the body that run saw, so an eval is not silently grading
+against instructions that were edited afterwards.
+
+To read or write the interchange format, pass your own YAML implementation —
+the package takes peer dependencies only:
+
+```ts
+import { parseSkillMarkdown } from "@juno-ai/bind/skills";
+import yaml from "js-yaml";
+
+const parsed = parseSkillMarkdown(raw, { parse: yaml.load, stringify: (v) => yaml.dump(v, { lineWidth: -1 }) });
+```
+
+Import is deliberately lenient — it repairs the unquoted-colon frontmatter
+mistake and warns — and fails only on frontmatter that is not YAML and on a
+missing `description`, the one field with no sensible default.
+
 ### How to restore a persisted activation set
 
 ```ts
@@ -923,7 +1265,9 @@ client error), call `releaseProbe` so the slot cannot stick.
 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
+Every export is re-exported from the package root **except `@juno-ai/bind/testing`,
+which is subpath-only so fixtures never reach a production bundle** — but prefer
+the subpath either way, since it
 keeps a consumer who only wants routing from pulling in the rest.
 
 | Import | Owns | Reach for it when |
@@ -935,7 +1279,9 @@ keeps a consumer who only wants routing from pulling in the rest.
 | `@juno-ai/bind/run` | Wall-clock deadline, failure classification, coalesced heartbeat, tool-batch pooling, child-run lineage and admission, poll backoff, tool-call receipts for retry-safe side effects | 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 |
+| `@juno-ai/bind/plugins` | Tool/plugin vocabulary, `defineTool` / `pluginFromTools`, the wire-definition and tool-result encoders, the registry factory, progressive-disclosure activation | You are authoring tools, or you have more of them than fit comfortably in one prompt |
+| `@juno-ai/bind/skills` | Skill vocabulary — the code-skill registry, the `SKILL.md` codec, the content hash, the catalog's total order and token budget, the active-instruction resolver, the activation controller, active-set bounds, and the Agent Skills Discovery document | Your agent needs loadable instructions, not just tools — a workspace's procedures, a house style, a runbook |
+| `@juno-ai/bind/testing` | Scripted-model fixtures — `loopHarness`, `scriptedModel`, `toolCallTurn`, `finalAnswer`, `freshState`, `recordingSink`, `steppingClock` | You want multi-turn, multi-tool tests without a credential or a mocked chat client |
 
 ### Contracts the types do not carry
 
@@ -1288,8 +1634,14 @@ const turn: TurnFn = async (messages, tools, signal) => {
 
 ### Accumulating run statistics
 
+**If you use `runToolLoop`, you do not need this** — it folds `RunStats` itself
+and returns it. This is the shape for a host driving turns by hand.
+
 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.
+and tool time separate so a slow tool never looks like a slow model. Model
+calls that are not agent turns — a compaction pass — go through
+`accumulateAuxiliarySpend` instead, which charges the tokens and the time
+without counting a turn.
 
 ```ts
 let stats = emptyRunStats();
@@ -1401,7 +1753,13 @@ try {
     stats = accumulateTurn(stats, result);
     await heartbeat.beat();
     if (!result.message.tool_calls?.length) break;
-    if (await runToolBatch(result.message.tool_calls)) { stopReason = "suspended"; break; }
+    const suspend = await runToolBatch(result.message.tool_calls);
+    if (suspend) {
+      // The two pause reasons are separate values — see the stop-reason table.
+      stopReason =
+        suspend.resumeKind === "answer" ? "waiting_for_reply" : "resuming_later";
+      break;
+    }
   }
 } catch (error) {
   stopReason = classifyRunFailure(deadline, error) === "timed_out" ? "deadline" : "aborted";
@@ -1579,10 +1937,12 @@ two rates weights a 10-token run like a 10,000-token one.
 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.
+- **Time-to-first-token in `RunStats`.** The loop now folds `RunStats` itself,
+  so `modelTimeMs`, `toolTimeMs` and the per-tool breakdown come for free — but
+  `ttftMs` lives on `TurnTimings` and only the transport can see the first byte.
+  A `callModel` that reported its own timings back would close the gap;
+  `ToolLoopTurn` would have to grow, which is a change to the shape every host
+  already implements.
 - **A streaming turn contract.** Half of this landed:
   `createTurnTextStream` owns the emit/retry interaction for assistant *text*,
   arms `producedOutput` itself, and repairs a retractable surface between

package/contracts/index.d.ts

@@ -1 +1 @@
-export { emptyRunStats, accumulateTurn, accumulateToolCall, accumulateRun, type TranscriptMessage, type AssistantTurnMessage, type WireToolDefinition, type WireToolCall, type TurnTimings, type TurnUsage, type ModelTurnResult, type TurnFn, type StopReason, type RunStats, } from "./turn.js";
+export { emptyRunStats, accumulateTurn, accumulateToolCall, accumulateAuxiliarySpend, accumulateRun, type AuxiliarySpend, type TranscriptMessage, type AssistantTurnMessage, type WireToolDefinition, type WireToolCall, type TurnTimings, type TurnUsage, type ModelTurnResult, type TurnFn, type StopReason, type RunStats, } from "./turn.js";

package/contracts/index.js

@@ -1 +1 @@
-export { emptyRunStats, accumulateTurn, accumulateToolCall, accumulateRun, } from "./turn.js";
+export { emptyRunStats, accumulateTurn, accumulateToolCall, accumulateAuxiliarySpend, accumulateRun, } from "./turn.js";

package/contracts/turn.d.ts

@@ -50,18 +50,67 @@ export interface ModelTurnResult {
  * completed assistant turn.
  */
 export type TurnFn = (messages: readonly TranscriptMessage[], tools: readonly WireToolDefinition[] | undefined, signal: AbortSignal | undefined) => Promise<ModelTurnResult>;
-/** Why a run stopped. `suspended` = a tool intentionally paused the run. */
-export type StopReason = "done" | "suspended" | "iteration_limit" | "deadline" | "aborted";
+/**
+ * Why a run stopped — the single vocabulary a host reports an outcome in,
+ * instead of re-deriving it from a handful of loop-state flags.
+ *
+ * `runToolLoop` returns five of the six directly:
+ *
+ *  - `done` — the model produced a turn with no tool calls (and no
+ *    `onTurnWouldEnd` nudge pushed it forward).
+ *  - `waiting_for_reply` — a tool asked a human a question and the run is
+ *    blocked until someone answers. **Nothing happens until they do.**
+ *  - `resuming_later` — a tool scheduled its own resume (a sleep, a timer).
+ *    The run paused on purpose and will come back by itself.
+ *  - `iteration_limit` — `maxIterations` was exhausted with the model still
+ *    calling tools. The run did not finish; it was cut off.
+ *  - `aborted` — the batch `signal` fired, or `shouldStop` asked to stop.
+ *
+ * The two pause reasons are split rather than one `suspended` because they are
+ * the outcomes whose consequences differ most: one needs a person to act, the
+ * other needs no one to do anything. Collapsed into a single value, a host
+ * that wanted to tell them apart had to go back and read `state.suspended` —
+ * which is the loop-state-flag reconstruction this type exists to replace.
+ *
+ * `deadline` is the one the loop does not return, and deliberately so: the
+ * wall-clock budget is a **throw-based** port (`throwIfTimedOut`), so an
+ * expired budget leaves the loop as a `RunTimeoutError` rather than a value.
+ * A host maps its catch block onto this vocabulary — `classifyRunFailure`
+ * from `@juno-ai/bind/run` recognises the same condition as `"timed_out"`.
+ * Returning `aborted` for an expired deadline would be worse than not
+ * returning it at all: the loop genuinely cannot distinguish a deadline signal
+ * from a cancellation signal once both are combined into one `AbortSignal`.
+ */
+export type StopReason = "done" | "waiting_for_reply" | "resuming_later" | "iteration_limit" | "deadline" | "aborted";
 /**
  * Cumulative run accounting: model-time and tool-time reported separately —
  * task wall-clock conflates provider inference speed with tool execution,
  * and consumers comparing models need the model's contribution isolated.
  */
 export interface RunStats {
+    /**
+     * Agent turns — one per model completion the loop iterated on. Auxiliary
+     * model calls (a compaction pass) contribute their tokens, cost and model
+     * time but NOT a turn, so this stays comparable with the loop's iteration
+     * budget. See {@link accumulateAuxiliarySpend}.
+     */
     readonly turns: number;
+    /**
+     * Tool calls that were actually **dispatched**. A call the batch refused at
+     * claim time (an aborted `signal`) never ran, so it is not counted here even
+     * though the model requested it — the gap between this and the requested
+     * count is exactly the work an abort prevented.
+     */
     readonly toolCalls: number;
     readonly inputTokens: number;
     readonly outputTokens: number;
+    /**
+     * Provider-reported cached input tokens, summed across turns. Zero is
+     * indistinguishable from "the transport could not report it" — a turn whose
+     * `cachedInputTokens` is `null` contributes nothing rather than poisoning the
+     * total, so read this as a floor.
+     */
+    readonly cachedInputTokens: number;
     readonly costCents: number;
     /** Sum of model `generationMs` across turns. */
     readonly modelTimeMs: number;
@@ -75,6 +124,32 @@ export interface RunStats {
 export declare function emptyRunStats(): RunStats;
 /** Fold one completed model turn into cumulative run stats. */
 export declare function accumulateTurn(stats: RunStats, turn: ModelTurnResult): RunStats;
+/**
+ * Model spend that is not an agent turn — today, a compaction pass.
+ *
+ * Split out rather than folded through {@link accumulateTurn} because the two
+ * numbers answer different questions. A compaction is a real model call that
+ * costs real money and real latency, so its tokens, cost and time belong in the
+ * run's totals; it is *not* an iteration the agent spent making progress, so
+ * counting it in `turns` would make `stats.turns` incomparable with the loop's
+ * `maxIterations` and quietly overstate how much thinking the agent did.
+ */
+export interface AuxiliarySpend {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /**
+     * Required, unlike the two below, because a caller that cannot price a call
+     * still knows it cost *something* and should pass `0` deliberately rather
+     * than omit it. Time and cache figures are genuinely unknowable to some
+     * callers, so they are optional and contribute nothing when absent.
+     */
+    readonly costCents: number;
+    /** Wall time of the auxiliary model call, if measured. */
+    readonly modelTimeMs?: number;
+    readonly cachedInputTokens?: number | null;
+}
+/** Fold auxiliary model spend into a run's totals without counting a turn. */
+export declare function accumulateAuxiliarySpend(stats: RunStats, spend: AuxiliarySpend): RunStats;
 /** Fold one dispatched tool call's duration into cumulative run stats. */
 export declare function accumulateToolCall(stats: RunStats, toolName: string, durationMs: number): RunStats;
 /**

package/contracts/turn.js

@@ -4,6 +4,7 @@ export function emptyRunStats() {
         toolCalls: 0,
         inputTokens: 0,
         outputTokens: 0,
+        cachedInputTokens: 0,
         costCents: 0,
         modelTimeMs: 0,
         toolTimeMs: 0,
@@ -20,11 +21,41 @@ export function accumulateTurn(stats, turn) {
         turns: stats.turns + 1,
         inputTokens: stats.inputTokens + turn.usage.inputTokens,
         outputTokens,
+        cachedInputTokens: stats.cachedInputTokens + (turn.usage.cachedInputTokens ?? 0),
         costCents: stats.costCents + (turn.usage.costCents ?? 0),
         modelTimeMs,
         outputTokensPerSecond: modelTimeMs > 0 ? (outputTokens / modelTimeMs) * 1000 : null,
     };
 }
+/** Fold auxiliary model spend into a run's totals without counting a turn. */
+export function accumulateAuxiliarySpend(stats, spend) {
+    const outputTokens = stats.outputTokens + spend.outputTokens;
+    const modelTimeMs = stats.modelTimeMs + (spend.modelTimeMs ?? 0);
+    return {
+        ...stats,
+        inputTokens: stats.inputTokens + spend.inputTokens,
+        outputTokens,
+        cachedInputTokens: stats.cachedInputTokens + (spend.cachedInputTokens ?? 0),
+        costCents: stats.costCents + spend.costCents,
+        modelTimeMs,
+        // Recomputed, not carried: the added output tokens and model time both move
+        // the rate, and leaving the old value would report a throughput that
+        // matches neither the turns nor the totals now stored beside it.
+        outputTokensPerSecond: modelTimeMs > 0 ? (outputTokens / modelTimeMs) * 1000 : null,
+    };
+}
+/**
+ * Read a tool's accumulated time without going through `Object.prototype`.
+ *
+ * A bare `breakdown[name] ?? 0` reads inherited properties, so a tool legally
+ * named `constructor` or `toString` returns a *function*, and `fn + duration`
+ * silently produces a string — a corrupted `toolTimeBreakdownMs` entry that
+ * typechecks as `number`. Tool names come from the model, so this is reachable
+ * on any run. Same guard the plugin registry already applies to alias lookups.
+ */
+function ownDuration(breakdown, toolName) {
+    return Object.hasOwn(breakdown, toolName) ? breakdown[toolName] : 0;
+}
 /** Fold one dispatched tool call's duration into cumulative run stats. */
 export function accumulateToolCall(stats, toolName, durationMs) {
     return {
@@ -33,7 +64,7 @@ export function accumulateToolCall(stats, toolName, durationMs) {
         toolTimeMs: stats.toolTimeMs + durationMs,
         toolTimeBreakdownMs: {
             ...stats.toolTimeBreakdownMs,
-            [toolName]: (stats.toolTimeBreakdownMs[toolName] ?? 0) + durationMs,
+            [toolName]: ownDuration(stats.toolTimeBreakdownMs, toolName) + durationMs,
         },
     };
 }
@@ -67,14 +98,16 @@ export function accumulateRun(stats, run) {
         ...stats.toolTimeBreakdownMs,
     };
     for (const [toolName, durationMs] of Object.entries(run.toolTimeBreakdownMs)) {
+        // Own-property read, for the same reason as `accumulateToolCall`.
         toolTimeBreakdownMs[toolName] =
-            (toolTimeBreakdownMs[toolName] ?? 0) + durationMs;
+            ownDuration(toolTimeBreakdownMs, toolName) + durationMs;
     }
     return {
         turns: stats.turns + run.turns,
         toolCalls: stats.toolCalls + run.toolCalls,
         inputTokens: stats.inputTokens + run.inputTokens,
         outputTokens,
+        cachedInputTokens: stats.cachedInputTokens + run.cachedInputTokens,
         costCents: stats.costCents + run.costCents,
         modelTimeMs,
         toolTimeMs: stats.toolTimeMs + run.toolTimeMs,

package/index.d.ts

@@ -11,9 +11,12 @@
  * coalesced heartbeat, failure classification, tool-batch pooling, child-run
  * lineage and admission), the streaming-completion watchdog and completion
  * defect detection (`src/completion/`), transcript validation/healing, provider
- * tool-schema sanitization, and the plugin/tool vocabulary with its registry and
+ * tool-schema sanitization, the plugin/tool vocabulary with its registry and
  * progressive-disclosure activation — generic over the host's invocation
- * context. What is NOT here is
+ * context — and the skill vocabulary that applies the same disclosure to
+ * instructions (`src/skills/` — the code-skill registry, the `SKILL.md` codec,
+ * the content hash that makes a replay honest, the catalog budget, the
+ * active-instruction resolver and its activation controller). What is NOT here is
  * the run driver: starting a run, recording what it did, and delivering its
  * output. See the README for the rest of what is deliberately absent.
  */
@@ -24,4 +27,5 @@ export * from "./run/index.js";
 export * from "./transcript/index.js";
 export * from "./tools/index.js";
 export * from "./plugins/index.js";
+export * from "./skills/index.js";
 export * from "./loop/index.js";