@pentoshi/clai 4.0.3 → 4.2.0

package/dist/llm/request-plan.js

@@ -0,0 +1,279 @@
+import { createHash } from "node:crypto";
+import { createReasoningArtifactReplayTarget, reasoningArtifactReplayDecision, reasoningArtifactsForMessage, } from "./reasoning-artifacts.js";
+import { isRequestContextSystemMessage } from "./system-messages.js";
+import { isReasoningUnsupported, modelAcceptsImages, modelSupportsThinking, } from "./capabilities.js";
+import { resolveSampling } from "./sampling.js";
+import { isBuiltInProviderId, resolveProviderProfile, } from "./provider-profile.js";
+import { providerWireApi, resolveBuiltInProfile } from "./provider-profiles.js";
+/**
+ * Canonical request plan (doc 03 §"Canonical request plan", doc 06 §3).
+ *
+ * One immutable, renderer-neutral object describes what a logical generation
+ * will send: route, timeline with stable/mutable boundaries, tools, replay
+ * decisions for every artifact, controls, images, route policy, budget, and a
+ * privacy-safe cache-prefix fingerprint. Provider serializers emit their wire
+ * bodies from a compiled plan; nothing dispatches from ad hoc message arrays
+ * past this boundary.
+ */
+export const REQUEST_PLAN_VERSION = 1;
+export const REQUEST_PLAN_COMPILER_VERSION = 1;
+const REPLAY_DIALECT_BY_WIRE = {
+    "chat-completions": "openai-compatible",
+    "anthropic-messages": "anthropic-messages",
+    "gemini-generate-content": "gemini-generate-content",
+    "meta-responses": "meta-responses",
+    "ollama-chat": "ollama-chat",
+};
+const PLAN_HASH_DOMAIN = "clai.request-plan.v1\0";
+// Repository-wide conservative mixed text/JSON ratio; matches the artifact
+// accounting estimator so plan sections compose with other token estimates.
+function estimateTokens(byteLength) {
+    return Math.ceil(byteLength / 3.3);
+}
+function hashParts(parts) {
+    const hash = createHash("sha256").update(PLAN_HASH_DOMAIN, "utf8");
+    let byteLength = 0;
+    for (const part of parts) {
+        const bytes = Buffer.from(part, "utf8");
+        hash.update(`${bytes.length}:`, "utf8");
+        hash.update(bytes);
+        byteLength += bytes.length;
+    }
+    return { sha256: hash.digest("hex"), byteLength };
+}
+/** Leading system/developer run; the stable instruction prefix. */
+function instructionsEnd(messages) {
+    let index = 0;
+    while (index < messages.length && messages[index].role === "system") {
+        index += 1;
+    }
+    return index;
+}
+/**
+ * The mutable suffix starts at the last user message: everything after it is
+ * the in-flight turn (live request state, open tool exchange, current input)
+ * and may still change before dispatch.
+ */
+function liveStart(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        if (messages[index].role === "user")
+            return index;
+    }
+    return messages.length;
+}
+function cacheAffectingValue(field, controls) {
+    switch (field) {
+        case "messages":
+        case "tools":
+            return `${field}-section`;
+        case "thinking":
+            return `${controls.reasoningEnabled}:${controls.effort}`;
+        case "reasoning":
+            return controls.reasoningEnabled ? "enabled" : "omitted";
+        case "reasoning_effort":
+        case "reasoning.effort":
+            return controls.reasoningEnabled ? controls.effort : "off";
+        case "temperature":
+            return String(controls.temperature);
+        case "top_p":
+            return controls.topP === undefined ? "omitted" : String(controls.topP);
+        default:
+            return "declared";
+    }
+}
+function cacheSection(ordinal, section, parts) {
+    const { sha256, byteLength } = hashParts(parts);
+    return Object.freeze({
+        ordinal,
+        section,
+        sha256,
+        byteLength,
+        estimatedTokens: estimateTokens(byteLength),
+        itemCount: parts.length,
+    });
+}
+/**
+ * Deterministically compile one immutable plan. Compilation is pure: the same
+ * inputs always produce a deep-equal plan with identical section hashes.
+ */
+export function compileRequestPlan(input) {
+    const messages = Object.freeze([...input.messages]);
+    const wire = providerWireApi(input.provider, input.model);
+    const target = createReasoningArtifactReplayTarget({
+        provider: input.provider,
+        model: input.model,
+        dialect: REPLAY_DIALECT_BY_WIRE[wire],
+        ...(input.endpoint ? { endpoint: input.endpoint } : {}),
+    });
+    const instructionsBoundary = instructionsEnd(messages);
+    const liveBoundary = liveStart(messages);
+    const sections = [
+        {
+            kind: "instructions",
+            messageStart: 0,
+            messageEnd: instructionsBoundary,
+            messageCount: instructionsBoundary,
+        },
+        {
+            kind: "history",
+            messageStart: instructionsBoundary,
+            messageEnd: liveBoundary,
+            messageCount: Math.max(0, liveBoundary - instructionsBoundary),
+        },
+        {
+            kind: "live",
+            messageStart: liveBoundary,
+            messageEnd: messages.length,
+            messageCount: Math.max(0, messages.length - liveBoundary),
+        },
+    ].map((section) => Object.freeze(section));
+    const mutableMessageIndexes = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        if (index >= liveBoundary || isRequestContextSystemMessage(messages[index])) {
+            mutableMessageIndexes.push(index);
+        }
+    }
+    const reasoningEnabled = Boolean(input.reasoning?.enabled);
+    const effort = input.reasoning?.effort ?? "medium";
+    const controlSuppression = isReasoningUnsupported(input.provider, input.model)
+        ? "observed-rejection"
+        : reasoningEnabled && !modelSupportsThinking(input.provider, input.model)
+            ? "capability-denied"
+            : undefined;
+    const sampling = resolveSampling({
+        provider: input.provider,
+        model: input.model,
+        reasoningEnabled,
+        requestedTemperature: input.temperature,
+    });
+    const profile = isBuiltInProviderId(input.provider)
+        ? resolveBuiltInProfile({
+            provider: input.provider,
+            model: input.model,
+            endpointHash: target.endpointHash,
+        })
+        : resolveProviderProfile({
+            provider: input.provider,
+            model: input.model,
+            wireApi: wire,
+            endpointHash: target.endpointHash,
+        });
+    const decisions = [];
+    const replayedArtifactParts = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        const message = messages[index];
+        const withinCacheBoundary = index < liveBoundary && !isRequestContextSystemMessage(message);
+        for (const artifact of reasoningArtifactsForMessage(message)) {
+            const decision = reasoningArtifactReplayDecision(artifact, target, {
+                hasToolCalls: Boolean(message.toolCalls?.length),
+            });
+            decisions.push(Object.freeze({ messageIndex: index, decision }));
+            if (decision.action === "replayed" && withinCacheBoundary) {
+                replayedArtifactParts.push(JSON.stringify({
+                    kind: artifact.kind,
+                    raw: artifact.raw,
+                    position: artifact.position,
+                }));
+            }
+        }
+    }
+    const tools = Object.freeze([...(input.tools ?? [])]);
+    const imageMessageIndexes = [];
+    let imageCount = 0;
+    for (let index = 0; index < messages.length; index += 1) {
+        const count = messages[index].images?.length ?? 0;
+        if (count > 0) {
+            imageMessageIndexes.push(index);
+            imageCount += count;
+        }
+    }
+    const stableInstructions = messages
+        .slice(0, instructionsBoundary)
+        .filter((message) => !isRequestContextSystemMessage(message));
+    const stableHistory = messages
+        .slice(instructionsBoundary, liveBoundary)
+        .filter((message) => !isRequestContextSystemMessage(message));
+    const settingsValueInput = {
+        reasoningEnabled,
+        effort,
+        temperature: sampling.temperature,
+        topP: sampling.topP,
+    };
+    const cacheSections = [
+        cacheSection(1, "instructions", stableInstructions.map((m) => JSON.stringify(m))),
+        cacheSection(2, "tools", tools.map((tool) => JSON.stringify(tool))),
+        cacheSection(3, "history", stableHistory.map((m) => JSON.stringify(m))),
+        cacheSection(4, "artifacts", replayedArtifactParts),
+        cacheSection(5, "settings", [
+            `serializer:${wire}`,
+            `version:${REQUEST_PLAN_COMPILER_VERSION}`,
+            ...[...profile.cache.cacheAffectingFields]
+                .sort()
+                .map((field) => `${field}=${cacheAffectingValue(field, settingsValueInput)}`),
+        ]),
+    ];
+    const prefixHash = createHash("sha256").update(PLAN_HASH_DOMAIN, "utf8");
+    for (const section of cacheSections)
+        prefixHash.update(section.sha256, "hex");
+    return Object.freeze({
+        version: REQUEST_PLAN_VERSION,
+        route: Object.freeze({
+            provider: input.provider,
+            model: input.model,
+            serializer: wire,
+            serializerVersion: 1,
+            compilerVersion: REQUEST_PLAN_COMPILER_VERSION,
+            ...(target.endpointHash ? { endpointHash: target.endpointHash } : {}),
+        }),
+        timeline: Object.freeze({
+            messages,
+            sections: Object.freeze(sections),
+            mutableMessageIndexes: Object.freeze(mutableMessageIndexes),
+        }),
+        tools: Object.freeze({
+            definitions: tools,
+            ...(input.toolChoice !== undefined ? { choice: input.toolChoice } : {}),
+            ...(input.parallelToolCalls !== undefined
+                ? { parallelToolCalls: input.parallelToolCalls }
+                : {}),
+        }),
+        replay: Object.freeze({
+            target,
+            decisions: Object.freeze(decisions),
+        }),
+        controls: Object.freeze({
+            ...(input.reasoning ? { reasoning: input.reasoning } : {}),
+            ...(controlSuppression ? { controlSuppression } : {}),
+            temperature: sampling.temperature,
+            ...(sampling.topP !== undefined ? { topP: sampling.topP } : {}),
+            ...(input.maxTokens !== undefined
+                ? { requestedMaxTokens: input.maxTokens }
+                : {}),
+            stream: input.stream,
+        }),
+        images: Object.freeze({
+            visionAccepted: modelAcceptsImages(input.provider, input.model),
+            imageMessageIndexes: Object.freeze(imageMessageIndexes),
+            imageCount,
+        }),
+        policy: Object.freeze({
+            reasoningGeneration: profile.reasoning.generation,
+            controlDialect: profile.reasoning.control.dialect,
+            controlStatus: profile.reasoning.control.status,
+            replayScope: profile.reasoning.replayScope,
+            cache: profile.cache,
+            limits: profile.limits,
+        }),
+        budget: Object.freeze({ plannedAdmissions: 1 }),
+        cache: Object.freeze({
+            policy: profile.cache,
+            fingerprint: Object.freeze({
+                prefixMessageCount: stableInstructions.length + stableHistory.length,
+                replayedArtifactCount: replayedArtifactParts.length,
+                sections: Object.freeze(cacheSections),
+                prefixSha256: prefixHash.digest("hex"),
+            }),
+        }),
+    });
+}
+//# sourceMappingURL=request-plan.js.map

package/dist/llm/request-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-plan.js","sourceRoot":"","sources":["../../src/llm/request-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAazC,OAAO,EACL,mCAAmC,EACnC,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,mBAAmB,EACnB,sBAAsB,GAOvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEhF;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAU,CAAC;AAC/C,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAU,CAAC;AAwHxD,MAAM,sBAAsB,GAGxB;IACF,kBAAkB,EAAE,mBAAmB;IACvC,oBAAoB,EAAE,oBAAoB;IAC1C,yBAAyB,EAAE,yBAAyB;IACpD,gBAAgB,EAAE,gBAAgB;IAClC,aAAa,EAAE,aAAa;CAC7B,CAAC;AAEF,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AAElD,2EAA2E;AAC3E,4EAA4E;AAC5E,SAAS,cAAc,CAAC,UAAkB;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,SAAS,CAChB,KAAwB;IAExB,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACnE,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,EAAE,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnB,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC;IAC7B,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;AACpD,CAAC;AAED,mEAAmE;AACnE,SAAS,eAAe,CAAC,QAAgC;IACvD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAE,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrE,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,QAAgC;IACjD,KAAK,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC7D,IAAI,QAAQ,CAAC,KAAK,CAAE,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC;IACrD,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,CAAC;AACzB,CAAC;AAED,SAAS,mBAAmB,CAC1B,KAAa,EACb,QAKC;IAED,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,GAAG,KAAK,UAAU,CAAC;QAC5B,KAAK,UAAU;YACb,OAAO,GAAG,QAAQ,CAAC,gBAAgB,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC3D,KAAK,WAAW;YACd,OAAO,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3D,KAAK,kBAAkB,CAAC;QACxB,KAAK,kBAAkB;YACrB,OAAO,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QAC7D,KAAK,aAAa;YAChB,OAAO,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QACtC,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzE;YACE,OAAO,UAAU,CAAC;IACtB,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CACnB,OAAe,EACf,OAAoC,EACpC,KAAwB;IAExB,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,OAAO;QACP,OAAO;QACP,MAAM;QACN,UAAU;QACV,eAAe,EAAE,cAAc,CAAC,UAAU,CAAC;QAC3C,SAAS,EAAE,KAAK,CAAC,MAAM;KACxB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA8B;IAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,mCAAmC,CAAC;QACjD,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO,EAAE,sBAAsB,CAAC,IAAI,CAAC;QACrC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC,CAAC;IAEH,MAAM,oBAAoB,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,QAAQ,GACZ;QACE;YACE,IAAI,EAAE,cAAuB;YAC7B,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,oBAAoB;YAChC,YAAY,EAAE,oBAAoB;SACnC;QACD;YACE,IAAI,EAAE,SAAkB;YACxB,YAAY,EAAE,oBAAoB;YAClC,UAAU,EAAE,YAAY;YACxB,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,oBAAoB,CAAC;SAC/D;QACD;YACE,IAAI,EAAE,MAAe;YACrB,YAAY,EAAE,YAAY;YAC1B,UAAU,EAAE,QAAQ,CAAC,MAAM;YAC3B,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,YAAY,CAAC;SAC1D;KAEJ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAE3C,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAC3C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACxD,IAAI,KAAK,IAAI,YAAY,IAAI,6BAA6B,CAAC,QAAQ,CAAC,KAAK,CAAE,CAAC,EAAE,CAAC;YAC7E,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,MAAM,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,EAAE,MAAM,IAAI,QAAQ,CAAC;IACnD,MAAM,kBAAkB,GAAG,sBAAsB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC;QAC5E,CAAC,CAAE,oBAA8B;QACjC,CAAC,CAAC,gBAAgB,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC;YACvE,CAAC,CAAE,mBAA6B;YAChC,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,QAAQ,GAAG,eAAe,CAAC;QAC/B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,gBAAgB;QAChB,oBAAoB,EAAE,KAAK,CAAC,WAAW;KACxC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;QACjD,CAAC,CAAC,qBAAqB,CAAC;YACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC;QACJ,CAAC,CAAC,sBAAsB,CAAC;YACrB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,IAAI;YACb,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAC;IAEP,MAAM,SAAS,GAAkC,EAAE,CAAC;IACpD,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAC3C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAE,CAAC;QACjC,MAAM,mBAAmB,GACvB,KAAK,GAAG,YAAY,IAAI,CAAC,6BAA6B,CAAC,OAAO,CAAC,CAAC;QAClE,KAAK,MAAM,QAAQ,IAAI,4BAA4B,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7D,MAAM,QAAQ,GAAG,+BAA+B,CAAC,QAAQ,EAAE,MAAM,EAAE;gBACjE,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;aACjD,CAAC,CAAC;YACH,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,IAAI,mBAAmB,EAAE,CAAC;gBAC1D,qBAAqB,CAAC,IAAI,CACxB,IAAI,CAAC,SAAS,CAAC;oBACb,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,GAAG,EAAE,QAAQ,CAAC,GAAG;oBACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;iBAC5B,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,mBAAmB,GAAa,EAAE,CAAC;IACzC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAE,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC;QACnD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAChC,UAAU,IAAI,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,MAAM,kBAAkB,GAAG,QAAQ;SAChC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC;SAC9B,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,6BAA6B,CAAC,OAAO,CAAC,CAAC,CAAC;IAChE,MAAM,aAAa,GAAG,QAAQ;SAC3B,KAAK,CAAC,oBAAoB,EAAE,YAAY,CAAC;SACzC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,6BAA6B,CAAC,OAAO,CAAC,CAAC,CAAC;IAChE,MAAM,kBAAkB,GAAG;QACzB,gBAAgB;QAChB,MAAM;QACN,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,IAAI,EAAE,QAAQ,CAAC,IAAI;KACpB,CAAC;IAEF,MAAM,aAAa,GAA8B;QAC/C,YAAY,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACjF,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QACnE,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACvE,YAAY,CAAC,CAAC,EAAE,WAAW,EAAE,qBAAqB,CAAC;QACnD,YAAY,CACV,CAAC,EACD,UAAU,EACV;YACE,cAAc,IAAI,EAAE;YACpB,WAAW,6BAA6B,EAAE;YAC1C,GAAG,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC;iBACvC,IAAI,EAAE;iBACN,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,CAAC,EAAE,CAAC;SAChF,CACF;KACF,CAAC;IAEF,MAAM,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACzE,KAAK,MAAM,OAAO,IAAI,aAAa;QAAE,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE9E,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,OAAO,EAAE,oBAAoB;QAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,UAAU,EAAE,IAAI;YAChB,iBAAiB,EAAE,CAAC;YACpB,eAAe,EAAE,6BAA6B;YAC9C,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtE,CAAC;QACF,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;YACtB,QAAQ;YACR,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;YACjC,qBAAqB,EAAE,MAAM,CAAC,MAAM,CAAC,qBAAqB,CAAC;SAC5D,CAAC;QACF,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;YACnB,WAAW,EAAE,KAAK;YAClB,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,GAAG,CAAC,KAAK,CAAC,iBAAiB,KAAK,SAAS;gBACvC,CAAC,CAAC,EAAE,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,EAAE;gBAChD,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;QACF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACpB,MAAM;YACN,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;SACpC,CAAC;QACF,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;YACtB,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/D,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS;gBAC/B,CAAC,CAAC,EAAE,kBAAkB,EAAE,KAAK,CAAC,SAAS,EAAE;gBACzC,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC;QACF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACpB,cAAc,EAAE,kBAAkB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC;YAC/D,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC;YACvD,UAAU;SACX,CAAC;QACF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACpB,mBAAmB,EAAE,OAAO,CAAC,SAAS,CAAC,UAAU;YACjD,cAAc,EAAE,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO;YACjD,aAAa,EAAE,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM;YAC/C,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,WAAW;YAC1C,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC;QACF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAU,EAAE,CAAC;QACxD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;YACnB,MAAM,EAAE,OAAO,CAAC,KAAK;YACrB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC;gBACzB,kBAAkB,EAAE,kBAAkB,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM;gBACpE,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;gBACnD,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;gBACtC,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC;aACvC,CAAC;SACH,CAAC;KACH,CAAC,CAAC;AACL,CAAC"}

package/dist/llm/router.d.ts

@@ -1,15 +1,33 @@
-import type { CompletionRequest, CompletionResult, ProviderId } from "../types.js";
+import type { CompletionRequest, CompletionResult, ProviderId, SuccessfulRequestSnapshot } from "../types.js";
 import { ProviderError } from "./http.js";
+import { type ProviderStreamEventSink } from "./stream-events.js";
 import { type ProviderKeyEvent } from "./key-rotation.js";
 import type { LlmProvider, ProviderAuth } from "./provider.js";
+import { OperationUsageRecorder, type OperationUsageSnapshot } from "./operation-usage.js";
+import { OperationLedger } from "./operation-ledger.js";
 /** Toast replace-key so key rotation never stacks notifications. */
 export declare const API_KEY_TOAST_KEY = "api-key-rotation";
 export type ProviderKeyEventHandler = (event: ProviderKeyEvent) => void;
 export interface StreamWithProviderOptions {
     readonly onStatus?: ((message: string) => void) | undefined;
     readonly onKeyEvent?: ProviderKeyEventHandler | undefined;
+    readonly onStreamEvent?: ProviderStreamEventSink | undefined;
+    /** Additive per-admission accounting for this logical operation. */
+    readonly attemptUsage?: OperationUsageRecorder | undefined;
+    readonly operation?: OperationLedger | undefined;
+    readonly adoptFallback?: boolean | undefined;
+    /** Receives the immutable terminal snapshot on success or failure. */
+    readonly onOperationUsage?: ((snapshot: OperationUsageSnapshot) => void) | undefined;
     /** Cap retries for this request (default MAX_RETRIES). Use 0-1 for compaction. */
     readonly maxRetries?: number | undefined;
+    /**
+     * Pin the route and emit exactly one physical generation request: no provider
+     * fallback, no key or endpoint rotation, no capability-adaptation retry. Used
+     * by operations whose prompt is too expensive to send twice (compaction) and
+     * by auxiliary requests that must not multiply.
+     */
+    readonly singleDispatch?: boolean | undefined;
+    readonly onSuccessfulRequest?: ((snapshot: SuccessfulRequestSnapshot) => void) | undefined;
 }
 /**
  * User-facing classification of provider failures (auth, capacity, disconnect,