@narumitw/pi-langfuse 0.50.6 → 0.51.1

package/dist/tracing.d.ts

@@ -0,0 +1,202 @@
+export { MAX_CAPTURE_BYTES, sanitizeTraceValue } from "./sanitizer.js";
+export declare const TRACE_SCHEMA_VERSION = "2";
+export interface ObservationAttributes {
+    input?: unknown;
+    output?: unknown;
+    metadata?: Record<string, unknown>;
+    level?: "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
+    statusMessage?: string;
+    completionStartTime?: Date;
+    model?: string;
+    modelParameters?: Record<string, string | number>;
+    usageDetails?: Record<string, number>;
+    costDetails?: Record<string, number>;
+    version?: string;
+    name?: string;
+    sessionId?: string;
+    userId?: string;
+    tags?: string[];
+}
+export interface Observation {
+    readonly traceId?: string;
+    update(attributes: ObservationAttributes): Observation;
+    updateTrace?(attributes: ObservationAttributes): Observation;
+    end(endTime?: number): Observation;
+}
+export type ObservationType = "agent" | "generation" | "span" | "tool";
+export interface TraceBackend {
+    start(name: string, attributes: ObservationAttributes, options: {
+        asType: ObservationType;
+        parent?: Observation;
+        startTime?: Date;
+    }): Observation;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export interface TraceRecorderOptions {
+    sessionId: string;
+    userId?: string;
+    cwd: string;
+    mode: string;
+    captureContent: boolean;
+    traceName?: string;
+    tags?: readonly string[];
+    metadata?: Readonly<Record<string, unknown>>;
+    onTraceId?: (traceId: string) => void;
+}
+interface ModelDescriptor {
+    provider?: string;
+    id?: string;
+    api?: string;
+}
+export interface GitMetadata {
+    branch?: string;
+    commit?: string;
+    detached: boolean;
+}
+export interface ContextSnapshot {
+    leafId?: string | null;
+    contextUsage?: {
+        tokens: number | null;
+        contextWindow: number;
+        percent: number | null;
+    };
+}
+interface BeginAgentInput {
+    prompt: unknown;
+    images?: unknown;
+    model?: ModelDescriptor;
+    git?: GitMetadata;
+    snapshot?: ContextSnapshot;
+    requestId?: string;
+}
+interface AttemptInput {
+    reason?: string;
+}
+interface GenerationInput {
+    startedAt?: number;
+    payload?: unknown;
+    payloadStage?: "before_provider_request";
+    model?: ModelDescriptor;
+    thinkingLevel?: string;
+}
+interface AssistantMessage {
+    role: string;
+    content?: unknown;
+    provider?: string;
+    api?: string;
+    model?: string;
+    responseModel?: string;
+    responseId?: string;
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        cacheWrite1h?: number;
+        reasoning?: number;
+        totalTokens?: number;
+        cost?: {
+            input?: number;
+            output?: number;
+            cacheRead?: number;
+            cacheWrite?: number;
+            total?: number;
+        };
+    };
+    stopReason?: string;
+    errorMessage?: string;
+}
+interface ToolResult {
+    content?: unknown;
+    details?: unknown;
+    isError?: boolean;
+}
+interface TurnResult {
+    message: {
+        role: string;
+        stopReason?: string;
+        errorMessage?: string;
+    };
+    toolResultCount: number;
+}
+interface CompactionStart {
+    reason: string;
+    willRetry: boolean;
+    tokensBefore?: number;
+    messagesToSummarize: number;
+    turnPrefixMessages: number;
+    branchEntries: number;
+    isSplitTurn: boolean;
+}
+interface CompactionFinish {
+    reason: string;
+    willRetry: boolean;
+    fromExtension: boolean;
+    tokensBefore?: number;
+    details?: unknown;
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        totalTokens?: number;
+        cost?: {
+            input?: number;
+            output?: number;
+            cacheRead?: number;
+            cacheWrite?: number;
+            total?: number;
+        };
+    };
+}
+export declare class TraceRecorder {
+    private readonly backend;
+    private readonly context;
+    private root;
+    private attempt;
+    private attemptIndex;
+    private turn;
+    private turnIndex;
+    private generation;
+    private readonly tools;
+    private readonly duplicateToolIds;
+    private compaction;
+    private lastOutput;
+    private lastAssistant;
+    private lastAttemptOutcome;
+    private unresolvedToolErrors;
+    private startSnapshot;
+    private counters;
+    constructor(backend: TraceBackend, context: TraceRecorderOptions);
+    private startObservation;
+    hasActiveTrace(): boolean;
+    hasActiveAttempt(): boolean;
+    beginAgent(input: BeginAgentInput): void;
+    beginAttempt(input?: AttemptInput): void;
+    finishAttempt(message?: AssistantMessage): void;
+    beginTurn(turnIndex: number): void;
+    finishTurn(turnIndex: number, result: TurnResult): void;
+    beginGeneration(input?: GenerationInput): void;
+    recordProviderResponse(status: number, headers?: Record<string, string>): void;
+    markGenerationFirstOutput(timestamp?: number): void;
+    markGenerationEnd(endTime?: number): void;
+    finishAssistant(message: AssistantMessage): void;
+    beginTool(toolCallId: string, toolName: string, args?: unknown, startedAt?: number): void;
+    recordToolInput(toolCallId: string, input: unknown): void;
+    recordToolProgress(toolCallId: string, timestamp?: number): void;
+    finishTool(toolCallId: string, result: ToolResult): void;
+    beginCompaction(input: CompactionStart): void;
+    finishCompaction(input: CompactionFinish): void;
+    settle(snapshot?: ContextSnapshot): void;
+    interrupt(statusMessage: string, snapshot?: ContextSnapshot): void;
+    dispose(statusMessage?: string, snapshot?: ContextSnapshot): void;
+    private closeActiveTrace;
+    private closeAttempt;
+    private startToolObservation;
+    private closeTurn;
+    private closeTools;
+    private closeGeneration;
+    private closeCompaction;
+    private capture;
+}

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@narumitw/pi-langfuse",
-  "version": "0.50.6",
+  "version": "0.51.1",
   "description": "Pi extension that traces LLM generations and tool activity to Langfuse.",
   "type": "module",
   "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "private": false,
   "keywords": [
     "pi-package",
@@ -35,8 +43,8 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@types/node": "26.4.1",
+    "@earendil-works/pi-coding-agent": "0.86.0",
+    "@types/node": "26.6.2",
     "typescript": "7.0.2",
     "esbuild": "0.28.2"
   },

package/src/git.ts

@@ -0,0 +1,60 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { GitMetadata } from "./tracing.js";
+
+const GIT_LOOKUP_TIMEOUT_MS = 1_000;
+const MAX_GIT_BRANCH_LENGTH = 256;
+
+type GitExecutor = ExtensionAPI["exec"];
+
+export async function resolveGitMetadata(exec: GitExecutor, cwd: string): Promise<GitMetadata | undefined> {
+  const [branchResult, commit] = await Promise.all([resolveGitBranch(exec, cwd), resolveGitCommit(exec, cwd)]);
+  if (!branchResult.resolved) return undefined;
+  if (branchResult.branch) {
+    return {
+      branch: branchResult.branch,
+      ...(commit ? { commit } : {}),
+      detached: false,
+    };
+  }
+  return commit ? { commit, detached: true } : undefined;
+}
+
+async function resolveGitBranch(exec: GitExecutor, cwd: string): Promise<{ resolved: boolean; branch?: string }> {
+  try {
+    const result = await exec("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+      cwd,
+      timeout: GIT_LOOKUP_TIMEOUT_MS,
+    });
+    if (result.killed) return { resolved: false };
+    if (result.code === 1) return { resolved: true };
+    if (result.code !== 0) return { resolved: false };
+    const branch = normalizeGitBranch(result.stdout);
+    return branch ? { resolved: true, branch } : { resolved: false };
+  } catch {
+    return { resolved: false };
+  }
+}
+
+async function resolveGitCommit(exec: GitExecutor, cwd: string): Promise<string | undefined> {
+  try {
+    const result = await exec("git", ["rev-parse", "--verify", "--short=12", "HEAD"], {
+      cwd,
+      timeout: GIT_LOOKUP_TIMEOUT_MS,
+    });
+    if (result.code !== 0 || result.killed) return undefined;
+    const commit = result.stdout.trim();
+    return /^[0-9a-f]{4,64}$/iu.test(commit) ? commit.toLowerCase() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeGitBranch(value: string): string | undefined {
+  const branch = value.trim();
+  if (!branch || branch.length > MAX_GIT_BRANCH_LENGTH) return undefined;
+  for (const character of branch) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code <= 31 || code === 127) return undefined;
+  }
+  return branch;
+}

package/src/index.ts

@@ -1 +1,10 @@
 export { default } from "./langfuse.js";
+export {
+  type CreateLangfuseRuntimeOptions,
+  createLangfuseRuntime,
+  createPiLangfuseSession,
+  type LangfuseRuntime,
+  type LangfuseRuntimeConfig,
+  type PiLangfuseSession,
+  type PiLangfuseSessionOptions,
+} from "./public-api.js";