@threadplane/langgraph 0.0.49 → 0.0.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadplane/langgraph",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "description": "LangGraph adapter for @threadplane/chat — Angular bindings for LangGraph Platform.",
   "keywords": [
     "angular",

package/types/threadplane-langgraph.d.ts

@@ -4,7 +4,7 @@ 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, Message, AgentStatus, ToolCall, AgentInterrupt, Subagent, AgentCheckpoint, MockAgent, MockAgentOptions, Citation, Thread } from '@threadplane/chat';
+import { AgentRuntimeTelemetrySink, AgentWithHistory, AgentSubmitInput, AgentSubmitOptions, ClientToolsCapability, AgentRef, Message, AgentStatus, AgentError, 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 { FakeAgentConfig } from '@threadplane/chat/testing';
@@ -166,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;
@@ -183,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. */
@@ -211,7 +230,7 @@ interface SubagentStreamRef {
  * any LangGraph-specific demo. Raw LangGraph signals are prefixed with
  * `langGraph` to avoid collision with the runtime-neutral names.
  */
-interface LangGraphAgent<T = unknown, ResolvedBag extends BagTemplate = BagTemplate> extends AgentWithHistory {
+interface LangGraphAgent<T = unknown, ResolvedBag extends BagTemplate = BagTemplate> extends AgentWithHistory<T> {
     /** Raw LangChain BaseMessage list. Use `messages` for chat rendering. */
     langGraphMessages: Signal<BaseMessage[]>;
     /** All interrupts received during the current run (raw LangGraph shape). */
@@ -224,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. */
@@ -301,6 +327,8 @@ interface AgentConfig<T = Record<string, unknown>, _Bag extends BagTemplate = Ba
     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. */
@@ -333,7 +361,20 @@ interface AgentConfig<T = Record<string, unknown>, _Bag extends BagTemplate = Ba
  *   }),
  * ];
  * ```
+ *
+ * **Typed state via AgentRef.** Pass a typed ref as the first argument to flow
+ * the state shape from `provideAgent` to `injectAgent` without repeating the
+ * generic at every call site:
+ *
+ * ```ts
+ * export const TRIP = createAgentRef<TripState>('trip');
+ * // app.config.ts:
+ * providers: [provideAgent(TRIP, { assistantId: 'trip-graph' })]
+ * // component:
+ * const agent = injectAgent(TRIP); // LangGraphAgent<TripState>
+ * ```
  */
+declare function provideAgent<T = Record<string, unknown>>(ref: AgentRef<T>, configOrFactory: AgentConfig<T> | (() => AgentConfig<T>)): Provider[];
 declare function provideAgent<T = Record<string, unknown>>(configOrFactory: AgentConfig<T> | (() => AgentConfig<T>)): Provider[];
 
 /**
@@ -344,8 +385,19 @@ declare function provideAgent<T = Record<string, unknown>>(configOrFactory: Agen
  * 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).
+ *
+ * **Typed state via AgentRef.** Pass the same ref that was supplied to
+ * `provideAgent(ref, …)` to carry the state type through DI without repeating
+ * the generic at every call site:
+ *
+ * ```ts
+ * const agent = injectAgent(TRIP); // LangGraphAgent<TripState>
+ * ```
+ *
+ * The no-arg form defaults to `LangGraphAgent<Record<string, unknown>>`.
  */
-declare function injectAgent<T = Record<string, unknown>, ResolvedBag extends BagTemplate = BagTemplate>(): LangGraphAgent<T, ResolvedBag>;
+declare function injectAgent(): LangGraphAgent<Record<string, unknown>>;
+declare function injectAgent<T, ResolvedBag extends BagTemplate = BagTemplate>(ref: AgentRef<T>): LangGraphAgent<T, ResolvedBag>;
 
 /**
  * Optional registry that collects per-instance agent lifecycles within
@@ -442,8 +494,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. */
@@ -475,7 +528,7 @@ interface MockLangGraphAgent extends LangGraphAgent<any, any> {
     messages: WritableSignal<Message[]>;
     status: WritableSignal<AgentStatus>;
     isLoading: WritableSignal<boolean>;
-    error: WritableSignal<unknown>;
+    error: WritableSignal<AgentError | undefined>;
     toolCalls: WritableSignal<ToolCall[]>;
     interrupt: WritableSignal<AgentInterrupt | undefined>;
     subagents: WritableSignal<Map<string, Subagent>>;
@@ -558,17 +611,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):
@@ -620,6 +690,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;
@@ -687,5 +758,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_LIFECYCLE, AgentLifecycleRegistry, FakeStreamTransport, FetchStreamTransport, LANGGRAPH_CLIENT, 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, 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 };