@suluk/cockpit 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "The pure cockpit core (cycle model · builder model · codegen · deploy planning · validate/audit/preview) shared by the vscode extension and the /superadmin web admin panel. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"
@@ -19,7 +19,7 @@
   ".": "./src/index.ts"
 },
 "dependencies": {
-  "@suluk/core": "^0.1.7",
+  "@suluk/core": "^0.1.9",
   "@suluk/hono": "^0.1.2",
   "@suluk/scalar": "^0.1.2",
   "@suluk/swagger": "^0.1.2",
@@ -27,7 +27,8 @@
   "@suluk/builder": "^0.1.11",
   "@suluk/deploy": "^0.1.3",
   "@suluk/cost": "^0.1.2",
-  "@suluk/visual": "^0.1.3"
+  "@suluk/visual": "^0.1.3",
+  "@suluk/agents": "^0.1.1"
 },
 "devDependencies": {
   "@types/bun": "latest"

package/src/agents.ts

@@ -0,0 +1,191 @@
+/**
+ * The AGENTS view (C027) — the cockpit's OBSERVE surface for the `x-suluk-agents` composition layer. Pure
+ * (no host) → unit-tested; the extension/admin shells render it. STRICTLY OBSERVE: this derives the static tier
+ * tree, effective (intersection) scope, the gate findings, the worst-case reachable surface, and a PROJECTION
+ * PREVIEW (artifact file/tool NAMES only). It NEVER executes an agent, fetches a preprompt, or touches a
+ * credential — agent execution + secrets live outside the cockpit (C020 no-credentials seam / C023 L3 line).
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import {
+  lintAgents, lintOk, reachableSurface, analyzeScopes, resolveOperationRef,
+  agentMap, subAgentKey, effectiveUnderPolicies, policiesFor, lintPolicy, contextReport, skillModels,
+  type LintFinding, type Scope, type AgentContextLoad, type UnflattenSuggestion, type FlattenSuggestion, type ModelCatalog,
+} from "@suluk/agents";
+
+export interface AgentSkillView {
+  name: string;
+  model: string[];
+  tier?: "resident" | "cold-tail";
+  /** has a provenance.contentHash ⇒ drift is detectable (the staleness binding). */
+  pinned: boolean;
+  source?: string;
+}
+export interface AgentRouteView {
+  name: string;
+  operationRef: string;
+  guarantee?: string;
+  /** serving partition: resident (default tool list) vs cold-tail (behind discover_tools). Absent ⇒ resident. */
+  tier?: "resident" | "cold-tail";
+  /** does the operationRef resolve to a real operation? (false ⇒ a dangling ref, like Conin's MCP-only primitive). */
+  resolves: boolean;
+}
+export interface AgentNodeView {
+  name: string;
+  description: string;
+  /** an orchestrator has sub-agents; a leaf does not (the recursion base case). */
+  kind: "orchestrator" | "leaf";
+  maxDepth?: number;
+  /** scope after INTERSECTION along the reaching path (null = unconstrained). */
+  effectiveScope: Scope;
+  skills: AgentSkillView[];
+  routes: AgentRouteView[];
+  subAgents: string[];
+  /** worst-case statically-enumerable reach (tools + transitively-reachable sub-agents). */
+  reachable: { tools: string[]; agents: string[] };
+  /** OBSERVE-only preview of what projection WOULD emit — names, never executed, never credentialed. */
+  projection: { pluginFiles: string[]; openRouterTools: string[]; residentTools: string[]; discoverableTools: string[] };
+  /** operator governance diff (C028) — present only when an x-suluk-policy governs this agent. */
+  governed?: AgentGovernedView;
+  /** estimated default context load (resident instructions+tools+overhead) vs budget/window — the unflatten check (C027). */
+  context: AgentContextLoad;
+  /** per-skill model pick (C027 × @suluk/models) — present only when agentsView is given a catalog. OBSERVE-only:
+   * "why this model" (declared vs selected, top ids, deciding preference, UNKNOWN-coverage gaps). Never executes. */
+  modelSelection?: { skill: string; from?: "declared" | "selected"; ids?: string[]; resolve?: "pinned" | "router" | "latest"; pickPinned?: boolean; decidingPreference?: string; coverageGaps?: string[]; error?: string }[];
+}
+/** The agent-declared vs operator-effective diff + the cost three-number (cap / estimate / actual). Read-only. */
+export interface AgentGovernedView {
+  effectiveScope: Scope;
+  effectiveMaxDepth?: number;
+  nestingForbidden: boolean;
+  deniedTools: string[];
+  deniedSubAgents: string[];
+  narrowings: { axis: string; detail: string }[];
+  /** the three distinct owners: cap (operator x-suluk-policy, enforced-by-adapter) / estimate (author) / actual (C026 runtime). */
+  cost: { cap: string | null; estimate: string | null; actual: string };
+}
+export interface AgentsView {
+  present: boolean;
+  agents: AgentNodeView[];
+  /** entry-point agents — not referenced as a sub-agent by any other agent. */
+  roots: string[];
+  findings: LintFinding[];
+  /** true ⇒ no error-severity findings across the whole map (the gate). */
+  installable: boolean;
+  /** context-budget findings (model-fit / over-budget / overloaded / empty-layer / passthrough / flattenable) — the right-sizing check. */
+  contextFindings: LintFinding[];
+  /** for every over-target agent: what to move to cold-tail or extract into a sub-agent (split DOWN). */
+  unflatten: UnflattenSuggestion[];
+  /** for every thin/redundant layer: what to collapse up (the dual — merge UP). */
+  flatten: FlattenSuggestion[];
+}
+
+/** Agents referenced as a sub-agent by someone else (so the complement is the set of roots). */
+function referencedChildren(doc: OpenAPIv4Document): Set<string> {
+  const ref = new Set<string>();
+  for (const a of Object.values(agentMap(doc))) {
+    for (const r of Object.values(a.agents ?? {})) {
+      const k = subAgentKey(r.ref);
+      if (k) ref.add(k);
+    }
+  }
+  return ref;
+}
+
+/** The operator-governance diff for one agent (declared vs effective + the cost three-number). */
+function governedView(doc: OpenAPIv4Document, agentName: string): AgentGovernedView {
+  const { effective, narrowings } = effectiveUnderPolicies(doc, agentName);
+  const policy = policiesFor(doc, agentName).find((p) => p.costCeiling);
+  const cap = policy?.costCeiling ? `${policy.costCeiling.amount} ${policy.costCeiling.amountUnit} (enforcedBy ${policy.costCeiling.enforcedBy})` : null;
+  const cost = agentMap(doc)[agentName]["x-suluk-cost"] as { estimateMicroUsd?: number; amount?: number } | undefined;
+  const est = cost?.estimateMicroUsd ?? cost?.amount;
+  return {
+    effectiveScope: effective.scope,
+    ...(effective.maxDepth !== undefined ? { effectiveMaxDepth: effective.maxDepth } : {}),
+    nestingForbidden: effective.nestingForbidden,
+    deniedTools: effective.deniedTools,
+    deniedSubAgents: effective.deniedSubAgents,
+    narrowings: narrowings.map((n) => ({ axis: n.axis, detail: n.detail })),
+    // three distinct owners — cap (operator, enforced-by-adapter) / estimate (author) / actual (runtime, C026)
+    cost: { cap, estimate: typeof est === "number" ? `${est} µ$` : null, actual: "reconciled at runtime (C026)" },
+  };
+}
+
+/** Build the OBSERVE view-model for the agent layer of a document. Never throws; tolerates non-installable agents. */
+export function agentsView(doc: OpenAPIv4Document, opts: { catalog?: ModelCatalog } = {}): AgentsView {
+  const map = agentMap(doc);
+  const names = Object.keys(map).sort((a, b) => a.localeCompare(b));
+  const present = names.length > 0;
+  const findings = [...lintAgents(doc), ...lintPolicy(doc)];
+  const cr = contextReport(doc, opts.catalog ? { catalog: opts.catalog } : {}); // static load (no snapshots ⇒ a lower bound)
+
+  // effective scopes across the whole map: merge a walk from every root (covers every reachable node)
+  const referenced = referencedChildren(doc);
+  const roots = names.filter((n) => !referenced.has(n));
+  const effAll: Record<string, Scope> = {};
+  for (const r of roots) Object.assign(effAll, analyzeScopes(doc, r).effective);
+
+  const agents: AgentNodeView[] = names.map((name) => {
+    const a = map[name];
+    const subAgents = Object.values(a.agents ?? {}).map((r) => r.ref).sort();
+    const skills: AgentSkillView[] = Object.entries(a.skills ?? {}).map(([sk, s]) => ({
+      name: sk,
+      model: s.model ?? [],
+      ...(s.tier ? { tier: s.tier } : {}),
+      pinned: !!s.provenance?.contentHash,
+      ...(s.provenance?.source ? { source: s.provenance.source } : {}),
+    })).sort((x, y) => x.name.localeCompare(y.name));
+    const routes: AgentRouteView[] = Object.entries(a.routes ?? {}).map(([rk, r]) => ({
+      name: rk,
+      operationRef: r.operationRef,
+      ...(r.guarantee ? { guarantee: r.guarantee } : {}),
+      ...(r.tier ? { tier: r.tier } : {}),
+      resolves: !!resolveOperationRef(doc, r.operationRef),
+    })).sort((x, y) => x.name.localeCompare(y.name));
+    return {
+      name,
+      description: a.description,
+      kind: subAgents.length > 0 ? "orchestrator" : "leaf",
+      ...(a.maxDepth !== undefined ? { maxDepth: a.maxDepth } : {}),
+      effectiveScope: effAll[name] ?? (a.scope ?? null),
+      skills,
+      routes,
+      subAgents,
+      reachable: reachableSurface(doc, name),
+      projection: {
+        pluginFiles: ["plugin.json", ".mcp.json", ...skills.map((s) => `skills/${s.name}/SKILL.md`)],
+        openRouterTools: routes.map((r) => r.name),
+        // the tier-trim: only resident tools are in the default surface; cold-tail sits behind discover_tools
+        residentTools: routes.filter((r) => r.tier !== "cold-tail").map((r) => r.name),
+        discoverableTools: routes.filter((r) => r.tier === "cold-tail").map((r) => r.name),
+      },
+      ...(policiesFor(doc, name).length > 0 ? { governed: governedView(doc, name) } : {}),
+      context: cr.loads.find((l) => l.agent === name)!,
+      ...(opts.catalog ? {
+        modelSelection: Object.keys(a.skills ?? {}).sort().map((sk) => {
+          const minWin = cr.loads.find((l) => l.agent === name)?.minWindowRequired;
+          try {
+            const r = skillModels(doc, name, sk, opts.catalog!, minWin);
+            return {
+              skill: sk, from: r.from, ids: r.ids.slice(0, 3), resolve: r.target.kind, pickPinned: r.pickPinned,
+              ...(r.selection?.ranked[0] ? { decidingPreference: r.selection.ranked[0].why.decidingPreference } : {}),
+              ...(r.selection ? { coverageGaps: r.selection.coverageGaps } : {}),
+            };
+          } catch (e) { return { skill: sk, error: e instanceof Error ? e.message : String(e) }; } // governed + router ⇒ fail-loud, surfaced
+        }),
+      } : {}),
+    };
+  });
+
+  return { present, agents, roots, findings, installable: lintOk(findings), contextFindings: cr.findings, unflatten: cr.suggestions, flatten: cr.flatten };
+}
+
+/** A one-line ship-readiness summary for the agent layer (mirrors the cockpit's other *Summary helpers). */
+export function agentsSummary(view: AgentsView): string {
+  if (!view.present) return "no agents (x-suluk-agents absent)";
+  const errs = view.findings.filter((f) => f.severity === "error").length;
+  const warns = view.findings.filter((f) => f.severity === "warning").length;
+  const verdict = view.installable ? "✓ installable" : `✕ ${errs} blocking`;
+  const unflatten = view.unflatten.length ? `, ${view.unflatten.length} to unflatten` : "";
+  const flatten = view.flatten.length ? `, ${view.flatten.length} to flatten` : "";
+  return `${view.agents.length} agent(s), ${view.roots.length} root(s) — ${verdict}${warns ? `, ${warns} warning(s)` : ""}${unflatten}${flatten}`;
+}

package/src/index.ts

@@ -23,6 +23,12 @@ export { componentReport, approveComponents, type ComponentReport } from "./visu
 export { type Baseline, primitiveCss } from "@suluk/visual";
 // lifecycle / ship-readiness (L3): the round-trip loop as one checklist — authored → coherent → confident → generated → deployed.
 export { contractGates, shipSummary, type Gate, type GateStatus } from "./lifecycle";
+// agents (C027, OBSERVE): the x-suluk-agents tier tree, effective scope, gate findings, reachable surface + a
+// projection preview — read-only; agent execution + secrets live OUTSIDE the cockpit (C020 no-credentials seam).
+export {
+  agentsView, agentsSummary,
+  type AgentsView, type AgentNodeView, type AgentSkillView, type AgentRouteView, type AgentGovernedView,
+} from "./agents";
 // cost formatting, re-exported so the extension shell can render a live /cost ledger without a direct @suluk/cost dep.
 export { formatMicroUsd, summarize, type CostSummary } from "@suluk/cost";
 // modules (C021): install a contract fragment into the hub doc — the cockpit then re-projects it for free.

package/test/agents.test.ts

@@ -0,0 +1,146 @@
+import { test, expect, describe } from "bun:test";
+import type { OpenAPIv4Document, HttpMethod, Request } from "@suluk/core";
+import { agentsView, agentsSummary } from "../src/index";
+import { SEED_CATALOG } from "@suluk/agents";
+
+const req = (method: HttpMethod): Request => ({ method, responses: { ok: { status: 200 } } });
+
+const doc: OpenAPIv4Document = {
+  openapi: "4.0.0-candidate",
+  info: { title: "agents-view", version: "0" },
+  paths: {
+    "v1/deliverables": { requests: { generateDeliverable: req("post") } },
+    "v1/library/search": { requests: { searchLibrary: req("get") } },
+  },
+  "x-suluk-agents": {
+    conin: {
+      description: "Orchestrator: docs → graded deliverables.",
+      scope: ["project:read", "library:read"],
+      maxDepth: 1,
+      skills: { operate: { model: ["anthropic/claude-opus-4"], tier: "cold-tail", provenance: { source: "https://x/v1/instructions", contentHash: "sha256-abc", version: "1" } } },
+      routes: { generate_deliverable: { operationRef: "#/paths/v1~1deliverables/requests/generateDeliverable", guarantee: "same-in-same-out" } },
+      agents: { retrieval: { ref: "#/x-suluk-agents/coninRetrieval" } },
+    },
+    coninRetrieval: {
+      description: "Untrusted retrieval leaf.",
+      scope: ["library:read"],
+      maxDepth: 0,
+      skills: { search: { model: ["google/gemini-2.5-flash"], tier: "resident" } }, // no provenance ⇒ unpinned
+      routes: { search_library: { operationRef: "#/paths/v1~1library~1search/requests/searchLibrary" } },
+      agents: {},
+    },
+  },
+};
+
+describe("C027 cockpit agents view (OBSERVE)", () => {
+  const v = agentsView(doc);
+
+  test("derives the tier tree + roots", () => {
+    expect(v.present).toBe(true);
+    expect(v.agents.map((a) => a.name)).toEqual(["conin", "coninRetrieval"]);
+    expect(v.roots).toEqual(["conin"]); // retrieval is referenced as a sub-agent → not a root
+    const [conin, retr] = v.agents;
+    expect(conin.kind).toBe("orchestrator");
+    expect(retr.kind).toBe("leaf");
+  });
+
+  test("shows effective (intersection) scope + skill pinning + route resolution", () => {
+    const conin = v.agents.find((a) => a.name === "conin")!;
+    const retr = v.agents.find((a) => a.name === "coninRetrieval")!;
+    expect(conin.effectiveScope).toEqual(["project:read", "library:read"]);
+    expect(retr.effectiveScope).toEqual(["library:read"]);
+    expect(conin.skills[0].pinned).toBe(true);   // has contentHash
+    expect(retr.skills[0].pinned).toBe(false);   // no provenance
+    expect(conin.routes[0].resolves).toBe(true);
+    expect(conin.reachable.tools).toEqual(["generate_deliverable", "search_library"]);
+  });
+
+  test("projection preview is names-only (no execution, no creds)", () => {
+    const conin = v.agents.find((a) => a.name === "conin")!;
+    expect(conin.projection.pluginFiles).toEqual(["plugin.json", ".mcp.json", "skills/operate/SKILL.md"]);
+    expect(conin.projection.openRouterTools).toEqual(["generate_deliverable"]);
+  });
+
+  test("tier-trim is visible in the projection preview (resident vs discoverable)", () => {
+    const t = structuredClone(doc);
+    t["x-suluk-agents"]!.coninRetrieval.routes!.search_library.tier = "cold-tail";
+    const retr = agentsView(t).agents.find((a) => a.name === "coninRetrieval")!;
+    expect(retr.projection.discoverableTools).toEqual(["search_library"]);
+    expect(retr.projection.residentTools).not.toContain("search_library");
+    expect(retr.routes.find((r) => r.name === "search_library")!.tier).toBe("cold-tail");
+  });
+
+  test("installable + summary when the gate is clean", () => {
+    expect(v.installable).toBe(true);
+    expect(agentsSummary(v)).toContain("✓ installable");
+  });
+
+  test("a dangling operationRef surfaces in the view AND blocks installability", () => {
+    const bad = structuredClone(doc);
+    bad["x-suluk-agents"]!.conin.routes!.generate_deliverable.operationRef = "#/paths/nope/requests/x";
+    const bv = agentsView(bad);
+    expect(bv.installable).toBe(false);
+    expect(bv.agents.find((a) => a.name === "conin")!.routes[0].resolves).toBe(false);
+    expect(bv.findings.some((f) => f.code === "dangling-operation-ref")).toBe(true);
+    expect(agentsSummary(bv)).toContain("blocking");
+  });
+
+  test("context-budget load is attached, and unflatten surfaces when an agent is over budget (the add-a-layer check)", () => {
+    expect(v.agents.find((a) => a.name === "conin")!.context.totalTokens).toBeGreaterThan(0);
+    const tiny = structuredClone(doc);
+    tiny["x-suluk-agents"]!.conin.contextBudget = { tokens: 50, basis: "estimate" };
+    const v2 = agentsView(tiny);
+    expect(v2.contextFindings.some((f) => f.code === "context-over-budget")).toBe(true);
+    expect(v2.unflatten.some((u) => u.agent === "conin")).toBe(true);
+    expect(agentsSummary(v2)).toContain("unflatten");
+  });
+
+  test("model selection surfaces 'why this model' when a catalog is supplied (C027 × @suluk/models)", () => {
+    const view = agentsView(doc, { catalog: SEED_CATALOG });
+    const conin = view.agents.find((a) => a.name === "conin")!;
+    expect(conin.modelSelection).toBeDefined();
+    const operate = conin.modelSelection!.find((m) => m.skill === "operate")!;
+    expect(operate.from).toBe("declared"); // operate has an explicit model[] → opt-out
+    expect(operate.ids).toEqual(["anthropic/claude-opus-4"]);
+    expect(agentsView(doc).agents[0].modelSelection).toBeUndefined(); // no catalog ⇒ no surface (back-compat)
+
+    const d = structuredClone(doc);
+    d["x-suluk-agents"]!.conin.skills!.operate = { modelProfile: "cheap-fast" };
+    const sel = agentsView(d, { catalog: SEED_CATALOG }).agents.find((a) => a.name === "conin")!.modelSelection!.find((m) => m.skill === "operate")!;
+    expect(sel.from).toBe("selected");
+    expect(sel.ids!.length).toBeGreaterThan(0);
+    expect(sel.resolve).toBe("pinned"); // C030 default, ungoverned
+    expect(sel.pickPinned).toBe(true);
+    expect(sel.decidingPreference).toBeTruthy();
+  });
+
+  test("absent agent layer is handled", () => {
+    const empty = agentsView({ openapi: "4.0.0-candidate", info: { title: "x", version: "0" }, paths: {} });
+    expect(empty.present).toBe(false);
+    expect(agentsSummary(empty)).toContain("no agents");
+  });
+
+  test("operator policy (C028): the OBSERVE diff shows declared vs effective + the cost three-number", () => {
+    const g = structuredClone(doc);
+    g["x-suluk-agents"]!.conin["x-suluk-cost"] = { estimateMicroUsd: 8000 };
+    g["x-suluk-policy"] = {
+      "acme-fleet": {
+        appliesTo: ["#/x-suluk-agents/conin"],
+        tools: { deny: ["generate_deliverable"] },
+        forbidNesting: true,
+        costCeiling: { amount: 5000, amountUnit: "micro-usd", basis: "per-request", enforcedBy: "adapter" },
+      },
+    };
+    const conin = agentsView(g).agents.find((a) => a.name === "conin")!;
+    expect(conin.governed).toBeDefined();
+    expect(conin.governed!.deniedTools).toEqual(["generate_deliverable"]);
+    expect(conin.governed!.nestingForbidden).toBe(true);
+    expect(conin.governed!.cost.cap).toContain("5000 micro-usd");
+    expect(conin.governed!.cost.cap).toContain("enforcedBy adapter"); // never reads as schema-enforced
+    expect(conin.governed!.cost.estimate).toBe("8000 µ$");
+    expect(conin.governed!.cost.actual).toContain("runtime");
+    expect(conin.governed!.narrowings.some((n) => n.axis === "tools")).toBe(true);
+    // an ungoverned agent has no diff
+    expect(agentsView(doc).agents.find((a) => a.name === "conin")!.governed).toBeUndefined();
+  });
+});