# Actions and Modes

URL: /code/builders/startup/actions-and-modes · Id: `page:code/builders/startup/actions-and-modes`

> Every call to a Verb returns an Action, with a status, a reason while it waits, who acted for whom, the Mode the caller chose, and a hidden Function.

Every call to a [Verb](/business/nouns/verb) returns an [Action](/business/nouns/action), whoever calls and whoever does the work. The Action carries a status, a reason while it waits, who acted for whom, and the [Mode](/business/nouns/mode) the caller chose.

## Every call returns an Action
A well-formed, authenticated call always returns an Action. [Invalid input](/code/api/errors/invalid-input), an unknown Verb, or a missing key fail at the edge with a plain error and no Action.

What the [Thing](/business/nouns/thing) decides is different. A wrong state, a spent [Limit](/business/nouns/limit), or a [Mandate](/business/nouns/mandate) out of scope returns an Action with status `refused`, its reason, and the [refused](/code/api/errors/refused) error.

Take a [Startup](/business/nouns/startup) that closes the monthly books for small design studios. Its `Close.run` Verb reconciles a month of bank lines. Called by a client, by the Startup's own [Agent](/business/nouns/agent), or by a cron schedule, it returns the same Action.

## Who acted, for whom
Every Action records `by`, the [Worker](/business/nouns/worker) that acted, and `for`, the party it acted on behalf of. When an Agent acts for someone else, the Action also names the Mandate that let it.

An Agent acts in one of two ways. As itself, it uses the Startup's own accounts and identifies as an agent. For a [Human](/business/nouns/human), it acts under a Mandate scoped by [Channel](/business/nouns/channel), volume, topics, and Limits, and the Human is the author of record.

The bookkeeping Startup's Agent emails a client's vendor as the client, under the client's Mandate. The Action reads `by: agent`, `for: client`, and names the Mandate. The client sees every message sent in their name, and pausing or revoking the Mandate takes effect at once.

## Five statuses
An Action has one of five statuses. Every change of status appends an [Event](/business/nouns/event).

| Status | Meaning |
| --- | --- |
| `pending` | Not finished. Its reason says why. |
| `done` | Finished, with a result. |
| `failed` | Finished, with an error. |
| `canceled` | Stopped before it finished, by a caller, a watcher, or a deadline. |
| `refused` | Never started: the state, a Limit, or a Mandate did not allow it. |

A finished Action is final. A retry after `failed` is a new Action, linked to the one that failed.

`done` is the doer's claim. Where a [Customer](/business/nouns/customer) must accept the result, acceptance is a separate Event, such as `Close.accepted`. The [Offer](/business/nouns/offer) bills on the Event it declares.

## Why an Action waits
A `pending` Action always names its reason. `running` means the platform is executing; every `Awaiting` reason names who holds the work while nothing runs.

| Reason | The Action waits for |
| --- | --- |
| `queued` | Capacity to start. |
| `running` | Nothing: it is executing now. |
| `retrying` | A failed step to run again after a backoff. |
| `awaitingWorker` | A Worker to answer a [Task](/business/nouns/task), such as an [Approval](/business/nouns/approval). |
| `awaitingInput` | The caller or a Customer to supply something. |
| `awaitingSource` | An outside [Source](/business/nouns/source) to respond. |
| `awaitingAction` | A child Action to finish. |
| `awaitingTime` | A scheduled time or a delay window to pass. |

An operator scanning a queue sees at once whether the platform is busy or a person is late. A month close stuck on `awaitingInput` is the client's missing receipt, not a slow server.

## Three Modes
A Mode is how long the caller waits and whether the call is stored. Each Verb declares a default Mode and the Modes a caller may choose.

```ts
import { $ } from 'startup-builder'

const preview = await $.try.Period.close({ period: 'period_2026_09' }) // waits, stores nothing
const action = await $.send.Period.close({ period: 'period_2026_09' }) // returns at once, status pending
const period = await $.do.Period.close({ period: 'period_2026_09' }) // waits for the finished Action
```

`try` suits previews, quotes, and lookups, and has no side effects. `send` suits long work and steps a Human takes: the caller gets the `pending` Action and follows its Events. `do` holds the call until the Action finishes, and is the default for writes.

The API takes `?mode=send` and answers `202` with the `pending` Action; the CLI takes `--send`. Every call in every Mode is metered as a usage Event, and nothing billed is ever sampled.

## Four kinds of Function
A [Function](/business/nouns/function) is how a Verb executes. The caller never sees which kind runs, because every call returns the same Action.

| Kind | Does the work | In the bookkeeping Startup |
| --- | --- | --- |
| `code` | Deterministic code. | Matches bank lines to invoices by amount and date. |
| `generative` | A model that writes content or structured data. | Drafts the month-end summary for the client. |
| `agentic` | An Agent taking steps with [Tools](/business/nouns/tool). | Chases an unmatched payment through the client's inbox. |
| `human` | A Human, through a Task. | Signs a tax filing that the law reserves to a credentialed preparer. |

Work goes to the cheapest kind that can do it. A miss or low confidence escalates one rung: code, then generative, then agentic, then human. Because the kind is invisible, a Startup moves a Verb between kinds without changing its API.

The bookkeeping Startup first runs `Close.review` as a human Function. It moves the Verb to an agentic Function once the Agent's [Evaluator](/business/nouns/evaluator) verdicts agree with the reviewer on 95 percent of closes. No caller changes a line.

## Next
[What a Startup sells](/products/four-kinds): the four kinds of [Product](/business/nouns/product), and how each one earns.