@lightcone-ai/daemon 0.14.18 → 0.15.0

package/src/agent-manager.js

@@ -18,10 +18,14 @@ import { startSession, stopSession, stopAllSessions } from './browser-login.js';
 import { markInvalidatedLeases } from './governance-state.js';
 import { resolveExitOfflineDetail, resolveLifecycleExitState } from './lifecycle-protocol.js';
 import { runPublishJob } from './publish-job-runner.js';
+import { resolveOutboundRateLimitConfig } from './runtime-config.js';
+import { probeChatBridgeCapability } from './capability-probe.js';
 
 const KIMI_SYSTEM_PROMPT_FILE = '.lightcone-kimi-system.md';
 const KIMI_AGENT_FILE = '.lightcone-kimi-agent.yaml';
 const KIMI_MCP_FILE = '.lightcone-kimi-mcp.json';
+const CHAT_CAPABILITY_ID = 'chat';
+const CAPABILITY_PROBE_TIMEOUT_MS = 8000;
 const LOCAL_FILE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const LOCAL_MCP_ROOTS = Object.freeze([
   path.resolve(LOCAL_FILE_DIR, '../mcp-servers'),
@@ -129,6 +133,10 @@ function replacePlaceholders(text, replacements) {
   return next;
 }
 
+function previewText(value, max = 500) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
 export class AgentManager {
   constructor({ serverUrl, machineApiKey }) {
     this.serverUrl = serverUrl;
@@ -138,6 +146,10 @@ export class AgentManager {
     // key → true (spawn in progress)
     this.starting = new Set();
     this.directiveRefreshTimers = new Map();
+    this.outboundRateLimit = resolveOutboundRateLimitConfig();
+    this.outboundHistory = new Map();
+    this.outboundCooldownUntil = new Map();
+    this.inboxPauseUntil = new Map();
   }
 
   _key(agentId, workspaceId) {
@@ -189,6 +201,111 @@ export class AgentManager {
     return dir;
   }
 
+  _nowMs() {
+    return Date.now();
+  }
+
+  _trimOutboundHistory(key, nowMs = this._nowMs()) {
+    const history = this.outboundHistory.get(key) ?? [];
+    const cutoff = nowMs - this.outboundRateLimit.windowMs;
+    const trimmed = history.filter(ts => Number.isFinite(ts) && ts > cutoff);
+    if (trimmed.length > 0) this.outboundHistory.set(key, trimmed);
+    else this.outboundHistory.delete(key);
+    return trimmed;
+  }
+
+  _getRemainingCooldownMs(key, nowMs = this._nowMs()) {
+    const cooldownUntil = Number(this.outboundCooldownUntil.get(key) ?? 0);
+    if (!Number.isFinite(cooldownUntil) || cooldownUntil <= nowMs) {
+      this.outboundCooldownUntil.delete(key);
+      this.inboxPauseUntil.delete(key);
+      return 0;
+    }
+    return cooldownUntil - nowMs;
+  }
+
+  _isInboundFlushPaused(key, nowMs = this._nowMs()) {
+    const pauseUntil = Number(this.inboxPauseUntil.get(key) ?? 0);
+    if (!Number.isFinite(pauseUntil) || pauseUntil <= nowMs) {
+      this.inboxPauseUntil.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  _emitOutboundRateLimitEvent(connection, {
+    agentId,
+    workspaceId,
+    historyCount,
+    nowMs,
+    cooldownUntilMs,
+  }) {
+    connection.send({
+      type: 'agent:governance_event',
+      agentId,
+      workspaceId,
+      eventType: 'agent_outbound_rate_limit_triggered',
+      reason: 'hard_cap',
+      payload: {
+        count: historyCount,
+        window_ms: this.outboundRateLimit.windowMs,
+        soft_cap: this.outboundRateLimit.softCap,
+        hard_cap: this.outboundRateLimit.hardCap,
+        cooldown_ms: this.outboundRateLimit.cooldownMs,
+        triggered_at: new Date(nowMs).toISOString(),
+        cooldown_until: new Date(cooldownUntilMs).toISOString(),
+      },
+    });
+  }
+
+  _recordSuccessfulOutboundMessage({
+    key,
+    agent,
+    agentId,
+    workspaceId,
+    connection,
+    nowMs = this._nowMs(),
+  }) {
+    const history = this._trimOutboundHistory(key, nowMs);
+    history.push(nowMs);
+    this.outboundHistory.set(key, history);
+
+    if (history.length > this.outboundRateLimit.softCap) {
+      console.warn(
+        `[WARN] [AgentManager] outbound rate high agent=${agent?.config?.displayName ?? agentId.slice(0, 8)} `
+        + `workspace=${workspaceId ?? 'none'} count_60s=${history.length}`
+      );
+    }
+    if (history.length <= this.outboundRateLimit.hardCap) {
+      return;
+    }
+
+    const cooldownUntilMs = nowMs + this.outboundRateLimit.cooldownMs;
+    this.outboundCooldownUntil.set(key, cooldownUntilMs);
+    this.inboxPauseUntil.set(key, cooldownUntilMs);
+
+    console.warn(
+      `[WARN] [AgentManager] outbound hard cap triggered agent=${agent?.config?.displayName ?? agentId.slice(0, 8)} `
+      + `workspace=${workspaceId ?? 'none'} count_60s=${history.length} cooldown_until=${new Date(cooldownUntilMs).toISOString()}`
+    );
+    this._emitOutboundRateLimitEvent(connection, {
+      agentId,
+      workspaceId,
+      historyCount: history.length,
+      nowMs,
+      cooldownUntilMs,
+    });
+
+    if (agent?.proc) {
+      agent.stopCause = 'outbound_rate_limited';
+      try {
+        agent.proc.kill();
+      } catch (err) {
+        console.warn(`[AgentManager] Failed to stop rate-limited agent ${agentId}: ${err.message}`);
+      }
+    }
+  }
+
   _materializeSkills(workspaceDir, skills) {
     const skillsDir = path.join(workspaceDir, '.skills');
     mkdirSync(skillsDir, { recursive: true });
@@ -206,8 +323,64 @@ export class AgentManager {
     }
   }
 
+  _normalizeDeliverySenderType(senderType) {
+    const normalized = String(senderType ?? '').trim().toLowerCase();
+    if (normalized === 'user') return 'user';
+    if (normalized === 'agent') return 'peer-agent';
+    return 'system';
+  }
+
+  _formatDeliveryHeaderValue(value) {
+    const normalized = String(value ?? '').trim();
+    if (!normalized) return 'unknown';
+    if (/^[A-Za-z0-9_:@#./-]+$/.test(normalized)) return normalized;
+    return JSON.stringify(normalized);
+  }
+
+  _formatDeliveryTarget(message) {
+    const workspaceType = String(message?.workspace_type ?? '').trim().toLowerCase();
+    const workspaceName = String(message?.workspace_name ?? '').trim();
+    const parentWorkspaceName = String(message?.parent_workspace_name ?? '').trim();
+    const parentWorkspaceType = String(message?.parent_workspace_type ?? '').trim().toLowerCase();
+
+    if (workspaceType === 'dm' || workspaceType === 'lightcone_dm') {
+      return `dm:@${workspaceName || 'unknown'}`;
+    }
+    if (workspaceType === 'thread') {
+      if (parentWorkspaceType === 'dm' || parentWorkspaceType === 'lightcone_dm') {
+        return `dm:@${parentWorkspaceName || workspaceName || 'unknown'}`;
+      }
+      return `#${parentWorkspaceName || workspaceName || 'unknown'}`;
+    }
+    return `#${workspaceName || 'all'}`;
+  }
+
   _formatDeliveryText(message) {
-    return `New message in ${message.workspace_type === 'dm' ? 'dm from' : `#${message.workspace_name} from`} ${message.sender_name}: ${message.content}`;
+    const fromType = this._normalizeDeliverySenderType(message?.sender_type);
+    const senderName = String(message?.sender_name ?? '').trim();
+    const target = this._formatDeliveryTarget(message);
+    const messageIdShort = String(message?.message_id ?? '').trim().slice(0, 8);
+    const time = String(message?.timestamp ?? '').trim();
+    const content = String(message?.content ?? '').trim();
+
+    const fields = [`from=${fromType}`];
+    if (fromType === 'user') {
+      fields.push(`user=${this._formatDeliveryHeaderValue(senderName || 'unknown')}`);
+    } else if (fromType === 'peer-agent') {
+      fields.push(`agent=${this._formatDeliveryHeaderValue(senderName || 'unknown')}`);
+    } else {
+      const reason = String(message?.reason ?? message?.type ?? 'delivery').trim() || 'delivery';
+      fields.push(`reason=${this._formatDeliveryHeaderValue(reason)}`);
+    }
+    fields.push(`target=${this._formatDeliveryHeaderValue(target)}`);
+    if (messageIdShort) fields.push(`msg=${this._formatDeliveryHeaderValue(messageIdShort)}`);
+    if (time) fields.push(`time=${this._formatDeliveryHeaderValue(time)}`);
+
+    if (fromType === 'system') {
+      return `[${fields.join(' ')}] ${content}`;
+    }
+    const speaker = senderName ? `@${senderName}` : '@unknown';
+    return `[${fields.join(' ')}] ${speaker}: ${content}`;
   }
 
   _emitLifecycle(connection, {
@@ -235,6 +408,35 @@ export class AgentManager {
     });
   }
 
+  _emitCapabilityProbe(connection, {
+    agentId,
+    workspaceId,
+    capabilityId = CHAT_CAPABILITY_ID,
+    state = 'unknown',
+    reason = null,
+    runtime = null,
+    details = null,
+    latencyMs = null,
+    probedAt = new Date().toISOString(),
+  }) {
+    const normalizedCapabilityId = String(capabilityId ?? '').trim().toLowerCase() || CHAT_CAPABILITY_ID;
+    const normalizedState = String(state ?? '').trim().toLowerCase() || 'unknown';
+    const normalizedReason = String(reason ?? '').trim() || null;
+    const normalizedRuntime = String(runtime ?? '').trim().toLowerCase() || null;
+    connection.send({
+      type: 'agent:capability_probe',
+      agentId,
+      workspaceId,
+      capabilityId: normalizedCapabilityId,
+      state: normalizedState,
+      reason: normalizedReason,
+      runtime: normalizedRuntime,
+      details: details && typeof details === 'object' ? details : null,
+      latencyMs: Number.isFinite(Number(latencyMs)) ? Number(latencyMs) : null,
+      probedAt,
+    });
+  }
+
   _takePendingMessage(key) {
     if (!this._pendingMessages) return null;
     const pending = this._pendingMessages.get(key);
@@ -320,10 +522,14 @@ export class AgentManager {
   _buildCodexMcpArgs(mcpServers) {
     const args = [];
     for (const [serverKey, server] of Object.entries(mcpServers)) {
+      const normalizedKey = String(serverKey ?? '').trim();
+      if (!normalizedKey) continue;
+      const keyExpr = /^[A-Za-z0-9_-]+$/.test(normalizedKey)
+        ? normalizedKey
+        : JSON.stringify(normalizedKey);
       const serverArgs = Array.isArray(server.args) ? server.args.map((item) => String(item)) : [];
       const envVars = normalizeObject(server.env);
       const envPairs = Object.entries(envVars).map(([k, v]) => `${k}=${String(v ?? '')}`);
-      const keyExpr = JSON.stringify(serverKey);
       const commandExpr = JSON.stringify(envPairs.length > 0 ? 'env' : server.command);
       const argsExpr = JSON.stringify(envPairs.length > 0 ? [...envPairs, server.command, ...serverArgs] : serverArgs);
       args.push(
@@ -373,7 +579,6 @@ export class AgentManager {
     const codexPrompt = startupMsg
       ? `${codexBasePrompt}\n\nNew message received:\n\n${this._formatDeliveryText(startupMsg.message)}\n\nRespond as appropriate. Complete all required work before stopping.`
       : codexBasePrompt;
-
     const authToken = config?.authToken || this.machineApiKey;
     const userId = config?.userId ?? 'default';
     const profileRoot = path.join(homedir(), '.lightcone', 'chrome-profiles');
@@ -390,6 +595,17 @@ export class AgentManager {
     };
     const mcpServers = this._resolveDirectiveMcpServers(directive, baseReplacements);
 
+    if (runtime === 'codex') {
+      const mcpKeys = Object.keys(mcpServers);
+      console.log(
+        `[AgentManager][codex][spawn] agent=${config?.displayName ?? agentId} workspace=${workspaceId ?? 'none'} `
+        + `startup_seq=${startupMsg?.seq ?? 'none'} prompt_len=${codexPrompt.length} `
+        + `session=${config?.sessionId ?? 'none'} `
+        + `mcp=${mcpKeys.join(',') || 'none'} `
+        + `startup_preview="${previewText(startupMsg?.message?.content ?? '')}"`
+      );
+    }
+
     let kimiFiles = null;
     if (runtime === 'kimi') {
       kimiFiles = this._createKimiConfigFiles(workspaceDir, {
@@ -596,6 +812,28 @@ export class AgentManager {
       console.log(`[AgentManager] Agent ${config?.displayName ?? agentId} in workspace ${workspaceName ?? workspaceId} already registered`);
       return;
     }
+    const remainingCooldownMs = this._getRemainingCooldownMs(key);
+    if (remainingCooldownMs > 0) {
+      const remainingSeconds = Math.ceil(remainingCooldownMs / 1000);
+      const reason = `outbound_rate_limited_cooldown:${remainingSeconds}s`;
+      console.warn(
+        `[WARN] [AgentManager] Rejecting start for rate-limited agent=${config?.displayName ?? agentId} `
+        + `workspace=${workspaceName ?? workspaceId ?? 'none'} cooldown_remaining_s=${remainingSeconds}`
+      );
+      this._emitLifecycle(connection, {
+        agentId,
+        workspaceId,
+        runtime: config?.runtime ?? 'claude',
+        reachability: 'reachable',
+        availability: 'paused',
+        runtimeState: 'stopped',
+        reason,
+        sessionId: config?.sessionId ?? null,
+      });
+      connection.send({ type: 'agent:status', agentId, workspaceId, status: 'inactive' });
+      connection.send({ type: 'agent:activity', agentId, workspaceId, activity: 'offline', detail: reason, entries: [] });
+      return;
+    }
     this.starting.add(key);
 
     const requestedRuntime = String(config.runtime ?? 'claude').trim().toLowerCase() || 'claude';
@@ -607,6 +845,15 @@ export class AgentManager {
       rollbackStartupMessage?.(reason ?? 'spawn_failed');
       this._clearDirectiveRefresh(key);
       this.starting.delete(key);
+      this._emitCapabilityProbe(connection, {
+        agentId,
+        workspaceId,
+        capabilityId: CHAT_CAPABILITY_ID,
+        state: 'unready',
+        reason: reason ?? 'spawn_failed',
+        runtime: runtimeHint,
+        details: { stage: 'fail_start' },
+      });
       this._emitLifecycle(connection, {
         agentId,
         workspaceId,
@@ -773,6 +1020,40 @@ export class AgentManager {
       return;
     }
 
+    this._emitCapabilityProbe(connection, {
+      agentId,
+      workspaceId,
+      capabilityId: CHAT_CAPABILITY_ID,
+      state: 'unknown',
+      reason: 'probe_pending',
+      runtime,
+      details: { stage: 'spawn_preflight' },
+    });
+
+    const capabilityProbe = await probeChatBridgeCapability({
+      chatBridgePath,
+      cwd: workspaceDir,
+      timeoutMs: CAPABILITY_PROBE_TIMEOUT_MS,
+      env: {
+        ...spawnPlan.env,
+        SERVER_URL: spawnPlan.env?.SERVER_URL ?? this.serverUrl,
+        MACHINE_API_KEY: spawnPlan.env?.MACHINE_API_KEY ?? runtimeConfig.authToken ?? this.machineApiKey,
+        AGENT_ID: spawnPlan.env?.AGENT_ID ?? agentId,
+        WORKSPACE_ID: spawnPlan.env?.WORKSPACE_ID ?? (workspaceId ?? ''),
+        WORKSPACE_DIR: spawnPlan.env?.WORKSPACE_DIR ?? workspaceDir,
+      },
+    });
+    this._emitCapabilityProbe(connection, {
+      agentId,
+      workspaceId,
+      capabilityId: CHAT_CAPABILITY_ID,
+      state: capabilityProbe.state,
+      reason: capabilityProbe.reason,
+      runtime,
+      details: capabilityProbe.details,
+      latencyMs: capabilityProbe.latencyMs,
+    });
+
     console.log(`[AgentManager] Spawning ${runtime} for ${config.displayName ?? agentId} workspace=${workspaceName ?? workspaceId ?? 'none'} directive=${directive.directive_id ?? 'n/a'}`);
     const stdio = runtime === 'codex'
       ? ['ignore', 'pipe', 'pipe']
@@ -791,6 +1072,15 @@ export class AgentManager {
       this._clearDirectiveRefresh(key);
       this.starting.delete(key);
       this.agents.delete(key);
+      this._emitCapabilityProbe(connection, {
+        agentId,
+        workspaceId,
+        capabilityId: CHAT_CAPABILITY_ID,
+        state: 'unready',
+        reason: detail ?? 'spawn_failed',
+        runtime,
+        details: { stage: 'spawn_error' },
+      });
       this._emitLifecycle(connection, {
         agentId,
         workspaceId,
@@ -828,6 +1118,7 @@ export class AgentManager {
         kimiIdle: false,
         directive,
         requiredCredentials,
+        lastStartupMessage: startupMsg?.message ?? null,
         stopCause: null,
       });
       this.starting.delete(key);
@@ -875,8 +1166,11 @@ export class AgentManager {
         sessionId: config.sessionId ?? null,
         proc,
         runtime: 'codex',
+        codexVisibleTextSeen: false,
+        codexSendMessageUsed: false,
         directive,
         requiredCredentials,
+        lastStartupMessage: startupMsg?.message ?? null,
         stopCause: null,
       });
       this.starting.delete(key);
@@ -901,6 +1195,7 @@ export class AgentManager {
         runtime: 'claude',
         directive,
         requiredCredentials,
+        lastStartupMessage: startupMsg?.message ?? null,
         stopCause: null,
       });
       this.starting.delete(key);
@@ -929,7 +1224,12 @@ export class AgentManager {
       this._clearDirectiveRefresh(key);
       this.agents.delete(key);
 
-      if (code === 0 && runtime === 'codex' && this._pendingMessages?.get(key)?.length) {
+      if (code === 0
+        && runtime === 'codex'
+        && agent?.stopCause !== 'contract_violation'
+        && agent?.stopCause !== 'outbound_rate_limited'
+        && this._getRemainingCooldownMs(key) <= 0
+        && this._pendingMessages?.get(key)?.length) {
         const pendingCount = this._pendingMessages?.get(key)?.length ?? 0;
         console.log(
           `[AgentManager] Codex exited cleanly with pending=${pendingCount}; restarting next turn for ${config.displayName ?? agentId}`
@@ -1293,6 +1593,13 @@ export class AgentManager {
   _flushPending(key, connection) {
     if (!this._pendingMessages) return;
     if (this.agents.get(key)?.runtime === 'codex') return;
+    if (this._isInboundFlushPaused(key)) {
+      const pendingCount = this._pendingMessages.get(key)?.length ?? 0;
+      if (pendingCount > 0) {
+        console.warn(`[WARN] [AgentManager] Inbox flush paused key=${key} pending=${pendingCount}`);
+      }
+      return;
+    }
     const pending = this._pendingMessages.get(key);
     if (!pending || pending.length === 0) return;
     this._pendingMessages.delete(key);
@@ -1358,7 +1665,21 @@ export class AgentManager {
           });
           connection.send({ type: 'agent:activity', agentId, workspaceId, activity: 'thinking', detail: '', entries: [] });
           break;
+        case 'text':
+          agent.codexVisibleTextSeen = true;
+          console.log(`[AgentManager][${agent.config?.displayName ?? agentId.slice(0, 8)}][codex] <text> ${String(evt.text ?? '').slice(0, 500)}`);
+          break;
         case 'tool_call':
+          if (evt.name === 'send_message') {
+            agent.codexSendMessageUsed = true;
+            this._recordSuccessfulOutboundMessage({
+              key,
+              agent,
+              agentId,
+              workspaceId,
+              connection,
+            });
+          }
           this._emitLifecycle(connection, {
             agentId,
             workspaceId,
@@ -1395,6 +1716,9 @@ export class AgentManager {
   _parseCodexLine(key, agentId, workspaceId, line, connection) {
     const agent = this.agents.get(key);
     if (!agent) return;
+    console.log(
+      `[AgentManager][${agent.config?.displayName ?? agentId.slice(0, 8)}][codex][raw] ${String(line).slice(0, 1200)}`
+    );
     const events = parseCodexLine(line);
     for (const evt of events) {
       switch (evt.kind) {
@@ -1417,7 +1741,26 @@ export class AgentManager {
           });
           connection.send({ type: 'agent:activity', agentId, workspaceId, activity: 'thinking', detail: '', entries: [] });
           break;
+        case 'text':
+          agent.codexVisibleTextSeen = true;
+          console.log(
+            `[AgentManager][${agent.config?.displayName ?? agentId.slice(0, 8)}][codex][text] ${String(evt.text ?? '').slice(0, 1200)}`
+          );
+          break;
         case 'tool_call':
+          if (evt.name === 'send_message') {
+            agent.codexSendMessageUsed = true;
+            this._recordSuccessfulOutboundMessage({
+              key,
+              agent,
+              agentId,
+              workspaceId,
+              connection,
+            });
+          }
+          console.log(
+            `[AgentManager][${agent.config?.displayName ?? agentId.slice(0, 8)}][codex][tool] ${evt.name ?? 'unknown_tool'}`
+          );
           this._emitLifecycle(connection, {
             agentId,
             workspaceId,
@@ -1431,6 +1774,15 @@ export class AgentManager {
           connection.send({ type: 'agent:activity', agentId, workspaceId, activity: 'working', detail: evt.name, entries: [] });
           break;
         case 'turn_end':
+          const startupSenderType = String(agent.lastStartupMessage?.sender_type ?? '').trim().toLowerCase();
+          if (startupSenderType === 'user' && agent.codexVisibleTextSeen && !agent.codexSendMessageUsed) {
+            agent.stopCause = 'contract_violation';
+            console.warn(
+              `[AgentManager][${agent.config?.displayName ?? agentId.slice(0, 8)}][codex] contract_violation: visible text emitted without send_message workspace=${workspaceId ?? 'none'}`
+            );
+          }
+          agent.codexVisibleTextSeen = false;
+          agent.codexSendMessageUsed = false;
           this._emitLifecycle(connection, {
             agentId,
             workspaceId,
@@ -1444,6 +1796,9 @@ export class AgentManager {
           connection.send({ type: 'agent:activity', agentId, workspaceId, activity: 'online', detail: '', entries: [] });
           break;
         case 'error':
+          console.error(
+            `[AgentManager][${agent.config?.displayName ?? agentId.slice(0, 8)}][codex][error] ${evt.message}`
+          );
           console.error(`[AgentManager][codex][${agentId}] Error: ${evt.message}`);
           break;
       }
@@ -1475,6 +1830,18 @@ export class AgentManager {
           console.log(`[AgentManager][${displayName}] <text> ${block.text?.slice(0, 500)}`);
         } else if (block.type === 'tool_use') {
           console.log(`[AgentManager][${displayName}] <tool_use> ${block.name} params=${JSON.stringify(block.input ?? {}).slice(0, 500)}`);
+          if (block.name === 'send_message') {
+            const agent = this.agents.get(key);
+            if (agent) {
+              this._recordSuccessfulOutboundMessage({
+                key,
+                agent,
+                agentId,
+                workspaceId,
+                connection,
+              });
+            }
+          }
           this._emitLifecycle(connection, {
             agentId,
             workspaceId,

package/src/capability-probe.js

@@ -0,0 +1,113 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const REQUIRED_CHAT_TOOLS = Object.freeze(['check_messages', 'send_message']);
+const DEFAULT_PROBE_TIMEOUT_MS = 8000;
+
+function toErrorCode(error, fallback = 'probe_failed') {
+  const message = String(error?.message ?? error ?? '').trim();
+  if (!message) return fallback;
+  return message.toLowerCase().replace(/[^a-z0-9:_-]+/g, '_').slice(0, 120) || fallback;
+}
+
+function withTimeout(promise, timeoutMs, label) {
+  const effectiveTimeoutMs = Math.max(1000, Number(timeoutMs) || DEFAULT_PROBE_TIMEOUT_MS);
+  let timeout = null;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeout = setTimeout(() => {
+      const error = new Error(label);
+      error.code = label;
+      reject(error);
+    }, effectiveTimeoutMs);
+  });
+  return Promise.race([
+    promise,
+    timeoutPromise,
+  ]).finally(() => {
+    if (timeout) clearTimeout(timeout);
+  });
+}
+
+function normalizeEnv(env = {}) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value == null) continue;
+    normalized[key] = String(value);
+  }
+  return normalized;
+}
+
+function summarizeMissingTools(toolNames) {
+  return REQUIRED_CHAT_TOOLS.filter((toolName) => !toolNames.has(toolName));
+}
+
+export async function probeChatBridgeCapability({
+  chatBridgePath,
+  cwd,
+  env = {},
+  timeoutMs = DEFAULT_PROBE_TIMEOUT_MS,
+} = {}) {
+  const startedAt = Date.now();
+  const normalizedEnv = normalizeEnv(env);
+  const client = new Client({
+    name: 'lightcone-capability-probe',
+    version: '1.0.0',
+  });
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [chatBridgePath],
+    cwd,
+    env: normalizedEnv,
+    stderr: 'pipe',
+  });
+
+  try {
+    await withTimeout(client.connect(transport), timeoutMs, 'probe_connect_timeout');
+    const listed = await withTimeout(client.listTools(), timeoutMs, 'probe_list_tools_timeout');
+    const tools = Array.isArray(listed?.tools) ? listed.tools : [];
+    const toolNames = new Set(
+      tools
+        .map((tool) => String(tool?.name ?? '').trim())
+        .filter(Boolean)
+    );
+    const missingTools = summarizeMissingTools(toolNames);
+    const latencyMs = Date.now() - startedAt;
+    if (missingTools.length > 0) {
+      return {
+        state: 'unready',
+        reason: `missing_tools:${missingTools.join(',')}`,
+        latencyMs,
+        details: {
+          toolCount: tools.length,
+          missingTools,
+        },
+      };
+    }
+    return {
+      state: 'ready',
+      reason: null,
+      latencyMs,
+      details: {
+        toolCount: tools.length,
+        missingTools: [],
+      },
+    };
+  } catch (error) {
+    return {
+      state: 'unready',
+      reason: toErrorCode(error, 'probe_failed'),
+      latencyMs: Date.now() - startedAt,
+      details: {
+        toolCount: null,
+        missingTools: [...REQUIRED_CHAT_TOOLS],
+        error: String(error?.message ?? error ?? 'unknown_error').slice(0, 500),
+      },
+    };
+  } finally {
+    try {
+      await withTimeout(client.close(), 1200, 'probe_close_timeout');
+    } catch {
+      // noop: closing a failed/half-open client may throw.
+    }
+  }
+}

package/src/chat-bridge.js

@@ -53,6 +53,12 @@ const GOVERNANCE_TIMEOUT_MS = Number(process.env.GOVERNANCE_TIMEOUT_MS ?? 5000);
 const LEASE_GRACE_MS = Number(process.env.GOVERNANCE_LEASE_GRACE_MS ?? 5000);
 const BUNDLE_EVENT_FLUSH_MS = Number(process.env.GOVERNANCE_BUNDLE_FLUSH_MS ?? 2000);
 
+function redactTokenPrefix(token) {
+  const normalized = String(token ?? '').trim();
+  if (!normalized) return 'missing';
+  return normalized.slice(0, 18);
+}
+
 // Current active workspaceId for memory isolation (defaults to spawn-time WORKSPACE_ID)
 let currentWorkspaceId = WORKSPACE_ID;
 
@@ -2266,4 +2272,12 @@ if (IS_HOST_AGENT) {
 // ── start ─────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`[chat-bridge] MCP Server started (agentId=${AGENT_ID}, host=${IS_HOST_AGENT ? 'true' : 'false'})`);
+console.error(
+  `[chat-bridge] MCP Server started `
+  + `agentId=${AGENT_ID || 'missing'} `
+  + `workspaceId=${currentWorkspaceId || 'none'} `
+  + `host=${IS_HOST_AGENT ? 'true' : 'false'} `
+  + `serverUrl=${SERVER_URL || 'missing'} `
+  + `machineKey=${redactTokenPrefix(MACHINE_API_KEY)} `
+  + `governanceBundle=${GOVERNANCE_SPAWN_BUNDLE_ID || 'none'}`
+);