@suluk/agents 0.1.0

package/src/manifest.ts

@@ -0,0 +1,141 @@
+/**
+ * The signable AGENT MANIFEST (C027 marketplace reuse, C021) — a deterministic, canonical descriptor of an agent
+ * and its reachable sub-tree, suitable for distribution through the signed marketplace. It deliberately INCLUDES
+ * every skill's `contentHash`, so signing the manifest (with @suluk/builder's `signRegistry`) covers the served
+ * preprompt: a preprompt that drifts AFTER the signature is minted is a detectable unsigned change — `verifyAgentFreshness`
+ * catches it (the C021 supply-chain concern, council open-Q #8). It also carries the effective (intersection) scope of
+ * every node + any escalations, so worst-case authz reach is auditable from the signed artifact alone.
+ *
+ * Pure + crypto-free: the signing/verifying lives in @suluk/builder; this package only produces what gets signed.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import type { ModelCatalog } from "@suluk/models";
+import { agentMap } from "./resolve";
+import { reachableSurface, type ConformanceFinding } from "./conformance";
+import { analyzeScopes, type Scope, type ScopeEscalation } from "./scope";
+import { effectiveUnderPolicies, policiesFor } from "./policy";
+import { contextReport } from "./context";
+import { skillModels } from "./model-select";
+import { contentHash } from "./skill";
+
+export interface AgentManifestSkill {
+  name: string;
+  model: string[];
+  tier?: "resident" | "cold-tail";
+  source?: string;
+  /** the pinned hash of the served instructions — what the signature ends up covering. */
+  contentHash?: string;
+  version?: string;
+}
+export interface AgentManifestRoute {
+  name: string;
+  operationRef: string;
+  guarantee?: "same-in-same-out" | "idempotent" | "safe";
+}
+/** The operator-effective surface after x-suluk-policy narrowing (present only when a policy governs the agent). */
+export interface AgentManifestGoverned {
+  scope: Scope;
+  maxDepth?: number;
+  nestingForbidden: boolean;
+  allowedTools: string[];
+  deniedTools: string[];
+  allowedSubAgents: string[];
+}
+export interface AgentManifestNode {
+  name: string;
+  description: string;
+  /** effective scope after intersection along the reaching path (null = unconstrained). */
+  effectiveScope: Scope;
+  skills: AgentManifestSkill[];
+  routes: AgentManifestRoute[];
+  subAgents: string[];
+  /** 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 }[];
+}
+export interface AgentManifest {
+  manifestVersion: 1;
+  agent: string;
+  /** the root + every transitively-reachable sub-agent, sorted by name (canonical). */
+  nodes: AgentManifestNode[];
+  /** the statically-enumerable worst-case reachable surface. */
+  reachable: { tools: string[]; agents: string[] };
+  /** any per-edge scope escalations (an installable agent has none). */
+  escalations: ScopeEscalation[];
+}
+
+const byName = <T extends { name: string }>(xs: T[]) => [...xs].sort((a, b) => a.name.localeCompare(b.name));
+
+/** Build the canonical, signable manifest for an agent and its reachable sub-tree. Pure; does not throw. */
+export function agentManifest(doc: OpenAPIv4Document, agentName: string, opts: { catalog?: ModelCatalog } = {}): AgentManifest {
+  const map = agentMap(doc);
+  const { effective, escalations } = analyzeScopes(doc, agentName);
+  const reach = reachableSurface(doc, agentName);
+  const nodeKeys = [agentName, ...reach.agents].filter((k) => map[k]).sort((a, b) => a.localeCompare(b));
+  // per-agent peak load → the hard min-context gate, when a catalog is supplied (drives the model selection fold)
+  const minWinByAgent: Record<string, number> = {};
+  if (opts.catalog) for (const l of contextReport(doc, { catalog: opts.catalog }).loads) minWinByAgent[l.agent] = l.minWindowRequired;
+
+  const nodes: AgentManifestNode[] = nodeKeys.map((key) => {
+    const a = map[key];
+    const skills: AgentManifestSkill[] = byName(
+      Object.entries(a.skills ?? {}).map(([name, s]) => ({
+        name,
+        model: s.model ?? [],
+        ...(s.tier ? { tier: s.tier } : {}),
+        ...(s.provenance?.source ? { source: s.provenance.source } : {}),
+        ...(s.provenance?.contentHash ? { contentHash: s.provenance.contentHash } : {}),
+        ...(s.provenance?.version ? { version: s.provenance.version } : {}),
+      })),
+    );
+    const routes: AgentManifestRoute[] = byName(
+      Object.entries(a.routes ?? {}).map(([name, r]) => ({ name, operationRef: r.operationRef, ...(r.guarantee ? { guarantee: r.guarantee } : {}) })),
+    );
+    const subAgents = Object.values(a.agents ?? {}).map((r) => r.ref).sort();
+    let governed: AgentManifestGoverned | undefined;
+    if (policiesFor(doc, key).length > 0) {
+      const e = effectiveUnderPolicies(doc, key).effective;
+      governed = {
+        scope: e.scope,
+        ...(e.maxDepth !== undefined ? { maxDepth: e.maxDepth } : {}),
+        nestingForbidden: e.nestingForbidden,
+        allowedTools: [...e.allowedTools].sort(),
+        deniedTools: [...e.deniedTools].sort(),
+        allowedSubAgents: [...e.allowedSubAgents].sort(),
+      };
+    }
+    let modelSelection: AgentManifestNode["modelSelection"];
+    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 { name: key, description: a.description, effectiveScope: effective[key] ?? null, skills, routes, subAgents, ...(governed ? { governed } : {}), ...(modelSelection ? { modelSelection } : {}) };
+  });
+
+  return { manifestVersion: 1, agent: agentName, nodes, reachable: reach, escalations };
+}
+
+/**
+ * Verify a signed manifest's skills against the CURRENT served snapshots: each skill's signed `contentHash` must
+ * equal the hash of its current snapshot. A mismatch ⇒ the served preprompt drifted after the signature was minted
+ * (a stale/unsigned change). A skill with no declared `contentHash` ⇒ unpinned (drift undetectable). Snapshots are
+ * keyed `"<agentKey>/<skillName>"`; a skill with no provided snapshot is skipped (cannot be checked here).
+ */
+export function verifyAgentFreshness(manifest: AgentManifest, snapshots: Record<string, string>): ConformanceFinding[] {
+  const out: ConformanceFinding[] = [];
+  for (const node of manifest.nodes) {
+    for (const skill of node.skills) {
+      const key = `${node.name}/${skill.name}`;
+      if (!skill.contentHash) { out.push({ code: "unpinned-skill", detail: `${key}: no contentHash — drift undetectable` }); continue; }
+      const snap = snapshots[key];
+      if (snap === undefined) continue;
+      const now = contentHash(snap);
+      if (now !== skill.contentHash) out.push({ code: "stale-skill", detail: `${key}: signed contentHash ${skill.contentHash} ≠ current ${now} — served instructions drifted after mint` });
+    }
+  }
+  return out;
+}

package/src/model-select.ts

@@ -0,0 +1,54 @@
+/**
+ * The MODEL-SELECTION seam (C027 × @suluk/models) — a skill declares NEEDS, not a frozen model id, and the catalog
+ * picks the best CURRENT model. Requirements are DERIVED from the agent structure (tool-bearing ⇒ needs tool-calling)
+ * + the context analyzer's `minWindowRequired` (the agent's multi-round peak load becomes the hard min-context gate)
+ * + the skill's explicit `modelRequire` + the C028 `modelAllowlist` MEET across governing policies. Preferences come
+ * 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 { agentMap } from "./resolve";
+import { policiesFor } from "./policy";
+
+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). */
+  snapshotHash: string | null;
+}
+
+/** The C028 modelAllowlist MEET across every policy governing this agent (intersection of the present allowlists). */
+function effectiveAllowlist(doc: OpenAPIv4Document, agentName: string): string[] | undefined {
+  const lists = policiesFor(doc, agentName).map((p) => p.modelAllowlist).filter((a): a is string[] => Array.isArray(a) && a.length > 0);
+  if (!lists.length) return undefined;
+  return lists.reduce((acc, a) => acc.filter((x) => a.includes(x)));
+}
+
+/** Run the catalog selector for a skill from its declared NEEDS + the analyzer load. */
+export function resolveSkillModels(doc: OpenAPIv4Document, agentName: string, skillName: string, catalog: ModelCatalog, minWindowRequired?: number): SelectResult {
+  const agent = agentMap(doc)[agentName];
+  const skill = agent?.skills?.[skillName];
+  const allowlist = effectiveAllowlist(doc, agentName);
+  const minWin = Math.max(minWindowRequired ?? 0, skill?.modelRequire?.minContext ?? 0);
+  const reqs = deriveRequirements({
+    minWindowRequired: minWin > 0 ? minWin : undefined,
+    hasRoutes: Object.keys(agent?.routes ?? {}).length > 0,
+    needsStructured: skill?.modelRequire?.needsStructured,
+    inputModalities: skill?.modelRequire?.inputModalities,
+    policy: allowlist ? { modelAllowlist: allowlist } : undefined,
+  });
+  const prefs: Preferences = { profile: skill?.modelProfile, prefer: skill?.modelPrefer };
+  return selectModel(reqs, prefs, catalog);
+}
+
+/** The public seam: the models for a skill — its DECLARED list (opt-out) or the catalog-SELECTED ranked ids. */
+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 };
+}

package/src/policy.ts

@@ -0,0 +1,210 @@
+/**
+ * Operator governance overlay (C028) — `x-suluk-policy`. An OPERATOR-owned policy NARROWS what an agent
+ * self-declares: effective = INTERSECT(operatorPolicy, agentSelfDeclaration), a total, order-independent MEET that
+ * NEVER EXCEEDS either input on any axis (scope/tier/model/depth/tools/sub-agents). This is the security floor —
+ * monotone-narrowing-only; a widening result is a lint HARD-FAIL, not a precedence tiebreak.
+ *
+ * SCOPE OF THIS MODULE: the statically-decidable subset only. The `costCeiling` is DECLARED here (the operator's
+ * third number, cap/estimate/actual) but the schema cannot ENFORCE it — `enforcedBy` names a runtime adapter, and a
+ * cap-breaching run is a NAMED conformance failure, never silently honored. The terminate-at-spend kill-switch is
+ * RESERVED, built-by-nobody until the reopen-trigger (C028).
+ */
+import type { OpenAPIv4Document, SulukAgent, SulukPolicy } from "@suluk/core";
+import { agentMap, deepStrings, parsePointer } from "./resolve";
+import { intersectScope, type Scope } from "./scope";
+import type { LintFinding, Severity } from "./lint";
+
+const TIER_RANK = { resident: 0, "cold-tail": 1 } as const;
+type Tier = keyof typeof TIER_RANK;
+
+/** deny/allow membership: an `allow` list (when present) is the ONLY permitted set; `deny` removes further. */
+const passes = (key: string, f?: { deny?: string[]; allow?: string[] }): boolean => {
+  if (!f) return true;
+  if (f.allow && !f.allow.includes(key)) return false;
+  if (f.deny && f.deny.includes(key)) return false;
+  return true;
+};
+
+export interface EffectiveSkill {
+  name: string;
+  /** INTERSECT(skill.model, policy.modelAllowlist). */
+  model: string[];
+  tier?: Tier;
+  /** false ⇒ model ∩ allowlist = ∅: the operator's allowlist leaves this skill no model to run. */
+  usable: boolean;
+}
+export interface EffectiveAgent {
+  agent: string;
+  /** INTERSECT(agent.scope, policy.scopeAllowlist). */
+  scope: Scope;
+  maxDepth?: number;
+  nestingForbidden: boolean;
+  skills: EffectiveSkill[];
+  allowedTools: string[];
+  deniedTools: string[];
+  allowedSubAgents: string[];
+  deniedSubAgents: string[];
+}
+export interface PolicyNarrowing {
+  axis: "scope" | "tier" | "model" | "maxDepth" | "tools" | "retrievalTools" | "subAgents" | "nesting";
+  detail: string;
+}
+export interface PolicyConstrainResult {
+  effective: EffectiveAgent;
+  narrowings: PolicyNarrowing[];
+}
+
+/** Does this policy govern `agentKey`? (empty/absent appliesTo ⇒ all agents.) */
+export function policyAppliesTo(policy: SulukPolicy, agentKey: string): boolean {
+  const refs = policy.appliesTo;
+  if (!refs || refs.length === 0) return true;
+  return refs.some((r) => { const t = parsePointer(r); return t && t.length === 2 && t[0] === "x-suluk-agents" && t[1] === agentKey; });
+}
+
+/** All policies in the document that govern `agentKey`. */
+export function policiesFor(doc: OpenAPIv4Document, agentKey: string): SulukPolicy[] {
+  return Object.values(doc["x-suluk-policy"] ?? {}).filter((p) => policyAppliesTo(p, agentKey));
+}
+
+/** Apply ONE operator policy to an agent — a monotone MEET. Returns the narrowed envelope + an audit of every cut. */
+export function policyConstrain(agentName: string, agent: SulukAgent, policy: SulukPolicy): PolicyConstrainResult {
+  const narrowings: PolicyNarrowing[] = [];
+  const note = (axis: PolicyNarrowing["axis"], detail: string) => narrowings.push({ axis, detail });
+
+  // scope: INTERSECT(agent.scope, scopeAllowlist)
+  const declaredScope: Scope = agent.scope ?? null;
+  const scope = intersectScope(declaredScope, policy.scopeAllowlist ?? null);
+  if (declaredScope && scope && scope.length < declaredScope.length)
+    note("scope", `scope narrowed ${declaredScope.length}→${scope.length} (removed ${declaredScope.filter((s) => !scope.includes(s)).join(", ")})`);
+
+  // tier + model per skill
+  const skills: EffectiveSkill[] = Object.entries(agent.skills ?? {}).map(([name, s]) => {
+    let tier = s.tier as Tier | undefined;
+    if (policy.capTier && tier && TIER_RANK[tier] > TIER_RANK[policy.capTier]) { note("tier", `skill "${name}" tier ${tier}→${policy.capTier} (capped)`); tier = policy.capTier; }
+    let model = s.model ?? [];
+    if (policy.modelAllowlist) {
+      const before = model.length;
+      model = model.filter((m) => policy.modelAllowlist!.includes(m));
+      if (model.length < before) note("model", `skill "${name}" models ${before}→${model.length} (modelAllowlist)`);
+    }
+    return { name, model, ...(tier ? { tier } : {}), usable: !policy.modelAllowlist || model.length > 0 };
+  });
+
+  // tools (routes); retrievalTools is an ADDITIONAL filter on an untrusted tier
+  const isUntrusted = agent.trustBoundary === "untrusted";
+  const allowedTools: string[] = [], deniedTools: string[] = [];
+  for (const rk of Object.keys(agent.routes ?? {})) {
+    const ok = passes(rk, policy.tools) && (isUntrusted ? passes(rk, policy.retrievalTools) : true);
+    (ok ? allowedTools : deniedTools).push(rk);
+  }
+  if (deniedTools.length) note(isUntrusted && policy.retrievalTools ? "retrievalTools" : "tools", `denied tools: ${deniedTools.join(", ")}`);
+
+  // sub-agents: deny/allow, and forbidNesting wipes them all
+  const nestingForbidden = !!policy.forbidNesting;
+  const allowedSubAgents: string[] = [], deniedSubAgents: string[] = [];
+  for (const local of Object.keys(agent.agents ?? {})) {
+    const ok = !nestingForbidden && passes(local, policy.agents);
+    (ok ? allowedSubAgents : deniedSubAgents).push(local);
+  }
+  if (nestingForbidden && Object.keys(agent.agents ?? {}).length) note("nesting", "forbidNesting ⇒ all sub-agents removed (effective maxDepth 0)");
+  else if (deniedSubAgents.length) note("subAgents", `denied sub-agents: ${deniedSubAgents.join(", ")}`);
+
+  // maxDepth: min(agent.maxDepth, maxDepthCap); forbidNesting ⇒ 0
+  let maxDepth = agent.maxDepth;
+  if (nestingForbidden) maxDepth = 0;
+  else if (policy.maxDepthCap !== undefined) {
+    const capped = Math.min(agent.maxDepth ?? policy.maxDepthCap, policy.maxDepthCap);
+    if (capped !== agent.maxDepth) note("maxDepth", `maxDepth ${agent.maxDepth ?? "∞"}→${capped} (maxDepthCap)`);
+    maxDepth = capped;
+  }
+
+  return {
+    effective: { agent: agentName, scope, ...(maxDepth !== undefined ? { maxDepth } : {}), nestingForbidden, skills, allowedTools, deniedTools, allowedSubAgents, deniedSubAgents },
+    narrowings,
+  };
+}
+
+/** Apply ALL governing policies to an agent (MEET is associative/commutative — compose left-to-right). */
+export function effectiveUnderPolicies(doc: OpenAPIv4Document, agentName: string): PolicyConstrainResult {
+  const agent = agentMap(doc)[agentName];
+  const policies = policiesFor(doc, agentName);
+  if (!agent || policies.length === 0) {
+    return { effective: { agent: agentName, scope: agent?.scope ?? null, ...(agent?.maxDepth !== undefined ? { maxDepth: agent.maxDepth } : {}), nestingForbidden: false, skills: Object.entries(agent?.skills ?? {}).map(([name, s]) => ({ name, model: s.model ?? [], ...(s.tier ? { tier: s.tier as Tier } : {}), usable: true })), allowedTools: Object.keys(agent?.routes ?? {}), deniedTools: [], allowedSubAgents: Object.keys(agent?.agents ?? {}), deniedSubAgents: [] }, narrowings: [] };
+  }
+  // fold: apply each policy in turn by intersecting its result with the running effective via a synthetic agent
+  let merged = policyConstrain(agentName, agent, policies[0]);
+  for (const p of policies.slice(1)) {
+    const next = policyConstrain(agentName, agent, p);
+    merged = {
+      effective: {
+        agent: agentName,
+        scope: intersectScope(merged.effective.scope, next.effective.scope),
+        ...(merged.effective.maxDepth !== undefined || next.effective.maxDepth !== undefined ? { maxDepth: Math.min(merged.effective.maxDepth ?? Infinity, next.effective.maxDepth ?? Infinity) } : {}),
+        nestingForbidden: merged.effective.nestingForbidden || next.effective.nestingForbidden,
+        skills: merged.effective.skills.map((s) => { const o = next.effective.skills.find((x) => x.name === s.name)!; return { name: s.name, model: s.model.filter((m) => o.model.includes(m)), ...(s.tier ? { tier: s.tier } : {}), usable: s.usable && o.usable }; }),
+        allowedTools: merged.effective.allowedTools.filter((t) => next.effective.allowedTools.includes(t)),
+        deniedTools: [...new Set([...merged.effective.deniedTools, ...next.effective.deniedTools])].sort(),
+        allowedSubAgents: merged.effective.allowedSubAgents.filter((a) => next.effective.allowedSubAgents.includes(a)),
+        deniedSubAgents: [...new Set([...merged.effective.deniedSubAgents, ...next.effective.deniedSubAgents])].sort(),
+      },
+      narrowings: [...merged.narrowings, ...next.narrowings],
+    };
+  }
+  return merged;
+}
+
+// ───────────────────────────── lint ─────────────────────────────
+
+const RUNTIME_EXPR = /\{\s*\$(request|response|method|url|statusCode|inputs)\b/i;
+const microUsd = (amount: number, unit: "micro-usd" | "cents" | "usd") => amount * (unit === "usd" ? 1_000_000 : unit === "cents" ? 10_000 : 1);
+
+/** Lint every operator policy: D1 selector-rejection, dangling appliesTo, unsatisfiability, widening, cap<estimate. */
+export function lintPolicy(doc: OpenAPIv4Document): LintFinding[] {
+  const out: LintFinding[] = [];
+  const map = agentMap(doc);
+  const add = (severity: Severity, code: string, agent: string, detail: string, at?: string) => out.push({ severity, code, agent, detail, at });
+
+  for (const [pname, policy] of Object.entries(doc["x-suluk-policy"] ?? {})) {
+    // D1: no request-value selector anywhere in a policy
+    for (const { path, value } of deepStrings(policy))
+      if (RUNTIME_EXPR.test(value)) add("error", "request-value-selector", pname, `D1: a request-value runtime-expression is forbidden in a policy ("${value}")`, path);
+
+    // appliesTo must bind by agent name (and resolve)
+    for (const ref of policy.appliesTo ?? []) {
+      const t = parsePointer(ref);
+      if (!t || t.length !== 2 || t[0] !== "x-suluk-agents") add("error", "policy-applies-malformed", pname, `appliesTo "${ref}" must be a #/x-suluk-agents/<key> ref (never a request predicate)`);
+      else if (!map[t[1]]) add("error", "policy-applies-dangling", pname, `appliesTo refs a missing agent: ${t[1]}`);
+    }
+
+    // per governed agent: unsatisfiability + monotone-narrowing guard + cap<estimate
+    for (const [aname, agent] of Object.entries(map)) {
+      if (!policyAppliesTo(policy, aname)) continue;
+      const { effective } = policyConstrain(aname, agent, policy);
+
+      for (const s of effective.skills)
+        if (!s.usable) add("error", "policy-unsatisfiable", pname, `modelAllowlist leaves skill "${s.name}" of agent "${aname}" no runnable model`, `${aname}.skills.${s.name}`);
+      if (Object.keys(agent.routes ?? {}).length > 0 && effective.allowedTools.length === 0)
+        add("error", "policy-unsatisfiable", pname, `policy denies EVERY tool of agent "${aname}" — the agent can do nothing`, aname);
+
+      // monotone guard (defensive — MEET cannot widen; a widening here is a bug)
+      if (effective.scope && agent.scope && effective.scope.some((s) => !agent.scope!.includes(s)))
+        add("error", "policy-widening", pname, `policy WIDENED agent "${aname}" scope — inadmissible (effective must INTERSECT, never grant)`, aname);
+
+      // cap-below-estimate cross-facet (pure static; warning — the operator under-budgeted vs the author's own number)
+      const cost = agent["x-suluk-cost"] as { estimateMicroUsd?: number; amount?: number } | undefined;
+      const est = cost?.estimateMicroUsd ?? cost?.amount;
+      if (policy.costCeiling && typeof est === "number") {
+        const cap = microUsd(policy.costCeiling.amount, policy.costCeiling.amountUnit);
+        if (cap < est) add("warning", "cap-below-estimate", pname, `costCeiling (${cap} µ$) is below agent "${aname}" own estimate (${est} µ$) — operator under-budgeted`, aname);
+      }
+    }
+
+    // honesty: enforcedBy is required by the type, but flag a costCeiling that omits a basis (ambiguous metering)
+    if (policy.costCeiling && !policy.costCeiling.basis)
+      add("warning", "cost-ceiling-no-basis", pname, "costCeiling has no `basis` — the metering window is ambiguous (declared, not enforced regardless)");
+  }
+  return out;
+}
+
+/** True ⇒ no error-severity policy findings. */
+export const policyOk = (findings: LintFinding[]): boolean => !findings.some((f) => f.severity === "error");

package/src/project.ts

@@ -0,0 +1,156 @@
+/**
+ * The TWIN PROJECTION (C027) — one `x-suluk-agents` declaration → a Claude plugin AND an OpenRouter/OpenAI-compatible
+ * manifest. Both are PURE FUNCTIONS of (doc, agentName, opts): zero network at generate time (instruction snapshots
+ * are inputs, contentHash-pinned), deterministic, and the map KEY is the stable wire-level tool/function id on both.
+ * No credentials ever enter an artifact (the .mcp.json OAuth token is acquired host-side; C020/C023 upheld).
+ * Projection refuses a non-installable agent (fail-loud) — so a dangling operationRef or a missing maxDepth does
+ * NOT silently emit a broken artifact.
+ */
+import type { OpenAPIv4Document, SchemaOrRef, SulukSkillRef } from "@suluk/core";
+import { agentMap, resolveOperationRef } from "./resolve";
+import { assertAgentInstallable } from "./lint";
+import { contentHash, renderSkillMd } from "./skill";
+
+const stable = (v: unknown) => JSON.stringify(v, null, 2);
+
+/** The first skill that declares a model — an agent's primary LLM tier (drives the model preference list). */
+function primarySkill(skills?: Record<string, SulukSkillRef>): [string, SulukSkillRef] | null {
+  for (const [k, s] of Object.entries(skills ?? {})) if (s.model && s.model.length) return [k, s];
+  const first = Object.entries(skills ?? {})[0];
+  return first ?? null;
+}
+
+// ───────────────────────────── Claude plugin projection ─────────────────────────────
+
+export interface ClaudePluginOptions {
+  /** the HTTP MCP endpoint the plugin connects to (e.g. https://host/mcp). */
+  mcpUrl: string;
+  version?: string;
+  displayName?: string;
+  homepage?: string;
+  keywords?: string[];
+  author?: { name: string; email?: string };
+  /** instruction snapshots per skill name (the pinned served content); a skill without one emits no SKILL.md. */
+  instructions?: Record<string, string>;
+}
+
+export interface ClaudePluginArtifacts {
+  /** path → content; e.g. "plugin.json", ".mcp.json", "skills/operate/SKILL.md". */
+  files: Record<string, string>;
+}
+
+export function projectClaudePlugin(doc: OpenAPIv4Document, agentName: string, opts: ClaudePluginOptions): ClaudePluginArtifacts {
+  assertAgentInstallable(doc, agentName);
+  const agent = agentMap(doc)[agentName];
+
+  const pluginJson = {
+    name: agentName,
+    ...(opts.displayName ? { displayName: opts.displayName } : {}),
+    description: agent.description,
+    version: opts.version ?? "0.1.0",
+    ...(opts.author ? { author: opts.author } : {}),
+    ...(opts.homepage ? { homepage: opts.homepage } : {}),
+    ...(opts.keywords ? { keywords: opts.keywords } : {}),
+    mcpServers: "./.mcp.json",
+  };
+
+  // HTTP MCP with host-side OAuth — NO token embedded (creds never cross the seam; C020/C023).
+  const mcpJson = { mcpServers: { [agentName]: { type: "http", url: opts.mcpUrl, oauth: {} } } };
+
+  const files: Record<string, string> = {
+    "plugin.json": stable(pluginJson),
+    ".mcp.json": stable(mcpJson),
+  };
+
+  for (const [sk, skill] of Object.entries(agent.skills ?? {})) {
+    const text = opts.instructions?.[sk];
+    if (text === undefined) continue; // no snapshot supplied → no generated SKILL.md (honest: we never invent text)
+    files[`skills/${sk}/SKILL.md`] = renderSkillMd({
+      name: sk,
+      description: skill.whenToUse ?? agent.description,
+      instructions: text,
+      source: skill.provenance?.source,
+      version: skill.provenance?.version,
+    });
+  }
+
+  return { files };
+}
+
+// ──────────────────────────── OpenRouter / OpenAI-compatible ────────────────────────────
+
+export interface OpenRouterFunctionTool {
+  type: "function";
+  function: { name: string; description: string; parameters: SchemaOrRef };
+}
+
+export interface OpenRouterAgentManifest {
+  name: string;
+  /** model preference list (cheap→capable) from the primary skill; the OpenRouter ids to try in order. */
+  model: string[];
+  tier?: "resident" | "cold-tail";
+  /** a POINTER to the served instructions + the pinned hash — never inlined creds, never the full text by default. */
+  instructions: { source?: string; contentHash?: string; version?: string };
+  /**
+   * The DEFAULT tool surface — RESIDENT routes only, plus a synthetic `discover_tools` when cold-tail routes exist.
+   * This is the tier-trim: the cheap/lower tier carries a SMALLER tool surface (the conditional context reduction).
+   */
+  tools: OpenRouterFunctionTool[];
+  /** COLD-TAIL routes — NOT in the default surface; revealed on demand via `discover_tools`. */
+  discoverable: OpenRouterFunctionTool[];
+  /** sub-agents → one front-door tool each (dispatched as a NEW completion at the child's tier). */
+  subAgents: { name: string; ref: string }[];
+}
+
+/** The synthetic meta-tool that reveals cold-tail tools — present in the default surface only when some exist. */
+const DISCOVER_TOOLS_FN: OpenRouterFunctionTool = {
+  type: "function",
+  function: {
+    name: "discover_tools",
+    description: "Reveal additional cold-tail tools for this agent on demand. They are kept OUT of the default tool list so the resident surface stays small — call this to widen it (reorder/lazy-load, never widen beyond the declared reachable set).",
+    parameters: { type: "object" },
+  },
+};
+
+export interface OpenRouterOptions {
+  /** instruction snapshots per skill name; when given for the primary skill, the manifest carries the computed hash. */
+  instructions?: Record<string, string>;
+}
+
+export function projectOpenRouter(doc: OpenAPIv4Document, agentName: string, opts: OpenRouterOptions = {}): OpenRouterAgentManifest {
+  assertAgentInstallable(doc, agentName);
+  const agent = agentMap(doc)[agentName];
+  const prim = primarySkill(agent.skills);
+  const [primName, primSkill] = prim ?? [undefined, undefined as SulukSkillRef | undefined];
+
+  const snapshot = primName ? opts.instructions?.[primName] : undefined;
+  const instructions = {
+    source: primSkill?.provenance?.source,
+    contentHash: snapshot !== undefined ? contentHash(snapshot) : primSkill?.provenance?.contentHash,
+    version: primSkill?.provenance?.version,
+  };
+
+  const built = Object.entries(agent.routes ?? {}).map(([rk, route]) => {
+    const req = resolveOperationRef(doc, route.operationRef)?.request; // installable ⇒ non-null
+    const parameters: SchemaOrRef = (req?.contentSchema ?? req?.parameterSchema?.body ?? { type: "object" }) as SchemaOrRef;
+    const description = req?.summary ?? req?.description ?? `route ${rk} (${route.guarantee ?? "declared"})`;
+    const fn: OpenRouterFunctionTool = { type: "function", function: { name: rk, description, parameters } };
+    return { tier: route.tier ?? "resident", fn };
+  });
+  const residentTools = built.filter((b) => b.tier !== "cold-tail").map((b) => b.fn);
+  const discoverable = built.filter((b) => b.tier === "cold-tail").map((b) => b.fn);
+  // the default surface is resident-only; expose `discover_tools` ONLY when there is something to discover
+  const tools = discoverable.length ? [...residentTools, DISCOVER_TOOLS_FN] : residentTools;
+
+  const subAgents = Object.entries(agent.agents ?? {}).map(([local, r]) => ({ name: local, ref: r.ref }));
+
+  return {
+    name: agentName,
+    model: primSkill?.model ?? [],
+    ...(primSkill?.tier ? { tier: primSkill.tier } : {}),
+    instructions,
+    tools,
+    discoverable,
+    subAgents,
+  };
+}