@threadplane/langgraph 0.0.49 → 0.0.51

package/fesm2022/threadplane-langgraph.mjs

@@ -1,11 +1,11 @@
 import * as i0 from '@angular/core';
-import { signal, Injectable, inject, DestroyRef, isSignal, computed, effect, InjectionToken } from '@angular/core';
+import { signal, Injectable, InjectionToken, computed, inject, DestroyRef, isSignal, effect } from '@angular/core';
 import { toObservable, toSignal } from '@angular/core/rxjs-interop';
 import { takeUntil, Subject, BehaviorSubject, of, throttleTime, asyncScheduler } from 'rxjs';
 import { takeUntil as takeUntil$1 } from 'rxjs/operators';
 import { Client } from '@langchain/langgraph-sdk';
 import { getToolCallsWithResults } from '@langchain/langgraph-sdk/utils';
-import { mockAgent } from '@threadplane/chat';
+import { toAgentError, isAbortError, AgentError, AGENT_ERROR_MESSAGES, mockAgent } from '@threadplane/chat';
 
 // SPDX-License-Identifier: MIT
 /**
@@ -56,14 +56,26 @@ const ResourceStatus = {
  * 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 });
  * ```
  */
-function createLangGraphClient(apiUrl) {
-    return new Client({ apiUrl: toAbsoluteApiUrl(apiUrl) });
+function createLangGraphClient(apiUrl, clientOptions) {
+    return new Client({
+        apiUrl: toAbsoluteApiUrl(apiUrl),
+        ...(clientOptions?.maxRetries !== undefined
+            ? { callerOptions: { maxRetries: clientOptions.maxRetries } }
+            : {}),
+    });
 }
 /** Exported separately so non-Client callers (e.g. raw fetch) can
  *  share the same normalization logic. */
@@ -93,12 +105,13 @@ class FetchStreamTransport {
     /**
      * @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, onThreadId) {
+    constructor(apiUrl, onThreadId, clientOptions) {
         // createLangGraphClient handles the absolute-URL normalization
         // required by the SDK when `apiUrl` is a relative `/api`-style
         // path proxied by middleware in production.
-        this.client = createLangGraphClient(apiUrl);
+        this.client = createLangGraphClient(apiUrl, clientOptions);
         this.onThreadId = onThreadId;
     }
     /** Open a streaming connection, creating a thread if needed. */
@@ -517,13 +530,15 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         currentThreadId = id;
         userOnThreadId?.(id);
     };
-    const transport = options.transport ?? new FetchStreamTransport(options.apiUrl, wrappedOnThreadId);
+    const transport = options.transport ?? new FetchStreamTransport(options.apiUrl, wrappedOnThreadId, options.clientOptions);
     let currentThreadId = null;
     let lastPayload = null;
     let lastOptions;
     let abortController = null;
     let historyAbortController = null;
     let hasSeenThreadId = false;
+    /** True when the current abort was user-initiated (via stop()). Reset at the start of every new runStream(). */
+    let userAbortRequested = false;
     const toolProgressMap = new Map();
     const queuedRuns = [];
     let drainingQueue = false;
@@ -557,7 +572,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         subjects.toolCalls$.next([]);
         subjects.messageMetadata$.next(new Map());
         subjects.subagents$.next(new Map());
-        void cancelQueueEntries(takeQueuedRuns()).catch(err => subjects.error$.next(err));
+        void cancelQueueEntries(takeQueuedRuns()).catch(err => subjects.error$.next(toAgentError(err)));
         publishQueue();
         subjects.custom$.next([]);
         subjects.isThreadLoading$.next(false);
@@ -634,7 +649,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         }
         catch (err) {
             if (!controller.signal.aborted && err?.name !== 'AbortError') {
-                subjects.error$.next(err);
+                subjects.error$.next(toAgentError(err));
             }
         }
         finally {
@@ -746,7 +761,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
             }
         }
         catch (err) {
-            subjects.error$.next(err);
+            subjects.error$.next(toAgentError(err));
             subjects.status$.next(ResourceStatus.Error);
             captureAgentRuntimeTelemetry(options.telemetry, 'ngaf:stream_errored', {
                 ...telemetryProperties,
@@ -758,6 +773,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
     async function runStream(payload, opts, requestType = 'submit') {
         abortController?.abort();
         abortController = new AbortController();
+        userAbortRequested = false;
         const startedAt = Date.now();
         captureRuntimeRequestTelemetry(requestType);
         captureAgentRuntimeTelemetry(options.telemetry, 'ngaf:stream_started', telemetryProperties);
@@ -768,6 +784,10 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         toolProgressMap.clear();
         lastPayload = payload;
         lastOptions = opts;
+        // Tracks whether at least one stream event has been processed this run.
+        // Used to distinguish a mid-stream network interruption (kind:'interrupted')
+        // from a fresh connect failure (falls through to toAgentError classification).
+        let streamingStarted = false;
         // Optimistically inject human messages so they appear immediately
         // without waiting for the server to echo them back. Assign a stable id
         // when missing — track-by-id in the chat-message-list relies on stable
@@ -791,6 +811,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
             for await (const event of iter) {
                 if (abortController.signal.aborted)
                     break;
+                streamingStarted = true;
                 processEvent(event);
             }
             if (!abortController.signal.aborted) {
@@ -806,11 +827,26 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
             }
         }
         catch (err) {
-            if (err?.name === 'AbortError') {
-                subjects.status$.next(ResourceStatus.Resolved);
+            if (isAbortError(err) && userAbortRequested) {
+                // User explicitly called stop() — treat as graceful idle, not an error.
+                subjects.status$.next(ResourceStatus.Idle);
+            }
+            else if (isAbortError(err)) {
+                // A non-user-requested abort: interrupted if a stream had started, else a
+                // connect-phase failure. Never "aborted" (that's reserved for user stop).
+                const e = streamingStarted
+                    ? new AgentError({ kind: 'interrupted', message: AGENT_ERROR_MESSAGES.interrupted, retryable: true, cause: err })
+                    : new AgentError({ kind: 'connection', message: AGENT_ERROR_MESSAGES.connection, retryable: true, cause: err });
+                subjects.error$.next(e);
+                subjects.status$.next(ResourceStatus.Error);
+                captureAgentRuntimeTelemetry(options.telemetry, 'ngaf:stream_errored', {
+                    ...telemetryProperties,
+                    durationMs: Date.now() - startedAt,
+                    errorClass: agentRuntimeTelemetryErrorClass(err),
+                });
             }
             else {
-                subjects.error$.next(err);
+                subjects.error$.next(toAgentError(err));
                 subjects.status$.next(ResourceStatus.Error);
                 captureAgentRuntimeTelemetry(options.telemetry, 'ngaf:stream_errored', {
                     ...telemetryProperties,
@@ -945,7 +981,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
                 break;
             }
             case 'error':
-                subjects.error$.next(event['error']);
+                subjects.error$.next(toAgentError(event['error']));
                 subjects.status$.next(ResourceStatus.Error);
                 break;
             case 'interrupt':
@@ -1089,9 +1125,16 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
             await runStream(payload, opts);
         },
         stop: async () => {
+            userAbortRequested = true;
             abortController?.abort();
             await clearQueue();
-            subjects.status$.next(ResourceStatus.Resolved);
+            // Note: status is set to Idle by the runStream() catch when it sees
+            // isAbortError && userAbortRequested. The explicit set here handles
+            // the case where stop() is called when no stream is active (so the
+            // catch never fires) or when clearQueue() raised an error.
+            if (subjects.status$.value !== ResourceStatus.Idle) {
+                subjects.status$.next(ResourceStatus.Idle);
+            }
         },
         switchThread: (id) => {
             setThreadId(id, true);
@@ -1123,7 +1166,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
                 });
             }
             catch (err) {
-                subjects.error$.next(err);
+                subjects.error$.next(toAgentError(err));
                 subjects.status$.next(ResourceStatus.Error);
                 captureAgentRuntimeTelemetry(options.telemetry, 'ngaf:stream_errored', {
                     ...telemetryProperties,
@@ -1696,6 +1739,29 @@ const _internalsForTesting = {
     isFinalCanonicalReasoningContent,
 };
 
+// SPDX-License-Identifier: MIT
+/**
+ * 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.
+ */
+const LANGGRAPH_CLIENT_OPTIONS = new InjectionToken('LANGGRAPH_CLIENT_OPTIONS');
+/**
+ * First-defined-wins resolution across precedence layers (highest first).
+ * Whole-object semantics — no per-field merge — so the winning layer is the
+ * single source for every option. Returns undefined when all layers are absent.
+ */
+function resolveClientOptions(...layers) {
+    for (const layer of layers) {
+        if (layer)
+            return layer;
+    }
+    return undefined;
+}
+
 const ROOT_ID = '$';
 /**
  * Builds a branch-aware checkpoint tree from LangGraph thread history.
@@ -1826,6 +1892,124 @@ function normalizeCitation(entry, fallbackIndex) {
     };
 }
 
+// SPDX-License-Identifier: MIT
+/** Serialize a tool result value to a string for the ToolMessage content. */
+function safeStringify(v) {
+    return typeof v === 'string' ? v : JSON.stringify(v);
+}
+/**
+ * Merge client_tools into a run payload.
+ *
+ * If payload is null we keep it null — a null payload signals a no-input
+ * resume (used by regenerate and command resumes) and the server must
+ * receive null, not an object. The catalog can only be injected when the
+ * payload is a plain object that the graph's add_messages reducer can
+ * process; it cannot be injected into a command-resume (null payload) or
+ * into an already-typed non-record payload.
+ *
+ * Returns a new object; never mutates the original.
+ */
+function mergeClientTools(payload, catalog) {
+    if (catalog.length === 0)
+        return payload;
+    if (payload === null || payload === undefined)
+        return payload;
+    if (typeof payload !== 'object' || Array.isArray(payload))
+        return payload;
+    return { ...payload, client_tools: catalog };
+}
+/**
+ * Creates a ClientToolsCapability backed by a LangGraph submit function and
+ * a store of tool-call signals. Extracted into a factory so it can be
+ * unit-tested in isolation without standing up a full Angular DI environment.
+ *
+ * The capability:
+ *  - Maintains a catalog of client tool specs (setCatalog). The caller
+ *    is responsible for threading the catalog into every run payload via
+ *    mergeClientTools() before calling manager.submit — see agent.fn.ts.
+ *  - Exposes a `pending` computed signal: tool calls whose name is in the
+ *    catalog, have no backend result, and haven't been resolved client-side
+ *    yet — but ONLY when the run is not in progress (isLoading===false).
+ *    The backend ends the run without emitting a ToolMessage result for
+ *    client tools, so `result` stays undefined on those entries.
+ *  - resolve(id, result): marks the call as resolved, then issues a NEW
+ *    run on the SAME thread by calling submitFn with:
+ *      input: {
+ *        messages: [{ type: 'tool', role: 'tool', tool_call_id: id, content }],
+ *        client_tools: catalog(),
+ *      }
+ *    The `add_messages` reducer on the Python side appends the ToolMessage
+ *    to thread state. Including `client_tools` ensures the model sees the
+ *    full tool catalog on the continuation run.
+ *
+ * Catalog shipping: the catalog is NOT injected by this factory's
+ * submitFn call in resolve() — the resolved-tool run builds the payload
+ * directly. For normal submit/regenerate runs, the agent.fn.ts wrapper
+ * uses mergeClientTools() to inject `client_tools` into the payload
+ * before forwarding to manager.submit. This keeps injection concerns
+ * co-located with the run-issuing call sites.
+ */
+function createClientToolsCapability(submitFn, store) {
+    const catalog = signal([], ...(ngDevMode ? [{ debugName: "catalog" }] : []));
+    const resolvedIds = signal(new Set(), ...(ngDevMode ? [{ debugName: "resolvedIds" }] : []));
+    const pending = computed(() => {
+        // Client tools are only actionable after the run ends (the backend
+        // signals this by ending the run WITHOUT emitting a ToolMessage result
+        // for client tools).
+        if (store.isLoading())
+            return [];
+        const names = new Set(catalog().map((s) => s.name));
+        const done = resolvedIds();
+        return store.toolCalls().filter((tc) => names.has(tc.name) && tc.result === undefined && !done.has(tc.id));
+    }, ...(ngDevMode ? [{ debugName: "pending" }] : []));
+    const capability = {
+        catalog,
+        setCatalog(specs) {
+            catalog.set([...specs]);
+        },
+        pending,
+        resolve(id, result) {
+            // Mark as resolved first so pending() drops it immediately.
+            resolvedIds.update((s) => new Set(s).add(id));
+            // Cast rather than rely on discriminant narrowing: consumer apps that
+            // compile this source with `strictNullChecks: false` don't narrow the
+            // ClientToolResult union in a ternary.
+            const ok = result.ok;
+            const value = result.value;
+            const error = result.error;
+            // Write the outcome onto the LOCAL ToolCall (via the adapter's override
+            // layer). The client tool DID produce a result client-side, so this is
+            // semantically correct — and it freezes the transcript card: the mounted
+            // ask component re-renders with its own emitted value as props and can
+            // branch to a resolved/frozen state. Without this, the LOCAL tool call
+            // never gets a result (only the backend ToolMessage does) so the card
+            // stays interactive forever.
+            store.applyClientResult(id, {
+                result: ok ? value : { error },
+                ...(ok ? {} : { error, status: 'error' }),
+            });
+            const content = ok
+                ? safeStringify(value)
+                : `Error: ${error}`;
+            // Issue a new run on the same thread. LangGraph's add_messages reducer
+            // appends the ToolMessage to the thread state. `client_tools` is
+            // included so the model sees the full tool catalog on the continuation.
+            //
+            // Message shape: both `type` and `role` are set for compatibility —
+            // the LangGraph server's add_messages coercion reads `role` (Python
+            // side), while the bridge's local optimistic-message path reads `type`
+            // (via toMessage's normalizeMessageType). This mirrors the human-message
+            // shape used in buildSubmitUpdate (agent.fn.ts line 732).
+            const toolPayload = {
+                messages: [{ type: 'tool', role: 'tool', tool_call_id: id, content }],
+                client_tools: catalog(),
+            };
+            void submitFn(toolPayload);
+        },
+    };
+    return capability;
+}
+
 // SPDX-License-Identifier: MIT
 /**
  * Walk LangGraph history (newest-first) and pair each AIMessage id with
@@ -1899,11 +2083,15 @@ function agent(options) {
     // Injection context required
     const destroyRef = inject(DestroyRef);
     const globalConfig = inject(AGENT_CONFIG, { optional: true });
+    const sharedClientOptions = inject(LANGGRAPH_CLIENT_OPTIONS, { optional: true });
     const destroy$ = new Subject();
     destroyRef.onDestroy(() => { destroy$.next(); destroy$.complete(); });
     // Merge: call-site options take precedence over global provider config
     const apiUrl = options.apiUrl ?? globalConfig?.apiUrl ?? '';
     const transport = options.transport ?? globalConfig?.transport;
+    // clientOptions precedence: agent({...}) call-site → provideAgent config →
+    // app-wide LANGGRAPH_CLIENT_OPTIONS token → SDK default.
+    const clientOptions = resolveClientOptions(options.clientOptions, globalConfig?.clientOptions, sharedClientOptions);
     const init = (options.initialValues ?? {});
     // All subjects created before the bridge
     const status$ = new BehaviorSubject(ResourceStatus.Idle);
@@ -2039,7 +2227,7 @@ function agent(options) {
             lcThreadPersistedAt.set(Date.now());
     });
     const manager = createStreamManagerBridge({
-        options: { ...options, apiUrl, transport },
+        options: { ...options, apiUrl, transport, clientOptions },
         subjects,
         threadId$,
         destroy$: destroy$.asObservable(),
@@ -2060,6 +2248,9 @@ function agent(options) {
     // CD anyway.
     const rawMessages = toSignal(messages$, { initialValue: [] });
     const statusSig = toSignal(status$, { initialValue: ResourceStatus.Idle });
+    // Cast justified: error$ accepts only AgentError | undefined (bridge catch normalizes all errors via
+    // toAgentError before calling next(); resetDerivedThreadState passes undefined). The BehaviorSubject
+    // is typed unknown to satisfy StreamSubjects<unknown> invariance at the subjects-bag assignment.
     const errorSig = toSignal(error$, { initialValue: undefined });
     const hasValueSig = toSignal(hasValue$, { initialValue: false });
     const interruptSig = toSignal(interrupt$, { initialValue: undefined });
@@ -2083,7 +2274,21 @@ function agent(options) {
     // updates per token. DOM stability is provided by `track message.id`
     // in chat-message-list, not by Message identity.
     const messagesNeutral = computed(() => rawMessages().map((m) => toMessage(m, manager.getReasoningDurationMs)), ...(ngDevMode ? [{ debugName: "messagesNeutral" }] : []));
-    const toolCallsNeutral = computed(() => rawToolCalls().map(toToolCall), ...(ngDevMode ? [{ debugName: "toolCallsNeutral" }] : []));
+    // Client-tool resolutions written client-side. The raw `toolCalls$` stream
+    // (and thus `rawToolCalls`) only ever carries backend results — a resolved
+    // client tool (`ask`/`view`) never receives a backend ToolMessage on its
+    // LOCAL call. These overrides layer the client-side outcome over the raw
+    // projection so the transcript card can freeze (see chat-tool-views
+    // toToolViewSpec, which spreads `result` into the mounted component's props).
+    const clientResultOverrides = signal(new Map(), ...(ngDevMode ? [{ debugName: "clientResultOverrides" }] : []));
+    const toolCallsNeutral = computed(() => {
+        const overrides = clientResultOverrides();
+        return rawToolCalls().map((tc) => {
+            const neutral = toToolCall(tc);
+            const patch = overrides.get(neutral.id);
+            return patch ? { ...neutral, ...patch } : neutral;
+        });
+    }, ...(ngDevMode ? [{ debugName: "toolCallsNeutral" }] : []));
     const statusNeutral = computed(() => mapStatus(statusSig()), ...(ngDevMode ? [{ debugName: "statusNeutral" }] : []));
     const stateNeutral = computed(() => {
         const v = value();
@@ -2102,6 +2307,16 @@ function agent(options) {
     const messageCheckpointsSig = computed(() => computeMessageCheckpoints(historySig()), ...(ngDevMode ? [{ debugName: "messageCheckpointsSig" }] : []));
     const experimentalBranchTree = computed(() => buildBranchTree(historySig()), ...(ngDevMode ? [{ debugName: "experimentalBranchTree" }] : []));
     const events$ = buildEvents$(customSig);
+    // ── Client tools capability ──────────────────────────────────────────────
+    // The capability takes a direct reference to manager.submit so it can issue
+    // follow-up runs (resolve) without going through the full submit() wrapper.
+    // The catalog is injected into every outbound payload via mergeClientTools()
+    // in the submit wrapper below and in the resolve path inside the capability.
+    const clientToolsCap = createClientToolsCapability((payload, opts) => manager.submit(payload, opts), {
+        toolCalls: toolCallsNeutral,
+        isLoading,
+        applyClientResult: (id, patch) => clientResultOverrides.update((m) => new Map(m).set(id, patch)),
+    });
     return {
         // ── Runtime-neutral surface (AgentWithHistory) ────────────────────────
         messages: messagesNeutral,
@@ -2125,9 +2340,20 @@ function agent(options) {
                 lcInterruptResolvedAt.set(Date.now());
             }
             const request = buildSubmitRequest(input, opts);
-            return manager.submit(request.payload, request.options);
+            // Thread the client-tools catalog into every outbound payload so the
+            // backend middleware can merge them into the model's tool list. Null
+            // payloads (regenerate re-runs, command resumes) are left unchanged.
+            const payload = mergeClientTools(request.payload, clientToolsCap.catalog());
+            return manager.submit(payload, request.options);
         },
         stop: () => manager.stop(),
+        retry: async () => {
+            if (isLoading())
+                return; // no-op while a run is in flight
+            error$.next(undefined); // clear the error before re-running
+            await manager.resubmitLast();
+        },
+        clientTools: clientToolsCap,
         regenerate: async (assistantMessageIndex) => {
             if (isLoading()) {
                 throw new Error('Cannot regenerate while agent is loading another response');
@@ -2468,80 +2694,53 @@ const AGENT_CONFIG = new InjectionToken('AGENT_CONFIG');
  * @internal — exported for spec access only. Consumers must use `injectAgent()`.
  */
 const AGENT = new InjectionToken('AGENT');
-/**
- * Wire the LangGraph adapter into Angular's dependency injection.
- *
- * 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.
- *
- * 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.
- *
- * **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:
- *
- * ```ts
- * providers: [
- *   provideAgent(() => {
- *     const route = inject(ActivatedRoute);
- *     return { assistantId: 'chat', threadId: toSignal(route.paramMap) };
- *   }),
- * ];
- * ```
- */
-function provideAgent(configOrFactory) {
+/** @internal — shared factory that reads AGENT_CONFIG and constructs the singleton. */
+function agentFactory() {
+    // useFactory runs in an injection context, so the legacy `agent()`
+    // factory's `inject(DestroyRef)` calls work.
+    const config = inject(AGENT_CONFIG);
+    if (config.assistantId === undefined) {
+        throw new Error('provideAgent: `assistantId` is required to construct the AGENT singleton.');
+    }
+    return agent({
+        assistantId: config.assistantId,
+        ...(config.apiUrl !== undefined ? { apiUrl: config.apiUrl } : {}),
+        ...(config.threadId !== undefined ? { threadId: config.threadId } : {}),
+        ...(config.onThreadId !== undefined ? { onThreadId: config.onThreadId } : {}),
+        ...(config.initialValues !== undefined ? { initialValues: config.initialValues } : {}),
+        ...(config.throttle !== undefined ? { throttle: config.throttle } : {}),
+        ...(config.toMessage !== undefined ? { toMessage: config.toMessage } : {}),
+        ...(config.transport !== undefined ? { transport: config.transport } : {}),
+        ...(config.clientOptions !== undefined ? { clientOptions: config.clientOptions } : {}),
+        ...(config.telemetry !== undefined ? { telemetry: config.telemetry } : {}),
+        ...(config.filterSubagentMessages !== undefined ? { filterSubagentMessages: config.filterSubagentMessages } : {}),
+        ...(config.subagentToolNames !== undefined ? { subagentToolNames: config.subagentToolNames } : {}),
+    });
+}
+function isAgentRef(x) {
+    return typeof x === 'object' && x !== null && 'token' in x;
+}
+function provideAgent(refOrConfig, maybeConfig) {
+    const ref = isAgentRef(refOrConfig) ? refOrConfig : undefined;
+    const configOrFactory = (ref ? maybeConfig : refOrConfig);
     // Resolve the factory (if any) lazily, inside the injection context of the
     // AGENT_CONFIG useFactory below — never at decoration time.
     const resolveConfig = () => typeof configOrFactory === 'function' ? configOrFactory() : configOrFactory;
-    return [
+    const providers = [
         // AGENT_CONFIG resolves the config once (running the factory in an
         // injection context if a factory was passed). AGENT reads the resolved
         // config from here, so the factory is invoked exactly once.
         { provide: AGENT_CONFIG, useFactory: resolveConfig },
-        {
-            provide: AGENT,
-            useFactory: () => {
-                // useFactory runs in an injection context, so the legacy `agent()`
-                // factory's `inject(DestroyRef)` calls work.
-                const config = inject(AGENT_CONFIG);
-                if (config.assistantId === undefined) {
-                    throw new Error('provideAgent: `assistantId` is required to construct the AGENT singleton.');
-                }
-                return agent({
-                    assistantId: config.assistantId,
-                    ...(config.apiUrl !== undefined ? { apiUrl: config.apiUrl } : {}),
-                    ...(config.threadId !== undefined ? { threadId: config.threadId } : {}),
-                    ...(config.onThreadId !== undefined ? { onThreadId: config.onThreadId } : {}),
-                    ...(config.initialValues !== undefined ? { initialValues: config.initialValues } : {}),
-                    ...(config.throttle !== undefined ? { throttle: config.throttle } : {}),
-                    ...(config.toMessage !== undefined ? { toMessage: config.toMessage } : {}),
-                    ...(config.transport !== undefined ? { transport: config.transport } : {}),
-                    ...(config.telemetry !== undefined ? { telemetry: config.telemetry } : {}),
-                    ...(config.filterSubagentMessages !== undefined ? { filterSubagentMessages: config.filterSubagentMessages } : {}),
-                    ...(config.subagentToolNames !== undefined ? { subagentToolNames: config.subagentToolNames } : {}),
-                });
-            },
-        },
+        { provide: AGENT, useFactory: (agentFactory) },
     ];
+    if (ref)
+        providers.push({ provide: ref.token, useExisting: AGENT });
+    return providers;
 }
 
 // SPDX-License-Identifier: MIT
-/**
- * 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).
- */
-function injectAgent() {
-    return inject(AGENT);
+function injectAgent(ref) {
+    return inject(ref ? ref.token : AGENT);
 }
 
 // SPDX-License-Identifier: MIT
@@ -2889,8 +3088,9 @@ const LANGGRAPH_CLIENT = new InjectionToken('LANGGRAPH_CLIENT');
  */
 class LangGraphThreadsAdapter {
     config = inject(LANGGRAPH_THREADS_CONFIG);
+    sharedClientOptions = inject(LANGGRAPH_CLIENT_OPTIONS, { optional: true }) ?? undefined;
     client = inject(LANGGRAPH_CLIENT, { optional: true })
-        ?? createLangGraphClient(this.config.apiUrl);
+        ?? createLangGraphClient(this.config.apiUrl, this.sharedClientOptions);
     fallback = this.config.titleFallback ?? 'Untitled';
     _threads = signal([], ...(ngDevMode ? [{ debugName: "_threads" }] : []));
     _archived = signal([], ...(ngDevMode ? [{ debugName: "_archived" }] : []));
@@ -3093,5 +3293,5 @@ function refreshOnTransition(watch, isActive, fn) {
  * Generated bundle index. Do not edit.
  */
 
-export { AGENT_LIFECYCLE, AgentLifecycleRegistry, FakeStreamTransport, FetchStreamTransport, LANGGRAPH_CLIENT, LANGGRAPH_THREADS_CONFIG, LangGraphThreadsAdapter, MockAgentTransport, ResourceStatus, createLangGraphClient, extractCitations, injectAgent, mockLangGraphAgent, provideAgent, provideFakeAgent, refreshOnRunEnd, refreshOnTransition, toAbsoluteApiUrl };
+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 };
 //# sourceMappingURL=threadplane-langgraph.mjs.map