@ultrathink-solutions/openclaw-logfire 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `@ultrathink-solutions/openclaw-logfire` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-15
+
+### Added
+
+- Initial release
+- Full agent lifecycle tracing with OTEL GenAI semantic conventions
+- `invoke_agent` root spans with agent name, session key, workspace, and channel attribution
+- `execute_tool` child spans with tool arguments, duration, and result size
+- Error tracing with OTEL exception events (type, message, stack trace)
+- Token usage metrics (`gen_ai.client.token.usage` histogram)
+- Operation duration metrics (`gen_ai.client.operation.duration` histogram)
+- Pydantic Logfire OTLP HTTP export (US and EU regions)
+- Clickable Logfire trace URLs in agent logs
+- Secret redaction for API keys, platform tokens, JWTs, and credentials
+- W3C traceparent injection into HTTP commands for distributed tracing
+- W3C trace context extraction from inbound webhook headers
+- Configurable trace depth (tool input/output capture, message content, inference events)
+- Batch and simple span processor modes
+- Zero-config quickstart (just set `LOGFIRE_TOKEN`)
+
+[0.1.0]: https://github.com/Ultrathink-Solutions/openclaw-logfire/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ultrathink Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# @ultrathink/openclaw-logfire
+
+Pydantic [Logfire](https://pydantic.dev/logfire) observability plugin for [OpenClaw](https://openclaw.ai).
+
+Full agent lifecycle tracing aligned with [OTEL GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) — tool calls, token metrics, error stack traces, and optional distributed tracing across services.
+
+## Quickstart
+
+```bash
+npm install @ultrathink/openclaw-logfire
+```
+
+Set your Logfire write token:
+
+```bash
+export LOGFIRE_TOKEN="your-token"
+```
+
+Add to `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "logfire": {
+        "enabled": true,
+        "config": {}
+      }
+    }
+  }
+}
+```
+
+Restart OpenClaw. That's it — traces appear in your Logfire dashboard.
+
+## What You Get
+
+### Span Hierarchy
+
+Every agent invocation produces a trace tree:
+
+```
+invoke_agent chief-of-staff          (root span)
+  |-- execute_tool Read              (file read)
+  |-- execute_tool exec              (shell command)
+  |-- execute_tool Write             (file write)
+  |-- execute_tool web_search        (web search)
+```
+
+### Attributes (OTEL GenAI Semantic Conventions)
+
+| Attribute | Example | Description |
+|-----------|---------|-------------|
+| `gen_ai.operation.name` | `invoke_agent` | Operation type |
+| `gen_ai.agent.name` | `chief-of-staff` | Agent identifier |
+| `gen_ai.conversation.id` | `session_abc123` | Session key |
+| `gen_ai.tool.name` | `Read` | Tool being called |
+| `gen_ai.tool.call.arguments` | `{"path": "/..."}` | Tool input (opt-in) |
+| `gen_ai.usage.input_tokens` | `1024` | Prompt tokens |
+| `gen_ai.usage.output_tokens` | `512` | Completion tokens |
+| `error.type` | `ToolExecutionError` | Error classification |
+| `exception.stacktrace` | `Error: ...` | Full stack trace |
+| `openclaw.workspace` | `chief-of-staff` | Workspace name |
+| `openclaw.channel` | `slack` | Message source |
+
+### Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `gen_ai.client.token.usage` | Histogram | Token counts by type (input/output) |
+| `gen_ai.client.operation.duration` | Histogram | Agent invocation latency (seconds) |
+
+### Error Tracing
+
+Tool failures include full OTEL exception events:
+
+- `exception.type` — Error class name
+- `exception.message` — Error description
+- `exception.stacktrace` — Full stack trace
+
+Errors propagate up the span tree so the root `invoke_agent` span is marked as errored.
+
+## Configuration
+
+All settings are optional. Sensible defaults work out of the box.
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "logfire": {
+        "enabled": true,
+        "config": {
+          // Logfire project (enables clickable trace links in logs)
+          "projectUrl": "https://logfire.pydantic.dev/myorg/myproject",
+          "region": "us",           // "us" or "eu"
+          "environment": "production",
+          "serviceName": "openclaw-agent",
+
+          // GenAI provider name for OTEL compliance
+          "providerName": "anthropic",
+
+          // Trace depth controls
+          "captureToolInput": true,       // Record tool arguments
+          "captureToolOutput": false,     // Record tool results (verbose)
+          "toolInputMaxLength": 2048,     // Truncation limit
+          "captureStackTraces": true,     // Stack traces on errors
+          "captureMessageContent": false, // Record message text (privacy)
+          "redactSecrets": true,          // Strip API keys from tool args
+
+          // Distributed tracing (opt-in)
+          "distributedTracing": {
+            "enabled": false,
+            "urlPatterns": ["https://api.mycompany.com/*"]
+          },
+
+          // Metrics
+          "enableMetrics": true,
+
+          // Trace links
+          "enableTraceLinks": true
+        }
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LOGFIRE_TOKEN` | Logfire write token (required) |
+| `LOGFIRE_ENVIRONMENT` | Deployment environment fallback |
+| `LOGFIRE_PROJECT_URL` | Project URL fallback |
+| `LOGFIRE_PROVIDER_NAME` | Provider name fallback |
+
+### Secret Redaction
+
+When `redactSecrets: true` (default), the plugin strips values matching common patterns before recording tool arguments:
+
+- API keys (`api_key: sk_live_...`)
+- Platform tokens (`ghp_`, `gho_`, `glpat_`, `xoxb-`, etc.)
+- JWTs (`eyJ...`)
+- Bearer tokens, passwords, credentials
+
+## Distributed Tracing
+
+Connect OpenClaw traces to your backend services. When enabled, the plugin injects `traceparent` headers into HTTP calls made by exec/Bash tools.
+
+```jsonc
+{
+  "distributedTracing": {
+    "enabled": true,
+    "injectIntoCommands": true,      // Add traceparent to curl/wget/httpie
+    "extractFromWebhooks": true,     // Extract traceparent from inbound webhooks
+    "urlPatterns": [                 // Only inject for matching URLs
+      "https://api.mycompany.com/*",
+      "http://localhost:8000/*"
+    ]
+  }
+}
+```
+
+This produces connected traces across services:
+
+```
+OpenClaw: invoke_agent chief-of-staff
+  |-- execute_tool exec (curl POST /v1/api)
+       |-- [Backend] FastAPI: POST /v1/api
+            |-- database query
+            |-- LLM call
+```
+
+Your backend must support W3C trace context extraction (most frameworks do: FastAPI with Logfire, Express with OTEL, etc.).
+
+## Architecture
+
+```
+openclaw-logfire/src/
+  index.ts              Plugin entry point + hook wiring
+  config.ts             Typed configuration with defaults
+  otel.ts               OTEL SDK initialization (Logfire OTLP)
+  hooks/
+    before-agent-start  invoke_agent span creation
+    before-tool-call    execute_tool span + context propagation
+    tool-result-persist Tool span close + errors + stack traces
+    agent-end           Span close + metrics + trace link
+    message-received    Channel attribution + inbound context
+  context/
+    span-store          Session -> active spans (LIFO tool stack)
+    propagation         W3C traceparent inject/extract
+  metrics/
+    genai-metrics       Token usage + operation duration histograms
+  events/
+    inference-details   Opt-in inference operation event
+```
+
+### OpenClaw Hooks Used
+
+| Hook | Purpose |
+|------|---------|
+| `before_agent_start` | Create root `invoke_agent` span |
+| `before_tool_call` | Create `execute_tool` child span |
+| `tool_result_persist` | Close tool span, record errors |
+| `agent_end` | Close spans, emit metrics |
+| `message_received` | Enrich with channel info |
+
+Requires OpenClaw >= 2026.2.1 (`before_tool_call` was wired in that version).
+
+## Development
+
+```bash
+git clone https://github.com/Ultrathink-Solutions/openclaw-logfire
+cd openclaw-logfire
+npm install
+npm run typecheck
+npm test
+```
+
+### Local testing with OpenClaw
+
+```bash
+# Symlink into OpenClaw extensions
+ln -s $(pwd) ~/.openclaw/extensions/openclaw-logfire
+
+# Or add to openclaw.json
+# "plugins": { "load": { "paths": ["./path/to/openclaw-logfire"] } }
+
+export LOGFIRE_TOKEN="your-write-token"
+openclaw restart
+openclaw plugins list  # Should show "logfire" as enabled
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Plugin configuration with sensible defaults.
+ *
+ * Every option can be left unset for a zero-config quickstart —
+ * just export LOGFIRE_TOKEN and enable the plugin.
+ */
+export interface DistributedTracingConfig {
+    enabled: boolean;
+    injectIntoCommands: boolean;
+    extractFromWebhooks: boolean;
+    urlPatterns: string[];
+}
+export interface BatchConfig {
+    maxQueueSize: number;
+    maxExportBatchSize: number;
+    scheduledDelayMs: number;
+}
+export interface LogfirePluginConfig {
+    token: string;
+    projectUrl: string;
+    region: 'us' | 'eu';
+    environment: string;
+    serviceName: string;
+    providerName: string;
+    captureToolInput: boolean;
+    captureToolOutput: boolean;
+    toolInputMaxLength: number;
+    toolOutputMaxLength: number;
+    captureStackTraces: boolean;
+    captureMessageContent: boolean;
+    captureToolDefinitions: boolean;
+    captureInferenceEvents: boolean;
+    redactSecrets: boolean;
+    distributedTracing: DistributedTracingConfig;
+    enableMetrics: boolean;
+    metricsIntervalMs: number;
+    enableTraceLinks: boolean;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    resourceAttributes: Record<string, string>;
+    spanProcessorType: 'batch' | 'simple';
+    batchConfig: BatchConfig;
+}
+/**
+ * Merge user-provided config with defaults and env vars.
+ * Env vars serve as fallbacks when explicit config is not set.
+ */
+export declare function resolveConfig(userConfig: Record<string, unknown> | undefined): LogfirePluginConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAElC,KAAK,EAAE,MAAM,CAAC;IAGd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IAGpB,YAAY,EAAE,MAAM,CAAC;IAGrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,sBAAsB,EAAE,OAAO,CAAC;IAChC,sBAAsB,EAAE,OAAO,CAAC;IAChC,aAAa,EAAE,OAAO,CAAC;IAGvB,kBAAkB,EAAE,wBAAwB,CAAC;IAG7C,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAG1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAG9C,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,iBAAiB,EAAE,OAAO,GAAG,QAAQ,CAAC;IACtC,WAAW,EAAE,WAAW,CAAC;CAC1B;AA0CD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC9C,mBAAmB,CAoFrB"}

package/dist/config.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Plugin configuration with sensible defaults.
+ *
+ * Every option can be left unset for a zero-config quickstart —
+ * just export LOGFIRE_TOKEN and enable the plugin.
+ */
+const DEFAULTS = {
+    token: '',
+    projectUrl: '',
+    region: 'us',
+    environment: '',
+    serviceName: 'openclaw-agent',
+    providerName: '',
+    captureToolInput: true,
+    captureToolOutput: false,
+    toolInputMaxLength: 2048,
+    toolOutputMaxLength: 512,
+    captureStackTraces: true,
+    captureMessageContent: false,
+    captureToolDefinitions: false,
+    captureInferenceEvents: false,
+    redactSecrets: true,
+    distributedTracing: {
+        enabled: false,
+        injectIntoCommands: true,
+        extractFromWebhooks: true,
+        urlPatterns: ['*'],
+    },
+    enableMetrics: true,
+    metricsIntervalMs: 60_000,
+    enableTraceLinks: true,
+    logLevel: 'info',
+    resourceAttributes: {},
+    spanProcessorType: 'batch',
+    batchConfig: {
+        maxQueueSize: 2048,
+        maxExportBatchSize: 512,
+        scheduledDelayMs: 5000,
+    },
+};
+/**
+ * Merge user-provided config with defaults and env vars.
+ * Env vars serve as fallbacks when explicit config is not set.
+ */
+export function resolveConfig(userConfig) {
+    const raw = userConfig ?? {};
+    const distributedTracingRaw = raw.distributedTracing ?? {};
+    const batchConfigRaw = raw.batchConfig ?? {};
+    return {
+        token: asString(raw.token) ||
+            process.env.LOGFIRE_TOKEN ||
+            '',
+        projectUrl: asString(raw.projectUrl) ||
+            process.env.LOGFIRE_PROJECT_URL ||
+            DEFAULTS.projectUrl,
+        region: asEnum(raw.region, ['us', 'eu']) ?? DEFAULTS.region,
+        environment: asString(raw.environment) ||
+            process.env.LOGFIRE_ENVIRONMENT ||
+            'development',
+        serviceName: asString(raw.serviceName) || DEFAULTS.serviceName,
+        providerName: asString(raw.providerName) ||
+            process.env.LOGFIRE_PROVIDER_NAME ||
+            DEFAULTS.providerName,
+        captureToolInput: asBool(raw.captureToolInput) ?? DEFAULTS.captureToolInput,
+        captureToolOutput: asBool(raw.captureToolOutput) ?? DEFAULTS.captureToolOutput,
+        toolInputMaxLength: asInt(raw.toolInputMaxLength) ?? DEFAULTS.toolInputMaxLength,
+        toolOutputMaxLength: asInt(raw.toolOutputMaxLength) ?? DEFAULTS.toolOutputMaxLength,
+        captureStackTraces: asBool(raw.captureStackTraces) ?? DEFAULTS.captureStackTraces,
+        captureMessageContent: asBool(raw.captureMessageContent) ?? DEFAULTS.captureMessageContent,
+        captureToolDefinitions: asBool(raw.captureToolDefinitions) ?? DEFAULTS.captureToolDefinitions,
+        captureInferenceEvents: asBool(raw.captureInferenceEvents) ?? DEFAULTS.captureInferenceEvents,
+        redactSecrets: asBool(raw.redactSecrets) ?? DEFAULTS.redactSecrets,
+        distributedTracing: {
+            enabled: asBool(distributedTracingRaw.enabled) ??
+                DEFAULTS.distributedTracing.enabled,
+            injectIntoCommands: asBool(distributedTracingRaw.injectIntoCommands) ??
+                DEFAULTS.distributedTracing.injectIntoCommands,
+            extractFromWebhooks: asBool(distributedTracingRaw.extractFromWebhooks) ??
+                DEFAULTS.distributedTracing.extractFromWebhooks,
+            urlPatterns: asStringArray(distributedTracingRaw.urlPatterns) ??
+                DEFAULTS.distributedTracing.urlPatterns,
+        },
+        enableMetrics: asBool(raw.enableMetrics) ?? DEFAULTS.enableMetrics,
+        metricsIntervalMs: asInt(raw.metricsIntervalMs) ?? DEFAULTS.metricsIntervalMs,
+        enableTraceLinks: asBool(raw.enableTraceLinks) ?? DEFAULTS.enableTraceLinks,
+        logLevel: asEnum(raw.logLevel, ['debug', 'info', 'warn', 'error']) ??
+            DEFAULTS.logLevel,
+        resourceAttributes: asStringRecord(raw.resourceAttributes) ?? DEFAULTS.resourceAttributes,
+        spanProcessorType: asEnum(raw.spanProcessorType, ['batch', 'simple']) ??
+            DEFAULTS.spanProcessorType,
+        batchConfig: {
+            maxQueueSize: asInt(batchConfigRaw.maxQueueSize) ?? DEFAULTS.batchConfig.maxQueueSize,
+            maxExportBatchSize: asInt(batchConfigRaw.maxExportBatchSize) ??
+                DEFAULTS.batchConfig.maxExportBatchSize,
+            scheduledDelayMs: asInt(batchConfigRaw.scheduledDelayMs) ??
+                DEFAULTS.batchConfig.scheduledDelayMs,
+        },
+    };
+}
+// --- type coercion helpers ---
+function asString(v) {
+    return typeof v === 'string' ? v : '';
+}
+function asBool(v) {
+    return typeof v === 'boolean' ? v : undefined;
+}
+function asInt(v) {
+    return typeof v === 'number' && Number.isInteger(v) ? v : undefined;
+}
+function asEnum(v, allowed) {
+    return typeof v === 'string' && allowed.includes(v)
+        ? v
+        : undefined;
+}
+function asStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === 'string')
+        ? v
+        : undefined;
+}
+function asStringRecord(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return undefined;
+    const entries = Object.entries(v);
+    if (entries.every(([, val]) => typeof val === 'string')) {
+        return v;
+    }
+    return undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B;;;;;GAKG;AAwDH,MAAM,QAAQ,GAAwB;IACpC,KAAK,EAAE,EAAE;IACT,UAAU,EAAE,EAAE;IACd,MAAM,EAAE,IAAI;IACZ,WAAW,EAAE,EAAE;IACf,WAAW,EAAE,gBAAgB;IAC7B,YAAY,EAAE,EAAE;IAEhB,gBAAgB,EAAE,IAAI;IACtB,iBAAiB,EAAE,KAAK;IACxB,kBAAkB,EAAE,IAAI;IACxB,mBAAmB,EAAE,GAAG;IACxB,kBAAkB,EAAE,IAAI;IACxB,qBAAqB,EAAE,KAAK;IAC5B,sBAAsB,EAAE,KAAK;IAC7B,sBAAsB,EAAE,KAAK;IAC7B,aAAa,EAAE,IAAI;IAEnB,kBAAkB,EAAE;QAClB,OAAO,EAAE,KAAK;QACd,kBAAkB,EAAE,IAAI;QACxB,mBAAmB,EAAE,IAAI;QACzB,WAAW,EAAE,CAAC,GAAG,CAAC;KACnB;IAED,aAAa,EAAE,IAAI;IACnB,iBAAiB,EAAE,MAAM;IAEzB,gBAAgB,EAAE,IAAI;IACtB,QAAQ,EAAE,MAAM;IAEhB,kBAAkB,EAAE,EAAE;IACtB,iBAAiB,EAAE,OAAO;IAC1B,WAAW,EAAE;QACX,YAAY,EAAE,IAAI;QAClB,kBAAkB,EAAE,GAAG;QACvB,gBAAgB,EAAE,IAAI;KACvB;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,UAA+C;IAE/C,MAAM,GAAG,GAAG,UAAU,IAAI,EAAE,CAAC;IAE7B,MAAM,qBAAqB,GACxB,GAAG,CAAC,kBAA8C,IAAI,EAAE,CAAC;IAC5D,MAAM,cAAc,GAAI,GAAG,CAAC,WAAuC,IAAI,EAAE,CAAC;IAE1E,OAAO;QACL,KAAK,EACH,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;YACnB,OAAO,CAAC,GAAG,CAAC,aAAa;YACzB,EAAE;QACJ,UAAU,EACR,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;YACxB,OAAO,CAAC,GAAG,CAAC,mBAAmB;YAC/B,QAAQ,CAAC,UAAU;QACrB,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,IAAI,QAAQ,CAAC,MAAM;QAC3D,WAAW,EACT,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC;YACzB,OAAO,CAAC,GAAG,CAAC,mBAAmB;YAC/B,aAAa;QACf,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,QAAQ,CAAC,WAAW;QAC9D,YAAY,EACV,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,qBAAqB;YACjC,QAAQ,CAAC,YAAY;QAEvB,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,QAAQ,CAAC,gBAAgB;QAC3E,iBAAiB,EACf,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,QAAQ,CAAC,iBAAiB;QAC7D,kBAAkB,EAChB,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,QAAQ,CAAC,kBAAkB;QAC9D,mBAAmB,EACjB,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,QAAQ,CAAC,mBAAmB;QAChE,kBAAkB,EAChB,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,QAAQ,CAAC,kBAAkB;QAC/D,qBAAqB,EACnB,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,QAAQ,CAAC,qBAAqB;QACrE,sBAAsB,EACpB,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,IAAI,QAAQ,CAAC,sBAAsB;QACvE,sBAAsB,EACpB,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,IAAI,QAAQ,CAAC,sBAAsB;QACvE,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,aAAa;QAElE,kBAAkB,EAAE;YAClB,OAAO,EACL,MAAM,CAAC,qBAAqB,CAAC,OAAO,CAAC;gBACrC,QAAQ,CAAC,kBAAkB,CAAC,OAAO;YACrC,kBAAkB,EAChB,MAAM,CAAC,qBAAqB,CAAC,kBAAkB,CAAC;gBAChD,QAAQ,CAAC,kBAAkB,CAAC,kBAAkB;YAChD,mBAAmB,EACjB,MAAM,CAAC,qBAAqB,CAAC,mBAAmB,CAAC;gBACjD,QAAQ,CAAC,kBAAkB,CAAC,mBAAmB;YACjD,WAAW,EACT,aAAa,CAAC,qBAAqB,CAAC,WAAW,CAAC;gBAChD,QAAQ,CAAC,kBAAkB,CAAC,WAAW;SAC1C;QAED,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,aAAa;QAClE,iBAAiB,EACf,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,QAAQ,CAAC,iBAAiB;QAE5D,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,QAAQ,CAAC,gBAAgB;QAC3E,QAAQ,EACN,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;YACxD,QAAQ,CAAC,QAAQ;QAEnB,kBAAkB,EAChB,cAAc,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,QAAQ,CAAC,kBAAkB;QACvE,iBAAiB,EACf,MAAM,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAClD,QAAQ,CAAC,iBAAiB;QAC5B,WAAW,EAAE;YACX,YAAY,EACV,KAAK,CAAC,cAAc,CAAC,YAAY,CAAC,IAAI,QAAQ,CAAC,WAAW,CAAC,YAAY;YACzE,kBAAkB,EAChB,KAAK,CAAC,cAAc,CAAC,kBAAkB,CAAC;gBACxC,QAAQ,CAAC,WAAW,CAAC,kBAAkB;YACzC,gBAAgB,EACd,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC;gBACtC,QAAQ,CAAC,WAAW,CAAC,gBAAgB;SACxC;KACF,CAAC;AACJ,CAAC;AAED,gCAAgC;AAEhC,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,MAAM,CAAC,CAAU;IACxB,OAAO,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC;AAED,SAAS,KAAK,CAAC,CAAU;IACvB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACtE,CAAC;AAED,SAAS,MAAM,CACb,CAAU,EACV,OAAY;IAEZ,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAK,OAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/D,CAAC,CAAE,CAAO;QACV,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,SAAS,aAAa,CAAC,CAAU;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QAC9D,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,SAAS,cAAc,CACrB,CAAU;IAEV,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9E,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,EAAE,CAAC;QACxD,OAAO,CAA2B,CAAC;IACrC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/context/propagation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * W3C trace context propagation for distributed tracing.
+ *
+ * - Outbound: Injects traceparent into exec/Bash tool arguments
+ *   when they contain HTTP calls matching configured URL patterns.
+ * - Inbound: Extracts traceparent from webhook headers for span linking.
+ */
+import { type Span, type SpanContext } from '@opentelemetry/api';
+import type { BeforeToolCallEvent } from '../hooks/before-tool-call.js';
+/**
+ * Inject W3C traceparent into exec/Bash tool arguments.
+ *
+ * Detects curl/wget/httpie commands and appends trace headers.
+ * Only injects if the target URL matches one of the configured patterns.
+ */
+export declare function injectTraceContext(event: BeforeToolCallEvent, parentSpan: Span, urlPatterns: string[]): void;
+/**
+ * Extract W3C trace context from inbound webhook headers.
+ * Returns a SpanContext for adding as a span link, or null.
+ */
+export declare function extractW3CContext(headers: Record<string, string>): SpanContext | null;
+//# sourceMappingURL=propagation.d.ts.map

package/dist/context/propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.ts","sourceRoot":"","sources":["../../src/context/propagation.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,EAIL,KAAK,IAAI,EACT,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,mBAAmB,EAC1B,UAAU,EAAE,IAAI,EAChB,WAAW,EAAE,MAAM,EAAE,GACpB,IAAI,CAwCN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,WAAW,GAAG,IAAI,CAapB"}

package/dist/context/propagation.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MIT
+/**
+ * W3C trace context propagation for distributed tracing.
+ *
+ * - Outbound: Injects traceparent into exec/Bash tool arguments
+ *   when they contain HTTP calls matching configured URL patterns.
+ * - Inbound: Extracts traceparent from webhook headers for span linking.
+ */
+import { context, propagation, trace, } from '@opentelemetry/api';
+import picomatch from 'picomatch';
+/**
+ * Inject W3C traceparent into exec/Bash tool arguments.
+ *
+ * Detects curl/wget/httpie commands and appends trace headers.
+ * Only injects if the target URL matches one of the configured patterns.
+ */
+export function injectTraceContext(event, parentSpan, urlPatterns) {
+    const args = event.tool?.args;
+    if (!args)
+        return;
+    const command = typeof args === 'string'
+        ? args
+        : args.command ??
+            args.cmd ??
+            '';
+    if (typeof command !== 'string')
+        return;
+    // Only inject into HTTP client commands
+    if (!isHttpCommand(command))
+        return;
+    // Check if the URL matches configured patterns
+    const url = extractUrlFromCommand(command);
+    if (!url || !matchesPatterns(url, urlPatterns))
+        return;
+    // Build the traceparent/tracestate headers
+    const carrier = {};
+    const ctx = trace.setSpan(context.active(), parentSpan);
+    propagation.inject(ctx, carrier);
+    if (!carrier.traceparent)
+        return;
+    // Append -H flags to the command
+    let headerFlags = ` -H "traceparent: ${carrier.traceparent}"`;
+    if (carrier.tracestate) {
+        headerFlags += ` -H "tracestate: ${carrier.tracestate}"`;
+    }
+    // Mutate the event's tool args to include trace headers
+    if (typeof args === 'string') {
+        event.tool.args = args + headerFlags;
+    }
+    else if (typeof args.command === 'string') {
+        args.command += headerFlags;
+    }
+    else if (typeof args.cmd === 'string') {
+        args.cmd += headerFlags;
+    }
+}
+/**
+ * Extract W3C trace context from inbound webhook headers.
+ * Returns a SpanContext for adding as a span link, or null.
+ */
+export function extractW3CContext(headers) {
+    const traceparent = headers.traceparent ?? headers.Traceparent ?? headers.TRACEPARENT;
+    if (!traceparent)
+        return null;
+    const carrier = { traceparent };
+    const tracestate = headers.tracestate ?? headers.Tracestate ?? headers.TRACESTATE;
+    if (tracestate)
+        carrier.tracestate = tracestate;
+    const extractedCtx = propagation.extract(context.active(), carrier);
+    const span = trace.getSpan(extractedCtx);
+    return span?.spanContext() ?? null;
+}
+// --- internal helpers ---
+function isHttpCommand(cmd) {
+    return /\b(curl|wget|httpie|http)\b/i.test(cmd);
+}
+/**
+ * Best-effort URL extraction from a shell command string.
+ * Handles common patterns: curl URL, curl -X POST URL, etc.
+ */
+function extractUrlFromCommand(cmd) {
+    // Match URLs (http:// or https://) in the command
+    const match = cmd.match(/https?:\/\/[^\s"']+/);
+    return match ? match[0] : null;
+}
+function matchesPatterns(url, patterns) {
+    if (patterns.length === 0)
+        return false;
+    if (patterns.includes('*'))
+        return true;
+    return patterns.some((pattern) => picomatch.isMatch(url, pattern));
+}
+//# sourceMappingURL=propagation.js.map

package/dist/context/propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.js","sourceRoot":"","sources":["../../src/context/propagation.ts"],"names":[],"mappings":"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"}

package/dist/context/span-store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * In-memory store mapping OpenClaw session keys to active OTEL spans.
+ *
+ * Tool spans use a stack (LIFO) so nested tool calls close in the
+ * correct order.  A TTL-based cleanup prevents memory leaks from
+ * sessions that never fire agent_end (e.g. gateway crash).
+ */
+import type { Span, Context } from '@opentelemetry/api';
+export interface ToolSpanEntry {
+    span: Span;
+    ctx: Context;
+    name: string;
+    callId: string;
+    startTime: number;
+}
+export interface SessionSpanContext {
+    /** Root span: invoke_agent */
+    agentSpan: Span;
+    agentCtx: Context;
+    /** Tool call stack (LIFO for correct nesting) */
+    toolStack: ToolSpanEntry[];
+    /** Monotonic tool call counter for sequencing */
+    toolSequence: number;
+    /** Whether any tool errored (propagated to agent span) */
+    hasError: boolean;
+    /** Request start timestamp */
+    startTime: number;
+}
+declare class SpanStore {
+    private sessions;
+    set(sessionKey: string, ctx: SessionSpanContext): void;
+    get(sessionKey: string): SessionSpanContext | undefined;
+    delete(sessionKey: string): void;
+    /** Push a tool span onto the session's stack. */
+    pushTool(sessionKey: string, entry: ToolSpanEntry): void;
+    /** Pop the most recent tool span (LIFO). */
+    popTool(sessionKey: string): ToolSpanEntry | undefined;
+    /** Peek at the top of the tool stack without removing. */
+    peekTool(sessionKey: string): ToolSpanEntry | undefined;
+    get size(): number;
+    /** End orphaned spans and remove stale sessions. */
+    private cleanup;
+}
+export declare const spanStore: SpanStore;
+export {};
+//# sourceMappingURL=span-store.d.ts.map

package/dist/context/span-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-store.d.ts","sourceRoot":"","sources":["../../src/context/span-store.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAElB,iDAAiD;IACjD,SAAS,EAAE,aAAa,EAAE,CAAC;IAE3B,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IAErB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAElB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAKD,cAAM,SAAS;IACb,OAAO,CAAC,QAAQ,CAAyC;IAEzD,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAKtD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIvD,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIhC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI;IAMxD,4CAA4C;IAC5C,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAMtD,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAMvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,oDAAoD;IACpD,OAAO,CAAC,OAAO;CAahB;AAED,eAAO,MAAM,SAAS,WAAkB,CAAC"}