Lifecycle & control

An agent is active while a wake runs, idle while it sleeps between wakes, and archived once it has been quiet long enough — and from the outside, you can intervene with exactly four verbs.

The states

        wake arrives                idle window passes
 idle ───────────────► active      idle ───────────────► archived
 active ──────────────► idle       archived ────────────► active
        turn ends                   any message (resurrection)

Nothing here is terminal. An idle agent is fully alive — it holds its state and wakes instantly. An archived agent has been put away — but as you'll see below, even that is reversible by sending it a message.

The four control verbs

Outside intervention is deliberately small: interrupt, pause, resume, archive. Anything else you want to tell an agent is just a message.

interrupt stops the current run cleanly. The run ends with run_finished(outcome: "interrupted") on the timeline, partial work already recorded stays recorded, and the agent remains immediately messageable — interrupted is not broken.

pause holds the agent: new wakes queue up instead of running, and nothing is processed until resume lifts the pause and works through the queue in order. Nothing sent to a paused agent is lost. A paused agent is also never auto-archived out from under you.

archive requests archival now instead of waiting for the idle window — same effect as the automatic path below.

teaspill control /a/researcher/01j9z8k3q7v2m8f4t6d1c5b0aa interrupt --reason "wrong topic"

Idle auto-archive

An agent that stays idle past its idle window — 30 minutes by default, tunable per deployment with TEASPILL_IDLE_ARCHIVE_MS — archives automatically: its complete state is stored in the catalog, its working footprint is released, and its catalog status flips to archived. This is the default cost model — you never pay for agents that have nothing to do, and you never write cleanup code.

Resurrection

Send any message to an archived agent and it comes back: same URL, same timeline, same memory. State is restored from the catalog, the message is processed as a normal wake, and — the detail that keeps histories whole — the event numbering continues where it left off. The event right after archived is the resurrecting wake's run_started. Nothing distinguishes an agent that archived and returned from one that never left, except the markers saying so.

Archive and resurrection together are why teaspill agents can be long-lived by default: a support agent per customer, a project agent per repo — idle ones cost storage, not compute, and any of them is one message from awake.

Steer: talking to a busy agent

Messages normally queue for the next wake. Steer injects a message into the agent's current run instead — mid-turn, between steps — for the "wait, also check X" moment when the agent is already working. If the agent isn't mid-turn, a steer degrades gracefully into a normal message: nothing is lost, it arrives as its own wake.

Steer is a delivery mode, not a fifth verb. Today it is how agents nudge each other: the send_message tool accepts mode: "steer", so a parent can redirect a freshly spawned child without waiting for the child's turn to end.

Custom control is messages

There is no fifth verb and no signal vocabulary. "Re-prioritize", "switch model", "drop that subtask" — anything domain-specific — is a typed message your agent declares a schema for and handles like any other input. The four verbs cover the platform's business (stopping, holding, shelving); everything about your agent's behavior stays in your agent's vocabulary.

Next steps

That completes the concept ramp. The Glossary collects every term in one place — from here, Building agents puts the whole vocabulary to work.