From 54946b016801a8d59d1ddf723215e08f67e1e174 Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 17 Nov 2026 17:13:50 -0800 Subject: [PATCH] feat(langgraph): create the thread on the first message in the React session Angular agent() accepts a null threadId, creates the thread on the first submit and reports it through onThreadId. The React runtime createSession required a threadId, so apps had to create a thread before the user typed anything, and a "New chat" that was never sent left an empty thread behind. threadId is now optional (string | null). Without it the session sends no request until the first submit, which calls the new optional transport.createThread() once before the run (the owned SDK transport uses client.threads.create() under the owned maxRetries policy, 0 by default). The id is reported through onThreadId and read from session.threadId. A replacing submit shares the pending request, stop keeps a thread it creates, and dispose aborts it. A failed creation settles the submit with the generic request error (status only, never the body) and is retryable, since no run started. Before the thread exists, load and checkStatus resolve without a request and fork/regenerate reject. A string threadId behaves exactly as before. Co-Authored-By: Claude Opus 5.5 --- .../react/langgraph/guides/persistence.mdx | 14 + .../lib/transport/fetch-stream.transport.ts | 18 + libs/langgraph/src/runtime/README.md | 30 +- libs/langgraph/src/runtime/create-session.ts | 158 ++++++- .../langgraph/src/runtime/lazy-thread.spec.ts | 416 ++++++++++++++++++ .../src/runtime/lazy-thread.type-test.ts | 24 + libs/langgraph/src/runtime/transport.types.ts | 7 + 7 files changed, 643 insertions(+), 24 deletions(-) create mode 100644 libs/langgraph/src/runtime/lazy-thread.spec.ts create mode 100644 libs/langgraph/src/runtime/lazy-thread.type-test.ts diff --git a/apps/website/content/docs/react/langgraph/guides/persistence.mdx b/apps/website/content/docs/react/langgraph/guides/persistence.mdx index d0aee6806..d9e681a3b 100644 --- a/apps/website/content/docs/react/langgraph/guides/persistence.mdx +++ b/apps/website/content/docs/react/langgraph/guides/persistence.mdx @@ -36,6 +36,20 @@ export async function openConversation(apiUrl: string, confirmedThreadId: string } ~~~ +## Start a conversation without a thread + +Omit `threadId` to start an empty session. It sends no request until the first submit, which creates the thread before the run starts and reports its ID through `onThreadId`. A **New chat** that the user never sends leaves no empty thread behind. Record the reported ID; `session.threadId` holds it after creation. + +~~~tsx +import { createSession } from '@threadplane/langgraph'; + +export function startConversation(apiUrl: string, remember: (threadId: string) => void) { + return createSession({ apiUrl, assistantId: 'persistence', onThreadId: remember }); +} +~~~ + +Before that thread exists, `load()` and `checkStatus()` resolve without a request, and `fork()` and `regenerate()` reject. A second submit while the thread is being created waits for the same thread. If creation fails, the session reports a request error and stays usable: retry or send again. The session still belongs to one thread once it has one, so open a new session for another conversation. + The [React conversation walkthrough](/docs/react/langgraph/concepts/conversation-turns) connects this capability to requests, tools, UI state, and saved history. ## Create and revisit conversations diff --git a/libs/langgraph/src/lib/transport/fetch-stream.transport.ts b/libs/langgraph/src/lib/transport/fetch-stream.transport.ts index 6655cd18f..9d4d28ce7 100644 --- a/libs/langgraph/src/lib/transport/fetch-stream.transport.ts +++ b/libs/langgraph/src/lib/transport/fetch-stream.transport.ts @@ -104,6 +104,24 @@ export class FetchStreamTransport implements AgentTransport { yield* this.iterateSdkRun(run, signal); } + /** Create an empty thread, as `stream` does when it has no thread id. */ + async createThread(signal: AbortSignal): Promise { + let thread: Awaited>; + try { + thread = await this.client.threads.create({ signal }); + } catch (error) { + return this.rethrowOperationError(error, signal); + } + try { + const id = thread.thread_id; + if (typeof id !== 'string' || !id) + throw new Error('Invalid LangGraph thread response.'); + return id; + } catch (error) { + return this.rethrowLocalError(error, signal); + } + } + /** Join an already-started run without creating a new thread. */ async *joinStream( threadId: string, diff --git a/libs/langgraph/src/runtime/README.md b/libs/langgraph/src/runtime/README.md index 113ce204f..347cc4f51 100644 --- a/libs/langgraph/src/runtime/README.md +++ b/libs/langgraph/src/runtime/README.md @@ -13,6 +13,30 @@ builds. Commands, frozen manual review and dependency/type limitations are in This does not change the published package root or narrow the current custom transport declaration into a final public contract. +## Thread creation + +`threadId` is optional. A session created without one (or with `null`) starts +empty and sends no request until its first submit, which calls +`transport.createThread(signal)` once, before the run. The owned SDK transport +implements it with `client.threads.create()`, the call the Angular transport +makes, under the owned `maxRetries` policy (0 unless a number is supplied). A +supplied transport without `createThread` makes construction throw. The created id +is reported once through `onThreadId` and is read from `session.threadId`; a +throwing callback does not affect the run. The id is not part of the snapshot. + +- A submit that replaces a submit waiting on creation shares the same request, + so one session never creates two threads. Stop leaves the request running and + keeps a thread it creates; dispose aborts it and reports nothing. +- A failed creation settles the submit as `error` with the generic request + message. Only an unprotected SDK error's numeric status is read (401 and 403 + report `auth`), never its message or body. No run started, so the error is + `recovery: 'retry'` when `retry()` exists and `none` otherwise; the next submit + or `retry()` makes a new creation request. +- Before the thread exists, `load()` and `checkStatus()` resolve without a + request, `fork()` and `regenerate()` reject, and `reconnect()` and `resume()` + reject as they do with nothing to join or answer. +- There is no thread switch: a session still belongs to one thread once it has one. + ## Visible text The shared private wire helper preserves a top-level string verbatim. Arrays join @@ -164,7 +188,8 @@ undispatched (a browser `TypeError: fetch failed` carries no cause, and a reset after the server accepted the request looks identical to one that never left), so a pre-response failure is an `interrupted` error too, not a retryable `connection` one. The only `retry` the runtime emits is for a run the backend -itself reports as failed (see "Retry" below). +itself reports as failed (see "Retry" below), and for a first submit whose thread +could not be created, which started no run (see "Thread creation" above). `recovery: 'check'` is offered exactly when `transport.getHistory` exists for an ordinary submit, with or without a captured run id, and `checkStatus()` is exposed @@ -208,7 +233,8 @@ run so the two surfaces cannot disagree. when the transport has `getRunStatus`, because only the exact run's status can settle a failure. It sends a command again when, and only when, the backend reported that command's run as `error` or `timeout`, at close or through -`checkStatus()`. That error carries `retryable: true` and `recovery: 'retry'`. +`checkStatus()`, or when the command's thread could not be created. That error +carries `retryable: true` and `recovery: 'retry'`. - The transcript and values return to what they were before the command, and the command's captured input is sent again. A submission keeps its user message id, diff --git a/libs/langgraph/src/runtime/create-session.ts b/libs/langgraph/src/runtime/create-session.ts index 23657e254..5c85add9c 100644 --- a/libs/langgraph/src/runtime/create-session.ts +++ b/libs/langgraph/src/runtime/create-session.ts @@ -112,7 +112,13 @@ import { export interface SessionOptions { readonly assistantId: string; - readonly threadId: string; + /** The thread this session belongs to. Omit it, or pass null, to start an + * empty session that creates its thread on the first submit. That requires + * `transport.createThread`, which the owned SDK transport provides. */ + readonly threadId?: string | null; + /** Called once with the id of the thread this session created. Never called + * when `threadId` is given. A throwing callback does not affect the run. */ + readonly onThreadId?: (threadId: string) => void; readonly transport?: AgentTransport; readonly apiUrl?: string; /** The owned SDK transport defaults maxRetries to 0: an ambiguous failed @@ -131,6 +137,9 @@ export type LangGraphSession< > > = Omit, 'getSnapshot' | 'submit'> & { getSnapshot(): LangGraphSnapshot; + /** The session's thread: the given `threadId`, or the thread it created on + * the first submit. Undefined until that thread exists. */ + readonly threadId: string | undefined; submit( input: LangGraphSubmitInput, options?: LangGraphRunOptions @@ -270,7 +279,10 @@ export function createSession( readonly tools?: Record; } ): LangGraphSession { - const { assistantId, threadId } = options; + const { assistantId, onThreadId } = options; + let threadId: string | undefined = options.threadId ?? undefined; + if (onThreadId !== undefined && typeof onThreadId !== 'function') + throw new TypeError('onThreadId must be a function.'); const { definitions, catalog } = captureTools(options.tools); const typedTools = options.tools !== undefined; const suppliedStore = options.executionStore; @@ -311,6 +323,54 @@ export function createSession( const protectedTransport = transport instanceof FetchStreamTransport && transport.protectsOperationErrors; + const createThread = transport.createThread?.bind(transport); + if (threadId === undefined && !createThread) + throw new TypeError( + 'A session without a threadId requires transport.createThread().' + ); + /** The one pending thread creation every waiting command shares. */ + let creation: + | { readonly controller: AbortController; readonly id: Promise } + | undefined; + /** The session thread. Commands that reach here only run once it exists. */ + function thread(): string { + if (threadId === undefined) + throw new Error('The session thread does not exist yet.'); + return threadId; + } + /** Creates the session thread once. Stop leaves the request running, so a + * thread that is created is never lost; dispose aborts it. A failure clears + * the creation so the next command makes a new request. */ + function ensureThread(): Promise { + if (threadId !== undefined) return Promise.resolve(threadId); + if (creation) return creation.id; + const create = createThread; + if (!create) return Promise.reject(createSafeRequestError()); + const current = { controller: new AbortController() } as { + readonly controller: AbortController; + id: Promise; + }; + creation = current; + current.id = (async () => { + try { + const id = await create(current.controller.signal); + if (typeof id !== 'string' || !id) throw new Error('Invalid thread id.'); + if (creation !== current || disposed) throw createSafeRequestError(); + creation = undefined; + threadId = id; + try { + onThreadId?.(id); + } catch { + /* Application callbacks cannot affect the run. */ + } + return id; + } catch (error) { + if (creation === current) creation = undefined; + throw error; + } + })(); + return current.id; + } const persistence = createToolPersistence( buffer, async (messages, signal, branch) => { @@ -325,13 +385,13 @@ export function createSession( if (branch) branch.state = beginCheckpointEffect(branch.state, 'write'); try { const result = await transport.updateState( - threadId, + thread(), { messages }, signal, confirmed ? { checkpoint: confirmed.position } : undefined ); if (branch && confirmed) { - const position = captureCheckpoint(result, threadId); + const position = captureCheckpoint(result, thread()); branch.state = { kind: 'ready', confirmed: { ...confirmed, position }, @@ -423,6 +483,37 @@ export function createSession( }; } + /** Thread creation failed before any run started, so the command can be + * sent again. Only the status of an unprotected SDK error is read, never its + * message or body. */ + function threadCreationError(raw: unknown): AgentError { + let status: number | undefined; + if (!protectedTransport) { + try { + const value = record(raw)?.['status']; + if (typeof value === 'number') status = value; + } catch { + /* An unreadable failure is reported without a status. */ + } + } + if (status === 401 || status === 403) + return { + kind: 'auth', + message: 'Authentication failed. Check your credentials.', + status, + retryable: false, + recovery: 'none', + }; + const retry = !!getRunStatus; + return { + kind: 'server', + message: 'The LangGraph request failed.', + ...(status !== undefined ? { status } : {}), + retryable: retry, + recovery: retry ? 'retry' : 'none', + }; + } + function unsettledToolError(): AgentError { return { kind: 'interrupted', @@ -648,7 +739,7 @@ export function createSession( definition, call, attempt.controller.signal, - { threadId, toolCallId: call.id }, + { threadId: thread(), toolCallId: call.id }, store, groups >= 10 ); @@ -878,6 +969,17 @@ export function createSession( (attempt.input.kind === 'resume' && attempt.groups === 0)) && canCheck && !attempt.physical?.evidence.unsafe; + if (threadId === undefined) { + // The first submit of a session without a thread creates it before the + // run. A replacing submit waits for the same request. + try { + await ensureThread(); + } catch (raw) { + if (owns(attempt)) settle(attempt, 'error', threadCreationError(raw)); + return; + } + if (!owns(attempt)) return; + } try { let groups = attempt.groups; let input = attempt.input.kind === 'submit' ? attempt.input.messages : []; @@ -927,7 +1029,7 @@ export function createSession( try { evidence = run.received ? { unsafe: true } - : captureRun(previous, metadata, threadId); + : captureRun(previous, metadata, thread()); } catch { evidence = { unsafe: true }; } @@ -938,7 +1040,7 @@ export function createSession( const events = joining && joinStream && run.evidence.runId ? joinStream( - threadId, + thread(), run.evidence.runId, joining, attempt.controller.signal, @@ -948,7 +1050,7 @@ export function createSession( ) : transport.stream( assistantId, - threadId, + thread(), payload, attempt.controller.signal, !suppliedTransport || @@ -1009,7 +1111,7 @@ export function createSession( } const previousEvidence = run.evidence; const checkpoint = attempt.branch - ? captureCheckpointEvent(event, threadId) + ? captureCheckpointEvent(event, thread()) : undefined; const cursor = advanceCursor(previousEvidence, event, joining); if (!owns(attempt)) return; @@ -1077,7 +1179,7 @@ export function createSession( if (run.evidence.runId && !run.evidence.unsafe && getRunStatus) { try { status = await getRunStatus( - threadId, + thread(), run.evidence.runId, attempt.controller.signal ); @@ -1091,7 +1193,7 @@ export function createSession( } else { run.confirmed = true; const saved = await getState( - threadId, + thread(), run.checkpoint.position, attempt.controller.signal ); @@ -1144,7 +1246,7 @@ export function createSession( historyChecked = true; try { const history = await getHistory( - threadId, + thread(), attempt.controller.signal ); if (!owns(attempt)) return; @@ -1182,7 +1284,7 @@ export function createSession( ) { try { const history = await getHistory( - threadId, + thread(), attempt.controller.signal ); if (!owns(attempt)) return; @@ -1319,7 +1421,7 @@ export function createSession( if (run?.evidence.runId && !run.evidence.unsafe && getRunStatus) { try { status = await getRunStatus( - threadId, + thread(), run.evidence.runId, attempt.controller.signal ); @@ -1331,7 +1433,7 @@ export function createSession( if (status !== 'pending' && status !== 'running') { try { const history = await getHistory( - threadId, + thread(), attempt.controller.signal ); if (!owns(attempt)) return; @@ -1502,7 +1604,7 @@ export function createSession( if (preparing !== preparation || disposed || !getState) return; try { const saved = await getState( - threadId, + thread(), preparation.checkpoint, preparation.controller.signal ); @@ -1544,12 +1646,14 @@ export function createSession( throw new Error( 'Fork requires an SDK transport with maxRetries set to zero.' ); + if (threadId === undefined) + throw new Error('Fork requires the session thread to exist.'); const capturedRevision = revision; const external = options?.signal; const current = () => !disposed && !external?.aborted && capturedRevision === revision; if (!current()) return; - const position = captureCheckpoint(checkpoint, threadId); + const position = captureCheckpoint(checkpoint, thread()); if (!current()) return; const captured = captureSubmitInput(input); if (!current()) return; @@ -1858,14 +1962,14 @@ export function createSession( ? [ captureCheckpointState( await getState( - threadId, + thread(), confirmed.position, read.controller.signal ), confirmed.position ), ] - : await getHistory!(threadId, read.controller.signal); + : await getHistory!(thread(), read.controller.signal); await publication.command(() => { if (!ownsLoad(read)) return; const previousState = state; @@ -1942,6 +2046,8 @@ export function createSession( throw new Error( 'History cannot replace an active request, recovery, or unsettled tool results.' ); + // Before the first submit creates the thread there is no history. + if (threadId === undefined) return; // A check owned by an earlier resume yields to a fresh read: the pause it // answered is restored from history, so the decision can be sent again. let withdrawn: AbortController | undefined; @@ -2057,7 +2163,7 @@ export function createSession( if (run?.evidence.runId && !run.evidence.unsafe && getRunStatus) { try { status = await getRunStatus( - threadId, + thread(), run.evidence.runId, captured.controller.signal ); @@ -2084,7 +2190,7 @@ export function createSession( } } const history = await transport.getHistory?.( - threadId, + thread(), captured.controller.signal ); await publication.command(() => { @@ -2156,8 +2262,10 @@ export function createSession( throw new Error('No prompt precedes that message.'); }; const prompt = select(); + if (threadId === undefined) + throw new Error('Regenerate requires the session thread to exist.'); const history = await getHistory!( - threadId, + thread(), options?.signal ?? new AbortController().signal ); // The transcript may have moved on while history was read. @@ -2193,6 +2301,9 @@ export function createSession( return { getSnapshot: publication.getSnapshot, + get threadId() { + return threadId; + }, subscribe: (notify) => disposed ? () => undefined : publication.subscribe(notify), onCustomEvent: (listener) => @@ -2215,6 +2326,8 @@ export function createSession( publication.command(() => { if (disposed) return; disposed = true; + const pendingThread = creation; + creation = undefined; const preparation = detachPreparation(); retained = undefined; const reading = detachLoad(); @@ -2227,6 +2340,7 @@ export function createSession( if (attempt) close(attempt, true); closeLoad(reading); closePreparation(preparation); + pendingThread?.controller.abort(); }), }; } diff --git a/libs/langgraph/src/runtime/lazy-thread.spec.ts b/libs/langgraph/src/runtime/lazy-thread.spec.ts new file mode 100644 index 000000000..a1ca40933 --- /dev/null +++ b/libs/langgraph/src/runtime/lazy-thread.spec.ts @@ -0,0 +1,416 @@ +import { afterEach, describe, expect, it, vi } from 'vitest'; +import type { Run } from '@langchain/langgraph-sdk'; +import { createSession } from './create-session'; +import { deferred } from './testing/deferred'; +import type { AgentTransport, StreamEvent } from './transport.types'; + +type Payload = { messages?: { id: string; type: string; content: string }[] }; + +/** A completed run that echoes the submitted user message and answers it. */ +function answer(payload: unknown, content = 'Done'): StreamEvent[] { + return [ + { + type: 'values', + data: { + messages: [ + ...((payload as Payload | null)?.messages ?? []), + { type: 'ai', id: `answer-${content}`, content }, + ], + }, + }, + ]; +} + +function fixture( + options: { + createThread?: NonNullable; + runStatus?: boolean; + } = {} +) { + const createThread = vi.fn>( + options.createThread ?? (async () => 'created') + ); + const stream = vi.fn(async function* ( + _assistant, + thread, + payload, + _signal, + settings + ) { + settings?.onRunCreated?.({ run_id: 'run-0', thread_id: thread ?? '' }); + yield* answer(payload); + }); + const getHistory = vi.fn>( + async () => [] + ); + const getState = vi.fn>(); + const getRunStatus = vi.fn>( + async (): Promise => 'success' + ); + const joinStream = vi.fn>( + async function* () { + yield* []; + } + ); + const updateState = vi.fn>(); + const onThreadId = vi.fn<(threadId: string) => void>(); + const transport: AgentTransport = { + stream, + createThread, + getHistory, + getState, + joinStream, + updateState, + ...(options.runStatus === false ? {} : { getRunStatus }), + }; + const session = createSession({ + assistantId: 'a', + transport, + onThreadId, + }); + return { + session, + createThread, + stream, + getHistory, + getState, + getRunStatus, + joinStream, + updateState, + onThreadId, + }; +} + +describe('a session without a thread', () => { + afterEach(() => { + vi.restoreAllMocks(); + vi.unstubAllGlobals(); + }); + + it('sends no request before the first submit', async () => { + const f = fixture(); + expect(f.session.threadId).toBeUndefined(); + const initial = f.session.getSnapshot(); + await f.session.load?.(); + await f.session.checkStatus?.(); + await expect(f.session.reconnect()).rejects.toThrow( + 'Reconnect requires an idle retained run' + ); + await expect(f.session.resume(true)).rejects.toThrow( + 'Resume requires an observed interrupt.' + ); + await expect( + f.session.fork( + { + thread_id: 'other', + checkpoint_ns: '', + checkpoint_id: 'c', + checkpoint_map: {}, + }, + 'Branch' + ) + ).rejects.toThrow('Fork requires the session thread to exist.'); + await expect(f.session.regenerate?.('missing')).rejects.toThrow(); + expect(await f.session.retry?.()).toBe('aborted'); + await f.session.stop(); + expect(f.session.getSnapshot()).toBe(initial); + for (const call of [ + f.createThread, + f.stream, + f.getHistory, + f.getState, + f.getRunStatus, + f.joinStream, + f.updateState, + f.onThreadId, + ]) + expect(call).not.toHaveBeenCalled(); + await f.session.dispose(); + }); + + it('creates the thread on the first submit, reports it, and reuses it', async () => { + const f = fixture(); + expect(await f.session.submit('Hello')).toBe('success'); + expect(f.createThread).toHaveBeenCalledTimes(1); + expect(f.onThreadId).toHaveBeenCalledTimes(1); + expect(f.onThreadId).toHaveBeenCalledWith('created'); + expect(f.session.threadId).toBe('created'); + expect(f.stream).toHaveBeenCalledTimes(1); + expect(f.stream.mock.calls[0][1]).toBe('created'); + // The thread exists before the run starts. + expect(f.createThread.mock.invocationCallOrder[0]).toBeLessThan( + f.stream.mock.invocationCallOrder[0] + ); + expect( + f.session.getSnapshot().messages.map(({ role, content }) => [role, content]) + ).toEqual([ + ['user', 'Hello'], + ['assistant', 'Done'], + ]); + expect(await f.session.submit('Again')).toBe('success'); + expect(f.createThread).toHaveBeenCalledTimes(1); + expect(f.onThreadId).toHaveBeenCalledTimes(1); + expect(f.stream.mock.calls[1][1]).toBe('created'); + await f.session.load?.(); + expect(f.getHistory).toHaveBeenCalledTimes(1); + expect(f.getHistory.mock.calls[0][0]).toBe('created'); + await f.session.dispose(); + }); + + it('creates one thread when a second submit replaces a pending creation', async () => { + const pending = deferred(); + const f = fixture({ createThread: () => pending.promise }); + const first = f.session.submit('First'); + await Promise.resolve(); + const second = f.session.submit('Second'); + pending.resolve('only'); + expect(await first).toBe('interrupted'); + expect(await second).toBe('success'); + expect(f.createThread).toHaveBeenCalledTimes(1); + expect(f.onThreadId).toHaveBeenCalledTimes(1); + expect(f.onThreadId).toHaveBeenCalledWith('only'); + expect(f.stream).toHaveBeenCalledTimes(1); + expect(f.stream.mock.calls[0][1]).toBe('only'); + expect((f.stream.mock.calls[0][2] as Payload).messages?.[0].content).toBe( + 'Second' + ); + await f.session.dispose(); + }); + + it('keeps a thread whose creation finishes after stop', async () => { + const pending = deferred(); + const f = fixture({ createThread: () => pending.promise }); + const first = f.session.submit('First'); + await Promise.resolve(); + await f.session.stop(); + expect(await first).toBe('aborted'); + pending.resolve('kept'); + await pending.promise; + await Promise.resolve(); + expect(f.session.threadId).toBe('kept'); + expect(f.onThreadId).toHaveBeenCalledWith('kept'); + expect(f.stream).not.toHaveBeenCalled(); + expect(await f.session.submit('Second')).toBe('success'); + expect(f.createThread).toHaveBeenCalledTimes(1); + expect(f.stream.mock.calls[0][1]).toBe('kept'); + await f.session.dispose(); + }); + + it('aborts a pending creation on dispose and never reports it', async () => { + let signal: AbortSignal | undefined; + const pending = deferred(); + const f = fixture({ + createThread: (abort) => { + signal = abort; + return pending.promise; + }, + }); + const first = f.session.submit('First'); + await Promise.resolve(); + await f.session.dispose(); + expect(await first).toBe('aborted'); + expect(signal?.aborted).toBe(true); + pending.resolve('late'); + await pending.promise; + await Promise.resolve(); + expect(f.session.threadId).toBeUndefined(); + expect(f.onThreadId).not.toHaveBeenCalled(); + expect(f.stream).not.toHaveBeenCalled(); + }); + + it('reports a failed creation without its body and retries it', async () => { + let attempts = 0; + const f = fixture({ + createThread: async () => { + if (attempts++ === 0) + throw Object.assign(new Error('PRIVATE_BODY'), { status: 500 }); + return 'second'; + }, + }); + expect(await f.session.submit('Hello')).toBe('error'); + const failed = f.session.getSnapshot(); + expect(failed).toMatchObject({ + status: 'error', + error: { + kind: 'server', + message: 'The LangGraph request failed.', + retryable: true, + recovery: 'retry', + }, + }); + expect(JSON.stringify(failed)).not.toContain('PRIVATE_BODY'); + expect(f.session.threadId).toBeUndefined(); + expect(f.onThreadId).not.toHaveBeenCalled(); + expect(f.stream).not.toHaveBeenCalled(); + expect(await f.session.retry?.()).toBe('success'); + expect(f.createThread).toHaveBeenCalledTimes(2); + expect(f.session.threadId).toBe('second'); + expect(f.onThreadId).toHaveBeenCalledWith('second'); + expect( + f.session.getSnapshot().messages.map(({ role, content }) => [role, content]) + ).toEqual([ + ['user', 'Hello'], + ['assistant', 'Done'], + ]); + await f.session.dispose(); + }); + + it('accepts a new submit after a failed creation when retry is unavailable', async () => { + let attempts = 0; + const f = fixture({ + runStatus: false, + createThread: async () => { + if (attempts++ === 0) throw new TypeError('fetch failed'); + return 'second'; + }, + }); + expect(f.session.retry).toBeUndefined(); + expect(await f.session.submit('Hello')).toBe('error'); + expect(f.session.getSnapshot().error).toMatchObject({ + kind: 'server', + message: 'The LangGraph request failed.', + retryable: false, + recovery: 'none', + }); + expect(await f.session.submit('Hello again')).toBe('success'); + expect(f.createThread).toHaveBeenCalledTimes(2); + expect(f.stream.mock.calls[0][1]).toBe('second'); + await f.session.dispose(); + }); + + it('reports a rejected credential as an authentication failure', async () => { + const f = fixture({ + createThread: async () => { + throw Object.assign(new Error('PRIVATE_BODY'), { status: 401 }); + }, + }); + expect(await f.session.submit('Hello')).toBe('error'); + expect(f.session.getSnapshot().error).toEqual({ + kind: 'auth', + message: 'Authentication failed. Check your credentials.', + status: 401, + retryable: false, + recovery: 'none', + }); + await f.session.dispose(); + }); + + it('rejects an empty created thread id', async () => { + const f = fixture({ createThread: async () => '' }); + expect(await f.session.submit('Hello')).toBe('error'); + expect(f.session.threadId).toBeUndefined(); + expect(f.onThreadId).not.toHaveBeenCalled(); + expect(f.stream).not.toHaveBeenCalled(); + await f.session.dispose(); + }); + + it('isolates a throwing onThreadId callback from the run', async () => { + const stream = vi.fn(async function* ( + _assistant, + _thread, + payload + ) { + yield* answer(payload); + }); + const session = createSession({ + assistantId: 'a', + transport: { stream, createThread: async () => 'created' }, + onThreadId: () => { + throw new Error('application failure'); + }, + }); + expect(await session.submit('Hello')).toBe('success'); + expect(session.threadId).toBe('created'); + await session.dispose(); + }); + + it('requires a transport that can create threads', () => { + expect(() => + createSession({ + assistantId: 'a', + transport: { + stream: async function* () { + yield* []; + }, + }, + }) + ).toThrow(TypeError); + }); + + it('leaves a session with a fixed thread unchanged', async () => { + const createThread = vi.fn(async () => 'never'); + const onThreadId = vi.fn(); + const stream = vi.fn(async function* ( + _assistant, + _thread, + payload + ) { + yield* answer(payload); + }); + const session = createSession({ + assistantId: 'a', + threadId: 'fixed', + transport: { stream, createThread }, + onThreadId, + }); + expect(session.threadId).toBe('fixed'); + expect(await session.submit('Hello')).toBe('success'); + expect(stream.mock.calls[0][1]).toBe('fixed'); + expect(createThread).not.toHaveBeenCalled(); + expect(onThreadId).not.toHaveBeenCalled(); + await session.dispose(); + }); + + it('creates the thread through the owned SDK client without retries', async () => { + const fetch = vi.fn(async (input: string | URL | Request) => { + const url = String(input); + if (url.endsWith('/threads')) + return new Response(JSON.stringify({ thread_id: 'server-thread' }), { + headers: { 'content-type': 'application/json' }, + }); + return new Response( + `event: values\ndata: ${JSON.stringify({ + messages: [{ type: 'ai', id: 'answer', content: 'Done' }], + })}\n\n`, + { headers: { 'content-type': 'text/event-stream' } } + ); + }); + vi.stubGlobal('fetch', fetch); + const onThreadId = vi.fn(); + const session = createSession({ + assistantId: 'a', + apiUrl: 'https://runtime.example', + onThreadId, + }); + expect(fetch).not.toHaveBeenCalled(); + expect(await session.submit('Hello')).toBe('success'); + expect(onThreadId).toHaveBeenCalledWith('server-thread'); + expect(String(fetch.mock.calls[0][0])).toBe( + 'https://runtime.example/threads' + ); + expect(String(fetch.mock.calls[1][0])).toContain( + '/threads/server-thread/runs/stream' + ); + await session.dispose(); + }); + + it('fails an owned creation once, without reading its body', async () => { + const fetch = vi.fn( + async () => new Response('PRIVATE_BODY', { status: 500 }) + ); + vi.stubGlobal('fetch', fetch); + const session = createSession({ + assistantId: 'a', + apiUrl: 'https://runtime.example', + }); + expect(await session.submit('Hello')).toBe('error'); + expect(fetch).toHaveBeenCalledTimes(1); + const snapshot = session.getSnapshot(); + expect(snapshot.error).toMatchObject({ + kind: 'server', + message: 'The LangGraph request failed.', + }); + expect(JSON.stringify(snapshot)).not.toContain('PRIVATE_BODY'); + await session.dispose(); + }); +}); diff --git a/libs/langgraph/src/runtime/lazy-thread.type-test.ts b/libs/langgraph/src/runtime/lazy-thread.type-test.ts new file mode 100644 index 000000000..bfd386e45 --- /dev/null +++ b/libs/langgraph/src/runtime/lazy-thread.type-test.ts @@ -0,0 +1,24 @@ +import type { AgentSession } from '@threadplane/core'; +import { createSession, type SessionOptions } from './create-session'; + +const lazy = createSession({ + assistantId: 'a', + onThreadId: (threadId: string) => void threadId, +}); +const fixed = createSession({ assistantId: 'a', threadId: 't' }); +const cleared = createSession({ assistantId: 'a', threadId: null }); +const current: string | undefined = lazy.threadId; +// @ts-expect-error The thread does not exist before the first submit. +const known: string = lazy.threadId; +// @ts-expect-error The created id is read, never assigned. +fixed.threadId = 'other'; +// @ts-expect-error onThreadId receives the created thread id. +createSession({ assistantId: 'a', onThreadId: (threadId: number) => threadId }); +// @ts-expect-error A thread id is text. +createSession({ assistantId: 'a', threadId: 1 }); +const createThread: NonNullable['createThread'] = + async (signal: AbortSignal) => (signal.aborted ? 'aborted' : 'created'); +const observer: AgentSession = lazy; +// @ts-expect-error The core observer has no LangGraph thread. +void observer.threadId; +void [cleared, current, known, createThread]; diff --git a/libs/langgraph/src/runtime/transport.types.ts b/libs/langgraph/src/runtime/transport.types.ts index 973d57822..f49337e2d 100644 --- a/libs/langgraph/src/runtime/transport.types.ts +++ b/libs/langgraph/src/runtime/transport.types.ts @@ -124,6 +124,13 @@ export interface AgentTransport { options?: LangGraphSubmitOptions ): AsyncIterable; + /** + * Optional: create an empty thread once and resolve its id. A session + * created without a `threadId` calls this on its first submit, before the + * run starts. Make a single request: the session never retries it. + */ + createThread?(signal: AbortSignal): Promise; + /** Optional: join an already-started run without creating a new one. */ joinStream?( threadId: string,