@mupt-ai/dari-gateway 0.0.0-stage → 0.2.0

package/src/context/interaction_fingerprint_format.ts

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+
+import { stableStringify } from "@mupt-ai/dari-router/policy-engine";
+
+import type {
+  InteractionContent,
+  InteractionRequest,
+} from "../interaction/types";
+
+// Bump when canonical fingerprint semantics change so persisted hashes from
+// incompatible contracts remain disjoint.
+const INTERACTION_FINGERPRINT_VERSION = "interaction-v3";
+
+const OPTION_FINGERPRINT_VERSION = "interaction-options-v1";
+
+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 function interactionFingerprintHeadHash(
+  routerId: string,
+  request: InteractionRequest,
+): string {
+  const systemItems: Array<{ actor: "system" | "developer"; content: FingerprintContent }> = [];
+  for (const item of request.items) {
+    if (
+      item.type !== "message"
+      || (item.role !== "system" && item.role !== "developer")
+    ) {
+      break;
+    }
+    systemItems.push({
+      actor: item.role,
+      content: systemFingerprintContent(item.content, item.contentShape),
+    });
+  }
+  return sha256(stableStringify({
+    version: INTERACTION_FINGERPRINT_VERSION,
+    routerId,
+    ...(request.agentContext === undefined ? {} : { agentContext: {
+      requestClass: request.agentContext.requestClass,
+      agentId: request.agentContext.agentId ?? null,
+    } }),
+    instructions: request.instructions ?? null,
+    systemItems,
+    tools: request.tools,
+  }));
+}
+
+function systemFingerprintContent(
+  content: string | InteractionContent[] | null,
+  shape: "string" | "parts" | "null" | "absent",
+): FingerprintContent {
+  const normalized = interactionFingerprintContent(content, shape);
+  // Anthropic defines a string system value and one plain text block as
+  // equivalent. Preserve that established head identity without flattening
+  // structured system content such as images or multiple blocks.
+  if (
+    Array.isArray(normalized)
+    && normalized.length === 1
+    && normalized[0]?.type === "text"
+  ) {
+    return normalized[0].text;
+  }
+  return normalized;
+}
+
+export function interactionOptionsFingerprints(
+  request: InteractionRequest,
+): { tool_choice_fp: string; response_format_fp: string } {
+  return {
+    tool_choice_fp: optionFingerprint("tool-choice", request.toolChoice ?? null),
+    response_format_fp: optionFingerprint(
+      "response-format",
+      request.responseFormat ?? null,
+    ),
+  };
+}
+
+export function canonicalInteractionFingerprintStep(
+  step: InteractionFingerprintStep,
+): string {
+  return stableStringify({
+    actor: step.actor,
+    content: step.content,
+    calls: step.calls.length > 0 ? step.calls : null,
+    resultCallId: step.resultCallId,
+    ...(step.itemId ? { itemId: step.itemId } : {}),
+    ...(step.phase ? { phase: step.phase } : {}),
+    ...(step.reasoning ? { reasoning: step.reasoning } : {}),
+  });
+}
+
+export function interactionFingerprintContent(
+  content: string | InteractionContent[] | null,
+  shape: "string" | "parts" | "null" | "absent",
+): FingerprintContent {
+  // Preserve the established identity rule that absent and explicit null
+  // content are equivalent. Structured parts remain distinct from strings.
+  if (shape === "absent" || shape === "null") return null;
+  if (shape === "string") {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+    return content
+      .filter((part): part is { type: "text"; text: string } =>
+        part.type === "text"
+      )
+      .map((part) => part.text)
+      .join("");
+  }
+  if (!Array.isArray(content)) return [];
+  return content.map((part) => {
+    if (part.type === "text") return { type: "text" as const, text: part.text };
+    if (part.type === "tool_reference") {
+      return {
+        type: "tool_reference" as const,
+        toolName: part.toolName,
+      };
+    }
+    return {
+      type: "image" as const,
+      url: part.url,
+      ...(part.detail !== undefined ? { detail: part.detail } : {}),
+    };
+  });
+}
+
+export function normalizedAssistantFingerprintContent(
+  content: string | InteractionContent[] | null,
+  shape: "string" | "parts" | "null" | "absent",
+): FingerprintContent {
+  const normalized = interactionFingerprintContent(content, shape);
+  return typeof normalized === "string" && normalized.trim() === ""
+    ? null
+    : normalized;
+}
+
+export function appendFingerprintContentText(
+  content: FingerprintContent,
+  text: string,
+): FingerprintContent {
+  if (!text) return content;
+  if (typeof content === "string") return content ? `${content}\n${text}` : text;
+  if (Array.isArray(content)) return [...content, { type: "text", text }];
+  return text;
+}
+
+function optionFingerprint(kind: string, value: unknown): string {
+  return sha256(
+    `${OPTION_FINGERPRINT_VERSION}\u0000${kind}\u0000${stableStringify(value)}`,
+  );
+}
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}

package/src/context/interaction_lease_depth.ts

@@ -0,0 +1,150 @@
+import type {
+  InteractionContent,
+  InteractionMessage,
+  InteractionRequest,
+} from "../interaction/types";
+
+type AssistantGroup = {
+  kind: "assistant";
+  rawBlocks: number;
+  hasContent: boolean;
+  hasReasoning: boolean;
+  hasToolCalls: boolean;
+  hostedToolCarrier: boolean;
+};
+
+type LastGroup = AssistantGroup | { kind: "other" } | null;
+
+// Monotonic, target-independent position used only to fence asynchronous
+// lease writes. It follows canonical Interaction grouping and deliberately
+// does not serialize selector messages or approximate provider cache blocks.
+export function interactionLeaseFenceDepth(
+  request: InteractionRequest,
+): number {
+  const state: { depth: number; last: LastGroup } = {
+    depth: 0,
+    last: null,
+  };
+
+  const startAssistant = (args: {
+    rawBlocks: number;
+    hasContent?: boolean;
+    hasReasoning?: boolean;
+    hasToolCalls?: boolean;
+    hostedToolCarrier?: boolean;
+  }): AssistantGroup => {
+    const assistant: AssistantGroup = {
+      kind: "assistant",
+      rawBlocks: args.rawBlocks,
+      hasContent: args.hasContent ?? false,
+      hasReasoning: args.hasReasoning ?? false,
+      hasToolCalls: args.hasToolCalls ?? false,
+      hostedToolCarrier: args.hostedToolCarrier ?? false,
+    };
+    state.depth += groupBlockCount(assistant.rawBlocks);
+    state.last = assistant;
+    return assistant;
+  };
+
+  const addAssistantBlock = (assistant: AssistantGroup): void => {
+    const before = groupBlockCount(assistant.rawBlocks);
+    assistant.rawBlocks += 1;
+    state.depth += groupBlockCount(assistant.rawBlocks) - before;
+  };
+
+  const addOther = (blocks: number): void => {
+    state.depth += groupBlockCount(blocks);
+    state.last = { kind: "other" };
+  };
+
+  for (const item of request.items) {
+    if (item.type === "reasoning") {
+      if (
+        state.last?.kind === "assistant"
+        && !state.last.hasContent
+        && !state.last.hostedToolCarrier
+      ) {
+        state.last.hasReasoning = true;
+      } else {
+        startAssistant({ rawBlocks: 0, hasReasoning: true });
+      }
+      continue;
+    }
+
+    if (item.type === "reasoning_configuration") {
+      continue;
+    }
+
+    if (item.type === "tool_result") {
+      addOther(1);
+      continue;
+    }
+
+    if (item.type === "tool_call" || item.type === "hosted_tool_call") {
+      const assistant = state.last?.kind === "assistant"
+        ? state.last
+        : startAssistant({ rawBlocks: 0 });
+      addAssistantBlock(assistant);
+      assistant.hasToolCalls = true;
+      if (item.type === "hosted_tool_call") {
+        assistant.hostedToolCarrier = true;
+      }
+      continue;
+    }
+
+    if (item.role === "system" || item.role === "developer") {
+      state.last = { kind: "other" };
+      continue;
+    }
+
+    const blocks = messageContentBlocks(item);
+    const hasContent = blocks > 0;
+    if (
+      item.role === "assistant"
+      && state.last?.kind === "assistant"
+      && state.last.hasReasoning
+      && !state.last.hasContent
+      && !state.last.hasToolCalls
+    ) {
+      const before = groupBlockCount(state.last.rawBlocks);
+      state.last.rawBlocks = blocks;
+      state.last.hasContent = hasContent;
+      state.depth += groupBlockCount(state.last.rawBlocks) - before;
+      continue;
+    }
+
+    if (item.role === "assistant") {
+      startAssistant({ rawBlocks: blocks, hasContent });
+    } else {
+      addOther(blocks);
+    }
+  }
+
+  return state.depth;
+}
+
+function messageContentBlocks(message: InteractionMessage): number {
+  if (message.contentShape === "absent" || message.contentShape === "null") {
+    return 0;
+  }
+  if (message.contentShape === "string") {
+    return stringContent(message.content).length > 0 ? 1 : 0;
+  }
+  if (Array.isArray(message.content)) return message.content.length;
+  return message.content === null ? 0 : 1;
+}
+
+function stringContent(content: string | InteractionContent[] | null): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part): part is { type: "text"; text: string } =>
+      part.type === "text"
+    )
+    .map((part) => part.text)
+    .join("");
+}
+
+function groupBlockCount(rawBlocks: number): number {
+  return Math.max(1, rawBlocks);
+}

package/src/context/lease_history.ts

@@ -0,0 +1,200 @@
+import {
+  isReasoningEffort,
+  isRecord,
+  routingCandidateKey,
+  type ChatMessage,
+  type JsonValue,
+  type RouterPrefixHit,
+  type RoutingCandidate,
+  type SelectorLeaseHistoryEntry,
+} from "@mupt-ai/dari-router/policy-engine";
+
+const MAX_HISTORY_LEASES = 3;
+const MAX_OBSERVATION_CHARS = 3_000;
+const TEST_COMMAND = /(?:^|\s)(?:bun|npm|pnpm|yarn|uv|pytest|cargo|go|make|npx|bash)\b[^\n]*(?:test|check|lint|typecheck|vet|build)/i;
+
+type LeaseSegment = {
+  candidate: RoutingCandidate;
+  requestedTurns: number;
+  lastRemaining: number;
+  rationale: string;
+};
+
+type ConversationTurn = {
+  assistant: ChatMessage;
+  toolResults: ChatMessage[];
+};
+
+export function leaseHistoryFromPrefixHits(args: {
+  prefixHits: readonly RouterPrefixHit[];
+  conversationId: string;
+  candidates: readonly RoutingCandidate[];
+  messages: readonly ChatMessage[];
+}): SelectorLeaseHistoryEntry[] {
+  const candidateKeys = new Set(args.candidates.map(routingCandidateKey));
+  const hits = deduplicatedHits(args.prefixHits)
+    .filter((hit) => hit.conversation_id === args.conversationId)
+    .sort((left, right) => left.message_depth - right.message_depth);
+  const segments: LeaseSegment[] = [];
+  for (const hit of hits) {
+    const remaining = hit.lease_turns_remaining;
+    const effort = hit.next_reasoning_effort;
+    if (
+      typeof remaining !== "number" ||
+      !Number.isInteger(remaining) ||
+      remaining < 0 ||
+      !hit.next_model ||
+      !isReasoningEffort(effort)
+    ) {
+      continue;
+    }
+    const candidate = { model: hit.next_model, reasoningEffort: effort };
+    if (!candidateKeys.has(routingCandidateKey(candidate))) continue;
+    const current = segments.at(-1);
+    if (
+      current !== undefined &&
+      routingCandidateKey(current.candidate) === routingCandidateKey(candidate) &&
+      remaining < current.lastRemaining
+    ) {
+      current.lastRemaining = remaining;
+      continue;
+    }
+    segments.push({
+      candidate,
+      requestedTurns: remaining + 1,
+      lastRemaining: remaining,
+      rationale: hit.reason ?? "",
+    });
+  }
+
+  const recent = segments.slice(-MAX_HISTORY_LEASES);
+  const turns = conversationTurns(args.messages);
+  let turnCursor = turns.length;
+  const history = [...recent].reverse().map((segment) => {
+    const completedTurns = Math.max(
+      0,
+      Math.min(segment.requestedTurns, segment.requestedTurns - segment.lastRemaining),
+    );
+    const start = Math.max(0, turnCursor - completedTurns);
+    const observation = turns.slice(start, turnCursor);
+    turnCursor = start;
+    return observationForSegment(segment, completedTurns, observation);
+  });
+  return history.reverse();
+}
+
+function observationForSegment(
+  segment: LeaseSegment,
+  completedTurns: number,
+  turns: readonly ConversationTurn[],
+): SelectorLeaseHistoryEntry {
+  const calls = turns.flatMap((turn) => turn.assistant.tool_calls ?? []);
+  const results = turns.flatMap((turn) => turn.toolResults);
+  const lastCall = calls.at(-1);
+  const callId = typeof lastCall?.["id"] === "string" ? lastCall["id"] : null;
+  const lastResult = callId === null
+    ? undefined
+    : [...results].reverse().find((result) => result.tool_call_id === callId);
+  const testCall = [...calls].reverse().find((call) => {
+    const parsed = toolCall(call);
+    return parsed?.name === "bash" && TEST_COMMAND.test(command(parsed.arguments));
+  });
+  const parsedLastCall = lastCall === undefined ? null : toolCall(lastCall);
+  const parsedTestCall = testCall === undefined ? null : toolCall(testCall);
+  const testCallId = typeof testCall?.["id"] === "string" ? testCall["id"] : null;
+  const testResult = testCallId === null
+    ? undefined
+    : [...results].reverse().find((result) => result.tool_call_id === testCallId);
+  const lastAssistant = turns.at(-1)?.assistant;
+  const thought = lastAssistant?.reasoning_content
+    ?? lastAssistant?.reasoning_text
+    ?? lastAssistant?.reasoning
+    ?? null;
+  return {
+    candidate: {
+      model: segment.candidate.model,
+      thinking_level: segment.candidate.reasoningEffort,
+    },
+    requested_turns: segment.requestedTurns,
+    completed_turns: completedTurns,
+    rationale: truncate(segment.rationale),
+    last_agent_thought: thought === null ? null : truncate(thought),
+    last_tool_call: parsedLastCall === null
+      ? null
+      : { name: parsedLastCall.name, arguments: compactJson(parsedLastCall.arguments) },
+    last_tool_result: lastResult === undefined ? null : compactJson(lastResult.content ?? null),
+    // Generic Chat Completions tool results do not carry a portable error bit
+    // or a trustworthy changed-file count.
+    tool_errors: null,
+    files_changed: null,
+    tests: parsedTestCall === null
+      ? null
+      : {
+          command: truncate(command(parsedTestCall.arguments)),
+          status: "unknown",
+          result: testResult === undefined ? null : compactJson(testResult.content ?? null),
+        },
+  };
+}
+
+function deduplicatedHits(hits: readonly RouterPrefixHit[]): RouterPrefixHit[] {
+  const byState = new Map<string, RouterPrefixHit>();
+  for (const hit of hits) {
+    const key = [
+      hit.conversation_id,
+      hit.message_depth,
+      hit.next_model ?? "",
+      hit.next_reasoning_effort ?? "",
+      hit.lease_turns_remaining ?? "",
+    ].join("\u0000");
+    const existing = byState.get(key);
+    if (existing === undefined || existing.updated_at < hit.updated_at) byState.set(key, hit);
+  }
+  return [...byState.values()];
+}
+
+function conversationTurns(messages: readonly ChatMessage[]): ConversationTurn[] {
+  const turns: ConversationTurn[] = [];
+  let current: ConversationTurn | undefined;
+  for (const message of messages) {
+    if (message.role === "assistant") {
+      current = { assistant: message, toolResults: [] };
+      turns.push(current);
+    } else if (message.role === "tool" && current !== undefined) {
+      current.toolResults.push(message);
+    }
+  }
+  return turns;
+}
+
+function toolCall(value: Record<string, unknown>): { name: string; arguments: JsonValue } | null {
+  const fn = value["function"];
+  if (!isRecord(fn) || typeof fn.name !== "string") return null;
+  const rawArguments = fn.arguments ?? {};
+  if (typeof rawArguments !== "string") {
+    return { name: fn.name, arguments: compactJson(rawArguments) };
+  }
+  try {
+    return { name: fn.name, arguments: JSON.parse(rawArguments) as JsonValue };
+  } catch {
+    return { name: fn.name, arguments: rawArguments };
+  }
+}
+
+function command(value: JsonValue): string {
+  return isRecord(value) && typeof value.command === "string" ? value.command : "";
+}
+
+function compactJson(value: unknown): JsonValue {
+  const serialized = JSON.stringify(value) ?? "null";
+  if (serialized.length <= MAX_OBSERVATION_CHARS) {
+    return JSON.parse(serialized) as JsonValue;
+  }
+  return `${serialized.slice(0, MAX_OBSERVATION_CHARS)}…`;
+}
+
+function truncate(value: string): string {
+  return value.length <= MAX_OBSERVATION_CHARS
+    ? value
+    : `${value.slice(0, MAX_OBSERVATION_CHARS)}…`;
+}

package/src/context/pricing.ts

@@ -0,0 +1,30 @@
+import type { ModelPricing, PricingLookup } from "@mupt-ai/dari-router/policy-engine";
+import type { ResolvedRouter } from "../types";
+
+
+export function pricingLookupForRouter(credentials: ResolvedRouter): PricingLookup {
+  return (model: string): ModelPricing | null => modelPricingForRouter(credentials, model);
+}
+
+export function modelPricingForRouter(
+  credentials: ResolvedRouter,
+  model: string,
+): ModelPricing | null {
+  const price = credentials.model_prices?.[model];
+  if (!price || typeof price.input !== "number" || typeof price.output !== "number") return null;
+  // Null cached rates mean the provider publishes none: bill cached prompt
+  // buckets at the input rate, never for free.
+  return {
+    input: price.input,
+    output: price.output,
+    cacheRead: price.cached_input ?? price.input,
+    cacheWrite: price.cache_write ?? price.input,
+    ...(price.tiers?.length ? { tiers: price.tiers.map((tier) => ({
+      inputTokensAbove: tier.input_tokens_above,
+      input: tier.input,
+      output: tier.output,
+      cacheRead: tier.cached_input ?? tier.input,
+      cacheWrite: tier.cache_write ?? tier.input,
+    })) } : {}),
+  };
+}