* 🏝️ fix: Let a No-Workspace Turn Carry a Remembered Approval Mode
A conversation set to run without attached workspaces failed every turn with
"The selected code approval mode is not permitted by the current policy" when
the reader had picked Accept edits or Full access for a workspace earlier.
With no attached target, the server validated the requested mode against an
empty policy that only allows ask. A turn with no attached target now accepts
any known mode, resolves it to ask for the run, and keeps the conversation's
stored mode instead of overwriting or unsetting it. Unknown values are still
rejected, and any attached target, including a subagent's, keeps the strict
check.
The composer treated an explicit no-workspace chat as still running on the
agent's default machine, so it kept offering and submitting the remembered
mode. It now offers no attached mode there, and the submit path sends ask
whenever the turn resolves to run without a workspace.
* fix: Leave an Unset Approval Mode Unset on a No-Workspace Turn
A turn without an attached target seeded the conversation's approval mode
from the request when the row stored none. A current client sends the gated
ask there, so the first no-workspace turn of a new chat wrote ask and
replaced the remembered pick the composer would otherwise keep offering.
Such a turn now only carries forward a mode the conversation already stores;
a stored mode still comes only from a turn that validated it against its
attached targets.
* fix: Gate the Approval Menu on the Resolved Workspace Mode and the Saved Conversation
The composer hid attached approval modes only for a chat that recorded a
no-workspace decision, while useCodeWorkspace also resolves one for a saved
chat with no recorded decision and for a draft still choosing. The approval
menu, the queued-turn snapshot, and the submit path now read the mode the
composer resolved, so the control matches what the turn sends.
A no-workspace turn kept the mode of the row admission loaded, but a turn
sent with overrideConvoId is saved under another conversation; the stored
mode is now read only when that row is the conversation being saved.
* fix: Preserve the Saved Conversation's Approval Mode Through a No-Workspace Turn
A no-workspace turn chose what to record from the row admission loaded, but
a turn sent with overrideConvoId is saved under another conversation while
its unsets are still computed from that loaded row, so either the source
row's mode was copied onto the target or the target's own mode was unset.
Such a turn now records no mode and declares codeApprovalMode preserved:
the conversation write skips it when computing unsets, so the stored mode of
whichever conversation the turn is saved under stays as it is, and a chat
that stores none keeps offering the remembered pick. Turns with attached
targets record exactly the mode they validated, as before.
* 🔗 feat(agents): use LibreChat prompt groups as agent instructions
Agents can link a prompt group revision or Production as their instructions. The link resolves at the start of each turn through a cached resolver. The cache clears on promote and delete. Editors without VIEW on the group see a restricted placeholder.
* fix: remove duplicate logger import from agent initialization tests
* fix: honor prompt management capabilities for linked agent instructions
* test: seed prompt manager capabilities in authorization fixtures
* fix: clear acknowledged linked prompt edits before version restore
* test: adapt merged chain coverage to prompt-aware payload helper
---------
Co-authored-by: Lia <lia@librechat.ai>
* 📡 fix: Explain Model Streams That Die Mid-Response
* 📡 fix: Bound Model Stream Failures to Response Bodies
---------
Co-authored-by: Lia <lia@librechat.ai>
* fix: Surface Persistent Memory Before First Save
* fix: Distinguish Unreadable Memory From Empty Memory
---------
Co-authored-by: Lia <lia@librechat.ai>
* 🗂️ fix: Keep a Running Attachment Chat in the Sidebar
Since #15694, a turn with model-bound attachments defers its user-message
write until the model admits the payload. That write was also what created
a new conversation's row, so for the whole first model call, which with a
long generated script or extended thinking can run for minutes, the
conversation did not exist. Any conversation-list refetch in that window
(starting another chat, deleting one, reloading) dropped the running chat
from the sidebar until its run finished, and GET /api/convos/:id answered
404 for it.
When attachments are the only reason to defer, the new conversation's row
is now written as the run starts, carrying the same fields the message
write would set but no message. The message itself stays deferred until
admission, and its write waits for a seed still in flight so the two
upserts never race. A content policy still holds back every write, the
row included, as #14425 intended.
The conversation half of saveMessageToDatabase moves into
saveConversationToDatabase so the seed and the message write share one
path.
* 🧱 refactor: Own Turn Conversation Writes in packages/api
The conversation half of a turn's writes (the row a message save
upserts, the retention context it stamps, and the new seed ahead of a
deferred first message) moves into `conversations/save.ts`, which takes
`getConvo`/`saveConvo` from the caller. BaseClient keeps only the
wiring: the retention lookup that must stay synchronous for Stop, the
message save, and the calls into the module.
The seed passes an empty `appendMessageIds`, which tells `saveConvo`
the row holds no messages yet, so it no longer reads the message list
before the upsert. It also resolves the conversation once and leaves it
on the request, so the deferred message save reuses it instead of
looking the conversation up again.
save.spec.ts drives the real data-schemas methods against an in-memory
MongoDB: the seed creates an empty row without reading messages, the
message save appends to it without a second lookup, an existing chat and
a subagent thread are left alone, a temporary chat keeps its retention,
and a failed lookup settles instead of rejecting.
* 🗣️ fix: Keep Provider Error Text on Unclassified Agent Failures
An upstream failure LangChain does not classify discarded the provider's own
message and answered with the generic upstream sentence plus a status, so a
gateway or privacy-proxy rejection lost the only account of what happened.
The provider text now rides along in the persisted payload as `message`,
withheld only where a content policy inspects the traffic — the same condition
`getUserFacingProviderError` and `getUserFacingRequestError` already decide by.
* fix: Harden Provider Error Detail Retention
---------
Co-authored-by: Danny Avila <danny@librechat.ai>
* 📭 fix: Deliver Attachment Text Until a File Tool Holds It
A `none`-routed upload had its extracted text withheld whenever a file tool was
enabled, on the assumption the tool would serve the file. A plain chat with the
File Search toggle runs an ephemeral agent, so the upload is filed under no tool
resource and never embedded: the text was withheld for a vector store that never
received the file, and the attachment reached nothing.
Withholding now requires the record to show the tool holds the file, which is the
same evidence deferred provisioning reads before queueing it. `resources.ts`
delegates to that shared predicate so the two cannot disagree again.
* test: Give the Code-Running Primary Agent a Sandbox Copy
---------
Co-authored-by: Lia <lia@librechat.ai>
* 🪂 feat: Opt-In Text Fallback for Files No Tool Can Read
An upload routed to tools (`llmDeliveryPath: none`) reaches nothing when the
agent handling the turn runs neither Run Code nor File Search, or runs one that
cannot read the type. With `fileConfig.endpoints.<endpoint>.textFallbackWithoutTools`
(also accepted at the top level and inherited from `default`), such a turn
delivers the text extracted at upload instead. The setting is off by default,
which keeps today's behavior.
- Upload: when the setting is on and an inferred `none` route finds no reading
tool, the built-in document parser or native text reader stores the text on
the file, best effort, under the extracted-text size cap and content policy.
- Turn: `resolveTurnLLMDeliveryPath` re-resolves each inferred route against
the tools the agent runs, and `applyTurnTextFallback` marks copies of the
records a turn loads, so endpoint filtering, limits, inspection, history
replay and steer media all see the text the turn delivers. The stored route
is never rewritten.
- Explicit destinations, records predating routing, and turns whose tools are
unknown are left as they are.
* 🧪 test: Resolve Custom Endpoint Fallback Under the Endpoint Name
Uploads route a custom endpoint agent by its saved provider, the endpoint name. initializeAgent marks turn copies before getProviderConfig swaps the provider for the backing client, and the endpoint keeps the name afterward, so the client and child encoders resolve the opt-in under the same endpoint. Cover both the initialization path and the post-initialization agent shape.
* ♻️ refactor: Share One Extracted-Text Storage Cap Across Uploads
The fallback defined its own copy of the 15 MiB cap context uploads already apply to extracted text. Export MAX_STORED_EXTRACTED_TEXT_BYTES from files/extract and use it in both places, documenting that it bounds what a MongoDB file document can hold rather than operator policy.
* 🧭 fix: Keep Fallback Text Wherever a Later Turn Can Deliver It
Extraction skipped uploads filed under a reading tool, so a handoff agent
without that tool, or the same agent after its tools or grants changed, had
no text to fall back to. Store fallback text for every inferred route on a
message attachment; files kept on an agent's tool resources never reach a
prompt and still skip it.
Turn marking only ran while the fallback was enabled, so a stored tool-routed
record whose type the endpoint now routes to text stayed marked `none` and
`extractFileContext` skipped it. applyTurnTextDelivery (renamed from
applyTurnTextFallback) now marks any stored `none` record with text that the
turn resolves to text, and returns early when no such record is loaded.
* 🚦 fix: Admit Every Attachment by the Route Its Turn Delivers
A record upload routed to tools that the current endpoint sends to the
provider stayed marked `none` on the turn copy, so admission skipped it while
BaseClient encoded its bytes, bypassing attachment count and size limits.
applyTurnDelivery (renamed from applyTurnTextDelivery) now gives every record
whose route upload inferred the route the turn resolves, before endpoint
filtering, limits and inspection, matching the run-file encoder.
hasInferredLLMDeliveryPath shares the inferred-route rule with the resolver.
Fallback extraction selected the document parser inside the CJS upload path.
resolveUploadFallbackText now takes the upload and picks parseDocument or
parseTextNative itself, with the extractors injectable, so process.js passes
request data only. Its tests run the real parser against the xlsx fixture and
the real native reader against temporary files.
* 🎚️ fix: Read Custom Endpoint Dialect From Config on Both Sides of Init
initializeAgent materializes turn routes before getProviderConfig swaps the
saved custom endpoint name in agent.provider for its backing client, so
routing read that name as a non-OpenAI dialect. Media a custom endpoint opted
into could then be materialized off the provider path, skipping admission,
while the finalized client still sent the bytes. resolveAgentDeliveryRouting
now reads the dialect with getCustomEndpointProvider, as upload does, which
holds before and after the swap.
The upload fallback plan now keys on the chosen-destination marker the turn
resolver reads, so an upload recorded as chosen, including every legacy
chooser upload, never pays for text a turn cannot deliver.
* 🛡️ fix: Apply Turn Routes Only While the Record Stays Admitted
Resolution while initializing and at delivery can disagree: delivery reads a
Responses API choice only the finished client config holds. Applying a route
that takes a record out of admission, off the model path or to text it never
stored, would then skip the limits for a file the client still sends.
applyTurnDelivery now applies a route only while the record stays model-bound;
admitting a record the turn leaves out cannot slip past a limit.
* 🕹️ feat: Run Declared Project Actions on Attached Workers (#15943)
* feat: use declared attached project actions
* Complete named action definitions and approval previews
* Sort named environment imports
* Sort native environment fixture imports
* 🔓 fix: Keep Code Approval Mode Selectable Mid-Run (#15938)
* 🔓 fix: Keep Code Approval Mode Selectable Mid-Run
The composer's code approval mode selector was disabled while a run streamed, and a mode picked during a run was reverted when the final or abort event merged the server conversation back. The selector now stays usable in flight and both merges retain a mid-run selection, which the next send carries.
* 🔓 fix: Retain Mid-Run Approval Mode Across Cache and Recovery
Stamp the live approval mode onto the submission conversation at send so the retention baseline matches what was read, keep a retained mode in the conversation query cache on final and cancel, and rebuild failed or aborted conversations from a preset that carries the mid-run pick.
* 🔓 fix: Scope Retained Approval Mode to the Submitted Conversation
Retention now requires the live conversation to be the one the run submitted, or the id the server assigned to a new chat, so navigating elsewhere mid-run cannot write that conversation's mode back. A single recovery helper rebuilds failed or aborted conversations from the retained preset and patches the detail cache for every recovery site.
* 🔓 refactor: Keep the Local Approval Mode on Every Server Merge
Replace per-path retention with one rule: a locally picked code approval mode is newer than any server copy of the same conversation, so the final and abort merges and the error recovery preset keep it. The selector writes the pick into the conversation's detail cache, which navigation rebuilds from, so the pick is conversation-scoped without reading the index-global atom from the SSE handlers.
* 🔓 fix: Prefer the Live Conversation When Caching the Final Merge
The final handler's detail-cache merge now takes the local approval mode from the open conversation when it is the one that finished, falling back to the cached record only for a conversation that is no longer on screen.
* 🔓 fix: Keep the Local Approval Mode Through Settled-Start Reconciliation
The resumable transport's settled-start reconciliation and replacement handoff wrote a fetched conversation straight into conversation state and the detail cache. Both now apply the same local-mode rule as the event handlers, treating a new chat's pending id as the settled conversation's own.
* 🔓 fix: Seed the Detail Record When a Mode Is Picked
A conversation that has its id but no detail record yet now gets one from the live conversation when a mode is picked, the same key the resumable transport seeds optimistically, so recovery and navigation find the pick. A chat with no id yet still keeps the pick in conversation state alone.
* ⬆️ chore: bump agents to 3.8.7 (#15947)
* 🧭 refactor: Settle Turn Delivery Routing Once in Agent Initialization
`initializeAgent` resolved the provider and its client options only after the
turn's files were loaded and admitted, and the two delivery readers each rebuilt
the attachment routing from the agent object at their own moment: `BaseClient`
took the custom-endpoint dialect from the already-swapped `agent.provider`, the
run-file encoder from whatever child config it was handed.
Move `getProviderConfig`/`getOptions` ahead of file discovery, where nothing in
between fed them, and settle one `deliveryRouting` value with every input final:
the file policy under the endpoint's own name, the dialect its config declares,
the Responses API decision the model call uses, and the transcription setting.
`InitializedAgent`, the child encoder and `BaseClient` consume that value;
`resolveTurnLLMDeliveryPath` is the one place a stored route is resolved again.
* fix: Preserve attachment reachability across handoffs and late steers
* test: Type the untrusted attachment reference fixture
---------
Co-authored-by: Ravi Kumar L <upman@users.noreply.github.com>
* 🧷 fix: Skip Failed Summaries When Resolving the Conversation Checkpoint
* 🧷 fix: Keep a Failed Summary Out of the Model-Facing History Boundary
* 🧭 refactor: Own the Summary Checkpoint Predicate in packages/api
* 🧯 fix: Reject Unfinished Summaries Everywhere and Recount Stripped Turns
* 🧬 fix: Version Event-Actor Summary State So Legacy Prefixes Cannot Warm
* 🏷️ fix: Stamp Inherited Summaries Where Actor State Is Assembled
* ⚖️ fix: Drop Unusable Summaries While Building the Prompt
* 🧷 fix: Repoint Prompt Content Instead of Splicing Stored Parts
* 🧭 fix: Treat a Streamed Summary Without a Boundary as Unfinished
The server has stamped `failed` on an errored summarize round only since
#14546, and `summarizing` never reaches storage, so every round that errored
on v0.8.7 or rc2 was persisted as a plain summary holding its partial deltas.
The flag checks cannot tell that row from a checkpoint, so upgraded
conversations kept losing the history before it.
The aggregator settles it structurally, identically in every SDK release
that has shipped compaction (3.1.63 through 3.8.6): deltas stream `content`
blocks into the part, and only a completed round replaces the part with the
final block, which is the sole writer of `boundary`. A `content`-block summary
without a boundary therefore never finished. `isUsableSummaryPart` and the
shared `isCompactedLeaf` both apply that rule; bare-`text` rows predate the
aggregator and stay governed by the flags.
Fixtures that stand for completed summaries now carry the boundary a real
run writes, and the flag fixtures keep one so they still test the flags.
* 🔁 fix: Strip Unusable Summaries From Responses API Continuations
`previous_response_id` loads the stored conversation and hands each message's
`content` array straight to `formatAgentMessages`, whose summary scan takes
the last summary part carrying text as the history boundary. The chat client
strips unusable summaries before that scan; this entry point did not, so a
conversation continued through the Responses API still lost everything before
a failed round. The same packages/api helper now runs ahead of the formatter.
* 🧭 refactor: Own Event-Actor Summary Selection in packages/api
`getLatestEventActorSummary` decides which summary a warm continuation
carries forward, how a missing token count is recorded, and how the state is
stamped. That is compaction behavior, and every helper it relies on already
lives in `packages/api/src/agents`, so it moves beside `isUsableSummaryPart`
and the controller imports it.
* 🧪 test: Give the Finished Compaction Leaf the Boundary a Completed Round Writes
`isCompactedLeaf` now requires the boundary only a completed summary block carries, so the client fixture for a finished compaction needs one, and a boundaryless leaf joins the interrupted compactions that can be retried.
---------
Co-authored-by: Danny Avila <danny@librechat.ai>
* 🧭 fix: Let a Sealed Chat Follow Its Agent to a New Machine
A conversation's code-environment decision is sealed on its first turn, but the
environment an agent uses stays editable. Pointing an agent at a different
attached machine left every chat sealed to the old one with no valid move: the
client showed an unusable workspace chooser, and any other selection was
rejected by the server as locked. Forking copied the stale seal.
The owner can now move such a chat explicitly. The composer names the machine
the chat used and the one its agent uses now, and moving it goes through an
owner-scoped endpoint that compare-and-swaps the persisted decision after
validating the new workspace against the live worker. A move never switches the
workspace of an environment the decision already covers, never upgrades a chat
that continues without an attached environment, and is refused while a
generation is in flight.
A saved chat also no longer auto-selects a sole workspace for an environment its
decision never covered, which submitted a selection the server always rejected.
* fix: Hold Moves Through Terminal Saves and Move Every Target at Once
A terminal claim marks a generation complete before its response save lands,
and that save still writes the decision the run started with, so a move is now
refused until terminalPersistencePending clears.
The API advertises codeEnvironmentMoveVersion, and the client offers a move only
when it is present, so a new client never exposes an endpoint an older API lacks.
The move menu picks one workspace per new environment, with a sole workspace
preselected, and a single confirm sends the complete target set in one request,
so a partial move can no longer leave a half-migrated decision. A new machine
that advertises no workspace shows its unavailable state instead of an empty
section, and the confirm stays disabled.
* fix: Keep Runs From Rewriting Moved Decisions and Gate Moves by Policy
Every agent turn used to persist the decision it started with, so a run from any
ingress that settled after a move could write the old decision back: the chat
controller reads the conversation before its generation job exists, and
Responses API runs never enroll one. Runs now persist a decision only for a
conversation that does not store one yet, and a legacy row records only the mode
it inferred, so no admission or persistence order can revert a move.
Moves are now an operator setting, statefulCodeSessions.conversationMoves.enabled,
off by default. The API advertises codeEnvironmentMoveVersion and accepts moves
only where the effective policy enables them.
A saved chat carrying attached selections no longer auto-selects a sole workspace
even when selection-less decisions are not advertised, because the server seals
those selections either way.
* fix: Fence Moves Across Remote Runs and Let Moves Drop Unused Machines
A Responses API run is keyed by its response id, so the conversation stream
alone could not show it still working on a chat. A move is now refused while any
generation that can still act for the conversation exists, using the same
conversation-scoped enumeration conversation deletion drains.
A move now validates every workspace it persists, not only the added ones, so a
successful move never hands back a decision whose kept workspace is gone.
A chat sealed to machines its agents no longer all use could not be sent or
moved: the client trimmed the unused selection and the server rejected the
trimmed set as locked. A saved chat now treats that seal as unresolvable, offers
a move that drops the unused machine, and the server accepts drop-only moves.
* fix: Own the Decision Fallback in TypeScript and Settle Move Caches
The fields a run may persist when it never resolved a decision were chosen by a
branch in AgentClient; resolvePersistableCodeEnvironmentDecision now owns that
fallback too, under the same never-overwrite rule, and the CJS method only wires
the request into it.
Workspace choices made in the move menu belong to the chat they were made in, so
another relocatable chat targeting the same machine starts undecided.
A successful move cancels conversation, pinned, and list reads already in flight
before writing the moved decision, so a response from before the move cannot
restore the replaced decision in the cache.
* 🧷 fix: Mark a Failed Compaction So Its Rerun Controls Stay Withheld
A manual compaction that failed with an error part carried no marker: the
server stamped `initiatedBy: 'user'` only on a summary that produced text and
returned early once an error part existed. On a branch ending in a user
message, the resulting turn had no marker and a user parent, so the hover row
kept Edit, Regenerate and Continue — and using one answered that user message
instead of retrying the compaction.
`markCompactionOutcome` now marks whichever part carries the outcome, summary
or error, and `isUserInitiatedCompaction` reads both. The marking moved from
`api/server/controllers/agents/client.js` into `packages/api`, where the
behavior belongs; the controller keeps the call.
* 🏷️ refactor: Type the compaction spec helpers with SummaryContentPart
* 🧯 fix: Record a Marked Failure When a Compaction Produces Nothing
A compaction run that produced neither a summary nor an error part threw
COMPACTION_FAILED out of `sendCompletion`. The turn was then saved by
`saveErrorTurn`, which writes only top-level `text`/`error` and no content, so
the row carried no compaction marker: on a user leaf the hover row kept
Regenerate, and using it answered that user message.
`markCompactionOutcome` now records the typed failure as a marked error content
part instead, so the turn streams and persists like every other failed
compaction. A cancelled run still fails as a typed error, leaving the abort
path to own the turn. `saveErrorTurn` marks the compaction rows it still writes
for failures that are rethrown rather than recorded as content.
Verified end to end by two new mock scenarios that run Compact context against
a summarizer returning nothing, live and after a reload.
* 🧪 test: Run the Empty-Compaction Scenarios Against a Real Compaction
* 🧱 refactor: Resolve Failed-Turn Compaction Content in packages/api
`saveErrorTurn` decided in CJS whether a failed row carries compaction
identity. The decision moves to `resolveFailedTurnContent` in
`packages/api`, which returns the content fields a failed turn is persisted
with — the marked failure for a compaction, nothing for any other turn — and
`request.js` spreads the result.
* 🧹 fix: Keep an Unusable Summary Out of a Failed Compaction's Turn
History loading accepts any nonempty summary as the conversation's checkpoint
(`BaseClient.findSummaryContentBlock` ignores `failed`), so a compaction that
streamed partial text before failing would have persisted that truncated text
beside its recorded failure and replaced the history it failed to summarize.
The fallback now drops the unusable summary, leaving the typed failure as the
turn's whole outcome.
The empty-summarizer scenarios switch the shared fixture summarizer to blank
output, so the reset moves to `afterEach` and runs even when the helper throws
before its caller's `finally`.
* 💰 fix: Record Token Usage for Stopped Agent Turns
The agents Stop route only signals the abort; the run's cleanup skipped recordCollectedUsage on an aborted signal, trusting an abort middleware that is mounted only on the assistants abort routes. Stopped and error-aborted agent turns therefore wrote no transactions and never debited the balance.
The run now records its collected usage on every exit, labelling a stopped turn's transactions with context 'abort'. The owner of the run charges, so a cross-replica Stop is still billed exactly once.
* 💰 fix: Make the Run the Single Charger for a Stopped Turn
The legacy assistants-mounted abort route still billed a non-assistants job — provider usage via spendCollectedUsage, or a text-count fallback — on top of what the run records on exit, and its array clear ran only after its own awaited write, so the two could race even on one replica. The route now only stops and persists; the run records its usage once, labelled through resolveRunUsageContext in packages/api.
* 💰 fix: Keep the Text-Count Fallback From Re-Billing Recorded Usage
BaseClient falls back to text-count billing whenever the recorded usage has no positive output count, so a stopped call that reported input tokens and no output was debited by recordCollectedUsage and then charged its estimated prompt again. AgentClient.recordTokenUsage now returns early once provider usage was recorded (hasRecordedProviderUsage in packages/api); an all-zero report still falls through to the estimate.
* 💰 refactor: Lift Fallback Token Billing Into packages/api
recordFallbackTokenUsage owns the whole fallback operation — the recorded-usage guard, the estimate spend, the reasoning row and the error boundary — taking spendTokens as an injected dependency. AgentClient.recordTokenUsage only builds the transaction metadata from the client and calls it.
* 💰 fix: Label Fallback Billing From the Run's Stop State
BaseClient invokes the estimate fallback without a context, so the sole row for an initial turn stopped before any provider usage was labelled 'message'. recordTokenUsage now defaults the context from the run's own abort signal.
* 💰 refactor: Default the Fallback Billing Label in packages/api
recordFallbackTokenUsage takes the run's raw abort state and derives the transaction label itself; AgentClient.recordTokenUsage passes the signal through and no longer chooses the context.
* 💰 fix: Guard Fallback Billing on the Collected Primary Entries
The stream aggregate recordCollectedUsage returns takes its input from the first primary call only, so a later cancelled call that reported input alone was billed yet invisible to the fallback guard, which then charged the estimated prompt again. recordFallbackTokenUsage now also consults the collected entries themselves (hasRecordedPrimaryUsage), ignoring summarization, subagent and sequential usage; AgentClient passes its collected entries through.
* 🧊 feat: Persist Context Fading Tier Across Agent Runs
Carry the pruner's latched context-fading tier from `@librechat/agents`
through `contextMeta` the way `calibrationRatio` already travels, so a
historical tool result keeps the same truncated bytes from one run to the
next and Anthropic's prefix-based prompt cache survives across turns
(danny-avila/agents#497).
- Add `IAgentFadingTier` to the message and conversation `contextMeta`
types, schemas and the data-provider zod schema
- Add `isAgentFadingTier`, `resolvePersistableFadingTier` and
`resolveRunContextMeta` in `packages/api`; a tier is persisted once it
carries information (masking active or a budget below the window), and
a latched tier is kept even at a neutral calibration ratio
- Seed `createRun({ fadingTier })` from the parent response's contextMeta
regardless of encoding, since caps are character-based; the field rides
the existing forward-compatible `runConfig` variable and older SDK
versions ignore it, as does `Run.getFadingTier` being absent
- Accept a valid `fading` field in event actor context and reject a
malformed one, matching the calibration checks
- Capture run context meta through one module-level helper for both
completion paths instead of two inline copies
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Seed Fading Tier Across HITL Resume, Validate at the DB Layer
Address review findings on fading tier persistence:
- Leave the "is this tier worth persisting" decision to the SDK, whose
`Run.getFadingTier()` now returns only informative tiers; comparing
against the client's window misclassified untouched conversations
whenever a reserve ratio was configured
- Carry `contextMeta` through the HITL pause projection (staged approval,
job metadata, resume state) and seed the rebuilt client from it, so a
paused turn resumes with the same tier and calibration instead of
re-deriving a shallower one and rewriting the prefix
- Share run seeding between `chatCompletion` and `resumeCompletion`, and
make capture tolerate partial runs and bare resume contexts
- Validate `contextMeta.fading` in `commitAgentEventActorState` with a
shared `isAgentFadingTier` guard in data-schemas, so a malformed tier is
rejected at the DB layer instead of silently cold-starting the actor
- Reuse `IAgentEventActorContextMeta` for `IMessage.contextMeta` instead of
extending an inline duplicate
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 test: Cover Resume Seeding From Paused Context Meta
Assert the resume controller seeds the rebuilt client from the context meta
captured at the pause before rebuilding the run, and move the capture
helper's JSDoc back above its function.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧹 style: Sort Imports in Fading Tier Plumbing
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Persist Fading Tier Through Redis Jobs and Branches
Address Codex and Copilot review findings on fading tier persistence:
- Deserialize `contextMeta` in `RedisJobStore`, whose explicit read mapper
rebuilt every other pause field but this one, so Redis-backed
deployments resumed with no tier to seed after every HITL pause
- Copy server-private `contextMeta` onto the assistant message created by
`POST /api/messages/branch`, so the next turn seeds its pruner the same
way it would from the parallel source response
- Constrain the `fading` subdocuments in both Mongoose schemas (version
enum, positive budget, required fields) to match the zod schema
- Throw a distinct "fading tier is invalid" error from both context meta
validators instead of reporting a calibration failure
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Carry Context Meta Through Stop and Re-Pause
Addresses the second Codex pass on the fading-tier persistence:
- A re-pause whose resumed segment has nothing persistable now clears the
job's `contextMeta` in the same transition instead of leaving the first
pause's calibration and tier for the next resume to seed from.
- The client publishes the run's live calibration and fading tier onto the
job after each pre-invoke context snapshot (deduplicated on value), and
the Stop path copies `jobData.contextMeta` onto the stopped response, so
a follow-up from a stopped turn keeps the prompt prefix stable.
- Mid-run captures (HITL pause, Stop) read the graph's live state; `Run`
refreshes its own getters only after the stream settles, so the pause
used to persist the seeds it started from.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Fence Context Meta Publication Ahead of Stop
A Stop handled by another replica reads the job before the owner is
signaled, so a fire-and-forget publish could lose the race, and a run
stopped before its first context snapshot never published the tier it
inherited. The client now publishes the inherited seed before the run
streams or resumes, and the context-usage handler awaits each
snapshot's publish so the write lands before the model call it
describes begins. Failures still only log; the pre-run publish is
optional-called so bare resume contexts keep working.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Read Back Context Meta After the Abort Claim
The run owner publishes its context meta ahead of each model call and
awaits the write, so a publish landing between the abort's initial job
read and its terminal claim describes the call whose partial output the
abort snapshot carries. abortJob now reads the same-epoch job back after
the claim and content re-read and takes its context meta, so the stopped
response persists the tier that produced its bytes. The refresh is
best-effort and logs on failure like the content refresh beside it.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Share In-Flight Context Meta Writes and Clear Neutral Live State
Two snapshot callbacks in a parallel-agent run can capture the same tier
before the first write settles; the publisher now caches the in-flight
promise per serialized value so the second caller awaits the same
durable write instead of treating an uncommitted value as published.
A live snapshot with nothing left to persist after an earlier publish now
writes a neutral record (ratio 1, no tier), since a running job's fields
cannot be deleted through the metadata writer, so a Stop no longer
persists an earlier non-neutral state onto the response. The pre-run
seed publish is unchanged and is told apart from live snapshots by a
flag from the context-usage sink.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 chore: Drop Unused Rest Parameter in Context Meta Test
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 feat: Persist Per-Agent Fading Tiers as Compact Context Meta
Reconciles the host with @librechat/agents at 9aacad1a, where graph
history stays canonical and each Run derives a provider-only projection
from the latched tiers. LibreChat therefore persists only compact state:
the calibration ratio, the default agent's tier, and now the per-agent
tiers from Run.getFadingTiers(), stored as validated entries so agent IDs
never become MongoDB field names and restored onto a null-prototype
record for RunConfig.fadingTiers. Truncated messages, canonical tool
content, projection provenance and per-message truncation state are
never persisted; the SDK's latched flag is stripped on capture.
The per-agent map travels everywhere the single tier already did:
response contextMeta, event-actor checkpoint state, HITL pause and
resume job metadata in both stores, the Stop path, and branch creation.
A shared Mongoose definition keeps the message and conversation schemas
identical, the zod schema validates entries, and commitAgentEventActorState
rejects malformed maps. Comments no longer describe graph messages as
truncated; only the provider projection is.
Tests cover: tool results and inputs reach the persisted content parts
at full size; contextMeta carries exactly the compact tier and
calibration fields; a persisted snapshot round-trips into the seeded
RunConfig unchanged and prototype-safe; per-agent tiers survive pause,
Redis job round-trips, and event-actor context validation.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Restore Event Actor Types and Publish Seeds Before Abortable Setup
The previous commit's doc rewording in the conversation types dropped the
event-actor interfaces that precede the fading tier, which broke the
declaration bundle in CI; they are restored unchanged.
The inherited context meta is now published onto the job as soon as the
parent's state is loaded and awaited at the top of chatCompletion and
resumeCompletion, ahead of run creation and the other abortable setup
stages, so a Stop during setup still persists the parent's tiers onto the
stopped response. The partial response saved when every subscriber
disconnects now carries the job's context meta like the Stop and pause
paths do. The branch route keeps the source's context meta in the saved
message but strips it from the HTTP response, matching client reads.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Serialize Distinct Context Meta Publications
Overlapping snapshots from parallel agents could carry different tiers;
each started its own write and both job stores keep whichever write
finished last, so an older snapshot could overwrite a newer one. Each
distinct publication is now issued after the previous one settles, in
call order, so the newest snapshot is what a Stop reads back. Equal
values still share one write.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Project Root Message Reads and Keep Inherited Meta on Setup Failure
The root GET /api/messages paths returned raw documents: the
single-message query read called getMessages without a projection and the
cursor page performed an unprojected find. Both now apply
CLIENT_MESSAGE_SELECT, with getMessagesByCursor accepting a select option,
so the persisted fading tiers never reach the client through the
paginated endpoint; the search-hydration read projects the same way.
A turn that loads a parent's context meta but fails before its run exists
used to replace the inherited meta with the capture of a missing run, so
the persisted error response lost the last valid tiers. Both finalizers
now keep the inherited meta when no run was created while a created run's
neutral state may still clear it.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 refactor: Move Context Meta Publication Into packages/api
The publication coordinator (ordering, deduplication, in-flight sharing,
failure state) now lives in packages/api as createContextMetaPublisher,
with selectRunContextMetaToPublish deciding what a publication carries;
the legacy client keeps only the wiring to the job metadata writer. A
transiently failing write is retried with a short backoff before the
publication is reported and forgotten, so a snapshot's model call no
longer proceeds on the first rejection while the job holds the previous
record. The SDK swallows handler errors, so retrying is the only way to
strengthen the fence without failing the turn.
A terminal save now supplies contextMeta: null when the finished run has
nothing to carry, and saveMessage unsets a previously stored value in
that case, so a disconnect snapshot's record cannot outlive the run that
completed neutrally.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Widen the saveMessage Method Type for the Null Unset
The exported method interface still typed contextMeta as the message
field, so the spec exercising the null unset failed typechecking; it now
mirrors the implementation signature.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Publish Every Agent's Snapshot, Sanitize Search Hits, Unbound Agent IDs
The context-usage handler now awaits the run's context meta publish for
every ON_CONTEXT_USAGE event, hidden sequential agents included, while
the visible-snapshot bookkeeping and the client emission keep their gate;
a Stop before the next visible snapshot finds the tier a hidden agent's
model call latched. Search results are built from the hydrated hit minus
its server-private contextMeta, since Meilisearch hydration projects every
schema field. The per-agent tier entry guard no longer caps the agent ID
length: ephemeral agent IDs encode endpoint, model and sender without a
bound, and dropping such an entry would let that agent alone re-derive
its tier on the next turn. Also formats the publication spec so the
static checks pass.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Unset Context Meta Atomically, Keep Publication State After a Failed Write
- `saveMessage` folds the `contextMeta` unset into the same update that
persists the terminal response, on both the plain and the provenance-merge
paths, so a failure between two writes can no longer leave a completed row
carrying a disconnect snapshot's state.
- `createContextMetaPublisher` tracks whether any record has committed
separately from the retryable latest publication, so `hasPublished` stays
true after a later publication exhausts its retries and a following neutral
snapshot still overwrites the earlier record on the job.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Carry Context Meta Through the Resumable Stop Route and Neutral Resumed Completions
- The resumable Stop route copies the refreshed `jobData.contextMeta` onto the
terminal assistant message it persists, as the abort middleware already
does, so a stopped resumable response keeps the tiers that produced its
partial output.
- A resumed run that completes with neutral context state now saves
`contextMeta: null`, which unsets the paused segment's record instead of
letting an omitted field keep it on the completed row.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Trust Only Server-Authored Context Meta, Unset It on a Neutral Stop, Read It From the Job on Disconnect
- `POST /api/messages/:conversationId` and conversation imports drop any
client-supplied `contextMeta`, and the run seeds its calibration and fading
tiers only from a server-authored parent response, so a forged tier can never
shape a provider projection.
- Both Stop paths save `contextMeta: jobData.contextMeta ?? null`, so a job that
re-paused with neutral state unsets what an earlier pause stored on the row
instead of leaving it behind.
- The disconnect partial save reads the same-epoch job record for the run's
published context meta, since the client-facing resume snapshot never carries
server-private state.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧪 test: Mock the Job Store in the Resume Metadata Spec
The disconnect partial save now reads the same-epoch job record through
`GenerationJobManager.getJobStore()`, so the resume metadata spec's manager
mock provides it as the other disconnect spec already does.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 🧊 fix: Keep Context Meta Off the POST Message Response
`POST /api/messages/:conversationId` returned the saved row verbatim, so a
client write against an existing server-authored message echoed the row's
stored context meta. The route now projects the row through the same client
projection the branch route uses, which drops the server-private field.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
* 📦 chore: Bump @librechat/agents to 3.7.16 for Persisted Fading Tiers
3.7.16 is the first release that carries danny-avila/agents#497, so
`Run.getFadingTier()` / `getFadingTiers()` now report the latched tier
this branch persists and `RunConfig.fadingTier` / `fadingTiers` seed the
next run from it. The dependency set is unchanged from 3.7.15; only the
package entry moves.
Adds an SDK-backed round trip to the fading spec: a first pruner latches
an informative tier, `resolveRunContextMeta` reduces it to the persisted
shape, and a second pruner seeded from that shape reproduces the first
run's projected tool-exchange bytes under instruction and calibration
drift, while an unseeded pruner under the same drift relaxes its tier and
rewrites them.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNbgMeR2aZDyhsqAy4L8gF
---------
Co-authored-by: Claude <noreply@anthropic.com>
* feat: Handle reaching the agent tool-call limit gracefully
When the graph exhausts its per-turn step budget, persist the turn as
unfinished with finish_reason tool_call_limit instead of a red error.
Warn the model as the budget runs low, and offer Keep going or Answer now.
* docs: Add screenshots of the tool-call-limit notice
Light and dark captures of the unfinished-turn card for the PR description.
* style: Tighten the tool-call-limit notice card
Pin dismiss to the top-right with uniform rounding, use a slightly
smaller hit target, and round the card to xl. Refresh the PR screenshots.
* fix: Address Copilot review findings on the step-budget path
Skip empty and subagent-scoped PostToolBatch events when counting
rounds. Drop the double-cast in the notice test helper and coerce the
tool-call-limit finish reason in the Continue-gate spec.
* fix: Address Codex review findings on budget and dismiss
Pass the resolved recursion limit into the OpenAI-compatible
processStream path so the step-budget hook matches the graph.
Reset the notice dismiss state when the displayed message id changes.
* fix: Unblock CI typecheck and import sorting
Declare recursion_limit on the OpenAI service agent type, sort that
file's local imports, and route the notice test context through unknown
so tsc accepts the partial ChatContext fixture.
* fix: Sort remaining PR imports for static checks
* chore: Remove tool-call-limit notice screenshots
* fix: Keep recovery actions from consuming composer drafts
Pass empty file, skill, and quote overrides on Keep going and Answer
now so a staged compose is not attached or drained.
* 🤖 feat: make event actor HITL durable
* 🤖 fix: break event actor outcome cycle
* 🤖 fix: close durable actor terminal races
* fix: harden durable event actor recovery proofs
* fix: close event actor resume publication races
* feat: resume event actors from checkpoint forks
* fix: fence event actor checkpoint uncertainty
* fix: satisfy event actor type contracts
* fix: make actor reconciliation recoverable
* fix: preserve event actor lifecycle transitions
* fix: fence event actor lifecycle outcomes
* fix: enforce event actor lifecycle ownership
* fix: retain event actor settlement proof
* 🔒 fix: Retain Event Actor Receipts Through Repair and Bound Their Journal
Repair and compensation deleted the reconciliation row they resolved, which
was the only durable proof that the invocation had already applied an external
action. A delayed duplicate owner could then reacquire the same invocation id
and repeat that action. Both resolutions now retire their receipt to `settled`
and record how it settled, so the same-id tombstone survives; `history_repaired`
and `action_compensated` still force a cold rebuild. Compensation undoes the
effect without re-authorizing the delivery, so a legitimate retry must arrive
under a new invocation id. A retried repair converges on its own receipt.
Bound the journal so a long-lived actor cannot grow its conversation document
without limit: a new fence is admitted only when no active lifecycle row
exists, so a capped push can evict nothing but the oldest settled receipts.
Stop shipping the unbounded source payload on every bound-child continuation.
It rode the delivery body regardless of the feature flag while the sibling
`fire` body deliberately sends event identity alone, so a large webhook payload
could push a previously working delivery past the chat route's body limit. The
actor binds an invocation from identity and never builds the prompt from it.
Blank the positional token map on warm continuations. It is derived from the
full DB history, while a warm run executes on checkpoint-restored state, so its
indices address different messages and the pruner never recounts them —
misattributing cached counts to the wrong messages in both directions.
Keep the replaced-claim exit on its cleanup path when preserving reconciliation
fails: the committing CAS already left a blocking row, so the failed status
upgrade costs provenance, not safety.
* 🧪 test: Pin the Warm Continuation's Map/Summary Asymmetry
Give the warm-continuation client test a populated token map and a real
cross-run summary so its assertions bite: the positional map must arrive
blank (checkpoint-restored state no longer matches DB-derived indices, and
the pruner never recounts a populated entry) while `initialSummary` must
pass through unchanged — it rides the system tail and summarizes
pre-boundary turns that were excluded from the very history the committed
checkpoint was built from, so blanking it would silently drop context no
warm run can recover.
* ⚖️ fix: Honor Compensation in Settlement and Age-Bound the Receipt Journal
A compensated receipt still tombstones its invocation id, but its external
effect was explicitly undone — the terminal handler nonetheless replayed
every settled lifecycle's stored action as authoritative and settled the
public outcome as applied, telling an action-aware source the operation
stands and suppressing the new-invocation retry compensation requires. The
handler now settles a compensated invocation as failed with an explicit
compensation error, overriding even fresh applied run evidence from a
replayed generation; verified and repaired receipts continue to replay
applied.
Receipt eviction is now primarily age-based: a stale same-id owner is
bounded by time, not by how many newer invocations settle, so the previous
count-only slice let a high-rate actor evict a tombstone while its delayed
duplicate owner could still wake and repeat the action. Admission prunes
only settled receipts older than a retention window that dwarfs every
generation, job, and delivery-retry lifetime, and the count cap is demoted
to a raised document-size backstop.
* 🔀 fix: Serialize Compensation Against Settlement and Never Evict Live Receipts
The terminal handler read its lifecycle snapshot, verified history, and then
settled the public outcome — so a compensation resolving the same receipt
during that window lost: the handler settled applied from its stale snapshot
and no retry could ever change the replay-identity-locked outcome. The
receipt's status CAS is now the serialization point: verification resolves
the receipt BEFORE settling, whichever transition wins determines the public
outcome, and a crash between resolve and settle converges through the
retained receipt's replay. The verified-replay probe requires the receipt's
own resolution, so a compensated receipt can never satisfy a verification
retry. This inverts the settle-before-receipt ordering deliberately: that
ordering guarded proof that resolution used to delete, and the receipt now
retains its full action proof through resolution.
The document-size cap is no longer an eviction quota. A receipt inside its
retention window is never discarded: when the journal holds a full cap of
unexpired receipts, new invocations are refused fail-closed until receipts
age out, making duplicate protection and document integrity simultaneous
invariants instead of a rate-dependent trade.
* 🎓 fix: Keep Skill-Bearing Event Actors on the Legacy Path
Skill primes are spliced into the message list directly ahead of the newest
message, and a warm continuation forwards only that newest message — so a
checkpoint-restored actor would keep serving the prime bodies baked in at
its last cold start and never observe an edited or newly attached skill.
Until the actor head carries a context fingerprint that forces a cold
rebuild when the agent's skill context changes, agents with always-apply or
manual skill primes stay on the legacy path, which re-primes fresh bodies
every turn: correct on every event, just never warm.
* 📜 fix: Gate Fork Mode on the Skills Capability, Not Just Request-Time Primes
History-derived re-priming was a third path into the same staleness class:
an actor that previously invoked a skill carries no request-time prime
arrays, yet primeInvokedSkills re-resolves that skill's current body from
history each turn and the warm slice drops the reconstruction — leaving the
checkpoint's old body active after edits. The fork gate now keys on the
priming hook itself (present exactly when the skills capability is enabled)
alongside the request-time arrays, so every skill-body path routes to the
legacy rebuild until #15235's context fingerprint restores warm
continuation for skill-bearing actors.
* 🧾 fix: Capture Applied-Action Proof at Tool Execution, Not After sendMessage
The executor read applied-action evidence from the run-step collection the
instant sendMessage resolved, but that collection is populated
asynchronously — an applied invocation could classify as actionless
(runSteps still empty while the tool result already streamed), discarding
its fork and stranding the actor cold while the terminal handler later
settled the same delivery as applied from the persisted evidence.
Authoritative proof is now recorded in graph context the moment the
expected tool executes: the request-owned recorder observes the tool-end
chain (which ToolNode dispatches synchronously with both input and output)
and applies the same fences as run-step evidence — exact tool name with the
MCP-suffixed form, the declared argument subset against the execution
input, an error-free result, and the background non-execution receipt
exclusion. readAppliedAction consults the receipt first; run-step
inspection remains the fallback for paths that bypass the tool-end chain.
Regression coverage reproduces the observed ordering: the real executor
commits the head from the receipt while run steps are empty, warm-continues
the next event, and never re-executes the action; recorder fences and the
receipt-first controller wiring are covered separately.
* 🎯 fix: Supply Execution Arguments to the Tool End Callback
The live Vertex + MCP canary exposed a contract mismatch the synthetic
fixtures hid: the ON_TOOL_EXECUTE execution path invoked its tool end
callback with output only, while the action recorder must verify the
declared argument subset against the execution input. The receipt never
qualified, every turn fell back to cold history rebuilds, and the
tournament advanced with zero actor heads and zero retained checkpoints
while looking successful.
The execution handler owns both halves at the same moment, so the fix is
at the source rather than a correlation store: ToolEndCallbackData gains
the executed call's input and every callback site passes tc.args. A
handler-level regression drives the real createToolExecuteHandler and
asserts the callback receives both fields; recorder regressions pin the
production shapes — an output-only tool end must starve an
argument-fenced receipt rather than trust an unfenced match, and still
qualifies a name-only expected action.
* 🕵️ fix: Mark Background Deliveries So They Cannot Impersonate Applied Actions
The background-claim callback reports the ORIGINAL tool's name for artifact
attribution on the poll turn that harvests a completed task. A name-only
expected action could therefore be impersonated by work some earlier turn
dispatched: the recorder would attribute that delivery to the current
invocation and commit a head whose state never contained the invocation's
own action. The run-step evidence path never had this hole — it sees the
poll tool's name — so the recorder must match its provenance discipline.
Delivery callbacks now carry an explicit backgroundDelivery marker set at
the one site that rewrites the name, and the recorder ignores marked
deliveries outright. Regressions pin both halves of the contract: the
delivery callback must carry the marker with the poll call's arguments,
and a marked delivery can never qualify even a name-only expected action.
* 🧿 fix: Version Invalidations, Keep Evidence Ahead of Output Policy, Gate Detachable Actions
Three closeout-round findings, each converted into an invariant.
Every legacy-path invalidation now advances a durable epoch — including for
headless and already cold-marked actors, where the marker alone leaves no
CAS-visible trace — and the actor-head CAS requires the epoch observed at
preparation. A concurrently prepared fork whose history predates an
intervening legacy turn can no longer commit past it; the commit reports an
ordinary conflict and journals.
Execution identity is now emitted before post-execution output policy: when
a side-effecting tool succeeds but its returned content is withheld by the
output filter, the callback delivers an outputFiltered receipt with blank
content — the recorder accepts it as proof (rejecting model-detached calls
it cannot distinguish through the blank shape), the artifact path never
sees it, and an applied action is no longer reclassified actionless and
re-executed on retry.
Background-capable expected actions stay off the fork path: dispatch
returns a launch handle every evidence fence correctly rejects, and the
completion is provenance-marked as another turn's work, so a fork would
settle actionless before the external effect lands with nothing to stop a
retry from dispatching it again. The gate mirrors the MCP-suffix name
matching of the evidence path.
* 🚧 fix: Seal the Whole Legacy Turn Behind a Second Epoch Advance
The epoch fenced only the legacy turn's start: a fork preparing after the
begin invalidation but before the turn's message persistence observed the
new epoch and cold marker, rebuilt from history that did not yet contain
the turn, and committed cleanly because nothing advanced the epoch again —
making the incomplete rebuild authoritative and clearing the marker.
Every legacy event turn now seals its invalidation at terminal persistence
with a second epoch advance, on the success, replaced-claim, and error
exits alike. Sealing deliberately carries no quiescence requirement — it
must succeed while a fork fence is active, because that is exactly the
mid-turn race it defeats — and a fork that already committed against the
begin epoch is healed the same way: the seal re-marks the head cold, so
the next event rebuilds with complete history. Seal failure never diverts
the turn's own exit; the begin bump still fences everything prepared
before the turn.
* 🔗 fix: Replace the Best-Effort Epoch Bump With a Durable Legacy-Turn Fence
The second epoch advance could not make a legacy turn atomic, and three
findings shared that root cause: two conditional updates left a headless
gap a fork could create the head inside; the error exit sealed before
saveErrorTurn made the error history durable; and any crash or failure
between persistence and sealing left an incomplete fork authoritative,
because the seal was best-effort and its failure was swallowed.
A legacy turn now carries one durable fence. A token is written before
execution by a single update-pipeline write — no two-write gap, and the
cold marker is applied only where a head exists via $cond/$$REMOVE. While
the token is present no fork may prepare (the adapter refuses) or commit
(the CAS requires its absence), because the turn's messages are not yet
durable. One atomic write clears the exact token and advances the epoch
once history is persisted — after saveErrorTurn on the error exit — and
success, replacement, and error exits all route through it.
Failure is now fail-closed rather than silent: a failed seal leaves the
token set, which keeps blocking forks and is logged as such, and a fence
abandoned by a crashed turn is reclaimed only once stale, advancing the
epoch and marking any head cold so the next event rebuilds from whatever
history actually survived.
* fix: serialize legacy event actor turns
* fix: close legacy actor fence ownership gaps
* fix: preserve legacy actor persistence fences
* 🧭 fix: Carry Quoted Excerpts Through Mid-Run Steering
"Add to chat" quote chips were dropped by every during-run steer path: the
steer POST had no quotes concept, so a composer-origin steer left the chip
staged (gluing onto the NEXT send) and a queued item steered into the live
run lost its quotes silently.
Quotes now ride the steer protocol end to end:
- POST + admission: `quotes` on the steer body, normalized like the chat
route's (getReferencedQuotes caps), part of the idempotency fingerprint
only when present so pre-existing receipts still replay.
- Injection: merged into the model-bound turn as Markdown blockquotes at
both boundaries (text-only and media paths), mirroring prependQuotes.
- Persistence + replay: the STEER content part stores `quotes` separately
from the typed text; stampSteerPartMedia re-merges them per turn (even
with resendFiles off) via the SDK's transient media stamp, with the quote
block folded into the token budget.
- UI: composer steers/interrupt-steers drain the chips (skill picks stay
staged — they configure a NEW turn's run); SteerPart and the in-flight
bubble render the same MessageQuotes reference blocks as user bubbles;
queued/failed rows show a quote count; reconnect reseeds fall back to the
server item's quotes when no local chip survives.
- buildMessages keeps its zero-await path to the parallel context kickoff
via a synchronous stamp-target probe.
* 🧭 fix: Keep Quotes in the Client-Safe Steer Projection
toPendingSteer is the projection behind resume-state pendingSteers, abort
responses, and terminal leftover claims — dropping quotes there would lose
them on exactly the recovery paths the reconnect reseed's server fallback
relies on.
* 🧪 test: In-Flight Steer Bubble Renders Carried Quotes
* 🔁 fix: Re-Stage Quotes When a Pre-Quotes Replica Accepts the Steer
Codex flagged the rolling-deploy window: an old replica 202s a quoted steer
while dropping the excerpts, so the client cleared the chips for context the
model never received.
The 202 (fresh and receipt replay) now echoes quotesAccepted from the
DURABLE item; a missing echo on a quote-bearing composer-origin steer
re-stages the excerpts as composer chips — the pre-steer behavior, so they
ride the next send instead of vanishing — and strips them from the surviving
chip so a later terminal conversion cannot duplicate them. Queued-origin
steers keep quotes on the item, whose restore paths already return it
intact. The residual cross-version lost-ACK retry stays fail-closed as a
409 idempotency conflict (failed chip with retry controls).
* 🔁 fix: Close the Remaining Cross-Version Quote-Loss Windows
Codex round 2:
- Send now of a quoted queued item against a pre-quotes replica now
re-stages the excerpts too (the row is consumed and the words inject
bare, so the composer is their only remaining home); the strip clears the
chip's captured origin copy so reclaims and terminal conversions cannot
duplicate them.
- A quoted retry whose lost first ACK was accepted by a pre-quotes replica
now REPLAYS that legacy receipt instead of 409ing: the stored fingerprint
matching the quote-less hash of the same words proves the cross-version
case, and the replayed 202's missing echo drives the re-stage. Different
quotes against a quote-bearing receipt still conflict.
- TSteerAppliedEvent.part gains the quotes field (typed SSE consumers).
* 🧪 test: Drop the Stale Narrow SteerDrainOutput Alias
The spec's local intersection re-declared injectedMessages with
content: string, predating the SDK pin that declares the field natively
(content: string | MessageContentComplex[]). Under CI's clean install the
hook's BaseHookOutput is no longer assignable to that narrower alias; the
plain PostToolBatchHookOutput is the correct type for every drain/boundary
assertion. Verified against the published 3.6.16 dist and the local one.
* 🔁 fix: Honor the Generation Owner's Quote Capability End to End
Codex round 4:
- steerQuotesCapable rides job metadata (createJob + HITL resume rewrite),
mirroring preemptCapable's owner-recorded pattern: an upgraded admission
replica no longer stores quotes — or claims them accepted — for a
generation whose older owning drain would silently drop them at
injection. The missing echo drives the client re-stage, and a later
capable handover cannot double-deliver restored context.
- Applied events reconcile dropped quotes: when a quote-less applied part
settles a quote-bearing chip (the lost-202 ordering the ACK-echo path
cannot see), resolveSteerChip and both reconnect settle paths re-stage
the chip's excerpts before removing their only copy. mergeRestagedQuotes
dedupe keeps every trigger idempotent for the same excerpts.
* 🔁 fix: Re-Read Quote Capability at the Last Moment and Cap Restaged Chips
Codex round 5:
- A HITL resume rewrites steerQuotesCapable without changing the
generation's createdAt, so the enqueue fence cannot see a
capable-to-legacy handover landing during admission's awaits. Re-read
the owner's flag immediately before item construction (paid for only by
quote-bearing requests); the residual between re-read and enqueue commit
matches preemptCapable's documented race.
- mergeRestagedQuotes now respects the 10-quote contract with the staged
chips winning: a restored tail that cannot ride the next send is dropped
explicitly instead of rendering as a chip the submission would silently
discard. MAX_QUOTE_COUNT moves to utils/steer as the single client
source; QuoteButton imports it.
* 🔁 fix: Steer Quote Coverage for Preflights, Memory, and Single-Scan Stamping
Codex round 6:
- Stored-message policy inspection now extracts steer-part quotes as quote
fragments (path /content/N/quotes/M), so conversation import and shared
link preflights inspect the newly persisted field exactly like top-level
message.quotes.
- The memory copy gets its own quote-merge stamp (text only, resendFiles
false): formatAgentMessages ignores part.quotes, so without it a steer
whose substance lives in its excerpt reached the chat model but never
memory extraction.
- collectSteerStampTargets replaces the boolean probe: buildMessages
collects once and hands the targets to stampSteerPartMedia, keeping the
zero-await fast path without scanning the history twice.
* 🔁 fix: Redis Quote Plumbing, Conversion-Race Guard, and Quote-Bound Recovery Proof
Codex round 7:
- RedisJobStore.deserializeJob now restores steerQuotesCapable (the explicit
mapper otherwise dropped it on every read, leaving quote steering inert in
Redis deployments), with the round-trip spec extended.
- Both Lua parked-steer projections (terminal close + generation
replacement) forward item.quotes, matching toPendingSteer — a lost final
no longer strips excerpts from durable recovery in Redis mode.
- The no-echo restage reads the SURVIVING chip (reclaimRejectedChipQuotes):
a terminal conversion that beat the delayed 202 already moved the quotes
onto the queued follow-up, and re-staging them again double-delivered.
Regression-tested with the conversion-before-ACK ordering.
- RecoveredSteerPayload binds normalized, order-significant quotes (builder,
validator, TS matcher, and the Lua decode+matcher): a stale client
presenting the same recoverySteerId with altered or missing quotes cannot
consume the parked source. Quote-less sources keep matching quote-less
recoveries.
* 🔁 fix: Execution-Bound Quote Capability with an Atomic Enqueue Predicate
Codex round 8:
- steerQuotesCapable becomes a transient assertion translated (at createJob
and in ApprovalLifecycle.resolve) into steerQuotesExecutionId, valid only
while it equals the LIVE providerExecutionId. A legacy replica winning a
HITL resume rewrites the execution id without knowing the marker, so its
stale assertion self-invalidates — a bare boolean could not be cleared by
code that predates it.
- The fenced enqueue evaluates that equality atomically (all three Redis
scripts decode-and-strip like the existing preemptCapable normalization;
both InMemory sites mirror it) and returns the persisted item, so the
quotesAccepted echo reflects exactly what was stored even when a handover
lands between admission's read and the commit. The last-moment re-read is
gone — the transaction is the authority.
- Tests: capable-resume re-binding, legacy-resume omit-not-clear
invalidation, the admission-vs-handover race (capability read true, then
execution rewritten before enqueue), and the Redis round-trip of the
marker.
* 🔁 fix: Full Redis Parking Coverage and Loss-Moment Quote Restaging
Codex round 9:
- The two remaining Redis parking projections (terminal status CAS and
stale-running cleanup) forward item.quotes — every field-picked steer
projection now carries them (audited: 2 Lua 'projected' + 2 Lua
'clientItem' + toPendingSteer).
- The ordinary no-echo ACK no longer re-stages: the steer has not injected
yet, so the quotes stay carried on the pending chip. A quote-less applied
event re-stages them at the actual loss; a terminal leftover conversion
carries them onto the recovered row, whose normal send delivers quotes on
any server — re-staging at the ACK let that leftover auto-send bare text
while the excerpts glued onto an unrelated draft. Only the settled
receipt replay (already injected, no future event) reclaims immediately.
* 🔁 fix: Legacy-Replayable Receipts with Separate Quote Identity
Codex round 10: an upgraded-first receipt stored a quote-inclusive
fingerprint no pre-quotes replica could recompute, so a lost-ACK retry
routed through one 409'd already-accepted words with duplicate-send
controls.
The durable fingerprint reverts to the quote-independent 3-field hash —
the one shape EVERY deployed version computes, replayable across a rolling
deploy in both directions — and quote identity moves beside it as
requestedQuotesFingerprint (of the REQUESTED quotes, pre any capability
strip, so an incapable-owner acceptance still replays its own retries).
Absent records (legacy-written or quote-less) accept any same-words retry,
preserving the round-5 rule; present records must match exactly, keeping
different-quotes clientSteerId reuse a 409 on quote-aware readers. Under
the keep-on-chip client contract a legacy replay's missing echo is
harmless — the excerpts stay carried on the pending chip.
* 🧪 chore: Re-Trigger CI After Dropped Workflow Events
buildMessages formatted every history row twice per turn — a prompt
copy and a memory copy — then discarded the entire memory payload
unless some row carried fileContext, which is the rare case. The
memory copy has exactly two consumers: that payload, and the canonical
recount of a row, where it is content-identical to the prompt copy
unless the row itself has fileContext. So the prompt copy is now the
recount surface for context-free rows, a fileContext row builds its
memory copy at recount time, and the full memory payload is assembled
in a deferred pass — same formatting, same per-row merge order — only
once a row has proven the payload will be kept. The common turn
formats each row once instead of twice and no longer allocates a
payload it throws away.
Also forwards the run's useLegacyContent to formatAgentMessages as the
new legacyContent option, inert on the current SDK release: once the
SDK change ships, text history is emitted pre-flattened so the
per-request legacy projection stops cloning every message and the
context meter's identity-based count reuse holds across the
projection.
The aggregator writes content parts at provider-source indexes, which can
skip slots and leave holes in contentParts. Array.prototype.map preserves
those holes and the Map constructor iterates them as undefined, so
rebaseActivityPhaseBounds threw "Iterator value undefined is not an entry
object" at the end of every run with sparse content — deterministic with
parent phase summaries enabled, on both the completion and resume paths.
Build the identity map with an index loop that skips nullish slots. Holes
must stay out of the map: one undefined key would falsely match every hole
in previousParts as a retained part and corrupt the rebased bound.