openclaw-openagent 1.0.0

package/src/app/verbose-preflight.ts

@@ -0,0 +1,190 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/plugin-entry';
+import { logger } from '../util/logger.js';
+
+type AgentEvent = {
+  runId?: unknown;
+  stream?: unknown;
+  data?: unknown;
+  [key: string]: unknown;
+};
+
+type AgentRunContext = {
+  verboseLevel?: string;
+  [key: string]: unknown;
+};
+
+type AgentEventState = {
+  listeners?: Set<(evt: AgentEvent) => void>;
+  runContextById?: Map<string, AgentRunContext>;
+};
+
+const AGENT_EVENT_STATE_KEY = Symbol.for('openclaw.agentEvents.state');
+const REMOTE_TOOL_CALL_IDS = new Set<string>();
+const REMOTE_TOOL_CALL_IDS_BY_RUN = new Map<string, Set<string>>();
+const PROMOTED_RUNS = new Set<string>();
+
+let installed = false;
+let missingStateWarned = false;
+let missingRuntimeWarned = false;
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : {};
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function readToolName(data: Record<string, unknown>): string {
+  const call = asRecord(data.call);
+  return (
+    readString(data.name) ||
+    readString(data.toolName) ||
+    readString(data.tool_name) ||
+    readString(call.name)
+  ).toLowerCase();
+}
+
+function readToolCallId(data: Record<string, unknown>): string {
+  const call = asRecord(data.call);
+  return (
+    readString(data.toolCallId) ||
+    readString(data.tool_call_id) ||
+    readString(data.id) ||
+    readString(call.id)
+  );
+}
+
+function isOpenagentRemoteToolName(name: string): boolean {
+  return name.includes('call_remote_agent') || name.includes('openagent_delegate');
+}
+
+function rememberRemoteToolCall(runId: string, toolCallId: string): void {
+  REMOTE_TOOL_CALL_IDS.add(toolCallId);
+  let runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
+  if (!runToolCallIds) {
+    runToolCallIds = new Set<string>();
+    REMOTE_TOOL_CALL_IDS_BY_RUN.set(runId, runToolCallIds);
+  }
+  runToolCallIds.add(toolCallId);
+}
+
+function forgetRemoteToolCall(runId: string, toolCallId: string): void {
+  REMOTE_TOOL_CALL_IDS.delete(toolCallId);
+  const runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
+  if (!runToolCallIds) return;
+  runToolCallIds.delete(toolCallId);
+  if (runToolCallIds.size === 0) {
+    REMOTE_TOOL_CALL_IDS_BY_RUN.delete(runId);
+  }
+}
+
+function forgetRun(runId: string): void {
+  PROMOTED_RUNS.delete(runId);
+  const runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
+  if (!runToolCallIds) return;
+  for (const toolCallId of runToolCallIds) {
+    REMOTE_TOOL_CALL_IDS.delete(toolCallId);
+  }
+  REMOTE_TOOL_CALL_IDS_BY_RUN.delete(runId);
+}
+
+function getAgentEventState(): AgentEventState | null {
+  const state = (globalThis as Record<PropertyKey, unknown>)[AGENT_EVENT_STATE_KEY];
+  if (!state || typeof state !== 'object') return null;
+  return state as AgentEventState;
+}
+
+function promoteRunVerboseLevel(runId: string, toolCallId: string, toolName: string): void {
+  const state = getAgentEventState();
+  const runContextById = state?.runContextById;
+
+  if (!(runContextById instanceof Map)) {
+    if (!missingStateWarned) {
+      missingStateWarned = true;
+      logger.warn('[verbose-preflight] OpenClaw agent event state is unavailable; OpenAgent SSE payload may be stripped');
+    }
+    return;
+  }
+
+  let ctx = runContextById.get(runId);
+  if (!ctx) {
+    ctx = {};
+    runContextById.set(runId, ctx);
+  }
+
+  if (ctx.verboseLevel !== 'full') {
+    ctx.verboseLevel = 'full';
+  }
+
+  if (!PROMOTED_RUNS.has(runId)) {
+    PROMOTED_RUNS.add(runId);
+    logger.info(`[verbose-preflight] promoted run verboseLevel=full (runId=${runId}, toolCallId=${toolCallId || 'unknown'}, tool=${toolName || 'unknown'})`);
+  }
+}
+
+function handleAgentEvent(evt: AgentEvent): void {
+  const runId = readString(evt.runId);
+  if (!runId) return;
+
+  const data = asRecord(evt.data);
+
+  if (evt.stream === 'lifecycle') {
+    const phase = readString(data.phase);
+    if (phase === 'end' || phase === 'error') {
+      forgetRun(runId);
+    }
+    return;
+  }
+
+  if (evt.stream !== 'tool') return;
+  const toolName = readToolName(data);
+  const toolCallId = readToolCallId(data);
+
+  if (toolCallId && isOpenagentRemoteToolName(toolName)) {
+    rememberRemoteToolCall(runId, toolCallId);
+  }
+
+  const shouldKeepPayload =
+    isOpenagentRemoteToolName(toolName) ||
+    (toolCallId !== '' && REMOTE_TOOL_CALL_IDS.has(toolCallId));
+
+  if (!shouldKeepPayload) return;
+
+  promoteRunVerboseLevel(runId, toolCallId, toolName);
+
+  const phase = readString(data.phase);
+  if (toolCallId && (phase === 'result' || phase === 'error' || phase === 'end')) {
+    forgetRemoteToolCall(runId, toolCallId);
+  }
+}
+
+function prioritizePreflightListener(listener: (evt: AgentEvent) => void): void {
+  const listeners = getAgentEventState()?.listeners;
+  if (!(listeners instanceof Set) || !listeners.has(listener)) return;
+
+  const rest = Array.from(listeners).filter(item => item !== listener);
+  listeners.clear();
+  listeners.add(listener);
+  for (const item of rest) listeners.add(item);
+
+  logger.debug('[verbose-preflight] listener moved before gateway subscribers');
+}
+
+export function installOpenagentVerbosePreflight(api: OpenClawPluginApi): void {
+  if (installed) return;
+
+  const onAgentEvent = api.runtime?.events?.onAgentEvent;
+  if (typeof onAgentEvent !== 'function') {
+    if (!missingRuntimeWarned) {
+      missingRuntimeWarned = true;
+      logger.warn('[verbose-preflight] api.runtime.events.onAgentEvent is unavailable; OpenAgent SSE payload preflight disabled');
+    }
+    return;
+  }
+
+  onAgentEvent(handleAgentEvent);
+  prioritizePreflightListener(handleAgentEvent);
+  installed = true;
+  logger.info('[verbose-preflight] installed');
+}

package/src/auth/config.ts

@@ -0,0 +1,197 @@
+/**
+ * Auth — Configuration resolution
+ *
+ * Resolves OpenAgent account configuration from the OpenClaw config object.
+ * Supports two configuration layouts:
+ *   1. Nested: cfg.channels.openagent.accounts.{accountId}.*
+ *   2. Fallback (F1 compat): cfg.channels.openagent.agentId / .apiKey (top-level shorthand)
+ *
+ * See §0.1 of refactoring-plan.md.
+ */
+
+const DEFAULT_API_BASE = 'https://api.openagent.club';
+/**
+ * OASN 默认 API base。
+ *
+ * 未配置时故意使用不可达占位，避免把本地或生产请求误打到 REL 私有地址。
+ * 解析优先级：账号级 api_base > channel 级 api_base > 环境变量 > 该占位。
+ */
+export const DEFAULT_OASN_API_BASE = 'https://oasn.invalid/CONFIGURE_ME';
+
+export function isUnconfiguredOasnApiBase(value: string | undefined): boolean {
+  return !value || value === DEFAULT_OASN_API_BASE;
+}
+
+/**
+ * Transport 类型 —— v3.9+ 双轨抽象。
+ *
+ * 默认 'tim' 保留向后兼容（旧 openagent 配置无此字段，按 TIM 路径走）。
+ * 新 OASN 部署在配置中显式设置 transport='oasn'。
+ */
+export type TransportType = 'oasn' | 'tim';
+
+export interface OpenagentAccountConfig {
+  /** Resolved account ID */
+  accountId: string;
+  /** Display name */
+  name: string;
+  /** Whether the channel is enabled */
+  enabled: boolean;
+  /** Whether required credentials (agentId + apiKey) are present */
+  configured: boolean;
+  /** Agent identity on OpenAgent network */
+  agentId: string;
+  /** API key for auth verification */
+  apiKey: string;
+  /** API base URL */
+  apiBase: string;
+  /** Optional Access-layer API base URL for invocations/files when REL splits services */
+  accessApiBase: string;
+  /** Claim URL returned by OASN onboarding */
+  claimUrl: string;
+  /** Current onboarding claim status */
+  status: 'unregistered' | 'unclaimed' | 'claim_pending' | 'claimed' | 'credential_expired' | 'unknown';
+  /** Registration timestamp stored by the plugin */
+  registeredAt: string;
+  /**
+   * Transport 选型（v3.9+）。
+   *
+   *   - 'oasn': 直接走 OASN HTTP API（Bearer api_key）
+   *   - 'tim':  走腾讯云 IM（默认，向后兼容）
+   *
+   * 未在 config 中显式声明时默认 'tim'，确保旧版插件配置无需迁移即可工作。
+   */
+  transport: TransportType;
+  /** Raw merged config object */
+  config: Record<string, unknown>;
+}
+
+/**
+ * Extract the OpenAgent-specific config block from the full OpenClaw config.
+ * Handles multiple config key locations that have drifted across versions.
+ *
+ * v3.9+ 兼容：同时支持 `channels.oasn` / `entries.openclaw-oasn` / `entries.openclaw-plugin-oasn`，
+ * 与原有 openagent 键名并列查找。优先 oasn → openagent，便于过渡期同时挂双配置。
+ */
+export function getOpenagentConfig(cfg: Record<string, unknown>): Record<string, unknown> {
+  if (!cfg) return {};
+  const channels = cfg['channels'] as Record<string, unknown> | undefined;
+  const plugins = cfg['plugins'] as Record<string, unknown> | undefined;
+  const entries = plugins?.['entries'] as Record<string, unknown> | undefined;
+
+  return (channels?.['oasn'] as Record<string, unknown>)
+    || (channels?.['openagent'] as Record<string, unknown>)
+    || (entries?.['openclaw-oasn'] as Record<string, unknown>)?.['config'] as Record<string, unknown>
+    || (entries?.['openclaw-plugin-oasn'] as Record<string, unknown>)?.['config'] as Record<string, unknown>
+    || (entries?.['openclaw-openagent'] as Record<string, unknown>)?.['config'] as Record<string, unknown>
+    || (entries?.['openclaw-plugin-openagent'] as Record<string, unknown>)?.['config'] as Record<string, unknown>
+    || {};
+}
+
+/**
+ * Resolve a specific account's configuration from OpenClaw config.
+ *
+ * @param cfg - Full OpenClaw configuration object
+ * @param accountId - Target account ID, or 'default' to pick the first available
+ */
+export function resolveOpenagentAccount(
+  cfg: Record<string, unknown>,
+  accountId?: string,
+): OpenagentAccountConfig {
+  const clCfg = getOpenagentConfig(cfg);
+  const accounts = (clCfg['accounts'] || {}) as Record<string, Record<string, unknown>>;
+
+  // Resolve actual account ID
+  let actualAccountId = accountId || 'default';
+  const keys = Object.keys(accounts);
+  if (actualAccountId === 'default') {
+    actualAccountId = keys.length > 0 ? keys[0]! : 'default';
+  }
+
+  const targetAcc = accounts[actualAccountId] || {};
+
+  // F1 fallback: support top-level agentId/apiKey in the openagent config block
+  const agentId = (targetAcc['agentId'] || targetAcc['agent_id']
+    || clCfg['agentId']
+    || (actualAccountId !== 'default' ? actualAccountId : '')) as string;
+
+  const apiKey = (targetAcc['api_key'] || targetAcc['apiKey']
+    || clCfg['apiKey']
+    || '') as string;
+
+  // ── transport 字段（v3.9+ 双轨抽象） ──
+  // 解析顺序：账号级 > 顶层 > 默认 'oasn'
+  // 同时支持 snake_case 与 camelCase（与项目里其它配置字段一致）。
+  const transportRaw = (targetAcc['transport']
+    || clCfg['transport']
+    || 'oasn') as string;
+  const transport: TransportType = transportRaw === 'tim' ? 'tim' : 'oasn';
+
+  // OASN 路径优先使用 OASN 默认 base；TIM 路径维持原 openagent.club 默认
+  const fallbackApiBase = transport === 'oasn' ? DEFAULT_OASN_API_BASE : DEFAULT_API_BASE;
+  const envApiBase = transport === 'oasn'
+    ? (process.env.OASN_API_BASE || process.env.OPENAGENT_OASN_API_BASE || '')
+    : '';
+  const apiBase = (targetAcc['api_base'] || targetAcc['apiBase']
+    || clCfg['api_base']
+    || clCfg['apiBase']
+    || envApiBase
+    || fallbackApiBase) as string;
+  const envAccessApiBase = transport === 'oasn'
+    ? (process.env.OASN_ACCESS_API_BASE || process.env.OPENAGENT_OASN_ACCESS_API_BASE || '')
+    : '';
+  const accessApiBase = (targetAcc['access_api_base'] || targetAcc['accessApiBase']
+    || clCfg['access_api_base']
+    || clCfg['accessApiBase']
+    || envAccessApiBase
+    || apiBase) as string;
+  const claimUrl = (targetAcc['claim_url'] || targetAcc['claimUrl'] || clCfg['claim_url'] || clCfg['claimUrl'] || '') as string;
+  const rawStatus = (targetAcc['status'] || targetAcc['claim_status'] || targetAcc['claimStatus'] || clCfg['status'] || '') as string;
+  const normalizedStatus = normalizeClaimStatus(rawStatus, agentId, apiKey);
+  const registeredAt = (targetAcc['registered_at'] || targetAcc['registeredAt'] || '') as string;
+
+  return {
+    accountId: actualAccountId,
+    name: (clCfg['name'] || targetAcc['name'] || 'OpenAgent') as string,
+    enabled: clCfg['enabled'] !== false && targetAcc['enabled'] !== false,
+    configured: Boolean(agentId && apiKey),
+    agentId,
+    apiKey,
+    apiBase,
+    accessApiBase,
+    claimUrl,
+    status: normalizedStatus,
+    registeredAt,
+    transport,
+    config: { ...clCfg, ...targetAcc },
+  };
+}
+
+function normalizeClaimStatus(
+  raw: string,
+  agentId: string,
+  apiKey: string,
+): OpenagentAccountConfig['status'] {
+  switch (raw) {
+    case 'unregistered':
+    case 'unclaimed':
+    case 'claim_pending':
+    case 'claimed':
+    case 'credential_expired':
+    case 'unknown':
+      return raw;
+    case 'claim_email_sent':
+      return 'claim_pending';
+    default:
+      return agentId || apiKey ? 'unknown' : 'unregistered';
+  }
+}
+
+/**
+ * List available account IDs from the config.
+ */
+export function listAccountIds(cfg: Record<string, unknown>): string[] {
+  const clCfg = getOpenagentConfig(cfg);
+  const accounts = clCfg['accounts'] as Record<string, unknown> | undefined;
+  return accounts ? Object.keys(accounts) : [];
+}

package/src/auth/credential-manager.ts

@@ -0,0 +1,146 @@
+/**
+ * Auth -- Credential lifecycle manager
+ *
+ * ⚠️  TIM-only 路径（v3.9+ 双轨抽象）
+ * ---------------------------------------------------------
+ * 仅在 transport='tim' 下被 AccountRuntime 持有。OASN 路径下 api_key 直接
+ * 作为 Bearer 透传，无 UserSig 换取过程，AccountRuntime._connectOASN()
+ * 显式跳过 CredentialManager 的创建（见 account.ts §Phase 2）。
+ *
+ * 备注：类名保留为 CredentialManager（而非 TimCredentialManager），是因为
+ * 重命名会波及 channel.ts / errors / 文档等多处，价值有限；语义上"TIM-only"
+ * 由本模块的引用方收敛。
+ *
+ * Single source of truth for TIM credentials.
+ * Handles caching, expiry detection, refresh, and cooldown.
+ *
+ * Usage: AccountRuntime holds one instance per agent.
+ * Call getCredentials() whenever you need valid TIM credentials --
+ * it returns cached ones if still valid, or fetches fresh ones from backend.
+ *
+ * See docs/repair/002-auth-lifecycle-v3.0.5.md for full design.
+ */
+
+import { verifyAgent, type TIMCredentials } from './verify.js';
+import { logger } from '../util/logger.js';
+
+// ── Constants ──
+
+/** Cooldown after a failed attempt (unclaimed / network error) */
+const COOLDOWN_MS = 30_000;
+
+/** Refresh credentials 5 minutes before actual expiry */
+const EXPIRE_MARGIN_MS = 5 * 60 * 1000;
+
+// ── CredentialError ──
+
+export type CredentialErrorReason = 'unclaimed' | 'cooldown' | 'error';
+
+/**
+ * Thrown by getCredentials() when valid credentials cannot be obtained.
+ * Callers use `reason` to decide how to respond to the user.
+ */
+export class CredentialError extends Error {
+  constructor(
+    public readonly reason: CredentialErrorReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'CredentialError';
+  }
+}
+
+// ── CredentialManager ──
+
+export type CredentialStatus = 'idle' | 'unclaimed' | 'valid' | 'expired' | 'error';
+
+export class CredentialManager {
+  private _credentials: TIMCredentials | null = null;
+  private _expiresAt = 0;
+  private _cooldownUntil = 0;
+  private _status: CredentialStatus = 'idle';
+
+  constructor(
+    private readonly _agentId: string,
+    private readonly _apiKey: string,
+  ) {}
+
+  // ── Public API ──
+
+  /**
+   * Get valid TIM credentials.
+   *
+   * - Has cached + not expired -> return immediately (zero network cost)
+   * - In cooldown -> throw CredentialError('cooldown')
+   * - No cache or expired -> call verifyAgent() to fetch fresh credentials
+   *   - claimed=true -> cache + return
+   *   - claimed=false -> throw CredentialError('unclaimed')
+   *   - network error -> throw CredentialError('error')
+   */
+  async getCredentials(): Promise<TIMCredentials> {
+    // Fast path: valid cache
+    if (this._credentials && Date.now() < this._expiresAt) {
+      return this._credentials;
+    }
+
+    // Cooldown protection
+    const now = Date.now();
+    if (now < this._cooldownUntil) {
+      const remainSec = Math.ceil((this._cooldownUntil - now) / 1000);
+      throw new CredentialError('cooldown', `Credential refresh on cooldown (${remainSec}s remaining)`);
+    }
+
+    // Fetch from backend
+    try {
+      const result = await verifyAgent(this._agentId, this._apiKey);
+
+      if (!result) {
+        // unclaimed: verifyAgent returns null when agent is not claimed
+        this._status = 'unclaimed';
+        this._cooldownUntil = Date.now() + COOLDOWN_MS;
+        throw new CredentialError('unclaimed', `Agent ${this._agentId} is not claimed yet (bind email first)`);
+      }
+
+      // Success
+      this._credentials = result;
+      this._expiresAt = Date.now() + (result.expire * 1000) - EXPIRE_MARGIN_MS;
+      this._status = 'valid';
+      logger.info(
+        `[auth/credential] Credentials obtained for ${this._agentId}, ` +
+        `valid until ${new Date(this._expiresAt).toISOString()}`,
+      );
+
+      return this._credentials;
+    } catch (err) {
+      if (err instanceof CredentialError) throw err;
+      // Network / server error
+      this._status = 'error';
+      this._cooldownUntil = Date.now() + COOLDOWN_MS;
+      throw new CredentialError('error', `Credential fetch failed: ${(err as Error).message}`);
+    }
+  }
+
+  /** Current credential status (for logging/debugging) */
+  get status(): CredentialStatus {
+    return this._status;
+  }
+
+  /** Whether cached credentials are still valid */
+  get isValid(): boolean {
+    return this._status === 'valid' && this._credentials !== null && Date.now() < this._expiresAt;
+  }
+
+  /**
+   * Force-expire cached credentials.
+   *
+   * Call this when TIM SDK reports KICKED_OUT with type='userSigExpired'.
+   * Do NOT call for network disconnects -- old credentials are still valid.
+   * Next getCredentials() call will fetch fresh ones from backend.
+   */
+  invalidate(): void {
+    this._credentials = null;
+    this._expiresAt = 0;
+    this._status = 'expired';
+    logger.info(`[auth/credential] Credentials invalidated for ${this._agentId}`);
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Auth — Module barrel export
+ */
+
+export {
+  getOpenagentConfig,
+  resolveOpenagentAccount,
+  listAccountIds,
+  type OpenagentAccountConfig,
+} from './config.js';
+
+export {
+  verifyAgent,
+  type VerifyResult,
+  type TIMCredentials,
+} from './verify.js';
+
+export {
+  CredentialManager,
+  CredentialError,
+  type CredentialErrorReason,
+  type CredentialStatus,
+} from './credential-manager.js';
+

package/src/auth/verify.ts

@@ -0,0 +1,99 @@
+/**
+ * Auth — Agent verification against OpenAgent auth service
+ *
+ * ⚠️  TIM-only 路径（v3.9+ 双轨抽象）
+ * ---------------------------------------------------------
+ * 本模块用 apiKey 换取 TIM SDK 凭证（sdkAppId + userSig），仅在 transport='tim'
+ * 下被 CredentialManager 调用。OASN 路径不需要此流程 —— api_key 直接作为
+ * Bearer Token，由 OasnTransport 在 ready() 中通过 GET /api/agent-cards/{agent_id}
+ * 自校验。
+ *
+ * Verifies agent identity and retrieves TIM credentials (sdkAppId + userSig).
+ * See docs/API_Auth_Proxy.md for the auth service contract.
+ */
+
+import { httpPost } from '../util/http.js';
+import { logger } from '../util/logger.js';
+
+// OPENAGENT_AUTH_BASE env var allows overriding the auth endpoint for local dev.
+// Falls back to the OpenAgent API base if auth.ai-talk.live is not reachable.
+const AUTH_BASE =
+  process.env.OPENAGENT_AUTH_BASE ||
+  'https://auth.ai-talk.live';
+
+export interface VerifyResult {
+  /** Whether the agent credentials are valid */
+  valid: boolean;
+  /** Whether the agent has been claimed (bound to an email) */
+  claimed: boolean;
+  /** TIM SDK credentials (only present if valid && claimed) */
+  tim?: {
+    sdkAppId: number;
+    userSig: string;
+    /** UserSig validity in seconds (e.g. 604800 = 7 days) */
+    expire: number;
+  };
+}
+
+export interface TIMCredentials {
+  sdkAppId: number;
+  userSig: string;
+  userId: string;
+  /** UserSig validity in seconds (e.g. 604800 = 7 days) */
+  expire: number;
+}
+
+/**
+ * Verify agent identity and retrieve TIM credentials.
+ *
+ * @param agentId - Agent identifier on the OpenAgent network
+ * @param apiKey - API key for authentication
+ * @returns TIM credentials if agent is claimed, null if unclaimed
+ * @throws Error if credentials are invalid or server error
+ */
+export async function verifyAgent(
+  agentId: string,
+  apiKey: string,
+): Promise<TIMCredentials | null> {
+  // ── Dev mode: skip real auth and return mock TIM credentials ──
+  // Set OPENAGENT_SKIP_VERIFY=1 to bypass auth.ai-talk.live when offline.
+  if (process.env.OPENAGENT_SKIP_VERIFY === '1') {
+    logger.warn(`[auth] OPENAGENT_SKIP_VERIFY=1 — using mock TIM credentials for ${agentId}`);
+    return {
+      sdkAppId: 0,
+      userSig: 'dev-mock-usersig',
+      userId: agentId,
+      expire: 604800,
+    };
+  }
+
+  logger.info(`[auth] Verifying agent ${agentId} at ${AUTH_BASE}`);
+
+  const verifyData = await httpPost<VerifyResult>(
+    `${AUTH_BASE}/api/auth/verify`,
+    { agent_id: agentId, api_key: apiKey },
+  );
+
+  if (!verifyData.valid) {
+    throw new Error('Agent verification failed (Invalid credentials)');
+  }
+
+  if (!verifyData.claimed) {
+    logger.info(`[auth] Agent ${agentId} is not claimed yet`);
+    return null;
+  }
+
+  const tim = verifyData.tim;
+  if (!tim?.userSig || !tim?.sdkAppId) {
+    throw new Error('Missing TIM credentials in verification response');
+  }
+
+  logger.info(`[auth] Verification successful for ${agentId}`);
+
+  return {
+    sdkAppId: tim.sdkAppId,
+    userSig: tim.userSig,
+    userId: agentId,
+    expire: tim.expire ?? 604800,
+  };
+}