@agdf/mcp-server 0.0.0-stage → 0.20.0

package/src/generation.js

@@ -0,0 +1,211 @@
+import { fork } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { generationMessage, validGenerationMessage, generationManifest, manifestDigest, generationFailureReason, GENERATION_LIMITS as L } from './generation-protocol.js';
+import { loadCockpitResource } from './cockpit-resource.js';
+import { DispatchExecutionError } from './worker.js';
+
+// One live facade, three directly owned children, no process registry or PID
+// discovery. Capacity includes startup and unconfirmed cleanup, not just current.
+export async function createOwnedGenerationFacade({ runtime, publisher, createControlRuntime, surface, cockpitDir, cockpitMode,
+  Fork = fork, qualifyMs = L.qualify, closeMs = L.close, invokeMs = L.qualify, onEvent = () => {} } = {}) {
+  if (![qualifyMs, closeMs, invokeMs].every(value => Number.isSafeInteger(value) && value > 0)
+    || qualifyMs > L.qualify || closeMs > L.close || invokeMs > L.qualify) throw Error('generation_deadline_invalid');
+  const epoch = randomUUID(), slots = new Map(), routes = new Map(), presentations = new Map(), operations = new Map(), receipts = new Map();
+  let current, nextGeneration = 0, replacing = false, closed = false, closing, actualContext = {}, nativeRequired = false;
+  const uiDigest = runtime.ui ? loadCockpitResource(runtime.ui).digest : undefined;
+  const expected = manifestDigest(generationManifest(runtime, uiDigest, publisher.initial.sdkDigest));
+  const event = (row, kind, reason) => onEvent({ owner_epoch: epoch, generation_id: row?.id ?? null, kind, reason: reason ?? null, occupancy: slots.size });
+  const failure = (reason, extra = {}) => ({ outcome: 'rejected', reason, authorizes: false, ...extra });
+  function status() {
+    return { available: true, owner_epoch: epoch, maximum: L.slots, occupancy: slots.size, current_generation: current?.id ?? null,
+      candidate_active: replacing, generations: [...slots.values()].map(row => ({ generation_id: row.id,
+        publication_id: row.package.publication_id, state: row.state, active_requests: row.inflight,
+        uncertain_operations: row.unknown.size, views: row.observed?.views ?? null,
+        confirmed_exit: row.exited, usable: row === current && row.state === 'current' && !row.exited })), authorizes: false };
+  }
+  function request(row, kind, payload, context = {}, original = null, timeout = qualifyMs) {
+    if (row.exited || !row.child?.connected) return Promise.reject(new DispatchExecutionError('generation_unavailable', 'not_dispatched'));
+    const id = randomUUID(), message = generationMessage(epoch, row.id, kind, payload, context, original, id);
+    if (!validGenerationMessage(message, { epoch, generation: row.id })) return Promise.reject(new DispatchExecutionError('generation_input_limit', 'not_dispatched'));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { row.pending.delete(id); reject(new DispatchExecutionError('generation_response_unknown')); }, timeout);
+      row.pending.set(id, { kind, original, resolve, reject, timer });
+      row.child.send(message, error => { if (error) { clearTimeout(timer); row.pending.delete(id); reject(new DispatchExecutionError('generation_connection_lost')); } });
+    });
+  }
+  async function observe(row) {
+    try { const reply = await request(row, 'session_inspect', {}); row.observed = reply.payload; return row.observed; }
+    catch { row.state = 'close_unconfirmed'; return null; }
+  }
+  async function retire(row, teardown = false) {
+    if (row === current || row.inflight || row.unknown.size || row.state === 'closing' || row.state === 'close_unconfirmed') return false;
+    const work = await observe(row);
+    if (!work || !teardown && work.views || work.inflight || work.executor || work.uncertain) return false;
+    row.state = 'closing'; event(row, 'orderly_close');
+    let exitTimer;
+    const ended = new Promise(resolve => {
+      if (row.exited) { resolve(false); return; }
+      row.end = resolve; exitTimer = setTimeout(() => { row.state = 'close_unconfirmed'; event(row, 'close_unconfirmed'); resolve(false); }, closeMs);
+    });
+    try { const ack = await request(row, 'shutdown', {}, {}, null, closeMs);
+      row.closeAck = ack.kind === 'closed' && !ack.payload.views && !ack.payload.inflight && !ack.payload.executor && !ack.payload.uncertain;
+    } catch { row.state = 'close_unconfirmed'; event(row, 'close_unconfirmed'); }
+    const confirmed = await ended; clearTimeout(exitTimer); return confirmed;
+  }
+  async function reserve(packageInfo, context) {
+    if (slots.size >= L.slots) {
+      const candidates = [...slots.values()].filter(row => row !== current && !row.inflight && !row.unknown.size
+        && !['starting', 'qualifying', 'closing', 'close_unconfirmed'].includes(row.state)).sort((a, b) => a.id - b.id);
+      for (const row of candidates) { if (await retire(row)) break; }
+    }
+    if (slots.size >= L.slots) throw Error('generation_capacity_protected');
+    const row = { id: ++nextGeneration, package: packageInfo, state: 'starting', pending: new Map(),
+      unknown: new Set(), inflight: 0, exited: false, closeAck: false, observed: null };
+    slots.set(row.id, row); event(row, 'reserved'); // Reservation precedes acquisition/load/spawn.
+    try {
+      const claim = publisher.acquire(packageInfo, { ownerEpoch: epoch, generation: row.id });
+      row.child = Fork(join(packageInfo.packageRoot, 'src/generation-entry.js'), [epoch, String(row.id)],
+        { stdio: ['ignore', 'ignore', 'ignore', 'ipc'], serialization: 'json', execArgv: [] });
+      claim.bindOwnedChild(row.child, { confirmedEnd: () => row.closeAck && !row.inflight && !row.unknown.size });
+      row.child.on('message', reply => {
+        if (!validGenerationMessage(reply, { epoch, generation: row.id, reply: true })) { event(row, 'invalid_reply'); return; }
+        const pending = row.pending.get(reply.request_id);
+        if (!pending || pending.original !== reply.original_operation_id) { event(row, 'unknown_reply'); return; }
+        const expectedKind = { qualify: 'qualified', invoke: 'result', session_inspect: 'status', shutdown: 'closed' }[pending.kind];
+        if (reply.kind !== expectedKind && reply.kind !== 'failure') return;
+        clearTimeout(pending.timer); row.pending.delete(reply.request_id);
+        if (reply.kind === 'failure') pending.reject(new DispatchExecutionError(reply.payload.reason));
+        else {
+          if (reply.kind === 'closed') row.closeAck = !reply.payload.views && !reply.payload.inflight && !reply.payload.executor && !reply.payload.uncertain;
+          pending.resolve(reply);
+        }
+      });
+      row.child.once('exit', () => {
+        row.exited = true;
+        for (const pending of row.pending.values()) { clearTimeout(pending.timer); pending.reject(new DispatchExecutionError('generation_connection_lost')); }
+        row.pending.clear();
+        if (row.closeAck && !row.inflight && !row.unknown.size) { slots.delete(row.id); row.state = 'closed'; event(row, 'confirmed_exit'); row.end?.(true); }
+        else { row.state = 'close_unconfirmed'; event(row, 'unexpected_exit'); row.end?.(false); }
+      });
+      row.child.once('error', () => { row.state = 'close_unconfirmed'; event(row, 'spawn_failed'); });
+      row.state = 'qualifying'; event(row, 'qualifying');
+      const qualified = (await request(row, 'qualify', { surface, commandGroups: [...(runtime.trustedContext.commandGroups ?? [])],
+        ...(cockpitDir ? { cockpitDir } : {}), ...(cockpitMode ? { cockpitMode } : {}) }, context)).payload;
+      if (manifestDigest(qualified.manifest) !== expected || qualified.producer.server_digest !== packageInfo.digest
+        || qualified.producer.dispatcher_digest !== packageInfo.dispatcherDigest || qualified.producer.sdk_digest !== packageInfo.sdkDigest
+        || nativeRequired && !qualified.support.app_mediation) throw Error('generation_manifest_incompatible');
+      row.state = 'qualified'; event(row, 'qualified'); return row;
+    } catch (error) {
+      event(row, 'qualification_failed', generationFailureReason(error));
+      if (!row.child) { slots.delete(row.id); event(row, 'not_spawned'); }
+      else { row.state = 'draining'; await retire(row); }
+      throw error;
+    }
+  }
+  const control = {
+    status,
+    async refresh() { await Promise.all([...slots.values()].filter(row => !row.exited).map(observe)); return status(); },
+    inspect(id, input) { const record = receipts.get(id);
+      if (record && (record.input.run_id !== input.run_id || record.input.primary_target !== input.primary_target
+        || record.input.expected_revision_id !== input.expected_revision_id)) return { status: 'unknown', reason: 'connection_control_binding_invalid', authorizes: false };
+      return record ? { status: record.result ? 'recorded' : 'pending',
+      request_digest: record.digest, result: record.result, current: status(), authorizes: false }
+      : { status: 'unknown', reason: 'connection_control_record_unavailable', current: status(), authorizes: false }; },
+    async replace({ input, candidate, requestDigest, revalidate }) {
+      const prior = receipts.get(input.operation_id);
+      if (prior) return prior.digest !== requestDigest ? failure('operation_payload_conflict')
+        : prior.result ? { ...prior.result, outcome: prior.result.outcome === 'accepted' ? 'already_applied' : prior.result.outcome, historical_effect: true, current: status() }
+        : { outcome: 'effect_unknown', reason: 'generation_replacement_pending', current: status(), authorizes: false };
+      if (receipts.size >= L.receipts) return failure('connection_control_capacity');
+      if (closed || replacing) return failure(closed ? 'connection_closed' : 'generation_replacement_busy');
+      const record = { digest: requestDigest, input, result: null }; receipts.set(input.operation_id, record); replacing = true;
+      let candidateRow;
+      try {
+        revalidate(); const packageInfo = publisher.resolve(candidate);
+        candidateRow = await reserve(packageInfo, actualContext); revalidate();
+        const previous = current; current = candidateRow; current.state = 'current';
+        if (previous) previous.state = previous.exited ? 'close_unconfirmed' : 'draining';
+        event(current, 'admitted'); record.result = { outcome: 'accepted', reason: null, operation_id: input.operation_id,
+          request_digest: requestDigest, effect: { runtime_replaced: true, generation_id: current.id }, current: status(), authorizes: false };
+      } catch (error) {
+        if (candidateRow && candidateRow !== current) { candidateRow.state = 'draining'; await retire(candidateRow); }
+        record.result = failure(generationFailureReason(error), { operation_id: input.operation_id, current: status() });
+      } finally { replacing = false; }
+      record.result.current = status(); return record.result;
+    },
+  };
+  const controlRuntime = createControlRuntime(control);
+  function operationKey(input, id = input.operation_id) { return JSON.stringify([input.primary_target, input.run_id, id]); }
+  async function invoke(name, args, host = {}, signal) {
+    if (signal?.aborted) throw new DispatchExecutionError('dispatch_cancelled', 'not_dispatched');
+    if (closed) throw new DispatchExecutionError('connection_closed', 'not_dispatched');
+    actualContext = { client: host.client, uiSupported: host.uiSupported === true };
+    if (args.operation_id && name === 'agdf_record' && args.command?.kind === 'runtime_generation.replace'
+      && operations.has(operationKey(args))) throw new DispatchExecutionError('operation_payload_conflict', 'not_dispatched');
+    if (args.operation_id && args.command?.kind !== 'runtime_generation.replace' && receipts.has(args.operation_id))
+      throw new DispatchExecutionError('operation_payload_conflict', 'not_dispatched');
+    if (name === 'agdf_record' && args.command?.kind === 'runtime_generation.replace'
+      || name === 'agdf_inspect' && args.operation === 'runtime-generations') {
+      const result = await controlRuntime.tool(name).execute(controlRuntime.tool(name).parse(args));
+      return controlRuntime.projectToolResult(name, args, name === 'agdf_inspect' && result.report?.available ? { ...result, report: await control.refresh() } : result);
+    }
+    if (name === 'agdf_inspect' && args.operation === 'operation-status' && receipts.has(args.module)) {
+      const validated = await controlRuntime.tool(name).execute(controlRuntime.tool(name).parse(args));
+      return controlRuntime.projectToolResult(name, args, validated.report?.status === 'unknown' || validated.report?.status === 'absent'
+        ? { ...validated, report: control.inspect(args.module, args) } : validated);
+    }
+    const knownSession = args.session_id && routes.get(args.session_id);
+    if (args.session_id && !knownSession) throw new DispatchExecutionError('session_expired', 'not_dispatched');
+    const id = name === 'agdf_inspect' && args.operation === 'operation-status' ? args.module : args.operation_id;
+    const key = id && operationKey(args, id), original = key && operations.get(key);
+    const presentationId = args.command?.payload?.presentation_id ?? args.presentation_id;
+    const presentationOwner = presentationId && presentations.get(operationKey(args, presentationId));
+    const row = knownSession ?? original ?? presentationOwner ?? current;
+    if (!row || row.exited) throw new DispatchExecutionError('generation_unavailable', 'not_dispatched');
+    if (args.operation_id && !original) {
+      if (operations.size >= L.routes) throw new DispatchExecutionError('generation_route_capacity', 'not_dispatched');
+      operations.set(key, row);
+    }
+    ++row.inflight; event(row, 'invoke', name);
+    try {
+      const result = (await request(row, 'invoke', { name, arguments: args }, actualContext, args.operation_id ?? null, invokeMs)).payload;
+      if (args.operation_id && result.outcome === 'effect_unknown') row.unknown.add(key);
+      if (name === 'agdf_inspect' && args.operation === 'operation-status' && result.report?.status === 'recorded'
+        && result.report.receipt?.operation_id === args.module) row.unknown.delete(key);
+      if (result.app_capability === 'available') nativeRequired = true;
+      if (result.family_result?.presentation_id && ['accepted', 'already_applied'].includes(result.outcome)) {
+        const presentationKey = operationKey(args, result.family_result.presentation_id);
+        if (!presentations.has(presentationKey) && presentations.size >= L.routes) throw Error('generation_route_capacity');
+        presentations.set(presentationKey, row);
+      }
+      for (const meta of [result._meta?.agdf_decision, result._meta?.agdf_cockpit]) {
+        for (const selector of [meta?.session_id, meta?.read_session_id]) {
+          if (selector) { if (routes.size >= L.routes) throw Error('generation_route_capacity'); routes.set(selector, row); }
+        }
+      }
+      return result;
+    } catch (error) { if (args.operation_id && error.dispatch !== 'not_dispatched') row.unknown.add(key); throw error; }
+    finally { --row.inflight; if (closed && !row.inflight && !row.unknown.size) void retire(row, true); }
+  }
+  current = await reserve(publisher.initial, {}); current.state = 'current'; event(current, 'admitted');
+  // Validate the public request here, but transport that exact public shape.
+  // Core parse results contain trusted runtime context and are executable inputs,
+  // not wire requests; parsing them again in a child both breaks the contract
+  // and copies the entire locale registry into a bounded private message.
+  const tools = runtime.tools.map(tool => ({ ...tool, parentOwned: true,
+    parse: input => { tool.parse(input); return input; }, execute: input => invoke(tool.name, input) }));
+  // The server supplies actual initialize/request context only at this seam.
+  for (const tool of tools) tool.execute = (input, signal, host) => invoke(tool.name, input, host, signal);
+  return Object.freeze({ ...runtime, tools, tool: name => tools.find(tool => tool.name === name),
+    requiresProjectedResult: true, postprocessToolResult: undefined, inspectOwnership: status, runtimeControl: control,
+    close() {
+      return closing ??= (async () => {
+        closed = true;
+        const previous = current; current = null; if (previous && !previous.exited) previous.state = 'draining';
+        await Promise.allSettled([...slots.values()].map(row => retire(row, true)));
+        return status();
+      })();
+    },
+  });
+}

package/src/main.js

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import { createAgdfWorkerExecutor, serveAgdfStdio } from "./server.js";
+import { loadCockpitResource } from './cockpit-resource.js';
+
+export async function runMcpServer({ surface, cockpitDir, cockpitMode, runtime, executor, ownedPublication, ownedPublisher, onClosed } = {}) {
+  if (cockpitMode !== undefined && (cockpitMode !== 'plugin' || surface !== 'codex' || cockpitDir !== undefined)) throw Error('AGDF_COCKPIT_TARGET_INVALID');
+  const defaultRuntime = runtime === undefined && cockpitDir === undefined && cockpitMode === undefined;
+  // A supplied, bound runtime owns its resources. Do not load a second package
+  // composition merely to run an explicit adapter/protocol fixture.
+  const dispatcherRuntime = runtime === undefined ? await import('create-agdf/mcp-dispatch-runtime') : null;
+  runtime ??= cockpitDir !== undefined || cockpitMode !== undefined ? await dispatcherRuntime.createMcpCockpitRuntime({ surface, cockpitDir, cockpitMode }) : dispatcherRuntime.createMcpDispatchRuntime({ surface });
+  const serverVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  if (runtime.trustedContext.expectedVersion !== serverVersion) {
+    process.stderr.write("AGDF_MCP_VERSION_MISMATCH\n");
+    process.exitCode = 1;
+    return null;
+  }
+  if (runtime.trustedContext.provenanceStatus !== "matched") {
+    process.stderr.write("AGDF_MCP_RUNTIME_PROVENANCE_INVALID\n");
+    process.exitCode = 1;
+    return null;
+  }
+  if (defaultRuntime && surface === 'codex' && dispatcherRuntime?.createMcpDecisionRuntime) {
+    const ui = { uri: dispatcherRuntime.DECISION_UI_URI, mimeType: 'text/html;profile=mcp-app', limit: 4 * 1024 ** 2, kind: 'decision' };
+    ui.digest = loadCockpitResource(ui).digest;
+    // A shipped resource does not qualify native App-only mediation. Production
+    // actions remain disabled until exact package/host evidence is provided.
+    runtime = await dispatcherRuntime.createMcpDecisionRuntime({ runtime, ui });
+  }
+  if (runtime.mode === 'cockpit') loadCockpitResource(runtime.ui);
+  if (ownedPublication) {
+    const { createOwnedGenerationFacade } = await import('./generation.js');
+    if (!ownedPublisher) throw Error('runtime_publication_unowned');
+    const publisher = ownedPublisher;
+    runtime = await createOwnedGenerationFacade({ runtime, publisher, surface, cockpitDir, cockpitMode,
+      createControlRuntime: runtimeControl => dispatcherRuntime.createMcpDispatchRuntime({ surface, runtimeControl }) });
+  }
+  const dispatchExecutor = executor ?? (runtime.mode === 'cockpit' ? undefined
+    : createAgdfWorkerExecutor(runtime, { releaseOwnedLock: dispatcherRuntime?.releaseAbandonedOwnedLock ?? null }));
+  const handle = serveAgdfStdio({
+    runtime,
+    executor: dispatchExecutor,
+    onerror(code) {
+      process.stderr.write(`${code}\n`);
+    },
+  });
+  let closing;
+  const close = () => closing ??= handle.close().then(result => { onClosed?.(result); return result; });
+  process.once("SIGINT", close);
+  process.once("SIGTERM", close);
+  process.stdin.once("close", close);
+  process.stdin.once("end", close);
+  if (process.stdin.readableEnded || process.stdin.destroyed) void close();
+  return Object.freeze({ close });
+}

package/src/server.js

@@ -0,0 +1,187 @@
+import { McpServer, ProtocolError, ProtocolErrorCode, fromJsonSchema } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { DispatchExecutionError, createWorkerDispatchExecutor } from "./worker.js";
+import { loadCockpitResource } from './cockpit-resource.js';
+import { requestDeclaresMcpAppUi, requestMcpClientInfo, requestMcpClientCapabilities } from "./ui-capability.js";
+
+export const SERVER_NAME = "agdf-mcp";
+
+function toolResult(runtime, name, input, result, serialize = runtime.serialize, provider, peer, facts) {
+  // A generation must supply its own descriptor. Never reinterpret old results
+  // with the facade's current runtime. Local owners project after postprocessing.
+  const emit = value => {
+    const projected = Object.hasOwn(value._meta ?? {}, 'agdf/tool-result') || runtime.requiresProjectedResult ? value
+      : runtime.projectToolResult(name, input, value, facts);
+    const { domain, metadata, descriptor } = runtime.consumeToolResult(name, projected);
+    const text = serialize(domain);
+    const response = {
+      content: [{ type: 'text', text: domain.presentation_delivery?.text ?? text },
+        ...(descriptor.failed ? [{ type: 'text', text: descriptor.message }] : [])],
+      structuredContent: JSON.parse(text),
+      ...(descriptor.failed ? { isError: true } : {}),
+      ...(Object.keys(metadata).length || provider ? { _meta: { ...metadata,
+        ...(provider ? { 'agdf/provider': provider, 'agdf/peer': peer } : {}) } } : {}),
+    };
+    return response;
+  };
+  let response = emit(result);
+  if (runtime.responseLimit && Buffer.byteLength(JSON.stringify(response), 'utf8') > runtime.responseLimit) {
+    // The fallback itself is projected, checked and measured; no recursive call.
+    const limitFacts = { code: 'resource_limit', dispatch: 'unknown' };
+    const failure = runtime.projectToolResult(name, input, runtime.failure('resource_limit', name, input, limitFacts), limitFacts);
+    response = emit(failure);
+    if (Buffer.byteLength(JSON.stringify(response), 'utf8') > runtime.responseLimit) throw Error('tool_result_invalid');
+  }
+  return response;
+}
+
+export function buildAgdfServer({ runtime, executor } = {}) {
+  if (!runtime?.definition || typeof runtime.serialize !== "function") {
+    throw new TypeError("AGDF MCP runtime is required");
+  }
+  if (runtime.trustedContext?.provenanceStatus !== "matched") {
+    throw new TypeError("AGDF MCP owned runtime is required");
+  }
+  const tools = runtime.tools ?? [{ name: runtime.definition.name, definition: runtime.definition, parse: runtime.parse, execute: runtime.execute }];
+  const dispatchExecutor = executor ?? {
+    execute: async (argumentsValue, { toolName, signal } = {}) => {
+      const tool = tools.find((entry) => entry.name === (toolName ?? runtime.definition.name));
+      if (!tool) throw new DispatchExecutionError("dispatch_worker_failed");
+      let parsed;
+      try { parsed = tool.parse(argumentsValue); }
+      catch (error) { const facts = runtime.normalizeFailure(error, { phase: 'parse' }); throw new DispatchExecutionError(facts.code, facts.dispatch, facts.field); }
+      return tool.execute(parsed, signal);
+    },
+    close: async () => runtime.close?.(),
+  };
+  const server = new McpServer(
+    { name: SERVER_NAME, version: runtime.trustedContext.expectedVersion },
+    { capabilities: { tools: {}, ...(runtime.ui ? { resources: {} } : {}) } },
+  );
+  // Capability checks guard execution and resource access. Codex must first
+  // discover the plugin tool metadata before selecting its UI-capable route.
+  const gated = runtime.mode === 'cockpit' && runtime.uiCapabilityRequired === true;
+  const discoverBeforeUi = gated && runtime.trustedContext.surface === 'codex';
+  // serveStdio pins one SDK server instance for the connection's lifetime.
+  // This is a server-issued observation, never a guessed host namespace or approval.
+  const provider = gated && runtime.trustedContext.surface === 'codex' ? Object.freeze({
+    schema_version: 1, authorizes: false, identity_scope: 'sdk_server_instance',
+    connection_id: randomUUID(), server_module: fileURLToPath(import.meta.url),
+    version: runtime.trustedContext.expectedVersion,
+  }) : undefined;
+  const respond = (name, input, result, serialize, context, facts) => toolResult(runtime, name, input, result, serialize, provider, provider ? {
+    client_info: requestMcpClientInfo(server.server, context), capabilities: requestMcpClientCapabilities(server.server, context),
+  } : undefined, facts);
+  const uiAllowed = (context) => !gated || requestDeclaresMcpAppUi(server.server, context, runtime.ui.mimeType);
+  const supportsUi = context => !!runtime.ui && requestDeclaresMcpAppUi(server.server, context, runtime.ui.mimeType);
+  // Discovery needs the exact schemas, but does not execute any tool. Compile
+  // each validator on its first validation, using the same SDK provider/options.
+  // Input validation still precedes execution; successful output is still checked.
+  const schemaProvider = new AjvJsonSchemaValidator();
+  const deferredSchemas = { getValidator(schema) {
+    let validate;
+    return value => (validate ??= schemaProvider.getValidator(schema))(value);
+  } };
+  for (const tool of tools) {
+    const { name, definition, serialize } = tool;
+    server.registerTool(
+      name,
+      {
+        description: definition.description,
+        annotations: definition.annotations,
+        inputSchema: fromJsonSchema(definition.inputSchema, deferredSchemas),
+        ...(definition.outputSchema ? { outputSchema: fromJsonSchema(definition.outputSchema, deferredSchemas) } : {}),
+        ...(definition._meta ? { _meta: definition._meta } : {}),
+      },
+      async (argumentsValue, context) => {
+        const denied = !uiAllowed(context) ? runtime.unsupportedUiCode ?? 'resource_denied'
+          : tool.requiresUi && !supportsUi(context) ? 'host_ui_unsupported' : null;
+        if (denied) {
+          const facts = { code: denied, dispatch: 'not_dispatched' };
+          const failure = runtime.projectToolResult(name, argumentsValue, runtime.failure(denied, name, argumentsValue, facts), facts);
+          return respond(name, argumentsValue, failure, serialize ?? runtime.serialize, context, facts);
+        }
+        let phase = tool.parentOwned ? 'parse' : 'execute';
+        try {
+          let result;
+          if (tool.parentOwned) {
+            const parsed = tool.parse(argumentsValue); phase = 'execute';
+            result = await tool.execute(parsed, context.signal,
+              { client: requestMcpClientInfo(server.server, context), uiSupported: supportsUi(context) });
+          } else result = await dispatchExecutor.execute(argumentsValue, { signal: context.signal, toolName: name });
+          if (runtime.postprocessToolResult) result = await runtime.postprocessToolResult(name, argumentsValue, result,
+            { uiSupported: supportsUi(context), client: requestMcpClientInfo(server.server, context) });
+          return respond(name, argumentsValue, result, serialize ?? runtime.serialize, context);
+        } catch (error) {
+          const facts = runtime.normalizeFailure(error, { phase });
+          const failure = runtime.failure(facts.code, name, argumentsValue, facts);
+          // A local execution/delivery failure is owned here, including malformed
+          // producer output. It never causes re-execution or a second write.
+          const projected = runtime.projectToolResult(name, argumentsValue, failure, facts);
+          return respond(name, argumentsValue, projected, serialize ?? runtime.serialize, context, facts);
+        }
+      },
+    );
+  }
+  if (runtime.ui) {
+    const resource = loadCockpitResource(runtime.ui);
+    server.registerResource(runtime.mode === 'decision' ? 'AGDF Gate Decision' : runtime.ui.label ?? 'AGDF Cockpit', resource.uri, { mimeType: resource.mimeType, _meta: resource._meta },
+      async (_uri, context) => {
+        if (!uiAllowed(context) || runtime.mode === 'decision' && !supportsUi(context)) throw new ProtocolError(ProtocolErrorCode.InvalidParams, "resource_denied");
+        return { contents: [resource] };
+      });
+    if (gated || runtime.mode === 'decision') {
+      // McpServer's list handlers ignore the request context, so the gated surface lists per request.
+      const listedTools = tools.map(({ name, definition }) => ({
+        name, description: definition.description, inputSchema: server.toolInputSchemaJson(name),
+        annotations: definition.annotations, ...(definition._meta ? { _meta: definition._meta } : {}),
+        ...(definition.outputSchema ? { outputSchema: definition.outputSchema } : {}),
+      }));
+      const listedResource = { uri: resource.uri, name: runtime.ui.label ?? 'AGDF Cockpit', mimeType: resource.mimeType, _meta: resource._meta };
+      server.server.removeRequestHandler("tools/list");
+      server.server.setRequestHandler("tools/list", (_request, context) => ({ tools: !discoverBeforeUi && !uiAllowed(context) ? [] : runtime.mode === 'decision' && !supportsUi(context)
+        ? listedTools.filter(tool => !tools.find(entry => entry.name === tool.name)?.requiresUi) : listedTools }));
+      server.server.removeRequestHandler("resources/list");
+      server.server.setRequestHandler("resources/list", (_request, context) => ({ resources: uiAllowed(context) && (runtime.mode !== 'decision' || supportsUi(context)) ? [listedResource] : [] }));
+    }
+  }
+  return Object.assign(server, {
+    closeAgdfRuntime: async () => { await dispatchExecutor.close(); return runtime.close?.(); },
+  });
+}
+
+export function serveAgdfStdio({ runtime, executor, onerror } = {}) {
+  const instances = new Set();
+  const handle = serveStdio(() => {
+    const server = buildAgdfServer({ runtime, executor });
+    instances.add(server);
+    return server;
+  }, {
+    legacy: "serve",
+    onerror: () => onerror?.("AGDF_MCP_TRANSPORT_ERROR"),
+  });
+  return Object.freeze({
+    async close() {
+      // The generation facade is prepared before a client initializes. A host
+      // may cancel that connection without creating any SDK server instance;
+      // its already-owned executor/runtime must still close and prove exit.
+      const owners = instances.size ? [...instances].map(server => () => server.closeAgdfRuntime())
+        : [async () => { await executor?.close(); return runtime.close?.(); }];
+      const results = await Promise.allSettled(owners.map(close => close()));
+      await handle.close();
+      return { confirmed: results.length > 0 && results.every(result => result.status === 'fulfilled' && result.value?.occupancy === 0) };
+    },
+  });
+}
+
+export function createAgdfWorkerExecutor(runtime, options = {}) {
+  return createWorkerDispatchExecutor({
+    surface: runtime.trustedContext.surface,
+    expectedVersion: runtime.trustedContext.expectedVersion,
+    commandGroups: runtime.trustedContext.commandGroups,
+    ...options,
+  });
+}

package/src/ui-capability.js

@@ -0,0 +1,17 @@
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY } from "@modelcontextprotocol/server";
+
+// Extension id under which MCP Apps hosts declare UI support (@modelcontextprotocol/ext-apps EXTENSION_ID).
+export const MCP_APP_UI_EXTENSION = "io.modelcontextprotocol/ui";
+export const requestMcpClientInfo = (server, context) => context?.mcpReq?.envelope?.[CLIENT_INFO_META_KEY] ?? server.getClientVersion();
+export const requestMcpClientCapabilities = (server, context) => context?.mcpReq?.envelope?.[CLIENT_CAPABILITIES_META_KEY] ?? server.getClientCapabilities();
+
+export function declaresMcpAppUi(capabilities, mimeType) {
+  const mimeTypes = capabilities?.extensions?.[MCP_APP_UI_EXTENSION]?.mimeTypes;
+  return Array.isArray(mimeTypes) && mimeTypes.includes(mimeType);
+}
+
+// 2026-07-28 requests carry the capabilities in their envelope; 2025-era connections declare them once
+// in initialize. The SDK does not expose envelope capabilities through getClientCapabilities() here.
+export function requestDeclaresMcpAppUi(server, context, mimeType) {
+  return declaresMcpAppUi(requestMcpClientCapabilities(server, context), mimeType);
+}

package/src/worker-entry.js

@@ -0,0 +1,39 @@
+import { subscribe } from "node:diagnostics_channel";
+import { parentPort, workerData } from "node:worker_threads";
+import { OWNED_LOCK_CHANNEL, createMcpDispatchRuntime } from "create-agdf/mcp-dispatch-runtime";
+import { ownedLockForwarder } from "./worker.js";
+
+function send(message) {
+  parentPort?.postMessage(message);
+}
+
+// Forward lock ownership synchronously. If this thread is terminated while it holds
+// a run lock, the executor releases exactly that lock after the thread has exited.
+subscribe(OWNED_LOCK_CHANNEL, ownedLockForwarder(send));
+
+let runtime, phase = 'setup';
+try {
+  send({ type: 'phase', phase: 'runtime_provenance' });
+  runtime = createMcpDispatchRuntime({ surface: workerData.surface, ...(workerData.commandGroups !== undefined ? { commandGroups: workerData.commandGroups } : {}) });
+  if (runtime.trustedContext.provenanceStatus !== "matched") {
+    send({ type: "failure", code: "runtime_provenance_invalid", dispatch: "not_dispatched" });
+  } else if (runtime.trustedContext.expectedVersion !== workerData.expectedVersion) {
+    send({ type: "failure", code: "runtime_version_mismatch", dispatch: "not_dispatched" });
+  } else {
+    const tool = workerData.toolName ? runtime.tool(workerData.toolName) : runtime.tool(runtime.definition.name);
+    if (!tool) {
+      send({ type: "failure", code: "dispatch_worker_failed", dispatch: "not_dispatched" });
+    } else {
+      phase = 'parse';
+      const parsed = tool.parse(workerData.argumentsValue);
+      phase = 'execute';
+      send({ type: 'phase', phase: 'operation' });
+      const result = await tool.execute(parsed);
+      send({ type: 'phase', phase: 'result' });
+      send({ type: "result", result });
+    }
+  }
+} catch (error) {
+  const facts = runtime?.normalizeFailure(error, { phase }) ?? { code: 'dispatch_worker_failed', dispatch: 'not_dispatched' };
+  send({ type: 'failure', ...facts });
+}