@swarmclawai/swarmclaw 1.9.20 → 1.9.22

package/README.md

@@ -81,8 +81,10 @@ Extension tutorial: https://swarmclaw.ai/docs/extension-tutorial
 Download the one-click installer from [swarmclaw.ai/downloads](https://swarmclaw.ai/downloads).
 Available for macOS (Apple Silicon & Intel), Windows, and Linux (AppImage + .deb).
 
-Current builds are ad-hoc signed but not notarized, so on first launch:
-- **macOS:** right-click the app in Finder → **Open** → **Open** to bypass Gatekeeper. If macOS instead reports *"SwarmClaw is damaged and can't be opened"* (common on Apple Silicon when the dmg was quarantined by Safari), strip the quarantine attribute and relaunch:
+The release workflow supports Developer ID signing and notarization when Apple
+credentials are configured. If a macOS build is still ad-hoc signed, first
+launch may need one manual approval:
+- **macOS:** right-click the app in Finder → **Open** → **Open** to bypass Gatekeeper. If macOS instead reports *"SwarmClaw is damaged and can't be opened"* (common when the dmg was quarantined by Safari), strip the quarantine attribute and relaunch:
   ```bash
   xattr -dr com.apple.quarantine /Applications/SwarmClaw.app
   ```
@@ -407,6 +409,24 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.22 Highlights
+
+Research tools release: agents now get direct `web_extract` and `web_crawl` tools alongside `web_search`, `web_fetch`, and the unified `web` tool.
+
+- **Source-grounded extraction.** `web_extract` returns a page title, canonical URL, and readable content for known source URLs.
+- **Bounded crawls.** `web_crawl` walks same-origin links by default with conservative page and depth caps, plus an explicit external-link opt-in.
+- **Better routing.** Tool aliases, capability policy, planning hints, continuation recovery, and the chat UI all recognize the granular research tools.
+- **Regression coverage.** New tests cover action inference, tool-call translation, direct tool registration, extraction cleanup, and same-origin crawl bounds.
+
+### v1.9.21 Highlights
+
+Provider diagnostics release: connection checks now return a structured step timeline across setup, provider settings, and agent editing.
+
+- **Connection timelines.** Provider checks show endpoint resolution, model discovery, fallback selection, and chat/gateway verification steps.
+- **Safer error details.** Token-like values are redacted before check messages or diagnostics are returned to the UI.
+- **Local runtime debugging.** LM Studio, Ollama, custom OpenAI-compatible endpoints, cloud providers, OpenClaw gateways, and CLI providers all report concise pass/fail diagnostics.
+- **macOS signing path.** Desktop releases now forward Developer ID and Apple notarization credentials when configured, while ad-hoc fallback builds keep the quarantine workaround documented.
+
 ### v1.9.20 Highlights
 
 Provider reliability release: local OpenAI-compatible runtimes now get safer endpoint handling, clearer setup, and first-class LM Studio support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.20",
+  "version": "1.9.22",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",
@@ -85,10 +85,10 @@
     "lint:baseline": "node ./scripts/lint-baseline.mjs check",
     "lint:baseline:update": "node ./scripts/lint-baseline.mjs update",
     "cli": "node ./bin/swarmclaw.js",
-    "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/ensure-sandbox-browser-image.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
+    "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/electron-signing-config.test.mjs scripts/ensure-sandbox-browser-image.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/gateways/gateway-topology.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/gateways/topology-route.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
-    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/agent-planning-mode.test.ts src/lib/agent-config-history.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/chats/session-context-pack.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/runs/run-handoff.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/server/schedules/schedule-preview.test.ts src/lib/quality/release-readiness.test.ts src/lib/quality/architecture-health.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-execution-policy.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/config-versions/config-versions-route.test.ts src/app/api/runs/run-handoff-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/preview/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
+    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/agent-planning-mode.test.ts src/lib/agent-config-history.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/provider-diagnostics.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/chats/session-context-pack.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/runs/run-handoff.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/server/schedules/schedule-preview.test.ts src/lib/quality/release-readiness.test.ts src/lib/quality/architecture-health.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-execution-policy.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/server/session-tools/web-crawl.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/config-versions/config-versions-route.test.ts src/app/api/runs/run-handoff-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/preview/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",
     "test:e2e": "node --import tsx scripts/browser-e2e-smoke.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",

package/src/app/api/setup/check-provider/route.test.ts

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict'
 import test from 'node:test'
 
 import { normalizeOllamaSetupEndpoint, normalizeOpenClawUrl, parseErrorMessage } from './helpers'
+import { POST } from './route'
 
 test('normalizeOllamaSetupEndpoint strips local /v1 suffixes but preserves cloud endpoints', () => {
   assert.equal(
@@ -117,3 +118,46 @@ test('normalizeOpenClawUrl handles bare IP:port', () => {
   assert.equal(httpUrl, 'http://10.0.0.5:18789')
   assert.equal(wsUrl, 'ws://10.0.0.5:18789')
 })
+
+test('POST returns provider diagnostics with normalized LM Studio targets and redacted errors', async () => {
+  const originalFetch = globalThis.fetch
+  const calls: string[] = []
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    const url = String(input)
+    calls.push(url)
+    if (url.endsWith('/models')) {
+      return new Response(JSON.stringify({ data: [{ id: 'google/gemma-4-e4b' }] }), { status: 200 })
+    }
+    return new Response(
+      JSON.stringify({ error: { message: 'Malformed token sk-local-secret provided.' } }),
+      { status: 400 },
+    )
+  }) as typeof fetch
+
+  try {
+    const res = await POST(new Request('http://localhost/api/setup/check-provider', {
+      method: 'POST',
+      body: JSON.stringify({
+        provider: 'lmstudio',
+        endpoint: 'http://10.2.0.2:1234',
+      }),
+    }))
+    const payload = await res.json()
+
+    assert.equal(payload.ok, false)
+    assert.equal(payload.normalizedEndpoint, 'http://10.2.0.2:1234/v1')
+    assert.deepEqual(calls, [
+      'http://10.2.0.2:1234/v1/models',
+      'http://10.2.0.2:1234/v1/chat/completions',
+    ])
+    assert.ok(Array.isArray(payload.diagnostics))
+    assert.equal(payload.diagnostics[0].target, 'http://10.2.0.2:1234/v1')
+    assert.equal(payload.message, 'Malformed token sk-... provided.')
+    assert.equal(
+      payload.diagnostics.some((step: { detail?: string }) => step.detail?.includes('sk-local-secret')),
+      false,
+    )
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})

package/src/app/api/setup/check-provider/route.ts

@@ -4,10 +4,12 @@ import { listCredentialIdsByProvider } from '@/lib/server/credentials/credential
 import { getDeviceId, wsConnect, rpcOnConnectedGateway } from '@/lib/providers/openclaw'
 import { isCliProviderId } from '@/lib/providers/cli-provider-metadata'
 import { checkCliProviderReady } from '@/lib/server/cli-provider-readiness'
+import { createProviderDiagnostics, sanitizeProviderDiagnosticText } from '@/lib/server/provider-diagnostics'
 import { OPENAI_COMPATIBLE_DEFAULTS } from '@/lib/server/provider-health'
 import { normalizeLmStudioEndpoint, normalizeOpenAiCompatibleV1Endpoint } from '@/lib/providers/openai-compatible-endpoint'
 import { resolveOllamaRuntimeConfig } from '@/lib/server/ollama-runtime'
 import { normalizeOllamaSetupEndpoint, normalizeOpenClawUrl, parseErrorMessage } from './helpers'
+import type { ProviderCheckResult } from '@/types/provider'
 
 interface SetupCheckBody {
   provider?: string
@@ -33,15 +35,21 @@ async function checkOpenAiCompatible(
   endpointRaw: string,
   defaultEndpoint: string,
   modelHint?: string,
-): Promise<{ ok: boolean; message: string; normalizedEndpoint: string }> {
+): Promise<ProviderCheckResult> {
+  const diagnostics = createProviderDiagnostics()
   const normalizedEndpoint = (endpointRaw || defaultEndpoint).replace(/\/+$/, '')
+  diagnostics.pass('Endpoint resolved', { target: normalizedEndpoint })
   const authHeaders = apiKey ? { authorization: `Bearer ${apiKey}` } : undefined
 
   // First, discover a model to test with (prefer the hint, fall back to the first available model)
   let testModel = modelHint || ''
-  if (!testModel) {
+  if (testModel) {
+    diagnostics.pass('Test model selected', { detail: testModel })
+  } else {
+    const modelsTarget = `${normalizedEndpoint}/models`
+    const startedAt = Date.now()
     try {
-      const modelsRes = await fetch(`${normalizedEndpoint}/models`, {
+      const modelsRes = await fetch(modelsTarget, {
         headers: authHeaders,
         signal: AbortSignal.timeout(8_000),
         cache: 'no-store',
@@ -49,10 +57,33 @@ async function checkOpenAiCompatible(
       if (modelsRes.ok) {
         const modelsPayload = await modelsRes.json().catch(() => ({} as Record<string, unknown>))
         const first = Array.isArray(modelsPayload?.data) ? modelsPayload.data[0] : null
-        if (first?.id) testModel = String(first.id)
+        if (first?.id) {
+          testModel = String(first.id)
+          diagnostics.pass('Model discovery completed', {
+            target: modelsTarget,
+            detail: `Using ${testModel}`,
+            durationMs: Date.now() - startedAt,
+          })
+        } else {
+          diagnostics.warn('Model discovery returned no models', {
+            target: modelsTarget,
+            durationMs: Date.now() - startedAt,
+          })
+        }
+      } else {
+        const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(modelsRes, `${providerName} models returned ${modelsRes.status}.`))
+        diagnostics.warn('Model discovery failed', {
+          target: modelsTarget,
+          detail: `HTTP ${modelsRes.status}: ${detail}`,
+          durationMs: Date.now() - startedAt,
+        })
       }
-    } catch {
-      // Model discovery failed — we'll still try the chat endpoint with the provider's default
+    } catch (err: unknown) {
+      diagnostics.warn('Model discovery request failed', {
+        target: modelsTarget,
+        detail: err instanceof Error && err.message ? err.message : 'Unable to query models.',
+        durationMs: Date.now() - startedAt,
+      })
     }
   }
 
@@ -74,55 +105,105 @@ async function checkOpenAiCompatible(
       'LM Studio': 'local-model',
     }
     testModel = fallbacks[providerName] || 'gpt-4o-mini'
+    diagnostics.warn('Fallback test model selected', { detail: testModel })
   }
 
   // Test the chat completions endpoint with a minimal request
-  const res = await fetch(`${normalizedEndpoint}/chat/completions`, {
-    method: 'POST',
-    headers: {
-      'content-type': 'application/json',
-      ...(authHeaders || {}),
-    },
-    body: JSON.stringify({
-      model: testModel,
-      max_completion_tokens: 8,
-      messages: [{ role: 'user', content: 'Reply OK' }],
-    }),
-    signal: AbortSignal.timeout(15_000),
-    cache: 'no-store',
-  })
+  const chatTarget = `${normalizedEndpoint}/chat/completions`
+  const chatStartedAt = Date.now()
+  let res: Response
+  try {
+    res = await fetch(chatTarget, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(authHeaders || {}),
+      },
+      body: JSON.stringify({
+        model: testModel,
+        max_completion_tokens: 8,
+        messages: [{ role: 'user', content: 'Reply OK' }],
+      }),
+      signal: AbortSignal.timeout(15_000),
+      cache: 'no-store',
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error && err.name === 'TimeoutError'
+      ? 'Connection check timed out. Verify endpoint/network and try again.'
+      : (err instanceof Error && err.message ? err.message : 'Chat endpoint request failed.')
+    diagnostics.fail('Chat completion request failed', {
+      target: chatTarget,
+      detail: message,
+      durationMs: Date.now() - chatStartedAt,
+    })
+    return { ok: false, message: sanitizeProviderDiagnosticText(message), normalizedEndpoint, diagnostics: diagnostics.toJSON() }
+  }
   if (!res.ok) {
-    const detail = await parseErrorMessage(res, `${providerName} returned ${res.status}.`)
-    return { ok: false, message: detail, normalizedEndpoint }
+    const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(res, `${providerName} returned ${res.status}.`))
+    diagnostics.fail('Chat completion check failed', {
+      target: chatTarget,
+      detail: `HTTP ${res.status}: ${detail}`,
+      durationMs: Date.now() - chatStartedAt,
+    })
+    return { ok: false, message: detail, normalizedEndpoint, diagnostics: diagnostics.toJSON() }
   }
+  diagnostics.pass('Chat completion check passed', {
+    target: chatTarget,
+    detail: `Verified with ${testModel}`,
+    durationMs: Date.now() - chatStartedAt,
+  })
   return {
     ok: true,
     message: `Connected to ${providerName}. Chat endpoint verified with ${testModel}.`,
     normalizedEndpoint,
+    diagnostics: diagnostics.toJSON(),
   }
 }
 
-async function checkAnthropic(apiKey: string, endpointRaw: string, modelRaw: string): Promise<{ ok: boolean; message: string }> {
+async function checkAnthropic(apiKey: string, endpointRaw: string, modelRaw: string): Promise<ProviderCheckResult> {
+  const diagnostics = createProviderDiagnostics()
   const model = modelRaw || 'claude-sonnet-4-6'
   const baseUrl = (endpointRaw || 'https://api.anthropic.com').replace(/\/+$/, '')
-  const res = await fetch(`${baseUrl}/v1/messages`, {
-    method: 'POST',
-    headers: {
-      'x-api-key': apiKey,
-      'anthropic-version': '2023-06-01',
-      'content-type': 'application/json',
-    },
-    body: JSON.stringify({
-      model,
-      max_tokens: 12,
-      messages: [{ role: 'user', content: 'Reply with ANTHROPIC_SETUP_OK' }],
-    }),
-    signal: AbortSignal.timeout(15_000),
-    cache: 'no-store',
-  })
+  diagnostics.pass('Endpoint resolved', { target: baseUrl })
+  diagnostics.pass('Test model selected', { detail: model })
+  const target = `${baseUrl}/v1/messages`
+  const startedAt = Date.now()
+  let res: Response
+  try {
+    res = await fetch(target, {
+      method: 'POST',
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 12,
+        messages: [{ role: 'user', content: 'Reply with ANTHROPIC_SETUP_OK' }],
+      }),
+      signal: AbortSignal.timeout(15_000),
+      cache: 'no-store',
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error && err.name === 'TimeoutError'
+      ? 'Connection check timed out. Verify endpoint/network and try again.'
+      : (err instanceof Error && err.message ? err.message : 'Anthropic request failed.')
+    diagnostics.fail('Message check request failed', {
+      target,
+      detail: message,
+      durationMs: Date.now() - startedAt,
+    })
+    return { ok: false, message: sanitizeProviderDiagnosticText(message), diagnostics: diagnostics.toJSON() }
+  }
   if (!res.ok) {
-    const detail = await parseErrorMessage(res, `Anthropic returned ${res.status}.`)
-    return { ok: false, message: detail }
+    const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(res, `Anthropic returned ${res.status}.`))
+    diagnostics.fail('Message check failed', {
+      target,
+      detail: `HTTP ${res.status}: ${detail}`,
+      durationMs: Date.now() - startedAt,
+    })
+    return { ok: false, message: detail, diagnostics: diagnostics.toJSON() }
   }
   const payload = await res.json().catch(() => ({} as Record<string, unknown>))
   const content = Array.isArray(payload.content) ? payload.content : []
@@ -130,7 +211,12 @@ async function checkAnthropic(apiKey: string, endpointRaw: string, modelRaw: str
   const text = firstContent && typeof firstContent === 'object' && 'text' in firstContent && typeof firstContent.text === 'string'
     ? firstContent.text
     : ''
-  return { ok: true, message: text ? `Connected to Anthropic. Sample: ${text.slice(0, 120)}` : 'Connected to Anthropic.' }
+  diagnostics.pass('Message check passed', {
+    target,
+    detail: text ? `Sample: ${text.slice(0, 80)}` : 'Provider returned a successful response.',
+    durationMs: Date.now() - startedAt,
+  })
+  return { ok: true, message: text ? `Connected to Anthropic. Sample: ${text.slice(0, 120)}` : 'Connected to Anthropic.', diagnostics: diagnostics.toJSON() }
 }
 
 async function checkOllama(params: {
@@ -138,7 +224,8 @@ async function checkOllama(params: {
   modelRaw: string
   ollamaMode?: string
   apiKey?: string
-}): Promise<{ ok: boolean; message: string; normalizedEndpoint: string; recommendedModel?: string }> {
+}): Promise<ProviderCheckResult> {
+  const diagnostics = createProviderDiagnostics()
   const runtime = resolveOllamaRuntimeConfig({
     model: params.modelRaw,
     ollamaMode: params.ollamaMode ?? null,
@@ -146,22 +233,32 @@ async function checkOllama(params: {
     apiEndpoint: params.endpointRaw,
   })
   const normalizedEndpoint = normalizeOllamaSetupEndpoint(runtime.endpoint, runtime.useCloud)
+  diagnostics.pass('Endpoint resolved', {
+    target: normalizedEndpoint,
+    detail: runtime.useCloud ? 'Ollama Cloud mode' : 'Local Ollama mode',
+  })
   const headers: Record<string, string> = runtime.apiKey ? { authorization: `Bearer ${runtime.apiKey}` } : {}
   if (runtime.useCloud && !runtime.apiKey) {
+    diagnostics.fail('Credential required', { detail: 'Ollama Cloud requires an API key.' })
     return {
       ok: false,
       message: 'Ollama Cloud model requires an API key. Set OLLAMA_API_KEY or attach an Ollama credential.',
       normalizedEndpoint,
+      diagnostics: diagnostics.toJSON(),
     }
   }
 
   // Discover a model to test with
   let testModel = params.modelRaw || ''
   let recommendedModel: string | undefined
-  if (!testModel) {
+  if (testModel) {
+    diagnostics.pass('Test model selected', { detail: testModel })
+  } else {
+    const tagsPath = runtime.useCloud ? '/v1/models' : '/api/tags'
+    const target = `${normalizedEndpoint}${tagsPath}`
+    const startedAt = Date.now()
     try {
-      const tagsPath = runtime.useCloud ? '/v1/models' : '/api/tags'
-      const res = await fetch(`${normalizedEndpoint}${tagsPath}`, {
+      const res = await fetch(target, {
         headers: headers.authorization ? headers : undefined,
         signal: AbortSignal.timeout(8_000),
         cache: 'no-store',
@@ -177,63 +274,126 @@ async function checkOllama(params: {
         if (firstModel) {
           testModel = firstModel
           recommendedModel = firstModel
+          diagnostics.pass('Model discovery completed', {
+            target,
+            detail: `Using ${firstModel}`,
+            durationMs: Date.now() - startedAt,
+          })
         }
         if (models.length === 0) {
+          diagnostics.warn('Model discovery returned no models', {
+            target,
+            durationMs: Date.now() - startedAt,
+          })
           return {
             ok: true,
             message: runtime.useCloud
               ? 'Connected to Ollama Cloud, but no models were returned.'
               : 'Connected to Ollama, but no models are installed yet. Run `ollama pull <model>` to add one.',
             normalizedEndpoint,
+            diagnostics: diagnostics.toJSON(),
           }
         }
+      } else {
+        const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(res, `Ollama model discovery returned ${res.status}.`))
+        diagnostics.warn('Model discovery failed', {
+          target,
+          detail: `HTTP ${res.status}: ${detail}`,
+          durationMs: Date.now() - startedAt,
+        })
       }
-    } catch {
-      // Model discovery failed — try chat anyway
+    } catch (err: unknown) {
+      diagnostics.warn('Model discovery request failed', {
+        target,
+        detail: err instanceof Error && err.message ? err.message : 'Unable to query models.',
+        durationMs: Date.now() - startedAt,
+      })
     }
   }
 
-  if (!testModel) testModel = 'llama3.2'
+  if (!testModel) {
+    testModel = 'llama3.2'
+    diagnostics.warn('Fallback test model selected', { detail: testModel })
+  }
 
   // Test the chat endpoint
   const label = runtime.useCloud ? 'Ollama Cloud' : 'Ollama'
   const chatEndpoint = `${normalizedEndpoint}/v1/chat/completions`
   const chatBody = JSON.stringify({ model: testModel, max_completion_tokens: 8, messages: [{ role: 'user', content: 'Reply OK' }] })
 
-  const chatRes = await fetch(chatEndpoint, {
-    method: 'POST',
-    headers: { ...headers, 'content-type': 'application/json' },
-    body: chatBody,
-    signal: AbortSignal.timeout(30_000),
-    cache: 'no-store',
-  })
+  const chatStartedAt = Date.now()
+  let chatRes: Response
+  try {
+    chatRes = await fetch(chatEndpoint, {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: chatBody,
+      signal: AbortSignal.timeout(30_000),
+      cache: 'no-store',
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error && err.name === 'TimeoutError'
+      ? 'Connection check timed out. Verify endpoint/network and try again.'
+      : (err instanceof Error && err.message ? err.message : 'Ollama chat request failed.')
+    diagnostics.fail('Chat completion request failed', {
+      target: chatEndpoint,
+      detail: message,
+      durationMs: Date.now() - chatStartedAt,
+    })
+    return { ok: false, message: sanitizeProviderDiagnosticText(message), normalizedEndpoint, recommendedModel, diagnostics: diagnostics.toJSON() }
+  }
   if (!chatRes.ok) {
-    const detail = await parseErrorMessage(chatRes, `${label} chat returned ${chatRes.status}.`)
-    return { ok: false, message: detail, normalizedEndpoint, recommendedModel }
+    const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(chatRes, `${label} chat returned ${chatRes.status}.`))
+    diagnostics.fail('Chat completion check failed', {
+      target: chatEndpoint,
+      detail: `HTTP ${chatRes.status}: ${detail}`,
+      durationMs: Date.now() - chatStartedAt,
+    })
+    return { ok: false, message: detail, normalizedEndpoint, recommendedModel, diagnostics: diagnostics.toJSON() }
   }
+  diagnostics.pass('Chat completion check passed', {
+    target: chatEndpoint,
+    detail: `Verified with ${testModel}`,
+    durationMs: Date.now() - chatStartedAt,
+  })
   return {
     ok: true,
     message: `Connected to ${label}. Chat verified with ${testModel}.`,
     normalizedEndpoint,
     recommendedModel: recommendedModel || testModel,
+    diagnostics: diagnostics.toJSON(),
   }
 }
 
-async function checkOpenClaw(apiKey: string, endpointRaw: string): Promise<{ ok: boolean; message: string; normalizedEndpoint: string; deviceId?: string; errorCode?: string; recommendedModel?: string }> {
+async function checkOpenClaw(apiKey: string, endpointRaw: string): Promise<ProviderCheckResult> {
+  const diagnostics = createProviderDiagnostics()
   const { httpUrl: normalizedEndpoint, wsUrl } = normalizeOpenClawUrl(endpointRaw)
   const token = apiKey || undefined
   const deviceId = getDeviceId()
+  diagnostics.pass('Endpoint resolved', { target: normalizedEndpoint })
 
+  const wsStartedAt = Date.now()
   const result = await wsConnect(wsUrl, token, true, 10_000)
 
   if (!result.ok) {
     if (result.ws) try { result.ws.close() } catch {}
-    return { ok: false, message: result.message, normalizedEndpoint, deviceId, errorCode: result.errorCode }
+    diagnostics.fail('Gateway websocket check failed', {
+      target: wsUrl,
+      detail: result.message,
+      durationMs: Date.now() - wsStartedAt,
+    })
+    return { ok: false, message: sanitizeProviderDiagnosticText(result.message), normalizedEndpoint, deviceId, errorCode: result.errorCode, diagnostics: diagnostics.toJSON() }
   }
+  diagnostics.pass('Gateway websocket check passed', {
+    target: wsUrl,
+    detail: deviceId ? `Device ${deviceId}` : undefined,
+    durationMs: Date.now() - wsStartedAt,
+  })
 
   // Attempt model discovery via RPC before closing the connection
   let recommendedModel: string | undefined
   if (result.ws) {
+    const modelStartedAt = Date.now()
     try {
       const payload = await rpcOnConnectedGateway(result.ws, 'models.list', {}, 8_000) as Record<string, unknown> | unknown[] | undefined
       const p = payload as Record<string, unknown> | undefined
@@ -246,13 +406,20 @@ async function checkOpenClaw(apiKey: string, endpointRaw: string): Promise<{ ok:
       } else if (typeof first?.name === 'string') {
         recommendedModel = first.name
       }
-    } catch {
-      // Model discovery is non-fatal — connection still counts as successful
+      diagnostics.pass('Gateway model discovery completed', {
+        detail: recommendedModel ? `Using ${recommendedModel}` : 'No model recommendation returned.',
+        durationMs: Date.now() - modelStartedAt,
+      })
+    } catch (err: unknown) {
+      diagnostics.warn('Gateway model discovery failed', {
+        detail: err instanceof Error && err.message ? err.message : 'Model discovery is unavailable.',
+        durationMs: Date.now() - modelStartedAt,
+      })
     }
     try { result.ws.close() } catch {}
   }
 
-  return { ok: true, message: 'Connected to OpenClaw gateway.', normalizedEndpoint, deviceId, recommendedModel }
+  return { ok: true, message: 'Connected to OpenClaw gateway.', normalizedEndpoint, deviceId, recommendedModel, diagnostics: diagnostics.toJSON() }
 }
 
 export async function POST(req: Request) {
@@ -302,7 +469,12 @@ export async function POST(req: Request) {
 
   if (isCliProviderId(provider)) {
     const result = checkCliProviderReady(provider)
-    return NextResponse.json(result)
+    const diagnostics = createProviderDiagnostics()
+    diagnostics.add('CLI readiness check', result.ok ? 'pass' : 'fail', {
+      detail: result.message,
+      target: result.binaryPath || result.binaryName || provider,
+    })
+    return NextResponse.json({ ...result, diagnostics: diagnostics.toJSON() })
   }
 
   if (!provider) {