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,