@suluk/agents 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@suluk/agents",
+  "version": "0.1.0",
+  "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"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/agents"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
+},
+"dependencies": {
+"@suluk/core": "^0.1.7",
+"@suluk/models": "^0.1.0"
+},
+"devDependencies": {
+"@types/bun": "latest",
+"@suluk/builder": "^0.1.11"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/conformance.ts

@@ -0,0 +1,97 @@
+/**
+ * Conformance checks that are NOT lint (they need a runtime/served fact to compare against the contract). The
+ * headline one is the OVER-SERVE auditor: the council red-line says the full reachable tool/route surface must be
+ * STATICALLY enumerable from the document, and a serving layer's `discover_tools` may REORDER/lazy-load but NEVER
+ * WIDEN the declared set. Conin's public MCP `tools/list` (app.ts:2585) ships the FULL catalog — a NAMED
+ * conformance failure this function catches.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { agentMap, childKeys } from "./resolve";
+import { contentHash } from "./skill";
+import { effectiveUnderPolicies, policiesFor } from "./policy";
+
+export interface ConformanceFinding {
+  code: string;
+  detail: string;
+}
+
+/**
+ * The statically-enumerable reachable surface of an agent: its own route keys (the wire ids) + every route key of
+ * every transitively-reachable sub-agent. Worst-case authz reach, computed with ZERO requests. (Cycle-safe.)
+ */
+export function reachableSurface(doc: OpenAPIv4Document, agentName: string): { tools: string[]; agents: string[] } {
+  const map = agentMap(doc);
+  const tools = new Set<string>();
+  const agents = new Set<string>();
+  const walk = (key: string) => {
+    const a = map[key];
+    if (!a || agents.has(key)) return;
+    agents.add(key);
+    for (const rk of Object.keys(a.routes ?? {})) tools.add(rk);
+    for (const c of childKeys(a)) if (c.key) walk(c.key);
+  };
+  walk(agentName);
+  agents.delete(agentName);
+  return { tools: [...tools].sort(), agents: [...agents].sort() };
+}
+
+/**
+ * OVER-SERVE auditor: assert the tools a server actually exposes are a SUBSET of the declared reachable surface.
+ * Any served tool NOT in the surface is a WIDENING — the contract is no longer the source of truth for authz reach.
+ */
+export function assertServedSubset(doc: OpenAPIv4Document, agentName: string, servedToolNames: string[]): ConformanceFinding[] {
+  const surface = new Set(reachableSurface(doc, agentName).tools);
+  return servedToolNames
+    .filter((t) => !surface.has(t))
+    .map((t) => ({ code: "over-serve", detail: `served tool "${t}" is NOT in the declared reachable surface — discover_tools may reorder/lazy-load, never widen` }));
+}
+
+/**
+ * The RESIDENT surface of an agent (C027) — its own routes whose `tier` is not `cold-tail` (the default-visible
+ * tool set). Cold-tail routes are revealed via `discover_tools`, never in the default list. This is the set a
+ * conforming serving adapter must trim to for the context-reduction claim to bind.
+ */
+export function residentSurface(doc: OpenAPIv4Document, agentName: string): string[] {
+  const a = agentMap(doc)[agentName];
+  return Object.entries(a?.routes ?? {}).filter(([, r]) => r.tier !== "cold-tail").map(([k]) => k).sort();
+}
+
+/**
+ * TIER-TRIM CONFORMANCE: the DEFAULT served tool set must contain NO cold-tail tool (those belong behind
+ * `discover_tools`). A cold-tail tool in the default list is a silent no-op of the tier label — the reduction the
+ * tiering thesis promises is not actually being delivered on the served path.
+ */
+export function assertDefaultServedResident(doc: OpenAPIv4Document, agentName: string, defaultServedToolNames: string[]): ConformanceFinding[] {
+  const resident = new Set(residentSurface(doc, agentName));
+  const a = agentMap(doc)[agentName];
+  const coldTail = new Set(Object.entries(a?.routes ?? {}).filter(([, r]) => r.tier === "cold-tail").map(([k]) => k));
+  return defaultServedToolNames
+    .filter((t) => coldTail.has(t) && !resident.has(t))
+    .map((t) => ({ code: "cold-tail-in-default", detail: `cold-tail tool "${t}" is in the DEFAULT served set — it must sit behind discover_tools, or the tier-trim (and its context reduction) is a no-op` }));
+}
+
+/**
+ * POLICY-AWARE OVER-SERVE (C028): when an operator policy governs the agent, the served tools must be a subset of
+ * the POST-POLICY effective surface — a served tool the operator DENIED is a conformance failure (the operator cap
+ * must hold on the wire). With no governing policy this is identical to {@link assertServedSubset}.
+ */
+export function assertServedSubsetGoverned(doc: OpenAPIv4Document, agentName: string, servedToolNames: string[]): ConformanceFinding[] {
+  if (policiesFor(doc, agentName).length === 0) return assertServedSubset(doc, agentName, servedToolNames);
+  const allowed = new Set(effectiveUnderPolicies(doc, agentName).effective.allowedTools);
+  const surface = new Set(reachableSurface(doc, agentName).tools);
+  return servedToolNames.flatMap((t) =>
+    !surface.has(t) ? [{ code: "over-serve", detail: `served tool "${t}" is NOT in the declared reachable surface` }]
+    : !allowed.has(t) ? [{ code: "policy-denied-served", detail: `served tool "${t}" was DENIED by operator policy but is being served — the operator cap is not holding on the wire` }]
+    : []);
+}
+
+/**
+ * SKILL-FRESHNESS: a skill's declared `provenance.contentHash` must match the hash of the CURRENT served snapshot.
+ * A mismatch means the served preprompt drifted after the contentHash was minted — an unsigned change in production
+ * (the C021 supply-chain concern). No declared hash ⇒ a warning (drift is undetectable).
+ */
+export function verifySkillFreshness(declaredHash: string | undefined, currentSnapshot: string): ConformanceFinding[] {
+  if (!declaredHash) return [{ code: "unpinned-skill", detail: "no declared contentHash — served-instruction drift cannot be detected" }];
+  const now = contentHash(currentSnapshot);
+  return declaredHash === now ? [] : [{ code: "stale-skill", detail: `declared contentHash ${declaredHash} ≠ current ${now} — the served instructions drifted` }];
+}

package/src/context.ts

@@ -0,0 +1,256 @@
+/**
+ * CONTEXT INTELLIGENCE (C027) — the agent layer's self-knowledge about its own context economics. No one engineers
+ * the perfect agent first try: you declare tools + agents, then MEASURE and let the analyzer right-size the layering.
+ * It answers three questions per agent, statically and honestly:
+ *
+ *  1. LOAD — how much context a single inference AT this agent must hold by default: resident skill instructions
+ *     (when a snapshot is supplied) + the resident tool surface (name+description+schema per tool, +1 dispatch tool
+ *     per sub-agent, +discover_tools when cold-tail exists) + framing overhead. Cold-tail tools and sub-agent
+ *     INTERNALS are NOT counted — that is the whole point of the tiering.
+ *  2. RIGHT-SIZING (the flatten/unflatten DUALITY) — too big (over budget/window, heavy resident surface) ⇒
+ *     UNFLATTEN (move tools to cold-tail / extract a sub-agent). Too small or redundant (a thin leaf, or a
+ *     passthrough that just delegates) ⇒ FLATTEN (collapse the layer up), because every layer COSTS a dispatch tool
+ *     + a fresh framing overhead per front-door hop — an unearned layer can cost more than one flat call.
+ *  3. MODEL FIT — which of an agent's DECLARED candidate models can actually hold its load, and the minimum context
+ *     window it needs. "Which models are expected to work with this agent" is then a computed, checkable fact.
+ *
+ * HONESTY: token counts are ESTIMATES (~4 chars/token, no real tokenizer) and instruction sizes are only known when
+ * a snapshot is supplied — every report says so. This sizes the SHAPE + the window need, not the bill, and it does
+ * NOT judge a model's REASONING capability (only whether the context fits) — the declared model[] is the author's
+ * capability intent; the analyzer validates window-fit against it.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import type { ModelCatalog } from "@suluk/models";
+import { agentMap, resolveOperationRef, subAgentKey } from "./resolve";
+import type { LintFinding, Severity } from "./lint";
+
+const CHARS_PER_TOKEN = 4;
+const estTokens = (s: string) => Math.ceil(s.length / CHARS_PER_TOKEN);
+const BASE_OVERHEAD = 400;          // function-calling framing / system scaffolding (paid once per inference hop)
+const SUBAGENT_DISPATCH = 60;       // one front-door dispatch tool per sub-agent (name + short desc)
+const DISCOVER_TOOLS = 60;          // the discover_tools meta-tool, present when cold-tail routes exist
+const OVERLOAD_TOOL_COUNT = 12;     // a flat agent with this many resident tools is an unflatten candidate
+const OVERLOAD_FRACTION = 0.5;      // ...or whose resident tool surface eats this share of its target
+const FLATTEN_THIN_TOOLS = 3;       // a leaf sub-agent with <= this many resident tools is a flatten candidate
+
+/**
+ * A model's context window — read from the @suluk/models CATALOG (the council deleted the old hard-coded
+ * DEFAULT_WINDOWS table: we do not guess windows). Precedence: an explicit `opts.modelWindows` override, then the
+ * catalog row's `context.maxWindow`, else null (UNKNOWN — fail-closed in the hard min-context filter).
+ */
+function windowFor(id: string, opts: ContextOptions): number | null {
+  if (opts.modelWindows?.[id] !== undefined) return opts.modelWindows[id];
+  return opts.catalog?.rows.find((r) => r.id === id)?.context.maxWindow.value ?? null;
+}
+
+export interface ToolContextCost { name: string; tokens: number; tier: "resident" | "cold-tail" }
+/** Per declared candidate model: does its context window hold this agent's load? (window null ⇒ unknown model.) */
+export interface ModelFit { model: string; window: number | null; fits: boolean | null; headroom: number | null }
+export interface AgentContextLoad {
+  agent: string;
+  instructionsTokens: number;
+  instructionsMeasured: boolean;
+  residentToolTokens: number;
+  overheadTokens: number;
+  totalTokens: number;
+  coldTailTokens: number;
+  tools: ToolContextCost[];
+  subAgentCount: number;
+  /** the minimum context window a model needs to run this agent (= the multi-round PEAK load). */
+  minWindowRequired: number;
+  /** within-agent thinking cap (C029), if declared. */
+  maxRounds?: number;
+  thinkingBudget?: number;
+  /** worst-case load accounting for thinking round-accretion (= totalTokens when no thinking). Fit checks use THIS. */
+  peakTokens: number;
+  /** which DECLARED models are expected to work (window ≥ load) and which can't hold it. */
+  modelFit: ModelFit[];
+  budget?: number;
+  /** the smallest declared model window (the binding window constraint), if any model is known. */
+  modelWindow?: number;
+  target?: number;
+  utilization?: number;
+}
+
+export interface UnflattenSuggestion {
+  agent: string;
+  reason: string;
+  moveToColdTail: string[];
+  wouldSaveTokens: number;
+  alsoConsider: string;
+}
+
+/** The dual of unflatten: a thin/redundant layer worth collapsing UP into its parent. */
+export interface FlattenSuggestion {
+  parent: string;
+  child: string;
+  reason: string;
+  /** the parent's load if the child's resident tools+instructions were inlined. */
+  mergedParentTokens: number;
+  fitsTarget: boolean;
+  /** per-hop overhead removed by collapsing (the child's framing + its dispatch tool). */
+  savedHopOverhead: number;
+}
+
+export interface ContextReport {
+  loads: AgentContextLoad[];
+  findings: LintFinding[];
+  /** unflatten suggestions for over-target agents (split DOWN). */
+  suggestions: UnflattenSuggestion[];
+  /** flatten suggestions for thin/redundant layers (collapse UP). */
+  flatten: FlattenSuggestion[];
+}
+
+export interface ContextOptions {
+  instructions?: Record<string, string>;
+  /** the model catalog (@suluk/models) — context windows are read from it; replaces the old hard-coded table. */
+  catalog?: ModelCatalog;
+  /** per-id window overrides (takes precedence over the catalog); handy for tests/pins. */
+  modelWindows?: Record<string, number>;
+}
+
+function routeCost(doc: OpenAPIv4Document, name: string, operationRef: string, tier: "resident" | "cold-tail"): ToolContextCost {
+  const req = resolveOperationRef(doc, operationRef)?.request;
+  const desc = req?.summary ?? req?.description ?? "";
+  const schema = req?.contentSchema ?? req?.parameterSchema?.body ?? {};
+  const tokens = estTokens(name) + estTokens(desc) + estTokens(JSON.stringify(schema)) + 12 /* wrapper */;
+  return { name, tokens, tier };
+}
+
+/** Compute the context-intelligence report (load + right-sizing + model fit) for every agent in the document. */
+export function contextReport(doc: OpenAPIv4Document, opts: ContextOptions = {}): ContextReport {
+  const map = agentMap(doc);
+  const loads: AgentContextLoad[] = [];
+  const findings: LintFinding[] = [];
+  const suggestions: UnflattenSuggestion[] = [];
+  const add = (severity: Severity, code: string, agent: string, detail: string) => findings.push({ severity, code, agent, detail });
+
+  for (const [name, agent] of Object.entries(map)) {
+    const skillEntries = Object.entries(agent.skills ?? {});
+    const routeEntries = Object.entries(agent.routes ?? {});
+
+    let instructionsTokens = 0; let anyResidentSkill = false; let anyUnmeasured = false;
+    for (const [sk, s] of skillEntries) {
+      if (s.tier === "cold-tail") continue;
+      anyResidentSkill = true;
+      const snap = opts.instructions?.[`${name}/${sk}`];
+      if (snap !== undefined) instructionsTokens += estTokens(snap);
+      else anyUnmeasured = true;
+    }
+    const instructionsMeasured = anyResidentSkill ? !anyUnmeasured : true;
+
+    const tools = routeEntries.map(([rk, r]) => routeCost(doc, rk, r.operationRef, r.tier === "cold-tail" ? "cold-tail" : "resident"));
+    const residentTools = tools.filter((t) => t.tier === "resident");
+    const coldTailTools = tools.filter((t) => t.tier === "cold-tail");
+    const subAgentCount = Object.keys(agent.agents ?? {}).length;
+
+    const residentToolTokens = residentTools.reduce((n, t) => n + t.tokens, 0) + subAgentCount * SUBAGENT_DISPATCH + (coldTailTools.length ? DISCOVER_TOOLS : 0);
+    const coldTailTokens = coldTailTools.reduce((n, t) => n + t.tokens, 0);
+    const overheadTokens = BASE_OVERHEAD;
+    const totalTokens = instructionsTokens + residentToolTokens + overheadTokens;
+
+    // thinking round-accretion (C029): a multi-round agent's PEAK load exceeds the single-shot base. Estimate the
+    // accretion as the declared thinking budget, else each extra round re-accumulates ~the resident tool surface.
+    const maxRounds = agent.thinking?.maxRounds;
+    const thinkingBudget = agent.thinking?.budget?.tokens;
+    const accretion = agent.thinking ? (thinkingBudget ?? Math.max(0, (maxRounds ?? 1) - 1) * residentToolTokens) : 0;
+    const peakTokens = totalTokens + accretion;
+
+    // model fit: which declared (resident-skill) models can hold this load (the multi-round PEAK)
+    const candidateModels = [...new Set(skillEntries.filter(([, s]) => s.tier !== "cold-tail").flatMap(([, s]) => s.model ?? []))];
+    const modelFit: ModelFit[] = candidateModels.map((m) => {
+      const window = windowFor(m, opts);
+      return { model: m, window, fits: window === null ? null : peakTokens <= window, headroom: window === null ? null : window - peakTokens };
+    });
+    const withWindow = modelFit.filter((f) => f.window !== null);
+    const modelWindow = withWindow.length ? Math.min(...withWindow.map((f) => f.window!)) : undefined;
+
+    const budget = agent.contextBudget?.tokens;
+    const target = budget !== undefined && modelWindow !== undefined ? Math.min(budget, modelWindow) : budget ?? modelWindow;
+    const utilization = target ? peakTokens / target : undefined;
+
+    const load: AgentContextLoad = {
+      agent: name, instructionsTokens, instructionsMeasured, residentToolTokens, overheadTokens, totalTokens,
+      coldTailTokens, tools, subAgentCount, minWindowRequired: peakTokens, modelFit, peakTokens,
+      ...(maxRounds !== undefined ? { maxRounds } : {}), ...(thinkingBudget !== undefined ? { thinkingBudget } : {}),
+      ...(budget !== undefined ? { budget } : {}), ...(modelWindow !== undefined ? { modelWindow } : {}),
+      ...(target !== undefined ? { target } : {}), ...(utilization !== undefined ? { utilization } : {}),
+    };
+    loads.push(load);
+
+    // findings
+    if (skillEntries.length === 0 && routeEntries.length === 0)
+      add("info", "empty-layer", name, "agent declares no skills and no routes — a reserved layer to fill");
+    if (anyResidentSkill && anyUnmeasured)
+      add("info", "unmeasured-instructions", name, "no instruction snapshot supplied — totalTokens is a LOWER BOUND (tools+overhead only)");
+
+    // thinking round-accretion (C029): the multi-round peak, fixing the single-shot blindspot
+    if (agent.thinking && accretion > 0)
+      add("info", "thinking-context-growth", name, `thinking (maxRounds ${maxRounds ?? 1}) accretes ~${accretion} tok over the ${totalTokens}-tok single-shot base → peak ~${peakTokens}; fit checks use the peak`);
+
+    // model-fit findings (replaces a bare over-window check — names WHICH models work; basis = the PEAK)
+    const tooSmall = withWindow.filter((f) => !f.fits);
+    if (withWindow.length > 0 && tooSmall.length === withWindow.length)
+      add("error", "no-fitting-model", name, `estimated peak load ${peakTokens} tok exceeds EVERY declared model window (smallest ${modelWindow}) — unflatten${agent.thinking ? ", lower maxRounds," : ""} or declare a larger-context model`);
+    else if (tooSmall.length > 0)
+      add("warning", "model-too-small", name, `declared model(s) ${tooSmall.map((f) => f.model).join(", ")} cannot hold this agent (needs ≥${peakTokens} tok window) — they are listed but will not work`);
+
+    if (budget !== undefined && peakTokens > budget)
+      add("warning", "context-over-budget", name, `estimated peak load ${peakTokens} tok exceeds declared contextBudget ${budget}`);
+    const overloadByFraction = target !== undefined && residentToolTokens > OVERLOAD_FRACTION * target;
+    if (residentTools.length >= OVERLOAD_TOOL_COUNT || overloadByFraction)
+      add("warning", "flat-agent-overloaded", name, `resident surface is heavy (${residentTools.length} tools, ${residentToolTokens} tok) — candidate to unflatten (move tools to cold-tail or extract a sub-agent)`);
+
+    const s = suggestUnflatten(load);
+    if (s) suggestions.push(s);
+  }
+
+  // ── FLATTEN pass (the dual): a thin leaf reached by exactly one parent, whose merge still fits, is gratuitous ──
+  const loadBy = new Map(loads.map((l) => [l.agent, l]));
+  const refCount = new Map<string, number>();
+  for (const a of Object.values(map)) for (const r of Object.values(a.agents ?? {})) { const k = subAgentKey(r.ref); if (k) refCount.set(k, (refCount.get(k) ?? 0) + 1); }
+  const flatten: FlattenSuggestion[] = [];
+  for (const [pname, agent] of Object.entries(map)) {
+    const childKeys = Object.values(agent.agents ?? {}).map((r) => subAgentKey(r.ref)).filter((k): k is string => !!k && !!map[k]);
+    const ownRoutes = Object.keys(agent.routes ?? {}).length;
+    const ownResidentSkills = Object.values(agent.skills ?? {}).filter((s) => s.tier !== "cold-tail").length;
+    if (ownRoutes === 0 && ownResidentSkills === 0 && childKeys.length === 1)
+      add("warning", "passthrough-agent", pname, `delegates to "${childKeys[0]}" with no own tools or resident instructions — pure indirection; collapse the two`);
+    for (const ck of childKeys) {
+      const child = map[ck];
+      const childIsLeaf = Object.keys(child.agents ?? {}).length === 0;
+      if (!childIsLeaf || (refCount.get(ck) ?? 0) !== 1) continue; // only a leaf reached by exactly one parent
+      const pl = loadBy.get(pname)!; const cl = loadBy.get(ck)!;
+      const inlinedTools = cl.tools.filter((t) => t.tier === "resident").reduce((n, t) => n + t.tokens, 0);
+      const childResidentToolCount = cl.tools.filter((t) => t.tier === "resident").length;
+      const merged = pl.totalTokens - SUBAGENT_DISPATCH + inlinedTools + cl.instructionsTokens;
+      const fitsTarget = pl.target === undefined || merged <= pl.target;
+      if (childResidentToolCount <= FLATTEN_THIN_TOOLS && fitsTarget) {
+        flatten.push({ parent: pname, child: ck, reason: `thin leaf (${childResidentToolCount} resident tool(s)); merged load ${merged}${pl.target !== undefined ? ` ≤ target ${pl.target}` : " (no target)"}`, mergedParentTokens: merged, fitsTarget, savedHopOverhead: BASE_OVERHEAD + SUBAGENT_DISPATCH });
+        add("info", "flattenable-layer", pname, `sub-agent "${ck}" is a thin leaf that merges within budget — the layer costs ~${BASE_OVERHEAD + SUBAGENT_DISPATCH} tok/hop it does not earn; consider flattening`);
+      }
+    }
+  }
+
+  return { loads, findings, suggestions, flatten };
+}
+
+/** When an agent is over its target, the cheapest decomposition: which resident tools to push to cold-tail. */
+export function suggestUnflatten(load: AgentContextLoad, target = load.target): UnflattenSuggestion | null {
+  if (target === undefined || load.peakTokens <= target) return null;
+  const resident = load.tools.filter((t) => t.tier === "resident").sort((a, b) => b.tokens - a.tokens);
+  const move: string[] = []; let saved = 0;
+  for (const t of resident) {
+    if (load.peakTokens - saved <= target) break;
+    move.push(t.name); saved += t.tokens;
+  }
+  return {
+    agent: load.agent,
+    reason: `peak load ${load.peakTokens} tok over target ${target} (${Math.round((load.utilization ?? 0) * 100)}%)`,
+    moveToColdTail: move,
+    wouldSaveTokens: saved,
+    alsoConsider: move.length >= 3
+      ? `${move.length} tools cluster here — consider extracting them into a sub-agent (front-door re-entry keeps them out of this agent's context entirely)`
+      : "move these tools to cold-tail (tier: cold-tail) so they sit behind discover_tools",
+  };
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @suluk/agents — the Suluk Agent composition layer (C027). Lint + project an `x-suluk-agents` map (skills +
+ * deterministic routes + by-name sub-agents) into a Claude plugin AND an OpenRouter/OpenAI-compatible manifest:
+ * one contract, two artifacts, zero network at generate time. This package is the OTHER side of the D1 wall —
+ * it reads `x-suluk-agents`, which @suluk/core's matcher (buildAda/matchRequest) provably never does. Selection
+ * and tiering are runtime-advisory; determinism is DECLARED, never enforced. CANDIDATE tooling — NOT official OAS.
+ *
+ * NB (the C027 module-boundary invariant): @suluk/core MUST NEVER import @suluk/agents. The dependency is one-way.
+ * test/core-boundary.test.ts enforces it as a maintained tripwire.
+ */
+export { lintAgents, lintOk, assertAgentInstallable, type LintFinding, type Severity } from "./lint";
+export {
+  parsePointer, resolveOperationRef, agentMap, subAgentKey, childKeys, findCycle, subtreeDepth, deepStrings,
+  type OperationLocus, type ResolvedOperation,
+} from "./resolve";
+export { contentHash, renderSkillMd, type SkillRenderInput } from "./skill";
+export {
+  projectClaudePlugin, projectOpenRouter,
+  type ClaudePluginOptions, type ClaudePluginArtifacts,
+  type OpenRouterOptions, type OpenRouterAgentManifest, type OpenRouterFunctionTool,
+} from "./project";
+export { reachableSurface, residentSurface, assertServedSubset, assertServedSubsetGoverned, assertDefaultServedResident, verifySkillFreshness, type ConformanceFinding } from "./conformance";
+export { intersectScope, analyzeScopes, localEscalations, type Scope, type ScopeEscalation } from "./scope";
+export {
+  agentManifest, verifyAgentFreshness,
+  type AgentManifest, type AgentManifestNode, type AgentManifestSkill, type AgentManifestRoute, type AgentManifestGoverned,
+} from "./manifest";
+// policy (C028): the operator governance overlay — monotone-narrowing MEET + the static lints. costCeiling is
+// DECLARED, never schema-enforced (enforcedBy names a runtime adapter); enforcement is reserved (build-by-nobody).
+export {
+  policyConstrain, effectiveUnderPolicies, policiesFor, policyAppliesTo, lintPolicy, policyOk,
+  type EffectiveAgent, type EffectiveSkill, type PolicyNarrowing, type PolicyConstrainResult,
+} from "./policy";
+// context budget (C027): estimate each agent's default context load (resident instructions + tool surface) vs its
+// budget + smallest model window, and say what to unflatten when overloaded. Estimates, not a tokenizer.
+export {
+  contextReport, suggestUnflatten,
+  type ContextReport, type AgentContextLoad, type UnflattenSuggestion, type FlattenSuggestion,
+  type ModelFit, type ToolContextCost, type ContextOptions,
+} 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 { selectModel, deriveRequirements, SEED_CATALOG, PROFILES, type ModelCatalog, type SelectResult, type Preferences, type HardFilters } from "@suluk/models";

package/src/lint.ts

@@ -0,0 +1,118 @@
+/**
+ * The C027 agent linter — the BLOCKING author/install gate the council made a red-line. It enforces what
+ * JSON-Schema cannot, and (crucially) the D1 selector-rejection: NO agent field may carry a request-value
+ * runtime-expression, so the matcher can never be pressured into reading an agent field (the #20 tripwire,
+ * declined by removal-by-design). Lint is the only place determinism/acyclicity/depth are checked — never the
+ * runtime matcher.
+ */
+import type { OpenAPIv4Document, SulukAgent } from "@suluk/core";
+import { agentMap, childKeys, deepStrings, findCycle, resolveOperationRef, subtreeDepth } from "./resolve";
+import { localEscalations } from "./scope";
+
+export type Severity = "error" | "warning" | "info";
+export interface LintFinding {
+  severity: Severity;
+  /** machine code, e.g. "agent-cycle", "missing-max-depth", "dangling-operation-ref", "request-value-selector". */
+  code: string;
+  agent: string;
+  detail: string;
+  /** dotted locus within the agent, e.g. "routes.run_core_primitive.operationRef". */
+  at?: string;
+}
+
+/** A C018-style runtime expression — a request-value selector. Forbidden ANYWHERE in an agent (D1). */
+const RUNTIME_EXPR = /\{\s*\$(request|response|method|url|statusCode|inputs)\b/i;
+
+/** Fields whose presence-as-a-router would smuggle dynamic dispatch into the static contract (defense in depth). */
+const FORBIDDEN_SELECTOR_KEYS = new Set(["selector", "strategy", "discriminator", "routeWhen", "dispatchOn"]);
+
+export function lintAgents(doc: OpenAPIv4Document): LintFinding[] {
+  const map = agentMap(doc);
+  const out: LintFinding[] = [];
+  const add = (severity: Severity, code: string, agent: string, detail: string, at?: string) =>
+    out.push({ severity, code, agent, detail, at });
+
+  for (const [name, agent] of Object.entries(map)) {
+    // --- description: required, routing-oriented (the field the serving LLM selects on) ---
+    const desc = (agent.description ?? "").trim();
+    if (!desc) add("error", "empty-description", name, "an agent description is required and routing-oriented");
+    else if (!desc.includes(" ")) add("warning", "thin-description", name, `one-word description "${desc}" — the serving LLM will mis-route`);
+
+    // --- D1 GATE: no request-value selector anywhere in the agent object ---
+    for (const { path, value } of deepStrings(agent)) {
+      if (RUNTIME_EXPR.test(value))
+        add("error", "request-value-selector", name, `D1: a request-value runtime-expression is forbidden in an agent ("${value}")`, path);
+    }
+    for (const { path } of deepStrings(agent)) {
+      const leaf = path.split(".").pop() ?? "";
+      if (FORBIDDEN_SELECTOR_KEYS.has(leaf))
+        add("error", "request-value-selector", name, `D1: field "${leaf}" would route on request data — inadmissible`, path);
+    }
+
+    // --- routes: by-name $refs into EXISTING operations; NO model; resolve-lint ---
+    for (const [rk, route] of Object.entries(agent.routes ?? {})) {
+      if ((route as unknown as Record<string, unknown>).model !== undefined)
+        add("error", "route-has-model", name, `route "${rk}" carries a model — a route is deterministic (no model); make it a skill`, `routes.${rk}`);
+      if (!route.operationRef)
+        add("error", "missing-operation-ref", name, `route "${rk}" has no operationRef`, `routes.${rk}`);
+      else if (!resolveOperationRef(doc, route.operationRef))
+        add("error", "dangling-operation-ref", name, `route "${rk}" operationRef does not resolve to an existing operation: ${route.operationRef}`, `routes.${rk}.operationRef`);
+    }
+
+    // --- skills: a skill is the LLM tier (model present); provenance should pin the source ---
+    for (const [sk, skill] of Object.entries(agent.skills ?? {})) {
+      if (!skill.model || skill.model.length === 0)
+        add("warning", "skill-without-model", name, `skill "${sk}" has no model — a no-model unit is a route, not a skill`, `skills.${sk}`);
+      if (skill.provenance && !skill.provenance.contentHash)
+        add("warning", "skill-provenance-unpinned", name, `skill "${sk}" provenance lacks a contentHash — drift cannot be detected`, `skills.${sk}.provenance`);
+    }
+
+    // --- sub-agents: by-name refs must resolve; recursion needs a bound; no cycles ---
+    const children = childKeys(agent);
+    for (const c of children) {
+      if (!c.key) add("error", "malformed-subagent-ref", name, `sub-agent "${c.local}" ref is not a #/x-suluk-agents/<key> pointer: ${c.ref}`, `agents.${c.local}`);
+      else if (!map[c.key]) add("error", "dangling-subagent-ref", name, `sub-agent "${c.local}" refs a missing agent: ${c.key}`, `agents.${c.local}`);
+    }
+
+    // --- scope: a child may not DECLARE a permission its caller does not grant (no escalation across a hop; D1-of-authz) ---
+    for (const esc of localEscalations(doc, name)) {
+      add("error", "scope-escalation", name, `sub-agent "${esc.childLocal}" (${esc.child}) declares scope its caller does not grant: ${esc.perms.join(", ")} — a child's effective scope is INTERSECTION(child, caller), never union`, `agents.${esc.childLocal}`);
+    }
+
+    // --- thinking bound (C029): maxRounds REQUIRED + positive when `thinking` present; no loop-process / stopCondition ---
+    if (agent.thinking) {
+      const mr = agent.thinking.maxRounds;
+      if (mr === undefined) add("error", "missing-max-rounds", name, "thinking present but no maxRounds — a thinking envelope MUST declare its round cap (mirrors maxDepth-required-when-agents)", "thinking");
+      else if (!(typeof mr === "number" && mr >= 1 && Number.isInteger(mr))) add("error", "invalid-max-rounds", name, `maxRounds must be an integer >= 1 (got ${mr})`, "thinking.maxRounds");
+      // any stopCondition-shaped member is forbidden — the loop trajectory stays runtime-opaque (declare the bound, not the process)
+      for (const k of Object.keys(agent.thinking as Record<string, unknown>))
+        if (/^(stopCondition|stopConditionKind|steps?|loop|process|until|while)$/i.test(k))
+          add("error", "thinking-process-declared", name, `thinking.${k} models the loop PROCESS — forbidden (declare the bound maxRounds/budget, never the trajectory; it stays runtime-opaque)`, `thinking.${k}`);
+    }
+    if (children.length > 0) {
+      const cycle = findCycle(map, name);
+      if (cycle) add("error", "agent-cycle", name, `recursion cycle: ${cycle.join(" → ")}`);
+      if (agent.maxDepth === undefined)
+        add("error", "missing-max-depth", name, "an agent with sub-agents MUST declare maxDepth (no bound ⇒ does not install)");
+      else if (!cycle) {
+        const depth = subtreeDepth(map, name);
+        if (depth > agent.maxDepth)
+          add("error", "depth-exceeds-max", name, `reachable sub-agent depth ${depth} exceeds declared maxDepth ${agent.maxDepth}`);
+      }
+    }
+  }
+  return out;
+}
+
+/** True ⇒ no error-severity findings (warnings/info are advisory). */
+export const lintOk = (findings: LintFinding[]): boolean => !findings.some((f) => f.severity === "error");
+
+/** Convenience: lint a single agent's existence + errors, throwing the first error (for fail-loud projection). */
+export function assertAgentInstallable(doc: OpenAPIv4Document, agentName: string): void {
+  if (!agentMap(doc)[agentName]) throw new Error(`@suluk/agents: no agent "${agentName}" in x-suluk-agents`);
+  const errs = lintAgents(doc).filter((f) => f.severity === "error" && f.agent === agentName);
+  if (errs.length) throw new Error(`@suluk/agents: agent "${agentName}" does not install:\n  - ${errs.map((e) => `${e.code}: ${e.detail}`).join("\n  - ")}`);
+}
+
+// re-export the agent type for consumers that only import the linter
+export type { SulukAgent };