Skip to content

feat(core): add interrupts, resume and child agents to the session contract - #1675

Closed
blove wants to merge 7 commits into
mainfrom
blove/core-interrupts-subagents
Closed

blove wants to merge 7 commits into
mainfrom
blove/core-interrupts-subagents

Conversation

@blove

@blove blove commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What

Interrupts, resume and child agents join the framework-neutral session contract, and the LangGraph session supplies interrupts and resume through it.

Stacked on #1654 (typed state). Retarget to main once that lands.

Core (@threadplane/core)

  • AgentSnapshot.interrupts?: readonly AgentInterrupt[]: what a paused run waits on. Each has an id, and may carry the backend's value, a reason, a display message and a toolCallId.
  • AgentSession.resume?(responses, options): answers pending interrupts by id. A response is { interruptId, status: 'resolved', value? } or { interruptId, status: 'cancelled' }.
  • AgentSnapshot.subagents?: readonly AgentSubagent[]: child agents in start order, each with id, status (running, complete, error, unknown), its own messages and toolCalls, and optional name, description, toolCallId, parentId, error.
  • createFakeAgentSession publishes both fields (setInterrupts, setSubagents), records resume calls, removes answered interrupts and takes an onResume handler.

All three are optional, so a session that cannot pause or reports no children is unchanged.

LangGraph native session (breaking)

  • Every published interrupt has an id: the backend's when it sent one, breakpoint for a static breakpoint, the position (interrupt-0) otherwise. LangGraphInterrupt is now AgentInterrupt plus the wire metadata; child observations in subgraphs keep the wire shape as LangGraphWireInterrupt.
  • resume(value?) becomes resume(responses), the core command. There is one resume command, as decided for this milestone.
    • One pending interrupt: its response's value is sent as the resume value, exactly as before. No value sends no command, as before.
    • Several pending: the answered ones go as one map keyed by backend id, the form callers already built by hand.
    • Rejected before anything is sent: an id that is not pending, an id named twice, an empty list, and cancelled (LangGraph has no cancelled response; a refusal is a value the graph reads).

Callers moved to the new command

  • LangGraph runtime specs (through a private answerPending test helper) and type tests.
  • Cockpit React examples: langgraph/interrupts, chat/interrupts, deep-agents/filesystem, plus the local state types in chat/debug, chat/subagents, chat/threads and chat/tool-calls that redeclared interrupts.
  • examples/chat/native: the approval decision, its fixture expectations and the provider tooling.
  • Parity fixtures and the packed-consumer type probes (runtime-consumer.mjs, langgraph-candidate/installed-types.ts, ag-ui-candidate/installed-types.ts).

Wire changes to know about

Two callers used to wrap a single answer in an id-keyed map. With one interrupt pending the session now sends the plain value, so their expected request bodies changed:

  • examples/chat/native: command.resume is 'approved' or 'denied', not { [id]: 'approved' }.
  • fixtures/react-parity/runtime: the final approval sends true, not { 'final-approval': true }.

The provider-routing diagnostic in examples/chat/native/tooling/approval-provider-consumer.ts sent a resume for an id that is not pending. The session now rejects that locally (covered by its own specs), so the diagnostic sends the id-keyed command through the SDK client instead. Its request footprint changes from 46 to 45 requests.

Not in this PR

  • AG-UI: its session keeps resume(pauseId, responses) here. Moving it to the core command belongs on top of feat(ag-ui): make the session a core AgentSession #1659, which makes that session a core AgentSession. Until then the two PRs disagree on that one type, so whichever lands second needs that follow-up.
  • LangGraph subagents (from subgraphs) and AG-UI subagents: the core shape is here; the sessions supply it next.
  • Chat reading interrupts and subagents from the session.
  • Website docs. The LangGraph interrupts guide describes resume in prose only and stays accurate.

Verification

  • nx run-many -t runtime-quality,runtime-type-tests,test,type-tests,lint -p core,langgraph,ag-ui,react,angular: pass. LangGraph runtime: 1086 tests.

  • Mutation checks on the new LangGraph logic (not-pending check, cancelled check, published ids, single-interrupt value): each fails tests, then restored.

  • nx run-many -t test,lint for the seven touched cockpit React projects: pass. All 41 cockpit React apps type-check against source with a scratch config (the per-app build type check needs the packed packages).

  • examples/chat/native/tooling/run.mjs test: 513 pass.

  • Package lane after a fresh build of core, content, angular, react: verify-boundaries.mjs --built, verify-packages.mjs, verify-angular-package.mjs, verify-langgraph-candidate.mjs, verify-ag-ui-candidate.mjs: pass.

  • inventory.mjs --check --drift warn: valid.

  • nx run native-conversation-react:provider-test (canonical provider, 45-request footprint): pass.

Not run locally: Playwright e2e (cockpit, website), browser-proof.mjs, and the AG-UI client-tools and Mastra verifiers.

🤖 Generated with Claude Code

AgentSession and AgentSnapshot take a second type parameter for application
state. The snapshot gains an optional, deeply readonly `state`, and `submit`
accepts `{ message, state }` with a partial state as well as plain text.

A session is told its state type by one declaration: `type<T>()` for the type
alone, or any Standard Schema value to also check each state as it arrives.
`readState` runs that check for session implementations. The fake session
holds, sets and validates state the same way.

No backend session supplies `state` yet; LangGraph and AG-UI follow.
…ntract

The snapshot gains optional interrupts and subagents, and the session an
optional resume(responses) that answers pending interrupts by id. The fake
session publishes both fields and records resume calls.
Every published interrupt has an id, and resume takes the core contract's
responses in place of a bare value. One pending interrupt receives its
response's value; several are answered as one map keyed by backend id.
Callers in the cockpit examples, the native conversation example and the
parity fixtures move to the new command.
…he client only

The raw session has loaded nothing at that point, so its resume rejects for
a missing pause, not for the unmatched id. The session's own specs cover
the rejection; the diagnostic keeps the provider routing evidence.
Base automatically changed from blove/core-typed-session-state to main November 19, 2026 18:38
@blove

blove commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by #1677, which carries all of this PR plus the AG-UI changes it now needs to compile against main (after #1659).

@blove blove closed this Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant