@aiwg/cli 2026.8.17 → 2026.8.18

package/bin/aiwg.mjs

@@ -46,7 +46,18 @@ function detectVersionChannel(version) {
   if (version.includes('-alpha.')) return 'alpha';
   if (version.includes('-nightly.')) return 'nightly';
   try {
-    const raw = readFileSync(path.join(os.homedir(), '.aiwg', 'channel.json'), 'utf8');
+    const legacyDir = path.join(os.homedir(), '.aiwg');
+    const xdgDir = path.join(os.homedir(), '.config', 'aiwg');
+    const configDir = process.env.AIWG_CONFIG
+      ? path.resolve(process.env.AIWG_CONFIG)
+      : existsSync(legacyDir) ? legacyDir : existsSync(xdgDir) ? xdgDir : legacyDir;
+    const installationFile = path.join(configDir, 'installation.json');
+    if (existsSync(installationFile)) {
+      const installation = JSON.parse(readFileSync(installationFile, 'utf8'));
+      if (installation?.runMode === 'development') return 'dev';
+      if (typeof installation?.channel === 'string') return installation.channel;
+    }
+    const raw = readFileSync(path.join(configDir, 'channel.json'), 'utf8');
     const cfg = JSON.parse(raw);
     if (cfg?.devMode) return 'dev';
     if (typeof cfg?.channel === 'string') return cfg.channel;
@@ -124,6 +135,7 @@ const FAST_HELP_TEXT = `
 
   VALIDATION
     validate-metadata [path]     Validate AIWG component metadata (defaults to agentic/code)
+    installation <action>        Inspect/adopt/switch canonical global installation
     verify <artifact>            Verify DSSE provenance using an explicit versioned trust root
     verify trust <action>        Bootstrap, update, or inspect artifact trust state
     context-firewall [scan]      Audit provider context, trust, drift, poisoning signals, and budget
@@ -368,9 +380,19 @@ async function main() {
 
   // Resolve the active router once. In dev mode this points into the checkout,
   // while packageRoot still points at the globally installed launcher.
-  const routerPath = await resolveRouterPath();
+  const routerPath = args[0] === 'installation'
+    ? path.join(packageRoot, 'dist', 'src', 'cli', 'router.js')
+    : await resolveRouterPath();
   const activePackageRoot = path.resolve(path.dirname(routerPath), '..', '..', '..');
 
+  // Fail closed when a different installation wins PATH resolution. Recovery
+  // commands remain reachable so an operator can explicitly adopt or switch.
+  if (args[0] !== 'installation') {
+    const identityPath = path.join(activePackageRoot, 'dist', 'src', 'installation', 'manager.mjs');
+    const { assertCanonicalInstallation } = await import(pathToFileURL(identityPath).href);
+    assertCanonicalInstallation({ actualRoot: activePackageRoot });
+  }
+
   // Wire up the logger level from -v/-vv/--quiet/AIWG_LOG_LEVEL before any
   // handler runs, and stamp the top-level invocation ID so the logger can
   // tag every record with it.

package/dist/src/a2a/agent-card.js

@@ -11,6 +11,7 @@
 // The card declares required + optional extensions, supported transports,
 // and skills.
 import { loadJwkSet, verifyAgentCardSignature } from './jws.js';
+import { normalizeAgentCard } from './protocol.js';
 const DEFAULT_TTL_MS = 5 * 60 * 1000;
 export class AgentCardCache {
     ttlMs;
@@ -83,8 +84,9 @@ export async function fetchAgentCard(host, instanceId, opts = {}) {
     catch (err) {
         throw new Error(`fetchAgentCard: invalid JSON from ${url}: ${err.message}`);
     }
+    const normalized = normalizeAgentCard(card);
     if (opts.skipVerify) {
-        return { card, raw, verifiedAt: new Date().toISOString() };
+        return { card, normalized, raw, verifiedAt: new Date().toISOString() };
     }
     let jwks = opts.jwks;
     if (!jwks) {
@@ -98,6 +100,7 @@ export async function fetchAgentCard(host, instanceId, opts = {}) {
     verifyAgentCardSignature(raw, jwks);
     const verified = {
         card,
+        normalized,
         raw,
         verifiedAt: new Date().toISOString(),
     };

package/dist/src/a2a/client.js

@@ -15,6 +15,9 @@
 //   GET    /agents/{id}/v1/extendedAgentCard            (extended card)
 //   GET    /agents/{id}/v1/card                         (legacy extended card)
 import { A2AError, A2AHttpClient } from './http.js';
+import { decodePushNotificationConfig, decodeSendMessageResponse, decodeTask, encodeMessage, encodePushNotificationConfig, } from './codecs.js';
+import { A2AEventReconciler, decodeStreamResponse } from './events.js';
+import { normalizeAgentCard, selectAgentInterface } from './protocol.js';
 export const A2A_RUNTIME_V1 = 'https://agentic-sandbox.aiwg.io/extensions/runtime/v1';
 export const A2A_IDEMPOTENCY_V1 = 'https://agentic-sandbox.aiwg.io/extensions/idempotency/v1';
 export const A2A_HITL_PROMPT_V1 = 'https://agentic-sandbox.aiwg.io/extensions/hitl-prompt/v1';
@@ -25,21 +28,84 @@ export const A2A_PTY_EXTENSIONS_V1 = 'https://agentic-sandbox.aiwg.io/extensions
 export const DEFAULT_REQUIRED_EXTENSIONS = [A2A_RUNTIME_V1, A2A_IDEMPOTENCY_V1];
 export class A2AClient {
     instanceId;
+    protocolVersion;
+    protocolPolicy;
+    selectedInterface;
     http;
     extensionSet;
+    fallbackClient;
+    allowProtocolFallback;
+    onProtocolFallback;
     constructor(opts) {
         this.instanceId = opts.instanceId;
+        this.protocolPolicy = opts.protocolPolicy ?? opts.protocolVersion ?? '0.3';
+        if (this.protocolPolicy === 'auto' && !opts.selectedInterface) {
+            throw new Error('A2AClient protocolPolicy=auto requires A2AClient.negotiate() or selectedInterface');
+        }
+        this.selectedInterface = opts.selectedInterface;
+        this.protocolVersion = opts.selectedInterface?.protocolVersion ?? opts.protocolVersion ?? '0.3';
+        this.allowProtocolFallback = opts.allowProtocolFallback ?? false;
+        this.onProtocolFallback = opts.onProtocolFallback;
         const required = opts.requiredExtensions ?? DEFAULT_REQUIRED_EXTENSIONS;
         const optional = opts.optionalExtensions ?? [];
         this.extensionSet = [...required, ...optional];
         this.http = new A2AHttpClient({
             ...opts,
+            baseUrl: opts.selectedInterface?.url ?? opts.baseUrl,
+            protocolVersion: this.protocolVersion,
             defaultExtensions: this.extensionSet,
         });
+        if (opts.selectedInterface && opts.onProtocolSelection) {
+            opts.onProtocolSelection({
+                selected: this.protocolVersion,
+                interface: opts.selectedInterface,
+                policy: this.protocolPolicy,
+            });
+        }
+    }
+    /** Discover, normalize, and select an AgentCard interface deterministically. */
+    static async negotiate(opts) {
+        const policy = opts.protocolPolicy ?? 'auto';
+        const { selectedInterface: _ignoredSelectedInterface, protocolVersion: _ignoredProtocolVersion, onProtocolSelection, ...negotiationOpts } = opts;
+        const discovery = new A2AClient({ ...negotiationOpts, protocolPolicy: '0.3', protocolVersion: '0.3' });
+        const card = await discovery.getAgentCard();
+        const normalized = normalizeAgentCard(card);
+        const selected = selectAgentInterface(normalized, { policy });
+        const client = new A2AClient({
+            ...negotiationOpts,
+            protocolPolicy: policy,
+            protocolVersion: selected.protocolVersion,
+            selectedInterface: selected,
+        });
+        if (policy === 'auto' && selected.protocolVersion === '1.0' && opts.allowProtocolFallback) {
+            try {
+                const fallback = selectAgentInterface(normalized, { policy: '0.3' });
+                client.fallbackClient = new A2AClient({
+                    ...negotiationOpts,
+                    protocolPolicy: '0.3',
+                    protocolVersion: '0.3',
+                    selectedInterface: fallback,
+                    allowProtocolFallback: false,
+                });
+            }
+            catch {
+                // No compatible 0.3 interface; auto remains 1.0-only.
+            }
+        }
+        // Fire once for the interface actually selected for use; the dormant
+        // downgrade adapter is not itself a selection event.
+        onProtocolSelection?.({ selected: selected.protocolVersion, interface: selected, policy });
+        return client;
     }
     agentPath() {
         return `/agents/${encodeURIComponent(this.instanceId)}/v1`;
     }
+    operationPath(v1Path, legacyPath) {
+        if (this.selectedInterface) {
+            return this.protocolVersion === '1.0' ? `/${v1Path}` : `/v1/${legacyPath}`;
+        }
+        return `${this.agentPath()}/${legacyPath}`;
+    }
     // ---------- AgentCard ----------
     /**
      * Fetch the well-known unsigned card. Callers that need verification should
@@ -115,15 +181,32 @@ export class A2AClient {
      * `idempotentReplayed: true`.
      */
     async sendMessage(message, opts = {}) {
-        const path = `${this.agentPath()}/messages:send`;
+        const path = this.operationPath('message:send', 'messages:send');
         const requestOptions = {
             method: 'POST',
-            body: { message },
+            body: { message: encodeMessage(this.protocolVersion, message) },
             extensions: opts.extensions ? [...opts.extensions] : this.extensionSet,
         };
         if (opts.signal)
             requestOptions.signal = opts.signal;
-        const resp = await this.http.request(path, requestOptions);
+        let resp;
+        try {
+            resp = await this.http.request(path, requestOptions);
+        }
+        catch (error) {
+            if (error instanceof A2AError
+                && error.versionNotSupported
+                && this.protocolVersion === '1.0'
+                && this.protocolPolicy === 'auto'
+                && this.allowProtocolFallback
+                && this.fallbackClient) {
+                const reason = `${error.problem.type}: ${error.problem.detail ?? error.problem.title}`;
+                this.onProtocolFallback?.({ from: '1.0', to: '0.3', reason });
+                const fallback = await this.fallbackClient.sendMessage(message, opts);
+                return { ...fallback, fallbackReason: reason };
+            }
+            throw error;
+        }
         if (!resp.body) {
             throw new A2AError(resp.status, path, {
                 type: 'about:blank',
@@ -131,15 +214,18 @@ export class A2AClient {
                 code: 'aiwg.empty_send_message',
             });
         }
+        const task = decodeSendMessageResponse(this.protocolVersion, resp.body);
         return {
-            task: resp.body,
+            task,
             idempotentReplayed: resp.idempotentReplayed,
             activatedExtensions: resp.activatedExtensions,
+            protocolVersion: this.protocolVersion,
+            ...(this.selectedInterface ? { selectedInterface: this.selectedInterface } : {}),
         };
     }
     // ---------- Tasks ----------
     async getTask(taskId, opts = {}) {
-        const path = `${this.agentPath()}/tasks/${encodeURIComponent(taskId)}`;
+        const path = this.operationPath(`tasks/${encodeURIComponent(taskId)}`, `tasks/${encodeURIComponent(taskId)}`);
         const requestOptions = { method: 'GET' };
         if (opts.signal)
             requestOptions.signal = opts.signal;
@@ -151,24 +237,27 @@ export class A2AClient {
                 code: 'aiwg.empty_get_task',
             });
         }
-        return resp.body;
+        return decodeTask(this.protocolVersion, resp.body);
     }
     /** List tasks for this instance, optionally filtered by state. */
     async listTasks(filter = {}) {
         const params = new URLSearchParams();
         if (filter.state)
-            params.set('state', filter.state);
+            params.set(this.protocolVersion === '1.0' ? 'status' : 'state', filter.state);
         if (filter.limit !== undefined)
-            params.set('limit', String(filter.limit));
+            params.set(this.protocolVersion === '1.0' ? 'pageSize' : 'limit', String(filter.limit));
         const query = params.toString();
-        const path = `${this.agentPath()}/tasks${query ? '?' + query : ''}`;
+        const basePath = this.operationPath('tasks', 'tasks');
+        const path = `${basePath}${query ? '?' + query : ''}`;
         const resp = await this.http.request(path, { method: 'GET' });
         if (!resp.body)
             return [];
-        return Array.isArray(resp.body) ? resp.body : resp.body.tasks ?? [];
+        const raw = Array.isArray(resp.body) ? resp.body : resp.body.tasks ?? [];
+        return raw.map((task, index) => decodeTask(this.protocolVersion, task, `$.tasks[${index}]`));
     }
     async cancelTask(taskId, opts = {}) {
-        const path = `${this.agentPath()}/tasks/${encodeURIComponent(taskId)}/cancel`;
+        const encoded = encodeURIComponent(taskId);
+        const path = this.operationPath(`tasks/${encoded}:cancel`, `tasks/${encoded}/cancel`);
         const requestOptions = {
             method: 'POST',
             body: {},
@@ -184,7 +273,11 @@ export class A2AClient {
                 code: 'aiwg.empty_cancel_task',
             });
         }
-        return resp.body;
+        const body = this.protocolVersion === '1.0'
+            && resp.body && typeof resp.body === 'object' && 'task' in resp.body
+            ? resp.body.task
+            : resp.body;
+        return decodeTask(this.protocolVersion, body);
     }
     // ---------- Task subscription (SSE) ----------
     /**
@@ -205,7 +298,9 @@ export class A2AClient {
             params.set('replay_from', String(opts.replayFromSeq));
         }
         const query = params.toString();
-        const path = `${this.agentPath()}/tasks/${encodeURIComponent(taskId)}/subscribe${query ? '?' + query : ''}`;
+        const encoded = encodeURIComponent(taskId);
+        const basePath = this.operationPath(`tasks/${encoded}:subscribe`, `tasks/${encoded}/subscribe`);
+        const path = `${basePath}${query ? '?' + query : ''}`;
         const controller = new AbortController();
         const externalSignal = opts.signal;
         if (externalSignal) {
@@ -215,10 +310,11 @@ export class A2AClient {
                 externalSignal.addEventListener('abort', () => controller.abort(), { once: true });
         }
         const http = this.http;
+        const protocolVersion = this.protocolVersion;
         let cancelled = false;
         async function* iterate() {
             const resp = await http.request(path, {
-                method: 'GET',
+                method: protocolVersion === '1.0' ? 'POST' : 'GET',
                 headers: { accept: 'text/event-stream' },
                 signal: controller.signal,
                 raw: true,
@@ -238,12 +334,21 @@ export class A2AClient {
                     code: 'aiwg.subscribe_empty_body',
                 });
             }
+            const reconciler = new A2AEventReconciler({
+                taskId,
+                requireInitialSnapshot: protocolVersion === '1.0',
+            });
             for await (const frame of parseEventStream(resp.rawBody)) {
                 if (cancelled)
                     return;
-                const event = decodeStreamEvent(frame);
-                if (event)
-                    yield event;
+                const event = decodeStreamEvent(protocolVersion, frame);
+                if (!event)
+                    continue;
+                const accepted = reconciler.accept(event);
+                if (accepted)
+                    yield accepted;
+                if (reconciler.isTerminal())
+                    return;
             }
         }
         const generator = iterate();
@@ -259,10 +364,10 @@ export class A2AClient {
     }
     // ---------- Push notification configs ----------
     async createPushNotificationConfig(taskId, config) {
-        const path = `${this.agentPath()}/tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs`;
+        const path = this.operationPath(`tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs`, `tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs`);
         const resp = await this.http.request(path, {
             method: 'POST',
-            body: config,
+            body: encodePushNotificationConfig(this.protocolVersion, config),
             extensions: [...this.extensionSet],
         });
         if (!resp.body) {
@@ -272,10 +377,11 @@ export class A2AClient {
                 code: 'aiwg.empty_push_config_create',
             });
         }
-        return resp.body;
+        return decodePushNotificationConfig(this.protocolVersion, resp.body);
     }
     async getPushNotificationConfig(taskId, configId) {
-        const path = `${this.agentPath()}/tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs/${encodeURIComponent(configId)}`;
+        const suffix = `tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs/${encodeURIComponent(configId)}`;
+        const path = this.operationPath(suffix, suffix);
         const resp = await this.http.request(path, { method: 'GET' });
         if (!resp.body) {
             throw new A2AError(resp.status, path, {
@@ -284,10 +390,11 @@ export class A2AClient {
                 code: 'aiwg.empty_push_config_get',
             });
         }
-        return resp.body;
+        return decodePushNotificationConfig(this.protocolVersion, resp.body);
     }
     async deletePushNotificationConfig(taskId, configId) {
-        const path = `${this.agentPath()}/tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs/${encodeURIComponent(configId)}`;
+        const suffix = `tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs/${encodeURIComponent(configId)}`;
+        const path = this.operationPath(suffix, suffix);
         await this.http.request(path, {
             method: 'DELETE',
             extensions: [...this.extensionSet],
@@ -357,55 +464,28 @@ export async function* parseEventStream(stream) {
         reader.releaseLock();
     }
 }
-function decodeStreamEvent(frame) {
+export function decodeStreamEvent(protocolVersion, frame) {
     if (!frame.data)
         return null;
+    let obj;
     try {
-        const obj = JSON.parse(frame.data);
-        // Prefer the `kind` field if present (matches StreamEvent discriminator).
-        // Otherwise fall back to `event:` header from the frame.
-        const kindFromBody = typeof obj['kind'] === 'string' ? obj['kind'] : undefined;
-        const kind = kindFromBody ?? frame.event;
-        if (!kind)
-            return null;
-        switch (kind) {
-            case 'task-state':
-                if (obj['task']) {
-                    return { kind: 'task-state', task: obj['task'] };
-                }
-                return null;
-            case 'status-update':
-                if (typeof obj['taskId'] === 'string' && obj['status']) {
-                    const out = {
-                        kind: 'status-update',
-                        taskId: obj['taskId'],
-                        status: obj['status'],
-                    };
-                    if (typeof obj['final'] === 'boolean') {
-                        out.final = obj['final'];
-                    }
-                    return out;
-                }
-                return null;
-            case 'artifact-update':
-                if (typeof obj['taskId'] === 'string' && obj['artifact']) {
-                    const out = {
-                        kind: 'artifact-update',
-                        taskId: obj['taskId'],
-                        artifact: obj['artifact'],
-                    };
-                    if (typeof obj['append'] === 'boolean') {
-                        out.append = obj['append'];
-                    }
-                    return out;
-                }
-                return null;
-            default:
-                return null;
-        }
+        obj = JSON.parse(frame.data);
     }
-    catch {
-        return null;
+    catch (error) {
+        throw new A2AError(502, 'sse', {
+            type: 'about:blank',
+            title: 'Invalid SSE JSON',
+            detail: error.message,
+            code: 'aiwg.invalid_stream_json',
+        });
     }
+    const sequence = frame.id !== undefined && /^\d+$/.test(frame.id)
+        ? Number(frame.id)
+        : undefined;
+    return decodeStreamResponse(protocolVersion, obj, {
+        ...(frame.event ? { eventName: frame.event } : {}),
+        ...(frame.id ? { eventId: frame.id } : {}),
+        ...(sequence !== undefined ? { sequence } : {}),
+    });
 }
 //# sourceMappingURL=client.js.map