@juno-ai/bind 2.0.0 → 4.0.0

package/contracts/index.d.ts

@@ -1 +1 @@
-export { emptyRunStats, accumulateTurn, accumulateToolCall, type TranscriptMessage, type AssistantTurnMessage, type WireToolDefinition, type WireToolCall, type TurnTimings, type TurnUsage, type ModelTurnResult, type TurnFn, type StopReason, type RunStats, } from "./turn";
+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";

package/contracts/index.js

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

package/contracts/turn.d.ts

@@ -1,16 +1,16 @@
 import type OpenAI from "openai";
 /**
- * Turn vocabulary — the shared language between the turn kernel (arriving in
- * a later extraction phase), LLM transports, and hosts.
+ * Turn vocabulary — the shared language between the turn kernel
+ * (`@juno-ai/bind/loop`), LLM transports, and hosts.
  *
  * The declared wire format is the OpenAI chat-completions message shape,
  * consumed as **types only** (`openai` is a peer used purely for its type
  * declarations here; no runtime import). Hosts on other client stacks (e.g.
  * the Vercel AI SDK) adapt at the turn-function boundary.
  *
- * NOTE: `ToolPlugin` / tool-context contracts deliberately do NOT live here
- * yet — they are being reshaped by the single-agent consolidation work in
- * the host repo and move here once that lands.
+ * The tool/plugin vocabulary is a separate contract and lives in `plugins/`,
+ * not here: this module is about what a turn *is* on the wire, while that one
+ * is about what a host can register and how the harness discloses it.
  */
 export type TranscriptMessage = OpenAI.ChatCompletionMessageParam;
 export type AssistantTurnMessage = OpenAI.ChatCompletionMessage;
@@ -18,8 +18,8 @@ export type WireToolDefinition = OpenAI.ChatCompletionTool;
 export type WireToolCall = OpenAI.ChatCompletionMessageToolCall;
 /**
  * Per-turn latency/throughput measurements. Field shapes deliberately match
- * the metrics the AA/StirrupJS harness reports (`speedStats`) so numbers are
- * directly comparable with published benchmark methodology:
+ * the metrics the StirrupJS benchmark harness reports (`speedStats`), so
+ * numbers are directly comparable with published benchmark methodology:
  * time-to-first-token, generation wall time, and output tokens/second —
  * plus the model-time vs tool-time split that per-task wall-clock hides.
  */
@@ -77,3 +77,27 @@ export declare function emptyRunStats(): RunStats;
 export declare function accumulateTurn(stats: RunStats, turn: ModelTurnResult): RunStats;
 /** Fold one dispatched tool call's duration into cumulative run stats. */
 export declare function accumulateToolCall(stats: RunStats, toolName: string, durationMs: number): RunStats;
+/**
+ * Fold a completed run's totals into another run's — the roll-up for a chain
+ * that spawned child runs (`@juno-ai/bind/run`).
+ *
+ * Two things follow from summing across runs rather than within one, and both
+ * are correct rather than artifacts:
+ *
+ *  - **`modelTimeMs` can exceed the chain's wall-clock**, because children that
+ *    ran concurrently each contribute their own. That is precisely why model
+ *    time and wall-clock are separate numbers; a chain's *cost* is the sum, its
+ *    *latency* is not.
+ *  - **`outputTokensPerSecond` is recomputed from the merged totals**, not
+ *    averaged from the parts. An average of two rates weights a 10-token run
+ *    the same as a 10,000-token one and reports a throughput neither run
+ *    achieved.
+ *
+ * The fold is associative and order-independent, so a chain reduces cleanly in
+ * whatever order its children finish:
+ *
+ * ```ts
+ * const chainTotals = childStats.reduce(accumulateRun, parentStats);
+ * ```
+ */
+export declare function accumulateRun(stats: RunStats, run: RunStats): RunStats;

package/contracts/turn.js

@@ -37,3 +37,48 @@ export function accumulateToolCall(stats, toolName, durationMs) {
         },
     };
 }
+/**
+ * Fold a completed run's totals into another run's — the roll-up for a chain
+ * that spawned child runs (`@juno-ai/bind/run`).
+ *
+ * Two things follow from summing across runs rather than within one, and both
+ * are correct rather than artifacts:
+ *
+ *  - **`modelTimeMs` can exceed the chain's wall-clock**, because children that
+ *    ran concurrently each contribute their own. That is precisely why model
+ *    time and wall-clock are separate numbers; a chain's *cost* is the sum, its
+ *    *latency* is not.
+ *  - **`outputTokensPerSecond` is recomputed from the merged totals**, not
+ *    averaged from the parts. An average of two rates weights a 10-token run
+ *    the same as a 10,000-token one and reports a throughput neither run
+ *    achieved.
+ *
+ * The fold is associative and order-independent, so a chain reduces cleanly in
+ * whatever order its children finish:
+ *
+ * ```ts
+ * const chainTotals = childStats.reduce(accumulateRun, parentStats);
+ * ```
+ */
+export function accumulateRun(stats, run) {
+    const outputTokens = stats.outputTokens + run.outputTokens;
+    const modelTimeMs = stats.modelTimeMs + run.modelTimeMs;
+    const toolTimeBreakdownMs = {
+        ...stats.toolTimeBreakdownMs,
+    };
+    for (const [toolName, durationMs] of Object.entries(run.toolTimeBreakdownMs)) {
+        toolTimeBreakdownMs[toolName] =
+            (toolTimeBreakdownMs[toolName] ?? 0) + durationMs;
+    }
+    return {
+        turns: stats.turns + run.turns,
+        toolCalls: stats.toolCalls + run.toolCalls,
+        inputTokens: stats.inputTokens + run.inputTokens,
+        outputTokens,
+        costCents: stats.costCents + run.costCents,
+        modelTimeMs,
+        toolTimeMs: stats.toolTimeMs + run.toolTimeMs,
+        outputTokensPerSecond: modelTimeMs > 0 ? (outputTokens / modelTimeMs) * 1000 : null,
+        toolTimeBreakdownMs,
+    };
+}

package/index.d.ts

@@ -5,9 +5,20 @@
  * completion into tool effects into the next turn's context. This package is
  * the harness that runs that chain.
  *
- * Current surface: the deterministic LLM provider-routing core (see
- * `docs/bind.md` and the LLM Provider Routing PRD). The turn kernel and tool
- * contracts move here in later extraction phases.
+ * Current surface: the tool-calling turn kernel (`src/loop/` — the iteration
+ * engine itself), the deterministic LLM provider-routing core, the turn
+ * vocabulary, the run mechanics (deadline, coalesced heartbeat, failure
+ * classification, tool-batch pooling, child-run lineage and admission),
+ * transcript validation/healing, provider tool-schema sanitization, and the
+ * plugin/tool vocabulary with its registry and progressive-disclosure
+ * activation — generic over the host's invocation context. 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.
  */
-export * from "./routing/index";
-export * from "./contracts/index";
+export * from "./routing/index.js";
+export * from "./contracts/index.js";
+export * from "./run/index.js";
+export * from "./transcript/index.js";
+export * from "./tools/index.js";
+export * from "./plugins/index.js";
+export * from "./loop/index.js";

package/index.js

@@ -5,9 +5,20 @@
  * completion into tool effects into the next turn's context. This package is
  * the harness that runs that chain.
  *
- * Current surface: the deterministic LLM provider-routing core (see
- * `docs/bind.md` and the LLM Provider Routing PRD). The turn kernel and tool
- * contracts move here in later extraction phases.
+ * Current surface: the tool-calling turn kernel (`src/loop/` — the iteration
+ * engine itself), the deterministic LLM provider-routing core, the turn
+ * vocabulary, the run mechanics (deadline, coalesced heartbeat, failure
+ * classification, tool-batch pooling, child-run lineage and admission),
+ * transcript validation/healing, provider tool-schema sanitization, and the
+ * plugin/tool vocabulary with its registry and progressive-disclosure
+ * activation — generic over the host's invocation context. 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.
  */
-export * from "./routing/index";
-export * from "./contracts/index";
+export * from "./routing/index.js";
+export * from "./contracts/index.js";
+export * from "./run/index.js";
+export * from "./transcript/index.js";
+export * from "./tools/index.js";
+export * from "./plugins/index.js";
+export * from "./loop/index.js";

package/loop/index.d.ts

@@ -0,0 +1 @@
+export { runToolLoop, type ToolLoopParams, type ToolLoopState, type ToolLoopTurn, type ToolCallOutcome, type CompactionApplied, type RunStatus, } from "./tool-loop.js";

package/loop/index.js

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

package/loop/tool-loop.d.ts

@@ -0,0 +1,260 @@
+import type OpenAI from "openai";
+/**
+ * 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
+ * updates, heartbeats, activity rows, persistence, cancellation — is injected,
+ * so the loop itself does no I/O and holds no host vocabulary.
+ *
+ * Three ports are worth understanding before wiring this up, because each
+ * replaced something the loop previously hardcoded:
+ *
+ *  - **`runsSerially`** decides which calls in a batch must run one at a time,
+ *    ahead of the rest. Not a performance knob: a call that changes what tools
+ *    exist has to take effect before a later call in the same batch tries to
+ *    use them.
+ *  - **`isFatalToolError`** decides which thrown errors abort the run instead
+ *    of becoming a tool error the model can read. Cancellation and "we failed
+ *    to record the result" belong here; a tool that simply failed does not.
+ *  - **`onToolCallRejected`** observes the errors that were synthesized rather
+ *    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.
+ */
+/** One model completion's message + the provider usage the loop accounts for. */
+export interface ToolLoopTurn {
+    message: OpenAI.ChatCompletionMessage;
+    inputTokens: number;
+    outputTokens: number;
+    costCents: number;
+}
+/**
+ * Outcome of running one tool call inside an assistant `tool_calls` batch.
+ *
+ * Every optional field is a **control signal**: the loop branches on it. They
+ * are not host payload passing through — `loadedPluginName` grows the active
+ * set, `requestCompaction` triggers a compaction at the batch boundary, and
+ * `suspend` ends the run. A host's own per-call data belongs inside
+ * `toolMessage`, which the loop only appends.
+ */
+export type ToolCallOutcome = {
+    toolMessage: OpenAI.ChatCompletionToolMessageParam;
+    /**
+     * A plugin this call activated; the loop adds it to the active set at once —
+     * but ONLY from the serial phase. A call that reaches the concurrent phase
+     * has already missed its window (a later call in the same batch could
+     * already be running), so this field is ignored there rather than applied
+     * late. Return it from a call your `runsSerially` selects, or it is dropped.
+     */
+    loadedPluginName?: string;
+    /** An instruction module this call loaded, passed to `activateSkills`. Serial phase only, as above. */
+    loadedSkillRef?: string;
+    /** Plugins the loaded module needs, activated before it. Serial phase only, as above. */
+    autoLoadedPlugins?: string[];
+    /** Compact the transcript at this batch's boundary. */
+    requestCompaction?: boolean;
+    /**
+     * End the run. `answer` records the open call and WITHHOLDS its tool message
+     * — the result is a human's future answer, threaded back on resume — so at
+     * most one may be open at a time; a second in the same batch is answered with
+     * an error rather than left unpaired. `wake` keeps its tool message and
+     * re-enters through a fresh prompt.
+     */
+    suspend?: {
+        toolCallId: string;
+        reason: string;
+        resumeKind: "answer" | "wake";
+        request?: unknown;
+    };
+};
+/**
+ * Result of compacting: the new transcript + the compaction call's own usage,
+ * plus a deferred `persist` step. The loop applies accounting + swaps the
+ * transcript BEFORE calling `persist`, so a persistence failure can't drop the
+ * tokens the compaction LLM call already consumed.
+ */
+export interface CompactionApplied {
+    messages: OpenAI.ChatCompletionMessageParam[];
+    inputTokens: number;
+    outputTokens: number;
+    costCents: number;
+    /** Persist the compacted session + activity row. Runs after accounting. */
+    persist: () => Promise<void>;
+}
+/**
+ * Mutable accumulator threaded through the loop. The caller seeds it and reads
+ * it back after; a shared object (rather than return values) lets the caller's
+ * coalesced heartbeat read live token totals mid-loop. `messages` is mutated in
+ * place (assistant + tool turns appended; replaced wholesale on compaction).
+ */
+export interface ToolLoopState {
+    messages: OpenAI.ChatCompletionMessageParam[];
+    inputTokens: number;
+    outputTokens: number;
+    costCents: number;
+    /** Provider prompt/completion tokens from the most recent turn (0 right after a compaction). */
+    lastPromptTokens: number;
+    lastOutputTokens: number;
+    /** True once any turn has produced a real provider count this run. */
+    hasFreshTokenCount: boolean;
+    /** Cumulative tool calls dispatched this run — the count only, never names or
+     *  results. Feeds a live progress indicator via `onProgressUpdate`. */
+    toolCalls: number;
+    /** True when the loop ended because a tool suspended the run (asked a human a
+     *  question, or scheduled its own resume). Distinguishes an intentional pause
+     *  from an iteration-limit cutoff — without it a caller reports "couldn't
+     *  finish" over a run that stopped exactly where it meant to. */
+    endedTurnViaTool?: boolean;
+    /** Set when a tool suspended the run awaiting an answer: the open tool-call is
+     *  waiting on a human or an external system. The loop withholds that call's
+     *  `tool` message — its result IS the future answer — and ends the run; a
+     *  resume threads the answer back as the matching `role:"tool"` result. At
+     *  most one may be open at a time; extras in the same batch are answered with
+     *  a synthesized error so no second slot is left unpaired. */
+    suspended?: {
+        toolCallId: string;
+        reason: string;
+        resumeKind: "answer";
+        request?: unknown;
+    };
+}
+export type RunStatus = "thinking" | "thinking_with_tools" | "executing_tools";
+export interface ToolLoopParams {
+    state: ToolLoopState;
+    /** Active plugin set — read to build tool defs, grown by `activatePlugins`. */
+    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
+     *  stream flows (throttled ~1 Hz inside the model call); the loop adds the
+     *  prior cumulative before forwarding to `onProgressUpdate`. */
+    callModel: (messages: OpenAI.ChatCompletionMessageParam[], tools: OpenAI.ChatCompletionTool[] | undefined, onOutputProgress?: (estimatedOutputTokens: number) => void) => Promise<ToolLoopTurn>;
+    /** Build the tool definitions for the current active-plugin set (+ MCP). */
+    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 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.
+     */
+    activateSkills: (skillRefs: string[]) => Promise<void> | void;
+    /**
+     * Must this call run on its own, before the rest of its batch?
+     *
+     * True for any call that changes what the later calls can do — activating a
+     * plugin, loading an instruction module. The loop runs those one at a time
+     * and applies each outcome immediately, so a dependent call in the SAME batch
+     * sees the effect. Everything else fans out concurrently, pooled per tool
+     * name.
+     *
+     * Unwired, nothing is serial: every call runs in the concurrent phase, which
+     * is correct for a host whose tools do not reshape the tool surface.
+     */
+    runsSerially?: (toolCall: OpenAI.ChatCompletionMessageToolCall) => boolean;
+    /**
+     * Should this thrown error abort the run rather than become a tool error the
+     * model reads?
+     *
+     * Two things belong here: **cancellation**, which must propagate even when no
+     * `ensureNotCancelled` observer is wired, and a failure to *record* an
+     * outcome — synthesizing "the tool failed" over a persistence failure tells
+     * the model a lie about work that may well have happened.
+     *
+     * Unwired, nothing is fatal: every failure is synthesized into a tool error
+     * and the run continues. That is the safe default for an isolated tool, and
+     * the wrong one as soon as your tools write anything.
+     */
+    isFatalToolError?: (error: unknown) => boolean;
+    /**
+     * A tool call failed and was answered with a synthesized error instead of
+     * throwing. The model sees it either way; without this observer nothing else
+     * does.
+     */
+    onToolCallRejected?: (toolCallId: string, error: unknown) => void;
+    /** Throw to abort (run cancelled). Checked at the top of each iteration and after each batch. */
+    ensureNotCancelled?: () => Promise<void> | void;
+    /** Throw a timeout error if the wall-clock budget is exhausted (checked first each iteration). */
+    throwIfTimedOut?: () => void;
+    /** Phase status for rich client feedback. */
+    onStatus?: (status: RunStatus) => void;
+    /** Intermediate assistant text emitted alongside tool calls. NOTE: when
+     *  `onAssistantMessage` is also wired, a text-with-tools message fires to BOTH
+     *  observers (they have different contracts — see below). Wire only one per
+     *  output surface so the same text isn't delivered twice. */
+    onThinking?: (content: string) => void;
+    /**
+     * Every assistant message that carries non-empty text content, fired the
+     * moment it's produced — whether or not it also requested tools, and including
+     * the final tool-less reply. Unlike `onThinking` (text-with-tools only), this
+     * sees ALL of a turn's assistant text, so a caller can stream each message to
+     * the client as it lands rather than batching them at turn end. Receives the
+     * already-trimmed content.
+     */
+    onAssistantMessage?: (content: string) => void;
+    /** Flush accumulated progress (heartbeat). Called force-true after each turn. */
+    flushProgress?: () => Promise<void> | void;
+    /** Cumulative live progress: the running output-token count (updated
+     *  mid-stream and after each model turn) and the number of tool calls made so
+     *  far this run (the count only — never a name or a result). Called with the
+     *  estimate during streaming and with real totals at each iteration boundary,
+     *  and again right after a batch is dispatched so the count rises promptly. */
+    onProgressUpdate?: (outputTokens: number, toolCalls: number) => void;
+    /** Return true to stop the loop after the current turn (e.g. agent disabled mid-run). */
+    shouldStop?: () => Promise<boolean> | boolean;
+    /**
+     * Called when the model produced a turn with NO tool calls — i.e. the loop is
+     * about to stop. Return a non-empty string to inject it as a synthetic `user`
+     * message and CONTINUE the loop instead of stopping; return null/empty to stop
+     * as normal (the default behavior when unwired). Use it to push a stalled turn
+     * forward — nudging an agent that ended a turn having made no progress at all.
+     * Receives the cumulative tool-call count so the hook can detect exactly that.
+     * MUST be self-bounding (eventually return null); `maxIterations` bounds it
+     * regardless, and the injected `user` message is model-only — a caller that
+     * persists a transcript should ignore `user` turns it didn't originate.
+     *
+     * `cumulativeToolCalls` is the running total across ALL iterations of this run
+     * (not just the current one), so a hook can detect "made zero tool calls the
+     * whole run" — a tool call in any earlier iteration makes it non-zero.
+     */
+    onTurnWouldEnd?: (assistantMessage: OpenAI.ChatCompletionMessage, cumulativeToolCalls: number) => string | null | Promise<string | null>;
+    /** Drain queued human interrupts for this run. */
+    drainInterrupts?: () => Array<{
+        userId: string;
+        content: string;
+    }>;
+    /** Report that an interrupt was received (activity row). */
+    onInterruptReceived?: (interrupt: {
+        userId: string;
+        content: string;
+    }) => Promise<void> | void;
+    /** Decide whether the live context (token count) needs auto-compaction. */
+    needsCompaction?: (currentTokens: number) => boolean;
+    /**
+     * Perform + persist a compaction and return the new transcript + usage. The
+     * loop owns swapping `state.messages` and resetting the live counts; this
+     * callback owns the LLM passes and persistence (session + activity row).
+     */
+    applyCompaction?: (trigger: "manual" | "auto", messages: OpenAI.ChatCompletionMessageParam[]) => Promise<CompactionApplied>;
+}
+/**
+ * Repeatedly call the model and execute the tools it requests, until it stops
+ * requesting them, a caller stops the loop, a tool suspends the run, or
+ * `maxIterations` is reached.
+ *
+ * Intrinsic: plugin/module activation, two-phase tool batching, compaction
+ * (manual + auto), interrupt draining, and the suspend protocol. Injected:
+ * every side effect — status, heartbeat, activity, persistence, cancellation.
+ *
+ * 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.
+ */
+export declare function runToolLoop(params: ToolLoopParams): Promise<void>;