@juno-ai/bind 5.0.0 → 7.0.0

package/completion/tool-calls.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Reading a tool call the model asked for.
+ *
+ * This is the dispatch half of a rule whose other half lives in
+ * `defects.ts`, and the two only work if they agree. `detectCompletionDefect`
+ * decides that a tool call with *empty* arguments is legitimate — the normal
+ * zero-argument shape, not a truncation — and passes it through to be run.
+ * Something then has to run it, and that something has to reach the same
+ * conclusion: empty arguments mean no arguments, not malformed JSON.
+ *
+ * Splitting those halves across a package boundary is how the original bug
+ * happened. Providers send `""` for a zero-arg call as readily as `"{}"`, the
+ * dispatcher fed `""` to `JSON.parse`, and a perfectly good call died as
+ * "Invalid JSON in tool arguments" — a whole recovery turn spent on a turn
+ * that was never broken. A host adopting only the detection half inherits the
+ * permissive decision and has to independently invent the matching parse.
+ *
+ * So both halves read {@link toolCallArgumentsAbsent}. One definition, and a
+ * change to what "absent" means cannot update one side and miss the other.
+ */
+/**
+ * The shape this module reads. Structural rather than tied to an SDK's class,
+ * and `type` is optional because a host assembling calls by hand may not carry
+ * one — its absence is treated as the ordinary function call it almost always
+ * is, while a *present* non-function type is refused.
+ */
+export interface DispatchableToolCall {
+    readonly type?: string | undefined;
+    readonly function?: {
+        readonly name?: string | undefined;
+        readonly arguments?: string | undefined;
+    } | undefined;
+}
+/**
+ * Whether a tool call carried no arguments at all.
+ *
+ * Whitespace counts as absent: a provider that pads its zero-arg payload is
+ * still saying "no arguments", and treating `"  "` as content sends it to a
+ * JSON parse that can only fail.
+ */
+export declare function toolCallArgumentsAbsent(rawArguments: string): boolean;
+/**
+ * What a tool call's arguments turned out to be.
+ *
+ * A tagged union rather than a throw, because every outcome here has to end
+ * with the host emitting a `tool` message for this call's id. A transcript
+ * where an assistant asked for a tool and no `tool` message answers it is
+ * rejected by the provider on the *next* request, so "give up on this call"
+ * is never an option — only "dispatch it" or "answer it with an error".
+ */
+export type ToolCallArguments = 
+/** Dispatch with these. `{}` for a legitimate zero-argument call. */
+{
+    kind: "parsed";
+    arguments: Record<string, unknown>;
+}
+/**
+ * Not a function call, so there is nothing to dispatch. Present in the
+ * OpenAI union (`type: "custom"`) and in whatever a future provider adds.
+ */
+ | {
+    kind: "unsupported_type";
+    type: string;
+}
+/**
+ * Arguments that cannot be used: either not JSON at all, or JSON that is not
+ * an object.
+ *
+ * The two have different histories, which matters for how the host words the
+ * error. A *syntax* failure by this point is a real error rather than a
+ * truncation — a cut-off stream is caught upstream by
+ * `detectCompletionDefect` and retried, so anything still unparseable here
+ * survived that. A payload that parsed but is not an object was never
+ * eligible for that retry (it parses fine), so the model's next turn is its
+ * only correction — which is why {@link detail} names what was wrong, and
+ * why a host should put it in front of the model rather than only in a log.
+ */
+ | {
+    kind: "unparseable";
+    detail: string;
+};
+/**
+ * Read a tool call's arguments, or say why it cannot be dispatched.
+ *
+ * A parsed value that is not a JSON object — `"null"`, `"[]"`, `"42"`, all
+ * valid JSON — is refused rather than passed on. Tool arguments are a named
+ * parameter bag by definition, and handing a tool an array where it expects
+ * fields turns a clear failure here into a confusing one inside the tool.
+ */
+export declare function parseToolCallArguments(toolCall: DispatchableToolCall): ToolCallArguments;

package/completion/tool-calls.js

@@ -0,0 +1,67 @@
+/**
+ * Reading a tool call the model asked for.
+ *
+ * This is the dispatch half of a rule whose other half lives in
+ * `defects.ts`, and the two only work if they agree. `detectCompletionDefect`
+ * decides that a tool call with *empty* arguments is legitimate — the normal
+ * zero-argument shape, not a truncation — and passes it through to be run.
+ * Something then has to run it, and that something has to reach the same
+ * conclusion: empty arguments mean no arguments, not malformed JSON.
+ *
+ * Splitting those halves across a package boundary is how the original bug
+ * happened. Providers send `""` for a zero-arg call as readily as `"{}"`, the
+ * dispatcher fed `""` to `JSON.parse`, and a perfectly good call died as
+ * "Invalid JSON in tool arguments" — a whole recovery turn spent on a turn
+ * that was never broken. A host adopting only the detection half inherits the
+ * permissive decision and has to independently invent the matching parse.
+ *
+ * So both halves read {@link toolCallArgumentsAbsent}. One definition, and a
+ * change to what "absent" means cannot update one side and miss the other.
+ */
+/**
+ * Whether a tool call carried no arguments at all.
+ *
+ * Whitespace counts as absent: a provider that pads its zero-arg payload is
+ * still saying "no arguments", and treating `"  "` as content sends it to a
+ * JSON parse that can only fail.
+ */
+export function toolCallArgumentsAbsent(rawArguments) {
+    return rawArguments.trim().length === 0;
+}
+/**
+ * Read a tool call's arguments, or say why it cannot be dispatched.
+ *
+ * A parsed value that is not a JSON object — `"null"`, `"[]"`, `"42"`, all
+ * valid JSON — is refused rather than passed on. Tool arguments are a named
+ * parameter bag by definition, and handing a tool an array where it expects
+ * fields turns a clear failure here into a confusing one inside the tool.
+ */
+export function parseToolCallArguments(toolCall) {
+    if (toolCall.type !== undefined && toolCall.type !== "function") {
+        return { kind: "unsupported_type", type: toolCall.type };
+    }
+    const raw = toolCall.function?.arguments;
+    if (typeof raw !== "string" || toolCallArgumentsAbsent(raw)) {
+        // The empty case and the missing case are the same call: the model named a
+        // tool and gave it nothing, which is what a zero-argument tool looks like.
+        return { kind: "parsed", arguments: {} };
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            kind: "unparseable",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        // `typeof` alone is not a usable name here: it reports both `null` and an
+        // array as "object", so the two payloads most likely to arrive would be
+        // described as the very thing they were rejected for not being.
+        const got = value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
+        return { kind: "unparseable", detail: `expected a JSON object, got ${got}` };
+    }
+    return { kind: "parsed", arguments: value };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "5.0.0",
+  "version": "7.0.0",
   "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, 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",

package/routing/errors.d.ts

@@ -66,6 +66,26 @@ export interface FailureDisposition {
     /** Return to the caller immediately; no further traversal. */
     readonly propagate: boolean;
 }
+/**
+ * The disposition for a failure whose attempt **already produced output the
+ * caller cannot take back** — tokens streamed to a UI, or a provider-side
+ * effect a replay would repeat.
+ *
+ * Every other input to `failureDisposition` is a property of the *error*. This
+ * one is a property of the *attempt*, and only the host knows it: a transport
+ * that buffers the whole completion before returning can always replay, and one
+ * that forwards deltas to a live view cannot. So it arrives as a fact on the
+ * failure outcome rather than as another arm of the taxonomy.
+ *
+ * Traversal is withheld entirely — not just the same-endpoint retry. Trying the
+ * next provider re-renders the same turn, which is the same duplication with a
+ * different label on it.
+ *
+ * The **breaker effect is preserved**: the endpoint really did fail, and that is
+ * true regardless of how far the response got. Suppressing it here would hide a
+ * dying endpoint from every later call precisely because it dies late.
+ */
+export declare function propagateOnly(disposition: FailureDisposition): FailureDisposition;
 /**
  * The exhaustive failure → routing-behavior matrix (PRD §7.1). Pure; the
  * executor applies it, the circuit breaker consumes its `breaker` effect.

package/routing/errors.js

@@ -39,6 +39,36 @@ const CREDENTIAL_FAILURE = Object.freeze({
     breaker: "open_immediately",
     propagate: false,
 });
+/**
+ * The disposition for a failure whose attempt **already produced output the
+ * caller cannot take back** — tokens streamed to a UI, or a provider-side
+ * effect a replay would repeat.
+ *
+ * Every other input to `failureDisposition` is a property of the *error*. This
+ * one is a property of the *attempt*, and only the host knows it: a transport
+ * that buffers the whole completion before returning can always replay, and one
+ * that forwards deltas to a live view cannot. So it arrives as a fact on the
+ * failure outcome rather than as another arm of the taxonomy.
+ *
+ * Traversal is withheld entirely — not just the same-endpoint retry. Trying the
+ * next provider re-renders the same turn, which is the same duplication with a
+ * different label on it.
+ *
+ * The **breaker effect is preserved**: the endpoint really did fail, and that is
+ * true regardless of how far the response got. Suppressing it here would hide a
+ * dying endpoint from every later call precisely because it dies late.
+ */
+export function propagateOnly(disposition) {
+    if (disposition.propagate)
+        return disposition;
+    return Object.freeze({
+        sameEndpointRetry: false,
+        nextProvider: false,
+        fallbackModel: false,
+        breaker: disposition.breaker,
+        propagate: true,
+    });
+}
 /**
  * The exhaustive failure → routing-behavior matrix (PRD §7.1). Pure; the
  * executor applies it, the circuit breaker consumes its `breaker` effect.

package/routing/executor.d.ts

@@ -7,6 +7,18 @@ export type AttemptOutcome<T> = Readonly<{
 }> | Readonly<{
     kind: "failure";
     error: InferenceAttemptError;
+    /**
+     * This attempt already put output somewhere the caller cannot take it
+     * back — tokens forwarded to a live view, or a provider-side effect a
+     * replay would repeat. The executor then **withholds all traversal** and
+     * propagates, because retrying re-renders a turn the user has partly seen.
+     *
+     * Omitted means replayable, which is right for a transport that buffers
+     * the whole completion before returning — it has shown nobody anything
+     * yet. Set it from the transport, at the point the first byte leaves:
+     * a boolean the transport flips when it forwards its first delta.
+     */
+    producedOutput?: boolean;
 }>;
 /**
  * One provider request. The host's transport adapter performs the network

package/routing/executor.js

@@ -1,4 +1,4 @@
-import { failureDisposition, isRetriableAttemptError, } from "./errors.js";
+import { failureDisposition, propagateOnly, isRetriableAttemptError, } from "./errors.js";
 /**
  * Drive one structured-output attempt over a frozen route plan with the
  * normative loop nesting (PRD §5.2): model stage → provider candidate →
@@ -71,7 +71,12 @@ export async function executeRoutePlan(options) {
                     };
                 }
                 failures.push(outcome.error);
-                const disposition = failureDisposition(outcome.error);
+                // The clamp is applied to the taxonomy's answer rather than folded into
+                // it, so `failureDisposition` stays total over the error kinds and this
+                // stays one testable step. See `propagateOnly`.
+                const disposition = outcome.producedOutput === true
+                    ? propagateOnly(failureDisposition(outcome.error))
+                    : failureDisposition(outcome.error);
                 switch (disposition.breaker) {
                     case "none":
                         // A breaker-invisible failure (abort, propagated client error)

package/routing/index.d.ts

@@ -6,7 +6,7 @@ export { buildRoutePlan, type RoutePlanRequest, type RoutePlanResult } from "./p
 export { buildRoutePlanWithConfigDegradation, type DegradedStage, type DegradedPlanResult, } from "./plan-degradation.js";
 export { computeConfiguredRatesCostCents, type BillingBasisUsage, type BillingBasisResult, } from "./billing-basis.js";
 export { fallbackKindOfCursor } from "./executor.js";
-export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, type RouteAttemptCursor, type AttemptTarget, type HttpFailureCategory, type InferenceAttemptError, type FailureDisposition, type BreakerEffect, } from "./errors.js";
+export { failureDisposition, propagateOnly, categorizeHttpStatus, isRetriableAttemptError, type RouteAttemptCursor, type AttemptTarget, type HttpFailureCategory, type InferenceAttemptError, type FailureDisposition, type BreakerEffect, } from "./errors.js";
 export { classifyAttemptError, retryAfterMsFromHeaders, isAbortByName, type AttemptClassification, type TransportFailure, type TransportFailureKind, } from "./attempt-errors.js";
 export { createCircuitBreaker, type BreakerKey, type CircuitBreakerOptions, type EndpointAdmission, type RecordFailureOptions, type RouteCircuitBreaker, } from "./circuit-breaker.js";
 export { executeRoutePlan, type AttemptOutcome, type AttemptFn, type FallbackKind, type ExecutePlanOptions, type RouteExecutionResult, } from "./executor.js";

package/routing/index.js

@@ -6,7 +6,7 @@ export { buildRoutePlan } from "./planner.js";
 export { buildRoutePlanWithConfigDegradation, } from "./plan-degradation.js";
 export { computeConfiguredRatesCostCents, } from "./billing-basis.js";
 export { fallbackKindOfCursor } from "./executor.js";
-export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, } from "./errors.js";
+export { failureDisposition, propagateOnly, categorizeHttpStatus, isRetriableAttemptError, } from "./errors.js";
 export { classifyAttemptError, retryAfterMsFromHeaders, isAbortByName, } from "./attempt-errors.js";
 export { createCircuitBreaker, } from "./circuit-breaker.js";
 export { executeRoutePlan, } from "./executor.js";

package/run/children.d.ts

@@ -86,6 +86,26 @@ export type ChainRule =
     msSinceLastSpawn: number | null;
     cooldownMs: number;
 }
+/**
+ * Whether this parent→child pair has *already* run, at all, within whatever
+ * scope the host measured over. The stronger sibling of
+ * `pair_cooldown`: a cooldown lets a pair repeat once enough time passes,
+ * while this permits the pair exactly once and never again.
+ *
+ * Reach for it where a repeat is not slow but wrong — two agents that answer
+ * each other are a loop whose every hop looks individually reasonable, and a
+ * time-based bound only makes such a loop cheaper per hour rather than
+ * ending it.
+ *
+ * The scope is the host's to choose and is deliberately not modelled here:
+ * "already paired in this chain" and "already paired in this conversation"
+ * are the same rule over different measurements, and naming either one would
+ * put a product's containment vocabulary into the harness.
+ */
+ | {
+    kind: "pair_seen";
+    alreadyPaired: boolean;
+}
 /**
  * A ceiling on concurrent runs for the whole tenant. Worth having alongside
  * the chain rules: depth and chain budgets constrain one lineage, and neither
@@ -95,6 +115,26 @@ export type ChainRule =
     kind: "tenant_ceiling";
     activeRuns: number;
     maxActiveRuns: number;
+}
+/**
+ * How many runs a tenant may *start* within a rolling window, as opposed to
+ * how many may be in flight at once (`tenant_ceiling`).
+ *
+ * The two bound different abuses and neither implies the other. A ceiling
+ * caps concurrency, so a caller that starts and finishes runs quickly slips
+ * under it indefinitely — a message flood, or one fan-out across a large
+ * group, is exactly that shape. A rate caps total starts, so it bounds spend
+ * where the ceiling bounds load.
+ *
+ * `windowMs` is carried only so the refusal can say how long the wait is;
+ * the rule does not roll the window itself. The host measures over whatever
+ * window it chose and passes both.
+ */
+ | {
+    kind: "tenant_rate";
+    runsInWindow: number;
+    maxRuns: number;
+    windowMs: number;
 };
 export type ChildAdmission = {
     admitted: true;
@@ -105,9 +145,9 @@ export type ChildAdmission = {
     /**
      * Could waiting change this answer?
      *
-     * The four rules are not the same kind of refusal, and prose alone does
-     * not separate them: a cooldown clears on its own, a spent chain budget
-     * never does. Without this a model reads "refused" and has to guess
+     * The rules are not all the same kind of refusal, and prose alone does
+     * not separate them: a cooldown or a rolling window clears on its own, a
+     * spent chain budget or a repeated pair never does. Without this a model reads "refused" and has to guess
      * between waiting and giving up — and guessing wrong either wastes the
      * run on retries into the same wall or abandons work it could have done
      * a moment later.
@@ -127,6 +167,18 @@ export type ChildAdmission = {
  * reason the model sees when several apply. An empty rule list admits — this
  * function bounds what it is given and claims nothing about what it is not.
  *
+ * **When a measurement fails, omit the rule — do not pass a sentinel.** The
+ * two failure postures here answer different questions and are easy to
+ * conflate. A rule whose number arrived broken (`NaN`, negative) refuses,
+ * because a nonsense count is not evidence of safety. A rule you could not
+ * measure at all — the count query threw, the store was unreachable — is
+ * absent, and absence admits. That is a deliberate seam, not an oversight:
+ * whether a transient infrastructure failure should stop all work or let it
+ * through is an availability judgement about a specific product, and this
+ * function has no standing to make it. Decide it at the call site, in a
+ * `catch`, by choosing whether to append the rule. Passing `NaN` or `-1` to
+ * mean "unknown" inverts the answer you almost certainly want.
+ *
  * **Call before enqueuing, never after.** A chain that is bounded only once its
  * runs are already queued is not bounded; it is billed.
  *

package/run/children.js

@@ -48,6 +48,18 @@ parent) {
  * reason the model sees when several apply. An empty rule list admits — this
  * function bounds what it is given and claims nothing about what it is not.
  *
+ * **When a measurement fails, omit the rule — do not pass a sentinel.** The
+ * two failure postures here answer different questions and are easy to
+ * conflate. A rule whose number arrived broken (`NaN`, negative) refuses,
+ * because a nonsense count is not evidence of safety. A rule you could not
+ * measure at all — the count query threw, the store was unreachable — is
+ * absent, and absence admits. That is a deliberate seam, not an oversight:
+ * whether a transient infrastructure failure should stop all work or let it
+ * through is an availability judgement about a specific product, and this
+ * function has no standing to make it. Decide it at the call site, in a
+ * `catch`, by choosing whether to append the rule. Passing `NaN` or `-1` to
+ * mean "unknown" inverts the answer you almost certainly want.
+ *
  * **Call before enqueuing, never after.** A chain that is bounded only once its
  * runs are already queued is not bounded; it is billed.
  *
@@ -83,8 +95,8 @@ function evaluateRule(rule) {
             const childDepth = rule.parentDepth + 1;
             return childDepth >= rule.maxDepth
                 ? refuse(rule, false, `chain depth limit reached (${childDepth}/${rule.maxDepth}) — ` +
-                    `this is as deep as the chain may go, so do the work in this run ` +
-                    `instead of spawning`)
+                    `as far as work may be handed on, and waiting will not change ` +
+                    `that; do this work here rather than delegating again`)
                 : null;
         }
         case "chain_budget": {
@@ -94,8 +106,8 @@ function evaluateRule(rule) {
                 return broken;
             return rule.runsInChain >= rule.maxRuns
                 ? refuse(rule, false, `chain run budget exhausted (${rule.runsInChain}/${rule.maxRuns}) — ` +
-                    `the budget is spent for this whole chain and does not refill, so ` +
-                    `do the work in this run instead of spawning`)
+                    `spent for this whole chain and it does not refill, so do this ` +
+                    `work here rather than delegating again`)
                 : null;
         }
         case "pair_cooldown": {
@@ -106,10 +118,19 @@ function evaluateRule(rule) {
             if (broken)
                 return broken;
             return rule.msSinceLastSpawn < rule.cooldownMs
-                ? refuse(rule, true, `spawn cooldown active (${rule.msSinceLastSpawn}ms since the last ` +
-                    `spawn, ${rule.cooldownMs}ms required) — retry in ` +
-                    `${rule.cooldownMs - rule.msSinceLastSpawn}ms, or do the work in ` +
-                    `this run`)
+                ? refuse(rule, true, `handoff cooldown active — retry in ` +
+                    `${rule.cooldownMs - rule.msSinceLastSpawn}ms, or do this work ` +
+                    `here (${rule.msSinceLastSpawn}ms since the last handoff, ` +
+                    `${rule.cooldownMs}ms required)`)
+                : null;
+        }
+        case "pair_seen": {
+            // A boolean carries no measurement to validate — the host either
+            // observed the prior pairing or it did not.
+            return rule.alreadyPaired
+                ? refuse(rule, false, `repeat handoff refused — these two have already worked together ` +
+                    `here and are allowed to only once, so waiting will not change ` +
+                    `that; do this work here instead`)
                 : null;
         }
         case "tenant_ceiling": {
@@ -119,8 +140,20 @@ function evaluateRule(rule) {
                 return broken;
             return rule.activeRuns >= rule.maxActiveRuns
                 ? refuse(rule, true, `concurrent run ceiling reached (${rule.activeRuns}/` +
-                    `${rule.maxActiveRuns}) — this clears as other runs finish, so ` +
-                    `retry shortly or do the work in this run`)
+                    `${rule.maxActiveRuns}) — clears as other runs finish, so retry ` +
+                    `shortly or do this work here`)
+                : null;
+        }
+        case "tenant_rate": {
+            const broken = unmeasurable(rule, rule.runsInWindow, "runsInWindow") ??
+                unmeasurable(rule, rule.maxRuns, "maxRuns") ??
+                unmeasurable(rule, rule.windowMs, "windowMs");
+            if (broken)
+                return broken;
+            return rule.runsInWindow >= rule.maxRuns
+                ? refuse(rule, true, `start-rate limit reached (${rule.runsInWindow}/${rule.maxRuns} ` +
+                    `runs in the last ${rule.windowMs}ms) — the window rolls, so ` +
+                    `wait up to ${rule.windowMs}ms and retry, or do this work here`)
                 : null;
         }
         default: {

package/run/index.d.ts

@@ -1,3 +1,4 @@
 export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, type RunDeadline, type CoalescedHeartbeat, } from "./harness.js";
 export { runToolCallsPooledByTool } from "./tool-batch.js";
 export { rootChain, descendChain, admitChildRun, createPollSchedule, type ChainRef, type ChainRule, type ChildAdmission, type PollStep, type PollSchedule, type PollScheduleOptions, } from "./children.js";
+export { toolCallReceiptKeyString, canonicalJson, toolCallArgsHash, decideToolCallReceipt, type ToolCallReceiptKey, type DigestFn, type ReceiptState, type EffectResumability, type ReceiptDecision, } from "./receipts.js";

package/run/index.js

@@ -1,3 +1,4 @@
 export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, } from "./harness.js";
 export { runToolCallsPooledByTool } from "./tool-batch.js";
 export { rootChain, descendChain, admitChildRun, createPollSchedule, } from "./children.js";
+export { toolCallReceiptKeyString, canonicalJson, toolCallArgsHash, decideToolCallReceipt, } from "./receipts.js";