openclaw-openagent 1.0.0

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

@@ -0,0 +1,106 @@
+/**
+ * OASN Agent 注册与认领
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §2.1 / §2.2
+ *
+ * 调用时机：
+ *   - registerAgent：插件首次安装、本地无 agent_id/api_key 时
+ *   - claimAgent：用户主动触发认领（带 owner_email）
+ *
+ * 关键约束：
+ *   - register 返回的 api_key **是明文且仅此一次**。调用方必须立即持久化（最好走 keychain，§11.6）
+ *   - 当前后端 RegisterAgentCommand 只定义 platform；install_id/device_hint 需先扩展后端契约
+ */
+
+import { logger } from '../../util/logger.js';
+import type { AgentStatusResult, ClaimParams, ClaimResult, RegisterResult } from '../types.js';
+import type { OasnHttpClient } from './oasn-http.js';
+import {
+  OASN_ENDPOINTS,
+  type ClaimAgentRequest,
+  type ClaimAgentResponse,
+  type AgentStatusResponse,
+  type RegisterAgentRequest,
+  type RegisterAgentResponse,
+} from './oasn-types.js';
+import {
+  normalizeAgentStatus,
+  normalizeClaimResult,
+  normalizeRegisterResult,
+} from './oasn-normalize.js';
+
+/**
+ * OASN Agent 注册模块。
+ *
+ * 注意 register 和 claim 是 OASN-only 能力，TIM transport 不暴露这两个方法。
+ * AccountRuntime 在 transport-type === 'oasn' 时才能调用。
+ */
+export class OasnRegister {
+  constructor(private readonly _http: OasnHttpClient) {}
+
+  /**
+   * 注册新 Agent（首次安装流程）。
+   *
+   * @param platform OpenClaw 上固定为 "openclaw"
+   * @returns 含一次性明文 api_key 的注册响应。调用方必须立即持久化。
+   */
+  async register(
+    platform: string,
+    _params?: { installId?: string; deviceHint?: string },
+  ): Promise<RegisterResult> {
+    const body: RegisterAgentRequest = { platform };
+
+    logger.info(`[transport/oasn/register] register platform=${platform}`);
+
+    // skipRetry=true：register 是不幂等的写入，重试可能创建多个 agent
+    const resp = await this._http.post<RegisterAgentResponse>(
+      OASN_ENDPOINTS.REGISTER,
+      body,
+      { skipRetry: true },
+    );
+
+    const result = normalizeRegisterResult(resp);
+    logger.info(`[transport/oasn/register] registered agent_id=${result.agent_id} status=${result.status}`);
+    return result;
+  }
+
+  /**
+   * 触发认领邮件发送。
+   * 认证方式由 OasnHttpClient 注入的 Bearer 决定：
+   *   - 带 api_key：传入 { agent_id, owner_email }
+   *   - 不带 api_key（首次进入）：传入 { claim_token, owner_email }
+   */
+  async claim(params: ClaimParams): Promise<ClaimResult> {
+    if (!params.agent_id && !params.claim_token) {
+      throw new Error('OasnRegister.claim: must provide either agent_id or claim_token');
+    }
+    if (!params.owner_email) {
+      throw new Error('OasnRegister.claim: owner_email required');
+    }
+
+    const body: ClaimAgentRequest = {
+      ownerEmail: params.owner_email,
+    };
+    if (params.agent_id) body.agentId = params.agent_id;
+    if (params.claim_token) body.claimToken = params.claim_token;
+
+    logger.info(`[transport/oasn/register] claim email=${params.owner_email.replace(/(.).+(@.+)/, '$1***$2')}`);
+
+    const resp = await this._http.post<ClaimAgentResponse>(
+      OASN_ENDPOINTS.CLAIM,
+      body,
+      { skipRetry: true },
+    );
+
+    return normalizeClaimResult(resp);
+  }
+
+  async getStatus(agentId: string): Promise<AgentStatusResult> {
+    const resp = await this._http.get<AgentStatusResponse>(
+      OASN_ENDPOINTS.AGENT_STATUS(agentId),
+      { skipRetry: true },
+    );
+    return normalizeAgentStatus(resp);
+  }
+}

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

@@ -0,0 +1,341 @@
+/**
+ * OasnTransport —— 装配 OASN 子模块为统一的 AgentTransport
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-transport-abstraction-design.md §2.4
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §3.1
+ *
+ * 子模块组装：
+ *   - OasnHttpClient    HTTP 基础（Bearer 注入 / 重试 / 401 拦截）
+ *   - OasnRegister      register / claim
+ *   - OasnAgentCard     get / update / getCurrentOwner
+ *   - OasnDiscovery     search / categories
+ *   - OasnInvocation    sendTask / waitForTaskResult（核心路径）
+ *   - OasnFiles         upload / download + LRU
+ *
+ * 与 CoreTransport 契约的映射：
+ *   - id           = options.accountId
+ *   - transportType= 'oasn'
+ *   - ready()      = 用 credentials.token 设置 Bearer，调 GET /api/agent-cards/{agent_id} 探活
+ *                    （404 也算成功 —— 未认领的 agent 仍能用 api_key，只是公开查询返 404）
+ *   - dispose()    = 释放 HTTP（无长连接）+ 清空 token
+ *   - isReady      = ready() 成功且 token 非空
+ *   - 'credential_expired' 事件 = §11.5 401 撤销路径
+ *
+ * 与 TimTransport 的差异：
+ *   - 不持有 WebSocket / 长连接 → dispose 几乎是 no-op
+ *   - 不实现 IMChannelTransport（onTaskReceived / sendGroupMessage 等）
+ *   - register/claim/updateAgentCard/uploadFile/downloadArtifact 是 OASN-only 能力
+ */
+
+import { EventEmitter } from 'node:events';
+
+import { logger } from '../../util/logger.js';
+import {
+  makeTransportError,
+  type AgentCard,
+  type AgentCardPatch,
+  type AgentStatusResult,
+  type CategoryTree,
+  type ClaimParams,
+  type ClaimResult,
+  type CoreTransportEvent,
+  type DownloadArtifactResult,
+  type OasnTransport,
+  type OwnerInfo,
+  type ProgressCallback,
+  type RegisterResult,
+  type SearchQuery,
+  type SearchResult,
+  type TaskHandle,
+  type TaskRequest,
+  type TaskResult,
+  type TransportCredentials,
+  type TransportError,
+  type UploadFileParams,
+  type UploadFileResult,
+} from '../types.js';
+import { OasnAgentCard } from './oasn-agent-card.js';
+import { OasnDiscovery } from './oasn-discovery.js';
+import { OasnFiles } from './oasn-files.js';
+import { OasnHttpClient } from './oasn-http.js';
+import {
+  OasnInvocation,
+  type CreateInvocationOptions,
+  type PendingInvocationStore,
+} from './oasn-invocation.js';
+import { OasnRegister } from './oasn-register.js';
+
+// ───────────────────────────────────────────────────────────────
+// 构造选项
+// ───────────────────────────────────────────────────────────────
+
+export interface OasnTransportInitOptions {
+  /** 实例 id（多账户场景区分用） */
+  accountId: string;
+  /** OASN API base URL，例 `https://api.oasn.ai` */
+  apiBase: string;
+  /** Optional Access-layer API base URL for invocation/file/artifact endpoints. */
+  accessApiBase?: string;
+  /**
+   * 当前 agent_id（用于 ready() 探活 + register 后回填）。
+   * 可在 ready() 之前为空（未注册场景），但 sendTask 之类操作会失败。
+   */
+  agentId?: string;
+  /** §11.1 持久化钩子（接 StateStore.pending_invocations）；可选 */
+  pendingStore?: PendingInvocationStore;
+  /** 单次 HTTP 超时（默认 30s） */
+  defaultTimeoutMs?: number;
+  /** retryable 错误自动重试次数（默认 3） */
+  maxRetries?: number;
+}
+
+// ───────────────────────────────────────────────────────────────
+// 实现类
+// ───────────────────────────────────────────────────────────────
+
+export class OasnTransportImpl extends EventEmitter implements OasnTransport {
+  readonly transportType = 'oasn' as const;
+  readonly id: string;
+
+  private _http: OasnHttpClient;
+  private _accessHttp: OasnHttpClient;
+  private _agentCard: OasnAgentCard;
+  private _discovery: OasnDiscovery;
+  private _register: OasnRegister;
+  private _invocation: OasnInvocation;
+  private _files: OasnFiles;
+
+  private _agentId: string | undefined;
+  private _isReady = false;
+  private _claimStatus: AgentStatusResult['status'] | 'unknown' = 'unknown';
+
+  constructor(options: OasnTransportInitOptions) {
+    super();
+    this.id = options.accountId;
+    this._agentId = options.agentId;
+
+    // ── HTTP 层（含 401 撤销回调） ────────────────────────────────
+    const httpConfig = {
+      apiBase: options.apiBase,
+      defaultTimeoutMs: options.defaultTimeoutMs,
+      maxRetries: options.maxRetries,
+      onCredentialRevoked: () => this._onCredentialRevoked(),
+    };
+    this._http = new OasnHttpClient(httpConfig);
+    this._accessHttp = new OasnHttpClient({
+      ...httpConfig,
+      apiBase: options.accessApiBase || options.apiBase,
+    });
+
+    // ── 子模块（共享 HTTP 实例） ──────────────────────────────────
+    this._agentCard = new OasnAgentCard(this._http);
+    this._discovery = new OasnDiscovery(this._http);
+    this._register = new OasnRegister(this._http);
+    this._invocation = new OasnInvocation(this._accessHttp, options.pendingStore);
+    this._files = new OasnFiles(this._accessHttp);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // CoreTransport
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * 校验 api_key 有效性 + 进入可工作状态。
+   *
+   * 验证策略：
+   *   1. 设置 Bearer = credentials.token
+   *   2. 若 agentId 已知 → 调 GET /api/agent-cards/{agent_id}
+   *      - status 接口返回 claimed 才允许后续 Invocation
+   *      - 401 → onCredentialRevoked 回调，抛 TransportError
+   *
+   * 注：credentials.identity 在 OASN 场景下应等于 agent_id。
+   */
+  async ready(credentials: TransportCredentials): Promise<void> {
+    if (!credentials.token) {
+      throw makeTransportError('MISSING_CREDENTIAL', 'OASN ready: token (api_key) is required');
+    }
+    this._http.setToken(credentials.token);
+    this._accessHttp.setToken(credentials.token);
+
+    // 若构造时未传 agentId，则从 credentials.identity 读取
+    if (!this._agentId && credentials.identity) {
+      this._agentId = credentials.identity;
+    }
+
+    if (this._agentId) {
+      try {
+        const status = await this._register.getStatus(this._agentId);
+        this._claimStatus = status.status;
+        logger.info(
+          `[transport/oasn] ready agent_id=${this._agentId} `
+          + `claim_status=${status.status}`,
+        );
+      } catch (err) {
+        const te = err as TransportError;
+        // 401 已经在 HTTP 层触发了 onCredentialRevoked，再次显式抛
+        if (te.code === 'HTTP_401' || te.code === 'UNAUTHENTICATED') {
+          this._isReady = false;
+          throw te;
+        }
+        // 其他错误（网络/服务端 5xx 等）：不阻止 ready，但保持 unknown，sendTask 会阻断
+        logger.warn(`[transport/oasn] ready probe failed code=${te.code} msg=${te.message}, continuing anyway`);
+      }
+    } else {
+      logger.info('[transport/oasn] ready called without agent_id; skipping probe (register flow expected)');
+    }
+
+    this._isReady = true;
+  }
+
+  async dispose(): Promise<void> {
+    // OASN 无长连接 —— 清 token 即可
+    this._http.setToken(undefined);
+    this._accessHttp.setToken(undefined);
+    this._isReady = false;
+    logger.info(`[transport/oasn] disposed account=${this.id}`);
+  }
+
+  get isReady(): boolean {
+    return this._isReady;
+  }
+
+  // EventEmitter 已经实现 on/off，此处仅做类型对齐（接口签名要求）
+  override on(event: CoreTransportEvent, handler: (...args: any[]) => void): this {
+    return super.on(event, handler);
+  }
+
+  override off(event: CoreTransportEvent, handler: (...args: any[]) => void): this {
+    return super.off(event, handler);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // TaskTransport（T2 核心路径）
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * 发起远程 Agent 调用 → POST /api/invocations。
+   *
+   * §11.1：若 task.requestId 视作 toolCallId 传入，OasnInvocation 会去 pendingStore
+   * 查同名记录，命中则复用 idempotency_key，避免重复创建 Invocation。
+   */
+  async sendTask(targetAgentId: string, task: TaskRequest): Promise<TaskHandle> {
+    if (!this._isReady) {
+      throw makeTransportError('NOT_READY', 'OASN transport not ready; call ready() first');
+    }
+    if (this._claimStatus !== 'claimed') {
+      throw makeTransportError(
+        'REGISTRATION_NOT_ACTIVATED',
+        'OASN ClientAgent must be claimed before creating invocations',
+        { retryable: false },
+      );
+    }
+
+    // 把 task.requestId 映射为 toolCallId（若存在）
+    const opts: CreateInvocationOptions = {};
+    if (task.requestId) opts.toolCallId = task.requestId;
+    if (task.timeoutMs !== undefined) opts.timeoutMs = task.timeoutMs;
+
+    return this._invocation.sendTask(targetAgentId, task, opts);
+  }
+
+  /** 等待结果（轮询 / 未来可升级到 SSE） */
+  waitForTaskResult(
+    handle: TaskHandle,
+    options: { timeoutMs: number; signal?: AbortSignal; onProgress?: ProgressCallback },
+  ): Promise<TaskResult> {
+    return this._invocation.waitForTaskResult(handle, options);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // DiscoveryTransport
+  // ═══════════════════════════════════════════════════════════════
+
+  searchAgents(query: SearchQuery): Promise<SearchResult> {
+    return this._discovery.search(query);
+  }
+
+  getAgent(agentId: string): Promise<AgentCard | null> {
+    return this._agentCard.get(agentId);
+  }
+
+  getCategories(params?: { agentType?: string }): Promise<CategoryTree> {
+    return this._discovery.getCategories(params);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // RegistrationTransport（OASN-only）
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * 注册新 Agent。
+   *
+   * 注意：register 不要求 ready() —— 首次安装时还没有 api_key。
+   * 但 register 成功后，调用方需立即把 api_key 持久化 + 调 ready() 进入可工作状态。
+   */
+  async registerAgent(
+    platform: string,
+    params?: { installId?: string; deviceHint?: string },
+  ): Promise<RegisterResult> {
+    const result = await this._register.register(platform, params);
+    // 回填 agentId（后续 ready() 探活会用到）
+    this._agentId = result.agent_id;
+    return result;
+  }
+
+  async claimAgent(params: ClaimParams): Promise<ClaimResult> {
+    const result = await this._register.claim(params);
+    this._claimStatus = 'claim_pending';
+    return result;
+  }
+
+  async getAgentStatus(agentId: string): Promise<AgentStatusResult> {
+    const result = await this._register.getStatus(agentId);
+    this._claimStatus = result.status;
+    return result;
+  }
+
+  updateAgentCard(agentId: string, patch: AgentCardPatch): Promise<AgentCard> {
+    return this._agentCard.update(agentId, patch);
+  }
+
+  getCurrentOwner(): Promise<OwnerInfo | null> {
+    return this._agentCard.getCurrentOwner();
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // FileTransport（OASN-only）
+  // ═══════════════════════════════════════════════════════════════
+
+  uploadFile(file: UploadFileParams): Promise<UploadFileResult> {
+    // 默认走 LRU 路径，避免重复上传同一份内容
+    return this._files.ensureFileRef(file);
+  }
+
+  downloadArtifact(artifactId: string): Promise<DownloadArtifactResult> {
+    return this._files.downloadArtifact(artifactId);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // §11.5 401 撤销恢复路径
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * HTTP 层捕获 401 时调用：
+   *   1. 清掉本地 Bearer
+   *   2. 标记 not ready
+   *   3. 发 'credential_expired' 事件，AccountRuntime 接收后清凭证 + 引导 register
+   *
+   * 注意：不直接清 OpenClaw config —— config 持久层的清理由 AccountRuntime 决定。
+   */
+  private _onCredentialRevoked(): void {
+    if (!this._isReady) return; // 防止 ready 探活阶段重复触发
+    logger.error('[transport/oasn] api_key revoked (401 UNAUTHENTICATED) - emitting credential_expired');
+    this._http.setToken(undefined);
+    this._isReady = false;
+    this.emit('credential_expired', {
+      transportType: 'oasn',
+      accountId: this.id,
+    });
+  }
+}