docs: fix checkpointer guidance and document chat-sidenav - #813
Merged
Conversation
Found by building both tutorial apps from scratch against the published packages and running them. - langgraph/persistence: the guide opened with "every LangGraph agent needs a checkpointer" and showed `compile(checkpointer=MemorySaver())`, while the quickstart tells you to run `langgraph dev`. Doing both does not degrade — the platform rejects a graph carrying its own checkpointer and the server exits on startup with GraphLoadError. Split the guidance by how the graph is served and quote the actual failure. - chat/components/chat-sidenav: the composition had no docs page and no JSDoc. Its ng-content slots are all named, so a <chat> placed inside is silently dropped — you get a sidebar and an empty pane with no error. Add the page (inputs/outputs, Thread contract, ThreadActionAdapter) and a JSDoc example showing the chat as a sibling. - chat/client-tools: client-tool results come back keyed by tool_call_id with no tool name, so the intuitive server-side filter by name matches nothing, silently. Document the id-based lookup. This is fixed by the protocol on AG-UI, whose ToolMessageSchema has no name field and parses in strip mode, so matching on the id is the portable approach. api-docs.json regenerated for the new JSDoc. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
blove
enabled auto-merge (squash)
August 14, 2026 03:55
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
This was referenced Aug 14, 2026
blove
added a commit
that referenced
this pull request
Aug 14, 2026
Pushes to main do not cancel in-progress runs (cancel-in-progress is true only for pull_request), so runs serialize and a slower older run can reach its deploy job long after a newer commit has already shipped. It then rebuilds --prod from its own older checkout and promotes it, silently overwriting production. Observed 2026-08-14: the CI run for #813 promoted at 04:37, replacing the deployment that had published two blog posts from #814 at 04:13. Both posts 404'd until the next merge happened to redeploy them. Nothing failed; CI was green the whole time. Add a freshness check to each job that promotes: resolve the current tip of main and skip promotion when it no longer matches github.sha, logging a warning so the skip is visible. Setup and change-detection steps still run; only the production-touching steps are gated. Covers all five promotions — website, cockpit, Angular examples, the canonical demo, and the ag-ui demo. The last of those was found by the new spec assertion, not by reading the file. Notes on the implementation: - Uses `git ls-remote`, not `git fetch --depth=1`: a shallow fetch would mark the deploy job's full clone shallow and break the --affected history checks that run right after it. - Fails loudly when the tip cannot be resolved, rather than treating an empty result as "stale" and silently skipping every deploy. - Gates the demo build-stamp verification too, since it asserts the deployed SHA equals this run's SHA. This narrows the race to the build window rather than closing it entirely; a commit landing mid-build can still be overtaken. Fixing that completely means either serializing promotions or having Vercel resolve the alias, which is a larger change. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three fixes found by building both tutorial apps from scratch against the published
@threadplane/*@0.0.57packages and driving them in a browser against live backends.1. The persistence guide's checkpointer advice breaks
langgraph devdocs/langgraph/guides/persistence.mdxopened with "Every LangGraph agent needs a checkpointer" and showedbuilder.compile(checkpointer=MemorySaver()). The quickstart, meanwhile, tells you to runlanggraph dev.Doing both doesn't degrade gracefully — the server refuses to load the graph and exits:
Verified by compiling a checkpointer into a graph and starting
langgraph devagainst it. The guide now splits by how the graph is served: no checkpointer when serving throughlanggraph dev/ Platform (usePOSTGRES_URI), checkpointers when you embed the graph in your own process — includingag-ui-langgraphservers, which need one foraget_state.2.
<chat-sidenav>had no docs page and no JSDocEvery
ng-contentslot on the composition is named, so a<chat>placed between the tags is silently dropped — you get a sidebar and an empty pane, no error. This is the opposite of<chat-sidebar>, which does project app content. It cost me a debugging pass while writing the tutorial.Adds
docs/chat/components/chat-sidenav.mdx(inputs, outputs,Threadcontract,ThreadActionAdapter, drawer mode) plus a JSDoc block showing the chat as a sibling. Also documents two contract facts that are easy to miss:statusis not auto-filtered andpinnedis not auto-sorted — consumers pre-filter and pre-sort.3. Client-tool results carry no tool name
A client-tool result arrives as a tool message keyed by
tool_call_idwith noname, so the intuitive server-side filter matches nothing — silently, forever:Documented with the id-based lookup. Worth noting this is not fixable on the AG-UI side:
ToolMessageSchemain@ag-ui/coredefines onlyid/role/content/toolCallId/ optionalerror/encryptedValue, and parses in strip mode, so an addednamewould be dropped on the wire. The LangGraph adapter could send one, but that would create cross-adapter asymmetry in the durable-write path (the subsystem behind #807/#809/#810) while "match on the id" stays the portable advice either way. Docs felt like the right call — happy to revisit if you'd rather have the field.Verification
nx lint chat,nx lint website— 0 errorslibs/chatvitest — 1102 passed / 123 filesapps/websitevitest — 12 failed / 76 passed, identical to a cleanmaincheckout (confirmed by stashing); no new failuresapi-docs.jsonregenerated and committed so the CI bot doesn't have to pushOne pre-existing failure is unrelated and left alone:
docs.spec.ts > auto-rendered API pages resolve generated entriesfails on main because the middleware "LangGraph.js Helpers" page is a group page whose title matches no single generated export.🤖 Generated with Claude Code