openclaw-openagent 1.0.1 → 1.0.3

package/dist/src/transport/oasn/oasn-http.d.ts

@@ -0,0 +1,98 @@
+/**
+ * OASN HTTP 客户端
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-transport-abstraction-design.md §11.5（401 撤销）
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §五（统一错误格式）
+ *
+ * 职责：
+ *   1. 提供 GET/POST/PATCH/multipart 上传/二进制下载 等基础方法
+ *   2. 注入 `Authorization: Bearer <api_key>` 头
+ *   3. 解析 OASN 统一错误响应（`{ error: { code, message, retryable, request_id } }`）
+ *      → 抛出 TransportError（保留 retryable / requestId 字段，便于上层判断）
+ *   4. 401/UNAUTHENTICATED 时触发 `onCredentialRevoked` 回调（§11.5 撤销路径）
+ *   5. 支持自动重试（仅当 `retryable: true` 时，最多 3 次指数退避）
+ *
+ * 不在此层处理：
+ *   - SSE 升级（详见 oasn-invocation.ts 的 subscribeToInvocation）
+ *   - 业务幂等持久化（详见 oasn-invocation.ts + state/store.ts）
+ *   - file_ref LRU（详见 oasn-files.ts）
+ */
+/** OASN HTTP 客户端配置 */
+export interface OasnHttpConfig {
+    /** API base URL，如 `https://api.oasn.ai` */
+    apiBase: string;
+    /** Bearer token（api_key 或 access_token） */
+    token?: string;
+    /** 单次请求默认超时（ms） */
+    defaultTimeoutMs?: number;
+    /** 自动重试最大次数（仅当响应 retryable=true 时） */
+    maxRetries?: number;
+    /**
+     * 401/UNAUTHENTICATED 触发回调。
+     * 由 OasnTransport 接入，进一步触发 `credential_expired` 事件 + 清本地凭证（§11.5）。
+     */
+    onCredentialRevoked?: () => void;
+}
+/** 请求选项 */
+export interface OasnRequestOptions {
+    /** 自定义超时（覆盖 defaultTimeoutMs） */
+    timeoutMs?: number;
+    /** 自定义额外头（Authorization 由 client 自动注入，无需传入） */
+    headers?: Record<string, string>;
+    /** 跳过自动重试（如轮询接口自己控制节奏） */
+    skipRetry?: boolean;
+    /** Abort 信号 */
+    signal?: AbortSignal;
+}
+export declare class OasnHttpClient {
+    private _config;
+    constructor(config: OasnHttpConfig);
+    /** 动态更新 token —— 注册成功后由 OasnTransport 调用 */
+    setToken(token: string | undefined): void;
+    get<T>(path: string, options?: OasnRequestOptions): Promise<T>;
+    post<T>(path: string, body: unknown, options?: OasnRequestOptions): Promise<T>;
+    patch<T>(path: string, body: unknown, options?: OasnRequestOptions): Promise<T>;
+    /**
+     * multipart/form-data 上传。
+     * 仅支持 file + metadata 字段，不做通用 multipart 支持（OASN 上传场景固定）。
+     */
+    postMultipart<T>(path: string, parts: {
+        file: {
+            content: Buffer;
+            filename: string;
+            mimeType?: string;
+        };
+        fields?: Record<string, string>;
+    }, options?: OasnRequestOptions): Promise<T>;
+    /**
+     * 下载二进制内容（用于 Artifact 下载）。
+     * 不解析响应，直接返回 ArrayBuffer + 头信息。
+     */
+    getBinary(path: string, options?: OasnRequestOptions): Promise<{
+        content: ArrayBuffer;
+        mimeType: string;
+        displayName: string;
+    }>;
+    /**
+     * 暴露底层 raw 请求，用于 SSE 等流式场景（如 oasn-invocation 的 SSE 升级）。
+     * 调用方自行处理流式响应。
+     */
+    rawHttpRequest(method: string, path: string, headers: Record<string, string>, body?: Buffer | string, options?: OasnRequestOptions): Promise<{
+        statusCode: number;
+        headers: Record<string, string>;
+        body: string;
+    }>;
+    private _resolveUrl;
+    private _buildHeaders;
+    /**
+     * JSON 请求 —— body 自动 JSON.stringify，响应 JSON.parse。
+     * 含重试逻辑（仅当 retryable=true 时）。
+     */
+    private _jsonRequest;
+    private _rawRequest;
+    /** 执行单次 HTTP 请求（不解析响应体格式） */
+    private _doRawRequest;
+    /** 二进制下载 */
+    private _doBinaryRequest;
+}

package/dist/src/transport/oasn/oasn-http.js

@@ -0,0 +1,362 @@
+/**
+ * OASN HTTP 客户端
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-transport-abstraction-design.md §11.5（401 撤销）
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §五（统一错误格式）
+ *
+ * 职责：
+ *   1. 提供 GET/POST/PATCH/multipart 上传/二进制下载 等基础方法
+ *   2. 注入 `Authorization: Bearer <api_key>` 头
+ *   3. 解析 OASN 统一错误响应（`{ error: { code, message, retryable, request_id } }`）
+ *      → 抛出 TransportError（保留 retryable / requestId 字段，便于上层判断）
+ *   4. 401/UNAUTHENTICATED 时触发 `onCredentialRevoked` 回调（§11.5 撤销路径）
+ *   5. 支持自动重试（仅当 `retryable: true` 时，最多 3 次指数退避）
+ *
+ * 不在此层处理：
+ *   - SSE 升级（详见 oasn-invocation.ts 的 subscribeToInvocation）
+ *   - 业务幂等持久化（详见 oasn-invocation.ts + state/store.ts）
+ *   - file_ref LRU（详见 oasn-files.ts）
+ */
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+import { logger } from '../../util/logger.js';
+import { makeTransportError } from '../types.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+// ───────────────────────────────────────────────────────────────
+// 错误转换
+// ───────────────────────────────────────────────────────────────
+/**
+ * 把 HTTP 响应（含可能的 OASN 统一错误体）转换为 TransportError。
+ * 如果响应非 OASN 统一格式，使用 HTTP 状态码做兜底。
+ */
+function toTransportError(statusCode, rawBody) {
+    let code = `HTTP_${statusCode}`;
+    let message = rawBody.slice(0, 500);
+    let retryable = statusCode >= 500 || statusCode === 429 || statusCode === 408;
+    let requestId;
+    try {
+        const parsed = JSON.parse(rawBody);
+        if (parsed?.error?.code) {
+            code = parsed.error.code;
+            message = parsed.error.message ?? message;
+            retryable = parsed.error.retryable ?? retryable;
+            requestId = parsed.error.request_id;
+        }
+    }
+    catch {
+        // 非 JSON 响应，保留兜底值
+    }
+    return makeTransportError(code, `[${statusCode}] ${message}`, { retryable, requestId });
+}
+// ───────────────────────────────────────────────────────────────
+// OasnHttpClient
+// ───────────────────────────────────────────────────────────────
+export class OasnHttpClient {
+    _config;
+    constructor(config) {
+        if (!config.apiBase) {
+            throw new Error('OasnHttpClient: apiBase is required');
+        }
+        this._config = {
+            apiBase: config.apiBase,
+            token: config.token,
+            defaultTimeoutMs: config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+            maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+            onCredentialRevoked: config.onCredentialRevoked,
+        };
+    }
+    /** 动态更新 token —— 注册成功后由 OasnTransport 调用 */
+    setToken(token) {
+        this._config.token = token;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // 公共方法
+    // ─────────────────────────────────────────────────────────────
+    async get(path, options) {
+        return this._jsonRequest('GET', path, undefined, options);
+    }
+    async post(path, body, options) {
+        return this._jsonRequest('POST', path, body, options);
+    }
+    async patch(path, body, options) {
+        return this._jsonRequest('PATCH', path, body, options);
+    }
+    /**
+     * multipart/form-data 上传。
+     * 仅支持 file + metadata 字段，不做通用 multipart 支持（OASN 上传场景固定）。
+     */
+    async postMultipart(path, parts, options) {
+        const boundary = `------oasn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+        const chunks = [];
+        // 普通字段
+        if (parts.fields) {
+            for (const [key, value] of Object.entries(parts.fields)) {
+                chunks.push(Buffer.from(`--${boundary}\r\n`
+                    + `Content-Disposition: form-data; name="${key}"\r\n\r\n`
+                    + `${value}\r\n`));
+            }
+        }
+        // 文件字段
+        const mime = parts.file.mimeType ?? 'application/octet-stream';
+        chunks.push(Buffer.from(`--${boundary}\r\n`
+            + `Content-Disposition: form-data; name="file"; filename="${parts.file.filename}"\r\n`
+            + `Content-Type: ${mime}\r\n\r\n`));
+        chunks.push(parts.file.content);
+        chunks.push(Buffer.from(`\r\n--${boundary}--\r\n`));
+        const body = Buffer.concat(chunks);
+        return this._rawRequest('POST', path, body, {
+            ...options,
+            headers: {
+                'Content-Type': `multipart/form-data; boundary=${boundary}`,
+                ...options?.headers,
+            },
+            isJsonBody: false,
+            expectJsonResponse: true,
+        });
+    }
+    /**
+     * 下载二进制内容（用于 Artifact 下载）。
+     * 不解析响应，直接返回 ArrayBuffer + 头信息。
+     */
+    async getBinary(path, options) {
+        const url = this._resolveUrl(path);
+        const headers = this._buildHeaders({});
+        const timeoutMs = options?.timeoutMs ?? this._config.defaultTimeoutMs;
+        return this._doBinaryRequest(url, headers, timeoutMs, options?.signal);
+    }
+    /**
+     * 暴露底层 raw 请求，用于 SSE 等流式场景（如 oasn-invocation 的 SSE 升级）。
+     * 调用方自行处理流式响应。
+     */
+    rawHttpRequest(method, path, headers, body, options) {
+        const url = this._resolveUrl(path);
+        const fullHeaders = this._buildHeaders(headers);
+        const timeoutMs = options?.timeoutMs ?? this._config.defaultTimeoutMs;
+        return this._doRawRequest(url, method, fullHeaders, body, timeoutMs, options?.signal);
+    }
+    // ─────────────────────────────────────────────────────────────
+    // 内部实现
+    // ─────────────────────────────────────────────────────────────
+    _resolveUrl(path) {
+        if (/^https?:\/\//i.test(path)) {
+            return new URL(path);
+        }
+        // path 必须以 / 开头
+        const base = this._config.apiBase.replace(/\/$/, '');
+        return new URL(`${base}${path}`);
+    }
+    _buildHeaders(extra) {
+        const headers = {
+            Accept: 'application/json',
+            ...extra,
+        };
+        if (this._config.token) {
+            headers['Authorization'] = `Bearer ${this._config.token}`;
+        }
+        return headers;
+    }
+    /**
+     * JSON 请求 —— body 自动 JSON.stringify，响应 JSON.parse。
+     * 含重试逻辑（仅当 retryable=true 时）。
+     */
+    async _jsonRequest(method, path, body, options) {
+        return this._rawRequest(method, path, body, {
+            ...options,
+            isJsonBody: true,
+            expectJsonResponse: true,
+        });
+    }
+    async _rawRequest(method, path, body, options) {
+        const url = this._resolveUrl(path);
+        const headers = this._buildHeaders(options?.headers ?? {});
+        let bodyBuffer;
+        if (body !== undefined) {
+            if (options.isJsonBody) {
+                const json = typeof body === 'string' ? body : JSON.stringify(body);
+                bodyBuffer = Buffer.from(json);
+                headers['Content-Type'] = 'application/json';
+                headers['Content-Length'] = String(bodyBuffer.length);
+            }
+            else {
+                bodyBuffer = body;
+                if (!headers['Content-Length']) {
+                    headers['Content-Length'] = String(bodyBuffer.length);
+                }
+            }
+        }
+        const maxAttempts = options.skipRetry ? 1 : (this._config.maxRetries + 1);
+        let lastErr;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                if (attempt > 0) {
+                    // 指数退避：200ms / 400ms / 800ms（含少量随机抖动）
+                    const delay = 200 * Math.pow(2, attempt - 1) + Math.floor(Math.random() * 50);
+                    await new Promise((r) => setTimeout(r, delay));
+                    logger.info(`[transport/oasn/http] retry ${attempt}/${maxAttempts - 1} ${method} ${path}`);
+                }
+                const { statusCode, body: respBody } = await this._doRawRequest(url, method, headers, bodyBuffer, options?.timeoutMs ?? this._config.defaultTimeoutMs, options?.signal);
+                if (statusCode >= 200 && statusCode < 300) {
+                    if (!options.expectJsonResponse)
+                        return undefined;
+                    if (statusCode === 204 || !respBody)
+                        return undefined;
+                    try {
+                        return JSON.parse(respBody);
+                    }
+                    catch (parseErr) {
+                        throw makeTransportError('INVALID_JSON_RESPONSE', `Failed to parse OASN response: ${parseErr.message}`);
+                    }
+                }
+                // 错误响应
+                const err = toTransportError(statusCode, respBody);
+                // §11.5 401/UNAUTHENTICATED 撤销路径
+                if (statusCode === 401 || err.code === 'UNAUTHENTICATED') {
+                    logger.warn(`[transport/oasn/http] 401 UNAUTHENTICATED on ${method} ${path}`);
+                    this._config.onCredentialRevoked?.();
+                    throw err; // 401 不重试
+                }
+                if (!err.retryable || attempt === maxAttempts - 1)
+                    throw err;
+                lastErr = err;
+                logger.warn(`[transport/oasn/http] retryable error code=${err.code} on ${method} ${path}, will retry`);
+            }
+            catch (err) {
+                // 网络层错误（DNS / 连接 / 超时） —— 视为可重试
+                const isTransport = err.code !== undefined;
+                if (isTransport)
+                    throw err;
+                lastErr = err;
+                if (attempt === maxAttempts - 1) {
+                    throw makeTransportError('NETWORK_ERROR', `${method} ${path} failed: ${err.message}`, { retryable: true });
+                }
+            }
+        }
+        // 不可达，但 TS 需要
+        throw lastErr ?? new Error('Unknown HTTP error');
+    }
+    /** 执行单次 HTTP 请求（不解析响应体格式） */
+    _doRawRequest(url, method, headers, body, timeoutMs, signal) {
+        const isHttps = url.protocol === 'https:';
+        const requestFn = isHttps ? httpsRequest : httpRequest;
+        return new Promise((resolve, reject) => {
+            const reqOptions = {
+                method,
+                headers,
+                hostname: url.hostname,
+                port: url.port || (isHttps ? 443 : 80),
+                path: `${url.pathname}${url.search}`,
+            };
+            let settled = false;
+            let timeoutHandle;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                fn();
+            };
+            const req = requestFn(reqOptions, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const respBody = Buffer.concat(chunks).toString('utf-8');
+                    const respHeaders = {};
+                    for (const [k, v] of Object.entries(res.headers)) {
+                        if (typeof v === 'string')
+                            respHeaders[k] = v;
+                        else if (Array.isArray(v))
+                            respHeaders[k] = v.join(', ');
+                    }
+                    finish(() => resolve({
+                        statusCode: res.statusCode ?? 0,
+                        headers: respHeaders,
+                        body: respBody,
+                    }));
+                });
+                res.on('error', (err) => finish(() => reject(err)));
+            });
+            req.on('error', (err) => finish(() => reject(err)));
+            timeoutHandle = setTimeout(() => {
+                req.destroy(new Error(`OASN HTTP timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            // Abort 支持
+            if (signal) {
+                const onAbort = () => {
+                    req.destroy(new Error('Request aborted'));
+                };
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener('abort', onAbort, { once: true });
+            }
+            if (body)
+                req.write(body);
+            req.end();
+        });
+    }
+    /** 二进制下载 */
+    _doBinaryRequest(url, headers, timeoutMs, signal) {
+        const isHttps = url.protocol === 'https:';
+        const requestFn = isHttps ? httpsRequest : httpRequest;
+        return new Promise((resolve, reject) => {
+            const reqOptions = {
+                method: 'GET',
+                headers,
+                hostname: url.hostname,
+                port: url.port || (isHttps ? 443 : 80),
+                path: `${url.pathname}${url.search}`,
+            };
+            let settled = false;
+            let timeoutHandle;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                fn();
+            };
+            const req = requestFn(reqOptions, (res) => {
+                const status = res.statusCode ?? 0;
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const buf = Buffer.concat(chunks);
+                    if (status >= 200 && status < 300) {
+                        const mime = String(res.headers['content-type'] ?? 'application/octet-stream');
+                        const disposition = String(res.headers['content-disposition'] ?? '');
+                        const nameMatch = disposition.match(/filename\*?=([^;]+)/i);
+                        const displayName = nameMatch
+                            ? decodeURIComponent(nameMatch[1].replace(/^UTF-8''/i, '').replace(/^"|"$/g, ''))
+                            : 'artifact';
+                        finish(() => resolve({
+                            content: buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength),
+                            mimeType: mime,
+                            displayName,
+                        }));
+                    }
+                    else {
+                        finish(() => reject(toTransportError(status, buf.toString('utf-8'))));
+                    }
+                });
+                res.on('error', (err) => finish(() => reject(err)));
+            });
+            req.on('error', (err) => finish(() => reject(err)));
+            timeoutHandle = setTimeout(() => {
+                req.destroy(new Error(`OASN binary download timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            if (signal) {
+                const onAbort = () => req.destroy(new Error('Request aborted'));
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener('abort', onAbort, { once: true });
+            }
+            req.end();
+        });
+    }
+}

package/dist/src/transport/oasn/oasn-invocation.d.ts

@@ -0,0 +1,154 @@
+/**
+ * OASN Invocation —— 任务调用 + 轮询订阅 ⭐
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §2.14 / §2.15
+ *   - docs/specs/2026-06-16-oasn-transport-abstraction-design.md
+ *       §11.1（idempotency_key 持久化）
+ *       §11.2（abort 与 cancel 缺失）
+ *       §11.3（timeoutMs ↔ effective_timeout_ms 协调）
+ *       §11.8（subscribeToInvocation 抽象 + SSE 升级）
+ *
+ * 子模块包含 3 个核心能力：
+ *
+ *   1. createInvocation()   POST /api/invocations
+ *      - 维护 idempotency_key（接受外部传入，便于 §11.1 持久化复用）
+ *      - 返回 invocation_id / session_id / effective_timeout_ms / next_poll_after_ms
+ *
+ *   2. subscribeToInvocation(id, opts)
+ *      - 默认实现 = 轮询循环
+ *      - 上层 waitForTaskResult 只调用此抽象，对推送/轮询无感知
+ *      - 后续可在此处理 SSE 升级（探测 Accept: text/event-stream），保持外部 API 不变
+ *
+ *   3. waitForTaskResult(handle, opts)
+ *      - 包装 subscribeToInvocation，转换为 TaskResult
+ *      - 终态时拉取 artifacts 列表（不下载内容，仅引用）
+ *      - 协调本地 timeoutMs 与服务端 effective_timeout_ms（§11.3）
+ *      - signal.aborted → 标记 abandoned（§11.2，不调用 cancel API 因为不存在）
+ */
+import { type ProgressCallback, type TaskHandle, type TaskRequest, type TaskResult } from '../types.js';
+import type { OasnHttpClient } from './oasn-http.js';
+import { type GetInvocationResponse } from './oasn-types.js';
+/** Invocation 持久化钩子（接 StateStore.pending_invocations，§11.1） */
+export interface PendingInvocationStore {
+    /** sendTask 前查询：若同一 toolCallId 已有未完成 invocation，返回已存的 idempotency_key */
+    getPending(toolCallId: string): {
+        idempotency_key: string;
+        invocation_id?: string;
+    } | null;
+    /** sendTask 拿到 invocation_id 后回写 */
+    upsertPending(record: {
+        tool_call_id: string;
+        idempotency_key: string;
+        invocation_id?: string;
+        session_id?: string;
+        target_agent_id?: string;
+        status: string;
+    }): void;
+    /** 终态时清理 */
+    markTerminal(invocationId: string, status: string): void;
+    /** §11.2 abort 时标记为 abandoned */
+    markAbandoned(invocationId: string): void;
+}
+/**
+ * subscribeToInvocation 选项。
+ * 抽象层屏蔽轮询/SSE 差异：上层只关心 onProgress / onComplete / signal。
+ */
+export interface SubscribeOptions {
+    /** 进度推送回调 */
+    onProgress?: (progress: {
+        content: string;
+        raw: GetInvocationResponse['progress'];
+    }) => void;
+    /** 终态回调（succeeded/failed/timed_out/cancelled） */
+    onComplete: (final: GetInvocationResponse) => void;
+    /** abort 信号 */
+    signal?: AbortSignal;
+    /** 总等待时长上限（ms）—— 由 waitForTaskResult 协调后传入 */
+    totalTimeoutMs: number;
+    /** 服务端首轮建议间隔（来自 createInvocation 响应） */
+    initialPollAfterMs?: number;
+}
+/** sendTask 拓展输入（OASN 特有） */
+export interface CreateInvocationOptions {
+    /**
+     * §11.1：客户端持久化的工具调用 id。提供后会与 PendingInvocationStore 联动：
+     *   - 若已存在未完成记录 → 复用其 idempotency_key（实现进程崩溃恢复）
+     *   - 否则生成新 UUID 并落盘
+     *
+     * 不传时退化为每次随机 UUID（无持久化）。
+     */
+    toolCallId?: string;
+    /** 期望超时（毫秒），服务端可能裁决（effective_timeout_ms） */
+    timeoutMs?: number;
+    /** 客户端分组标识，便于服务端聚合排障 */
+    clientRequestGroupId?: string;
+}
+export declare class OasnInvocation {
+    private readonly _http;
+    private readonly _pendingStore?;
+    /** invocation_id → effective_timeout_ms（waitForTaskResult §11.3 用） */
+    private _effectiveTimeoutMap;
+    /** invocation_id → 首轮 next_poll_after_ms */
+    private _initialPollMap;
+    constructor(_http: OasnHttpClient, _pendingStore?: PendingInvocationStore | undefined);
+    /**
+     * 创建 Invocation。
+     *
+     * 返回 TaskHandle —— 含 invocation_id / session_id / effective_timeout_ms / next_poll_after_ms。
+     * 上层将此 handle 传给 waitForTaskResult。
+     */
+    sendTask(targetAgentId: string, task: TaskRequest, options?: CreateInvocationOptions): Promise<TaskHandle>;
+    /**
+     * 订阅 Invocation 状态变化，直至终态或 abort/timeout。
+     *
+     * 当前实现：纯轮询循环。
+     * 后续若服务端支持 SSE，可在此函数内部探测升级，外部 API 保持不变。
+     *
+     * 返回 Promise，在终态/超时/abort 时 resolve（内部不抛错，错误由 onComplete 携带 final.status 判定）。
+     */
+    subscribeToInvocation(invocationId: string, options: SubscribeOptions): Promise<void>;
+    /**
+     * 等待任务结果（终态后转换为 TaskResult）。
+     *
+     * §11.3 协调：
+     *   实际等待时间 = max(本地 timeoutMs, 服务端 effective_timeout_ms)
+     *   差距 > 30% 时输出 warn，提示用户调整。
+     */
+    waitForTaskResult(handle: TaskHandle, options: {
+        timeoutMs: number;
+        signal?: AbortSignal;
+        onProgress?: ProgressCallback;
+    }): Promise<TaskResult>;
+    /**
+     * 把终态 Invocation 响应转换为 TaskResult。
+     *
+     *   - succeeded → status:'complete' + content=summary + artifacts + webuiContinuation
+     *   - 其它终态 → status:'error' + content=user_error.message
+     *
+     * content 的归一路径：
+     *   inlineResult.summary > visible_result.inline_result_summary > ''
+     *
+     * webui_continuation 仅在 succeeded 时抽取（失败场景后端不保证存在）。
+     */
+    private _toTaskResult;
+    /**
+     * 从终态响应里抽取 WebUI continuation（camelCase / snake_case 双归一）。
+     * 缺必要字段（id / launch_url）时返回 undefined，调用方按 falsy 处理即可。
+     */
+    private _toWebuiContinuation;
+    /** 终态错误专用 TransportError，便于上层 catch */
+    private _terminalError;
+    private _toArtifactRef;
+    private _normalizeCreateInvocation;
+    /** clamp 轮询间隔到合理范围 */
+    private _clampPollInterval;
+    /** 可被 abort 中断的 sleep */
+    private _sleepWithAbort;
+    /** abort 场景虚拟终态 —— 不调用服务端 cancel（API 不存在 §11.2） */
+    private _buildAbandonedResponse;
+    /** timeout 虚拟终态 */
+    private _buildTimeoutResponse;
+    /** invocation_id 不存在时的虚拟终态 */
+    private _build404Response;
+}