@agent-inspect/langchain 6.7.4 → 6.8.0

package/dist/index.d.cts

@@ -47,12 +47,17 @@ interface LangChainStreamingOptions {
 }
 interface AgentInspectCallbackOptions extends LangChainStreamingOptions {
     runName?: string;
+    /** Trace directory for JSONL. When set and `persist` is omitted, persistence is enabled. */
     traceDir?: string;
     silent?: boolean;
     capture?: CaptureMode;
     redact?: RedactionRule[];
     maxPreviewChars?: number;
-    /** When true, persist callback lifecycle as schemaVersion "0.1" JSONL (default false). */
+    /**
+     * Persist callback lifecycle as schemaVersion "0.1" JSONL.
+     * When omitted: enabled if `traceDir` is set, otherwise in-memory only.
+     * Explicit `false` forces in-memory even when `traceDir` is set.
+     */
     persist?: boolean;
     /** Optional run id for standalone persisted runs (defaults to generated id). */
     runId?: string;
@@ -72,9 +77,58 @@ type RetrieverDocuments = Parameters<NonNullable<BaseCallbackHandler["handleRetr
 declare class AgentInspectCallback extends BaseCallbackHandler {
     #private;
     name: string;
+    /**
+     * Ensure LangGraph/LangChain awaits async handler work (persistence) before
+     * invoke/stream settles. Required for deterministic standalone envelopes.
+     */
+    awaitHandlers: boolean;
     constructor(options?: AgentInspectCallbackOptions);
     getEvents(): InspectEvent[];
     clear(): void;
+    /**
+     * Bounded adapter diagnostics for the current invocation (counts only).
+     * Safe for CLI/MCP summaries — no absolute paths or payloads.
+     *
+     * @experimental
+     */
+    getDiagnostics(): {
+        lateEventCount: number;
+        activeRunCount: number;
+        endedRunCount: number;
+        pendingRelationshipCount: number;
+        knownRelationshipCount: number;
+        syntheticGroupCount: number;
+        envelopeStarted: boolean;
+        finalized: boolean;
+        completionGeneration: number;
+        hasTerminalError: boolean;
+        inMemoryEventCount: number;
+        deferredPersistStartCount: number;
+    };
+    /**
+     * Drain deferred completion work (microtask finalization).
+     * Idempotent. Failures are isolated and never thrown to user code.
+     *
+     * @experimental Additive finalization API for serverless / unusual callback shapes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Complete the standalone envelope when started. Fallback when automatic
+     * completion cannot run (e.g. process shutdown). Idempotent.
+     * Failures are isolated and never thrown to user code.
+     *
+     * @experimental Additive finalization API for serverless / unusual callback shapes.
+     */
+    finalize(options?: {
+        status?: "success" | "error";
+        errorMessage?: string;
+    }): Promise<void>;
+    /**
+     * `flush()` then `finalize()`. Idempotent. Failures are isolated.
+     *
+     * @experimental Additive finalization API for serverless / unusual callback shapes.
+     */
+    close(): Promise<void>;
     handleChainStart(chain: Serialized, inputs: ChainValues, runId: string, runType?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string, parentRunId?: string, _extra?: Record<string, unknown>): Promise<void>;
     handleChainEnd(outputs: ChainValues, runId: string, parentRunId?: string, tags?: string[], _kwargs?: {
         inputs?: Record<string, unknown>;
@@ -92,7 +146,7 @@ declare class AgentInspectCallback extends BaseCallbackHandler {
     }): void | Promise<void>;
     handleLLMEnd(output: LLMResult, runId: string, parentRunId?: string, tags?: string[], _extraParams?: Record<string, unknown>): Promise<void>;
     handleLLMError(err: unknown, runId: string, parentRunId?: string, tags?: string[], _extraParams?: Record<string, unknown>): Promise<void>;
-    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string, _toolCallId?: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string, toolCallId?: string): Promise<void>;
     handleToolEnd(output: unknown, runId: string, parentRunId?: string, tags?: string[]): Promise<void>;
     handleToolError(err: unknown, runId: string, parentRunId?: string, tags?: string[]): Promise<void>;
     handleRetrieverStart(retriever: Serialized, _query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, name?: string): Promise<void>;
@@ -102,6 +156,26 @@ declare class AgentInspectCallback extends BaseCallbackHandler {
     handleAgentEnd(finish: AgentFinish, runId: string, parentRunId?: string, tags?: string[]): Promise<void>;
 }
 
+/** Options for explicit envelope finalization (serverless / unusual callback shapes). */
+interface FinalizeOptions {
+    status?: "success" | "error";
+    errorMessage?: string;
+    endTime?: number;
+}
+/** Bounded persistence diagnostics (no absolute paths / customer payloads). */
+interface AdapterPersistenceDiagnostics {
+    readonly lateEventCount: number;
+    readonly activeRunCount: number;
+    readonly endedRunCount: number;
+    readonly pendingRelationshipCount: number;
+    readonly knownRelationshipCount: number;
+    readonly syntheticGroupCount: number;
+    readonly envelopeStarted: boolean;
+    readonly finalized: boolean;
+    readonly completionGeneration: number;
+    readonly hasTerminalError: boolean;
+}
+
 interface TokenUsage {
     input?: number;
     output?: number;
@@ -116,4 +190,4 @@ declare function safePreview(value: unknown, maxChars: number): string | undefin
 /** Shallow plain metadata: drops functions/symbols; avoids deep nesting. Never throws. */
 declare function toPlainMetadata(value: unknown): Record<string, unknown>;
 
-export { AgentInspectCallback, type AgentInspectCallbackOptions, type CaptureMode, type LangChainRunMetadata, type LangChainStreamingOptions, type TokenUsage, extractModelName, extractTokenUsage, safePreview, toPlainMetadata };
+export { type AdapterPersistenceDiagnostics, AgentInspectCallback, type AgentInspectCallbackOptions, type CaptureMode, type FinalizeOptions, type LangChainRunMetadata, type LangChainStreamingOptions, type TokenUsage, extractModelName, extractTokenUsage, safePreview, toPlainMetadata };

package/dist/index.d.ts

@@ -47,12 +47,17 @@ interface LangChainStreamingOptions {
 }
 interface AgentInspectCallbackOptions extends LangChainStreamingOptions {
     runName?: string;
+    /** Trace directory for JSONL. When set and `persist` is omitted, persistence is enabled. */
     traceDir?: string;
     silent?: boolean;
     capture?: CaptureMode;
     redact?: RedactionRule[];
     maxPreviewChars?: number;
-    /** When true, persist callback lifecycle as schemaVersion "0.1" JSONL (default false). */
+    /**
+     * Persist callback lifecycle as schemaVersion "0.1" JSONL.
+     * When omitted: enabled if `traceDir` is set, otherwise in-memory only.
+     * Explicit `false` forces in-memory even when `traceDir` is set.
+     */
     persist?: boolean;
     /** Optional run id for standalone persisted runs (defaults to generated id). */
     runId?: string;
@@ -72,9 +77,58 @@ type RetrieverDocuments = Parameters<NonNullable<BaseCallbackHandler["handleRetr
 declare class AgentInspectCallback extends BaseCallbackHandler {
     #private;
     name: string;
+    /**
+     * Ensure LangGraph/LangChain awaits async handler work (persistence) before
+     * invoke/stream settles. Required for deterministic standalone envelopes.
+     */
+    awaitHandlers: boolean;
     constructor(options?: AgentInspectCallbackOptions);
     getEvents(): InspectEvent[];
     clear(): void;
+    /**
+     * Bounded adapter diagnostics for the current invocation (counts only).
+     * Safe for CLI/MCP summaries — no absolute paths or payloads.
+     *
+     * @experimental
+     */
+    getDiagnostics(): {
+        lateEventCount: number;
+        activeRunCount: number;
+        endedRunCount: number;
+        pendingRelationshipCount: number;
+        knownRelationshipCount: number;
+        syntheticGroupCount: number;
+        envelopeStarted: boolean;
+        finalized: boolean;
+        completionGeneration: number;
+        hasTerminalError: boolean;
+        inMemoryEventCount: number;
+        deferredPersistStartCount: number;
+    };
+    /**
+     * Drain deferred completion work (microtask finalization).
+     * Idempotent. Failures are isolated and never thrown to user code.
+     *
+     * @experimental Additive finalization API for serverless / unusual callback shapes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Complete the standalone envelope when started. Fallback when automatic
+     * completion cannot run (e.g. process shutdown). Idempotent.
+     * Failures are isolated and never thrown to user code.
+     *
+     * @experimental Additive finalization API for serverless / unusual callback shapes.
+     */
+    finalize(options?: {
+        status?: "success" | "error";
+        errorMessage?: string;
+    }): Promise<void>;
+    /**
+     * `flush()` then `finalize()`. Idempotent. Failures are isolated.
+     *
+     * @experimental Additive finalization API for serverless / unusual callback shapes.
+     */
+    close(): Promise<void>;
     handleChainStart(chain: Serialized, inputs: ChainValues, runId: string, runType?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string, parentRunId?: string, _extra?: Record<string, unknown>): Promise<void>;
     handleChainEnd(outputs: ChainValues, runId: string, parentRunId?: string, tags?: string[], _kwargs?: {
         inputs?: Record<string, unknown>;
@@ -92,7 +146,7 @@ declare class AgentInspectCallback extends BaseCallbackHandler {
     }): void | Promise<void>;
     handleLLMEnd(output: LLMResult, runId: string, parentRunId?: string, tags?: string[], _extraParams?: Record<string, unknown>): Promise<void>;
     handleLLMError(err: unknown, runId: string, parentRunId?: string, tags?: string[], _extraParams?: Record<string, unknown>): Promise<void>;
-    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string, _toolCallId?: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string, toolCallId?: string): Promise<void>;
     handleToolEnd(output: unknown, runId: string, parentRunId?: string, tags?: string[]): Promise<void>;
     handleToolError(err: unknown, runId: string, parentRunId?: string, tags?: string[]): Promise<void>;
     handleRetrieverStart(retriever: Serialized, _query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, name?: string): Promise<void>;
@@ -102,6 +156,26 @@ declare class AgentInspectCallback extends BaseCallbackHandler {
     handleAgentEnd(finish: AgentFinish, runId: string, parentRunId?: string, tags?: string[]): Promise<void>;
 }
 
+/** Options for explicit envelope finalization (serverless / unusual callback shapes). */
+interface FinalizeOptions {
+    status?: "success" | "error";
+    errorMessage?: string;
+    endTime?: number;
+}
+/** Bounded persistence diagnostics (no absolute paths / customer payloads). */
+interface AdapterPersistenceDiagnostics {
+    readonly lateEventCount: number;
+    readonly activeRunCount: number;
+    readonly endedRunCount: number;
+    readonly pendingRelationshipCount: number;
+    readonly knownRelationshipCount: number;
+    readonly syntheticGroupCount: number;
+    readonly envelopeStarted: boolean;
+    readonly finalized: boolean;
+    readonly completionGeneration: number;
+    readonly hasTerminalError: boolean;
+}
+
 interface TokenUsage {
     input?: number;
     output?: number;
@@ -116,4 +190,4 @@ declare function safePreview(value: unknown, maxChars: number): string | undefin
 /** Shallow plain metadata: drops functions/symbols; avoids deep nesting. Never throws. */
 declare function toPlainMetadata(value: unknown): Record<string, unknown>;
 
-export { AgentInspectCallback, type AgentInspectCallbackOptions, type CaptureMode, type LangChainRunMetadata, type LangChainStreamingOptions, type TokenUsage, extractModelName, extractTokenUsage, safePreview, toPlainMetadata };
+export { type AdapterPersistenceDiagnostics, AgentInspectCallback, type AgentInspectCallbackOptions, type CaptureMode, type FinalizeOptions, type LangChainRunMetadata, type LangChainStreamingOptions, type TokenUsage, extractModelName, extractTokenUsage, safePreview, toPlainMetadata };