# Run-layer primitives

Each row is something an agent runtime should already give the agent. A design that proposes a replacement must name one of the four reasons in [SKILL.md](../SKILL.md). When your runtime lacks a primitive, the last column says what to build: build it once, for every feature.

## Deferred and repeated runs

| Need | Primitive | What it carries | Wrong pattern | If you lack it |
| --- | --- | --- | --- | --- |
| The user asked to run later or on a schedule | A scheduling tool the agent calls: `create` with `run_in`, `every`, or `cron` | A task id, the prompt for the next run, and a link to the origin conversation | A cron job per feature that starts agent runs | One generic scheduler for agent runs, exposed as one agent tool |
| The agent volunteers a follow-up that the user did not ask for | A proposal card that the user accepts; the schedule is computed at accept time | The proposed timing, the reason, and an optional watch check | Scheduling without consent, or a job that decides on its own to re-run | A proposal record plus an accept action that creates the scheduled task |
| "Is it still happening?" | A watch check on a scheduled task. Each run records `stable` or `triggered`; the task resolves itself after N stable checks | The check to run and the history of results | A table of open issues and a poller that re-checks them | A `watch_for` field on the task and one tool that records a check result |

A deferred run is a fresh conversation. It does not resume the transcript. It carries a stored summary of the origin conversation and the state of the follow-up. Anything the later run must know goes into a memory file or the task's prompt file before the current turn ends.

There is no `sleep`, `wait`, `timer`, or `resume_conversation` tool. Do not propose one. A turn that waits holds a model context, a sandbox, and a connection open for nothing.

## Wake-up when work finishes

| Need | Primitive | What it carries | Wrong pattern | If you lack it |
| --- | --- | --- | --- | --- |
| Continue the same conversation after work outside the stream completes (a subagent, a long command, an external job) | A completion event: the finishing work writes an event, and a dispatcher delivers it to the conversation once | The event kind, the result or its location, and a lease so that only one worker delivers it | A status column plus a job that polls it | An outbox table with claim, defer, and acknowledge, and one dispatcher for every kind of finished work |

Completion wakes the agent. Nothing polls for it. A new kind of finished work adds an event kind, not a poller.

## Memory across runs

| Need | Primitive | What it carries | Wrong pattern | If you lack it |
| --- | --- | --- | --- | --- |
| A scheduled task remembers between runs | One memory file per task id, with `## Active Notes` and `## Run Log` | Lessons the next run must apply, and a log of what each run found | A `save_findings` and `load_findings` tool pair plus a table | A file in the agent's workspace keyed by the task id, and a prompt line that tells the run to read it first |
| The instruction to use that memory | One prompt block: read Active Notes first, append a Run Log entry, promote stable lessons, leave scheduler bookkeeping out | The protocol, not the data | A backend job that summarizes old runs into the prompt | One paragraph of prompt text |
| Memory about incidents, reviews, or the workspace | Files with frontmatter, such as an incident file with `outcome: verified \| unverified \| failed` | Facts, their source, and whether a fix held | A memory service with its own API and store | A folder in the agent's workspace and a schema for the frontmatter |
| How the agent writes any of it | The agent's normal file tools: `read`, `write`, `edit`, `grep` | Nothing extra | A `save_memory` tool | Nothing; the agent already has a computer |

A memory write surfaces in the next conversation, not in the current turn. Most harnesses freeze per-conversation context on the first turn so that the prompt cache keeps working. A design that needs a write to be visible in the same turn needs a context block that re-renders, not a memory write.

## Durable model-visible context

| Need | Primitive | What it carries | Wrong pattern | If you lack it |
| --- | --- | --- | --- | --- |
| The model must see X on every turn of this conversation | One registered context block that the harness appends to the conversation history. It is frozen after the first render, or re-rendered each call when the subject moves | Rendered text. An empty render means "no news". A failed render raises, so the harness tries again on the next call | A tool that returns context; a message rebuilt on every request | A small block registry: `applies()`, `render()`, a stability flag, and a fixed order that keeps the prompt cache prefix stable |
| Where a new instruction belongs | Static system prompt for rules true everywhere; a context block for values per conversation; a tool description for how to call one tool; a reminder near one action | The right home for the text | Every rule in the system prompt | A short decision list in your contributor guide |

## Delegation and approval

| Need | Primitive | What it carries | Wrong pattern | If you lack it |
| --- | --- | --- | --- | --- |
| Bounded parallel or background work | Subagents, each with a brief and a complete list of the tools it may use | The brief, the tool list, and a final report back to the parent | A job-queue fan-out that starts separate agent runs | A spawn tool plus the completion event above |
| A human must answer before the turn continues | A blocking interrupt; one pending tool call per checkpoint | The exact action and the reason | A custom pause flag and a polling loop | Use the interrupt in your agent framework |
| A human may answer later | The proposal card above | The proposal | An email that asks the user to reply | The proposal record |

## Signal: what starts a run

| Signal | Primitive |
| --- | --- |
| A user turn | The chat stream |
| Time | The scheduler: `run_in`, `every`, or `cron` |
| An agent proposal the user enabled | The proposal accept action, which creates a scheduled task |
| Work that finished elsewhere | A completion event kind |
| An external event | A webhook handler or a detector that enqueues a run |

A new signal is a new event kind or a new webhook handler that enqueues a run. It is not a job that scans a table for work.

## Deliver: where a result lands

| Need | Primitive |
| --- | --- |
| Alert the user from a follow-up run | The watch check tool sends an alert when a check is `triggered` |
| An in-app notification | The notification feature |
| Slack, Teams, or email | The messaging feature |
| A way back to the screen | A stable URL for each record. Put it in every Operate `get` and `list` result and in every alert |

## The rules this ladder rests on

- Exhaust the agent primitives (prompt protocol text, the scheduler, memory file edits) before you add backend machinery.
- The file is the contract. The backend keeps only what cannot be a file instruction.
- The agent owns judgment. The backend owns identity, status, retries, validation, and what the model is shown.
- Separate the harness (what the model sees and may do) from the runtime (what keeps the run alive). A Run-layer need is almost always a harness change.
