Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
50998de
feat(core): add typed application state to the session contract
blove Nov 18, 2026
bf1780d
feat(ag-ui): type the session's state and publish it in the core view
blove Nov 18, 2026
3894f08
feat(ag-ui): make the session a core AgentSession
blove Nov 18, 2026
016a123
test(ag-ui): expect core fields on the session snapshot in the packag…
blove Nov 18, 2026
72675d9
feat(core): add interrupts, resume and child agents to the session co…
blove Nov 19, 2026
d666233
feat(langgraph): answer interrupts by id through the core resume command
blove Nov 19, 2026
50984f8
test(native-conversation): send the unmatched-id diagnostic through t…
blove Nov 19, 2026
9812d7c
Merge remote-tracking branch 'origin/main' into blove/ag-ui-typed-ses…
blove Nov 19, 2026
84473df
Merge remote-tracking branch 'origin/main' into HEAD
blove Nov 19, 2026
f43223d
Merge remote-tracking branch 'origin/main' into blove/core-interrupts…
blove Nov 19, 2026
a73307f
Merge remote-tracking branch 'origin/main' into blove/core-interrupts…
blove Nov 19, 2026
a9376fc
Merge remote-tracking branch 'origin/main' into blove/core-interrupts…
blove Nov 19, 2026
ca50ac4
Merge the final head of #1658 into blove/ag-ui-session-is-agent-session
blove Nov 19, 2026
1e81b58
Merge the squash of #1658 into blove/ag-ui-session-is-agent-session (…
blove Nov 19, 2026
2d3100d
Merge remote-tracking branch 'origin/main' into blove/ag-ui-session-i…
blove Nov 19, 2026
ef1042c
Merge branch 'blove/core-interrupts-subagents' into blove/ag-ui-core-…
blove Nov 19, 2026
6815ffd
Merge remote-tracking branch 'origin/main' into HEAD
blove Nov 19, 2026
d31ac51
docs(ag-ui): the candidate emits the core session, not a view
blove Nov 19, 2026
1b4a8f8
feat(ag-ui): answer interrupts through the core resume command and pu…
blove Nov 19, 2026
f015faf
Merge the final head of #1659 into blove/ag-ui-core-resume
blove Nov 19, 2026
251be93
Merge the squash of #1659 into blove/ag-ui-core-resume (already merge…
blove Nov 19, 2026
51833c0
Merge remote-tracking branch 'origin/main' into blove/ag-ui-core-resume
blove Nov 19, 2026
24df2a7
feat(langgraph): publish child graphs as core child agents
blove Nov 19, 2026
0b3b702
test(parity): list the AG-UI child projection in the reviewed candida…
blove Nov 19, 2026
eb7dec8
test(cockpit): answer the Strands fixture's pauses through the core r…
blove Nov 20, 2026
0952bcf
Merge branch 'blove/ag-ui-core-resume' into blove/langgraph-core-suba…
blove Nov 20, 2026
47b6bb8
test(parity): count the child-agent projection and check child tool c…
blove Nov 20, 2026
a912975
Merge the squash of #1677 into blove/langgraph-core-subagents (alread…
blove Nov 20, 2026
670c133
Keep the canonical demo bundle budget from main (#1679)
blove Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 35 additions & 9 deletions libs/langgraph/src/runtime/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -317,15 +317,15 @@ panel or telemetry: `getSnapshot()` returns a frozen `LangGraphLifecycle` and
`useSyncExternalStore`. Each value is epoch milliseconds on this clock, null
until its milestone happens.

| Value | Stamped |
| --------------------- | -------------------------------------------------------------- |
| `streamStartedAt` | The first event to arrive on any run's stream. |
| `streamErrorAt` | The most recent published failure, as `{ at, kind }`. |
| `interruptReceivedAt` | The first time the session held a pending interrupt. |
| `interruptResolvedAt` | The most recent `resume` the session accepted. |
| `threadPersistedAt` | The first history read that returned saved checkpoints. |
| `toolCallStartedAt` | The first time the session held a tool call. |
| `toolCallCompletedAt` | The first time a tool call was complete or failed. |
| Value | Stamped |
| --------------------- | ------------------------------------------------------- |
| `streamStartedAt` | The first event to arrive on any run's stream. |
| `streamErrorAt` | The most recent published failure, as `{ at, kind }`. |
| `interruptReceivedAt` | The first time the session held a pending interrupt. |
| `interruptResolvedAt` | The most recent `resume` the session accepted. |
| `threadPersistedAt` | The first history read that returned saved checkpoints. |
| `toolCallStartedAt` | The first time the session held a tool call. |
| `toolCallCompletedAt` | The first time a tool call was complete or failed. |

A session serves one thread, so nothing is reset: where the Angular adapter
clears its `AgentLifecycle` on `switchThread()`, a session for another thread
Expand Down Expand Up @@ -365,6 +365,32 @@ paused. The preflight detects already-observed consumption, but it is not an ato
server claim. Applications must coordinate responders to the same task. Distinct
checkpoint branches do not provide independent opposing decisions on one task.

## Child agents

`snapshot.subgraphs` holds one entry for each child graph the run reported, with
its `namespace`, its own `messages` and `toolCalls`, its `state`, `interrupts`
and `error`. `snapshot.subagents` publishes the same children as the core
contract's child agents, one for each and in the same order, so a component
written for core sessions can show them:

- `id` is the namespace path as JSON, which stays unique whatever a segment
contains. `parentId` is the `id` of the enclosing child graph, and is absent
for a child of the root graph. `namespace` is kept alongside.
- `name` is the node that started the child: the part of the last namespace
segment before its `:`.
- `messages` and `toolCalls` are the child graph's own, the same references as
in `subgraphs`. The root `messages` and `toolCalls` do not repeat them.
- `status` is `error` for a child that failed, with the display text in
`error`, and `running` while the root run is going. After the run, a child
whose last message succeeded is `complete`, one a pause stopped is still
`running` because a resume continues it, and any other child is `unknown`.
- LangGraph does not relate a child graph to a tool call, so `toolCallId` and
`description` are never set.

A child agent keeps its reference while its child graph and status are
unchanged. Child agents give no command authority: answering a pause is the
root session's `resume`.

## Thread directory

`createLangGraphThreadDirectory` in `thread-directory.ts` implements the
Expand Down
14 changes: 13 additions & 1 deletion libs/langgraph/src/runtime/langgraph-snapshot.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,10 @@ import type {
DeepReadonly,
PlainValue,
Message,
ToolCall,
ToolContract,
} from '@threadplane/core';
import type { LangGraphSubagent } from './subagent-projection.js';
import type { Interrupt, ThreadState } from '@langchain/langgraph-sdk';

/** Compact metadata from an explicitly loaded page, without repeated state data. */
Expand Down Expand Up @@ -39,20 +41,25 @@ export type LangGraphSnapshotState<TState = unknown> = unknown extends TState
export interface LangGraphSubgraph {
readonly namespace: readonly string[];
readonly messages: readonly Message[];
/** The child graph's own tool calls, referenced by `Message.toolCallIds` in `messages`. */
readonly toolCalls: readonly ToolCall[];
/** A child graph's state. It is never checked against the session's declaration. */
readonly state: LangGraphState | undefined;
readonly interrupts: readonly LangGraphWireInterrupt[];
readonly error?: AgentError;
}

/** What a publication supplies: the session derives `subagents` from `subgraphs`. */
export type LangGraphPublication = Omit<LangGraphSnapshot, 'subagents'>;

/** Backend-private extension; the core snapshot remains backend-independent. */
export type LangGraphSnapshot<
TTools extends { [K in keyof TTools]: ToolContract } = Record<
string,
ToolContract
>,
TState = unknown
> = Omit<AgentSnapshot<TTools, TState>, 'interrupts'> & {
> = Omit<AgentSnapshot<TTools, TState>, 'interrupts' | 'subagents'> & {
/** Last explicit history page; undefined until loaded. Not a live branch tree. */
readonly history: readonly LangGraphHistoryEntry[] | undefined;
/**
Expand All @@ -68,4 +75,9 @@ export type LangGraphSnapshot<
readonly reconnect?: { readonly runId: string };
readonly interrupts: readonly LangGraphInterrupt[];
readonly subgraphs: readonly LangGraphSubgraph[];
/**
* The child graphs in `subgraphs` as the core contract's child agents, one
* for each and in the same order.
*/
readonly subagents: readonly LangGraphSubagent[];
};
22 changes: 21 additions & 1 deletion libs/langgraph/src/runtime/ownership.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,13 @@ import {
} from '@threadplane/core';
import type {
LangGraphInterrupt,
LangGraphPublication,
LangGraphWireInterrupt,
LangGraphSnapshot,
LangGraphSubgraph,
LangGraphState,
} from './langgraph-snapshot.js';
import { projectSubagents } from './subagent-projection.js';

// Only objects projected here are trusted. Object.isFrozen on external input is
// insufficient: its children may still be mutable. The weak set retains no data.
Expand Down Expand Up @@ -324,7 +326,7 @@ export function ownSnapshot(

/** One backend aggregate, composing the core fields and owned application data. */
export function ownLangGraphSnapshot(
input: LangGraphSnapshot,
input: LangGraphPublication,
previous?: LangGraphSnapshot
): LangGraphSnapshot {
const core = ownSnapshot(input, previous);
Expand All @@ -333,6 +335,12 @@ export function ownLangGraphSnapshot(
previous?.history as PlainValue
) as LangGraphSnapshot['history'];
const subgraphs = ownSubgraphs(input.subgraphs, previous?.subgraphs);
// Derived here, so the children always agree with the published child graphs.
const subagents = projectSubagents(
subgraphs,
core.status,
previous?.subagents
);
const state = ownValueWithSharing(input.state, previous?.state) as
| LangGraphState
| undefined;
Expand All @@ -355,6 +363,7 @@ export function ownLangGraphSnapshot(
stateIssues === previous?.stateIssues &&
interrupts === previous?.interrupts &&
subgraphs === previous?.subgraphs &&
subagents === previous?.subagents &&
reconnect === previous?.reconnect
)
return previous;
Expand All @@ -371,6 +380,7 @@ export function ownLangGraphSnapshot(
...(stateIssues ? { stateIssues } : {}),
interrupts,
subgraphs,
subagents,
...(reconnect ? { reconnect } : {}),
});
}
Expand All @@ -390,6 +400,13 @@ export function ownSubgraph(
ownMessage,
sameMessage
);
// A restored child graph may predate `toolCalls`.
const toolCalls = ownArray(
input.toolCalls ?? [],
previous?.toolCalls,
ownToolCall,
sameToolCall
);
const state = ownValueWithSharing(input.state, previous?.state) as
| LangGraphState
| undefined;
Expand All @@ -404,6 +421,7 @@ export function ownSubgraph(
previous &&
namespace === previous.namespace &&
messages === previous.messages &&
toolCalls === previous.toolCalls &&
state === previous.state &&
interrupts === previous.interrupts &&
error === previous.error
Expand All @@ -412,6 +430,7 @@ export function ownSubgraph(
return freeze({
namespace,
messages,
toolCalls,
state,
interrupts,
...(error ? { error } : {}),
Expand All @@ -430,6 +449,7 @@ export function ownSubgraphs(
a === b ||
(a.namespace === b.namespace &&
a.messages === b.messages &&
a.toolCalls === b.toolCalls &&
a.state === b.state &&
a.interrupts === b.interrupts &&
sameError(a.error, b.error))
Expand Down
28 changes: 14 additions & 14 deletions libs/langgraph/src/runtime/publication.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ import { streamingDelivery } from '@threadplane/core';
import { describe, expect, it } from 'vitest';
import { createPublication } from './publication';
import { deferred } from './testing/deferred';
import type { LangGraphSnapshot } from './langgraph-snapshot';
import type { LangGraphPublication } from './langgraph-snapshot';

function snapshot(content = 'one'): LangGraphSnapshot {
function snapshot(content = 'one'): LangGraphPublication {
return {
status: 'idle',
history: undefined,
Expand Down Expand Up @@ -36,7 +36,7 @@ describe('private snapshot publication', () => {
it('publishes reasoning-only changes, owns queued getter strings and suppresses equal values', () => {
const publication = createPublication(snapshot());
let reasoning = 'Captured';
const input = (): LangGraphSnapshot => ({
const input = (): LangGraphPublication => ({
...snapshot(),
messages: [
{
Expand All @@ -47,7 +47,7 @@ describe('private snapshot publication', () => {
},
],
});
const seen: LangGraphSnapshot[] = [];
const seen: LangGraphPublication[] = [];
publication.subscribe(() => {
seen.push(publication.getSnapshot());
if (seen.length === 1) {
Expand Down Expand Up @@ -78,11 +78,11 @@ describe('private snapshot publication', () => {
const citations = [
{ id: 'c', index: 1, title: 'Original', extra: { tags: ['original'] } },
];
const input = (): LangGraphSnapshot => ({
const input = (): LangGraphPublication => ({
...snapshot('two'),
messages: [{ ...snapshot('two').messages[0], citations }],
});
const seen: LangGraphSnapshot[] = [];
const seen: LangGraphPublication[] = [];
publication.subscribe(() => {
seen.push(publication.getSnapshot());
if (seen.length === 1) {
Expand Down Expand Up @@ -138,7 +138,7 @@ describe('private snapshot publication', () => {
if (populated) array[0] = 1;
return array;
};
const input = (length: number): LangGraphSnapshot => ({
const input = (length: number): LangGraphPublication => ({
...snapshot(),
toolCalls: [
{
Expand Down Expand Up @@ -230,7 +230,7 @@ describe('private snapshot publication', () => {
...snapshot('Invalid'),
state: { count: 9 },
interrupts: [{ value: new Date() }],
} as unknown as LangGraphSnapshot)
} as unknown as LangGraphPublication)
).toThrow(TypeError);
expect(publication.getSnapshot()).toBe(before);
});
Expand All @@ -241,20 +241,20 @@ describe('private snapshot publication', () => {
publication.publish({
...snapshot('candidate'),
state: { bad: new Date(0) },
} as unknown as LangGraphSnapshot)
} as unknown as LangGraphPublication)
).toThrow(TypeError);
expect(publication.getSnapshot()).toBe(before);
});

it('owns application values and suppresses equal queued aggregate publications', () => {
const data = { stable: { x: 1 }, count: 1 };
const publication = createPublication({ ...snapshot(), state: data });
const first = publication.getSnapshot() as LangGraphSnapshot;
const first = publication.getSnapshot() as LangGraphPublication;
expect(first.state).toEqual(data);
expect(first.state).not.toBe(data);
data.stable.x = 9;
expect(first.state?.['stable']).toEqual({ x: 1 });
const seen: LangGraphSnapshot[] = [];
const seen: LangGraphPublication[] = [];
for (let index = 0; index < 2; index++)
publication.subscribe(() => {
if (publication.getSnapshot().status === 'running') {
Expand All @@ -268,7 +268,7 @@ describe('private snapshot publication', () => {
}
});
publication.subscribe(() =>
seen.push(publication.getSnapshot() as LangGraphSnapshot)
seen.push(publication.getSnapshot() as LangGraphPublication)
);
publication.publish({ ...first, status: 'running' });
expect(seen).toHaveLength(2);
Expand All @@ -288,7 +288,7 @@ describe('private snapshot publication', () => {
toolCalls: [{ ...input.toolCalls[0], args: new Date() }],
};
expect(() =>
createPublication(invalid as unknown as LangGraphSnapshot)
createPublication(invalid as unknown as LangGraphPublication)
).toThrow(TypeError);
const publication = createPublication({
...input,
Expand All @@ -300,7 +300,7 @@ describe('private snapshot publication', () => {
toolCalls: [
{ id: 't', name: 'search', status: 'running', args: new Date() },
],
} as unknown as LangGraphSnapshot)
} as unknown as LangGraphPublication)
).toThrow(TypeError);
});
it('caches repeated reads per session and observes only actual changes', () => {
Expand Down
6 changes: 3 additions & 3 deletions libs/langgraph/src/runtime/publication.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
import type { AgentSessionCustomEvent } from '@threadplane/core';
import type { LangGraphSnapshot } from './langgraph-snapshot.js';
import type { LangGraphPublication } from './langgraph-snapshot.js';
import { ownLangGraphSnapshot } from './ownership.js';

/** Backend-private publication. Listener failures are reported once to the
* optional callback and otherwise ignored; reporter failures are contained too.
* Neither kind of failure changes execution state or rejects a command. */
export function createPublication(
initial: LangGraphSnapshot,
initial: LangGraphPublication,
reportListenerError: (error: unknown) => void = () => undefined
) {
let current = ownLangGraphSnapshot(initial);
Expand Down Expand Up @@ -36,7 +36,7 @@ export function createPublication(
}
}

function publish(input: LangGraphSnapshot): void {
function publish(input: LangGraphPublication): void {
// Capture external ingress now, including when a listener queues a publish.
const captured = ownLangGraphSnapshot(input, current);
schedule(() => {
Expand Down
1 change: 1 addition & 0 deletions libs/langgraph/src/runtime/session-lifecycle.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ describe('neutral session ownership', () => {
state: undefined,
interrupts: [],
subgraphs: [],
subagents: [],
});
expect(first).not.toHaveBeenCalled();
expect(a.stream).not.toHaveBeenCalled();
Expand Down
Loading
Loading