Approval (approvalGate)
Purpose
Holds a draft until the owner sends or discards it. A Normal-mode employee
with "Ask me before sending anything" on answers through
agent -> approvalGate -> reply: the gate records the agent's draft (who it
goes to, what it says), shows it as a card in the employee's chat, and waits.
Send lets the draft, or the owner's edit of it, through to the reply node once
the 5-second Undo window has passed; Discard (once Restore can no longer bring
it back), expiry or a Reset lets nothing through. The workflow's Ask first rule
is read live: with it off the draft goes straight through, recorded as sent
without asking; a workflow with no rule always asks. Hire builds this wiring
(services/employees/builder.py); the node is also usable by hand in the
editor. Feature overview: Normal mode; the decisions and
the card: Chat Protocol, Approvals.
Inputs (handles)
| Handle |
Connection type |
Required |
Purpose |
input-main |
main |
yes |
The agent's reply (drives the draft template) and the trigger's data (the recipient) |
Parameters
| Name |
Type |
Default |
Required |
displayOptions.show |
Description |
channel |
string |
"" |
no |
- |
The app the reply goes out through (shown on the card) |
recipient |
string |
"" |
no |
- |
Who the reply goes to, from the trigger (ints such as Telegram chat ids are coerced) |
recipient_label |
string |
"" |
no |
- |
How the card names the recipient |
subject |
string |
"" |
no |
- |
Subject line, for email |
draft |
string |
"" |
no |
- |
The message waiting for approval (capped at 20,000 characters) |
context_excerpt |
string |
"" |
no |
- |
The message being answered, shown above the draft (capped at 2,000) |
max_length |
int |
20000 |
no |
- |
Longest edit the channel accepts (1-20,000) |
timeout_hours |
int |
168 |
no |
- |
Hours before the draft expires (1-720) |
Outputs (handles)
| Handle |
Shape |
Description |
output-main |
object |
The decision (see below); fails closed |
Output payload (TypeScript shape)
{
approved: boolean;
status: 'approved' | 'discarded' | 'expired' | 'cancelled' | 'skipped';
skipped: boolean;
text: string; // the sent text (the edit if there was one); "" unless approved
subject: string; // "" unless approved
recipient: string; // "" unless approved
recipient_label: string; // "" unless approved
approval_id: string | null;
edited: boolean;
automatic: boolean; // it went without asking: Ask first was off
}
The reply node reads {{<gate label>.text}} and {{<gate label>.recipient}},
and its incoming edge carries {"field": "result.approved", "operator": "is_true"}
(services/approvals/contract.py::approved_edge_condition), so nothing is sent
unless the owner approved. The recipient always comes from the run's trigger,
never from the agent's text.
Logic Flow
flowchart TD
A[Receive params] --> B{draft empty or NO_REPLY?}
B -- yes --> S[Return skipped, no row]
B -- no --> C[Idempotency key: activity identity on Temporal, execution + node + inputs fingerprint in-process]
C --> R{new row and Ask first off?}
R -- yes --> A2[Create it approved and handed on, approved_by auto] --> O
R -- no --> D[get_or_create approval_requests row]
D -- created --> E[Broadcast approval_lifecycle requested]
D --> F{row status}
E --> F
F -- pending --> H{expired?}
H -- yes --> X[Settle expired, broadcast] --> O
H -- no --> J
F -- approved, Undo window open --> J
F -- approved, window over --> K[Hand it on: consumed_at] --> O
F -- discarded, Restore window open --> J
F -- discarded, window over / expired / cancelled --> O[Return the outcome]
J{worker shutting down?} -- yes --> W[Raise NodeWaitInterrupted: Temporal retries the attempt]
J -- no --> L[Wait for a notification, the window's end or POLL_SECONDS; re-read the row] --> F
Decision Logic
- Validation: parameters are coerced and capped by the Params validators;
extra="ignore".
- Branches: an empty draft, or exactly
NO_REPLY, returns
status: "skipped" and creates no row. The agent answers NO_REPLY when
nothing should go out; the gate's own incoming edge also carries
result.response != NO_REPLY.
- Identity:
t:{workflow_id}:{run_id}:{activity_id} inside a Temporal
activity, so a retry after a restart re-attaches to the same draft;
p:{execution}:{node}:{sha256(outputs)[:16]} in-process, where one
execution id can span several runs of a deployment.
- Waiting: a process-local waiter (
services/approvals/waiter.py) wakes
the gate the moment decide_approval moves the row; it also re-reads the
row every POLL_SECONDS (10), or at the end of an Undo or Restore window, to
see decisions made in another process and expiry. Undo moves an approved
draft back to pending, and the gate keeps waiting.
- Error paths: a worker shutting down mid-wait raises
NodeWaitInterrupted,
which BaseNode.as_activity turns into a retryable ApplicationError. On
the in-process path there is no retry, and the run fails as for any error.
Side Effects
- Database writes: one
approval_requests row per draft
(server/models/approvals.py): the
recipient, draft, final text, status, revision and expiry. Decisions are
compare-and-swap on revision.
- Broadcasts:
approval_lifecycle (source
opencompany://services/approvals, CloudEvents type
com.opencompany.approval.<stage>, subject = approval id). Identity only,
never the message body or the recipient; the chat refetches through
list_approvals. Node status waiting while it waits.
- External API calls: none.
- File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: none.
- Services: the approvals package
(
server/services/approvals/):
store, waiter, listeners, reconcile, queries, contract.
- Python packages:
temporalio (activity identity and worker shutdown).
- Environment variables: none.
Edge cases & known limits
- Runs on
TaskQueue.TRIGGERS_EVENT with a 24-hour start_to_close and
unlimited retries (maximum_attempts=0); expiry, not the retry policy,
ends a wait. Each waiting draft holds one slot on that queue's worker.
- A Reset cancels the workflow's pending drafts (
reset_execution_state), and
deleting the workflow removes its rows (workflow-deleted hook).
- Rows left pending by a crashed process are cancelled by
reconcile_once, which list_approvals runs: local rows created before
this process started, and Temporal rows whose generation is no longer live.
- Deciding while the employee is paused is allowed; the response carries
will_send_on_resume: true for an approved gate draft and the card says so.
Gate drafts resume through their graph's downstream admission gate.
- In a new controlled generation, an approval wait already admitted as a node
Activity counts as business work. Stop lets it settle on a decision or expiry
under its existing retries, retains the outcome, and can remain Stopping
while it waits. Resume admits the downstream action rather than recreating
the draft. This differs from separately approved tool calls, whose
ApprovedToolCallWorkflow send lifecycle is independent of generation Stop.
See Workflow control.
Related
- WebSocket handlers
(
services/approvals/handlers.py):
list_approvals {workflow_id?, status?, limit <= 100} returns the owner's
drafts, per-workflow pending counts and server_time;
decide_approval {approval_id, decision: "send" | "discard", text?, subject?, decision_key}
is idempotent per decision_key and validates edits against max_length.
Errors: already_decided, expired, cancelled, not_found, invalid_request.
- Other nodes that consume this output: the reply node of the app that
received the message (
whatsappSend, telegramSend, discordSend,
googleGmail, msMail, whatsappBusinessSend).
- Architecture docs: Normal mode,
Plugin System.