Skip to content

📜 feat: Store What a Background Subagent Child Streamed as Standard Content - #18173

Merged
danny-avila merged 1 commit into
danny-avila/background-child-jobsfrom
danny-avila/child-row-content
Nov 14, 2026
Merged

danny-avila merged 1 commit into
danny-avila/background-child-jobsfrom
danny-avila/child-row-content

Conversation

@danny-avila

Copy link
Copy Markdown
Collaborator

Summary

A background subagent child's result row stores its text and a bounded activity projection, not the content parts every agent message stores. Once a child finishes, anything that reads the row has to rebuild the child's output from that projection, so a child thread cannot be shown by the components that show a chat.

This PR also stores what the child streamed as standard content on the <taskId>:assistant row, on completion, failure and cancellation. text, subagentTranscript and subagentActivityProjection are written as before, so the current panel and the thread view read exactly what they read today.

endpoints.agents.subagentActivity.generationContentBytes bounds the stored content: 4 MiB serialized by default, 0 stores none. Content over the bound is left off and the row keeps only its text and projection, so the row always fits and a large child can never lose its result to an oversized document.

Stacked on #18169, which provides the content: it is the fold of the frames the child's generation job streams. With that job off (generationJobs: false) nothing changes.

One consequence to know about: forking a child thread into a normal chat copies its rows, so a forked chat now shows the child's full parts (tool calls included) and sends them to the model on the next turn, where it used to carry the child's final text only.

How it works

The content is read once per settlement, after the stream has drained, and the same value goes to the row and to the stream's final event.

 await this.settleGeneration(lease, false, async () => {
+  const content = this.generationContent(lease);
   await this.persistResult(
     scope, request, runtime.taskId, preparedThread, result, detachedUsage,
     lease.content?.throughSequence, appliedSteers, publicRecorder.snapshot(),
+    content,
   );
-  return this.generationFinal(request, runtime.taskId, preparedThread, lease, { text: result.content });
+  return this.generationFinal(request, runtime.taskId, preparedThread, { text: result.content, content });
 });

generationContent returns nothing when the child had no stream, streamed nothing, or the serialized parts exceed the budget.

Type of change

  • Feature

Testing

Tested environments/configuration:

  • MongoDB memory server, the real SubagentThreadTaskStore, and the real GenerationJobManagerClass in memory mode

Automated tests:

  • Added to subagentThreads.generation.spec.ts: a completed child's row carries the streamed text as a text content part beside its text; a cancelled child's row keeps what it had streamed; a failed child's row keeps it with error: true and no provider detail; the row stores text only when the stream is off, when the content is over its budget, and when the budget is zero.
  • Updated the config defaults case in packages/data-provider/src/config.spec.ts.
  • Reran subagentThreads.spec.ts (116), subagentGeneration.spec.ts, view.spec.ts. One existing case in subagentThreads.spec.ts ("keeps activity delivery observational when its transport is unavailable") failed once when four Mongo-backed specs ran in parallel; it passed three times alone and in the full spec run alone, and does not use this code path.
  • npx tsc --noEmit in packages/api; npm run static-checks -- --against origin/dev.

Not covered: forking a child thread with the new rows in a running app.

A child's result row carried its text and a bounded activity projection, not
the content parts every agent message stores, so a reader had to rebuild the
child's output from the projection. The row now also carries what the child
streamed, on completion, failure and cancellation, in the standard shape.

endpoints.agents.subagentActivity.generationContentBytes bounds it (4 MiB by
default, 0 stores none). Content over the bound is left off, so the row always
fits and keeps its text and projection as before.
@danny-avila
danny-avila marked this pull request as ready for review November 14, 2026 20:37
@danny-avila
danny-avila merged commit 5420227 into danny-avila/background-child-jobs Nov 14, 2026
73 of 74 checks passed
@danny-avila
danny-avila deleted the danny-avila/child-row-content branch November 14, 2026 20:38
danny-avila added a commit that referenced this pull request Nov 15, 2026
… Job (#18169)

* 🫀 feat: Let a Job Owner Keep a Silent Run Alive

A generation job's idle clock advances only with emitted chunks, so a run that
works without output for 20 minutes is reaped while it is still alive.
touchJob refreshes the idle clock and the storage lifetimes an append would
have extended, fenced on the generation epoch and limited to the replica that
owns the runtime.

* 🧶 refactor: Share One Fold From Child Frames to Content Parts

readSubagentContent folded public child frames into content parts inline.
The fold is now a synchronous function a second caller can use, so a frame
can be folded and published without yielding in between.

* 🏷️ feat: Mark the Generation Job of a Background Subagent Task

Job metadata gains subagentTaskId and subagentParentConversationId, set only
by the subagent task store. A marked job is a child-thread job, so it stays
out of the active chat list, and isBackgroundChildJob tells it apart from an
event-bound child, whose job the chat controller owns.

* 🧵 feat: Run a Background Child as a Resumable Generation Job

createChildGenerationHost opens a generation job keyed by the child thread id
and feeds it the child's public step frames. Text deltas that queue behind a
slow write merge instead of dropping, the terminal state is claimed before the
caller persists and the final event is published only afterwards, and no
stream failure can fail the child: the run and its result carry on without a
live view.

* 🪢 feat: Stream a Background Child Through Its Own Generation Job

The subagent task store takes a childGenerations dependency. Once a child's
thread and input row are durable it opens a job keyed by the thread id, feeds
it each public frame, refreshes its idle clock on every lease renewal, and
settles it around its own persistence, so a reader sees the final event only
after the result row exists. A cancel, a failure and a job aborted from
outside all end both the child and its stream.

endpoints.agents.subagentActivity.generationJobs turns it off. A stream that
cannot be opened or written never fails the child.

* 🔌 feat: Give the Server's Task Store Its Child Stream

The host wiring builds the child generation host from the generation job
manager and hands it to the subagent task store, so a background child's
stream is reachable in the running server.

* 🚧 fix: Refuse Chat Abort and Steer on a Background Child's Job

The chat abort route saves a user row and a partial response and upserts the
conversation, and the steer route queues text only the chat controller drains.
Both authorized on the job's owner alone, so either could act on a background
child's job and write a chat-shaped history into a view-only thread, or accept
a steer nothing would ever apply. Both now answer 409 for a job the subagent
task store owns; the child is stopped and steered through its control
endpoint.

* 🧹 fix: Evict a Finished Job Before a Live One at Capacity

The in-memory job store made room by deleting its oldest job whatever its
status, so a full store could end a run somebody was still waiting on. It now
takes the oldest finished job first. Also covers a job manager that shuts down
while a background child runs: the child still persists its cancellation.

* 🛰️ test: Read a Background Child's Stream From Another Replica

Against real Redis: a second replica resumes with everything the child has
streamed, receives only newer deltas live, then the final event; a child that
streams past the manager's 5,000-event early buffer before anyone attaches
still resumes whole on both replicas; and the owner's touch keeps a silent
child's job alive.

* 🧽 chore: Sort Imports in the Child Stream Files

* 🧪 test: Expect the Child Stream Lever in the Activity Defaults

* 📜 feat: Store What a Background Child Streamed as Standard Content (#18173)

A child's result row carried its text and a bounded activity projection, not
the content parts every agent message stores, so a reader had to rebuild the
child's output from the projection. The row now also carries what the child
streamed, on completion, failure and cancellation, in the standard shape.

endpoints.agents.subagentActivity.generationContentBytes bounds it (4 MiB by
default, 0 stores none). Content over the bound is left off, so the row always
fits and keeps its text and projection as before.

* 🛟 fix: Keep a Stalled or Failing Child Stream From Touching Its Child

Four ways the stream could still reach the run it only observes. A frame that
could not be copied threw into the child's own progress report. A job store
that never answered held the child's start behind job creation and its result
behind the terminal claim. And a stream that had stopped being written was
never ended, so its job read as a live child for twenty minutes after the
child finished.

Frames are now copied defensively, opening and settling are bounded, a job
that arrives after its child stopped waiting is ended, and a detached stream
is still touched and still settled with its full final event.

* 🧯 fix: Let a Child Stream Observe Its Run Without Ever Stopping It

Review round 1.

A failed Redis append retires the job's runtime by aborting its controller,
and the child stream forwarded every abort of that controller to the task
store as a cancellation. A stream-store outage therefore stopped the child's
model and tool work. The stream no longer signals the child at all: deletion,
shutdown and the control endpoint already stop a child through the task
store, and an aborted, reaped or retired job now only ends the live view.

The in-memory store's capacity eviction preferred any terminal job, including
one that still owed persistence, a host action, a schedule reconciliation or
a provider drain. Those are no longer treated as finished.

The chat abort route's refusal for a background child's job moves out of the
CJS route into createBackgroundChildAbortGuard, registered ahead of it.

* ♻️ fix: Replace a Dead Background Child's Job on Its Thread

A background child's job outlives an owner that crashed, or a settlement that
could not reach the store, for up to twenty minutes. A continuation of the
thread in that window was refused its own stream, because the dead job still
read as live. The caller of open holds the thread's lease, so a background
child's job still marked live there has lost its owner: it is replaced and its
readers are told to refetch. A live job that is not a background child's, such
as an event-bound child paused for approval, is still never replaced.

* 🧱 fix: Fail the Abort Guard Closed and Budget Content Against the Whole Row

Review round 2.

The abort guard passed the request on when its job lookup failed, so a
retried lookup in the route could run the chat-shaped abort on a child the
guard never saw. A failed lookup now ends the request at the error boundary.

A child's streamed content was checked against its own limit only. A result
row also carries the text and the transcript, so content that passed the
limit could push the document past MongoDB's 16 MiB and turn a successful
child into a failed one. The content is now the optional field: it is left
off whenever the row's large fields together would exceed the budget.

Also accounts for the guard's job read in the two abort route specs that
sequence it, and gives the limiter spec's api mock the guard.

* 🪶 refactor: Settle a Child Stream Once and Fold a Frame It Cannot Copy

The task store settles a child's stream on its outcome path and again in its
cleanup. The second call made another terminal claim that could only lose;
the stream now remembers that it claimed and only persists. A frame that
cannot be copied is still folded from the original, so the stored content
stays whole when the stream detaches over it.

* 🧪 test: Cover the Child Stream's Failure Branches and the Content Fold

The change-risk report showed the stream's fail-open branches untested: a
terminal claim that lands after its wait, a claim or a final publish that
throws, the settle timeout, the backlog limit, and a rejected touch. Each now
has a case. The shared content fold gets direct cases for a closed step, a
commentary phase and an applied steer.
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