@openwop/openwop-conformance 1.1.1 → 1.2.0

package/src/lib/webhook-receiver.ts

@@ -0,0 +1,137 @@
+/**
+ * Reference webhook receiver for the conformance suite — implements
+ * the verification contract per `spec/v1/webhooks.md` §"Signature
+ * recipe" + §"Replay-attack resistance" so adversarial-input scenarios
+ * can verify that a properly-implemented receiver rejects the
+ * documented failure modes.
+ *
+ * Mirrors the SDK's verifyWebhookSignature helper (sdk/typescript/src/
+ * webhook-helpers.ts) but inlined here so the conformance suite stays
+ * dependency-free vs. the SDK. The two MUST produce identical
+ * outcomes for the same inputs.
+ *
+ * @see spec/v1/webhooks.md §"Signature recipe"
+ * @see sdk/typescript/src/webhook-helpers.ts (canonical SDK
+ *      implementation; this file is a conformance-suite mirror)
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export const DEFAULT_FRESHNESS_WINDOW_SECONDS = 300;
+
+export type WebhookRejectionReason =
+  | 'signature_mismatch'
+  | 'timestamp_expired'
+  | 'timestamp_too_far_in_future'
+  | 'malformed_signature_header'
+  | 'malformed_timestamp_header'
+  | 'wrong_algorithm'
+  | 'duplicate_signature';
+
+export type WebhookVerifyResult =
+  | { accepted: true }
+  | { accepted: false; reason: WebhookRejectionReason };
+
+export interface WebhookReceiverState {
+  /** Set of signature values the receiver has already accepted (anti-replay). */
+  acceptedSignatures: Set<string>;
+}
+
+export function createReceiverState(): WebhookReceiverState {
+  return { acceptedSignatures: new Set() };
+}
+
+export interface VerifyOptions {
+  /** Default 5 minutes per spec. Set 0 to disable freshness check. */
+  freshnessWindowSeconds?: number;
+  /** Override `now` (unix seconds) for deterministic tests. */
+  nowSeconds?: number;
+}
+
+/**
+ * Verify a single webhook delivery against the canonical recipe.
+ * Returns `{ accepted: true }` on success; `{ accepted: false, reason }`
+ * otherwise. Updates `state.acceptedSignatures` on acceptance for
+ * replay-attack detection on subsequent calls.
+ *
+ * Receivers MUST pass the **exact** request body bytes — parsed-and-
+ * reserialized JSON will fail verification.
+ */
+export function verifyWebhookDelivery(
+  secret: string,
+  signatureHeader: string,
+  algorithmHeader: string | undefined,
+  timestampHeader: string,
+  rawBody: string | Buffer,
+  state: WebhookReceiverState,
+  options: VerifyOptions = {},
+): WebhookVerifyResult {
+  // 1. Algorithm gating. Hosts MAY include an explicit
+  //    X-openwop-Signature-Algorithm header; receivers MUST refuse
+  //    anything other than `v1` per webhooks.md §"Signature algorithm
+  //    versioning". Absence is treated as the v1 default.
+  if (algorithmHeader !== undefined && algorithmHeader !== 'v1') {
+    return { accepted: false, reason: 'wrong_algorithm' };
+  }
+
+  // 2. Signature header parse.
+  if (!signatureHeader.startsWith('v1=')) {
+    return { accepted: false, reason: 'malformed_signature_header' };
+  }
+  const providedHex = signatureHeader.slice(3);
+  if (!/^[0-9a-f]+$/i.test(providedHex)) {
+    return { accepted: false, reason: 'malformed_signature_header' };
+  }
+
+  // 3. Anti-replay: receivers MUST refuse a signature value seen
+  //    before, even if the timestamp would otherwise be fresh
+  //    (defense-in-depth against an attacker resending a captured
+  //    delivery before the original's timestamp window expires).
+  if (state.acceptedSignatures.has(signatureHeader)) {
+    return { accepted: false, reason: 'duplicate_signature' };
+  }
+
+  // 4. Timestamp parse + freshness window.
+  const timestamp = Number(timestampHeader);
+  if (!Number.isInteger(timestamp) || timestamp <= 0) {
+    return { accepted: false, reason: 'malformed_timestamp_header' };
+  }
+  const window = options.freshnessWindowSeconds ?? DEFAULT_FRESHNESS_WINDOW_SECONDS;
+  if (window > 0) {
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const delta = now - timestamp;
+    if (delta > window) return { accepted: false, reason: 'timestamp_expired' };
+    if (delta < -window) return { accepted: false, reason: 'timestamp_too_far_in_future' };
+  }
+
+  // 5. HMAC recompute + constant-time compare.
+  const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+  const expectedHex = createHmac('sha256', secret).update(`${timestamp}.${bodyStr}`, 'utf8').digest('hex');
+  const providedBuf = Buffer.from(providedHex, 'hex');
+  const expectedBuf = Buffer.from(expectedHex, 'hex');
+  if (providedBuf.length !== expectedBuf.length || !timingSafeEqual(providedBuf, expectedBuf)) {
+    return { accepted: false, reason: 'signature_mismatch' };
+  }
+
+  // 6. Accept + record for replay detection.
+  state.acceptedSignatures.add(signatureHeader);
+  return { accepted: true };
+}
+
+/**
+ * Sign a payload the way the host would — useful for building
+ * adversarial-input fixtures in scenarios.
+ */
+export function signPayload(
+  secret: string,
+  timestamp: number,
+  rawBody: string | Buffer,
+): { signatureHeader: string; timestampHeader: string; algorithmHeader: 'v1' } {
+  const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+  const hex = createHmac('sha256', secret).update(`${timestamp}.${bodyStr}`, 'utf8').digest('hex');
+  return {
+    signatureHeader: `v1=${hex}`,
+    timestampHeader: String(timestamp),
+    algorithmHeader: 'v1',
+  };
+}

package/src/lib/workflow-chain-expansion.ts

@@ -0,0 +1,213 @@
+/**
+ * Workflow-chain pack expansion — reference implementation of the
+ * 9-step host-editor expansion semantics from
+ * `spec/v1/workflow-chain-packs.md` §"Expansion semantics (normative)".
+ *
+ * Pure function. Zero I/O, zero crypto. Hosts implementing chain
+ * expansion in their workflow editors MAY import this directly OR
+ * adapt the algorithm into their language of choice — the contract
+ * this code encodes is the spec, not the code itself.
+ *
+ * What this implements:
+ *   - Step 3: validate referenced typeIds resolve (delegated to caller via
+ *     `isTypeIdResolvable` predicate)
+ *   - Step 5: `{{params.<name>}}` literal substitution (recursive into
+ *     nested string fields inside `config` / `inputs`)
+ *   - Step 6: per-expansion node-id rewrite with a chainId-derived prefix
+ *     for collision-free splice into the parent workflow
+ *   - Step 8: capability propagation (chain.capabilities[] → every
+ *     expanded WorkflowNode.capabilities[])
+ *   - Edge endpoint rewriting (`from`/`to` ids that reference fragment
+ *     nodes get the same prefix)
+ *
+ * What this deliberately DOESN'T implement (host-specific concerns):
+ *   - Step 1: registry resolution (network/storage path is host-specific)
+ *   - Step 2: signature verification (use `node:crypto`'s Ed25519 path —
+ *     see workflow-chain-pack-signature-verification.test.ts)
+ *   - Step 4: parameter-form prompting (host-UI concern)
+ *   - Step 7: splice into parent workflow (host-editor concern; this
+ *     function returns the rewritten fragment ready to be appended)
+ *   - Step 9: persistence (host-storage concern)
+ *
+ * @see spec/v1/workflow-chain-packs.md §"Expansion semantics (normative)"
+ * @see RFCS/0013-workflow-chain-packs.md
+ */
+
+/** A workflow-chain entry as it appears in a pack manifest. */
+export interface WorkflowChain {
+  chainId: string;
+  version: string;
+  label: string;
+  description: string;
+  parameters: object;
+  dag: { nodes: ReadonlyArray<FragmentNode>; edges?: ReadonlyArray<FragmentEdge> };
+  outputs?: Record<string, { type: string; description: string }>;
+  capabilities?: ReadonlyArray<'streamable' | 'cacheable' | 'side-effectful' | 'mcp-exportable'>;
+}
+
+export interface FragmentNode {
+  id: string;
+  typeId: string;
+  name?: string;
+  position?: { x: number; y: number };
+  config?: Record<string, unknown>;
+  inputs?: Record<string, unknown>;
+}
+
+export interface FragmentEdge {
+  from: string;
+  to: string;
+  condition?: string;
+}
+
+/** Per-expansion context the caller supplies. */
+export interface ExpansionContext {
+  /** Caller-supplied unique tag for this expansion (e.g., 4-hex random).
+   *  Combined with the chainId slug to namespace expanded node ids so
+   *  the same chain can be expanded multiple times within one parent
+   *  workflow without id collisions. */
+  expansionId: string;
+  /** Author-supplied parameter values, ALREADY VALIDATED against the
+   *  chain's `parameters` JSON Schema. This function does NOT re-validate
+   *  — the caller MUST ajv-compile `chain.parameters` and reject invalid
+   *  input with `chain_parameter_invalid` BEFORE calling. */
+  params: Record<string, unknown>;
+  /** Predicate the caller supplies for typeId resolution (step 3). Should
+   *  return `true` if the typeId is registered with the destination host
+   *  (either reserved `core.*` or published via a known node pack). */
+  isTypeIdResolvable: (typeId: string) => boolean;
+}
+
+/** Result of expansion — ready to be spliced into a parent workflow's
+ *  `nodes[]` / `edges[]`. */
+export interface ExpandedFragment {
+  nodes: ReadonlyArray<{
+    id: string;
+    typeId: string;
+    name?: string;
+    position?: { x: number; y: number };
+    config?: Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    capabilities?: ReadonlyArray<string>;
+  }>;
+  edges: ReadonlyArray<{ from: string; to: string; condition?: string }>;
+  /** Map of original-fragment-id → rewritten-id, so the caller can
+   *  wire the parent workflow's adjacent edges into the expansion. */
+  idMap: ReadonlyMap<string, string>;
+}
+
+/** Thrown when expansion encounters a chain that references a typeId the
+ *  destination host can't resolve. Carries both the offending `typeId`
+ *  and the `chainId` for diagnostic reporting. The error message uses
+ *  the wire-level error code `chain_unresolvable_typeid` per
+ *  `workflow-chain-packs.md` §"Error codes". */
+export class ChainUnresolvableTypeIdError extends Error {
+  readonly code = 'chain_unresolvable_typeid';
+  constructor(readonly typeId: string, readonly chainId: string) {
+    super(`chain_unresolvable_typeid: '${typeId}' in chain '${chainId}'`);
+    this.name = 'ChainUnresolvableTypeIdError';
+  }
+}
+
+const PARAM_PATTERN = /\{\{params\.([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
+
+/** Recursive literal substitution of `{{params.<name>}}` placeholders in
+ *  any string field. Non-string values pass through unchanged; nested
+ *  arrays/objects are walked. */
+function substitute(value: unknown, params: Record<string, unknown>): unknown {
+  if (typeof value === 'string') {
+    return value.replace(PARAM_PATTERN, (_match, name: string) => {
+      const v = params[name];
+      // Per the spec, parameter values are validated against the chain's
+      // parameters schema BEFORE expansion, so `v === undefined` here
+      // means the chain author referenced an undeclared parameter — the
+      // safest substitution is the empty string (matching the standard
+      // {{...}} convention in n8n/Handlebars).
+      return v === undefined ? '' : String(v);
+    });
+  }
+  if (Array.isArray(value)) return value.map((v) => substitute(v, params));
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = substitute(v, params);
+    return out;
+  }
+  return value;
+}
+
+/** Rewrite an edge endpoint ref. `ref` is either `<nodeId>` or
+ *  `<nodeId>.<portName>`. Only the nodeId portion is rewritten; the
+ *  portName (if present) is preserved verbatim. Refs that don't match
+ *  a fragment node id pass through unchanged (lets edges to/from
+ *  parent-workflow nodes work via post-splice wiring). */
+function rewriteEdgeRef(
+  ref: string,
+  fragmentNodeIds: ReadonlySet<string>,
+  prefix: string,
+): string {
+  const dotIdx = ref.indexOf('.');
+  const nodeId = dotIdx === -1 ? ref : ref.slice(0, dotIdx);
+  const portPart = dotIdx === -1 ? '' : ref.slice(dotIdx);
+  return fragmentNodeIds.has(nodeId) ? `${prefix}${nodeId}${portPart}` : ref;
+}
+
+/** Compute the per-expansion node-id prefix from the chainId + expansionId.
+ *  The chainId's dots are replaced with underscores so the resulting ids
+ *  remain valid in storage backends that reserve `.` for hierarchical
+ *  keys. */
+function computePrefix(chainId: string, expansionId: string): string {
+  return `${chainId.replace(/\./g, '_')}_${expansionId}_`;
+}
+
+/**
+ * Expand a workflow-chain into a concrete fragment ready to splice into a
+ * parent workflow. Implements steps 3 + 5 + 6 + 8 of the normative
+ * `workflow-chain-packs.md` §"Expansion semantics" flow.
+ *
+ * @throws ChainUnresolvableTypeIdError when any `dag.nodes[].typeId`
+ *   fails the caller's `isTypeIdResolvable` predicate.
+ */
+export function expandChain(chain: WorkflowChain, ctx: ExpansionContext): ExpandedFragment {
+  // Step 3: validate every typeId resolves.
+  for (const node of chain.dag.nodes) {
+    if (!ctx.isTypeIdResolvable(node.typeId)) {
+      throw new ChainUnresolvableTypeIdError(node.typeId, chain.chainId);
+    }
+  }
+
+  const prefix = computePrefix(chain.chainId, ctx.expansionId);
+  const fragmentNodeIds = new Set(chain.dag.nodes.map((n) => n.id));
+  const idMap = new Map<string, string>();
+  for (const id of fragmentNodeIds) idMap.set(id, `${prefix}${id}`);
+
+  // Steps 5 + 6 + 8: substitute placeholders, rewrite ids, propagate capabilities.
+  const expandedNodes = chain.dag.nodes.map((n) => {
+    const out: ExpandedFragment['nodes'][number] = {
+      id: `${prefix}${n.id}`,
+      typeId: n.typeId,
+    };
+    if (n.name !== undefined) out.name = n.name;
+    if (n.position !== undefined) out.position = n.position;
+    if (n.config !== undefined) {
+      out.config = substitute(n.config, ctx.params) as Record<string, unknown>;
+    }
+    if (n.inputs !== undefined) {
+      out.inputs = substitute(n.inputs, ctx.params) as Record<string, unknown>;
+    }
+    if (chain.capabilities && chain.capabilities.length > 0) {
+      out.capabilities = [...chain.capabilities];
+    }
+    return out;
+  });
+
+  const expandedEdges = (chain.dag.edges ?? []).map((e) => {
+    const out: ExpandedFragment['edges'][number] = {
+      from: rewriteEdgeRef(e.from, fragmentNodeIds, prefix),
+      to: rewriteEdgeRef(e.to, fragmentNodeIds, prefix),
+    };
+    if (e.condition !== undefined) out.condition = e.condition;
+    return out;
+  });
+
+  return { nodes: expandedNodes, edges: expandedEdges, idMap };
+}

package/src/scenarios/agentPackCatalog.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Multi-Agent Shift — `core.openwop.agents.{deep-research, react, supervisor}`
+ * pack-catalog evidence.
+ *
+ * The three reference agent packs published 2026-05-17 are registry-signed
+ * (keyId `openwop-team-1`) but had no in-tree conformance scenarios
+ * proving their `agents[]` manifests are reachable via the host pack
+ * surface AND that each manifest's contents match the contract documented
+ * in `RFCS/0003-agent-packs.md` + `schemas/agent-manifest.schema.json`.
+ *
+ * This file closes that gap. Three test groups, one per pack. Each group:
+ *   1. Skips when the host doesn't advertise `capabilities.agents.supported`
+ *      OR doesn't expose a pack-listing endpoint (`/v1/packs` returning
+ *      404/501 → soft-skip).
+ *   2. Locates the pack by name in the host's pack list.
+ *   3. Validates the pack's `agents[]` entry against the AgentManifest
+ *      contract: required fields, agentId namespace pattern, modelClass
+ *      enum, toolAllowlist format, handoff schema refs.
+ *
+ * Behavioral assertions (the agent actually researches / reacts / supervises)
+ * require an LLM + real agentRuntime host and live outside the public
+ * conformance suite. The advertisement-shape + manifest-validity coverage
+ * here is the wire-level guarantee a third-party host MUST satisfy to
+ * claim "I ship the reference agent packs."
+ *
+ * @see RFCS/0003-agent-packs.md
+ * @see schemas/agent-manifest.schema.json
+ * @see packs/core.openwop.agents.{deep-research,react,supervisor}/pack.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isAgentSupported } from '../lib/multi-agent-capabilities.js';
+
+interface PackList {
+  packs?: Array<{
+    name?: string;
+    version?: string;
+    agents?: Array<{
+      agentId?: string;
+      persona?: string;
+      modelClass?: string;
+      systemPrompt?: string;
+      systemPromptRef?: string;
+      toolAllowlist?: string[];
+      memoryShape?: Record<string, unknown>;
+      handoff?: { taskSchemaRef?: string; returnSchemaRef?: string };
+    }>;
+  }>;
+}
+
+// AgentManifest agentId pattern from schemas/agent-manifest.schema.json.
+const AGENT_ID_PATTERN = /^(core|vendor|community|private|local)\.[a-z][a-z0-9_-]*(\.[a-z][a-zA-Z0-9_-]*)+$/;
+const VALID_MODEL_CLASSES = new Set([
+  'reasoning', 'tool-using', 'chat', 'code', 'vision', 'multimodal',
+  'embedding', 'classification', 'retrieval', 'research', 'delegate',
+]);
+const VALID_TOOL_SCOPES = ['openwop:', 'mcp:', 'vendor.', 'community.', 'private.', 'local.', 'host:'];
+
+async function findPack(name: string): Promise<PackList['packs'] extends Array<infer T> | undefined ? T | null : never> {
+  const res = await driver.get('/v1/packs');
+  if (res.status === 404 || res.status === 501) return null as never;
+  if (res.status !== 200) return null as never;
+  const body = res.json as PackList;
+  if (!Array.isArray(body.packs)) return null as never;
+  const found = body.packs.find((p) => p.name === name);
+  // Cast through unknown to satisfy the conditional return type.
+  return (found ?? null) as never;
+}
+
+function assertAgentManifestShape(
+  agent: NonNullable<NonNullable<PackList['packs']>[number]['agents']>[number],
+  expectations: { agentIdEndsWith?: string; modelClass?: string; minTools?: number },
+): void {
+  // Required: agentId, persona, modelClass.
+  expect(typeof agent.agentId, 'AgentManifest.agentId MUST be a string').toBe('string');
+  expect(typeof agent.persona, 'AgentManifest.persona MUST be a string').toBe('string');
+  expect(typeof agent.modelClass, 'AgentManifest.modelClass MUST be a string').toBe('string');
+
+  // agentId pattern (RFCS/0003 §A namespace tiers).
+  expect(
+    AGENT_ID_PATTERN.test(agent.agentId ?? ''),
+    driver.describe(
+      'schemas/agent-manifest.schema.json §agentId',
+      `agentId "${agent.agentId}" MUST match the namespace-tier pattern`,
+    ),
+  ).toBe(true);
+
+  // modelClass enum check (loose — the schema declares an enum but
+  // hosts MAY extend with research/delegate per the reference packs).
+  if (agent.modelClass !== undefined) {
+    expect(
+      VALID_MODEL_CLASSES.has(agent.modelClass),
+      `AgentManifest.modelClass "${agent.modelClass}" SHOULD be a recognized class`,
+    ).toBe(true);
+  }
+
+  // systemPrompt XOR systemPromptRef.
+  const hasInline = typeof agent.systemPrompt === 'string' && agent.systemPrompt.length > 0;
+  const hasRef = typeof agent.systemPromptRef === 'string' && agent.systemPromptRef.length > 0;
+  expect(
+    hasInline !== hasRef,
+    'AgentManifest MUST have exactly one of systemPrompt | systemPromptRef',
+  ).toBe(true);
+
+  // toolAllowlist: optional, but when present each entry MUST start with a recognized scope.
+  if (Array.isArray(agent.toolAllowlist)) {
+    for (const tool of agent.toolAllowlist) {
+      expect(
+        VALID_TOOL_SCOPES.some((scope) => tool.startsWith(scope)),
+        `toolAllowlist entry "${tool}" MUST start with a recognized scope`,
+      ).toBe(true);
+    }
+    if (expectations.minTools !== undefined) {
+      expect(
+        agent.toolAllowlist.length,
+        `agent's toolAllowlist MUST have at least ${expectations.minTools} entries`,
+      ).toBeGreaterThanOrEqual(expectations.minTools);
+    }
+  }
+
+  // Per-pack expectations.
+  if (expectations.agentIdEndsWith !== undefined) {
+    expect(agent.agentId ?? '').toContain(expectations.agentIdEndsWith);
+  }
+  if (expectations.modelClass !== undefined) {
+    expect(agent.modelClass).toBe(expectations.modelClass);
+  }
+}
+
+const SKIP = !isAgentSupported();
+
+describe.skipIf(SKIP)('core.openwop.agents.deep-research — pack catalog evidence', () => {
+  it('host pack-list includes deep-research with a well-formed AgentManifest', async () => {
+    const pack = await findPack('core.openwop.agents.deep-research');
+    if (pack === null) return; // host doesn't expose /v1/packs or doesn't have this pack
+    expect(pack.version, 'pack version MUST be present').toBeDefined();
+    expect(Array.isArray(pack.agents) && pack.agents.length === 1, 'deep-research ships exactly one agent').toBe(true);
+    assertAgentManifestShape(pack.agents![0]!, {
+      agentIdEndsWith: 'deep-research',
+      modelClass: 'research',
+      minTools: 1,
+    });
+    // Domain-specific: deep-research uses long-term memory + RAG retrievers.
+    const tools = pack.agents![0]!.toolAllowlist ?? [];
+    expect(
+      tools.some((t) => t.includes('rag') || t.includes('retriever')),
+      'deep-research SHOULD allow at least one rag/retriever tool',
+    ).toBe(true);
+    expect(
+      pack.agents![0]!.memoryShape?.longTerm,
+      'deep-research MUST request longTerm memory (it persists facts across runs)',
+    ).toBe(true);
+  });
+});
+
+describe.skipIf(SKIP)('core.openwop.agents.react — pack catalog evidence', () => {
+  it('host pack-list includes react with a well-formed AgentManifest', async () => {
+    const pack = await findPack('core.openwop.agents.react');
+    if (pack === null) return;
+    expect(pack.version).toBeDefined();
+    expect(Array.isArray(pack.agents) && pack.agents.length >= 1, 'react ships at least one agent').toBe(true);
+    assertAgentManifestShape(pack.agents![0]!, {
+      agentIdEndsWith: 'react',
+    });
+    // ReAct pattern requires handoff schemas (task + return).
+    const handoff = pack.agents![0]!.handoff;
+    expect(handoff, 'react AgentManifest MUST include a handoff block').toBeDefined();
+    expect(typeof handoff?.taskSchemaRef, 'handoff.taskSchemaRef MUST be a string').toBe('string');
+    expect(typeof handoff?.returnSchemaRef, 'handoff.returnSchemaRef MUST be a string').toBe('string');
+  });
+});
+
+describe.skipIf(SKIP)('core.openwop.agents.supervisor — pack catalog evidence', () => {
+  it('host pack-list includes supervisor with a well-formed AgentManifest', async () => {
+    const pack = await findPack('core.openwop.agents.supervisor');
+    if (pack === null) return;
+    expect(pack.version).toBeDefined();
+    expect(Array.isArray(pack.agents) && pack.agents.length >= 1, 'supervisor ships at least one agent').toBe(true);
+    assertAgentManifestShape(pack.agents![0]!, {
+      agentIdEndsWith: 'supervisor',
+    });
+    // Supervisor pattern delegates to crew members; its modelClass should
+    // be `delegate` or `reasoning` (it makes orchestration decisions).
+    const mc = pack.agents![0]!.modelClass;
+    expect(
+      mc === 'delegate' || mc === 'reasoning',
+      `supervisor SHOULD have modelClass=delegate|reasoning, got "${mc}"`,
+    ).toBe(true);
+    // Supervisor needs handoff schemas to dispatch work.
+    expect(pack.agents![0]!.handoff, 'supervisor MUST include handoff schemas').toBeDefined();
+  });
+});
+
+describe.skipIf(SKIP)('agent-pack catalog summary', () => {
+  it('all three 2026-05-17 reference agent packs are catalog-reachable', async () => {
+    const names = [
+      'core.openwop.agents.deep-research',
+      'core.openwop.agents.react',
+      'core.openwop.agents.supervisor',
+    ];
+    const found: string[] = [];
+    for (const n of names) {
+      const p = await findPack(n);
+      if (p !== null) found.push(n);
+    }
+    // Either none are present (host doesn't ship these — skip) OR all are
+    // present (host ships the full reference batch). Half-shipping is a
+    // configuration error worth flagging.
+    if (found.length === 0) return;
+    expect(
+      found.length,
+      'host SHOULD ship the reference agent packs as a coherent batch (none, or all three)',
+    ).toBe(names.length);
+  });
+});