Actions and Modes

Every call to a Verb returns an 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 the caller chose.

Every call returns an ActionCopy Anchor Link

A well-formed, authenticated call always returns an Action. Invalid input, an unknown Verb, or a missing key fail at the edge with a plain error and no Action.

What the Thing decides is different. A wrong state, a spent Limit, or a Mandate out of scope returns an Action with status refused, its reason, and the refused error.

Take a 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, or by a cron schedule, it returns the same Action.

Who acted, for whomCopy Anchor Link

Every Action records by, the 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, it acts under a Mandate scoped by 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 statusesCopy Anchor Link

An Action has one of five statuses. Every change of status appends an Event.

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 must accept the result, acceptance is a separate Event, such as Close.accepted. The Offer bills on the Event it declares.

Why an Action waitsCopy Anchor Link

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

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 ModesCopy Anchor Link

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.

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 FunctionCopy Anchor Link

A Function is how a Verb executes. The caller never sees which kind runs, because every call returns the same Action.

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 verdicts agree with the reviewer on 95 percent of closes. No caller changes a line.

NextCopy Anchor Link

What a Startup sells: the four kinds of Product, and how each one earns.