# Automation Runtime and Guarantees

> What Type.com does from deploy to the end of a code automation run: the VM, agent tasks, queueing, access, state, guarantees, retries, and failures.

Canonical page: https://docs.type.com/automations/reference/runtime/

This is what Type.com does from deploy to the end of a code automation run: the VM, agent tasks, queueing, access, state, guarantees, retries, and failures. For the short version, see [Core concepts](https://docs.type.com/automations/how-it-works/index.md).

## The run at a glance

```text
Trigger: a schedule, a Slack message, a GitHub event, a webhook, an email, or a feed item
  └─ Type saves the event
  └─ Filters run on the server
  └─ The run starts
       ├─ Instruction automation: the managed agent runs the instructions in a new thread
       └─ Code automation: the subscription's entry stage runs
             ├─ code stages run in new QuickJS VMs and reach apps and the sandbox through ctx
             ├─ agent stages give one step to the managed agent
             └─ a code stage ends the run with complete() or blocked()
  └─ Run history records the output, the stages, and any errors
```

| | Instruction automation | Code automation |
| --- | --- | --- |
| What runs | The managed agent, in a new thread | A graph of code stages and agent stages |
| Skills | The managed agent loads named skills and finds others | In agent stages |
| Sandbox | The managed agent's sandbox | One sandbox for each run, shared by its stages, through `ctx.tools` |
| Acts as | The automation creator, for scheduled runs | The automation creator |
| Run time | One managed agent turn | Each code stage: its recovery window, 30 minutes by default. An agent stage can wait for a person. |
| After a failure | Safe temporary failures can retry. A schedule pauses after three failed runs in a row, or immediately when a person must act. | A stage retries only when waiting can help and its code did not start. Other failures fail that run; the automation keeps running. |

## Graph rules

A code stage can also return a `Promise`, a `Result`, or a `ResultAsync` of a decision. An `Err` fails the stage.

An agent stage's result always goes to the code stage in `onResult`. That stage's input is `{ taskInput, result, receipt }`; build its schema with `agentResult(agentStage)`.

When you omit `deployment.mode`, Type.com infers it from the graph: `code_with_optional_agent` when the graph has an agent stage, and `code` when it does not. An automation in `code` mode cannot run an agent stage.

Graph limits: 1 to 32 stages, up to 32 transitions for each code stage, and up to 64 stage invocations in one run. A stage name starts with a lowercase letter and has up to 64 letters, digits, and underscores. See [Limits](https://docs.type.com/automations/reference/limits/index.md).

## Deploy a code automation

```text
type-cli automations deploy
  └─ validation    typecheck the source, read the subscriptions, and check the graph
  └─ fixtures      run webhook adapter fixtures, then fixtures.json
  └─ subscription  check each subscription's source and access
  └─ activation    save the revision and turn on its subscriptions
```

- The CLI reads your files as data. No code runs on your computer. Type reads the `automation(...)` export in an isolated VM with no credentials.
- Each deploy saves a new **revision**. A failed deploy does not change the active revision.
- The first deploy turns the automation on. A later deploy keeps the automation paused if it was paused.
- After Type pauses an automation for a failure, a deploy is refused until a member enables the automation again.
- The automation belongs to a Space and to the person who created it. Only the creator can deploy changes to it.

## Run a code automation

```text
Event or schedule
  └─ Type saves the event
  └─ Resource filters and the matcher run on the server
  └─ Debounce groups events, if set
  └─ The run waits in the automation's queue
  └─ The entry stage runs with { ctx, input }
  └─ Type saves the stage's decision, its output, and its checkpoint together
  └─ next(): the next stage runs. complete() or blocked(): the run ends.
```

### Code stages

Each code stage invocation starts in a new QuickJS VM. The VM:

- runs the saved code of the revision that the run started with,
- has no `fetch`, no file system, no shell, and no Node or Bun APIs,
- can import only the SDK, `zod`, `neverthrow`, and your project files,
- discards `console` output,
- has a 1 GiB memory limit,
- stops when the stage's recovery window ends: 30 minutes by default, and never longer. Retries of the same stage share that window.

Nothing in memory carries over from one stage to the next. Pass data in the `next()` input, or save it with `ctx.saveCheckpoint()`.

Your code reaches the outside only through `ctx`. Type checks each call. For shell work, `ctx.tools` can call a separate [sandbox](https://docs.type.com/automations/sandbox/index.md).

### Agent stages

When a run reaches an agent stage, Type.com starts the managed agent on a task, in a new thread in the automation's Space that is named after the stage. The agent acts as the automation's creator, with the automation's skills and model settings. It gets the stage's instructions, its input, and the result schema. It finishes the task by submitting a result that matches the stage's `output` schema. A final chat answer does not complete the task. Type checks the result, and then the `onResult` code stage runs.

The agent's reply stays in Type. To post or write the result somewhere, do it in the `onResult` code stage.

A question that the agent asks a person can wait for an answer with no time limit. A task needs attention if its thread is deleted, if the agent stops without an accepted result, or if it makes no progress for 24 hours. See [Agent Stages](https://docs.type.com/automations/agent-handoff/index.md).

### One stage at a time

Type runs one code stage at a time for each automation, across all its subscriptions. Other events for the automation wait in its queue.

- A `next()` to a code stage runs right away, before other queued events.
- While an agent stage works or waits for a person, the queue moves on, so later events can run.
- When Type accepts the agent's result, the `onResult` stage joins the queue. It runs with the run's original source and contracts.
- Different automations run independently.

Pausing an automation stops new runs. By default, each run in progress stops at its next stage: an agent stage that is already running finishes its turn, and no further stage starts. The person who pauses it can instead let runs in progress finish, through their later stages, on the version they started with. Automatic pauses, such as a deleted connection or a repair agent's request for human help, stop runs in progress at their next stage, and so do archiving and stopping runs in progress.

Saving a new version doesn't pause an automation. A run executes every stage on the version that was current when it was admitted, even after a newer version is saved: its code, definition, retry policy, and the model and instructions of its agent stages. Accounts, permissions and the channel are always current. New events, including events that were waiting to start, run the new version.

## Access and identity

- A run uses the access of the person who created the automation, and the connections of its Space. Agent stages also act as the creator.
- Type gives each code stage a scoped token for that stage. The VM never gets a provider credential.
- Type checks the connection's access for each event and each call.
- An AI agent in a thread can have more access than the automation. A call that works in a thread can fail in the automation.

## State

| State | Where | Lasts |
| --- | --- | --- |
| Checkpoint | `ctx.checkpoint`, `ctx.saveCheckpoint()` | Until the next successful save. One for each subscription. |
| Stage input | `next(stage, input)` | One stage invocation. |
| Output | `complete(output)`, `blocked(reason, output)` | In run history. Code cannot read it. |
| Saved data | `ctx.read.data` | Read only from code. |
| Sandbox files | The run's sandbox | Until the run ends. Later stages of the same run can read them. |
| Local variables | The VM | One stage invocation. |

Type.com saves a code stage's decision, its output, and its checkpoint together, after the stage succeeds. `ctx.saveCheckpoint()` replaces the subscription's whole checkpoint, and only if nobody saved it after the stage read it. If another run or version saved it in the meantime, Type keeps that checkpoint and saves the stage's decision, output and follow-up runs without its own. The run still succeeds, with a note that its checkpoint was not saved. Writes to other apps happen when you call them. They are not part of this save. See [Write Safely](https://docs.type.com/automations/safe-writes/index.md).

## Guarantees

| Type.com does | Type does not |
| --- | --- |
| Save each verified event before it starts work. | Promise the order of runs. |
| Run a provider retry with the same event ID only one time for each subscription. | Make external writes exactly once. An effect key does not prevent a second write. |
| Save a stage's checkpoint and decision only when the code stage succeeds. | Save the checkpoint of a failed stage. |
| Persist safe retries with their original occurrence, budget, and deadline across restarts. | Replay a stage whose code started, or treat missing logs as proof of safety. |
| Start at most one repair agent for an eligible code failure, and keep the automation paused for review. | Undo the writes of a failed run, replay it after a repair, or resume because an agent says it is fixed. |
| Keep events that it saved but did not start before a pause, and run them after resume. | Save events that come during a pause. |
| Start a schedule again after a resume: a cron at its next time, an interval at the next scheduler pass. | Run schedule times that passed during a pause. |

## Failures

Type.com retries a failed stage only when waiting can help, such as a rate limit or a temporary outage, and it can prove that the stage's code did not start. By default, it retries up to 3 times, after about 30 seconds, 2 minutes, and 10 minutes, within a 30-minute recovery window. A retry keeps its place in the queue, so later events for the automation wait behind it.

When a stage fails and cannot be retried, the run is recorded as failed and the automation keeps running, however many runs fail in a row. Type never replays the failed run.

- A code failure starts one repair agent in the Space. The agent tries to save corrected code as a new version, with a fixture that reproduces the failure, while the automation runs. That is its goal, not a guaranteed result. While that version keeps failing, later failures use that repair. Another repair starts only after a successful run, a newly saved version, or 24 hours without a failure.
- A saved account that refuses a request during a run starts a repair agent that checks what it can change and tells the owner which account to reconnect.
- A saved account that is unavailable before a run starts fails that run without a repair agent. Runs succeed again once a member reconnects it.
- A failure after a write may have gone through, and a platform failure after the code started, fail that run without a repair agent.
- If retries run out before the code started, for example during a platform outage, the run is recorded as failed.
- When most of an automation's recent runs have failed, Type alerts its owner that it keeps failing.

A repair agent pauses the automation only when it judges that further runs would do harm. A member then reviews its report and selects **Enable**.

See [Troubleshoot and Fix Failed Runs](https://docs.type.com/automations/test-troubleshoot/index.md).
