npm - @latitude-data/openclaw-telemetry - Versions diffs - 0.0.9 → 0.1.0 - Mend

@latitude-data/openclaw-telemetry 0.0.9 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -1,278 +1,138 @@
 # @latitude-data/openclaw-telemetry
-OpenClaw plugin that streams every agent run to [Latitude](https://latitude.so) as OTLP traces — full system prompt, message history, assistant output, token usage, tool I/O, and the running agent's name on every span.
+OpenClaw plugin that streams every agent run to [Latitude](https://latitude.so) as OTLP traces: the user prompt and the sending user, the system prompt, every model call with its own tokens, cost and time to first token, the tools the agent was offered and the ones it called, memory reads and writes, subagents, cron runs and compactions, all grouped into one Latitude session per OpenClaw session.
+This is the OpenClaw counterpart to the other harness integrations ([`latitude-telemetry-hermes`](../hermes), [`@latitude-data/claude-code-telemetry`](../claude-code), [`@latitude-data/pi-telemetry`](../pi)).
+> OpenClaw also bundles a generic OpenTelemetry exporter (`@openclaw/diagnostics-otel`). It deliberately scrubs session, run and user ids ([openclaw/openclaw#91927](https://github.com/openclaw/openclaw/issues/91927)), exports no system prompt, no tool definitions and no memory, so it cannot produce Latitude sessions, users, tool rollups or the memory ledger. Use this plugin for full fidelity.
 ## Requirements
-- **OpenClaw 2026.4.25 or newer** on PATH.
+- **OpenClaw 2026.8.1 or newer** on PATH.
 - A **Latitude API key** from `https://console.latitude.so/projects/<your-slug>/settings/keys` and the matching **project slug**.
 ## Install
-### Recommended — one-shot CLI
-The companion CLI handles every step (install, config, validate, restart) in one command:
+### One-shot CLI
 ```bash
-npx -y @latitude-data/openclaw-telemetry-cli@0.0.9 install
+npx -y @latitude-data/openclaw-telemetry-cli@0.1.0 install
 ```
-It prompts for your API key and project slug, runs `openclaw plugins install` for you, writes the plugin entry into `openclaw.json`, adds the plugin to `plugins.allow`, validates the result, and (on TTY) offers to restart the gateway. See the [CLI README](https://github.com/latitude-dev/latitude-llm/tree/main/packages/telemetry/openclaw-cli#readme) for the full flag matrix, dry-run mode, custom config dir, and CI usage.
+The installer prompts for the API key and project slug, runs `openclaw plugins install --accept-capabilities`, writes the plugin entry into `openclaw.json`, adds it to `plugins.allow`, validates the result and offers to restart the gateway. See the [CLI README](../openclaw-cli#readme) for flags, dry-run mode, custom config dir and CI usage.
 ### Manual install
-If you'd rather not use the CLI, do exactly what it does, in four steps:
-#### 1. Install the runtime
-```bash
-openclaw plugins install @latitude-data/openclaw-telemetry@0.0.9
-```
-Pin to an exact version. OpenClaw's `security audit --deep` warns about unpinned install specs, so always include the `@<version>` suffix.
-OpenClaw fetches from npm, runs its security scan, copies files into `~/.openclaw/extensions/<id>/`, and creates a (disabled) `plugins.entries["@latitude-data/openclaw-telemetry"]` entry in `~/.openclaw/openclaw.json`.
-#### 2. Configure and enable
-Run these `openclaw config set` commands (use bracket notation so the scoped package name parses correctly). Substitute your real API key and project slug:
-```bash
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.apiKey' "lat_xxx"
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.project' "my-project-slug"
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.allowConversationAccess' true
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].hooks.allowConversationAccess' true
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].enabled' true
-```
-Both `allowConversationAccess` writes are required — see [The two flags](#the-two-flags).
-#### 3. Add to `plugins.allow` (optional but recommended)
-OpenClaw warns at every gateway restart about non-bundled plugins that auto-load without provenance via `plugins.allow`. Silence the warning:
-```bash
-# `config set` can't append to arrays — set the whole list. Include any other
-# plugins you already have in `plugins.allow`.
-openclaw config set 'plugins.allow' '["@latitude-data/openclaw-telemetry"]'
-```
-#### 4. Restart the gateway
 ```bash
+openclaw plugins install @latitude-data/openclaw-telemetry@0.1.0 --accept-capabilities
+P='plugins.entries["@latitude-data/openclaw-telemetry"]'
+openclaw config set "$P.config.apiKey" "lat_xxx"
+openclaw config set "$P.config.project" "my-project-slug"
+openclaw config set "$P.config.allowConversationAccess" true
+openclaw config set "$P.hooks.allowConversationAccess" true
+openclaw config set "$P.enabled" true
 openclaw gateway restart
 ```
-Verify everything's wired:
+`--accept-capabilities` records your consent to the plugin's declared surface; OpenClaw requires it for every non-bundled plugin. Both `allowConversationAccess` keys are required, see [The two flags](#the-two-flags). Optionally add the plugin id to `plugins.allow` to silence OpenClaw's provenance warning at startup (`config set` replaces the whole array, so include any ids already there).
+Verify:
 ```bash
 openclaw config validate --json
-# → {"valid": true, ...}
-grep -E "blocked|plugin not found|latitude" /tmp/openclaw/openclaw-*.log | tail
-# → ready (N plugins: ..., @latitude-data/openclaw-telemetry, ...)
-# → no "blocked", no "plugin not found"
-```
-Send a message to one of your OpenClaw agents — within seconds, traces appear at `https://console.latitude.so/projects/<your-slug>`.
-#### Or: hand-edit `~/.openclaw/openclaw.json`
-Equivalent to steps 2 + 3 in one paste:
-```jsonc
-{
-  "plugins": {
-    "allow": ["@latitude-data/openclaw-telemetry"],
-    "entries": {
-      "@latitude-data/openclaw-telemetry": {
-        "enabled": true,
-        "hooks": {
-          "allowConversationAccess": true
-        },
-        "config": {
-          "apiKey": "lat_xxx",
-          "project": "my-project-slug",
-          "allowConversationAccess": true
-        }
-      }
-    }
-  }
-}
+grep -E "latitude-openclaw|typed hook" /tmp/openclaw/openclaw-*.log | tail
 ```
-Merge with whatever else is in `openclaw.json`. Then run `openclaw config validate` and `openclaw gateway restart`.
+With `config.debug` on, the gateway log shows `[latitude-openclaw] enabled v0.1.0 ...` at startup and one `exported N spans` line per run.
 ## Uninstall
-If you installed via the CLI:
 ```bash
-npx -y @latitude-data/openclaw-telemetry-cli@0.0.9 uninstall
+npx -y @latitude-data/openclaw-telemetry-cli@0.1.0 uninstall
+# or
+openclaw plugins uninstall @latitude-data/openclaw-telemetry --force && openclaw gateway restart
 ```
-Manual uninstall:
-```bash
-openclaw plugins uninstall @latitude-data/openclaw-telemetry --force
-openclaw gateway restart
-```
-OpenClaw removes the extension files, install record, plugin entry, and the `plugins.allow` entry.
-## Targeting staging or local dev
-By default the plugin sends to production (`https://ingest.latitude.so`). Override `baseUrl` to point elsewhere:
-```bash
-# Staging
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' \
-  "https://staging-ingest.latitude.so"
-# Local dev
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' \
-  "http://localhost:3002"
-```
-The CLI handles this with `--staging` / `--dev` flags.
-## Structural-only telemetry (no content capture)
-To get trace metadata (timings, token usage, model name, agent name, ids) without prompt/response content, keep `hooks.allowConversationAccess` at `true` so events still dispatch, and set only `config.allowConversationAccess` to `false`:
-```bash
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.allowConversationAccess' false
-openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].hooks.allowConversationAccess' true
-```
-Setting `hooks.allowConversationAccess=false` would block dispatch entirely — see [The two flags](#the-two-flags). With this config the plugin still emits the full span tree, just with content attributes (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`, tool args/results) scrubbed. Each span carries `latitude.captured.content: false` so the gate state is visible in the Latitude UI.
-The CLI handles this with `--no-content`.
 ## What gets sent
-For each agent run, the plugin emits one trace shaped like the actual run:
+One trace per agent run (a user turn, a cron run, a heartbeat, a subagent run):
 ```
-agent (root, traceId = hash(runId))
-├─ compaction         (0..1, rare; budget-triggered)
-├─ model_call         (1..N, one per provider API call)
-├─ tool_call: foo     (between model_calls; sibling of agent)
-├─ model_call
-├─ tool_call: bar
-├─ subagent           (0..N — the child's full agent tree nests under here)
-│   └─ agent
-│       ├─ model_call
-│       └─ tool_call: ...
-└─ model_call         (final)
+interaction                              invoke_agent   prompt, final answer, outcome, sender
+├── search_memory                        memory         the snapshot injected at session start, once per session
+├── llm_request                          chat           tokens, cost, TTFT, system prompt, tool definitions, messages
+├── tool_call:<name>                     execute_tool   arguments, result, error
+│   └── search_memory | upsert_memory    memory         memory tools and memory file writes
+├── tool_call:sessions_spawn
+│   └── subagent                         spawn → ended, with the child run's interaction nested inside
+├── compaction
+└── llm_request
 ```
-Five span kinds:
-- **`agent`** — root of the run. Carries `openclaw.session.key`, `openclaw.agent.id`, `openclaw.agent.name`, aggregated token usage across all generations, run duration, success/error status, the first user prompt, and the full final message list. Attempt-aggregate `gen_ai.*` lands here.
-- **`model_call`** — one per provider API call inside the run. Carries provider, request/response model, `openclaw.api`, `openclaw.transport`, per-call duration, outcome, error category, time-to-first-byte, request payload bytes, response stream bytes, upstream request id hash, and `gen_ai.input.messages` snapshotted at the moment that generation started. Per-call output messages and per-call token usage aren't surfaced by OpenClaw today (attempt-aggregate only); those stay on `agent`.
-- **`tool_call:<name>`** — one per tool invocation. Canonical `gen_ai.tool.*` attributes: `name`, `call.id`, `call.arguments`, `call.result`. Sibling of `agent`, NOT child of `model_call` — tools run between generations, not during them.
-- **`compaction`** — rare; fires when OpenClaw hits the message budget mid-run. Records before/after message counts and the compacted-out count.
-- **`subagent`** — one per child run spawned by this agent. The child's entire `agent` subtree (its own `model_call`s, `tool_call`s, even further-nested `subagent`s) parents itself underneath via cross-runId trace propagation, so a spawn tree is one waterfall in one trace.
+Every span carries the OpenClaw session id (`session.id`), the sender of a user turn (`user.id`), the agent (`gen_ai.agent.name`), derived tags and `openclaw.*` metadata. A subagent's spans join the parent's trace and session so one delegation reads as one conversation.
-Every span carries `openclaw.agent.id` and `openclaw.agent.name` — multi-agent setups produce spans tagged with the invoking agent's id, letting you filter and group by agent in the Latitude UI. All spans share the same `traceId`, so they group as one trace per agent run (and one trace per spawn tree, by virtue of the subagent linkage).
+Per-call usage, cost, finish reason and output come from the run's transcript at `agent_end`, matched to each `model_call_started` / `model_call_ended` window by timestamp; OpenClaw's own cost is reported as the span's cost so a model missing from Latitude's catalog still shows a price. Tags are `openclaw`, the channel (`slack`, `telegram`, ...), the agent id, `cron:<job>` on cron runs and `subagent:<agent>` on a run that spawned one, plus whatever `config.tags` adds.
-### Backend caveat: Codex / Claude-Code-style providers
+Design notes, hook traps and the full attribute tables live in [`dev-docs/openclaw-telemetry.md`](../../../dev-docs/openclaw-telemetry.md).
-OpenClaw's `model_call_started` / `model_call_ended` hooks fire from its `selection` layer, which wraps the agent's `streamFn` invocation. For "agentic" backends (Codex, Claude Code) the inner generations happen inside the backend's own loop and don't surface as separate `model_call` events. Result: a Codex-backed run shows ONE `model_call` per attempt instead of N. Anthropic and OpenAI direct don't have this issue. The fix is upstream in OpenClaw — out of scope for this plugin.
+## Configuration
-## How it works
+Everything lives under `plugins.entries["@latitude-data/openclaw-telemetry"]`.
-We subscribe to OpenClaw's typed plugin hooks (`src/plugins/hook-types.ts` upstream). The model is "one span per paired before/after (or start/end) event":
+### `.config` — read by the plugin
-| Span | Start hook | End hook |
+| Key | Default | Description |
 | --- | --- | --- |
-| `agent` | `before_agent_start` | `agent_end` |
-| `model_call` | `model_call_started` | `model_call_ended` |
-| `tool_call` | `before_tool_call` | `after_tool_call` |
-| `compaction` | `before_compaction` | `after_compaction` |
-| `subagent` | `subagent_spawned` | `subagent_ended` |
-Two more hooks (`llm_input`, `llm_output`) are subscribed to for **content only** — they don't open or close spans, they just enrich the `agent` span with attempt-aggregate data and seed the rolling history snapshot used by per-call `model_call.gen_ai.input.messages`.
-The hook system runs handlers fire-and-forget, so nothing we do here can slow the agent loop. The one exception is `before_tool_call`, which is a `runModifyingHook` — our handler returns `undefined` so OpenClaw dispatches the tool normally. Returning anything else (e.g. `{block: true}`) would block every tool call.
-**No runtime wrapping.** We stay inside the supported plugin API rather than monkey-patching `@mariozechner/pi-ai`. The hooks give us everything, at lower risk of breaking on OpenClaw updates.
-## Configuration reference
-Two blocks live under `plugins.entries["@latitude-data/openclaw-telemetry"]`:
-### `.config` — read by the plugin's runtime
-| Key | Required | Default | Description |
-| --- | --- | --- | --- |
-| `apiKey` | yes | — | Bearer token for Latitude ingestion. |
-| `project` | yes | — | Slug of the project to route traces into. |
-| `baseUrl` | no | `https://ingest.latitude.so` | Override OTLP ingest origin. The CLI sets this only when `--staging` or `--dev` is passed. |
-| `allowConversationAccess` | no | `false` | When `true`, attach raw prompts, assistant responses, system instructions, and tool I/O to spans. When `false`, emit only timing, token usage, model name, agent id, and structural ids — same span tree, scrubbed payloads. **Must match `hooks.allowConversationAccess` below — see [The two flags](#the-two-flags).** |
-| `redact` | no | — | Custom local attribute redaction before export: `{ "attributes": ["/^gen_ai\\.(input|output)\\.messages$/"], "mask": "[]" }`. Patterns are exact strings, regex source strings, or `/pattern/flags` strings. |
-| `enabled` | no | `true` | Set to `false` to pause emission without uninstalling. |
-| `debug` | no | `false` | Log diagnostic lines to stderr (visible in the gateway log). |
-### `.hooks` — read by OpenClaw's runtime
-| Key | Required | Default | Description |
-| --- | --- | --- | --- |
-| `allowConversationAccess` | yes (on 2026.4.25+) | — | OpenClaw's hook dispatcher gates `llm_input` / `llm_output` / `before_tool_call` / `after_tool_call` / `agent_end` events on this. When `false` or absent, every typed hook is blocked and the plugin never sees an event — which means no traces, with the gateway log showing `[plugins] typed hook "..." blocked because non-bundled plugins must set plugins.entries.<id>.hooks.allowConversationAccess=true`. |
+| `apiKey` | — | Latitude API key (required). |
+| `project` | — | Project slug (required). |
+| `baseUrl` | `https://ingest.latitude.so` | Ingest origin, without `/v1/traces`. |
+| `allowConversationAccess` | `false` | Attach prompts, responses, system prompt, tool I/O and memory bodies. Must match `hooks.allowConversationAccess`. |
+| `serviceName` | `openclaw` | OTLP `service.name`, the Service axis in Latitude. |
+| `tags` | — | Extra tags, array or comma-separated string. |
+| `metadata` | — | Extra metadata, string map. Keys starting with `openclaw.` are ignored. |
+| `memory` | `true` | Emit memory spans. |
+| `memoryContent` | `true` | Include memory bodies and queries on memory spans. |
+| `toolDefinitions` | `true` | Attach the offered tool definitions to each model call. |
+| `maxContentChars` | `262144` | Per-attribute content budget. Strings are truncated from the middle; message lists and tool definitions drop items from the middle so they still parse. |
+| `redact` | — | `{ "attributes": ["exact key" or "/regex/flags"], "mask": "******" }`: mask selected attribute values before export, keeping the key. |
+| `enabled` | `true` | Set to `false` to pause emission. |
+| `debug` | `false` | Log diagnostics to the gateway log. |
+### `.hooks` — read by OpenClaw
+| Key | Description |
+| --- | --- |
+| `allowConversationAccess` | OpenClaw's dispatch gate for `llm_input`, `llm_output` and `agent_end`. When absent or `false`, those hooks are never registered for this plugin and no traces are produced. |
 ### The two flags
-`hooks.allowConversationAccess` and `config.allowConversationAccess` mean different things:
+- `hooks.allowConversationAccess` is the **dispatch gate**: `false` means OpenClaw never forwards the conversation hooks, so nothing is exported.
+- `config.allowConversationAccess` is the **content gate**: `false` means the full span tree still ships, with message, prompt, tool I/O and memory bodies removed and `latitude.captured.content=false` on every span.
-- **`hooks.*`** is the **dispatch gate**. `false` → OpenClaw never forwards events to us. No traces.
-- **`config.*`** is the **payload-content gate**. `false` → we emit spans normally but scrub message content from them. Structural-only telemetry.
+Structural-only telemetry is therefore `hooks: true` plus `config: false` (the CLI's `--no-content`).
-For *this* plugin we always couple them — the CLI writes both from the same source. If you hand-edit:
+### Targeting staging or local dev
-- **Both `true`**: full content capture (the default).
-- `hooks: true` + `config: false`: structural-only telemetry (set via `--no-content`).
-- `hooks: false` + anything: no traces. Don't.
-### Environment-variable fallbacks
-If a `config.*` key isn't set, the runtime falls back to env vars on the gateway process: `LATITUDE_API_KEY`, `LATITUDE_PROJECT`, `LATITUDE_BASE_URL`, `LATITUDE_DEBUG`, `LATITUDE_OPENCLAW_ENABLED`. Useful for flipping `debug` without editing `openclaw.json`.
-## Privacy
+```bash
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' "https://staging-ingest.latitude.so"
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' "http://localhost:3002"
+```
-The CLI's first-install default writes `allowConversationAccess: true` to both blocks → full content capture. Pass `--no-content` for structural-only telemetry.
+The CLI has `--staging` / `--dev` for the same.
-For hand-edited configs, leaving `allowConversationAccess` out entirely produces **no traces** (not "structural-only traces") because `hooks.allowConversationAccess` defaults to `false` at OpenClaw's level and dispatch is blocked. Always set both keys explicitly.
+## How it fails
-To pause emission without uninstalling, set `enabled: false` on the plugin entry, or `LATITUDE_OPENCLAW_ENABLED=0` in the gateway environment.
+Fail-open. An unreachable ingest, a bad key or a malformed hook payload is logged (with `debug: true`) and the agent run continues. Exports retry on `429`, `5xx` and network errors and never resend a span that was accepted.
-For field-level PII controls while keeping content capture enabled, add `config.redact`. For example, to send empty message arrays for prompts/responses before anything leaves the gateway:
+## Development
-```jsonc
-{
-  "plugins": {
-    "entries": {
-      "@latitude-data/openclaw-telemetry": {
-        "config": {
-          "redact": {
-            "attributes": ["/^gen_ai\\.(input|output)\\.messages$/"],
-            "mask": "[]"
-          }
-        }
-      }
-    }
-  }
-}
+```bash
+pnpm --filter @latitude-data/openclaw-telemetry test
+pnpm --filter @latitude-data/openclaw-telemetry build && (cd packages/telemetry/openclaw && npm pack)
+openclaw plugins install npm-pack:/path/to/latitude-data-openclaw-telemetry-0.1.0.tgz --accept-capabilities --force
 ```
-## Supported OpenClaw versions
-Requires **2026.4.25 or newer**. Earlier versions either reject `hooks.allowConversationAccess` outright (≤ 2026.4.21) or have unverified dispatch gating (2026.4.22 – 2026.4.24). The CLI's version check aborts on older versions; manual installs run into validation errors. Run `npm install -g openclaw@latest` to upgrade.
-## How it fails
-Fail-open by design. If the API is unreachable, your key is wrong, or a hook payload is malformed, the plugin logs to stderr (when `debug: true`) and the agent run continues unaffected.
 ## License
 MIT

package/dist/plugin.d.ts CHANGED Viewed

@@ -1,3 +1,46 @@
+//#region src/types.d.ts
+interface OtlpAnyValue {
+  stringValue?: string;
+  intValue?: string;
+  boolValue?: boolean;
+  doubleValue?: number;
+  arrayValue?: {
+    values: OtlpAnyValue[];
+  };
+}
+interface OtlpKeyValue {
+  key: string;
+  value: OtlpAnyValue;
+}
+interface OtlpSpan {
+  traceId: string;
+  spanId: string;
+  parentSpanId: string;
+  name: string;
+  kind: number;
+  startTimeUnixNano: string;
+  endTimeUnixNano: string;
+  attributes: OtlpKeyValue[];
+  status: {
+    code: number;
+  };
+}
+interface OtlpResourceSpans {
+  resource: {
+    attributes: OtlpKeyValue[];
+  };
+  scopeSpans: Array<{
+    scope: {
+      name: string;
+      version: string;
+    };
+    spans: OtlpSpan[];
+  }>;
+}
+interface OtlpExportRequest {
+  resourceSpans: OtlpResourceSpans[];
+}
+//#endregion
 //#region src/redaction.d.ts
 interface RedactConfig {
   attributes: string[];
@@ -14,11 +57,18 @@ interface Config {
   /**
    * When false, the plugin still emits one span per LLM call / tool / run, but
    * scrubs raw conversation content (input/output messages, system prompt,
-   * tool args, tool results, the surfaced first-prompt). Token counts, model
-   * names, agent ids, and timings are unaffected.
+   * tool args, tool results, memory bodies). Token counts, model names, agent
+   * ids, and timings are unaffected.
    */
   allowConversationAccess: boolean;
   redact?: RedactConfig | undefined;
+  serviceName: string;
+  tags: string[];
+  metadata: Record<string, string>;
+  memory: boolean;
+  memoryContent: boolean;
+  toolDefinitions: boolean;
+  maxContentChars: number;
 }
 //#endregion
 //#region src/logger.d.ts
@@ -26,102 +76,136 @@ interface Logger {
   debug: (msg: string) => void;
   warn: (msg: string) => void;
 }
+/** Shape of OpenClaw's `api.logger`; lines written through it land in the gateway log. */
+interface HostLogger {
+  debug?: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}
+//#endregion
+//#region src/usage.d.ts
+type AttrValue = string | number | boolean | unknown[] | Record<string, unknown> | undefined;
 //#endregion
 //#region src/span-builder.d.ts
 /**
- * Builds the per-trace span tree for an OpenClaw agent run from the granular
- * paired hooks. Replaces the older `turn-builder.ts` model that collapsed the
- * whole attempt into a single `llm_request` span — that shape was wrong on
- * two counts: `llm_input` / `llm_output` fire ONCE per attempt (not per
- * generation), and an attempt is a sequence of generations interleaved with
- * tool executions.
- *
- * Span set this builder produces:
+ * Builds one trace per OpenClaw agent run from the typed plugin hooks:
  *
- *   agent (root)
- *   ├─ compaction        (0..1, rare)
- *   ├─ model_call        (1..N, one per provider API call)
- *   ├─ tool_call: ...    (interleaved between model_calls; siblings of agent)
- *   ├─ subagent          (0..N; child agent runs nest INSIDE these via
- *   │   └─ agent ...      cross-runId trace propagation)
- *   └─ model_call        (final)
+ *   interaction (root, invoke_agent)
+ *   ├── search_memory        (once per session: the snapshot injected at session start)
+ *   ├── llm_request          (chat; one per provider call, per-call usage + cost + messages)
+ *   ├── tool_call:<name>     (execute_tool; sibling of llm_request, tools run between calls)
+ *   │   └── search_memory / upsert_memory / delete_memory   (memory tools and memory file writes)
+ *   ├── tool_call:sessions_spawn
+ *   │   └── subagent         (spawn → ended; the child run's interaction nests underneath)
+ *   ├── compaction
+ *   └── llm_request
  *
- * Tool spans are siblings of `agent`, not children of `model_call`, because
- * tools run BETWEEN generations — not during them. Nesting under model_call
- * would falsely imply concurrency.
- *
- * `llm_input` / `llm_output` are NOT span boundaries here. They're data-only
- * feeds that enrich the parent `agent` span (full message history, output
- * messages, aggregate token usage).
+ * No hook announces a run before `llm_input`, so the root opens lazily on the
+ * first event that carries a run id. `agent_end` carries the whole transcript,
+ * which is where per-call usage, cost and output content come from; it fires
+ * before `llm_output`, so finalization waits for the latter or a short grace.
  */
 interface SpanRecord {
-  /** Stable id for the span (16 hex chars). */
   spanId: string;
-  /** Span tree id (32 hex chars). */
   traceId: string;
-  /** Empty string for root agent spans, parent's spanId otherwise. */
   parentSpanId: string;
-  /** OpenClaw event noun (`agent` / `model_call` / `tool_call` / `compaction` / `subagent`). */
   name: string;
+  /** OTel SpanKind: 1 INTERNAL, 3 CLIENT. */
+  kind: number;
   startMs: number;
   endMs: number | undefined;
-  /** Free-form attribute bag — flattened to OTLP key/value at emit time. */
   attrs: Record<string, AttrValue>;
-  /** Status — set at close from the event payload's outcome/error. */
   outcome?: "ok" | "error";
   errorMessage?: string | undefined;
 }
-type AttrValue = string | number | boolean | unknown[] | Record<string, unknown> | undefined;
 interface BuildResult {
-  /** Run id this batch belongs to. */
   runId: string;
-  /** All spans ready to be exported (agent + everything beneath it). */
   spans: SpanRecord[];
 }
 //#endregion
+//#region src/transport.d.ts
+interface TransportOptions {
+  baseUrl: string;
+  apiKey: string;
+  project: string;
+  logger: Logger;
+  timeoutMs?: number;
+  maxAttempts?: number;
+  fetchImpl?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Ships OTLP requests sequentially with bounded retries. Every span is sent
+ * exactly once on success: Latitude's trace and session rollups add per
+ * insert, so a duplicate would inflate counts; a `4xx` other than `429` is
+ * therefore final, while `429`, `5xx` and network errors retry with backoff.
+ */
+declare class Transport {
+  private readonly url;
+  private readonly opts;
+  private chain;
+  private pending;
+  constructor(opts: TransportOptions);
+  enqueue(payload: OtlpExportRequest): void;
+  /** Resolves when everything queued so far has been sent or given up on, or the budget elapses. */
+  flush(budgetMs: number): Promise<void>;
+  private send;
+}
+//#endregion
 //#region src/plugin.d.ts
 /**
- * Minimal structural type for OpenClaw's plugin API — only the fields we
- * touch. We avoid importing from `openclaw/plugin-sdk` so the package stays
- * usable when OpenClaw isn't installed (the CLI and tests don't need it),
- * and so we're robust to small signature changes across OpenClaw versions.
- *
- * `pluginConfig` is the user's `plugins.entries[id].config` block — that's
- * the canonical place to read credentials and feature flags. The OpenClaw
- * plugin SDK also exposes the same value as `api.pluginConfig` on the
- * builder API; keep both names in sync if the upstream contract evolves.
+ * Structural type for the slice of OpenClaw's plugin API this plugin touches.
+ * Kept local so the package works without OpenClaw installed (tests, CLI) and
+ * tolerates small upstream signature changes.
  */
 interface OpenClawPluginApiLike {
-  logger?: Logger;
+  logger?: HostLogger;
   pluginConfig?: Record<string, unknown>;
+  /** The whole OpenClaw config; only the plugin's own `hooks` block is read. */
+  config?: {
+    plugins?: {
+      entries?: Record<string, {
+        hooks?: {
+          allowConversationAccess?: boolean;
+        };
+      }>;
+    };
+  };
+  /** Host runtime helpers; the state dir and the agent event stream are used when present. */
+  runtime?: {
+    state?: {
+      resolveStateDir?: () => string;
+    };
+    events?: {
+      onAgentEvent?: (listener: (evt: AgentEventLike) => void) => unknown;
+    };
+  };
   on: <K extends string>(hookName: K, handler: (event: unknown, ctx: unknown) => unknown, opts?: {
     priority?: number;
   }) => void;
 }
+interface AgentEventLike {
+  runId?: string;
+  stream?: string;
+  ts?: number;
+  data?: Record<string, unknown>;
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+}
 interface RegisterOptions {
   /** Override the config, mostly for tests. */
   config?: Config;
-  /** Override the logger. */
   logger?: Logger;
-  /**
-   * Hook to observe the emitted run right before it's posted. Used by tests;
-   * not a stable public API.
-   */
+  /** Observe each finished batch right before export. Tests only. */
   onEmit?: (result: BuildResult) => void;
+  /** Replace the network transport. Tests only. */
+  transport?: Pick<Transport, "enqueue" | "flush">;
+  now?: () => number;
+  schedule?: (fn: () => void, ms: number) => () => void;
 }
-/**
- * Register the Latitude plugin against an OpenClaw plugin API. OpenClaw calls
- * this once at plugin activation; we wire up the granular paired hooks
- * (model_call_started/_ended, before_/after_tool_call, before_/after_compaction,
- * subagent_spawned/_ended, before_agent_start/agent_end) plus the
- * data-only feeds (llm_input/llm_output) that enrich the agent span.
- *
- * Every typed hook on OpenClaw's side fires fire-and-forget for non-modifying
- * hooks; before_tool_call is a `runModifyingHook` where returning anything
- * other than undefined blocks the tool call. Our handler returns nothing —
- * keep it that way.
- */
 declare function registerLatitudePlugin(api: OpenClawPluginApiLike, opts?: RegisterOptions): void;
 //#endregion
-export { OpenClawPluginApiLike, RegisterOptions, registerLatitudePlugin as default };
+export { AgentEventLike, OpenClawPluginApiLike, RegisterOptions, registerLatitudePlugin as default };
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"plugin.d.ts","names":[],"sources":["../src/redaction.ts","../src/config.ts","../src/logger.ts","../src/span-builder.ts","../src/plugin.ts"],"mappings":";~~UAEiB~~,YAAA;EACf,UAAA;EACA,IAAA;AAAA;;;UCFe,MAAA;EACf,MAAA;EACA,OAAA;EACA,OAAA;EACA,OAAA;EACA,KAAA~~;;;AALF;;;;EAYE~~,uBAAA;EACA,MAAA,GAAS,YAAA;AAAA;;;~~UCbM~~,MAAA;EACf,KAAA,GAAQ,GAAA;EACR,IAAA,GAAO,GAAA;AAAA~~;;;AFFT;;;;;;;;ACAA;;;;;;;;;;;;;;;;;ACAA~~;~~AFAA~~,~~UGoDiB~~,~~UAAA;;EAEf~~,~~MAAA~~;~~EDrDA~~;~~ECuDA~~,OAAA;~~EDtDA~~;~~ECwDA~~,YAAA;~~EDxDkB~~;~~EC0DlB~~,IAAA;EACA,OAAA;EACA,KAAA~~;;EAEA~~,KAAA,EAAO,MAAA,SAAe,SAAA;~~EAZG;EAczB~~,OAAA;EACA,YAAA;AAAA;AAAA,~~KAGU~~,~~SAAA~~,~~2CAAoD~~,~~MAAA~~;AAAA,~~UAoD/C~~,WAAA;~~EA9Df~~;~~EAgEA~~,KAAA;~~EA9DA~~;~~EAgEA~~,KAAA,~~EAAO~~,~~UAAA~~;AAAA~~;;;;;;;;;AF9HT;;;;;UG8BiB~~,qBAAA;EACf,MAAA,GAAS,~~MAAA~~;EACT,YAAA,GAAe,MAAA;~~EACf~~,EAAA,qBACE,QAAA,EAAU,CAAA,EACV,OAAA,GAAU,KAAA,WAAgB,GAAA,uBAC1B,IAAA;IAAS,QAAA;EAAA;AAAA;AAAA,UAII,eAAA;~~EH3BM~~;~~EG6BrB~~,MAAA,GAAS,MAAA~~;;EAET~~,MAAA,GAAS,MAAA;~~EF5CM;;;;EEiDf~~,MAAA,IAAU,MAAA,EAAQ,WAAA;AAAA~~;;;;;;;;ADGpB;;;;;iBCYwB~~,sBAAA,CAAuB,GAAA,EAAK,qBAAA,EAAuB,IAAA,GAAM,eAAA"}
1	+ {"version":3,"file":"plugin.d.ts","names":[],"sources":["../src/types.ts","../src/redaction.ts","../src/config.ts","../src/logger.ts","../src/usage.ts","../src/span-builder.ts","../src/transport.ts","../src/plugin.ts"],"mappings":"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"}