@swarmclawai/swarmclaw 1.5.1 → 1.5.3

package/README.md

@@ -15,6 +15,46 @@ Docs: https://swarmclaw.ai/docs
 Website: https://swarmclaw.ai  
 Extension tutorial: https://swarmclaw.ai/docs/extension-tutorial
 
+## Hosted Deploys
+
+SwarmClaw now ships provider-ready deploy files at the repo root:
+
+- `render.yaml` for Render Blueprint deploys from the public GHCR image
+- `fly.toml` for Fly.io image-backed deploys
+- `railway.json` for Railway-aligned health and restart defaults
+
+The published image is:
+
+```text
+ghcr.io/swarmclawai/swarmclaw:latest
+```
+
+Hosted deployments should:
+
+- mount persistent storage at `/app/data`
+- manage secrets through the provider dashboard
+- set `ACCESS_KEY` and `CREDENTIAL_SECRET`
+- point health checks at `/api/healthz`
+
+Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment
+
+## OpenTelemetry OTLP Export
+
+SwarmClaw supports opt-in OTLP trace export for chat turns, direct model streams, tool execution, and structured-session runs.
+
+Minimal configuration:
+
+```bash
+OTEL_ENABLED=true
+OTEL_SERVICE_NAME=swarmclaw
+OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4318
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-token
+```
+
+If you need a trace-specific endpoint, set `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` directly instead.
+
+Operational docs: https://swarmclaw.ai/docs/observability
+
 ## Screenshots
 
 <table>
@@ -215,6 +255,17 @@ SwarmClaw agents can join [SwarmFeed](https://swarmfeed.ai) — a social network
 
 Read the docs at [swarmclaw.ai/docs/swarmfeed](https://swarmclaw.ai/docs/swarmfeed) and visit [swarmfeed.ai](https://swarmfeed.ai) for the platform itself.
 
+### v1.5.3 Highlights
+
+- **Copilot CLI v1.x compatibility**: the `copilot-cli` provider now handles the current event format (`assistant.message_delta`, `assistant.message`, updated `result` payload) while keeping backward compatibility with the legacy format. Also fixes `--resume` flag syntax. (Community contribution by [@borislavnnikolov](https://github.com/borislavnnikolov) -- PR #36)
+
+### v1.5.2 Highlights
+
+- **Hosted deploy path for SwarmClaw itself**: added root-level `render.yaml`, `fly.toml`, and `railway.json` so the published `ghcr.io/swarmclawai/swarmclaw:latest` image is easier to run on always-on platforms.
+- **Public health endpoint for hosted platforms**: added `/api/healthz` and exempted it from access-key auth so Render, Fly.io, and Railway can perform liveness checks without weakening the rest of the API surface.
+- **OTLP/OpenTelemetry foundation**: SwarmClaw can now export traces for chat turns, direct model streams, protocol runs, and tool execution to any OTLP-compatible backend using environment variables only.
+- **Docs and landing-page deploy refresh**: `swarmclaw.ai` now exposes the hosted deploy path and a dedicated observability guide instead of burying those operator workflows in general setup docs.
+
 ### v1.5.1 Highlights
 
 - **Standalone connector lifecycle**: connector start, stop, status, and repair now work correctly in standalone production builds (`npm start` / pm2) where the daemon runs in-process. Previously these operations silently failed because the controller assumed a daemon subprocess was always present. (Community contribution by [@borislavnnikolov](https://github.com/borislavnnikolov) -- PR #35)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.1",
-  "description": "Self-hosted AI runtime for OpenClaw, delegation, autonomy, runtime skills, crypto wallets, and chat platform connectors.",
+  "version": "1.5.3",
+  "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -74,7 +74,7 @@
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js 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",
     "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/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/openclaw-exports.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
-    "test:runtime": "tsx --test src/lib/server/knowledge-sources.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/safe-parse-body.test.ts src/app/api/approvals/route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/logs/route.test.ts src/app/api/tts/route.test.ts",
+    "test:runtime": "tsx --test src/lib/server/knowledge-sources.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/app/api/approvals/route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/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": "tsx .workbench/browser-e2e/run.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",
@@ -88,6 +88,9 @@
     "@langchain/langgraph": "^1.2.2",
     "@langchain/openai": "^1.2.8",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/sdk-node": "^0.214.0",
     "@multiavatar/multiavatar": "^1.0.7",
     "@playwright/mcp": "^0.0.68",
     "@slack/bolt": "^4.6.0",

package/src/app/api/healthz/route.test.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import { GET } from '@/app/api/healthz/route'
+
+test('GET /api/healthz returns an ok payload', async () => {
+  const response = await GET()
+  assert.equal(response.status, 200)
+
+  const payload = await response.json()
+  assert.equal(payload.ok, true)
+  assert.equal(payload.service, 'swarmclaw')
+  assert.equal(typeof payload.time, 'number')
+})

package/src/app/api/healthz/route.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from 'next/server'
+
+export async function GET() {
+  return NextResponse.json({
+    ok: true,
+    service: 'swarmclaw',
+    time: Date.now(),
+  })
+}

package/src/cli/index.js

@@ -734,6 +734,13 @@ const COMMAND_GROUPS = [
       cmd('get', 'GET', '/system/status', 'Get system health summary (safe for external monitors)'),
     ],
   },
+  {
+    name: 'healthz',
+    description: 'Public liveness probe',
+    commands: [
+      cmd('get', 'GET', '/healthz', 'Get public health check payload'),
+    ],
+  },
   {
     name: 'usage',
     description: 'Usage and cost summary',

package/src/instrumentation.ts

@@ -5,9 +5,11 @@ const TAG = 'instrumentation'
 export async function register() {
   if (process.env.NEXT_RUNTIME === 'nodejs') {
     const { log } = await import('@/lib/server/logger')
+    const { ensureOpenTelemetryStarted, shutdownOpenTelemetry } = await import('@/lib/server/observability/otel')
     const isWorkerOnly = process.env.SWARMCLAW_WORKER_ONLY === '1'
     const { initWsServer, closeWsServer } = await import('./lib/server/ws-hub')
     const { ensureDaemonStarted } = await import('@/lib/server/runtime/daemon-state')
+    await ensureOpenTelemetryStarted()
     
     // One-time migration: backfill allKnownPeerIds on existing connector sessions
     try {
@@ -44,6 +46,11 @@ export async function register() {
       } catch (err) {
         log.error(TAG, 'Failed to stop daemon during shutdown:', err)
       }
+      try {
+        await shutdownOpenTelemetry()
+      } catch (err) {
+        log.error(TAG, 'Failed to stop OpenTelemetry during shutdown:', err)
+      }
       if (!isWorkerOnly) {
         await closeWsServer()
       }

package/src/lib/providers/copilot-cli.ts

@@ -46,7 +46,7 @@ export function streamCopilotCliChat({ session, message, imagePath, systemPrompt
   const prompt = promptParts.join('\n\n')
 
   const args = ['-p', prompt, '--output-format=json', '-s', '--yolo']
-  if (session.copilotSessionId) args.push('--resume', session.copilotSessionId)
+  if (session.copilotSessionId) args.push(`--resume=${session.copilotSessionId}`)
   if (session.model) args.push('--model', session.model)
 
   // System prompt: write temp AGENTS.override.md in a temp config dir
@@ -106,14 +106,35 @@ export function streamCopilotCliChat({ session, message, imagePath, systemPrompt
         const ev = JSON.parse(line) as Record<string, unknown>
         eventCount++
 
-        // Capture session ID from init event
+        const data = ev.data as Record<string, unknown> | undefined
+
+        // Capture session ID — legacy 'init' event or modern 'result' event
         if (ev.type === 'init' && typeof ev.session_id === 'string') {
           session.copilotSessionId = ev.session_id
-          log.info('copilot-cli', `Got session_id: ${ev.session_id}`)
+          log.info('copilot-cli', `Got session_id (init): ${ev.session_id}`)
+        } else if (ev.type === 'result' && typeof ev.sessionId === 'string') {
+          session.copilotSessionId = ev.sessionId
+          log.info('copilot-cli', `Got session_id (result): ${ev.sessionId}`)
+        }
+
+        // Modern format: streaming delta — assistant.message_delta { data: { deltaContent } }
+        if (ev.type === 'assistant.message_delta' && typeof data?.deltaContent === 'string') {
+          fullResponse += data.deltaContent
+          write(`data: ${JSON.stringify({ t: 'd', text: data.deltaContent })}\n\n`)
+        }
+
+        // Modern format: full assistant message — assistant.message { data: { content } }
+        else if (ev.type === 'assistant.message' && typeof data?.content === 'string') {
+          // Only emit as final result if we haven't been streaming deltas
+          if (!fullResponse) {
+            fullResponse = data.content
+            write(`data: ${JSON.stringify({ t: 'r', text: data.content })}\n\n`)
+          }
+          log.debug('copilot-cli', `Assistant message (${data.content.length} chars)`)
         }
 
-        // Streaming text deltas
-        if (ev.type === 'content_block_delta') {
+        // Legacy: streaming text deltas — content_block_delta { delta: { text } }
+        else if (ev.type === 'content_block_delta') {
           const delta = ev.delta as Record<string, unknown> | undefined
           if (typeof delta?.text === 'string') {
             fullResponse += delta.text
@@ -121,19 +142,19 @@ export function streamCopilotCliChat({ session, message, imagePath, systemPrompt
           }
         }
 
-        // Agent message chunks (ACP format)
+        // Legacy: agent message chunks (ACP format)
         else if (ev.type === 'agent_message_chunk' && typeof ev.text === 'string') {
           fullResponse += ev.text
           write(`data: ${JSON.stringify({ t: 'd', text: ev.text })}\n\n`)
         }
 
-        // Assistant message content
+        // Legacy: assistant message content
         else if (ev.type === 'message' && ev.role === 'assistant' && typeof ev.content === 'string') {
           fullResponse += ev.content
           write(`data: ${JSON.stringify({ t: 'd', text: ev.content })}\n\n`)
         }
 
-        // Completed item with agent_message
+        // Legacy: completed item with agent_message
         else if (ev.type === 'item.completed' && (ev.item as Record<string, unknown>)?.type === 'agent_message') {
           const item = ev.item as Record<string, unknown>
           if (typeof item.text === 'string') {
@@ -143,7 +164,7 @@ export function streamCopilotCliChat({ session, message, imagePath, systemPrompt
           }
         }
 
-        // Final result
+        // Legacy: final result with string result field
         else if (ev.type === 'result' && typeof ev.result === 'string') {
           fullResponse = ev.result
           write(`data: ${JSON.stringify({ t: 'r', text: ev.result })}\n\n`)

package/src/lib/server/chat-execution/chat-execution.ts

@@ -1,5 +1,6 @@
 import type { ExecuteChatTurnInput, ExecuteChatTurnResult } from './chat-execution-types'
 import { perf } from '@/lib/server/runtime/perf'
+import { setSpanAttributes, withServerSpan } from '@/lib/server/observability/otel-tracing'
 import { markProviderSuccess } from '@/lib/server/provider-health'
 import { executePreparedChatTurn } from '@/lib/server/chat-execution/chat-turn-stream-execution'
 import { finalizeChatTurn } from '@/lib/server/chat-execution/chat-turn-finalization'
@@ -50,84 +51,121 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
     sessionId,
     source = 'chat',
   } = input
-  const endTurnPerf = perf.start('chat-execution', 'executeSessionChatTurn', { sessionId, source })
-  const preparedTurn = await prepareChatTurn(input)
-  if (preparedTurn.kind === 'blocked') {
-    const result = await completeBlockedChatTurn(preparedTurn)
-    endTurnPerf({
-      durationMs: 0,
-      toolEventCount: result.toolEvents.length,
-      inputTokens: result.inputTokens || 0,
-      outputTokens: result.outputTokens || 0,
-      error: !!result.error,
-    })
-    return result
-  }
+  return withServerSpan('swarmclaw.chat.turn', {
+    'swarmclaw.session.id': sessionId,
+    'swarmclaw.chat.source': source,
+    'swarmclaw.chat.has_image': Boolean(input.imagePath || input.imageUrl),
+    'swarmclaw.chat.attached_file_count': input.attachedFiles?.length || 0,
+  }, async (span) => {
+    const endTurnPerf = perf.start('chat-execution', 'executeSessionChatTurn', { sessionId, source })
+    const preparedTurn = await prepareChatTurn(input)
+    if (preparedTurn.kind === 'blocked') {
+      const result = await completeBlockedChatTurn(preparedTurn)
+      setSpanAttributes(span, {
+        'swarmclaw.chat.blocked': true,
+        'swarmclaw.chat.tool_event_count': result.toolEvents.length,
+        'swarmclaw.chat.error': Boolean(result.error),
+        'gen_ai.usage.input_tokens': result.inputTokens || 0,
+        'gen_ai.usage.output_tokens': result.outputTokens || 0,
+      })
+      endTurnPerf({
+        durationMs: 0,
+        toolEventCount: result.toolEvents.length,
+        inputTokens: result.inputTokens || 0,
+        outputTokens: result.outputTokens || 0,
+        error: !!result.error,
+      })
+      return result
+    }
 
-  const partialPersistence = createPartialAssistantPersistence({
-    prepared: preparedTurn,
-    onEvent: input.onEvent,
-  })
+    setSpanAttributes(span, {
+      'swarmclaw.chat.blocked': false,
+      'swarmclaw.chat.agentic': preparedTurn.hasExtensions,
+      'swarmclaw.chat.provider': preparedTurn.providerType,
+      'gen_ai.request.model': preparedTurn.sessionForRun.model,
+    })
 
-  const preflight = await runChatTurnPreflight({
-    prepared: preparedTurn,
-    emit: partialPersistence.emit,
-    toolEvents: partialPersistence.getToolEvents(),
-  })
+    const partialPersistence = createPartialAssistantPersistence({
+      prepared: preparedTurn,
+      onEvent: input.onEvent,
+    })
 
-  if (preflight?.terminalResult) {
-    if (preflight.terminalResult.text) input.onEvent?.({ t: 'd', text: preflight.terminalResult.text })
-    partialPersistence.stop()
-    await partialPersistence.awaitIdle()
-    endTurnPerf({
-      durationMs: 0,
-      toolEventCount: preflight.terminalResult.toolEvents.length,
-      inputTokens: preflight.terminalResult.inputTokens || 0,
-      outputTokens: preflight.terminalResult.outputTokens || 0,
-      error: !!preflight.terminalResult.error,
+    const preflight = await runChatTurnPreflight({
+      prepared: preparedTurn,
+      emit: partialPersistence.emit,
+      toolEvents: partialPersistence.getToolEvents(),
     })
-    return preflight.terminalResult
-  }
 
-  let streamResult: Awaited<ReturnType<typeof executePreparedChatTurn>>
-  try {
-    streamResult = await executePreparedChatTurn({
+    if (preflight?.terminalResult) {
+      if (preflight.terminalResult.text) input.onEvent?.({ t: 'd', text: preflight.terminalResult.text })
+      partialPersistence.stop()
+      await partialPersistence.awaitIdle()
+      setSpanAttributes(span, {
+        'swarmclaw.chat.preflight_terminal': true,
+        'swarmclaw.chat.tool_event_count': preflight.terminalResult.toolEvents.length,
+        'swarmclaw.chat.error': Boolean(preflight.terminalResult.error),
+        'gen_ai.usage.input_tokens': preflight.terminalResult.inputTokens || 0,
+        'gen_ai.usage.output_tokens': preflight.terminalResult.outputTokens || 0,
+      })
+      endTurnPerf({
+        durationMs: 0,
+        toolEventCount: preflight.terminalResult.toolEvents.length,
+        inputTokens: preflight.terminalResult.inputTokens || 0,
+        outputTokens: preflight.terminalResult.outputTokens || 0,
+        error: !!preflight.terminalResult.error,
+      })
+      return preflight.terminalResult
+    }
+
+    let streamResult: Awaited<ReturnType<typeof executePreparedChatTurn>>
+    try {
+      streamResult = await executePreparedChatTurn({
+        input,
+        prepared: preparedTurn,
+        partialPersistence,
+        preflightToolRoutingResult: preflight?.directMemoryResult || null,
+      })
+
+      await partialPersistence.awaitIdle()
+    } finally {
+      partialPersistence.stop()
+    }
+
+    if (!streamResult.errorMessage) {
+      markProviderSuccess(preparedTurn.providerType, preparedTurn.sessionForRun.credentialId)
+    }
+
+    const result = await finalizeChatTurn({
       input,
       prepared: preparedTurn,
       partialPersistence,
-      preflightToolRoutingResult: preflight?.directMemoryResult || null,
+      fullResponse: streamResult.fullResponse,
+      errorMessage: streamResult.errorMessage,
+      initialToolRoutingResult: streamResult.toolRoutingResult,
+      responseCacheHit: streamResult.responseCacheHit,
+      directUsage: streamResult.directUsage,
+      durationMs: streamResult.durationMs,
+      knowledgeRetrievalTrace: streamResult.knowledgeRetrievalTrace || null,
+      emit: partialPersistence.emit,
     })
 
-    await partialPersistence.awaitIdle()
-  } finally {
-    partialPersistence.stop()
-  }
-
-  if (!streamResult.errorMessage) {
-    markProviderSuccess(preparedTurn.providerType, preparedTurn.sessionForRun.credentialId)
-  }
-
-  const result = await finalizeChatTurn({
-    input,
-    prepared: preparedTurn,
-    partialPersistence,
-    fullResponse: streamResult.fullResponse,
-    errorMessage: streamResult.errorMessage,
-    initialToolRoutingResult: streamResult.toolRoutingResult,
-    responseCacheHit: streamResult.responseCacheHit,
-    directUsage: streamResult.directUsage,
-    durationMs: streamResult.durationMs,
-    knowledgeRetrievalTrace: streamResult.knowledgeRetrievalTrace || null,
-    emit: partialPersistence.emit,
-  })
+    setSpanAttributes(span, {
+      'swarmclaw.chat.cache_hit': streamResult.responseCacheHit,
+      'swarmclaw.chat.tool_event_count': result.toolEvents.length,
+      'swarmclaw.chat.error': Boolean(result.error),
+      'swarmclaw.chat.estimated_cost': result.estimatedCost ?? 0,
+      'swarmclaw.chat.has_retrieval_trace': Boolean(result.retrievalTrace),
+      'gen_ai.usage.input_tokens': result.inputTokens || 0,
+      'gen_ai.usage.output_tokens': result.outputTokens || 0,
+    })
+    endTurnPerf({
+      durationMs: streamResult.durationMs,
+      toolEventCount: result.toolEvents.length,
+      inputTokens: result.inputTokens || 0,
+      outputTokens: result.outputTokens || 0,
+      error: !!result.error,
+    })
 
-  endTurnPerf({
-    durationMs: streamResult.durationMs,
-    toolEventCount: result.toolEvents.length,
-    inputTokens: result.inputTokens || 0,
-    outputTokens: result.outputTokens || 0,
-    error: !!result.error,
+    return result
   })
-
-  return result
 }

package/src/lib/server/chat-execution/chat-turn-stream-execution.ts

@@ -22,6 +22,7 @@ import {
 import { perf } from '@/lib/server/runtime/perf'
 import { getSessionMessages } from '@/lib/server/sessions/session-repository'
 import { notify } from '@/lib/server/ws-hub'
+import { setSpanAttributes, withServerSpan } from '@/lib/server/observability/otel-tracing'
 import { errorMessage as toErrorMessage } from '@/lib/shared-utils'
 
 import type { ExecuteChatTurnInput } from './chat-execution-types'
@@ -142,22 +143,34 @@ export async function executePreparedChatTurn(params: {
     )
 
     if (hasExtensions) {
-      const result = await streamAgentChat({
-        session: sessionForRun,
-        message: effectiveMessage,
-        imagePath: resolvedImagePath,
-        imageUrl,
-        attachedFiles,
-        apiKey,
-        systemPrompt,
-        executionBrief,
-        extraSystemContext: [executionBriefContextBlock].filter((value): value is string => typeof value === 'string' && value.trim().length > 0),
-        write: (raw) => parseAndEmit(raw),
-        history: heartbeatHistory ?? applyContextClearBoundary(getSessionMessages(sessionId)),
-        signal: abortController.signal,
-        source,
-        classification,
-        promptMode,
+      const result = await withServerSpan('swarmclaw.chat.agentic_stream', {
+        'swarmclaw.session.id': sessionId,
+        'swarmclaw.chat.source': source,
+        'swarmclaw.chat.provider': providerType,
+        'gen_ai.request.model': sessionForRun.model,
+      }, async (span) => {
+        const agenticResult = await streamAgentChat({
+          session: sessionForRun,
+          message: effectiveMessage,
+          imagePath: resolvedImagePath,
+          imageUrl,
+          attachedFiles,
+          apiKey,
+          systemPrompt,
+          executionBrief,
+          extraSystemContext: [executionBriefContextBlock].filter((value): value is string => typeof value === 'string' && value.trim().length > 0),
+          write: (raw) => parseAndEmit(raw),
+          history: heartbeatHistory ?? applyContextClearBoundary(getSessionMessages(sessionId)),
+          signal: abortController.signal,
+          source,
+          classification,
+          promptMode,
+        })
+        setSpanAttributes(span, {
+          'swarmclaw.chat.tool_event_count': agenticResult.toolEvents.length,
+          'swarmclaw.chat.has_retrieval_trace': Boolean(agenticResult.knowledgeRetrievalTrace),
+        })
+        return agenticResult
       })
       fullResponse = result.finalResponse || result.fullText
       knowledgeRetrievalTrace = result.knowledgeRetrievalTrace || null
@@ -232,7 +245,20 @@ export async function executePreparedChatTurn(params: {
           signal: abortController.signal,
         })
         try {
-          fullResponse = await doStreamChat()
+          fullResponse = await withServerSpan('swarmclaw.chat.model_stream', {
+            'swarmclaw.session.id': sessionId,
+            'swarmclaw.chat.source': source,
+            'swarmclaw.chat.provider': providerType,
+            'gen_ai.request.model': sessionForRun.model,
+          }, async (span) => {
+            const response = await doStreamChat()
+            setSpanAttributes(span, {
+              'gen_ai.usage.input_tokens': directUsage.inputTokens || 0,
+              'gen_ai.usage.output_tokens': directUsage.outputTokens || 0,
+              'swarmclaw.chat.response_cacheable': canUseResponseCache,
+            })
+            return response
+          })
         } catch (streamErr: unknown) {
           const streamErrMsg = toErrorMessage(streamErr)
           const streamStatus = (streamErr as Record<string, unknown>)?.status
@@ -243,7 +269,20 @@ export async function executePreparedChatTurn(params: {
               historyLen: directHistorySnapshot.length,
             })
             directHistorySnapshot = directHistorySnapshot.slice(-10)
-            fullResponse = await doStreamChat()
+            fullResponse = await withServerSpan('swarmclaw.chat.model_stream.retry', {
+              'swarmclaw.session.id': sessionId,
+              'swarmclaw.chat.source': source,
+              'swarmclaw.chat.provider': providerType,
+              'gen_ai.request.model': sessionForRun.model,
+              'swarmclaw.chat.retry_reason': 'context_overflow',
+            }, async (span) => {
+              const response = await doStreamChat()
+              setSpanAttributes(span, {
+                'gen_ai.usage.input_tokens': directUsage.inputTokens || 0,
+                'gen_ai.usage.output_tokens': directUsage.outputTokens || 0,
+              })
+              return response
+            })
           } else {
             throw streamErr
           }

package/src/lib/server/observability/otel-config.test.ts

@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import {
+  parseOtelHeaders,
+  resolveOtelConfig,
+  resolveOtelTracesEndpoint,
+} from '@/lib/server/observability/otel-config'
+
+function env(overrides: Record<string, string>): NodeJS.ProcessEnv {
+  return {
+    NODE_ENV: 'test',
+    ...overrides,
+  }
+}
+
+describe('otel config', () => {
+  it('stays disabled unless OTEL_ENABLED is truthy', () => {
+    assert.equal(resolveOtelConfig(env({ OTEL_EXPORTER_OTLP_ENDPOINT: 'http://localhost:4318' })), null)
+  })
+
+  it('normalizes a base OTLP endpoint to the traces path', () => {
+    assert.equal(
+      resolveOtelTracesEndpoint(env({
+        OTEL_EXPORTER_OTLP_ENDPOINT: 'https://collector.example.com:4318',
+      })),
+      'https://collector.example.com:4318/v1/traces',
+    )
+  })
+
+  it('prefers an explicit OTLP traces endpoint', () => {
+    assert.equal(
+      resolveOtelTracesEndpoint(env({
+        OTEL_EXPORTER_OTLP_ENDPOINT: 'https://collector.example.com:4318',
+        OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: 'https://collector.example.com/custom/traces',
+      })),
+      'https://collector.example.com/custom/traces',
+    )
+  })
+
+  it('parses OTLP headers and applies the default service name', () => {
+    const config = resolveOtelConfig(env({
+      OTEL_ENABLED: 'true',
+      OTEL_EXPORTER_OTLP_ENDPOINT: 'https://collector.example.com:4318',
+      OTEL_EXPORTER_OTLP_HEADERS: 'Authorization=Bearer token, X-Team = swarm ',
+    }))
+
+    assert.ok(config)
+    assert.equal(config.serviceName, 'swarmclaw')
+    assert.deepEqual(config.headers, {
+      Authorization: 'Bearer token',
+      'X-Team': 'swarm',
+    })
+    assert.equal(config.tracesEndpoint, 'https://collector.example.com:4318/v1/traces')
+  })
+
+  it('ignores malformed header entries', () => {
+    assert.deepEqual(parseOtelHeaders('good=value, broken, =oops, missing='), {
+      good: 'value',
+    })
+  })
+})

package/src/lib/server/observability/otel-config.ts

@@ -0,0 +1,67 @@
+export interface OTelConfig {
+  enabled: true
+  serviceName: string
+  tracesEndpoint: string
+  headers: Record<string, string>
+}
+
+function parseBooleanFlag(value: string | undefined): boolean {
+  if (typeof value !== 'string') return false
+  const normalized = value.trim().toLowerCase()
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on'
+}
+
+function cleanEnvValue(value: string | undefined): string | null {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed ? trimmed : null
+}
+
+export function resolveOtelTracesEndpoint(env: NodeJS.ProcessEnv = process.env): string | null {
+  const tracesEndpoint = cleanEnvValue(env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT)
+  if (tracesEndpoint) return tracesEndpoint.replace(/\/+$/, '')
+
+  const baseEndpoint = cleanEnvValue(env.OTEL_EXPORTER_OTLP_ENDPOINT)
+  if (!baseEndpoint) return null
+
+  const normalizedBase = baseEndpoint.replace(/\/+$/, '')
+  if (!normalizedBase) return null
+  if (normalizedBase.endsWith('/v1/traces')) return normalizedBase
+  return `${normalizedBase}/v1/traces`
+}
+
+export function parseOtelHeaders(value: string | undefined): Record<string, string> {
+  if (typeof value !== 'string') return {}
+  const entries = value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+
+  const headers: Record<string, string> = {}
+  for (const entry of entries) {
+    const separatorIndex = entry.indexOf('=')
+    if (separatorIndex <= 0) continue
+    const key = entry.slice(0, separatorIndex).trim()
+    const headerValue = entry.slice(separatorIndex + 1).trim()
+    if (!key || !headerValue) continue
+    headers[key] = headerValue
+  }
+  return headers
+}
+
+export function resolveOtelConfig(env: NodeJS.ProcessEnv = process.env): OTelConfig | null {
+  if (!parseBooleanFlag(env.OTEL_ENABLED)) return null
+
+  const tracesEndpoint = resolveOtelTracesEndpoint(env)
+  if (!tracesEndpoint) return null
+
+  const serviceName = cleanEnvValue(env.OTEL_SERVICE_NAME) || 'swarmclaw'
+  const headers = parseOtelHeaders(env.OTEL_EXPORTER_OTLP_TRACES_HEADERS || env.OTEL_EXPORTER_OTLP_HEADERS)
+
+  return {
+    enabled: true,
+    serviceName,
+    tracesEndpoint,
+    headers,
+  }
+}

package/src/lib/server/observability/otel-tracing.ts

@@ -0,0 +1,52 @@
+import {
+  trace,
+  SpanStatusCode,
+  type Attributes,
+  type AttributeValue,
+  type Span,
+} from '@opentelemetry/api'
+import { errorMessage } from '@/lib/shared-utils'
+
+type SpanAttributeInput = Record<string, AttributeValue | null | undefined>
+
+function sanitizeAttributes(attributes?: SpanAttributeInput): Attributes | undefined {
+  if (!attributes) return undefined
+  const cleaned: Attributes = {}
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value === undefined || value === null) continue
+    cleaned[key] = value
+  }
+  return Object.keys(cleaned).length > 0 ? cleaned : undefined
+}
+
+export function setSpanAttributes(span: Span, attributes?: SpanAttributeInput): void {
+  const cleaned = sanitizeAttributes(attributes)
+  if (!cleaned) return
+  span.setAttributes(cleaned)
+}
+
+export function recordSpanError(span: Span, err: unknown): void {
+  span.recordException(err instanceof Error ? err : new Error(errorMessage(err)))
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: errorMessage(err),
+  })
+}
+
+export async function withServerSpan<T>(
+  name: string,
+  attributes: SpanAttributeInput | undefined,
+  fn: (span: Span) => Promise<T> | T,
+): Promise<T> {
+  const tracer = trace.getTracer('swarmclaw.runtime')
+  return tracer.startActiveSpan(name, { attributes: sanitizeAttributes(attributes) }, async (span) => {
+    try {
+      return await fn(span)
+    } catch (err) {
+      recordSpanError(span, err)
+      throw err
+    } finally {
+      span.end()
+    }
+  })
+}

package/src/lib/server/observability/otel.ts

@@ -0,0 +1,79 @@
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { log } from '@/lib/server/logger'
+import { hmrSingleton } from '@/lib/shared-utils'
+import { resolveOtelConfig } from '@/lib/server/observability/otel-config'
+
+const TAG = 'otel'
+
+interface OTelState {
+  started: boolean
+  startPromise: Promise<boolean> | null
+  sdk: NodeSDK | null
+}
+
+const otelState = hmrSingleton<OTelState>('__swarmclaw_otel_state__', () => ({
+  started: false,
+  startPromise: null,
+  sdk: null,
+}))
+
+export function isOtelEnabled(): boolean {
+  return resolveOtelConfig() !== null
+}
+
+export async function ensureOpenTelemetryStarted(): Promise<boolean> {
+  const config = resolveOtelConfig()
+  if (!config) return false
+  if (otelState.started) return true
+  if (otelState.startPromise) return otelState.startPromise
+
+  otelState.startPromise = (async () => {
+    try {
+      process.env.OTEL_SERVICE_NAME = process.env.OTEL_SERVICE_NAME || config.serviceName
+      const exporter = new OTLPTraceExporter({
+        url: config.tracesEndpoint,
+        headers: Object.keys(config.headers).length > 0 ? config.headers : undefined,
+      })
+      const sdk = new NodeSDK({
+        traceExporter: exporter,
+      })
+      sdk.start()
+      otelState.sdk = sdk
+      otelState.started = true
+      log.info(TAG, 'OpenTelemetry OTLP tracing enabled', {
+        serviceName: config.serviceName,
+        tracesEndpoint: config.tracesEndpoint,
+      })
+      return true
+    } catch (err) {
+      otelState.sdk = null
+      otelState.started = false
+      log.error(TAG, 'Failed to initialize OpenTelemetry tracing', err)
+      return false
+    } finally {
+      otelState.startPromise = null
+    }
+  })()
+
+  return otelState.startPromise
+}
+
+export async function shutdownOpenTelemetry(): Promise<void> {
+  const sdk = otelState.sdk
+  if (!sdk) {
+    otelState.started = false
+    otelState.startPromise = null
+    return
+  }
+
+  otelState.sdk = null
+  otelState.started = false
+  otelState.startPromise = null
+
+  try {
+    await sdk.shutdown()
+  } catch (err) {
+    log.warn(TAG, 'Failed to flush OpenTelemetry tracing during shutdown', err)
+  }
+}

package/src/lib/server/protocols/protocol-run-lifecycle.ts

@@ -39,6 +39,7 @@ import {
   syncProtocolParentFromChildRun,
 } from '@/lib/server/protocols/protocol-step-helpers'
 import { stepProtocolRun } from '@/lib/server/protocols/protocol-step-processors'
+import { setSpanAttributes, withServerSpan } from '@/lib/server/observability/otel-tracing'
 
 // ---- Singletons ----
 
@@ -308,79 +309,91 @@ export async function runProtocolRun(runId: string, deps?: ProtocolRunDeps): Pro
     return loadProtocolRunById(runId)
   }
   try {
-    let run = loadProtocolRunById(runId)
-    if (!run) return null
-    if (run.status === 'cancelled' || run.status === 'archived' || run.status === 'completed' || run.status === 'paused') return run
-    run = persistRun({
-      ...run,
-      status: run.status === 'waiting' ? 'running' : run.status,
-      waitingReason: null,
-      pauseReason: null,
-      lastError: null,
-      startedAt: run.startedAt || now(deps),
-      updatedAt: now(deps),
-    })
-    if (run.parentRunId) syncProtocolParentFromChildRun(run, deps)
+    return await withServerSpan('swarmclaw.protocol.run', {
+      'swarmclaw.protocol.run_id': runId,
+    }, async (span) => {
+      let run = loadProtocolRunById(runId)
+      if (!run) return null
+      setSpanAttributes(span, {
+        'swarmclaw.protocol.template_id': run.templateId,
+        'swarmclaw.protocol.source_kind': run.sourceRef.kind,
+        'swarmclaw.protocol.participant_count': run.participantAgentIds.length,
+        'swarmclaw.protocol.status': run.status,
+      })
+      if (run.status === 'cancelled' || run.status === 'archived' || run.status === 'completed' || run.status === 'paused') return run
+      run = persistRun({
+        ...run,
+        status: run.status === 'waiting' ? 'running' : run.status,
+        waitingReason: null,
+        pauseReason: null,
+        lastError: null,
+        startedAt: run.startedAt || now(deps),
+        updatedAt: now(deps),
+      })
+      if (run.parentRunId) syncProtocolParentFromChildRun(run, deps)
 
-    const MAX_STEP_ITERATIONS = 500
-    let stepIterations = 0
-    while (run.status === 'running' || run.status === 'draft') {
-      stepIterations++
-      if (stepIterations > MAX_STEP_ITERATIONS) {
-        run = persistRun({ ...run, status: 'failed', lastError: `Exceeded maximum step iterations (${MAX_STEP_ITERATIONS}). Possible infinite loop in step graph.`, updatedAt: now(deps) })
-        appendProtocolEvent(run.id, { type: 'failed', summary: `Exceeded maximum step iterations (${MAX_STEP_ITERATIONS}).` }, deps)
-        break
-      }
-      if (shouldYieldBetweenProtocolSteps(deps)) {
-        // Yield between steps in the fire-and-forget runtime so I/O, HTTP responses,
-        // and timers can run.
-        await new Promise(r => setTimeout(r, 0))
-      }
-      const latest = loadProtocolRunById(run.id)
-      if (!latest) return null
-      if (latest.status === 'paused' || latest.status === 'cancelled' || latest.status === 'archived' || latest.status === 'completed') {
+      const MAX_STEP_ITERATIONS = 500
+      let stepIterations = 0
+      while (run.status === 'running' || run.status === 'draft') {
+        stepIterations++
+        if (stepIterations > MAX_STEP_ITERATIONS) {
+          run = persistRun({ ...run, status: 'failed', lastError: `Exceeded maximum step iterations (${MAX_STEP_ITERATIONS}). Possible infinite loop in step graph.`, updatedAt: now(deps) })
+          appendProtocolEvent(run.id, { type: 'failed', summary: `Exceeded maximum step iterations (${MAX_STEP_ITERATIONS}).` }, deps)
+          break
+        }
+        if (shouldYieldBetweenProtocolSteps(deps)) {
+          // Yield between steps in the fire-and-forget runtime so I/O, HTTP responses,
+          // and timers can run.
+          await new Promise(r => setTimeout(r, 0))
+        }
+        const latest = loadProtocolRunById(run.id)
+        if (!latest) return null
+        if (latest.status === 'paused' || latest.status === 'cancelled' || latest.status === 'archived' || latest.status === 'completed') {
+          run = latest
+          break
+        }
         run = latest
-        break
-      }
-      run = latest
-      renewProtocolLease(run.id)
+        renewProtocolLease(run.id)
 
-      // DAG scheduler: compute step readiness before stepping
-      const sched = computeStepReadiness(run.steps || [], run.entryStepId || null, run.stepState)
-      if (sched.dagMode) {
-        run = persistRun({
-          ...run,
-          stepState: sched.stepState,
-          completedStepIds: sched.completedStepIds,
-          runningStepIds: sched.runningStepIds,
-          readyStepIds: sched.readyStepIds,
-          failedStepIds: sched.failedStepIds,
-          updatedAt: now(deps),
-        })
-        if (sched.readyStepIds.length === 0 && sched.runningStepIds.length === 0) {
-          // No more work — either all done or stuck
-          const allSteps = run.steps || []
-          const allCompleted = allSteps.every((s) => sched.stepState[s.id]?.status === 'completed')
-          if (allCompleted) {
-            run = completeProtocolRun(run, deps)
-          } else {
-            run = persistRun({ ...run, status: 'failed', lastError: 'DAG stuck: no ready steps and not all completed.', updatedAt: now(deps) })
-            appendProtocolEvent(run.id, { type: 'failed', summary: 'DAG stuck: no ready steps and not all completed.' }, deps)
+        const sched = computeStepReadiness(run.steps || [], run.entryStepId || null, run.stepState)
+        if (sched.dagMode) {
+          run = persistRun({
+            ...run,
+            stepState: sched.stepState,
+            completedStepIds: sched.completedStepIds,
+            runningStepIds: sched.runningStepIds,
+            readyStepIds: sched.readyStepIds,
+            failedStepIds: sched.failedStepIds,
+            updatedAt: now(deps),
+          })
+          if (sched.readyStepIds.length === 0 && sched.runningStepIds.length === 0) {
+            const allSteps = run.steps || []
+            const allCompleted = allSteps.every((s) => sched.stepState[s.id]?.status === 'completed')
+            if (allCompleted) {
+              run = completeProtocolRun(run, deps)
+            } else {
+              run = persistRun({ ...run, status: 'failed', lastError: 'DAG stuck: no ready steps and not all completed.', updatedAt: now(deps) })
+              appendProtocolEvent(run.id, { type: 'failed', summary: 'DAG stuck: no ready steps and not all completed.' }, deps)
+            }
+            break
+          }
+          if (sched.readyStepIds.length > 0) {
+            const nextReadyId = sched.readyStepIds[0]
+            run = persistRun({ ...run, currentStepId: nextReadyId, updatedAt: now(deps) })
           }
-          break
-        }
-        if (sched.readyStepIds.length > 0) {
-          // Pick first ready step as currentStepId
-          const nextReadyId = sched.readyStepIds[0]
-          run = persistRun({ ...run, currentStepId: nextReadyId, updatedAt: now(deps) })
         }
-      }
 
-      run = await stepProtocolRun(run, deps)
-      if (run.status === 'waiting' || run.status === 'paused' || run.status === 'failed' || run.status === 'cancelled' || run.status === 'archived' || run.status === 'completed') break
-    }
-    if (run.parentRunId) syncProtocolParentFromChildRun(run, deps)
-    return run
+        run = await stepProtocolRun(run, deps)
+        if (run.status === 'waiting' || run.status === 'paused' || run.status === 'failed' || run.status === 'cancelled' || run.status === 'archived' || run.status === 'completed') break
+      }
+      setSpanAttributes(span, {
+        'swarmclaw.protocol.step_iterations': stepIterations,
+        'swarmclaw.protocol.status': run.status,
+        'swarmclaw.protocol.current_step_id': run.currentStepId,
+      })
+      if (run.parentRunId) syncProtocolParentFromChildRun(run, deps)
+      return run
+    })
   } catch (err: unknown) {
     const failed = updateRun(runId, (current) => ({
       ...current,

package/src/lib/server/session-tools/index.ts

@@ -58,6 +58,7 @@ import {
   isExternalExtensionId,
   splitCapabilityIds,
 } from '@/lib/capability-selection'
+import { setSpanAttributes, withServerSpan } from '@/lib/server/observability/otel-tracing'
 
 export type { ToolContext, SessionToolsResult }
 export { sweepOrphanedBrowsers, cleanupSessionBrowser, getActiveBrowserCount, hasActiveBrowser }
@@ -388,65 +389,80 @@ export async function buildSessionTools(cwd: string, enabledExtensions: string[]
       const schema = (candidate as unknown as { schema?: z.ZodTypeAny }).schema || z.object({}).passthrough()
       return tool(
         async (args) => {
-          // Check abort before executing any tool — prevents wasted work after chat stop
-          if (abortSignalRef.signal?.aborted) {
-            throw new DOMException('Tool execution aborted', 'AbortError')
-          }
-          const normalizedArgs = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
-          const hookSession = resolveCurrentSession() || buildFallbackHookSession()
-          // Enforce file access policy before execution
-          if (fileAccessPolicy) {
-            const denial = enforceFileAccessPolicy(candidate.name, normalizedArgs, cwd, fileAccessPolicy)
-            if (denial) return denial
-          }
-          let guardedArgs: Record<string, unknown> | null = normalizedArgs
-          if (ctx?.beforeToolCall) {
-            const guardResult = await ctx.beforeToolCall({
-              session: hookSession,
-              toolName: candidate.name,
-              input: guardedArgs,
-              runId: ctx.runId,
-            })
-            if (guardResult?.warning) {
-              ctx.onToolCallWarning?.({
+          return withServerSpan('swarmclaw.tool.call', {
+            'swarmclaw.tool.name': candidate.name,
+            'swarmclaw.session.id': ctx?.sessionId || null,
+            'swarmclaw.agent.id': ctx?.agentId || null,
+            'swarmclaw.run.id': ctx?.runId || null,
+          }, async (span) => {
+            // Check abort before executing any tool — prevents wasted work after chat stop
+            if (abortSignalRef.signal?.aborted) {
+              setSpanAttributes(span, { 'swarmclaw.tool.aborted': true })
+              throw new DOMException('Tool execution aborted', 'AbortError')
+            }
+            const normalizedArgs = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
+            const hookSession = resolveCurrentSession() || buildFallbackHookSession()
+            if (fileAccessPolicy) {
+              const denial = enforceFileAccessPolicy(candidate.name, normalizedArgs, cwd, fileAccessPolicy)
+              if (denial) {
+                setSpanAttributes(span, { 'swarmclaw.tool.blocked': true })
+                return denial
+              }
+            }
+            let guardedArgs: Record<string, unknown> | null = normalizedArgs
+            if (ctx?.beforeToolCall) {
+              const guardResult = await ctx.beforeToolCall({
+                session: hookSession,
                 toolName: candidate.name,
-                message: guardResult.warning,
+                input: guardedArgs,
+                runId: ctx.runId,
               })
+              if (guardResult?.warning) {
+                ctx.onToolCallWarning?.({
+                  toolName: candidate.name,
+                  message: guardResult.warning,
+                })
+              }
+              if (typeof guardResult?.blockReason === 'string' && guardResult.blockReason.trim()) {
+                setSpanAttributes(span, { 'swarmclaw.tool.blocked': true })
+                throw new Error(guardResult.blockReason.trim())
+              }
+              if (guardResult && 'input' in guardResult) {
+                guardedArgs = guardResult.input === undefined ? guardedArgs : guardResult.input ?? null
+              }
             }
-            if (typeof guardResult?.blockReason === 'string' && guardResult.blockReason.trim()) {
-              throw new Error(guardResult.blockReason.trim())
+            const hookResult = await runCapabilityBeforeToolCall(
+              {
+                session: hookSession,
+                toolName: candidate.name,
+                input: guardedArgs,
+                runId: ctx?.runId || undefined,
+              },
+              { enabledIds: activeExtensions },
+            )
+            if (hookResult.warning) {
+              ctx?.onToolCallWarning?.({
+                toolName: candidate.name,
+                message: hookResult.warning,
+              })
             }
-            if (guardResult && 'input' in guardResult) {
-              guardedArgs = guardResult.input === undefined ? guardedArgs : guardResult.input ?? null
+            if (hookResult.blockReason) {
+              setSpanAttributes(span, { 'swarmclaw.tool.blocked': true })
+              throw new Error(hookResult.blockReason)
             }
-          }
-          const hookResult = await runCapabilityBeforeToolCall(
-            {
-              session: hookSession,
-              toolName: candidate.name,
-              input: guardedArgs,
-              runId: ctx?.runId || undefined,
-            },
-            { enabledIds: activeExtensions },
-          )
-          if (hookResult.warning) {
-            ctx?.onToolCallWarning?.({
-              toolName: candidate.name,
-              message: hookResult.warning,
+            const effectiveArgs = hookResult.input ?? guardedArgs
+            const result = await candidate.invoke(effectiveArgs ?? {})
+            const outputText = typeof result === 'string' ? result : JSON.stringify(result)
+            setSpanAttributes(span, {
+              'swarmclaw.tool.output_bytes': Buffer.byteLength(outputText, 'utf-8'),
             })
-          }
-          if (hookResult.blockReason) {
-            throw new Error(hookResult.blockReason)
-          }
-          const effectiveArgs = hookResult.input ?? guardedArgs
-          const result = await candidate.invoke(effectiveArgs ?? {})
-          const outputText = typeof result === 'string' ? result : JSON.stringify(result)
-          await runCapabilityHook(
-            'afterToolExec',
-            { session: hookSession, toolName: candidate.name, input: effectiveArgs, output: outputText },
-            { enabledIds: activeExtensions },
-          )
-          return outputText
+            await runCapabilityHook(
+              'afterToolExec',
+              { session: hookSession, toolName: candidate.name, input: effectiveArgs, output: outputText },
+              { enabledIds: activeExtensions },
+            )
+            return outputText
+          })
         },
         {
           name: candidate.name,

package/src/proxy.ts

@@ -91,6 +91,7 @@ export function proxy(request: NextRequest) {
   if (
     !pathname.startsWith('/api/')
     || pathname === '/api/auth'
+    || pathname === '/api/healthz'
     || isWebhookTrigger
     || isConnectorWebhook
   ) {