@suluk/agents 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/agents",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Suluk Agent composition (C027): lint + project an `x-suluk-agents` map (skills + deterministic routes + by-name sub-agents) to a Claude plugin AND an OpenRouter/OpenAI-compatible manifest — one contract, two artifacts, zero network at generate time. Determinism is DECLARED not enforced; the matcher never reads an agent field. CANDIDATE tooling — NOT official OAS.",
   "publishConfig": {
   "access": "public"
@@ -19,8 +19,8 @@
 ".": "./src/index.ts"
 },
 "dependencies": {
-"@suluk/core": "^0.1.7",
-"@suluk/models": "^0.1.0"
+"@suluk/core": "^0.1.9",
+"@suluk/models": "^0.1.3"
 },
 "devDependencies": {
 "@types/bun": "latest",

package/src/index.ts

@@ -40,5 +40,5 @@ export {
 } from "./context";
 // model-selection seam (C027 × @suluk/models): a skill declares NEEDS (profile + the analyzer's minWindowRequired +
 // the C028 allowlist MEET) and the catalog picks the best CURRENT model — never a hard-coded id.
-export { resolveSkillModels, skillModels, type SkillModelResolution } from "./model-select";
+export { resolveSkillModels, skillModels, deriveCQT, type SkillModelResolution, type ResolvedTarget } from "./model-select";
 export { selectModel, deriveRequirements, SEED_CATALOG, PROFILES, type ModelCatalog, type SelectResult, type Preferences, type HardFilters } from "@suluk/models";

package/src/manifest.ts

@@ -52,8 +52,9 @@ export interface AgentManifestNode {
   /** operator-effective surface after x-suluk-policy (C028) — so the C021 signature covers the operator's caps. */
   governed?: AgentManifestGoverned;
   /** catalog-pinned model selection per skill (present only when agentManifest is given a catalog) — reproducible: the
-   * snapshotHash is signed, so a re-pick week-over-week with no author edit is auditable (C027 contentHash discipline). */
-  modelSelection?: { skill: string; ids: string[]; from: "declared" | "selected"; snapshotHash: string | null }[];
+   * snapshotHash is signed (the SURVIVOR SET), so a re-pick week-over-week with no author edit is auditable. `resolve`
+   * is the C030 mode; `pickPinned` false ⇒ set-pinned but the served id is NOT reproducible (router/latest). */
+  modelSelection?: { skill: string; ids: string[]; from: "declared" | "selected"; snapshotHash: string | null; resolve: "pinned" | "router" | "latest"; pickPinned: boolean }[];
 }
 export interface AgentManifest {
   manifestVersion: 1;
@@ -110,7 +111,7 @@ export function agentManifest(doc: OpenAPIv4Document, agentName: string, opts: {
     if (opts.catalog) {
       modelSelection = Object.keys(a.skills ?? {}).sort().map((sk) => {
         const r = skillModels(doc, key, sk, opts.catalog!, minWinByAgent[key]);
-        return { skill: sk, ids: r.ids, from: r.from, snapshotHash: r.snapshotHash };
+        return { skill: sk, ids: r.ids, from: r.from, snapshotHash: r.snapshotHash, resolve: r.target.kind, pickPinned: r.pickPinned };
       });
     }
     return { name: key, description: a.description, effectiveScope: effective[key] ?? null, skills, routes, subAgents, ...(governed ? { governed } : {}), ...(modelSelection ? { modelSelection } : {}) };

package/src/model-select.ts

@@ -6,18 +6,54 @@
  * from the skill's `modelProfile`/`modelPrefer`. An explicit `model[]` (with no profile/prefer) is the author's
  * opt-out — returned verbatim.
  */
-import type { OpenAPIv4Document } from "@suluk/core";
-import { selectModel, deriveRequirements, type ModelCatalog, type SelectResult, type Preferences } from "@suluk/models";
+import type { OpenAPIv4Document, SulukSkillRef } from "@suluk/core";
+import { selectModel, deriveRequirements, PROFILES, type ModelCatalog, type SelectResult, type Preferences } from "@suluk/models";
 import { agentMap } from "./resolve";
 import { policiesFor } from "./policy";
 
+/**
+ * How a skill RESOLVES to a runtime model (C030, council wf_75f87ab6-b1b — unanimous hybrid). We keep the survivor
+ * SET (governance + caps + min-context, the moat) and either PIN a concrete reproducible id, or DELEGATE the
+ * per-request pick to OpenRouter's auto-router fenced by our ENUMERATED survivor allowlist (never a wildcard).
+ */
+export type ResolvedTarget =
+  | { kind: "pinned"; model: string }
+  | { kind: "router"; model: "openrouter/auto"; allowedModels: string[]; costQualityTradeoff: number }
+  | { kind: "latest"; model: string; note: string };
+
 export interface SkillModelResolution {
   ids: string[];
   from: "declared" | "selected";
   /** the selector result (filter trace + per-axis why + coverage gaps) when `from === "selected"`. */
   selection?: SelectResult;
-  /** the catalog snapshot the pick was made against — reproducibility (null when declared). */
+  /** the catalog snapshot the SURVIVOR SET was pinned against (null when declared). */
   snapshotHash: string | null;
+  /** the resolved runtime target (pin / router / latest). */
+  target: ResolvedTarget;
+  /** true ⇒ the SERVED model id is reproducible (pinned). false ⇒ set-pinned but pick-NOT-pinned (router/latest). */
+  pickPinned: boolean;
+}
+
+/** An operator policy governs this agent ⇒ FORCE PIN (reproducible + auditable; the runtime router cannot bind an
+ * endpoint region/retention, and its pick is non-reproducible across dates). C030 governance gate — mechanical. */
+function isGoverned(doc: OpenAPIv4Document, agentName: string): boolean {
+  return policiesFor(doc, agentName).length > 0;
+}
+
+/** cost_quality_tradeoff 0..10 (0=quality, 10=cost) — mechanical from the profile's cost-vs-intelligence weights
+ * (set explicitly; do NOT inherit OpenRouter's cost-leaning default of 7). */
+export function deriveCQT(skill: SulukSkillRef | undefined): number {
+  const base = skill?.modelProfile ? PROFILES[skill.modelProfile].prefer : { intelligence: 2, cost: 2, speed: 1, context: 1 };
+  const w = { ...base, ...(skill?.modelPrefer ?? {}) };
+  const denom = (w.cost ?? 0) + (w.intelligence ?? 0);
+  return denom === 0 ? 5 : Math.max(0, Math.min(10, Math.round((10 * (w.cost ?? 0)) / denom)));
+}
+
+/** Best-effort `~author/family-latest` alias for the latest-resolution opt-in (defers the concrete version). */
+function toLatestAlias(id: string): string {
+  const [author, rest] = id.split("/");
+  const family = (rest ?? "").replace(/[-.:@](\d.*|latest|preview|chat|instruct).*$/i, "");
+  return author && family ? `~${author}/${family}-latest` : id;
 }
 
 /** The C028 modelAllowlist MEET across every policy governing this agent (intersection of the present allowlists). */
@@ -44,11 +80,27 @@ export function resolveSkillModels(doc: OpenAPIv4Document, agentName: string, sk
   return selectModel(reqs, prefs, catalog);
 }
 
-/** The public seam: the models for a skill — its DECLARED list (opt-out) or the catalog-SELECTED ranked ids. */
+/** The public seam: the models for a skill — its DECLARED list (opt-out) or the catalog-SELECTED ranked ids, resolved
+ * to a runtime TARGET (pin / router / latest) under the C030 governance gate. */
 export function skillModels(doc: OpenAPIv4Document, agentName: string, skillName: string, catalog: ModelCatalog, minWindowRequired?: number): SkillModelResolution {
   const skill = agentMap(doc)[agentName]?.skills?.[skillName];
   // explicit model[] with no profile/prefer ⇒ the author opted out of catalog selection
-  if (skill?.model?.length && !skill.modelProfile && !skill.modelPrefer) return { ids: skill.model, from: "declared", snapshotHash: null };
-  const selection = resolveSkillModels(doc, agentName, skillName, catalog, minWindowRequired);
-  return { ids: selection.ranked.map((r) => r.id), from: "selected", selection, snapshotHash: catalog.snapshotHash };
+  const declared = !!(skill?.model?.length && !skill?.modelProfile && !skill?.modelPrefer);
+  const selection = declared ? undefined : resolveSkillModels(doc, agentName, skillName, catalog, minWindowRequired);
+  const ids = declared ? skill!.model! : selection!.ranked.map((r) => r.id);
+  const from: "declared" | "selected" = declared ? "declared" : "selected";
+  const snapshotHash = declared ? null : catalog.snapshotHash;
+
+  const mode = skill?.modelResolve ?? "pinned";
+  // GOVERNANCE GATE (mechanical): a governed skill MUST pin — router/latest are non-reproducible + cannot bind an endpoint.
+  if (isGoverned(doc, agentName) && mode !== "pinned")
+    throw new Error(`@suluk/agents: skill "${skillName}" of agent "${agentName}" is GOVERNED by an operator policy — modelResolve:"${mode}" is inadmissible (a governed skill must be "pinned" for reproducible, auditable, endpoint-bindable selection). Remove the policy or use "pinned".`);
+
+  let target: ResolvedTarget;
+  let pickPinned: boolean;
+  if (mode === "router") { target = { kind: "router", model: "openrouter/auto", allowedModels: ids, costQualityTradeoff: deriveCQT(skill) }; pickPinned = false; }
+  else if (mode === "latest") { target = { kind: "latest", model: toLatestAlias(ids[0] ?? ""), note: "~-latest defers the concrete version to request time — NOT reproducible (recorded in the why-explainer)" }; pickPinned = false; }
+  else { target = { kind: "pinned", model: ids[0] ?? "" }; pickPinned = true; }
+
+  return { ids, from, selection, snapshotHash, target, pickPinned };
 }

package/test/model-select.test.ts

@@ -1,6 +1,6 @@
 import { test, expect, describe } from "bun:test";
 import type { OpenAPIv4Document } from "@suluk/core";
-import { skillModels, resolveSkillModels, SEED_CATALOG } from "../src/index";
+import { skillModels, resolveSkillModels, deriveCQT, SEED_CATALOG } from "../src/index";
 
 /** An agent with routes (⇒ needs tool-calling) and two skills: a needs-based one + an explicit opt-out. */
 function doc(): OpenAPIv4Document {
@@ -54,3 +54,45 @@ describe("C027 × @suluk/models — the model-selection seam", () => {
     expect(r.ids).toEqual(["google/gemini-2.5-flash"]); // even though cheap-fast might prefer gpt-4o-mini
   });
 });
+
+describe("C030 resolution target — pin (default) / router (delegate) / latest, governance-gated", () => {
+  test("default is a REPRODUCIBLE pin", () => {
+    const r = skillModels(doc(), "conin", "operate", SEED_CATALOG);
+    expect(r.target).toEqual({ kind: "pinned", model: r.ids[0] });
+    expect(r.pickPinned).toBe(true);
+  });
+
+  test("modelResolve:'router' (ungoverned) delegates to openrouter/auto with an ENUMERATED survivor allowlist", () => {
+    const d = doc();
+    d["x-suluk-agents"]!.conin.skills!.operate = { modelProfile: "cheap-fast", modelResolve: "router" };
+    const r = skillModels(d, "conin", "operate", SEED_CATALOG);
+    expect(r.target.kind).toBe("router");
+    if (r.target.kind === "router") {
+      expect(r.target.model).toBe("openrouter/auto");
+      expect(r.target.allowedModels).toEqual(r.ids); // enumerated survivor ids — NEVER a wildcard
+      expect(r.target.costQualityTradeoff).toBeGreaterThan(5); // cheap-fast leans cost
+    }
+    expect(r.pickPinned).toBe(false);
+  });
+
+  test("a GOVERNED skill declaring 'router' FAILS LOUD (must pin — reproducible + endpoint-bindable)", () => {
+    const d = doc();
+    d["x-suluk-policy"] = { fleet: { appliesTo: ["#/x-suluk-agents/conin"], modelAllowlist: ["google/gemini-2.5-flash"] } };
+    d["x-suluk-agents"]!.conin.skills!.operate = { modelProfile: "balanced", modelResolve: "router" };
+    expect(() => skillModels(d, "conin", "operate", SEED_CATALOG)).toThrow(/GOVERNED|pinned/);
+  });
+
+  test("modelResolve:'latest' emits a ~-latest alias (non-reproducible, recorded)", () => {
+    const d = doc();
+    d["x-suluk-agents"]!.conin.skills!.operate = { modelProfile: "max-reasoning", modelResolve: "latest" };
+    const r = skillModels(d, "conin", "operate", SEED_CATALOG);
+    expect(r.target.kind).toBe("latest");
+    if (r.target.kind === "latest") expect(r.target.model.startsWith("~")).toBe(true);
+    expect(r.pickPinned).toBe(false);
+  });
+
+  test("deriveCQT is mechanical: cheap-fast leans cost (>5), max-reasoning leans quality (0)", () => {
+    expect(deriveCQT({ modelProfile: "cheap-fast" })).toBeGreaterThan(5);
+    expect(deriveCQT({ modelProfile: "max-reasoning" })).toBe(0);
+  });
+});