feat(agents): add a fork tool so Horton can branch the current session

[kevin-dp]

Summary

• Adds an optional anchor: 'latest_completed_run' field on the fork endpoint so callers without access to the source's per-row pointer side-table can still fork at the same anchor the UI uses.
• Adds ctx.fork(targetEntityUrl?, opts?) on HandlerContext, with auto-observe (runFinished + includeResponse) so the caller wakes when the fork's next run finishes. Defaults targetEntityUrl to ctx.entityUrl for self-fork.
• Gives Horton a fork tool plus a "When to fork (vs spawn_worker)" section in the system prompt framing the distinction: spawn for an isolated subtask with empty context, fork for parallel exploration that needs the conversation's full history.

How it composes

The minimal flow exercised against localhost:4437:

1. User: "What's 7 × 8?" → Horton answers, run completes (anchor exists).
2. User: "Now fork(), then send the fork '9 × 9', then end your turn."
3. Horton dispatches the fork, ends his turn. The auto-observed fork's runFinished wakes him with the response.

The "demo loop" the design was scoped to (analyze → fork N → synthesise the winner) needs an end-turn-then-fork pattern because the fork anchor is the latest completed run — anything mid-turn is excluded. The system prompt's new "When to fork" workflow walks Horton through this.

Wire shape

POST /_electric/entities/horton/abc123/fork
{ "anchor": "latest_completed_run" }

Server-side: reads the source root's main history, walks for the last runs row with status === 'completed', derives { offset, sub_offset } using the same pointer convention the runtime mints from onBeforeBatch, then runs the existing pointer-fork path with it. Mutually exclusive with fork_pointer (400 if both). 400 if no completed run exists.

Server-side rollout

This depends on the agents-server having the new anchor field. Local self-hosted servers built from this PR work immediately. Cloud (Stratovolt) needs to be redeployed on the new package before the tool works against it — without anchor handling, the old endpoint falls through to the HEAD-clone path's waitForIdleSubtree, which times out at 120s when an agent calls fork from inside its own turn (source can't become idle while the request is pending). Confirmed during local testing.

Known follow-ups

• Optional explicit anchor (deferred v2) — fork currently always anchors at "latest completed run." A messagesAgo or similar parameter to address earlier anchors is parked for a follow-up. The simplest case fits the demo flow; explicit addressing waits for a concrete use case to shape the API.
• Prompt nudge tightening — initial local testing shows Horton sometimes still inlines parallel work in his own response rather than reaching for fork. The "When to fork" section is in place but may need stronger directive language for ambiguous "give me three takes" prompts. Iterating on the wording is a small follow-up that doesn't change the tool surface.

Test plan

• npx tsc --noEmit clean across agents-server, agents-runtime, agents.
• Existing tests: agents-runtime 777/779 (2 pre-existing skips), agents 54/54. agents-server 360/402 with one pre-existing flake unrelated to this change (a docker port collision on the local box).
• Manual against localhost:4437: minimal fork() + send() round-trip; auto-observe wakes the parent with the fork's response; new entity tile appears in the desktop UI.
• Cloud rollout: deploy the new @electric-ax/agents-server to Stratovolt before announcing the tool works against Cloud.

🤖 Generated with Claude Code

[github-actions]

Electric Agents Desktop Builds

Build artifacts for commit e7c05a4.

Platform	Status	Artifact
macOS Apple Silicon	Passed	DMG
macOS Intel	Passed	DMG
Windows x64	Passed	Installer
Linux x64	Passed	AppImage / deb

Workflow run

[github-actions]

Electric Agents Mobile Build

Local mobile checks ran for commit e7c05a4.

The EAS Android preview build was skipped because the mobile-eas-build label is not present.
Add the mobile-eas-build label to this PR to produce an installable preview build.

Workflow run

[samwillis]

API shape: align ctx.fork with ctx.spawn

I think we should tighten the public ctx.fork API before this lands. Right now the shapes are quite different:

ctx.spawn(type, id, args?, opts?)
ctx.fork(targetEntityUrl?, opts?)

That makes fork feel like a minimal Horton-specific helper rather than a general runtime API. In spawn, id names the new entity being created. In fork, targetEntityUrl names the source entity being copied, while the new fork's instance_id is not exposed.

Could we make fork mirror spawn more closely, e.g.:

ctx.fork(sourceEntityUrl, id, opts?)

where id maps to the fork endpoint's instance_id, so id consistently means "the new entity being created".

For self-fork ergonomics, I'd also suggest a convenience wrapper rather than overloading the first string argument:

ctx.forkSelf(id, opts?)

That keeps ctx.fork(sourceEntityUrl, id, opts?) unambiguous while still making the common self-fork case concise.

Options: reuse the spawn options where possible

The opts object should probably mirror spawn as much as the semantics allow:

type ForkOptions = {
  initialMessage?: unknown
  wake?: Wake
  tags?: Record<string, string>
  observe?: boolean
  sandbox?: SpawnSandboxOption
}

initialMessage feels especially important. The expected workflow today is fork() then send(), but that makes branch creation a two-step operation and can leave idle forks behind if the second step fails. Making the initial message part of the fork operation would be cleaner and easier to reason about.

Similarly, wake should probably be configurable rather than hardcoded to runFinished + includeResponse; observe: false can remain the opt-out.

Reliability: partial success is currently reported as failure

There's also a reliability issue in the current implementation: ctx.fork() creates the fork first, then registers the auto-observe wake.

const { entityUrl: forkUrl } =
  await wiringConfig.forkEntity(targetEntityUrl)

if (opts?.observe !== false) {
  await doObserve(entity(forkUrl), {
    on: `runFinished`,
    includeResponse: true,
  })
}

If wake registration fails, the call rejects even though the fork already exists. Horton then reports "Error forking session" without the fork URL. A retry can create duplicate idle forks, and the original fork will not wake the parent.

If we add initialMessage and wake to fork, I'd prefer fork creation, initial dispatch, and wake registration to be handled atomically server-side. If that's too much for this PR, we should at least return/report the fork URL when observation setup fails so callers can recover.

Test coverage

Please add focused tests for the new anchor: "latest_completed_run" path:

• resolving the latest completed run into the expected fork pointer
• rejecting when the source has no completed run
• forwarding anchor through the HTTP route
• ideally, covering the fork + observe failure behavior above

[codecov]

Codecov Report

❌ Patch coverage is 18.84817% with 310 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.55%. Comparing base (048e2b6) to head (e7c05a4).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/agents-runtime/src/setup-context.ts	0.53%	186 Missing ⚠️
packages/agents-runtime/src/process-wake.ts	5.76%	49 Missing ⚠️
...ckages/agents-runtime/src/runtime-server-client.ts	5.88%	32 Missing ⚠️
packages/agents/src/tools/fork.ts	9.52%	19 Missing ⚠️
packages/agents-runtime/src/context-factory.ts	20.00%	8 Missing ⚠️
...agents-server-ui/src/components/EntityTimeline.tsx	0.00%	6 Missing ⚠️
packages/agents-server-ui/src/lib/sendMessage.ts	0.00%	6 Missing ⚠️
packages/agents-server/src/entity-manager.ts	93.33%	3 Missing ⚠️
...kages/agents-server/src/routing/entities-router.ts	95.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4489       +/-   ##
===========================================
- Coverage   69.21%   55.55%   -13.66%     
===========================================
  Files          77      301      +224     
  Lines        9238    34417    +25179     
  Branches     2878     9713     +6835     
===========================================
+ Hits         6394    19121    +12727     
- Misses       2826    15278    +12452     
  Partials       18       18               

Flag	Coverage Δ
packages/agents	70.52% <9.52%> (-1.00%)	⬇️
packages/agents-mobile	84.09% <ø> (?)
packages/agents-runtime	79.48% <3.16%> (?)
packages/agents-server	73.76% <93.84%> (+1.02%)	⬆️
packages/agents-server-ui	5.78% <0.00%> (?)
packages/electric-ax	46.42% <ø> (ø)
typescript	55.55% <18.84%> (-13.66%)	⬇️
unit-tests	55.55% <18.84%> (-13.66%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[kevin-dp]

@samwillis i addressed all your comments. Please have another look.

[samwillis]

Thanks for the update. This does address a good chunk of the earlier feedback: ctx.fork now uses an opts bag, has spawn-like initialMessage / wake / tags / observe options, moves wake registration into the server-side fork path with rollback, and adds useful coverage for the latest_completed_run anchor and wake rollback paths.

I think a few things still need tightening before this is ready:

Align ctx.fork with ctx.spawn by exposing branch id and target URL as positional args

The main API alignment point is still missing. spawn makes the new entity id explicit:

ctx.spawn(type, id, args?, opts?)

but ctx.fork still does not let the caller name the fork, even though the HTTP endpoint already supports instance_id:

ctx.fork({
  targetEntityUrl?,
  initialMessage?,
  wake?,
  tags?,
  observe?,
})

I'd prefer fork to follow the same positional-arguments-plus-options shape as spawn, with explicit positional args for the new branch id and source entity URL:

ctx.fork(id, targetEntityUrl, opts?)

Where:

• id maps to the endpoint's instance_id and names the new fork/branch.
• targetEntityUrl is the source entity to fork.
• opts carries the spawn-like behavior options.

For self-fork ergonomics, I'd make that explicit with a convenience wrapper rather than defaulting targetEntityUrl to the current entity:

ctx.forkSelf(id, opts?)

For example:

await ctx.forkSelf("branch-a", {
  initialMessage: { text: "Try approach A" },
})

await ctx.fork("branch-b", "/horton/source-session", {
  initialMessage: { text: "Try approach B" },
  tags: { experiment: "fork-api" },
})

This keeps id consistently meaning "the new entity being created" across spawn and fork, while avoiding implicit self-fork behavior.

Validate parent and wake subscriber inputs on the fork route

The route now accepts parent and wake from the request body and passes them straight into forkSubtree. forkSubtree then sets the new root fork's parent and registers a wake using wake.subscriberUrl.

That differs from spawn, which resolves/validates the parent entity before attaching the new entity to it. A direct API caller should not be able to attach a fork under an arbitrary parent URL or register a wake for an arbitrary subscriber without validation/authorization.

Please validate at least:

• parent exists
• the caller is allowed to create/attach a child under that parent
• wake.subscriberUrl matches/is allowed for that parent/caller, or is derived server-side instead of accepted from the body

Non-blocking: clarify initialMessage atomicity

The comments say the initial message is atomic with the fork RPC and prevents idle partial forks, but implementation still sends it after forkSubtree returns and after dispatch subscription linking:

const result = await ctx.entityManager.forkSubtree(...)
for (const forkedEntity of result.entities) {
  await linkEntityDispatchSubscription(ctx, forkedEntity)
}
if (parsed.initialMessage !== undefined) {
  await ctx.entityManager.send(result.root.url, ...)
}

If linking or send fails, the endpoint returns an error after the fork has already been created. That may be acceptable if making this truly transactional is hard on the server, but we should at least make the comments/docs precise so callers know initialMessage is delivered after fork creation rather than atomically rolled back with it.

Return shape parity

Less blocking, but still worth considering: spawn returns an EntityHandle, while fork returns only { url }. If forks are now children and use the same parent-ownership model as spawned workers, it would be cleaner if the handler API exposed a similar handle surface where practical.

[KyleAMathews]

Forking at run boundaries makes a lot of sense actually... that's the only coherent place to do it really. This would make it easier to fork at older points too as the UI could expose forking at each run point and then the run object itself could list its final offset to bridge from that to the offset.