128 lines
6.8 KiB
Markdown
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. |