@juno-ai/bind 8.0.0 → 10.0.0

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/loop/index.d.ts

@@ -1 +1,2 @@
-export { runToolLoop, type ToolLoopParams, type ToolLoopState, type ToolLoopTurn, type ToolCallOutcome, type CompactionApplied, type RunStatus, } from "./tool-loop.js";
+export type { StopReason, RunStats } from "../contracts/turn.js";
+export { runToolLoop, MissingActivationPortError, type ToolLoopParams, type ToolLoopResult, type ToolLoopState, type ToolLoopTurn, type ToolCallOutcome, type CompactionApplied, type RunStatus, } from "./tool-loop.js";

package/loop/index.js

@@ -1 +1 @@
-export { runToolLoop, } from "./tool-loop.js";
+export { runToolLoop, MissingActivationPortError, } from "./tool-loop.js";

package/loop/tool-loop.d.ts

@@ -1,4 +1,5 @@
 import type OpenAI from "openai";
+import { type RunStats, type StopReason } from "../contracts/turn.js";
 /**
  * The agent iteration engine: call the model, run the tools it asked for,
  * repeat until it stops asking. Everything that *happens* as a result — status
@@ -19,11 +20,13 @@ import type OpenAI from "openai";
  *    than thrown. Without it they are invisible — the model sees them, your
  *    logs do not.
  *
- * Turn accounting is deliberately the flat usage the loop needs to run
- * (`ToolLoopTurn`), not the richer `ModelTurnResult` in `@juno-ai/bind/contracts`
- * with its timings. The two describe the same event at different resolutions
- * and converge when the loop learns to accumulate `RunStats` directly; until
- * then a host that wants throughput metrics folds them alongside.
+ * Turn accounting is the flat usage a host's `callModel` returns
+ * (`ToolLoopTurn`), not the richer `ModelTurnResult` in
+ * `@juno-ai/bind/contracts` with its timings. The loop bridges them: it
+ * measures each `callModel` with an injectable `now` and folds the pair
+ * through `accumulateTurn`, so `runToolLoop` returns a full `RunStats`
+ * without a host changing the shape it already returns. `ttftMs` is the one
+ * field that cannot cross — only the transport sees the first byte.
  */
 /** One model completion's message + the provider usage the loop accounts for. */
 export interface ToolLoopTurn {
@@ -31,6 +34,12 @@ export interface ToolLoopTurn {
     inputTokens: number;
     outputTokens: number;
     costCents: number;
+    /**
+     * Provider-reported cached input tokens, when the transport can report them.
+     * Optional — omit it (or pass `null`) and the run's `cachedInputTokens` total
+     * simply does not count this turn, rather than counting it as a zero.
+     */
+    cachedInputTokens?: number | null;
 }
 /**
  * Outcome of running one tool call inside an assistant `tool_calls` batch.
@@ -82,6 +91,8 @@ export interface CompactionApplied {
     inputTokens: number;
     outputTokens: number;
     costCents: number;
+    /** Provider-reported cached input tokens for the compaction call, if known. */
+    cachedInputTokens?: number | null;
     /** Persist the compacted session + activity row. Runs after accounting. */
     persist: () => Promise<void>;
 }
@@ -123,10 +134,79 @@ export interface ToolLoopState {
     };
 }
 export type RunStatus = "thinking" | "thinking_with_tools" | "executing_tools";
+/**
+ * A tool asked the loop to activate a plugin or an instruction module, and the
+ * port that would do it was not wired.
+ *
+ * Reported through `onToolCallRejected` rather than thrown: the call itself
+ * succeeded and its tool message is already correct, so failing the run would
+ * be worse than the missing activation. But it must not be silent — before
+ * these ports were optional this was a compile error, and the runtime symptom
+ * (an agent that keeps loading a plugin it never receives) points nowhere near
+ * the cause.
+ *
+ * Match on `error.name === "MissingActivationPortError"` rather than
+ * `instanceof` if you consume this package from a projected or re-bundled copy
+ * — two copies of a class in one module graph make `instanceof` silently
+ * false, and this package is Copybara-projected and republished.
+ */
+export declare class MissingActivationPortError extends Error {
+    readonly port: "activatePlugins" | "activateSkills";
+    readonly name = "MissingActivationPortError";
+    constructor(port: "activatePlugins" | "activateSkills");
+}
+/**
+ * What a completed loop reports back.
+ *
+ * Returned rather than folded into `ToolLoopState` because these are the run's
+ * *conclusion*, not its live progress: a caller reads `state` mid-run for a
+ * heartbeat, and reads this once, after. Before it existed every host
+ * re-derived the outcome from three flags and an iteration count, and each got
+ * a slightly different answer.
+ */
+export interface ToolLoopResult {
+    /**
+     * Why the loop stopped. See {@link StopReason} — `deadline` arrives as a
+     * thrown error rather than a value, and is never returned here.
+     *
+     * `aborted` means only "the batch signal was set, or `shouldStop` said so".
+     * It does not say *which*, because a combined signal cannot. A host that
+     * needs timeout-vs-cancellation reaches for its own `RunDeadline` (and
+     * `classifyRunFailure`), not for this value.
+     */
+    readonly stopReason: StopReason;
+    /**
+     * Cumulative accounting for the run: turns, dispatched tool calls, tokens
+     * (including provider-reported cached input), cost, and the model-time vs
+     * tool-time split with a per-tool breakdown.
+     *
+     * **`stats` is this invocation's contribution alone**; `state` is whatever
+     * the caller seeded plus that. They match only when the caller 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 do not substitute one for
+     * the other.
+     *
+     * They also differ on tool calls on purpose: `state.toolCalls` counts what
+     * the model *requested* (it drives a live progress indicator, so it has to
+     * rise the moment a batch is dispatched), while `stats.toolCalls` counts
+     * what actually *ran*. An aborted batch is exactly the gap between them.
+     *
+     * Both are lost if the loop throws — a deadline, a cancellation, or a fatal
+     * tool error leaves no return value, so `state` (which is mutated in place)
+     * is the only accounting that survives those exits.
+     */
+    readonly stats: RunStats;
+}
 export interface ToolLoopParams {
     state: ToolLoopState;
-    /** Active plugin set — read to build tool defs, grown by `activatePlugins`. */
-    activePlugins: Set<string>;
+    /**
+     * Active plugin set. The loop does not read it — `buildTools` and
+     * `activatePlugins` are the host's own closures over it — so it is optional
+     * and passing one is purely a convenience for a host that likes threading it
+     * through explicitly.
+     */
+    activePlugins?: Set<string>;
     maxIterations: number;
     /** Call the model with the current transcript + tool defs. `onOutputProgress`
      *  (optional) receives a running estimate of THIS call's output tokens as the
@@ -137,15 +217,38 @@ export interface ToolLoopParams {
     buildTools: () => OpenAI.ChatCompletionTool[];
     /** Execute one tool call → the `tool` message + control signals. */
     runToolCall: (toolCall: OpenAI.ChatCompletionMessageToolCall) => Promise<ToolCallOutcome>;
-    /** Activate newly loaded plugins (mutate the catalog/active set). */
-    activatePlugins: (pluginNames: string[]) => void;
+    /**
+     * Activate newly loaded plugins (mutate the catalog/active set). Optional:
+     * a host with a fixed tool surface has nothing to activate, and requiring an
+     * empty function from it bought nothing.
+     */
+    activatePlugins?: (pluginNames: string[]) => void;
     /**
      * Activate newly loaded skills: inject their bodies into the system prompt's
      * instructions section and refresh the catalog. Async because a host may
      * re-read the module body from storage. Expected to no-op for a ref the agent
-     * cannot access — the loop does not pre-validate them.
+     * cannot access — the loop does not pre-validate them. Optional, as above.
      */
-    activateSkills: (skillRefs: string[]) => Promise<void> | void;
+    activateSkills?: (skillRefs: string[]) => Promise<void> | void;
+    /**
+     * Clock for the model-time and tool-time measurements in
+     * {@link ToolLoopResult.stats}. Defaults to `Date.now`, the package's one
+     * sanctioned ambient-clock exception; inject a fake to make timing
+     * assertions deterministic.
+     *
+     * **Must be a real monotonic clock when tools can run concurrently.** Each
+     * call records `now()` at dispatch and again when it settles, so a shared
+     * counter that only advances when some *other* call asks it to will charge
+     * one tool for another's time. A cooperatively-advanced fake is fine for a
+     * serial batch (`runsSerially`), and fine for the model-time figures always.
+     *
+     * Measured *around* `callModel`, so the number includes whatever that
+     * function does internally — a defect retry, a fallback provider, a routing
+     * hop. That is the honest figure for cost-and-latency accounting: it is what
+     * the turn actually took. A host that wants the successful attempt's
+     * generation time alone already has it, inside its own transport.
+     */
+    now?: () => number;
     /**
      * Must this call run on its own, before the rest of its batch?
      *
@@ -235,6 +338,20 @@ export interface ToolLoopParams {
         userId: string;
         content: string;
     }) => Promise<void> | void;
+    /**
+     * Bounds the tool batch. Combine the run's deadline with any cancellation
+     * signal (`deadline.withExternal(cancelSignal)`) and pass the result.
+     *
+     * Without it, `throwIfTimedOut` and `ensureNotCancelled` are only consulted
+     * between iterations, so a deadline that fires while the model is being
+     * called still lets the whole batch execute its side effects, and a hung tool
+     * holds the run open for as long as it runs. Those are throw-based ports and
+     * cannot express "stop claiming new work" to a pool already in flight — only
+     * a signal can.
+     *
+     * Optional so an existing host is unchanged until it opts in.
+     */
+    signal?: AbortSignal | undefined;
     /** Decide whether the live context (token count) needs auto-compaction. */
     needsCompaction?: (currentTokens: number) => boolean;
     /**
@@ -256,5 +373,7 @@ export interface ToolLoopParams {
  * Mutates `state` (messages + token accumulators) in place. That is deliberate
  * rather than a return value: a caller's heartbeat reads live totals off it
  * mid-loop, which a returned result could not provide until the run ended.
+ * The {@link ToolLoopResult} it *returns* is the complementary half — the
+ * run's conclusion, which only exists once the loop is over.
  */
-export declare function runToolLoop(params: ToolLoopParams): Promise<void>;
+export declare function runToolLoop(params: ToolLoopParams): Promise<ToolLoopResult>;