@juno-ai/bind 9.0.0 → 11.0.0

package/index.js

@@ -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";

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;
+    /**
+     * 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.
      */
-    activateSkills: (skillRefs: string[]) => Promise<void> | void;
+    now?: () => number;
     /**
      * Must this call run on its own, before the rest of its batch?
      *
@@ -270,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>;