@aiwg/cli 2026.8.16 → 2026.8.18

package/dist/src/installation/manager.mjs

@@ -0,0 +1,243 @@
+import { execFileSync } from 'node:child_process';
+import {
+  accessSync,
+  constants,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+import { resolveUserConfigDir } from '../config/user-config-dir.mjs';
+
+export const INSTALLATION_IDENTITY_VERSION = 1;
+export const INSTALLATION_FILE = 'installation.json';
+const METHODS = new Set(['npm', 'web', 'source']);
+const RUN_MODES = new Set(['normal', 'development']);
+const CHANNELS = new Set(['stable', 'next', 'nightly', 'edge']);
+const STRATEGIES = new Set(['npm-global', 'signed-web', 'source-git']);
+
+function canonicalPath(value) {
+  const resolved = path.resolve(value);
+  try { return realpathSync.native(resolved); } catch { return resolved; }
+}
+
+function packageName(root) {
+  try {
+    return JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')).name ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function inferInstallationMethod(root) {
+  if (packageName(root) === '@aiwg/cli') return 'web';
+  if (existsSync(path.join(root, '.git'))) return 'source';
+  return 'npm';
+}
+
+function resolveExecutable(name, options = {}) {
+  const env = options.env ?? process.env;
+  const explicit = options.managerExecutable ?? env.AIWG_PACKAGE_MANAGER_EXECUTABLE;
+  if (explicit) return canonicalPath(explicit);
+  if (name === 'npm' && env.npm_execpath) return canonicalPath(env.npm_execpath);
+
+  const besideNode = path.join(path.dirname(process.execPath), process.platform === 'win32' ? `${name}.cmd` : name);
+  if (existsSync(besideNode)) return canonicalPath(besideNode);
+  try {
+    const finder = process.platform === 'win32' ? 'where.exe' : 'which';
+    const found = execFileSync(finder, [name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .split(/\r?\n/, 1)[0]?.trim();
+    return found ? canonicalPath(found) : null;
+  } catch {
+    return null;
+  }
+}
+
+function strategyFor(method) {
+  if (method === 'web') return 'signed-web';
+  if (method === 'source') return 'source-git';
+  return 'npm-global';
+}
+
+function executableIsUsable(file) {
+  try {
+    if (!statSync(file).isFile()) return false;
+    if (process.platform !== 'win32') accessSync(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validateIdentity(value, file) {
+  const invalid = !value || typeof value !== 'object'
+    || value.schemaVersion !== INSTALLATION_IDENTITY_VERSION
+    || !METHODS.has(value.method)
+    || !RUN_MODES.has(value.runMode)
+    || !CHANNELS.has(value.channel)
+    || typeof value.root !== 'string'
+    || !path.isAbsolute(value.root)
+    || !STRATEGIES.has(value.updateStrategy)
+    || value.updateStrategy !== strategyFor(value.method)
+    || (value.managerExecutable !== null
+      && (typeof value.managerExecutable !== 'string' || !path.isAbsolute(value.managerExecutable)));
+  if (invalid) {
+    const error = new Error(`Invalid AIWG installation identity at ${file}. Run \`aiwg installation adopt\` to replace it.`);
+    error.code = 'AIWG_INSTALLATION_INVALID';
+    throw error;
+  }
+  return value;
+}
+
+export function installationFile(options = {}) {
+  return path.join(resolveUserConfigDir(options), INSTALLATION_FILE);
+}
+
+export function createInstallationIdentity(options) {
+  if (!options?.actualRoot) throw new Error('actualRoot is required to create an installation identity');
+  const root = canonicalPath(options.root ?? options.actualRoot);
+  const method = options.method ?? inferInstallationMethod(root);
+  const runMode = options.runMode ?? (method === 'source' ? 'development' : 'normal');
+  const requestedChannel = options.channel ?? (runMode === 'development' ? 'edge' : 'stable');
+  const channel = requestedChannel === 'latest'
+    ? 'stable'
+    : ['alpha', 'beta', 'rc'].includes(requestedChannel) ? 'next' : requestedChannel;
+  const executableName = method === 'npm' ? 'npm' : method === 'source' ? 'git' : null;
+  return {
+    schemaVersion: INSTALLATION_IDENTITY_VERSION,
+    runMode,
+    method,
+    root,
+    updateStrategy: options.updateStrategy ?? strategyFor(method),
+    managerExecutable: executableName ? resolveExecutable(executableName, options) : null,
+    channel,
+    edgePath: options.edgePath ? canonicalPath(options.edgePath) : (runMode === 'development' ? root : null),
+    checkOnStartup: options.checkOnStartup ?? true,
+    lastUpdateCheck: options.lastUpdateCheck ?? null,
+    updateCheckInterval: options.updateCheckInterval ?? 86_400_000,
+    recordedAt: options.recordedAt ?? new Date().toISOString(),
+  };
+}
+
+export function saveInstallationIdentity(identity, options = {}) {
+  const file = installationFile(options);
+  const validated = validateIdentity(identity, file);
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(validated, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, file);
+  return validated;
+}
+
+function readLegacy(options = {}) {
+  const file = path.join(resolveUserConfigDir(options), 'channel.json');
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+/** Load the canonical record, migrating legacy channel.json on first access. */
+export function loadInstallationIdentity(options = {}) {
+  const file = installationFile(options);
+  if (existsSync(file)) {
+    try { return validateIdentity(JSON.parse(readFileSync(file, 'utf8')), file); }
+    catch (error) {
+      if (error?.code === 'AIWG_INSTALLATION_INVALID') throw error;
+      const wrapped = new Error(`Cannot read AIWG installation identity at ${file}: ${error.message}`);
+      wrapped.code = 'AIWG_INSTALLATION_INVALID';
+      throw wrapped;
+    }
+  }
+  if (options.createIfMissing === false) return null;
+  if (!options.actualRoot) return null;
+
+  const legacy = options.legacyConfig ?? readLegacy(options) ?? {};
+  const development = legacy.devMode === true;
+  const root = development && legacy.edgePath ? legacy.edgePath : options.actualRoot;
+  const method = options.method ?? (development ? 'source' : inferInstallationMethod(root));
+  const identity = createInstallationIdentity({
+    ...options,
+    root,
+    method,
+    runMode: development ? 'development' : undefined,
+    channel: legacy.channel ?? options.channel,
+    edgePath: legacy.edgePath,
+    lastUpdateCheck: legacy.lastUpdateCheck,
+    updateCheckInterval: legacy.updateCheckInterval,
+    checkOnStartup: legacy.checkOnStartup,
+  });
+  return saveInstallationIdentity(identity, options);
+}
+
+export function inspectInstallation(options = {}) {
+  const actualRoot = canonicalPath(options.actualRoot);
+  const actualMethod = options.actualMethod ?? inferInstallationMethod(actualRoot);
+  const identity = options.identity ?? loadInstallationIdentity({ ...options, actualRoot });
+  if (!identity) return { state: 'unrecorded', identity: null, actualRoot, actualMethod, drift: ['installation identity is not recorded'] };
+
+  const drift = [];
+  const canonicalRoot = canonicalPath(identity.root);
+  if (!existsSync(canonicalRoot)) drift.push(`canonical root does not exist: ${canonicalRoot}`);
+  if (canonicalRoot !== actualRoot) drift.push(`actual root ${actualRoot} differs from canonical root ${canonicalRoot}`);
+  if (identity.method !== actualMethod) drift.push(`actual method ${actualMethod} differs from canonical method ${identity.method}`);
+  if (identity.method !== 'web' && !identity.managerExecutable) {
+    drift.push(`canonical ${identity.method} installation has no recorded manager executable`);
+  }
+  if (identity.managerExecutable && !executableIsUsable(identity.managerExecutable)) {
+    drift.push(`recorded manager executable is missing or not executable: ${identity.managerExecutable}`);
+  }
+  return {
+    state: drift.length === 0 ? 'aligned' : (existsSync(canonicalRoot) ? 'mismatch' : 'stale'),
+    identity,
+    canonicalRoot,
+    actualRoot,
+    actualMethod,
+    drift,
+  };
+}
+
+export function formatInstallationDiagnostic(status) {
+  if (status.state === 'aligned') return 'Canonical installation is aligned.';
+  return [
+    'AIWG installation identity drift detected; update and refresh are blocked.',
+    ...status.drift.map((item) => `- ${item}`),
+    'Inspect: aiwg installation show',
+    'Adopt this installation: aiwg installation adopt',
+    'Switch deliberately: aiwg installation switch --root <path> --method <npm|web|source> [--manager <absolute-path>]',
+  ].join('\n');
+}
+
+export function assertCanonicalInstallation(options = {}) {
+  const status = inspectInstallation(options);
+  if (status.state !== 'aligned') {
+    const error = new Error(formatInstallationDiagnostic(status));
+    error.code = 'AIWG_INSTALLATION_DRIFT';
+    error.status = status;
+    throw error;
+  }
+  return status;
+}
+
+export function adoptInstallation(options) {
+  const inferred = inferInstallationMethod(options.actualRoot);
+  if (options.method && options.method !== inferred) {
+    throw new Error(`Cannot adopt ${options.actualRoot} as ${options.method}; package contents identify it as ${inferred}.`);
+  }
+  const identity = createInstallationIdentity({ ...options, root: options.actualRoot });
+  saveInstallationIdentity(identity, options);
+  return inspectInstallation({ ...options, actualRoot: identity.root, identity });
+}
+
+export function switchInstallation(options) {
+  if (!options?.root || !options?.method) throw new Error('switch requires root and method');
+  if (!existsSync(path.resolve(options.root))) throw new Error(`Installation root does not exist: ${path.resolve(options.root)}`);
+  const inferred = inferInstallationMethod(options.root);
+  if (options.method !== inferred) {
+    throw new Error(`Cannot switch ${options.root} as ${options.method}; package contents identify it as ${inferred}.`);
+  }
+  const identity = createInstallationIdentity({ ...options, actualRoot: options.root });
+  saveInstallationIdentity(identity, options);
+  return inspectInstallation({ ...options, actualRoot: identity.root, identity });
+}

package/dist/src/providers/transformation-receipt-integration.js

@@ -1,5 +1,5 @@
-import { createHash } from 'node:crypto';
-import { access, lstat, readFile, readdir } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { access, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { readAiwgConfig } from '../config/aiwg-config.js';
@@ -25,6 +25,65 @@ const FRAMEWORK_BUNDLE_DIRS = {
     validation: 'validation-complete',
     'knowledge-base': 'knowledge-base',
 };
+const PROVIDER_TRANSFORMATION_EVIDENCE_STATE_SCHEMA = 'aiwg.provider-transformation-evidence-state.v1';
+export function providerTransformationEvidenceStatePath(projectRoot, provider, scope) {
+    const receiptPath = providerTransformationReceiptPath(projectRoot, provider, scope);
+    return receiptPath.replace(/\.json$/, '.evidence.json');
+}
+function validateEvidenceState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('evidence state must be an object');
+    const state = value;
+    if (state.schemaVersion !== PROVIDER_TRANSFORMATION_EVIDENCE_STATE_SCHEMA)
+        throw new Error('unsupported evidence state schema');
+    if (!Number.isFinite(Date.parse(state.recordedAt)))
+        throw new Error('recordedAt must be an RFC 3339 date-time');
+    if (state.scope !== 'project' && state.scope !== 'user')
+        throw new Error('scope must be project or user');
+    if (!['local-source', 'source-unavailable', 'verification-failed'].includes(state.disposition)) {
+        throw new Error('unsupported source evidence disposition');
+    }
+    if (!state.provider || state.provider.includes('/') || state.provider.includes('\\'))
+        throw new Error('provider is invalid');
+    return state;
+}
+async function writeEvidenceState(options, disposition) {
+    const provider = normalizeProviderDefinitionId(options.provider) ?? options.provider;
+    const target = providerTransformationEvidenceStatePath(options.projectRoot, provider, options.scope);
+    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${randomUUID()}.tmp`);
+    const state = {
+        schemaVersion: PROVIDER_TRANSFORMATION_EVIDENCE_STATE_SCHEMA,
+        recordedAt: options.generatedAt ?? new Date().toISOString(),
+        provider,
+        scope: options.scope,
+        disposition,
+    };
+    try {
+        await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        await rename(temporary, target);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    await rm(providerTransformationReceiptPath(options.projectRoot, provider, options.scope), { force: true });
+    return target;
+}
+async function readEvidenceState(options) {
+    const provider = normalizeProviderDefinitionId(options.provider) ?? options.provider;
+    try {
+        const state = validateEvidenceState(JSON.parse(await readFile(providerTransformationEvidenceStatePath(options.projectRoot, provider, options.scope), 'utf8')));
+        if (state.provider !== provider || state.scope !== options.scope)
+            throw new Error('evidence state identity does not match deployment');
+        return state;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
 function sha256(value) {
     return createHash('sha256').update(value).digest('hex');
 }
@@ -225,6 +284,17 @@ function receiptBundles(installed, options) {
         .sort();
     return deployed.length > 0 ? deployed : [...new Set(options.requestedBundles)].sort();
 }
+/**
+ * Return whether the deployed provider surface includes project-local source
+ * material that cannot be authenticated by an AIWG signed web release.
+ */
+export async function providerReceiptHasLocalSources(rawOptions) {
+    const provider = normalizeProviderDefinitionId(rawOptions.provider) ?? rawOptions.provider;
+    const options = { ...rawOptions, provider };
+    const installed = await installedEntries(options);
+    return receiptBundles(installed, options)
+        .some(bundle => installed[bundle]?.source === 'project-local');
+}
 /**
  * Convert an already signature-verified web release into the stable verifier
  * result contract for the complete canonical bundle consumed by deployment.
@@ -375,6 +445,27 @@ export async function resolveProviderReceiptRuntimeEvidence(rawOptions) {
     };
 }
 export async function finalizeProviderTransformationReceipt(options) {
+    if (options.sourceDisposition) {
+        const evidenceStatePath = await writeEvidenceState(options, options.sourceDisposition);
+        if (options.sourceDisposition === 'local-source') {
+            return {
+                status: 'policy-exempt',
+                receiptPath: null,
+                evidenceStatePath,
+                outputCount: 0,
+                reason: 'local-source development deployments are exempt from signed-release receipt issuance',
+            };
+        }
+        return {
+            status: options.sourceDisposition === 'source-unavailable' ? 'source-unavailable' : 'skipped',
+            receiptPath: null,
+            evidenceStatePath,
+            outputCount: 0,
+            reason: options.sourceDisposition === 'source-unavailable'
+                ? 'verified signed-release source evidence is not available from cache or configured resource access'
+                : 'canonical source verification failed',
+        };
+    }
     if (!options.sourceVerifications) {
         return {
             status: 'skipped',
@@ -412,9 +503,11 @@ export async function finalizeProviderTransformationReceipt(options) {
         transformer: evidence.transformer,
         outputPaths: evidence.outputPaths,
     });
+    const receiptPath = await writeProviderTransformationReceipt(options.projectRoot, receipt);
+    await rm(providerTransformationEvidenceStatePath(options.projectRoot, evidence.provider, options.scope), { force: true });
     return {
         status: 'written',
-        receiptPath: await writeProviderTransformationReceipt(options.projectRoot, receipt),
+        receiptPath,
         outputCount: receipt.outputs.length,
     };
 }
@@ -425,6 +518,40 @@ export async function diagnoseIntegratedProviderTransformationReceipt(options) {
         await access(receiptPath);
     }
     catch {
+        const state = await readEvidenceState(options);
+        if (state?.disposition === 'local-source') {
+            return {
+                status: 'policy-exempt',
+                receiptPath,
+                checkedOutputs: 0,
+                findings: [{
+                        kind: 'policy-exempt',
+                        message: 'This local-source development deployment is explicitly exempt from signed-release transformation receipts.',
+                    }],
+            };
+        }
+        if (state?.disposition === 'source-unavailable') {
+            return {
+                status: 'source-evidence-unavailable',
+                receiptPath,
+                checkedOutputs: 0,
+                findings: [{
+                        kind: 'source-evidence-unavailable',
+                        message: 'The deployment succeeded, but verified signed-release source evidence was unavailable from cache or configured resource access.',
+                    }],
+            };
+        }
+        if (state?.disposition === 'verification-failed') {
+            return {
+                status: 'drifted',
+                receiptPath,
+                checkedOutputs: 0,
+                findings: [{
+                        kind: 'source-verification-failure',
+                        message: 'Canonical source verification failed during receipt finalization.',
+                    }],
+            };
+        }
         return {
             status: 'missing-receipt',
             receiptPath,

package/dist/src/security/artifact-verifier.js

@@ -1,4 +1,4 @@
-import { ARTIFACT_TRUST_STATE_SCHEMA_VERSION, channelStateKey, decodeBase64, dssePae, isIdentityRevoked, parseTrustRoot, publicKeyFingerprint, scopeMatches, selectDelegations, sha256, validateTrustState, verifyBytes, } from './artifact-trust.js';
+import { ARTIFACT_TRUST_STATE_SCHEMA_VERSION, canonicalJson, channelStateKey, decodeBase64, dssePae, isIdentityRevoked, parseTrustRoot, publicKeyFingerprint, scopeMatches, selectDelegations, sha256, validateTrustState, verifyBytes, } from './artifact-trust.js';
 export const ARTIFACT_VERIFICATION_RESULT_SCHEMA_VERSION = 'aiwg.verify.result.v1';
 export const ARTIFACT_VERIFICATION_EXIT_CODES = {
     verified: 0,
@@ -351,6 +351,12 @@ export async function verifyArtifact(input) {
             identities: allAuthenticated.map(identity => identity.id).sort(),
         });
     }
+    if (!Buffer.from(canonicalJson(statement), 'utf8').equals(payload)) {
+        return result('mismatched', input, [{ code: 'NONCANONICAL_SIGNED_PAYLOAD', message: 'Signed provenance payload is not canonical JSON' }], {
+            ...common,
+            identities: allAuthenticated.map(identity => identity.id).sort(),
+        });
+    }
     const scopeInput = {
         assetType: statement.predicate.assetType,
         namespace: statement.predicate.publisher.namespace,

package/dist/src/serve/a2a-terminal-observer.js

@@ -10,6 +10,7 @@
  */
 import { A2AClient } from '../a2a/client.js';
 import { isTerminalTaskState, } from '../a2a/types.js';
+import { extractGraphMetadata } from '../flow/graph-metadata.js';
 const DEFAULT_POLL_INTERVAL_MS = 1000;
 const DEFAULT_MAX_POLLS = 300;
 export async function observeA2ATerminalState(registry, executor, missionId, a2aInstanceId, initialTask, opts = {}) {
@@ -18,7 +19,11 @@ export async function observeA2ATerminalState(registry, executor, missionId, a2a
             baseUrl: executor.transportEndpoints.rest,
             bearer: executor.token,
             instanceId: a2aInstanceId,
+            protocolVersion: opts.protocolVersion ?? '0.3',
+            protocolPolicy: opts.protocolVersion ?? '0.3',
         };
+        if (opts.selectedInterface)
+            clientOpts.selectedInterface = opts.selectedInterface;
         if (opts.fetch)
             clientOpts.fetch = opts.fetch;
         const client = new A2AClient(clientOpts);
@@ -90,21 +95,39 @@ function emitTerminalTask(registry, executorId, missionId, task) {
     }));
 }
 function makeEnvelope(event, executorId, missionId, task, data) {
+    const graph = extractGraphMetadata(task.metadata);
     return {
         event,
         executor_id: executorId,
         mission_id: missionId,
         ts: task.status.timestamp ?? new Date().toISOString(),
-        data,
+        data: {
+            ...data,
+            ...(graph ? {
+                graph_metadata: { ...graph, nodeState: taskStateToGraphState(task.status.state) },
+                graph_node_state: taskStateToGraphState(task.status.state),
+            } : {}),
+        },
     };
 }
+function taskStateToGraphState(state) {
+    switch (state) {
+        case 'submitted': return 'pending';
+        case 'working': return 'running';
+        case 'input-required':
+        case 'auth-required': return 'blocked-hitl';
+        case 'completed': return 'succeeded';
+        case 'failed':
+        case 'rejected': return 'failed';
+        case 'canceled': return 'canceled';
+        default: return 'unknown';
+    }
+}
 function taskStatusSummary(task) {
-    const status = task.status;
-    return typeof status.summary === 'string' ? status.summary : undefined;
+    return task.status.summary;
 }
 function exitCodeData(task) {
-    const status = task.status;
-    return typeof status.exit_code === 'number' ? { exit_code: status.exit_code } : {};
+    return task.status.exitCode !== undefined ? { exit_code: task.status.exitCode } : {};
 }
 function sleep(ms) {
     return new Promise((resolve) => {

package/dist/src/serve/dispatch-router.js

@@ -12,7 +12,7 @@
  *   v1 payload                       →  A2A Message
  *   --------------------------------    --------------------------------------
  *   mission_id                          message.messageId (idempotency key)
- *   objective                           parts[0] = { kind: 'text', text: ... }
+ *   objective                           parts[0] = normalized text content
  *   completion                          metadata.completion
  *   executor_filter                     metadata.executor_filter
  *   long_running                        metadata.long_running
@@ -39,7 +39,10 @@ export async function routeDispatch(executor, payload, opts = {}) {
     }
     catch (err) {
         // Only fall back on a 404 from the v2 path. Everything else propagates.
-        if (err instanceof A2AError && err.status === 404) {
+        const policy = opts.a2aProtocolPolicy ?? '0.3';
+        const allowLegacyFallback = policy !== '1.0'
+            && (opts.allowLegacyExecutorFallback ?? true);
+        if (allowLegacyFallback && err instanceof A2AError && err.status === 404) {
             // Capture sunset for the telemetry event if any was attached.
             const sunset = err.problem.code === 'aiwg.deprecation_strict' ? undefined : undefined;
             if (opts.onV1Fallback) {
@@ -62,6 +65,8 @@ async function dispatchV2(executor, payload, opts) {
         bearer: executor.token,
         instanceId: a2aInstanceId,
         requiredExtensions: opts.requiredExtensions ?? [A2A_RUNTIME_V1, A2A_IDEMPOTENCY_V1],
+        protocolPolicy: opts.a2aProtocolPolicy ?? '0.3',
+        allowProtocolFallback: opts.allowA2AProtocolFallback ?? false,
     };
     if (opts.fetch)
         clientOpts.fetch = opts.fetch;
@@ -69,7 +74,27 @@ async function dispatchV2(executor, payload, opts) {
         clientOpts.optionalExtensions = opts.optionalExtensions;
     if (opts.onDeprecation)
         clientOpts.onDeprecation = opts.onDeprecation;
-    const client = new A2AClient(clientOpts);
+    if (opts.onA2AProtocolFallback)
+        clientOpts.onProtocolFallback = opts.onA2AProtocolFallback;
+    if (opts.onA2AProtocolSelection) {
+        clientOpts.onProtocolSelection = info => opts.onA2AProtocolSelection?.(info);
+    }
+    // The deployed 0.3 compatibility route predates AgentCard negotiation. Model
+    // it as an explicit interface so headerless legacy selection is observable
+    // in registry, telemetry, audit, and dispatch results without adding a new
+    // discovery dependency to the compatibility path.
+    if (clientOpts.protocolPolicy === '0.3') {
+        clientOpts.selectedInterface = {
+            url: `${executor.transportEndpoints.rest.replace(/\/+$/, '')}/agents/${encodeURIComponent(a2aInstanceId)}`,
+            protocolBinding: 'REST',
+            protocolVersion: '0.3',
+            preference: 0,
+            legacy: true,
+        };
+    }
+    const client = clientOpts.protocolPolicy === '0.3'
+        ? new A2AClient(clientOpts)
+        : await A2AClient.negotiate(clientOpts);
     const message = payloadToMessage(payload);
     const result = await client.sendMessage(message);
     return {
@@ -79,6 +104,9 @@ async function dispatchV2(executor, payload, opts) {
         dispatchPath: 'v2',
         task: result.task,
         idempotentReplayed: result.idempotentReplayed,
+        a2aProtocolVersion: result.protocolVersion,
+        ...(result.selectedInterface ? { a2aInterface: result.selectedInterface } : {}),
+        ...(result.fallbackReason ? { a2aFallbackReason: result.fallbackReason } : {}),
     };
 }
 function resolveA2AInstanceId(executor, payload, opts) {
@@ -145,7 +173,7 @@ function payloadToMessage(payload) {
     return {
         messageId: payload.mission_id,
         role: 'user',
-        parts: [{ kind: 'text', text: payload.objective }],
+        parts: [{ type: 'text', text: payload.objective }],
         metadata,
     };
 }

package/dist/src/serve/executor-registry.js

@@ -232,6 +232,7 @@ export class ExecutorRegistry extends EventEmitter {
             // Upsert — preserve token and registeredAt
             existing.name = req.name;
             existing.a2aInstanceId = req.a2a_instance_id;
+            delete existing.a2aProtocol;
             existing.version = req.version;
             existing.specVersion = req.spec_version;
             existing.transportEndpoints = req.transport_endpoints;
@@ -614,6 +615,24 @@ export class ExecutorRegistry extends EventEmitter {
     getRegistration(executorId) {
         return this.executors.get(executorId);
     }
+    /** Publish the negotiated interface used for the most recent A2A dispatch. */
+    recordA2AProtocolSelection(executorId, selection) {
+        const executor = this.executors.get(executorId);
+        if (!executor)
+            return false;
+        executor.a2aProtocol = {
+            ...selection,
+            selectedAt: selection.selectedAt ?? new Date().toISOString(),
+        };
+        this.emit('executor:a2a_protocol_selected', {
+            executorId,
+            selectedVersion: selection.selectedVersion,
+            protocolBinding: selection.interface.protocolBinding,
+            interfaceUrl: selection.interface.url,
+            ...(selection.fallbackReason ? { fallbackReason: selection.fallbackReason } : {}),
+        });
+        return true;
+    }
     /**
      * Pick the best executor matching the given filter.
      *
@@ -708,6 +727,16 @@ function toSummary(e) {
     };
     if (e.a2aInstanceId)
         summary.a2a_instance_id = e.a2aInstanceId;
+    if (e.a2aProtocol) {
+        summary.a2a_protocol = {
+            policy: e.a2aProtocol.policy,
+            selected_version: e.a2aProtocol.selectedVersion,
+            protocol_binding: e.a2aProtocol.interface.protocolBinding,
+            interface_url: e.a2aProtocol.interface.url,
+            selected_at: e.a2aProtocol.selectedAt,
+            ...(e.a2aProtocol.fallbackReason ? { fallback_reason: e.a2aProtocol.fallbackReason } : {}),
+        };
+    }
     return summary;
 }
 // Singleton instance