create-agdf 0.20.1 → 0.30.0

package/lib/mcp-lifecycle/service.js

@@ -1,3 +1,4 @@
+import { isRunOwnedDataPath } from '#agdf-core/control-state/run-identity.js';
 import { execHostFileSync } from "../host-command.js";
 import { realpathSync, statSync, readFileSync, lstatSync, existsSync } from "node:fs";
 import { createHash } from 'node:crypto';
@@ -214,8 +215,8 @@ export function runMcpLifecycle({
       runtime: { status: 'not_evaluated', version: expectedVersion }, registration: null };
     try {
       const evidencePath = resolve(selectedTarget, cockpitEvidence);
-      const containment = relative(join(selectedTarget, '.agdf/control/artefacts'), evidencePath);
-      if (containment.startsWith('..') || isAbsolute(containment) || realpathSync(evidencePath) !== evidencePath
+      const containment = relative(selectedTarget, evidencePath).split('\\').join('/');
+      if (!isRunOwnedDataPath(containment) || realpathSync(evidencePath) !== evidencePath
         || lstatSync(evidencePath).size > 65_536) throw Error('AGDF_MCP_COCKPIT_EVIDENCE_INVALID');
       const bytes = readFileSync(evidencePath, 'utf8'), evidence = JSON.parse(bytes);
       const digest = 'sha256:' + createHash('sha256').update(bytes).digest('hex');
@@ -232,8 +233,8 @@ export function runMcpLifecycle({
           return 'sha256:' + createHash('sha256').update(readFileSync(path)).digest('hex');
         };
         for (const ref of evidence.evidence) {
-          const file = resolve(selectedTarget, ref.path), rel = relative(join(selectedTarget, '.agdf/control/artefacts'), file);
-          if (rel.startsWith('..') || isAbsolute(rel) || readDigest(file) !== ref.digest) throw Error('AGDF_MCP_COCKPIT_EVIDENCE_INVALID');
+          const file = resolve(selectedTarget, ref.path), rel = relative(selectedTarget, file).split('\\').join('/');
+          if (!isRunOwnedDataPath(rel) || readDigest(file) !== ref.digest) throw Error('AGDF_MCP_COCKPIT_EVIDENCE_INVALID');
         }
         if (env.AGDF_DISPATCH_PLUGIN_ROOT && (resolve(env.AGDF_DISPATCH_PLUGIN_ROOT) !== evidence.plugin_root
           || existsSync(env.AGDF_DISPATCH_PLUGIN_ROOT) && realpathSync(env.AGDF_DISPATCH_PLUGIN_ROOT) !== evidence.plugin_root))

package/lib/mcp-lifecycle/thread-owner.js

@@ -0,0 +1,164 @@
+import { Worker } from 'node:worker_threads';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import process from 'node:process';
+import { createMcpGenerationPublisher } from './package.js';
+import { GENERATION_LIMITS as L, OWNER_LIMITS, generationMessage, validGenerationMessage,
+  generationFailureReason, ownerFrame, encodeOwnerFrame, decodeOwnerFrame, publicationSelector } from '../mcp-owner-protocol.js';
+
+// The detached retention owner alone owns actual Worker objects and claims.
+// It imports no SDK or domain factory. Protected slots survive uncertain exits.
+export function superviseThreadMcpFacade({ runtime, surface, cockpitDir, cockpitMode, pluginRoot,
+  env, claim, signals = process, deadlineNs } = {}) {
+  const binding = { token: claim.token, connection_epoch: randomUUID(), publication_id: runtime.publication_id };
+  const publicationDeadline = performance.now() + Math.max(0, Number(BigInt(deadlineNs) - process.hrtime.bigint()) / 1e6);
+  const publisher = createMcpGenerationPublisher(runtime, { publicationDeadline });
+  const rows = new Map(), seen = new Set();
+  let generationEpoch, highestGeneration = 0;
+  let facade, facadeExited = false, facadeAck = false, failed = false, pendingBytes = 0, pendingCount = 0;
+  const post = (kind, payload, id, row) => {
+    if (facadeExited) return;
+    facade.postMessage(encodeOwnerFrame(ownerFrame(binding, kind, payload, id, row), binding, { reply: true }));
+  };
+  function release(row, id) {
+    const entry = row.pending.get(id);
+    if (entry) { row.pending.delete(id); pendingBytes -= entry.bytes; --pendingCount; clearTimeout(entry.timer); }
+    return entry;
+  }
+  function transmit(row, message, { orphan = false, bytes = 0 } = {}) {
+    if (!row.worker || row.exited || row.pending.has(message.request_id)
+      || pendingCount >= OWNER_LIMITS.frames || pendingBytes + bytes > OWNER_LIMITS.bytes) throw Error('generation_request_capacity');
+    const entry = { message, orphan, bytes };
+    row.pending.set(message.request_id, entry); ++pendingCount; pendingBytes += bytes;
+    // An expired call is protected, not removed/replayed. A late reply can still
+    // settle ownership; until then its credit and slot remain occupied.
+    entry.timer = setTimeout(() => {
+      // The still-pending exact request protects the slot and claim. A later
+      // validated matching reply can prove completion; timeout alone cannot.
+      if (!orphan) post('failure', { reason: 'generation_response_unknown' }, message.request_id, row);
+    }, message.kind === 'shutdown' ? L.close : L.qualify);
+    row.worker.postMessage(JSON.stringify(message));
+  }
+  function drain(row) {
+    if (!facadeExited || row.exited || row.draining || row.pending.size || row.uncertain) return;
+    row.draining = true;
+    try { transmit(row, generationMessage(row.epoch, row.generation, 'session_inspect', {}, {}, null, randomUUID()), { orphan: true }); }
+    catch { row.uncertain = true; }
+  }
+  function receive(row, wire) {
+    if (typeof wire !== 'string' || Buffer.byteLength(wire) > L.result) { row.uncertain = true; return; }
+    let reply; try { reply = JSON.parse(wire); } catch { row.uncertain = true; return; }
+    if (!validGenerationMessage(reply, { epoch: row.epoch, generation: row.generation, reply: true })) { row.uncertain = true; return; }
+    const entry = row.pending.get(reply.request_id);
+    const expected = { qualify: 'qualified', invoke: 'result', session_inspect: 'status', shutdown: 'closed' }[entry?.message.kind];
+    if (!entry || reply.original_operation_id !== entry.message.original_operation_id
+      || reply.kind !== expected && reply.kind !== 'failure') { row.uncertain = true; return; }
+    release(row, reply.request_id);
+    if (reply.kind === 'closed') row.closeAck = !reply.payload.views && !reply.payload.inflight && !reply.payload.executor && !reply.payload.uncertain;
+    if (entry.message.original_operation_id && (reply.kind === 'failure' || reply.payload?.outcome === 'effect_unknown')) row.unknown.add(entry.message.original_operation_id);
+    const args = entry.message.payload?.arguments;
+    if (entry.message.payload?.name === 'agdf_inspect' && args?.operation === 'operation-status' && reply.payload?.report?.status === 'recorded'
+      && (reply.payload.report.receipt?.operation_id ?? reply.payload.report.receipt?.operation?.operation_id) === args.module.split('/').at(-1)) row.unknown.delete(args.module.split('/').at(-1));
+    if (entry.orphan) {
+      if (reply.kind === 'status' && !reply.payload.inflight && !reply.payload.executor && !reply.payload.uncertain && !row.unknown.size) {
+        try { transmit(row, generationMessage(row.epoch, row.generation, 'shutdown', {}, {}, null, randomUUID()), { orphan: true }); }
+        catch { row.uncertain = true; }
+      } else if (reply.kind !== 'closed') row.uncertain = true;
+    } else {
+      try { post('message', reply, reply.request_id, row); } catch { row.uncertain = true; }
+      drain(row);
+    }
+  }
+  function open(frame) {
+    if (rows.size >= L.slots || rows.has(frame.generation_id) || !frame.generation_epoch
+      || generationEpoch && frame.generation_epoch !== generationEpoch || frame.generation_id <= highestGeneration
+      || highestGeneration === 0 && (frame.generation_id !== 1 || frame.publication_id !== binding.publication_id)
+      || frame.payload?.publication_id !== frame.publication_id) throw Error('generation_capacity_protected');
+    // Re-resolve the actual candidate every time, never reuse the initial image
+    // across async boundaries or accept caller-selected paths.
+    generationEpoch ??= frame.generation_epoch; highestGeneration = frame.generation_id;
+    const initial = frame.generation_id === 1;
+    const expected = publicationSelector(runtime);
+    if (initial && (Object.keys(frame.payload).sort().join() !== Object.keys(expected).sort().join()
+      || Object.keys(expected).some(key => frame.payload[key] !== expected[key]))) throw Error('runtime_candidate_manifest_invalid');
+    // Initial identity is already bound, but never trusted across this async
+    // boundary: acquire below repeats the full fresh inspection under lock.
+    // Replacements additionally resolve through the existing publisher.
+    const selected = initial ? runtime : publisher.resolve(frame.payload);
+    if (selected.executionModel !== 'owner_threads_v1') throw Error('generation_manifest_incompatible');
+    const row = { epoch: frame.generation_epoch, generation: frame.generation_id, publication_id: frame.publication_id,
+      pending: new Map(), unknown: new Set(), uncertain: false, exited: false, closeAck: false };
+    rows.set(row.generation, row);
+    try {
+      const owned = publisher.acquire(selected, { ownerEpoch: row.epoch, generation: row.generation, ...(row.generation === 1 ? { publicationDeadline } : {}) });
+      row.claim = owned;
+      const worker = new Worker(pathToFileURL(join(selected.packageRoot, 'src/generation-thread-entry.js')),
+        { workerData: { epoch: row.epoch, generation: row.generation }, stdin: false, stdout: true, stderr: true, env: { ...env, AGDF_DISPATCH_PLUGIN_ROOT: pluginRoot }, execArgv: [] });
+      row.worker = worker;
+      // Domain output cannot contaminate the facade's public MCP STDOUT.
+      worker.stdout.resume(); worker.stderr.pipe(process.stderr, { end: false });
+      owned.bindOwnedWorker(worker, { confirmedEnd: () => row.closeAck && !row.pending.size && !row.unknown.size && !row.uncertain });
+      worker.on('message', wire => receive(row, wire));
+      worker.once('error', () => { row.uncertain = true; });
+      worker.once('exit', code => {
+        row.exited = true;
+        for (const entry of row.pending.values()) clearTimeout(entry.timer);
+        if (code === 0 && row.closeAck && !row.pending.size && !row.unknown.size && !row.uncertain) rows.delete(row.generation);
+        else { row.uncertain = true; failed = true; }
+        try { post('exit', { code }, randomUUID(), row); } catch { failed = true; }
+      });
+      post('opened', { opened: true }, frame.request_id, row);
+    } catch (error) {
+      if (!row.claim) rows.delete(row.generation);
+      else { row.uncertain = true; failed = true; }
+      throw error;
+    }
+  }
+  return new Promise((resolve, reject) => {
+    facade = new Worker(pathToFileURL(join(runtime.dispatcherRoot, 'lib/mcp-lifecycle/facade-thread-entry.js')),
+      { workerData: { input: { runtime, surface, ...(cockpitDir ? { cockpitDir } : {}), ...(cockpitMode ? { cockpitMode } : {}),
+        pluginRoot, token: claim.token, deadline_ns: deadlineNs }, binding }, env, stdin: true, stdout: true, stderr: true, execArgv: [] });
+    claim.bindOwnedWorker(facade, { confirmedEnd: () => facadeAck && !failed && rows.size === 0 });
+    // Native streams implement actual backpressure in both directions.
+    facade.stdout.pipe(process.stdout, { end: false }); facade.stderr.pipe(process.stderr, { end: false }); process.stdin.pipe(facade.stdin);
+    facade.stdin.on('error', () => {});
+    const stop = () => { try { post('stop', {}, randomUUID()); } catch { failed = true; } };
+    const detach = () => {
+      signals.off('SIGTERM', stop); signals.off('SIGINT', stop); signals.off('disconnect', stop); process.stdin.unpipe(facade.stdin);
+    };
+    signals.on('SIGTERM', stop); signals.on('SIGINT', stop); signals.on('disconnect', stop);
+    facade.on('message', wire => {
+      let frame;
+      try {
+        frame = decodeOwnerFrame(wire, binding);
+        if (seen.has(frame.request_id) || seen.size >= OWNER_LIMITS.history) throw Error('generation_request_capacity');
+        seen.add(frame.request_id);
+        if (frame.kind === 'closed' && frame.generation_id === null && frame.publication_id === binding.publication_id
+          && Object.keys(frame.payload).join() === 'confirmed' && typeof frame.payload.confirmed === 'boolean') {
+          facadeAck = frame.payload.confirmed;
+          // A signalled client may keep public stdin open. After the facade's
+          // own close acknowledgement, finish its real input stream so the
+          // Worker can exit naturally and supply actual lifetime evidence.
+          process.stdin.unpipe(facade.stdin); process.stdin.pause(); facade.stdin.end(); return;
+        }
+        if (frame.kind === 'open') { open(frame); return; }
+        const row = rows.get(frame.generation_id);
+        if (!row || row.epoch !== frame.generation_epoch || row.publication_id !== frame.publication_id
+          || frame.kind !== 'send' || !validGenerationMessage(frame.payload, { epoch: row.epoch, generation: row.generation })
+          || frame.request_id !== frame.payload.request_id) throw Error('generation_input_limit');
+        transmit(row, frame.payload, { bytes: Buffer.byteLength(wire) });
+      } catch (error) {
+        if (frame) try { post('failure', { reason: generationFailureReason(error) }, frame.request_id,
+          { epoch: frame.generation_epoch, generation: frame.generation_id, publication_id: frame.publication_id }); } catch { failed = true; }
+      }
+    });
+    facade.once('error', () => { failed = true; });
+    facade.once('exit', code => {
+      facadeExited = true; detach();
+      for (const row of rows.values()) drain(row);
+      if (code === 0 && facadeAck && !failed && rows.size === 0) resolve({ closed: true, confirmed_exit: true });
+      else reject(Error('AGDF_MCP_FACADE_CLOSE_UNCONFIRMED'));
+    });
+  });
+}

package/lib/mcp-owner-protocol.js

@@ -0,0 +1 @@
+export * from '#agdf-core/runtime/mcp-owner-protocol.js';

package/lib/mcp-protocol-runtime.js

@@ -0,0 +1,308 @@
+import { projectOperationStatusCall } from '#agdf-core/control-inspect/project-operation-call.js';
+import { resolveMcpInput } from '#agdf-core/mcp-input-resolution.js';
+import { withInputResolution } from '#agdf-core/control-state/input-resolution.js';
+import { effectiveConfiguration } from '#agdf-core/resources/configuration.js';
+import { resources } from './runtime/control-context.js';
+import {
+  SKILL_DISPATCH_CONTRACT_VERSION,
+  SKILL_DISPATCH_FUNCTION_DEFINITION,
+  SKILL_DISPATCH_SCHEMA_VERSION,
+  SKILL_DISPATCH_MAX_OUTPUT_BYTES,
+  emptySkillDispatchTiming,
+  parseSkillDispatchFunctionArguments,
+  serializeSkillDispatchResult,
+  SkillDispatchInputError,
+} from "#agdf-core/skill-dispatch/contract.js";
+import { TaskTargetInputError } from '#agdf-core/task-target-resolution.js';
+import { ReadSelectionError } from '#agdf-core/control-inspect/selection.js';
+import { localePack } from '#agdf-core/interaction-presentation.js';
+import { TOOL_ERROR_CONTRACT, TOOL_RESULT_META, describeToolResult, projectToolResult, consumeToolResult, executionFacts, validExecutionFacts, isEphemeralControlCommand } from '#agdf-core/mcp-tool-errors.js';
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { CONTROL_INSPECT_FUNCTION_DEFINITION, parseControlInspectFunctionArguments, serializeControlInspectResult } from "#agdf-core/control-inspect/contract.js";
+import { mcpInputValidationHint } from '#agdf-core/mcp-input-hints.js';
+import { createInspectFailureResult } from "#agdf-core/control-inspect/result.js";
+import { interactionLocales, packageRoot, pluginDefinition } from "./cli/runtime-context.js";
+import { RUN_COMMAND_GROUPS, RUN_COMMAND_LIMITS, commandGroupDefinition, validateRunCommand, validateRunCommandResult, runCommandRequestDigest, schemaDiagnostics } from '#agdf-core/control-state/run-command-schema.js';
+import { creationRunId } from '#agdf-core/control-state/run-identity.js';
+import {
+  digestMcpDispatcherPackage,
+  inspectOwnedMcpRuntimeRoot, MCP_RUNTIME_OWNER, MCP_RUNTIME_MARKER,
+  evaluateDecisionAppQualification, inspectDecisionAppQualification,
+} from "#agdf-core/runtime/plugin-provenance.js";
+
+
+// Compose the canonical structural contract at the existing producing/consuming
+// boundary. The descriptor projector stays dependency-free and policy-pure.
+function checkCommandResult(name, result) {
+  if (Object.hasOwn(RUN_COMMAND_GROUPS, name) && validateRunCommandResult(result).length) {
+    throw Object.assign(new Error('tool_result_invalid'), { facts: { code: 'tool_result_invalid', dispatch: 'unknown' } });
+  }
+}
+// MCP text blocks carry compact JSON; indentation tripled deeply nested schema reports.
+const compactDispatchResult = (value) => serializeSkillDispatchResult(value, { space: 0 });
+const compactInspectResult = (value) => serializeControlInspectResult(value, { space: 0 });
+export function errorSupport(cockpit = false) {
+  return {
+    inputValidationHint: mcpInputValidationHint,
+    isEphemeralControlCommand, toolErrorContract: TOOL_ERROR_CONTRACT, responseLimit: SKILL_DISPATCH_MAX_OUTPUT_BYTES,
+    projectToolResult(name, input = {}, result, facts) {
+      const pack = localePack(interactionLocales, input.presentation_language ?? (cockpit ? 'de' : 'en'));
+      checkCommandResult(name, result);
+      const { _meta, ...domain } = result;
+      const serialize = name === 'agdf_dispatch' ? compactDispatchResult : name === 'agdf_inspect' ? compactInspectResult : JSON.stringify;
+      const checked = JSON.parse(serialize(domain));
+      const projected = projectToolResult(name, input, { ...checked, ...(_meta ? { _meta } : {}) }, pack, facts);
+      // Existing serializers can replace oversized output before projection.
+      // Their terminal instruction must agree with the same bounded guidance.
+      if (checked.outcome === 'evaluator_error' && checked.diagnostics?.some(d => ['dispatch_output_too_large', 'inspect_output_too_large'].includes(d.code))) {
+        const message = projected._meta[TOOL_RESULT_META].message;
+        return { ...projected, recovery: { action: message }, host_action: { ...projected.host_action, text: message } };
+      }
+      return projected;
+    },
+    consumeToolResult(name, result) { checkCommandResult(name, result); return consumeToolResult(name, result); },
+    normalizeFailure(error, { phase = 'execute' } = {}) {
+      if (validExecutionFacts(error?.facts)) return { ...error.facts, ...(error.diagnostic ? { configuration: error.diagnostic } : {}) };
+      if (phase === 'parse' && (error instanceof SkillDispatchInputError || error instanceof TaskTargetInputError || error instanceof ReadSelectionError)) {
+        const facts = { code: error instanceof ReadSelectionError ? 'inspect_input_invalid' : 'dispatch_input_invalid', dispatch: 'not_dispatched', ...(error.field ? { field: error.field } : {}) };
+        return validExecutionFacts(facts) ? facts : { code: 'dispatch_input_invalid', dispatch: 'not_dispatched' };
+      }
+      if (phase === 'parse' && ['command_schema_invalid', 'resource_denied', 'decision_schema_invalid'].includes(error?.code ?? error?.message))
+        return { code: error.code ?? error.message, dispatch: 'not_dispatched' };
+      return executionFacts(error, { phase });
+    },
+  };
+}
+
+function ownedInspection(inspection) {
+  const root = resolve(packageRoot, '..', '..'), markerPath = join(root, MCP_RUNTIME_MARKER);
+  if (!inspection || inspection.status !== 'matched'
+    || inspection.root !== root || inspection.dispatcherRoot !== resolve(packageRoot)
+    || inspection.packageRoot !== join(root, 'node_modules', '@agdf', 'mcp-server')
+    || inspection.markerPath !== markerPath || inspection.version !== pluginDefinition.version) return null;
+  try {
+    const marker = JSON.parse(readFileSync(markerPath, 'utf8'));
+    if (![1, 2].includes(marker.schema_version) || marker.owner !== MCP_RUNTIME_OWNER || marker.version !== pluginDefinition.version
+      || marker.server_digest !== inspection.digest || marker.dispatcher_digest !== inspection.dispatcherDigest
+      || marker.sdk_digest !== inspection.sdkDigest) return null;
+    return Object.freeze({ root, markerPath, serverDigest: inspection.digest, dispatcherDigest: inspection.dispatcherDigest,
+      sdkDigest: inspection.sdkDigest, decisionQualification: marker.decision_app_qualification });
+  } catch { return null; }
+}
+
+export {
+  CONTROL_INSPECT_FUNCTION_DEFINITION,
+  SKILL_DISPATCH_FUNCTION_DEFINITION,
+  parseControlInspectFunctionArguments,
+  parseSkillDispatchFunctionArguments,
+  serializeSkillDispatchResult,
+};
+export { DECISION_UI_URI } from '#agdf-core/mcp-resource-contract.js';
+// The worker executor releases locks of a thread it has seen exit (packages/mcp-server).
+export { OWNED_LOCK_CHANNEL, releaseAbandonedOwnedLock } from '#agdf-core/owned-file-lock.js';
+
+const FAILURE_ACTIONS = Object.freeze({
+  dispatch_busy: "Wait for the active AGDF dispatch to finish and retry once.",
+  dispatch_cancelled: "Retry the AGDF dispatch if it is still required.",
+  dispatch_timeout: "Inspect the original operation status before replaying the identical UUID and request; a timeout does not prove rollback.",
+  dispatch_worker_termination_unconfirmed: "Inspect the original operation status and retained executor; its termination is unconfirmed. Do not start a replacement mutation.",
+  dispatch_worker_failed: "Repair the installed AGDF MCP runtime and retry once.",
+  runtime_version_mismatch: "Install matching AGDF MCP server and dispatcher versions, then retry once.",
+  runtime_provenance_invalid: "Repair the owned AGDF MCP runtime and retry once.",
+});
+
+function createFailureResult(code, runtimeEvidence) {
+  const action = FAILURE_ACTIONS[code] ?? FAILURE_ACTIONS.dispatch_worker_failed;
+  return {
+    schema_version: SKILL_DISPATCH_SCHEMA_VERSION,
+    contract_version: SKILL_DISPATCH_CONTRACT_VERSION,
+    outcome: "evaluator_error",
+    terminal: true,
+    authorizes: false,
+    skill: null,
+    runtime: runtimeEvidence,
+    target: null,
+    control: null,
+    presentation: null,
+    continuation: null,
+    recovery: { action },
+    host_action: {
+      mode: "transmit_recovery_verbatim_and_stop",
+      source: "recovery.action",
+      text: action,
+      allow_surrounding_text: false,
+      may_request_run_or_evidence: false,
+    },
+    timing: emptySkillDispatchTiming(),
+    diagnostics: [{ code }],
+  };
+}
+
+export function inspectMcpDispatcherRuntime() {
+  return dispatcherInspection(inspectOwnedMcpRuntimeRoot(resolve(packageRoot, '..', '..'), pluginDefinition.version));
+}
+
+function dispatcherInspection(observation) {
+  const runtimeDigest = observation?.dispatcherDigest ?? digestMcpDispatcherPackage(packageRoot);
+  const owned = ownedInspection(observation);
+  return Object.freeze({
+    expectedVersion: pluginDefinition.version,
+    packageRoot,
+    skillSet: pluginDefinition.skillSet,
+    interactionLocales,
+    provenanceStatus: owned ? "matched" : "unowned",
+    generationIdentity: owned ? { server_digest: owned.serverDigest, dispatcher_digest: owned.dispatcherDigest, sdk_digest: owned.sdkDigest } : null,
+    runtimeEvidence: Object.freeze({
+      machine_validation: owned ? "local_exact_version_digest" : "unavailable",
+      plugin_root: packageRoot,
+      runtime_digest: runtimeDigest,
+      provenance_status: owned ? "matched" : "unowned",
+    }),
+    decisionQualificationReport: owned ? (client, resourceDigest) => inspectDecisionAppQualification(owned.root, owned.decisionQualification, {
+      client, server_digest: owned.serverDigest, dispatcher_digest: owned.dispatcherDigest, sdk_digest: owned.sdkDigest, resource_digest: resourceDigest,
+    }) : () => ({ qualified: false, reason: 'runtime_provenance_unavailable', authorizes: false }),
+    decisionQualification: owned ? (client, resourceDigest) => evaluateDecisionAppQualification(owned.root, owned.decisionQualification, {
+      client, server_digest: owned.serverDigest, dispatcher_digest: owned.dispatcherDigest,
+      sdk_digest: owned.sdkDigest, resource_digest: resourceDigest,
+    }) : () => false,
+  });
+}
+
+export function configuredMcpCommandGroups(env = process.env) {
+  if (env.AGDF_MCP_COMMAND_GROUPS === undefined) return Object.keys(RUN_COMMAND_GROUPS);
+  const values = env.AGDF_MCP_COMMAND_GROUPS === '' ? [] : env.AGDF_MCP_COMMAND_GROUPS.split(',');
+  if (new Set(values).size !== values.length || values.some(group => !Object.hasOwn(RUN_COMMAND_GROUPS, group))) throw Error('AGDF_MCP_COMMAND_GROUPS_INVALID');
+  return values;
+}
+
+const unwrapped = () => { throw Object.assign(Error('generation_unavailable'), { code: 'generation_unavailable', dispatch: 'not_dispatched' }); };
+
+export function composeMcpProtocolRuntime({ surface, inspected = inspectMcpDispatcherRuntime(), commandGroups = configuredMcpCommandGroups(), execute = unwrapped, executeInspect = unwrapped, executeCommand = unwrapped, lookupOriginal, executionContext, inputContext } = {}) {
+  const trustedContext = Object.freeze({
+    surface,
+    expectedVersion: inspected.expectedVersion,
+    skillSet: inspected.skillSet,
+    interactionLocales: inspected.interactionLocales,
+    provenanceStatus: inspected.provenanceStatus ?? "unowned",
+    commandGroups: Object.freeze([...commandGroups]),
+    decisionQualification: inspected.decisionQualification ?? (() => false),
+    decisionQualificationReport: inspected.decisionQualificationReport ?? (() => ({ qualified: false, reason: 'host_context_unavailable', authorizes: false })),
+  });
+  const parse = (argumentsValue) => parseSkillDispatchFunctionArguments(argumentsValue, trustedContext);
+  const failureEvidence = { ...inspected.runtimeEvidence, expected_version: inspected.expectedVersion };
+  const rawTools = [
+    Object.freeze({ name: SKILL_DISPATCH_FUNCTION_DEFINITION.name, definition: SKILL_DISPATCH_FUNCTION_DEFINITION, parse, execute, serialize: compactDispatchResult }),
+    Object.freeze({
+      name: CONTROL_INSPECT_FUNCTION_DEFINITION.name,
+      definition: CONTROL_INSPECT_FUNCTION_DEFINITION,
+      parentOwned: value => value?.operation === 'doctor',
+      parse: (argumentsValue) => parseControlInspectFunctionArguments(argumentsValue, trustedContext),
+      execute: (input, signal) => executeInspect(input, { signal }),
+      serialize: compactInspectResult,
+    }),
+    ...commandGroups.map(group => Object.freeze({ name: group, definition: commandGroupDefinition(group),
+      parentOwned: input => group === 'agdf_record' && ['material.stage', 'planned_material.stage'].includes(input?.command?.kind)
+        || group === 'agdf_prepare' && input?.command?.kind === 'presentation.deliver',
+      parse: argumentsValue => {
+        const errors = validateRunCommand(group, argumentsValue);
+        if (errors.length) throw Error('command_schema_invalid');
+        return argumentsValue;
+      }, execute: (input, signal, host) => executeCommand(group, input, signal, host), serialize: value => JSON.stringify(value) })),
+  ];
+  const contexts = new WeakMap();
+  const normalize = (name, args) => {
+    if (contexts.has(args)) return contexts.get(args);
+    if (inputContext) return { ...inputContext, arguments: args };
+    const definition = rawTools.find(tool => tool.name === name)?.definition;
+    if (!definition) throw Error('command_group_unsupported');
+    return resolveMcpInput(definition, args, { defaults: resources.defaults, lookupOriginal, executionContext,
+      runtimeRoots: [resources.packageRoot, resources.generatedRoot, dirname(dirname(resources.contractsRoot)), ...(resources.templatesRoot ? [dirname(dirname(resources.templatesRoot))] : [])] });
+  };
+  const tools = Object.freeze(rawTools.map(tool => Object.freeze({ ...tool,
+    parse(args) {
+      const selected = normalize(tool.name, args), parsed = tool.parse(selected.arguments);
+      contexts.set(parsed, selected); return parsed;
+    },
+    execute(input, signal, host) {
+      const selected = contexts.get(input) ?? inputContext;
+      return withInputResolution(selected?.resolution, () => tool.execute(input, signal, host), selected?.original === true);
+    },
+  })));
+  if (tools.filter(tool => Object.hasOwn(RUN_COMMAND_GROUPS, tool.name)).reduce((bytes, tool) => bytes + Buffer.byteLength(JSON.stringify(tool.definition)), 0) > RUN_COMMAND_LIMITS.aggregate_definition_bytes) throw Error('command_aggregate_definition_budget_exceeded');
+  return Object.freeze({
+    ...errorSupport(),
+    definition: SKILL_DISPATCH_FUNCTION_DEFINITION,
+    parse,
+    execute,
+    tools,
+    prepareInput(name, args) {
+      if (!rawTools.some(tool => tool.name === name)) return args;
+      const selected = normalize(name, args); contexts.set(selected.arguments, selected); return selected.arguments;
+    },
+    inputContextFor(input) {
+      const selected = contexts.get(input);
+      return selected ? { resolution: selected.resolution, original: selected.original } : undefined;
+    },
+    validatePublicInput(name, args) {
+      const definition = tools.find(tool => tool.name === name)?.definition;
+      if (!definition) return false;
+      if (schemaDiagnostics(args, definition.inputSchema).length) throw Object.assign(Error('command_schema_invalid'), { facts: { code: 'command_schema_invalid', dispatch: 'not_dispatched' } });
+      return true;
+    },
+    configurationProjection(input) {
+      const selected = contexts.get(input) ?? inputContext;
+      return selected?.resolution ? effectiveConfiguration(selected.resolution.configuration, selected.original ? 'original_operation' : 'current') : null;
+    },
+    producerIdentity: inspected.generationIdentity ?? null,
+    tool: name => tools.find(tool => tool.name === name) ?? null,
+    serialize: compactDispatchResult,
+    failure(code, toolName = SKILL_DISPATCH_FUNCTION_DEFINITION.name, argumentsValue, { dispatch = 'unknown', field, cause_code, worker_phase, elapsed_ms, configuration } = {}) {
+      const facts = { code, dispatch, ...(field ? { field } : {}),
+        ...(cause_code ? { cause_code } : {}), ...(worker_phase ? { worker_phase } : {}) };
+      const finish = value => {
+        if (configuration) value = { ...value, diagnostics: [...(value.diagnostics ?? []), configuration] };
+        if (validExecutionFacts(facts)) {
+          const { code: _code, dispatch: _dispatch, ...details } = facts;
+          if (value.diagnostics?.length) value = { ...value, diagnostics: value.diagnostics.map((d, i) => i === 0 ? { ...d, ...details } : d) };
+          else if (facts.cause_code || facts.worker_phase) value = { ...value, diagnostics: [{ code, ...details }] };
+        }
+        const message = describeToolResult(toolName, argumentsValue ?? {}, value,
+          localePack(interactionLocales, argumentsValue?.presentation_language ?? 'en'), facts).message;
+        return value.terminal ? { ...value, recovery: { action: message }, host_action: { ...value.host_action, text: message } } : value;
+      };
+      if (Object.hasOwn(RUN_COMMAND_GROUPS, toolName)) {
+        const valid = argumentsValue && validateRunCommand(toolName, argumentsValue).length === 0;
+        if (valid && ['presentation.deliver', 'material.stage', 'planned_material.stage'].includes(argumentsValue.command.kind)) return finish({ schema_version: '1', outcome: 'rejected',
+          reason: argumentsValue.command.kind.endsWith('material.stage') ? 'material_state_unavailable' : 'delivery_state_unavailable',
+          operation_id: argumentsValue.operation_id, request_digest: runCommandRequestDigest(argumentsValue), authorizes: false,
+          recovery: argumentsValue.command.kind.endsWith('material.stage')
+            ? 'Read material.stage/status for the original transfer in this generation. After generation loss restage identical semantic bytes, preserving the original future canonical write UUID. No gate or Run mutation was attempted.'
+            : 'Observe this same prepared presentation/delivery. No gate or Run mutation was attempted; do not create another question. Read its exact document if delivery access is unconfirmed.' });
+        return finish({ schema_version: '1', outcome: dispatch === 'not_dispatched' ? 'rejected' : 'effect_unknown', reason: code,
+          operation_id: valid ? argumentsValue.operation_id : null, request_digest: valid ? runCommandRequestDigest(argumentsValue) : null,
+          binding: valid ? argumentsValue.command.kind === 'project.initialize' ? { target_id: argumentsValue.target_id, kind: 'project.initialize' } : { target_id: argumentsValue.target_id, run_id: argumentsValue.command.kind === 'run.create' ? creationRunId(argumentsValue.operation_id) : argumentsValue.run_id,
+            expected_revision_id: argumentsValue.command.kind === 'run.create' ? null : argumentsValue.expected_revision_id, kind: argumentsValue.command.kind } : null,
+          ...(valid && argumentsValue.command.kind === 'project.initialize' && dispatch !== 'not_dispatched' ? { next_calls: [projectOperationStatusCall(argumentsValue)] } : {}),
+          dispatch, authorizes: false, recovery: dispatch === 'not_dispatched' ? 'No command was dispatched by this attempt.'
+            : valid && argumentsValue.command.kind === 'project.initialize' ? 'Use the supplied project.initialize/original-UUID operation-status call, without Run/revision; retain the exact original setup request.'
+            : 'Inspect operation-status with the original UUID and preserve the exact original payload. Do not infer non-execution or create another decision.' });
+      }
+      if (toolName === CONTROL_INSPECT_FUNCTION_DEFINITION.name) {
+        const action = FAILURE_ACTIONS[code] ?? FAILURE_ACTIONS.dispatch_worker_failed;
+        return finish(createInspectFailureResult(code, failureEvidence, action, { elapsedMs: elapsed_ms }));
+      }
+      return finish(createFailureResult(code, failureEvidence));
+    },
+    trustedContext,
+  });
+}
+
+export function createMcpTransportRuntime(options = {}) {
+  return composeMcpProtocolRuntime(options);
+}
+
+export async function createMcpDecisionTransportRuntime({ runtime, ui } = {}) {
+  const { composeMcpDecisionProtocol } = await import('./mcp-decision-protocol.js');
+  return composeMcpDecisionProtocol({ runtime, ui });
+}