openclaw-openagent 1.0.13 → 1.0.14

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

@@ -1,604 +0,0 @@
-/**
- * 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 { randomUUID } from 'node:crypto';
-
-import { logger } from '../../util/logger.js';
-import {
-  makeTransportError,
-  type ArtifactRef,
-  type ProgressCallback,
-  type TaskHandle,
-  type TaskRequest,
-  type TaskResult,
-  type TransportError,
-  type WebuiContinuationRef,
-} from '../types.js';
-import type { OasnHttpClient } from './oasn-http.js';
-import {
-  isInvocationTerminal,
-  OASN_ENDPOINTS,
-  type ArtifactResponse,
-  type CreateInvocationRequest,
-  type CreateInvocationResponse,
-  type GetInvocationResponse,
-  type InvocationStatus,
-  type VisibleResultResponse,
-} 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;
-}
-
-/** 轮询常量 —— 服务端 next_poll_after_ms 的下限保护，避免风暴 */
-const MIN_POLL_INTERVAL_MS = 500;
-/** 轮询间隔上限（防止服务端返回异常大值） */
-const MAX_POLL_INTERVAL_MS = 30_000;
-/** 当 next_poll_after_ms 缺失时使用的兜底值 */
-const FALLBACK_POLL_INTERVAL_MS = 2_000;
-
-export class OasnInvocation {
-  /** invocation_id → effective_timeout_ms（waitForTaskResult §11.3 用） */
-  private _effectiveTimeoutMap = new Map<string, number>();
-  /** invocation_id → 首轮 next_poll_after_ms */
-  private _initialPollMap = new Map<string, number>();
-
-  constructor(
-    private readonly _http: OasnHttpClient,
-    private readonly _pendingStore?: PendingInvocationStore,
-  ) {}
-
-  // ═══════════════════════════════════════════════════════════════
-  // sendTask（POST /api/invocations）
-  // ═══════════════════════════════════════════════════════════════
-
-  /**
-   * 创建 Invocation。
-   *
-   * 返回 TaskHandle —— 含 invocation_id / session_id / effective_timeout_ms / next_poll_after_ms。
-   * 上层将此 handle 传给 waitForTaskResult。
-   */
-  async sendTask(
-    targetAgentId: string,
-    task: TaskRequest,
-    options?: CreateInvocationOptions,
-  ): Promise<TaskHandle> {
-    // §11.1：尝试复用 pending 记录
-    let idempotencyKey: string;
-    let pendingRecord: ReturnType<NonNullable<typeof this._pendingStore>['getPending']> | null = null;
-    if (options?.toolCallId && this._pendingStore) {
-      pendingRecord = this._pendingStore.getPending(options.toolCallId);
-    }
-    if (pendingRecord) {
-      idempotencyKey = pendingRecord.idempotency_key;
-      logger.info(
-        `[transport/oasn/invocation] reuse pending tool_call_id=${options?.toolCallId} `
-        + `idempotency_key=${idempotencyKey}`,
-      );
-    } else {
-      idempotencyKey = randomUUID();
-    }
-
-    const body: CreateInvocationRequest = {
-      idempotency_key: idempotencyKey,
-      service_agent_id: targetAgentId,
-      input: { task: task.task },
-    };
-    if (task.sessionId) body.session_id = task.sessionId;
-    if (task.inputFileRefs?.length) body.input_file_refs = task.inputFileRefs;
-    if (task.inputArtifactRefs?.length) body.input_artifact_refs = task.inputArtifactRefs;
-    if (options?.timeoutMs !== undefined) body.timeout_ms = options.timeoutMs;
-    if (options?.clientRequestGroupId) body.client_request_group_id = options.clientRequestGroupId;
-
-    logger.info(
-      `[transport/oasn/invocation] sendTask target=${targetAgentId} `
-      + `idempotency_key=${idempotencyKey} replay=${pendingRecord ? 'maybe' : 'new'}`,
-    );
-
-    // 注意：服务端按 idempotency_key 去重，重试是安全的；此处保留默认重试策略
-    const resp = await this._http.post<CreateInvocationResponse>(
-      OASN_ENDPOINTS.INVOCATIONS,
-      body,
-    );
-    const created = this._normalizeCreateInvocation(resp, options?.timeoutMs);
-    if (!created.invocationId) {
-      throw makeTransportError('INVALID_INVOCATION_RESPONSE', 'Create invocation response missing invocationId');
-    }
-
-    logger.info(
-      `[transport/oasn/invocation] created invocation_id=${created.invocationId} `
-      + `status=${created.status} effective_timeout_ms=${created.effectiveTimeoutMs} `
-      + `replay=${created.idempotentReplay}`,
-    );
-
-    // 回填 pending 记录
-    if (options?.toolCallId && this._pendingStore) {
-      this._pendingStore.upsertPending({
-        tool_call_id: options.toolCallId,
-        idempotency_key: idempotencyKey,
-        invocation_id: created.invocationId,
-        session_id: created.sessionId,
-        target_agent_id: targetAgentId,
-        status: created.status,
-      });
-    }
-
-    // 缓存服务端裁决参数，留给 waitForTaskResult 使用
-    this._effectiveTimeoutMap.set(created.invocationId, created.effectiveTimeoutMs);
-    this._initialPollMap.set(created.invocationId, created.nextPollAfterMs);
-
-    return {
-      invocationId: created.invocationId,
-      sessionId: created.sessionId,
-      effectiveTimeoutMs: created.effectiveTimeoutMs,
-      nextPollAfterMs: created.nextPollAfterMs,
-    };
-  }
-
-  // ═══════════════════════════════════════════════════════════════
-  // subscribeToInvocation —— §11.8 抽象层
-  // ═══════════════════════════════════════════════════════════════
-
-  /**
-   * 订阅 Invocation 状态变化，直至终态或 abort/timeout。
-   *
-   * 当前实现：纯轮询循环。
-   * 后续若服务端支持 SSE，可在此函数内部探测升级，外部 API 保持不变。
-   *
-   * 返回 Promise，在终态/超时/abort 时 resolve（内部不抛错，错误由 onComplete 携带 final.status 判定）。
-   */
-  async subscribeToInvocation(
-    invocationId: string,
-    options: SubscribeOptions,
-  ): Promise<void> {
-    const { onProgress, onComplete, signal, totalTimeoutMs, initialPollAfterMs } = options;
-    const startAt = Date.now();
-    let nextDelay = this._clampPollInterval(initialPollAfterMs ?? this._initialPollMap.get(invocationId));
-
-    while (true) {
-      // ── abort 检查 ────────────────────────────────────────────
-      if (signal?.aborted) {
-        logger.warn(`[transport/oasn/invocation] subscribe aborted invocation_id=${invocationId}`);
-        // §11.2：服务端没有 cancel API，只能本地标记
-        this._pendingStore?.markAbandoned(invocationId);
-        // 用一个虚拟的"cancelled"终态通知上层
-        onComplete(this._buildAbandonedResponse(invocationId));
-        return;
-      }
-
-      // ── 总超时检查 ────────────────────────────────────────────
-      const elapsed = Date.now() - startAt;
-      if (elapsed >= totalTimeoutMs) {
-        logger.warn(
-          `[transport/oasn/invocation] subscribe timed out invocation_id=${invocationId} `
-          + `elapsed=${elapsed}ms limit=${totalTimeoutMs}ms`,
-        );
-        this._pendingStore?.markAbandoned(invocationId);
-        onComplete(this._buildTimeoutResponse(invocationId));
-        return;
-      }
-
-      // ── 等待下次轮询 ──────────────────────────────────────────
-      const remaining = totalTimeoutMs - elapsed;
-      const waitMs = Math.min(nextDelay, remaining);
-      await this._sleepWithAbort(waitMs, signal);
-      if (signal?.aborted) continue; // 让下一轮迭代命中上面 abort 分支统一处理
-
-      // ── 拉取最新状态 ──────────────────────────────────────────
-      let resp: GetInvocationResponse;
-      try {
-        resp = await this._http.get<GetInvocationResponse>(
-          OASN_ENDPOINTS.INVOCATION(invocationId),
-        );
-      } catch (err) {
-        const te = err as TransportError;
-        // 404 当成 cancelled —— 服务端可能已清理
-        if (te.code === 'INVOCATION_NOT_FOUND' || te.code === 'HTTP_404') {
-          logger.warn(`[transport/oasn/invocation] invocation gone: ${invocationId}`);
-          onComplete(this._build404Response(invocationId));
-          return;
-        }
-        // 其它错误：retryable 的等下一轮，否则向上抛
-        if (te.retryable) {
-          logger.warn(
-            `[transport/oasn/invocation] poll retryable error code=${te.code} for ${invocationId}, will retry`,
-          );
-          // 延后下一轮（指数式，但不超过上限）
-          nextDelay = this._clampPollInterval(nextDelay * 2);
-          continue;
-        }
-        throw err;
-      }
-
-      // ── 进度推送 ───────────────────────────────────────────────
-      const safeStatusMessage = resp.progress?.safeStatusMessage ?? resp.progress?.safe_status_message;
-      if (onProgress && safeStatusMessage) {
-        try {
-          onProgress({
-            content: safeStatusMessage,
-            raw: resp.progress,
-          });
-        } catch (cbErr) {
-          // 不让回调异常影响轮询
-          logger.warn(`[transport/oasn/invocation] onProgress callback threw: ${(cbErr as Error).message}`);
-        }
-      }
-
-      // ── 终态判定 ───────────────────────────────────────────────
-      if (isInvocationTerminal(resp.status)) {
-        logger.info(`[transport/oasn/invocation] terminal status=${resp.status} invocation_id=${invocationId}`);
-        this._pendingStore?.markTerminal(invocationId, resp.status);
-        onComplete(resp);
-        return;
-      }
-
-      // ── 决定下次轮询间隔 ──────────────────────────────────────
-      nextDelay = this._clampPollInterval(resp.nextPollAfterMs ?? resp.next_poll_after_ms ?? FALLBACK_POLL_INTERVAL_MS);
-    }
-  }
-
-  // ═══════════════════════════════════════════════════════════════
-  // waitForTaskResult —— 包装 subscribeToInvocation 为 TaskResult
-  // ═══════════════════════════════════════════════════════════════
-
-  /**
-   * 等待任务结果（终态后转换为 TaskResult）。
-   *
-   * §11.3 协调：
-   *   实际等待时间 = max(本地 timeoutMs, 服务端 effective_timeout_ms)
-   *   差距 > 30% 时输出 warn，提示用户调整。
-   */
-  async waitForTaskResult(
-    handle: TaskHandle,
-    options: { timeoutMs: number; signal?: AbortSignal; onProgress?: ProgressCallback },
-  ): Promise<TaskResult> {
-    const effective = handle.effectiveTimeoutMs
-      ?? this._effectiveTimeoutMap.get(handle.invocationId)
-      ?? options.timeoutMs;
-
-    const totalTimeoutMs = Math.max(options.timeoutMs, effective);
-
-    // §11.3：差距超过 30% 时提示
-    if (effective > options.timeoutMs * 1.3) {
-      logger.warn(
-        `[transport/oasn/invocation] effective_timeout_ms=${effective} exceeds local timeoutMs=${options.timeoutMs} `
-        + `by >30% (invocation_id=${handle.invocationId}); consider increasing local timeout`,
-      );
-    } else if (options.timeoutMs > effective * 1.3) {
-      logger.warn(
-        `[transport/oasn/invocation] local timeoutMs=${options.timeoutMs} exceeds effective_timeout_ms=${effective} `
-        + `by >30% (invocation_id=${handle.invocationId}); server may give up earlier`,
-      );
-    }
-
-    return new Promise<TaskResult>((resolve, reject) => {
-      this.subscribeToInvocation(handle.invocationId, {
-        totalTimeoutMs,
-        signal: options.signal,
-        initialPollAfterMs: handle.nextPollAfterMs,
-        onProgress: options.onProgress
-          ? (p) => options.onProgress!({
-              requestId: handle.invocationId,
-              content: p.content,
-            })
-          : undefined,
-        onComplete: (final) => {
-          try {
-            const result = this._toTaskResult(handle.invocationId, final);
-            // 终态错误转换为 reject，便于上层 catch
-            if (result.status === 'error') {
-              reject(this._terminalError(final, handle));
-              return;
-            }
-            resolve(result);
-          } catch (err) {
-            reject(err);
-          }
-        },
-      }).catch(reject);
-    });
-  }
-
-  // ═══════════════════════════════════════════════════════════════
-  // 内部工具
-  // ═══════════════════════════════════════════════════════════════
-
-  /**
-   * 把终态 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(invocationId: string, final: GetInvocationResponse): TaskResult {
-    const webuiContinuation = this._toWebuiContinuation(final);
-
-    if (final.status === 'succeeded') {
-      const inlineResult = final.inlineResult ?? final.inline_result;
-      const visible = final.visibleResult ?? final.visible_result;
-      const summary = inlineResult?.summary
-        ?? visible?.inlineResultSummary
-        ?? visible?.inline_result_summary
-        ?? '';
-      return {
-        requestId: invocationId,
-        status: 'complete',
-        content: summary,
-        artifacts: (final.artifacts ?? []).map(this._toArtifactRef),
-        webuiContinuation,
-      };
-    }
-
-    const message = this._invocationFailureMessage(
-      final,
-      `Invocation ended with status=${final.status}`,
-    );
-    return {
-      requestId: invocationId,
-      status: 'error',
-      content: message,
-      artifacts: (final.artifacts ?? []).map(this._toArtifactRef),
-      webuiContinuation,
-    };
-  }
-
-  /**
-   * 从终态响应里抽取 WebUI continuation（camelCase / snake_case 双归一）。
-   * 缺必要字段（id / launch_url）时返回 undefined，调用方按 falsy 处理即可。
-   */
-  private _toWebuiContinuation(final: GetInvocationResponse): WebuiContinuationRef | undefined {
-    const visible: VisibleResultResponse | undefined =
-      final.visibleResult ?? final.visible_result;
-    const raw = visible?.webuiContinuation ?? visible?.webui_continuation;
-    if (!raw) return undefined;
-
-    const id = raw.continuationId ?? raw.continuation_id;
-    const launchUrl = raw.launchUrl ?? raw.launch_url;
-    if (!id || !launchUrl) return undefined;
-
-    return {
-      id,
-      launchUrl,
-      displayName: raw.displayName ?? raw.display_name ?? 'Open WebUI',
-      visibleState: raw.visibleState ?? raw.visible_state ?? 'available',
-      sessionId: raw.sessionId ?? raw.session_id,
-    };
-  }
-
-  /** 终态错误专用 TransportError，便于上层 catch */
-  private _terminalError(final: GetInvocationResponse, handle: TaskHandle): TransportError {
-    const code = this._invocationFailureCode(final) ?? `INVOCATION_${final.status.toUpperCase()}`;
-    const msg = this._invocationFailureMessage(final, `Invocation ${final.status}`);
-    return makeTransportError(code, msg, {
-      invocationId: handle.invocationId,
-      sessionId: handle.sessionId,
-    });
-  }
-
-  private _invocationFailureCode(final: GetInvocationResponse): string | undefined {
-    return this._firstText(
-      final.userError?.code,
-      final.user_error?.code,
-      final.userErrorCode,
-      final.user_error_code,
-    );
-  }
-
-  private _invocationFailureMessage(final: GetInvocationResponse, fallback: string): string {
-    const userMessage = this._firstText(
-      final.userError?.message,
-      final.user_error?.message,
-      final.userErrorMessage,
-      final.user_error_message,
-    );
-    if (userMessage) return userMessage;
-
-    const inlineResult = final.inlineResult ?? final.inline_result;
-    const visible = final.visibleResult ?? final.visible_result;
-    const fallbackMessage = this._firstText(
-      inlineResult?.summary,
-      visible?.inlineResultSummary,
-      visible?.inline_result_summary,
-      final.progress?.safeStatusMessage,
-      final.progress?.safe_status_message,
-    );
-    const code = this._invocationFailureCode(final);
-    if (fallbackMessage && code && !fallbackMessage.includes(code)) return `${fallbackMessage} (${code})`;
-    return fallbackMessage ?? code ?? fallback;
-  }
-
-  private _firstText(...values: Array<unknown>): string | undefined {
-    for (const value of values) {
-      if (typeof value !== 'string') continue;
-      const trimmed = value.trim();
-      if (trimmed) return trimmed;
-    }
-    return undefined;
-  }
-
-  private _toArtifactRef(art: ArtifactResponse): ArtifactRef {
-    return {
-      id: art.artifactId ?? art.artifact_id ?? '',
-      displayName: art.displayName ?? art.display_name ?? 'artifact',
-      mimeType: art.mimeType ?? art.mime_type ?? 'application/octet-stream',
-      sizeBytes: art.sizeBytes ?? art.size_bytes ?? 0,
-      contentAvailable: art.contentAvailable ?? art.content_available ?? false,
-      contentUrl: art.contentUrl ?? art.content_url ?? '',
-    };
-  }
-
-  private _normalizeCreateInvocation(
-    resp: CreateInvocationResponse,
-    requestedTimeoutMs: number | undefined,
-  ): {
-    invocationId: string;
-    sessionId: string | undefined;
-    status: CreateInvocationResponse['status'];
-    effectiveTimeoutMs: number;
-    nextPollAfterMs: number;
-    idempotentReplay: boolean;
-  } {
-    return {
-      invocationId: resp.invocationId ?? resp.invocation_id ?? '',
-      sessionId: resp.sessionId ?? resp.session_id,
-      status: resp.status,
-      effectiveTimeoutMs: resp.effectiveTimeoutMs ?? resp.effective_timeout_ms ?? requestedTimeoutMs ?? 0,
-      nextPollAfterMs: resp.nextPollAfterMs ?? resp.next_poll_after_ms ?? FALLBACK_POLL_INTERVAL_MS,
-      idempotentReplay: resp.idempotentReplay ?? resp.idempotent_replay ?? false,
-    };
-  }
-
-  /** clamp 轮询间隔到合理范围 */
-  private _clampPollInterval(ms: number | null | undefined): number {
-    if (!ms || ms <= 0) return FALLBACK_POLL_INTERVAL_MS;
-    return Math.min(MAX_POLL_INTERVAL_MS, Math.max(MIN_POLL_INTERVAL_MS, ms));
-  }
-
-  /** 可被 abort 中断的 sleep */
-  private _sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
-    return new Promise((resolve) => {
-      if (signal?.aborted) {
-        resolve();
-        return;
-      }
-      const t = setTimeout(() => {
-        if (signal) signal.removeEventListener('abort', onAbort);
-        resolve();
-      }, ms);
-      const onAbort = () => {
-        clearTimeout(t);
-        resolve();
-      };
-      signal?.addEventListener('abort', onAbort, { once: true });
-    });
-  }
-
-  /** abort 场景虚拟终态 —— 不调用服务端 cancel（API 不存在 §11.2） */
-  private _buildAbandonedResponse(invocationId: string): GetInvocationResponse {
-    const now = new Date().toISOString();
-    return {
-      invocation_id: invocationId,
-      session_id: '',
-      status: 'cancelled' as InvocationStatus,
-      next_poll_after_ms: null,
-      created_at: now,
-      updated_at: now,
-      user_error: {
-        code: 'CLIENT_ABORTED',
-        message: '已发起调用但放弃跟踪结果（服务端可能仍在执行）',
-      },
-    };
-  }
-
-  /** timeout 虚拟终态 */
-  private _buildTimeoutResponse(invocationId: string): GetInvocationResponse {
-    const now = new Date().toISOString();
-    return {
-      invocation_id: invocationId,
-      session_id: '',
-      status: 'timed_out' as InvocationStatus,
-      next_poll_after_ms: null,
-      created_at: now,
-      updated_at: now,
-      user_error: {
-        code: 'CLIENT_TIMEOUT',
-        message: '本地等待超时，服务端可能仍在执行',
-      },
-    };
-  }
-
-  /** invocation_id 不存在时的虚拟终态 */
-  private _build404Response(invocationId: string): GetInvocationResponse {
-    const now = new Date().toISOString();
-    return {
-      invocation_id: invocationId,
-      session_id: '',
-      status: 'cancelled' as InvocationStatus,
-      next_poll_after_ms: null,
-      created_at: now,
-      updated_at: now,
-      user_error: {
-        code: 'INVOCATION_NOT_FOUND',
-        message: 'Invocation 不存在或已清理',
-      },
-    };
-  }
-}