@swarmclawai/swarmclaw 0.6.7 → 0.7.0

package/src/lib/server/main-agent-loop.ts

@@ -1,22 +1,40 @@
 import { genId } from '@/lib/id'
 import { z } from 'zod'
 import type { GoalContract, MessageToolEvent } from '@/types'
-import { loadSessions, saveSessions, loadAgents, saveAgents, loadTasks, saveTasks } from './storage'
+import { loadSessions, saveSessions, loadAgents, saveAgents, loadTasks, saveTasks, loadSettings } from './storage'
 import { log } from './logger'
 import { getMemoryDb } from './memory-db'
 import { isProtectedMainSession } from './main-session'
+import { logExecution } from './execution-log'
 import {
   mergeGoalContracts,
   parseGoalContractFromText,
   parseMainLoopPlan,
   parseMainLoopReview,
 } from './autonomy-contract'
-const MAX_PENDING_EVENTS = 40
-const MAX_TIMELINE_EVENTS = 80
+import { buildIdentityContext } from './heartbeat-service'
+
+const MAX_PENDING_EVENTS = 60
+const MAX_TIMELINE_EVENTS = 120
 const EVENT_TTL_MS = 7 * 24 * 60 * 60 * 1000
-const MEMORY_NOTE_MIN_INTERVAL_MS = 90 * 60 * 1000
+const MEMORY_NOTE_MIN_INTERVAL_MS = 30 * 60 * 1000
 const DEFAULT_FOLLOWUP_DELAY_SEC = 45
-const MAX_FOLLOWUP_CHAIN = 6
+const DEFAULT_MAX_FOLLOWUP_CHAIN = 20
+function getMaxFollowupChain(agentId: string | undefined): number {
+  if (agentId) {
+    const agents = loadAgents()
+    const agent = agents[agentId]
+    if (typeof agent?.maxFollowupChain === 'number' && agent.maxFollowupChain > 0) {
+      return Math.min(agent.maxFollowupChain, 100)
+    }
+  }
+  const settings = loadSettings()
+  if (typeof settings?.maxFollowupChain === 'number' && settings.maxFollowupChain > 0) {
+    return Math.min(settings.maxFollowupChain, 100)
+  }
+  return DEFAULT_MAX_FOLLOWUP_CHAIN
+}
+
 const META_LINE_RE = /\[MAIN_LOOP_META\]\s*(\{[^\n]*\})/i
 const AGENT_HEARTBEAT_META_RE = /\[AGENT_HEARTBEAT_META\]\s*(\{[^\n]*\})/i
 const SCREENSHOT_GOAL_HINT = /\b(screenshot|screen shot|snapshot|capture)\b/i
@@ -25,6 +43,14 @@ const SCHEDULE_GOAL_HINT = /\b(schedule|scheduled|every\s+\w+|interval|cron|recu
 const UPLOAD_ARTIFACT_HINT = /(?:sandbox:)?\/api\/uploads\/[^\s)\]]+|https?:\/\/[^\s)\]]+\.(?:png|jpe?g|webp|gif|pdf)\b/i
 const SENT_ARTIFACT_HINT = /\b(sent|shared|uploaded|returned)\b[^.]*\b(screenshot|snapshot|image|file)\b/i
 
+const COMPANION_GOAL_PROMPT = `
+## Identity & Vibe
+You are a persistent companion.
+1. **Identity**: Embody your creature, theme, and vibe. Your emoji is your signature.
+2. **Workspace Context**: Respect the current workspace. Read IDENTITY.md and HEARTBEAT.md if they exist.
+3. **Continuity**: Maintain awareness of the user's long-term journey. Proactively help with open-ended goals without being asked for every step.
+`.trim()
+
 interface MainLoopSessionMessageLike {
   text?: string
 }
@@ -45,13 +71,12 @@ export interface MainLoopTimelineEntry {
   at: number
   source: string
   note: string
-  status?: 'idle' | 'progress' | 'blocked' | 'ok'
+  status?: 'idle' | 'progress' | 'blocked' | 'ok' | 'reflection'
 }
 
 export interface MainLoopState {
   goal: string | null
   goalContract: GoalContract | null
-  status: 'idle' | 'progress' | 'blocked' | 'ok'
   summary: string | null
   nextAction: string | null
   planSteps: string[]
@@ -61,9 +86,12 @@ export interface MainLoopState {
   missionTaskId: string | null
   momentumScore: number
   paused: boolean
+  status: 'idle' | 'progress' | 'blocked' | 'ok'
   autonomyMode: 'assist' | 'autonomous'
   pendingEvents: MainLoopEvent[]
   timeline: MainLoopTimelineEntry[]
+  missionTokens: number
+  missionCostUsd: number
   followupChainCount: number
   metaMissCount: number
   workingMemoryNotes: string[]
@@ -104,6 +132,9 @@ export interface HandleMainLoopRunResultInput {
   resultText: string
   error?: string
   toolEvents?: MessageToolEvent[]
+  inputTokens?: number
+  outputTokens?: number
+  estimatedCost?: number
 }
 
 function toOneLine(value: string, max = 240): string {
@@ -143,7 +174,7 @@ function appendTimeline(
   source: string,
   note: string,
   now = Date.now(),
-  status?: 'idle' | 'progress' | 'blocked' | 'ok',
+  status?: 'idle' | 'progress' | 'blocked' | 'ok' | 'reflection',
 ) {
   const normalizedNote = toOneLine(note, 400)
   if (!normalizedNote) return
@@ -278,6 +309,8 @@ function normalizeState(raw: any, now = Date.now()): MainLoopState {
     autonomyMode: raw?.autonomyMode === 'assist' ? 'assist' : 'autonomous',
     pendingEvents,
     timeline,
+    missionTokens: typeof raw?.missionTokens === 'number' && Number.isFinite(raw.missionTokens) ? raw.missionTokens : 0,
+    missionCostUsd: typeof raw?.missionCostUsd === 'number' && Number.isFinite(raw.missionCostUsd) ? raw.missionCostUsd : 0,
     followupChainCount: clampInt(raw?.followupChainCount, 0, 0, 100),
     metaMissCount: clampInt(raw?.metaMissCount, 0, 0, 100),
     workingMemoryNotes: normalizeStringList(raw?.workingMemoryNotes, 24, 260),
@@ -489,6 +522,7 @@ function upsertMissionTask(session: any, state: MainLoopState, now: number): str
   const statusMap = {
     idle: 'backlog',
     progress: 'running',
+    reflection: 'running',
     blocked: 'failed',
     ok: 'completed',
   } as const
@@ -603,6 +637,9 @@ function maybeStoreMissionMemoryNote(
     state.reviewNote ? `review: ${state.reviewNote}` : '',
     typeof state.reviewConfidence === 'number' ? `review_confidence: ${state.reviewConfidence}` : '',
     state.missionTaskId ? `mission_task_id: ${state.missionTaskId}` : '',
+    typeof state.missionTokens === 'number' ? `mission_tokens: ${state.missionTokens}` : '',
+    typeof state.missionCostUsd === 'number' ? `mission_cost_usd: $${state.missionCostUsd.toFixed(4)}` : '',
+    state.workingMemoryNotes?.length ? `working_notes: ${state.workingMemoryNotes.slice(-5).join('; ')}` : '',
   ].filter(Boolean).join('\n')
 
   try {
@@ -622,20 +659,27 @@ function maybeStoreMissionMemoryNote(
       category: 'mission',
       title,
       content,
-    } as any)
+    })
     state.lastMemoryNoteAt = now
-  } catch (err: any) {
-    appendEvent(state, 'memory_note_error', `Failed to store mission memory note: ${toOneLine(err?.message || String(err), 240)}`, now)
+    logExecution(session.id, 'mission_checkpoint', `Checkpoint: ${toOneLine(state.goal || '', 120)}`, {
+      agentId: session.agentId,
+      detail: { momentumScore: state.momentumScore, followupChainCount: state.followupChainCount, missionTokens: state.missionTokens, missionCostUsd: state.missionCostUsd },
+    })
+  } catch (err: unknown) {
+    appendEvent(state, 'memory_note_error', `Failed to store mission memory note: ${toOneLine(err instanceof Error ? err.message : String(err), 240)}`, now)
   }
 }
 
-function buildFollowupPrompt(state: MainLoopState, opts?: { hasMemoryTool?: boolean }): string {
+function buildFollowupPrompt(state: MainLoopState, opts?: { hasMemoryTool?: boolean; agent?: Record<string, unknown> | null; session?: Record<string, unknown> | null }): string {
   const hasMemoryTool = opts?.hasMemoryTool === true
+  const identityContext = buildIdentityContext(opts?.session, opts?.agent)
   const goal = state.goal || 'No explicit goal yet. Continue with the strongest actionable objective from recent context.'
   const nextAction = state.nextAction || 'Determine the next highest-impact action and execute it.'
   const contractLines = buildGoalContractLines(state)
   return [
     'SWARM_MAIN_AUTO_FOLLOWUP',
+    identityContext,
+    COMPANION_GOAL_PROMPT,
     `Mission goal: ${goal}`,
     `Next action to execute now: ${nextAction}`,
     `Current status: ${state.status}`,
@@ -647,6 +691,9 @@ function buildFollowupPrompt(state: MainLoopState, opts?: { hasMemoryTool?: bool
     state.reviewNote ? `Last review: ${state.reviewNote}` : '',
     buildPendingEventLines(state),
     buildTimelineLines(state),
+    state.planSteps.length === 0 && state.followupChainCount === 0
+      ? 'Before executing, break the mission goal into 3-7 concrete subtasks. Output a [MAIN_LOOP_PLAN] JSON line with your plan, then execute the first step immediately.'
+      : '',
     'Act autonomously. Use available tools to execute work, verify results, and keep momentum.',
     state.autonomyMode === 'assist'
       ? 'Assist mode: execute safe internal analysis by default, and ask before irreversible external side effects (sending messages, purchases, account mutations).'
@@ -673,6 +720,9 @@ export function isMainSession(session: any): boolean {
 
 export function buildMainLoopHeartbeatPrompt(session: any, fallbackPrompt: string): string {
   const now = Date.now()
+  const agents = loadAgents()
+  const agent = session.agentId ? agents[session.agentId] : null
+  const identityContext = buildIdentityContext(session, agent)
   const state = normalizeState(session?.mainLoopState, now)
   const goal = state.goal || inferGoalFromSessionMessages(session) || null
   const hasMemoryTool = Array.isArray(session?.tools) && session.tools.includes('memory')
@@ -684,6 +734,8 @@ export function buildMainLoopHeartbeatPrompt(session: any, fallbackPrompt: strin
 
   return [
     'SWARM_MAIN_MISSION_TICK',
+    identityContext,
+    COMPANION_GOAL_PROMPT,
     `Time: ${new Date(now).toISOString()}`,
     `Mission goal: ${promptGoal}`,
     `Current status: ${state.status}`,
@@ -883,7 +935,7 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
   const sessions = loadSessions()
   const session = sessions[input.sessionId]
   if (!session) return null
-  if (!isMainSession(session)) return handleAgentHeartbeatResult(session, input)
+  if (!isProtectedMainSession(session)) return handleAgentHeartbeatResult(session, input)
 
   const now = Date.now()
   const state = normalizeState(session.mainLoopState, now)
@@ -902,6 +954,10 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
       appendTimeline(state, 'user_goal', `Goal updated: ${userGoal}`, now, state.status)
       appendWorkingMemoryNote(state, `goal:${userGoal}`)
       forceMemoryNote = true
+      logExecution(input.sessionId, 'mission_start', `New goal: ${toOneLine(userGoal, 200)}`, {
+        agentId: session.agentId,
+        detail: { goal: userGoal, planSteps: state.planSteps },
+      })
     } else if (userGoalContract?.objective) {
       state.goal = userGoalContract.objective
       state.goalContract = mergeGoalContracts(state.goalContract, userGoalContract)
@@ -909,8 +965,22 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
       appendTimeline(state, 'user_goal_contract', `Goal contract updated: ${userGoalContract.objective}`, now, state.status)
       appendWorkingMemoryNote(state, `contract:${userGoalContract.objective}`)
       forceMemoryNote = true
+      logExecution(input.sessionId, 'mission_start', `New goal contract: ${toOneLine(userGoalContract.objective, 200)}`, {
+        agentId: session.agentId,
+        detail: { goal: userGoalContract.objective, contract: userGoalContract, planSteps: state.planSteps },
+      })
     }
     state.followupChainCount = 0
+    state.missionTokens = 0
+    state.missionCostUsd = 0
+  }
+
+  // Accumulate per-mission token/cost tracking
+  if (typeof input.inputTokens === 'number') {
+    state.missionTokens = (state.missionTokens || 0) + input.inputTokens + (input.outputTokens || 0)
+  }
+  if (typeof input.estimatedCost === 'number') {
+    state.missionCostUsd = (state.missionCostUsd || 0) + input.estimatedCost
   }
 
   if (state.paused && input.internal) {
@@ -958,7 +1028,7 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
 
   if (shouldAutoKickFromUserGoal) {
     followup = {
-      message: buildFollowupPrompt(state, { hasMemoryTool }),
+      message: buildFollowupPrompt(state, { hasMemoryTool, agent: session.agentId ? loadAgents()[session.agentId] : null, session }),
       delayMs: 1500,
       dedupeKey: `main-loop-user-kickoff:${input.sessionId}`,
     }
@@ -1020,11 +1090,33 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
       )
       consumeEvents(state, meta.consume_event_ids)
 
-      if (meta.follow_up === true && !input.error && !isHeartbeatOk && !state.paused && state.followupChainCount < MAX_FOLLOWUP_CHAIN) {
+      // Budget enforcement: check mission cost against goalContract.budgetUsd
+      const budgetUsd = state.goalContract?.budgetUsd
+      if (typeof budgetUsd === 'number' && budgetUsd > 0 && typeof state.missionCostUsd === 'number') {
+        const usageRatio = state.missionCostUsd / budgetUsd
+        if (usageRatio >= 1.0 && !state.paused) {
+          state.paused = true
+          state.status = 'blocked'
+          appendTimeline(state, 'budget_exceeded', `Mission budget exceeded ($${state.missionCostUsd.toFixed(4)} / $${budgetUsd.toFixed(4)}). Mission paused.`, now, 'blocked')
+          appendEvent(state, 'budget_exceeded', `Budget limit reached: $${state.missionCostUsd.toFixed(4)} of $${budgetUsd.toFixed(4)}`, now)
+          logExecution(input.sessionId, 'budget_warning', `Budget exceeded: $${state.missionCostUsd.toFixed(4)} / $${budgetUsd.toFixed(4)}`, {
+            agentId: session.agentId,
+            detail: { missionCostUsd: state.missionCostUsd, budgetUsd, missionTokens: state.missionTokens },
+          })
+        } else if (usageRatio >= 0.8) {
+          appendEvent(state, 'budget_warning', `Mission approaching budget limit: $${state.missionCostUsd.toFixed(4)} of $${budgetUsd.toFixed(4)} (${Math.round(usageRatio * 100)}%)`, now)
+          logExecution(input.sessionId, 'budget_warning', `Budget at ${Math.round(usageRatio * 100)}%: $${state.missionCostUsd.toFixed(4)} / $${budgetUsd.toFixed(4)}`, {
+            agentId: session.agentId,
+            detail: { missionCostUsd: state.missionCostUsd, budgetUsd, usagePercent: Math.round(usageRatio * 100) },
+          })
+        }
+      }
+
+      if (meta.follow_up === true && !input.error && !isHeartbeatOk && !state.paused && state.followupChainCount < getMaxFollowupChain(session.agentId)) {
         state.followupChainCount += 1
         const delaySec = clampInt(meta.delay_sec, DEFAULT_FOLLOWUP_DELAY_SEC, 5, 900)
         followup = {
-          message: buildFollowupPrompt(state, { hasMemoryTool }),
+          message: buildFollowupPrompt(state, { hasMemoryTool, agent: session.agentId ? loadAgents()[session.agentId] : null, session }),
           delayMs: delaySec * 1000,
           dedupeKey: `main-loop-followup:${input.sessionId}`,
         }
@@ -1034,6 +1126,12 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
       }
       if (state.status === 'ok' || state.status === 'blocked') {
         forceMemoryNote = true
+        if (state.status === 'ok') {
+          logExecution(input.sessionId, 'mission_complete', `Mission completed: ${toOneLine(state.goal || 'unknown', 200)}`, {
+            agentId: session.agentId,
+            detail: { momentumScore: state.momentumScore, followupChainCount: state.followupChainCount, missionTokens: state.missionTokens, missionCostUsd: state.missionCostUsd },
+          })
+        }
       }
     } else if (!isHeartbeatOk && trimmedText) {
       state.metaMissCount = Math.min(100, state.metaMissCount + 1)
@@ -1064,6 +1162,7 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
   state.missionTaskId = upsertMissionTask(session, state, now)
   const shouldWritePeriodicMemory = !!state.summary && state.status === 'progress'
   maybeStoreMissionMemoryNote(session, state, now, input.source, forceMemoryNote || shouldWritePeriodicMemory)
+
   state.momentumScore = computeMomentumScore(state)
 
   state.updatedAt = now

package/src/lib/server/main-session.ts

@@ -3,12 +3,15 @@ const MAIN_SESSION_NAME = '__main__'
 export function isProtectedMainSession(session: any): boolean {
   if (!session || typeof session !== 'object') return false
   if (session.mainSession === true) return true
-
-  const name = typeof session.name === 'string' ? session.name.trim() : ''
-  if (name === MAIN_SESSION_NAME) return true
+  if (session.sessionType === 'orchestrated') return true
 
   const id = typeof session.id === 'string' ? session.id.trim() : ''
   if (id.startsWith('main-')) return true
+  if (id.startsWith('agent-thread-')) return true
+
+  const name = typeof session.name === 'string' ? session.name.trim() : ''
+  if (name === MAIN_SESSION_NAME) return true
+  if (name.startsWith('agent-thread:')) return true
 
   return false
 }

package/src/lib/server/mcp-conformance.test.ts

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { runMcpConformanceCheck } from './mcp-conformance.ts'
+
+test('runMcpConformanceCheck reports connect/list failure for unsupported transport', async () => {
+  const result = await runMcpConformanceCheck({
+    id: 'bad',
+    name: 'Bad MCP',
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    transport: 'invalid-transport' as any,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  })
+
+  assert.equal(result.ok, false)
+  assert.equal(result.toolsCount, 0)
+  assert.ok(result.issues.some((issue) => issue.code === 'connect_or_list_failed'))
+})

package/src/lib/server/mcp-conformance.ts

@@ -0,0 +1,233 @@
+import type { McpServerConfig } from '@/types'
+import { connectMcpServer, disconnectMcpServer } from './mcp-client'
+
+export interface McpConformanceIssue {
+  level: 'error' | 'warning'
+  code: string
+  message: string
+  toolName?: string
+}
+
+export interface McpConformanceOptions {
+  timeoutMs?: number
+  smokeToolName?: string | null
+  smokeToolArgs?: Record<string, unknown> | null
+}
+
+export interface McpConformanceResult {
+  ok: boolean
+  serverId: string
+  serverName: string
+  checkedAt: number
+  toolsCount: number
+  smokeToolName: string | null
+  issues: McpConformanceIssue[]
+  timings: {
+    connectMs: number
+    listToolsMs: number
+    smokeInvokeMs: number | null
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 12_000
+const MIN_TIMEOUT_MS = 1_000
+const MAX_TIMEOUT_MS = 120_000
+
+function normalizeTimeoutMs(value: unknown): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number.parseInt(value, 10)
+      : Number.NaN
+  if (!Number.isFinite(parsed)) return DEFAULT_TIMEOUT_MS
+  return Math.max(MIN_TIMEOUT_MS, Math.min(MAX_TIMEOUT_MS, Math.trunc(parsed)))
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (error) => {
+        clearTimeout(timer)
+        reject(error)
+      },
+    )
+  })
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function normalizedRequired(schema: Record<string, unknown>): string[] {
+  const required = schema.required
+  if (!Array.isArray(required)) return []
+  return required.filter((entry): entry is string => typeof entry === 'string')
+}
+
+function findSmokeTool(tools: Array<Record<string, unknown>>, preferredName?: string | null): string | null {
+  const preferred = typeof preferredName === 'string' ? preferredName.trim() : ''
+  if (preferred) {
+    const found = tools.find((tool) => tool.name === preferred)
+    if (found) return preferred
+  }
+
+  const noArg = tools.find((tool) => {
+    const schema = isRecord(tool.inputSchema) ? tool.inputSchema : {}
+    const required = normalizedRequired(schema)
+    return required.length === 0
+  })
+  if (noArg && typeof noArg.name === 'string' && noArg.name.trim()) return noArg.name
+  return null
+}
+
+function validateToolSchemas(tools: Array<Record<string, unknown>>, issues: McpConformanceIssue[]): void {
+  const seenNames = new Set<string>()
+  for (const tool of tools) {
+    const toolName = typeof tool.name === 'string' ? tool.name.trim() : ''
+    if (!toolName) {
+      issues.push({
+        level: 'error',
+        code: 'tool_name_missing',
+        message: 'Tool is missing a valid name.',
+      })
+      continue
+    }
+    if (seenNames.has(toolName)) {
+      issues.push({
+        level: 'error',
+        code: 'tool_name_duplicate',
+        message: `Duplicate tool name "${toolName}" detected.`,
+        toolName,
+      })
+      continue
+    }
+    seenNames.add(toolName)
+
+    const schema = isRecord(tool.inputSchema) ? tool.inputSchema : null
+    if (!schema) {
+      issues.push({
+        level: 'warning',
+        code: 'tool_schema_missing',
+        message: `Tool "${toolName}" is missing an input schema.`,
+        toolName,
+      })
+      continue
+    }
+
+    const schemaType = typeof schema.type === 'string' ? schema.type : 'object'
+    if (schemaType !== 'object') {
+      issues.push({
+        level: 'warning',
+        code: 'tool_schema_non_object',
+        message: `Tool "${toolName}" schema type is "${schemaType}" (expected "object").`,
+        toolName,
+      })
+    }
+
+    const properties = isRecord(schema.properties) ? schema.properties : {}
+    const required = normalizedRequired(schema)
+    for (const req of required) {
+      if (!Object.prototype.hasOwnProperty.call(properties, req)) {
+        issues.push({
+          level: 'warning',
+          code: 'tool_schema_required_missing_property',
+          message: `Tool "${toolName}" marks "${req}" as required but it is not present in schema.properties.`,
+          toolName,
+        })
+      }
+    }
+  }
+}
+
+export async function runMcpConformanceCheck(
+  server: McpServerConfig,
+  options: McpConformanceOptions = {},
+): Promise<McpConformanceResult> {
+  const timeoutMs = normalizeTimeoutMs(options.timeoutMs)
+  const issues: McpConformanceIssue[] = []
+  const checkedAt = Date.now()
+  const result: McpConformanceResult = {
+    ok: false,
+    serverId: server.id,
+    serverName: server.name,
+    checkedAt,
+    toolsCount: 0,
+    smokeToolName: null,
+    issues,
+    timings: {
+      connectMs: 0,
+      listToolsMs: 0,
+      smokeInvokeMs: null,
+    },
+  }
+
+  let client: unknown
+  let transport: unknown
+  const connectStart = Date.now()
+  try {
+    const conn = await withTimeout(connectMcpServer(server), timeoutMs, 'MCP connect')
+    client = conn.client
+    transport = conn.transport
+    result.timings.connectMs = Date.now() - connectStart
+
+    const mcpClient = client as { listTools: () => Promise<Record<string, unknown>>; callTool: (opts: Record<string, unknown>) => Promise<unknown> }
+    const listStart = Date.now()
+    const listResponse = await withTimeout(mcpClient.listTools(), timeoutMs, 'MCP listTools') as Record<string, unknown>
+    result.timings.listToolsMs = Date.now() - listStart
+    const tools = Array.isArray(listResponse?.tools) ? listResponse.tools as Array<Record<string, unknown>> : []
+    result.toolsCount = tools.length
+
+    validateToolSchemas(tools, issues)
+
+    const smokeToolName = findSmokeTool(tools, options.smokeToolName)
+    result.smokeToolName = smokeToolName
+    if (!smokeToolName) {
+      issues.push({
+        level: 'warning',
+        code: 'smoke_tool_missing',
+        message: 'No smoke-testable tool found (no no-arg tool and no explicit smokeToolName).',
+      })
+    } else {
+      const smokeArgs = options.smokeToolArgs && isRecord(options.smokeToolArgs)
+        ? options.smokeToolArgs
+        : {}
+      const smokeStart = Date.now()
+      try {
+        await withTimeout(
+          mcpClient.callTool({ name: smokeToolName, arguments: smokeArgs }),
+          timeoutMs,
+          `MCP callTool(${smokeToolName})`,
+        )
+      } catch (err) {
+        issues.push({
+          level: 'error',
+          code: 'smoke_tool_failed',
+          message: err instanceof Error ? err.message : String(err),
+          toolName: smokeToolName,
+        })
+      } finally {
+        result.timings.smokeInvokeMs = Date.now() - smokeStart
+      }
+    }
+  } catch (err) {
+    issues.push({
+      level: 'error',
+      code: 'connect_or_list_failed',
+      message: err instanceof Error ? err.message : String(err),
+    })
+  } finally {
+    if (client && transport) {
+      await disconnectMcpServer(client, transport)
+    }
+  }
+
+  result.ok = issues.every((issue) => issue.level !== 'error')
+  return result
+}