@aiwg/cli 2026.8.17 → 2026.8.18

package/dist/src/cli/handlers/serve.js

@@ -27,8 +27,14 @@ const pushSecretRegistry = new PushSecretRegistry();
 const webhookIdempotency = new IdempotencyCache();
 const DEFAULT_PORT = 7337;
 const DEFAULT_HOST = '127.0.0.1';
+function readA2AProtocolPolicy(value) {
+    const policy = value ?? '0.3';
+    if (policy === '0.3' || policy === '1.0' || policy === 'auto')
+        return policy;
+    throw new Error(`AIWG_A2A_PROTOCOL_POLICY must be 0.3, 1.0, or auto (received '${policy}')`);
+}
 /**
- * Parse --port, --bind, --no-open, --read-only flags from args
+ * Parse dashboard and A2A negotiation flags from args.
  */
 function parseServeArgs(args) {
     let port = DEFAULT_PORT;
@@ -36,6 +42,9 @@ function parseServeArgs(args) {
     let open = true;
     let readOnly = false;
     let sandbox = null;
+    let a2aProtocolPolicy;
+    let allowA2AProtocolFallback;
+    let allowLegacyExecutorFallback;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '--port' && args[i + 1]) {
@@ -58,8 +67,33 @@ function parseServeArgs(args) {
         else if (arg === '--read-only') {
             readOnly = true;
         }
+        else if (arg === '--a2a-protocol' && args[i + 1]) {
+            a2aProtocolPolicy = readA2AProtocolPolicy(args[i + 1]);
+            i++;
+        }
+        else if (arg === '--a2a-protocol-fallback') {
+            allowA2AProtocolFallback = true;
+        }
+        else if (arg === '--no-a2a-protocol-fallback') {
+            allowA2AProtocolFallback = false;
+        }
+        else if (arg === '--a2a-legacy-executor-fallback') {
+            allowLegacyExecutorFallback = true;
+        }
+        else if (arg === '--no-a2a-legacy-executor-fallback') {
+            allowLegacyExecutorFallback = false;
+        }
     }
-    return { port, host, open, readOnly, sandbox };
+    return {
+        port,
+        host,
+        open,
+        readOnly,
+        sandbox,
+        ...(a2aProtocolPolicy ? { a2aProtocolPolicy } : {}),
+        ...(allowA2AProtocolFallback !== undefined ? { allowA2AProtocolFallback } : {}),
+        ...(allowLegacyExecutorFallback !== undefined ? { allowLegacyExecutorFallback } : {}),
+    };
 }
 // ============================================================
 // WebSocket routing (#851)
@@ -499,6 +533,13 @@ async function setupWebSockets(httpServer, readOnly) {
  * @see #1277 — moves the integration suite off spawn-based testing
  */
 export async function startServer(opts) {
+    const configuredA2AProtocolPolicy = opts.a2aProtocolPolicy
+        ?? readA2AProtocolPolicy(process.env['AIWG_A2A_PROTOCOL_POLICY']);
+    const configuredA2AProtocolFallback = opts.allowA2AProtocolFallback
+        ?? process.env['AIWG_A2A_PROTOCOL_FALLBACK'] === 'true';
+    const configuredLegacyExecutorFallback = configuredA2AProtocolPolicy !== '1.0'
+        && (opts.allowLegacyExecutorFallback
+            ?? process.env['AIWG_A2A_LEGACY_EXECUTOR_FALLBACK'] !== 'false');
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let honoMod;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -760,8 +801,32 @@ export async function startServer(opts) {
         let a2aInstanceId;
         let dispatchPath = 'v2';
         let a2aTask = undefined;
+        let a2aProtocolVersion;
+        let a2aInterface;
+        let a2aFallbackReason;
+        const a2aProtocolPolicy = configuredA2AProtocolPolicy;
         try {
             const result = await routeDispatch(executor, payload, {
+                a2aProtocolPolicy,
+                allowA2AProtocolFallback: configuredA2AProtocolFallback,
+                allowLegacyExecutorFallback: configuredLegacyExecutorFallback,
+                onA2AProtocolSelection: (info) => {
+                    telemetryStore.ingest(createEvent('a2a.protocol.selected', sessionId, {
+                        selected_version: info.selected,
+                        policy: info.policy,
+                        ...(info.interface ? {
+                            protocol_binding: info.interface.protocolBinding,
+                            interface_url: info.interface.url,
+                        } : {}),
+                    }, missionId));
+                },
+                onA2AProtocolFallback: (info) => {
+                    telemetryStore.ingest(createEvent('a2a.protocol.fallback', sessionId, {
+                        from_version: info.from,
+                        to_version: info.to,
+                        reason: info.reason,
+                    }, missionId));
+                },
                 onV1Fallback: (info) => {
                     logServeWarn('dispatch', `v1 fallback for executor ${info.executorId}: ${info.reason}`);
                     telemetryStore.ingest(createEvent('v1.dispatch.fallback', sessionId, info, missionId));
@@ -775,6 +840,9 @@ export async function startServer(opts) {
             dispatchPath = result.dispatchPath;
             a2aInstanceId = result.a2aInstanceId;
             a2aTask = result.task;
+            a2aProtocolVersion = result.a2aProtocolVersion;
+            a2aInterface = result.a2aInterface;
+            a2aFallbackReason = result.a2aFallbackReason;
             if (result.estimatedStart)
                 estimatedStart = result.estimatedStart;
         }
@@ -796,12 +864,22 @@ export async function startServer(opts) {
             return c.json({ error: errorTag, detail: msg }, status);
         }
         // 4. Record the mission and emit telemetry
+        if (a2aProtocolVersion && a2aInterface) {
+            executorRegistry.recordA2AProtocolSelection(executor.executorId, {
+                policy: a2aProtocolPolicy,
+                selectedVersion: a2aProtocolVersion,
+                interface: a2aInterface,
+                ...(a2aFallbackReason ? { fallbackReason: a2aFallbackReason } : {}),
+            });
+        }
         executorRegistry.assignMission(missionId, executor.executorId);
         if (dispatchPath === 'v2' && a2aTask && a2aInstanceId) {
             void observeA2ATerminalState(executorRegistry, executor, missionId, a2aInstanceId, a2aTask, {
                 onError: (err) => {
                     logServeWarn('dispatch', `A2A terminal observer failed for mission ${missionId}: ${err.message ?? String(err)}`);
                 },
+                ...(a2aProtocolVersion ? { protocolVersion: a2aProtocolVersion } : {}),
+                ...(a2aInterface ? { selectedInterface: a2aInterface } : {}),
             });
         }
         telemetryStore.ingest(createEvent('mission.dispatch', sessionId, {
@@ -809,6 +887,8 @@ export async function startServer(opts) {
             executorId: executor.executorId,
             objective: payload.objective,
             completion: payload.completion,
+            ...(a2aProtocolVersion ? { a2a_protocol_version: a2aProtocolVersion } : {}),
+            ...(a2aFallbackReason ? { a2a_fallback_reason: a2aFallbackReason } : {}),
         }, missionId));
         // 5. Return 202 Accepted
         const dispatchResp = {
@@ -819,6 +899,14 @@ export async function startServer(opts) {
         };
         if (a2aInstanceId)
             dispatchResp.a2a_instance_id = a2aInstanceId;
+        if (a2aProtocolVersion)
+            dispatchResp.a2a_protocol_version = a2aProtocolVersion;
+        if (a2aInterface) {
+            dispatchResp.a2a_protocol_binding = a2aInterface.protocolBinding;
+            dispatchResp.a2a_interface_url = a2aInterface.url;
+        }
+        if (a2aFallbackReason)
+            dispatchResp.a2a_fallback_reason = a2aFallbackReason;
         if (estimatedStart)
             dispatchResp.estimated_start = estimatedStart;
         return c.json(dispatchResp, 202);
@@ -947,6 +1035,7 @@ export async function startServer(opts) {
         const result = await handleWebhook(configId, bodyBuf, signature, eventId, {
             registry: pushSecretRegistry,
             idempotency: webhookIdempotency,
+            contentType: c.req.header('content-type') ?? undefined,
             route: async (entry, event) => {
                 // Append to mission recentEvents via a synthesized envelope.
                 // The 'mission.webhook' event type falls through the registry's
@@ -990,11 +1079,17 @@ export async function startServer(opts) {
         if (!p.secret || typeof p.secret !== 'string' || p.secret.length < 16) {
             return c.json({ error: 'secret is required and must be ≥16 chars' }, 400);
         }
+        if (p.protocolVersion === '1.0' && !p.taskId) {
+            return c.json({ error: 'taskId is required for A2A 1.0 push ownership scope' }, 400);
+        }
         pushSecretRegistry.register({
             configId: p.configId,
             secret: p.secret,
             ...(p.missionId ? { missionId: p.missionId } : {}),
             ...(p.taskId ? { taskId: p.taskId } : {}),
+            ...(p.contextId ? { contextId: p.contextId } : {}),
+            ...(p.protocolVersion ? { protocolVersion: p.protocolVersion } : {}),
+            ...(p.taskOwner ? { taskOwner: p.taskOwner } : {}),
             ...(p.metadata ? { metadata: p.metadata } : {}),
         });
         return c.json({ ok: true, configId: p.configId }, 201);
@@ -1749,10 +1844,18 @@ export const serveHandler = {
     category: 'project',
     aliases: [],
     async execute(ctx) {
-        const { port, host, open, readOnly } = parseServeArgs(ctx.args);
+        const { port, host, open, readOnly, a2aProtocolPolicy, allowA2AProtocolFallback, allowLegacyExecutorFallback, } = parseServeArgs(ctx.args);
         let server;
         try {
-            server = await startServer({ port, host, readOnly, frameworkRoot: ctx.frameworkRoot });
+            server = await startServer({
+                port,
+                host,
+                readOnly,
+                frameworkRoot: ctx.frameworkRoot,
+                ...(a2aProtocolPolicy ? { a2aProtocolPolicy } : {}),
+                ...(allowA2AProtocolFallback !== undefined ? { allowA2AProtocolFallback } : {}),
+                ...(allowLegacyExecutorFallback !== undefined ? { allowLegacyExecutorFallback } : {}),
+            });
         }
         catch (error) {
             const { handlerResultFromError } = await import('../errors.js');

package/dist/src/cli/handlers/session.js

@@ -21,6 +21,7 @@ import { spawnSync } from 'child_process';
 import { ensureRuntimeHome, writeProfileConfig, launchWithProfile } from '../../mcp/adapters/codex-runtime.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
 import { forceUpdateCheck } from '../../update/checker.mjs';
+import { updateInstallation } from '../../update/service.mjs';
 import { readAiwgConfig, getDeploymentSummary, VALID_PROVIDERS, } from '../../config/aiwg-config.js';
 import { getProviderConfig, isSpawnableProvider, PROVIDER_CONFIGS, } from '../agent-spawn.js';
 import { useHandler as useFrameworkHandler } from './use.js';
@@ -84,8 +85,11 @@ async function checkAndUpdateVersion(noRepair) {
         debug('cli:session:update', 'forceUpdateCheck failed', err);
         if (!noRepair) {
             console.log('  Version check failed — attempting sync...');
-            const r = spawnSync('npm', ['install', '-g', 'aiwg@latest'], { stdio: 'inherit' });
-            if (r.status !== 0) {
+            try {
+                await updateInstallation();
+            }
+            catch (updateError) {
+                debug('cli:session:update', 'canonical installation update failed', updateError);
                 console.warn('  WARN  Could not update aiwg — continuing with current version.');
                 return false;
             }
@@ -103,10 +107,11 @@ function runDoctor(_frameworkRoot, cwd) {
 }
 /**
  * Attempt to repair a failed doctor result.
- * Strategy: `aiwg sync` first; if that fails, offer full reinstall.
+ * Strategy: `aiwg sync`; package repair remains bound to the canonical update
+ * strategy and never falls through to an arbitrary npm on PATH.
  * Returns true if repair succeeded (doctor now passes).
  */
-function repairInstallation(frameworkRoot, cwd, provider, installedFrameworks) {
+function repairInstallation(frameworkRoot, cwd, provider) {
     // Strategy 1: sync (update + redeploy)
     console.log('\n  Attempting auto-repair via `aiwg sync`...');
     const syncResult = spawnSync(process.execPath, [process.argv[1], 'sync'], { stdio: 'inherit', cwd });
@@ -118,29 +123,13 @@ function repairInstallation(frameworkRoot, cwd, provider, installedFrameworks) {
             return true;
         }
     }
-    // Strategy 2: full reinstall
-    console.log('\n  Sync did not fully resolve the issue. Attempting full reinstall...');
-    const reinstallResult = spawnSync('npm', ['install', '-g', 'aiwg@latest'], { stdio: 'inherit' });
-    if (reinstallResult.status === 0 && installedFrameworks.length > 0) {
-        // Redeploy all installed frameworks for this provider
-        console.log(`\n  Redeploying frameworks to ${provider}...`);
-        for (const fw of installedFrameworks) {
-            spawnSync(process.execPath, [process.argv[1], 'use', fw, '--provider', provider], { stdio: 'inherit', cwd });
-        }
-        // Final doctor check
-        const finalOk = runDoctor(frameworkRoot, cwd);
-        if (finalOk) {
-            console.log('  OK  Full reinstall + redeploy succeeded.');
-            return true;
-        }
-    }
     // Could not auto-repair
     console.log(`
   ✗  Auto-repair could not resolve all issues.
 
   Manual options:
-    aiwg sync                       — sync and redeploy
-    npm install -g aiwg@latest      — reinstall package
+    aiwg installation show          — inspect canonical install drift
+    aiwg refresh                    — update and redeploy canonically
     aiwg use all --provider ${provider.padEnd(10)} — redeploy all frameworks
 
   Report this issue:
@@ -291,10 +280,7 @@ export const sessionHandler = {
         console.log('\n  Running health checks...');
         const doctorOk = runDoctor(frameworkRoot, cwd);
         if (!doctorOk && !noRepair) {
-            // Read installed frameworks before attempting repair (needed for redeploy)
-            const config = await readAiwgConfig(cwd);
-            const installedFrameworks = Object.keys(config?.installed ?? {});
-            const repaired = repairInstallation(frameworkRoot, cwd, provider, installedFrameworks);
+            const repaired = repairInstallation(frameworkRoot, cwd, provider);
             if (!repaired) {
                 // Repair failed — still continue (user was already informed)
             }

package/dist/src/cli/handlers/utilities.js

@@ -777,6 +777,10 @@ export const updateHandler = {
                 console.log(`${update.message}\n`);
             }
             catch (error) {
+                if (error.code === 'AIWG_INSTALLATION_DRIFT'
+                    || error.code === 'AIWG_INSTALLATION_INVALID') {
+                    return { exitCode: 78, message: error instanceof Error ? error.message : String(error) };
+                }
                 console.error(`Warning: Update check failed: ${error instanceof Error ? error.message : String(error)}`);
                 console.log('Continuing with re-deployment...\n');
             }

package/dist/src/cli/handlers/version.js

@@ -53,6 +53,7 @@ function collectFingerprint(versionInfo) {
             logFile: loggerInfo.logFile,
         },
         invocation_id: loggerInfo.provenance.invocation_id,
+        installation: versionInfo.installation,
     };
     if (versionInfo.gitHash) {
         fp.git = {
@@ -115,6 +116,9 @@ async function displayVersion(opts) {
         ui.dim(`    path:      ${fp.packageRoot}`);
     }
     ui.dim(`    channel:   ${fp.channel}`);
+    ui.dim(`    install:   ${fp.installation.identity?.method ?? 'unrecorded'} (${fp.installation.state})`);
+    ui.dim(`    canonical: ${fp.installation.identity?.root ?? '(unrecorded)'}`);
+    ui.dim(`    actual:    ${fp.installation.actualRoot}`);
     ui.dim(`    node:      ${fp.node}`);
     ui.dim(`    platform:  ${fp.platform.os} ${fp.platform.arch} (${fp.platform.release})`);
     ui.dim(`    tty:       stdin=${fp.tty.stdin} stdout=${fp.tty.stdout} stderr=${fp.tty.stderr}`);

package/dist/src/config/user-config-dir.mjs

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Resolve AIWG's global, provider-neutral user configuration directory.
+ *
+ * Contract: explicit override > AIWG_CONFIG > existing ~/.aiwg > existing
+ * ~/.config/aiwg > ~/.aiwg. Keeping this in a dependency-free ESM module lets
+ * the launcher, channel manager, updater, and TypeScript config API share the
+ * exact same resolution rules.
+ */
+export function resolveUserConfigDir(options = {}) {
+  if (options.configDir) return path.resolve(options.configDir);
+  const env = options.env ?? process.env;
+  if (env.AIWG_CONFIG) return path.resolve(env.AIWG_CONFIG);
+
+  const home = options.homeDir ?? os.homedir();
+  const legacy = path.join(home, '.aiwg');
+  const xdg = path.join(home, '.config', 'aiwg');
+  const pathExists = options.exists ?? existsSync;
+  if (pathExists(legacy)) return legacy;
+  if (pathExists(xdg)) return xdg;
+  return legacy;
+}
+
+export function userConfigFile(name, options = {}) {
+  return path.join(resolveUserConfigDir(options), name);
+}

package/dist/src/config/user-config.js

@@ -16,9 +16,9 @@
  * @implements #545
  */
 import { readFile, writeFile, mkdir, access } from 'fs/promises';
-import { resolve } from 'path';
-import { homedir } from 'os';
 import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { resolveUserConfigDir } from './user-config-dir.mjs';
 /**
  * Known config files in the user config directory
  */
@@ -28,6 +28,7 @@ export const KNOWN_CONFIG_FILES = [
     { filename: 'ops.json', description: 'Ops workspace registry' },
     { filename: 'mcp-servers.json', description: 'MCP server registry (single source of truth)' },
     { filename: 'packages.yaml', description: 'Installed remote packages (aiwg install)' },
+    { filename: 'installation.json', description: 'Canonical global installation identity' },
 ];
 /**
  * Default user config values
@@ -60,26 +61,7 @@ export const DEFAULT_USER_CONFIG = {
  *   4. ~/.aiwg (default if neither exists)
  */
 export function resolveConfigDir(overridePath) {
-    // 1. Explicit override from env or CLI flag
-    const envOverride = process.env.AIWG_CONFIG;
-    if (overridePath) {
-        return resolve(overridePath);
-    }
-    if (envOverride) {
-        return resolve(envOverride);
-    }
-    // 2. Check primary path: ~/.aiwg
-    const primaryPath = resolve(homedir(), '.aiwg');
-    if (existsSync(primaryPath)) {
-        return primaryPath;
-    }
-    // 3. Check fallback path: ~/.config/aiwg
-    const fallbackPath = resolve(homedir(), '.config/aiwg');
-    if (existsSync(fallbackPath)) {
-        return fallbackPath;
-    }
-    // 4. Default to primary if neither exists
-    return primaryPath;
+    return resolveUserConfigDir({ configDir: overridePath });
 }
 /**
  * User-level configuration manager

package/dist/src/extensions/commands/definitions.js

@@ -164,6 +164,24 @@ export const updateCommand = {
         },
     },
 };
+export const installationCommand = {
+    id: 'installation',
+    type: 'command',
+    name: 'Installation Identity',
+    description: 'Inspect, adopt, or deliberately switch the canonical global AIWG installation',
+    version: '1.0.0',
+    capabilities: ['cli', 'installation', 'update', 'diagnostics', 'recovery'],
+    keywords: ['installation', 'canonical', 'adopt', 'switch', 'package-manager', 'drift'],
+    category: 'maintenance',
+    platforms: { claude: 'full', generic: 'full' },
+    deployment: { pathTemplate: '.{platform}/commands/{id}.md', core: true },
+    metadata: {
+        type: 'command',
+        template: 'utility',
+        argumentHint: '<show|adopt|switch> [--root <path>] [--method <npm|web|source>] [--manager <absolute-path>] [--json]',
+        allowedTools: ['Read', 'Write'],
+    },
+};
 // Renamed from `refreshCommand` as part of #694 (avoid collision with git sync
 // semantics) and re-linked to `refreshHandler` in #919. Users who type
 // `aiwg sync` still reach this handler via its 'sync' alias and see a
@@ -912,7 +930,7 @@ export const serveCommand = {
         triggerPhrases: ['serve dashboard', 'start server', 'open dashboard', 'aiwg serve'],
         commandHint: {
             template: 'utility',
-            argumentHint: '[--port <n>] [--bind <host>] [--no-open] [--read-only]',
+            argumentHint: '[--port <n>] [--bind <host>] [--no-open] [--read-only] [--a2a-protocol <0.3|1.0|auto>] [--a2a-protocol-fallback] [--no-a2a-legacy-executor-fallback]',
             allowedTools: ['Bash'],
         },
     },
@@ -3569,6 +3587,7 @@ export const commandDefinitions = [
     doctorCommand,
     contextFirewallCommand,
     updateCommand,
+    installationCommand,
     refreshCommand,
     regenerateCommand,
     workspaceContextCommand,

package/dist/src/features/catalog.js

@@ -72,7 +72,7 @@ export const FEATURE_CATALOG = [
     },
     {
         name: 'graph',
-        description: 'Graphology backend for rich artifact traversal and graph operators',
+        description: 'Graphology backend for artifact-index traversal only; not Flow graph execution',
         packages: ['graphology', 'graphology-operators', 'graphology-traversal'],
         packageSpecs: {
             graphology: '0.26.0',
@@ -82,6 +82,7 @@ export const FEATURE_CATALOG = [
         enables: [
             'index.graphBackend: graphology',
             'in-memory attributed graph traversal and operator workflows',
+            'artifact graph data operations (use graph-pattern addon for Flow execution graphs)',
         ],
         cost: '~2 MB — pure JS, no native deps',
     },

package/dist/src/flow/graph-metadata.js

@@ -0,0 +1,56 @@
+/** A2A/telemetry metadata key reserved for the optional Flow graph profile. */
+export const AIWG_GRAPH_METADATA_KEY = 'aiwg.flow.graph';
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export function isGraphExecutionMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const item = value;
+    return item.schemaVersion === 'graph.flow.aiwg.io/v1'
+        && nonEmpty(item.graphId)
+        && nonEmpty(item.graphVersion)
+        && nonEmpty(item.runId)
+        && nonEmpty(item.nodeId)
+        && nonEmpty(item.nodeRunId);
+}
+export function graphMetadataRecord(value) {
+    return { [AIWG_GRAPH_METADATA_KEY]: value };
+}
+export function extractGraphMetadata(metadata) {
+    const value = metadata?.[AIWG_GRAPH_METADATA_KEY];
+    return isGraphExecutionMetadata(value) ? value : undefined;
+}
+/**
+ * Project graph metadata to an explicitly named audience. Public projection
+ * removes execution identifiers and decision evidence. Cockpit receives only
+ * the declared route-decision summary; arbitrary user/task context is never a
+ * member of this contract and is therefore dropped by construction.
+ */
+export function projectGraphMetadata(value, audience) {
+    if (!isGraphExecutionMetadata(value))
+        throw new Error('Invalid graph execution metadata.');
+    if (audience === 'internal')
+        return structuredClone(value);
+    const common = {
+        schemaVersion: value.schemaVersion,
+        graphVersion: value.graphVersion,
+        nodeId: value.nodeId,
+        ...(value.edgeId ? { edgeId: value.edgeId } : {}),
+        ...(value.routeName ? { routeName: value.routeName } : {}),
+        ...(value.runtimeBinding ? { runtimeBinding: value.runtimeBinding } : {}),
+        ...(value.nodeState ? { nodeState: value.nodeState } : {}),
+    };
+    if (audience === 'public')
+        return common;
+    return {
+        ...common,
+        graphId: value.graphId,
+        runId: value.runId,
+        nodeRunId: value.nodeRunId,
+        ...(value.checkpointId ? { checkpointId: value.checkpointId } : {}),
+        ...(value.routeReason ? { routeReason: value.routeReason } : {}),
+        ...(value.routeEvidence === undefined ? {} : { routeEvidence: structuredClone(value.routeEvidence) }),
+    };
+}
+//# sourceMappingURL=graph-metadata.js.map