pi-langfuse 1.6.0 → 1.7.0

package/README.md

@@ -34,6 +34,7 @@ Langfuse observability extension for [Pi Coding Agent](https://github.com/earend
    - Langfuse public key, starting with `pk-lf-...`
    - Langfuse secret key, starting with `sk-lf-...`
    - Langfuse host, defaulting to `https://cloud.langfuse.com`
+   - Optional Langfuse user ID for per-user usage and cost aggregation
 
 3. Run Pi normally:
 
@@ -63,7 +64,7 @@ To inspect the active configuration without exposing secrets:
 /langfuse-status
 ```
 
-The status command reports the config source, host, masked public key, capture policy, active-run state, config path, and last runtime error.
+The status command reports the config source, host, masked public key, whether a user ID is configured, capture policy, active-run state, config path, and last runtime error. It never prints the user ID itself.
 
 ### Method 2: Environment variables
 
@@ -73,9 +74,11 @@ Set these before starting Pi:
 export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx"
 export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
 export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # optional; LANGFUSE_HOST is also supported
+export LANGFUSE_USER_ID="user-123"                     # optional; max 200 characters
 ```
 
 Saved config takes precedence. Environment variables are only used when `~/.pi/agent/pi-langfuse/config.json` is missing or incomplete.
+If saved credentials exist but `userId` is absent, `LANGFUSE_USER_ID` is still used. An explicitly saved `userId` takes precedence.
 
 For short-lived SDK hosts, set the bounded final score-delivery attempt during shutdown:
 
@@ -222,10 +225,13 @@ Create or update `~/.pi/agent/pi-langfuse/config.json`:
   "publicKey": "pk-lf-xxxx",
   "secretKey": "sk-lf-xxxx",
   "host": "https://cloud.langfuse.com",
+  "userId": "user-123",
   "privacyPreset": "conversations"
 }
 ```
 
+`userId` is optional, explicit-only, and limited to 200 characters. The extension does not infer it from the local operating-system account. When configured, it is propagated to every observation in the trace so Langfuse can provide per-user filtering and cost aggregation.
+
 Fine-grained capture flags can also be persisted:
 
 ```json
@@ -267,10 +273,18 @@ This command makes a timeout-bounded authenticated request to Langfuse and, if i
 - Each user prompt within that session becomes a separate trace.
 - The trace contains the final assistant output shown in Pi.
 - Tool runs appear as tool observations with arguments, results, and error state.
+  Pi 1.0 nested calls (including codemode tools) are parented by `parentToolCallId`.
+  A tool's own model usage/cost appears in a child `tool-usage` generation; transcript totals that
+  include descendants are not ingested again. Pi's tool usage does not identify each nested model,
+  so these aggregate generations have no inferred model name or price.
 - 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.
+  Virtual routing preserves `selectedModel`/`selectedProvider` alongside `actualModel`/`actualProvider`;
+  the generation model and `provider` metadata use the actual identity when available.
 - 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.
+  State is refreshed before every provider request, including after lazy tool loading, and unchanged
+  state is deduplicated within an attempt.
 - 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.

package/README_CN.md

@@ -34,6 +34,7 @@
    - Langfuse 公钥，以 `pk-lf-...` 开头
    - Langfuse 密钥，以 `sk-lf-...` 开头
    - Langfuse 主机地址，默认 `https://cloud.langfuse.com`
+   - 可选的 Langfuse 用户 ID，用于按用户汇总用量和成本
 
 3. 正常运行 Pi：
 
@@ -63,7 +64,7 @@ Langfuse API 密钥可在 **Langfuse Cloud** -> **Settings** -> **API Keys** 中
 /langfuse-status
 ```
 
-状态命令会显示配置来源、主机地址、脱敏后的公钥、采集策略、是否有活跃运行、配置文件路径，以及最近一次运行时错误。
+状态命令会显示配置来源、主机地址、脱敏后的公钥、是否已配置用户 ID、采集策略、是否有活跃运行、配置文件路径，以及最近一次运行时错误，但不会输出用户 ID 本身。
 
 ### 方式 2：环境变量
 
@@ -73,9 +74,11 @@ Langfuse API 密钥可在 **Langfuse Cloud** -> **Settings** -> **API Keys** 中
 export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx"
 export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
 export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # 可选；也支持 LANGFUSE_HOST
+export LANGFUSE_USER_ID="user-123"                     # 可选；最长 200 个字符
 ```
 
 保存的配置优先级更高。只有当 `~/.pi/agent/pi-langfuse/config.json` 缺失或不完整时，扩展才会使用环境变量。
+如果已保存凭据但没有 `userId`，仍会读取 `LANGFUSE_USER_ID`；显式保存的 `userId` 优先级更高。
 
 对于短生命周期的 SDK 宿主，可设置关闭时最终分数发送尝试的上限：
 
@@ -203,10 +206,13 @@ export PI_LANGFUSE_SPLIT_REASONING_TOKENS=true
   "publicKey": "pk-lf-xxxx",
   "secretKey": "sk-lf-xxxx",
   "host": "https://cloud.langfuse.com",
+  "userId": "user-123",
   "privacyPreset": "conversations"
 }
 ```
 
+`userId` 是可选的显式配置，最长 200 个字符。扩展不会从本机操作系统账户推断该值。配置后，它会传播到 trace 中的每个 observation，以支持 Langfuse 按用户筛选并汇总成本。
+
 也可以持久化细粒度采集开关：
 
 ```json
@@ -248,10 +254,16 @@ pi list
 - 该会话中的每个用户提示词都会生成一个独立 trace。
 - trace 中会包含 Pi 实际显示的最终助手回复。
 - 工具执行会以工具观察节点展示参数、结果和错误状态。
+  Pi 1.0 的嵌套调用（含 codemode 内部工具）按 `parentToolCallId` 建立父子关系。
+  工具自身的模型用量和费用记录在子级 `tool-usage` generation 中，不会重复上报 transcript 中包含
+  后代工具的合计用量。Pi 的工具 usage 未标识每个内部模型，因此这些聚合节点不推断模型名称或价格。
 - 模型请求会以生成观察节点展示；如果提供商暴露相关信息，还会包含用量和成本。
   开启 `PI_LANGFUSE_SPLIT_REASONING_TOKENS` 后，推理 token 会作为独立用量桶上报。
+  虚拟模型路由分别记录 `selectedModel`/`selectedProvider` 和 `actualModel`/`actualProvider`；
+  获得实际模型身份后，generation 的 model 和 `provider` 元数据使用实际值。
 - Pi 0.86 的 transcript-aware system/tool 状态会作为 `system-state` 事件上报；generation 会引用有效的
   prompt/tool 状态指纹、活动工具数、更新传输方式和缓存命中率。
+  每次 provider 请求前都会刷新状态，覆盖工具延迟加载；同一 attempt 内的未变化状态不会重复生成事件。
 - 自动重试会归入 `agent-attempt` span，trace 会持续到 `agent_settled` 才结束。
 - cache warming 决策及持久化的 `cache_warm` 用量会被记录；若 warming 发生时没有活动的用户请求 trace，
   会创建按相同 session 分组的独立 trace。

package/index.ts

@@ -37,6 +37,7 @@ import {
   finishGenerationFromMessage,
   createFallbackGenerationFromTurn,
   recordTTFT,
+  recordGenerationIdentity,
 } from "./src/handlers/generation.js";
 import {
   startToolObservation,
@@ -145,13 +146,18 @@ export default async function (pi: ExtensionAPI) {
   }));
 
   pi.on("before_provider_request", async (event, ctx) => withSession(ctx, async () => {
-    await startGeneration(asRecord(event));
+    await recordSystemState(ctx, pi.getActiveTools(), false);
+    await startGeneration(asRecord(event), ctx.model);
   }));
 
   pi.on("after_provider_response", async (event, ctx) => withSession(ctx, async () => {
     updateGenerationMetadata(asRecord(event));
   }));
 
+  pi.on("provider_stream_event", (event, ctx) => withSession(ctx, () => {
+    recordGenerationIdentity(asRecord(event));
+  }));
+
   pi.on("message_update", async (event, ctx) => withSession(ctx, async () => {
     recordTTFT(asRecord(event));
     const message = getMessageFromEvent(asRecord(event));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-langfuse",
-	"version": "1.6.0",
+	"version": "1.7.0",
 	"description": "Langfuse extension for Pi coding agent",
 	"repository": {
 		"type": "git",
@@ -62,7 +62,7 @@
 		"node": ">=22"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "^0.86.0",
+		"@earendil-works/pi-coding-agent": "^1.0.0",
 		"tsx": "^4.19.0",
 		"typescript": "^6.0.3"
 	}

package/src/commands.ts

@@ -211,6 +211,7 @@ function formatStatus(configPath: string, env: Record<string, string | undefined
     `Source: ${configSource(env, configPath)}`,
     `Host: ${safeConfig?.host ?? config.host}`,
     `Public key: ${safeConfig?.publicKey ?? "[REDACTED_SECRET]"}`,
+    `User ID: ${config.userId ? "configured" : "not set"}`,
     `Config file: ${configPath}`,
     `Privacy preset: ${inferPreset(policy)}`,
     "Capture:",

package/src/config.ts

@@ -8,6 +8,16 @@ import { createCapturePolicy, type EnvLike } from "./capture-policy.js";
 import { createPayloadLimits } from "./limits.js";
 import { createUsageOptions } from "./usage-options.js";
 
+const MAX_LANGFUSE_USER_ID_LENGTH = 200;
+
+function normalizeUserId(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed.slice(0, MAX_LANGFUSE_USER_ID_LENGTH) : undefined;
+}
+
 export function loadConfigFromFile(path = CONFIG_PATH, env: EnvLike = process.env as EnvLike): Config | null {
   if (existsSync(path)) {
     try {
@@ -23,6 +33,7 @@ export function loadConfigFromFile(path = CONFIG_PATH, env: EnvLike = process.en
           publicKey: config.publicKey,
           secretKey: config.secretKey,
           host: config.host || DEFAULT_LANGFUSE_HOST,
+          userId: normalizeUserId(config.userId) ?? normalizeUserId(env.LANGFUSE_USER_ID),
           capturePolicy: createCapturePolicy(captureSource),
           limits: createPayloadLimits(env),
           usage: createUsageOptions(captureSource),
@@ -47,6 +58,7 @@ export function loadConfigFromEnv(env: EnvLike = process.env as EnvLike): Config
     publicKey,
     secretKey,
     host: env.LANGFUSE_BASE_URL || env.LANGFUSE_HOST || DEFAULT_LANGFUSE_HOST,
+    userId: normalizeUserId(env.LANGFUSE_USER_ID),
     capturePolicy: createCapturePolicy(env),
     limits: createPayloadLimits(env),
     usage: createUsageOptions(env),
@@ -108,10 +120,12 @@ async function collectConfigFromUI(ctx: any, reason: string): Promise<Config | n
   }
 
   const hostInput = (await ctx.ui.input("Langfuse host:", DEFAULT_LANGFUSE_HOST))?.trim();
+  const userId = normalizeUserId(await ctx.ui.input("Langfuse user ID (optional):", ""));
   return {
     publicKey,
     secretKey,
     host: hostInput || DEFAULT_LANGFUSE_HOST,
+    ...(userId ? { userId } : {}),
     capturePolicy: createCapturePolicy(),
   };
 }

package/src/handlers/agent.ts

@@ -96,6 +96,7 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
     const root = rt.propagateAttributes(
       {
         sessionId: state.currentSessionId ? truncate(state.currentSessionId, 200) : undefined,
+        userId: state.config?.userId,
         traceName: "pi-agent",
         metadata: stringMetadata(captured.metadata),
       },

package/src/handlers/generation.ts

@@ -14,6 +14,7 @@ import {
   extractModelParameters,
   extractCacheMetrics,
   inferToolUpdateTransport,
+  extractModelIdentity,
 } from "../utils.js";
 import type { GenerationState, ObservationUpdate } from "../types.js";
 import { applyCapturePolicy } from "../capture-policy.js";
@@ -34,7 +35,7 @@ export function getOpenGeneration(): GenerationState | undefined {
   return undefined;
 }
 
-export async function startGeneration(event: Record<string, unknown>) {
+export async function startGeneration(event: Record<string, unknown>, selectedModel?: unknown) {
   if (state.isTracingDisabled || !state.agentState?.root) {
     return;
   }
@@ -43,11 +44,16 @@ export async function startGeneration(event: Record<string, unknown>) {
     const key = getRequestKey(event, `generation-${++state.agentState.generationSeq}`);
     const payload = getProviderPayload(event);
     const modelParameters = extractModelParameters(payload);
-    const model = String(event.model ?? event.modelId ?? state.currentModel ?? "");
-    const provider = String(event.provider ?? state.currentProvider ?? "");
+    const selected = extractModelIdentity(selectedModel ?? state.currentModel, selectedModel ? undefined : state.currentProvider);
+    const payloadModel = payload && typeof payload === "object" ? (payload as Record<string, unknown>).model : undefined;
+    const actual = extractModelIdentity(event.model ?? event.modelId ?? payloadModel, event.provider);
     const toolUpdateTransport = inferToolUpdateTransport(payload, (state.agentState.systemStateSequence ?? 0) > 1);
     const metadata = shapePayload({
-      provider,
+      provider: actual.provider ?? selected.provider,
+      selectedModel: selected.model,
+      selectedProvider: selected.provider,
+      actualModel: actual.model,
+      actualProvider: actual.provider,
       requestId: key,
       url: event.url,
       method: event.method,
@@ -81,7 +87,7 @@ export async function startGeneration(event: Record<string, unknown>) {
       name: "llm-generation",
       body: {
         input: captured.input,
-        model: model || undefined,
+        model: actual.model ?? selected.model,
         modelParameters,
         metadata: captured.metadata,
       },
@@ -172,6 +178,21 @@ export function recordTTFT(event: Record<string, unknown>) {
   }
 }
 
+/** Routing identity is available before the assistant message, including failed streams. */
+export function recordGenerationIdentity(event: Record<string, unknown>) {
+  const generation = getOpenGeneration();
+  if (!generation) return;
+  const actual = extractModelIdentity(event.model, event.provider);
+  if (!actual.model && !actual.provider) return;
+  if (generation.metadata.actualModel === actual.model && generation.metadata.actualProvider === actual.provider) return;
+  generation.metadata = applyCapturePolicy({ metadata: shapePayload({
+    ...generation.metadata,
+    ...(actual.model ? { actualModel: actual.model } : {}),
+    ...(actual.provider ? { provider: actual.provider, actualProvider: actual.provider } : {}),
+  }) as Record<string, unknown> }, getCapturePolicy()).metadata ?? {};
+  generation.observation.update({ model: actual.model, metadata: generation.metadata });
+}
+
 export async function finishGenerationFromMessage(event: Record<string, unknown>) {
   if (state.isTracingDisabled || !state.agentState) {
     return;
@@ -196,15 +217,17 @@ export async function finishGenerationFromMessage(event: Record<string, unknown>
   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 actual = extractModelIdentity(message.model ?? event.model, message.provider ?? event.provider);
   const update: ObservationUpdate = {
     output,
-    model: model || undefined,
+    model: actual.model ?? (generation.metadata.actualModel as string | undefined) ?? (state.currentModel || undefined),
     modelParameters,
     usageDetails,
     ...(costDetails ? { costDetails } : {}),
     metadata: {
       ...generation.metadata,
+      ...(actual.model ? { actualModel: actual.model } : {}),
+      ...(actual.provider ? { provider: actual.provider, actualProvider: actual.provider } : {}),
       finishReason: message.finishReason ?? message.stopReason ?? event.finishReason,
       ...cacheMetrics,
     },
@@ -235,13 +258,17 @@ export async function createFallbackGenerationFromTurn(event: Record<string, unk
     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 actual = extractModelIdentity(message.model ?? event.model, message.provider ?? event.provider);
     const captured = applyCapturePolicy(
       {
         input: state.agentState.promptInput,
         output: extractAssistantOutput(message),
         metadata: {
-          provider: state.currentProvider || undefined,
+          provider: actual.provider ?? (state.currentProvider || undefined),
+          selectedModel: state.currentModel || undefined,
+          selectedProvider: state.currentProvider || undefined,
+          actualModel: actual.model,
+          actualProvider: actual.provider,
           sourceEvent: "turn_end",
           promptStateHash: state.agentState.promptStateHash,
           toolStateHash: state.agentState.toolStateHash,
@@ -260,7 +287,7 @@ export async function createFallbackGenerationFromTurn(event: Record<string, unk
       body: {
         input: captured.input,
         output: captured.output,
-        model: model || undefined,
+        model: actual.model ?? (state.currentModel || undefined),
         modelParameters,
         usageDetails,
         ...(costDetails ? { costDetails } : {}),

package/src/handlers/system-state.ts

@@ -73,7 +73,7 @@ export function initializeSystemStateTracking(ctx: any): void {
   }
 }
 
-export async function recordSystemState(ctx: any, activeTools: string[]): Promise<void> {
+export async function recordSystemState(ctx: any, activeTools: string[], emitUnchanged = true): Promise<void> {
   const agent = state.agentState;
   if (state.isTracingDisabled || !agent?.root) return;
 
@@ -133,6 +133,9 @@ export async function recordSystemState(ctx: any, activeTools: string[]): Promis
   const changed = isInitial || promptChanged || toolsChanged || systemMessages.length > 0;
   if (changed) session.systemStateSequence++;
 
+  // agent_start emits a snapshot; unchanged request hooks keep the existing reference.
+  if (!changed && !emitUnchanged && agent.systemStateSequence !== undefined) return;
+
   const capturePolicy = getCapturePolicy();
   const rawSystemUpdate = systemMessages.length > 0
     ? systemMessages.map(({ entryId, message }) => ({ entryId, ...message }))

package/src/handlers/tool.ts

@@ -11,6 +11,7 @@ import {
   estimatePayloadBytes,
   getCapturePolicy,
   getLimits,
+  extractToolUsage,
 } from "../utils.js";
 import { applyCapturePolicy, redactOptionsFor } from "../capture-policy.js";
 import { redactString } from "../redaction.js";
@@ -27,17 +28,19 @@ export async function startToolObservation(event: Record<string, unknown>) {
 
   try {
     const toolName = getToolName(event);
+    const parentToolCallId = typeof event.parentToolCallId === "string" ? event.parentToolCallId : undefined;
     const toolInput = getToolInput(event);
     const shapedInput = shapePayload(toolInput, { maxString: getLimits().maxToolPayload });
     const captured = applyCapturePolicy(
       {
         toolInput: shapedInput,
-        metadata: { toolName, toolCallId },
+        metadata: shapePayload({ toolName, toolCallId, parentToolCallId }) as Record<string, unknown>,
       },
       getCapturePolicy(),
     );
     const inputBytes = estimatePayloadBytes(captured.toolInput, getLimits().maxToolPayload);
-    const parent = state.agentState.activeTurn ?? state.agentState.activeAttempt ?? state.agentState.root;
+    const parentTool = parentToolCallId ? state.agentState.activeTools.get(parentToolCallId) : undefined;
+    const parent = parentTool?.observation ?? state.agentState.activeTurn ?? state.agentState.activeAttempt ?? state.agentState.root;
     const tool = await startChildObservation({
       parent,
       runtime: getRuntime,
@@ -56,6 +59,7 @@ export async function startToolObservation(event: Record<string, unknown>) {
       ended: false,
       startedAt: Date.now(),
       inputBytes,
+      parentToolCallId,
     });
   } catch (e) {
     console.warn("📊 Langfuse: Failed to start tool observation", e);
@@ -76,6 +80,8 @@ export async function finishToolObservation(event: Record<string, unknown>) {
   if (!activeTool || activeTool.ended) {
     return;
   }
+  // Claim completion before creating the usage child (which awaits the runtime).
+  activeTool.ended = true;
 
   const isError = Boolean(event.isError ?? event.error ?? event.status === "error");
   const output =
@@ -92,17 +98,47 @@ export async function finishToolObservation(event: Record<string, unknown>) {
     const captured = applyCapturePolicy(
       {
         toolOutput: shapedOutput,
-        metadata: {
+        metadata: shapePayload({
           toolName: activeTool.toolName,
           toolCallId,
+          parentToolCallId: activeTool.parentToolCallId,
           isError,
-        },
+        }) as Record<string, unknown>,
       },
       policy,
     );
     const outputBytes = estimatePayloadBytes(captured.toolOutput, getLimits().maxToolPayload);
     const durationMs = Math.max(0, Date.now() - activeTool.startedAt);
 
+    // Pi's tool_result and tool_execution_end carry only this tool's own usage.
+    // Do not consume transcript toolResult usage, which includes all descendants.
+    // A separate generation makes this cost visible on Langfuse versions that
+    // only account for usage/cost on generation observations.
+    const { usageDetails, costDetails } = extractToolUsage(event);
+    if (usageDetails || costDetails) {
+      try {
+        const usage = await startChildObservation({
+          parent: activeTool.observation,
+          runtime: getRuntime,
+          name: "tool-usage",
+          body: {
+            usageDetails,
+            costDetails,
+            metadata: applyCapturePolicy({ metadata: shapePayload({
+              toolName: activeTool.toolName,
+              toolCallId,
+              parentToolCallId: activeTool.parentToolCallId,
+              usageSource: "tool-result",
+            }) as Record<string, unknown> }, policy).metadata,
+          },
+          asType: "generation",
+        });
+        usage.end();
+      } catch (error) {
+        console.warn("📊 Langfuse: Failed to record tool usage", error);
+      }
+    }
+
     activeTool.observation
       .update({
         output: captured.toolOutput,
@@ -118,8 +154,6 @@ export async function finishToolObservation(event: Record<string, unknown>) {
         },
       })
       .end();
-    activeTool.ended = true;
-
     if (isError) {
       state.errorCount++;
       await sendScore("tool_is_error", 1, {

package/src/langfuse.ts

@@ -29,6 +29,7 @@ interface RestFallbackTrace {
   input?: unknown;
   output?: unknown;
   sessionId?: string;
+  userId?: string;
   metadata?: Record<string, unknown>;
 }
 
@@ -558,12 +559,15 @@ function wrapObservation(
   store.observationById.set(id, record);
 
   if (!parentObservationId && !store.trace) {
+    const propagated = readPropagatedAttributes(observation);
     store.trace = {
       id: traceId,
       timestamp: record.startTime,
       name,
       input: body?.input,
-      sessionId: typeof metadata?.sessionId === "string" ? metadata.sessionId : state.currentSessionId || undefined,
+      sessionId: propagated.sessionId
+        ?? (typeof metadata?.sessionId === "string" ? metadata.sessionId : state.currentSessionId || undefined),
+      userId: propagated.userId ?? state.config?.userId,
       metadata,
     };
   }
@@ -743,6 +747,7 @@ async function fallbackToRestIngestion(rt: LangfuseRuntime, signal: AbortSignal)
         input: trace.input,
         output: trace.output,
         sessionId: trace.sessionId,
+        userId: trace.userId,
         metadata: trace.metadata,
       },
     },

package/src/types.ts

@@ -6,6 +6,7 @@ export interface Config {
   publicKey: string;
   secretKey: string;
   host: string;
+  userId?: string;
   capturePolicy?: CapturePolicy;
   limits?: PayloadLimits;
   usage?: UsageOptions;
@@ -132,6 +133,7 @@ export interface ToolState {
   ended: boolean;
   startedAt: number;
   inputBytes: number;
+  parentToolCallId?: string;
 }
 
 export interface AgentState {

package/src/utils.ts

@@ -593,6 +593,29 @@ export function extractCostDetails(messageOrEvent: Record<string, unknown>): Rec
   };
 }
 
+/** Accept both provider model ids and Pi Model objects without serializing the whole model. */
+export function extractModelIdentity(value: unknown, provider?: unknown): { model?: string; provider?: string } {
+  const record = value && typeof value === "object" ? value as Record<string, unknown> : undefined;
+  const model = record?.id ?? record?.model ?? value;
+  const actualProvider = provider ?? record?.provider;
+  return {
+    ...(typeof model === "string" && model ? { model } : {}),
+    ...(typeof actualProvider === "string" && actualProvider ? { provider: actualProvider } : {}),
+  };
+}
+
+/** Tool hooks report own usage; transcript toolResult messages also include descendants' usage. */
+export function extractToolUsage(event: Record<string, unknown>): {
+  usageDetails?: Record<string, number>;
+  costDetails?: Record<string, number>;
+} {
+  const result = event.result && typeof event.result === "object"
+    ? event.result as Record<string, unknown>
+    : {};
+  const source = { usage: event.usage ?? result.usage, cost: event.cost ?? result.cost };
+  return { usageDetails: extractUsage(source), costDetails: extractCostDetails(source) };
+}
+
 export function extractResponseMetadata(event: Record<string, unknown>): Record<string, unknown> {
   return shapePayload(
     {