@evomap/evolver-adapter-public 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/auth/legacyShim.d.ts

@@ -13,8 +13,8 @@ export type NodeSecretVersionHandler = (nodeSecretVersion?: number) => void;
  */
 export type NodeSecretDivergenceHandler = () => void;
 /**
- * node_secret 双轨过渡(M6-5, 6 个月). 包旧 64-hex node_secret 成 AuthProvider.
- * **node_secret 走 request body**(gep-a2a 契约, 实测 dev: requireNodeSecret 读 body 非 header), 不轮换.
+ * LegacyAuthShim exposes node_secret as a transport-neutral credential field. HubFetch promotes it to
+ * Authorization: Bearer for GET and strict GEP envelope endpoints before egress.
  */
 export declare class LegacyAuthShim implements hub.AuthProvider {
     private nodeSecret;

package/dist/auth/legacyShim.js

@@ -13,8 +13,8 @@ export function parseNodeSecretVersion(value) {
     return Number.isSafeInteger(parsed) ? parsed : undefined;
 }
 /**
- * node_secret 双轨过渡(M6-5, 6 个月). 包旧 64-hex node_secret 成 AuthProvider.
- * **node_secret 走 request body**(gep-a2a 契约, 实测 dev: requireNodeSecret 读 body 非 header), 不轮换.
+ * LegacyAuthShim exposes node_secret as a transport-neutral credential field. HubFetch promotes it to
+ * Authorization: Bearer for GET and strict GEP envelope endpoints before egress.
  */
 export class LegacyAuthShim {
     nodeSecret;

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/auth/windowsPowerShell.d.ts

@@ -0,0 +1,3 @@
+export declare const POWERSHELL_STDIN_SCRIPT_COMMAND = "& ([scriptblock]::Create([Console]::In.ReadToEnd()))";
+export declare function windowsAclFailureDetail(cause: unknown): string;
+export declare function stripPowerShellClixml(text: string): string;

package/dist/auth/windowsPowerShell.js

@@ -0,0 +1,91 @@
+export const POWERSHELL_STDIN_SCRIPT_COMMAND = '& ([scriptblock]::Create([Console]::In.ReadToEnd()))';
+export function windowsAclFailureDetail(cause) {
+    const error = cause;
+    const parts = [];
+    if (typeof error?.code === 'string' && error.code) {
+        parts.push('code ' + normalizePowerShellDiagnostic(error.code));
+    }
+    if (typeof error?.status === 'number')
+        parts.push('exit ' + error.status);
+    if (typeof error?.signal === 'string' && error.signal) {
+        parts.push('signal ' + normalizePowerShellDiagnostic(error.signal));
+    }
+    const streams = [error?.stderr, error?.stdout]
+        .map((stream) => (typeof stream === 'string'
+        ? stream
+        : Buffer.isBuffer(stream) ? stream.toString('utf8') : ''))
+        .map(stripPowerShellClixml)
+        .filter((text) => text.length > 0);
+    if (streams.length > 0) {
+        parts.push(streams.join(' | '));
+    }
+    else {
+        const message = typeof error?.message === 'string' ? error.message : '';
+        const detail = stripPowerShellClixml(message.replace(/-EncodedCommand\s+\S+/g, '-EncodedCommand <omitted>'));
+        if (detail)
+            parts.push(detail);
+    }
+    return boundPowerShellDiagnostic(parts.join('; '));
+}
+export function stripPowerShellClixml(text) {
+    if (/#<\s*CLIXML\b/i.test(text)) {
+        const errorRecords = [];
+        const serializedErrors = /<S\b(?=[^>]*\bS=\x22Error\x22)[^>]*>([\s\S]*?)<\/S>/gi;
+        for (const match of text.matchAll(serializedErrors)) {
+            const record = decodePowerShellClixmlText(match[1] ?? '');
+            const hasLocationBoilerplate = /(?:^|\s)At line:\d+ char:\d+/i.test(record);
+            const decoded = normalizePowerShellDiagnostic(stripPowerShellLocationBoilerplate(record));
+            if (decoded)
+                errorRecords.push(decoded);
+            if (hasLocationBoilerplate)
+                break;
+        }
+        if (errorRecords.length > 0)
+            return [...new Set(errorRecords)].join(' | ');
+    }
+    return normalizePowerShellDiagnostic(stripPowerShellLocationBoilerplate(text)
+        .replace(/<Objs\b[\s\S]*?<\/Objs>/g, ' ')
+        .replace(/<Objs\b[^\n]*/g, ' ')
+        .replace(/#<\s*CLIXML\b/gi, ' '));
+}
+function stripPowerShellLocationBoilerplate(text) {
+    return text.replace(/(?:^|\s)At line:\d+ char:\d+[\s\S]*$/i, ' ');
+}
+function decodePowerShellClixmlText(text) {
+    return text
+        .replace(/_x([0-9a-f]{4})_/gi, (_match, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+        .replace(/&#x([0-9a-f]+);/gi, (match, value) => decodeXmlCodePoint(match, value, 16))
+        .replace(/&#([0-9]+);/g, (match, value) => decodeXmlCodePoint(match, value, 10))
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, String.fromCharCode(34))
+        .replace(/&apos;/g, String.fromCharCode(39))
+        .replace(/&amp;/g, '&');
+}
+function decodeXmlCodePoint(match, value, radix) {
+    const codePoint = Number.parseInt(value, radix);
+    if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff ||
+        (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
+        return match;
+    }
+    return String.fromCodePoint(codePoint);
+}
+const POWERSHELL_DIAGNOSTIC_FORMAT_CHARACTER = /^\p{Cf}$/u;
+function normalizePowerShellDiagnostic(text) {
+    const sanitized = [];
+    for (const character of text) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        const isControl = codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+        const isFormat = POWERSHELL_DIAGNOSTIC_FORMAT_CHARACTER.test(character);
+        sanitized.push(isControl || isFormat || codePoint === 0x2028 || codePoint === 0x2029 ? ' ' : character);
+    }
+    return sanitized.join('').replace(/\s+/g, ' ').trim();
+}
+function boundPowerShellDiagnostic(text) {
+    const limit = 300;
+    if (text.length <= limit)
+        return text;
+    const headLength = Math.ceil((limit - 3) / 2);
+    const tailLength = limit - 3 - headLength;
+    return text.slice(0, headLength) + '...' + text.slice(-tailLength);
+}

package/dist/hubCapability.d.ts

@@ -8,6 +8,8 @@ export declare const PUBLIC_PROTOCOL_VERSION = "gep-a2a/1.0.0";
 export declare const PUBLIC_HUB_CAPABILITIES: hub.HubCapabilityName[];
 export declare const USED_ASSET_IDS_MAX = 50;
 export declare const USED_ASSET_ID_MAX_LEN = 200;
+export declare const LEARNING_ASSET_IDS_MAX = 50;
+export declare const LEARNING_ASSET_ID_MAX_LEN = 128;
 /**
  * An outcome the agent reports back to the hub's memory graph after a cycle.
  * `usedAssetIds` is the fetch->outcome attribution claim: which hub assets the
@@ -56,8 +58,13 @@ export interface AccountAssetListResult {
     hasMore: boolean;
     nextCursor?: string;
 }
+export declare class MalformedAccountAssetPageError extends Error {
+    constructor();
+}
 /** 完整 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;
@@ -72,6 +79,8 @@ export interface PublicHelloResult {
     ok: boolean;
     authError?: boolean;
     nodeId?: string;
+    claimCode?: string;
+    claimUrl?: string;
     nodeSecretVersion?: number;
     rateLimitUntilMs?: number;
     error?: string;
@@ -81,6 +90,12 @@ export interface PublicHelloResult {
     httpStatus?: number;
     secretDiverged?: boolean;
 }
+export interface PublicHelloOptions {
+    rotate: boolean;
+    evolverVersion?: string;
+    /** Keep trust probes from adopting or clearing local credential state. */
+    preserveCredentials?: boolean;
+}
 export interface PublicHeartbeatOptions {
     evolverVersion?: string;
     lastUpdate?: PublicLastUpdatePayload;
@@ -116,6 +131,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;
@@ -129,18 +145,24 @@ export declare class PublicHubCapability implements hub.HubCapability {
     readonly auth: hub.AuthProvider;
     readonly recipes: hub.RecipeCapability;
     constructor(opts: PublicHubOptions);
-    hello(opts: {
-        rotate: boolean;
-        evolverVersion?: string;
-    }): Promise<PublicHelloResult>;
+    private evolverVersionForWire;
+    private envFingerprintForWire;
+    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>;
+    /**
+     * Fetch one asset AND say why, when the answer is not an asset. `fetchAssetById` collapses every outcome to
+     * `null`, so a caller could not tell "the hub does not have this" from "the hub delivered something the
+     * client refuses" — and the CLI reported both as `not_found` on assets that demonstrably exist (#964).
+     */
+    fetchAssetDeliveryById(assetId: string, options?: hub.FetchAssetByIdOptions): Promise<hub.AssetDeliveryOutcome>;
+    fetchAssetById(assetId: string, options?: hub.FetchAssetByIdOptions): 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;
@@ -156,6 +178,8 @@ export declare class PublicHubCapability implements hub.HubCapability {
     recordOutcome(report: OutcomeReport): Promise<OutcomeReceipt>;
     recordMemoryEvent(report: MemoryGraphEventReport): Promise<MemoryGraphEventReceipt>;
     recordReuseResult(report: hub.ReuseResultReport): Promise<hub.ReuseResultReceipt>;
+    listLearningAssets(options?: hub.LearningAssetListOptions): Promise<hub.LearningAssetListResult>;
+    recordLearningAssetUsage(report: hub.LearningAssetUsageReport): Promise<hub.LearningAssetUsageReceipt>;
     /**
      * Pre-publish dry-run (POST /a2a/validate). The hub runs the same hub-side quality +
      * content-safety gate as publish but stores nothing and charges no credits. This adapter is
@@ -168,8 +192,10 @@ export declare class PublicHubCapability implements hub.HubCapability {
      */
     validate(bundle: hub.AssetRecord[]): Promise<hub.ValidateReceipt>;
     createRecipe(request: hub.RecipeCreateRequest): Promise<hub.RecipeReceipt>;
-    publishRecipe(recipeId: string): Promise<hub.RecipeReceipt>;
+    publishRecipe(recipeId: string, options?: hub.RecipePublishOptions): Promise<hub.RecipeReceipt>;
     getRecipe(recipeId: string): Promise<hub.RecipeFetchReceipt>;
+    searchRecipes(request?: hub.RecipeSearchRequest): Promise<hub.RecipeSearchReceipt>;
+    listRecipes(request?: hub.RecipeSearchRequest): Promise<hub.RecipeSearchReceipt>;
     expressRecipe(recipeId: string, request?: hub.RecipeExpressRequest): Promise<hub.RecipeExpressionReceipt>;
     task: {
         claim: (taskId: string) => Promise<{