@swarmclawai/swarmclaw 1.9.19 → 1.9.21

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
   ```
@@ -182,7 +184,7 @@ Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment
 
 ## Core Capabilities
 
-- **Providers**: 23 built-in — Claude Code CLI, Codex CLI, OpenCode CLI, Gemini CLI, Copilot CLI, Cursor Agent CLI, Qwen Code CLI, Goose, Anthropic, OpenAI, OpenRouter, Google Gemini, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Nebius, DeepInfra, Ollama, OpenClaw, and Hermes Agent, plus compatible custom endpoints.
+- **Providers**: 24+ built-in — Claude Code CLI, Codex CLI, OpenCode CLI, Gemini CLI, Copilot CLI, Cursor Agent CLI, Qwen Code CLI, Goose, Anthropic, OpenAI, OpenRouter, Google Gemini, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Nebius, DeepInfra, Ollama, LM Studio, OpenClaw, and Hermes Agent, plus compatible custom endpoints.
 - **OpenRouter**: <img src="public/provider-logos/openrouter.png" alt="OpenRouter logo" width="20" height="20" /> Use OpenRouter as a first-class built-in provider with its standard OpenAI-compatible endpoint and routed model IDs such as `openai/gpt-4.1-mini`.
 - **Hermes Agent**: <img src="public/provider-logos/hermes-agent.png" alt="Hermes Agent logo" width="20" height="20" /> Connect Hermes through its OpenAI-compatible API server, locally or through a reachable remote `/v1` endpoint.
 - **Delegation**: built-in delegation to Claude Code, Codex CLI, OpenCode CLI, Gemini CLI, Cursor Agent CLI, Qwen Code CLI, and native SwarmClaw subagents.
@@ -407,6 +409,24 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### 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.
+
+- **LM Studio provider.** LM Studio is available in setup, provider settings, agent editing, model discovery, and connection checks with an optional API key.
+- **Endpoint normalization.** LM Studio and OpenAI-compatible OpenAI overrides normalize bare hosts like `http://127.0.0.1:1234` to `/v1` before calling models or chat completions.
+- **Provider switch isolation.** Switching an agent from a local endpoint back to a fixed cloud provider clears stale per-agent endpoints and fallback keys.
+- **Manual model flow.** Provider model saves now preserve explicit empty endpoint resets and optional-key providers can be tested without creating a credential.
+
 ### v1.9.19 Highlights
 
 Output hygiene release: final assistant responses now use the shared internal metadata scrubber before persistence, UI reset, connector delivery, and completion hooks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.19",
+  "version": "1.9.21",
   "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/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,9 +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
@@ -32,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',
@@ -48,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,
+      })
     }
   }
 
@@ -70,57 +102,108 @@ async function checkOpenAiCompatible(
       DeepInfra: 'deepseek-ai/DeepSeek-R1-0528',
       OpenRouter: 'openai/gpt-4.1-mini',
       'Hermes Agent': 'hermes-agent',
+      '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 : []
@@ -128,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: {
@@ -136,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,
@@ -144,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',
@@ -175,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
@@ -244,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) {
@@ -300,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) {
@@ -312,7 +486,13 @@ export async function POST(req: Request) {
       case 'openai': {
         if (!apiKey) return NextResponse.json({ ok: false, message: 'OpenAI API key is required.' })
         const info = OPENAI_COMPATIBLE_DEFAULTS.openai
-        const result = await checkOpenAiCompatible(info.name, apiKey, endpoint, info.defaultEndpoint, model)
+        const result = await checkOpenAiCompatible(
+          info.name,
+          apiKey,
+          normalizeOpenAiCompatibleV1Endpoint(endpoint || info.defaultEndpoint, info.defaultEndpoint),
+          info.defaultEndpoint,
+          model,
+        )
         return NextResponse.json(result)
       }
       case 'openrouter': {
@@ -345,6 +525,17 @@ export async function POST(req: Request) {
         const result = await checkOpenAiCompatible(info.name, apiKey, endpoint, info.defaultEndpoint, model)
         return NextResponse.json(result)
       }
+      case 'lmstudio': {
+        const info = OPENAI_COMPATIBLE_DEFAULTS.lmstudio
+        const result = await checkOpenAiCompatible(
+          info.name,
+          apiKey,
+          normalizeLmStudioEndpoint(endpoint || info.defaultEndpoint),
+          info.defaultEndpoint,
+          model,
+        )
+        return NextResponse.json(result)
+      }
       case 'ollama': {
         const result = await checkOllama({
           endpointRaw: endpoint,