@threadplane/langgraph 0.0.46

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@threadplane/langgraph",
+  "version": "0.0.46",
+  "peerDependencies": {
+    "@threadplane/chat": "*",
+    "@angular/core": "^20.0.0 || ^21.0.0",
+    "@langchain/core": "^1.1.33",
+    "@langchain/langgraph-sdk": "^1.7.4",
+    "rxjs": "~7.8.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cacheplane/angular-agent-framework.git",
+    "directory": "libs/langgraph"
+  },
+  "homepage": "https://github.com/cacheplane/angular-agent-framework#readme",
+  "bugs": {
+    "url": "https://github.com/cacheplane/angular-agent-framework/issues"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/threadplane-langgraph.mjs",
+  "typings": "types/threadplane-langgraph.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/threadplane-langgraph.d.ts",
+      "default": "./fesm2022/threadplane-langgraph.mjs"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "@threadplane/telemetry": "*"
+  },
+  "scripts": {
+    "postinstall": "threadplane-telemetry-postinstall || true"
+  }
+}

package/types/threadplane-langgraph.d.ts

@@ -0,0 +1,629 @@
+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 { 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';
+
+interface AgentLifecycle {
+    /** Epoch ms of the first stream chunk arrival. Resets on switchThread(). */
+    readonly streamStartedAt: Signal<number | null>;
+    /** Epoch ms + classification of the most recent stream error. Resets on switchThread(). */
+    readonly streamErrorAt: Signal<{
+        at: number;
+        classification: string;
+    } | null>;
+    /** Epoch ms of the first interrupt$ non-null in this stream. Resets on switchThread(). */
+    readonly interruptReceivedAt: Signal<number | null>;
+    /** Epoch ms of the most recent submit({ resume }) call. Resets on switchThread(). */
+    readonly interruptResolvedAt: Signal<number | null>;
+    /** Epoch ms when the agent's "create new thread" branch fired. Resets on switchThread(). */
+    readonly threadCreatedAt: Signal<number | null>;
+    /** Epoch ms when an existing thread was restored from server (proves persistence). Resets on switchThread(). */
+    readonly threadPersistedAt: Signal<number | null>;
+    /** Epoch ms of the first tool call append. Resets on switchThread(). */
+    readonly toolCallStartedAt: Signal<number | null>;
+    /** Epoch ms of the first tool call result transition. Resets on switchThread(). */
+    readonly toolCallCompletedAt: Signal<number | null>;
+}
+declare const AGENT_LIFECYCLE: InjectionToken<AgentLifecycle>;
+
+/**
+ * Runtime constant mirroring Angular's ResourceStatus string-union type.
+ * Angular 21 ships ResourceStatus as a pure string-union type (no runtime value),
+ * so we provide a const-object shim for code that needs runtime comparisons.
+ */
+declare const ResourceStatus: {
+    readonly Idle: "idle";
+    readonly Loading: "loading";
+    readonly Reloading: "reloading";
+    readonly Resolved: "resolved";
+    readonly Error: "error";
+    readonly Local: "local";
+};
+type ResourceStatus = ResourceStatus$1;
+/** An event emitted by a LangGraph stream. */
+interface StreamEvent {
+    /** Event type identifier (e.g., 'values', 'messages', 'error', 'interrupt'). */
+    type: 'values' | `values|${string}` | 'messages' | `messages|${string}` | `messages/${string}` | `messages/${string}|${string}` | 'updates' | `updates|${string}` | 'tools' | `tools|${string}` | 'custom' | `custom|${string}` | 'error' | `error|${string}` | 'metadata' | 'checkpoints' | `checkpoints|${string}` | 'tasks' | `tasks|${string}` | 'debug' | `debug|${string}` | 'events' | `events|${string}` | 'interrupt' | 'interrupts';
+    namespace?: string[];
+    messages?: unknown[];
+    messageMetadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Strategy for handling concurrent LangGraph runs on the same thread. */
+type LangGraphMultitaskStrategy = 'reject' | 'interrupt' | 'rollback' | 'enqueue';
+type LangGraphDurability = 'exit' | 'async' | 'sync';
+type LangGraphOnCompletion = 'complete' | 'continue';
+type LangGraphOnDisconnect = 'cancel' | 'continue';
+/** Options accepted by LangGraph-backed submit calls. */
+interface LangGraphSubmitOptions {
+    signal?: AbortSignal;
+    config?: Config;
+    context?: unknown;
+    checkpoint?: Omit<Checkpoint, 'thread_id'> | null;
+    checkpointId?: string;
+    command?: Command;
+    metadata?: Metadata;
+    checkpointDuring?: boolean;
+    durability?: LangGraphDurability;
+    interruptBefore?: '*' | string[];
+    interruptAfter?: '*' | string[];
+    onCompletion?: LangGraphOnCompletion;
+    webhook?: string;
+    onDisconnect?: LangGraphOnDisconnect;
+    afterSeconds?: number;
+    ifNotExists?: 'create' | 'reject';
+    onRunCreated?: (params: {
+        run_id: string;
+        thread_id?: string;
+    }) => void;
+    streamMode?: StreamMode[];
+    streamSubgraphs?: boolean;
+    streamResumable?: boolean;
+    feedbackKeys?: string[];
+    /** Convenience alias normalized to `command.resume` before invoking LangGraph. */
+    resume?: unknown;
+    /** Strategy for handling concurrent runs on the same thread. */
+    multitaskStrategy?: LangGraphMultitaskStrategy;
+}
+/** A queued server-side LangGraph run. */
+interface AgentQueueEntry<T = unknown> {
+    /** Server-side run ID. */
+    id: string;
+    /** Thread that owns the queued run. */
+    threadId: string;
+    /** Values submitted for the queued run. */
+    values: T | null | undefined;
+    /** Submit options used when the queued run was created. */
+    options?: LangGraphSubmitOptions;
+    /** Timestamp when the queued run was registered locally. */
+    createdAt: Date;
+}
+/** Public queue surface for pending server-side LangGraph runs. */
+interface AgentQueue<T = unknown> {
+    /** Read-only pending queue entries. */
+    readonly entries: ReadonlyArray<AgentQueueEntry<T>>;
+    /** Number of pending queue entries. */
+    readonly size: number;
+    /** Cancel a specific pending run by server run ID. */
+    cancel: (id: string) => Promise<boolean>;
+    /** Cancel all pending runs and clear the queue. */
+    clear: () => Promise<void>;
+}
+/** A checkpoint entry in the experimental branch tree. */
+interface AgentBranchTreeNode<T = unknown> {
+    type: 'node';
+    value: ThreadState<T>;
+    path: string[];
+}
+/** A branch fork where each item is an alternate checkpoint sequence. */
+interface AgentBranchTreeFork<T = unknown> {
+    type: 'fork';
+    items: AgentBranchTree<T>[];
+}
+/** Tree representation of LangGraph checkpoint history for time-travel UIs. */
+interface AgentBranchTree<T = unknown> {
+    type: 'sequence';
+    items: Array<AgentBranchTreeNode<T> | AgentBranchTreeFork<T>>;
+}
+/** A custom event emitted by the LangGraph backend via adispatch_custom_event(). */
+interface CustomStreamEvent {
+    /** Event name set by the backend (e.g., 'state_update'). */
+    name: string;
+    /** Arbitrary payload from the backend. */
+    data: unknown;
+}
+/** Transport interface for connecting to a LangGraph agent. */
+interface AgentTransport {
+    /** Open a streaming connection to an agent and yield events. */
+    stream(assistantId: string, threadId: string | null, payload: unknown, signal: AbortSignal, options?: LangGraphSubmitOptions): AsyncIterable<StreamEvent>;
+    /** Optional: join an already-started run without creating a new one. */
+    joinStream?(threadId: string, runId: string, lastEventId: string | undefined, signal: AbortSignal): AsyncIterable<StreamEvent>;
+    /** Optional: create a server-side queued run without joining it immediately. */
+    createQueuedRun?(assistantId: string, threadId: string, payload: unknown, signal: AbortSignal, options?: LangGraphSubmitOptions): Promise<AgentQueueEntry>;
+    /** Optional: cancel a server-side run. */
+    cancelRun?(threadId: string, runId: string, signal: AbortSignal): Promise<void>;
+    /** Optional: load persisted checkpoint history for a thread. */
+    getHistory?(threadId: string, signal: AbortSignal): Promise<ThreadState[]>;
+    /**
+     * Optional: update server-side thread state (e.g. to emit RemoveMessage
+     * entries for regenerate rollback). Forwards to the LangGraph
+     * `threads.updateState` API.
+     *
+     * `options.asNode` corresponds to LangGraph's `as_node` parameter — the
+     * server treats the update as if that node had just produced the values,
+     * which determines what the next pull resumes. `regenerate()` passes
+     * `asNode: '__start__'` so the next `submit(null)` resumes at the entry
+     * node and re-runs `generate` against the rolled-back state.
+     */
+    updateState?(threadId: string, values: Record<string, unknown>, signal: AbortSignal, options?: {
+        asNode?: string;
+    }): Promise<void>;
+}
+/** Options for creating a LangGraph-backed agent via {@link agent}. */
+interface AgentOptions<T, _ResolvedBag extends BagTemplate> {
+    /** Base URL of the LangGraph Platform API. Defaults to `provideAgent({ apiUrl })` when omitted. */
+    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 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[];
+}
+/** Reference to a subagent's streaming state. */
+interface SubagentStreamRef {
+    /** The tool call ID that spawned this subagent. */
+    toolCallId: string;
+    /** Optional human-readable subagent type/name. */
+    name?: string;
+    /** Current execution status of the subagent. */
+    status: Signal<'pending' | 'running' | 'complete' | 'error'>;
+    /** Current state values from the subagent. */
+    values: Signal<Record<string, unknown>>;
+    /** Messages from the subagent conversation. */
+    messages: Signal<BaseMessage[]>;
+}
+/**
+ * Unified LangGraph agent surface returned by `agent({...})`.
+ *
+ * Extends the runtime-neutral `AgentWithHistory` contract (chat-consumable)
+ * with the full LangGraph-specific API. One object drives both `<chat>` and
+ * 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 {
+    /** Raw LangChain BaseMessage list. Use `messages` for chat rendering. */
+    langGraphMessages: Signal<BaseMessage[]>;
+    /** All interrupts received during the current run (raw LangGraph shape). */
+    langGraphInterrupts: Signal<Interrupt<ResolvedBag['InterruptType']>[]>;
+    /** Raw LangGraph tool calls (with run-state). Use `toolCalls` for chat rendering. */
+    langGraphToolCalls: Signal<ToolCallWithResult[]>;
+    /** Raw LangGraph history (ThreadState[]). Use `history` for AgentCheckpoint[]. */
+    langGraphHistory: Signal<ThreadState<T>[]>;
+    /** Experimental branch tree derived from LangGraph checkpoint history. */
+    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>;
+    /** 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. */
+    hasValue: Signal<boolean>;
+    /** Re-submit the last input to restart the stream. */
+    reload: () => void;
+    /**
+     * Discards the assistant message at the given index AND all messages after
+     * it, then re-runs the agent against the trimmed conversation tail. The
+     * preceding user message (at index - 1) is preserved and re-submitted as
+     * the agent's input. No new user message is added to the history.
+     *
+     * Throws if the message at `index` is not 'assistant' role, or if the
+     * agent is currently loading another response.
+     */
+    regenerate: (assistantMessageIndex: number) => Promise<void>;
+    /** Progress updates for currently executing tools. */
+    toolProgress: Signal<ToolProgress[]>;
+    /** Pending server-side runs created via `multitaskStrategy: 'enqueue'`. */
+    queue: Signal<AgentQueue>;
+    /** Filtered list of subagents with status 'running'. */
+    activeSubagents: Signal<SubagentStreamRef[]>;
+    /** Get a subagent stream by the tool call ID that spawned it. */
+    getSubagent: (toolCallId: string) => SubagentStreamRef | undefined;
+    /** Get subagent streams by their configured subagent type/name. */
+    getSubagentsByType: (type: string) => SubagentStreamRef[];
+    /** Get subagent streams spawned by the tool calls on a specific AI message. */
+    getSubagentsByMessage: (msg: AIMessage) => SubagentStreamRef[];
+    /** Raw custom events stream (signal of array). The runtime-neutral
+     *  `events$` Observable is derived from this. */
+    customEvents: Signal<CustomStreamEvent[]>;
+    /** Current branch identifier for time-travel navigation. */
+    branch: Signal<string>;
+    /** Set the active branch for time-travel navigation. */
+    setBranch: (branch: string) => void;
+    /** True while a thread switch is loading state from the server. */
+    isThreadLoading: Signal<boolean>;
+    /** Switch to a different thread, resetting derived state. */
+    switchThread: (threadId: string | null) => void;
+    /** Join an already-running stream by run ID. */
+    joinStream: (runId: string, lastEventId?: string) => Promise<void>;
+    /** Get metadata for a specific message by index. */
+    getMessagesMetadata: (msg: BaseMessage, idx?: number) => MessageMetadata<Record<string, unknown>> | undefined;
+    /** Get tool call results associated with an AI message (LangGraph types). */
+    getToolCalls: (msg: AIMessage) => ToolCallWithResult[];
+    /**
+     * Lifecycle signals for observability/telemetry. Eight read-only signals
+     * capture key transitions (first stream chunk, first interrupt, tool
+     * call start/complete, thread create/persist, errors). All reset on
+     * `switchThread()`. See {@link AgentLifecycle}.
+     */
+    lifecycle: AgentLifecycle;
+}
+
+/**
+ * Creates a LangGraph-backed Angular agent.
+ *
+ * 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.
+ *
+ * @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
+ *
+ * @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),
+ * });
+ *
+ * // Access signals in template
+ * // chat.messages(), chat.status(), chat.error()
+ * ```
+ */
+declare function agent<T = Record<string, unknown>, Bag extends BagTemplate = BagTemplate>(options: AgentOptions<T, InferBag<T, Bag>>): LangGraphAgent<T, InferBag<T, Bag>>;
+
+/**
+ * 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.
+ */
+declare function provideAgent(config: AgentConfig): Provider;
+
+/**
+ * Optional registry that collects per-instance agent lifecycles within
+ * an Angular injection context. External instrumentation packages
+ * (e.g. cockpit-telemetry) provide this token and read from it.
+ *
+ * `@threadplane/langgraph` does NOT provide this itself — `agent()` writes to
+ * the registry only when an external consumer has provided it.
+ */
+declare class AgentLifecycleRegistry {
+    private readonly _lifecycles;
+    /** Reactive list of registered lifecycles. */
+    readonly lifecycles: Signal<readonly AgentLifecycle[]>;
+    register(lifecycle: AgentLifecycle): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AgentLifecycleRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AgentLifecycleRegistry>;
+}
+
+/**
+ * Test transport for deterministic agent testing without a real LangGraph server.
+ *
+ * Script event batches upfront, then emit them manually or step through them
+ * in your test specs. Supports error injection and close control.
+ *
+ * @example
+ * ```typescript
+ * const transport = new MockAgentTransport([
+ *   [{ type: 'values', messages: [aiMsg('Hello')] }],
+ *   [{ type: 'values', messages: [aiMsg('Done')] }],
+ * ]);
+ * ```
+ */
+declare class MockAgentTransport implements AgentTransport {
+    history: ThreadState[];
+    readonly historyCalls: string[];
+    readonly streams: Array<{
+        threadId: string | null;
+        payload: unknown;
+        options?: LangGraphSubmitOptions;
+    }>;
+    readonly createdQueuedRuns: AgentQueueEntry[];
+    readonly cancelledRuns: Array<{
+        threadId: string;
+        runId: string;
+    }>;
+    readonly joinedRuns: Array<{
+        threadId: string;
+        runId: string;
+    }>;
+    private script;
+    private scriptIndex;
+    private streaming;
+    private eventQueue;
+    private resolvers;
+    private closed;
+    private pendingError;
+    /** @param script - Array of event batches. Each batch is emitted as a group. */
+    constructor(script?: StreamEvent[][]);
+    /** Advance to the next scripted batch. Pass the returned events to `emit()`. */
+    nextBatch(): StreamEvent[];
+    /** Manually emit events into the stream. */
+    emit(events: StreamEvent[]): void;
+    /** Inject an error into the stream. */
+    emitError(err: Error): void;
+    /** Close the stream. Remaining queued events are drained before completion. */
+    close(): void;
+    /** Returns true if a stream is currently active. */
+    isStreaming(): boolean;
+    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(threadId: string, runId: string, lastEventId: string | undefined, signal: AbortSignal): AsyncIterable<StreamEvent>;
+    private flush;
+}
+
+/**
+ * Production transport that connects to a LangGraph Platform API via HTTP and SSE.
+ *
+ * Creates threads automatically if no threadId is provided, and streams events
+ * using the LangGraph SDK client.
+ *
+ * @example
+ * ```typescript
+ * const transport = new FetchStreamTransport(
+ *   'http://localhost:2024',
+ *   (id) => console.log('New thread:', id),
+ * );
+ * ```
+ */
+declare class FetchStreamTransport implements AgentTransport {
+    private client;
+    private onThreadId?;
+    /**
+     * @param apiUrl - Base URL of the LangGraph Platform API
+     * @param onThreadId - Optional callback invoked when a new thread is created
+     */
+    constructor(apiUrl: string, onThreadId?: (id: string) => void);
+    /** 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. */
+    joinStream(threadId: string, runId: string, lastEventId: string | undefined, signal: AbortSignal): AsyncIterable<StreamEvent>;
+    /** Create a pending server-side run using LangGraph's enqueue strategy. */
+    createQueuedRun(assistantId: string, threadId: string, payload: unknown, signal: AbortSignal, options?: LangGraphSubmitOptions): Promise<AgentQueueEntry>;
+    /** Cancel a server-side run. */
+    cancelRun(threadId: string, runId: string, signal: AbortSignal): Promise<void>;
+    /** Load persisted checkpoint history for a thread. */
+    getHistory(threadId: string, signal: AbortSignal): Promise<ThreadState[]>;
+    /** Update server-side thread state, e.g. to remove messages for regenerate rollback. */
+    updateState(threadId: string, values: Record<string, unknown>, _signal: AbortSignal, options?: {
+        asNode?: string;
+    }): Promise<void>;
+}
+
+/**
+ * A LangGraphAgent mock with writable signals for easy test control.
+ *
+ * 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>;
+    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.
+ */
+declare function mockLangGraphAgent(initial?: {
+    messages?: Message[];
+    langGraphMessages?: BaseMessage[];
+    status?: AgentStatus;
+    isLoading?: boolean;
+    error?: unknown;
+    hasValue?: boolean;
+    isThreadLoading?: boolean;
+}): MockLangGraphAgent;
+
+interface KwargsLike {
+    additional_kwargs?: Record<string, unknown> | undefined;
+}
+declare function extractCitations(msg: KwargsLike): Citation[] | undefined;
+
+/**
+ * Construct a LangGraph SDK Client that accepts both absolute URLs
+ * (`http://localhost:2024`) and relative `/api`-style paths that get
+ * proxied by middleware in production. The SDK itself rejects
+ * relative URLs, so this helper rewrites them against
+ * `window.location.origin` when running in the browser.
+ *
+ * Single source of truth for the absolute-URL rewrite — the streaming
+ * transport (`fetch-stream.transport.ts`) and the threads adapter
+ * (`LangGraphThreadsAdapter`) both go through here.
+ *
+ * @example
+ * ```ts
+ * const client = createLangGraphClient(environment.langGraphApiUrl);
+ * const threads = await client.threads.search({ limit: 50 });
+ * ```
+ */
+declare function createLangGraphClient(apiUrl: string): Client;
+/** Exported separately so non-Client callers (e.g. raw fetch) can
+ *  share the same normalization logic. */
+declare function toAbsoluteApiUrl(apiUrl: string): string;
+
+/**
+ * Configuration consumed by {@link LangGraphThreadsAdapter}. Provide
+ * via {@link LANGGRAPH_THREADS_CONFIG} (typically in app.config.ts):
+ *
+ * ```ts
+ * providers: [
+ *   { provide: LANGGRAPH_THREADS_CONFIG, useValue: {
+ *       apiUrl: environment.langGraphApiUrl,
+ *   }},
+ * ],
+ * ```
+ *
+ * The adapter expects backends to write the thread title to
+ * `metadata.title`. Spec 2026-05-19-llm-generated-labels-design.md
+ * originally proposed `metadata.thread_title` for cockpit caps but
+ * we converged on `title` to match the canonical demo and avoid a
+ * per-cap configuration knob.
+ */
+interface LangGraphThreadsConfig {
+    /** Base URL for the LangGraph Platform API. Accepts both absolute
+     *  URLs and relative `/api`-style paths. */
+    apiUrl: string;
+    /** Fallback label for threads whose title hasn't been written yet
+     *  (e.g. created but never sent). Defaults to `'Untitled'`. */
+    titleFallback?: string;
+}
+declare const LANGGRAPH_THREADS_CONFIG: InjectionToken<LangGraphThreadsConfig>;
+/** Optional adapter clients can pass an explicit Client (e.g. for
+ *  testing). When omitted, the adapter constructs one via
+ *  {@link createLangGraphClient}. */
+declare const LANGGRAPH_CLIENT: InjectionToken<Client<_langchain_langgraph_sdk.DefaultValues, _langchain_langgraph_sdk.DefaultValues, unknown>>;
+/**
+ * SDK-backed thread store. Wraps `client.threads.*` and maps SDK
+ * threads to the framework's {@link Thread} type for direct use with
+ * `<chat-thread-list>` / `<chat-sidenav>`.
+ *
+ * Consumers wire the framework's `ThreadActionAdapter` to instance
+ * methods (rename/delete/archive/pin/...) so the right-click menu
+ * round-trips through the LangGraph SDK without per-app boilerplate.
+ *
+ * @example
+ * ```ts
+ * const svc = inject(LangGraphThreadsAdapter);
+ * const actions: ThreadActionAdapter = {
+ *   rename: (id, t) => svc.rename(id, t),
+ *   delete: (id) => svc.delete(id),
+ * };
+ * ```
+ */
+declare class LangGraphThreadsAdapter {
+    private readonly config;
+    private readonly client;
+    private readonly fallback;
+    private readonly _threads;
+    private readonly _archived;
+    /** Active (non-archived) threads, sorted with pinned first. */
+    readonly threads: Signal<Thread[]>;
+    /** Threads whose `metadata.archived === true`. */
+    readonly archivedThreads: Signal<Thread[]>;
+    /** Fetch the latest thread list from the server. Failures are
+     *  logged via `console.error` (not swallowed silently — silent
+     *  catches have masked prod issues in the past).
+     *
+     *  Invocation and resolution are logged at `console.debug` so prod
+     *  inspection can distinguish "never called" from "called but
+     *  resolved empty" from "called and threw." This was prompted by a
+     *  demo.threadplane.ai cold-load bug where the sidenav stayed empty
+     *  with no visible signal. Tighten the log volume if it becomes
+     *  noisy. */
+    refresh(): Promise<void>;
+    /** Fetch a single thread by id. Returns `null` when the server
+     *  returns 404 (thread doesn't exist) so callers can distinguish
+     *  "missing" from "couldn't reach the server" — genuine network
+     *  errors rethrow. Used by URL-based thread routing to validate a
+     *  pasted/shared thread id before activating it. */
+    getThread(threadId: string): Promise<Thread | null>;
+    create(metadata?: Record<string, unknown>): Promise<string | null>;
+    delete(threadId: string): Promise<void>;
+    rename(threadId: string, newTitle: string): Promise<void>;
+    archive(threadId: string): Promise<void>;
+    unarchive(threadId: string): Promise<void>;
+    pin(threadId: string): Promise<void>;
+    unpin(threadId: string): Promise<void>;
+    moveToProject(threadId: string, projectId: string | null): Promise<void>;
+    /** Re-stamp `metadata.pinnedOrder = 0,1,2,...` for the pinned slice
+     *  to reflect the new ordering. */
+    reorderPinned(threadId: string, beforeId: string | null): Promise<void>;
+    private toThread;
+    static ɵfac: i0.ɵɵFactoryDeclaration<LangGraphThreadsAdapter, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<LangGraphThreadsAdapter>;
+}
+
+/**
+ * Call `fn` whenever the agent's status transitions out of `'running'`
+ * (i.e. when a run completes — success, error, or interrupt). Useful
+ * for refreshing thread lists, telemetry, or any other state that
+ * lags the agent.
+ *
+ * Must be called within an injection context (constructor or
+ * `runInInjectionContext`) — uses Angular's `effect` under the hood.
+ *
+ * @example
+ * ```ts
+ * constructor() {
+ *   refreshOnRunEnd(this.agent, () => this.threads.refresh());
+ * }
+ * ```
+ */
+declare function refreshOnRunEnd(agent: LangGraphAgent, fn: () => void | Promise<void>): void;
+/**
+ * Call `fn` whenever any of the watched signals transitions from a
+ * truthy "active" value to a non-active value. Generic version of
+ * {@link refreshOnRunEnd} for callers tracking custom state machines.
+ *
+ * Must be called within an injection context.
+ */
+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 };