@aiwg/cli 2026.8.17 → 2026.8.19

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/use.js

@@ -1873,11 +1873,13 @@ async function deploySourceDirectory(opts) {
         args.push('--force');
     if (opts.copyAll)
         args.push('--copy-all');
+    if (opts.kernelOnly)
+        args.push('--kernel-only');
     if (opts.quiet)
         args.unshift('--quiet');
     const runner = createScriptRunner(opts.frameworkRoot);
     const result = await runner.run('tools/agents/deploy-agents.mjs', args, opts.quiet ? { capture: true } : {});
-    if (result.exitCode === 0) {
+    if (result.exitCode === 0 && !opts.kernelOnly) {
         try {
             await registerSourceCliCommands({
                 source: opts.source,
@@ -2436,6 +2438,7 @@ export class UseHandler {
             }
             ui.dim('  Use `aiwg use all` for the full deployment.');
             for (const providerName of providersForFiltered) {
+                const kernelOnly = !copyAll;
                 for (const selected of selectedFrameworks) {
                     const frameworkDir = resolveFrameworkDir(selected);
                     if (!frameworkDir)
@@ -2450,6 +2453,7 @@ export class UseHandler {
                         verbose,
                         force,
                         copyAll,
+                        kernelOnly,
                         quiet,
                         modelArgs: modelDeployArgs,
                     });
@@ -2467,6 +2471,7 @@ export class UseHandler {
                         verbose,
                         force,
                         copyAll,
+                        kernelOnly,
                         quiet,
                         modelArgs: modelDeployArgs,
                     });
@@ -2484,6 +2489,7 @@ export class UseHandler {
                         verbose,
                         force,
                         copyAll,
+                        kernelOnly,
                         quiet,
                         modelArgs: modelDeployArgs,
                     });
@@ -2985,6 +2991,11 @@ export class UseHandler {
         const providerDeployArgs = builtInProviderResolution.requestedProvider
             ? withProviderOverride(deployFilteredArgs, provider)
             : deployFilteredArgs;
+        const bulkKernelOnly = framework === 'all'
+            && !remainingArgs.includes('--copy-all')
+            && !remainingArgs.includes('--copy-standard-skills');
+        if (bulkKernelOnly)
+            providerDeployArgs.push('--kernel-only');
         const targetIdx = remainingArgs.findIndex(a => a === '--target');
         const target = targetIdx >= 0 && remainingArgs[targetIdx + 1] ? remainingArgs[targetIdx + 1] : process.cwd();
         if ((verbose || dryRun) && projectLocalProviderResolution.requestedProvider) {
@@ -3084,11 +3095,15 @@ export class UseHandler {
         }
         // Build common args for addon deployments (inherit provider and target)
         const addonBaseArgs = ['--deploy-commands', '--deploy-skills', '--deploy-rules'];
+        if (bulkKernelOnly)
+            addonBaseArgs.push('--kernel-only');
         addonBaseArgs.push(...modelDeployArgs);
         if (provider)
             addonBaseArgs.push('--provider', provider);
         if (target)
             addonBaseArgs.push('--target', target);
+        if (dryRun)
+            addonBaseArgs.push('--dry-run');
         if (verbose)
             addonBaseArgs.push('--verbose');
         // Forward --copy-all to addon deploys so the legacy mirror behavior
@@ -3182,7 +3197,7 @@ export class UseHandler {
         }
         await ensureProviderGeneratedDirsIgnored(target, provider, { dryRun, verbose });
         const paths = getProviderPaths(provider);
-        if (!dryRun && !skipUtils) {
+        if (!dryRun && !skipUtils && !bulkKernelOnly) {
             const wrapperValidation = await validateDeployedModelWrappers({
                 provider,
                 target,
@@ -3200,7 +3215,7 @@ export class UseHandler {
         const targetKernelSkillsDir = kernelSkillsPath ? resolveProviderPath(target, kernelSkillsPath) : '';
         // Translate deployed skills to commands for providers that require legacy command format.
         // (#550) Skills are canonical; commands are generated deployment artifacts.
-        if (providerNeedsCommands(provider) && targetCommandsDir) {
+        if (!bulkKernelOnly && providerNeedsCommands(provider) && targetCommandsDir) {
             try {
                 const translationResult = await translateSkillsToCommands(targetSkillsDir, {
                     provider,
@@ -3222,7 +3237,7 @@ export class UseHandler {
         // provider loads skills natively: users still expect setup, update,
         // status, intake, and flow workflows to show up in the provider's `/`
         // command picker where supported.
-        if (targetCommandsDir) {
+        if (!bulkKernelOnly && targetCommandsDir) {
             try {
                 const standardMirrored = await mirrorStandardCommandSkills({
                     provider,

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

package/dist/src/installation/manager-command.mjs

@@ -0,0 +1,31 @@
+import { execFileSync } from 'node:child_process';
+
+function quoteCmdArgument(value) {
+  return `"${String(value).replace(/%/g, '%%').replace(/"/g, '""')}"`;
+}
+
+/**
+ * Resolve a package-manager invocation without asking Node to execute a
+ * Windows command script directly. Node rejects direct .cmd/.bat execution on
+ * current Windows releases; cmd.exe is the native interpreter for those files.
+ */
+export function resolveManagerCommand(file, args, options = {}) {
+  const platform = options.platform ?? process.platform;
+  if (platform !== 'win32' || !/\.(?:cmd|bat)$/i.test(file)) {
+    return { file, args };
+  }
+
+  const env = options.env ?? process.env;
+  const commandInterpreter = env.ComSpec || env.COMSPEC || 'cmd.exe';
+  const command = `"${[file, ...args].map(quoteCmdArgument).join(' ')}"`;
+  return {
+    file: commandInterpreter,
+    args: ['/d', '/s', '/c', command],
+  };
+}
+
+export function executeManagerCommand(file, args, options = {}) {
+  const invocation = resolveManagerCommand(file, args, options);
+  const execute = options.execute ?? execFileSync;
+  return execute(invocation.file, invocation.args, options.execOptions ?? { stdio: 'inherit' });
+}