openclaw-openagent 1.0.1 → 1.0.3

package/dist/src/transport/factory.js

@@ -0,0 +1,54 @@
+/**
+ * Transport 工厂 —— 按配置创建 AgentTransport 实例
+ *
+ * 设计依据：docs/specs/2026-06-16-oasn-transport-abstraction-design.md §3.1
+ *
+ * 调用方（AccountRuntime）通过 transportType 字段决定走 OASN 还是 TIM 路径，
+ * 工厂内部 lazy-import 各自的实现模块，确保「未启用的 transport 不进入运行时」。
+ *   - 选 OASN 时不加载 TIM SDK（节省启动内存 & 避免无意义的 WebSocket 探测）
+ *   - 选 TIM  时不加载 OASN HTTP 客户端（更小的攻击面）
+ *
+ * 注意：transport 实例创建后必须显式调用 ready(credentials) 才能使用，
+ * 工厂只负责实例化，不负责凭证校验和连接。
+ */
+/**
+ * 创建 transport 实例。
+ *
+ * 关键设计：返回类型是 union `AgentTransport`，调用方需用 `transportType` 字段 narrow：
+ *
+ * ```ts
+ * const t = await createTransport({ transportType: 'oasn', apiBase, agentId });
+ * if (t.transportType === 'oasn') {
+ *   // 这里 TypeScript 知道 t 是 OasnTransport —— 可以调 t.registerAgent()
+ *   await t.registerAgent('openclaw');
+ * }
+ * ```
+ *
+ * @throws 当 OASN 路径但缺少 apiBase 时
+ */
+export async function createTransport(options) {
+    if (options.transportType === 'oasn') {
+        if (!options.apiBase) {
+            throw new Error('createTransport: apiBase is required for OASN transport');
+        }
+        // lazy import：选 OASN 时才加载 OASN 模块（OASN HTTP 客户端不依赖 TIM SDK）
+        const { OasnTransportImpl } = await import('./oasn/oasn-transport.js');
+        return new OasnTransportImpl({
+            apiBase: options.apiBase,
+            accessApiBase: options.accessApiBase,
+            agentId: options.agentId ?? '',
+            accountId: options.accountId ?? options.agentId ?? 'default',
+            // §11.1 持久化挂载点：仅当上层提供 pendingStore 时启用
+            ...(options.pendingStore ? { pendingStore: options.pendingStore } : {}),
+        });
+    }
+    if (options.transportType === 'tim') {
+        // lazy import：选 TIM 时才加载 TIM SDK（避免 OASN 路径下加载 ~2MB 的 SDK）
+        const { TimTransportImpl } = await import('./tim/tim-transport.js');
+        return new TimTransportImpl({
+            accountId: options.accountId ?? 'default',
+        });
+    }
+    // 编译期已是 'oasn' | 'tim' 的 union，运行期还能到这里说明配置异常
+    throw new Error(`createTransport: unknown transportType "${options.transportType}"`);
+}

package/dist/src/transport/oasn/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * OASN transport 子模块统一出口。
+ *
+ * 设计依据：docs/specs/2026-06-16-oasn-transport-abstraction-design.md §3.1
+ *
+ * 仅 re-export 实现类与跨模块共用类型。OASN 内部 API 类型（snake_case 协议字段）
+ * 不导出到外层 —— 上层应面向 src/transport/types.ts 的通用类型编程。
+ */
+export { OasnTransportImpl } from './oasn-transport.js';
+export type { OasnTransportInitOptions } from './oasn-transport.js';
+export type { PendingInvocationStore } from './oasn-invocation.js';
+export type { OasnErrorBody } from './oasn-types.js';

package/dist/src/transport/oasn/index.js

@@ -0,0 +1,9 @@
+/**
+ * OASN transport 子模块统一出口。
+ *
+ * 设计依据：docs/specs/2026-06-16-oasn-transport-abstraction-design.md §3.1
+ *
+ * 仅 re-export 实现类与跨模块共用类型。OASN 内部 API 类型（snake_case 协议字段）
+ * 不导出到外层 —— 上层应面向 src/transport/types.ts 的通用类型编程。
+ */
+export { OasnTransportImpl } from './oasn-transport.js';

package/dist/src/transport/oasn/oasn-agent-card.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OASN AgentCard CRUD + Owner 查询
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §2.7 / §2.8 / §2.9
+ *
+ * 端点：
+ *   - GET   /api/agent-cards/{agent_id}    公开查询（claimed+active+public 才 200）
+ *   - PATCH /api/agent-cards/{agent_id}    Owner 或 Agent 更新
+ *   - GET   /api/users/me                  当前 Owner（Owner access token 场景）
+ */
+import type { AgentCard, AgentCardPatch, OwnerInfo } from '../types.js';
+import type { OasnHttpClient } from './oasn-http.js';
+export declare class OasnAgentCard {
+    private readonly _http;
+    constructor(_http: OasnHttpClient);
+    /**
+     * 查询 AgentCard 公开信息。
+     *
+     * 用途：
+     *   1. `connect()` 时验证 api_key 有效性（即使返回 404 也能确认 Bearer 没被 401）
+     *   2. UI 展示其他 Agent 的详情
+     *
+     * 404 时返回 null（agent 不存在、未认领、或 private）。
+     */
+    get(agentId: string): Promise<AgentCard | null>;
+    /**
+     * 更新 AgentCard。
+     * PATCH 语义：省略字段不变，显式 null 清空。
+     */
+    update(agentId: string, patch: AgentCardPatch): Promise<AgentCard>;
+    /**
+     * 查询当前 Owner（仅当 Bearer 是 Owner access token 时可用）。
+     * Agent api_key 调用此接口可能返回 403。
+     */
+    getCurrentOwner(): Promise<OwnerInfo | null>;
+    private _toAgentCard;
+}

package/dist/src/transport/oasn/oasn-agent-card.js

@@ -0,0 +1,102 @@
+/**
+ * OASN AgentCard CRUD + Owner 查询
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §2.7 / §2.8 / §2.9
+ *
+ * 端点：
+ *   - GET   /api/agent-cards/{agent_id}    公开查询（claimed+active+public 才 200）
+ *   - PATCH /api/agent-cards/{agent_id}    Owner 或 Agent 更新
+ *   - GET   /api/users/me                  当前 Owner（Owner access token 场景）
+ */
+import { logger } from '../../util/logger.js';
+import { OASN_ENDPOINTS, } from './oasn-types.js';
+import { normalizeAgentCard } from './oasn-normalize.js';
+export class OasnAgentCard {
+    _http;
+    constructor(_http) {
+        this._http = _http;
+    }
+    /**
+     * 查询 AgentCard 公开信息。
+     *
+     * 用途：
+     *   1. `connect()` 时验证 api_key 有效性（即使返回 404 也能确认 Bearer 没被 401）
+     *   2. UI 展示其他 Agent 的详情
+     *
+     * 404 时返回 null（agent 不存在、未认领、或 private）。
+     */
+    async get(agentId) {
+        try {
+            const resp = await this._http.get(OASN_ENDPOINTS.AGENT_CARD(agentId));
+            return this._toAgentCard(resp);
+        }
+        catch (err) {
+            const te = err;
+            if (te.code === 'HTTP_404' || te.code === 'AGENT_CARD_NOT_FOUND') {
+                logger.info(`[transport/oasn/agent-card] get(${agentId}) → 404 not found`);
+                return null;
+            }
+            throw err;
+        }
+    }
+    /**
+     * 更新 AgentCard。
+     * PATCH 语义：省略字段不变，显式 null 清空。
+     */
+    async update(agentId, patch) {
+        const body = {};
+        // 只复制存在的字段（undefined 不发，null 显式发出）
+        if ('name' in patch)
+            body.name = patch.name;
+        if ('description' in patch)
+            body.description = patch.description;
+        if ('MOM' in patch)
+            body.MOM = patch.MOM;
+        if ('tags' in patch)
+            body.tags = patch.tags;
+        if ('category' in patch)
+            body.category = patch.category;
+        if ('avatar_ref' in patch)
+            body.avatarRef = patch.avatar_ref;
+        if ('visibility' in patch)
+            body.visibility = patch.visibility;
+        if ('public_metadata' in patch)
+            body.publicMetadata = patch.public_metadata;
+        logger.info(`[transport/oasn/agent-card] update agent=${agentId} fields=${Object.keys(body).join(',')}`);
+        const resp = await this._http.patch(OASN_ENDPOINTS.AGENT_CARD(agentId), body);
+        return this._toAgentCard(resp);
+    }
+    /**
+     * 查询当前 Owner（仅当 Bearer 是 Owner access token 时可用）。
+     * Agent api_key 调用此接口可能返回 403。
+     */
+    async getCurrentOwner() {
+        try {
+            const resp = await this._http.get(OASN_ENDPOINTS.USERS_ME);
+            return {
+                owner_id: resp.ownerId ?? resp.owner_id ?? '',
+                owner_type: resp.ownerType ?? resp.owner_type ?? '',
+                display_name: resp.displayName ?? resp.display_name ?? '',
+                email_masked: resp.emailMasked ?? resp.email_masked ?? '',
+                ...((resp.emailVerifiedAt ?? resp.email_verified_at)
+                    ? { email_verified_at: resp.emailVerifiedAt ?? resp.email_verified_at }
+                    : {}),
+                status: resp.status,
+            };
+        }
+        catch (err) {
+            const te = err;
+            if (te.code === 'HTTP_401' || te.code === 'HTTP_403' || te.code === 'UNAUTHENTICATED') {
+                return null;
+            }
+            throw err;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────
+    // 工具
+    // ─────────────────────────────────────────────────────────────
+    _toAgentCard(resp) {
+        return normalizeAgentCard(resp);
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * OASN Discovery —— Agent 搜索 + Category 树
+ *
+ * 设计依据：docs/specs/2026-06-16-oasn-api-module-mapping.md §2.10 ~ §2.13
+ *
+ * 三种搜索方式，按非空字段路由到对应端点：
+ *   - query   → POST /api/agent-cards/search/by-query    （自然语言）
+ *   - category→ POST /api/agent-cards/search/by-category （分类浏览）
+ *   - tags    → POST /api/agent-cards/search/by-tags     （标签筛选）
+ *
+ * 当前 OASN search 仅支持 agent_types=['service']（详见设计文档 §九 风险表）。
+ */
+import type { CategoryTree, SearchQuery, SearchResult } from '../types.js';
+import type { OasnHttpClient } from './oasn-http.js';
+export declare class OasnDiscovery {
+    private readonly _http;
+    constructor(_http: OasnHttpClient);
+    /**
+     * 路由到对应搜索端点。
+     *
+     * 优先级（互斥使用）：query > category > tags。
+     * 当多个字段都传入时，以 query 为准并 logger.warn 提示。
+     */
+    search(query: SearchQuery): Promise<SearchResult>;
+    private _searchByQuery;
+    private _searchByCategory;
+    private _searchByTags;
+    /** 获取 category 树（用于 Agent Book UI 的分类浏览面板） */
+    getCategories(params?: {
+        agentType?: string;
+    }): Promise<CategoryTree>;
+    private _toSearchResult;
+}

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

@@ -0,0 +1,97 @@
+/**
+ * OASN Discovery —— Agent 搜索 + Category 树
+ *
+ * 设计依据：docs/specs/2026-06-16-oasn-api-module-mapping.md §2.10 ~ §2.13
+ *
+ * 三种搜索方式，按非空字段路由到对应端点：
+ *   - query   → POST /api/agent-cards/search/by-query    （自然语言）
+ *   - category→ POST /api/agent-cards/search/by-category （分类浏览）
+ *   - tags    → POST /api/agent-cards/search/by-tags     （标签筛选）
+ *
+ * 当前 OASN search 仅支持 agent_types=['service']（详见设计文档 §九 风险表）。
+ */
+import { logger } from '../../util/logger.js';
+import { OASN_ENDPOINTS, } from './oasn-types.js';
+import { normalizeCategoryTree, normalizeSearchResponse } from './oasn-normalize.js';
+export class OasnDiscovery {
+    _http;
+    constructor(_http) {
+        this._http = _http;
+    }
+    /**
+     * 路由到对应搜索端点。
+     *
+     * 优先级（互斥使用）：query > category > tags。
+     * 当多个字段都传入时，以 query 为准并 logger.warn 提示。
+     */
+    async search(query) {
+        const hasQuery = !!query.query && query.query.trim().length > 0;
+        const hasCategory = !!query.category && query.category.length > 0;
+        const hasTags = !!query.tags && query.tags.length > 0;
+        if ([hasQuery, hasCategory, hasTags].filter(Boolean).length > 1) {
+            logger.warn('[transport/oasn/discovery] multiple search criteria provided, prioritising query > category > tags');
+        }
+        if (hasQuery)
+            return this._searchByQuery(query);
+        if (hasCategory)
+            return this._searchByCategory(query);
+        if (hasTags)
+            return this._searchByTags(query);
+        // 都为空：默认走 query=""（服务端可能拒绝，但 transport 不主动推断）
+        throw new Error('OasnDiscovery.search: at least one of query/category/tags must be provided');
+    }
+    async _searchByQuery(q) {
+        const body = {
+            query: q.query.trim(),
+            agentTypes: q.agentTypes ?? ['service'],
+        };
+        if (q.sort)
+            body.sort = q.sort;
+        if (q.pageSize !== undefined)
+            body.pageSize = q.pageSize;
+        if (q.pageNum !== undefined)
+            body.pageNum = q.pageNum;
+        const resp = await this._http.post(OASN_ENDPOINTS.SEARCH_BY_QUERY, body);
+        return this._toSearchResult(resp);
+    }
+    async _searchByCategory(q) {
+        const body = {
+            category: q.category,
+            agentTypes: q.agentTypes ?? ['service'],
+        };
+        if (q.sort)
+            body.sort = q.sort;
+        if (q.pageSize !== undefined)
+            body.pageSize = q.pageSize;
+        if (q.pageNum !== undefined)
+            body.pageNum = q.pageNum;
+        const resp = await this._http.post(OASN_ENDPOINTS.SEARCH_BY_CATEGORY, body);
+        return this._toSearchResult(resp);
+    }
+    async _searchByTags(q) {
+        const body = {
+            tags: q.tags,
+            agentTypes: q.agentTypes ?? ['service'],
+        };
+        if (q.sort)
+            body.sort = q.sort;
+        if (q.pageSize !== undefined)
+            body.pageSize = q.pageSize;
+        if (q.pageNum !== undefined)
+            body.pageNum = q.pageNum;
+        const resp = await this._http.post(OASN_ENDPOINTS.SEARCH_BY_TAGS, body);
+        return this._toSearchResult(resp);
+    }
+    /** 获取 category 树（用于 Agent Book UI 的分类浏览面板） */
+    async getCategories(params) {
+        const qs = params?.agentType ? `?agent_type=${encodeURIComponent(params.agentType)}` : '';
+        const resp = await this._http.get(`${OASN_ENDPOINTS.CATEGORIES}${qs}`);
+        return normalizeCategoryTree(resp);
+    }
+    // ─────────────────────────────────────────────────────────────
+    // 工具
+    // ─────────────────────────────────────────────────────────────
+    _toSearchResult(resp) {
+        return normalizeSearchResponse(resp);
+    }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * 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 type { DownloadArtifactResult, UploadFileParams, UploadFileResult } from '../types.js';
+import type { OasnHttpClient } from './oasn-http.js';
+export declare class OasnFiles {
+    private readonly _http;
+    /**
+     * §11.4 LRU 缓存。
+     * 利用 Map 的插入顺序天然 = 访问顺序：每次访问后 delete + set 重新插入到尾部。
+     */
+    private _refCache;
+    constructor(_http: OasnHttpClient);
+    /**
+     * 上传文件，返回 file_ref。
+     *
+     * 调用方应优先用 ensureFileRef() 复用；本方法是"无脑重传"路径。
+     */
+    uploadFile(file: UploadFileParams): Promise<UploadFileResult>;
+    /**
+     * §11.4 入口：根据内容 hash 命中缓存就复用，否则重传。
+     * sendTask 前应调用此方法，避免 file_ref 过期导致 invocation 400。
+     */
+    ensureFileRef(file: UploadFileParams): Promise<UploadFileResult>;
+    /**
+     * 下载 Artifact 内容。
+     *
+     * 注意：不缓存（artifact 一般是大文件 / 一次性消费），需要缓存的请上层包装。
+     */
+    downloadArtifact(artifactIdOrContentUrl: string): Promise<DownloadArtifactResult>;
+    /**
+     * 实际上传逻辑。multipart/form-data：
+     *   - file       文件二进制
+     *   - display_name / purpose / expires_in_seconds  字段（按需）
+     */
+    private _doUpload;
+    /** Map LRU put：满了就淘汰最旧 */
+    private _cachePut;
+    private _artifactContentPath;
+    /** Blob | Buffer → Buffer */
+    private _toBuffer;
+    /** sha256 hex —— 标识文件唯一性 */
+    private _hashBuffer;
+    /** ISO 8601 → epoch ms（解析失败时给 0，让缓存下次 miss） */
+    private _parseExpiresAt;
+}

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

@@ -0,0 +1,174 @@
+/**
+ * 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 { OASN_ENDPOINTS } from './oasn-types.js';
+/** LRU 上限 */
+const FILE_REF_LRU_MAX = 100;
+/** expires_at 临近多少 ms 视为已过期 */
+const EXPIRY_MARGIN_MS = 60_000;
+export class OasnFiles {
+    _http;
+    /**
+     * §11.4 LRU 缓存。
+     * 利用 Map 的插入顺序天然 = 访问顺序：每次访问后 delete + set 重新插入到尾部。
+     */
+    _refCache = new Map();
+    constructor(_http) {
+        this._http = _http;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // 上传
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * 上传文件，返回 file_ref。
+     *
+     * 调用方应优先用 ensureFileRef() 复用；本方法是"无脑重传"路径。
+     */
+    async uploadFile(file) {
+        const buffer = await this._toBuffer(file.content);
+        return this._doUpload(buffer, file);
+    }
+    /**
+     * §11.4 入口：根据内容 hash 命中缓存就复用，否则重传。
+     * sendTask 前应调用此方法，避免 file_ref 过期导致 invocation 400。
+     */
+    async ensureFileRef(file) {
+        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) {
+        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  字段（按需）
+     */
+    async _doUpload(buffer, file) {
+        const fields = {
+            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(OASN_ENDPOINTS.FILES, {
+            file: {
+                content: buffer,
+                filename: file.displayName,
+                mimeType: file.mimeType,
+            },
+            fields,
+        });
+        return {
+            fileRef: resp.fileRef ?? resp.file_ref ?? '',
+            displayName: resp.displayName ?? resp.display_name ?? 'unknown',
+            mimeType: resp.mimeType ?? resp.mime_type ?? 'application/octet-stream',
+            sizeBytes: resp.sizeBytes ?? resp.size_bytes ?? 0,
+            expiresAt: this._parseExpiresAt(resp.expiresAt ?? resp.expires_at ?? ''),
+        };
+    }
+    /** Map LRU put：满了就淘汰最旧 */
+    _cachePut(hash, result) {
+        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.slice(0, 8)}`);
+            }
+        }
+        this._refCache.set(hash, {
+            fileRef: result.fileRef,
+            expiresAt: result.expiresAt,
+            mimeType: result.mimeType,
+            displayName: result.displayName,
+            sizeBytes: result.sizeBytes,
+        });
+    }
+    _artifactContentPath(artifactIdOrContentUrl) {
+        if (/^https?:\/\//i.test(artifactIdOrContentUrl) || artifactIdOrContentUrl.startsWith('/')) {
+            return artifactIdOrContentUrl;
+        }
+        return OASN_ENDPOINTS.ARTIFACT_CONTENT(artifactIdOrContentUrl);
+    }
+    /** Blob | Buffer → Buffer */
+    async _toBuffer(content) {
+        if (Buffer.isBuffer(content))
+            return content;
+        // Browser Blob path（Node 18+ 内置 Blob）
+        const ab = await content.arrayBuffer();
+        return Buffer.from(ab);
+    }
+    /** sha256 hex —— 标识文件唯一性 */
+    _hashBuffer(buf) {
+        return createHash('sha256').update(buf).digest('hex');
+    }
+    /** ISO 8601 → epoch ms（解析失败时给 0，让缓存下次 miss） */
+    _parseExpiresAt(iso) {
+        const ms = Date.parse(iso);
+        return Number.isNaN(ms) ? 0 : ms;
+    }
+}