@threadplane/langgraph 0.0.49 → 0.0.50

package/fesm2022/threadplane-langgraph.mjs

@@ -1,5 +1,5 @@
 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';
@@ -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,7 +530,7 @@ 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;
@@ -1696,6 +1709,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 +1862,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 +2053,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 +2197,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(),
@@ -2083,7 +2241,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 +2274,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 +2307,14 @@ 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(),
+        clientTools: clientToolsCap,
         regenerate: async (assistantMessageIndex) => {
             if (isLoading()) {
                 throw new Error('Cannot regenerate while agent is loading another response');
@@ -2521,6 +2708,7 @@ function provideAgent(configOrFactory) {
                     ...(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 } : {}),
@@ -2889,8 +3077,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 +3282,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