@suluk/agents 0.1.0

package/test/manifest.test.ts

@@ -0,0 +1,41 @@
+import { test, expect, describe } from "bun:test";
+import { agentManifest, verifyAgentFreshness, contentHash } from "../src/index";
+import { coninDoc, coninInstructions } from "./fixtures/conin";
+
+describe("C027 signable agent manifest", () => {
+  const m = agentManifest(coninDoc, "conin");
+
+  test("canonical: root + reachable sub-tree, sorted, no escalations", () => {
+    expect(m.manifestVersion).toBe(1);
+    expect(m.agent).toBe("conin");
+    expect(m.nodes.map((n) => n.name)).toEqual(["conin", "coninRetrieval"]);
+    expect(m.escalations).toEqual([]);
+    expect(m.reachable.tools).toEqual(["find_comparables", "generate_deliverable", "run_core_primitive", "search_library"]);
+  });
+
+  test("carries each skill's contentHash (so a signature over the manifest covers preprompt drift)", () => {
+    const conin = m.nodes.find((n) => n.name === "conin")!;
+    expect(conin.skills[0].contentHash).toBe("sha256-9f2c0000deadbeef");
+    expect(conin.effectiveScope).toEqual(["project:read", "deliverable:write", "library:read"]);
+    const retr = m.nodes.find((n) => n.name === "coninRetrieval")!;
+    expect(retr.effectiveScope).toEqual(["library:read"]);
+  });
+
+  test("deterministic — twice equal", () => {
+    expect(agentManifest(coninDoc, "conin")).toEqual(m);
+  });
+
+  test("freshness: a drifted served snapshot is caught against the signed contentHash", () => {
+    // declared hashes in the fixture are placeholders → any real snapshot drifts
+    const drift = verifyAgentFreshness(m, { "conin/operate": coninInstructions.operate });
+    expect(drift.map((f) => f.code)).toContain("stale-skill");
+    // a snapshot whose hash MATCHES the signed one is fresh
+    const matchHash = m.nodes.find((n) => n.name === "conin")!.skills[0].contentHash!;
+    const synthetic = "X".repeat(3);
+    // build a manifest whose skill hash equals the synthetic snapshot's hash, then verify fresh
+    const m2 = structuredClone(m);
+    m2.nodes.find((n) => n.name === "conin")!.skills[0].contentHash = contentHash(synthetic);
+    expect(verifyAgentFreshness(m2, { "conin/operate": synthetic }).filter((f) => f.code === "stale-skill")).toEqual([]);
+    expect(matchHash.startsWith("sha256-")).toBe(true);
+  });
+});

package/test/model-select.test.ts

@@ -0,0 +1,56 @@
+import { test, expect, describe } from "bun:test";
+import type { OpenAPIv4Document } from "@suluk/core";
+import { skillModels, resolveSkillModels, 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 {
+  return {
+    openapi: "4.0.0-candidate",
+    info: { title: "x", version: "0" },
+    paths: { "v1/s": { requests: { search: { method: "get", responses: { ok: { status: 200 } } } } } },
+    "x-suluk-agents": {
+      conin: {
+        description: "orchestrator with a tool",
+        routes: { search: { operationRef: "#/paths/v1~1s/requests/search" } },
+        skills: {
+          operate: { modelProfile: "cheap-fast" },          // needs-based ⇒ catalog selects
+          legacy: { model: ["anthropic/claude-opus-4"] },   // explicit list ⇒ opt-out, returned verbatim
+        },
+      },
+    },
+  } as OpenAPIv4Document;
+}
+
+describe("C027 × @suluk/models — the model-selection seam", () => {
+  test("a needs-based skill resolves to a catalog SELECTION (tool-calling derived from the agent's routes)", () => {
+    const r = skillModels(doc(), "conin", "operate", SEED_CATALOG);
+    expect(r.from).toBe("selected");
+    expect(r.ids.length).toBeGreaterThan(0);
+    expect(r.snapshotHash).toBe(SEED_CATALOG.snapshotHash); // reproducible pin
+    // hasRoutes ⇒ needsTools was derived ⇒ the winner passed the tool-calling filter
+    expect(r.selection!.ranked[0].why.passedFilters).toContain("tool-calling");
+    // cheap-fast ⇒ a cheap model, never the premium ones
+    expect(["anthropic/claude-opus-4", "openai/gpt-5"]).not.toContain(r.ids[0]);
+  });
+
+  test("an explicit model[] with no profile is the author's OPT-OUT — returned verbatim", () => {
+    const r = skillModels(doc(), "conin", "legacy", SEED_CATALOG);
+    expect(r.from).toBe("declared");
+    expect(r.ids).toEqual(["anthropic/claude-opus-4"]);
+    expect(r.snapshotHash).toBeNull();
+  });
+
+  test("the analyzer's minWindowRequired flows in as a hard min-context filter", () => {
+    // require a 500k window ⇒ only the 1M-window seed models survive
+    const sel = resolveSkillModels(doc(), "conin", "operate", SEED_CATALOG, 500000);
+    const ids = sel.ranked.map((x) => x.id);
+    expect(ids.every((id) => ["google/gemini-2.5-flash", "google/gemini-2.5-pro", "meta-llama/llama-4-maverick"].includes(id))).toBe(true);
+  });
+
+  test("the C028 modelAllowlist is the TERMINAL MEET — selection is restricted to it", () => {
+    const d = doc();
+    d["x-suluk-policy"] = { fleet: { appliesTo: ["#/x-suluk-agents/conin"], modelAllowlist: ["google/gemini-2.5-flash"] } };
+    const r = skillModels(d, "conin", "operate", SEED_CATALOG);
+    expect(r.ids).toEqual(["google/gemini-2.5-flash"]); // even though cheap-fast might prefer gpt-4o-mini
+  });
+});

package/test/policy.test.ts

@@ -0,0 +1,103 @@
+import { test, expect, describe } from "bun:test";
+import type { OpenAPIv4Document } from "@suluk/core";
+import {
+  effectiveUnderPolicies, policyConstrain, lintPolicy, policyOk,
+  agentManifest, assertServedSubsetGoverned,
+} from "../src/index";
+import { coninDoc } from "./fixtures/conin";
+
+/** Conin under an operator policy that narrows every axis. */
+function governed(): OpenAPIv4Document {
+  const d = structuredClone(coninDoc);
+  d["x-suluk-policy"] = {
+    "acme-fleet": {
+      appliesTo: ["#/x-suluk-agents/conin", "#/x-suluk-agents/coninRetrieval"],
+      scopeAllowlist: ["project:read", "library:read"], // drops deliverable:write
+      tools: { deny: ["run_core_primitive"] },
+      capTier: "resident",                               // conin.operate is cold-tail → resident
+      modelAllowlist: ["google/gemini-2.5-flash"],       // drops opus
+      maxDepthCap: 0,
+      forbidNesting: true,                               // removes the retrieval sub-agent
+      costCeiling: { amount: 5000, amountUnit: "micro-usd", basis: "per-request", enforcedBy: "adapter" },
+    },
+  };
+  return d;
+}
+
+describe("C028 policyConstrain — monotone-narrowing MEET (effective = INTERSECT(operator, agent))", () => {
+  const d = governed();
+  const { effective, narrowings } = effectiveUnderPolicies(d, "conin");
+
+  test("narrows scope, model, tier, tools, depth, nesting — never widens", () => {
+    expect(effective.scope).toEqual(["project:read", "library:read"]); // deliverable:write removed
+    const operate = effective.skills.find((s) => s.name === "operate")!;
+    expect(operate.model).toEqual(["google/gemini-2.5-flash"]); // opus dropped
+    expect(operate.tier).toBe("resident");                      // capped from cold-tail
+    expect(operate.usable).toBe(true);
+    expect(effective.allowedTools).toEqual(["generate_deliverable"]);
+    expect(effective.deniedTools).toEqual(["run_core_primitive"]);
+    expect(effective.nestingForbidden).toBe(true);
+    expect(effective.maxDepth).toBe(0);
+    expect(effective.deniedSubAgents).toEqual(["retrieval"]);
+    expect(narrowings.map((n) => n.axis).sort()).toEqual(["model", "nesting", "scope", "tier", "tools"]);
+  });
+
+  test("the MEET never grants a capability the agent did not self-declare", () => {
+    // effective scope ⊆ agent scope
+    const declared = d["x-suluk-agents"]!.conin.scope!;
+    expect(effective.scope!.every((s) => declared.includes(s))).toBe(true);
+  });
+});
+
+describe("C028 lintPolicy", () => {
+  test("a satisfiable, well-formed policy lints clean (no errors)", () => {
+    const findings = lintPolicy(governed());
+    expect(findings.filter((f) => f.severity === "error")).toEqual([]);
+    expect(policyOk(findings)).toBe(true);
+  });
+
+  test("NAMED failure: a modelAllowlist that excludes every model of a skill is unsatisfiable", () => {
+    const d = governed();
+    d["x-suluk-policy"]!["acme-fleet"].modelAllowlist = ["openai/gpt-9"]; // matches no Conin skill model
+    expect(lintPolicy(d).some((f) => f.code === "policy-unsatisfiable")).toBe(true);
+  });
+
+  test("appliesTo must resolve to a real agent (dangling caught)", () => {
+    const d = governed();
+    d["x-suluk-policy"]!["acme-fleet"].appliesTo = ["#/x-suluk-agents/ghost"];
+    expect(lintPolicy(d).some((f) => f.code === "policy-applies-dangling")).toBe(true);
+  });
+
+  test("D1: a request-value selector smuggled into a policy is forbidden", () => {
+    const d = governed();
+    d["x-suluk-policy"]!["acme-fleet"]["x-when"] = "{$request.body#/tier}";
+    expect(lintPolicy(d).some((f) => f.code === "request-value-selector")).toBe(true);
+  });
+
+  test("cap-below-estimate: an operator cap under the agent's own estimate is flagged (cross-facet, static)", () => {
+    const d = governed();
+    d["x-suluk-agents"]!.conin["x-suluk-cost"] = { estimateMicroUsd: 10000 };
+    // cap = 5000 µ$ < estimate 10000 µ$
+    expect(lintPolicy(d).some((f) => f.code === "cap-below-estimate")).toBe(true);
+  });
+});
+
+describe("C028 manifest + conformance folds", () => {
+  test("the signed manifest carries the operator-effective surface (so the signature covers caps)", () => {
+    const m = agentManifest(governed(), "conin");
+    const conin = m.nodes.find((n) => n.name === "conin")!;
+    expect(conin.governed).toBeDefined();
+    expect(conin.governed!.allowedTools).toEqual(["generate_deliverable"]);
+    expect(conin.governed!.deniedTools).toEqual(["run_core_primitive"]);
+    expect(conin.governed!.nestingForbidden).toBe(true);
+    expect(conin.governed!.maxDepth).toBe(0);
+    // an ungoverned agent has no `governed` field
+    expect(agentManifest(coninDoc, "conin").nodes.find((n) => n.name === "conin")!.governed).toBeUndefined();
+  });
+
+  test("NAMED failure: serving a policy-DENIED tool is an over-serve (operator cap not holding on the wire)", () => {
+    const findings = assertServedSubsetGoverned(governed(), "conin", ["generate_deliverable", "run_core_primitive"]);
+    expect(findings.map((f) => f.code)).toEqual(["policy-denied-served"]);
+    expect(findings[0].detail).toContain("run_core_primitive");
+  });
+});

package/test/project.test.ts

@@ -0,0 +1,103 @@
+import { test, expect, describe } from "bun:test";
+import { projectClaudePlugin, projectOpenRouter, contentHash, residentSurface, assertDefaultServedResident } from "../src/index";
+import { coninDoc, coninInstructions, coninDayOne } from "./fixtures/conin";
+
+describe("C027 Claude-plugin projection", () => {
+  const plug = projectClaudePlugin(coninDoc, "conin", {
+    mcpUrl: "https://construction-intelligence.saastemly.com/mcp",
+    version: "1.0.0",
+    homepage: "https://construction-intelligence.saastemly.com",
+    instructions: coninInstructions,
+  });
+
+  test("emits plugin.json + .mcp.json + a generated SKILL.md", () => {
+    expect(Object.keys(plug.files).sort()).toEqual([".mcp.json", "plugin.json", "skills/operate/SKILL.md"]);
+    const pj = JSON.parse(plug.files["plugin.json"]);
+    expect(pj.name).toBe("conin");
+    expect(pj.mcpServers).toBe("./.mcp.json");
+    expect(pj.description.length).toBeGreaterThan(10);
+  });
+
+  test(".mcp.json is HTTP MCP with host-side OAuth and NO embedded credential", () => {
+    const mj = JSON.parse(plug.files[".mcp.json"]);
+    expect(mj.mcpServers.conin.type).toBe("http");
+    expect(mj.mcpServers.conin.url).toContain("/mcp");
+    expect(mj.mcpServers.conin.oauth).toEqual({});
+    // no token / bearer / secret may ever appear in a projected artifact
+    expect(plug.files[".mcp.json"]).not.toMatch(/bearer|token|secret|api[_-]?key/i);
+  });
+
+  test("SKILL.md carries the contentHash + version staleness stamp (the genuinely-missing feature)", () => {
+    const md = plug.files["skills/operate/SKILL.md"];
+    expect(md).toContain("name: operate");
+    expect(md).toContain(`contentHash: ${contentHash(coninInstructions.operate)}`);
+    expect(md).toContain("version: 2026-06-11");
+    expect(md).toContain("source: https://construction-intelligence.saastemly.com/v1/instructions");
+    expect(md.trimEnd().endsWith(coninInstructions.operate)).toBe(true);
+  });
+
+  test("projection is a PURE FUNCTION — same contract in, byte-identical artifacts out", () => {
+    const again = projectClaudePlugin(coninDoc, "conin", {
+      mcpUrl: "https://construction-intelligence.saastemly.com/mcp",
+      version: "1.0.0",
+      homepage: "https://construction-intelligence.saastemly.com",
+      instructions: coninInstructions,
+    });
+    expect(again).toEqual(plug);
+  });
+});
+
+describe("C027 OpenRouter projection", () => {
+  const m = projectOpenRouter(coninDoc, "conin", { instructions: coninInstructions });
+
+  test("routes → function tools keyed by the wire id; model preference from the primary skill", () => {
+    expect(m.model).toEqual(["anthropic/claude-opus-4", "google/gemini-2.5-flash"]);
+    expect(m.tier).toBe("cold-tail");
+    expect(m.tools.map((t) => t.function.name).sort()).toEqual(["generate_deliverable", "run_core_primitive"]);
+    expect(m.tools.every((t) => t.type === "function")).toBe(true);
+  });
+
+  test("instructions is a pointer + a pinned contentHash, never the raw text by default", () => {
+    expect(m.instructions.source).toContain("/v1/instructions");
+    expect(m.instructions.contentHash).toBe(contentHash(coninInstructions.operate));
+    expect(m.instructions.version).toBe("2026-06-11");
+  });
+
+  test("sub-agents surface as front-door dispatch targets, by name", () => {
+    expect(m.subAgents).toEqual([{ name: "retrieval", ref: "#/x-suluk-agents/coninRetrieval" }]);
+  });
+
+  test("deterministic — twice equal", () => {
+    expect(projectOpenRouter(coninDoc, "conin", { instructions: coninInstructions })).toEqual(m);
+  });
+});
+
+describe("C027 tier-trim — cold-tail routes leave the default served surface (the real context reduction)", () => {
+  const tiered = structuredClone(coninDoc);
+  tiered["x-suluk-agents"]!.conin.routes!.run_core_primitive.tier = "cold-tail";
+  const m = projectOpenRouter(tiered, "conin", { instructions: coninInstructions });
+
+  test("default tools[] = resident + discover_tools; cold-tail moves to discoverable[]", () => {
+    expect(m.tools.map((t) => t.function.name).sort()).toEqual(["discover_tools", "generate_deliverable"]);
+    expect(m.discoverable.map((t) => t.function.name)).toEqual(["run_core_primitive"]);
+  });
+
+  test("no discover_tools meta when there is nothing to discover (all resident)", () => {
+    const allResident = projectOpenRouter(coninDoc, "conin", { instructions: coninInstructions });
+    expect(allResident.tools.some((t) => t.function.name === "discover_tools")).toBe(false);
+    expect(allResident.discoverable).toEqual([]);
+  });
+
+  test("residentSurface + the cold-tail-in-default conformance auditor", () => {
+    expect(residentSurface(tiered, "conin")).toEqual(["generate_deliverable"]);
+    expect(assertDefaultServedResident(tiered, "conin", ["generate_deliverable"])).toEqual([]);
+    expect(assertDefaultServedResident(tiered, "conin", ["generate_deliverable", "run_core_primitive"]).map((f) => f.code)).toEqual(["cold-tail-in-default"]);
+  });
+});
+
+describe("projection refuses a non-installable agent (fail-loud, not a broken artifact)", () => {
+  test("Conin's day-one dangling operationRef throws on BOTH targets", () => {
+    expect(() => projectOpenRouter(coninDayOne(), "conin")).toThrow(/does not install|run_core_primitive|dangling/);
+    expect(() => projectClaudePlugin(coninDayOne(), "conin", { mcpUrl: "https://x/mcp" })).toThrow(/does not install|run_core_primitive|dangling/);
+  });
+});

package/test/scope.test.ts

@@ -0,0 +1,27 @@
+import { test, expect, describe } from "bun:test";
+import { intersectScope, analyzeScopes, lintAgents } from "../src/index";
+import { coninDoc, escalationDoc } from "./fixtures/conin";
+
+describe("C027 scope intersection (least-privilege by construction)", () => {
+  test("intersectScope treats null as unconstrained", () => {
+    expect(intersectScope(null, ["a", "b"])).toEqual(["a", "b"]);
+    expect(intersectScope(["a", "b"], null)).toEqual(["a", "b"]);
+    expect(intersectScope(["a", "b", "c"], ["b", "c", "d"])).toEqual(["b", "c"]);
+    expect(intersectScope(null, null)).toBeNull();
+  });
+
+  test("a child's effective scope is the intersection with its caller's", () => {
+    const { effective, escalations } = analyzeScopes(coninDoc, "conin");
+    expect(escalations).toEqual([]);
+    expect(effective["conin"]).toEqual(["project:read", "deliverable:write", "library:read"]);
+    // retrieval declares only library:read; caller grants it → effective = library:read
+    expect(effective["coninRetrieval"]).toEqual(["library:read"]);
+  });
+
+  test("NAMED failure: a child needing a permission the caller doesn't grant is an escalation (confused-deputy)", () => {
+    const { escalations } = analyzeScopes(escalationDoc(), "conin");
+    expect(escalations).toEqual([{ parent: "conin", childLocal: "retrieval", child: "coninRetrieval", perms: ["library:read"] }]);
+    // and it blocks installation (an error-severity lint)
+    expect(lintAgents(escalationDoc()).some((f) => f.severity === "error" && f.code === "scope-escalation")).toBe(true);
+  });
+});

package/test/signing.integration.test.ts

@@ -0,0 +1,45 @@
+import { test, expect, describe } from "bun:test";
+import { signRegistry, verifyRegistrySignature, generateSigningKeypair } from "@suluk/builder";
+import { agentManifest, verifyAgentFreshness, contentHash } from "../src/index";
+import { coninDoc, coninInstructions } from "./fixtures/conin";
+
+/**
+ * The C027 marketplace supply-chain loop (council open-Q #8): an agent manifest is signed through the SAME
+ * @suluk/builder ECDSA-P256 registry signing (C021). Because the manifest carries each skill's contentHash, the
+ * signature COVERS the served preprompt — a preprompt that drifts after mint is detectable (verifyAgentFreshness),
+ * and any structural tamper breaks the signature. One mechanism, reused unchanged.
+ */
+describe("C027 × C021 — a signed agent manifest covers preprompt drift", () => {
+  const snapshot = coninInstructions.operate;
+
+  test("sign → verify → preprompt-drift caught → structural-tamper caught", async () => {
+    // pin the operate skill's contentHash to the actual served snapshot, then mint a signature over the manifest
+    const manifest = agentManifest(coninDoc, "conin");
+    manifest.nodes.find((n) => n.name === "conin")!.skills[0].contentHash = contentHash(snapshot);
+
+    const { publicKey, privateKey } = await generateSigningKeypair();
+    const sig = await signRegistry(manifest, privateKey);
+
+    // (1) a faithfully-distributed manifest verifies, and its skills are fresh against the current snapshot
+    expect(await verifyRegistrySignature(manifest, sig, publicKey)).toBe(true);
+    expect(verifyAgentFreshness(manifest, { "conin/operate": snapshot }).filter((f) => f.code === "stale-skill")).toEqual([]);
+
+    // (2) PREPROMPT DRIFT after mint: the served text changes but the signed manifest does not — the signature still
+    //     verifies (nothing in the artifact changed), yet the freshness check catches the drift via the signed hash
+    const drifted = snapshot + "  ← edited on the server after signing";
+    expect(await verifyRegistrySignature(manifest, sig, publicKey)).toBe(true);
+    expect(verifyAgentFreshness(manifest, { "conin/operate": drifted }).map((f) => f.code)).toContain("stale-skill");
+
+    // (3) STRUCTURAL TAMPER: mutate the manifest (redirect a route) — the signature no longer verifies
+    const tampered = structuredClone(manifest);
+    tampered.nodes.find((n) => n.name === "conin")!.routes[0].operationRef = "#/paths/evil/requests/x";
+    expect(await verifyRegistrySignature(tampered, sig, publicKey)).toBe(false);
+
+    // (4) key-order independence: same content, different top-level insertion order, still verifies (canonicalJson)
+    const reordered = {
+      escalations: manifest.escalations, reachable: manifest.reachable,
+      nodes: manifest.nodes, agent: manifest.agent, manifestVersion: manifest.manifestVersion,
+    };
+    expect(await verifyRegistrySignature(reordered, sig, publicKey)).toBe(true);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }