@openwop/openwop-conformance 1.0.0

package/src/lib/mcp-fake-server.ts

@@ -0,0 +1,185 @@
+/**
+ * Track 6: in-process synthetic MCP server for roundtrip conformance.
+ *
+ * Implements just enough of the Model Context Protocol's HTTP/JSON-RPC
+ * transport (https://spec.modelcontextprotocol.io/) to exercise the
+ * host's MCP-integration code path:
+ *
+ *   - `initialize` — server info + capabilities
+ *   - `tools/list` — returns a single deterministic `echo` tool
+ *   - `tools/call name=echo` — records invocation, returns input verbatim
+ *
+ * Records every invocation in memory so scenarios can assert the host
+ * called the expected tool with the expected arguments. The server is
+ * Node-stdlib-only (no MCP SDK dependency) — the wire shape is small
+ * enough to implement directly.
+ *
+ * Operator contract: when a host integrates MCP via a configurable
+ * server URL, the operator points the host at this fake's endpoint
+ * (printed at suite init). Hosts that hardcode MCP servers cannot
+ * exercise the roundtrip scenario and the test skips.
+ *
+ * @see spec/v1/mcp-integration.md
+ * @see SECURITY/threat-model-prompt-injection.md §"UNTRUSTED marker"
+ */
+
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+export interface McpInvocation {
+  readonly method: string;
+  readonly params: unknown;
+  readonly timestamp: number;
+}
+
+export class McpFakeServer {
+  private _server: Server | null = null;
+  private _boundPort = 0;
+  private readonly _invocations: McpInvocation[] = [];
+
+  async start(port: number = 0): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const server = createServer((req, res) => this._handle(req, res));
+      server.on('error', reject);
+      server.listen(port, '127.0.0.1', () => {
+        const addr = server.address() as AddressInfo;
+        this._server = server;
+        this._boundPort = addr.port;
+        resolve();
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (!this._server) return;
+    const server = this._server;
+    this._server = null;
+    return new Promise((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  endpoint(): string {
+    return `http://127.0.0.1:${this._boundPort}`;
+  }
+
+  invocations(): readonly McpInvocation[] {
+    return this._invocations;
+  }
+
+  reset(): void {
+    this._invocations.length = 0;
+  }
+
+  private async _handle(
+    req: import('node:http').IncomingMessage,
+    res: import('node:http').ServerResponse,
+  ): Promise<void> {
+    if (req.method !== 'POST') {
+      res.writeHead(405).end();
+      return;
+    }
+    const chunks: Buffer[] = [];
+    for await (const c of req) chunks.push(c as Buffer);
+    const body = Buffer.concat(chunks).toString('utf8');
+
+    let rpc: { jsonrpc?: string; id?: unknown; method?: string; params?: unknown };
+    try {
+      rpc = JSON.parse(body);
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' } }));
+      return;
+    }
+
+    if (typeof rpc.method === 'string') {
+      this._invocations.push({
+        method: rpc.method,
+        params: rpc.params ?? null,
+        timestamp: Date.now(),
+      });
+    }
+
+    const response = this._respond(rpc);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(response));
+  }
+
+  private _respond(rpc: {
+    id?: unknown;
+    method?: string;
+    params?: unknown;
+  }): Record<string, unknown> {
+    const id = rpc.id ?? null;
+    switch (rpc.method) {
+      case 'initialize':
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            protocolVersion: '2025-03-26',
+            capabilities: { tools: {} },
+            serverInfo: { name: 'openwop-conformance-fake-mcp', version: '1.0.0' },
+          },
+        };
+
+      case 'tools/list':
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            tools: [
+              {
+                name: 'echo',
+                description: 'Returns the `text` argument verbatim. Deterministic.',
+                inputSchema: {
+                  type: 'object',
+                  properties: { text: { type: 'string' } },
+                  required: ['text'],
+                  additionalProperties: false,
+                },
+              },
+            ],
+          },
+        };
+
+      case 'tools/call': {
+        const params = (rpc.params ?? {}) as { name?: string; arguments?: { text?: string } };
+        if (params.name !== 'echo') {
+          return {
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32602, message: `Unknown tool: ${params.name}` },
+          };
+        }
+        const text = params.arguments?.text ?? '';
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            content: [{ type: 'text', text }],
+            isError: false,
+          },
+        };
+      }
+
+      default:
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32601, message: `Method not found: ${rpc.method}` },
+        };
+    }
+  }
+}
+
+// Module-scope instance + lifecycle helpers, mirroring otel-collector.ts.
+let _instance: McpFakeServer | null = null;
+
+export function setMcpFakeServer(s: McpFakeServer | null): void {
+  _instance = s;
+}
+
+export function getMcpFakeServer(): McpFakeServer | null {
+  return _instance;
+}

package/src/lib/multi-agent-capabilities.ts

@@ -0,0 +1,155 @@
+/**
+ * Multi-Agent Shift capability-gating helper.
+ *
+ * Reads the host's `/.well-known/openwop` `capabilities.agents` block
+ * + `capabilities.conversationPrimitive` flag at suite init and caches
+ * them as discrete predicates. Sibling to `lib/fixtures.ts` — same
+ * pattern, different surface.
+ *
+ * Why: Multi-Agent Shift scenarios (Phases 1-6) gate on per-phase
+ * capability flags. Mirrors the fixture-gating pattern from RFC 0003
+ * so conformance scenarios skip honestly when the host's advertisement
+ * doesn't claim the relevant phase support.
+ *
+ * Cache lifecycle:
+ *   - `setMultiAgentCapabilities(...)` populates from a discovery
+ *     payload. Idempotent — repeated calls with the same payload are
+ *     no-ops. Setup file calls this from a top-level `await`.
+ *   - Sync predicates (`isAgentSupported()`, etc.) return false until
+ *     the cache is set — same defensive default as fixture-gating.
+ *   - `__resetForTests()` clears the cache for unit tests.
+ *
+ * @see spec/v1/capabilities.md §`agents`
+ * @see spec/v1/capabilities.md §`conversationPrimitive`
+ */
+
+import type { DiscoveryPayload } from './profiles.js';
+
+interface AgentCaps {
+  supported: boolean;
+  profile: string | undefined;
+  modelClasses: ReadonlySet<string>;
+  orchestratorPattern: string | undefined;
+  memoryBackends: ReadonlySet<string>;
+  orchestrator: boolean;
+  dispatch: boolean;
+  reasoning:
+    | {
+        verbosity: 'summary' | 'full' | 'off' | undefined;
+        tokenLimit: number | undefined;
+      }
+    | undefined;
+}
+
+let _agentCaps: AgentCaps | null = null;
+let _conversationPrimitive = false;
+
+function asBoolean(value: unknown): boolean {
+  return value === true;
+}
+
+function asStringSet(value: unknown): ReadonlySet<string> {
+  if (!Array.isArray(value)) return new Set();
+  return new Set(value.filter((v): v is string => typeof v === 'string' && v.length > 0));
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Populate the cache from a discovery-doc payload. Tolerant of malformed
+ * inputs — anything other than the expected shape is treated as "absent."
+ */
+export function setMultiAgentCapabilities(c: DiscoveryPayload | null | undefined): void {
+  if (!c || typeof c !== 'object') {
+    _agentCaps = null;
+    _conversationPrimitive = false;
+    return;
+  }
+
+  const agentsRaw = (c as { agents?: unknown }).agents;
+  if (agentsRaw && typeof agentsRaw === 'object') {
+    const a = agentsRaw as Record<string, unknown>;
+    const reasoningRaw = a.reasoning;
+    const reasoning =
+      reasoningRaw && typeof reasoningRaw === 'object'
+        ? {
+            verbosity: asString((reasoningRaw as Record<string, unknown>).verbosity) as
+              | 'summary'
+              | 'full'
+              | 'off'
+              | undefined,
+            tokenLimit:
+              typeof (reasoningRaw as Record<string, unknown>).tokenLimit === 'number'
+                ? ((reasoningRaw as Record<string, unknown>).tokenLimit as number)
+                : undefined,
+          }
+        : undefined;
+    _agentCaps = {
+      supported: asBoolean(a.supported),
+      profile: asString(a.profile),
+      modelClasses: asStringSet(a.modelClasses),
+      orchestratorPattern: asString(a.orchestratorPattern),
+      memoryBackends: asStringSet(a.memoryBackends),
+      orchestrator: asBoolean(a.orchestrator),
+      dispatch: asBoolean(a.dispatch),
+      reasoning,
+    };
+  } else {
+    _agentCaps = null;
+  }
+
+  _conversationPrimitive = asBoolean((c as { conversationPrimitive?: unknown }).conversationPrimitive);
+}
+
+/** Phase 1 master switch. */
+export function isAgentSupported(): boolean {
+  return _agentCaps?.supported === true;
+}
+
+/** Phase 1 reasoning verbosity. */
+export function getReasoningVerbosity(): 'summary' | 'full' | 'off' | undefined {
+  return _agentCaps?.reasoning?.verbosity;
+}
+
+/** Phase 2 — host supports the named modelClass. */
+export function hasModelClass(modelClass: string): boolean {
+  return _agentCaps?.modelClasses.has(modelClass) === true;
+}
+
+/** Phase 2 — host advertises an orchestrator pattern (any value). */
+export function hasOrchestratorPattern(): boolean {
+  return typeof _agentCaps?.orchestratorPattern === 'string';
+}
+
+/** Phase 3 — host advertises long-term memory backend. */
+export function hasLongTermMemory(): boolean {
+  return _agentCaps?.memoryBackends.has('long-term') === true;
+}
+
+/** Phase 4 — host implements `core.conversationGate` + `conversation.*` suspends. */
+export function isConversationPrimitiveSupported(): boolean {
+  return _conversationPrimitive;
+}
+
+/** Phase 5 — host implements `core.orchestrator.supervisor` + CP-1. */
+export function isOrchestratorSupported(): boolean {
+  return _agentCaps?.orchestrator === true;
+}
+
+/** Phase 6 — host implements `core.dispatch` + CP-2. */
+export function isDispatchSupported(): boolean {
+  return _agentCaps?.dispatch === true;
+}
+
+/** Diagnostic — returns the cached state or `null` if not yet set. */
+export function getCachedAgentCaps(): AgentCaps | null {
+  return _agentCaps;
+}
+
+/** Test-only reset. */
+export function __resetForTests(): void {
+  _agentCaps = null;
+  _conversationPrimitive = false;
+}

package/src/lib/multiProcess.ts

@@ -0,0 +1,141 @@
+/**
+ * Multi-process host orchestrator for the staleClaim conformance
+ * scenario.
+ *
+ * Spawns a host child process directly via `child_process.spawn` so
+ * the test has a real PID to SIGKILL. Using `npm start` + killing the
+ * npm wrapper does NOT reach the actual host process — that pattern
+ * leaves the host running.
+ *
+ * The harness is small and zero-deps. It assumes the SQLite reference
+ * host's `tsx src/server.ts` entrypoint accepts:
+ *
+ *   - OPENWOP_PORT
+ *   - OPENWOP_API_KEY
+ *   - OPENWOP_SQLITE_PATH
+ *   - OPENWOP_CLAIM_TTL_MS
+ *   - OPENWOP_HEARTBEAT_INTERVAL_MS
+ *
+ * Other host implementations adapt the spawn command.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface SpawnedHostConfig {
+  /** Repo-root-relative path to the host's package directory. */
+  readonly packageDir: string;
+  /** Bind port. */
+  readonly port: number;
+  /** Bearer token. */
+  readonly apiKey: string;
+  /** Absolute path to the SQLite DB file (shared across processes). */
+  readonly dbPath: string;
+  /** Claim TTL in ms. Tests use a short value (e.g., 2000). */
+  readonly claimTtlMs: number;
+  /** Heartbeat renewal interval in ms. Tests use ≤ claimTtlMs/2. */
+  readonly heartbeatIntervalMs: number;
+}
+
+export interface SpawnedHost {
+  readonly process: ChildProcess;
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  /** Resolves once `/.well-known/openwop` returns 200. */
+  ready(): Promise<void>;
+  /** Force-kill (SIGKILL) — does NOT trigger the host's graceful shutdown handler. */
+  kill(): Promise<void>;
+  /** Graceful kill (SIGTERM) — triggers the host's shutdown handler (releases claims). */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Find the repo root by walking up from this file until we see the
+ * spec corpus marker.
+ */
+function findRepoRoot(): string {
+  let probe = new URL('.', import.meta.url).pathname;
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(probe, 'spec', 'v1'))) return probe;
+    probe = join(probe, '..');
+  }
+  throw new Error('Could not locate repo root from conformance/src/lib/multiProcess.ts');
+}
+
+export async function spawnHost(config: SpawnedHostConfig): Promise<SpawnedHost> {
+  const repoRoot = findRepoRoot();
+  const cwd = join(repoRoot, config.packageDir);
+
+  const env = {
+    ...process.env,
+    OPENWOP_HOST: '127.0.0.1',
+    OPENWOP_PORT: String(config.port),
+    OPENWOP_API_KEY: config.apiKey,
+    OPENWOP_SQLITE_PATH: config.dbPath,
+    OPENWOP_CLAIM_TTL_MS: String(config.claimTtlMs),
+    OPENWOP_HEARTBEAT_INTERVAL_MS: String(config.heartbeatIntervalMs),
+  };
+
+  // Spawn `npx tsx src/server.ts` directly (not `npm start`) so we get
+  // the tsx PID, not the npm wrapper PID. SIGKILL on the npm wrapper
+  // does NOT propagate to the tsx child — confirmed by smoke testing
+  // when this lib was authored.
+  const proc = spawn('npx', ['tsx', 'src/server.ts'], {
+    cwd,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  const baseUrl = `http://127.0.0.1:${config.port}`;
+  const host: SpawnedHost = {
+    process: proc,
+    baseUrl,
+    apiKey: config.apiKey,
+    async ready(): Promise<void> {
+      const deadline = Date.now() + 10_000;
+      while (Date.now() < deadline) {
+        if (proc.exitCode !== null) {
+          throw new Error(`Host exited before ready (code ${proc.exitCode})`);
+        }
+        try {
+          const res = await fetch(`${baseUrl}/.well-known/openwop`);
+          if (res.ok) return;
+        } catch {
+          // not yet listening
+        }
+        await new Promise((r) => setTimeout(r, 200));
+      }
+      throw new Error(`Host at ${baseUrl} did not become ready within 10s`);
+    },
+    async kill(): Promise<void> {
+      if (proc.pid !== undefined && proc.exitCode === null) {
+        proc.kill('SIGKILL');
+      }
+      await new Promise<void>((resolve) => {
+        if (proc.exitCode !== null) {
+          resolve();
+          return;
+        }
+        proc.once('exit', () => resolve());
+        // Backstop in case the exit event already fired.
+        setTimeout(() => resolve(), 1000);
+      });
+    },
+    async shutdown(): Promise<void> {
+      if (proc.pid !== undefined && proc.exitCode === null) {
+        proc.kill('SIGTERM');
+      }
+      await new Promise<void>((resolve) => {
+        if (proc.exitCode !== null) {
+          resolve();
+          return;
+        }
+        proc.once('exit', () => resolve());
+        setTimeout(() => resolve(), 5000);
+      });
+    },
+  };
+
+  return host;
+}