Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
Delegation threads
Delegated work runs in a child thread so the work card can link to its full
execution history. The child thread carries parentThreadId and
parentDelegationId on its creation command, event payload, read model, and
shell. Both fields are nullable and optional at the decode boundary so events
and clients from before this feature continue to replay.
Parent-linked threads are execution details, not a bot's user conversation. Navigation selectors, roster message derivation, the web sidebar, mobile thread lists, and server thread search therefore omit them. Work cards retain the child thread id and remain the supported path to open that detail.
The web roster also remembers each bot's last chat path. Because a remembered
path can point at a thread that is not in the child-free shell list yet,
useBotChatTarget checks the target's own shell and drops it when the shell is
parent-linked or belongs to another bot. A bot with only child threads resolves
to no chat, so selecting it starts its direct chat. The work view's Open
chat navigates to the child bot's route rather than the child thread.
Record fields for placement, retry, and triggers
Three fields on AkeruDelegationRecord support work cards in the chat and
scheduled delegation. Each has a decoding default, so records written before
the fields existed decode unchanged. Records are stored as JSON, so no
migration was needed.
anchorMessageIdis the user message that started the parent turn.send()reads it from the parent thread'slatestTurn.requestMessageIdwhen that turn matches the delegation'sparentTurnId, and leaves itnullotherwise. Old records default tonull.retryOfDelegationIdpoints at the delegation a retry replaces. A retry is always a new record; the original is never mutated. Defaults tonull.triggeris"bot"for work a bot started withSendToAgentand"scheduled"for work a routine started. Defaults to"bot".
botChatTimeline in @akeru/client-runtime/state/bot-chat-timeline merges a
chat's messages, receipts, and delegations into one ordered list for web and
mobile. A card goes after its turn: after the anchor message and any later
message in the same parentTurnId. Without a known anchor it goes after the
turn's last message, and without either it goes at the end of the chat. Cards
at the same spot keep creation order.
Routines carry delegateToBotId, the bot a scheduled run hands its work to.
It defaults to null, meaning the routine's own bot does the work, and is
stored in the delegate_to_bot_id column of projection_routines (migration
71).
Lifecycle
SendToAgent returns a handle as soon as the child thread and its first turn
are dispatched. The handle carries delegationId, childThreadId,
childBotId, the bot name, and phase: "running". The parent turn keeps going
and usually replies before the child finishes.
AkeruDelegationRuntime watches each child in the background. When the child
turn ends it records the outcome as a delegation.updated event with a
Completed or Failed phase and acknowledgedAt: null, then appends an
activity to the parent chat. Mastra child turns report through the controller's
turn result. Every provider that can receive delegated work runs on the
controller, so no child turn reports through the legacy bridge. drain() resolves once every background watch has
recorded its outcome, so tests wait on it instead of sleeping.
A child started by a parent turn that later completes keeps running. When a
parent turn is interrupted, the runtime cancels the children that turn started.
When it fails, the runtime fails them with parent_failed and interrupts their
turns. Children marked keep survive both. Only children whose parentTurnId
matches the ended turn are settled, so work started by earlier turns is never
touched.
Restarts
The watch that settles a delegation lives only in the server process, so a
restart loses it while the record stays Queued or Running. Startup
therefore runs reconcileDelegations in apps/server/src/serverRuntimeStartup.ts
before the orchestration reactors start. It moves every Queued and Running
record to Failed with failure code internal and the message "The server
restarted before this work finished." Ownership, child thread and turn ids, and
startedAt are kept; completedAt is the restart time, so the card stops
counting. acknowledgedAt is null, so the parent bot hears about the failure
on its next turn, and the card offers Retry like any other failure. Running
before the reactors means no delegation from the new process can exist yet.
Blocked work waits on the user and is left alone, as are terminal records, so
a second startup writes nothing. Liveness is never inferred from elapsed time.
Routine recovery then settles any scheduled run whose work this failed (see
Scheduled delegation below).
ProviderCommandReactor startup recovery skips every thread with a
parentDelegationId. It neither replays a pending turn start, resumes a
pending resume, nor continues an interrupted turn on a delegated child, because
no watch would observe that turn. Provider session reconciliation still marks
such a child's orphaned session as errored.
Child waiters and timeouts
AgentController keeps one waiter per running child thread in a
PendingWaiters registry (apps/server/src/provider/PendingWaiters.ts). Each
waiter is an Effect Deferred awaited under Effect.timeoutOrElse, so no wait
is unbounded:
- A delegation with a
deadlinetimes out at the deadline with the message "The delegation deadline expired." A deadline already in the past fails at once. - A delegation with no deadline times out after
AKERU_CHILD_WAIT_DEFAULT_TIMEOUT(4 hours). Coding work can run for hours, so the bound catches a child that never reports back rather than a slow one.
Both cases reject awaitChild with PendingWaiterTimeoutError. The runtime
records that as a Failed phase with failure code timeout and interrupts
the child turn, so the card shows a timeout instead of running forever.
The registry lives in the controller layer's scope. When the layer shuts down,
its finalizer fails every outstanding waiter with PendingWaiterClosedError
("The agent controller stopped.").
Routine reviews use the same registry type. createRoutine opens a
dynamic_tool_call request and waits up to AKERU_ROUTINE_REVIEW_TIMEOUT
(1 hour) for the user's answer. An answer claims the review before the routine
is created, which stops the timeout, so an answer that arrives in time decides
the outcome even when creation finishes after the limit. The tool call then
returns the created routine or the creation error. On timeout the controller
resolves the request as a system cancellation (actor: "system",
outcome: "cancelled"), returns the session to running, and the tool call
fails with a message the bot relays. An answer that arrives after the timeout
is rejected as stale and creates nothing. A turn that ends first rejects its
open reviews, and layer shutdown fails any that remain. Routine reviews run only on the Mastra
path (Codex, Claude, Grok, Kimi For Coding, OpenCode Go).
Waiting on children
isThreadWaitingOnChildren in @akeru/contracts is true while any
delegation for the thread is queued, running, or blocked. The flag is derived
from the read model and never persisted. Web and mobile read it through
@akeru/client-runtime/delegation-presentation, which also derives each
card's delivery state.
Result delivery
A finished result is delivered to the parent bot exactly once, in one of two ways.
- The next parent turn. The decider handles
thread.turn.startby finding everyCompletedorFaileddelegation of that thread withacknowledgedAt: null. In the same command it emitsdelegation.updatedwithacknowledgedAtset for each one and lists their ids in the turn start event'sacknowledgedDelegationIds. Because acknowledgement and turn start are one persisted step, a restart replays the same state and cannot deliver a result twice or lose one.ProviderCommandReactorreads those records and passes them to the provider asdelegationResults, formatted bydelegationResultsContext. Each summary is shortened to about 4,000 characters; the card keeps the full text. CheckAgent. The tool returns each delegation'sstateandsummary(the result summary or failure message). Reading a finished, unacknowledged result acknowledges it, so the next turn does not repeat it.
If the parent never takes another turn, the result stays pending and the card
says it is waiting for the next reply. If the turn start fails before its
provider reads the results, ProviderCommandReactor releases their
acknowledgement so the next parent turn receives them, retrying in the
background when the release cannot land at once. It records the
provider.turn.start.failed activity before the session error clears the
pending turn start, so after a restart startup recovery either replays that
turn start or finds the failure and releases the results it acknowledged.
Canceled delegations have no result to deliver.
Provider injection
| Provider | Path | Where delegationResults goes |
|---|---|---|
| Codex | Mastra | Per-turn persistentMemoryContext |
| Kimi For Coding | Mastra | Per-turn persistentMemoryContext |
| Claude | Mastra | Per-turn persistentMemoryContext |
| Grok | Mastra | Per-turn persistentMemoryContext |
| OpenCode Go | Mastra | Per-turn persistentMemoryContext |
| OpenCode | Legacy bridge | Cannot delegate |
driverSupportsDelegation in @akeru/shared/delegationProviders names the
drivers in the Mastra rows. AgentController uses the same predicate to route
a turn to the controller, so a driver that gets the Akeru tool catalog is
exactly a driver that can delegate. delegationProviderMatrix.test.ts runs
send, access grant, result, usage, cancel, and the depth cap against each of
the five.
Legacy bridge providers
Standard OpenCode runs on the legacy bridge, which registers no tool session.
Its bots never see SendToAgent or the other delegation tools. A bot on
another provider that sends work to an OpenCode bot is refused before any child
thread exists: send resolves the target's driver through the
providerDriverKind option and throws
AkeruDelegationProviderUnsupportedError, which the tool runtime reports with
failure code denied. The message names the target bot and tells the sender
to do the work itself or pick a bot on another provider. When
providerDriverKind returns null because the target's provider instance no
longer exists, send refuses with "The target bot is not available in this
workspace." and also creates nothing.
Clients show the same limit before anyone asks. On web, the bot Tools sheet
shows a note for a bot whose provider cannot hand off work, and the group
@ picker marks such a bot with "Cannot take handed-off work"
(botEngineTakesDelegatedWork in botEngineSelection.ts). On mobile, the
group @ picker adds the same marker (groupMentionBots in
composerMentionItems.ts), and chat settings show the Tools note under
Options. Both use driverSupportsDelegation. A bot without an engine, or
whose provider instance the client cannot find, is not marked. MCP bot tools
for the legacy bridge are tracked separately.
Groups
A bot in a group chat can send work only to bots that are members of that
group. send checks membership before it creates anything and fails with
"The target bot is not available in the current group." A direct chat can
send work to any available bot.
The child always runs in a direct thread with the target's botId and
groupId: null, even when the parent is a group chat. When the child
completes, the runtime records the result as usual and then posts a
server-authored assistant message to the group:
Finished work for {parent bot}: {task} followed by the summary. The message
has ID delegation-result-{id} and respondingBotId set to the child bot, so
the group shows it from the bot that did the work. It starts no turn. The
runtime reads the parent bot's name when the child completes, so a rename
during the work shows the current name.
The delegation stays completed even when the group cannot take the result.
If the child bot left the group, was archived, or the group is gone, the
runtime skips the post and calls onGroupResultSkipped with
bot_left_group or group_unavailable. AgentController logs that at info
level. The runtime checks before it posts and again when the decider refuses
the message, so a member removed mid-post is reported the same way. Any other
delivery error goes to onWatchError.
Channel turns
When the parent turn started from an external channel message, the turn start
message carries a channelOrigin. ProviderCommandReactor then formats
pending results with delegationResultsContext(..., { channel: true }), which
uses delegationSummaryText from @akeru/shared to write plain-text lines
without Markdown. Akeru never starts a follow-up turn when delegated work
finishes, so the external sender sees the result in the reply to their next
message.
Request limits
contextis optional free text the parent passes to the child. It is capped atAKERU_DELEGATION_CONTEXT_MAX_CHARS(8,000). The runtime rejects longer context withAkeruDelegationContextTooLongError, which the tool runtime reports with failure codevalidation.memoryScopesis an allowlist. Each requested scope must be one the parent turn holds, or the request fails. An omitted list grants the child no memory scopes.- A parent thread can have at most
AKERU_DELEGATION_MAX_CONCURRENCY(3) active delegations, and delegation nests at mostAKERU_DELEGATION_MAX_DEPTH(2) levels.
Sending to the same bot again
A second SendToAgent to a bot that already has work from the same parent is
allowed. It creates a new delegation with its own child thread and returns its
own handle. The earlier work is not replaced or merged. Both count toward the
concurrency cap, and each result is delivered separately.
Temporary workers are not delegations
Task, CheckSubagent, MessageSubagent, and StopSubagent start a
temporary worker inside the parent's own turn. The worker is a copy of the
bot under a narrower grant, not a delegation to another bot, so it is not
covered by this document's acknowledgement and delivery rules. See
Temporary workers in providers.md.
Reverse states
Every way into a delegation state has a way back out.
- Cancel.
delegation.cancelwithkeep: falsemoves live work toCanceledwithcanceledBy: "user". It does nothing to work that has already finished. - Let it finish.
delegation.cancelwithkeep: trueonly setskeepon the record, and the work keeps running. A kept child survives its parent turn being interrupted or failing. A bot can set the same flag up front withkeep: trueonSendToAgent. - Retry.
delegation.retrystarts new work from aFailedorCanceledrecord. The decider refuses any other phase, a record that another record already retries (itsretryOfDelegationIdpoints at it), and a retry when the parent chat already hasAKERU_DELEGATION_MAX_CONCURRENCYactive delegations. The refusals areOrchestrationCommandInvariantErrors whose detail is readable text. Once a retry exists, the original is superseded: a later retry has to start from the newest record. An accepted retry emitsdelegation.retry-requestedand leaves the original record untouched.ProviderCommandReactorthen callsAgentController.dispatchDelegationwith{ _tag: "Retry" }. The runtime sends a new delegation to the same bot with the original task, expected result, access grant,keep,trigger, and anchor, plusretryOfDelegationIdpointing at the original. A deadline carries over only if it is still in the future. The originalcontextis not stored on the record, so a retry runs without it. Storing it would put up to 8,000 characters on every record sent to clients. If the runtime refuses the new work, the reactor appends adelegation.retry.failedactivity to the parent chat with the reason.
delegationActions(record, delegations) in
@akeru/client-runtime/delegationPresentation lists the actions a work card
offers, given the chat's delegations. Live work offers keep, unless it is
already kept, and cancel when AKERU_DELEGATION_TRANSITIONS allows it.
Failed and canceled work offers retry unless isDelegationSuperseded finds a
record that already retries it, which matches the decider's rule. Completed
work offers nothing. Clients send the actions with the cancelDelegation and
retryDelegation orchestration commands.
On web, DelegationCard takes the chat's delegations and renders one button
per action in its actions slot (Let it finish, Cancel, Try again), disables them
all while a command is in flight, and shows the decider's refusal text in an
error toast. On mobile, buildThreadFeed stores each card's actions on its feed
entry, and ThreadDelegationFeedCard sends the same commands. The buttons
disable while a command is in flight, and a refusal shows in an alert with the
server's text.
Scheduled delegation
A routine with delegateToBotId hands each run to that bot instead of running
a turn in its own chat. The routines runtime adapter calls
AgentController.dispatchDelegation with { _tag: "Scheduled" }. The runtime
records the delegation with trigger: "scheduled", parented on the routine's
chat with depth 0 and the owner bot's default grant. The run's approval policy
sets the runtime mode. The card anchors to the chat's last message when the
routine fired. The run's threadRef is the child thread, which is how the
runtime links the run to its delegation.
- A
Completeddelegation completes the run with the result summary. - A
Faileddelegation fails the run, opens an incident, and blocks the routine. - A
Canceleddelegation cancels the run. - Canceling the run cancels its delegation. A run canceled while its
delegation is still starting has no
threadRefyet. The decider refusesroutine.run.startfor a run that already ended, and the adapter then cancels the new delegation by thedelegationIdthe runtime returned. - Pausing or disabling the routine leaves running work alone. The pause only stops future runs.
- The web Done by picker leaves out the routine's own bot and lists bots
whose provider cannot take handed-off work as disabled options, using
routineDelegateOptionsinbotEngineSelection.ts. Mobile only shows the saved helper's name, so it has no picker to filter. checkDependenciesblocks a run up front, with "pick another bot" guidance, when the delegate bot is archived or missing, is the routine's own bot, or runs on a provider wheredriverSupportsDelegationis false (standard OpenCode). A run whose delegation the runtime still refuses is blocked with the runtime's reason.
Scheduled work has no live parent turn. Ending a turn in the routine's chat therefore never cancels it.
Routine recovery in apps/server/src/routines/RuntimeLive.ts also settles a
dispatched scheduled run from its persisted delegation. When the scheduled
delegation whose child chat is the run's threadRef has ended, recovery settles
the run the way the live delegation.updated path does. That covers work that
ended while the server was down and work reconcileDelegations failed at
startup, which no live subscriber sees. Recovery runs at startup and every
minute, and only settles a run that is still active, so it is idempotent.
A delegation that ends before routine.run.start records the run's
threadRef still does not settle the run, because recovery has no child chat
to match it by.