A Robot is woken by **triggers** and pushes results through **delivery channels**. Triggers and delivery are configured in the Mission Control UI — you do not write JSON config files manually.
This page explains the concepts behind each trigger type and documents the delivery payload format that your code receives.
---
## Triggers
Triggers are configured per-robot in **Mission Control → Robot Settings**. Three trigger types are available:
| Trigger | Starts at | Description |
|---------|-----------|-------------|
| **Clock** | P0 (Inspiration) | Runs the full six-phase pipeline on a schedule |
| **Human** | P1 (Goals) | User or external system sends an instruction; skips P0 |
| **Event** | P1 (Goals) | Fires when a webhook arrives or a database row changes; skips P0 |
### Clock
Schedule-driven execution. Three modes:
| Mode | Behaviour |
|------|-----------|
| **times** | Run at specific times on specific days (e.g. 09:00 and 18:00, Mon–Fri) |
| **interval** | Run every N duration (e.g. every 2 hours) |
| **daemon** | Run continuously — restart immediately after each completion |
All clock settings (times, days, timezone, timeout) are set in the Mission Control UI.
### Human
A Human trigger fires when a user sends an instruction to the Robot — for example, assigning a task, adjusting a goal, or giving a direct instruction. The intervention message becomes the goal context for P1.
Supported intervention actions:
| Action | Description |
|--------|-------------|
| `instruct` | Direct instruction to the Robot |
| `task.add` / `task.cancel` / `task.update` | Manage tasks |
| `goal.add` / `goal.adjust` / `goal.complete` / `goal.cancel` | Manage goals |
| `plan.add` / `plan.remove` / `plan.update` | Manage the plan queue |
### Event
An Event trigger fires when an external signal arrives. Two sources:
- **Webhook** — an HTTP `POST` to a configured path wakes the Robot. Optional filters match against the incoming payload.
- **Database** — Yao watches a table for inserts/updates that match the configured filter.
---
## Delivery
After P4 (Delivery Agent) produces its summary, Yao pushes the result through configured delivery channels. Three channels are available:
- **Email** — automatically sent to the Robot's manager; additional recipients can be configured.
- **Webhook** — POST to external URLs with a signed JSON payload.
- **Yao Process** — call your TypeScript function with a structured payload.
All three can be active at the same time. Delivery targets are configured in **Mission Control → Robot Settings → Delivery**.
As a developer, the Webhook and Yao Process channels require you to write code to receive the payload. The formats are documented below.
---
### Webhook
Yao sends a `POST` request to each configured URL with the following JSON body:
> **Note:** `trigger_type` is defined in the payload schema but may be empty in the current implementation. A fix is planned.
```json
{
"event": "robot.delivery",
"timestamp": "2025-01-01T12:00:00Z",
"execution_id": "exec-xxx",
"member_id": "member-xxx",
"team_id": "team-xxx",
"trigger_type": "clock",
"content": {
"summary": "Weekly report: 3 tasks completed.",
"body": "## Summary\n\n..."
},
"attachments": [
{
"title": "Task 1 result",
"description": "...",
"task_id": "task-xxx",
"file": "/path/to/file"
}
]
}
```
#### Signature Verification
If a signing secret is configured, Yao adds two headers:
```
X-Yao-Signature: <HMAC-SHA256 hex of the request body>
X-Yao-Signature-Algorithm: HMAC-SHA256
```
Verify in your server:
```typescript
import { createHmac } from "crypto";
function verifySignature(body: Buffer, signature: string, secret: string): boolean {
const expected = createHmac("sha256", secret).update(body).digest("hex");
return expected === signature;
}
```
---
### Yao Process
When the Process delivery fires, Yao calls your TypeScript function with a single structured argument:
```typescript
{
content: {
summary: string,
body: string,
attachments: Attachment[]
},
context: {
execution_id: string,
member_id: string,
team_id: string,
trigger_type: "clock" | "human" | "event"
}
}
```
#### Example: Custom Notification Script
```typescript
// scripts/notify.ts
import { Process, log } from "@yao/runtime";
export function Send(payload: {
content: { summary: string; body: string };
context: { team_id: string; trigger_type: string };
}) {
const { content, context } = payload;
log.Info("[notify.Send] delivery received", {
team_id: context.team_id,
trigger_type: context.trigger_type,
summary: content.summary,
});
Process("scripts.im.SendMessage", context.team_id, content.summary);
}
```
#### Extra Args
If extra fixed arguments are configured on the target, Yao passes them after the payload:
```
Send(payload, "extra-value-1", "extra-value-2", …)
```
The delivery payload is always the first argument.
---
### Using Multiple Channels
Email, Webhook, and Process can all be active at the same time. Yao calls all targets in sequence and logs any failures without stopping other deliveries.
