create-agdf 0.14.4 → 0.20.0

package/lib/mcp-dispatch-runtime.js

@@ -0,0 +1,360 @@
+import { createCoreServices } from "#agdf-core";
+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 } from '#agdf-core/mcp-tool-errors.js';
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { CONTROL_INSPECT_FUNCTION_DEFINITION, parseControlInspectFunctionArguments, serializeControlInspectResult } from "#agdf-core/control-inspect/contract.js";
+import { createInspectFailureResult } from "#agdf-core/control-inspect/service.js";
+import { assertMcpControlReadBoundary } from "#agdf-core/control-read-boundary.js";
+import { interactionLocales, packageRoot, pluginDefinition } from "./cli/runtime-context.js";
+import { RUN_COMMAND_GROUPS, RUN_COMMAND_LIMITS, commandGroupDefinition, validateRunCommand, runCommandRequestDigest } from '#agdf-core/control-state/run-command-contract.js';
+import {
+  digestDirectory,
+  digestMcpDispatcherPackage,
+  digestMcpSdkRuntime,
+  evaluateDecisionAppQualification, inspectDecisionAppQualification,
+} from "#agdf-core/runtime/plugin-provenance.js";
+
+const MCP_RUNTIME_OWNER = "create-agdf:mcp-runtime";
+
+function errorSupport(cockpit = false) {
+  return {
+    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'));
+      const { _meta, ...domain } = result;
+      const serialize = name === 'agdf_dispatch' ? serializeSkillDispatchResult : name === 'agdf_inspect' ? serializeControlInspectResult : 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,
+    normalizeFailure(error, { phase = 'execute' } = {}) {
+      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 });
+    },
+  };
+}
+
+export async function createMcpCockpitRuntime({ surface, cockpitDir, cockpitMode, inspected = inspectMcpDispatcherRuntime() } = {}) {
+  const pluginMode = cockpitMode === 'plugin';
+  if (cockpitMode !== undefined && !pluginMode || pluginMode && (surface !== 'codex' || cockpitDir !== undefined)
+    || !pluginMode && (!['codex', 'claude'].includes(surface) || typeof cockpitDir !== 'string' || !isAbsolute(cockpitDir))) throw new TypeError('AGDF_COCKPIT_TARGET_INVALID');
+  let root;
+  try { if (!pluginMode) { root = realpathSync(cockpitDir); if (!lstatSync(root).isDirectory()) throw Error(); } }
+  catch { throw new TypeError('AGDF_COCKPIT_TARGET_INVALID'); }
+  const [{ COCKPIT_RENDER_DEFINITION, COCKPIT_PLUGIN_RENDER_DEFINITION, COCKPIT_READ_DEFINITION, COCKPIT_UI_URI, COCKPIT_MIME, COCKPIT_LIMITS, parseCockpitArguments, parsePluginCockpitArguments },
+    { createCockpitSessionService }, { READ_LIMITS }] = await Promise.all([
+    import("#agdf-core/control-inspect/cockpit-contract.js"),
+    import("#agdf-core/control-inspect/cockpit-session.js"),
+    import("#agdf-core/control-read/snapshot.js"),
+  ]);
+  const session = createCockpitSessionService(root, { pluginMode });
+  const renderDefinition = pluginMode ? COCKPIT_PLUGIN_RENDER_DEFINITION : COCKPIT_RENDER_DEFINITION;
+  const tools = [
+    { name: renderDefinition.name, definition: renderDefinition,
+      parse: value => pluginMode ? parsePluginCockpitArguments(value) : parseCockpitArguments(value, true), execute: value => session.render(value) },
+    { name: COCKPIT_READ_DEFINITION.name, definition: COCKPIT_READ_DEFINITION,
+      parse: parseCockpitArguments, execute: (value, signal) => session.read(value, signal) },
+  ];
+  // Claude Code renders no MCP app UI today; its cockpit stays hidden until a client declares support.
+  return Object.freeze({ ...errorSupport(true), mode: 'cockpit', definition: renderDefinition, tools,
+    uiCapabilityRequired: pluginMode || surface === 'claude', responseLimit: READ_LIMITS.response,
+    ...(pluginMode ? { unsupportedUiCode: 'host_ui_unsupported' } : {}),
+    ui: Object.freeze({ uri: COCKPIT_UI_URI, mimeType: COCKPIT_MIME, limit: COCKPIT_LIMITS.html,
+      ...(pluginMode ? { label: 'Cockpit' } : {}) }),
+    serialize: value => JSON.stringify(value), failure: code => code === 'host_ui_unsupported'
+      ? { ...session.failure(code), retryable: false,
+        next_action: 'Use a Codex session that advertises MCP App UI support; configuration or tool discovery alone cannot render Cockpit.' }
+      : session.failure(code), close: () => session.close(),
+    inspectOwnership: () => session.inspectOwnership(),
+    trustedContext: Object.freeze({ surface, expectedVersion: inspected.expectedVersion, provenanceStatus: inspected.provenanceStatus }),
+  });
+}
+
+function readOwnedRuntimeMarker(dispatcherDigest) {
+  const root = resolve(packageRoot, "..", "..");
+  const markerPath = join(root, ".agdf-mcp-owned.json");
+  const serverRoot = join(root, "node_modules", "@agdf", "mcp-server");
+  const sdkServerRoot = join(root, "node_modules", "@modelcontextprotocol", "server");
+  const sdkCoreRoot = join(root, "node_modules", "@modelcontextprotocol", "core");
+  const sdkClientRoot = join(root, "node_modules", "@modelcontextprotocol", "client");
+  const sdkV1Root = join(root, "node_modules", "@modelcontextprotocol", "sdk");
+  try {
+    if (lstatSync(packageRoot).isSymbolicLink() || !existsSync(markerPath)
+        || !existsSync(serverRoot) || !existsSync(sdkServerRoot) || !existsSync(sdkCoreRoot)
+        || existsSync(sdkClientRoot) || existsSync(sdkV1Root)) return null;
+    if ([serverRoot, sdkServerRoot, sdkCoreRoot].some((path) => {
+      const stats = lstatSync(path);
+      return !stats.isDirectory() || stats.isSymbolicLink();
+    })) return null;
+    const marker = JSON.parse(readFileSync(markerPath, "utf8"));
+    const serverManifest = JSON.parse(readFileSync(join(serverRoot, "package.json"), "utf8"));
+    const sdkServerManifest = JSON.parse(readFileSync(join(sdkServerRoot, "package.json"), "utf8"));
+    const sdkCoreManifest = JSON.parse(readFileSync(join(sdkCoreRoot, "package.json"), "utf8"));
+    const serverDigest = digestDirectory(serverRoot);
+    const sdkDigest = digestMcpSdkRuntime(root);
+    if (![1, 2].includes(marker.schema_version)
+        || marker.owner !== MCP_RUNTIME_OWNER
+        || marker.version !== pluginDefinition.version
+        || serverManifest.name !== "@agdf/mcp-server"
+        || serverManifest.version !== pluginDefinition.version
+        || serverManifest.dependencies?.["create-agdf"] !== pluginDefinition.version
+        || serverManifest.dependencies?.["@modelcontextprotocol/server"] !== "2.0.0"
+        || sdkServerManifest.name !== "@modelcontextprotocol/server"
+        || sdkServerManifest.version !== "2.0.0"
+        || sdkCoreManifest.name !== "@modelcontextprotocol/core"
+        || sdkCoreManifest.version !== "2.0.0"
+        || marker.dispatcher_digest !== dispatcherDigest
+        || marker.server_digest !== serverDigest
+        || marker.sdk_digest !== sdkDigest) return null;
+    return Object.freeze({ markerPath, root, dispatcherDigest, serverDigest, 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/control-state/run-state-writer.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() {
+  const runtimeDigest = digestMcpDispatcherPackage(packageRoot);
+  const owned = readOwnedRuntimeMarker(runtimeDigest);
+  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;
+}
+
+export function createMcpDispatchRuntime({ surface, inspected = inspectMcpDispatcherRuntime(), commandGroups = configuredMcpCommandGroups(), runtimeControl } = {}) {
+  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 services = createCoreServices({ resources, observers: {
+    runtimeEvidence: inspected.runtimeEvidence,
+    validateControlReadBoundary: assertMcpControlReadBoundary,
+    commandGroups, runtimeControl,
+  } });
+  const execute = services.dispatch;
+  const executeInspect = services.inspect;
+  const parse = (argumentsValue) => parseSkillDispatchFunctionArguments(argumentsValue, trustedContext);
+  const failureEvidence = { ...inspected.runtimeEvidence, expected_version: inspected.expectedVersion };
+  const tools = Object.freeze([
+    Object.freeze({ name: SKILL_DISPATCH_FUNCTION_DEFINITION.name, definition: SKILL_DISPATCH_FUNCTION_DEFINITION, parse, execute, serialize: serializeSkillDispatchResult }),
+    Object.freeze({
+      name: CONTROL_INSPECT_FUNCTION_DEFINITION.name,
+      definition: CONTROL_INSPECT_FUNCTION_DEFINITION,
+      parse: (argumentsValue) => parseControlInspectFunctionArguments(argumentsValue, trustedContext),
+      execute: executeInspect,
+      serialize: serializeControlInspectResult,
+    }),
+    ...commandGroups.map(group => Object.freeze({ name: group, definition: commandGroupDefinition(group),
+      parse: argumentsValue => {
+        const errors = validateRunCommand(group, argumentsValue);
+        if (errors.length) throw Error('command_schema_invalid');
+        return argumentsValue;
+      }, execute: input => services.command(group, input), serialize: value => JSON.stringify(value) })),
+  ]);
+  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,
+    tool(name) {
+      return tools.find((entry) => entry.name === name) ?? null;
+    },
+    serialize: serializeSkillDispatchResult,
+    failure(code, toolName = SKILL_DISPATCH_FUNCTION_DEFINITION.name, argumentsValue, { dispatch = 'unknown', field, cause_code, worker_phase } = {}) {
+      const facts = { code, dispatch, ...(field ? { field } : {}),
+        ...(cause_code ? { cause_code } : {}), ...(worker_phase ? { worker_phase } : {}) };
+      const finish = value => {
+        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;
+        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 ? { target_id: argumentsValue.target_id, run_id: argumentsValue.run_id, expected_revision_id: argumentsValue.expected_revision_id, kind: argumentsValue.command.kind } : null,
+          dispatch, authorizes: false, recovery: dispatch === 'not_dispatched' ? 'No command was dispatched by this attempt.'
+            : '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));
+      }
+      return finish(createFailureResult(code, failureEvidence));
+    },
+    trustedContext,
+  });
+}
+
+// Only the App-capable adapter loads ephemeral view owners; Copilot/default Core
+// projections do not acquire a hidden dependency on the private cockpit reader.
+export async function createMcpDecisionRuntime({ runtime, ui, appOnlyMediationQualified = false } = {}) {
+  if (!runtime || runtime.trustedContext.surface !== 'codex') throw Error('decision_runtime_surface_invalid');
+  const [{ createDecisionSessionService }, { decisionActionDefinition, validateDecisionAction },
+    { COCKPIT_READ_DEFINITION, parseCockpitArguments }] = await Promise.all([
+    import('#agdf-core/control-inspect/decision-session.js'), import('#agdf-core/control-state/decision-action-contract.js'),
+    import('#agdf-core/control-inspect/cockpit-contract.js'),
+  ]);
+  const groups = runtime.trustedContext.commandGroups, session = createDecisionSessionService({ groups, appOnlyMediationQualified,
+    qualification: ({ client }) => appOnlyMediationQualified === true
+      || runtime.trustedContext.decisionQualification(client, ui.digest) === true });
+  const facade = decisionActionDefinition(groups);
+  const tools = runtime.tools.map(tool => tool.name === 'agdf_prepare' ? { ...tool,
+    definition: { ...tool.definition, _meta: { ui: { resourceUri: ui.uri, visibility: ['model', 'app'] } } } } : tool);
+  tools.push({ name: COCKPIT_READ_DEFINITION.name, definition: COCKPIT_READ_DEFINITION, requiresUi: true, parentOwned: true,
+    parse: parseCockpitArguments, execute: (input, signal) => session.read(input, signal), serialize: value => JSON.stringify(value) });
+  if (facade) tools.push({ name: facade.name, definition: facade, requiresUi: true, parentOwned: true,
+    parse: input => { if (validateDecisionAction(input, facade.inputSchema.properties.action.enum).length) throw Error('decision_schema_invalid'); return input; },
+    execute: (input, signal, host) => session.action(input, host), serialize: value => JSON.stringify(value) });
+  const bytes = tools.filter(tool => Object.hasOwn(RUN_COMMAND_GROUPS, tool.name) || tool.name === facade?.name)
+    .reduce((sum, tool) => sum + Buffer.byteLength(JSON.stringify(tool.definition)), 0);
+  if (bytes > RUN_COMMAND_LIMITS.aggregate_definition_bytes) { await session.close(); throw Error('command_aggregate_definition_budget_exceeded'); }
+  return Object.freeze({ ...runtime, tools: Object.freeze(tools), ui, mode: 'decision',
+    tool: name => tools.find(tool => tool.name === name) ?? null,
+    async postprocessToolResult(name, input, result, { uiSupported, client } = {}) {
+      if (name === 'agdf_inspect' && input.operation === 'native-qualification' && result.report?.available) {
+        return { ...result, report: { ...result.report, ui_rendering_support: uiSupported ? 'supported' : 'unsupported',
+          action_qualification: runtime.trustedContext.decisionQualificationReport(client, ui.digest),
+          enabled_command_groups: [...groups], authorizes: false } };
+      }
+      if (name !== 'agdf_prepare' || input.command?.kind !== 'presentation.prepare') return result;
+      const delivered = uiSupported ? await session.open(input, result, { client })
+        : { ...result, app_capability: 'unavailable', app_reason: 'host_ui_unsupported' };
+      const prepared = result.family_result;
+      if (typeof prepared?.text !== 'string') return delivered;
+      // Capability advertisement and an emitted resource do not prove that this
+      // request surface displays it (in particular a remote/iPad Chat). Until an
+      // actual display observation exists, send the complete decision once.
+      const displayed = delivered.app_capability === 'available' && delivered.app_display === 'confirmed';
+      const text = displayed && typeof prepared.companion_text === 'string'
+        ? prepared.companion_text : prepared.text;
+      return { ...delivered, presentation_delivery: { mode: displayed ? 'native_plus_chat' : 'full_chat', display: displayed ? 'confirmed' : 'unconfirmed',
+        text, presentation_id: prepared.presentation_id, revision_id: prepared.revision_id,
+        document_digest: prepared.document_digest ?? prepared.artefact_digest, document_language: prepared.document_language ?? null,
+        ...(prepared.preview_review ? { preview_review: { operation: 'presentation-preview', version: prepared.preview_review.descriptor.version,
+          content_digest: prepared.preview_review.rendered_digest, access_state: displayed ? 'native_bound' : 'not_observed',
+          target_id: input.target_id, run_id: input.run_id, gate: 'PRD', expected_revision_id: input.expected_revision_id, presentation_id: prepared.presentation_id } } : {}),
+        instruction: 'Forward this exact Chat text once. Do not append a second decision request. On a human request to read the document, use presentation-document with this exact binding and every returned cursor; deliver all ordered chunks in the same Chat before requesting a decision. A local file link is not remote access proof.'
+          + (prepared.preview_review ? ' The required preview uses presentation-preview with the supplied exact selectors and every cursor. Offer only supported isolated rendering of those exact bytes. If this surface cannot show it, state that access is unavailable and the review remains open; never call raw HTML, a local link or an unopened resource a viewed preview.' : ''),
+        authorizes: false } };
+    },
+    failure(code, name, input, dispatch) {
+      return name === 'agdf_decision_action' ? { schema_version: '1', outcome: dispatch?.dispatch === 'not_dispatched' ? 'rejected' : 'effect_unknown',
+        reason: code, operation_id: input?.operation_id ?? null, authorizes: false, recovery: 'Inspect the original UUID; do not infer non-execution or submit another decision.' }
+        : name === 'agdf_cockpit_read' ? { schema_version: '1', outcome: 'rejected', reason: code, authorizes: false } : runtime.failure(code, name, input, dispatch);
+    },
+    close: () => session.close(), inspectOwnership: () => session.inspectOwnership(),
+  });
+}
+

package/lib/mcp-lifecycle/adapter-contract.js

@@ -0,0 +1,54 @@
+import { claudeAdapter } from "./adapters/claude.js";
+import { codexAdapter } from "./adapters/codex.js";
+import { copilotAdapter } from "./adapters/copilot.js";
+import { opencodeAdapter } from "./adapters/opencode.js";
+
+const REQUIRED = Object.freeze([
+  "nativeScope",
+  "probeHost",
+  "resolveSources",
+  "inspect",
+  "createTransaction",
+  "referenceIdentity",
+  "permissionEffect",
+]);
+
+export function validateMcpHostAdapter(adapter) {
+  const errors = [];
+  if (!adapter || typeof adapter !== "object") errors.push("adapter");
+  if (!["codex", "claude", "opencode", "copilot"].includes(adapter?.surface)) errors.push("surface");
+  for (const method of REQUIRED) if (typeof adapter?.[method] !== "function") errors.push(method);
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze(errors) });
+}
+
+export function validateMcpResolvedSources(sources) {
+  const errors = [];
+  if (!Array.isArray(sources) || !sources.length) return Object.freeze({ valid: false, errors: Object.freeze(["sources"]) });
+  for (const [index, source] of sources.entries()) {
+    if (!source || typeof source !== "object") { errors.push(`source:${index}`); continue; }
+    if (typeof source.id !== "string" || !source.id.trim()) errors.push(`source:${index}:id`);
+    if (typeof source.path !== "string" || !source.path.trim()) errors.push(`source:${index}:path`);
+    if (!Number.isInteger(source.priority)) errors.push(`source:${index}:priority`);
+    if (typeof source.selected !== "boolean") errors.push(`source:${index}:selected`);
+  }
+  if (sources.filter((source) => source?.selected === true).length !== 1) errors.push("selected_source");
+  if (new Set(sources.map((source) => source?.id)).size !== sources.length) errors.push("source_ids");
+  if (new Set(sources.map((source) => source?.priority)).size !== sources.length) errors.push("source_priorities");
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze([...new Set(errors)]) });
+}
+
+const entries = [codexAdapter, claudeAdapter, opencodeAdapter, copilotAdapter];
+for (const adapter of entries) {
+  const validation = validateMcpHostAdapter(adapter);
+  if (!validation.valid) throw new Error(`AGDF_MCP_ADAPTER_INVALID:${adapter?.surface ?? "unknown"}:${validation.errors.join(",")}`);
+}
+
+const registry = new Map(entries.map((adapter) => [adapter.surface, adapter]));
+
+export function resolveMcpHostAdapter(surface) {
+  const adapter = registry.get(surface);
+  if (!adapter) throw new Error("AGDF_MCP_SURFACE_UNSUPPORTED");
+  return adapter;
+}
+
+export const mcpHostAdapters = Object.freeze(Object.fromEntries(entries.map((adapter) => [adapter.surface, adapter])));

package/lib/mcp-lifecycle/adapters/claude.js

@@ -0,0 +1,123 @@
+import { inheritedPermissionEffect, referenceIdentityForSurface } from "./file-utils.js";
+
+function nativeScope(scope) { return scope === "project" ? "local" : "user"; }
+
+function commandArgs(action, scope, spec) {
+  if (action === "enable") return ["mcp", "add", "--transport", "stdio", "--scope", nativeScope(scope), "agdf", "--", spec.command, ...spec.args];
+  return ["mcp", "remove", "--scope", nativeScope(scope), "agdf"];
+}
+
+function parse(output) {
+  const fields = new Map(String(output).split("\n").map((line) => {
+    const match = /^\s*([^:]+):\s*(.*)$/u.exec(line);
+    return match ? [match[1], match[2]] : ["", ""];
+  }).filter(([name]) => name));
+  const scopeText = fields.get("Scope") ?? "";
+  const observedScope = scopeText.startsWith("Local config") ? "local"
+    : scopeText.startsWith("Project config") ? "shared_project"
+      : scopeText.startsWith("User config") ? "user" : "unknown";
+  const argsText = fields.get("Args") ?? "";
+  const suffix = " --surface claude";
+  const observed = fields.get("Type") === "stdio" && argsText.endsWith(suffix)
+    ? { command: fields.get("Command"), args: [argsText.slice(0, -suffix.length), "--surface", "claude"] }
+    : null;
+  return { fields, observedScope, observed };
+}
+
+function sources({ scope }) {
+  const selectedNative = nativeScope(scope);
+  return [
+    { id: "local", path: "claude:local:agdf", priority: 10, selected: selectedNative === "local", status: "absent" },
+    { id: "shared_project", path: "claude:project:agdf", priority: 20, selected: false, status: "absent" },
+    { id: "user", path: "claude:user:agdf", priority: 30, selected: selectedNative === "user", status: "absent" },
+  ];
+}
+
+function inspect({ scope, target, spec, exec }) {
+  const selectedNative = nativeScope(scope);
+  const sourceList = sources({ scope });
+  try {
+    const parsed = parse(exec("claude", ["mcp", "get", "agdf"], { cwd: target, encoding: "utf8", stdio: "pipe" }));
+    const source = sourceList.find((item) => item.id === parsed.observedScope);
+    if (!source) return { status: "invalid", selected_status: "invalid", effective_status: "invalid",
+      selected_source: selectedNative, effective_source: "unknown", sources: sourceList, native_scope: selectedNative,
+      path: `claude:${selectedNative}:agdf`, identity: null, observed: parsed.observed };
+    const matched = parsed.fields.get("Type") === "stdio" && parsed.fields.get("Command") === spec.command
+      && parsed.fields.get("Args") === spec.args.join(" ");
+    source.status = matched ? "matched" : "foreign";
+    const selected = sourceList.find((item) => item.selected);
+    const conflict = selectedNative === "user" && ["local", "shared_project"].includes(parsed.observedScope);
+    return { status: conflict ? "precedence_conflict" : source.status, selected_status: selected.status,
+      effective_status: source.status, selected_source: selectedNative, effective_source: source.id,
+      sources: sourceList.map((item) => Object.freeze({ ...item, source: item.id })), native_scope: selectedNative, path: selected.path,
+      identity: null, observed: parsed.observed };
+  } catch (error) {
+    const output = `${String(error?.stdout ?? "")}\n${String(error?.stderr ?? "")}`;
+    if (error?.status === 1 && output.includes('No MCP server named "agdf"')) {
+      return { status: "absent", selected_status: "absent", effective_status: "absent",
+        selected_source: selectedNative, effective_source: selectedNative,
+        sources: sourceList.map((item) => Object.freeze({ ...item, source: item.id })),
+        native_scope: selectedNative, path: `claude:${selectedNative}:agdf`, identity: null };
+    }
+    throw new Error("AGDF_MCP_CLAUDE_INSPECTION_FAILED");
+  }
+}
+
+function transaction({ action, scope, target, spec, previousSpec, exec }) {
+  const current = inspect({ scope, target, spec, exec });
+  if (current.status === "precedence_conflict") throw new Error("AGDF_MCP_REGISTRATION_PRECEDENCE_CONFLICT");
+  if (["foreign", "invalid"].includes(current.selected_status) && !previousSpec) throw new Error("AGDF_MCP_REGISTRATION_FOREIGN");
+  if ((action === "enable" && current.selected_status === "matched") || (action === "disable" && current.selected_status === "absent")) {
+    return { status: "unchanged", path: current.path, apply() {}, rollback() {} };
+  }
+  let applied = "none";
+  const call = (args) => exec("claude", args, { cwd: target, encoding: "utf8", stdio: "pipe" });
+  const remove = () => call(commandArgs("disable", scope, spec));
+  const add = (value) => call(commandArgs("enable", scope, value));
+  return { status: "changed", path: current.path,
+    apply() {
+      if (action === "enable" && previousSpec) {
+        remove();
+        applied = "previous_removed";
+        try { add(spec); applied = "new_added"; } catch (error) {
+          try { add(previousSpec); applied = "none"; } catch { throw new Error("AGDF_MCP_CLAUDE_UPDATE_ROLLBACK_FAILED"); }
+          throw error;
+        }
+      } else {
+        call(commandArgs(action, scope, spec));
+        applied = "single_applied";
+      }
+    },
+    rollback() {
+      if (applied === "none") return;
+      if (action === "enable" && previousSpec) {
+        if (applied === "new_added") remove();
+        add(previousSpec);
+      } else {
+        const inverse = action === "enable" ? "disable" : "enable";
+        call(commandArgs(inverse, scope, spec));
+      }
+      applied = "none";
+    },
+  };
+}
+
+function probe({ exec, target }) {
+  try {
+    const output = String(exec("claude", ["--version"], { cwd: target, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })).trim();
+    const version = output.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/)?.[0];
+    return Object.freeze({ status: version ? "detected" : "unsupported", version: version ?? null,
+      client_variant: "cli", config_variant: "native_cli" });
+  } catch { return Object.freeze({ status: "unavailable", version: null, client_variant: "cli", config_variant: "native_cli" }); }
+}
+
+export const claudeAdapter = Object.freeze({
+  surface: "claude",
+  nativeScope,
+  probeHost: probe,
+  resolveSources: sources,
+  inspect,
+  createTransaction: transaction,
+  referenceIdentity: (input) => referenceIdentityForSurface("claude", nativeScope, input),
+  permissionEffect: inheritedPermissionEffect,
+});

package/lib/mcp-lifecycle/adapters/codex-origin-probe.js

@@ -0,0 +1,87 @@
+// Bounded discovery in a disposable project context. No model turn or config write.
+import { spawn } from 'node:child_process';
+import { isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveHostCommand } from '../../host-command.js';
+import { CODEX_MCP_STARTUP_ARGS, independentCodexEnvironment } from '../../host-adapters/codex/mcp-startup.js';
+
+export function observeCodexOrigins({ target, all = false, command, spawnProcess = spawn, timeoutMs = 45_000, now = Date.now }) {
+  if (typeof target !== 'string' || !isAbsolute(target)) return Promise.resolve({ status: 'unavailable', reason: 'target_invalid' });
+  return new Promise(resolve => {
+    let child, pending = '', received = 0, done = false, phase = 'initialize', threadId, closing, closeTimer, pollTimer, inventoryId = 3;
+    const deadline = now() + timeoutMs;
+    const finish = result => {
+      if (done) return;
+      done = true; clearTimeout(timer); clearTimeout(pollTimer);
+      if (!child) { resolve(result); return; }
+      if (child.exitCode != null || child.signalCode != null) {
+        resolve(child.exitCode === 0 && child.signalCode === null ? result : { status: 'unavailable', reason: 'teardown_unconfirmed' }); return;
+      }
+      closing = result;
+      const remaining = Math.min(2000, deadline - now());
+      if (remaining <= 0) { child.kill(); resolve(result.status === 'observed' ? { status: 'unavailable', reason: 'teardown_unconfirmed' } : result); return; }
+      closeTimer = setTimeout(() => { child.kill(); resolve({ status: 'unavailable', reason: 'teardown_unconfirmed' }); }, remaining);
+      try { child.stdin.end(); } catch { clearTimeout(closeTimer); child.kill(); resolve({ status: 'unavailable', reason: 'teardown_unconfirmed' }); }
+    };
+    const timer = setTimeout(() => finish({ status: 'unavailable', reason: 'timeout' }), timeoutMs);
+    const send = message => child.stdin.write(JSON.stringify(message) + '\n');
+    try {
+      const resolved = command ?? resolveHostCommand('codex', { env: process.env });
+      child = spawnProcess(resolved.executable, [...resolved.prefixArgs, ...CODEX_MCP_STARTUP_ARGS, 'app-server'], { cwd: target, env: independentCodexEnvironment(process.env),
+        stdio: ['pipe', 'pipe', 'pipe'], shell: false, windowsHide: true });
+      child.on('error', () => finish({ status: 'unavailable', reason: 'spawn_failed' }));
+      child.on('exit', (code, signal) => {
+        if (closing) { clearTimeout(closeTimer); resolve(code === 0 && !signal ? closing : { status: 'unavailable', reason: 'teardown_unconfirmed' }); }
+        else finish({ status: 'unavailable', reason: 'process_exit' });
+      });
+      child.stderr.on('data', () => {});
+      child.stdin.on('error', () => finish({ status: 'unavailable', reason: 'stdin_failed' }));
+      child.stdout.on('data', chunk => {
+        received += Buffer.byteLength(chunk); pending += String(chunk);
+        if (received > 1024 * 1024) return finish({ status: 'unavailable', reason: 'response_limit' });
+        let newline;
+        while (!done && (newline = pending.indexOf('\n')) !== -1) {
+          const line = pending.slice(0, newline); pending = pending.slice(newline + 1);
+          let message; try { message = JSON.parse(line); } catch { continue; }
+          if (phase === 'initialize' && message.id === 1) {
+            if (message.error) return finish({ status: 'unavailable', reason: 'initialize_failed' });
+            phase = 'project'; send({ method: 'initialized' });
+            // Cwd on the process alone does not scope mcpServerStatus/list.
+            // The context is in-memory and receives no turn/start or user message.
+            send({ id: 2, method: 'thread/start', params: { cwd: target, ephemeral: true } });
+          } else if (phase === 'project' && message.id === 2) {
+            const context = message.result;
+            if (message.error || typeof context?.thread?.id !== 'string' || !context.thread.id
+              || context.cwd !== target || context.thread.cwd !== target || context.thread.ephemeral !== true)
+              return finish({ status: 'unavailable', reason: 'project_context_unconfirmed' });
+            threadId = context.thread.id; phase = 'inventory';
+            // The temporary context owns every connection it starts. A narrow
+            // server filter can finish while another SDK is still handshaking;
+            // collect the complete settled inventory before closing the host.
+            send({ id: 3, method: 'mcpServerStatus/list', params: { threadId, detail: 'full' } });
+          } else if (phase === 'inventory' && message.id === inventoryId) {
+            const rows = message.result?.data;
+            if (message.error || !Array.isArray(rows) || rows.length > 256 || message.result.nextCursor
+              || rows.some(row => typeof row?.name !== 'string' || (row.pluginId != null && typeof row.pluginId !== 'string')))
+              return finish({ status: 'unavailable', reason: 'inventory_unconfirmed' });
+            if (rows.some(row => ['starting', 'connecting'].includes(row.runtimeStatus))) {
+              pollTimer = setTimeout(() => send({ id: ++inventoryId, method: 'mcpServerStatus/list',
+                params: { threadId, detail: 'full' } }), 100);
+              continue;
+            }
+            finish({ status: 'observed', scope: { cwd: target, thread_id: threadId, ephemeral: true },
+              providers: rows.filter(row => all || row.name === 'agdf-cockpit').map(row => ({ server_id: row.name, plugin_id: row.pluginId ?? null,
+                runtime_status: row.runtimeStatus, tools: Object.keys(row.tools ?? {}) })) });
+          }
+        }
+      });
+      send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'agdf_cockpit_origin', version: '1' },
+        capabilities: { experimentalApi: true, requestAttestation: false } } });
+    } catch { finish({ status: 'unavailable', reason: 'launch_failed' }); }
+  });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const result = await observeCodexOrigins({ target: process.argv[2], all: process.argv[3] === '--all' });
+  process.stdout.write(JSON.stringify(result) + '\n');
+}