refactor(agent-core-v2): carry the context fold cursor in state and converge fold/projection internals - #2875
refactor(agent-core-v2): carry the context fold cursor in state and converge fold/projection internals#28757Sageer wants to merge 5 commits into
Conversation
…onverge fold/projection internals
- ContextModel state is now { messages, fold }: the loop-event fold cursor
(openStepUuid / pending / deferred) lives in the state instead of a
module-level WeakMap keyed by array identity, so wholesale replacements
(undo / clear / compaction / swarm exit) reset it structurally via
EMPTY_FOLD instead of a manual resetFold at five call sites.
- The display transcript and the wire model now share one generic fold
kernel (FoldFrame / FoldEntryAdapter), eliminating the mirrored second
implementation. Events tagged with a non-open step uuid are dropped and
step.end settles only the step it names — defensive in abnormal streams,
identical on well-formed ones (v1 replay unaffected).
- IAgentContextProjectorService converges to project(messages, policy) with
a ProjectionPolicy data object; llmRequester builds the policy from retry
state instead of selecting among four methods.
- Blob rehydrate now also covers messages still deferred in the fold cursor.
- ContextState is deeply frozen at the op boundary to preserve the consumer
immutability the wire's shallow freeze gave the bare array state.
|
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8780d6a0d8
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| // Asserts after EVERY prefix of the stream that the transcript's current | ||
| // conversation (the tail of `foldedLength` entries) matches the model fold. | ||
| // Compaction pauses the check until the next clear: the display's | ||
| // foldedLength is a UI collapse metric (kept users + summary marker, and | ||
| // legacy records put the summary first in the model but last in the | ||
| // display), so the two views diverge there BY DESIGN; clear realigns them. |
There was a problem hiding this comment.
This newly added inline explanation sits inside a helper body, and there are similar scenario notes in the added test case below; package guidance for agent-core-v2 requires comments to live only in the top-of-file /** */ block, so please move the parity rationale into the file header or encode it in helper/test names instead.
AGENTS.md reference: packages/agent-core-v2/AGENTS.md:L36-L38
Useful? React with 👍 / 👎.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2d419454df
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| openStepUuid: string | undefined; | ||
| pending: Set<string>; | ||
| deferred: ContextMessage[]; | ||
| /** A fold position: the entries reduced so far plus the fold cursor. */ |
There was a problem hiding this comment.
This new declaration-level JSDoc sits outside the top-of-file module header; in agent-core-v2, comments are restricted to the file header rather than beside declarations. Please move the fold-frame explanation into the module header or encode it in the exported names, and apply the same cleanup to the other added declaration comments in this change.
AGENTS.md reference: packages/agent-core-v2/AGENTS.md:L36-L38
Useful? React with 👍 / 👎.
|
@codex review |
|
Codex Review: Didn't find any major issues. Chef's kiss. Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
|
@codex review |
|
Codex Review: Didn't find any major issues. Nice work! Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
…s in context memory - isVacuousContentPart and dehydrateRecord now switch exhaustively over ContentPart / LoopRecordedEvent variants, so a new variant fails compilation until it takes an explicit position - the transcript/model parity comparator spreads whole messages and masks only summary content, so new ContextMessage fields join the comparison automatically - correct two stale header comments: local message ids persist with append_message records, and undo's prompt-owned-injection pairing depends on them after a resume
|
@codex review |
|
Codex Review: Didn't find any major issues. Already looking forward to the next diff. Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
2 participants
Related Issue
No linked issue — this is a preventive internal refactor of the agent-core-v2 context subsystem; the problem is explained below.
Problem
Three structural gaps in the context subsystem were held together by convention rather than by structure:
openStepUuid/pending/deferred) lived in a module-levelWeakMapkeyed by state-array identity. Every wholesale state replacement (undo / clear / compaction / swarm-mode exit) had to remember to callresetFold— five call sites in a different module from the cursor's definition, with no compile-time signal if forgotten.loopEventFold) and the display transcript fold (contextTranscript) — kept in sync only by a doc comment ("semantics mirror the v1 fold exactly"), so any semantic change could silently drift the display from the live view.project/projectStrict/projectMediaDegraded/projectMediaStripped), and the LLM requester selected among them with nested ternaries keyed by retry state.What changed
ContextModelstate is now{ messages, fold }. Wholesale replacements reset the cursor by returningEMPTY_FOLDin the samereturnthat replaces the messages — there is no out-of-band reset left to forget.ContextStateis deeply frozen at the op boundary to preserve the consumer immutability the wire's shallow freeze gave the bare array state. Blob rehydrate now also covers messages still deferred in the cursor (previously their blob references were never resolved after a restore).FoldFrame<E>+FoldEntryAdapter<E>); the wire model folds bare messages and the display transcript folds time-stamped entries through the same kernel, keeping only its display bookkeeping (times,foldedLength,clearFloor). Two deliberate defensive tightenings fall out of the unification: events tagged with a non-open step uuid are dropped instead of mis-appended to a retried step, andstep.endsettles only the step it names. Well-formed streams (including v1 replay records) are unaffected.project(messages, policy). Projection variability is now data (ProjectionPolicy { wire, media }); the requester builds the policy from retry state instead of selecting among four methods. Repair telemetry is unchanged.Verification: agent-core-v2 full suite green (312 files / 4906 tests, including new transcript↔model prefix-parity tests and fold-reset assertions), typecheck, build, lint (0 errors), import-boundary check, plus downstream
kap-server/klienttypechecks.No journal record format changes (v1/v2 replay compatibility preserved); the
IAgentContextMemoryServicecontract is untouched (its ~20 consumers needed no changes).Checklist
gen-changesetsskill, or this PR needs no changeset. (No changeset: agent-core-v2 internal refactor, not user-perceivable.)gen-docsskill, or this PR needs no doc update. (No user-facing behavior change.)