openclaw-openagent 1.0.0

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

@@ -0,0 +1,210 @@
+/**
+ * OASN 文件上传 + Artifact 下载
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §2.16 / §2.17
+ *   - docs/specs/2026-06-16-oasn-transport-abstraction-design.md §11.4（file_ref LRU）
+ *
+ * 端点：
+ *   - POST /api/files                         multipart 上传 → file_ref
+ *   - GET  /api/artifacts/{id}/content        二进制下载（带 Content-Disposition）
+ *
+ * §11.4 file_ref 过期刷新：
+ *   - 维护内存 LRU：sha256(content) → { fileRef, expiresAt, mimeType, displayName }
+ *   - 上传前调用 ensureFileRef(file)：命中且未过期 → 复用；否则重传
+ *   - 条目数上限 100，淘汰用 LRU
+ *   - expires_at 临近 60s 视为已过期（避免边缘竞态）
+ *
+ * 注意：
+ *   - LRU 仅在单进程内有效；进程重启后丢失，会触发一次重传（可接受）
+ *   - sha256 是 Node 内置，无外部依赖
+ */
+
+import { createHash } from 'node:crypto';
+
+import { logger } from '../../util/logger.js';
+import type {
+  DownloadArtifactResult,
+  UploadFileParams,
+  UploadFileResult,
+} from '../types.js';
+import type { OasnHttpClient } from './oasn-http.js';
+import { OASN_ENDPOINTS, type UploadFileResponse } from './oasn-types.js';
+
+/** LRU 上限 */
+const FILE_REF_LRU_MAX = 100;
+/** expires_at 临近多少 ms 视为已过期 */
+const EXPIRY_MARGIN_MS = 60_000;
+
+interface FileRefCacheEntry {
+  fileRef: string;
+  /** epoch ms */
+  expiresAt: number;
+  mimeType: string;
+  displayName: string;
+  sizeBytes: number;
+}
+
+export class OasnFiles {
+  /**
+   * §11.4 LRU 缓存。
+   * 利用 Map 的插入顺序天然 = 访问顺序：每次访问后 delete + set 重新插入到尾部。
+   */
+  private _refCache = new Map<string, FileRefCacheEntry>();
+
+  constructor(private readonly _http: OasnHttpClient) {}
+
+  // ═══════════════════════════════════════════════════════════════
+  // 上传
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * 上传文件，返回 file_ref。
+   *
+   * 调用方应优先用 ensureFileRef() 复用；本方法是"无脑重传"路径。
+   */
+  async uploadFile(file: UploadFileParams): Promise<UploadFileResult> {
+    const buffer = await this._toBuffer(file.content);
+    return this._doUpload(buffer, file);
+  }
+
+  /**
+   * §11.4 入口：根据内容 hash 命中缓存就复用，否则重传。
+   * sendTask 前应调用此方法，避免 file_ref 过期导致 invocation 400。
+   */
+  async ensureFileRef(file: UploadFileParams): Promise<UploadFileResult> {
+    const buffer = await this._toBuffer(file.content);
+    const hash = this._hashBuffer(buffer);
+    const cached = this._refCache.get(hash);
+
+    if (cached && cached.expiresAt - EXPIRY_MARGIN_MS > Date.now()) {
+      // LRU touch：移到尾部
+      this._refCache.delete(hash);
+      this._refCache.set(hash, cached);
+      logger.info(`[transport/oasn/files] file_ref cache HIT hash=${hash.slice(0, 8)} ref=${cached.fileRef}`);
+      return {
+        fileRef: cached.fileRef,
+        displayName: cached.displayName,
+        mimeType: cached.mimeType,
+        sizeBytes: cached.sizeBytes,
+        expiresAt: cached.expiresAt,
+      };
+    }
+
+    // 未命中或已过期 → 重传
+    if (cached) {
+      logger.info(`[transport/oasn/files] file_ref cache STALE hash=${hash.slice(0, 8)}, will re-upload`);
+      this._refCache.delete(hash);
+    }
+    const result = await this._doUpload(buffer, file);
+    this._cachePut(hash, result);
+    return result;
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // 下载（Artifact 二进制内容）
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * 下载 Artifact 内容。
+   *
+   * 注意：不缓存（artifact 一般是大文件 / 一次性消费），需要缓存的请上层包装。
+   */
+  async downloadArtifact(artifactIdOrContentUrl: string): Promise<DownloadArtifactResult> {
+    logger.info(`[transport/oasn/files] downloadArtifact ref=${artifactIdOrContentUrl}`);
+    const path = this._artifactContentPath(artifactIdOrContentUrl);
+    const resp = await this._http.getBinary(path);
+    return {
+      content: resp.content,
+      mimeType: resp.mimeType,
+      displayName: resp.displayName,
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // 内部
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * 实际上传逻辑。multipart/form-data：
+   *   - file       文件二进制
+   *   - display_name / purpose / expires_in_seconds  字段（按需）
+   */
+  private async _doUpload(buffer: Buffer, file: UploadFileParams): Promise<UploadFileResult> {
+    const fields: Record<string, string> = {
+      display_name: file.displayName,
+    };
+    if (file.purpose) fields.purpose = file.purpose;
+    if (file.expiresInSeconds !== undefined) fields.expires_in_seconds = String(file.expiresInSeconds);
+
+    logger.info(
+      `[transport/oasn/files] upload name=${file.displayName} size=${buffer.byteLength} `
+      + `mime=${file.mimeType ?? 'auto'} purpose=${file.purpose ?? 'none'}`,
+    );
+
+    const resp = await this._http.postMultipart<UploadFileResponse>(
+      OASN_ENDPOINTS.FILES,
+      {
+        file: {
+          content: buffer,
+          filename: file.displayName,
+          mimeType: file.mimeType,
+        },
+        fields,
+      },
+    );
+
+    return {
+      fileRef: resp.file_ref,
+      displayName: resp.display_name,
+      mimeType: resp.mime_type,
+      sizeBytes: resp.size_bytes,
+      expiresAt: this._parseExpiresAt(resp.expires_at),
+    };
+  }
+
+  /** Map LRU put：满了就淘汰最旧 */
+  private _cachePut(hash: string, result: UploadFileResult): void {
+    if (this._refCache.size >= FILE_REF_LRU_MAX) {
+      // 淘汰第一个 key（Map 迭代顺序 = 插入/touch 顺序）
+      const firstKey = this._refCache.keys().next().value;
+      if (firstKey !== undefined) {
+        this._refCache.delete(firstKey);
+        logger.info(`[transport/oasn/files] LRU evict hash=${(firstKey as string).slice(0, 8)}`);
+      }
+    }
+    this._refCache.set(hash, {
+      fileRef: result.fileRef,
+      expiresAt: result.expiresAt,
+      mimeType: result.mimeType,
+      displayName: result.displayName,
+      sizeBytes: result.sizeBytes,
+    });
+  }
+
+  private _artifactContentPath(artifactIdOrContentUrl: string): string {
+    if (/^https?:\/\//i.test(artifactIdOrContentUrl) || artifactIdOrContentUrl.startsWith('/')) {
+      return artifactIdOrContentUrl;
+    }
+    return OASN_ENDPOINTS.ARTIFACT_CONTENT(artifactIdOrContentUrl);
+  }
+
+  /** Blob | Buffer → Buffer */
+  private async _toBuffer(content: Blob | Buffer): Promise<Buffer> {
+    if (Buffer.isBuffer(content)) return content;
+    // Browser Blob path（Node 18+ 内置 Blob）
+    const ab = await content.arrayBuffer();
+    return Buffer.from(ab);
+  }
+
+  /** sha256 hex —— 标识文件唯一性 */
+  private _hashBuffer(buf: Buffer): string {
+    return createHash('sha256').update(buf).digest('hex');
+  }
+
+  /** ISO 8601 → epoch ms（解析失败时给 0，让缓存下次 miss） */
+  private _parseExpiresAt(iso: string): number {
+    const ms = Date.parse(iso);
+    return Number.isNaN(ms) ? 0 : ms;
+  }
+}

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

@@ -0,0 +1,483 @@
+/**
+ * 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, type RequestOptions } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+
+import { logger } from '../../util/logger.js';
+import { makeTransportError, type TransportError } from '../types.js';
+import type { OasnErrorBody } from './oasn-types.js';
+
+/** 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;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+
+// ───────────────────────────────────────────────────────────────
+// 错误转换
+// ───────────────────────────────────────────────────────────────
+
+/**
+ * 把 HTTP 响应（含可能的 OASN 统一错误体）转换为 TransportError。
+ * 如果响应非 OASN 统一格式，使用 HTTP 状态码做兜底。
+ */
+function toTransportError(
+  statusCode: number,
+  rawBody: string,
+): TransportError {
+  let code = `HTTP_${statusCode}`;
+  let message = rawBody.slice(0, 500);
+  let retryable = statusCode >= 500 || statusCode === 429 || statusCode === 408;
+  let requestId: string | undefined;
+
+  try {
+    const parsed = JSON.parse(rawBody) as Partial<OasnErrorBody>;
+    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 {
+  private _config: OasnHttpConfig;
+
+  constructor(config: OasnHttpConfig) {
+    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: string | undefined): void {
+    this._config.token = token;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // 公共方法
+  // ─────────────────────────────────────────────────────────────
+
+  async get<T>(path: string, options?: OasnRequestOptions): Promise<T> {
+    return this._jsonRequest<T>('GET', path, undefined, options);
+  }
+
+  async post<T>(path: string, body: unknown, options?: OasnRequestOptions): Promise<T> {
+    return this._jsonRequest<T>('POST', path, body, options);
+  }
+
+  async patch<T>(path: string, body: unknown, options?: OasnRequestOptions): Promise<T> {
+    return this._jsonRequest<T>('PATCH', path, body, options);
+  }
+
+  /**
+   * multipart/form-data 上传。
+   * 仅支持 file + metadata 字段，不做通用 multipart 支持（OASN 上传场景固定）。
+   */
+  async postMultipart<T>(
+    path: string,
+    parts: {
+      file: { content: Buffer; filename: string; mimeType?: string };
+      fields?: Record<string, string>;
+    },
+    options?: OasnRequestOptions,
+  ): Promise<T> {
+    const boundary = `------oasn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    const chunks: Buffer[] = [];
+
+    // 普通字段
+    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<T>('POST', path, body, {
+      ...options,
+      headers: {
+        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+        ...options?.headers,
+      },
+      isJsonBody: false,
+      expectJsonResponse: true,
+    });
+  }
+
+  /**
+   * 下载二进制内容（用于 Artifact 下载）。
+   * 不解析响应，直接返回 ArrayBuffer + 头信息。
+   */
+  async getBinary(
+    path: string,
+    options?: OasnRequestOptions,
+  ): Promise<{ content: ArrayBuffer; mimeType: string; displayName: string }> {
+    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: string,
+    path: string,
+    headers: Record<string, string>,
+    body?: Buffer | string,
+    options?: OasnRequestOptions,
+  ): Promise<{ statusCode: number; headers: Record<string, string>; body: string }> {
+    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);
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // 内部实现
+  // ─────────────────────────────────────────────────────────────
+
+  private _resolveUrl(path: string): URL {
+    if (/^https?:\/\//i.test(path)) {
+      return new URL(path);
+    }
+    // path 必须以 / 开头
+    const base = this._config.apiBase.replace(/\/$/, '');
+    return new URL(`${base}${path}`);
+  }
+
+  private _buildHeaders(extra: Record<string, string>): Record<string, string> {
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...extra,
+    };
+    if (this._config.token) {
+      headers['Authorization'] = `Bearer ${this._config.token}`;
+    }
+    return headers;
+  }
+
+  /**
+   * JSON 请求 —— body 自动 JSON.stringify，响应 JSON.parse。
+   * 含重试逻辑（仅当 retryable=true 时）。
+   */
+  private async _jsonRequest<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    options?: OasnRequestOptions,
+  ): Promise<T> {
+    return this._rawRequest<T>(method, path, body, {
+      ...options,
+      isJsonBody: true,
+      expectJsonResponse: true,
+    });
+  }
+
+  private async _rawRequest<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    options: OasnRequestOptions & { isJsonBody: boolean; expectJsonResponse: boolean },
+  ): Promise<T> {
+    const url = this._resolveUrl(path);
+    const headers = this._buildHeaders(options?.headers ?? {});
+
+    let bodyBuffer: Buffer | undefined;
+    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 as Buffer;
+        if (!headers['Content-Length']) {
+          headers['Content-Length'] = String(bodyBuffer.length);
+        }
+      }
+    }
+
+    const maxAttempts = options.skipRetry ? 1 : (this._config.maxRetries! + 1);
+    let lastErr: unknown;
+
+    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 as T;
+          if (statusCode === 204 || !respBody) return undefined as T;
+          try {
+            return JSON.parse(respBody) as T;
+          } catch (parseErr) {
+            throw makeTransportError(
+              'INVALID_JSON_RESPONSE',
+              `Failed to parse OASN response: ${(parseErr as Error).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 as TransportError).code !== undefined;
+        if (isTransport) throw err;
+        lastErr = err;
+        if (attempt === maxAttempts - 1) {
+          throw makeTransportError(
+            'NETWORK_ERROR',
+            `${method} ${path} failed: ${(err as Error).message}`,
+            { retryable: true },
+          );
+        }
+      }
+    }
+
+    // 不可达，但 TS 需要
+    throw lastErr ?? new Error('Unknown HTTP error');
+  }
+
+  /** 执行单次 HTTP 请求（不解析响应体格式） */
+  private _doRawRequest(
+    url: URL,
+    method: string,
+    headers: Record<string, string>,
+    body: Buffer | string | undefined,
+    timeoutMs: number,
+    signal?: AbortSignal,
+  ): Promise<{ statusCode: number; headers: Record<string, string>; body: string }> {
+    const isHttps = url.protocol === 'https:';
+    const requestFn = isHttps ? httpsRequest : httpRequest;
+
+    return new Promise((resolve, reject) => {
+      const reqOptions: RequestOptions = {
+        method,
+        headers,
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: `${url.pathname}${url.search}`,
+      };
+
+      let settled = false;
+      let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        if (timeoutHandle) clearTimeout(timeoutHandle);
+        fn();
+      };
+
+      const req = requestFn(reqOptions, (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk: Buffer) => chunks.push(chunk));
+        res.on('end', () => {
+          const respBody = Buffer.concat(chunks).toString('utf-8');
+          const respHeaders: Record<string, string> = {};
+          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();
+    });
+  }
+
+  /** 二进制下载 */
+  private _doBinaryRequest(
+    url: URL,
+    headers: Record<string, string>,
+    timeoutMs: number,
+    signal?: AbortSignal,
+  ): Promise<{ content: ArrayBuffer; mimeType: string; displayName: string }> {
+    const isHttps = url.protocol === 'https:';
+    const requestFn = isHttps ? httpsRequest : httpRequest;
+
+    return new Promise((resolve, reject) => {
+      const reqOptions: RequestOptions = {
+        method: 'GET',
+        headers,
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: `${url.pathname}${url.search}`,
+      };
+
+      let settled = false;
+      let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        if (timeoutHandle) clearTimeout(timeoutHandle);
+        fn();
+      };
+
+      const req = requestFn(reqOptions, (res) => {
+        const status = res.statusCode ?? 0;
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk: Buffer) => 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) as ArrayBuffer,
+              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();
+    });
+  }
+}