forking

Conversation Forking

A fork branches a conversation at a completed-run boundary. CubePi gives you two variants:

• Agent.fork(...) — a persistent fork. Copies messages from the source thread up to and including a chosen run_id into a brand-new thread you can continue to converse with.
• Agent.fork_once(...) — an ephemeral one-shot probe. Loads a snapshot in memory, runs one prompt, and returns the result without writing anything back to the source thread.

Both APIs key off run_id — a stable identifier for one prompt() → final assistant message cycle. Every message produced during a prompt carries the same run_id, so "the boundary after run R" is an unambiguous, reproducible cut.

The cubebox copy-button UX

The driving use case is the cubebox "branch this reply" button: under every assistant message in the UI there is a small affordance that forks the conversation into a fresh thread starting from the message above it. Users use it to explore "what if the assistant had answered this differently?" without polluting the original thread.

In that flow:

• the host generates the new thread's id (cubebox uses uuid7),
• calls Agent.fork(src, new, after_run_id=...) to materialise the branch, and
• opens a fresh agent against the new thread.

The features below — explicit run_id, active_run_id, fork APIs, and the HITL binding rules — are exactly what that UX needs.

Agent.prompt(run_id=...) — accept-or-generate

Agent.prompt() now returns the run_id it used for the call:

run_id = await agent.prompt("hello")
print(run_id)  # → "8c0b…" — server-generated

Hosts that want to control the id (cubebox, multi-machine relays, anything that needs the id before the call completes) can supply it:

import uuid_extensions   # or whatever uuid7 source you prefer

my_run_id = uuid_extensions.uuid7str()
run_id = await agent.prompt("hello", run_id=my_run_id)
assert run_id == my_run_id

While the run is in flight, the id is available on Agent.state.active_run_id: