private state channel: exposed when streaming values?

[fauxbytes]

Checked other resources

• I added a very descriptive title to this issue.
• I searched the LangGraph.js documentation with the integrated search.
• I used the GitHub search to find a similar question and didn't find it.
• I am sure that this is a bug in LangGraph.js rather than my code.
• The bug is not resolved by updating to the latest stable version of LangGraph (or the specific integration package).

Example Code

Using an example similar to the one in the docs:

import { z } from 'zod';
import { START, StateGraph } from '@langchain/langgraph';

const overall = z.object({question: z.string(), answer: z.string()});
const query = z.object({query: z.string()});
const docs = z.object({docs: z.array(z.string())});
const output = z.object({...overall.shape, ...docs.shape});
const node1 = async (state:z.infer<typeof overall>) => ({query: state.question + ' rephrased as a query!'});
const node2 = async (state:z.infer<typeof query>) => ({docs: [state.query, 'some random document']});
const node3 = async (state:z.infer<typeof output>) => ({answer: state.docs.concat([state.question]).join('\n\n')});
export const graph = new StateGraph(overall)
  .addNode(node1.name, node1)
  .addNode(node2.name, node2, {input: query})
  .addNode(node3.name, node3, {input: output})
  .addEdge(START, node1.name)
  .addEdge(node1.name, node2.name)
  .addEdge(node2.name, node3.name)
  .compile();

invokeing the graph indeed keeps the private state hidden:

graph.invoke({question: 'How are you?'}).then(console.log).catch(console.error);

{
  question: 'How are you?',
  answer: 'How are you? rephrased as a query!\n\nsome random document\n\nHow are you?'
}

Yet, when streaming, full state is returned, including private data:

graph.stream({question: 'How are you?'}, {streamMode: 'values'})
  .then(async stream => {
    for await (const event of stream) console.log(event);
  });

//...
{
  question: 'How are you?',
  answer: 'How are you? rephrased as a query!\n\nsome random document\n\nHow are you?',
  query: 'How are you? rephrased as a query!',
  docs: [ 'How are you? rephrased as a query!', 'some random document' ]
}

Error Message and Stack Trace (if applicable)

No response

Description

Think streaming by value violates the notion of state being "private".

In addition, this section mentions a PrivateState. Could not locate such construct in docs, source code.

System Info

package manager: pnpm
os: win11

$ cat package.json |jq '{dependencies,devDependencies}'
{
  "dependencies": {
    "@langchain/core": "^0.3.66",
    "@langchain/langgraph": "^0.3.8",
    "@langchain/openai": "^0.6.2",
    "dotenv": "^17.2.0",
    "langchain": "^0.3.30",
    "sqlite": "^5.1.1",
    "typeorm": "^0.3.25",
    "zod": "^4.0.5"
  },
  "devDependencies": {
    "@types/node": "^24.0.14",
    "ts-node": "^10.9.2",
    "typescript": "^5.8.3"
  }
}

$ node -v
v20.18.3