pi-langfuse 1.5.19 → 1.6.0

package/README.md

@@ -269,6 +269,12 @@ This command makes a timeout-bounded authenticated request to Langfuse and, if i
 - Tool runs appear as tool observations with arguments, results, and error state.
 - LLM requests appear as generation observations, including usage and cost when the provider exposes them.
   Reasoning tokens are reported as their own usage bucket when `PI_LANGFUSE_SPLIT_REASONING_TOKENS` is enabled.
+- Pi 0.86 transcript-aware prompt/tool state appears as `system-state` events. Generations reference the
+  effective prompt/tool state hashes, active tool count, update transport, and cache hit ratio.
+- Automatic retries are grouped under `agent-attempt` spans and the trace remains open until `agent_settled`.
+- Cache-warming decisions and persisted `cache_warm` usage are reported, including standalone session-grouped
+  traces when warming happens while no user-request trace is active.
+- Compaction is recorded as `session-compaction`, with a nested `compaction-summary` generation when usage is available.
 - Trace-level scores include tool counts, tool success rate, and whether the run had errors.
 
 The package also includes a Langfuse CLI skill, so Langfuse data can be queried directly from Pi:

package/README_CN.md

@@ -250,6 +250,12 @@ pi list
 - 工具执行会以工具观察节点展示参数、结果和错误状态。
 - 模型请求会以生成观察节点展示；如果提供商暴露相关信息，还会包含用量和成本。
   开启 `PI_LANGFUSE_SPLIT_REASONING_TOKENS` 后，推理 token 会作为独立用量桶上报。
+- Pi 0.86 的 transcript-aware system/tool 状态会作为 `system-state` 事件上报；generation 会引用有效的
+  prompt/tool 状态指纹、活动工具数、更新传输方式和缓存命中率。
+- 自动重试会归入 `agent-attempt` span，trace 会持续到 `agent_settled` 才结束。
+- cache warming 决策及持久化的 `cache_warm` 用量会被记录；若 warming 发生时没有活动的用户请求 trace，
+  会创建按相同 session 分组的独立 trace。
+- compaction 会记录为 `session-compaction`；若存在摘要用量，则包含 `compaction-summary` generation。
 - trace 级别会记录工具调用次数、工具成功率和是否出现错误。
 
 此包还包含一个内置 Langfuse 技能，可直接在 Pi 中查询 Langfuse 数据：

package/index.ts

@@ -14,10 +14,23 @@ import { state, resetRunState, runWithSession, setCurrentSession } from "./src/s
 import { ensureConfig, promptForConfig, loadConfig } from "./src/config.js";
 import { shutdownRuntime } from "./src/langfuse.js";
 import { handleLangfusePrivacyCommand, handleLangfuseStatusCommand, handleLangfuseTestCommand } from "./src/commands.js";
-import { getMessageFromEvent, extractAssistantOutput, getCapturePolicy } from "./src/utils.js";
-import { applyCapturePolicy } from "./src/capture-policy.js";
-import { startAgentRun, finishAgentRun, recordSystemPrompt } from "./src/handlers/agent.js";
+import { getMessageFromEvent, extractAssistantOutput } from "./src/utils.js";
+import {
+  startAgentRun,
+  finishAgentRun,
+  finishAgentAttempt,
+  cancelAgentRun,
+  recordSystemPrompt,
+  startAgentAttempt,
+} from "./src/handlers/agent.js";
 import { startTurnObservation, finishTurnObservation } from "./src/handlers/turn.js";
+import { initializeSystemStateTracking, recordSystemState } from "./src/handlers/system-state.js";
+import {
+  initializeUsageTracking,
+  recordCacheWarmingDecision,
+  recordNewUsageEntries,
+} from "./src/handlers/cache.js";
+import { recordSessionCompaction } from "./src/handlers/session.js";
 import {
   startGeneration,
   updateGenerationMetadata,
@@ -28,7 +41,6 @@ import {
 import {
   startToolObservation,
   finishToolObservation,
-  closeDanglingObservations,
 } from "./src/handlers/tool.js";
 
 // ============================================
@@ -36,6 +48,7 @@ import {
 // ============================================
 
 export default async function (pi: ExtensionAPI) {
+  const asRecord = (value: object): Record<string, unknown> => value as unknown as Record<string, unknown>;
   if (!state.config) {
     state.config = loadConfig();
   }
@@ -97,6 +110,8 @@ export default async function (pi: ExtensionAPI) {
     state.setupAttemptedThisSession = false;
     await ensureConfig(ctx);
     resetRunState();
+    initializeSystemStateTracking(ctx);
+    initializeUsageTracking(ctx);
   }));
 
   pi.on("model_select", async (event, ctx) => withSession(ctx, async () => {
@@ -105,84 +120,87 @@ export default async function (pi: ExtensionAPI) {
   }));
 
   pi.on("before_agent_start", async (event, ctx) => withSession(ctx, async () => {
-    await startAgentRun(event, ctx);
+    await recordNewUsageEntries(ctx);
+    await startAgentRun(asRecord(event), ctx);
   }));
 
   pi.on("agent_start", async (event, ctx) => withSession(ctx, async () => {
     if (!state.agentState?.root) {
-      await startAgentRun(event, ctx);
+      await startAgentRun(asRecord(event), ctx);
     }
+    await startAgentAttempt();
     // The system prompt is only final here: before_agent_start handlers that
     // run after this extension may still rewrite it.
     await recordSystemPrompt(ctx);
+    await recordSystemState(ctx, pi.getActiveTools());
+  }));
+
+  pi.on("cache_warming_decision", async (event, ctx) => withSession(ctx, async () => {
+    await recordNewUsageEntries(ctx);
+    await recordCacheWarmingDecision(asRecord(event), ctx);
   }));
 
   pi.on("turn_start", async (event, ctx) => withSession(ctx, async () => {
-    await startTurnObservation(event);
+    await startTurnObservation(asRecord(event));
   }));
 
   pi.on("before_provider_request", async (event, ctx) => withSession(ctx, async () => {
-    await startGeneration(event);
+    await startGeneration(asRecord(event));
   }));
 
   pi.on("after_provider_response", async (event, ctx) => withSession(ctx, async () => {
-    updateGenerationMetadata(event);
+    updateGenerationMetadata(asRecord(event));
   }));
 
   pi.on("message_update", async (event, ctx) => withSession(ctx, async () => {
-    recordTTFT(event);
-    const message = getMessageFromEvent(event);
+    recordTTFT(asRecord(event));
+    const message = getMessageFromEvent(asRecord(event));
     if (message?.role === "assistant" && state.agentState) {
       state.agentState.latestAssistantOutput = extractAssistantOutput(message);
     }
   }));
 
   pi.on("message_end", async (event, ctx) => withSession(ctx, async () => {
-    await finishGenerationFromMessage(event);
+    await finishGenerationFromMessage(asRecord(event));
   }));
 
   pi.on("tool_execution_start", async (event, ctx) => withSession(ctx, async () => {
-    await startToolObservation(event);
+    await startToolObservation(asRecord(event));
   }));
 
   pi.on("tool_call", async (event, ctx) => withSession(ctx, async () => {
-    await startToolObservation(event);
+    await startToolObservation(asRecord(event));
   }));
 
   pi.on("tool_result", async (event, ctx) => withSession(ctx, async () => {
-    await finishToolObservation(event);
+    await finishToolObservation(asRecord(event));
   }));
 
   pi.on("tool_execution_end", async (event, ctx) => withSession(ctx, async () => {
-    await finishToolObservation(event);
+    await finishToolObservation(asRecord(event));
   }));
 
   pi.on("turn_end", async (event, ctx) => withSession(ctx, async () => {
     state.turnCount++;
-    const message = getMessageFromEvent(event);
+    const record = asRecord(event);
+    const message = getMessageFromEvent(record);
     if (message?.role === "assistant") {
-      await createFallbackGenerationFromTurn(event, message);
-      await finishGenerationFromMessage(event);
+      await createFallbackGenerationFromTurn(record, message);
+      await finishGenerationFromMessage(record);
     }
-    finishTurnObservation(event);
+    finishTurnObservation(record);
   }));
 
   pi.on("agent_end", async (event, ctx) => withSession(ctx, async () => {
-    await finishAgentRun(event);
-    const sessionId = state.currentSessionId;
-    try {
-      await shutdownRuntime(sessionId);
-    } catch (error) {
-      console.warn("📊 Langfuse: Shutdown failed", error);
-    }
+    finishAgentAttempt(asRecord(event));
+  }));
+
+  pi.on("agent_settled", async (_event, ctx) => withSession(ctx, async () => {
+    await finishAgentRun();
   }));
 
   const handleSessionInterruption = (reason: string) => {
-    if (state.agentState?.root) {
-      closeDanglingObservations(reason);
-      state.agentState.root.update({ metadata: { completed: false, cancelled: true } }).end();
-    }
-    resetRunState();
+    cancelAgentRun(reason);
   };
 
   pi.on("session_before_switch", async (_event, ctx) => {
@@ -200,26 +218,11 @@ export default async function (pi: ExtensionAPI) {
   });
 
   pi.on("session_compact", async (event, ctx) => withSession(ctx, async () => {
-    if (state.agentState?.root) {
-      const parent = state.agentState.activeTurn ?? state.agentState.root;
-      try {
-        const observation = parent.startObservation ? parent.startObservation(
-          "session_compact", 
-          {
-            level: "DEFAULT",
-            statusMessage: "Context was compacted",
-            metadata: applyCapturePolicy({ metadata: { ...event } }, getCapturePolicy()).metadata
-          }, 
-          { asType: "span" }
-        ) : undefined;
-        observation?.end();
-      } catch (e) {
-        // ignore
-      }
-    }
+    await recordSessionCompaction(asRecord(event));
   }));
 
   pi.on("session_shutdown", async (_event, ctx) => withSession(ctx, async () => {
+    await recordNewUsageEntries(ctx);
     handleSessionInterruption("Session shutdown before agent completed");
     await shutdownRuntime();
   }));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-langfuse",
-	"version": "1.5.19",
+	"version": "1.6.0",
 	"description": "Langfuse extension for Pi coding agent",
 	"repository": {
 		"type": "git",
@@ -16,7 +16,6 @@
 	"files": [
 		"index.ts",
 		"src/",
-		"types/",
 		"README.md",
 		"README_CN.md",
 		"image.png",
@@ -52,7 +51,7 @@
 		"@opentelemetry/sdk-trace-base": "^2.0.1"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*"
+		"@earendil-works/pi-coding-agent": ">=0.86.0"
 	},
 	"publishConfig": {
 		"access": "public",
@@ -63,6 +62,7 @@
 		"node": ">=22"
 	},
 	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^0.86.0",
 		"tsx": "^4.19.0",
 		"typescript": "^6.0.3"
 	}

package/src/handlers/agent.ts

@@ -5,6 +5,7 @@ import { shapePayload, truncate, extractFinalAssistant, extractAssistantOutput,
 import { closeDanglingObservations } from "./tool.js";
 import { applyCapturePolicy } from "../capture-policy.js";
 import { collectSourceMetadata } from "../source-metadata.js";
+import { startChildObservation } from "../observation.js";
 
 function stringMetadata(metadata: Record<string, unknown> | undefined): Record<string, string> | undefined {
   if (!metadata) {
@@ -70,6 +71,7 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
           ...(state.currentModel ? { model: state.currentModel } : {}),
           ...(state.currentProvider ? { provider: state.currentProvider } : {}),
           sessionId: state.currentSessionId || undefined,
+          sessionLeafId: ctx?.sessionManager?.getLeafId?.() || undefined,
         },
       },
       capturePolicy,
@@ -84,6 +86,11 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
       activeTools: new Map(),
       sourceMetadata,
       providerMetadataByRequest: new Map(),
+      attemptCount: 0,
+      systemStateChangeCount: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      uncachedInputTokens: 0,
     };
 
     const root = rt.propagateAttributes(
@@ -112,6 +119,82 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
   }
 }
 
+export async function startAgentAttempt() {
+  const agent = state.agentState;
+  if (state.isTracingDisabled || !agent?.root) return;
+
+  if (agent.activeAttempt) {
+    agent.activeAttempt
+      .update({ level: "WARNING", statusMessage: "A new agent attempt started before the previous attempt ended" })
+      .end();
+  }
+
+  try {
+    agent.attemptCount++;
+    agent.activeAttempt = await startChildObservation({
+      parent: agent.root,
+      runtime: getRuntime,
+      name: "agent-attempt",
+      body: { metadata: { attemptIndex: agent.attemptCount } },
+      asType: "span",
+    });
+  } catch (error) {
+    console.warn("📊 Langfuse: Failed to start agent attempt", error);
+  }
+}
+
+export function finishAgentAttempt(event: Record<string, unknown> = {}) {
+  const agent = state.agentState;
+  if (!agent) return;
+  agent.lastAgentEndEvent = event;
+
+  closeDanglingObservations("Agent attempt ended before observation finalized");
+  if (agent.activeTurn) {
+    agent.activeTurn
+      .update({ level: "WARNING", statusMessage: "Agent attempt ended before turn finalized" })
+      .end();
+    agent.activeTurn = undefined;
+  }
+
+  if (!agent.activeAttempt) return;
+  try {
+    const lastAssistant = extractFinalAssistant(event.messages);
+    const captured = applyCapturePolicy(
+      { output: lastAssistant ? extractAssistantOutput(lastAssistant) : undefined },
+      getCapturePolicy(),
+    );
+    agent.activeAttempt.update({ output: captured.output }).end();
+  } catch (error) {
+    console.warn("📊 Langfuse: Failed to finish agent attempt", error);
+  } finally {
+    agent.activeAttempt = undefined;
+  }
+}
+
+export function cancelAgentRun(reason: string) {
+  const agent = state.agentState;
+  if (!agent?.root) {
+    resetRunState();
+    return;
+  }
+
+  closeDanglingObservations(reason);
+  if (agent.activeTurn) {
+    agent.activeTurn.update({ level: "WARNING", statusMessage: reason, metadata: { cancelled: true } }).end();
+    agent.activeTurn = undefined;
+  }
+  if (agent.activeAttempt) {
+    agent.activeAttempt.update({ level: "WARNING", statusMessage: reason, metadata: { cancelled: true } }).end();
+    agent.activeAttempt = undefined;
+  }
+  agent.root.update({
+    level: "WARNING",
+    statusMessage: reason,
+    metadata: { completed: false, cancelled: true },
+  }).end();
+  resetRunState();
+}
+
 /**
  * Records the effective system prompt on the root agent observation.
  *
@@ -161,7 +244,8 @@ export async function finishAgentRun(event: Record<string, unknown> = {}) {
     return;
   }
 
-  const lastAssistant = extractFinalAssistant(event.messages);
+  const finalEvent = Object.keys(event).length > 0 ? event : state.agentState.lastAgentEndEvent ?? {};
+  const lastAssistant = extractFinalAssistant(finalEvent.messages);
   const rawOutput = lastAssistant ? extractAssistantOutput(lastAssistant) : state.agentState.latestAssistantOutput;
   const captured = applyCapturePolicy(
     {
@@ -173,6 +257,19 @@ export async function finishAgentRun(event: Record<string, unknown> = {}) {
         model: state.currentModel || undefined,
         provider: state.currentProvider || undefined,
         totalTools: state.toolCallCount,
+        agentAttemptCount: state.agentState.attemptCount,
+        systemStateChangeCount: state.agentState.systemStateChangeCount,
+        promptStateHash: state.agentState.promptStateHash,
+        toolStateHash: state.agentState.toolStateHash,
+        activeToolCount: state.agentState.activeToolCount,
+        cacheReadTokens: state.agentState.cacheReadTokens,
+        cacheWriteTokens: state.agentState.cacheWriteTokens,
+        uncachedInputTokens: state.agentState.uncachedInputTokens,
+        cacheHitRatio:
+          state.agentState.cacheReadTokens + state.agentState.uncachedInputTokens > 0
+            ? state.agentState.cacheReadTokens /
+              (state.agentState.cacheReadTokens + state.agentState.uncachedInputTokens)
+            : undefined,
         ...computeEvaluationScores(),
       },
     },
@@ -181,6 +278,10 @@ export async function finishAgentRun(event: Record<string, unknown> = {}) {
   const scores = computeEvaluationScores();
 
   closeDanglingObservations("Agent run ended before observation finalized");
+  if (state.agentState.activeAttempt) {
+    state.agentState.activeAttempt.end();
+    state.agentState.activeAttempt = undefined;
+  }
 
   try {
     state.agentState.root

package/src/handlers/cache.ts

@@ -0,0 +1,147 @@
+import { applyCapturePolicy } from "../capture-policy.js";
+import { getRuntime } from "../langfuse.js";
+import { startChildObservation } from "../observation.js";
+import { getSessionRunState, state } from "../state.js";
+import { extractCostDetails, extractUsage, getCapturePolicy, truncate } from "../utils.js";
+
+type RecordLike = Record<string, unknown>;
+
+function sessionIdForTrace(): string | undefined {
+  return state.currentSessionId ? truncate(state.currentSessionId, 200) : undefined;
+}
+
+export function initializeUsageTracking(ctx: any): void {
+  const session = getSessionRunState();
+  try {
+    const entries = ctx?.sessionManager?.getEntries?.();
+    if (!Array.isArray(entries)) return;
+    for (const entry of entries) {
+      if (entry && typeof entry === "object" && (entry as RecordLike).type === "usage") {
+        const id = (entry as RecordLike).id;
+        if (typeof id === "string") session.seenUsageEntryIds.add(id);
+      }
+    }
+  } catch {
+    // Optional for SDK hosts without persisted sessions.
+  }
+}
+
+export async function recordCacheWarmingDecision(event: RecordLike, ctx: any): Promise<void> {
+  if (state.isTracingDisabled || !state.config) return;
+  const contextUsage = ctx?.getContextUsage?.();
+  const captured = applyCapturePolicy(
+    {
+      metadata: {
+        action: event.action,
+        warmCostEstimate: event.warmCost,
+        missCostEstimate: event.missCost,
+        continuationProbability: event.continuationProbability,
+        contextTokens: contextUsage?.tokens,
+        contextWindow: contextUsage?.contextWindow,
+        contextPercent: contextUsage?.percent,
+        idle: ctx?.isIdle?.(),
+        model: ctx?.model?.id,
+        provider: ctx?.model?.provider,
+      },
+    },
+    getCapturePolicy(),
+  );
+
+  try {
+    const parent = state.agentState?.activeTurn ?? state.agentState?.activeAttempt ?? state.agentState?.root;
+    if (parent) {
+      const observation = await startChildObservation({
+        parent,
+        runtime: getRuntime,
+        name: "cache-warming-decision",
+        body: { metadata: captured.metadata },
+        asType: "event",
+      });
+      observation.end();
+      return;
+    }
+
+    const runtime = await getRuntime();
+    const create = () => runtime.propagateAttributes(
+      {
+        sessionId: sessionIdForTrace(),
+        traceName: "pi-cache-warming",
+        metadata: {
+          ...(ctx?.model?.id ? { model: String(ctx.model.id) } : {}),
+          ...(ctx?.model?.provider ? { provider: String(ctx.model.provider) } : {}),
+        },
+      },
+      () => runtime.startObservation(
+        "cache-warming-decision",
+        { metadata: captured.metadata },
+        { asType: "event" },
+      ),
+    );
+    const observation = runtime.withRootContext ? runtime.withRootContext(create) : create();
+    observation.end();
+  } catch (error) {
+    console.warn("📊 Langfuse: Failed to record cache warming decision", error);
+  }
+}
+
+export async function recordNewUsageEntries(ctx: any): Promise<void> {
+  if (state.isTracingDisabled || !state.config) return;
+  const session = getSessionRunState();
+  let entries: unknown;
+  try {
+    entries = ctx?.sessionManager?.getEntries?.();
+  } catch {
+    return;
+  }
+  if (!Array.isArray(entries)) return;
+
+  for (const rawEntry of entries) {
+    if (!rawEntry || typeof rawEntry !== "object") continue;
+    const entry = rawEntry as RecordLike;
+    if (entry.type !== "usage" || typeof entry.id !== "string" || session.seenUsageEntryIds.has(entry.id)) continue;
+    if (entry.kind !== "cache_warm") {
+      session.seenUsageEntryIds.add(entry.id);
+      continue;
+    }
+
+    const usageDetails = extractUsage(entry);
+    const costDetails = extractCostDetails(entry);
+    const captured = applyCapturePolicy(
+      {
+        metadata: {
+          usageEntryId: entry.id,
+          kind: entry.kind,
+          note: entry.note,
+          provider: entry.provider,
+        },
+      },
+      getCapturePolicy(),
+    );
+
+    try {
+      const runtime = await getRuntime();
+      const parent = state.agentState?.activeTurn ?? state.agentState?.activeAttempt ?? state.agentState?.root;
+      const body = {
+        model: typeof entry.model === "string" ? entry.model : undefined,
+        usageDetails,
+        ...(costDetails ? { costDetails } : {}),
+        metadata: captured.metadata,
+      };
+      const observation = parent
+        ? await startChildObservation({ parent, runtime: getRuntime, name: "cache-warm", body, asType: "generation" })
+        : (runtime.withRootContext
+            ? runtime.withRootContext(() => runtime.propagateAttributes(
+                { sessionId: sessionIdForTrace(), traceName: "pi-cache-warm" },
+                () => runtime.startObservation("cache-warm", body, { asType: "generation" }),
+              ))
+            : runtime.propagateAttributes(
+                { sessionId: sessionIdForTrace(), traceName: "pi-cache-warm" },
+                () => runtime.startObservation("cache-warm", body, { asType: "generation" }),
+              ));
+      observation.end();
+      session.seenUsageEntryIds.add(entry.id);
+    } catch (error) {
+      console.warn("📊 Langfuse: Failed to record cache warming usage", error);
+    }
+  }
+}

package/src/handlers/generation.ts

@@ -12,6 +12,8 @@ import {
   extractCostDetails,
   getCapturePolicy,
   extractModelParameters,
+  extractCacheMetrics,
+  inferToolUpdateTransport,
 } from "../utils.js";
 import type { GenerationState, ObservationUpdate } from "../types.js";
 import { applyCapturePolicy } from "../capture-policy.js";
@@ -43,11 +45,26 @@ export async function startGeneration(event: Record<string, unknown>) {
     const modelParameters = extractModelParameters(payload);
     const model = String(event.model ?? event.modelId ?? state.currentModel ?? "");
     const provider = String(event.provider ?? state.currentProvider ?? "");
+    const toolUpdateTransport = inferToolUpdateTransport(payload, (state.agentState.systemStateSequence ?? 0) > 1);
     const metadata = shapePayload({
       provider,
       requestId: key,
       url: event.url,
       method: event.method,
+      promptStateHash: state.agentState.promptStateHash,
+      toolStateHash: state.agentState.toolStateHash,
+      systemStateSequence: state.agentState.systemStateSequence,
+      activeToolCount: state.agentState.activeToolCount,
+      toolUpdateTransport,
+      cachePreservationExpected:
+        toolUpdateTransport === "anthropic-native" ||
+        toolUpdateTransport === "openai-additional-tools" ||
+        toolUpdateTransport === "openai-tool-search" ||
+        toolUpdateTransport === "mid-conversation-system"
+          ? true
+          : toolUpdateTransport === "collapsed-leading-system"
+            ? false
+            : undefined,
     }) as Record<string, unknown>;
     const captured = applyCapturePolicy(
       {
@@ -57,7 +74,7 @@ export async function startGeneration(event: Record<string, unknown>) {
       getCapturePolicy(),
     );
 
-    const parent = state.agentState.activeTurn ?? state.agentState.root;
+    const parent = state.agentState.activeTurn ?? state.agentState.activeAttempt ?? state.agentState.root;
     const generation = await startChildObservation({
       parent,
       runtime: getRuntime,
@@ -177,6 +194,7 @@ export async function finishGenerationFromMessage(event: Record<string, unknown>
 
   const usageDetails = extractUsage({ ...event, message });
   const costDetails = extractCostDetails({ ...event, message });
+  const cacheMetrics = extractCacheMetrics({ ...event, message });
   const modelParameters = extractModelParameters(getProviderPayload(event)) ?? generation.modelParameters;
   const model = String(message.model ?? event.model ?? state.currentModel ?? "");
   const update: ObservationUpdate = {
@@ -188,6 +206,7 @@ export async function finishGenerationFromMessage(event: Record<string, unknown>
     metadata: {
       ...generation.metadata,
       finishReason: message.finishReason ?? message.stopReason ?? event.finishReason,
+      ...cacheMetrics,
     },
   };
   update.metadata = applyCapturePolicy({ metadata: update.metadata }, getCapturePolicy()).metadata;
@@ -195,6 +214,12 @@ export async function finishGenerationFromMessage(event: Record<string, unknown>
   try {
     generation.observation.update(update).end();
     generation.ended = true;
+    if (cacheMetrics) {
+      state.agentState.cacheReadTokens = (state.agentState.cacheReadTokens ?? 0) + cacheMetrics.cacheReadTokens;
+      state.agentState.cacheWriteTokens = (state.agentState.cacheWriteTokens ?? 0) + cacheMetrics.cacheWriteTokens;
+      state.agentState.uncachedInputTokens =
+        (state.agentState.uncachedInputTokens ?? 0) + cacheMetrics.uncachedInputTokens;
+    }
   } catch (e) {
     console.warn("📊 Langfuse: Failed to finish generation", e);
   }
@@ -208,6 +233,7 @@ export async function createFallbackGenerationFromTurn(event: Record<string, unk
   try {
     const usageDetails = extractUsage({ ...event, message });
     const costDetails = extractCostDetails({ ...event, message });
+    const cacheMetrics = extractCacheMetrics({ ...event, message });
     const modelParameters = extractModelParameters(getProviderPayload(event));
     const model = String(message.model ?? event.model ?? state.currentModel ?? "");
     const captured = applyCapturePolicy(
@@ -217,11 +243,16 @@ export async function createFallbackGenerationFromTurn(event: Record<string, unk
         metadata: {
           provider: state.currentProvider || undefined,
           sourceEvent: "turn_end",
+          promptStateHash: state.agentState.promptStateHash,
+          toolStateHash: state.agentState.toolStateHash,
+          systemStateSequence: state.agentState.systemStateSequence,
+          activeToolCount: state.agentState.activeToolCount,
+          ...cacheMetrics,
         },
       },
       getCapturePolicy(),
     );
-    const parent = state.agentState.activeTurn ?? state.agentState.root;
+    const parent = state.agentState.activeTurn ?? state.agentState.activeAttempt ?? state.agentState.root;
     const generation = await startChildObservation({
       parent,
       runtime: getRuntime,
@@ -240,6 +271,12 @@ export async function createFallbackGenerationFromTurn(event: Record<string, unk
 
     generation.end();
     state.agentState.generationOrder.push("turn-end-fallback");
+    if (cacheMetrics) {
+      state.agentState.cacheReadTokens = (state.agentState.cacheReadTokens ?? 0) + cacheMetrics.cacheReadTokens;
+      state.agentState.cacheWriteTokens = (state.agentState.cacheWriteTokens ?? 0) + cacheMetrics.cacheWriteTokens;
+      state.agentState.uncachedInputTokens =
+        (state.agentState.uncachedInputTokens ?? 0) + cacheMetrics.uncachedInputTokens;
+    }
   } catch (e) {
     console.warn("📊 Langfuse: Failed to create fallback generation", e);
   }

package/src/handlers/session.ts

@@ -0,0 +1,90 @@
+import { applyCapturePolicy } from "../capture-policy.js";
+import { getRuntime } from "../langfuse.js";
+import { startChildObservation } from "../observation.js";
+import { state } from "../state.js";
+import {
+  extractCostDetails,
+  extractUsage,
+  getCapturePolicy,
+  shapePayload,
+} from "../utils.js";
+
+type RecordLike = Record<string, unknown>;
+
+function namesFromTools(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((tool) => {
+    if (typeof tool === "string") return [tool];
+    if (!tool || typeof tool !== "object") return [];
+    const name = (tool as RecordLike).name;
+    return typeof name === "string" ? [name] : [];
+  });
+}
+
+export async function recordSessionCompaction(event: RecordLike): Promise<void> {
+  const agent = state.agentState;
+  if (state.isTracingDisabled || !agent?.root) return;
+
+  const entry = event.compactionEntry && typeof event.compactionEntry === "object"
+    ? event.compactionEntry as RecordLike
+    : {};
+  const checkpoint = entry.systemMessage && typeof entry.systemMessage === "object"
+    ? entry.systemMessage as RecordLike
+    : undefined;
+  const checkpointTools = namesFromTools(checkpoint?.toolsAdded);
+  const checkpointSections = checkpoint?.sections && typeof checkpoint.sections === "object"
+    ? Object.keys(checkpoint.sections as RecordLike)
+    : [];
+  const captured = applyCapturePolicy(
+    {
+      input: shapePayload({ summary: entry.summary }),
+      metadata: {
+        reason: event.reason,
+        willRetry: event.willRetry,
+        fromExtension: event.fromExtension,
+        compactionEntryId: entry.id,
+        firstKeptEntryId: entry.firstKeptEntryId,
+        tokensBefore: entry.tokensBefore,
+        checkpointSectionNames: checkpointSections,
+        checkpointToolNames: checkpointTools,
+        checkpointToolCount: checkpointTools.length,
+        promptStateHash: agent.promptStateHash,
+        toolStateHash: agent.toolStateHash,
+      },
+    },
+    getCapturePolicy(),
+  );
+
+  try {
+    const parent = agent.activeTurn ?? agent.activeAttempt ?? agent.root;
+    const compaction = await startChildObservation({
+      parent,
+      runtime: getRuntime,
+      name: "session-compaction",
+      body: { input: captured.input, metadata: captured.metadata },
+      asType: "span",
+    });
+
+    if (entry.usage && typeof entry.usage === "object") {
+      const summary = applyCapturePolicy({ output: entry.summary }, getCapturePolicy());
+      const costDetails = extractCostDetails({ usage: entry.usage });
+      const generation = await startChildObservation({
+        parent: compaction,
+        runtime: getRuntime,
+        name: "compaction-summary",
+        body: {
+          output: summary.output,
+          model: state.currentModel || undefined,
+          usageDetails: extractUsage({ usage: entry.usage }),
+          ...(costDetails ? { costDetails } : {}),
+          metadata: { provider: state.currentProvider || undefined },
+        },
+        asType: "generation",
+      });
+      generation.end();
+    }
+    compaction.end();
+  } catch (error) {
+    console.warn("📊 Langfuse: Failed to record session compaction", error);
+  }
+}

package/src/handlers/system-state.ts

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+
+import { applyCapturePolicy } from "../capture-policy.js";
+import { getRuntime } from "../langfuse.js";
+import { startChildObservation } from "../observation.js";
+import { getSessionRunState, state } from "../state.js";
+import { getCapturePolicy, shapePayload } from "../utils.js";
+
+type RecordLike = Record<string, unknown>;
+
+function fingerprint(value: string): string {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function toolName(tool: unknown): string | undefined {
+  if (typeof tool === "string") return tool;
+  if (!tool || typeof tool !== "object") return undefined;
+  const name = (tool as RecordLike).name;
+  return typeof name === "string" && name ? name : undefined;
+}
+
+function sortedUnique(values: Iterable<string>): string[] {
+  return [...new Set(values)].sort();
+}
+
+function readNewSystemMessages(ctx: any): Array<{ entryId: string; message: RecordLike }> {
+  const session = getSessionRunState();
+  let branch: unknown;
+  try {
+    branch = ctx?.sessionManager?.getBranch?.();
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(branch)) return [];
+
+  const messages: Array<{ entryId: string; message: RecordLike }> = [];
+  for (const rawEntry of branch) {
+    if (!rawEntry || typeof rawEntry !== "object") continue;
+    const entry = rawEntry as RecordLike;
+    const message = entry.message;
+    if (entry.type !== "message" || !message || typeof message !== "object") continue;
+    if ((message as RecordLike).role !== "system") continue;
+    const entryId = typeof entry.id === "string" ? entry.id : "";
+    if (!entryId || session.seenSystemEntryIds.has(entryId)) continue;
+    session.seenSystemEntryIds.add(entryId);
+    messages.push({ entryId, message: message as RecordLike });
+  }
+  return messages;
+}
+
+/** Mark restored transcript state as already seen so the first trace emits one snapshot, not the full history. */
+export function initializeSystemStateTracking(ctx: any): void {
+  const session = getSessionRunState();
+  try {
+    const branch = ctx?.sessionManager?.getBranch?.();
+    if (!Array.isArray(branch)) return;
+    for (const rawEntry of branch) {
+      if (!rawEntry || typeof rawEntry !== "object") continue;
+      const entry = rawEntry as RecordLike;
+      const message = entry.message;
+      if (
+        entry.type === "message" &&
+        typeof entry.id === "string" &&
+        message &&
+        typeof message === "object" &&
+        (message as RecordLike).role === "system"
+      ) {
+        session.seenSystemEntryIds.add(entry.id);
+      }
+    }
+  } catch {
+    // Session history is optional in SDK/headless hosts.
+  }
+}
+
+export async function recordSystemState(ctx: any, activeTools: string[]): Promise<void> {
+  const agent = state.agentState;
+  if (state.isTracingDisabled || !agent?.root) return;
+
+  let prompt = "";
+  try {
+    prompt = String((await ctx?.getSystemPrompt?.()) ?? "");
+  } catch {
+    // The tool state is still useful when a host cannot expose the rendered prompt.
+  }
+
+  const tools = sortedUnique(activeTools);
+  const promptStateHash = prompt ? fingerprint(prompt) : undefined;
+  const toolStateHash = fingerprint(JSON.stringify(tools));
+  const session = getSessionRunState();
+  const systemMessages = readNewSystemMessages(ctx);
+
+  const transcriptToolsAdded: string[] = [];
+  const transcriptToolsRemoved: string[] = [];
+  const sectionsChanged = new Set<string>();
+  const sectionsRemoved = new Set<string>();
+  const entryIds: string[] = [];
+  for (const { entryId, message } of systemMessages) {
+    entryIds.push(entryId);
+    const sections = message.sections;
+    if (sections && typeof sections === "object" && !Array.isArray(sections)) {
+      for (const [name, value] of Object.entries(sections as RecordLike)) {
+        (value === null ? sectionsRemoved : sectionsChanged).add(name);
+      }
+    }
+    if (Array.isArray(message.toolsAdded)) {
+      for (const tool of message.toolsAdded) {
+        const name = toolName(tool);
+        if (name) transcriptToolsAdded.push(name);
+      }
+    }
+    if (Array.isArray(message.toolsRemoved)) {
+      for (const tool of message.toolsRemoved) {
+        const name = toolName(tool);
+        if (name) transcriptToolsRemoved.push(name);
+      }
+    }
+  }
+
+  const previousTools = new Set(session.lastActiveTools);
+  const currentTools = new Set(tools);
+  const toolsAdded = sortedUnique([
+    ...tools.filter((name) => !previousTools.has(name)),
+    ...transcriptToolsAdded,
+  ]);
+  const toolsRemoved = sortedUnique([
+    ...session.lastActiveTools.filter((name) => !currentTools.has(name)),
+    ...transcriptToolsRemoved,
+  ]);
+  const promptChanged = session.lastPromptStateHash !== promptStateHash;
+  const toolsChanged = session.lastToolStateHash !== toolStateHash;
+  const isInitial = session.lastPromptStateHash === undefined && session.lastToolStateHash === undefined;
+  const changed = isInitial || promptChanged || toolsChanged || systemMessages.length > 0;
+  if (changed) session.systemStateSequence++;
+
+  const capturePolicy = getCapturePolicy();
+  const rawSystemUpdate = systemMessages.length > 0
+    ? systemMessages.map(({ entryId, message }) => ({ entryId, ...message }))
+    : { role: "system", content: prompt };
+  const captured = applyCapturePolicy(
+    {
+      systemPrompt: shapePayload(rawSystemUpdate),
+      metadata: {
+        stateSequence: session.systemStateSequence,
+        changeKind: isInitial ? "initial" : changed ? "updated" : "unchanged",
+        source: systemMessages.length > 0 ? "transcript" : "effective-snapshot",
+        transcriptEntryIds: entryIds,
+        promptStateHash,
+        toolStateHash,
+        promptChars: prompt.length,
+        activeToolCount: tools.length,
+        activeTools: tools,
+        toolsAdded,
+        toolsRemoved,
+        sectionsChanged: sortedUnique(sectionsChanged),
+        sectionsRemoved: sortedUnique(sectionsRemoved),
+      },
+    },
+    capturePolicy,
+  );
+
+  try {
+    const observation = await startChildObservation({
+      parent: agent.activeAttempt ?? agent.root,
+      runtime: getRuntime,
+      name: "system-state",
+      body: {
+        input: captured.systemPrompt,
+        metadata: captured.metadata,
+      },
+      asType: "event",
+    });
+    observation.end();
+  } catch (error) {
+    console.warn("📊 Langfuse: Failed to record system state", error);
+  }
+
+  if (changed) agent.systemStateChangeCount = (agent.systemStateChangeCount ?? 0) + 1;
+  agent.promptStateHash = promptStateHash;
+  agent.toolStateHash = toolStateHash;
+  agent.systemStateSequence = session.systemStateSequence;
+  agent.activeToolCount = tools.length;
+  session.lastPromptStateHash = promptStateHash;
+  session.lastToolStateHash = toolStateHash;
+  session.lastActiveTools = tools;
+}

package/src/handlers/tool.ts

@@ -37,7 +37,7 @@ export async function startToolObservation(event: Record<string, unknown>) {
       getCapturePolicy(),
     );
     const inputBytes = estimatePayloadBytes(captured.toolInput, getLimits().maxToolPayload);
-    const parent = state.agentState.activeTurn ?? state.agentState.root;
+    const parent = state.agentState.activeTurn ?? state.agentState.activeAttempt ?? state.agentState.root;
     const tool = await startChildObservation({
       parent,
       runtime: getRuntime,

package/src/handlers/turn.ts

@@ -25,7 +25,7 @@ export async function startTurnObservation(event: Record<string, unknown>) {
       getCapturePolicy(),
     );
     const observation = await startChildObservation({
-      parent: state.agentState.root,
+      parent: state.agentState.activeAttempt ?? state.agentState.root,
       runtime: getRuntime,
       name: "turn",
       body: {

package/src/observation.ts

@@ -11,7 +11,7 @@ export async function startChildObservation({
   runtime: () => Promise<LangfuseRuntime>;
   name: string;
   body?: ObservationUpdate;
-  asType: "generation" | "tool" | "span";
+  asType: "event" | "generation" | "tool" | "span";
 }): Promise<LangfuseObservation> {
   if (parent.startObservation) {
     return parent.startObservation(name, body, { asType });

package/src/state.ts

@@ -10,6 +10,12 @@ export interface SessionRunState {
   turnCount: number;
   tracingDisabled: boolean;
   setupAttemptedThisSession: boolean;
+  lastPromptStateHash?: string;
+  lastToolStateHash?: string;
+  lastActiveTools: string[];
+  systemStateSequence: number;
+  seenSystemEntryIds: Set<string>;
+  seenUsageEntryIds: Set<string>;
 }
 
 const DEFAULT_SESSION_ID = "__pi_langfuse_default_session__";
@@ -27,6 +33,10 @@ function createSessionRunState(): SessionRunState {
     turnCount: 0,
     tracingDisabled: false,
     setupAttemptedThisSession: false,
+    lastActiveTools: [],
+    systemStateSequence: 0,
+    seenSystemEntryIds: new Set(),
+    seenUsageEntryIds: new Set(),
   };
 }
 
@@ -130,11 +140,16 @@ export const state = {
 
 export function resetRunState(sessionId = getActiveSessionId()) {
   const normalizedSessionId = normalizeSessionId(sessionId);
-  const setupAttemptedThisSession =
-    state.sessionStates.get(normalizedSessionId)?.setupAttemptedThisSession ?? false;
+  const previous = state.sessionStates.get(normalizedSessionId);
   state.sessionStates.set(normalizedSessionId, {
     ...createSessionRunState(),
-    setupAttemptedThisSession,
+    setupAttemptedThisSession: previous?.setupAttemptedThisSession ?? false,
+    lastPromptStateHash: previous?.lastPromptStateHash,
+    lastToolStateHash: previous?.lastToolStateHash,
+    lastActiveTools: previous?.lastActiveTools ?? [],
+    systemStateSequence: previous?.systemStateSequence ?? 0,
+    seenSystemEntryIds: previous?.seenSystemEntryIds ?? new Set(),
+    seenUsageEntryIds: previous?.seenUsageEntryIds ?? new Set(),
   });
 }
 

package/src/types.ts

@@ -19,7 +19,7 @@ export interface LangfuseObservation {
   startObservation?(
     name: string,
     body?: ObservationUpdate,
-    options?: { asType?: "agent" | "generation" | "tool" | "span" },
+    options?: { asType?: "agent" | "event" | "generation" | "tool" | "span" },
   ): LangfuseObservation;
   setTraceIO?(body?: { input?: unknown; output?: unknown }): void;
 }
@@ -82,7 +82,7 @@ export interface LangfuseRuntime {
   startObservation: (
     name: string,
     body?: ObservationUpdate,
-    options?: { asType?: "agent" | "generation" | "tool" | "span" },
+    options?: { asType?: "agent" | "event" | "generation" | "tool" | "span" },
   ) => LangfuseObservation;
   propagateAttributes: (
     params: {
@@ -136,6 +136,7 @@ export interface ToolState {
 
 export interface AgentState {
   root?: LangfuseObservation;
+  activeAttempt?: LangfuseObservation;
   activeTurn?: LangfuseObservation;
   traceId?: string;
   promptInput?: unknown;
@@ -147,4 +148,14 @@ export interface AgentState {
   latestAssistantOutput?: unknown;
   sourceMetadata?: Record<string, unknown>;
   providerMetadataByRequest: Map<string, Record<string, unknown>>;
+  attemptCount: number;
+  lastAgentEndEvent?: Record<string, unknown>;
+  promptStateHash?: string;
+  toolStateHash?: string;
+  systemStateSequence?: number;
+  activeToolCount?: number;
+  systemStateChangeCount: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  uncachedInputTokens: number;
 }

package/src/utils.ts

@@ -334,6 +334,55 @@ export function getProviderPayload(event: Record<string, unknown>): unknown {
   return event.request ?? event.payload ?? event.body ?? event.providerPayload ?? event.messages ?? event;
 }
 
+export type ToolUpdateTransport =
+  | "anthropic-native"
+  | "openai-additional-tools"
+  | "openai-tool-search"
+  | "mid-conversation-system"
+  | "collapsed-leading-system";
+
+/** Classify the provider payload observed by this hook rather than guessing from the model name alone. */
+export function inferToolUpdateTransport(payload: unknown, hasPriorSystemState: boolean): ToolUpdateTransport | undefined {
+  let sawToolChangeBlock = false;
+  let sawAdditionalTools = false;
+  let sawToolSearch = false;
+  let sawTopLevelTools = false;
+  let sawMidConversationSystem = false;
+  let visited = 0;
+
+  const walk = (value: unknown, key?: string) => {
+    if (++visited > 2_000 || value === null || value === undefined) return;
+    if (key === "additional_tools") sawAdditionalTools = true;
+    if (key === "tools") sawTopLevelTools = true;
+    if (key === "tool_search" || key === "tool_search_output") sawToolSearch = true;
+    if (typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      let sawNonSystem = false;
+      for (const item of value) {
+        if (item && typeof item === "object" && !Array.isArray(item)) {
+          const role = (item as Record<string, unknown>).role;
+          if (role === "system" && sawNonSystem) sawMidConversationSystem = true;
+          if (role && role !== "system") sawNonSystem = true;
+        }
+        walk(item);
+      }
+      return;
+    }
+    const record = value as Record<string, unknown>;
+    const type = record.type;
+    if (type === "tool_addition" || type === "tool_removal") sawToolChangeBlock = true;
+    for (const [childKey, child] of Object.entries(record)) walk(child, childKey);
+  };
+
+  walk(payload);
+  if (sawToolChangeBlock) return "anthropic-native";
+  if (sawAdditionalTools) return "openai-additional-tools";
+  if (sawToolSearch) return "openai-tool-search";
+  if (sawMidConversationSystem) return "mid-conversation-system";
+  if (hasPriorSystemState && sawTopLevelTools) return "collapsed-leading-system";
+  return undefined;
+}
+
 export function extractModelParameters(payload: unknown): Record<string, string | number> | undefined {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
     return undefined;
@@ -487,6 +536,32 @@ export function extractUsage(
   };
 }
 
+export function extractCacheMetrics(messageOrEvent: Record<string, unknown>): {
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  uncachedInputTokens: number;
+  cacheHitRatio?: number;
+} | undefined {
+  const usage = (messageOrEvent.usage ??
+    (messageOrEvent.message && typeof messageOrEvent.message === "object"
+      ? (messageOrEvent.message as Record<string, unknown>).usage
+      : undefined)) as Record<string, unknown> | undefined;
+  if (!usage || typeof usage !== "object") return undefined;
+
+  const uncachedInputTokens = Number(
+    usage.input ?? usage.inputTokens ?? usage.prompt_tokens ?? usage.promptTokens ?? 0,
+  );
+  const cacheReadTokens = Number(usage.cacheRead ?? usage.cache_read ?? usage.cachedTokens ?? 0);
+  const cacheWriteTokens = Number(usage.cacheWrite ?? usage.cache_write ?? 0);
+  const denominator = uncachedInputTokens + cacheReadTokens;
+  return {
+    cacheReadTokens,
+    cacheWriteTokens,
+    uncachedInputTokens,
+    ...(denominator > 0 ? { cacheHitRatio: cacheReadTokens / denominator } : {}),
+  };
+}
+
 export function extractCostDetails(messageOrEvent: Record<string, unknown>): Record<string, number> | undefined {
   const usage = (messageOrEvent.usage ??
     (messageOrEvent.message && typeof messageOrEvent.message === "object"

package/types/langfuse-runtime-shims.d.ts

@@ -1,49 +0,0 @@
-declare module "@opentelemetry/sdk-trace-base" {
-  export class BasicTracerProvider {
-    constructor(options?: { resource?: unknown; spanProcessors?: unknown[] });
-    forceFlush?(): Promise<void>;
-    shutdown?(): Promise<void>;
-  }
-}
-
-declare module "@langfuse/otel" {
-  export class LangfuseSpanProcessor {
-    constructor(options: {
-      publicKey: string;
-      secretKey: string;
-      baseUrl: string;
-    });
-    forceFlush?(): Promise<void>;
-    shutdown?(): Promise<void>;
-  }
-}
-
-declare module "@langfuse/tracing" {
-  export function setLangfuseTracerProvider(provider: unknown): void;
-
-  export function startObservation(
-    name: string,
-    body?: Record<string, unknown>,
-    options?: { asType?: string },
-  ): unknown;
-
-  export function propagateAttributes<T>(
-    params: {
-      sessionId?: string;
-      traceName?: string;
-      metadata?: Record<string, string>;
-      tags?: string[];
-    },
-    fn: () => T,
-  ): T;
-}
-
-declare module "@langfuse/client" {
-  export class LangfuseClient {
-    constructor(options: {
-      publicKey: string;
-      secretKey: string;
-      baseUrl: string;
-    });
-  }
-}

package/types/node-shims.d.ts

@@ -1,29 +0,0 @@
-declare module "node:fs" {
-  export function mkdirSync(path: string, options?: { recursive?: boolean }): void;
-  export function readFileSync(path: string, encoding: string): string;
-  export function existsSync(path: string): boolean;
-  export function writeFileSync(path: string, data: string, encoding: string): void;
-}
-
-declare module "node:crypto" {
-  export function randomUUID(): string;
-}
-
-declare module "node:os" {
-  export function homedir(): string;
-}
-
-declare module "node:path" {
-  export function resolve(...paths: string[]): string;
-  export function dirname(path: string): string;
-  export function basename(path: string, suffix?: string): string;
-}
-
-declare module "node:url" {
-  export function fileURLToPath(url: string | URL): string;
-}
-
-declare const process: {
-  cwd(): string;
-  env: Record<string, string | undefined>;
-};

package/types/pi-coding-agent.d.ts

@@ -1,16 +0,0 @@
-declare module "@earendil-works/pi-coding-agent" {
-  export interface ExtensionContext {
-    sessionManager?: {
-      getSessionId?: () => unknown;
-      getSessionFile?: () => unknown;
-    };
-  }
-
-  export interface ExtensionAPI {
-    on(event: string, handler: (event: any, ctx: any) => unknown): void;
-    registerCommand(
-      name: string,
-      options: { description?: string; handler: (args: string, ctx: any) => unknown },
-    ): void;
-  }
-}