@threadplane/langgraph 0.0.47 → 0.0.49

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@threadplane/langgraph",
-  "version": "0.0.47",
+  "version": "0.0.49",
+  "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, 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(). */
@@ -203,7 +204,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
@@ -278,51 +279,73 @@ 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;
+    /** 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
@@ -440,46 +463,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;
 }
@@ -625,5 +687,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 { 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 };