@mupt-ai/dari-router 0.1.0

package/src/pi_types.ts

@@ -0,0 +1,71 @@
+import type {
+  Api,
+  AssistantMessage,
+  AssistantMessageEvent,
+  Context,
+  Model,
+  SimpleStreamOptions,
+} from "@mupt-ai/pi-ai";
+
+import type { ChatCompletionRequest, ReasoningEffort } from "./types.js";
+import type {
+  RouterCandidate,
+  RouterExecutorInput,
+  RouterExecutorResult,
+  RouterModel,
+  RouterRequest,
+} from "./framework_types.js";
+
+export type PiModel = Model<Api>;
+
+export type PiCredentialInput = {
+  provider: string;
+  model: string;
+  api: string;
+  purpose: "execution" | "selector";
+};
+
+export type PiApiKey = string | ((input: PiCredentialInput) => string | Promise<string>);
+
+export type PiModelRegistry = {
+  getModel(provider: string, id: string): PiModel | undefined;
+  completeSimple(
+    model: PiModel,
+    context: Context,
+    options?: SimpleStreamOptions,
+  ): Promise<AssistantMessage>;
+  streamSimple(
+    model: PiModel,
+    context: Context,
+    options?: SimpleStreamOptions,
+  ): AsyncIterable<AssistantMessageEvent>;
+};
+
+export type CreatePiRuntimeOptions = {
+  apiKey: PiApiKey;
+  registry?: PiModelRegistry;
+  timeoutMs?: number;
+  maxRetries?: number;
+};
+
+export type PiRouterModelOptions<Metadata = unknown> = Omit<
+  RouterModel<Metadata>,
+  "id" | "executor" | "provider" | "api"
+>;
+
+export type PiRuntime = {
+  model<Metadata = unknown>(
+    id: string,
+    options?: Partial<PiRouterModelOptions<Metadata>>,
+  ): RouterModel<Metadata>;
+  execute<Metadata>(input: RouterExecutorInput<Metadata>): Promise<RouterExecutorResult>;
+  select(request: ChatCompletionRequest, signal?: AbortSignal): Promise<string>;
+};
+
+export type PiExecution = {
+  request: RouterRequest;
+  candidate: Pick<RouterCandidate, "id" | "provider" | "api">;
+  reasoningEffort: ReasoningEffort;
+  signal: AbortSignal;
+  purpose: PiCredentialInput["purpose"];
+};

package/src/portable_reasoning_state.ts

@@ -0,0 +1,129 @@
+import { RouterFrameworkError } from "./framework_error.js";
+import type { ProviderIdentity } from "./continuation_state.js";
+import { isRecord } from "./types.js";
+
+const PREFIX = "dari-ir-v1.";
+const FAMILY_PREFIX = "dari-ir-";
+const MAX_JSON_BYTES = 4 * 1024;
+const MAX_ENCODED_CHARS = Math.ceil(MAX_JSON_BYTES / 3) * 4;
+
+export type PortableReasoningState = {
+  source?: ProviderIdentity;
+  itemId?: string;
+};
+
+export function encodePortableReasoningState(state: PortableReasoningState): string {
+  const source = state.source ? providerIdentity(state.source, "configuration") : undefined;
+  const itemId = state.itemId ? boundedString(state.itemId, 512, "configuration", "item ID") : undefined;
+  const payload = {
+    v: 1,
+    ...(source ? { source } : {}),
+    ...(itemId ? { id: itemId } : {}),
+  };
+  const json = JSON.stringify(payload);
+  if (Buffer.byteLength(json, "utf8") > MAX_JSON_BYTES) {
+    throw invalidPortableState(
+      "configuration",
+      "Portable reasoning state exceeds the encoded size limit.",
+    );
+  }
+  return `${PREFIX}${Buffer.from(json, "utf8").toString("base64url")}`;
+}
+
+export function decodeUntrustedPortableReasoningState(value: string): PortableReasoningState | null {
+  if (!value.startsWith(FAMILY_PREFIX)) return null;
+  if (!value.startsWith(PREFIX)) {
+    throw invalidPortableState(
+      "invalid_request",
+      "Portable reasoning state version is not supported.",
+    );
+  }
+
+  const encoded = value.slice(PREFIX.length);
+  if (!encoded || encoded.length > MAX_ENCODED_CHARS || !/^[A-Za-z0-9_-]+$/.test(encoded)) {
+    throw invalidPortableState(
+      "invalid_request",
+      "Portable reasoning state encoding is invalid.",
+    );
+  }
+  const bytes = Buffer.from(encoded, "base64url");
+  if (bytes.length > MAX_JSON_BYTES || bytes.toString("base64url") !== encoded) {
+    throw invalidPortableState(
+      "invalid_request",
+      "Portable reasoning state encoding is invalid.",
+    );
+  }
+
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw invalidPortableState(
+      "invalid_request",
+      "Portable reasoning state payload is invalid.",
+    );
+  }
+  if (!isRecord(decoded) || decoded.v !== 1) {
+    throw invalidPortableState(
+      "invalid_request",
+      "Portable reasoning state schema is invalid.",
+    );
+  }
+  const keys = Object.keys(decoded);
+  if (!keys.every((key) => key === "v" || key === "source" || key === "id")) {
+    throw invalidPortableState(
+      "invalid_request",
+      "Portable reasoning state schema is invalid.",
+    );
+  }
+  return {
+    ...(decoded.source !== undefined
+      ? { source: providerIdentity(decoded.source, "invalid_request") }
+      : {}),
+    ...(decoded.id !== undefined
+      ? { itemId: boundedString(decoded.id, 512, "invalid_request", "item ID") }
+      : {}),
+  };
+}
+
+function providerIdentity(
+  value: unknown,
+  kind: "configuration" | "invalid_request",
+): ProviderIdentity {
+  if (!isRecord(value) || !hasExactKeys(value, ["provider", "api", "model"])) {
+    throw invalidPortableState(kind, "Portable reasoning state source is invalid.");
+  }
+  return {
+    provider: boundedString(value.provider, 128, kind, "provider"),
+    api: boundedString(value.api, 128, kind, "API"),
+    model: boundedString(value.model, 512, kind, "model"),
+  };
+}
+
+function boundedString(
+  value: unknown,
+  maxLength: number,
+  kind: "configuration" | "invalid_request",
+  field: string,
+): string {
+  if (typeof value !== "string" || !value || value.length > maxLength) {
+    throw invalidPortableState(kind, `Portable reasoning state ${field} is invalid.`);
+  }
+  return value;
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  const actual = Object.keys(value);
+  return actual.length === keys.length && keys.every((key) => actual.includes(key));
+}
+
+function invalidPortableState(
+  kind: "configuration" | "invalid_request",
+  message: string,
+): RouterFrameworkError {
+  return new RouterFrameworkError(
+    kind,
+    message,
+    "invalid_provider_continuation_state",
+  );
+}

package/src/previous_decision.ts

@@ -0,0 +1,109 @@
+import {
+  isReasoningEffort,
+  routingCandidateKey,
+  type PreviousDecision,
+  type RouterPrefixHit,
+  type RoutingCandidate,
+} from "./types.js";
+
+// A previous decision only carries over when its exact model/thinking-level
+// pair is still a candidate for this request.
+export function compatiblePreviousDecision(
+  previousDecision: PreviousDecision | undefined,
+  candidates: RoutingCandidate[],
+): PreviousDecision | undefined {
+  if (previousDecision === undefined) return undefined;
+  const previousKey = routingCandidateKey(previousDecision);
+  return candidates.some((candidate) => routingCandidateKey(candidate) === previousKey)
+    ? previousDecision
+    : undefined;
+}
+
+export type ActiveLease = RoutingCandidate & { turnsRemaining: number };
+
+// An unexpired lease from the deepest identity hit. The lease names the stored
+// next-turn target exactly; if that pair is no longer a candidate for this
+// request, the lease dissolves and routing decides fresh.
+export function activeLeaseFromHit(
+  entry: RouterPrefixHit,
+  candidates: RoutingCandidate[],
+): ActiveLease | undefined {
+  const remaining = entry.lease_turns_remaining;
+  if (typeof remaining !== "number" || !Number.isInteger(remaining) || remaining <= 0) {
+    return undefined;
+  }
+  const nextEffort = entry.next_reasoning_effort;
+  if (!entry.next_model || !isReasoningEffort(nextEffort)) return undefined;
+  const target = { model: entry.next_model, reasoningEffort: nextEffort };
+  const targetKey = routingCandidateKey(target);
+  return candidates.some((candidate) => routingCandidateKey(candidate) === targetKey)
+    ? { ...target, turnsRemaining: remaining }
+    : undefined;
+}
+
+export type PendingLease = RoutingCandidate & {
+  turns: number;
+  reason: string | null;
+  outputText: string | null;
+};
+
+// The next lease decided ahead of the active one's expiry. Like the active
+// lease, it only survives while its exact pair is still a candidate.
+export function pendingLeaseFromHit(
+  entry: RouterPrefixHit,
+  candidates: RoutingCandidate[],
+): PendingLease | undefined {
+  const turns = entry.pending_lease_turns;
+  if (typeof turns !== "number" || !Number.isInteger(turns) || turns <= 0) {
+    return undefined;
+  }
+  const effort = entry.pending_lease_reasoning_effort;
+  if (!entry.pending_lease_model || !isReasoningEffort(effort)) return undefined;
+  const target = { model: entry.pending_lease_model, reasoningEffort: effort };
+  const targetKey = routingCandidateKey(target);
+  return candidates.some((candidate) => routingCandidateKey(candidate) === targetKey)
+    ? {
+        ...target,
+        turns,
+        reason: entry.pending_lease_reason ?? null,
+        outputText: entry.pending_lease_output_text ?? null,
+      }
+    : undefined;
+}
+
+// Reconstructs the previous decision from the deepest warm-prefix entry: the
+// stored next-turn recommendation when it is still a candidate, otherwise the
+// serving pair.
+export function previousDecisionFromHit(
+  entry: RouterPrefixHit,
+  candidates: RoutingCandidate[],
+): PreviousDecision | undefined {
+  const candidateKeys = new Set(candidates.map(routingCandidateKey));
+  const uniqueCandidateForModel = (model: string): RoutingCandidate | null => {
+    const matching = candidates.filter((candidate) => candidate.model === model);
+    return matching.length === 1 ? matching[0]! : null;
+  };
+  const nextEffort = entry.next_reasoning_effort;
+  const storedNext = entry.next_model
+    ? isReasoningEffort(nextEffort)
+      ? { model: entry.next_model, reasoningEffort: nextEffort }
+      : uniqueCandidateForModel(entry.next_model)
+    : null;
+  const serving = isReasoningEffort(entry.reasoning_bucket)
+    ? { model: entry.model, reasoningEffort: entry.reasoning_bucket }
+    : uniqueCandidateForModel(entry.model);
+  const storedNextIsCandidate = Boolean(
+    storedNext && candidateKeys.has(routingCandidateKey(storedNext)),
+  );
+  const selected = storedNext && storedNextIsCandidate
+    ? storedNext
+    : serving && candidateKeys.has(routingCandidateKey(serving))
+      ? serving
+      : null;
+  if (!selected) return undefined;
+  const storedNextWasRejected = Boolean(entry.next_model) && !storedNextIsCandidate;
+  return {
+    ...selected,
+    reason: storedNextWasRejected ? "" : (entry.reason ?? ""),
+  };
+}

package/src/prompts.ts

@@ -0,0 +1,69 @@
+// Selector system prompts, standalone so prompt review never requires
+// reading request-assembly code. Per-request candidate data rides in the
+// user message, keeping these byte-stable for provider prompt caching.
+
+import { FIXED_TURN_COST_PROJECTED_TURNS } from "./fixed_turn_cost_config.js";
+
+// Interpolated where a prompt names the projection horizons so the wording
+// cannot drift from the config that produces the data.
+const PROJECTED_TURNS_PHRASE = FIXED_TURN_COST_PROJECTED_TURNS.join(", ");
+
+export const SELECTOR_SYSTEM_PROMPT = `You are Dari's model router. Pick the best candidate model/thinking-level pair for the user's request.
+
+# Selection procedure
+
+1. Capability first: make sure the selected pair can reasonably handle the task. Consider both model capability and how much thinking the task needs; capability is never traded away for cost.
+2. Use imported eval scorecards as benchmark evidence when relevant.
+3. A missing benchmark score means that candidate pair was not evaluated on that benchmark; do not treat it as zero, failure, or negative evidence.
+4. When several pairs are viable on capability, use cost_estimates as the deciding factor between them.
+5. Prefer the previous_decision pair when the task hasn't changed.
+
+# Cost comparison rules
+
+- fixed_turn_cost_estimate.projections is the primary cost metric whenever it is present. Each entry estimates the whole agent loop from this decision point out to projected_turns requests, using current cache warmth, provider cache rules, cache hit probabilities, and output tokens folded into later requests. Compare candidates at the horizon the task looks likely to need.
+- Candidates with fixed_turn_cost_estimate are the preferred cost-comparison pool when capability is otherwise comparable.
+- Do not rank candidates by output_cost_per_mtok or est_input_cost_usd ahead of fixed_turn_cost_estimate.projections. Do not discard those estimates just because some candidates lack them.
+- For candidates without fixed_turn_cost_estimate, use est_input_cost_usd and output_cost_per_mtok as fallback cost evidence, and select such a candidate only when its capability and fallback pricing make it a better fit than candidates with fixed-turn estimates.
+
+# Output
+
+Return JSON matching the provided schema. selected_model and reasoning_effort must exactly match one candidate pair.
+The runtime chooses provider fallbacks separately; return only the primary decision.`;
+
+export const CUSTOM_SELECTOR_SYSTEM_PROMPT = `You are Dari's model router. Pick the best candidate model/thinking-level pair for the user's request.
+This router is configured with user-authored rules. Each custom_rules entry pairs a natural-language when condition with a model and an optional thinking_level. A null thinking_level means Auto: choose the most appropriate candidate thinking level for that rule's model. A non-null thinking_level pins the exact pair.
+Decide which rule's when condition best describes the current request — judge the latest phase or intent of the conversation (for example planning versus implementation), not just the first message — and select that rule's model and either its pinned thinking_level or an appropriate enabled level when it is Auto.
+custom_rules is ordered by model price, most expensive first; the order is presentation, not priority.
+When several rules match, pick the one whose when condition is most specific to the current request.
+When no rule matches, select default_target if it is set; its null thinking_level also means Auto. Otherwise prefer previous_decision when it is a candidate; otherwise pick the most capable candidate pair.
+Prefer previous_decision while the matched rule (or task phase) hasn't changed.
+Use imported eval scorecards as benchmark evidence when relevant. A missing benchmark score means that candidate pair was not evaluated on that benchmark; do not treat it as zero, failure, or negative evidence.
+Use cost_estimates only to break ties between rule-matched candidates or to choose among an Auto target's viable thinking levels; a rule match is never traded away for cost.
+When using cost_estimates, fixed_turn_cost_estimate.projections is the primary cost metric whenever present because it includes current cache warmth and projected loop cost at ${PROJECTED_TURNS_PHRASE} turns. For candidates without fixed_turn_cost_estimate, use est_input_cost_usd and output_cost_per_mtok as fallback cost evidence. Do not rank by output_cost_per_mtok ahead of fixed_turn_cost_estimate.projections.
+Return JSON matching the provided schema.
+selected_model and reasoning_effort must exactly match one candidate pair.
+The runtime chooses provider fallbacks separately; return only the primary decision.`;
+
+// System prompt for the anonymous candidate-action protocol (see
+// anonymous_actions.ts). It carries every invariant instruction, including how
+// to read the per-action blocks, so the user message stays pure data.
+export const ANONYMOUS_ACTION_SYSTEM_PROMPT = [
+  "You are Dari's model router for a coding agent.",
+  "Choose exactly one anonymous candidate action for the agent's next turns, and how many turns to commit to it.",
+  "Your choice is a lease: the chosen action serves that many consecutive turns before you are consulted again. A longer lease amortizes the cold start paid on its first turn across warm cache hits on the turns that follow; the lease ends early only if the task finishes or the provider fails.",
+  "Each action's block lists its benchmark standing and its projected cost at each lease length you may choose.",
+  "Rank is the action's position among every model scored on that benchmark, 1 being best. Z is how many standard deviations that model sits above or below the mean of those models.",
+  "Cost is the projected spend for the whole agent loop over exactly the turns of each lease option, from current cache warmth. Compare actions at the lease you intend to pick.",
+  "A missing benchmark score means that action was not evaluated on that benchmark; do not treat it as zero, failure, or negative evidence.",
+  "Prefer a cheaper action only when it is sufficiently likely to complete the task successfully.",
+  // Scaffolding for the thinking budget: the decision decomposes into judging
+  // how hard the task is and then finding the cheapest action-and-lease that
+  // clears that bar. Stating the decomposition costs a few prompt tokens and
+  // saves the policy from having to discover it from reward alone.
+  "Think in exactly three short steps, then stop:",
+  "1. Phase: one sentence — what stage the task is at based on the latest turn (exploring, editing, testing, wrapping up), roughly how many turns remain, and how hard the next step looks.",
+  "2. Evidence: one sentence — the one or two benchmarks most like this work, and which actions stand out on them.",
+  "3. Pick: name the cheapest action whose standing clears the difficulty, and the longest lease the remaining work justifies; go pricier or shorter only when the task demands it. Then end thinking immediately and answer.",
+  "Do not walk through every action, restate the scorecards, or retell the conversation.",
+  "Return only JSON matching the provided schema.",
+].join("\n");