context-mode 1.0.166 → 1.0.167

package/build/adapters/kimi/usage.js

@@ -0,0 +1,217 @@
+/**
+ * Kimi Code (kimi-code) per-turn token usage capture.
+ *
+ * Ground truth: context-mode-platform/docs/prds/2026-06-paid-observability/
+ * adapter-matrix/kimi.md (+ cited refs/platforms/kimi-code/...).
+ *
+ * Kimi Code emits REAL per-turn token usage + model, but ONLY on the
+ * `wire.jsonl` records stream — NOT through any hook stdin payload. Each usage
+ * line is an AgentRecord of `type: "usage.record"` carrying a normalized
+ * four-field Moonshot/OpenAI-compatible `TokenUsage` plus the model id:
+ *
+ *   refs/platforms/kimi-code/packages/agent-core/src/agent/usage/index.ts:27-32
+ *     — this.agent.records.logRecord({ type: 'usage.record', model, usage, usageScope })
+ *   refs/platforms/kimi-code/packages/agent-core/src/agent/records/types.ts:59-63
+ *     — record shape { model: string; usage: TokenUsage; usageScope?: UsageRecordScope }
+ *   refs/platforms/kimi-code/packages/agent-core/src/agent/index.ts:142
+ *     — new FileSystemAgentRecordPersistence(join(options.homedir, 'wire.jsonl'), ...)
+ *       => the persisted file is <sessionDir>/wire.jsonl.
+ *
+ * Normalized TokenUsage (kosong/src/usage.ts:7-13; parsed by
+ * kosong/src/providers/openai-common.ts:213-241):
+ *   { inputOther, output, inputCacheRead, inputCacheCreation }
+ *
+ * Mapping → buildAgentUsageEvent input shape:
+ *   inputOther          → input_tokens     (prompt - cached)
+ *   output              → output_tokens
+ *   inputCacheRead      → cache_read_tokens
+ *   inputCacheCreation  → cache_creation_tokens
+ *   record.model        → model_id
+ *
+ * INCREMENTAL: usage.record lines are per-step deltas (summed via addUsage;
+ * usage/index.ts:34,37). The cumulative total exists only in-memory, never on
+ * disk — so cost capture sums the NEW delta lines per model since a cursor.
+ *
+ * Native cost: kimi-code's TokenUsage carries NO USD cost field (verified
+ * against the matrix doc field list — only token counts). So native_cost_usd
+ * is left null and buildAgentUsageEvent falls back to the pricing catalog.
+ *
+ * Pure, null-safe, algorithmic — NO regex.
+ */
+import { buildAgentUsageEvent } from "../../session/extract.js";
+/** Non-negative finite number, else 0. */
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0;
+}
+/**
+ * Parse ONE kimi-code `usage.record` line object into the buildAgentUsageEvent
+ * input shape, or null when it is not a usage record / carries no usage /
+ * every token bucket is zero.
+ *
+ * Accepts the parsed AgentRecord object (NOT the raw JSONL string). Tolerant of
+ * the record being passed either as the full stamped record `{ type, model,
+ * usage, ... }` or a bare `{ model, usage }`.
+ */
+export function parseKimiUsage(record) {
+    if (!record || typeof record !== "object")
+        return null;
+    const rec = record;
+    // When a `type` discriminator is present it MUST be the usage record kind.
+    // Absent type → tolerate (caller may have already narrowed), but a wrong
+    // explicit type is rejected so non-usage records never produce cost events.
+    if (typeof rec.type === "string" && rec.type !== "usage.record")
+        return null;
+    const usageRaw = rec.usage;
+    if (!usageRaw || typeof usageRaw !== "object")
+        return null;
+    const usage = usageRaw;
+    const input_tokens = num(usage.inputOther);
+    const output_tokens = num(usage.output);
+    const cache_read_tokens = num(usage.inputCacheRead);
+    const cache_creation_tokens = num(usage.inputCacheCreation);
+    // Zero-everything record → null (mirrors buildAgentUsageEvent's zero->null
+    // contract; keeps the DB free of no-op cost events).
+    if (input_tokens <= 0 &&
+        output_tokens <= 0 &&
+        cache_read_tokens <= 0 &&
+        cache_creation_tokens <= 0) {
+        return null;
+    }
+    const model_id = typeof rec.model === "string" ? rec.model : "";
+    return {
+        model_id,
+        input_tokens,
+        output_tokens,
+        cache_creation_tokens,
+        cache_read_tokens,
+        // kimi-code TokenUsage carries no native USD field — defer to the catalog.
+        native_cost_usd: null,
+    };
+}
+/**
+ * Cursor-aware wire.jsonl reader for the Stop / SessionEnd hook.
+ *
+ * `wire.jsonl` is an append-only records stream that grows every turn; the
+ * forward loop forwards ALL passed events unconditionally, so re-summing the
+ * whole file each hook fire would double-count every prior turn. This sums only
+ * the `usage.record` lines NEW since the last fire, keyed by a per-session
+ * high-water cursor (a 1-based count of usage.record lines consumed so far,
+ * serialized as a decimal string in session_meta.usage_cursor).
+ *
+ *   - cursor null/empty/unparseable → process ALL usage.record lines.
+ *   - cursor = N (>= total)         → nothing new; no events, cursor unchanged.
+ *   - cursor = N (< total)          → process usage.record lines AFTER index N.
+ *   - BOUNDED COMPACTION FALLBACK: if the file SHRANK below the cursor (the
+ *     stream was truncated/rotated, so prior lines are gone), the cursor has
+ *     fallen off the front — process ONLY the LAST usage.record line so we
+ *     never re-emit the whole history. Mirrors extractTranscriptUsageSince.
+ *
+ * `cursor` returns the decimal string count of TOTAL usage.record lines seen,
+ * so the next fire resumes exactly past it.
+ *
+ * Per-model summation: lines are bucketed by model_id and each bucket emits one
+ * agent_usage event (incremental deltas are additive — addUsage semantics).
+ *
+ * Char-algorithmic JSONL parse (split on "\n", JSON.parse each line, skip
+ * blanks/unparseable). NO regex.
+ */
+export function extractKimiUsageSince(wireJsonlText, cursor) {
+    const inputCursor = parseCursor(cursor);
+    if (typeof wireJsonlText !== "string" || wireJsonlText.length === 0) {
+        // Empty/missing wire file: nothing to process, cursor unchanged.
+        return { events: [], cursor: cursor ?? null };
+    }
+    // Pass 1: materialize the ordered usage.record parse results (one linear
+    // walk). We keep the AgentUsageCounts for each usage.record line so the
+    // cursor counts ONLY usage records (not unrelated wire lines), making the
+    // high-water mark stable against interleaved non-usage records.
+    const records = [];
+    const lines = wireJsonlText.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // partial/corrupt trailing line — skip.
+        }
+        if (!obj || typeof obj !== "object")
+            continue;
+        if (obj.type !== "usage.record")
+            continue;
+        const parsed = parseKimiUsage(obj);
+        // A usage.record that sums to zero still ADVANCES the cursor (it was seen)
+        // but contributes no tokens. Push a zero-counts placeholder so the index
+        // accounting stays aligned with the on-disk usage.record ordinal.
+        records.push(parsed ?? {
+            model_id: "",
+            input_tokens: 0,
+            output_tokens: 0,
+            cache_creation_tokens: 0,
+            cache_read_tokens: 0,
+            native_cost_usd: null,
+        });
+    }
+    const total = records.length;
+    if (total === 0) {
+        // No usage records at all → nothing to emit, cursor unchanged.
+        return { events: [], cursor: cursor ?? null };
+    }
+    // Select the slice to sum.
+    let slice;
+    if (inputCursor === null || inputCursor <= 0) {
+        slice = records; // all usage records
+    }
+    else if (inputCursor >= total) {
+        if (inputCursor === total) {
+            // Caught up exactly — nothing new.
+            slice = [];
+        }
+        else {
+            // Cursor exceeds the on-disk count → the stream shrank (compaction /
+            // rotation). Bounded fallback: last usage record only.
+            slice = records.slice(total - 1);
+        }
+    }
+    else {
+        slice = records.slice(inputCursor); // strictly after the cursor index
+    }
+    // Sum the selected records per model and emit via the shared event builder.
+    const sums = new Map();
+    for (const r of slice) {
+        const cur = sums.get(r.model_id) ?? { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 };
+        cur.input += r.input_tokens;
+        cur.output += r.output_tokens;
+        cur.cacheCreate += r.cache_creation_tokens;
+        cur.cacheRead += r.cache_read_tokens;
+        sums.set(r.model_id, cur);
+    }
+    const events = [];
+    for (const [model, s] of sums) {
+        const ev = buildAgentUsageEvent({
+            model_id: model,
+            input_tokens: s.input,
+            output_tokens: s.output,
+            cache_creation_tokens: s.cacheCreate,
+            cache_read_tokens: s.cacheRead,
+        });
+        if (ev)
+            events.push(ev);
+    }
+    // Cursor always advances to the total usage.record count seen, so the next
+    // fire resumes past it. Even when the slice produced no events (all-zero or
+    // already caught up), the high-water mark moves forward.
+    return { events, cursor: String(total) };
+}
+/** Decimal-string cursor → non-negative integer count, or null when absent/invalid. */
+function parseCursor(cursor) {
+    if (typeof cursor !== "string" || cursor.length === 0)
+        return null;
+    const n = Number.parseInt(cursor, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    return n;
+}

package/build/adapters/omp/plugin.d.ts

@@ -52,6 +52,11 @@ type ToolCallEventResult = {
     block?: boolean;
     reason?: string;
 };
+type TurnEndEvent = {
+    type?: string;
+    message?: unknown;
+    messages?: unknown;
+};
 type HookEventCtx = Record<string, unknown> | undefined;
 type HookHandler<E, R = void> = (event: E, ctx: HookEventCtx) => R | undefined | Promise<R | undefined>;
 export interface MinimalHookAPI {
@@ -63,6 +68,7 @@ export interface MinimalHookAPI {
     }>): void;
     on(event: "tool_call", handler: HookHandler<ToolCallEvent, ToolCallEventResult>): void;
     on(event: "tool_result", handler: HookHandler<ToolResultEvent>): void;
+    on(event: "turn_end", handler: HookHandler<TurnEndEvent>): void;
     on(event: string, handler: (...args: unknown[]) => unknown): void;
 }
 /**

package/build/adapters/omp/plugin.js

@@ -24,11 +24,14 @@
  *      under OMP and is intentionally omitted here.
  */
 import { createHash } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveSessionDbPath, SessionDB } from "../../session/db.js";
-import { extractEvents } from "../../session/extract.js";
+import { extractEvents, buildAgentUsageEvent } from "../../session/extract.js";
 import { buildResumeSnapshot } from "../../session/snapshot.js";
 import { OMPAdapter } from "./index.js";
+import { parseOmpUsage } from "./usage.js";
 // ── Tool-name normalization ─────────────────────────────
 // OMP uses lowercase tool names (refs/.../hooks/types.ts:451 example
 // `toolName: "bash"`). Shared event extractors expect PascalCase
@@ -64,6 +67,57 @@ let _db = null;
 let _dbPath = "";
 let _sessionId = "";
 const _ompAdapter = new OMPAdapter();
+// ── MCP self-registration (issue #677) ───────────────────
+// The `omp plugin install context-mode` path wires THIS extension factory
+// (so routing hooks fire), but never creates the MCP config — so the 11
+// `ctx_*` tools stay unreachable even though curl/wget are blocked. Register
+// the server ourselves on plugin load, ONLY when absent (never clobber a
+// user's existing entry). Takes effect on the next OMP restart, same as the
+// manual mcp.json workaround the issue documents.
+const MCP_SERVER_NAME = "context-mode";
+// plugin.js ships at <pkg>/build/adapters/omp/plugin.js; the MCP server
+// bundle sits at the package root (<pkg>/server.bundle.mjs) — three up.
+const SERVER_BUNDLE_RELATIVE = "../../../server.bundle.mjs";
+function resolveServerBundle() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const bundle = resolve(here, SERVER_BUNDLE_RELATIVE);
+        return existsSync(bundle) ? bundle : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ensure `~/.omp/agent/mcp.json` registers the context-mode MCP server.
+ *
+ * Uses `node <abs>/server.bundle.mjs` rather than the `context-mode` bin:
+ * under the plugin install the package lives in `~/.omp/plugins/node_modules`
+ * and its bin is NOT on PATH, so the bare command would fail to spawn (the
+ * exact symptom reported on issue #677). Best effort — never throws, never
+ * breaks plugin load.
+ */
+function ensureMcpServerRegistered() {
+    try {
+        const bundle = resolveServerBundle();
+        if (!bundle)
+            return; // bundle missing → nothing safe to register
+        const settings = _ompAdapter.readSettings() ?? {};
+        const mcpServers = settings.mcpServers ?? {};
+        if (MCP_SERVER_NAME in mcpServers)
+            return; // already present — don't clobber
+        mcpServers[MCP_SERVER_NAME] = {
+            type: "stdio",
+            command: "node",
+            args: [bundle],
+        };
+        settings.mcpServers = mcpServers;
+        _ompAdapter.writeSettings(settings);
+    }
+    catch {
+        // best effort — a registration failure must never break plugin load
+    }
+}
 function getSessionDir() {
     const dir = _ompAdapter.getSessionDir();
     mkdirSync(dir, { recursive: true });
@@ -155,6 +209,9 @@ export default function ompPlugin(pi) {
     // earlier `OMP_PROJECT_DIR` read was an EM mistake — no upstream code
     // ever sets it. Drop it; fall through PI_PROJECT_DIR → cwd().
     const projectDir = process.env.PI_PROJECT_DIR || process.cwd();
+    // Self-register the MCP server so `ctx_*` tools are reachable under the
+    // plugin install path, not just the manual MCP-only path (issue #677).
+    ensureMcpServerRegistered();
     const db = getOrCreateDB(projectDir);
     // ── 1. session_start — initialize session row ─────────
     pi.on("session_start", (_event, ctx) => {
@@ -243,4 +300,32 @@ export default function ompPlugin(pi) {
         }
         return undefined;
     });
+    // ── 5. turn_end — per-turn token + provider cost capture ──
+    // OMP exposes REAL per-turn tokens AND a provider-computed USD cost on the
+    // completed turn's AssistantMessage (`event.message.usage` / `.model`),
+    // delivered INCREMENTALLY per turn (matrix §2,§5). parseOmpUsage maps that to
+    // the buildAgentUsageEvent counts (Usage.cacheWrite→cache_creation,
+    // cacheRead→cache_read, cost.total→native_cost_usd). buildAgentUsageEvent
+    // prefers the native cost over the local price table and returns null on an
+    // all-zero turn. We persist via db.insertEvent — the SessionDB-backed forward
+    // path used everywhere in this in-process plugin runtime (the .mjs
+    // attributeAndInsertEvents helper is the Claude-hook analogue, not reachable
+    // here). Best-effort: a usage parse must never break the turn.
+    pi.on("turn_end", (event) => {
+        try {
+            if (!_sessionId)
+                return undefined;
+            const counts = parseOmpUsage(event);
+            if (counts === null)
+                return undefined;
+            const usageEvent = buildAgentUsageEvent(counts);
+            if (usageEvent === null)
+                return undefined;
+            db.insertEvent(_sessionId, usageEvent, "PostToolUse");
+        }
+        catch {
+            // best effort — never break the turn on cost capture
+        }
+        return undefined;
+    });
 }

package/build/adapters/omp/usage.d.ts

@@ -0,0 +1,49 @@
+/**
+ * adapters/omp/usage — pure parse of an OMP `turn_end` / `agent_end` payload
+ * into the {@link buildAgentUsageEvent} counts shape.
+ *
+ * Ground truth (docs/prds/2026-06-paid-observability/adapter-matrix/omp.md §2-4):
+ *   - Per-turn usage rides on `AssistantMessage.usage`
+ *     (`refs/platforms/omp/packages/ai/src/types.ts:505-541`).
+ *   - The canonical `Usage` shape lives in pi-catalog
+ *     (`refs/platforms/omp/packages/catalog/src/types.ts:100-145`): fields
+ *     `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, plus a
+ *     fully-resolved `cost: { input, output, cacheRead, cacheWrite, total }`
+ *     (:138-144) — provider-computed, so NO client price table is needed.
+ *   - `model: string` is `provider/model` on the `AssistantMessage` (:510).
+ *   - `turn_end` carries `message: AssistantMessage`
+ *     (`refs/.../extensibility/shared-events.ts:204-208`); `agent_end` carries
+ *     `messages: AssistantMessage[]` (:191-194).
+ *
+ * Field mapping (matrix §3 → buildAgentUsageEvent input):
+ *   Usage.input      → input_tokens
+ *   Usage.output     → output_tokens
+ *   Usage.cacheWrite → cache_creation_tokens   (cache CREATION on the provider)
+ *   Usage.cacheRead  → cache_read_tokens
+ *   message.model    → model_id                (the `provider/model` string)
+ *   Usage.cost.total → native_cost_usd         (provider-computed, preferred)
+ *
+ * Algorithmic + null-safe. NO regex. Returns `null` whenever there is no
+ * usable signal (no message / no usage / every token bucket absent-or-zero),
+ * so a malformed or empty turn emits nothing.
+ */
+/**
+ * The counts object accepted by {@link buildAgentUsageEvent}. Re-declared here
+ * (structurally identical) so this module stays a leaf with no import cycle
+ * into the heavy `session/extract` module — the handler in `plugin.ts` passes
+ * the result straight through to `buildAgentUsageEvent`.
+ */
+export interface OmpUsageCounts {
+    model_id: string;
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_tokens: number;
+    cache_read_tokens: number;
+    native_cost_usd: number | null;
+}
+/**
+ * Parse an OMP `turn_end` / `agent_end` event payload into the
+ * {@link buildAgentUsageEvent} counts shape, or `null` when no usable usage is
+ * present. Pure and side-effect free.
+ */
+export declare function parseOmpUsage(payload: unknown): OmpUsageCounts | null;

package/build/adapters/omp/usage.js

@@ -0,0 +1,110 @@
+/**
+ * adapters/omp/usage — pure parse of an OMP `turn_end` / `agent_end` payload
+ * into the {@link buildAgentUsageEvent} counts shape.
+ *
+ * Ground truth (docs/prds/2026-06-paid-observability/adapter-matrix/omp.md §2-4):
+ *   - Per-turn usage rides on `AssistantMessage.usage`
+ *     (`refs/platforms/omp/packages/ai/src/types.ts:505-541`).
+ *   - The canonical `Usage` shape lives in pi-catalog
+ *     (`refs/platforms/omp/packages/catalog/src/types.ts:100-145`): fields
+ *     `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, plus a
+ *     fully-resolved `cost: { input, output, cacheRead, cacheWrite, total }`
+ *     (:138-144) — provider-computed, so NO client price table is needed.
+ *   - `model: string` is `provider/model` on the `AssistantMessage` (:510).
+ *   - `turn_end` carries `message: AssistantMessage`
+ *     (`refs/.../extensibility/shared-events.ts:204-208`); `agent_end` carries
+ *     `messages: AssistantMessage[]` (:191-194).
+ *
+ * Field mapping (matrix §3 → buildAgentUsageEvent input):
+ *   Usage.input      → input_tokens
+ *   Usage.output     → output_tokens
+ *   Usage.cacheWrite → cache_creation_tokens   (cache CREATION on the provider)
+ *   Usage.cacheRead  → cache_read_tokens
+ *   message.model    → model_id                (the `provider/model` string)
+ *   Usage.cost.total → native_cost_usd         (provider-computed, preferred)
+ *
+ * Algorithmic + null-safe. NO regex. Returns `null` whenever there is no
+ * usable signal (no message / no usage / every token bucket absent-or-zero),
+ * so a malformed or empty turn emits nothing.
+ */
+/** Coerce an unknown to a finite non-negative integer token count, else 0. */
+function toTokenCount(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return 0;
+    }
+    // Token counts are integers upstream; floor defensively against floats.
+    return Math.floor(value);
+}
+/** Coerce an unknown to a finite USD cost, else null (so the catalog can fill in). */
+function toCostUsd(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return null;
+    }
+    return value;
+}
+/** Narrow an unknown to a plain (non-null, non-array) object. */
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+/**
+ * Resolve the per-turn `AssistantMessage` from a `turn_end` (`.message`) or
+ * `agent_end` (`.messages[]`) payload. For `agent_end` we take the LAST
+ * assistant message — that is the turn that just completed and whose usage is
+ * the new delta (OMP usage is INCREMENTAL per turn, matrix §5).
+ */
+function resolveMessage(payload) {
+    const single = asRecord(payload.message);
+    if (single !== null)
+        return single;
+    const list = payload.messages;
+    if (Array.isArray(list)) {
+        for (let i = list.length - 1; i >= 0; i--) {
+            const m = asRecord(list[i]);
+            if (m !== null)
+                return m;
+        }
+    }
+    return null;
+}
+/**
+ * Parse an OMP `turn_end` / `agent_end` event payload into the
+ * {@link buildAgentUsageEvent} counts shape, or `null` when no usable usage is
+ * present. Pure and side-effect free.
+ */
+export function parseOmpUsage(payload) {
+    const root = asRecord(payload);
+    if (root === null)
+        return null;
+    const message = resolveMessage(root);
+    if (message === null)
+        return null;
+    const usage = asRecord(message.usage);
+    if (usage === null)
+        return null;
+    const input_tokens = toTokenCount(usage.input);
+    const output_tokens = toTokenCount(usage.output);
+    const cache_creation_tokens = toTokenCount(usage.cacheWrite);
+    const cache_read_tokens = toTokenCount(usage.cacheRead);
+    // No usable token signal → no event (mirrors buildAgentUsageEvent's own
+    // all-zero guard, but lets the handler short-circuit before building).
+    if (input_tokens <= 0 &&
+        output_tokens <= 0 &&
+        cache_creation_tokens <= 0 &&
+        cache_read_tokens <= 0) {
+        return null;
+    }
+    const model_id = typeof message.model === "string" ? message.model : "";
+    const cost = asRecord(usage.cost);
+    const native_cost_usd = cost !== null ? toCostUsd(cost.total) : null;
+    return {
+        model_id,
+        input_tokens,
+        output_tokens,
+        cache_creation_tokens,
+        cache_read_tokens,
+        native_cost_usd,
+    };
+}

package/build/adapters/openclaw/plugin.d.ts

@@ -78,6 +78,16 @@ interface OpenClawPluginApi {
     registerTool?(tool: OpenClawToolDef, opts?: {
         optional?: boolean;
     }): void;
+    /**
+     * Subscribe to the openclaw diagnostic-event bus (`model.usage` carries
+     * per-turn token usage + pre-computed costUsd — diagnostic-events.ts:1156).
+     * Some hosts surface `onDiagnosticEvent` directly on the activation `api`;
+     * others expose it only as a module export from
+     * `openclaw/plugin-sdk/diagnostic-runtime`. Typed loosely + optional so the
+     * plugin compiles and runs whether or not the host provides it (the SDK is
+     * not a dependency of this repo). Returns an unsubscribe function.
+     */
+    onDiagnosticEvent?(listener: (evt: unknown) => void): (() => void) | void;
     logger?: {
         info: (...args: unknown[]) => void;
         error: (...args: unknown[]) => void;

package/build/adapters/openclaw/plugin.js

@@ -39,6 +39,7 @@ import { OpenClawSessionDB } from "./session-db.js";
 import { extractEvents, extractUserEvents } from "../../session/extract.js";
 import { buildResumeSnapshot } from "../../session/snapshot.js";
 import { WorkspaceRouter } from "./workspace-router.js";
+import { handleOpenclawUsageEvent } from "./usage.js";
 import { buildNodeCommand } from "../types.js";
 import { OPENCLAW_TOOL_DEFS } from "./mcp-tools.js";
 // ── System-reminder filter (CCv2 — SLICE OClaw-3) ─────────
@@ -384,6 +385,62 @@ export default {
                 // Silent — session capture must never break the tool call
             }
         });
+        // ── 2b. model.usage — Per-turn token + cost capture ──────
+        // openclaw emits a first-class `model.usage` diagnostic event once per turn
+        // carrying the full usage breakdown + a pre-computed costUsd. We subscribe
+        // to the diagnostic-event bus (NOT the tool-call hook — before/after_tool_call
+        // carry approval/policy data only, no token usage). The handler
+        // (handleOpenclawUsageEvent) is decoupled + unit-tested; it parses → builds →
+        // inserts and never throws.
+        //
+        // tsc-safe SDK access: `onDiagnosticEvent` comes from the openclaw plugin SDK
+        // (`openclaw/plugin-sdk/diagnostic-runtime`), which is NOT in this repo's
+        // node_modules — a static import would break the build. We resolve it at
+        // runtime two ways, both best-effort:
+        //   1. directly off the activation `api` if the host surfaces it there;
+        //   2. otherwise a guarded dynamic import via a COMPUTED specifier string
+        //      (TS treats it as Promise<any> and skips module resolution, mirroring
+        //      the pathToFileURL(...).href dynamic imports above). Missing SDK → no-op.
+        const subscribeDiagnostics = (onDiag) => {
+            try {
+                onDiag((evt) => {
+                    try {
+                        const sid = sessionId; // snapshot to avoid race with session_start re-key
+                        handleOpenclawUsageEvent(evt, (e) => db.insertEvent(sid, e, "Diagnostic"));
+                    }
+                    catch {
+                        // Usage capture must never break the agent turn.
+                    }
+                });
+                log.debug("model.usage diagnostic subscription registered");
+            }
+            catch (err) {
+                log.warn?.("model.usage diagnostic subscription failed", err);
+            }
+        };
+        if (typeof api.onDiagnosticEvent === "function") {
+            subscribeDiagnostics(api.onDiagnosticEvent.bind(api));
+        }
+        else {
+            // Computed specifier so NodeNext does not try to resolve the (absent) SDK
+            // module at build time — the dynamic import is typed as Promise<any>.
+            const diagnosticRuntimeSpecifier = ["openclaw", "plugin-sdk", "diagnostic-runtime"].join("/");
+            void (async () => {
+                try {
+                    const mod = (await import(diagnosticRuntimeSpecifier));
+                    if (typeof mod?.onDiagnosticEvent === "function") {
+                        subscribeDiagnostics(mod.onDiagnosticEvent);
+                    }
+                    else {
+                        log.debug("diagnostic-runtime loaded but onDiagnosticEvent missing");
+                    }
+                }
+                catch {
+                    // SDK not installed (dev/test) — usage capture silently inert.
+                    log.debug("openclaw plugin-sdk/diagnostic-runtime unavailable — usage capture inert");
+                }
+            })();
+        }
         // ── 3. command:new — Session initialization ────────────
         registerCommandHook("command:new", async () => {
             try {

package/build/adapters/openclaw/usage.d.ts

@@ -0,0 +1,34 @@
+/**
+ * adapters/openclaw/usage — per-turn token + cost capture handler.
+ *
+ * openclaw emits a first-class `model.usage` diagnostic event once per turn
+ * (`DiagnosticUsageEvent`, refs/platforms/openclaw/src/infra/diagnostic-events.ts:18-47),
+ * carrying the full usage breakdown {input, output, cacheRead, cacheWrite} plus
+ * a PRE-COMPUTED `costUsd` (estimateUsageCost, agent-runner.ts:1995). Consumers
+ * subscribe via `onDiagnosticEvent(listener)` (diagnostic-events.ts:1156) — the
+ * exact bus the first-party diagnostics-otel / diagnostics-prometheus extensions
+ * read.
+ *
+ * This module is the parse→build→insert handler the plugin's diagnostic-event
+ * listener invokes. It is deliberately decoupled from the openclaw plugin SDK so
+ * it stays unit-testable: the caller passes the raw payload and an `insert`
+ * callback (the plugin hands it `db.insertEvent`-bound-to-sessionId). The handler
+ * never throws — a usage-capture failure must never break the agent turn.
+ *
+ * Capture surface: the diagnostic-event bus, NOT the tool-call hook. The native
+ * before_tool_call / after_tool_call relay carries only approval/policy data and
+ * NO token usage (matrix §4) — so usage cannot be captured from after_tool_call.
+ */
+import type { SessionEvent } from "../../session/extract.js";
+/** Minimal event-insert surface the handler needs (satisfied by SessionDB.insertEvent bound to a sessionId). */
+export type OpenClawUsageInsert = (event: SessionEvent) => void;
+/**
+ * Handle one openclaw `model.usage` diagnostic payload: parse the per-turn usage
+ * (NOT lastCallUsage), build the structured `agent_usage` event with openclaw's
+ * native `costUsd` (preferred over the pricing catalog), and insert it.
+ *
+ * Returns the inserted event (for tests / callers that want to forward) or null
+ * when the payload is not a usage event, carries no usage, or sums to zero.
+ * Best-effort: swallows any insert failure.
+ */
+export declare function handleOpenclawUsageEvent(payload: unknown, insert: OpenClawUsageInsert): SessionEvent | null;