@controlflow-ai/daemon 0.1.1 → 0.1.3

package/src/delivery-ws.ts

@@ -0,0 +1,269 @@
+import type { Server, ServerWebSocket } from 'bun';
+import { MessageStore } from './db.js';
+import { failure, HttpError } from './http.js';
+import type { MessageDelivery } from './types.js';
+import type { DeliveryConnectionStats, DeliveryWebSocketSummary } from './messaging-status.js';
+
+export interface DeliveryWebSocketData {
+  kind: 'daemon-delivery';
+  computerId: string;
+  connectionId: string;
+}
+
+export type DeliveryWebSocketFrame =
+  | { type: 'hello'; computer_id: string; connection_id: string }
+  | { type: 'delivery'; delivery: Pick<MessageDelivery, 'id' | 'message_id' | 'chat_id' | 'agent' | 'status'> }
+  | { type: 'pending'; agent: string; pending?: number }
+  | { type: 'pong'; at: string };
+
+export interface DeliveryNotifyResult {
+  deliveries: number;
+  target_connections: number;
+  open_sockets: number;
+  websocket_frames: number;
+}
+
+export type { DeliveryConnectionStats, DeliveryWebSocketSummary } from './messaging-status.js';
+
+export interface DeliveryWebSocketHubOptions {
+  logger?: Partial<Pick<Console, 'log' | 'warn'>>;
+  staleConnectionTimeoutMs?: number | null;
+}
+
+interface DeliveryConnectionTelemetry {
+  computerId: string | null;
+  lastOpenAt: string | null;
+  lastCloseAt: string | null;
+  lastPingAt: string | null;
+  lastPongAt: string | null;
+  lastCloseCode: number | null;
+  lastCloseReason: string | null;
+}
+
+function connectionAuthFromRequest(request: Request): { computerId: string; connectionId: string; token: string } {
+  const url = new URL(request.url);
+  const computerId = request.headers.get('x-pal-computer-id')?.trim() || url.searchParams.get('computer_id')?.trim();
+  const connectionId = request.headers.get('x-pal-connection-id')?.trim() || url.searchParams.get('connection_id')?.trim();
+  const token = request.headers.get('x-pal-connection-token')?.trim() || url.searchParams.get('token')?.trim();
+  if (!computerId || !connectionId || !token) {
+    throw new HttpError(401, 'MISSING_CONNECTION_AUTH', 'computer connection auth is required');
+  }
+  return { computerId, connectionId, token };
+}
+
+function sendFrame(ws: ServerWebSocket<DeliveryWebSocketData>, frame: DeliveryWebSocketFrame): boolean {
+  try {
+    return ws.send(JSON.stringify(frame)) > 0;
+  } catch {
+    return false;
+  }
+}
+
+export class DeliveryWebSocketHub {
+  private readonly socketsByConnection = new Map<string, Set<ServerWebSocket<DeliveryWebSocketData>>>();
+  private readonly telemetryByConnection = new Map<string, DeliveryConnectionTelemetry>();
+  private readonly log: Pick<Console, 'log' | 'warn'>;
+  private readonly staleConnectionTimeoutMs: number | null;
+
+  constructor(private readonly store: MessageStore, options: DeliveryWebSocketHubOptions = {}) {
+    this.log = {
+      log: options.logger?.log ?? console.log,
+      warn: options.logger?.warn ?? console.warn,
+    };
+    this.staleConnectionTimeoutMs = typeof options.staleConnectionTimeoutMs === 'number' && Number.isFinite(options.staleConnectionTimeoutMs) && options.staleConnectionTimeoutMs >= 0
+      ? options.staleConnectionTimeoutMs
+      : null;
+  }
+
+  pruneStaleConnections(now = new Date()): number {
+    if (this.staleConnectionTimeoutMs === null) return 0;
+    const closed = this.store.closeStaleComputerConnections(this.staleConnectionTimeoutMs, now);
+    if (closed > 0) this.log.warn(`[delivery/ws] closed ${closed} stale computer connection(s)`);
+    return closed;
+  }
+
+  private telemetry(connectionId: string, computerId: string | null): DeliveryConnectionTelemetry {
+    let telemetry = this.telemetryByConnection.get(connectionId);
+    if (!telemetry) {
+      telemetry = {
+        computerId,
+        lastOpenAt: null,
+        lastCloseAt: null,
+        lastPingAt: null,
+        lastPongAt: null,
+        lastCloseCode: null,
+        lastCloseReason: null,
+      };
+      this.telemetryByConnection.set(connectionId, telemetry);
+    } else if (computerId) {
+      telemetry.computerId = computerId;
+    }
+    return telemetry;
+  }
+
+  handleUpgrade(request: Request, server: Server<DeliveryWebSocketData>): Response | null {
+    const url = new URL(request.url);
+    if (request.method !== 'GET' || url.pathname !== '/api/daemon/ws') return null;
+    try {
+      const auth = connectionAuthFromRequest(request);
+      const connection = this.store.assertActiveComputerConnection({
+        computerId: auth.computerId,
+        connectionId: auth.connectionId,
+        token: auth.token,
+      });
+      const upgraded = server.upgrade(request, {
+        data: {
+          kind: 'daemon-delivery',
+          computerId: connection.computer_id,
+          connectionId: connection.id,
+        },
+      });
+      return upgraded
+        ? new Response(null)
+        : new Response('websocket upgrade failed', { status: 400 });
+    } catch (error) {
+      return failure(error);
+    }
+  }
+
+  websocket = {
+    open: (ws: ServerWebSocket<DeliveryWebSocketData>) => {
+      const { connectionId, computerId } = ws.data;
+      let sockets = this.socketsByConnection.get(connectionId);
+      if (!sockets) {
+        sockets = new Set();
+        this.socketsByConnection.set(connectionId, sockets);
+      }
+      sockets.add(ws);
+      const telemetry = this.telemetry(connectionId, computerId);
+      telemetry.lastOpenAt = new Date().toISOString();
+      telemetry.lastCloseAt = null;
+      telemetry.lastCloseCode = null;
+      telemetry.lastCloseReason = null;
+      this.log.log(`[delivery/ws] open computer=${computerId} connection=${connectionId} sockets=${sockets.size}`);
+      sendFrame(ws, { type: 'hello', computer_id: computerId, connection_id: connectionId });
+      for (const { agent, pending } of this.store.listPendingDeliveryAgentsForConnection(connectionId)) {
+        sendFrame(ws, { type: 'pending', agent, pending });
+      }
+    },
+    message: (ws: ServerWebSocket<DeliveryWebSocketData>, data: string | Buffer) => {
+      if (String(data) === 'ping') {
+        const at = new Date().toISOString();
+        const telemetry = this.telemetry(ws.data.connectionId, ws.data.computerId);
+        telemetry.lastPingAt = at;
+        if (sendFrame(ws, { type: 'pong', at })) {
+          telemetry.lastPongAt = at;
+        }
+      }
+    },
+    close: (ws: ServerWebSocket<DeliveryWebSocketData>, code: number, reason: string) => {
+      const sockets = this.socketsByConnection.get(ws.data.connectionId);
+      if (sockets) {
+        sockets.delete(ws);
+        if (sockets.size === 0) this.socketsByConnection.delete(ws.data.connectionId);
+      }
+      const telemetry = this.telemetry(ws.data.connectionId, ws.data.computerId);
+      telemetry.lastCloseAt = new Date().toISOString();
+      telemetry.lastCloseCode = code;
+      telemetry.lastCloseReason = reason || null;
+      this.log.log(`[delivery/ws] close computer=${ws.data.computerId} connection=${ws.data.connectionId} code=${code} sockets=${sockets?.size ?? 0}`);
+    },
+  };
+
+  notifyDeliveries(deliveries: MessageDelivery[]): DeliveryNotifyResult {
+    this.pruneStaleConnections();
+    const targetConnections = new Set<string>();
+    const pendingAgentsByConnection = new Map<string, Set<string>>();
+    let pendingDeliveries = 0;
+    let openSockets = 0;
+    let websocketFrames = 0;
+    for (const delivery of deliveries) {
+      if (delivery.status !== 'pending') continue;
+      pendingDeliveries += 1;
+      for (const connectionId of this.store.listOnlineDaemonConnectionsForAgent(delivery.agent)) {
+        targetConnections.add(connectionId);
+        let pendingAgents = pendingAgentsByConnection.get(connectionId);
+        if (!pendingAgents) {
+          pendingAgents = new Set();
+          pendingAgentsByConnection.set(connectionId, pendingAgents);
+        }
+        pendingAgents.add(delivery.agent);
+      }
+    }
+
+    for (const [connectionId, agents] of pendingAgentsByConnection) {
+      const sockets = this.socketsByConnection.get(connectionId);
+      if (!sockets?.size) continue;
+      openSockets += sockets.size;
+      const pendingCounts = new Map(
+        this.store.listPendingDeliveryAgentsForConnection(connectionId).map((item) => [item.agent, item.pending]),
+      );
+      for (const agent of agents) {
+        for (const ws of sockets) {
+          if (sendFrame(ws, { type: 'pending', agent, pending: pendingCounts.get(agent) ?? 0 })) {
+            websocketFrames += 1;
+          }
+        }
+      }
+    }
+    return {
+      deliveries: pendingDeliveries,
+      target_connections: targetConnections.size,
+      open_sockets: openSockets,
+      websocket_frames: websocketFrames,
+    };
+  }
+
+  statsForConnection(connectionId: string): DeliveryConnectionStats {
+    const connection = this.store.getComputerConnection(connectionId);
+    const telemetry = this.telemetryByConnection.get(connectionId);
+    return {
+      connection_id: connectionId,
+      computer_id: connection?.computer_id ?? telemetry?.computerId ?? null,
+      open_sockets: this.socketsByConnection.get(connectionId)?.size ?? 0,
+      last_open_at: telemetry?.lastOpenAt ?? null,
+      last_close_at: telemetry?.lastCloseAt ?? null,
+      last_ping_at: telemetry?.lastPingAt ?? null,
+      last_pong_at: telemetry?.lastPongAt ?? null,
+      last_close_code: telemetry?.lastCloseCode ?? null,
+      last_close_reason: telemetry?.lastCloseReason ?? null,
+      pending_agents: this.store.listPendingDeliveryAgentsForConnection(connectionId),
+      backlog: this.store.listDeliveryBacklogForConnection(connectionId),
+    };
+  }
+
+  statsAllConnections(): DeliveryWebSocketSummary {
+    this.pruneStaleConnections();
+    const connections = this.store.listActiveComputerConnections()
+      .map((connection) => this.statsForConnection(connection.id));
+    return {
+      connections,
+      totals: connections.reduce((totals, connection) => {
+        totals.connections += 1;
+        totals.open_sockets += connection.open_sockets;
+        for (const item of connection.backlog) {
+          totals.pending_deliveries += item.pending;
+          totals.claimed_deliveries += item.claimed;
+          totals.processing_completed_deliveries += item.processing_completed;
+          totals.expired_active_deliveries += item.expired_active;
+        }
+        return totals;
+      }, {
+        connections: 0,
+        open_sockets: 0,
+        pending_deliveries: 0,
+        claimed_deliveries: 0,
+        processing_completed_deliveries: 0,
+        expired_active_deliveries: 0,
+      }),
+    };
+  }
+
+  close(): void {
+    for (const sockets of this.socketsByConnection.values()) {
+      for (const ws of sockets) ws.close(1001, 'server shutting down');
+    }
+    this.socketsByConnection.clear();
+  }
+
+}

package/src/format.ts

@@ -5,7 +5,10 @@ export function formatMessage(message: Message): string {
   const chatName = sanitizeProviderIds(message.chat_name);
   const target = message.parent_id === null ? `#${chatName}` : `#${chatName}:${message.parent_id}`;
   const to = message.recipient ? ` -> @${sanitizeProviderIds(message.recipient)}` : '';
-  return `[${message.id} ${target} ${message.created_at}] @${sanitizeProviderIds(message.sender)}${to}: ${sanitizeProviderIds(message.content)}`;
+  const mentions = message.mentions?.length
+    ? ` -> ${message.mentions.map((mention) => `@${sanitizeProviderIds(mention)}`).join(',')}`
+    : '';
+  return `[${message.id} ${target} ${message.created_at}] @${sanitizeProviderIds(message.sender)}${to || mentions}: ${sanitizeProviderIds(message.content)}`;
 }
 
 export function formatMessages(messages: Message[]): string {

package/src/lark/app-registration.ts

@@ -0,0 +1,141 @@
+export type LarkRegistrationTenantBrand = 'feishu' | 'lark';
+
+export interface LarkRegistrationBegin {
+  deviceCode: string;
+  url: string;
+  expiresIn: number;
+  interval: number;
+}
+
+export interface LarkRegistrationComplete {
+  appId: string;
+  appSecret: string;
+  tenantBrand: LarkRegistrationTenantBrand;
+  userOpenId?: string;
+}
+
+export type LarkRegistrationPollResult =
+  | { status: 'pending' }
+  | { status: 'slow_down'; interval: number }
+  | { status: 'complete'; registration: LarkRegistrationComplete }
+  | { status: 'denied' | 'expired' | 'error'; message: string };
+
+export type RegistrationFetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+const FEISHU_ACCOUNTS_ORIGIN = 'https://accounts.feishu.cn';
+const LARK_ACCOUNTS_ORIGIN = 'https://accounts.larksuite.com';
+const REGISTRATION_PATH = '/oauth/v1/app/registration';
+
+interface RegistrationBeginBody {
+  device_code?: unknown;
+  verification_uri_complete?: unknown;
+  expires_in?: unknown;
+  interval?: unknown;
+  error?: unknown;
+  error_description?: unknown;
+}
+
+interface RegistrationPollBody {
+  client_id?: unknown;
+  client_secret?: unknown;
+  user_info?: { tenant_brand?: unknown; open_id?: unknown };
+  error?: unknown;
+  error_description?: unknown;
+}
+
+function sanitizeMessage(message: unknown): string {
+  return String(message ?? 'unknown').replace(/[A-Za-z0-9_-]{30,}/g, '***');
+}
+
+async function postRegistration(origin: string, params: Record<string, string>, fetchImpl: RegistrationFetchLike): Promise<unknown> {
+  const response = await fetchImpl(`${origin}${REGISTRATION_PATH}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(params).toString(),
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok && !(body && typeof body === 'object' && 'error' in body)) {
+    throw new Error(`registration request failed: HTTP ${response.status}`);
+  }
+  return body;
+}
+
+export async function beginLarkAppRegistration(options: {
+  fetchImpl?: RegistrationFetchLike;
+  source?: string;
+} = {}): Promise<LarkRegistrationBegin> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const body = await postRegistration(FEISHU_ACCOUNTS_ORIGIN, {
+    action: 'begin',
+    archetype: 'PersonalAgent',
+    auth_method: 'client_secret',
+    request_user_info: 'open_id',
+  }, fetchImpl) as RegistrationBeginBody;
+
+  if (typeof body.error === 'string') {
+    throw new Error(sanitizeMessage(body.error_description ?? body.error));
+  }
+  if (typeof body.device_code !== 'string' || typeof body.verification_uri_complete !== 'string') {
+    throw new Error('registration begin response did not include device_code and verification_uri_complete');
+  }
+
+  const url = new URL(body.verification_uri_complete);
+  url.searchParams.set('from', 'sdk');
+  url.searchParams.set('source', `node-sdk/${options.source ?? 'pal'}`);
+  url.searchParams.set('tp', 'sdk');
+
+  return {
+    deviceCode: body.device_code,
+    url: url.toString(),
+    expiresIn: typeof body.expires_in === 'number' ? body.expires_in : 600,
+    interval: typeof body.interval === 'number' ? body.interval : 5,
+  };
+}
+
+export async function pollLarkAppRegistration(options: {
+  deviceCode: string;
+  fetchImpl?: RegistrationFetchLike;
+  origin?: 'feishu' | 'lark';
+}): Promise<LarkRegistrationPollResult> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const origin = options.origin === 'lark' ? LARK_ACCOUNTS_ORIGIN : FEISHU_ACCOUNTS_ORIGIN;
+  let body: RegistrationPollBody;
+  try {
+    body = await postRegistration(origin, {
+      action: 'poll',
+      device_code: options.deviceCode,
+    }, fetchImpl) as RegistrationPollBody;
+  } catch (error) {
+    return {
+      status: 'error',
+      message: error instanceof Error ? sanitizeMessage(error.message) : sanitizeMessage(error),
+    };
+  }
+
+  if (typeof body.client_id === 'string' && typeof body.client_secret === 'string') {
+    const tenantBrand: LarkRegistrationTenantBrand = body.user_info?.tenant_brand === 'lark' ? 'lark' : 'feishu';
+    const openId = typeof body.user_info?.open_id === 'string' && body.user_info.open_id.startsWith('ou_')
+      ? body.user_info.open_id
+      : undefined;
+    return {
+      status: 'complete',
+      registration: {
+        appId: body.client_id,
+        appSecret: body.client_secret,
+        tenantBrand,
+        userOpenId: openId,
+      },
+    };
+  }
+
+  if (body.user_info?.tenant_brand === 'lark' && options.origin !== 'lark') {
+    return pollLarkAppRegistration({ ...options, origin: 'lark' });
+  }
+
+  const error = typeof body.error === 'string' ? body.error : '';
+  if (error === 'authorization_pending' || !error) return { status: 'pending' };
+  if (error === 'slow_down') return { status: 'slow_down', interval: 10 };
+  if (error === 'access_denied') return { status: 'denied', message: 'user denied app registration' };
+  if (error === 'expired_token') return { status: 'expired', message: 'registration QR code expired' };
+  return { status: 'error', message: sanitizeMessage(body.error_description ?? error) };
+}

package/src/lark/cli.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { defaultDbPath, defaultServerUrl } from '../config.js';
+import { defaultDbPath } from '../config.js';
 import { MessageStore } from '../db.js';
 import {
   boundAgents,
@@ -11,12 +11,6 @@ import { countInboundEvents, listRecentInboundEvents } from './inbound-events.js
 import { extractMentionOpenIds, ingestLarkMessage, type LarkMessageEnvelope } from './event-router.js';
 import { ChatDispatcher, chatKeyOf, parseReceivePolicy, PeriodicQueue, shouldAcceptForAgent, type DispatchInput, type ReceivePolicy } from './dispatcher.js';
 import { parseRuntimeSpec } from './agent-runtime.js';
-import {
-  formatLarkSetupNextSteps,
-  persistLarkCredential,
-  resolveLarkBotInfo,
-  runInteractiveLarkSetup,
-} from './setup.js';
 import { createLarkApiClient, sendTextMessage, startLarkDaemon } from './ws-daemon.js';
 
 export interface LarkCliArgs {
@@ -44,69 +38,6 @@ function flagBool(flags: Record<string, unknown>, key: string): boolean {
   return flags[key] === true;
 }
 
-async function postJson(url: string, body: unknown): Promise<{ ok: boolean; status: number; text: string }> {
-  try {
-    const response = await fetch(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(body),
-    });
-    return { ok: response.ok, status: response.status, text: await response.text() };
-  } catch (error) {
-    return { ok: false, status: 0, text: error instanceof Error ? error.message : String(error) };
-  }
-}
-
-async function listAgentsForSetup(serverUrl: string): Promise<Array<{ agent_key: string; display_name: string; runtime?: string | null }>> {
-  const response = await fetch(`${serverUrl.replace(/\/$/, '')}/api/agents`);
-  const payload = await response.json() as { ok?: boolean; data?: { agents?: Array<{ agent_key?: unknown; display_name?: unknown; runtime?: unknown }> }; message?: string };
-  if (!response.ok || payload.ok === false) {
-    throw new Error(payload.message ?? `agent list failed: ${response.status}`);
-  }
-  return (payload.data?.agents ?? [])
-    .filter((agent) => typeof agent.agent_key === 'string' && typeof agent.display_name === 'string')
-    .map((agent) => ({
-      agent_key: String(agent.agent_key),
-      display_name: String(agent.display_name),
-      runtime: agent.runtime === null || typeof agent.runtime === 'string' ? agent.runtime : undefined,
-    }));
-}
-
-async function onboardAgentForLark(flags: Record<string, unknown>, log: NonNullable<RunOptions['log']>, agent: string | undefined): Promise<boolean> {
-  if (!flagBool(flags, 'create-agent')) return true;
-  if (!agent) {
-    (log.error ?? console.error)('lark setup --create-agent requires --agent');
-    return false;
-  }
-  const serverUrl = flagString(flags, 'server') ?? defaultServerUrl();
-  const displayName = flagString(flags, 'agent-name') ?? agent;
-  const runtime = flagString(flags, 'runtime') ?? 'codex';
-  const computerId = flagString(flags, 'computer-id');
-  const result = await postJson(`${serverUrl.replace(/\/$/, '')}/api/agents/onboard`, {
-    agent_key: agent,
-    display_name: displayName,
-    runtime,
-    computer_id: computerId,
-  });
-  if (!result.ok) {
-    (log.error ?? console.error)(`agent onboard failed (${result.status || 'network'}): ${result.text}`);
-    return false;
-  }
-  (log.log ?? console.log)(`[lark setup] agent onboarded: ${agent}`);
-  return true;
-}
-
-async function reloadLarkIntegration(flags: Record<string, unknown>, log: NonNullable<RunOptions['log']>): Promise<void> {
-  if (flagBool(flags, 'no-reload')) return;
-  const serverUrl = flagString(flags, 'server') ?? defaultServerUrl();
-  const result = await postJson(`${serverUrl.replace(/\/$/, '')}/api/lark/reload`, {});
-  if (result.ok) {
-    (log.log ?? console.log)('[lark setup] server lark integration reloaded');
-  } else {
-    (log.warn ?? console.warn)(`[lark setup] saved config, but server reload failed (${result.status || 'network'}): ${result.text}`);
-  }
-}
-
 export async function runLarkCli(options: RunOptions): Promise<number> {
   const { argv } = options;
   const log = options.log ?? {};
@@ -118,58 +49,8 @@ export async function runLarkCli(options: RunOptions): Promise<number> {
   }
 
   if (sub === 'setup') {
-    const appId = flagString(argv.flags, 'app-id');
-    const appSecret = flagString(argv.flags, 'app-secret');
-    const label = flagString(argv.flags, 'label');
-    const agent = flagString(argv.flags, 'agent');
-    const path = flagString(argv.flags, 'config') ?? defaultLarkConfigPath();
-    if ('agents' in argv.flags) {
-      (log.error ?? console.error)('lark setup no longer supports --agents; bind one bot to one agent with --agent');
-      return 2;
-    }
-    if (!appId && !appSecret) {
-      const result = await runInteractiveLarkSetup({
-        configPath: path,
-        log: {
-          log: log.log ?? console.log,
-          warn: log.warn ?? console.warn,
-          error: log.error ?? console.error,
-        },
-        ask: options.setupAsk,
-        listAgents: () => listAgentsForSetup(flagString(argv.flags, 'server') ?? defaultServerUrl()),
-      });
-      if (result) await reloadLarkIntegration(argv.flags, log);
-      return result ? 0 : 2;
-    }
-    if (!appId || !appSecret) {
-      (log.error ?? console.error)('lark setup requires --app-id and --app-secret');
-      return 2;
-    }
-    if (!(await onboardAgentForLark(argv.flags, log, agent))) return 2;
-    const botInfo = await resolveLarkBotInfo(appId, appSecret);
-    if (!botInfo.ok) {
-      (log.error ?? console.error)(`lark setup could not resolve bot open_id (${botInfo.error}): ${botInfo.message}`);
-      return 2;
-    }
-    const result = persistLarkCredential({
-      appId,
-      appSecret,
-      label,
-      agent,
-      botOpenId: botInfo.openId,
-      configPath: path,
-    });
-    if (result.replaced) {
-      (log.warn ?? console.warn)(`[lark setup] overwrote existing credential for appId=${appId} in ${path}`);
-    }
-    if (flagBool(argv.flags, 'next-steps')) {
-      (log.log ?? console.log)(formatLarkSetupNextSteps(result));
-      await reloadLarkIntegration(argv.flags, log);
-      return 0;
-    }
-    printJson(result, { log: log.log });
-    await reloadLarkIntegration(argv.flags, log);
-    return 0;
+    (log.error ?? console.error)('lark setup has been removed. Bind or rebind bots with "bun run console -- agents update --key <agent> --lark-app-id <id> --lark-app-secret <secret> [--rebind-lark]".');
+    return 2;
   }
 
   if (sub === 'list') {
@@ -223,17 +104,6 @@ function printLarkUsage(log: NonNullable<RunOptions['log']>): void {
   (log.log ?? console.log)(`pal lark <subcommand> [flags]
 
 Subcommands:
-  setup [--app-id <id> --app-secret <secret>] [--label <name>] [--agent <agent-key>] [--config <path>] [--next-steps]
-        [--create-agent --agent-name <name> --runtime codex --computer-id <machine>] [--server <url>] [--no-reload]
-      Persist a (appId, appSecret) credential pair to ~/.pal/lark.json (0600).
-      With no app-id/app-secret flags, starts an interactive setup wizard that
-      validates credentials before writing the config.
-      Overwrites if appId already present and logs a warning.
-      Setup resolves the bot open_id through Feishu's bot info API before
-      writing config. --agent binds this bot to a logical agent key. --create-agent creates or
-      updates that agent through the Pal server before writing lark.json.
-      By default setup asks the running server to reload Lark integration.
-
   list [--config <path>]
       List configured bots (secrets redacted).
 
@@ -281,7 +151,7 @@ async function runDaemon(argv: LarkCliArgs, log: NonNullable<RunOptions['log']>)
   }
   const store = loadLarkCredentials(configPath);
   if (store.bots.length === 0) {
-    (log.error ?? console.error)(`No bots configured in ${configPath}. Run pal lark setup first.`);
+    (log.error ?? console.error)(`No bots configured in ${configPath}. Bind a bot with "bun run console -- agents update --key <agent> --lark-app-id <id> --lark-app-secret <secret>" first.`);
     return 2;
   }
   let targets = store.bots;
@@ -325,17 +195,17 @@ async function runDaemon(argv: LarkCliArgs, log: NonNullable<RunOptions['log']>)
   let resolvedRuntime: string | null = null;
   if (agentSpec) {
     const directRuntime = agentSpec.split(':')[0];
-    if (directRuntime === 'neeko' || directRuntime === 'coco' || directRuntime === 'coco-stream-json' || directRuntime === 'codex') {
+    if (directRuntime === 'neeko' || directRuntime === 'coco' || directRuntime === 'codex') {
       resolvedRuntime = directRuntime;
     } else {
       resolvedRuntime = msgStore.getAgentRuntime(agentSpec);
       if (!resolvedRuntime) {
-        (log.warn ?? console.warn)(`[lark] agent ${agentSpec} has no runtime configured in DB; defaulting to neeko. Run "bun run src/cli.ts agents create --key ${agentSpec} --name <name> --runtime neeko|coco|coco-stream-json|codex" to configure.`);
+        (log.warn ?? console.warn)(`[lark] agent ${agentSpec} has no runtime configured in DB; defaulting to neeko. Run "bun run src/cli.ts agents create --key ${agentSpec} --name <name> --runtime neeko|coco|codex" to configure.`);
         resolvedRuntime = 'neeko';
       }
     }
   }
-  const isDeliveryAgent = resolvedRuntime === 'neeko' || resolvedRuntime === 'coco' || resolvedRuntime === 'coco-stream-json' || resolvedRuntime === 'codex';
+  const isDeliveryAgent = resolvedRuntime === 'neeko' || resolvedRuntime === 'coco' || resolvedRuntime === 'codex';
 
   const dispatchers = new Map<string, { dispatcher: ChatDispatcher; periodic: PeriodicQueue | null; chatIdToLarkChatId: Map<string, string> }>();
   if (agentSpec && !isDeliveryAgent) {

package/src/lark/credentials.ts

@@ -40,18 +40,51 @@ export function saveLarkCredentials(store: LarkCredentialStore, path: string = d
 export interface AddCredentialResult {
   store: LarkCredentialStore;
   replaced: boolean;
+  unbound: LarkCredential[];
 }
 
-export function upsertCredential(store: LarkCredentialStore, credential: LarkCredential): AddCredentialResult {
+export function findCredentialByAgent(store: LarkCredentialStore, agent: string): LarkCredential | undefined {
+  const key = agent.trim();
+  if (!key) return undefined;
+  return store.bots.find((bot) => bot.agent?.trim() === key);
+}
+
+export function unbindCredentialAgent(store: LarkCredentialStore, agent: string): { store: LarkCredentialStore; changed: boolean; unbound?: LarkCredential } {
+  const key = agent.trim();
+  if (!key) throw new Error('agent is required');
+  const index = store.bots.findIndex((bot) => bot.agent?.trim() === key);
+  if (index === -1) return { store: { bots: [...store.bots] }, changed: false };
+  const next: LarkCredentialStore = { bots: [...store.bots] };
+  const existing = next.bots[index]!;
+  const { agent: _agent, ...withoutAgent } = existing;
+  next.bots[index] = withoutAgent;
+  return { store: next, changed: true, unbound: existing };
+}
+
+export function upsertCredential(store: LarkCredentialStore, credential: LarkCredential, options: { rebind?: boolean } = {}): AddCredentialResult {
   validateCredential(credential);
   const existingIndex = store.bots.findIndex((bot) => bot.appId === credential.appId);
   const next: LarkCredentialStore = { bots: [...store.bots] };
+  const unbound: LarkCredential[] = [];
+  const agent = credential.agent?.trim();
+  if (agent) {
+    const existingAgentIndex = next.bots.findIndex((bot, index) => index !== existingIndex && bot.agent?.trim() === agent);
+    if (existingAgentIndex !== -1) {
+      const existing = next.bots[existingAgentIndex]!;
+      if (!options.rebind) {
+        throw new Error(`agent ${agent} is already bound to Lark app ${existing.appId}; pass --rebind-lark to move the binding`);
+      }
+      const { agent: _agent, ...withoutAgent } = existing;
+      next.bots[existingAgentIndex] = withoutAgent;
+      unbound.push(existing);
+    }
+  }
   if (existingIndex === -1) {
     next.bots.push(credential);
-    return { store: next, replaced: false };
+    return { store: next, replaced: false, unbound };
   }
   next.bots[existingIndex] = credential;
-  return { store: next, replaced: true };
+  return { store: next, replaced: true, unbound };
 }
 
 export function findCredential(store: LarkCredentialStore, appId: string): LarkCredential | undefined {