@mupt-ai/dari-gateway 0.2.0 → 0.3.0

package/README.md

@@ -64,7 +64,7 @@ docker run -p 8080:8080 \
 | `DARI_GATEWAY_DB` | SQLite database for subscriptions and conversation state. Default `dari-gateway.db`. It stores subscription tokens in plaintext; protect it like a secret. |
 | `DARI_AUTO_ROUTING_API_KEY` | Optional. Select among a router's models with Dari Auto Routing. |
 | `PORT` | Listen port. Default `8080`. |
-| Provider keys | Each provider's standard variable, such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`. |
+| Provider keys | Each provider's standard variable, such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `META_API_KEY`, or `OPENROUTER_API_KEY`. |
 
 ## Configure
 
@@ -88,13 +88,17 @@ providers:                 # endpoints outside the built-in catalog
 
 Model ids are `provider/model`. Clients send `model: "dari/routing"` to let the router choose, or `model: "dari/model/<id>"` to pin one of its models. A Claude Code subscription serves Anthropic models only for Claude Code itself; a ChatGPT subscription serves OpenAI models for every client.
 
+### Model catalog
+
+`GET /v1/models?detail=1` (any gateway key; optionally `&provider=openrouter,meta`) and `listModelCatalog({ providers?, fetch?, signal? })` list each provider's tool-capable models as `dari/model/<id>`-ready ids with context window, max output tokens, input modalities, accepted thinking levels, and list prices in USD per million tokens (input, output, cache read, cache write, long-context tiers) with `price_as_of`. OpenRouter and Vercel AI Gateway are read live from their public models endpoints; other providers (default: OpenAI, Anthropic, Meta, xAI, Fireworks) come from the bundled Pi catalog.
+
 ## Coding agents
 
 ```bash
 export DARI_GATEWAY_URL=http://localhost:8080
 export DARI_GATEWAY_KEY=<one of DARI_GATEWAY_KEYS>
 
-dari credentials subscription connect claude-code   # or codex; repeat to pool plans
+dari credentials subscription connect claude-code   # or codex or muse-code; repeat to pool plans
 dari claude
 ```
 
@@ -115,8 +119,8 @@ The root entry needs no Bun APIs, so any runtime with web-standard `fetch`, `Req
 
 Platforms can also:
 
-- implement `resolveProviderCredential({ provider, model, routerId, organizationId, apiKey })` to supply a per-request `{ apiKey, baseUrl?, headers? }`, such as a tenant's own key, in place of the router's resolved key;
-- resolve routers with `strict: true` to serve only the requested `dari/model/<id>` at the requested thinking level, with no selector, lease, fallback, or personal subscription;
+- implement `resolveProviderCredential({ provider, model, routerId, organizationId, apiKey, clientHarness? })` to supply a per-request `{ apiKey, baseUrl?, headers?, subscription? }`, such as a tenant's own key, in place of the router's resolved key. With `subscription` (`"openai_codex"`, `"anthropic_claude_code"`, or `"meta_muse"`), `apiKey` is that plan's access token: Codex's `auth.json` `tokens.access_token`, the token `claude setup-token` prints, or the Model API key a Meta sign-in mints. The platform keeps it fresh. Strict routers serve these supplied plans, but never subscriptions the gateway resolved itself. A plan serves only its own provider's models; a Claude Code plan serves only Claude Code clients, and a Muse Code plan only Muse Code clients (recognized by their `x-client-id`);
+- resolve routers with `strict: true` to serve only the requested `dari/model/<id>` at the requested thinking level, with no selector, lease, fallback, or personal subscription. Set `strict_providers: ["openai"]` on the resolved router to permit any bundled-catalog model from that provider without enumerating `enabled_models`. Use `dari/model/openai/gpt-5.5`; bare IDs and unknown models remain refused. This grant is ignored on non-strict routers and does not discover uncatalogued models;
 - read exact usage from `recordRequest`: the summary carries input, output, cache-read, and cache-write tokens and `total_cost_usd`, preferring the provider's billed cost (`cost_source: "provider"`, from OpenRouter and Vercel AI Gateway). Failed and aborted requests are recorded too;
 - attribute cost with `X-Dari-Tags: run=r1,trial=3`, which is parsed into `RequestRecord.tags` and the `recordUsage` payload's `tags`.
 

package/dist/bun.d.ts

@@ -0,0 +1,2 @@
+export { installShutdownHandlers, startServer } from "./http/serve.js";
+export { startSelfHostedGateway } from "./self_host/main.js";

package/dist/bun.js

@@ -0,0 +1,4 @@
+// Bun-only entry points: the Bun.serve HTTP server and the self-hosted
+// gateway, whose state lives in bun:sqlite.
+export { installShutdownHandlers, startServer } from "./http/serve.js";
+export { startSelfHostedGateway } from "./self_host/main.js";

package/dist/context/eval_catalog.d.ts

@@ -0,0 +1,3 @@
+import type { PublicEvalCatalogCard } from "../types.js";
+import type { RouterEval } from "@mupt-ai/dari-router/policy-engine";
+export declare function publicCatalogSelectorEvals(catalog: PublicEvalCatalogCard[] | null | undefined): RouterEval[];

package/dist/context/eval_catalog.js

@@ -0,0 +1,7 @@
+// Convert public cards into hidden ratio-calibration inputs. Cards without a
+// sync timestamp or scores carry no signal and are dropped.
+export function publicCatalogSelectorEvals(catalog) {
+    if (!catalog)
+        return [];
+    return catalog.filter((card) => card.updated_at !== null && card.scores.length > 0);
+}

package/dist/context/interaction_fingerprint.d.ts

@@ -0,0 +1,27 @@
+import type { InteractionOutput, InteractionRequest, ProviderIdentity } from "../interaction/types.js";
+export type InteractionPrefixContext = {
+    chainByModel: ReadonlyMap<string, string[]>;
+    itemIndexByHashByModel: ReadonlyMap<string, ReadonlyMap<string, number>>;
+    looseChain: string[];
+    fingerprints: {
+        tool_choice_fp: string;
+        response_format_fp: string;
+    };
+};
+/**
+ * Hash variants sent during router resolution. The portable chain covers
+ * providers that receive readable history only. Exact continuation-source
+ * variants cover a return to the originating model. Because provider APIs
+ * are unknown before resolution, Responses tool history also contributes a
+ * composite call/item-ID variant for OpenAI-compatible Responses targets.
+ */
+export declare function interactionPrefixLookupHashes(routerId: string, request: InteractionRequest): string[];
+export declare function interactionLooseChain(routerId: string, request: InteractionRequest): string[];
+export declare function interactionConversationPrefix(request: InteractionRequest): string;
+export declare function interactionPrefixContext(routerId: string, request: InteractionRequest, targets: ReadonlyMap<string, ProviderIdentity>): InteractionPrefixContext;
+export declare function interactionPrefixChain(routerId: string, request: InteractionRequest, target: ProviderIdentity | null): string[];
+export declare function extendInteractionChain(lastHash: string, output: InteractionOutput, target: ProviderIdentity, policy: {
+    includeItemIds: boolean;
+    sourceProtocol: InteractionRequest["sourceProtocol"];
+}): string[];
+export declare function extendInteractionLooseChain(lastHash: string, output: InteractionOutput, sourceProtocol: InteractionRequest["sourceProtocol"]): string[];

package/dist/context/interaction_fingerprint.js

@@ -0,0 +1,519 @@
+import { createHash } from "node:crypto";
+import { stableStringify } from "@mupt-ai/dari-router/policy-engine";
+import { anthropicMessagesToInteraction } from "../protocol/input/anthropic_messages.js";
+import { internalChatCompletionsToInteraction } from "../protocol/input/chat_completions.js";
+import { anthropicContent } from "../protocol/output/anthropic_messages_output.js";
+import { assistantMessagePayload } from "../protocol/output/chat_completions.js";
+import { compatibleProviderContinuation } from "../interaction/provider_continuation_state.js";
+import { providerToolCallId, toolWireName } from "../interaction/tool_identity.js";
+import { ROUTING_PREFIX_HASHES_MAX_COUNT } from "../platform/routing_contract.js";
+import { appendFingerprintContentText, canonicalInteractionFingerprintStep, interactionFingerprintContent, interactionFingerprintHeadHash, interactionOptionsFingerprints, normalizedAssistantFingerprintContent, } from "./interaction_fingerprint_format.js";
+const MAX_CONTINUATION_TARGETS = 16;
+// The loose tier ignores reasoning and item ids, so provider identity and
+// tool-call-id composition cannot influence it: one chain per request.
+const LOOSE_POLICY = {
+    includeItemIds: false,
+    includePhase: false,
+    canonicalizeFunctionArguments: true,
+    loose: true,
+};
+// Salts the loose chain's seed so the two hash tiers can never collide in
+// the shared prefix-entry lookup space.
+const LOOSE_SEED_SALT = "fp-loose-1";
+const CONVERSATION_PREFIX_VERSION = "conversation-prefix-v1";
+/**
+ * Hash variants sent during router resolution. The portable chain covers
+ * providers that receive readable history only. Exact continuation-source
+ * variants cover a return to the originating model. Because provider APIs
+ * are unknown before resolution, Responses tool history also contributes a
+ * composite call/item-ID variant for OpenAI-compatible Responses targets.
+ */
+export function interactionPrefixLookupHashes(routerId, request) {
+    const targets = [null];
+    const seen = new Set();
+    for (let index = request.items.length - 1; index >= 0 && seen.size < MAX_CONTINUATION_TARGETS; index -= 1) {
+        const item = request.items[index];
+        if (item.type !== "reasoning" || !item.continuation)
+            continue;
+        const key = identityKey(item.continuation.source);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        targets.push(item.continuation.source);
+    }
+    const chains = targets.map((target) => interactionPrefixChain(routerId, request, target));
+    if (request.sourceProtocol === "openai_responses") {
+        chains.push(interactionPrefixChainFor(routerId, request, null, "openai-responses"));
+    }
+    chains.push(interactionLooseChain(routerId, request));
+    return deepestDistinctHashes(chains, ROUTING_PREFIX_HASHES_MAX_COUNT);
+}
+// The loose (client-durable) chain: what the conversation looks like once
+// reasoning payloads, item ids, and provider-specific canonicalization are
+// stripped. Distinct seed keeps its hashes disjoint from the strict tier.
+export function interactionLooseChain(routerId, request) {
+    return fingerprintChain(sha256(`${interactionFingerprintHeadHash(routerId, request)}\u0000${LOOSE_SEED_SALT}`), looseFingerprintSteps(request.sourceProtocol, request.items));
+}
+// Stable logical-conversation discriminator. This deliberately excludes the
+// cache head (instructions and tools) and hashes only the first normalized
+// transcript step. Growing history and tool changes preserve identity, while
+// unrelated work reusing the same harness session gets a new group.
+export function interactionConversationPrefix(request) {
+    const firstStep = conversationFingerprintSteps(looseFingerprintSteps(request.sourceProtocol, request.items)).at(0);
+    return sha256(stableStringify({
+        version: CONVERSATION_PREFIX_VERSION,
+        firstStep: firstStep === undefined
+            ? null
+            : canonicalInteractionFingerprintStep(firstStep),
+    }));
+}
+export function interactionPrefixContext(routerId, request, targets) {
+    const chainByModel = new Map();
+    const itemIndexByHashByModel = new Map();
+    for (const [model, target] of targets) {
+        const steps = interactionPrefixStepsFor(routerId, request, target, target.api);
+        chainByModel.set(model, steps.map((step) => step.hash));
+        itemIndexByHashByModel.set(model, new Map(steps.map((step) => [step.hash, step.itemIndex])));
+    }
+    return {
+        chainByModel,
+        itemIndexByHashByModel,
+        looseChain: interactionLooseChain(routerId, request),
+        fingerprints: interactionOptionsFingerprints(request),
+    };
+}
+// Loose fingerprints share the strict grouping logic so step boundaries
+// stay identical whether or not the client echoed reasoning; the policy just
+// drops the volatile fields. Target-independent by construction.
+function looseFingerprintSteps(sourceProtocol, items) {
+    return sourceProtocol === "openai_chat"
+        ? fingerprintChatInputSteps(items, null, null, LOOSE_POLICY)
+        : fingerprintSteps(items, null, null, LOOSE_POLICY);
+}
+export function interactionPrefixChain(routerId, request, target) {
+    return interactionPrefixStepsFor(routerId, request, target, target?.api ?? null)
+        .map((step) => step.hash);
+}
+function interactionPrefixChainFor(routerId, request, target, toolCallApi) {
+    return interactionPrefixStepsFor(routerId, request, target, toolCallApi)
+        .map((step) => step.hash);
+}
+function interactionPrefixStepsFor(routerId, request, target, toolCallApi) {
+    let hash = interactionFingerprintHeadHash(routerId, request);
+    const steps = [];
+    const responses = request.sourceProtocol === "openai_responses";
+    const fingerprintStepsForRequest = conversationFingerprintSteps(request.sourceProtocol === "openai_chat"
+        ? fingerprintChatInputSteps(request.items, target, toolCallApi)
+        : fingerprintSteps(request.items, target, toolCallApi, {
+            includeItemIds: true,
+            includePhase: responses,
+            canonicalizeFunctionArguments: responses,
+        }));
+    for (const step of fingerprintStepsForRequest) {
+        hash = extendFingerprintHash(hash, step);
+        steps.push({ hash, itemIndex: step.itemIndex });
+    }
+    return steps;
+}
+export function extendInteractionChain(lastHash, output, target, policy) {
+    let hash = lastHash;
+    const extension = [];
+    const steps = fingerprintClientEchoSteps(output, target, policy);
+    for (const step of steps) {
+        if (step.actor === "system" || step.actor === "developer")
+            continue;
+        hash = extendFingerprintHash(hash, step);
+        extension.push(hash);
+    }
+    return extension;
+}
+function fingerprintClientEchoSteps(output, target, policy) {
+    const items = clientEchoItems(output, policy.sourceProtocol);
+    if (policy.sourceProtocol === "openai_chat") {
+        return fingerprintChatInputSteps(items, target, target.api);
+    }
+    return fingerprintSteps(items, target, target.api, {
+        includeItemIds: policy.includeItemIds,
+        includePhase: policy.sourceProtocol === "openai_responses",
+        canonicalizeFunctionArguments: true,
+    });
+}
+// Prefix extensions must match the assistant output as the next client request
+// will carry it, not necessarily the provider's canonical output items.
+function clientEchoItems(output, sourceProtocol) {
+    if (sourceProtocol === "openai_chat") {
+        return internalChatCompletionsToInteraction({
+            model: "dari/routing",
+            messages: [assistantMessagePayload(output)],
+        }).items;
+    }
+    if (sourceProtocol === "anthropic_messages") {
+        return anthropicMessagesToInteraction({
+            model: "dari/routing",
+            max_tokens: 1,
+            messages: [{ role: "assistant", content: anthropicContent(output) }],
+        }).items;
+    }
+    return output.items;
+}
+// Loose-tier extension for the reply, mirroring interactionLooseChain's
+// policy: what the next request's loose chain computes at this depth no
+// matter which volatile fields the client's echo keeps.
+export function extendInteractionLooseChain(lastHash, output, sourceProtocol) {
+    let hash = lastHash;
+    const extension = [];
+    const items = clientEchoItems(output, sourceProtocol);
+    for (const step of looseFingerprintSteps(sourceProtocol, items)) {
+        if (step.actor === "system" || step.actor === "developer")
+            continue;
+        hash = extendFingerprintHash(hash, step);
+        extension.push(hash);
+    }
+    return extension;
+}
+// Chat carries reasoning, assistant text, and tool calls in one assistant
+// message. Its canonical interaction items intentionally separate those
+// concerns, so prefix hashing must regroup one wire message before hashing.
+function fingerprintChatInputSteps(items, target, toolCallApi, policy) {
+    const steps = [];
+    const toolCalls = new Map();
+    let pendingReasoning = [];
+    let pendingReasoningItemIndex = -1;
+    const flushReasoning = () => {
+        if (pendingReasoning.length === 0)
+            return;
+        steps.push({
+            actor: "assistant",
+            itemIndex: pendingReasoningItemIndex,
+            content: null,
+            calls: [],
+            resultCallId: null,
+            reasoning: pendingReasoning,
+        });
+        pendingReasoning = [];
+        pendingReasoningItemIndex = -1;
+    };
+    for (const [itemIndex, item] of items.entries()) {
+        if (item.type === "reasoning") {
+            if (policy?.loose)
+                continue;
+            pendingReasoning.push(reasoningFingerprint(item, target, false));
+            pendingReasoningItemIndex = itemIndex;
+            continue;
+        }
+        if (item.type === "message") {
+            if (item.role !== "assistant")
+                flushReasoning();
+            steps.push({
+                actor: item.role,
+                itemIndex,
+                content: item.role === "assistant"
+                    ? normalizedAssistantFingerprintContent(item.content, item.contentShape)
+                    : interactionFingerprintContent(item.content, item.contentShape),
+                calls: [],
+                resultCallId: null,
+                ...(item.role === "assistant" && pendingReasoning.length > 0
+                    ? { reasoning: pendingReasoning }
+                    : {}),
+            });
+            pendingReasoning = [];
+            pendingReasoningItemIndex = -1;
+            continue;
+        }
+        if (item.type === "reasoning_configuration") {
+            // Configuration updates change execution effort without becoming part
+            // of the conversational identity, just like request-level effort.
+            flushReasoning();
+            continue;
+        }
+        if (item.type === "tool_result") {
+            flushReasoning();
+            steps.push({
+                actor: "tool",
+                itemIndex,
+                content: interactionFingerprintContent(item.output, item.outputShape),
+                calls: [],
+                resultCallId: toolCalls.get(item.callId) ?? item.callId,
+            });
+            continue;
+        }
+        flushReasoning();
+        let assistant = steps.at(-1);
+        if (!assistant || assistant.actor !== "assistant") {
+            assistant = {
+                actor: "assistant",
+                content: null,
+                calls: [],
+                resultCallId: null,
+                itemIndex,
+            };
+            steps.push(assistant);
+        }
+        assistant.itemIndex = itemIndex;
+        if (item.type === "tool_call") {
+            const id = appendToolCall(assistant, item, toolCallApi, false, policy?.canonicalizeFunctionArguments ?? false);
+            toolCalls.set(item.callId, id);
+        }
+        else {
+            appendHostedToolCall(assistant, item);
+        }
+    }
+    flushReasoning();
+    return steps;
+}
+function fingerprintSteps(items, target, toolCallApi, policy) {
+    const steps = [];
+    const toolCalls = new Map();
+    for (const [itemIndex, item] of items.entries()) {
+        if (item.type === "reasoning") {
+            if (policy.loose)
+                continue;
+            const continuation = compatibleProviderContinuation(item.continuation, target);
+            const readable = continuationReadableText(item, continuation);
+            const itemFingerprint = reasoningFingerprint(item, target, policy.includeItemIds);
+            const previous = steps.at(-1);
+            if (previous?.actor === "assistant"
+                && (previous.calls.length > 0 || previous.reasoning?.length)) {
+                previous.itemIndex = itemIndex;
+                previous.content = appendFingerprintContentText(previous.content, readable);
+                previous.reasoning = [...(previous.reasoning ?? []), itemFingerprint];
+                continue;
+            }
+            steps.push({
+                actor: "assistant",
+                itemIndex,
+                content: readable || null,
+                calls: [],
+                resultCallId: null,
+                reasoning: [itemFingerprint],
+            });
+            continue;
+        }
+        if (item.type === "reasoning_configuration") {
+            continue;
+        }
+        if (item.type === "tool_result") {
+            steps.push({
+                actor: "tool",
+                itemIndex,
+                content: interactionFingerprintContent(item.output, item.outputShape),
+                calls: [],
+                resultCallId: toolCalls.get(item.callId) ?? item.callId,
+            });
+            continue;
+        }
+        if (item.type === "tool_call") {
+            let assistant = steps.at(-1);
+            if (!assistant || assistant.actor !== "assistant") {
+                assistant = {
+                    actor: "assistant",
+                    content: null,
+                    calls: [],
+                    resultCallId: null,
+                    itemIndex,
+                };
+                steps.push(assistant);
+            }
+            assistant.itemIndex = itemIndex;
+            const id = appendToolCall(assistant, item, toolCallApi, policy.includeItemIds, policy.canonicalizeFunctionArguments);
+            toolCalls.set(item.callId, id);
+            continue;
+        }
+        if (item.type === "hosted_tool_call") {
+            let assistant = steps.at(-1);
+            if (!assistant || assistant.actor !== "assistant") {
+                assistant = {
+                    actor: "assistant",
+                    content: null,
+                    calls: [],
+                    resultCallId: null,
+                    itemIndex,
+                };
+                steps.push(assistant);
+            }
+            assistant.itemIndex = itemIndex;
+            appendHostedToolCall(assistant, item);
+            continue;
+        }
+        steps.push({
+            actor: item.role,
+            itemIndex,
+            content: policy.loose && item.role === "assistant"
+                ? normalizedAssistantFingerprintContent(item.content, item.contentShape)
+                : interactionFingerprintContent(item.content, item.contentShape),
+            calls: [],
+            resultCallId: null,
+            ...(policy.includeItemIds && item.id ? { itemId: item.id } : {}),
+            ...(policy.includePhase && item.phase ? { phase: item.phase } : {}),
+        });
+    }
+    return steps;
+}
+function reasoningFingerprint(item, target, includeItemId) {
+    const continuation = compatibleProviderContinuation(item.continuation, target);
+    const readable = continuationReadableText(item, continuation);
+    return {
+        ...(includeItemId && item.id ? { itemId: item.id } : {}),
+        readableSha256: sha256(readable),
+        ...(continuation
+            ? { continuationStateSha256: sha256(stableStringify(continuation)) }
+            : {}),
+    };
+}
+function appendToolCall(assistant, item, toolCallApi, includeItemId, canonicalizeFunctionArguments) {
+    const id = providerToolCallId(item.callId, includeItemId ? item.id : undefined, toolCallApi);
+    assistant.calls = [
+        ...assistant.calls,
+        {
+            id,
+            kind: item.kind,
+            name: toolWireName(item.namespace, item.name),
+            input: toolArguments(item.kind, item.input, canonicalizeFunctionArguments),
+        },
+    ];
+    return id;
+}
+function appendHostedToolCall(assistant, item) {
+    const payload = {
+        ...item.payload,
+        type: item.providerType,
+        id: item.id,
+    };
+    if (item.status)
+        payload.status = item.status;
+    else
+        delete payload.status;
+    assistant.calls = [
+        ...assistant.calls,
+        {
+            id: item.id,
+            kind: "hosted",
+            name: item.tool,
+            input: payload,
+        },
+    ];
+}
+function continuationReadableText(item, continuation) {
+    if (continuation?.kind === "anthropic_thinking")
+        return normalizedReadable(continuation.thinking);
+    if (continuation?.kind === "anthropic_redacted_thinking")
+        return "";
+    return normalizedReadable([...item.summary, ...item.content].join("\n"));
+}
+// Streamed reasoning reaches clients as delta concatenations whose whitespace
+// joins differ from the aggregated response body (part separators, trailing
+// newlines), and the client echoes whichever form it saw. Whitespace therefore
+// cannot participate in conversation identity.
+function normalizedReadable(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function fingerprintChain(seed, steps) {
+    let hash = seed;
+    return conversationFingerprintSteps(steps).map((step) => {
+        hash = extendFingerprintHash(hash, step);
+        return hash;
+    });
+}
+function conversationFingerprintSteps(steps) {
+    const positional = [];
+    let sawConversationStep = false;
+    for (const step of steps) {
+        if (step.actor !== "system" && step.actor !== "developer") {
+            sawConversationStep = true;
+            const previous = positional.at(-1);
+            if (step.actor === "user" && previous?.actor === "user") {
+                previous.content = appendPositionalFingerprintContent(previous.content, step.content);
+                previous.itemIndex = step.itemIndex;
+            }
+            else {
+                positional.push({ ...step });
+            }
+            continue;
+        }
+        if (!sawConversationStep)
+            continue;
+        const text = fingerprintReadableText(step.content);
+        if (!text)
+            continue;
+        const previous = positional.at(-1);
+        if (previous?.actor === "user" || previous?.actor === "tool") {
+            previous.content = appendPositionalFingerprintText(previous.content, text);
+            previous.itemIndex = step.itemIndex;
+            continue;
+        }
+        positional.push({
+            actor: "user",
+            content: [{ type: "text", text }],
+            calls: [],
+            resultCallId: null,
+            itemIndex: step.itemIndex,
+        });
+    }
+    return positional;
+}
+function fingerprintReadableText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((part) => part.type === "text" ? part.text : "(image omitted)").join("\n");
+}
+function appendPositionalFingerprintText(content, text) {
+    return appendPositionalFingerprintContent(content, [{ type: "text", text }]);
+}
+function appendPositionalFingerprintContent(content, appended) {
+    const contentParts = typeof content === "string"
+        ? [{ type: "text", text: content }]
+        : content ?? [];
+    const appendedParts = typeof appended === "string"
+        ? [{ type: "text", text: appended }]
+        : appended ?? [];
+    return [...contentParts, ...appendedParts];
+}
+function extendFingerprintHash(lastHash, step) {
+    return sha256(`${lastHash}\u0000${canonicalInteractionFingerprintStep(step)}`);
+}
+function toolArguments(kind, input, canonicalizeFunctionArguments) {
+    if (kind === "custom")
+        return JSON.stringify({ input: typeof input === "string" ? input : "" });
+    if (canonicalizeFunctionArguments && typeof input === "string") {
+        try {
+            const parsed = JSON.parse(input);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // Provider execution reports malformed function arguments separately;
+            // fingerprinting itself must remain best-effort.
+        }
+    }
+    return input;
+}
+function deepestDistinctHashes(chains, max) {
+    const result = [];
+    const seen = new Set();
+    for (let depth = 1; result.length < max; depth += 1) {
+        let found = false;
+        for (const chain of chains) {
+            const hash = chain.at(-depth);
+            if (!hash)
+                continue;
+            found = true;
+            if (!seen.has(hash)) {
+                seen.add(hash);
+                result.push(hash);
+                if (result.length === max)
+                    break;
+            }
+        }
+        if (!found)
+            break;
+    }
+    return result;
+}
+function identityKey(identity) {
+    return `${identity.provider}\u0000${identity.api}\u0000${identity.model}`;
+}
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}

package/dist/context/interaction_fingerprint_format.d.ts

@@ -0,0 +1,42 @@
+import type { InteractionContent, InteractionRequest } from "../interaction/types.js";
+export type FingerprintContent = string | Array<{
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    url: string;
+    detail?: "auto" | "low" | "high" | "original";
+} | {
+    type: "tool_reference";
+    toolName: string;
+}> | null;
+export type FingerprintCall = {
+    id: string;
+    kind: "function" | "custom" | "hosted";
+    name: string;
+    input: unknown;
+};
+export type ReasoningFingerprint = {
+    itemId?: string;
+    readableSha256: string;
+    continuationStateSha256?: string;
+};
+export type InteractionFingerprintStep = {
+    actor: "system" | "developer" | "user" | "assistant" | "tool";
+    content: FingerprintContent;
+    calls: FingerprintCall[];
+    resultCallId: string | null;
+    itemIndex: number;
+    itemId?: string;
+    phase?: "commentary" | "final_answer";
+    reasoning?: ReasoningFingerprint[];
+};
+export declare function interactionFingerprintHeadHash(routerId: string, request: InteractionRequest): string;
+export declare function interactionOptionsFingerprints(request: InteractionRequest): {
+    tool_choice_fp: string;
+    response_format_fp: string;
+};
+export declare function canonicalInteractionFingerprintStep(step: InteractionFingerprintStep): string;
+export declare function interactionFingerprintContent(content: string | InteractionContent[] | null, shape: "string" | "parts" | "null" | "absent"): FingerprintContent;
+export declare function normalizedAssistantFingerprintContent(content: string | InteractionContent[] | null, shape: "string" | "parts" | "null" | "absent"): FingerprintContent;
+export declare function appendFingerprintContentText(content: FingerprintContent, text: string): FingerprintContent;