openclaw-openagent 1.0.0

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

@@ -0,0 +1,353 @@
+/**
+ * OASN API 请求/响应类型定义
+ *
+ * 设计依据：
+ *   - docs/specs/2026-06-16-oasn-api-module-mapping.md
+ *   - oasn-01-onboarding/apis.md（agent / claim / auth / agent-card / discovery）
+ *   - oasn-02-access-layer/apis.md（invocation / file / artifact）
+ *
+ * 这些类型仅在 OASN transport 内部使用，对外暴露的通用类型在 src/transport/types.ts。
+ * onboarding controller 的 Java record 当前使用 camelCase 请求/响应字段；
+ * transport 层兼容历史 snake_case 响应，并对外归一到 src/transport/types.ts 的稳定模型。
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// 通用错误响应
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * OASN 统一错误响应格式（所有 4xx/5xx 接口返回此结构）。
+ * 详见 api-module-mapping.md §五 通用错误处理。
+ */
+export interface OasnErrorBody {
+  error: {
+    /** 错误码：UNAUTHENTICATED / FORBIDDEN / TARGET_UNAVAILABLE / ... */
+    code: string;
+    /** 人类可读消息 */
+    message: string;
+    /** 客户端是否可重试（服务端裁决） */
+    retryable: boolean;
+    /** 附加上下文（端点定义具体字段） */
+    details?: Record<string, unknown>;
+    /** 排障追踪 id */
+    request_id?: string;
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Agent 注册 / 认领
+// ═══════════════════════════════════════════════════════════════
+
+export interface RegisterAgentRequest {
+  /** 当前固定为 "openclaw"（也可能是 "codex" / "claude_code" / "hermes"） */
+  platform: string;
+}
+
+export interface RegisterAgentResponse {
+  agentId?: string;
+  agent_id?: string;
+  agentType?: 'client';
+  agent_type?: 'client';
+  /** 一次性明文 api_key，仅此响应返回；服务端只存 hash */
+  apiKey?: string;
+  api_key?: string;
+  claimUrl?: string;
+  claim_url?: string;
+  status: 'unclaimed';
+  agentCard?: AgentCardResponse;
+  agent_card?: AgentCardResponse;
+}
+
+export interface AgentStatusResponse {
+  agentId?: string;
+  agent_id?: string;
+  status: 'unclaimed' | 'claim_pending' | 'claimed';
+  access_token?: string;
+  accessToken?: string;
+}
+
+export interface AgentCardResponse {
+  agentId?: string;
+  agent_id?: string;
+  agentType?: 'client' | 'service';
+  agent_type?: 'client' | 'service';
+  agentStatus?: string;
+  agent_status?: string;
+  claimStatus?: string;
+  claim_status?: string;
+    name: string;
+    description: string | null;
+    MOM: string | null;
+  tags: Array<{ tagId?: string; tag_id?: string; name: string }>;
+    category: string[];
+  avatarRef?: string | null;
+  avatar_ref?: string | null;
+  avatarUrl?: string | null;
+  avatar_url?: string | null;
+  visibility?: 'public' | 'private';
+  publicMetadata?: Record<string, unknown> | null;
+  public_metadata?: Record<string, unknown> | null;
+  updatedAt?: string;
+  updated_at?: string;
+}
+
+export interface ClaimAgentRequest {
+  agentId?: string;
+  claimToken?: string;
+  ownerEmail: string;
+}
+
+export interface ClaimAgentResponse {
+  agentId?: string;
+  agent_id?: string;
+  status: 'claim_email_sent';
+  ownerEmailMasked?: string;
+  owner_email_masked?: string;
+  expiresAt?: string;
+  expires_at?: string;
+}
+
+export interface UpdateAgentCardRequest {
+  name?: string | null;
+  description?: string | null;
+  MOM?: string | null;
+  tags?: string[] | null;
+  category?: string[] | null;
+  avatarRef?: string | null;
+  visibility?: 'public' | 'private';
+  publicMetadata?: Record<string, unknown> | null;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Discovery
+// ═══════════════════════════════════════════════════════════════
+
+export interface CategoryNodeResponse {
+  categoryId?: string;
+  category_id?: string;
+  name: string;
+  children?: CategoryNodeResponse[];
+}
+
+export interface CategoryTreeResponse {
+  categories: CategoryNodeResponse[];
+  updatedAt?: string;
+  updated_at?: string;
+}
+
+/** 三种搜索端点的请求结构 */
+export interface SearchByQueryRequest {
+  query: string;
+  agentTypes?: string[];
+  sort?: string[];
+  pageSize?: number;
+  pageNum?: number;
+}
+
+export interface SearchByCategoryRequest {
+  category: string[];
+  agentTypes?: string[];
+  sort?: string[];
+  pageSize?: number;
+  pageNum?: number;
+}
+
+export interface SearchByTagsRequest {
+  tags: string[];
+  agentTypes?: string[];
+  sort?: string[];
+  pageSize?: number;
+  pageNum?: number;
+}
+
+export interface SearchResponse {
+  searchId?: string;
+  search_id?: string;
+  agentCards?: AgentCardResponse[];
+  agent_cards?: AgentCardResponse[];
+  pageNum?: number;
+  page_num?: number;
+  pageSize?: number;
+  page_size?: number;
+  hasNext?: boolean;
+  has_next?: boolean;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Invocation（核心路径 ⭐）
+// ═══════════════════════════════════════════════════════════════
+
+export interface CreateInvocationRequest {
+  /** 客户端生成的幂等 key（详见 §11.1） */
+  idempotency_key: string;
+  service_agent_id: string;
+  /** 显式输入意图，至少包含 task 字段 */
+  input: { task: string } & Record<string, unknown>;
+  session_id?: string;
+  input_file_refs?: string[];
+  input_artifact_refs?: string[];
+  /** 期望超时（服务端裁决最终 effective_timeout_ms） */
+  timeout_ms?: number;
+  /** 客户端分组标识（可选） */
+  client_request_group_id?: string;
+}
+
+export interface CreateInvocationResponse {
+  invocationId?: string;
+  invocation_id?: string;
+  sessionId?: string;
+  session_id?: string;
+  status: 'accepted' | 'queued';
+  serviceAgentId?: string;
+  service_agent_id?: string;
+  effectiveTimeoutMs?: number;
+  effective_timeout_ms?: number;
+  nextPollAfterMs?: number;
+  next_poll_after_ms?: number;
+  /** 是否幂等重放（同一 idempotency_key 多次请求返回 true） */
+  idempotentReplay?: boolean;
+  idempotent_replay?: boolean;
+  createdAt?: string;
+  created_at?: string;
+}
+
+/** Invocation 状态枚举 */
+export type InvocationStatus =
+  | 'accepted'
+  | 'queued'
+  | 'running'
+  | 'succeeded'
+  | 'failed'
+  | 'timed_out'
+  | 'cancelled';
+
+/** 是否进入终态（停止轮询） */
+export function isInvocationTerminal(status: InvocationStatus): boolean {
+  return status === 'succeeded'
+    || status === 'failed'
+    || status === 'timed_out'
+    || status === 'cancelled';
+}
+
+export interface InvocationProgress {
+  lifecycleState?: string;
+  lifecycle_state?: string;
+  activityCategory?: string;
+  activity_category?: string;
+  progressPercent?: number;
+  progress_percent?: number;
+  elapsedMs?: number;
+  elapsed_ms?: number;
+  /** 可对外展示的安全状态描述（已脱敏） */
+  safeStatusMessage?: string;
+  safe_status_message?: string;
+}
+
+export interface ArtifactResponse {
+  artifactId?: string;
+  artifact_id?: string;
+  displayName?: string;
+  display_name?: string;
+  mimeType?: string;
+  mime_type?: string;
+  sizeBytes?: number;
+  size_bytes?: number;
+  contentAvailable?: boolean;
+  content_available?: boolean;
+  contentUrl?: string;
+  content_url?: string;
+}
+
+export interface GetInvocationResponse {
+  invocationId?: string;
+  invocation_id?: string;
+  sessionId?: string;
+  session_id?: string;
+  status: InvocationStatus;
+  progress?: InvocationProgress;
+  inlineResult?: {
+    summary: string;
+    [key: string]: unknown;
+  };
+  inline_result?: {
+    summary: string;
+    [key: string]: unknown;
+  };
+  artifacts?: ArtifactResponse[];
+  /** 终态时为 null */
+  nextPollAfterMs?: number | null;
+  next_poll_after_ms?: number | null;
+  warnings?: string[];
+  userError?: { code: string; message: string };
+  user_error?: { code: string; message: string };
+  createdAt?: string;
+  created_at?: string;
+  updatedAt?: string;
+  updated_at?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// File / Artifact
+// ═══════════════════════════════════════════════════════════════
+
+export interface UploadFileResponse {
+  file_ref: string;
+  display_name: string;
+  mime_type: string;
+  size_bytes: number;
+  /** ISO 8601 字符串 */
+  expires_at: string;
+  created_at: string;
+}
+
+// Artifact 下载返回二进制，没有 JSON 结构 —— 详见 oasn-files.ts
+
+// ═══════════════════════════════════════════════════════════════
+// Owner
+// ═══════════════════════════════════════════════════════════════
+
+export interface OwnerInfoResponse {
+  ownerId?: string;
+  owner_id?: string;
+  ownerType?: string;
+  owner_type?: string;
+  displayName?: string;
+  display_name?: string;
+  emailMasked?: string;
+  email_masked?: string;
+  emailVerifiedAt?: string;
+  email_verified_at?: string;
+  status: string;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 端点常量
+// ═══════════════════════════════════════════════════════════════
+
+/** OASN HTTP 端点路径（相对于 api_base） */
+export const OASN_ENDPOINTS = {
+  // Agent
+  REGISTER: '/api/agents/register',
+  CLAIM: '/api/agents/claim',
+  AGENT_STATUS: (agentId: string) => `/api/agents/${encodeURIComponent(agentId)}`,
+
+  // AgentCard
+  AGENT_CARD: (agentId: string) => `/api/agent-cards/${encodeURIComponent(agentId)}`,
+
+  // Discovery
+  CATEGORIES: '/api/agent-card-categories',
+  SEARCH_BY_QUERY: '/api/agent-cards/search/by-query',
+  SEARCH_BY_CATEGORY: '/api/agent-cards/search/by-category',
+  SEARCH_BY_TAGS: '/api/agent-cards/search/by-tags',
+
+  // Invocation
+  INVOCATIONS: '/api/invocations',
+  INVOCATION: (id: string) => `/api/invocations/${encodeURIComponent(id)}`,
+
+  // File / Artifact
+  FILES: '/api/files',
+  ARTIFACT_CONTENT: (id: string) => `/api/artifacts/${encodeURIComponent(id)}/content`,
+
+  // Owner
+  USERS_ME: '/api/users/me',
+} as const;

package/src/transport/tim/index.ts

@@ -0,0 +1,8 @@
+/**
+ * TimTransport 模块导出
+ *
+ * 设计依据：docs/specs/2026-06-16-oasn-transport-abstraction-design.md §3.1
+ */
+
+export { TimTransportImpl } from './tim-transport.js';
+export type { TimTransportInitOptions } from './tim-transport.js';