@juno-ai/bind 2.0.0 → 4.0.0

package/loop/tool-loop.js

@@ -0,0 +1,276 @@
+import { runToolCallsPooledByTool } from "../run/tool-batch.js";
+/**
+ * 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 async function runToolLoop(params) {
+    const { state, maxIterations, callModel, buildTools, runToolCall, activatePlugins, activateSkills, ensureNotCancelled, throwIfTimedOut, onStatus, onThinking, onAssistantMessage, flushProgress, onProgressUpdate, shouldStop, onTurnWouldEnd, drainInterrupts, onInterruptReceived, needsCompaction, applyCompaction, runsSerially, isFatalToolError, onToolCallRejected, } = params;
+    // An observer must not be able to change control flow: a host logger that
+    // throws while reporting a tool failure would otherwise turn a *reported*
+    // failure into a fatal one, which is the opposite of what the report is for.
+    const reportRejection = (toolCallId, error) => {
+        try {
+            onToolCallRejected?.(toolCallId, error);
+        }
+        catch {
+            // Nothing useful to do — the reporting channel is the thing that broke.
+        }
+    };
+    // Swap in a freshly-compacted transcript and reset the live counts. The
+    // provider count no longer reflects the compacted array, so drop it — the
+    // auto-compaction check skips while it's 0 (preventing an immediate
+    // re-trigger), and the next turn records a fresh real count.
+    const applyCompactionResult = (result) => {
+        state.inputTokens += result.inputTokens;
+        state.outputTokens += result.outputTokens;
+        state.costCents += result.costCents;
+        state.messages.length = 0;
+        state.messages.push(...result.messages);
+        state.lastPromptTokens = 0;
+        state.lastOutputTokens = 0;
+    };
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        throwIfTimedOut?.();
+        await ensureNotCancelled?.();
+        const tools = buildTools();
+        onStatus?.(iteration === 0 ? "thinking" : "thinking_with_tools");
+        // Stream live token progress: the per-call estimate is added to the cumulative
+        // from prior iterations so a caller's counter rises monotonically across a
+        // multi-iteration run. The real cumulative is published right after the call
+        // returns (below), reconciling any estimate drift.
+        const baseOutputTokens = state.outputTokens;
+        const result = await callModel(state.messages, tools.length > 0 ? tools : undefined, 
+        // Carry the cumulative tool count alongside the streamed token estimate so
+        // the pill shows both; no tools run *during* a model call, so the count is
+        // whatever has accumulated from prior iterations.
+        onProgressUpdate
+            ? (estCallTokens) => onProgressUpdate(baseOutputTokens + estCallTokens, state.toolCalls)
+            : undefined);
+        state.inputTokens += result.inputTokens;
+        state.outputTokens += result.outputTokens;
+        state.costCents += result.costCents;
+        state.lastPromptTokens = result.inputTokens;
+        state.lastOutputTokens = result.outputTokens;
+        state.hasFreshTokenCount = true;
+        const assistantMessage = result.message;
+        state.messages.push(assistantMessage);
+        if (assistantMessage.content && assistantMessage.tool_calls?.length) {
+            onThinking?.(assistantMessage.content);
+        }
+        // Stream every assistant text message (with or without tool calls, including
+        // the final tool-less reply) so a caller can surface it the moment it lands.
+        if (typeof assistantMessage.content === "string") {
+            const trimmed = assistantMessage.content.trim();
+            if (trimmed)
+                onAssistantMessage?.(trimmed);
+        }
+        // Force-flush progress so each iteration bumps the heartbeat at least once.
+        await flushProgress?.();
+        // Mid-run stop (e.g. the agent was disabled while running). Emit the
+        // iteration's final progress (the real cumulative token total) before bailing.
+        if (await shouldStop?.()) {
+            onProgressUpdate?.(state.outputTokens, state.toolCalls);
+            break;
+        }
+        // Count this iteration's tool batch (a single iteration can request several
+        // tools at once) BEFORE the single progress emit, so the new tool count rides
+        // the SAME frame as the iteration's real token total. A separate
+        // post-increment emit would be coalesced by a throttled transport and lag
+        // the count behind the tokens it belongs with.
+        const toolCalls = assistantMessage.tool_calls;
+        if (toolCalls && toolCalls.length > 0)
+            state.toolCalls += toolCalls.length;
+        onProgressUpdate?.(state.outputTokens, state.toolCalls);
+        if (!toolCalls || toolCalls.length === 0) {
+            // The model stopped calling tools — normally the turn is done. Give a
+            // caller a chance to push it forward instead: if `onTurnWouldEnd` returns
+            // text, inject it as a synthetic user message and keep looping. The hook
+            // is self-bounding and `maxIterations` is the hard ceiling, so this cannot
+            // spin forever.
+            const nudge = await onTurnWouldEnd?.(assistantMessage, state.toolCalls);
+            if (nudge && nudge.trim()) {
+                state.messages.push({ role: "user", content: nudge });
+                continue;
+            }
+            break;
+        }
+        onStatus?.("executing_tools");
+        // Two-phase batch: run activation calls (`tool-discovery__load_plugin` and
+        // `skills__load_skill`) SERIALLY and activate each immediately (so a
+        // dependent tool from the same batch sees the plugin active / the skill's
+        // owner plugin loaded), then run the rest concurrently, pooled per tool
+        // name. Outcomes are collected by original index and applied in emission
+        // order.
+        const outcomes = new Array(toolCalls.length);
+        const deferredIndices = [];
+        const deferredCalls = [];
+        for (let i = 0; i < toolCalls.length; i++) {
+            const tc = toolCalls[i];
+            if (runsSerially?.(tc)) {
+                // Mirror the concurrent batch's graceful error synthesis so a failing
+                // activation call (transient network/DB/timeout) doesn't crash the
+                // run — but let a fatal error propagate for an immediate abort.
+                try {
+                    const outcome = await runToolCall(tc);
+                    outcomes[i] = outcome;
+                    if (outcome.loadedPluginName) {
+                        activatePlugins([outcome.loadedPluginName]);
+                    }
+                    if (outcome.loadedSkillRef) {
+                        // Auto-load the module's owner plugin first so its tools are active
+                        // by the time the agent follows the freshly-injected instructions.
+                        if (outcome.autoLoadedPlugins?.length) {
+                            activatePlugins(outcome.autoLoadedPlugins);
+                        }
+                        await activateSkills([outcome.loadedSkillRef]);
+                    }
+                }
+                catch (err) {
+                    if (isFatalToolError?.(err))
+                        throw err;
+                    reportRejection(tc.id, err);
+                    outcomes[i] = {
+                        toolMessage: {
+                            role: "tool",
+                            tool_call_id: tc.id,
+                            content: JSON.stringify({
+                                success: false,
+                                error: err instanceof Error ? err.message : String(err),
+                            }),
+                        },
+                    };
+                }
+                continue;
+            }
+            deferredIndices.push(i);
+            deferredCalls.push(tc);
+        }
+        const settled = await runToolCallsPooledByTool(deferredCalls, runToolCall);
+        for (let j = 0; j < deferredCalls.length; j++) {
+            const origIndex = deferredIndices[j];
+            const call = deferredCalls[j];
+            const settledResult = settled[j];
+            if (settledResult.status === "fulfilled") {
+                outcomes[origIndex] = settledResult.value;
+            }
+            else {
+                // Let a fatal error abort the run immediately rather than be
+                // synthesized into a tool error — symmetric with the serial path, and
+                // so cancellation propagates even if no `ensureNotCancelled` boundary
+                // observer is wired.
+                if (isFatalToolError?.(settledResult.reason))
+                    throw settledResult.reason;
+                reportRejection(call.id, settledResult.reason);
+                outcomes[origIndex] = {
+                    toolMessage: {
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: JSON.stringify({
+                            success: false,
+                            error: settledResult.reason instanceof Error
+                                ? settledResult.reason.message
+                                : String(settledResult.reason),
+                        }),
+                    },
+                };
+            }
+        }
+        let compactionRequested = false;
+        let suspendRequested = false;
+        for (const outcome of outcomes) {
+            // An `answer`-suspend WITHHOLDS its tool message — the result is the
+            // future answer, threaded back on resume. At most one may be open: the
+            // first becomes `state.suspended`; any additional suspend in the same
+            // batch is answered with a synthesized error so no second slot is left
+            // unpaired. A `wake`-suspend keeps its tool message (it re-enters through
+            // a fresh prompt, not a threaded answer).
+            if (outcome.suspend) {
+                suspendRequested = true;
+                if (outcome.suspend.resumeKind === "answer") {
+                    if (!state.suspended) {
+                        // Rebuild with the literal "answer" kind so the assignment matches
+                        // `ToolLoopState.suspended` (always answer — see its type).
+                        state.suspended = { ...outcome.suspend, resumeKind: "answer" };
+                        continue; // withhold this call's tool message
+                    }
+                    state.messages.push({
+                        role: "tool",
+                        tool_call_id: outcome.suspend.toolCallId,
+                        content: JSON.stringify({
+                            success: false,
+                            error: "You already have one question waiting for an answer, so this " +
+                                "one was not asked. Wait for the pending answer and then ask " +
+                                "this, or finish the turn with what you have.",
+                        }),
+                    });
+                    continue;
+                }
+                // `wake` (e.g. sleep_until): fall through and push the tool message, then
+                // end the run — it re-enters via a prompt, not a threaded answer.
+            }
+            state.messages.push(outcome.toolMessage);
+            if (outcome.requestCompaction)
+                compactionRequested = true;
+        }
+        // A tool asked to end the run (it scheduled its own resume, or recorded an
+        // open call awaiting an answer). The tool results are already in
+        // state.messages above; stop now so the run doesn't keep going. Mark it as
+        // an intentional pause so a caller doesn't read the trailing tool-calling
+        // turn as an iteration-limit cutoff. Honor an explicit
+        // compaction requested in the same batch so the saved transcript is
+        // compacted — UNLESS a suspend is pending: compacting would rewrite the open
+        // suspended call, and that pair must survive verbatim to be resumable.
+        if (suspendRequested) {
+            if (compactionRequested && applyCompaction && !state.suspended) {
+                const compacted = await applyCompaction("manual", state.messages);
+                applyCompactionResult(compacted);
+                await compacted.persist();
+            }
+            state.endedTurnViaTool = true;
+            break;
+        }
+        await ensureNotCancelled?.();
+        // Explicit (tool-requested) compaction, flushed at the batch boundary so
+        // the summary sees the full batch of tool responses. Account for the
+        // compaction usage BEFORE persisting so a persist failure can't drop the
+        // tokens it already consumed.
+        if (compactionRequested && applyCompaction) {
+            const compacted = await applyCompaction("manual", state.messages);
+            applyCompactionResult(compacted);
+            await compacted.persist();
+        }
+        // Drain human interrupts queued while the agent was working.
+        for (const interrupt of drainInterrupts?.() ?? []) {
+            // Strip control chars/newlines from the id so it can't break out of the
+            // `[Interrupt from user …]` header line and inject transcript structure.
+            // (Internal-only sources today, but a future external caller could surface
+            // user-supplied ids.)
+            const safeUserId = interrupt.userId.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, "");
+            state.messages.push({
+                role: "user",
+                content: `[Interrupt from user ${safeUserId}]\n${interrupt.content}`,
+            });
+            await onInterruptReceived?.(interrupt);
+        }
+        // Auto-compaction using the provider's real token count. Skip when there's
+        // no fresh count (before the first call, or right after a compaction reset
+        // it to 0) so we don't immediately re-trigger.
+        const currentTokens = state.lastPromptTokens + state.lastOutputTokens;
+        if (state.lastPromptTokens > 0 &&
+            needsCompaction?.(currentTokens) &&
+            applyCompaction) {
+            const compacted = await applyCompaction("auto", state.messages);
+            applyCompactionResult(compacted);
+            await compacted.persist();
+        }
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juno-ai/bind",
-  "version": "2.0.0",
-  "description": "Agent harness: deterministic LLM provider routing core and turn contracts (turn kernel arrives in later phases). MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
+  "version": "4.0.0",
+  "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
@@ -18,6 +18,26 @@
     "./contracts": {
       "types": "./contracts/index.d.ts",
       "import": "./contracts/index.js"
+    },
+    "./loop": {
+      "types": "./loop/index.d.ts",
+      "import": "./loop/index.js"
+    },
+    "./run": {
+      "types": "./run/index.d.ts",
+      "import": "./run/index.js"
+    },
+    "./transcript": {
+      "types": "./transcript/index.d.ts",
+      "import": "./transcript/index.js"
+    },
+    "./tools": {
+      "types": "./tools/index.d.ts",
+      "import": "./tools/index.js"
+    },
+    "./plugins": {
+      "types": "./plugins/index.d.ts",
+      "import": "./plugins/index.js"
     }
   },
   "peerDependencies": {

package/plugins/activation.d.ts

@@ -0,0 +1,67 @@
+import type { PluginSummary } from "./registry.js";
+/**
+ * Progressive tool disclosure: which plugins are loaded right now, and how a
+ * persisted set is restored across a run boundary.
+ *
+ * Two-tier disclosure exists because tool-selection accuracy degrades once a
+ * model sees more than a few dozen tools, and because every tool's JSON Schema
+ * is resent on every turn. Core plugins load unconditionally; the rest are
+ * announced as a compact catalog and activated on demand.
+ *
+ * The governing rule for restoring a persisted set is that **it is a hint, not
+ * a fact**. Names are persisted; implementations are resolved at load time, and
+ * anything that no longer resolves is dropped rather than reported as active —
+ * a plugin can be renamed, gated off, or (for a dynamically connected one) fail
+ * to reconnect between runs.
+ */
+/** Why a persisted activation could not be restored. */
+export type ActivationDropReason = "unknown" | "unavailable" | "unreachable" | "error";
+export interface DroppedActivation {
+    /** The canonicalized name that was dropped. */
+    name: string;
+    reason: ActivationDropReason;
+}
+export interface RehydrateResult {
+    /** Canonicalized, de-duplicated names that resolved and stay active. */
+    active: string[];
+    /** Everything that did not survive, for the host to log. */
+    dropped: DroppedActivation[];
+}
+export interface RehydrateOptions {
+    /** Map a persisted (possibly legacy) name to its current canonical name. */
+    canonicalizeName: (name: string) => string;
+    /**
+     * Can this name be activated on THIS run? Async because restoring a
+     * dynamically connected plugin may require re-establishing a connection —
+     * the harness owns the policy, the host owns the transport.
+     *
+     * Return `true` to keep, or a drop reason to discard.
+     */
+    resolve: (name: string) => ActivationDropReason | true | Promise<ActivationDropReason | true>;
+    /**
+     * Observe a resolver rejection. The entry is dropped as `"error"` either way,
+     * and an observer that throws is swallowed — reporting a failure must not
+     * turn one bad name into a failed restore.
+     */
+    onResolveError?: (name: string, error: unknown) => void;
+}
+/**
+ * Restore a persisted activation set, re-validating every entry against
+ * current reality. Order is preserved; duplicates (including two legacy names
+ * that canonicalize to the same plugin) collapse to the first occurrence.
+ */
+export declare function rehydrateActivation(persisted: readonly string[], options: RehydrateOptions): Promise<RehydrateResult>;
+/** The activation set a fresh run starts from. */
+export declare function initialActivePlugins(corePlugins: readonly string[]): string[];
+export interface CatalogPartition {
+    active: PluginSummary[];
+    loadable: PluginSummary[];
+}
+/**
+ * Split the catalog into what is already active and what the model may load.
+ *
+ * This returns **data, not prose**: the wording of a catalog belongs to the
+ * host's system prompt, which is a product surface with its own voice and
+ * (in Monad's case) its own byte-for-byte prompt-cache concerns.
+ */
+export declare function partitionPluginCatalog(activePlugins: ReadonlySet<string>, allSummaries: readonly PluginSummary[]): CatalogPartition;

package/plugins/activation.js

@@ -0,0 +1,61 @@
+/**
+ * Restore a persisted activation set, re-validating every entry against
+ * current reality. Order is preserved; duplicates (including two legacy names
+ * that canonicalize to the same plugin) collapse to the first occurrence.
+ */
+export async function rehydrateActivation(persisted, options) {
+    const active = [];
+    const dropped = [];
+    const seen = new Set();
+    for (const rawName of persisted) {
+        const name = options.canonicalizeName(rawName);
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        // A throwing resolver drops its entry rather than failing the walk. The
+        // contract is best-effort restoration, and a host resolver that reaches a
+        // database or decrypts a credential can reject transiently — one bad name
+        // must not cost the caller every other restored plugin.
+        let verdict;
+        try {
+            verdict = await options.resolve(name);
+        }
+        catch (error) {
+            try {
+                options.onResolveError?.(name, error);
+            }
+            catch {
+                // An observer that throws (a logger choking on a circular error, a
+                // metrics client rejecting) would otherwise defeat the very guarantee
+                // this catch exists to provide.
+            }
+            // Not `unreachable`: that reason means a dynamic plugin failed to
+            // reconnect, and a resolver can just as well throw while checking a
+            // static plugin. Reporting the failure as its own kind keeps the host's
+            // drop logging honest about what it knows.
+            verdict = "error";
+        }
+        if (verdict === true)
+            active.push(name);
+        else
+            dropped.push({ name, reason: verdict });
+    }
+    return { active, dropped };
+}
+/** The activation set a fresh run starts from. */
+export function initialActivePlugins(corePlugins) {
+    return [...new Set(corePlugins)];
+}
+/**
+ * Split the catalog into what is already active and what the model may load.
+ *
+ * This returns **data, not prose**: the wording of a catalog belongs to the
+ * host's system prompt, which is a product surface with its own voice and
+ * (in Monad's case) its own byte-for-byte prompt-cache concerns.
+ */
+export function partitionPluginCatalog(activePlugins, allSummaries) {
+    return {
+        active: allSummaries.filter((summary) => activePlugins.has(summary.name)),
+        loadable: allSummaries.filter((summary) => !activePlugins.has(summary.name)),
+    };
+}

package/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export { hasContentParts, type ToolAnnotations, type ToolDef, type ToolFailureKind, type ToolPlugin, type ToolResult, type RegistrablePlugin, type SuspendDirective, } from "./tool.js";
+export { createToolRegistry, type PluginSummary, type ToolRegistry, type ToolRegistryOptions, } from "./registry.js";
+export { rehydrateActivation, initialActivePlugins, partitionPluginCatalog, type ActivationDropReason, type CatalogPartition, type DroppedActivation, type RehydrateOptions, type RehydrateResult, } from "./activation.js";

package/plugins/index.js

@@ -0,0 +1,3 @@
+export { hasContentParts, } from "./tool.js";
+export { createToolRegistry, } from "./registry.js";
+export { rehydrateActivation, initialActivePlugins, partitionPluginCatalog, } from "./activation.js";

package/plugins/registry.d.ts

@@ -0,0 +1,52 @@
+import type { RegistrablePlugin } from "./tool.js";
+/**
+ * A plugin registry, created as a **factory rather than a module singleton**.
+ *
+ * Monad's original registry was a module-level `Map` populated by
+ * self-registration at import time. That is workable in a long-lived Node
+ * process but wrong for a package targeting workerd isolates (module state is
+ * per-isolate and its lifetime is not the host's) and it makes tests share
+ * state implicitly. A host that wants the singleton ergonomics can still wrap
+ * one instance in a module — the choice moves to the host, which is where it
+ * belongs.
+ */
+export interface PluginSummary {
+    name: string;
+    description: string;
+    isCorePlugin: boolean;
+}
+export interface ToolRegistryOptions<TPlugin extends RegistrablePlugin> {
+    /**
+     * Always-active plugins, loaded on every run without explicit activation.
+     */
+    corePlugins: readonly string[];
+    /**
+     * Compatibility aliases for historical plugin names, mapping an old name to
+     * the current canonical one. Persisted activation state stores names, so an
+     * alias is how a rename avoids silently stripping capabilities from live
+     * sessions without a data migration. Entries are permanent.
+     */
+    aliases?: Readonly<Record<string, string>>;
+    /**
+     * Called after a plugin is registered. The seam for host-side side effects
+     * of registration (e.g. contributing a plugin's skills into a separate
+     * registry) without the harness knowing what those are.
+     */
+    onRegister?: (plugin: TPlugin) => void;
+}
+export interface ToolRegistry<TPlugin extends RegistrablePlugin> {
+    register(plugin: TPlugin): void;
+    /** Resolve by name (following aliases); `undefined` when absent or unavailable. */
+    get(name: string): TPlugin | undefined;
+    /** The canonical registered name for `name`, following any alias. */
+    canonicalizeName(name: string): string;
+    corePlugins(): string[];
+    isCoreName(name: string): boolean;
+    /** Every registered plugin, including currently-unavailable ones. */
+    all(): TPlugin[];
+    /** Summaries of available plugins only. */
+    summaries(): PluginSummary[];
+    /** Names of available plugins — the single source of truth for "what exists". */
+    availableNames(): string[];
+}
+export declare function createToolRegistry<TPlugin extends RegistrablePlugin>(options: ToolRegistryOptions<TPlugin>): ToolRegistry<TPlugin>;

package/plugins/registry.js

@@ -0,0 +1,54 @@
+export function createToolRegistry(options) {
+    const plugins = new Map();
+    const core = [...new Set(options.corePlugins)];
+    const coreSet = new Set(core);
+    const aliases = options.aliases ?? {};
+    // Own-property check, not `aliases[name] ?? name`: a bare index reads
+    // through Object.prototype, so a lookup of "constructor" or "toString"
+    // returns an inherited function instead of the name. Hosts supply arbitrary
+    // alias maps, and a plugin may legitimately be named either.
+    //
+    // The `typeof` check is not redundant with the declared type: a host may
+    // build its alias map from JSON or another untyped source, and this function
+    // is a hard invariant — every caller downstream treats the result as a
+    // string. Falling back to the input beats returning a lie.
+    const canonicalizeName = (name) => {
+        if (!Object.prototype.hasOwnProperty.call(aliases, name))
+            return name;
+        const alias = aliases[name];
+        return typeof alias === "string" ? alias : name;
+    };
+    const isAvailable = (plugin) => plugin.isAvailable?.() ?? true;
+    return {
+        register(plugin) {
+            plugins.set(plugin.name, plugin);
+            options.onRegister?.(plugin);
+        },
+        get(name) {
+            const plugin = plugins.get(name) ?? plugins.get(canonicalizeName(name));
+            return plugin && isAvailable(plugin) ? plugin : undefined;
+        },
+        canonicalizeName,
+        corePlugins() {
+            return [...core];
+        },
+        isCoreName(name) {
+            return coreSet.has(name);
+        },
+        all() {
+            return [...plugins.values()];
+        },
+        summaries() {
+            return [...plugins.values()].filter(isAvailable).map((plugin) => ({
+                name: plugin.name,
+                description: plugin.description,
+                isCorePlugin: coreSet.has(plugin.name),
+            }));
+        },
+        availableNames() {
+            return [...plugins.values()]
+                .filter(isAvailable)
+                .map((plugin) => plugin.name);
+        },
+    };
+}