@threadplane/langgraph 0.0.50 → 0.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadplane/langgraph",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "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, ClientToolsCapability, 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';
@@ -230,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). */
@@ -351,8 +351,13 @@ interface AgentConfig<T = Record<string, unknown>, _Bag extends BagTemplate = Ba
  * 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:
+ * component-scoped signals.
  *
+ * **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.
+ *
+ * @example Factory config reading route params
  * ```ts
  * providers: [
  *   provideAgent(() => {
@@ -361,7 +366,16 @@ interface AgentConfig<T = Record<string, unknown>, _Bag extends BagTemplate = Ba
  *   }),
  * ];
  * ```
+ * @example Typed state via AgentRef
+ * ```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[];
 
 /**
@@ -372,8 +386,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. The no-arg form defaults to
+ * `LangGraphAgent<Record<string, unknown>>`.
+ *
+ * @example Typed state via AgentRef
+ * ```ts
+ * const agent = injectAgent(TRIP); // LangGraphAgent<TripState>
+ * ```
  */
-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
@@ -504,7 +529,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>>;
@@ -574,6 +599,19 @@ declare class FakeStreamTransport implements AgentTransport {
 interface KwargsLike {
     additional_kwargs?: Record<string, unknown> | undefined;
 }
+/**
+ * Normalize {@link Citation}s out of a message's `additional_kwargs` (reading
+ * `citations` or `sources`). Exposed for advanced consumers building custom
+ * adapters or bridging non-LangGraph message shapes into the neutral
+ * `Citation[]` form.
+ *
+ * @param msg Any object with an `additional_kwargs` bag (e.g. a LangChain message).
+ * @returns The normalized citations, or `undefined` when none are present.
+ * @example
+ * ```ts
+ * const citations = extractCitations(lcMessage);
+ * ```
+ */
 declare function extractCitations(msg: KwargsLike): Citation[] | undefined;
 
 /**