Files
archie/docs/prds/workflow-calls.md
T

128 lines
6.8 KiB
Markdown

# 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: true` callers hold their containers.)
- **Repository.** `workflow.call` needs no repository, so it is legal in a
`repository: none` workflow: the callee inherits the caller's task record
(owner/repo/identity/org), and the callee's own `repository` mode 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 with `archie-core-t2db.42` and 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 not `running`,
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 COALESCE `EnqueueIssue`/`InsertChatTask` use). The
callee row carries `call_parent_task_id` and `call_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 verifies `call_parent_task_id` matches, 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 durable `workflow_call_started` event, and
continue. The callee's outcome is reported on its own run.
- `wait: true` — start, then poll `WorkflowCallStatus` (2 s, bounded by the
task's wall clock) until the callee is terminal. `completed`, `pr_open` and
`merged` succeed the step; `parked`, `failed`, `rejected`, `dead` and
`closed_wont_do` fail it with the callee's detail in the error. A durable
`workflow_call_finished` event 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 as `wait: false`.
## What is deliberately not here
- **Declared outputs.** `wait: true` receives the callee's terminal detail,
not structured outputs; the outputs model is its own bead.
- **The StepExecution tree.** The `call` kind is designed for in
`execution-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.