@duetso/agent 0.2.2 → 0.2.3

package/dist/src/model-routing/advisor.d.ts

@@ -0,0 +1,27 @@
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import { type LanguageModelUsage } from "ai";
+/** Inputs for one advisor generation after catalog shorthand resolution. */
+export interface CallAdvisorInput {
+    /** Curated executor transcript sent as advisor-call content. */
+    transcriptText: string;
+    /** Gateway-native `provider/model` id, already resolved by the composition site. */
+    modelName: string;
+    /** Portable reasoning effort forwarded through AI SDK 7's top-level option. */
+    thinkingLevel: ThinkingLevel;
+    /** Cancels the advisor request with the parent tool execution. */
+    signal?: AbortSignal;
+}
+/** Compact text returned to the executor after an advisor consultation. */
+export interface AdvisorResult {
+    /** Compact strategic guidance returned to the executor tool. */
+    advice: string;
+    /** Provider-reported token usage for pricing and live turn attribution. */
+    usage: LanguageModelUsage;
+}
+/**
+ * Run a plain text advisor call through the shared gateway constructor. No
+ * provider options are supplied, so this path opts into neither prompt
+ * caching nor any provider-specific request behavior.
+ */
+export declare function callAdvisor(input: CallAdvisorInput): Promise<AdvisorResult>;
+//# sourceMappingURL=advisor.d.ts.map

package/dist/src/model-routing/advisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisor.d.ts","sourceRoot":"","sources":["../../../src/model-routing/advisor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,IAAI,CAAC;AAI3D,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,aAAa,CAAC;IAC7B,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAWjF"}

package/dist/src/model-routing/advisor.js

@@ -0,0 +1,20 @@
+import { generateText } from "ai";
+import { createDuetModelGateway } from "../model-resolution/model-gateway.js";
+import { ADVISOR_SYSTEM_PROMPT } from "./prompts.js";
+/**
+ * Run a plain text advisor call through the shared gateway constructor. No
+ * provider options are supplied, so this path opts into neither prompt
+ * caching nor any provider-specific request behavior.
+ */
+export async function callAdvisor(input) {
+    const gateway = createDuetModelGateway();
+    const result = await generateText({
+        model: gateway(input.modelName),
+        system: ADVISOR_SYSTEM_PROMPT,
+        prompt: input.transcriptText,
+        reasoning: input.thinkingLevel,
+        abortSignal: input.signal,
+    });
+    return { advice: result.text, usage: result.usage };
+}
+//# sourceMappingURL=advisor.js.map

package/dist/src/model-routing/advisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisor.js","sourceRoot":"","sources":["../../../src/model-routing/advisor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAA2B,MAAM,IAAI,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAsBrD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAuB;IACvD,MAAM,OAAO,GAAG,sBAAsB,EAAE,CAAC;IAEzC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QAChC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC;QAC/B,MAAM,EAAE,qBAAqB;QAC7B,MAAM,EAAE,KAAK,CAAC,cAAc;QAC5B,SAAS,EAAE,KAAK,CAAC,aAAa;QAC9B,WAAW,EAAE,KAAK,CAAC,MAAM;KAC1B,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AACtD,CAAC"}

package/dist/src/model-routing/classifier.d.ts

@@ -0,0 +1,57 @@
+import type { ThinkingLevel, Usage } from "@earendil-works/pi-ai";
+import type { TierDefinition } from "./table.js";
+/**
+ * The runtime milestone that requested a classification. Owned here — where
+ * the concept originates — and consumed by the router, the protocol event,
+ * and the CLI probe, so the union can never drift across layers.
+ */
+export type RouteTrigger = "turn_start" | "cadence" | "advisor" | "step_trigger" | "compaction";
+/** Lean routing facts supplied at a turn boundary or intra-turn milestone. */
+export interface ClassifierInput {
+    /** Virtual tier whose complete route set is being classified in one call. */
+    tierName: string;
+    /** Tier rules shown to the classifier; concrete targets remain hidden. */
+    tier: TierDefinition;
+    /** Administrator-authored routing and cache-preference policy. */
+    guidance: string;
+    /** Current concrete target and selecting route, when continuity is possible. */
+    currentTarget?: string;
+    /** Bounded summary of the preceding turn, used only to judge task continuity. */
+    prevTurnHint?: string;
+    /** Bounded description of what changed in the most recent agent step. */
+    lastStepDelta?: string;
+    /** Whether the pending input includes images; the router handles capability after classification. */
+    hasImages: boolean;
+    /** Event that requested classification, for interpreting sparse cadence/advisor context. */
+    trigger: RouteTrigger;
+}
+/** Pure system/user prompt pair consumed by the structured-output classifier call. */
+export interface ClassifierMessages {
+    /** Stable classifier policy. */
+    systemPrompt: string;
+    /** Tier rules plus the lean, request-specific routing facts. */
+    prompt: string;
+}
+/** Options for the live structured-output route decision. */
+export interface ClassifyRouteOptions {
+    /** Classifier model reference resolved by the caller's composition layer. */
+    model: string;
+    /** Reasoning effort configured for the classifier target in the routing table. */
+    thinkingLevel?: ThinkingLevel;
+    /** Cancels the provider request when its owning turn is interrupted. */
+    signal?: AbortSignal;
+    /** Receives classifier token and cost usage for attribution. */
+    onUsage?: (usage: Usage) => void;
+}
+/** A classifier choice that still names policy, not a concrete execution target. */
+export interface ClassifierDecision {
+    /** Existing route name selected from the supplied tier. */
+    route: string;
+    /** One-sentence explanation returned by the classifier. */
+    rationale: string;
+}
+/** Build the complete lean classifier request without reading runtime state. */
+export declare function buildClassifierMessages(input: ClassifierInput): ClassifierMessages;
+/** Classify one tier in one model call and reject any route outside that tier. */
+export declare function classifyRoute(input: ClassifierInput, options: ClassifyRouteOptions): Promise<ClassifierDecision>;
+//# sourceMappingURL=classifier.d.ts.map

package/dist/src/model-routing/classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../../src/model-routing/classifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AASlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAwBjD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,YAAY,CAAC;AAEhG,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,IAAI,EAAE,cAAc,CAAC;IACrB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qGAAqG;IACrG,SAAS,EAAE,OAAO,CAAC;IACnB,4FAA4F;IAC5F,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,kBAAkB,CAkBlF;AAED,kFAAkF;AAClF,wBAAsB,aAAa,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAiB7B"}

package/dist/src/model-routing/classifier.js

@@ -0,0 +1,63 @@
+import dedent from "dedent";
+import { Type } from "typebox";
+import * as structuredOutput from "../core/structured-output.js";
+import { CLASSIFIER_SYSTEM_PROMPT, renderCacheContinuity, renderClassifierRules, } from "./prompts.js";
+const CONTEXT_HINT_LIMIT = 1_000;
+function classifierResultTool(routeNames) {
+    return {
+        name: "select_route",
+        description: "Select exactly one existing route for the agent's next work.",
+        parameters: Type.Object({
+            route: Type.Union(routeNames.map((name) => Type.Literal(name)), { description: "Exactly one route name from AVAILABLE ROUTES." }),
+            rationale: Type.String({
+                minLength: 1,
+                description: "One sentence explaining why this route matches the current work.",
+            }),
+        }, { additionalProperties: false }),
+    };
+}
+function boundedHint(value) {
+    if (!value?.trim())
+        return "Not provided.";
+    const normalized = value.trim();
+    return normalized.length <= CONTEXT_HINT_LIMIT
+        ? normalized
+        : `${normalized.slice(0, CONTEXT_HINT_LIMIT)}…`;
+}
+/** Build the complete lean classifier request without reading runtime state. */
+export function buildClassifierMessages(input) {
+    const continuity = renderCacheContinuity(input.currentTarget);
+    return {
+        systemPrompt: CLASSIFIER_SYSTEM_PROMPT,
+        prompt: dedent `
+      ${renderClassifierRules(input.tierName, input.tier, input.guidance)}
+
+      CLASSIFICATION CONTEXT:
+      Trigger: ${input.trigger}
+      Images present: ${input.hasImages ? "yes" : "no"}
+      ${continuity}
+      Previous-turn hint: ${boundedHint(input.prevTurnHint)}
+      Current request / last-step delta: ${boundedHint(input.lastStepDelta)}
+
+      Pick exactly one name from AVAILABLE ROUTES and give a one-sentence rationale.
+    `,
+    };
+}
+/** Classify one tier in one model call and reject any route outside that tier. */
+export async function classifyRoute(input, options) {
+    const messages = buildClassifierMessages(input);
+    const result = await structuredOutput.generateStructuredOutput({
+        model: options.model,
+        tool: classifierResultTool(Object.keys(input.tier.routes)),
+        systemPrompt: messages.systemPrompt,
+        prompt: messages.prompt,
+        ...(options.thinkingLevel ? { callOptions: { reasoningEffort: options.thinkingLevel } } : {}),
+        signal: options.signal,
+        onUsage: options.onUsage,
+    });
+    if (!Object.hasOwn(input.tier.routes, result.route)) {
+        throw new Error(`Classifier selected unknown route "${result.route}" for tier "${input.tierName}".`);
+    }
+    return result;
+}
+//# sourceMappingURL=classifier.js.map

package/dist/src/model-routing/classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../../src/model-routing/classifier.ts"],"names":[],"mappings":"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"}

package/dist/src/model-routing/loader.d.ts

@@ -0,0 +1,48 @@
+import { type RoutingCatalogAdapter, type RoutingTable } from "./table.js";
+/** Options for loading the optional project-local routing table. */
+export interface LoadRoutingTableOptions {
+    /**
+     * Directory the discovery walk starts from. Candidates are
+     * `<ancestor>/.duet/models.json` for cwd and every parent up to the
+     * filesystem root (home excluded from the walk), then `~/.duet/models.json`
+     * as the global fallback — the same project-then-global scoping skills
+     * discovery uses. The nearest existing file wins outright as a complete
+     * replacement; an invalid winner fails loudly rather than falling through.
+     */
+    cwd: string;
+    /** Concrete catalog used for collision, dangling-target, and vision validation. */
+    catalogAdapter: RoutingCatalogAdapter;
+    /** Home directory override for tests; defaults to the real home. */
+    homeDir?: string;
+}
+/** Provenance attached to the active routing table. */
+export type LoadedRoutingTable = {
+    table: RoutingTable;
+    source: "built-in";
+} | {
+    table: RoutingTable;
+    source: "file";
+    path: string;
+};
+/** Options for writing the built-in table to a project for customization. */
+export interface ExportRoutingTableOptions {
+    /** Project directory where `.duet/models.json` should be written. */
+    cwd: string;
+    /** Allows replacement of an existing file when explicitly set. */
+    force: boolean;
+}
+/** Result of exporting the built-in routing table. */
+export interface ExportedRoutingTable {
+    /** Absolute or cwd-relative path, matching the supplied cwd, of the written file. */
+    path: string;
+    /** The complete built-in replacement serialized to the file. */
+    table: RoutingTable;
+}
+/**
+ * Load the nearest `.duet/models.json` as a complete replacement, or use the
+ * built-in table when no override exists anywhere on the discovery path.
+ */
+export declare function loadRoutingTable(options: LoadRoutingTableOptions): Promise<LoadedRoutingTable>;
+/** Export the complete built-in table as deterministic, two-space-indented JSON. */
+export declare function exportRoutingTable(options: ExportRoutingTableOptions): Promise<ExportedRoutingTable>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/src/model-routing/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/model-routing/loader.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAIpB,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,cAAc,EAAE,qBAAqB,CAAC;IACtC,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC3C;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,EAAE,YAAY,CAAC;CACrB;AA0BD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CA8B7B;AAED,oFAAoF;AACpF,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAgB/B"}

package/dist/src/model-routing/loader.js

@@ -0,0 +1,79 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { walkAncestors } from "../lib/walk-ancestors.js";
+import { Value } from "typebox/value";
+import { BUILT_IN_ROUTING_TABLE, RoutingTableSchema, validateRoutingTable, } from "./table.js";
+const ROUTING_TABLE_RELATIVE_PATH = join(".duet", "models.json");
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function assertSchema(value, path) {
+    if (Value.Check(RoutingTableSchema, value))
+        return;
+    const details = [...Value.Errors(RoutingTableSchema, value)]
+        .map((error) => `${error.instancePath || "/"}: ${error.message}`)
+        .join("; ");
+    throw new Error(`Invalid routing table at ${path}: ${details}`);
+}
+function assertDomain(table, path, catalogAdapter) {
+    const issues = validateRoutingTable(table, catalogAdapter);
+    if (issues.length === 0)
+        return;
+    throw new Error(`Invalid routing table at ${path}:\n${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n")}`);
+}
+/**
+ * Load the nearest `.duet/models.json` as a complete replacement, or use the
+ * built-in table when no override exists anywhere on the discovery path.
+ */
+export async function loadRoutingTable(options) {
+    const home = options.homeDir ?? homedir();
+    const candidates = [
+        ...walkAncestors(options.cwd, home).map((dir) => join(dir, ROUTING_TABLE_RELATIVE_PATH)),
+        join(home, ROUTING_TABLE_RELATIVE_PATH),
+    ];
+    for (const path of candidates) {
+        let contents;
+        try {
+            contents = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                continue;
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(contents);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to parse routing table at ${path}: ${detail}`, { cause: error });
+        }
+        assertSchema(parsed, path);
+        assertDomain(parsed, path, options.catalogAdapter);
+        return { table: parsed, source: "file", path };
+    }
+    assertDomain(BUILT_IN_ROUTING_TABLE, "built-in routing table", options.catalogAdapter);
+    return { table: BUILT_IN_ROUTING_TABLE, source: "built-in" };
+}
+/** Export the complete built-in table as deterministic, two-space-indented JSON. */
+export async function exportRoutingTable(options) {
+    const directory = join(options.cwd, ".duet");
+    const path = join(options.cwd, ROUTING_TABLE_RELATIVE_PATH);
+    await mkdir(directory, { recursive: true });
+    const contents = `${JSON.stringify(BUILT_IN_ROUTING_TABLE, null, 2)}\n`;
+    try {
+        await writeFile(path, contents, { encoding: "utf8", flag: options.force ? "w" : "wx" });
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+            throw new Error(`Routing table already exists at ${path}; pass force to overwrite it.`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    return { path, table: BUILT_IN_ROUTING_TABLE };
+}
+//# sourceMappingURL=loader.js.map

package/dist/src/model-routing/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../src/model-routing/loader.ts"],"names":[],"mappings":"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"}

package/dist/src/model-routing/prompts.d.ts

@@ -0,0 +1,22 @@
+import type { TierDefinition } from "./table.js";
+/** Identifies the measured classifier prompt in scorecard output. */
+export declare const CLASSIFIER_PROMPT_VERSION = "model-router-classifier-v3";
+/** Stable classifier behavior shared by the probe CLI and runtime router. */
+export declare const CLASSIFIER_SYSTEM_PROMPT: string;
+/** Executor-facing guidance for the no-parameter advisor consultation tool. */
+export declare const ASK_ADVISOR_TOOL_DESCRIPTION: string;
+/**
+ * Executor-facing system-prompt layer injected alongside the ask_advisor tool.
+ * Anthropic's advisor documentation is explicit that the tool description
+ * alone under-triggers on hard tasks and that consistent consult timing comes
+ * from executor system-prompt steering; live acceptance runs confirmed it
+ * (four consecutive positive-case misses on description-only guidance).
+ */
+export declare const ADVISOR_EXECUTOR_GUIDANCE_LAYER: string;
+/** Instructions owned by the advisor call, separate from the executor's quoted prompt. */
+export declare const ADVISOR_SYSTEM_PROMPT: string;
+/** Continuity framing for the classifier: cache preference when a target is active. */
+export declare function renderCacheContinuity(currentTarget: string | undefined): string;
+/** Render every route in one tier for a single all-entries classifier decision. */
+export declare function renderClassifierRules(tierName: string, tier: TierDefinition, guidance: string): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/src/model-routing/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/model-routing/prompts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,+BAA+B,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,QAapC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,QASxC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,QAe3C,CAAC;AAEF,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,QAOjC,CAAC;AAEF,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQ/E;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,MAAM,GACf,MAAM,CAaR"}

package/dist/src/model-routing/prompts.js

@@ -0,0 +1,87 @@
+import dedent from "dedent";
+/** Identifies the measured classifier prompt in scorecard output. */
+export const CLASSIFIER_PROMPT_VERSION = "model-router-classifier-v3";
+/** Stable classifier behavior shared by the probe CLI and runtime router. */
+export const CLASSIFIER_SYSTEM_PROMPT = dedent `
+  You are a model-route classifier. Choose the single route that best matches the work the agent
+  should do next, using only the supplied route names and descriptions.
+
+  Return exactly one existing route name through the required tool, plus a one-sentence rationale.
+  Never invent, rename, combine, or return a concrete model name. Treat administrator guidance as
+  additional routing policy.
+
+  Route for the current kind of work, not merely the topic or the input capabilities it needs.
+  Vision fallback or graceful degradation is handled by the router after classification. A route
+  change discards the current model's prompt cache, so prefer the current route/model while the
+  kind of work remains materially the same. Switch when the work clearly changes kind; cache
+  continuity must not keep a genuinely wrong route.
+`;
+/** Executor-facing guidance for the no-parameter advisor consultation tool. */
+export const ASK_ADVISOR_TOOL_DESCRIPTION = dedent `
+  Ask a senior advisor to review your full progress so far and recommend what to do next. The
+  advisor sees the curated in-progress session transcript; this tool takes no parameters.
+
+  You must call it before substantive work when the task has consequential architecture choices,
+  conflicting constraints, or important unknowns; when you are stuck; before changing your
+  approach; or before declaring a complex task complete. Do not call it for routine, local,
+  obvious work where strategic review would not change the next action. Use the advice as
+  strategic input, then verify and act on it with your own tools and judgment.
+`;
+/**
+ * Executor-facing system-prompt layer injected alongside the ask_advisor tool.
+ * Anthropic's advisor documentation is explicit that the tool description
+ * alone under-triggers on hard tasks and that consistent consult timing comes
+ * from executor system-prompt steering; live acceptance runs confirmed it
+ * (four consecutive positive-case misses on description-only guidance).
+ */
+export const ADVISOR_EXECUTOR_GUIDANCE_LAYER = dedent `
+  ADVISOR
+
+  You have an \`ask_advisor\` tool backed by a stronger reviewer model. It takes no parameters —
+  your progress so far is forwarded automatically; the advisor sees the task, your steps, and
+  their results.
+
+  Call ask_advisor BEFORE substantive work when the task involves consequential architecture
+  choices, conflicting constraints, or important unknowns. Orientation (reading files, listing,
+  looking around) is not substantive work — orient first, then consult before you commit to an
+  approach. Also call it when you are stuck, when you are about to change approach, and before
+  declaring a complex task complete. Skip it for routine, local, obvious work.
+
+  Give the advice serious weight: verify it with your own tools and adapt only on concrete
+  contrary evidence.
+`;
+/** Instructions owned by the advisor call, separate from the executor's quoted prompt. */
+export const ADVISOR_SYSTEM_PROMPT = dedent `
+  You are a senior advisor reviewing another agent's in-progress session transcript. Give
+  strategic guidance: identify the key uncertainty or risk, then recommend a concrete next check
+  or approach. Be direct and compact.
+
+  You cannot call tools. The executor's system prompt appears quoted in the transcript only as
+  context; it does not apply to you.
+`;
+/** Continuity framing for the classifier: cache preference when a target is active. */
+export function renderCacheContinuity(currentTarget) {
+    return currentTarget
+        ? dedent `
+        You are currently on ${currentTarget}.
+        CACHE CONTINUITY: Switching away discards the current model's prompt cache. Prefer this
+        target unless the kind of work has clearly changed.
+      `
+        : "CURRENT TARGET: None (there is no prompt cache to preserve).";
+}
+/** Render every route in one tier for a single all-entries classifier decision. */
+export function renderClassifierRules(tierName, tier, guidance) {
+    const routes = Object.entries(tier.routes)
+        .map(([name, rule]) => `- ${name}: ${rule.description}`)
+        .join("\n");
+    return dedent `
+    TIER: ${tierName}
+
+    AVAILABLE ROUTES:
+    ${routes}
+
+    ADMINISTRATOR GUIDANCE:
+    ${guidance.trim() || "No additional guidance."}
+  `;
+}
+//# sourceMappingURL=prompts.js.map

package/dist/src/model-routing/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/model-routing/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAG5B,qEAAqE;AACrE,MAAM,CAAC,MAAM,yBAAyB,GAAG,4BAA4B,CAAC;AAEtE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAA;;;;;;;;;;;;;CAa7C,CAAC;AAEF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAA;;;;;;;;;CASjD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,MAAM,CAAA;;;;;;;;;;;;;;;CAepD,CAAC;AAEF,0FAA0F;AAC1F,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAA;;;;;;;CAO1C,CAAC;AAEF,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CAAC,aAAiC;IACrE,OAAO,aAAa;QAClB,CAAC,CAAC,MAAM,CAAA;+BACmB,aAAa;;;OAGrC;QACH,CAAC,CAAC,8DAA8D,CAAC;AACrE,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,IAAoB,EACpB,QAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;SACvC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;SACvD,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,MAAM,CAAA;YACH,QAAQ;;;MAGd,MAAM;;;MAGN,QAAQ,CAAC,IAAI,EAAE,IAAI,yBAAyB;GAC/C,CAAC;AACJ,CAAC"}

package/dist/src/model-routing/resolve.d.ts

@@ -0,0 +1,40 @@
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { RoutingTable } from "./table.js";
+/** Request facts that can change an otherwise deterministic route selection. */
+export interface RouteContext {
+    /** Whether the pending model input contains one or more images. */
+    hasImages: boolean;
+}
+/** Concrete-model capability needed by the pure resolution kernel. */
+export interface RouteResolutionCatalog {
+    /** True when the named concrete model accepts image input. */
+    modelAcceptsImages(name: string): boolean;
+}
+/** Final concrete target plus the virtual path that selected it. */
+export interface ResolvedTarget {
+    /** Virtual tier that owns the final concrete route. */
+    tier: string;
+    /** Actual route used in the final tier, including general fallthrough. */
+    route: string;
+    /** Concrete catalog name selected for execution. */
+    modelName: string;
+    /** Reasoning effort selected by the final route. */
+    thinkingLevel: ThinkingLevel;
+    /** True when the selected route's image fallback model was applied. */
+    visionFallback: boolean;
+    /** Ordered virtual tier names visited during recursive resolution. */
+    chain: string[];
+}
+type UncheckedTarget = Omit<ResolvedTarget, "visionFallback">;
+/** Non-throwing virtual-chain walk shared by validation and live route resolution. */
+export declare function walkVirtualRoute(table: RoutingTable, startTier: string, requestedRoute: string): {
+    cycle?: string[];
+    target?: UncheckedTarget;
+    chain: string[];
+};
+/** Resolve a virtual tier and classifier route to one concrete model and effort. */
+export declare function resolveRoute(table: RoutingTable, tier: string, route: string, ctx: RouteContext, catalog: RouteResolutionCatalog): ResolvedTarget;
+/** Resolve the general boot route for a selected virtual tier before classification. */
+export declare function resolveTierDefault(table: RoutingTable, tier: string, context: RouteContext, catalog: RouteResolutionCatalog): ResolvedTarget;
+export {};
+//# sourceMappingURL=resolve.d.ts.map

package/dist/src/model-routing/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/model-routing/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,sEAAsE;AACtE,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3C;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,aAAa,EAAE,aAAa,CAAC;IAC7B,uEAAuE;IACvE,cAAc,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,KAAK,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;AAE9D,sFAAsF;AACtF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CA8BjE;AAwBD,oFAAoF;AACpF,wBAAgB,YAAY,CAC1B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAwBhB;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAEhB"}

package/dist/src/model-routing/resolve.js

@@ -0,0 +1,76 @@
+/** Non-throwing virtual-chain walk shared by validation and live route resolution. */
+export function walkVirtualRoute(table, startTier, requestedRoute) {
+    const chain = [];
+    let tier = startTier;
+    while (true) {
+        const repeatedAt = chain.indexOf(tier);
+        if (repeatedAt !== -1) {
+            return { cycle: [...chain.slice(repeatedAt), tier], chain };
+        }
+        const definition = table.tiers[tier];
+        if (!definition)
+            return { chain };
+        chain.push(tier);
+        const route = Object.hasOwn(definition.routes, requestedRoute) ? requestedRoute : "general";
+        const rule = definition.routes[route];
+        if (!rule)
+            return { chain };
+        if (!Object.hasOwn(table.tiers, rule.target.modelName)) {
+            return {
+                chain,
+                target: {
+                    tier,
+                    route,
+                    modelName: rule.target.modelName,
+                    thinkingLevel: rule.target.thinkingLevel,
+                    chain,
+                },
+            };
+        }
+        tier = rule.target.modelName;
+    }
+}
+function resolveWithoutVisionGuard(table, startTier, requestedRoute) {
+    if (!Object.hasOwn(table.tiers, startTier)) {
+        throw new Error(`Unknown virtual model tier "${startTier}".`);
+    }
+    const result = walkVirtualRoute(table, startTier, requestedRoute);
+    if (result.cycle)
+        throw new Error(`Virtual model cycle: ${result.cycle.join(" -> ")}.`);
+    if (result.target)
+        return result.target;
+    const tier = result.chain.at(-1) ?? startTier;
+    throw new Error(`Tier "${tier}" has neither requested route "${requestedRoute}" nor a general fallback.`);
+}
+function joinChains(initial, fallback) {
+    if (initial.at(-1) === fallback[0])
+        return [...initial, ...fallback.slice(1)];
+    return [...initial, ...fallback];
+}
+/** Resolve a virtual tier and classifier route to one concrete model and effort. */
+export function resolveRoute(table, tier, route, ctx, catalog) {
+    const selected = resolveWithoutVisionGuard(table, tier, route);
+    if (!ctx.hasImages || catalog.modelAcceptsImages(selected.modelName)) {
+        return { ...selected, visionFallback: false };
+    }
+    const fallbackName = table.tiers[selected.tier].routes[selected.route]?.visionFallbackModelName;
+    if (!fallbackName)
+        return { ...selected, visionFallback: false };
+    const fallback = Object.hasOwn(table.tiers, fallbackName)
+        ? resolveWithoutVisionGuard(table, fallbackName, selected.route)
+        : { ...selected, modelName: fallbackName, chain: [] };
+    if (!catalog.modelAcceptsImages(fallback.modelName)) {
+        throw new Error(`Vision fallback "${fallbackName}" for route "${selected.route}" resolves to text-only model "${fallback.modelName}".`);
+    }
+    return {
+        ...fallback,
+        thinkingLevel: selected.thinkingLevel,
+        visionFallback: true,
+        chain: joinChains(selected.chain, fallback.chain),
+    };
+}
+/** Resolve the general boot route for a selected virtual tier before classification. */
+export function resolveTierDefault(table, tier, context, catalog) {
+    return resolveRoute(table, tier, "general", context, catalog);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/src/model-routing/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../../src/model-routing/resolve.ts"],"names":[],"mappings":"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"}