@evomap/evolver-adapter-public 2.0.0-beta.17 → 2.0.0-beta.19

package/dist/auth/oauthDeviceToken.d.ts

@@ -15,11 +15,11 @@ export interface TokenResp {
 }
 /** 注入的 OAuth device flow 传输(M6-6 真 HTTP; 测试用桩). refresh 走 refresh_token grant. */
 export interface OAuthTransport {
-    requestDeviceCode: (fingerprint: string) => Promise<DeviceCodeResp>;
-    pollToken: (deviceCode: string) => Promise<TokenResp | {
+    requestDeviceCode: (fingerprint: string, signal?: AbortSignal) => Promise<DeviceCodeResp>;
+    pollToken: (deviceCode: string, signal?: AbortSignal) => Promise<TokenResp | {
         pending: true;
     }>;
-    refresh?: (refreshToken: string) => Promise<TokenResp>;
+    refresh?: (refreshToken: string, signal?: AbortSignal) => Promise<TokenResp>;
 }
 export interface PublicOAuthOptions {
     credPath: string;
@@ -32,6 +32,8 @@ export interface PublicOAuthOptions {
     sleep?: (ms: number) => Promise<void>;
     /** 整个 device flow 的最长等待(默认 15min); 超时抛 device_flow_timeout. */
     maxWaitMs?: number;
+    /** Provider-level refresh bound, including injected transports. */
+    refreshTimeoutMs?: number;
 }
 /**
  * device token 认证(M6-5, 默认路径 evolver login). device code flow(学 gh auth login):
@@ -45,6 +47,7 @@ export declare class PublicOAuthProvider implements hub.AuthProvider {
     private readonly now;
     private readonly sleep;
     private readonly maxWaitMs;
+    private readonly refreshTimeoutMs;
     constructor(opts: PublicOAuthOptions);
     private fingerprint;
     /**
@@ -54,9 +57,9 @@ export declare class PublicOAuthProvider implements hub.AuthProvider {
      * itself (respecting the server interval); a terminal error from the transport
      * (access_denied / expired_token) propagates.
      */
-    login(): Promise<hub.Credential>;
-    authenticate(): Promise<hub.SignedRequest>;
-    rotate(): Promise<hub.Credential>;
+    login(parentSignal?: AbortSignal): Promise<hub.Credential>;
+    authenticate(req?: hub.HttpRequestLike): Promise<hub.SignedRequest>;
+    rotate(parentSignal?: AbortSignal): Promise<hub.Credential>;
     revoke(): Promise<void>;
     private persist;
 }

package/dist/auth/oauthDeviceToken.js

@@ -2,6 +2,43 @@ import { CredentialStore } from './credentialStore.js';
 import { resolveMachineId, machineFingerprint } from './machineId.js';
 export const TOKEN_TTL_MS = 24 * 60 * 60_000; // fallback only; the hub supplies expiresInMs (~1h)
 export const ROTATE_BEFORE_MS = 5 * 60_000; // refresh 5min before expiry (hub access tokens are short-lived ~1h)
+const DEFAULT_REFRESH_TIMEOUT_MS = 15_000;
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error('device_flow_timeout');
+}
+async function awaitWithAbort(promise, signal) {
+    const pending = Promise.resolve(promise);
+    if (signal.aborted) {
+        void pending.catch(() => { });
+        throw abortReason(signal);
+    }
+    return await new Promise((resolve, reject) => {
+        const cleanup = () => signal.removeEventListener('abort', onAbort);
+        const onAbort = () => {
+            cleanup();
+            reject(abortReason(signal));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        void pending.then((value) => { cleanup(); resolve(value); }, (error) => { cleanup(); reject(error); });
+    });
+}
+function linkedTimeoutSignal(parent, timeoutMs, timeoutReason) {
+    const controller = new AbortController();
+    const abortFromParent = () => controller.abort(parent?.reason);
+    if (parent?.aborted)
+        abortFromParent();
+    else
+        parent?.addEventListener('abort', abortFromParent, { once: true });
+    const timeout = setTimeout(() => controller.abort(timeoutReason), timeoutMs);
+    timeout.unref?.();
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            clearTimeout(timeout);
+            parent?.removeEventListener('abort', abortFromParent);
+        },
+    };
+}
 /**
  * device token 认证(M6-5, 默认路径 evolver login). device code flow(学 gh auth login):
  * 显示 user code → 用户在浏览器授权 → 轮询拿 token. 绑机器指纹(CEO: OS machineId+软兜底).
@@ -14,12 +51,14 @@ export class PublicOAuthProvider {
     now;
     sleep;
     maxWaitMs;
+    refreshTimeoutMs;
     constructor(opts) {
         this.opts = opts;
         this.store = new CredentialStore(opts.credPath);
         this.now = opts.now ?? (() => Date.now());
         this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
         this.maxWaitMs = opts.maxWaitMs ?? 15 * 60_000;
+        this.refreshTimeoutMs = Math.max(1, opts.refreshTimeoutMs ?? DEFAULT_REFRESH_TIMEOUT_MS);
     }
     fingerprint() { return machineFingerprint(resolveMachineId(this.opts.machine).id); }
     /**
@@ -29,43 +68,57 @@ export class PublicOAuthProvider {
      * itself (respecting the server interval); a terminal error from the transport
      * (access_denied / expired_token) propagates.
      */
-    async login() {
+    async login(parentSignal) {
         const cached = this.store.load();
         if (cached && 'token' in cached && (cached.expiresAt ?? 0) - ROTATE_BEFORE_MS > this.now())
             return cached;
         const fp = this.fingerprint();
-        const dc = await this.opts.transport.requestDeviceCode(fp);
-        (this.opts.onUserCode ?? ((d) => { process.stdout.write(`授权码 ${d.userCode} → ${d.verificationUri}\n`); }))(dc);
         const deadline = this.now() + this.maxWaitMs;
-        let intervalMs = dc.intervalMs;
-        for (;;) {
-            const res = await this.opts.transport.pollToken(dc.deviceCode);
-            if (!('pending' in res))
-                return this.persist(res, fp);
-            if (this.now() >= deadline)
-                throw new Error('device_flow_timeout');
-            await this.sleep(intervalMs);
-            intervalMs += 1000; // gentle back-off; the hub's slow_down also surfaces as pending
+        const deadlineSignal = linkedTimeoutSignal(parentSignal, Math.max(0, this.maxWaitMs), new Error('device_flow_timeout'));
+        try {
+            const dc = await awaitWithAbort(this.opts.transport.requestDeviceCode(fp, deadlineSignal.signal), deadlineSignal.signal);
+            (this.opts.onUserCode ?? ((d) => { process.stdout.write(`授权码 ${d.userCode} → ${d.verificationUri}\n`); }))(dc);
+            let intervalMs = dc.intervalMs;
+            for (;;) {
+                if (this.now() >= deadline)
+                    throw new Error('device_flow_timeout');
+                const res = await awaitWithAbort(this.opts.transport.pollToken(dc.deviceCode, deadlineSignal.signal), deadlineSignal.signal);
+                if (!('pending' in res))
+                    return this.persist(res, fp);
+                if (this.now() >= deadline)
+                    throw new Error('device_flow_timeout');
+                await awaitWithAbort(this.sleep(intervalMs), deadlineSignal.signal);
+                intervalMs += 1000; // gentle back-off; the hub's slow_down also surfaces as pending
+            }
+        }
+        finally {
+            deadlineSignal.dispose();
         }
     }
-    async authenticate() {
+    async authenticate(req) {
         let cred = this.store.load();
         if (!cred || !('token' in cred))
             throw new Error('oauth 未登录, 先 login()');
         if ((cred.expiresAt ?? 0) - ROTATE_BEFORE_MS <= this.now())
-            cred = await this.rotate();
+            cred = await this.rotate(req?.signal);
         return { headers: { authorization: `Bearer ${cred.token}`, 'x-evomap-device': cred.device ?? '' } };
     }
-    async rotate() {
+    async rotate(parentSignal) {
         const cred = this.store.load();
         const fp = this.fingerprint();
         // Prefer a seamless refresh_token rotation; fall back to a fresh device-flow
         // login only when there is no usable refresh token (or no refresh transport).
         if (cred && 'refreshToken' in cred && cred.refreshToken && this.opts.transport.refresh) {
-            const res = await this.opts.transport.refresh(cred.refreshToken);
-            return this.persist(res, fp, cred.refreshToken);
+            const refreshSignal = linkedTimeoutSignal(parentSignal, this.refreshTimeoutMs, new Error('oauth_refresh_timeout'));
+            try {
+                const res = await awaitWithAbort(this.opts.transport.refresh(cred.refreshToken, refreshSignal.signal), refreshSignal.signal);
+                return this.persist(res, fp, cred.refreshToken);
+            }
+            finally {
+                refreshSignal.dispose();
+            }
         }
-        return this.login();
+        return this.login(parentSignal);
     }
     async revoke() { }
     // fallbackRefresh: carry the prior refresh token forward when the hub's refresh

package/dist/auth/oauthHttpTransport.d.ts

@@ -16,6 +16,10 @@ export interface OAuthHttpTransportOptions {
     scopes?: string[];
     /** Injected for tests; defaults to the secure global fetch (https guard + forced TLS). */
     fetchFn?: FetchLike;
+    /** Per-request deadline. The device-flow provider separately enforces its total deadline. */
+    timeoutMs?: number;
+    /** Defensive response cap; configurable only to keep boundary tests small. */
+    maxResponseBytes?: number;
 }
 /**
  * Real HTTP transport (M6-6) for the RFC 8628 device authorization grant. The

package/dist/auth/oauthHttpTransport.js

@@ -1,4 +1,4 @@
-import { assertHubUrlSecure, globalFetchLike } from '../hubFetch.js';
+import { assertHubUrlSecure, drainHubResponse, globalFetchLike, HUB_GENERAL_TIMEOUT_MS, HUB_JSON_TEXT_MAX_BYTES, readHubResponseJson, } from '../hubFetch.js';
 const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
 /** First-party public client seeded on the hub (scripts/seed-evolver-oauth-client.js). */
 export const DEFAULT_CLIENT_ID = 'evolver-cli';
@@ -27,26 +27,77 @@ export function createOAuthHttpTransport(opts) {
     const clientId = opts.clientId ?? DEFAULT_CLIENT_ID;
     const scope = (opts.scopes ?? DEFAULT_SCOPES).join(' ');
     const fetchFn = opts.fetchFn ?? globalFetchLike;
-    async function postJson(path, body) {
+    const timeoutMs = Math.max(1, opts.timeoutMs ?? HUB_GENERAL_TIMEOUT_MS);
+    const maxResponseBytes = Math.max(1, opts.maxResponseBytes ?? HUB_JSON_TEXT_MAX_BYTES);
+    async function postJson(path, body, parentSignal) {
         const url = `${base}${path}`;
         assertHubUrlSecure(url); // defense in depth; also enforced inside globalFetchLike
-        const res = await fetchFn(url, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(body),
-        });
-        const json = (await res.json().catch(() => ({})));
-        return { status: res.status, json };
+        const controller = new AbortController();
+        const timeoutError = new Error(`${path} timed out after ${timeoutMs}ms`);
+        const timeout = setTimeout(() => controller.abort(timeoutError), timeoutMs);
+        timeout.unref?.();
+        const onParentAbort = () => controller.abort(parentSignal?.reason instanceof Error ? parentSignal.reason : new Error('device_flow_timeout'));
+        if (parentSignal?.aborted)
+            onParentAbort();
+        else
+            parentSignal?.addEventListener('abort', onParentAbort, { once: true });
+        const awaitRequest = async (promise) => {
+            const pending = Promise.resolve(promise);
+            if (controller.signal.aborted) {
+                void pending.catch(() => { });
+                throw controller.signal.reason;
+            }
+            return await new Promise((resolve, reject) => {
+                const cleanup = () => controller.signal.removeEventListener('abort', onAbort);
+                const onAbort = () => { cleanup(); reject(controller.signal.reason); };
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+                void pending.then((value) => { cleanup(); resolve(value); }, (error) => { cleanup(); reject(error); });
+            });
+        };
+        try {
+            const res = await awaitRequest(fetchFn(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                redirect: 'manual',
+                signal: controller.signal,
+            }));
+            if (res.status >= 300 && res.status < 400) {
+                await drainHubResponse(res, { signal: controller.signal });
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                throw new Error(`${path} refused an unexpected Hub redirect (HTTP ${res.status})`);
+            }
+            let json;
+            try {
+                json = await awaitRequest(readHubResponseJson(res, {
+                    maxBytes: maxResponseBytes,
+                    signal: controller.signal,
+                }));
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                if (!(error instanceof SyntaxError))
+                    throw error;
+                json = {};
+            }
+            return { status: res.status, json };
+        }
+        finally {
+            clearTimeout(timeout);
+            parentSignal?.removeEventListener('abort', onParentAbort);
+        }
     }
     return {
-        async requestDeviceCode(_fingerprint) {
+        async requestDeviceCode(_fingerprint, signal) {
             // The hub binds the device authorization to the client + the approving
             // user, not to a machine fingerprint, so the fingerprint is not sent here;
             // it is bound locally on the resulting credential (x-evomap-device header).
             const { status, json } = await postJson('/oauth/device_authorization', {
                 client_id: clientId,
                 scope,
-            });
+            }, signal);
             if (status >= 400 || !json.device_code || !json.user_code) {
                 throw new Error(`device_authorization failed (HTTP ${status}): ${json.error ?? 'no device_code'}`);
             }
@@ -57,12 +108,12 @@ export function createOAuthHttpTransport(opts) {
                 intervalMs: (json.interval ?? 5) * 1000,
             };
         },
-        async pollToken(deviceCode) {
+        async pollToken(deviceCode, signal) {
             const { status, json } = await postJson('/oauth/token', {
                 grant_type: DEVICE_GRANT,
                 device_code: deviceCode,
                 client_id: clientId,
-            });
+            }, signal);
             if (json.access_token) {
                 return tokenResp(json);
             }
@@ -71,12 +122,12 @@ export function createOAuthHttpTransport(opts) {
             }
             throw new Error(`token poll failed (HTTP ${status}): ${json.error ?? 'unknown'}`);
         },
-        async refresh(refreshToken) {
+        async refresh(refreshToken, signal) {
             const { status, json } = await postJson('/oauth/token', {
                 grant_type: 'refresh_token',
                 refresh_token: refreshToken,
                 client_id: clientId,
-            });
+            }, signal);
             if (!json.access_token) {
                 throw new Error(`refresh failed (HTTP ${status}): ${json.error ?? 'no access_token'}`);
             }

package/dist/hubCapability.d.ts

@@ -59,7 +59,9 @@ export interface AccountAssetListResult {
     nextCursor?: string;
 }
 /** 完整 GEP-A2A 信封(实测 dev: publish/fetch/validate 等协议消息端点必须全信封, 非仅 protocol+message_type). */
-export declare function gepEnvelope(messageType: string, payload: unknown): Record<string, unknown>;
+export declare function gepEnvelope(messageType: string, payload: unknown, options?: {
+    messageId?: string;
+}): Record<string, unknown>;
 export interface PublicHubOptions {
     baseUrl: string;
     auth: hub.AuthProvider;
@@ -74,6 +76,8 @@ export interface PublicHelloResult {
     ok: boolean;
     authError?: boolean;
     nodeId?: string;
+    claimCode?: string;
+    claimUrl?: string;
     nodeSecretVersion?: number;
     rateLimitUntilMs?: number;
     error?: string;
@@ -124,6 +128,7 @@ export interface PublicHeartbeatResult {
         reason?: string;
     };
     forceUpdate?: PublicForceUpdateDirective;
+    capabilityGaps?: readonly string[];
 }
 export declare function isHubDryRunEnabled(env?: Record<string, string | undefined>): boolean;
 export declare function outboundMaxBodyBytes(env?: Record<string, string | undefined>): number;
@@ -140,12 +145,13 @@ export declare class PublicHubCapability implements hub.HubCapability {
     hello(opts: PublicHelloOptions): Promise<PublicHelloResult>;
     heartbeat(opts?: PublicHeartbeatOptions): Promise<PublicHeartbeatResult>;
     private heartbeatMeta;
-    publish(bundle: hub.AssetRecord[]): Promise<hub.PublishReceipt>;
+    publish(bundle: hub.AssetRecord[], options?: hub.PublishOptions): Promise<hub.PublishReceipt>;
     fetch(query: hub.HubQuery): Promise<hub.AssetRecord[]>;
     fetchAssetById(assetId: string): Promise<hub.AssetRecord | null>;
     /**
      * #69: search != fetch. Free-text is the hub's vector endpoint (GET /a2a/assets/semantic-search?q=);
-     * signals/id queries fall through to fetch. /a2a/fetch does NOT do semantic, so text must not go there.
+     * signal/id queries use the Hub's free search-only phase on /a2a/fetch. /a2a/fetch does NOT do semantic,
+     * so text must not go there and paid/full fetch must remain an explicit follow-up.
      */
     search(query: hub.HubQuery): Promise<hub.AssetRecord[]>;
     agentDirectory: hub.AgentDirectoryCapability;

package/dist/hubCapability.js

@@ -1,10 +1,12 @@
-import { bootstrap, hub as hubNs } from '@evomap/evolver-core';
+import { createHash } from 'node:crypto';
+import { bootstrap, hub as hubNs, signals } from '@evomap/evolver-core';
 import { AuthError, HubFetch, HubClientError, isHubUnreachableError } from './hubFetch.js';
 import { isNodeSecret, parseNodeSecretVersion } from './auth/legacyShim.js';
-import { inboundToAgentEvent, agentEventToOutbound, publishRespToReceipt, searchQueryToFetchWire } from './wireMap.js';
+import { inboundToAgentEvent, agentEventToOutbound, publishRespToReceipt, searchQueryToFetchWire, searchQueryToSearchOnlyWire, } from './wireMap.js';
 import { antiAbuseTelemetryMode, buildHeartbeatAntiAbuseTelemetry, } from './antiAbuseTelemetry.js';
 import { getWorkspaceKeychainMode } from './auth/workspaceKeychain.js';
 import { agentDirectoryFailure, parsePublicAgentPage, parsePublicAgentProfile, paginatePublicAgentPage, mergePublicAgentPages, publicAgentSearchQuery, publicTaskDiscoveryQuery, PUBLIC_TASK_DISCOVERY_MAX_CANDIDATES, unsupportedPublicAvailability, unsupportedPublicSort, withDirectoryTimeout, } from './agentDirectory.js';
+import { assetMatchesId } from './hubReuse.js';
 export const INBOUND_LIMIT = 100;
 export const OUTBOUND_MAX_BATCH = 50;
 export const OUTBOUND_MAX_BODY_BYTES = 4 * 1024 * 1024;
@@ -21,13 +23,20 @@ export const USED_ASSET_ID_MAX_LEN = 200;
 export const LEARNING_ASSET_IDS_MAX = 50;
 export const LEARNING_ASSET_ID_MAX_LEN = 128;
 /** 完整 GEP-A2A 信封(实测 dev: publish/fetch/validate 等协议消息端点必须全信封, 非仅 protocol+message_type). */
-export function gepEnvelope(messageType, payload) {
+export function gepEnvelope(messageType, payload, options = {}) {
     return {
         protocol: 'gep-a2a', protocol_version: '1.0.0', message_type: messageType,
-        message_id: `msg_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`,
+        message_id: options.messageId ?? `msg_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`,
         timestamp: new Date().toISOString(), payload,
     };
 }
+function stablePublishMessageId(idempotencyKey) {
+    const digest = createHash('sha256')
+        .update(idempotencyKey.trim())
+        .digest('hex')
+        .slice(0, 40);
+    return `msg_idem_${digest}`;
+}
 // v1 a2aProtocol.js L1999-2003: the three app-level rejection reasons that mean
 // our cached node_secret has DIVERGED from the hub's record (hub-side reset,
 // restored-from-backup machine, manual unlink) — not a transport/generic failure.
@@ -143,6 +152,8 @@ export class PublicHubCapability {
                 ?? this.opts.senderId();
             const nodeSecret = stringField(payload, 'node_secret') ?? stringField(payload, 'nodeSecret');
             const nodeSecretVersion = parseNodeSecretVersion(payload['node_secret_version'] ?? payload['nodeSecretVersion']);
+            const claimCode = stringField(payload, 'claim_code') ?? stringField(payload, 'claimCode');
+            const claimUrl = stringField(payload, 'claim_url') ?? stringField(payload, 'claimUrl');
             if (!opts.preserveCredentials) {
                 if (nodeSecret && isNodeSecret(nodeSecret)) {
                     this.auth.adoptNodeSecret?.(nodeSecret, nodeSecretVersion);
@@ -154,6 +165,8 @@ export class PublicHubCapability {
             return {
                 ok: payload['ok'] !== false && Boolean(nodeId),
                 ...(nodeId ? { nodeId } : {}),
+                ...(claimCode ? { claimCode } : {}),
+                ...(claimUrl ? { claimUrl } : {}),
                 ...(nodeSecretVersion !== undefined ? { nodeSecretVersion } : {}),
                 ...(rateLimitUntilMs !== undefined ? { rateLimitUntilMs } : {}),
                 ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
@@ -215,15 +228,29 @@ export class PublicHubCapability {
         }
         return Object.keys(meta).length > 0 ? meta : undefined;
     }
-    async publish(bundle) {
+    async publish(bundle, options = {}) {
+        const normalizedIdempotencyKey = options.idempotencyKey?.trim();
+        if (options.idempotencyKey !== undefined && !normalizedIdempotencyKey) {
+            return {
+                receiptId: 'local_invalid_idempotency_key',
+                status: 'rejected',
+                terminal: true,
+                reason: 'publish idempotency key must not be blank',
+            };
+        }
         try {
             // 公版 /a2a/publish 收 payload.assets=[Gene,Capsule,(Event)] 捆绑(实测 dev).
-            const body = await this.http.call('POST', '/a2a/publish', gepEnvelope('publish', { assets: bundle }));
+            const idempotencyKey = normalizedIdempotencyKey;
+            const messageId = idempotencyKey !== undefined
+                ? stablePublishMessageId(idempotencyKey)
+                : undefined;
+            const body = await this.http.call('POST', '/a2a/publish', gepEnvelope('publish', { assets: bundle }, messageId ? { messageId } : {}));
             return publishRespToReceipt(200, body);
         }
         catch (e) {
-            if (e instanceof HubClientError)
-                return publishRespToReceipt(e.status, e.body ?? {});
+            if (e instanceof HubClientError) {
+                return publishRespToReceipt(e.status, e.body ?? {}, e.retryAfterMs);
+            }
             throw e; // 5xx/网络 → 重试
         }
     }
@@ -232,29 +259,35 @@ export class PublicHubCapability {
         // /a2a/fetch responses are FULL GEP envelopes (buildResponse('fetch', …)); the rows live at payload.results,
         // NOT at the top level. Reading body.results here always yielded [] — every fetch silently returned nothing.
         const body = await this.http.call('POST', '/a2a/fetch', gepEnvelope('fetch', searchQueryToFetchWire(query)));
-        return (body.payload?.results ?? []);
+        return assetsFromBody(body);
     }
     async fetchAssetById(assetId) {
         const id = assetId.trim();
         if (!id)
             return null;
         const body = await this.http.call('POST', '/a2a/fetch', gepEnvelope('fetch', { asset_ids: [id] }));
-        return assetsFromBody(body).find((asset) => assetMatchesId(asset, id)) ?? null;
+        return assetsFromBody(body).find((asset) => fetchResultMatchesId(asset, id)) ?? null;
     }
     /**
      * #69: search != fetch. Free-text is the hub's vector endpoint (GET /a2a/assets/semantic-search?q=);
-     * signals/id queries fall through to fetch. /a2a/fetch does NOT do semantic, so text must not go there.
+     * signal/id queries use the Hub's free search-only phase on /a2a/fetch. /a2a/fetch does NOT do semantic,
+     * so text must not go there and paid/full fetch must remain an explicit follow-up.
      */
     async search(query) {
         if (query.text && query.text.trim()) {
             // GET /a2a/assets/semantic-search returns a FLAT object keyed `assets` (no GEP envelope), plus a
-            // `search_status` (found / degraded(retryable) / low_confidence_only / no_match). Reading body.results
-            // here always yielded [] — the semantic path could never return a hit. (Status not surfaced yet: the
-            // HubCapability.search contract is AssetRecord[]; honoring search_status needs an interface change — later.)
-            const body = await this.http.call('GET', '/a2a/assets/semantic-search', undefined, { q: query.text, ...(query.limit !== undefined ? { limit: query.limit } : {}) });
-            return (body.assets ?? []);
+            // `search_status` (found / degraded(retryable) / low_confidence_only / no_match). Only an explicit
+            // no_match is a verified empty result; degraded or malformed 200 responses must not trigger ATP spend.
+            const body = await this.http.call('GET', '/a2a/assets/semantic-search', undefined, {
+                q: query.text,
+                ...(query.kind !== undefined ? { type: query.kind } : {}),
+                ...(query.domain !== undefined ? { domain: query.domain } : {}),
+                ...(query.limit !== undefined ? { limit: query.limit } : {}),
+            });
+            return semanticSearchAssets(body);
         }
-        return this.fetch(query);
+        const body = await this.http.call('POST', '/a2a/fetch', gepEnvelope('fetch', searchQueryToSearchOnlyWire(query)));
+        return signalSearchAssets(body);
     }
     agentDirectory = {
         search: async (request) => {
@@ -603,7 +636,10 @@ export class PublicHubCapability {
         const body = await this.http.call('POST', '/a2a/events/poll', gepEnvelope('events_poll', { timeout_ms: 1000 }));
         for (const e of body.events ?? []) {
             if (String(e['type']).startsWith('task_')) {
-                yield { taskId: String(e['payload']?.taskId ?? e['id']), type: String(e['type']), payload: e['payload'], priority: e['priority'] ?? 'medium', createdAt: Date.parse(String(e['created_at'] ?? '')) || 0 };
+                const payload = asRecord(e['payload']);
+                const wireTaskId = payload?.['task_id'] ?? payload?.['taskId'];
+                const taskId = typeof wireTaskId === 'string' && wireTaskId.length > 0 ? wireTaskId : String(e['id']);
+                yield { taskId, type: String(e['type']), payload: e['payload'], priority: e['priority'] ?? 'medium', createdAt: Date.parse(String(e['created_at'] ?? '')) || 0 };
             }
         }
     }
@@ -703,6 +739,44 @@ export class PublicHubCapability {
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
+function searchAssets(value, source) {
+    if (!Array.isArray(value))
+        throw new Error(`${source}_results_invalid`);
+    return value.map((candidate) => {
+        const record = asRecord(candidate);
+        if (!record)
+            throw new Error(`${source}_asset_invalid`);
+        const asset = unwrapFetchDeliveryRow(record);
+        const assetId = stringField(asset, 'asset_id') ?? stringField(asset, 'assetId');
+        if (!assetId)
+            throw new Error(`${source}_asset_invalid`);
+        return asset;
+    });
+}
+function semanticSearchAssets(body) {
+    const status = stringField(body, 'search_status');
+    if (status === 'degraded' || body['retryable'] === true)
+        throw new Error('semantic_search_degraded');
+    const assets = searchAssets(body['assets'], 'semantic_search');
+    if (status === 'no_match') {
+        if (assets.length !== 0)
+            throw new Error('semantic_search_status_invalid');
+        return assets;
+    }
+    if (status === 'found' || status === 'low_confidence_only') {
+        if (assets.length === 0)
+            throw new Error('semantic_search_status_invalid');
+        return assets;
+    }
+    // Older successful Hub responses are usable only when they carry a concrete candidate.
+    if (status === undefined && assets.length > 0)
+        return assets;
+    throw new Error('semantic_search_status_invalid');
+}
+function signalSearchAssets(body) {
+    const payload = asRecord(body['payload']);
+    return searchAssets(payload?.['results'], 'signal_search');
+}
 function recipeStepToWire(step) {
     return {
         asset_id: step.assetId,
@@ -809,7 +883,9 @@ function accountAssetsFromPayload(payload) {
     for (const candidate of candidates) {
         if (!Array.isArray(candidate))
             continue;
-        return candidate.filter((asset) => Boolean(asset && typeof asset === 'object' && !Array.isArray(asset)));
+        return candidate
+            .filter((asset) => Boolean(asset && typeof asset === 'object' && !Array.isArray(asset)))
+            .map(unwrapFetchDeliveryRow);
     }
     return [];
 }
@@ -912,8 +988,10 @@ function failureReason(error) {
     }
     return error instanceof Error ? error.message : String(error);
 }
-function assetMatchesId(asset, assetId) {
-    return Boolean(asset && (asset.asset_id === assetId || stringField(asset, 'id') === assetId));
+function fetchResultMatchesId(asset, requestedId) {
+    if (assetMatchesId(asset, requestedId))
+        return true;
+    return !requestedId.startsWith('sha256:') && Boolean(asset && stringField(asset, 'id') === requestedId);
 }
 function stringField(value, key) {
     return typeof value[key] === 'string' && value[key].length > 0 ? value[key] : undefined;
@@ -987,14 +1065,39 @@ function mailboxPushResultFromBody(body, events) {
     if (results.length === 0) {
         return { outcomes: events.map((event) => ({ id: event.id, status: 'accepted' })) };
     }
+    const resultIds = results.map(mailboxPushResultId);
+    const hasCompletePositions = results.length === events.length;
     return {
-        outcomes: events.map((event, index) => mailboxPushOutcomeFromRow(event.id, results, index)),
+        outcomes: events.map((event, index) => {
+            const matches = results.filter((_, resultIndex) => resultIds[resultIndex] === event.id);
+            if (matches.length === 1)
+                return mailboxPushOutcomeFromRow(event.id, matches[0]);
+            const positionalMatch = matches.length === 0
+                && hasCompletePositions
+                && resultIds[index] === undefined
+                ? results[index]
+                : undefined;
+            return mailboxPushOutcomeFromRow(event.id, positionalMatch);
+        }),
     };
 }
-function mailboxPushOutcomeFromRow(eventId, results, index) {
-    const match = results.find((result) => String(result['id'] ?? result['message_id'] ?? '') === eventId) ?? results[index];
-    if (!match)
-        return { id: eventId, status: 'accepted' };
+function mailboxPushResultId(row) {
+    const value = row['id'] ?? row['message_id'];
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return undefined;
+    const id = String(value);
+    return id.length > 0 ? id : undefined;
+}
+function mailboxPushOutcomeFromRow(eventId, match) {
+    if (!match) {
+        return {
+            id: eventId,
+            status: 'failed',
+            reason: 'mailbox_response_incomplete',
+            retryable: true,
+            terminal: false,
+        };
+    }
     const reason = mailboxPushFailureReason(match);
     if (!reason)
         return { id: eventId, status: 'accepted', raw: match };
@@ -1047,9 +1150,12 @@ function hubErrorStatus(err) {
     }
     return undefined;
 }
-// Retry-After hint from a HubClientError JSON body (429 cooldown). Headers aren't
-// carried on HubClientError, so we read the body's retry_after_ms / retry_after.
+// Prefer the standardized Retry-After header carried by HubClientError, then
+// preserve the existing JSON body hints as a compatibility fallback.
 function clientErrorRetryAfterMs(err) {
+    if (err instanceof HubClientError && typeof err.retryAfterMs === 'number' && Number.isFinite(err.retryAfterMs)) {
+        return err.retryAfterMs;
+    }
     const body = err instanceof HubClientError ? asRecord(err.body) : undefined;
     if (!body)
         return undefined;
@@ -1193,6 +1299,10 @@ function heartbeatResultFromBody(httpStatus, body) {
     const details = payload['details'] ?? body['details'];
     const ack = asRecord(payload['last_update_ack']);
     const forceUpdate = forceUpdateFromRecord(asRecord(payload['force_update']));
+    const rawCapabilityGaps = payload['capability_gaps'] ?? payload['capabilityGaps'];
+    const capabilityGaps = Array.isArray(rawCapabilityGaps)
+        ? signals.normalizeCapabilityGaps(rawCapabilityGaps)
+        : undefined;
     const ok = httpStatus >= 200
         && httpStatus < 300
         && payload['ok'] !== false
@@ -1210,6 +1320,7 @@ function heartbeatResultFromBody(httpStatus, body) {
                 ...(typeof ack['reason'] === 'string' ? { reason: ack['reason'] } : {}),
             } } : {}),
         ...(forceUpdate ? { forceUpdate } : {}),
+        ...(capabilityGaps !== undefined ? { capabilityGaps } : {}),
     };
 }
 function forceUpdateFromRecord(value) {