6.8 KiB
Workflows calling workflows
Status: Draft
Date: 2026-09-26
Bead: archie-core-t2db.41
Extends: docs/prds/event-automation.md (workflow/binding/profile model), docs/prds/state-store-contract.md (two new RPCs), docs/prds/execution-tree-state-machine.md (call kind)
The call, end to end
caller run (in agent container)
workflow.call step ──StartCall──▶ State Store EnqueueCallTask(caller, workflow, inputs)
│ callee task row: org/identity/owner/repo
│ derived from the caller row server-side
▼
callee task (queued, org of the caller)
│ daemon claims, pins the callee's OWN
│ definition → its OWN agent profile
▼
callee run (its own container, own tree)
wait: true ──poll──▶ State Store WorkflowCallStatus(caller, callee)
wait: false ──continue
A workflow.call step starts the callee as a first-class task and, with
wait: true, waits for its terminal state. The callee is never run "inside"
the caller: it gets its own task row, its own pinned definition, its own
profile, its own container, and its own outcome on its own run
(execution-tree-state-machine.md).
Save-time checks (the collection is the authority)
All semantic checks run in workflow.ValidateDefinitionCollection, the gate
every save and load of the workflow-definitions resource passes through.
A single-definition parse cannot see callees, so it validates shape only.
- Callee exists. A call to a workflow outside the collection is refused.
- Inputs checked. A call value is a literal or a reference
(
inputs.<name>) to the calling workflow's declared input. References must name a declared input; the resolved type must satisfy the callee's declared type; unknown callee inputs are refused; a required callee input must be assigned. - Self-calls refused. The call graph over the collection is walked from
every workflow; a workflow that reaches itself, directly or through other
workflows, is refused with the cycle path. (Cycles can otherwise deadlock:
wait: truecallers hold their containers.) - Repository.
workflow.callneeds no repository, so it is legal in arepository: noneworkflow: the callee inherits the caller's task record (owner/repo/identity/org), and the callee's ownrepositorymode decides whether its run clones. - Org enablement (bead
archie-core-t2db.42): the single instance-wide collection the current model serves is what "enabled for the caller's org" resolves against — an undefined callee parks. The callee's org is derived from the caller's row, so a callee is never visible outside its caller's org. The per-org enable/disable catalogue lands witharchie-core-t2db.42and becomes the one source of this predicate.
Runtime
Depth limit. workflow.MaxCallDepth (5). The calling stage refuses a call
that would exceed it; the store re-checks on insert (callee depth = caller
depth + 1), so no path can enqueue past the limit.
Starting the callee. The caller runs inside a container whose task-scoped
State Store grant authorizes only Update/Transition/InsertEvent on its
own task — it can neither enqueue a task nor read another one. One new
contract RPC starts the callee:
EnqueueCallTask(caller_task_id, workflow, inputs_json) → task— the store reads the caller row, refuses a caller that is notrunning, refuses past the depth limit, and inserts the callee row deriving org, workspace, identity, owner, repo and a fresh synthetic issue number from the caller (the same org COALESCEEnqueueIssue/InsertChatTaskuse). The callee row carriescall_parent_task_idandcall_depth.
Waiting on the callee. One new read RPC returns a call's callee:
WorkflowCallStatus(caller_task_id, call_task_id) → (status, detail)— the handler verifiescall_parent_task_idmatches, so a caller reads only its own callees, and returns the callee's status plus its latest transition detail (the callee's summary — the wait:true "outputs" until a structured outputs model lands).
Both RPCs are admitted to task-scoped grants on caller_task_id == granted task ID (authorizesTaskScopedCall gains two request-shape cases). This is
the one sanctioned widening of a task grant: the callee is the caller's child,
and starting it is the mechanism by which one event becomes several runs. The
widenings stay request-shape checks; the parent-child authorization is a
handler-side row check, so the interceptor never reads the database.
Schema. tasks gains call_parent_task_id (bigint, default 0) and
call_depth (int, default 0); both cross the wire on the Task message.
Columns default so existing writers and rows read as depth-0 root runs.
The engine capability. The workflow domain owns a consumer facade,
task.Caller (2 methods), carried by *staterpc.Client and wired into
TaskContext.Calls by the agent worker's composition root — the same shape
as workflow.Store. A runner with no Calls capability fails a
workflow.call step with a named error rather than pretending.
Semantics.
wait: false— start, record a durableworkflow_call_startedevent, and continue. The callee's outcome is reported on its own run.wait: true— start, then pollWorkflowCallStatus(2 s, bounded by the task's wall clock) until the callee is terminal.completed,pr_openandmergedsucceed the step;parked,failed,rejected,deadandclosed_wont_dofail it with the callee's detail in the error. A durableworkflow_call_finishedevent carries the terminal status and detail.- The caller's own stage/attempt accounting is unchanged: the call is one stage that took as long as its callee.
- A callee inherits the caller's task record but is otherwise independent:
retry, park and cancel of the callee never rewrite the caller. Cancelling a
caller cancels its callees through the operator action on each
(
execution-tree-state-machine.md"Cancellation"); until the tree state machine lands, a caller cancelled while waiting fails its stage and leaves the callee running — the same semantics aswait: false.
What is deliberately not here
- Declared outputs.
wait: truereceives the callee's terminal detail, not structured outputs; the outputs model is its own bead. - The StepExecution tree. The
callkind is designed for inexecution-tree-state-machine.md; this design lands the behaviour without the per-step records. - Per-org enablement — bead
archie-core-t2db.42's catalogue is the source once it exists.