@threadplane/langgraph 0.0.47 → 0.0.50

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@threadplane/langgraph",
-  "version": "0.0.47",
+  "version": "0.0.50",
+  "description": "LangGraph adapter for @threadplane/chat — Angular bindings for LangGraph Platform.",
+  "keywords": [
+    "angular",
+    "langgraph",
+    "langchain",
+    "agent",
+    "adapter",
+    "threadplane"
+  ],
   "peerDependencies": {
     "@threadplane/chat": "*",
     "@angular/core": "^20.0.0 || ^21.0.0",

package/types/threadplane-langgraph.d.ts

@@ -1,12 +1,13 @@
-import * as _langchain_langgraph_sdk from '@langchain/langgraph-sdk';
-import { Config, Checkpoint, Command, Metadata, StreamMode, ThreadState, BagTemplate, Interrupt, ToolCallWithResult, ToolProgress, InferBag, Client } from '@langchain/langgraph-sdk';
-export { BagTemplate, InferBag, Interrupt, ThreadState } from '@langchain/langgraph-sdk';
 import * as i0 from '@angular/core';
 import { InjectionToken, Signal, ResourceStatus as ResourceStatus$1, Provider, WritableSignal } from '@angular/core';
+import { BaseMessage, AIMessage } from '@langchain/core/messages';
+import * as _langchain_langgraph_sdk from '@langchain/langgraph-sdk';
+import { ThreadState, Config, Checkpoint, Command, Metadata, StreamMode, BagTemplate, Interrupt, ToolCallWithResult, ToolProgress, Client } from '@langchain/langgraph-sdk';
+export { BagTemplate, InferBag, Interrupt, ThreadState } from '@langchain/langgraph-sdk';
+import { AgentRuntimeTelemetrySink, AgentWithHistory, AgentSubmitInput, AgentSubmitOptions, ClientToolsCapability, Message, AgentStatus, ToolCall, AgentInterrupt, Subagent, AgentCheckpoint, MockAgent, MockAgentOptions, Citation, Thread } from '@threadplane/chat';
 import { MessageMetadata } from '@langchain/langgraph-sdk/ui';
 export { SubmitOptions } from '@langchain/langgraph-sdk/ui';
-import { BaseMessage, AIMessage } from '@langchain/core/messages';
-import { AgentRuntimeTelemetrySink, AgentWithHistory, AgentSubmitInput, AgentSubmitOptions, Message, AgentStatus, AgentInterrupt, ToolCall, AgentCheckpoint, Subagent, Citation, Thread } from '@threadplane/chat';
+import { FakeAgentConfig } from '@threadplane/chat/testing';
 
 interface AgentLifecycle {
     /** Epoch ms of the first stream chunk arrival. Resets on switchThread(). */
@@ -165,6 +166,23 @@ interface AgentTransport {
     }): Promise<void>;
 }
 /** Options for creating a LangGraph-backed agent via {@link agent}. */
+/**
+ * Tuning options for the underlying LangGraph SDK `Client` constructed by the
+ * default {@link FetchStreamTransport}. Ignored when a custom `transport` is
+ * supplied (the transport owns its own client).
+ */
+interface LangGraphClientOptions {
+    /**
+     * How many times a failed request — including the initial stream connect —
+     * is retried with exponential backoff before the error surfaces. Maps to the
+     * SDK's `callerOptions.maxRetries`. Omitted → the SDK default (currently 4).
+     *
+     * Set `0` to fail fast: useful for e2e tests that force a connection failure
+     * and assert the error surfaces promptly, rather than after the full
+     * multi-second backoff window.
+     */
+    maxRetries?: number;
+}
 interface AgentOptions<T, _ResolvedBag extends BagTemplate> {
     /** Base URL of the LangGraph Platform API. Defaults to `provideAgent({ apiUrl })` when omitted. */
     apiUrl?: string;
@@ -182,6 +200,8 @@ interface AgentOptions<T, _ResolvedBag extends BagTemplate> {
     toMessage?: (msg: unknown) => BaseMessage;
     /** Custom transport. Defaults to FetchStreamTransport. */
     transport?: AgentTransport;
+    /** Tuning options for the default transport's LangGraph SDK client (e.g. retry budget). */
+    clientOptions?: LangGraphClientOptions;
     /** Optional app-owned telemetry sink. No telemetry is emitted unless this is provided. */
     telemetry?: AgentRuntimeTelemetrySink | false;
     /** When true, subagent messages are filtered from the main messages signal. */
@@ -203,7 +223,7 @@ interface SubagentStreamRef {
     messages: Signal<BaseMessage[]>;
 }
 /**
- * Unified LangGraph agent surface returned by `agent({...})`.
+ * Unified LangGraph agent surface returned by `injectAgent()`.
  *
  * Extends the runtime-neutral `AgentWithHistory` contract (chat-consumable)
  * with the full LangGraph-specific API. One object drives both `<chat>` and
@@ -223,6 +243,13 @@ interface LangGraphAgent<T = unknown, ResolvedBag extends BagTemplate = BagTempl
     experimentalBranchTree: Signal<AgentBranchTree<T>>;
     /** Submit input, resume commands, checkpoint forks, or other LangGraph run options. */
     submit: (input: AgentSubmitInput | null | undefined, opts?: AgentSubmitOptions & LangGraphSubmitOptions) => Promise<void>;
+    /**
+     * Client-declared, client-executed tools. Call setCatalog() to register
+     * tool specs; the catalog is automatically shipped with every run via
+     * `input.client_tools`. Pending tool calls appear in pending() after
+     * the run ends; resolve() returns a result and continues the run.
+     */
+    clientTools: ClientToolsCapability;
     /** Current agent state values (raw, typed per the type parameter T). */
     value: Signal<T>;
     /** True once at least one value or message has been received. */
@@ -278,51 +305,75 @@ interface LangGraphAgent<T = unknown, ResolvedBag extends BagTemplate = BagTempl
 }
 
 /**
- * Creates a LangGraph-backed Angular agent.
+ * Configuration for an agent instance.
+ * Combines connection defaults with per-component options so the
+ * agent can be constructed once at provider time and injected
+ * everywhere it is needed.
+ */
+interface AgentConfig<T = Record<string, unknown>, _Bag extends BagTemplate = BagTemplate> {
+    /** Base URL of the LangGraph Platform API (e.g., `'http://localhost:2024'`). */
+    apiUrl?: string;
+    /** Agent or graph identifier on the LangGraph platform. */
+    assistantId?: string;
+    /** Thread ID to connect to. Pass a Signal for reactive thread switching. */
+    threadId?: Signal<string | null> | string | null;
+    /** Called when a new thread is auto-created by the transport. */
+    onThreadId?: (id: string) => void;
+    /** Initial state values before the first stream response arrives. */
+    initialValues?: Partial<T>;
+    /** Throttle signal updates in milliseconds. `false` to disable. */
+    throttle?: number | false;
+    /** Custom message deserializer for non-standard message formats. */
+    toMessage?: (msg: unknown) => BaseMessage;
+    /** Custom transport. Defaults to {@link FetchStreamTransport}. */
+    transport?: AgentTransport;
+    /** Tuning options for the default transport's LangGraph SDK client (e.g. retry budget). */
+    clientOptions?: LangGraphClientOptions;
+    /** Optional app-owned telemetry sink. No telemetry is emitted unless this is provided. */
+    telemetry?: AgentRuntimeTelemetrySink | false;
+    /** When true, subagent messages are filtered from the main messages signal. */
+    filterSubagentMessages?: boolean;
+    /** Tool names that indicate a subagent invocation. */
+    subagentToolNames?: string[];
+}
+/**
+ * Wire the LangGraph adapter into Angular's dependency injection.
  *
- * Must be called within an Angular injection context (component constructor,
- * field initializer, or `runInInjectionContext`). Returns a unified
- * {@link LangGraphAgent} whose properties are Angular Signals that update
- * in real time as LangGraph streams messages, values, tool calls, interrupts,
- * subagent state, and checkpoint history.
+ * Registers a singleton `LangGraphAgent` constructed from `config`. Retrieve it
+ * in any component with `injectAgent()`. Provide this at the application root
+ * (`app.config.ts`) for an app-wide agent.
  *
- * @typeParam T - The state shape returned by the agent
- * @typeParam Bag - Optional bag template for typed interrupts and submit payloads
- * @param options - Configuration for the LangGraph agent
- * @returns A {@link LangGraphAgent} with reactive signals and action methods
+ * To use a different agent in a component subtree, re-provide
+ * `provideAgent({...})` in that component's `providers: []` array —
+ * Angular's hierarchical DI scopes the singleton accordingly.
  *
- * @example
- * ```typescript
- * // In a component field initializer
- * const chat = agent({
- *   assistantId: 'chat_agent',
- *   apiUrl: 'http://localhost:2024',
- *   threadId: signal(this.savedThreadId),
- *   onThreadId: (id) => localStorage.setItem('threadId', id),
- * });
+ * **Static vs factory config.** Pass a plain `AgentConfig` object when the
+ * config is known up front. Pass a `() => AgentConfig` factory when the config
+ * depends on runtime/DI state — the factory runs inside an Angular injection
+ * context, so it may call `inject()` to read services, route params, or
+ * component-scoped signals:
  *
- * // Access signals in template
- * // chat.messages(), chat.status(), chat.error()
+ * ```ts
+ * providers: [
+ *   provideAgent(() => {
+ *     const route = inject(ActivatedRoute);
+ *     return { assistantId: 'chat', threadId: toSignal(route.paramMap) };
+ *   }),
+ * ];
  * ```
  */
-declare function agent<T = Record<string, unknown>, Bag extends BagTemplate = BagTemplate>(options: AgentOptions<T, InferBag<T, Bag>>): LangGraphAgent<T, InferBag<T, Bag>>;
+declare function provideAgent<T = Record<string, unknown>>(configOrFactory: AgentConfig<T> | (() => AgentConfig<T>)): Provider[];
 
 /**
- * Global configuration for agent instances.
- * Properties set here serve as defaults that can be overridden per-call.
- */
-interface AgentConfig {
-    /** Base URL of the LangGraph Platform API (e.g., `'http://localhost:2024'`). */
-    apiUrl?: string;
-    /** Custom transport implementation. Defaults to {@link FetchStreamTransport}. */
-    transport?: AgentTransport;
-}
-declare const AGENT_CONFIG: InjectionToken<AgentConfig>;
-/**
- * Angular provider factory that registers global defaults for all
- * agent instances in the application.
+ * Retrieve the LangGraph-backed Agent from the current Angular injection context.
+ *
+ * Mirrors `@threadplane/ag-ui`'s `injectAgent()` so consumer code is identical
+ * regardless of which adapter is wired in `app.config.ts`. The agent is a
+ * singleton scoped to the injector that called `provideAgent()` — re-provide
+ * in a child component's `providers: []` to scope a different agent to that
+ * subtree (Angular's hierarchical DI handles the rest).
  */
-declare function provideAgent(config: AgentConfig): Provider;
+declare function injectAgent<T = Record<string, unknown>, ResolvedBag extends BagTemplate = BagTemplate>(): LangGraphAgent<T, ResolvedBag>;
 
 /**
  * Optional registry that collects per-instance agent lifecycles within
@@ -419,8 +470,9 @@ declare class FetchStreamTransport implements AgentTransport {
     /**
      * @param apiUrl - Base URL of the LangGraph Platform API
      * @param onThreadId - Optional callback invoked when a new thread is created
+     * @param clientOptions - Optional SDK client tuning (e.g. `maxRetries`)
      */
-    constructor(apiUrl: string, onThreadId?: (id: string) => void);
+    constructor(apiUrl: string, onThreadId?: (id: string) => void, clientOptions?: LangGraphClientOptions);
     /** Open a streaming connection, creating a thread if needed. */
     stream(assistantId: string, threadId: string | null, payload: unknown, signal: AbortSignal, options?: LangGraphSubmitOptions): AsyncIterable<StreamEvent>;
     /** Join an already-started run without creating a new thread. */
@@ -440,46 +492,85 @@ declare class FetchStreamTransport implements AgentTransport {
 /**
  * A LangGraphAgent mock with writable signals for easy test control.
  *
+ * Builds on the runtime-neutral {@link MockAgent} from `@threadplane/chat`
+ * (which supplies the neutral `Agent`-contract writable signals plus
+ * `submit`/`stop`/`regenerate` call tracking) and layers the LangGraph-specific
+ * writable signals on top.
+ *
  * Cast the result of `mockLangGraphAgent()` to this type to access
  * writable signals without unsafe casts in test files.
  */
 interface MockLangGraphAgent extends LangGraphAgent<any, any> {
     messages: WritableSignal<Message[]>;
-    langGraphMessages: WritableSignal<BaseMessage[]>;
     status: WritableSignal<AgentStatus>;
     isLoading: WritableSignal<boolean>;
     error: WritableSignal<unknown>;
+    toolCalls: WritableSignal<ToolCall[]>;
+    interrupt: WritableSignal<AgentInterrupt | undefined>;
+    subagents: WritableSignal<Map<string, Subagent>>;
+    history: WritableSignal<AgentCheckpoint[]>;
+    submitCalls: MockAgent['submitCalls'];
+    stopCount: MockAgent['stopCount'];
+    _internal: MockAgent['_internal'];
+    langGraphMessages: WritableSignal<BaseMessage[]>;
     hasValue: WritableSignal<boolean>;
     value: WritableSignal<any>;
-    interrupt: WritableSignal<AgentInterrupt | undefined>;
     langGraphInterrupts: WritableSignal<Interrupt<any>[]>;
-    toolCalls: WritableSignal<ToolCall[]>;
     langGraphToolCalls: WritableSignal<ToolCallWithResult[]>;
     toolProgress: WritableSignal<ToolProgress[]>;
     queue: WritableSignal<AgentQueue>;
     branch: WritableSignal<string>;
-    history: WritableSignal<AgentCheckpoint[]>;
     langGraphHistory: WritableSignal<ThreadState<any>[]>;
     experimentalBranchTree: WritableSignal<AgentBranchTree<any>>;
     isThreadLoading: WritableSignal<boolean>;
-    subagents: WritableSignal<Map<string, Subagent>>;
     activeSubagents: WritableSignal<SubagentStreamRef[]>;
     customEvents: WritableSignal<CustomStreamEvent[]>;
 }
 /**
  * Creates a mock LangGraphAgent with writable signals for testing.
  * Control state by writing to the returned writable signals directly.
+ *
+ * Neutral `Agent`-contract signals come from {@link mockAgent}; LangGraph-specific
+ * signals are declared here and layered on top.
  */
-declare function mockLangGraphAgent(initial?: {
-    messages?: Message[];
+declare function mockLangGraphAgent(initial?: MockAgentOptions & {
     langGraphMessages?: BaseMessage[];
-    status?: AgentStatus;
-    isLoading?: boolean;
-    error?: unknown;
     hasValue?: boolean;
     isThreadLoading?: boolean;
 }): MockLangGraphAgent;
 
+/**
+ * Wire an in-process fake LangGraph agent into Angular DI.
+ *
+ * Streams a canned assistant reply (see FakeAgentConfig) with no backend —
+ * the symmetric counterpart to @threadplane/ag-ui's provideFakeAgent(). For
+ * advanced manual scripting (tool calls, interrupts, multi-batch), provide
+ * the agent yourself with
+ * `provideAgent({ assistantId, transport: new MockAgentTransport(...) })`.
+ */
+declare function provideFakeAgent(config?: FakeAgentConfig): Provider[];
+
+/**
+ * In-process AgentTransport that auto-streams a canned assistant reply.
+ *
+ * Backs `provideFakeAgent()`. Unlike `MockAgentTransport` (passive, driven
+ * manually from specs), this transport emits its tokens automatically on
+ * `stream()`, then completes — suitable for offline demos and integration tests.
+ *
+ * NOT for production use.
+ */
+declare class FakeStreamTransport implements AgentTransport {
+    private readonly tokens;
+    private readonly reasoningTokens;
+    private readonly delayMs;
+    constructor(config?: FakeAgentConfig);
+    stream(_assistantId: string, _threadId: string | null, _payload: unknown, signal: AbortSignal, _options?: LangGraphSubmitOptions): AsyncIterable<StreamEvent>;
+    createQueuedRun(_assistantId: string, threadId: string, payload: unknown, _signal: AbortSignal, options?: LangGraphSubmitOptions): Promise<AgentQueueEntry>;
+    cancelRun(_threadId: string, _runId: string, _signal: AbortSignal): Promise<void>;
+    getHistory(_threadId: string, _signal: AbortSignal): Promise<ThreadState[]>;
+    joinStream(): AsyncIterable<StreamEvent>;
+}
+
 interface KwargsLike {
     additional_kwargs?: Record<string, unknown> | undefined;
 }
@@ -496,17 +587,34 @@ declare function extractCitations(msg: KwargsLike): Citation[] | undefined;
  * transport (`fetch-stream.transport.ts`) and the threads adapter
  * (`LangGraphThreadsAdapter`) both go through here.
  *
+ * `clientOptions.maxRetries` maps to the SDK's `callerOptions.maxRetries`,
+ * which governs how many times a failed request (including the initial
+ * stream connect) is retried with exponential backoff before the error
+ * surfaces. Omitted → the SDK default (currently 4). Apps under test set
+ * `0` so a forced connection failure surfaces immediately instead of after
+ * the full backoff window.
+ *
  * @example
  * ```ts
  * const client = createLangGraphClient(environment.langGraphApiUrl);
  * const threads = await client.threads.search({ limit: 50 });
  * ```
  */
-declare function createLangGraphClient(apiUrl: string): Client;
+declare function createLangGraphClient(apiUrl: string, clientOptions?: LangGraphClientOptions): Client;
 /** Exported separately so non-Client callers (e.g. raw fetch) can
  *  share the same normalization logic. */
 declare function toAbsoluteApiUrl(apiUrl: string): string;
 
+/**
+ * App-wide LangGraph SDK client tuning (e.g. `maxRetries`). Provide once at the
+ * app root; both the agent's default {@link FetchStreamTransport} and the
+ * {@link LangGraphThreadsAdapter} read it so the retry budget is configured in
+ * one place. A call-site `agent({ clientOptions })` or per-agent
+ * `provideAgent({ clientOptions })` overrides it for that agent.
+ * Absent → the SDK default.
+ */
+declare const LANGGRAPH_CLIENT_OPTIONS: InjectionToken<LangGraphClientOptions>;
+
 /**
  * Configuration consumed by {@link LangGraphThreadsAdapter}. Provide
  * via {@link LANGGRAPH_THREADS_CONFIG} (typically in app.config.ts):
@@ -558,6 +666,7 @@ declare const LANGGRAPH_CLIENT: InjectionToken<Client<_langchain_langgraph_sdk.D
  */
 declare class LangGraphThreadsAdapter {
     private readonly config;
+    private readonly sharedClientOptions;
     private readonly client;
     private readonly fallback;
     private readonly _threads;
@@ -625,5 +734,5 @@ declare function refreshOnRunEnd(agent: LangGraphAgent, fn: () => void | Promise
  */
 declare function refreshOnTransition<T>(watch: Signal<T>, isActive: (v: T) => boolean, fn: () => void | Promise<void>): void;
 
-export { AGENT_CONFIG, AGENT_LIFECYCLE, AgentLifecycleRegistry, FetchStreamTransport, LANGGRAPH_CLIENT, LANGGRAPH_THREADS_CONFIG, LangGraphThreadsAdapter, MockAgentTransport, ResourceStatus, agent, createLangGraphClient, extractCitations, mockLangGraphAgent, provideAgent, refreshOnRunEnd, refreshOnTransition, toAbsoluteApiUrl };
-export type { AgentBranchTree, AgentBranchTreeFork, AgentBranchTreeNode, AgentConfig, AgentLifecycle, AgentOptions, AgentQueue, AgentQueueEntry, AgentTransport, CustomStreamEvent, LangGraphAgent, LangGraphMultitaskStrategy, LangGraphSubmitOptions, LangGraphThreadsConfig, MockLangGraphAgent, StreamEvent, SubagentStreamRef };
+export { AGENT_LIFECYCLE, AgentLifecycleRegistry, FakeStreamTransport, FetchStreamTransport, LANGGRAPH_CLIENT, LANGGRAPH_CLIENT_OPTIONS, LANGGRAPH_THREADS_CONFIG, LangGraphThreadsAdapter, MockAgentTransport, ResourceStatus, createLangGraphClient, extractCitations, injectAgent, mockLangGraphAgent, provideAgent, provideFakeAgent, refreshOnRunEnd, refreshOnTransition, toAbsoluteApiUrl };
+export type { AgentBranchTree, AgentBranchTreeFork, AgentBranchTreeNode, AgentConfig, AgentLifecycle, AgentOptions, AgentQueue, AgentQueueEntry, AgentTransport, CustomStreamEvent, LangGraphAgent, LangGraphClientOptions, LangGraphMultitaskStrategy, LangGraphSubmitOptions, LangGraphThreadsConfig, MockLangGraphAgent, StreamEvent, SubagentStreamRef };