@assistant-ui/react-langchain 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,111 @@
+## `@assistant-ui/react-langchain`
+
+Adapter that wraps [`useStream`](https://docs.langchain.com/oss/javascript/langgraph-sdk/react-stream) from `@langchain/react` and exposes it as an assistant-ui runtime, with hooks for reading interrupts, submitting raw state updates, and reading arbitrary LangGraph custom state keys.
+
+> assistant-ui also ships [`@assistant-ui/react-langgraph`](https://www.npmjs.com/package/@assistant-ui/react-langgraph), which integrates with `@langchain/langgraph-sdk` directly and has a broader feature set (subgraph events, UI messages, message metadata, cancellation). The two packages are independent adapters targeting different upstream libraries — pick whichever matches your upstream choice. See the [comparison](https://www.assistant-ui.com/docs/runtimes/langchain/comparison).
+
+## Features
+
+- Bridges LangChain's `useStream` to an assistant-ui `AssistantRuntime`
+- Tool invocations flow through assistant-ui's `useToolInvocations`
+- `useLangChainInterruptState` — read the current LangGraph interrupt
+- `useLangChainSubmit` — submit raw state updates (e.g. resume commands)
+- `useLangChainState<T>(key)` — read custom state keys like `todos` / `files` reactively
+- Optional assistant-cloud thread persistence
+
+## Installation
+
+```bash
+npm install @assistant-ui/react @assistant-ui/react-langchain @langchain/react
+```
+
+## Usage
+
+### Basic setup
+
+```tsx
+import { useStreamRuntime } from "@assistant-ui/react-langchain";
+import { AssistantRuntimeProvider, Thread } from "@assistant-ui/react";
+
+function App() {
+  const runtime = useStreamRuntime({
+    assistantId: "agent",
+    apiUrl: "http://localhost:2024",
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+`useStreamRuntime` accepts every option `useStream` from `@langchain/react` does, plus:
+
+- `cloud` — an `AssistantCloud` instance for persisting threads
+- `adapters` — `{ attachments, speech, feedback }`
+- `messagesKey` — the state key that holds messages (default `"messages"`)
+
+### Reading custom state keys
+
+LangGraph agents often expose structured state beyond messages (plans, todos, scratch files, generative-UI artifacts). Read them directly with `useLangChainState` — mirrors `useStream().values[key]` upstream and updates when the stream emits new state.
+
+```tsx
+import { useLangChainState } from "@assistant-ui/react-langchain";
+
+type Todo = { id: string; title: string; done: boolean };
+
+function TodoList() {
+  const todos = useLangChainState<Todo[]>("todos", []);
+
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Signatures:
+
+```ts
+useLangChainState<T>(key: string): T | undefined;
+useLangChainState<T>(key: string, defaultValue: T): T;
+```
+
+### Interrupts
+
+```tsx
+import {
+  useLangChainInterruptState,
+  useLangChainSubmit,
+} from "@assistant-ui/react-langchain";
+import { Command } from "@langchain/langgraph-sdk";
+
+function InterruptPrompt() {
+  const interrupt = useLangChainInterruptState();
+  const submit = useLangChainSubmit();
+
+  if (!interrupt) return null;
+
+  return (
+    <div>
+      <pre>{JSON.stringify(interrupt.value, null, 2)}</pre>
+      <button onClick={() => submit(null, { command: new Command({ resume: "yes" }) })}>
+        Approve
+      </button>
+    </div>
+  );
+}
+```
+
+### Message conversion
+
+The adapter ships `convertLangChainBaseMessage` for cases where you want to reuse the internal converter directly (e.g. when building a custom `ExternalStoreAdapter`).
+
+```ts
+import { convertLangChainBaseMessage } from "@assistant-ui/react-langchain";
+```

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { useStreamRuntime, useLangChainInterruptState, useLangChainSubmit, } from "./useStreamRuntime.js";
+export { useStreamRuntime, useLangChainInterruptState, useLangChainState, useLangChainSubmit, } from "./useStreamRuntime.js";
 export type { UseStreamRuntimeOptions } from "./useStreamRuntime.js";
 export { convertLangChainBaseMessage } from "./convertMessages.js";
 export type { LangChainBaseMessage, LangChainContentBlock, LangChainToolCall, } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,kBAAkB,GACnB,8BAA2B;AAC5B,YAAY,EAAE,uBAAuB,EAAE,8BAA2B;AAElE,OAAO,EAAE,2BAA2B,EAAE,6BAA0B;AAEhE,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,GAClB,mBAAgB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,GACnB,8BAA2B;AAC5B,YAAY,EAAE,uBAAuB,EAAE,8BAA2B;AAElE,OAAO,EAAE,2BAA2B,EAAE,6BAA0B;AAEhE,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,GAClB,mBAAgB"}

package/dist/index.js

@@ -1,3 +1,3 @@
-export { useStreamRuntime, useLangChainInterruptState, useLangChainSubmit, } from "./useStreamRuntime.js";
+export { useStreamRuntime, useLangChainInterruptState, useLangChainState, useLangChainSubmit, } from "./useStreamRuntime.js";
 export { convertLangChainBaseMessage } from "./convertMessages.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,kBAAkB,GACnB,8BAA2B;AAG5B,OAAO,EAAE,2BAA2B,EAAE,6BAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,GACnB,8BAA2B;AAG5B,OAAO,EAAE,2BAA2B,EAAE,6BAA0B"}

package/dist/useStreamRuntime.d.ts

@@ -48,4 +48,17 @@ export declare const useLangChainInterruptState: () => {
  * commands.
  */
 export declare const useLangChainSubmit: () => (values: Record<string, unknown> | null | undefined, options?: Record<string, unknown>) => Promise<void>;
+/**
+ * Read a custom LangGraph state key from the current thread. Mirrors
+ * `useStream().values[key]` from `@langchain/react` and updates when the
+ * stream emits new state.
+ *
+ * @example
+ * ```tsx
+ * const todos = useLangChainState<Todo[]>("todos");
+ * const files = useLangChainState<Record<string, string>>("files", {});
+ * ```
+ */
+export declare function useLangChainState<T>(key: string): T | undefined;
+export declare function useLangChainState<T>(key: string, defaultValue: T): T;
 //# sourceMappingURL=useStreamRuntime.d.ts.map

package/dist/useStreamRuntime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useStreamRuntime.d.ts","sourceRoot":"","sources":["../src/useStreamRuntime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AA4BpE,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,KAAK,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,EACL;QACE,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;QAC5C,MAAM,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;QAC5C,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;KACxC,GACD,SAAS,CAAC;IACd,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAoKF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,GAAI,uBAG9B,uBAAuB,kDAYzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B;YA/OhB,OAAO;aAqP7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,SAG3B,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAMpC,CAAC"}
+{"version":3,"file":"useStreamRuntime.d.ts","sourceRoot":"","sources":["../src/useStreamRuntime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AA6BpE,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,KAAK,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,EACL;QACE,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;QAC5C,MAAM,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;QAC5C,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;KACxC,GACD,SAAS,CAAC;IACd,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AA8KF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,GAAI,uBAG9B,uBAAuB,kDAazB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B;YA3PhB,OAAO;aAiQ7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,SAG3B,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAMpC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;AACjE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC"}

package/dist/useStreamRuntime.js

@@ -51,26 +51,33 @@ const getMessageContent = (msg) => {
     return content;
 };
 const useStreamThreadRuntime = ({ adapters, messagesKey = "messages", ...streamOptions }) => {
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const externalId = useAuiState((s) => s.threadListItem.externalId);
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const stream = useStream({
         ...streamOptions,
         threadId: externalId,
     });
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const [toolStatuses, setToolStatuses] = useState({});
     const hasExecutingTools = Object.values(toolStatuses).some((s) => s?.type === "executing");
     const effectiveIsRunning = stream.isLoading || hasExecutingTools;
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const threadMessages = useExternalMessageConverter({
         callback: convertLangChainBaseMessage,
         messages: stream.messages,
         isRunning: effectiveIsRunning,
     });
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const [runtimeRef] = useState(() => ({
         get current() {
             return runtime;
         },
     }));
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const streamRef = useRef(stream);
     streamRef.current = stream;
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const toolInvocations = useToolInvocations({
         state: {
             messages: threadMessages,
@@ -94,12 +101,15 @@ const useStreamThreadRuntime = ({ adapters, messagesKey = "messages", ...streamO
         },
         setToolStatuses,
     });
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const extras = useMemo(() => ({
         [symbolLangChainRuntimeExtras]: true,
         interrupt: stream.interrupt,
         interrupts: stream.interrupts,
         submit: stream.submit,
-    }), [stream.interrupt, stream.interrupts, stream.submit]);
+        values: stream.values,
+    }), [stream.interrupt, stream.interrupts, stream.submit, stream.values]);
+    // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
     const runtime = useExternalStoreRuntime({
         isRunning: effectiveIsRunning,
         messages: threadMessages,
@@ -163,6 +173,7 @@ export const useStreamRuntime = ({ cloud, ...options }) => {
     const cloudAdapter = useCloudThreadListAdapter({ cloud });
     return useRemoteThreadListRuntime({
         runtimeHook: function RuntimeHook() {
+            // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
             return useStreamThreadRuntime(optionsRef.current);
         },
         adapter: cloudAdapter,
@@ -193,4 +204,13 @@ export const useLangChainSubmit = () => {
         return submit(values, options);
     };
 };
+export function useLangChainState(key, defaultValue) {
+    return useAuiState((s) => {
+        const extras = s.thread.extras;
+        if (!extras)
+            return defaultValue;
+        const value = asLangChainRuntimeExtras(extras).values[key];
+        return value !== undefined ? value : defaultValue;
+    });
+}
 //# sourceMappingURL=useStreamRuntime.js.map

package/dist/useStreamRuntime.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStreamRuntime.js","sourceRoot":"","sources":["../src/useStreamRuntime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useStreamRuntime.js","sourceRoot":"","sources":["../src/useStreamRuntime.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/react-langchain",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "LangChain useStream adapter for assistant-ui",
   "keywords": [
     "langchain",
@@ -29,10 +29,10 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@assistant-ui/core": "^0.1.14",
-    "@assistant-ui/store": "^0.2.7",
+    "@assistant-ui/core": "^0.1.15",
+    "@assistant-ui/store": "^0.2.8",
     "assistant-cloud": "*",
-    "assistant-stream": "^0.3.11"
+    "assistant-stream": "^0.3.12"
   },
   "peerDependencies": {
     "@langchain/react": "^0.3.3",
@@ -45,12 +45,15 @@
     }
   },
   "devDependencies": {
-    "@langchain/core": "^1.1.39",
-    "@langchain/langgraph-sdk": "^1.8.8",
+    "@langchain/core": "^1.1.40",
+    "@langchain/langgraph-sdk": "^1.8.9",
     "@langchain/react": "^0.3.3",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
+    "jsdom": "^29.0.2",
     "react": "^19.2.5",
-    "@assistant-ui/x-buildutils": "0.0.5"
+    "vitest": "^4.1.5",
+    "@assistant-ui/x-buildutils": "0.0.6"
   },
   "publishConfig": {
     "access": "public",
@@ -66,6 +69,8 @@
     "url": "https://github.com/assistant-ui/assistant-ui/issues"
   },
   "scripts": {
-    "build": "aui-build"
+    "build": "aui-build",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 export {
   useStreamRuntime,
   useLangChainInterruptState,
+  useLangChainState,
   useLangChainSubmit,
 } from "./useStreamRuntime";
 export type { UseStreamRuntimeOptions } from "./useStreamRuntime";

package/src/useLangChainState.test.tsx

@@ -0,0 +1,92 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+import { renderHook } from "@testing-library/react";
+
+type Selector = (state: unknown) => unknown;
+const { mockUseAuiState } = vi.hoisted(() => ({
+  mockUseAuiState: vi.fn(),
+}));
+
+vi.mock(import("@assistant-ui/store"), async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    useAuiState: ((selector: Selector) =>
+      mockUseAuiState(selector)) as typeof actual.useAuiState,
+    useAui: (() => ({})) as unknown as typeof actual.useAui,
+  };
+});
+
+import { useLangChainState } from "./useStreamRuntime";
+
+// The real guard symbol in useStreamRuntime is module-private. To stand in for
+// runtime-produced extras, we use a Proxy whose `has` trap claims any symbol
+// with the description "langchain-runtime-extras" is present.
+const makeExtras = (values: Record<string, unknown>) =>
+  new Proxy(
+    { values },
+    {
+      has: (target, key) =>
+        (typeof key === "symbol" &&
+          key.description === "langchain-runtime-extras") ||
+        Reflect.has(target, key),
+    },
+  );
+
+const runSelectorAgainst = (extras: unknown) => {
+  mockUseAuiState.mockImplementationOnce((selector: Selector) =>
+    selector({ thread: { extras } }),
+  );
+};
+
+describe("useLangChainState", () => {
+  it("returns undefined when extras are absent", () => {
+    runSelectorAgainst(undefined);
+    const { result } = renderHook(() => useLangChainState<number>("count"));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("returns defaultValue when extras are absent", () => {
+    runSelectorAgainst(undefined);
+    const { result } = renderHook(() => useLangChainState<number>("count", 42));
+    expect(result.current).toBe(42);
+  });
+
+  it("reads the value for the given key from extras.values", () => {
+    runSelectorAgainst(makeExtras({ todos: [{ id: "a" }], count: 7 }));
+    const { result } = renderHook(() =>
+      useLangChainState<Array<{ id: string }>>("todos"),
+    );
+    expect(result.current).toEqual([{ id: "a" }]);
+  });
+
+  it("falls back to defaultValue when the key is missing from values", () => {
+    runSelectorAgainst(makeExtras({ unrelated: "x" }));
+    const { result } = renderHook(() => useLangChainState<number>("count", 99));
+    expect(result.current).toBe(99);
+  });
+
+  it("returns undefined when the key is missing and no default is given", () => {
+    runSelectorAgainst(makeExtras({ unrelated: "x" }));
+    const { result } = renderHook(() => useLangChainState<number>("count"));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("returns the stored value (not default) when both are present", () => {
+    runSelectorAgainst(makeExtras({ count: 0 }));
+    const { result } = renderHook(() => useLangChainState<number>("count", 99));
+    // 0 is a valid value; must be preserved over the default.
+    expect(result.current).toBe(0);
+  });
+
+  it("preserves explicit null over defaultValue", () => {
+    runSelectorAgainst(makeExtras({ flag: null }));
+    const { result } = renderHook(() =>
+      useLangChainState<string | null>("flag", "default"),
+    );
+    // LangGraph treats null as an explicit "cleared" value distinct
+    // from a missing key; the hook must not conflate them.
+    expect(result.current).toBeNull();
+  });
+});

package/src/useStreamRuntime.ts

@@ -31,6 +31,7 @@ type LangChainRuntimeExtras = {
     values: Record<string, unknown> | null | undefined,
     options?: Record<string, unknown>,
   ) => Promise<void>;
+  values: Record<string, unknown>;
 };
 
 const asLangChainRuntimeExtras = (extras: unknown): LangChainRuntimeExtras => {
@@ -110,15 +111,18 @@ const useStreamThreadRuntime = ({
   messagesKey = "messages",
   ...streamOptions
 }: Omit<UseStreamRuntimeOptions, "cloud">) => {
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const externalId = useAuiState((s) => s.threadListItem.externalId) as
     | string
     | null;
 
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const stream = useStream({
     ...streamOptions,
     threadId: externalId,
   });
 
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const [toolStatuses, setToolStatuses] = useState<
     Record<string, ToolExecutionStatus>
   >({});
@@ -127,21 +131,25 @@ const useStreamThreadRuntime = ({
   );
   const effectiveIsRunning = stream.isLoading || hasExecutingTools;
 
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const threadMessages = useExternalMessageConverter({
     callback: convertLangChainBaseMessage,
     messages: stream.messages as LangChainBaseMessage[],
     isRunning: effectiveIsRunning,
   });
 
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const [runtimeRef] = useState(() => ({
     get current() {
       return runtime;
     },
   }));
 
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const streamRef = useRef(stream);
   streamRef.current = stream;
 
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const toolInvocations = useToolInvocations({
     state: {
       messages: threadMessages,
@@ -169,16 +177,19 @@ const useStreamThreadRuntime = ({
     setToolStatuses,
   });
 
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const extras = useMemo(
     (): LangChainRuntimeExtras => ({
       [symbolLangChainRuntimeExtras]: true,
       interrupt: stream.interrupt,
       interrupts: stream.interrupts,
       submit: stream.submit,
+      values: stream.values,
     }),
-    [stream.interrupt, stream.interrupts, stream.submit],
+    [stream.interrupt, stream.interrupts, stream.submit, stream.values],
   );
 
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const runtime = useExternalStoreRuntime({
     isRunning: effectiveIsRunning,
     messages: threadMessages,
@@ -254,6 +265,7 @@ export const useStreamRuntime = ({
   const cloudAdapter = useCloudThreadListAdapter({ cloud });
   return useRemoteThreadListRuntime({
     runtimeHook: function RuntimeHook() {
+      // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
       return useStreamThreadRuntime(optionsRef.current);
     },
     adapter: cloudAdapter,
@@ -288,3 +300,28 @@ export const useLangChainSubmit = () => {
     return submit(values, options);
   };
 };
+
+/**
+ * Read a custom LangGraph state key from the current thread. Mirrors
+ * `useStream().values[key]` from `@langchain/react` and updates when the
+ * stream emits new state.
+ *
+ * @example
+ * ```tsx
+ * const todos = useLangChainState<Todo[]>("todos");
+ * const files = useLangChainState<Record<string, string>>("files", {});
+ * ```
+ */
+export function useLangChainState<T>(key: string): T | undefined;
+export function useLangChainState<T>(key: string, defaultValue: T): T;
+export function useLangChainState<T>(
+  key: string,
+  defaultValue?: T,
+): T | undefined {
+  return useAuiState((s) => {
+    const extras = s.thread.extras;
+    if (!extras) return defaultValue;
+    const value = asLangChainRuntimeExtras(extras).values[key] as T | undefined;
+    return value !== undefined ? value : defaultValue;
+  });
+}