# Agent

> Agents: hosted agents you message by name.

## Agent

```typescript
class Agent
```

A hosted agent. `Agent.fromName("host", { createIfMissing: true, instructions })`
is lazy; `(await agent.message("hi")).text` talks to it.

An account-level agent is shared: each user that messages it (via
`asUser` or `{ user }`) gets its own conversations. A user's own agent
always talks as that user.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `origin` | `AgentOrigin | null` | `api` for an agent made through the API, `app` for one built in the NoClick app (an id like `node:<workflow>:<node>`). |
| `name` | `string` |  |
| `model` | `string | null` | The model it runs, as its harness names it (`sonnet`, `openrouter/...`). |
| `harness` | `HarnessName | null` | What runs it: `sdk`, `claude_code`, `codex`, `opencode`, `hermes` or `openclaw`. |
| `modelConnection` | `string | null` | The connection whose key or plan it thinks with, by name (null on `sdk` without one). Hidden, like `instructions`, from a user's session reading an account agent. |
| `instructions` | `string | null` |  |
| `tools` | `(string | JsonObject)[]` | What it can use, as listed: refs, `{ tool, bind }` for an operation with arguments bound and `{ human, tools }` for a person. |
| `toolRules` | `ToolRules` | What it may do with each app it reaches (`ToolRules`); empty, everything its tools give is allowed. |
| `canRequest` | `string[]` | What it may ask its user to connect at run time. |
| `userId` | `string | null` |  |
| `workflowId` | `string | null` |  |
| `nodeId` | `string | null` | An app agent's step in its workflow (null for an API agent). |
| `workflowName` | `string | null` | An app agent's workflow, by name. |
| `access` | `string | null` | An app agent's workflow as you hold it: `owner`, or `editor` or `viewer` when it was shared with you (only an owner's or an editor's takes messages). |
| `enabled` | `boolean | null` | Whether an app agent is switched on; a disabled one takes no messages. |
| `appUrl` | `string | null` | Where an app agent is changed: its workflow in the NoClick app. |
| `parentId` | `string | null` | Its parent, whose budget it draws on. |
| `ttlS` | `number | null` | The time to live it was created with, in seconds (null if it isn't temporary); `expiresAt` is when it runs out. |
| `expiresAt` | `Date | null` | When a temporary agent expires (null if it isn't): it then stays readable, `expired`, for 30 days. |
| `budgetUsdPerMonth` | `number | null` |  |
| `budgetRestore` | `{ budgetUsdPerMonth: number | null; operationId: string | null } | null` | While a budget set for one run holds (`update({ budgetForRun: true })`), the budget that comes back as that run ends and after which run (`operationId` null: its next turn); null otherwise. |
| `region` | `RegionName | null` | The region its sandboxes run in, fixed when it was created; `null`: wherever NoClick has capacity. |
| `machineId` | `string | null` | Invite-only beta. The `Machine` its harness runs on (null: a sandbox of its own). |
| `createdAt` | `Date | null` |  |
| `browserProfileId` | `string | null` | The browser profile its `browser` tool signs in with. |
| `cardId` | `string | null` | Invite-only beta. The card it holds and pays with (null: none of its own). |
| `volumes` | `Record<string, string>` | The volumes its shell mounts: `{ path: volume id }`. |
| `memoryId` | `string | null` | Its own memory (`agent.memory`) as a `Memory` id, to attach to other agents. |
| `skills` | `{ id: string; pin: number | null }[] | null` | Its skills: each `{ id, pin }` (`pin` null: the latest). |
| `memories` | `{ id: string; writes: boolean }[] | null` | The memories it reads besides its own, in order: each `{ id, writes }` (null for a user's session reading an account agent). |
| `secretIds` | `string[]` | The secrets in its shell's environment, in order (a later one's key wins). |
| `timezone` | `string | null` | The IANA timezone its turns tell the time in (null: the acting user's, else UTC). |
| `repos` | `JsonObject[]` | The repositories cloned into its workspace: each its `connection`, `repository`, `branch`, `path` and `push` globs. |
| `setup` | `string[]` | Commands its sandbox (its container, on a machine) runs as it starts, after its repos and before its harness. |
| `docker` | `boolean` | Whether Docker runs in its sandbox, a VM of `sandboxSize` (a coding harness only). |
| `sandboxSize` | `SandboxSize | null` | The VM a Docker agent works in; null without Docker. |
| `appTesting` | `AppTesting` | How it may turn Docker on for a task that needs it (`AppTesting`). |
| `appTestingUsdPerHour` | `number | null` | What an hour of app testing costs where its sandbox runs; null without a sandbox of its own. |
| `modelSwitching` | `Required<ModelSwitching>` | How it moves to another of the owner's model connections (`ModelSwitching`). |
| `switchedFrom` | `SwitchedFrom | null` | While a plan's limit has it on another connection, the one it left (its first turn after goes back); else null. |
| `movedFrom` | `AgentMovedFrom | null` | Where a move from a laptop made it (its move, machine, folder and when); null otherwise. |
| `network` | `NetworkAccess | null` | What its shell and code reach: `true` (anywhere), `false` (only what it needs to work) or the hosts it may reach besides, as sent. |
| `shell` | `boolean | null` | Whether it has a shell (the `code` capability; `false` only on `sdk`). |
| `turnLimits` | `TurnLimits | null` | How far one of its turns goes, as set (null, or a limit left out: 200 steps, $1 and 30 minutes). |
| `effort` | `string | null` | Its conversations' reasoning effort (null: the model's own). |
| `speed` | `"standard" | "fast"` | `fast`: its conversations run in fast mode. |
| `permissionMode` | `PermissionMode` | How far its coding harness goes before asking a person where a conversation sets nothing. |
| `approvals` | `Record<string, JsonObject>` | What its own calls wait for a person on in place of the account's, by kind of hold (`disposition`, `under_usd`, `until`, `effective_at`, `pending`), and `routing`: who answers its held calls first (`approver`, `on_timeout`, `expires_in_s`); empty where it sets none (a child follows its parent's). |
| `status` | `AgentStatus | null` | `working`, `waiting`, `idle` or `expired`; `paused` is its own field (pausing stops triggers, not work). Null, like the activity fields below, for a user's session reading an account agent. |
| `lastActiveAt` | `Date | null` | When a turn of its last started or ended (null: it never ran, or hidden like `status`). |
| `runningTurns` | `number | null` | How many of its turns are queued, running or waiting on a person, any conversation (null: hidden like `status`). |
| `childCount` | `number | null` | How many live (not expired) children it has (`children()` lists them; null: hidden like `status`). |
| `jobId` | `string | null` | The task it was spawned with (its operation id), or null. |
| `usedBy` | `UsedBy[]` | The apps that bind it: `kind` (`project`), `id`, `name` and the `binding` name. |
| `paused` | `boolean` | Whether `pause()` stopped its triggers (false too for a user reading an account agent). |
| `helper` | `boolean` | Whether it's one of NoClick's helpers, made for NoClick's own work rather than one of your agents: an app's coding agent (which NoClick hands each change to that app's code), or a child one of NoClick's own agents spawned. |
| `noclick` | `boolean` | Whether it's a NoClick, your account's own or one of your spaces', rather than one of your agents: NoClick's own app shows it as NoClick, never by the name it's found by (a space's is `noclick-<the space's id>`). |
| `formerNames` | `string[]` | The names it went by before it was renamed, the latest first. Each still reaches it (`agent:<old name>`, `fromName`, an |
| `job` | `Job | null` | The task it was spawned with, as a `Job` to wait on, or null. |
| `triggerKinds` | `string[]` | The kinds of its triggers (`cron`, `webhook`, `event`, `platform`, `email`, `call`); an agent with `cron` is an automation. |
| `consoleUrl` | `string | null` | This agent in the developer console (null off the hosted API). |
| `a2aUrl` | `string` | The A2A JSON-RPC endpoint (`message/send`, `tasks/get`); callers authenticate with a platform key as a bearer token. |
| `memory` | `AgentMemory` | What it remembers across conversations: `list`, `search`, `read`, `save` and `delete` named entries. |

Types:

```typescript
/** Where an agent was made: through the API, or in the NoClick app. */
type AgentOrigin = "api" | "app";

/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

type JsonObject = { [key: string]: unknown };

/**
 * What an agent may do with each app it reaches, as `{ key: ToolRule }`. A key is an app as `tools` names it (a
 * connection's name, `"credential:<id>"`, an integration's, `"noclick"`, `"search"`, `"fetch"`), one action of it
 * (`"work-gmail.delete_email_message"`; NoClick's are its groups, `"noclick.spend"`), or `"*"` for whatever the rest
 * don't name. The most specific key naming a call decides it; none, it's allowed. With everything, `"*": "off"` keeps
 * it to the apps the rules turn on, so an account connected later starts off.
 */
type ToolRules = Record<string, ToolRule>;

/** `allow` runs a call, `ask` holds it for the owner's yes (an approval), `off` refuses it. */
type ToolRule = "allow" | "ask" | "off";

type RegionName = "us-east" | "us-west" | "eu" | "ap" | "in";

/** The VM a Docker agent works in: `small` (2 CPUs, 4 GB), `medium` (4 CPUs, 8 GB) or `large` (8 CPUs, 16 GB). */
type SandboxSize = "small" | "medium" | "large";

/**
 * How a coding agent may turn app testing on (Docker in its sandbox, for a task that runs the app or its tests against
 * a real database): `by_itself` turns it on when a task needs it and off once it's done, saying each in its chat;
 * `ask_first` asks the account's owner in the chat each time; `never`.
 */
type AppTesting = "by_itself" | "ask_first" | "never";

/** While a plan's limit has an agent on another connection: the one it left, and when that one is back. */
interface SwitchedFrom {
  connection: string;
  name: string | null;
  window: string | null;
  resetsAt: string | null;
}

/** Where a move from a laptop made an agent from (`Agent.movedFrom`). */
interface AgentMovedFrom {
  moveId: string;
  host: string | null;
  folder: string | null;
  at: Date | null;
}

/** `true` (anywhere), `false` (nothing) or the hosts it may reach, `"*.example.com"` for a domain and its subdomains. */
type NetworkAccess = boolean | string[];

/**
 * How far one turn of an `sdk` agent goes, each limit left out at its default: `steps` (model calls; 30, at most
 * 200), `usd` (what they cost; $1, at most $25) and `minutes` (15, at most 60).
 */
interface TurnLimits {
  steps?: number;
  usd?: number;
  minutes?: number;
}

/** When a conversation's coding harness asks a person before acting (`full-access`, the default, asks nothing). */
type PermissionMode = "approval-required" | "auto-accept-edits" | "auto" | "full-access";

/**
 * `working` (a turn queued or running), `waiting` (its turns wait on a person: a question, a
 * held call), `idle`, or `expired` (past its `ttlS`: no turns, readable for 30 days). Pausing
 * stops triggers, not work: see `paused`.
 */
type AgentStatus = "working" | "waiting" | "idle" | "expired";

/** An app that binds a database or a bucket, under its `binding` name. */
interface UsedBy {
  kind: string;
  id: string;
  name: string;
  binding: string | null;
}
```

### Agent.create

```typescript
static create(
  name: string,
  options: AgentCreateOptions & AgentApprovalsOption & AllowExisting & {
    instructions: string;
  },
): Promise<Agent>
```

Create an agent (names are unique per account and user; a duplicate throws `Conflict` with `existingId`).
With `allowExisting: true` a taken name returns the agent already there, as it is: nothing about it
changes, so it's made once and left alone after.

Parameters:

- `name` (`string`, required)
- `options.instructions` (`string`, required)
- `options.model` (`string`): The harness's own model: an OpenRouter id with the `openrouter/` prefix on `sdk`, an alias such
as `sonnet` on `claude_code`, a `provider/model` on `opencode`, `hermes` and `openclaw`; the
harness's default when omitted.
- `options.harness` (`HarnessName`): What runs it: `sdk` (the default), NoClick's own agent loop, or a coding agent in a sandbox of
its own (`claude_code`, `codex`, `opencode`, `hermes`, `openclaw`). A new harness without a
`model` takes that harness's default model, and each conversation carries on on it.
- `options.modelConnection` (`string | Connection | null`): The connection whose key or plan it thinks with: a `Connection` of a `kind: "model"`
integration such as `anthropic`, or its name, in the agent's own scope (a lazy
`createIfMissing` one is created first). Every CLI harness needs one, and it may still be
pending; on `sdk` it's optional and lets `model` name `anthropic/...` or `openai/...` on your key.
In `fromName`, `null` clears it (back to `sdk` takes `harness: "sdk", modelConnection: null`).
- `options.tools` (`AgentTools`)
- `options.toolRules` (`ToolRules`): What it may do with each app it reaches (`ToolRules`). In `update`, `{}` clears them.
- `options.ttlS` (`number`): A temporary agent: after this many seconds it's `expired`, taking no turns (its pending
wake-ups are canceled) and readable for 30 days, then deleted. Set when it's created, for good: an
existing agent with another makes `fromName` throw `Conflict` naming its `ttl_s`.
- `options.budgetUsdPerMonth` (`number | null`): In `fromName`, `null` clears it, as `browserProfile` and `card` do.
- `options.canRequest` (`(string | { name: string })[]`): What it may ask its user to connect at run time (a `request_connection` tool): integration
names (or `IntegrationInfo`s), single `"integration.operation"`s, or `"*"`. What the user connects
is a grant (`grants()`), kept apart from the agent's fields.
- `options.triggers` (`TriggerDefinition[]`): What wakes it without a message: `OnWebhook`, `OnEvent`, `OnPlatformEvent`, `Cron` and `OnQueue`.
- `options.browserProfile` (`string | BrowserProfile | null`): The profile its `browser` tool signs in with (a `BrowserProfile` or id of its own user's, or the
account's for an account agent): each conversation gets a browser of its own for a turn, a step only
a person can do holds the turn `awaiting_human`, and its calls follow policy as `browser.*`. In
`update`, `null` signs it out.
- `options.card` (`string | Card | null`, invite-only beta): Invite-only beta. The card it holds and pays with (a `Card` or id of its own scope; giving one
takes the key's `cards` scope): a card has one agent at a time. It gets `card__status` and
`card__purchase` (approve before paying: above the card's threshold the turn waits for a person, whose
answer is its next turn), which policy names `card.status` and `card.purchase`, and never sees the
number. A turn answering someone outside its scope, or a test run, buys nothing. A child it spawns pays
with the same card only when given `"card"` in its tools. In `update`, `null` takes its card back.
- `options.volumes` (`Record<string, VolumeRef>`): Volumes its shell mounts read-write, by absolute path, in every conversation, up to 5:
`{ "/data": Volume.fromName("datasets") }` (a `Volume`, an id or a name: its user's own, else the
account's). Not `/workspace`, `/root` or a system folder. An `sdk` agent's shell sees each as the
turn started and saves its writes when it ends; a coding harness's sandbox, while it's up.
- `options.secrets` (`SecretRef[]`): Secrets whose keys become environment variables in its shell, up to 20, a later one's key winning
(a `Secret`, an id or a name: its user's own, else the account's; an account agent's, the account's
only). A model provider's key (`OPENAI_API_KEY` and the like) belongs on `modelConnection`: a
secret holding one throws `InvalidRequest`.
- `options.timezone` (`string | null`): The IANA timezone every turn is told the date and time in; without one, the acting user's
`timezone`, else UTC. An account's own agent made without one starts in its owner's, where their
NoClick assistant tells the time. In `fromName`, `null` clears it.
- `options.repos` (`RepoCheckout[]`): Repositories cloned into its workspace (`/workspace/<name>`) at a conversation's first turn:
`connection.checkout(...)` through a `github` connection of its own scope, or `repo.checkout(...)`
for a NoClick `Repo` of its own scope, up to 10 (none with `shell: false`). Its `git` reaches those
repositories only, through NoClick, with a key made for its sandbox; a push goes through only to the branches the
checkout's `push` globs name (none: read-only), judged by NoClick on the way to the git host,
since a harness's own `git push` is no tool call a policy could judge. `gh` only reads a git host's.
- `options.network` (`NetworkAccess`): What its shell and code may reach: `true` (anywhere, the default), `false`, or up to 50 hosts
(`"pypi.org"`, or `"*.example.com"` for a domain and its subdomains), over HTTPS on port 443 only.
What it needs to work stays reachable, and `false` leaves only that: an `sdk` agent's shell reaches
NoClick's git proxy when it has `repos` (its model and tools run on NoClick); a coding harness reaches
NoClick's API, NoClick's proxy for its model on a key and for git, and on a Claude or ChatGPT plan that
provider's own hosts. Its tools run on NoClick, outside the limit. Omitted, its parent's, else
anywhere; the children it spawns take its. Where NoClick can't keep to a limited network (a coding
harness on a key other than Claude, ChatGPT or OpenRouter, say), it throws `NotAvailable` rather
than widen it. In `update`, from its next turn.
- `options.shell` (`boolean`): `false` takes the shell (the `code` capability) away from an `sdk` agent, and from the children it
spawns; a CLI harness refuses it with `InvalidRequest`, since its shell is the harness.
- `options.region` (`RegionName`): Where its sandboxes run (`regions()`), for good: a coding harness runs there whole, and an `sdk`
agent's shell does while its loop runs in NoClick's own service. Omitted, its parent's, else your
account's default region, else wherever NoClick has capacity. An existing agent elsewhere makes
`fromName` throw `Conflict` naming its `region`.
- `options.machine` (`string | Machine | null`, invite-only beta): Invite-only beta. The always-on `Machine` (or its id) its harness runs on instead of a
sandbox of its own: nothing reaped when it's quiet, no per-minute sandbox charge, in the
machine's region. A coding harness there reaches its model through NoClick's credential proxy,
so its `modelConnection` holds a Claude, ChatGPT or OpenRouter key, or your account's own plan: a
Claude plan on `claude_code` or a ChatGPT plan on `codex`, its sign-in kept in that agent's own
container (the answer's `notes` say so). Anyone else's plan throws `NotAvailable`; a machine runs
at most 50 agents. In `update`, `null` moves it back to sandboxes.
- `options.memories` (`MemoryRef[]`): The `Memory`s it reads besides its own (`agent.memory`), in order, up to 10: a `Memory`, its id or name
(its user's own, else the account's), or another agent's `memory`. Each is read-only to it unless given as
`memory.writable()`; a user's agent reads the account's memories but never writes them, and never another
user's. Every turn starts with each entry's name and description, its own memory's first.
- `options.skills` (`SkillRef[]`): The `Skill`s it uses, in order, up to 20: a `Skill` (`skill.pinned(n)` to hold one version), its id or name (its
user's own, else the account's). A coding harness finds them where it reads skills; an `sdk` agent sees each
one's name and description every turn and reads one with `skill__read`.
- `options.turnLimits` (`TurnLimits | null`): How far one turn of an `sdk` agent goes before it wraps up:
`{ steps: 100, usd: 2, minutes: 45 }`, each left out at its default ($1 of model calls and 30 minutes, with
200 model calls as a backstop; at most 200, $25 and 60). A turn its steps end stops there saying nothing and
carries on by itself in a follow-up turn on the same conversation, up to 3 in a row, unless a message comes
first; one its spend or minutes end says where the work stands and waits to be asked (`reply.endedBy` names
the limit). A coding harness ends its own turns, and refuses it with `InvalidRequest`. In `update` (from its
next turn) and `fromName`, `null` goes back to the defaults.
- `options.effort` (`string | null`): How hard its model reasons in every conversation: one of its harness's `efforts`
(`Agent.harnesses()`, or a conversation's settings). In `update` and `fromName`, `null` clears it.
- `options.speed` (`AgentSpeed | null`): `fast` runs its model in its harness's fast mode where it has one (`speeds`). In `update`, `null` clears it.
- `options.permissionMode` (`PermissionMode | null`): How far its coding harness goes before asking a person, in each conversation that sets none (a conversation's
`setPermissionMode` wins): one of its harness's `permissionModes`. In `update`, `null` puts back `full-access`.
- `options.setup` (`string[]`): Commands a coding agent's sandbox (its container, on a machine) runs as it starts, in order, after its `repos`
and with its secrets in the environment (a CLI installed, a config file written); up to 20. In `update`, `[]`
clears them.
- `options.docker` (`boolean`): Docker in a coding agent's sandbox, which is then a VM of `sandboxSize` with dockerd running before its first
turn: `docker`, `docker compose` and testcontainers work as on any Linux machine. The VM is billed at its cost
for all of its size while it's up. In `update`, `false` drops its size.
- `options.sandboxSize` (`SandboxSize | null`): The VM a Docker agent works in (`SandboxSize`; `small` unless it says). In `update`, `null` is `small` again.
- `options.appTesting` (`AppTesting`): How it may turn Docker on for a task that needs it, without `docker` (`AppTesting`; `by_itself` unless it says).
In `update`, `never` turns off what's on now, from its next turn.
- `options.modelSwitching` (`ModelSwitchingChange | null`): How it moves to another of the owner's model connections (`ModelSwitching`): left out, it switches by itself to
any of their own plans and asks before a paid key. In `update`, `null` is the default rule again; letting it switch
more freely is the owner's own call.
- `options.approvals` (`ScopeApprovals`): What its own calls wait for a person on, in place of the account's, by kind of hold (`ApprovalPolicy.get()` lists
the settable ones): `"allow"`, `"ask"`, `"deny"`, or `{ disposition, under_usd?, until? }` (a purchase allowed at
or under `under_usd`, asked above). Never looser than the account's ceiling for the kind (raise it with
`ApprovalPolicy.set({ ceilings })`), a child's never looser than its parent's (which it follows where it sets
none), and a purchase or a deletion past the default needs a monthly cap on the account. Loosening is the owner's:
signed in, their own message to one of their agents, or a key naming `approvals:policy` (after a 10-minute undo
window); an agent acting on its own waits for their yes. In `update`, a kind set to `null` goes back to the
account's (a child's, to its parent's). `toolRules` turning `noclick.spend` or `noclick.delete` to `"allow"` set
`purchase` or `delete` to allow with it. `routing` among them names who answers its held calls first, in place of
its parent's or the account's approver (finally the owner), as `ApprovalPolicy.set`'s `routing` takes it: never
the agent itself nor one of its children (its parent may approve its calls).
- `options.allowExisting` (`boolean`): A taken name returns the object already there, as it is: nothing about it changes.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `options.parent` (`string | Agent`): Its parent: a child's budget is held out of what the parent's has left; without one, it draws on the
parent's as it spends. Set when it's created, for good: an existing agent with another makes
`fromName` throw `Conflict` naming its `parent_id`.

Returns: The new agent, loaded.

Types:

```typescript
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;

/** A volume to mount: a `Volume`, its id, or its name (the user's own, else the account's). */
type VolumeRef = string | Volume;

/** A memory to attach: a `Memory`, `memory.writable()`, another agent's `agent.memory`, or a memory's id or name. */
type MemoryRef = string | Memory | MemoryLink | AgentMemory;

/** A skill to attach: a `Skill`, `skill.pinned(n)`, or a skill's id or name. */
type SkillRef = string | Skill | SkillLink;

/** A secret to pass: a `Secret`, its id, or its name (the user's own, else the account's). */
type SecretRef = string | Secret;

/** `true` (anywhere), `false` (nothing) or the hosts it may reach, `"*.example.com"` for a domain and its subdomains. */
type NetworkAccess = boolean | string[];

/**
 * How far one turn of an `sdk` agent goes, each limit left out at its default: `steps` (model calls; 30, at most
 * 200), `usd` (what they cost; $1, at most $25) and `minutes` (15, at most 60).
 */
interface TurnLimits {
  steps?: number;
  usd?: number;
  minutes?: number;
}

type RegionName = "us-east" | "us-west" | "eu" | "ap" | "in";

/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** How fast a conversation's model runs: `fast` where its harness has a fast mode (`speeds`). */
type AgentSpeed = "standard" | "fast";

/** When a conversation's coding harness asks a person before acting (`full-access`, the default, asks nothing). */
type PermissionMode = "approval-required" | "auto-accept-edits" | "auto" | "full-access";

/** The VM a Docker agent works in: `small` (2 CPUs, 4 GB), `medium` (4 CPUs, 8 GB) or `large` (8 CPUs, 16 GB). */
type SandboxSize = "small" | "medium" | "large";

/**
 * How a coding agent may turn app testing on (Docker in its sandbox, for a task that runs the app or its tests against
 * a real database): `by_itself` turns it on when a task needs it and off once it's done, saying each in its chat;
 * `ask_first` asks the account's owner in the chat each time; `never`.
 */
type AppTesting = "by_itself" | "ask_first" | "never";

/** `modelSwitching` as it's set: its allowed connections by name or as `Connection`s. Only what's given changes. */
interface ModelSwitchingChange {
  mode?: "switch" | "stay";
  allowed?: (string | Connection)[] | null;
}

/**
 * Left out when it's created, everything in its scope (`"everything"`): every connection, ones
 * connected later too, operations that need no account, the web and NoClick itself, plus the
 * account's owner to notify and ask for an account agent. A list narrows it to what it names:
 * connections (a `Connection`, or its name: every operation), one operation of one
 * (`"gmail.send_email_message"`), the capabilities `"search"` and `"fetch"`, a `Toolkit`, a
 * `Database` (its `query`, `execute` and `schema`, or `db.only(...)`; invite-only beta), a browser
 * (`"browser"`, or `"browser.act"` and the like), or a person (a
 * `Human` or `human.only(...)`: tools that notify, ask or hand off to them): at most 64 tools
 * in all. A string names a connection in the agent's own user (the account for an account agent,
 * whose `"credential:<id>"` names an account connected in the NoClick app), else an integration's operations that need no account (on NoClick's key), so
 * `tools: ["exa.search"]` (or `"exa"`, all of them) needs no connection. A `Connection` object from
 * another scope, another user's or the account's, stays that connection (a key acting for the whole
 * account only). A lazy `createIfMissing` connection is created first. Every agent can also run shell
 * commands (the `code` capability; a policy that denies `code` refuses them, and `shell: false` removes it).
 */
type AgentTools = ToolRef[] | { refs: ToolRef[] };

/**
 * A tool ref: a name, `"name.operation"`, a capability, a `Connection`, `connection.only(...)`, a
 * `Database` or `db.only(...)`. A name is a connection in the scope the tools run in, else an
 * integration's operations that need no account (on NoClick's key), so `"exa.search"` needs no connection.
 * An entry read back from `agent.tools` (`{ tool, bind }`, `{ human, tools }`) is taken as it is.
 */
type ToolRef = string | Connection | ConnectionOperations | Database | DatabaseOperations | ToolSource | JsonObject;

type JsonObject = { [key: string]: unknown };

/**
 * What an agent may do with each app it reaches, as `{ key: ToolRule }`. A key is an app as `tools` names it (a
 * connection's name, `"credential:<id>"`, an integration's, `"noclick"`, `"search"`, `"fetch"`), one action of it
 * (`"work-gmail.delete_email_message"`; NoClick's are its groups, `"noclick.spend"`), or `"*"` for whatever the rest
 * don't name. The most specific key naming a call decides it; none, it's allowed. With everything, `"*": "off"` keeps
 * it to the apps the rules turn on, so an account connected later starts off.
 */
type ToolRules = Record<string, ToolRule>;

/** `allow` runs a call, `ask` holds it for the owner's yes (an approval), `off` refuses it. */
type ToolRule = "allow" | "ask" | "off";

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** A key's, connected app's or agent's own approval settings by kind, with its `routing` beside them. */
type ScopeApprovals = Record<string, ApprovalSetting | ApprovalRouting>;

/** A kind's switch: `"allow"`, `"ask"`, `"deny"` (`terms` and `person_filing` take `"standing"` in place of `"allow"`:
 *  what's on file decides, never a person), the same as an object (a purchase may take `under_usd`; any kind `until`),
 *  or null for NoClick's default. */
type ApprovalSetting = "allow" | "ask" | "deny" | "standing" | {
  disposition: "allow" | "ask" | "deny" | "standing";
  under_usd?: number;
  until?: Date | string;
} | null;

/** Who answers a scope's held calls first (`approver`; null: the next scope up's), how long they have (`expires_in_s`,
 *  60 seconds to 7 days, a day by default), and what happens when they don't answer in time (`on_timeout`: `decline`,
 *  the default, or `escalate` to the next approver up, finally the owner); null puts it back. */
type ApprovalRouting = {
  approver?: Approver | null;
  on_timeout?: "decline" | "escalate" | null;
  expires_in_s?: number | null;
} | null;

/** Who answers a held call: the account's owner, a person by email, one of your users (by your id), one of your agents
 *  (by id or name), or your own code (a key holding `approvals:answer`). */
type Approver = "owner" | { owner: true } | { email: string } | { user_id: string } | { agent_id: string } |
  { code: true };
```

### Agent.fromName

```typescript
static fromName(
  name: string,
  options?: AgentCreateOptions & { createIfMissing?: boolean },
): Agent
```

A lazy reference to the agent called `name` for the current (or given) user: inside `asUser` only
that user's own agent, never an account agent of the same name. Given fields, it gets the agent and
sets the ones you pass, on every run: an existing agent whose instructions, model, `modelConnection`,
tools, `canRequest`, budget or another field `update` takes differ gets yours (the grants its user
gave it are kept), and its `triggers` too. `createIfMissing` only decides what happens when there's
none: `true` creates it (`instructions` is required then), else it throws `NotFound`. A field left
out is never changed; `null` clears `modelConnection`, `budgetUsdPerMonth`, `browserProfile` or
`card`, as `update` does. `region`, `ttlS` and `parent` are set when it's created, for good: an
existing agent with another throws `Conflict` naming it.

Setting fields is a write, every time it runs: do it at startup or in a setup script, and take the
bare `Agent.fromName("support")` in request handlers, or two versions of your server would keep
overwriting each other's values. To make an agent once and leave it alone after, use
`Agent.create(name, { ..., allowExisting: true })`.

Parameters:

- `name` (`string`, required)
- `options.createIfMissing` (`boolean`)
- `options.instructions` (`string`)
- `options.model` (`string`): The harness's own model: an OpenRouter id with the `openrouter/` prefix on `sdk`, an alias such
as `sonnet` on `claude_code`, a `provider/model` on `opencode`, `hermes` and `openclaw`; the
harness's default when omitted.
- `options.harness` (`HarnessName`): What runs it: `sdk` (the default), NoClick's own agent loop, or a coding agent in a sandbox of
its own (`claude_code`, `codex`, `opencode`, `hermes`, `openclaw`). A new harness without a
`model` takes that harness's default model, and each conversation carries on on it.
- `options.modelConnection` (`string | Connection | null`, default: unchanged): The connection whose key or plan it thinks with: a `Connection` of a `kind: "model"`
integration such as `anthropic`, or its name, in the agent's own scope (a lazy
`createIfMissing` one is created first). Every CLI harness needs one, and it may still be
pending; on `sdk` it's optional and lets `model` name `anthropic/...` or `openai/...` on your key.
In `fromName`, `null` clears it (back to `sdk` takes `harness: "sdk", modelConnection: null`).
- `options.tools` (`AgentTools`)
- `options.toolRules` (`ToolRules`): What it may do with each app it reaches (`ToolRules`). In `update`, `{}` clears them.
- `options.ttlS` (`number`): A temporary agent: after this many seconds it's `expired`, taking no turns (its pending
wake-ups are canceled) and readable for 30 days, then deleted. Set when it's created, for good: an
existing agent with another makes `fromName` throw `Conflict` naming its `ttl_s`.
- `options.budgetUsdPerMonth` (`number | null`, default: unchanged): In `fromName`, `null` clears it, as `browserProfile` and `card` do.
- `options.canRequest` (`(string | { name: string })[]`): What it may ask its user to connect at run time (a `request_connection` tool): integration
names (or `IntegrationInfo`s), single `"integration.operation"`s, or `"*"`. What the user connects
is a grant (`grants()`), kept apart from the agent's fields.
- `options.triggers` (`TriggerDefinition[]`): What wakes it without a message: `OnWebhook`, `OnEvent`, `OnPlatformEvent`, `Cron` and `OnQueue`.
- `options.browserProfile` (`string | BrowserProfile | null`, default: unchanged): The profile its `browser` tool signs in with (a `BrowserProfile` or id of its own user's, or the
account's for an account agent): each conversation gets a browser of its own for a turn, a step only
a person can do holds the turn `awaiting_human`, and its calls follow policy as `browser.*`. In
`update`, `null` signs it out.
- `options.card` (`string | Card | null`, invite-only beta, default: unchanged): Invite-only beta. The card it holds and pays with (a `Card` or id of its own scope; giving one
takes the key's `cards` scope): a card has one agent at a time. It gets `card__status` and
`card__purchase` (approve before paying: above the card's threshold the turn waits for a person, whose
answer is its next turn), which policy names `card.status` and `card.purchase`, and never sees the
number. A turn answering someone outside its scope, or a test run, buys nothing. A child it spawns pays
with the same card only when given `"card"` in its tools. In `update`, `null` takes its card back.
- `options.volumes` (`Record<string, VolumeRef>`): Volumes its shell mounts read-write, by absolute path, in every conversation, up to 5:
`{ "/data": Volume.fromName("datasets") }` (a `Volume`, an id or a name: its user's own, else the
account's). Not `/workspace`, `/root` or a system folder. An `sdk` agent's shell sees each as the
turn started and saves its writes when it ends; a coding harness's sandbox, while it's up.
- `options.secrets` (`SecretRef[]`): Secrets whose keys become environment variables in its shell, up to 20, a later one's key winning
(a `Secret`, an id or a name: its user's own, else the account's; an account agent's, the account's
only). A model provider's key (`OPENAI_API_KEY` and the like) belongs on `modelConnection`: a
secret holding one throws `InvalidRequest`.
- `options.timezone` (`string | null`, default: unchanged): The IANA timezone every turn is told the date and time in; without one, the acting user's
`timezone`, else UTC. An account's own agent made without one starts in its owner's, where their
NoClick assistant tells the time. In `fromName`, `null` clears it.
- `options.repos` (`RepoCheckout[]`): Repositories cloned into its workspace (`/workspace/<name>`) at a conversation's first turn:
`connection.checkout(...)` through a `github` connection of its own scope, or `repo.checkout(...)`
for a NoClick `Repo` of its own scope, up to 10 (none with `shell: false`). Its `git` reaches those
repositories only, through NoClick, with a key made for its sandbox; a push goes through only to the branches the
checkout's `push` globs name (none: read-only), judged by NoClick on the way to the git host,
since a harness's own `git push` is no tool call a policy could judge. `gh` only reads a git host's.
- `options.network` (`NetworkAccess`): What its shell and code may reach: `true` (anywhere, the default), `false`, or up to 50 hosts
(`"pypi.org"`, or `"*.example.com"` for a domain and its subdomains), over HTTPS on port 443 only.
What it needs to work stays reachable, and `false` leaves only that: an `sdk` agent's shell reaches
NoClick's git proxy when it has `repos` (its model and tools run on NoClick); a coding harness reaches
NoClick's API, NoClick's proxy for its model on a key and for git, and on a Claude or ChatGPT plan that
provider's own hosts. Its tools run on NoClick, outside the limit. Omitted, its parent's, else
anywhere; the children it spawns take its. Where NoClick can't keep to a limited network (a coding
harness on a key other than Claude, ChatGPT or OpenRouter, say), it throws `NotAvailable` rather
than widen it. In `update`, from its next turn.
- `options.shell` (`boolean`): `false` takes the shell (the `code` capability) away from an `sdk` agent, and from the children it
spawns; a CLI harness refuses it with `InvalidRequest`, since its shell is the harness.
- `options.region` (`RegionName`): Where its sandboxes run (`regions()`), for good: a coding harness runs there whole, and an `sdk`
agent's shell does while its loop runs in NoClick's own service. Omitted, its parent's, else your
account's default region, else wherever NoClick has capacity. An existing agent elsewhere makes
`fromName` throw `Conflict` naming its `region`.
- `options.machine` (`string | Machine | null`, invite-only beta): Invite-only beta. The always-on `Machine` (or its id) its harness runs on instead of a
sandbox of its own: nothing reaped when it's quiet, no per-minute sandbox charge, in the
machine's region. A coding harness there reaches its model through NoClick's credential proxy,
so its `modelConnection` holds a Claude, ChatGPT or OpenRouter key, or your account's own plan: a
Claude plan on `claude_code` or a ChatGPT plan on `codex`, its sign-in kept in that agent's own
container (the answer's `notes` say so). Anyone else's plan throws `NotAvailable`; a machine runs
at most 50 agents. In `update`, `null` moves it back to sandboxes.
- `options.memories` (`MemoryRef[]`): The `Memory`s it reads besides its own (`agent.memory`), in order, up to 10: a `Memory`, its id or name
(its user's own, else the account's), or another agent's `memory`. Each is read-only to it unless given as
`memory.writable()`; a user's agent reads the account's memories but never writes them, and never another
user's. Every turn starts with each entry's name and description, its own memory's first.
- `options.skills` (`SkillRef[]`): The `Skill`s it uses, in order, up to 20: a `Skill` (`skill.pinned(n)` to hold one version), its id or name (its
user's own, else the account's). A coding harness finds them where it reads skills; an `sdk` agent sees each
one's name and description every turn and reads one with `skill__read`.
- `options.turnLimits` (`TurnLimits | null`, default: unchanged): How far one turn of an `sdk` agent goes before it wraps up:
`{ steps: 100, usd: 2, minutes: 45 }`, each left out at its default ($1 of model calls and 30 minutes, with
200 model calls as a backstop; at most 200, $25 and 60). A turn its steps end stops there saying nothing and
carries on by itself in a follow-up turn on the same conversation, up to 3 in a row, unless a message comes
first; one its spend or minutes end says where the work stands and waits to be asked (`reply.endedBy` names
the limit). A coding harness ends its own turns, and refuses it with `InvalidRequest`. In `update` (from its
next turn) and `fromName`, `null` goes back to the defaults.
- `options.effort` (`string | null`, default: unchanged): How hard its model reasons in every conversation: one of its harness's `efforts`
(`Agent.harnesses()`, or a conversation's settings). In `update` and `fromName`, `null` clears it.
- `options.speed` (`AgentSpeed | null`, default: unchanged): `fast` runs its model in its harness's fast mode where it has one (`speeds`). In `update`, `null` clears it.
- `options.permissionMode` (`PermissionMode | null`, default: unchanged): How far its coding harness goes before asking a person, in each conversation that sets none (a conversation's
`setPermissionMode` wins): one of its harness's `permissionModes`. In `update`, `null` puts back `full-access`.
- `options.setup` (`string[]`): Commands a coding agent's sandbox (its container, on a machine) runs as it starts, in order, after its `repos`
and with its secrets in the environment (a CLI installed, a config file written); up to 20. In `update`, `[]`
clears them.
- `options.docker` (`boolean`): Docker in a coding agent's sandbox, which is then a VM of `sandboxSize` with dockerd running before its first
turn: `docker`, `docker compose` and testcontainers work as on any Linux machine. The VM is billed at its cost
for all of its size while it's up. In `update`, `false` drops its size.
- `options.sandboxSize` (`SandboxSize | null`): The VM a Docker agent works in (`SandboxSize`; `small` unless it says). In `update`, `null` is `small` again.
- `options.appTesting` (`AppTesting`): How it may turn Docker on for a task that needs it, without `docker` (`AppTesting`; `by_itself` unless it says).
In `update`, `never` turns off what's on now, from its next turn.
- `options.modelSwitching` (`ModelSwitchingChange | null`): How it moves to another of the owner's model connections (`ModelSwitching`): left out, it switches by itself to
any of their own plans and asks before a paid key. In `update`, `null` is the default rule again; letting it switch
more freely is the owner's own call.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `options.parent` (`string | Agent`): Its parent: a child's budget is held out of what the parent's has left; without one, it draws on the
parent's as it spends. Set when it's created, for good: an existing agent with another makes
`fromName` throw `Conflict` naming its `parent_id`.

Returns: An agent that loads (or is created, or has your fields set) the first time it's used.
Nothing is sent yet.

Types:

```typescript
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;

/** A volume to mount: a `Volume`, its id, or its name (the user's own, else the account's). */
type VolumeRef = string | Volume;

/** A memory to attach: a `Memory`, `memory.writable()`, another agent's `agent.memory`, or a memory's id or name. */
type MemoryRef = string | Memory | MemoryLink | AgentMemory;

/** A skill to attach: a `Skill`, `skill.pinned(n)`, or a skill's id or name. */
type SkillRef = string | Skill | SkillLink;

/** A secret to pass: a `Secret`, its id, or its name (the user's own, else the account's). */
type SecretRef = string | Secret;

/** `true` (anywhere), `false` (nothing) or the hosts it may reach, `"*.example.com"` for a domain and its subdomains. */
type NetworkAccess = boolean | string[];

/**
 * How far one turn of an `sdk` agent goes, each limit left out at its default: `steps` (model calls; 30, at most
 * 200), `usd` (what they cost; $1, at most $25) and `minutes` (15, at most 60).
 */
interface TurnLimits {
  steps?: number;
  usd?: number;
  minutes?: number;
}

type RegionName = "us-east" | "us-west" | "eu" | "ap" | "in";

/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** How fast a conversation's model runs: `fast` where its harness has a fast mode (`speeds`). */
type AgentSpeed = "standard" | "fast";

/** When a conversation's coding harness asks a person before acting (`full-access`, the default, asks nothing). */
type PermissionMode = "approval-required" | "auto-accept-edits" | "auto" | "full-access";

/** The VM a Docker agent works in: `small` (2 CPUs, 4 GB), `medium` (4 CPUs, 8 GB) or `large` (8 CPUs, 16 GB). */
type SandboxSize = "small" | "medium" | "large";

/**
 * How a coding agent may turn app testing on (Docker in its sandbox, for a task that runs the app or its tests against
 * a real database): `by_itself` turns it on when a task needs it and off once it's done, saying each in its chat;
 * `ask_first` asks the account's owner in the chat each time; `never`.
 */
type AppTesting = "by_itself" | "ask_first" | "never";

/** `modelSwitching` as it's set: its allowed connections by name or as `Connection`s. Only what's given changes. */
interface ModelSwitchingChange {
  mode?: "switch" | "stay";
  allowed?: (string | Connection)[] | null;
}

/**
 * Left out when it's created, everything in its scope (`"everything"`): every connection, ones
 * connected later too, operations that need no account, the web and NoClick itself, plus the
 * account's owner to notify and ask for an account agent. A list narrows it to what it names:
 * connections (a `Connection`, or its name: every operation), one operation of one
 * (`"gmail.send_email_message"`), the capabilities `"search"` and `"fetch"`, a `Toolkit`, a
 * `Database` (its `query`, `execute` and `schema`, or `db.only(...)`; invite-only beta), a browser
 * (`"browser"`, or `"browser.act"` and the like), or a person (a
 * `Human` or `human.only(...)`: tools that notify, ask or hand off to them): at most 64 tools
 * in all. A string names a connection in the agent's own user (the account for an account agent,
 * whose `"credential:<id>"` names an account connected in the NoClick app), else an integration's operations that need no account (on NoClick's key), so
 * `tools: ["exa.search"]` (or `"exa"`, all of them) needs no connection. A `Connection` object from
 * another scope, another user's or the account's, stays that connection (a key acting for the whole
 * account only). A lazy `createIfMissing` connection is created first. Every agent can also run shell
 * commands (the `code` capability; a policy that denies `code` refuses them, and `shell: false` removes it).
 */
type AgentTools = ToolRef[] | { refs: ToolRef[] };

/**
 * A tool ref: a name, `"name.operation"`, a capability, a `Connection`, `connection.only(...)`, a
 * `Database` or `db.only(...)`. A name is a connection in the scope the tools run in, else an
 * integration's operations that need no account (on NoClick's key), so `"exa.search"` needs no connection.
 * An entry read back from `agent.tools` (`{ tool, bind }`, `{ human, tools }`) is taken as it is.
 */
type ToolRef = string | Connection | ConnectionOperations | Database | DatabaseOperations | ToolSource | JsonObject;

type JsonObject = { [key: string]: unknown };

/**
 * What an agent may do with each app it reaches, as `{ key: ToolRule }`. A key is an app as `tools` names it (a
 * connection's name, `"credential:<id>"`, an integration's, `"noclick"`, `"search"`, `"fetch"`), one action of it
 * (`"work-gmail.delete_email_message"`; NoClick's are its groups, `"noclick.spend"`), or `"*"` for whatever the rest
 * don't name. The most specific key naming a call decides it; none, it's allowed. With everything, `"*": "off"` keeps
 * it to the apps the rules turn on, so an account connected later starts off.
 */
type ToolRules = Record<string, ToolRule>;

/** `allow` runs a call, `ask` holds it for the owner's yes (an approval), `off` refuses it. */
type ToolRule = "allow" | "ask" | "off";

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.fromId

```typescript
static fromId(agentId: string, options?: CallOptions): Agent
```

A lazy reference to an agent by NoClick id.

Parameters:

- `agentId` (`string`, required)
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.

Returns: An agent that loads the first time it's used. Nothing is sent yet.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.get

```typescript
static get(agentId: string, options?: CallOptions): Promise<Agent>
```

Load an agent by NoClick id now; an unknown id raises `noclick.NotFound`.

Parameters:

- `agentId` (`string`, required)
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: The agent, loaded.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.list

```typescript
static list(options?: AgentListOptions & { limit?: number }): Promise<Agent[]>
```

The agents the current user can message: inside `asUser` their own and the account's (messaged, not
changed; `userId` null), so a `name` may match one of each; outside it, the account's. `userFilter`
lists exactly whose instead. Expired agents are listed
for the 30 days they're kept; `status`, `activeSince`, `parent`, `temporary` and `harness` filter, and
`order: "last_active"` reads a column the turn runner stamps, on an index of its own.

After the account's API agents come the ones built in the NoClick app, which are the account's too
(`origin: "api"` or `"app"` lists only one kind); only `name` and `harness` apply to them, and the
other filters leave them out. `send` and `message` reach them; what they are is changed in the app.

    for (const agent of await Agent.list({ origin: "app" })) console.log(agent.name, agent.workflowName, agent.appUrl);

Parameters:

- `options.name` (`string`)
- `options.status` (`AgentStatus`): Only agents with this status.
- `options.activeSince` (`Date | string`): Only agents with a turn since then.
- `options.parent` (`string | Agent`): Only the children of this agent (an `Agent` or id).
- `options.temporary` (`boolean`): `true`: only agents with a `ttlS`; `false`: only agents without one.
- `options.harness` (`HarnessName`): Only agents on this harness.
- `options.order` (`(typeof AGENT_ORDERS)[number]`): `created` (the default: newest first) or `last_active` (most recently active first, those that never ran last).
- `options.origin` (`AgentOrigin`): Only agents made through the API (`api`) or built in the NoClick app (`app`).
- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: Every matching agent, newest first (or most recently active first), fetched page by page.

Types:

```typescript
/**
 * `working` (a turn queued or running), `waiting` (its turns wait on a person: a question, a
 * held call), `idle`, or `expired` (past its `ttlS`: no turns, readable for 30 days). Pausing
 * stops triggers, not work: see `paused`.
 */
type AgentStatus = "working" | "waiting" | "idle" | "expired";

/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** Where an agent was made: through the API, or in the NoClick app. */
type AgentOrigin = "api" | "app";

/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### Agent.listPage

```typescript
static listPage(options?: AgentListOptions & PageOptions): Promise<Page<Agent>>
```

One page of agents; pass `nextCursor` back as `cursor`. Takes `list`'s filters.

Parameters:

- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.
- `options.name` (`string`)
- `options.status` (`AgentStatus`): Only agents with this status.
- `options.activeSince` (`Date | string`): Only agents with a turn since then.
- `options.parent` (`string | Agent`): Only the children of this agent (an `Agent` or id).
- `options.temporary` (`boolean`): `true`: only agents with a `ttlS`; `false`: only agents without one.
- `options.harness` (`HarnessName`): Only agents on this harness.
- `options.order` (`(typeof AGENT_ORDERS)[number]`): `created` (the default: newest first) or `last_active` (most recently active first, those that never ran last).
- `options.origin` (`AgentOrigin`): Only agents made through the API (`api`) or built in the NoClick app (`app`).
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: A page whose `data` holds the agents and whose `next_cursor` is `None` on the last page.

Types:

```typescript
/**
 * `working` (a turn queued or running), `waiting` (its turns wait on a person: a question, a
 * held call), `idle`, or `expired` (past its `ttlS`: no turns, readable for 30 days). Pausing
 * stops triggers, not work: see `paused`.
 */
type AgentStatus = "working" | "waiting" | "idle" | "expired";

/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** Where an agent was made: through the API, or in the NoClick app. */
type AgentOrigin = "api" | "app";

/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### Agent.coding

```typescript
static coding(options?: ReadOptions): Promise<CodingAgents>
```

Every coding agent, and what each is doing. An agent on `claude_code`, `codex`, `opencode`, `hermes` or
`openclaw` (an app's own coding agent among them), with its `state` (`working`, `waiting` on a person, `warm`,
`paused` and why, `stopped`), where it runs, on whose model credential, its current job, each conversation that's
up (`runs`, a sandbox's with what it reserved) and its spend since the first of the month; then counts by
harness, model, state and place. Read from the turns, containers and sandboxes themselves. `userFilter` narrows
it to whose; omitted, every one of the account's for an account's key, a user's own for theirs.

    const { agents, byState } = await Agent.coding();
    for (const agent of agents) console.log(agent.name, agent.state, agent.job?.title);

Parameters:

- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: A `CodingAgents`.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### Agent.states

```typescript
static states(
  options?: ReadOptions & { workspace?: string },
): Promise<AgentStates>
```

Every agent's state, for a list of agents. What it's doing (`state`), the tool call it runs `now`,
what waits on a person (`waiting`, the badge's `total`) and when, read from its turns, asks and held calls. A page
follows it on the `platform:agent` frames. `workspace` keeps a workspace's agents.

    const { data } = await Agent.states();
    for (const row of data) console.log(row.name, row.state, row.now?.line);

Parameters:

- `options.workspace` (`string`)
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: An `AgentStateRow` per agent.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** Every agent's state: `data`, and when it was read. */
interface AgentStates {
  data: AgentStateRow[];
  readAt: Date | null;
  raw: JsonObject;
}

type JsonObject = { [key: string]: unknown };
```

### Agent.harnesses

```typescript
static harnesses(options?: { client?: NoClick }): Promise<HarnessInfo[]>
```

What can run an agent: each one's default model, whether it needs a `modelConnection` and which
providers serve it (`models()` searches its models). On a CLI harness a reply arrives whole, a
conversation's first turn starts its sandbox (warm a minute between turns) and its uptime is billed.

    const codex = (await Agent.harnesses()).find((h) => h.name === "codex");
    const models = await codex?.models({ search: "gpt-5" });

Parameters:

- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: Each harness's `name` (what `harness=` takes) and `default_model`, whether it
needs a `model_connection` and which model providers' `integrations` serve it,
whether its reply streams (`streaming`) and whether its `shell` is built in.
`models()` on one searches the models it offers.

### Agent.harnessInfo

```typescript
static harnessInfo(
  name: string,
  options?: { client?: NoClick },
): Promise<HarnessInfo>
```

One of `harnesses()` by name; an unknown name throws `NotFound` naming the ones there are.

    const opencode = await Agent.harnessInfo("opencode");

Parameters:

- `name` (`string`, required)
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: The harness: its `default_model`, whether it needs a `model_connection`, the model
providers' `integrations` that serve it, and `models()` to search what it offers.

### Agent.upload

```typescript
upload(file: FileInput, options?: UploadOptions): Promise<Attachment>
```

Store a file to send this agent with a message, capped as account files are: 10 MB an image (JPEG, PNG,
WebP or GIF), 15 MB a document, 20 MB audio or video. Send it once, with
`message(text, { files: [attachment] })`.

Parameters:

- `file` (`FileInput`, required)
- `options.name` (`string`): The file's name (a `File` has its own).
- `options.mimeType` (`string`): Its type (a `Blob` has its own; else read from the name).
- `options.voice` (`boolean`): A recorded voice clip (audio).
- `options.peaks` (`number[]`): A voice clip's waveform: loudness 0-1, at most 64 numbers.

Returns: The attachment; send it with `message(files=[...])`. An upload is sent once; sent, it's one of
the account's files (`noclick.attachments()`), which the account sends again.

Types:

```typescript
/** What to upload: bytes, or a `Blob` / `File` (its `name` and `type` are used when not given). */
type FileInput = Blob | Uint8Array | ArrayBuffer;
```

### Agent.send

```typescript
send(
  text: string | null,
  options?: {
    conversation?: string | null;
    files?: (Attachment | string)[];
    user?: UserOption;
    command?: AgentCommandInput;
    delivery?: MessageDelivery;;
  },
): Promise<Operation<AgentReply>>
```

Start a turn without waiting; `wait()` resolves to the `AgentReply`. `files` go with it, as `message` sends them.
`command` runs one of the conversation's harness's own commands in place of `text` (pass `text` as null), as
`commands` lists them, never parsed from text. `delivery` decides a message sent while the agent works on a turn
(it takes one at a time): `steer` joins that turn when it's in the same conversation, `queue` (or omitted) runs it
next; a command is never steered.

    await coder.send(null, { conversation: "main", command: { name: "compact" } });
    await coder.send("also update the README", { conversation: "main", delivery: "steer" });

Parameters:

- `text` (`string | null`, required)
- `options.conversation` (`string | null`)
- `options.files` (`(Attachment | string)[]`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `options.command` (`AgentCommandInput`)
- `options.delivery` (`MessageDelivery`)

Returns: The turn's operation, started. Keep its `id` to pick the reply up later, from anywhere.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/**
 * One of a coding harness's own commands to run instead of a message (`compact`, `review`, a custom command, a
 * skill), as `agent.commands(conversation)` lists them: `name` without the slash, `arguments` what follows it.
 */
interface AgentCommandInput {
  name: string;
  arguments?: string;
}

/**
 * How a message sent while the agent works on a turn (it takes one at a time) is delivered: `steer` puts it into that
 * turn when it's in the same conversation (its operation answers with that turn's reply; else it's an ordinary
 * message), `queue` (or omitted) runs it as the agent's next turn.
 */
type MessageDelivery = "steer" | "queue";
```

### Agent.commands

```typescript
commands(
  conversation: string,
  options?: { user?: UserOption },
): Promise<AgentCommands>
```

What the conversation's harness offers a person to run. Send one with `send(null, { command })`. It names its
commands and skills as the harness itself last listed them, what NoClick can and can't run there
(`capabilities`, `notSupported`), and how fresh the list is (`asOf`, `readFrom`).

    const { commands } = await coder.commands("main");

Parameters:

- `conversation` (`string`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Its commands and skills as the harness itself last listed them, what NoClick can and can't run there
(`capabilities`, `not_supported`), and how fresh the list is (`as_of`, `read_from`).

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.setPermissionMode

```typescript
setPermissionMode(
  conversation: string,
  mode: PermissionMode,
  options?: { user?: UserOption },
): Promise<ConversationSettings>
```

Set how far the conversation's coding harness goes before asking a person. `approval-required` asks before
commands and edits, `auto-accept-edits` runs edits and asks about commands, `auto` has its own review approve
routine work, and `full-access` (the default) asks nothing. Questions reach a person in every mode. Its next
message runs in it.

    await coder.setPermissionMode("main", "approval-required");

Parameters:

- `conversation` (`string`, required)
- `mode` (`PermissionMode`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The conversation's settings: the mode set, the mode its harness runs (`effective_permission_mode`), the
modes it enforces and what it can't do.

Types:

```typescript
/** When a conversation's coding harness asks a person before acting (`full-access`, the default, asks nothing). */
type PermissionMode = "approval-required" | "auto-accept-edits" | "auto" | "full-access";

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.requests

```typescript
requests(
  conversation: string,
  options?: { status?: HarnessRequest["status"]; user?: UserOption },
): Promise<HarnessRequest[]>
```

What the conversation's coding harness asked a person, newest first. `status` keeps `pending`, `answered`,
`expired` or `canceled` ones.

    const waiting = await coder.requests("main", { status: "pending" });

Parameters:

- `conversation` (`string`, required)
- `options.status` (`HarnessRequest["status"]`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Each `HarnessRequest`: an approval (what it would do) or a question, and where it stands.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.answer

```typescript
answer(
  conversation: string,
  requestId: string,
  decision: RequestDecision,
  options?: {
    note?: string;
    answers?: Record<string, string | string[]>;
    user?: UserOption;
  },
): Promise<HarnessRequest>
```

Answer what the conversation's coding harness asks. The `decision` is `allow_once`, `allow_always` (for the rest
of the session, where the harness can), `reject_once` (with a `note` the agent reads; a question: skip it) or
`cancel` (the turn stops). A question is answered with `answers` ({question: labels or your own words}) and `allow_once`. A
person's answer: never through an MCP connection.

    await coder.answer("main", waiting[0].id, "reject_once", { note: "Push to a branch, not main." });

Parameters:

- `conversation` (`string`, required)
- `requestId` (`string`, required)
- `decision` (`RequestDecision`, required)
- `options.note` (`string`)
- `options.answers` (`Record<string, string | string[]>`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The request as it stands now (`answered`; a `cancel` stops the turn, which ends it `canceled`).

Types:

```typescript
/** A person's answer to what a coding harness asks (ACP's `session/request_permission` options, and cancel). */
type RequestDecision = "allow_once" | "allow_always" | "reject_once" | "cancel";

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.message

```typescript
message(
  text: string,
  options?: {
    conversation?: string | null;
    files?: (Attachment | string)[];
    timeoutS?: number;
    user?: UserOption;
  },
): Promise<AgentReply>
```

Send `text` and wait for the reply. Without `conversation` it goes to the agent's session, the one conversation
everyone talking to it shares (`session()`); pass the reply's `conversation` back to stay in that thread.
`files` (at most 100) are attachments from `upload`, or their ids: the turn reads them as the agent's
media digest does, a document's text, a voice clip's transcript, an image as an image.

Parameters:

- `text` (`string`, required)
- `options.conversation` (`string | null`)
- `options.files` (`(Attachment | string)[]`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `options.timeoutS` (`number`)

Returns: The reply: its `text`, the `conversation` it belongs to and the `tool_calls` the turn made.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.history

```typescript
history(conversation: string, options?: AgentHistoryOptions): Promise<Message[]>
```

The messages of one conversation, oldest first. Every one, or the `limit` newest (1-200), just before `before`
(a `nextCursor` of `historyPage`). Each with its `role`, `text`, the `files` it carried, how it arrived (`via`,
for a text, a call or an email) and, a reply, its `toolCalls`; a `note` has its `data`.

Parameters:

- `conversation` (`string`, required)
- `options.limit` (`number`): The newest this many (1-200), oldest first; every message when omitted.
- `options.before` (`string`): Just before this cursor: a `nextCursor` of `historyPage`.
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Its messages, each with its `role`, `text`, `created_at`, the `files` it carried, how it
arrived (`via`, for a text, a call or an email) and, a reply, the `tool_calls` its turn made; a
`note` has its `data`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.historyPage

```typescript
historyPage(
  conversation: string,
  options?: AgentHistoryOptions,
): Promise<Page<Message>>
```

A page of `history`, to read a long thread back from its newest messages. The `limit` newest (1-200), just
before `before`, oldest first. `nextCursor`, while older ones remain, is the `before` of the page before it.

    let page = await support.historyPage("ticket-1841", { limit: 50 });
    while (page.nextCursor) page = await support.historyPage("ticket-1841", { limit: 50, before: page.nextCursor });

Parameters:

- `conversation` (`string`, required)
- `options.limit` (`number`): The newest this many (1-200), oldest first; every message when omitted.
- `options.before` (`string`): Just before this cursor: a `nextCursor` of `historyPage`.
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: A page whose `data` holds the messages and whose `next_cursor`, while older ones remain, is the
`before` of the page before it (None once it reaches the first message).

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.note

```typescript
note(
  conversation: string,
  text: string,
  options?: { data?: JsonObject; key?: string; user?: UserOption },
): Promise<boolean>
```

Add a line to a conversation without starting a turn. It shows in `history` and `watch` as a `note` with its
`data` (JSON, at most 4,096 bytes), and the agent reads both when its next turn starts, once. A `key` adds it
once: resolves to `false` when a note with that key already was.

    await support.note("ticket-1841", "Ada upgraded to the Pro plan.", { data: { plan: "pro" }, key: "plan:pro" });

Parameters:

- `conversation` (`string`, required)
- `text` (`string`, required)
- `options.data` (`JsonObject`)
- `options.key` (`string`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: `True` when it was added, `False` when a note with `key` already was.

Types:

```typescript
type JsonObject = { [key: string]: unknown };

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.withdrawQuestion

```typescript
withdrawQuestion(
  conversation: string,
  note: string,
  options?: { questionId?: string },
): Promise<string[]>
```

Withdraw the question the agent asked your account's owner once it no longer needs them. It was answered or
handled another way, in one of the account's conversations. Its page and card then refuse a late answer, the turn
that asked ends, and the agent reads `note` (1-4,000 characters: who answered, what was already sent) at its
next turn there. `questionId` names the question (its `HumanRequest.requestId`) when more than one waits there;
the others keep waiting. It acts as the account, which alone withdraws one, never a user. With none waiting, or
several and none named, it throws `Conflict`. Resolves to the text of each question withdrawn.

    await support.withdrawQuestion("ticket-1841", "Ana approved the refund on the phone; it's issued.");

Parameters:

- `conversation` (`string`, required)
- `note` (`string`, required)
- `options.questionId` (`string`)

Returns: The text of each question withdrawn.

### Agent.conversation

```typescript
conversation(name: string, options?: { user?: UserOption }): AgentConversation
```

One of its conversations, as a chat reads and changes it. Its settings, a fork, a revert, resuming it as the
agent's session, its context and usage, a command; no request until you call one.

    const chat = coder.conversation("main");
    await chat.update({ effort: "high" });

Parameters:

- `name` (`string`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: An `AgentConversation`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.startConversation

```typescript
startConversation(
  options?: { conversation?: string; title?: string; user?: UserOption },
): Promise<Conversation>
```

Start a new session (a chat's `/new` or `/clear`), as `clear` does, with `conversation` naming its key (one that
already has messages throws `Conflict`); omitted, NoClick makes one. Everyone talking to the agent shares it from
now on, and the one it leaves is kept, listed and can be resumed. Throws `Conflict` while the agent is working on
a turn.

Parameters:

- `options.conversation` (`string`)
- `options.title` (`string`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The new `Conversation`, `active`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.clear

```typescript
clear(options?: { title?: string; user?: UserOption }): Promise<Conversation>
```

Start a new session, like `/clear` in a terminal: everyone talking to the agent shares it from now on. The one it
leaves is kept, listed and can be resumed (`conversation(name).resume()`), and the agent's files stay as they
are. Throws `Conflict` while the agent is working on a turn. Resolves to the new conversation, `active`.

    const before = await coder.session();
    await coder.clear();
    await coder.message("Start on the billing page");   // the new session
    await coder.conversation(before!.conversation).resume();

Parameters:

- `options.title` (`string`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The new `Conversation`, `active`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.session

```typescript
session(options?: { user?: UserOption }): Promise<Conversation | null>
```

The agent's session: the one conversation everyone talking to it shares, where a message without a
`conversation` goes (the current user's, or the account's outside `asUser`). Null before the agent has one.

    const current = await support.session();
    if (current) console.log(await support.history(current.conversation, { limit: 20 }));

Parameters:

- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Its `Conversation` (`active`), or `None` before the agent has one.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.conversations

```typescript
conversations(
  options?: ReadOptions & { limit?: number; archived?: boolean },
): Promise<Conversation[]>
```

Its conversations, most recent first (the current user's, or those `userFilter` covers). `archived` keeps the
archived ones (true) or the others (false).
`userFilter` reads across users without the user header, which only the signed-in owner
may do on a user's own agent; with a secret key, read such an agent's threads without it.

Parameters:

- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.archived` (`boolean`)
- `options.client` (`NoClick`)

Returns: Every matching conversation (or the first `limit`), fetched page by page. `cost_usd`
is `None` for a thread with no recorded turns.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### Agent.conversationsPage

```typescript
conversationsPage(
  options?: ReadOptions & PageOptions & { archived?: boolean },
): Promise<Page<Conversation>>
```

One page of its conversations; pass `nextCursor` back as `cursor`.

Parameters:

- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`)
- `options.archived` (`boolean`)

Returns: A page whose `data` holds the conversations and whose `next_cursor` is `None` on the last page.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### Agent.handBack

```typescript
handBack(conversation: string, options?: { user?: UserOption }): Promise<void>
```

Give a conversation back to the agent after it handed it to a person
(its `hand_off` tool). The person's replies stay in its history, and the agent answers again
from the next message. The person can hand it back from their page too.

Parameters:

- `conversation` (`string`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.takeOver

```typescript
takeOver(
  conversation: string,
  options?: {
    interrupt?: boolean;
    cols?: number;
    rows?: number;
    user?: UserOption;
  },
): Promise<Terminal>
```

Take over a coding agent's conversation. Its harness's own terminal (Claude Code, Codex, OpenCode, Hermes Agent
or OpenClaw) on the session the agent works in, for the account's owner. The turn in flight finishes first unless
`interrupt` stops it (its delivery fails, saying the owner took over); messages wait until it's handed back. Needs
the signed-in owner or the account's secret key with the `agents:terminal` scope: a terminal shows the sandbox's
keys and tokens. Asked again while it's taken over, it resolves to a new token (a reload, a second tab). Throws
`Conflict` when nothing of the conversation is running (send it a message first).

    const terminal = await coder.takeOver("main", { interrupt: true, cols: 120, rows: 36 });
    const connection = terminal.connect({ onData: (bytes) => term.write(bytes) });

Parameters:

- `conversation` (`string`, required)
- `options.interrupt` (`boolean`)
- `options.cols` (`number`)
- `options.rows` (`number`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: A `Terminal`: its `url` and `token` open it (see `noclick.terminal`).

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.terminal

```typescript
terminal(
  conversation: string,
  options?: { user?: UserOption },
): Promise<Terminal>
```

Where a coding agent's conversation's terminal stands, with no token. Open it with `takeOver`, give it back
with `Terminal.handBack`.

Parameters:

- `conversation` (`string`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: A `Terminal` with its `state`, and no `url` or `token`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.spawn

```typescript
spawn(task: string, options?: SpawnOptions): Promise<Agent>
```

Make a child for one task and start it at once. The child lives where its parent does, on the
parent's harness, model and model connection unless told otherwise, and gets only tools its
parent has. `child.job` is the task: it runs while the child works on it and finishes when the
child's conversation goes quiet. `updates` are when NoClick makes the child report (`"done"`
always); every update wakes the parent in `conversation`, and those that come while it's busy
arrive together. An agent has up to 20 live children, 3 levels below an agent with no parent.
`Agent.create({ parent })` still makes a child without starting it.

Parameters:

- `task` (`string`, required)
- `options.updates` (`UpdateSpec[]`): When NoClick makes the child report, beside `"done"` (always on): `"blocked"`, `new Before(...)`, `new Every(...)`.
- `options.conversation` (`string`): The parent's conversation its updates wake; without one they wake nobody and wait on the job.
- `options.instructions` (`string`): The child's standing instructions: what its updates should say, and when to reach out freely.
- `options.tools` (`AgentTools`): Some of its parent's tools (it gets none of them otherwise); a tool its parent lacks is refused. `"card"`
gives it the card its parent pays with.
- `options.budgetUsd` (`number`): Its budget, held out of what its parent's has left; omitted, it draws on its parent's as it spends.
- `options.ttlS` (`number`): It expires this many seconds after it's made.
- `options.model` (`string`): The parent's model when omitted.
- `options.harness` (`HarnessName`): The parent's harness when omitted.
- `options.modelConnection` (`string | Connection`): The parent's model connection when omitted.
- `options.name` (`string`): `<parent>-<8 hex>` when omitted.
- `options.workstream` (`string`): The line of work the task belongs to (`Workstream`): one of yours, matched whatever its case, or a new name,
which makes one. Every charge of the job, and of what it starts, is counted under it.
- `options.approvals` (`ScopeApprovals`): The child's own approval settings (as `create` takes them), within its parent's, which it follows where it sets
none: one looser than its parent's throws `InvalidRequest`.
- `options.user` (`UserOption`, default: the current user): Whose conversation `conversation` is (an account parent talking to a user: that user's thread).

Returns: The child, loaded, with `parent_id` set to this agent and `job` its running task.

Types:

```typescript
/**
 * When NoClick makes a spawned child report: `"done"` (always on),
 * `"blocked"` (it starts waiting on a person), `new Before(...tools)` or `new Every(intervalS)`. What
 * an update says, and when to reach out freely, belong in the child's instructions or task.
 */
type UpdateSpec = "done" | "blocked" | Before | Every;

/**
 * Left out when it's created, everything in its scope (`"everything"`): every connection, ones
 * connected later too, operations that need no account, the web and NoClick itself, plus the
 * account's owner to notify and ask for an account agent. A list narrows it to what it names:
 * connections (a `Connection`, or its name: every operation), one operation of one
 * (`"gmail.send_email_message"`), the capabilities `"search"` and `"fetch"`, a `Toolkit`, a
 * `Database` (its `query`, `execute` and `schema`, or `db.only(...)`; invite-only beta), a browser
 * (`"browser"`, or `"browser.act"` and the like), or a person (a
 * `Human` or `human.only(...)`: tools that notify, ask or hand off to them): at most 64 tools
 * in all. A string names a connection in the agent's own user (the account for an account agent,
 * whose `"credential:<id>"` names an account connected in the NoClick app), else an integration's operations that need no account (on NoClick's key), so
 * `tools: ["exa.search"]` (or `"exa"`, all of them) needs no connection. A `Connection` object from
 * another scope, another user's or the account's, stays that connection (a key acting for the whole
 * account only). A lazy `createIfMissing` connection is created first. Every agent can also run shell
 * commands (the `code` capability; a policy that denies `code` refuses them, and `shell: false` removes it).
 */
type AgentTools = ToolRef[] | { refs: ToolRef[] };

/**
 * A tool ref: a name, `"name.operation"`, a capability, a `Connection`, `connection.only(...)`, a
 * `Database` or `db.only(...)`. A name is a connection in the scope the tools run in, else an
 * integration's operations that need no account (on NoClick's key), so `"exa.search"` needs no connection.
 * An entry read back from `agent.tools` (`{ tool, bind }`, `{ human, tools }`) is taken as it is.
 */
type ToolRef = string | Connection | ConnectionOperations | Database | DatabaseOperations | ToolSource | JsonObject;

type JsonObject = { [key: string]: unknown };

/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** A key's, connected app's or agent's own approval settings by kind, with its `routing` beside them. */
type ScopeApprovals = Record<string, ApprovalSetting | ApprovalRouting>;

/** A kind's switch: `"allow"`, `"ask"`, `"deny"` (`terms` and `person_filing` take `"standing"` in place of `"allow"`:
 *  what's on file decides, never a person), the same as an object (a purchase may take `under_usd`; any kind `until`),
 *  or null for NoClick's default. */
type ApprovalSetting = "allow" | "ask" | "deny" | "standing" | {
  disposition: "allow" | "ask" | "deny" | "standing";
  under_usd?: number;
  until?: Date | string;
} | null;

/** Who answers a scope's held calls first (`approver`; null: the next scope up's), how long they have (`expires_in_s`,
 *  60 seconds to 7 days, a day by default), and what happens when they don't answer in time (`on_timeout`: `decline`,
 *  the default, or `escalate` to the next approver up, finally the owner); null puts it back. */
type ApprovalRouting = {
  approver?: Approver | null;
  on_timeout?: "decline" | "escalate" | null;
  expires_in_s?: number | null;
} | null;

/** Who answers a held call: the account's owner, a person by email, one of your users (by your id), one of your agents
 *  (by id or name), or your own code (a key holding `approvals:answer`). */
type Approver = "owner" | { owner: true } | { email: string } | { user_id: string } | { agent_id: string } |
  { code: true };

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.children

```typescript
children(options?: { status?: AgentStatus; limit?: number }): Promise<Agent[]>
```

Its children, newest first (expired ones too, for their 30 days): `Agent.list({ parent })`, read where it lives.

Parameters:

- `options.status` (`AgentStatus`)
- `options.limit` (`number`): Return at most this many.

Returns: Each child with its `status`, `last_active_at`, `running_turns` and, if `spawn`
made it, the `job` it was started with.

Types:

```typescript
/**
 * `working` (a turn queued or running), `waiting` (its turns wait on a person: a question, a
 * held call), `idle`, or `expired` (past its `ttlS`: no turns, readable for 30 days). Pausing
 * stops triggers, not work: see `paused`.
 */
type AgentStatus = "working" | "waiting" | "idle" | "expired";
```

### Agent.jobs

```typescript
jobs(options?: JobFilters): Promise<Job[]>
```

The jobs it started, newest first: the tasks of the children it spawned, and the messages it sent
with its `agents` tools (whose only update is `done`).

Parameters:

- `options.status` (`OperationStatus | "live" | readonly (OperationStatus | "live")[]`): Statuses, or `"live"` for every non-terminal one.
- `options.kind` (`"task" | "message"`): `task` (spawned), or `message` (sent with its `agents` tools).
- `options.agent` (`string | Agent`): The agent doing the work (an `Agent` or id).
- `options.conversation` (`string`): The parent's conversation that started them.
- `options.limit` (`number`): Return at most this many.

Returns: Every matching job (or the first `limit`), newest first, each with its `status`, `step` and
`latest_update`; `wait()` on one gives its reply.

Types:

```typescript
type OperationStatus =
  | "queued" | "running" | "awaiting_human"
  | "succeeded" | "failed" | "canceled" | "expired";
```

### Agent.ask

```typescript
ask(
  question: string,
  options?: {
    conversation?: string;
    interject?: boolean;
    timeoutS?: number;
    user?: UserOption;
  },
): Promise<AgentReply>
```

Ask it something without stopping it. By default its model answers from a snapshot of the
conversation as it stands, with no tools; the question and answer aren't added to the
conversation, and its running turn carries on untouched (an `agent.ask` operation, billed like a
short turn). On a coding harness the snapshot holds the conversation to its last finished turn
plus what the running one has done so far: its NoClick tool calls and its own commands (with
their output), edits and reads, as its sandbox reported them. An agent on a Claude or ChatGPT plan rejects with `NotAvailable` (answering in a
one-off harness session is in invite-only beta). `interject: true` joins the running turn
instead (the harness's own steering; on `sdk`, before its next model call): the agent sees the
question, may change course, and the reply that turn ends with comes back; with nothing running
it's an ordinary message. `conversation` defaults to its session. Asked from another agent's turn,
it's an ordinary message: a job of the asker's whose reply wakes it.

Parameters:

- `question` (`string`, required)
- `options.conversation` (`string`)
- `options.interject` (`boolean`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `options.timeoutS` (`number`)

Returns: The answer as an `AgentReply`; with `interject`, the reply the turn it joined ended with.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.a2aCard

```typescript
a2aCard(): Promise<JsonObject>
```

Its A2A agent card (the JSON other agents discover it by): its `name`, JSON-RPC `url` and `skills`.

Returns: The card as a dict: the agent's `name`, its JSON-RPC `url` and the `skills` it offers.

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

### Agent.update

```typescript
update(
  changes: Omit<AgentFields, "modelConnection"> & { name?: string; budgetUsdPerMonth?: number | null; budgetForRun?: boolean; modelConnection?: string | Connection | null; } & Pick<AgentCreateOptions, "timezone" | "repos" | "network" | "shell" | "browserProfile" | "card" | "machine" | "memories" | "skills" | "turnLimits" | "secrets"> & AgentApprovalsOption,
): Promise<this>
```

Change fields; returns the updated agent. A new `harness` without a `model` takes that harness's
default model; `modelConnection: null` removes an `sdk` agent's own model key; `secrets` are those in its shell,
in place of the ones it has (`[]` takes them all away). `name` renames it, unique among its scope's agents: its
old name keeps reaching it and stays reserved for it (`formerNames`), and a NoClick keeps its name.
`budgetForRun: true` with `budgetUsdPerMonth` sets that budget for one run alone (its turn under way, else its
next one): the budget it replaced comes back once that run ends, however it ends (`budgetRestore` says what comes
back meanwhile). A budget set without it stands until changed.

    await coder.update({ budgetUsdPerMonth: 2, budgetForRun: true });
    console.log(coder.budgetRestore);   // { budgetUsdPerMonth: 10, operationId: null }

Parameters:

- `changes` (`Omit<AgentFields, "modelConnection"> & { name?: string; budgetUsdPerMonth?: number | null; budgetForRun?: boolean; modelConnection?: string | Connection | null; } & Pick<AgentCreateOptions, "timezone" | "repos" | "network" | "shell" | "browserProfile" | "card" | "machine" | "memories" | "skills" | "turnLimits" | "secrets"> & AgentApprovalsOption`, required)

Returns: This agent, updated. A field you leave out is unchanged, and changes apply from its next turn.

Types:

```typescript
interface AgentFields {
  instructions?: string;
  /**
   * The harness's own model: an OpenRouter id with the `openrouter/` prefix on `sdk`, an alias such
   * as `sonnet` on `claude_code`, a `provider/model` on `opencode`, `hermes` and `openclaw`; the
   * harness's default when omitted.
   */
  model?: string;
  /**
   * What runs it: `sdk` (the default), NoClick's own agent loop, or a coding agent in a sandbox of
   * its own (`claude_code`, `codex`, `opencode`, `hermes`, `openclaw`). A new harness without a
   * `model` takes that harness's default model, and each conversation carries on on it.
   */
  harness?: HarnessName;
  /**
   * The connection whose key or plan it thinks with: a `Connection` of a `kind: "model"`
   * integration such as `anthropic`, or its name, in the agent's own scope (a lazy
   * `createIfMissing` one is created first). Every CLI harness needs one, and it may still be
   * pending; on `sdk` it's optional and lets `model` name `anthropic/...` or `openai/...` on your key.
   * In `fromName`, `null` clears it (back to `sdk` takes `harness: "sdk", modelConnection: null`).
   */
  modelConnection?: string | Connection | null;
  /**
   * How hard its model reasons in every conversation: one of its harness's `efforts`
   * (`Agent.harnesses()`, or a conversation's settings). In `update` and `fromName`, `null` clears it.
   */
  effort?: string | null;
  /** `fast` runs its model in its harness's fast mode where it has one (`speeds`). In `update`, `null` clears it. */
  speed?: AgentSpeed | null;
  /**
   * How far its coding harness goes before asking a person, in each conversation that sets none (a conversation's
   * `setPermissionMode` wins): one of its harness's `permissionModes`. In `update`, `null` puts back `full-access`.
   */
  permissionMode?: PermissionMode | null;
  /**
   * Commands a coding agent's sandbox (its container, on a machine) runs as it starts, in order, after its `repos`
   * and with its secrets in the environment (a CLI installed, a config file written); up to 20. In `update`, `[]`
   * clears them.
   */
  setup?: string[];
  /**
   * Docker in a coding agent's sandbox, which is then a VM of `sandboxSize` with dockerd running before its first
   * turn: `docker`, `docker compose` and testcontainers work as on any Linux machine. The VM is billed at its cost
   * for all of its size while it's up. In `update`, `false` drops its size.
   */
  docker?: boolean;
  /** The VM a Docker agent works in (`SandboxSize`; `small` unless it says). In `update`, `null` is `small` again. */
  sandboxSize?: SandboxSize | null;
  /**
   * How it may turn Docker on for a task that needs it, without `docker` (`AppTesting`; `by_itself` unless it says).
   * In `update`, `never` turns off what's on now, from its next turn.
   */
  appTesting?: AppTesting;
  /**
   * How it moves to another of the owner's model connections (`ModelSwitching`): left out, it switches by itself to
   * any of their own plans and asks before a paid key. In `update`, `null` is the default rule again; letting it switch
   * more freely is the owner's own call.
   */
  modelSwitching?: ModelSwitchingChange | null;
  tools?: AgentTools;
  /** What it may do with each app it reaches (`ToolRules`). In `update`, `{}` clears them. */
  toolRules?: ToolRules;
  /**
   * What it may ask its user to connect at run time (a `request_connection` tool): integration
   * names (or `IntegrationInfo`s), single `"integration.operation"`s, or `"*"`. What the user connects
   * is a grant (`grants()`), kept apart from the agent's fields.
   */
  canRequest?: (string | { name: string })[];
}

/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** How fast a conversation's model runs: `fast` where its harness has a fast mode (`speeds`). */
type AgentSpeed = "standard" | "fast";

/** When a conversation's coding harness asks a person before acting (`full-access`, the default, asks nothing). */
type PermissionMode = "approval-required" | "auto-accept-edits" | "auto" | "full-access";

/** The VM a Docker agent works in: `small` (2 CPUs, 4 GB), `medium` (4 CPUs, 8 GB) or `large` (8 CPUs, 16 GB). */
type SandboxSize = "small" | "medium" | "large";

/**
 * How a coding agent may turn app testing on (Docker in its sandbox, for a task that runs the app or its tests against
 * a real database): `by_itself` turns it on when a task needs it and off once it's done, saying each in its chat;
 * `ask_first` asks the account's owner in the chat each time; `never`.
 */
type AppTesting = "by_itself" | "ask_first" | "never";

/** `modelSwitching` as it's set: its allowed connections by name or as `Connection`s. Only what's given changes. */
interface ModelSwitchingChange {
  mode?: "switch" | "stay";
  allowed?: (string | Connection)[] | null;
}

/**
 * Left out when it's created, everything in its scope (`"everything"`): every connection, ones
 * connected later too, operations that need no account, the web and NoClick itself, plus the
 * account's owner to notify and ask for an account agent. A list narrows it to what it names:
 * connections (a `Connection`, or its name: every operation), one operation of one
 * (`"gmail.send_email_message"`), the capabilities `"search"` and `"fetch"`, a `Toolkit`, a
 * `Database` (its `query`, `execute` and `schema`, or `db.only(...)`; invite-only beta), a browser
 * (`"browser"`, or `"browser.act"` and the like), or a person (a
 * `Human` or `human.only(...)`: tools that notify, ask or hand off to them): at most 64 tools
 * in all. A string names a connection in the agent's own user (the account for an account agent,
 * whose `"credential:<id>"` names an account connected in the NoClick app), else an integration's operations that need no account (on NoClick's key), so
 * `tools: ["exa.search"]` (or `"exa"`, all of them) needs no connection. A `Connection` object from
 * another scope, another user's or the account's, stays that connection (a key acting for the whole
 * account only). A lazy `createIfMissing` connection is created first. Every agent can also run shell
 * commands (the `code` capability; a policy that denies `code` refuses them, and `shell: false` removes it).
 */
type AgentTools = ToolRef[] | { refs: ToolRef[] };

/**
 * A tool ref: a name, `"name.operation"`, a capability, a `Connection`, `connection.only(...)`, a
 * `Database` or `db.only(...)`. A name is a connection in the scope the tools run in, else an
 * integration's operations that need no account (on NoClick's key), so `"exa.search"` needs no connection.
 * An entry read back from `agent.tools` (`{ tool, bind }`, `{ human, tools }`) is taken as it is.
 */
type ToolRef = string | Connection | ConnectionOperations | Database | DatabaseOperations | ToolSource | JsonObject;

type JsonObject = { [key: string]: unknown };

/**
 * What an agent may do with each app it reaches, as `{ key: ToolRule }`. A key is an app as `tools` names it (a
 * connection's name, `"credential:<id>"`, an integration's, `"noclick"`, `"search"`, `"fetch"`), one action of it
 * (`"work-gmail.delete_email_message"`; NoClick's are its groups, `"noclick.spend"`), or `"*"` for whatever the rest
 * don't name. The most specific key naming a call decides it; none, it's allowed. With everything, `"*": "off"` keeps
 * it to the apps the rules turn on, so an account connected later starts off.
 */
type ToolRules = Record<string, ToolRule>;

/** `allow` runs a call, `ask` holds it for the owner's yes (an approval), `off` refuses it. */
type ToolRule = "allow" | "ask" | "off";

interface AgentCreateOptions extends AgentFields, CallOptions {
  /**
   * A temporary agent: after this many seconds it's `expired`, taking no turns (its pending
   * wake-ups are canceled) and readable for 30 days, then deleted. Set when it's created, for good: an
   * existing agent with another makes `fromName` throw `Conflict` naming its `ttl_s`.
   */
  ttlS?: number;
  /**
   * Its parent: a child's budget is held out of what the parent's has left; without one, it draws on the
   * parent's as it spends. Set when it's created, for good: an existing agent with another makes
   * `fromName` throw `Conflict` naming its `parent_id`.
   */
  parent?: string | Agent;
  /** In `fromName`, `null` clears it, as `browserProfile` and `card` do. */
  budgetUsdPerMonth?: number | null;
  /** What wakes it without a message: `OnWebhook`, `OnEvent`, `OnPlatformEvent`, `Cron` and `OnQueue`. */
  triggers?: TriggerDefinition[];
  /**
   * The profile its `browser` tool signs in with (a `BrowserProfile` or id of its own user's, or the
   * account's for an account agent): each conversation gets a browser of its own for a turn, a step only
   * a person can do holds the turn `awaiting_human`, and its calls follow policy as `browser.*`. In
   * `update`, `null` signs it out.
   */
  browserProfile?: string | BrowserProfile | null;
  /**
   * Invite-only beta. The card it holds and pays with (a `Card` or id of its own scope; giving one
   * takes the key's `cards` scope): a card has one agent at a time. It gets `card__status` and
   * `card__purchase` (approve before paying: above the card's threshold the turn waits for a person, whose
   * answer is its next turn), which policy names `card.status` and `card.purchase`, and never sees the
   * number. A turn answering someone outside its scope, or a test run, buys nothing. A child it spawns pays
   * with the same card only when given `"card"` in its tools. In `update`, `null` takes its card back.
   */
  card?: string | Card | null;
  /**
   * Volumes its shell mounts read-write, by absolute path, in every conversation, up to 5:
   * `{ "/data": Volume.fromName("datasets") }` (a `Volume`, an id or a name: its user's own, else the
   * account's). Not `/workspace`, `/root` or a system folder. An `sdk` agent's shell sees each as the
   * turn started and saves its writes when it ends; a coding harness's sandbox, while it's up.
   */
  volumes?: Record<string, VolumeRef>;
  /**
   * The `Memory`s it reads besides its own (`agent.memory`), in order, up to 10: a `Memory`, its id or name
   * (its user's own, else the account's), or another agent's `memory`. Each is read-only to it unless given as
   * `memory.writable()`; a user's agent reads the account's memories but never writes them, and never another
   * user's. Every turn starts with each entry's name and description, its own memory's first.
   */
  memories?: MemoryRef[];
  /**
   * The `Skill`s it uses, in order, up to 20: a `Skill` (`skill.pinned(n)` to hold one version), its id or name (its
   * user's own, else the account's). A coding harness finds them where it reads skills; an `sdk` agent sees each
   * one's name and description every turn and reads one with `skill__read`.
   */
  skills?: SkillRef[];
  /**
   * Secrets whose keys become environment variables in its shell, up to 20, a later one's key winning
   * (a `Secret`, an id or a name: its user's own, else the account's; an account agent's, the account's
   * only). A model provider's key (`OPENAI_API_KEY` and the like) belongs on `modelConnection`: a
   * secret holding one throws `InvalidRequest`.
   */
  secrets?: SecretRef[];
  /**
   * The IANA timezone every turn is told the date and time in; without one, the acting user's
   * `timezone`, else UTC. An account's own agent made without one starts in its owner's, where their
   * NoClick assistant tells the time. In `fromName`, `null` clears it.
   */
  timezone?: string | null;
  /**
   * Repositories cloned into its workspace (`/workspace/<name>`) at a conversation's first turn:
   * `connection.checkout(...)` through a `github` connection of its own scope, or `repo.checkout(...)`
   * for a NoClick `Repo` of its own scope, up to 10 (none with `shell: false`). Its `git` reaches those
   * repositories only, through NoClick, with a key made for its sandbox; a push goes through only to the branches the
   * checkout's `push` globs name (none: read-only), judged by NoClick on the way to the git host,
   * since a harness's own `git push` is no tool call a policy could judge. `gh` only reads a git host's.
   */
  repos?: RepoCheckout[];
  /**
   * What its shell and code may reach: `true` (anywhere, the default), `false`, or up to 50 hosts
   * (`"pypi.org"`, or `"*.example.com"` for a domain and its subdomains), over HTTPS on port 443 only.
   * What it needs to work stays reachable, and `false` leaves only that: an `sdk` agent's shell reaches
   * NoClick's git proxy when it has `repos` (its model and tools run on NoClick); a coding harness reaches
   * NoClick's API, NoClick's proxy for its model on a key and for git, and on a Claude or ChatGPT plan that
   * provider's own hosts. Its tools run on NoClick, outside the limit. Omitted, its parent's, else
   * anywhere; the children it spawns take its. Where NoClick can't keep to a limited network (a coding
   * harness on a key other than Claude, ChatGPT or OpenRouter, say), it throws `NotAvailable` rather
   * than widen it. In `update`, from its next turn.
   */
  network?: NetworkAccess;
  /**
   * `false` takes the shell (the `code` capability) away from an `sdk` agent, and from the children it
   * spawns; a CLI harness refuses it with `InvalidRequest`, since its shell is the harness.
   */
  shell?: boolean;
  /**
   * How far one turn of an `sdk` agent goes before it wraps up:
   * `{ steps: 100, usd: 2, minutes: 45 }`, each left out at its default ($1 of model calls and 30 minutes, with
   * 200 model calls as a backstop; at most 200, $25 and 60). A turn its steps end stops there saying nothing and
   * carries on by itself in a follow-up turn on the same conversation, up to 3 in a row, unless a message comes
   * first; one its spend or minutes end says where the work stands and waits to be asked (`reply.endedBy` names
   * the limit). A coding harness ends its own turns, and refuses it with `InvalidRequest`. In `update` (from its
   * next turn) and `fromName`, `null` goes back to the defaults.
   */
  turnLimits?: TurnLimits | null;
  /**
   * Where its sandboxes run (`regions()`), for good: a coding harness runs there whole, and an `sdk`
   * agent's shell does while its loop runs in NoClick's own service. Omitted, its parent's, else your
   * account's default region, else wherever NoClick has capacity. An existing agent elsewhere makes
   * `fromName` throw `Conflict` naming its `region`.
   */
  region?: RegionName;
  /**
   * Invite-only beta. The always-on `Machine` (or its id) its harness runs on instead of a
   * sandbox of its own: nothing reaped when it's quiet, no per-minute sandbox charge, in the
   * machine's region. A coding harness there reaches its model through NoClick's credential proxy,
   * so its `modelConnection` holds a Claude, ChatGPT or OpenRouter key, or your account's own plan: a
   * Claude plan on `claude_code` or a ChatGPT plan on `codex`, its sign-in kept in that agent's own
   * container (the answer's `notes` say so). Anyone else's plan throws `NotAvailable`; a machine runs
   * at most 50 agents. In `update`, `null` moves it back to sandboxes.
   */
  machine?: string | Machine | null;
}

/** Options every call accepts: the client and the user it acts for. */
interface CallOptions {
  client?: NoClick;
  /** `undefined` = the ambient user (`asUser`), `null` = the account itself. */
  user?: UserOption;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;

/** A volume to mount: a `Volume`, its id, or its name (the user's own, else the account's). */
type VolumeRef = string | Volume;

/** A memory to attach: a `Memory`, `memory.writable()`, another agent's `agent.memory`, or a memory's id or name. */
type MemoryRef = string | Memory | MemoryLink | AgentMemory;

/** A skill to attach: a `Skill`, `skill.pinned(n)`, or a skill's id or name. */
type SkillRef = string | Skill | SkillLink;

/** A secret to pass: a `Secret`, its id, or its name (the user's own, else the account's). */
type SecretRef = string | Secret;

/** `true` (anywhere), `false` (nothing) or the hosts it may reach, `"*.example.com"` for a domain and its subdomains. */
type NetworkAccess = boolean | string[];

/**
 * How far one turn of an `sdk` agent goes, each limit left out at its default: `steps` (model calls; 30, at most
 * 200), `usd` (what they cost; $1, at most $25) and `minutes` (15, at most 60).
 */
interface TurnLimits {
  steps?: number;
  usd?: number;
  minutes?: number;
}

type RegionName = "us-east" | "us-west" | "eu" | "ap" | "in";

/** An agent's own approval settings, as `create`, `update` and `spawn` take them. */
interface AgentApprovalsOption {
  /**
   * What its own calls wait for a person on, in place of the account's, by kind of hold (`ApprovalPolicy.get()` lists
   * the settable ones): `"allow"`, `"ask"`, `"deny"`, or `{ disposition, under_usd?, until? }` (a purchase allowed at
   * or under `under_usd`, asked above). Never looser than the account's ceiling for the kind (raise it with
   * `ApprovalPolicy.set({ ceilings })`), a child's never looser than its parent's (which it follows where it sets
   * none), and a purchase or a deletion past the default needs a monthly cap on the account. Loosening is the owner's:
   * signed in, their own message to one of their agents, or a key naming `approvals:policy` (after a 10-minute undo
   * window); an agent acting on its own waits for their yes. In `update`, a kind set to `null` goes back to the
   * account's (a child's, to its parent's). `toolRules` turning `noclick.spend` or `noclick.delete` to `"allow"` set
   * `purchase` or `delete` to allow with it. `routing` among them names who answers its held calls first, in place of
   * its parent's or the account's approver (finally the owner), as `ApprovalPolicy.set`'s `routing` takes it: never
   * the agent itself nor one of its children (its parent may approve its calls).
   */
  approvals?: ScopeApprovals;
}

/** A key's, connected app's or agent's own approval settings by kind, with its `routing` beside them. */
type ScopeApprovals = Record<string, ApprovalSetting | ApprovalRouting>;

/** A kind's switch: `"allow"`, `"ask"`, `"deny"` (`terms` and `person_filing` take `"standing"` in place of `"allow"`:
 *  what's on file decides, never a person), the same as an object (a purchase may take `under_usd`; any kind `until`),
 *  or null for NoClick's default. */
type ApprovalSetting = "allow" | "ask" | "deny" | "standing" | {
  disposition: "allow" | "ask" | "deny" | "standing";
  under_usd?: number;
  until?: Date | string;
} | null;

/** Who answers a scope's held calls first (`approver`; null: the next scope up's), how long they have (`expires_in_s`,
 *  60 seconds to 7 days, a day by default), and what happens when they don't answer in time (`on_timeout`: `decline`,
 *  the default, or `escalate` to the next approver up, finally the owner); null puts it back. */
type ApprovalRouting = {
  approver?: Approver | null;
  on_timeout?: "decline" | "escalate" | null;
  expires_in_s?: number | null;
} | null;

/** Who answers a held call: the account's owner, a person by email, one of your users (by your id), one of your agents
 *  (by id or name), or your own code (a key holding `approvals:answer`). */
type Approver = "owner" | { owner: true } | { email: string } | { user_id: string } | { agent_id: string } |
  { code: true };
```

### Agent.grants

```typescript
grants(): Promise<AgentGrant[]>
```

The connections its user gave it at run time (requested or active), oldest first.

Returns: Each grant with the `connection` it names, its `integration`, its `status` and the
`operations` it covers (`None`: every one).

### Agent.toolAccess

```typescript
toolAccess(): Promise<AgentToolAccess>
```

What it may do with each app it reaches, app by app: each connection of its scope, NoClick and the web, whether
it's on, each action with what its rules say of it, and how often each ran in the last 7 days. Change it with
`update({ toolRules })`.

Returns: Each connection of its scope (connected later ones too), any app its rules name, NoClick and the web:
whether it's `on`, each action with what its rules say of it (`verdict`) and how often each ran in
the last 7 days (`calls`). `mode` is `restricted` when it's kept to the apps its rules turn on.

### Agent.switchModel

```typescript
switchModel(
  connection: string | Connection,
  options?: {
    reason?: string;
    evidence?: JsonObject;
    scope?: "once" | "standing";
  },
): Promise<ModelSwitchResult>
```

Move it onto another model connection (a `Connection`, its name, or `"noclick"` for NoClick's key): its harness
and model too where that one runs another, its conversations carrying over from their next turn. The same call its
own `switch_model` tool makes, by its `modelSwitching` rule: any of the owner's own plans; a paid key on the
owner's own call, or with `evidence` citing where they said so (`{channel_id, message_id, quote}`), which NoClick
checks is theirs, for this switch or (`scope: "standing"`) whenever a plan runs out; else NoClick asks them.

Parameters:

- `connection` (`string | Connection`, required)
- `options.reason` (`string`)
- `options.evidence` (`JsonObject`)
- `options.scope` (`"once" | "standing"`, default `"once"`)

Returns: `status`: `switched`, `unchanged`, or `asked` with its `request_id`.

Types:

```typescript
type JsonObject = { [key: string]: unknown };

/** What `agent.switchModel` did: `switched`, `unchanged`, or `asked` (the owner's one tap, `requestId`). */
interface ModelSwitchResult {
  status: "switched" | "unchanged" | "asked";
  connection: string;
  harness?: string;
  model?: string;
  pays?: "plan" | "per_use" | "at_cost";
  requestId?: string;
  message?: string;
  raw: JsonObject;
}
```

### Agent.modelGrants

```typescript
modelGrants(): Promise<ModelSwitchGrant[]>
```

The owner's say-so for its paid keys, newest first: each with how, where and when they gave it.

Returns: Each `ModelSwitchGrant`: which keys, once or standing, and how, where and when the owner gave it.

### Agent.grantModelSwitch

```typescript
grantModelSwitch(
  connections?: (string | Connection)[] | null,
  options?: { scope?: "once" | "standing" },
): Promise<ModelSwitchGrant>
```

Let it move onto paid keys by itself (`connections`, or any): the owner's own call.

Parameters:

- `connections` (`(string | Connection)[] | null`, default `null`)
- `options.scope` (`"once" | "standing"`, default `"standing"`)

Returns: The `ModelSwitchGrant` kept.

### Agent.revokeModelGrant

```typescript
revokeModelGrant(grant: ModelSwitchGrant | string): Promise<ModelSwitchGrant>
```

Take back the owner's say-so (a `ModelSwitchGrant` or its id).

Parameters:

- `grant` (`ModelSwitchGrant | string`, required)

Returns: The grant, with `revoked_at`.

### Agent.revokeGrant

```typescript
revokeGrant(grant: string | AgentGrant): Promise<void>
```

Take back a grant (an `AgentGrant` or its id): its tools leave the agent; the connection stays the user's.

Parameters:

- `grant` (`string | AgentGrant`, required)

### Agent.delete

```typescript
delete(): Promise<TrashItem>
```

Delete the agent and its sub-agents: they go to the trash, restorable for 30 days (pending
wake-ups and jobs end now). Returns its `TrashItem`.

Returns: Its `TrashItem`: `restore()` brings it and its sub-agents back.

### Agent.wake

```typescript
wake(conversation: string, options: WakeOptions): Promise<Wakeup>
```

Wake it later in `conversation`. At a moment (`at`), after a while (`afterS`), when an operation
reaches a terminal status or a platform event happens (`when`, narrowed by `filters`), or at each
time of a schedule (`every`, a `Cron`: a routine, until it's canceled). Then the conversation
takes a turn whose message is the `note`, followed by what woke it; a running turn there goes
first. Durable, delivered once, billed and capped like any turn; one the account can't pay for
fails. A recurring one stays pending, due at its schedule's next time after each turn, so times
it missed fold into one turn. An agent holds up to 100 pending and 20 recurring; a time wake-up is
1 minute to 365 days ahead, a schedule comes round at most every minute (every 15 for one the
agent sets itself), and a conversation's wake-ups at a time are delivered at least a minute apart (news, an
operation it waited on or a child's update, comes as soon as the conversation is free). Every agent can
also set, list, change and cancel its own with its `wake_me`, `list_wakeups` and `cancel_wakeup`
tools, in the conversation it's in or, with `conversation`, another of its own (never a channel's,
nor from a conversation with someone outside its scope), so work nobody is waiting on runs apart
from the thread a person reads. A channel's conversation (`channel:<its id>`) rejects with
`InvalidRequest`, as `message` does: only the channel starts turns there.

```ts
await assistant.wake("briefing", { every: new Cron("0 8 * * 1-5", { tz: "user" }),
  note: "Brief me on today's calendar and anything urgent in my inbox." });
```

Parameters:

- `conversation` (`string`, required)
- `options.note` (`string`, required): What the turn is told, 1 to 4,000 characters.
- `options.at` (`Date | string`): A moment: a `Date`, or an ISO 8601 string with its offset.
- `options.when` (`Operation<unknown> | readonly Operation<unknown>[] | string`): When an operation reaches a terminal status (a `Job`, a `HumanRequest`, a `ConnectLink`, ...; one that has wakes
it at once), once when the last of several does (a list of them, up to 20: its turn is told what each came to,
and a child's `done` update for one of those jobs comes in that turn), or a NoClick event type such as
`"connection.connected"` (`*` matches the rest of a name): the first matching event after it was set wakes it.
A user's conversation hears that user's events; one of your account's own hears every event, your users'
included.
- `options.filters` (`JsonObject`): With an event `when`: dotted paths into the event's `data` that must equal these values.
- `options.every` (`Cron`): A routine: it wakes the conversation at each time of this `Cron` until it's canceled (`tz: "user"` follows the
conversation's user). The note is what it's told, so the `Cron` takes no `message`.
- `options.user` (`UserOption`, default: the current user): Whose conversation it is, as `message()` takes it.
- `options.afterS` (`number`): This many seconds from now.

Returns: The wake-up, `pending`; `update()` changes it, `cancel()` calls it off.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

type JsonObject = { [key: string]: unknown };
```

### Agent.wakeups

```typescript
wakeups(
  options?: ReadOptions & {
    conversation?: string;
    status?: WakeupStatus;
    limit?: number;
  },
): Promise<Wakeup[]>
```

Its wake-ups in the acting user's conversations, newest first, or in those of the users
`userFilter` covers. That's `ALL_USERS`, `NO_USER`, a `User` or your id for one, read without the user
header, as `conversations` does. They're those your code and the agent set, and NoClick's own (a job's
update, a connect link it asked for being done, a decided approval); `conversation` and
`status` narrow them. Each one's `cancel()` acts in its own thread.

Parameters:

- `options.status` (`WakeupStatus`)
- `options.limit` (`number`): Return at most this many.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.client` (`NoClick`)
- `options.conversation` (`string`)

Returns: Every matching wake-up (or the first `limit`), newest first, each with its `source`, when it's
due (`at`) or what it waits for (`when`), whose thread it's in (`user_id`) and, once delivered,
the turn it started. `cancel()` acts in that wake-up's own thread.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** `pending` until its moment, then `delivered` (its turn started), `canceled` or `failed`. */
type WakeupStatus = "pending" | "delivered" | "canceled" | "failed";
```

### Agent.triggers

```typescript
triggers(): Promise<AgentTrigger[]>
```

What wakes it besides a message: schedules, webhooks, app and NoClick events, queues, and the inboxes
and numbers that hand it mail and calls.

Returns: Each trigger with its `kind`, its `spec`, its `status` (`paused` while the agent is),
the `url` a webhook listens at, when a schedule's `next_run` is and when it
`last_fired_at`. An `error` says why one can't fire.

### Agent.addTrigger

```typescript
addTrigger(trigger: TriggerDefinition): Promise<AgentTrigger>
```

Add a trigger (up to 20): an `OnWebhook` (its `url` is where to POST), an `OnEvent` (`error` until its
connection is connected) or a `Cron` (`nextRun` says when it fires; `paused` while the agent is). Where
`fromName(name, { triggers })` sets the triggers, that code's list wins the next time it runs.

Parameters:

- `trigger` (`TriggerDefinition`, required)

Returns: The trigger as added; a webhook's `url` is where to send its POSTs. An event
trigger whose connection isn't connected yet is `error` until it is.

Types:

```typescript
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;
```

### Agent.updateTrigger

```typescript
updateTrigger(
  trigger: AgentTrigger | string | TriggerDefinition,
  changes: TriggerChanges,
): Promise<AgentTrigger>
```

Change a trigger in place: it keeps its id, its history, and a webhook its URL. `cron` moves a schedule
to its time in its `tz` at once (and changes its `message` when the `Cron` has one); `message` changes what
any trigger's turn is told, and `conversation` the template a webhook, event or queue trigger keys
its conversations by (`null` clears either); `filters` replaces an app event's or NoClick event's filters (it
hears by them from the next delivery); `mode` changes the mode of a channel the agent sits in. A webhook's
name, an event's connection and event, and a queue stay: remove it and add another for that. `trigger` is an
`AgentTrigger`, its id, or the definition you added, as for `removeTrigger`. Checked and registered as
`addTrigger` does; a paused schedule takes its new time when it resumes. Returns the trigger as it is now,
with its new `nextRunAt`.

Parameters:

- `trigger` (`AgentTrigger | string | TriggerDefinition`, required)
- `changes` (`TriggerChanges`, required)

Returns: The trigger as it is now, with its new `next_run_at`.

Types:

```typescript
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;

/** What `agent.updateTrigger` changes; `null` clears `message`, `conversation` or `filters`. */
interface TriggerChanges {
  /** A schedule's new time, read in its `tz` (and its `message`, when it has one). */
  cron?: Cron;
  /** What the agent is told with every delivery. */
  message?: string | null;
  /** The template a webhook, event or queue trigger keys its conversations by. */
  conversation?: string | null;
  /** An app event's filters, by field, or a NoClick event's (dotted paths into its data): all of them, replacing its own. */
  filters?: JsonObject | null;
  /**
   * A channel trigger's: `mentions` (a person's post wakes the agents it names) or `all` (every person's post wakes
   * every agent in it). It's the channel's, so every agent in it hears it that way; your key needs `channels`.
   */
  mode?: "mentions" | "all";
}

type JsonObject = { [key: string]: unknown };
```

### Agent.pauseTrigger

```typescript
pauseTrigger(
  trigger: AgentTrigger | string | TriggerDefinition,
): Promise<AgentTrigger>
```

Pause one trigger, the agent running on. A schedule is skipped (its `nextRunAt` still reads), a webhook's
calls and app or NoClick events are acknowledged and dropped, a queue's messages wait on the queue. Pause
the agent (`pause()`) to stop everything that wakes it. Returns the trigger as it is now.

Parameters:

- `trigger` (`AgentTrigger | string | TriggerDefinition`, required)

Returns: The trigger as it is now (`paused` is `True`).

Types:

```typescript
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;
```

### Agent.resumeTrigger

```typescript
resumeTrigger(
  trigger: AgentTrigger | string | TriggerDefinition,
): Promise<AgentTrigger>
```

Resume a trigger paused on its own, or one its failures stopped. It wakes the agent again (a schedule at
its next run), unless the agent itself is paused.

Parameters:

- `trigger` (`AgentTrigger | string | TriggerDefinition`, required)

Returns: The trigger as it is now (`state` is `live` unless the agent is paused).

Types:

```typescript
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;
```

### Agent.removeTrigger

```typescript
removeTrigger(trigger: AgentTrigger | string | TriggerDefinition): Promise<void>
```

Remove a trigger: an `AgentTrigger`, its id, or the definition you added (`NotFound` if none matches; an
`OnWebhook` by its unique `name`). Mail and call triggers change on their inbox or number.

Parameters:

- `trigger` (`AgentTrigger | string | TriggerDefinition`, required)

Types:

```typescript
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;
```

### Agent.toolServers

```typescript
toolServers(options?: { conversation?: string }): Promise<AgentToolServer[]>
```

Its MCP servers, each a step of its automation, in the order they were added, with each one's state: how it
lets its client in (`signIn`), its `status` and `problem`, the `tools` its last run found, its `host` and
`icon`. With `conversation`, each as that conversation's coding harness last said it where that's newer
(`status` `connecting` too), and whether it can connect one again in place now (`reconnectable`:
`agent.conversation(name).reconnectToolServer(server.name)`).

Parameters:

- `options.conversation` (`string`)

Returns: A list of `AgentToolServer`, in the order they were added.

### Agent.addToolServer

```typescript
addToolServer(
  url: string,
  options?: {
    name?: string;
    transport?: "http" | "sse";
    credential?: string;
    headers?: Record<string, string>;
  },
): Promise<AgentToolServer>
```

Give it an MCP server's tools from its next turn. The server is a step of its automation, reached at its public
https URL (`transport: "sse"` for one that speaks only the older SSE), named `name`, else after the URL's host
(`mcp.linear.app` is `linear`). `credential` is the account's own sign-in to it, which NoClick's MCP sign-in
makes, or `headers` carry the key it takes instead (`{ Authorization: "Bearer <key>" }`): kept as a credential,
sent on every request, never read back. A server that asks its client to sign in, given neither, is added
waiting for a person (`status` `needs_sign_in`): `server.connectLink()` signs them in. Up to 20. Returns the
`AgentToolServer` as added: its `id` is what `removeToolServer` takes.

Parameters:

- `url` (`string`, required)
- `options.name` (`string`)
- `options.transport` (`"http" | "sse"`, default `"http"`)
- `options.credential` (`string`)
- `options.headers` (`Record<string, string>`)

Returns: The `AgentToolServer` as added: its `id` (what `remove_tool_server` takes), `name`, `url`,
how it lets its client in (`sign_in`), its `status` and its `headers`' names.

### Agent.updateToolServer

```typescript
updateToolServer(
  server: string | AgentToolServer,
  headers: Record<string, string>,
): Promise<AgentToolServer>
```

Replace an MCP server's headers. From its next turn it sends `headers` (a new key; `{}`: none), and those
given before are deleted.

Parameters:

- `server` (`string | AgentToolServer`, required)
- `headers` (`Record<string, string>`, required)

Returns: The `AgentToolServer` as it stands, its `headers` naming the new ones.

### Agent.removeToolServer

```typescript
removeToolServer(server: string | AgentToolServer): Promise<void>
```

Take an MCP server away (by `AgentToolServer` or `id`). Its tools stop from its next turn and the headers
given it go; its sign-in stays connected.

Parameters:

- `server` (`string | AgentToolServer`, required)

### Agent.rehearseTrigger

```typescript
rehearseTrigger(
  trigger: AgentTrigger | string | TriggerDefinition,
  options?: { sample?: unknown },
): Promise<Operation<Rehearsal>>
```

A test run of the turn a trigger would start now, without a real delivery. The agent reads what `sample` would
hand it (a webhook's body; an app event's or a NoClick event's data; a queue message's body; an email's
`{from, subject, text}`; a channel post's text or `{text, from}`), else a sample of its own (a schedule's or a
recurring wake-up's run; an app event's values placeholders in the shape it has reached your account in, no data
until one has; a NoClick event's from the event catalog), under the trigger's `message`, its tool calls answered
by a simulated world as in `rehearse`. A call and an approval can't be tested. `trigger` is an `AgentTrigger`,
its id, or the definition you added. `wait()` resolves to the `Rehearsal`.

Parameters:

- `trigger` (`AgentTrigger | string | TriggerDefinition`, required)
- `options.sample` (`unknown`)

Returns: The run's operation (kind `agent.rehearse`); `.wait()` gives the `Rehearsal`.

Types:

```typescript
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;
```

### Agent.inboxes

```typescript
inboxes(): Promise<Inbox[]>
```

The inboxes whose mail wakes it (created or updated with it as their `agent`).

Returns: Every such inbox, newest first, each with its `address`.

### Agent.pause

```typescript
pause(): Promise<this>
```

Stop every trigger from waking it: scheduled runs are skipped (not made up), webhook calls get a 409
their sender can retry, and app events, mail and calls meanwhile don't wake it. Messages your code sends
still run, as do calls under way.

Returns: This agent, with `paused` true.

### Agent.resume

```typescript
resume(): Promise<this>
```

Let its triggers wake it again, including one that stopped after failing; a schedule picks up at its next run.

Returns: This agent, with `paused` false.

### Agent.workspace

```typescript
workspace(
  conversation?: string,
  options?: { user?: UserOption },
): AgentWorkspace
```

The files it works on: its one `/workspace` (a `conversation` is accepted and ignored). Sends nothing yet.

Parameters:

- `conversation` (`string`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Its workspace, whose `files`, `read`, `write` and `url` reach its files.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.sandbox

```typescript
sandbox(conversation?: string, options?: { user?: UserOption }): AgentSandbox
```

The machine it works on, one whoever it answers. An `AgentSandbox`: what it is and costs, its files, and your own
commands on it beside its work. Without a `conversation` it's read through its session. Sends nothing yet.

    const machine = coder.sandbox();
    const { status, cpu, memoryMb, spentUsdToday } = await machine.get();

Parameters:

- `conversation` (`string`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Its sandbox, whose `get`, `files`, `read` and `exec` reach it.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.share

```typescript
share(): Promise<ShareLink>
```

Turn on its public chat page, or read it if it's on. Anyone with the link can talk to the agent,
no sign-in, each visitor in conversations of their own. Visitors' turns bill to you.

Returns: The link: its `url`, and `disable()` and `rotate()` to turn it off or change it.

### Agent.shareLink

```typescript
shareLink(): Promise<ShareLink | null>
```

Its chat page as it is, without turning it on (`share()` does that); null if it was never shared.

Returns: The link, `enabled` or not, or `None` if the agent has never been shared.

### Agent.stream

```typescript
async *stream(
  text: string,
  options?: {
    conversation?: string | null;
    files?: (Attachment | string)[];
    user?: UserOption;
    signal?: AbortSignal;
  },
): AsyncGenerator<AgentEvent>
```

Send `text` (and any `files`) and watch the turn: the reply as it's written, each tool call and result,
file, approval and long action, then `done` with the whole `AgentReply`. The same turn as
`message`, billed the same; a failed turn throws its error.

Parameters:

- `text` (`string`, required)
- `options.conversation` (`string | null`)
- `options.files` (`(Attachment | string)[]`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `options.signal` (`AbortSignal`)

Returns: `AgentEvent` values in order, ending with one whose `type` is `done` and whose `reply` is the
`AgentReply`. A turn that fails raises its error instead.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.watch

```typescript
async *watch(
  conversation: string,
  options?: { user?: UserOption; signal?: AbortSignal; replay?: boolean },
): AsyncGenerator<AgentEvent>
```

Follow one conversation live, whoever moves it. Turns a trigger, an answered `ask` or an
approved held call started, messages sent from another client or session, and a person's
replies after a hand-off. Yields `message` (a whole message, with its `role`, `files` and, a reply, its `toolCalls`), `text`,
`tool_call` (`held` names the approval when policy holds it), `tool_result`, `file`, `approval`
and `operation` (from its `"noclick"` tools) and `status` events; a coding harness's turn adds `output` and
`diff` (`AgentEvent`). Your own turns show up too; tell them apart by `operationId`. It runs until you stop
reading or abort `signal`. `replay` starts with the moments of the last hour that are still kept, so a turn
joined halfway is seen from its start.

Parameters:

- `conversation` (`string`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `options.replay` (`boolean`)
- `options.signal` (`AbortSignal`)

Returns: `AgentEvent` values as they happen: `message` (a whole message, with its `role`:
`user`, `assistant` or `person`, and its `files`), `text` as a reply is written,
`tool_call` (`held` names the approval when policy holds it), `tool_result`, `file`,
`approval` and `operation` (from its `"noclick"` tools), and `status` when the
conversation starts waiting on a person, is handed off or becomes `active`. A coding
harness's turn adds `output` and `diff` (`AgentEvent`).

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Agent.rehearse

```typescript
rehearse(
  message: string,
  options?: { scenario?: string; user?: UserOption },
): Promise<Operation<Rehearsal>>
```

A test run: a real turn where a simulated world answers every tool call, so nothing is sent or touched
and only its model connection need be connected. `scenario` sets that world;
without one, an ordinary busy day. Billed like a turn, against its budget; up to 10 per account queued or
running at once (`QuotaExceeded` past that). `wait()` resolves to the `Rehearsal`.

Parameters:

- `message` (`string`, required)
- `options.scenario` (`string`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The run's operation (kind `agent.rehearse`); `.wait()` gives the `Rehearsal`: the `reply`, and
the `tool_calls` it made with what the world answered.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

## AgentConversation

```typescript
class AgentConversation
```

One conversation with an agent, as a chat reads and changes it: `agent.conversation(name)`.

    const chat = coder.conversation("main");
    const { model, effort, efforts } = await chat.settings();
    const fork = await chat.fork({ message: "4" });

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` | The conversation's key. |

### AgentConversation.settings

```typescript
settings(): Promise<ConversationSettings>
```

What its next turn runs on.
Its `model`, `effort`, `speed` and `modelConnection` are the agent's (every conversation runs on them); `efforts`
and `speeds` are what its harness takes on that model, `accounts` what can pay for it.

Returns: A `ConversationSettings`.

### AgentConversation.update

```typescript
update(changes: ConversationChanges): Promise<ConversationSettings>
```

Change it from its next message: `permissionMode`, `title` (a rename) and `archived`. `model`, `effort`, `speed`
and `modelConnection` change the agent itself, for every conversation, as `Agent.update` does (`null` clears
`effort`, `speed` or `modelConnection`). Its harness stays the agent's.

Parameters:

- `changes` (`ConversationChanges`, required)

Returns: Its `ConversationSettings` after the change.

Types:

```typescript
/**
 * What `conversation(name).update` changes: `permissionMode`, `title` and `archived` the conversation's; `model`,
 * `effort`, `speed` and `modelConnection` the agent's, for every conversation (`null` clears all but `model`).
 */
interface ConversationChanges {
  model?: string | null;
  effort?: string | null;
  speed?: AgentSpeed | null;
  modelConnection?: string | null;
  permissionMode?: PermissionMode;
  title?: string;
  archived?: boolean;
}

/** How fast a conversation's model runs: `fast` where its harness has a fast mode (`speeds`). */
type AgentSpeed = "standard" | "fast";

/** When a conversation's coding harness asks a person before acting (`full-access`, the default, asks nothing). */
type PermissionMode = "approval-required" | "auto-accept-edits" | "auto" | "full-access";
```

### AgentConversation.fork

```typescript
fork(options?: { message?: string; title?: string }): Promise<Conversation>
```

Copy it into a new conversation, up to and with a message's turn.
`message` is a `Message.id` (the whole thread when omitted); the fork keeps its permission mode. Its agent reads
the copy in its own history (`agentReads` `native`), or, where it can't, as context its first turn carries.

Parameters:

- `options.message` (`string`)
- `options.title` (`string`)

Returns: The new `Conversation`, with `forked_from`.

### AgentConversation.resume

```typescript
resume(): Promise<Conversation>
```

Make it the agent's session again, like `claude --resume`: everyone talking to the agent shares it from now on,
and a message without a `conversation` goes to it. The agent's files stay as they are. Throws `Conflict` while
the agent is working on a turn, and `NotFound` for a conversation the agent never had.

    const [earlier] = (await coder.conversations({ limit: 20 })).filter((c) => !c.active);
    await coder.conversation(earlier.conversation).resume();

Returns: Its `Conversation`, `active`.

### AgentConversation.revert

```typescript
revert(
  message: string,
  options?: { files?: boolean },
): Promise<ConversationRevert>
```

Go back to before a message you sent.
It and everything after it leave the thread and what the agent reads; `files: true` also puts the files its
edits since changed back as they were, before its next turn. Resolves to what was reverted (its `text`, for the
composer). Throws `Conflict` while a turn runs or the agent waits on an answer there.

Parameters:

- `message` (`string`, required)
- `options.files` (`boolean`)

Returns: A `ConversationRevert`, whose `text` is the message's.

### AgentConversation.context

```typescript
context(): Promise<ConversationContext>
```

How full the model's context was at its last turn (a chat's `/context`).

Returns: A `ConversationContext`.

### AgentConversation.usage

```typescript
usage(): Promise<ConversationUsage>
```

What it cost and what pays for its model (a chat's `/usage`).

Returns: A `ConversationUsage`.

### AgentConversation.toolServers

```typescript
toolServers(): Promise<ToolServers>
```

The MCP servers its coding harness reaches its tools on: connected, connecting or failed, with their tools.

Returns: A `ToolServers`.

### AgentConversation.reconnectToolServer

```typescript
reconnectToolServer(name: string): Promise<ToolServers>
```

Do one tool server's handshake again, where its harness can (`toolServers().reconnect`): Claude Code and OpenCode
reconnect that server, Codex reloads all of them. Hermes Agent and OpenClaw connect theirs at every turn, so this
raises `noclick.Conflict` saying the next message reconnects them.

Parameters:

- `name` (`string`, required)

Returns: A `ToolServers`, as it stands after the reconnect started.

### AgentConversation.messageSubagent

```typescript
messageSubagent(callId: string, text: string): Promise<Operation<AgentReply>>
```

Tell one of its coding harness's own subagents something while it works: the `Task` (Claude Code) or `task`
(OpenCode) call `callId` in the conversation's running turn, as its events name it. No harness takes a message
into its subagent, so it joins the main session's turn, which reads whom it's for and passes it on; the thread
keeps it as yours (`Message.subagent`). Throws `Conflict` once that turn or the subagent has ended. A NoClick agent
it started takes messages itself (`Agent.send`).

    await coder.conversation("main").messageSubagent("toolu_01", "Also check the admin routes.");

Parameters:

- `callId` (`string`, required)
- `text` (`string`, required)

Returns: Its `agent.ask` `Operation`, answered with the reply of the turn it joined.

### AgentConversation.runCommand

```typescript
runCommand(
  name: string,
  args?,
  options?: { delivery?: MessageDelivery },
): Promise<CommandResult | Operation<AgentReply>>
```

Run a command typed in a chat.
One NoClick has a control for (`/model opus`, `/effort high`, `/fast`, `/new`, `/context`, `/usage`,
`/btw <question>`) resolves to that control's `CommandResult`; any other runs as the harness's own command, its
turn's `Operation`.

Parameters:

- `name` (`string`, required)
- `args` (`string`, default `""`)
- `options.delivery` (`MessageDelivery`)

Returns: A `CommandResult`, or the command's `Operation`.

Types:

```typescript
/**
 * How a message sent while the agent works on a turn (it takes one at a time) is delivered: `steer` puts it into that
 * turn when it's in the same conversation (its operation answers with that turn's reply; else it's an ordinary
 * message), `queue` (or omitted) runs it as the agent's next turn.
 */
type MessageDelivery = "steer" | "queue";
```

## AgentStateRow

```typescript
interface AgentStateRow
```

One agent as a list shows it: its `state` (`needs_you`: something waits on a person, its harness's request
included; `working`: a turn runs; `with_you`: a person has one of its conversations; `waking`: a turn of its own
is about to start; `failed`: its last turn failed; `idle`), the `conversation` that state is in, the tool call it
runs `now`, what `waiting` counts (asks, held calls and its harness's requests: `total` is the badge), and when.

| Attribute | Type | Description |
| --- | --- | --- |
| `agentId` | `string` |  |
| `name` | `string` |  |
| `harness` | `HarnessName` |  |
| `state` | `AgentState` |  |
| `conversation` | `string | null` |  |
| `now` | `AgentNow | null` |  |
| `waiting` | `{ asks: number; heldCalls: number; requests: number; total: number }` |  |
| `turnStartedAt` | `Date | null` |  |
| `lastActiveAt` | `Date | null` |  |
| `failed` | `{ message: string; at: Date | null } | null` |  |
| `waking` | `{ at: Date | null; why: string } | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** An agent's state for a list of agents, the first that holds, in this order. */
type AgentState = "needs_you" | "working" | "with_you" | "waking" | "failed" | "idle";

/** The tool call an agent runs now: a short `line` such as `bash: pytest -x` or `edit app/retries.py`. */
interface AgentNow {
  tool: string;
  kind: "command" | "edit" | "read" | "search" | "tool";
  line: string;
  since: Date | null;
  /** Whether that step still runs (false once it ended and the turn goes on). */
  running: boolean;
  /** That step in words, in its tense (`Running the plan usage tests`), as a coding harness's step says it. */
  label: string | null;
  category: StepCategory | null;
  /** What the turn did so far (`Read 5 files, searched 5 times`). */
  summary: string | null;
}

/** What a coding harness's step did, as NoClick judged it from what it runs. */
type StepCategory = "read" | "search" | "list" | "edit" | "test" | "install" | "run" | "tool";

type JsonObject = { [key: string]: unknown };
```

## CommandResult

```typescript
interface CommandResult
```

What a command NoClick has a control for came to (`/model`, `/effort`, `/new`, `/context`, `/usage`…).

| Attribute | Type | Description |
| --- | --- | --- |
| `control` | `string` |  |
| `command` | `{ name: string; arguments: string }` |  |
| `result` | `JsonObject` | The control's answer: conversation settings, a new conversation, its context, its usage, or an operation. |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## ConversationContext

```typescript
interface ConversationContext
```

How full the model's context was at the conversation's last turn: `usedTokens` of `windowTokens` (`percent`), as
its coding harness reported them (`source` `harness`) or as NoClick's runtime sent its last call (`noclick`), and
where it folds the thread by itself (`autoCompactsAt`, a share of the window). Null figures before a first turn.

| Attribute | Type | Description |
| --- | --- | --- |
| `model` | `string | null` |  |
| `usedTokens` | `number | null` |  |
| `windowTokens` | `number | null` |  |
| `percent` | `number | null` |  |
| `autoCompactsAt` | `number | null` |  |
| `source` | `"harness" | "noclick" | null` |  |
| `asOf` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## ConversationRevert

```typescript
interface ConversationRevert
```

A revert: the message it went back to before (its `text`, to put back in the composer), how many turns left the
thread and what the agent reads, and the files: `restored` (their edits are undone before its next turn, in its
sandbox, where they are), `kept` (with `files: false`), `notRestored` (and why: an edit too large to have been kept
whole) and `commandsNotUndone` (commands whose changes no diff records). `agentReads`: `native` when the agent reads
the thread as it is now in its own history, `context` when its next turn carries it as context.

| Attribute | Type | Description |
| --- | --- | --- |
| `conversation` | `string` |  |
| `message` | `string` |  |
| `text` | `string` |  |
| `droppedTurns` | `number` |  |
| `files` | `{ restored: string[]; kept: string[]; notRestored: { path: string; why: string }[]; commandsNotUndone: number }` |  |
| `filesApplied` | `"next_turn" | null` |  |
| `agentReads` | `"native" | "context"` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## AgentToolServer

```typescript
interface AgentToolServer
```

An MCP server an agent has as tools: a step of its automation (`id`, what `removeToolServer` takes), reached at its
`url` (on `host`) over `transport` (`http` or `sse`), letting its client in as `signIn` says (`none`, `key`: the
`headers` named, whose values are never read back, or `browser`: a person's sign-in, `signedIn` once one is set).
Its `status`: `connected`, `needs_sign_in` (nothing lets it in yet), `signed_out` (its sign-in was refused or
revoked), `failed` (its last run found no tools), `unchecked` (no run since it was last let in) or, read for a
conversation, `connecting` (its harness's handshake hasn't finished), with what's wrong in `problem`; the `tools` it
offered and when that was found (`checkedAt`); whether that conversation's harness can connect it again in place now
(`reconnectable`); and what draws it (`icon`: `{ integration }`, `{ mark: "noclick" }`, or null: draw its name's
first letter). Listed in the order they were added.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `name` | `string` |  |
| `url` | `string | null` |  |
| `transport` | `"http" | "sse"` |  |
| `signedIn` | `boolean` |  |
| `headers` | `string[]` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `agentId` | `string | null` |  |
| `host` | `string | null` |  |
| `signIn` | `"none" | "key" | "browser"` |  |
| `status` | `"connected" | "connecting" | "needs_sign_in" | "signed_out" | "failed" | "unchecked"` |  |
| `problem` | `ToolServerProblem | null` |  |
| `tools` | `ToolServerTool[]` |  |
| `icon` | `{ integration: string } | { mark: "noclick" } | null` |  |
| `checkedAt` | `Date | null` |  |
| `reconnectable` | `boolean` |  |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

### AgentToolServer.connectLink

```typescript
connectLink(options?: LinkOptions): Promise<ConnectLink<AgentToolServer>>
```

Mint a link where someone signs in to this server (`signIn` `browser`), the first time or again: NoClick's MCP
sign-in for it, which becomes the server's sign-in once it lands. `sendTo` also delivers it. A server that takes
a key rejects with `Conflict`: give it headers with `agent.updateToolServer`. `await link.wait()` resolves to
this server as it stands then.

Parameters:

- `options.redirectUrl` (`string`)
- `options.reason` (`string`)
- `options.sendTo` (`SendTo`): Also deliver the link: "user", "owner" (your account's owner), an email, or an object.

Returns: The link: its `url`, when it `expires_at`, and where it went when you set `send_to`. It's also the
operation that finishes once they've signed in: `link.wait()` returns this `AgentToolServer` as it
stands then.

Types:

```typescript
/** Where a connect link is delivered (by email only): the user, an email, or the wire dict. */
type SendTo = "user" | "owner" | true | string | JsonObject;

type JsonObject = { [key: string]: unknown };
```

## ConversationUsage

```typescript
interface ConversationUsage
```

What a conversation cost: `costUsd` (what its turns were charged), its model calls on your own key or plan
(`modelUsage`, null on NoClick's key), its `turns`, what pays for its model (`paysWith`) and, on a plan, the plan's
limits where its harness reported them.

| Attribute | Type | Description |
| --- | --- | --- |
| `costUsd` | `number` |  |
| `modelUsage` | `ModelUsage | null` |  |
| `turns` | `number` |  |
| `paysWith` | `"noclick" | "key" | "plan"` |  |
| `planLimits` | `PlanLimit[]` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
/** One limit of a provider's plan: how much of it is used and when it resets. */
interface PlanLimit {
  label: string;
  usedPercent: number | null;
  resetsAt: Date | null;
}

type JsonObject = { [key: string]: unknown };
```

## ToolServer

```typescript
interface ToolServer
```

One MCP server a conversation's coding harness reaches its tools on, as it stands.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `status` | `"connected" | "connecting" | "failed"` | `connected`, `connecting` (its handshake hasn't finished) or `failed`. |
| `toolCount` | `number | null` | How many tools it offers the model, where the harness says (null where it doesn't). |
| `error` | `string | null` | Why it failed, in the harness's or the server's words. |
| `tools` | `ToolServerTool[] | null` | Each tool it offers, where the harness lists them (Claude Code and Codex do; null where it doesn't). |

## ToolServerProblem

```typescript
interface ToolServerProblem
```

What's wrong with an agent's MCP server, as a connection's `disconnected` says it: `reason` (`needs_sign_in`,
`signed_out`, `refused`, `revoked` or `failed`), NoClick's one line (`message`), the server's own words where it
said any (`providerSaid`), since when (`since`, null for a server never signed in to) and what to do (`nextStep`).

| Attribute | Type | Description |
| --- | --- | --- |
| `reason` | `string` |  |
| `message` | `string` |  |
| `providerSaid` | `string | null` |  |
| `since` | `Date | null` |  |
| `nextStep` | `string | null` |  |

## ToolServers

```typescript
interface ToolServers
```

The tool servers of a conversation: read live from its running harness (`source: "live"`), else as its last turn
found them (`"last_turn"`), else none yet (`"none"`). `reconnect` says whether one server's handshake can be done
again in place (`scope: "server"`), only all of them at once (`"all"`), or not, and why not.

| Attribute | Type | Description |
| --- | --- | --- |
| `servers` | `ToolServer[]` |  |
| `source` | `"live" | "last_turn" | "none"` |  |
| `checkedAt` | `Date | null` |  |
| `reconnect` | `{ available: boolean; scope: "server" | "all" | null; why: string | null }` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## ToolServerTool

```typescript
interface ToolServerTool
```

A tool an MCP server offers: its `name` and `description`, as the server lists it.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `description` | `string | null` |  |

## AgentCommand

```typescript
interface AgentCommand
```

One command a conversation's harness offers.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `description` | `string` |  |
| `argumentHint` | `string` | What its arguments look like (`<instructions>`, `[env]`), empty when it names none. |
| `source` | `AgentCommandSource` |  |
| `aliases` | `string[]` | Other names it answers to. |

Types:

```typescript
/** Where a harness command comes from: the harness itself, your own (a project's or plugin's), a skill, an MCP prompt. */
type AgentCommandSource = "harness" | "custom" | "skill" | "mcp";
```

## AgentCommands

```typescript
interface AgentCommands
```

What a conversation's harness offers a person to run, read from the harness itself (Claude Code, Codex, OpenCode,
OpenClaw; Hermes Agent lists skills and runs no commands). Kept per agent and harness, so a stopped sandbox's last
list still answers: `asOf` says when it was read and `readFrom` whose sandbox read it (both null before its
sandbox ever started: send a message first).

| Attribute | Type | Description |
| --- | --- | --- |
| `harness` | `string` |  |
| `commands` | `AgentCommand[]` |  |
| `skills` | `AgentSkill[]` |  |
| `capabilities` | `Record<string, boolean>` | `commands`, `skills`, `compact`, `review`, `goal`, `init`, `steer`, `queue`. |
| `notSupported` | `Record<string, string>` | What NoClick can't run on this harness, and why. |
| `withheld` | `string[]` | Commands NoClick never runs from a chat, whatever the harness offers: those that change what NoClick sets up and guards for the agent (its MCP servers, permissions, credentials, model provider, process or settings files: Claude Code's `/config`, OpenClaw's owner commands). |
| `mapped` | `{ name: string; to: string }[]` | The harness's commands NoClick has a control of its own for, each with that control (`model`, `effort`, `new`, `usage`, `context`, `plan`, `delivery`, `ask`): Claude Code's `/model` is the model picker, its `/clear` a new session. A page offers the control in their place. |
| `asOf` | `Date | null` |  |
| `readFrom` | `"this_conversation" | "another_conversation" | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
/** One skill a conversation's harness has. */
interface AgentSkill {
  name: string;
  description: string;
}

type JsonObject = { [key: string]: unknown };
```

## AgentGrant

```typescript
interface AgentGrant
```

A connection the agent's user gave it at run time (it asked with its `request_connection` tool,
within `canRequest`). `status` is `requested` until the user connects, then `active`;
`operations` null means every operation.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `connection` | `string` |  |
| `integration` | `string` |  |
| `operations` | `string[] | null` |  |
| `status` | `"requested" | "active"` |  |
| `reason` | `string | null` |  |
| `conversation` | `string | null` |  |
| `createdAt` | `Date | null` |  |
| `grantedAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## ConversationSettings

```typescript
interface ConversationSettings
```

A conversation's settings: what its next turn runs on (the agent's `model`, `effort`, `speed` and `modelConnection`,
which every conversation runs on), the efforts and speeds its harness takes on that model, what can pay for it
(`accounts`), its permission mode (the strictest the harness enforces in `effectivePermissionMode`), its `title`,
whether it's `archived`, and the conversation it was forked from.

| Attribute | Type | Description |
| --- | --- | --- |
| `permissionMode` | `PermissionMode` |  |
| `effectivePermissionMode` | `PermissionMode` |  |
| `permissionModes` | `PermissionMode[]` |  |
| `notSupported` | `Record<string, string>` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `conversation` | `string` |  |
| `title` | `string | null` |  |
| `archived` | `boolean` |  |
| `harness` | `HarnessName | null` |  |
| `model` | `string | null` |  |
| `effort` | `string | null` | null: the model's own default (`defaultEffort`, when the harness says it). |
| `efforts` | `string[]` | The efforts its harness takes on its model, weakest first, in the harness's own words ([]: none). |
| `defaultEffort` | `string | null` |  |
| `speed` | `AgentSpeed` |  |
| `speeds` | `AgentSpeed[]` | `["standard", "fast"]` where its harness has a fast mode on its model; [] where it has none. |
| `modelConnection` | `string | null` |  |
| `accounts` | `ModelAccount[]` | What can pay for it: each `{name, integration, kind (key, plan or noclick), connected, usable, why}`. |
| `overridden` | `string[]` | What the conversation sets itself: its `permission_mode`. |
| `forkedFrom` | `ForkedFrom | null` | `{conversation, message, through}`: what it was forked from (`through`: its own last copied message). |

Types:

```typescript
/** When a conversation's coding harness asks a person before acting (`full-access`, the default, asks nothing). */
type PermissionMode = "approval-required" | "auto-accept-edits" | "auto" | "full-access";

type JsonObject = { [key: string]: unknown };

/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** How fast a conversation's model runs: `fast` where its harness has a fast mode (`speeds`). */
type AgentSpeed = "standard" | "fast";

/** What a conversation can run its model on: one of its scope's model connections, or NoClick's own key. */
interface ModelAccount {
  /** The connection's name to pass as `modelConnection` (`"noclick"` for NoClick's key; null on `sdk`, whose NoClick router takes no connection). */
  name: string | null;
  integration: string | null;
  /** `key`, a provider's `plan` (a Claude or ChatGPT sign-in), or `noclick`: NoClick's own key, at the model's cost. */
  kind: "key" | "plan" | "noclick";
  connected: boolean;
  /** Whether it runs the conversation's harness on its model now; `why` says why not. */
  usable: boolean;
  why: string | null;
}

/** The conversation a fork came from, the message it was forked at, and its own last copied message (`through`). */
interface ForkedFrom {
  conversation: string;
  message: string;
  through: string | null;
}
```

## HarnessRequest

```typescript
interface HarnessRequest
```

What a coding harness asks a person mid-turn: an `approval` (`action`: `command`, `edit`, `plan` (leaving Claude
Code's plan mode, its `plan` text), `read`, `fetch` or `tool`; `title` in a line, `detail` the command or the
files) or a `question` (`questions`, each `{id, header, question, options, multi_select}`). `status` is `pending`
until it's `answered`, `expired` (nobody answered in time: declined) or `canceled` (its turn stopped).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `kind` | `"approval" | "question"` |  |
| `status` | `"pending" | "answered" | "expired" | "canceled"` |  |
| `action` | `string | null` |  |
| `title` | `string | null` |  |
| `detail` | `string | null` |  |
| `plan` | `string | null` |  |
| `questions` | `JsonObject[]` |  |
| `options` | `{ optionId: string; name: string; kind: string }[]` |  |
| `answer` | `JsonObject | null` |  |
| `operationId` | `string | null` |  |
| `createdAt` | `Date | null` |  |
| `expiresAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `decision` | `string | null` | What it was answered with (`allow_once`, `reject_once`, …) and when; null until it's answered. |
| `answeredAt` | `Date | null` |  |
| `canceledReason` | `string | null` | Why it was closed unanswered: its turn ended first (failed, stopped, timed out). |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## AgentReply

```typescript
interface AgentReply
```

The agent's answer to one message.

| Attribute | Type | Description |
| --- | --- | --- |
| `text` | `string` |  |
| `conversation` | `string | null` | Pass back as `conversation` to continue the same thread. |
| `toolCalls` | `JsonObject[]` | The turn's tool calls, each `{tool, arguments, result, is_error, created_at}` as `history()` shows a reply's (a failed call's `result` is its error); a coding harness's own steps add `source: "harness"` and the rest of a `AgentStep` (its `id`, `kind`, `command`, `path`, `output`, `exit_code`, `duration_ms`, `diffs`), in the order they happened. |
| `operationId` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `modelUsage` | `ModelUsage | null` | The turn's model calls on your own key or plan (null on NoClick's key, whose cost is its `cost_usd`). |
| `endedBy` | `TurnLimitName | null` | The limit that ended the turn before it finished (its `turnLimits`), its text then saying where the work stands; null when the agent answered. |
| `summary` | `TurnSummary | null` | What a coding harness's turn did (null for a turn with no harness steps). |
| `groups` | `StepGroup[]` | Its harness steps' folds, in order. |
| `steps` | `AgentStep[]` | `toolCalls` as `AgentStep`s. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };

/** What can end a turn before the agent answers: its steps, its spend or its minutes (`turnLimits`). */
type TurnLimitName = "steps" | "spend" | "time";
```

## AgentStep

```typescript
interface AgentStep
```

One step of a turn as its reply keeps it (`Message.steps`, `AgentReply.steps`). A coding harness's own step
(`source` `harness`) has the fields its live events showed as it ran, under its `callId`: its `tool_call` (`kind`,
`tool`, `arguments`, `command`, `path`, `query`), its command's `output` (the last 4,096 characters; what came
before reads `[… N characters not shown …]`), its `tool_result` (`exitCode`, `durationMs`, `isError`, `result`)
and each `diff`. A turn keeps at most 200 such steps and 256,000 characters of their output and diffs, the
newest steps' first. NoClick's own tool calls are `kind` `tool`, with no `callId`.

What a harness's step did, in words, judged once by NoClick as it ran: its `category`, its `label` and where that
came from (`labelSource`: the harness's own `description`, Codex's `actions`, or `derived` from the command), the
command as shown (`displayCommand`: no `cd` into where it runs, heredocs shortened), a read's `lines`, how many lines
it printed (`outputLines`), a test run's `tests`, a count it reported (`progress`), an edit's `diffStat`, whether it
`failed` (a search that found nothing didn't) and the `group` it folds into (`StepGroup.id`).

| Attribute | Type | Description |
| --- | --- | --- |
| `kind` | `AgentStepKind` |  |
| `tool` | `string` |  |
| `callId` | `string | null` |  |
| `source` | `"harness" | (string & {}) | null` |  |
| `arguments` | `JsonObject` |  |
| `command` | `string | null` |  |
| `path` | `string | null` |  |
| `query` | `string | null` |  |
| `output` | `string | null` |  |
| `exitCode` | `number | null` |  |
| `durationMs` | `number | null` |  |
| `isError` | `boolean` |  |
| `result` | `unknown` |  |
| `diffs` | `AgentStepDiff[]` |  |
| `createdAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `category` | `StepCategory | null` |  |
| `label` | `StepLabel | null` |  |
| `labelSource` | `"description" | "actions" | "derived" | null` |  |
| `displayCommand` | `string | null` |  |
| `lines` | `{ from: number | null; to: number | null } | null` |  |
| `outputLines` | `number | null` |  |
| `tests` | `StepTests | null` |  |
| `progress` | `StepProgress | null` |  |
| `diffStat` | `DiffStat | null` |  |
| `failed` | `boolean | null` |  |
| `group` | `string | null` |  |
| `paths` | `string[]` | The files a read or an edit named, as it named them. |

Types:

```typescript
/** A step's kind: a coding harness's shell `command`, file `edit`, `read` or `search`, or any other `tool` (NoClick's own among them). */
type AgentStepKind = "command" | "edit" | "read" | "search" | "tool";

type JsonObject = { [key: string]: unknown };

/** What a coding harness's step did, as NoClick judged it from what it runs. */
type StepCategory = "read" | "search" | "list" | "edit" | "test" | "install" | "run" | "tool";
```

## AgentStepDiff

```typescript
interface AgentStepDiff
```

One file a step changed: a unified diff, or a new file's whole content (`change` `add`), at most 16,384 characters.

| Attribute | Type | Description |
| --- | --- | --- |
| `path` | `string` |  |
| `change` | `"add" | "update" | "delete" | (string & {}) | null` |  |
| `diff` | `string` |  |

## ChangedFile

```typescript
interface ChangedFile
```

A file a turn changed: the lines its edits added and removed, and `how` where not by an edit tool (`sed`, `script`).

| Attribute | Type | Description |
| --- | --- | --- |
| `path` | `string` |  |
| `added` | `number` |  |
| `removed` | `number` |  |
| `how` | `string[]` |  |

## DiffStat

```typescript
interface DiffStat
```

The lines an edit's diffs added and removed.

| Attribute | Type | Description |
| --- | --- | --- |
| `added` | `number` |  |
| `removed` | `number` |  |

## StepGroup

```typescript
interface StepGroup
```

Reads, searches and listings a coding harness made in a row, folded into one line as Claude Code folds them (never
a failed step): `label` (`Read 6 files, searched for 3 patterns`; `Reading …` while one runs), its `counts`
(`read`: files, `search`, `list`), its steps (`stepIds`) and `parent`, the subagent call whose steps they are. A
group no longer standing (a step left it) has no `stepIds`.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `label` | `string | null` |  |
| `counts` | `Record<string, number>` |  |
| `stepIds` | `string[]` |  |
| `running` | `boolean` |  |
| `parent` | `string | null` |  |

## StepLabel

```typescript
interface StepLabel
```

What a coding harness's step did, in words, in its tense: running as it runs (`Reading attachments.py`), done once
it ended (`Read attachments.py lines 55-110`). `text` is the whole line; `verb`, `object` and `detail` its parts.

| Attribute | Type | Description |
| --- | --- | --- |
| `text` | `string` |  |
| `verb` | `string | null` |  |
| `object` | `string | null` |  |
| `detail` | `string | null` |  |

## StepProgress

```typescript
interface StepProgress
```

How far a step is where it reported a count: `done` of `total`. A step that names no total has none.

| Attribute | Type | Description |
| --- | --- | --- |
| `done` | `number` |  |
| `total` | `number` |  |

## StepTests

```typescript
interface StepTests
```

A test run's counts, read from what it printed (pytest, vitest, jest, node's runner, cargo): as it streams (`done`
false; `total` once it's known) and at its end, and in words (`label`: `161 passed`, `2 of 43 failed`, `64 of 161`).

| Attribute | Type | Description |
| --- | --- | --- |
| `passed` | `number` |  |
| `failed` | `number` |  |
| `skipped` | `number` |  |
| `total` | `number | null` |  |
| `done` | `boolean` |  |
| `label` | `string` |  |

## TurnChanges

```typescript
interface TurnChanges
```

The files a turn changed (`label`: `Changed 5 files`), and how many only by a script or a command (`byScript`).

| Attribute | Type | Description |
| --- | --- | --- |
| `label` | `string` |  |
| `files` | `ChangedFile[]` |  |
| `added` | `number` |  |
| `removed` | `number` |  |
| `byScript` | `number` |  |

## TurnSummary

```typescript
interface TurnSummary
```

What a coding harness's turn did: `label` (`Read 9 files, searched 7 times`), its steps' `counts` by category, how
many `failed`, what it `changed` and its last test run's counts (`tests`).

| Attribute | Type | Description |
| --- | --- | --- |
| `label` | `string | null` |  |
| `counts` | `Record<string, number>` |  |
| `failed` | `number` |  |
| `changed` | `TurnChanges | null` |  |
| `tests` | `StepTests | null` |  |

## Conversation

```typescript
interface Conversation
```

One thread with an agent (a user's, or the account's own).

| Attribute | Type | Description |
| --- | --- | --- |
| `conversation` | `string` | Pass as `conversation` to continue it, or to `history()`. |
| `userId` | `string | null` |  |
| `title` | `string | null` |  |
| `preview` | `string | null` |  |
| `turns` | `number | null` |  |
| `costUsd` | `number | null` |  |
| `lastActivity` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `status` | `ConversationStatus | null` | `active`, `awaiting_human` (a turn waits on a person: its question, a held call, a sign-in) or `handed_off`. |
| `handedOffTo` | `string | null` | Who a `handed_off` conversation is with: the person's email or phone. |
| `modelUsage` | `ModelUsage | null` | Its model calls on your own key or plan, all turns together (null on NoClick's key). |
| `lastMessage` | `LastMessage | null` | Its newest message (null before any). |
| `people` | `MessageAuthor[]` | Who is in it: the people who wrote in it, the thread's own person first. |
| `archived` | `boolean` |  |
| `forkedFrom` | `ForkedFrom | null` | The conversation it was forked from, and at which message. |
| `agentReads` | `"native" | "context" | null` | A fork's: `native` when the agent reads the copied thread in its own history, `context` when carried as context. |
| `active` | `boolean` | Whether it's the agent's session now, the one conversation everyone talking to it shares; the others can be resumed. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };

/** `active`; `awaiting_human` while a turn waits on a person; `handed_off` while a person has it. */
type ConversationStatus = "active" | "awaiting_human" | "handed_off";

/** A conversation's newest message, as a list shows it. */
interface LastMessage {
  role: string;
  text: string;
  createdAt: Date | null;
}

/** Who sent a `user` message to an agent: the account, one of your users, another agent, or an app's code. */
interface MessageAuthor {
  type: "account" | "user" | "agent" | "app";
  id: string | null;
  name: string | null;
}

/** The conversation a fork came from, the message it was forked at, and its own last copied message (`through`). */
interface ForkedFrom {
  conversation: string;
  message: string;
  through: string | null;
}
```

## Message

```typescript
interface Message
```

One message of a conversation: its `role` is `user`, `assistant`, `person` (someone it was handed off to) or
`note` (a line added with `agent.note`, with its `data`).

| Attribute | Type | Description |
| --- | --- | --- |
| `role` | `string` |  |
| `text` | `string` |  |
| `createdAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `files` | `Attachment[]` | The files it carried (a `user` message's, sent with `files`). |
| `toolCalls` | `JsonObject[]` | A reply's tool calls: each `{tool, arguments, result, is_error, created_at}`, as its turn's `tool_call` and `tool_result` events showed it (`arguments` cut short are `{_truncated: true}`); a coding harness's reply has its own steps among them, in the order they happened (`AgentStep`). |
| `via` | `MessageVia | null` | How a `user` message arrived when not through the API (null otherwise). |
| `data` | `JsonObject | null` | A `note`'s data, as `agent.note` added it. |
| `trigger` | `MessageTrigger | null` | What started the turn of a `user` message no person sent (null for one someone sent). |
| `reasoning` | `ReasoningLine[]` | A reply's reasoning, as its turn's `reasoning` events showed it. |
| `operationId` | `string | null` | The turn it belongs to (an `agent.message` operation's id; null for a message no turn sent, like a person's). |
| `command` | `AgentCommandInput | null` | The harness command a `user` message ran in place of text (null for a message). |
| `id` | `string | null` | Its place in the thread, which stays (a revert marks, never removes): pass it to `forkConversation` or `revertConversation`. |
| `author` | `MessageAuthor | null` | Who sent a `user` message: `user` (one of your users, or you in a workspace you joined: `id` is that user's id), `account` (the account itself, its owner or a key), `agent` (another agent's turn) or `app` (an app's code); null for one no person sent (a trigger's, a wake-up's) or sent before NoClick kept it. |
| `notification` | `boolean` | An agent's message to its owner from another of its conversations (a `human__notify` that joined this thread). |
| `space` | `MessageSpace | null` | A `notification` passing on a space's news: the space it's from (null otherwise). |
| `subagent` | `MessageSubagent | null` | A `user` message written for one of its coding harness's subagents: which one (null otherwise). |
| `chat` | `string | null` | The chat a message of the agent's session came from, where it isn't the session's own: the `conversation` it was sent to (a WhatsApp chat's id, `channel:<id>`, `owner`, a shared page's visitor), which its reply goes back to (null otherwise). |
| `summary` | `TurnSummary | null` | What a coding harness's reply's turn did (null where it says nothing). |
| `groups` | `StepGroup[]` | Its harness steps' folds, in order. |
| `steps` | `AgentStep[]` | `toolCalls` as `AgentStep`s. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };

/**
 * How a `user` message reached the agent when not through the API: a text to NoClick's number on `whatsapp` or
 * `imessage`, said on a phone `call`, or `email` to one of its inboxes.
 */
type MessageVia = "whatsapp" | "imessage" | "call" | "email";

/**
 * What started the turn of a `user` message no person sent: a trigger (`kind` is its kind: `webhook`, `event`,
 * `cron`, `platform` or `queue`), a wake-up (`wakeup`), or NoClick carrying on once app testing changed
 * (`app_testing`), with its `id` and `title`; a NoClick event's (`platform`) has its `event` (`{id, type, data}`).
 */
interface MessageTrigger {
  kind: string;
  id: string;
  title?: string | null;
  event?: { id: string; type: string; data: JsonObject } | null;
}

/** One short line of what a turn's model was thinking (the title of a section of its reasoning). */
interface ReasoningLine {
  text: string;
  createdAt: Date | null;
}

/**
 * One of a coding harness's own commands to run instead of a message (`compact`, `review`, a custom command, a
 * skill), as `agent.commands(conversation)` lists them: `name` without the slash, `arguments` what follows it.
 */
interface AgentCommandInput {
  name: string;
  arguments?: string;
}

/** Who sent a `user` message to an agent: the account, one of your users, another agent, or an app's code. */
interface MessageAuthor {
  type: "account" | "user" | "agent" | "app";
  id: string | null;
  name: string | null;
}

/**
 * The space a notification passes news on from: a space's NoClick alerted the person, or answered a question their
 * NoClick asked it. `label` is what that NoClick goes by outside its space ("NoClick · Launch").
 */
interface MessageSpace {
  workspaceId: string;
  name: string;
  label: string;
}

/** The coding harness's subagent a `user` message was written for (`AgentConversation.messageSubagent`): the harness's
 *  call that runs it (`id`, its step's id) and what it was asked (`title`). */
interface MessageSubagent {
  id: string;
  title: string;
}
```

## HarnessInfo

```typescript
interface HarnessInfo
```

What can run an agent: one of `Agent.harnesses()`. `sdk` is NoClick's own agent loop; the others
are coding agents that run in a sandbox of their own, with a shell and files, and think with the
key or plan of a `modelConnection`. `models()` searches the models it offers.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `HarnessName` | What `harness` takes. |
| `label` | `string | null` |  |
| `version` | `string | null` | The version NoClick runs (null for `sdk`). |
| `defaultModel` | `string` | The model an agent on it gets when you give none. |
| `customModels` | `boolean` | Whether `model` also takes models `models()` doesn't offer. |
| `modelConnection` | `"required" | "optional"` | `required` for every CLI harness, `optional` for `sdk`. |
| `integrations` | `string[]` | The model providers (`kind: "model"` integrations) whose connection it can think with. |
| `streaming` | `"tokens" | "final"` | `tokens` when the reply streams as it's written, `final` when it arrives whole. |
| `shell` | `"built_in" | "code_capability"` | `built_in` when it has its own shell and file tools, `code_capability` when its shell is the `code` tool. |
| `notes` | `string[]` | What to know before choosing it (a model that needs a particular key, say). |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `efforts` | `string[]` | The reasoning efforts it takes on its default model, weakest first ([]: none); a conversation's settings list its model's. |
| `defaultEffort` | `string | null` | The effort it runs at when none is set (null: the model's own). |
| `speeds` | `AgentSpeed[]` | `["standard", "fast"]` where it has a fast mode on its default model, else []. |
| `noclickKey` | `{ runs: boolean; models: string[]; why: string | null }` | Whether a coding agent on it may run on NoClick's own key (`modelConnection: "noclick"`, at the model's cost), the models to suggest there, or why not. |
| `permissionModes` | `PermissionMode[]` | The permission modes it enforces ([]: none, as on `sdk`), and why it runs the others as another. |
| `notSupported` | `Record<string, string>` |  |

Types:

```typescript
/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

type JsonObject = { [key: string]: unknown };

/** How fast a conversation's model runs: `fast` where its harness has a fast mode (`speeds`). */
type AgentSpeed = "standard" | "fast";

/** When a conversation's coding harness asks a person before acting (`full-access`, the default, asks nothing). */
type PermissionMode = "approval-required" | "auto-accept-edits" | "auto" | "full-access";
```

### HarnessInfo.models

```typescript
models(options?: { search?: string; limit?: number }): Promise<HarnessModel[]>
```

The models it offers, its default first: the first `limit` (50; at most 200), or those whose id
or label contains `search` (case-insensitive). A search after a few quiet minutes reads the
providers' lists afresh, so it can take seconds.

    const models = await opencode.models({ search: "claude", limit: 10 });

Parameters:

- `options.limit` (`number`): Return at most this many.
- `options.search` (`string`)

Returns: Each model's `id` (what `model=` takes) and `label`. A harness whose
`custom_models` is True also runs ids it doesn't list.

## HarnessModel

```typescript
interface HarnessModel
```

A model a harness offers, by the `id` its `model` takes. One model reached several ways is a row per way, each with
its `route` and the same `canonical`, the model as its maker names it (`anthropic/claude-sonnet-5-5`); a model
reached one way is its own `canonical`.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `label` | `string | null` |  |
| `canonical` | `string` |  |
| `route` | `HarnessModelRoute` |  |
| `noclickKey` | `HarnessModelPrice | null` | What it costs on NoClick's own key; null where the key doesn't run it on this harness, or its price can't be read now. |

Types:

```typescript
/** How a model id reaches its model: its maker's own API, OpenRouter, or OpenCode Zen (`opencode`, `opencode-go`). */
type HarnessModelRoute = "maker" | "openrouter" | "opencode" | "opencode-go";

/**
 * A model's price on NoClick's own key: its output per million tokens (null for a router priced as the model it
 * picks for each call), and `needsFundsUsd`, the funds your account must have added (not its plan's included usage)
 * to put an agent on it there: set for a model over $2 a million output tokens, else null. An agent already on one
 * keeps running, and your own key or plan is never held to it.
 */
interface HarnessModelPrice {
  outputUsdPerMillion: number | null;
  needsFundsUsd: number | null;
}
```

## ModelUsage

```typescript
interface ModelUsage
```

What an agent's model calls on your own key or plan (its `modelConnection`) used: tokens in
(`cachedTokens` of them read from the provider's cache), tokens out, and what they come to in US
dollars at the provider's list price. NoClick doesn't bill these calls; this is how you see them.
A coding harness on a plan counts what it reports, priced as if it ran on a key.

| Attribute | Type | Description |
| --- | --- | --- |
| `inputTokens` | `number` |  |
| `outputTokens` | `number` |  |
| `cachedTokens` | `number` |  |
| `usd` | `number` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## ModelSwitching

```typescript
interface ModelSwitching
```

How an agent moves to another of its owner's model connections when its plan runs out, or when it's told to.
`switch` (the default): by itself, to any of the owner's own Claude or ChatGPT plans freely, and to a paid key (an
API key, NoClick's key at cost) only on the owner's say-so. `stay`: it never leaves its connection, and at a limit
waits for the reset. `allowed`: the connections (names) it moves between freely, paid keys included; null for the
default rule.

| Attribute | Type | Description |
| --- | --- | --- |
| `mode` | `"switch" | "stay"` |  |
| `allowed` | `string[] | null` |  |

## ModelSwitchGrant

```typescript
interface ModelSwitchGrant
```

The owner's say-so for an agent's paid keys: which (`connections`, null for any), `once` or `standing`, and how they
gave it (`source`: `cited`, words of theirs the agent cited, `evidence` saying where and when, the quote and a link;
`asked`, their tap; `owner`, their own call).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `connections` | `string[] | null` |  |
| `scope` | `"once" | "standing"` |  |
| `source` | `"cited" | "asked" | "owner"` |  |
| `evidence` | `JsonObject` |  |
| `grantedBy` | `JsonObject` |  |
| `usedAt` | `string | null` |  |
| `revokedAt` | `string | null` |  |
| `createdAt` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## AgentToolAccess

```typescript
interface AgentToolAccess
```

What an agent may do with each app it reaches (`agent.toolAccess()`). `mode` is `restricted` when it's kept to the
apps its rules turn on; `listed` when its `tools` are a list rather than everything, whose `rules` are what that
list amounts to.

| Attribute | Type | Description |
| --- | --- | --- |
| `mode` | `"everything" | "restricted"` |  |
| `listed` | `boolean` |  |
| `rules` | `ToolRules` |  |
| `since` | `Date | null` |  |
| `apps` | `AgentToolApp[]` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
/**
 * What an agent may do with each app it reaches, as `{ key: ToolRule }`. A key is an app as `tools` names it (a
 * connection's name, `"credential:<id>"`, an integration's, `"noclick"`, `"search"`, `"fetch"`), one action of it
 * (`"work-gmail.delete_email_message"`; NoClick's are its groups, `"noclick.spend"`), or `"*"` for whatever the rest
 * don't name. The most specific key naming a call decides it; none, it's allowed. With everything, `"*": "off"` keeps
 * it to the apps the rules turn on, so an account connected later starts off.
 */
type ToolRules = Record<string, ToolRule>;

/** `allow` runs a call, `ask` holds it for the owner's yes (an approval), `off` refuses it. */
type ToolRule = "allow" | "ask" | "off";

type JsonObject = { [key: string]: unknown };
```

## AgentToolApp

```typescript
interface AgentToolApp
```

One app in `agent.toolAccess()`: a connection of its scope, an integration its rules name, NoClick or the web.

| Attribute | Type | Description |
| --- | --- | --- |
| `key` | `string | null` | Its rule key; null for the web, whose two actions (`search`, `fetch`) are keys of their own. |
| `app` | `string` |  |
| `kind` | `"connection" | "integration" | "noclick" | "web"` |  |
| `integration` | `string | null` |  |
| `credentialType` | `string | null` |  |
| `label` | `string` |  |
| `account` | `string | null` | The account it's connected as (else its name), or what it does for NoClick and the web. |
| `status` | `ConnectionStatus | null` |  |
| `on` | `boolean` | Whether anything of it may run. |
| `calls` | `number` |  |
| `actions` | `AgentToolAction[]` |  |

Types:

```typescript
/**
 * `pending` until an account is connected, `disconnected` once it's revoked. A pending connection
 * still runs the operations whose `needsAccount` is false, on NoClick's key.
 */
type ConnectionStatus = "pending" | "connected" | "disconnected";
```

## AgentToolAction

```typescript
interface AgentToolAction
```

One action of an app in `agent.toolAccess()`: its rule `key`, what its rules say of it and how often it ran.

| Attribute | Type | Description |
| --- | --- | --- |
| `key` | `string` |  |
| `action` | `string` |  |
| `title` | `string` |  |
| `group` | `string | null` | Its integration's own grouping of it (`Message`, `Invoices`); null for NoClick's and the web's. |
| `kind` | `"read" | "send" | "change" | "delete" | "money"` | What it does, from its name: `read`, `send`, `change`, `delete` or `money` (a hint, never a rule). |
| `verdict` | `ToolRule` |  |
| `canAsk` | `boolean` | False where `ask` can't hold it (reading never waits for a person). |
| `calls` | `number` | Its calls that ran since `since`. |

Types:

```typescript
/** `allow` runs a call, `ask` holds it for the owner's yes (an approval), `off` refuses it. */
type ToolRule = "allow" | "ask" | "off";
```

## AgentMemory

```typescript
class AgentMemory
```

`agent.memory`: named notes the agent keeps across conversations. Every turn starts with each
entry's name and description; the agent reads a body when it needs one, and saves what it
learns. Your code can seed, read, correct and forget entries the same way.

An account agent keeps two layers: entries saved outside `asUser` are the account's, read in
every user's conversations, and what it learns while talking to a user is that user's
alone. A user's own agent has one memory, the user's. The agent changes the account's entries
only in conversations your code has with it outside `asUser`, and only reads its memory when it
answers someone outside your account (an inbox's sender, a caller, a visitor to its share link).
A long conversation also keeps its checkpoint here, in that conversation's layer
(`MemoryEntry.conversation`).

It's a `Memory` (its id is `agent.memoryId`) that goes with the agent: another agent of its
scope can read it too, with `memories: [agent.memory]`, and named memories (`Memory`) are
attached the same way.

### AgentMemory.list

```typescript
list(options?: { user?: UserOption }): Promise<MemoryEntry[]>
```

The entries of one layer (the account's outside `asUser`, else the user's), by name, without their content.

Parameters:

- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Each entry's name, description, version and when it last changed, by name; `content` is
`None` here, so `read` an entry for its body.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.search

```typescript
search(
  query: string,
  options?: { limit?: number; user?: UserOption },
): Promise<MemoryEntry[]>
```

Search what the agent remembers in a scope, the way the agent does (a user's entries and the
account's): entries whose name, description or content holds any of the query's words (`refund`
also finds `refunds`), or whose name or description holds the query; best first, with content
(10 unless `limit` says otherwise, at most 100).

Parameters:

- `query` (`string`, required)
- `options.limit` (`number`): Return at most this many.
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The best matches first (10 unless `limit` says otherwise, at most 100), each with its `content`
and `user_id` (`None` for the account's entries).

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.read

```typescript
read(name: string, options?: { user?: UserOption }): Promise<MemoryEntry>
```

One entry in full; a name with no entry throws `NotFound`.

Parameters:

- `name` (`string`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The entry with its `content` and the `version` to pass back when you change it.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.save

```typescript
save(
  name: string,
  content: string,
  options?: { description?: string; version?: number; user?: UserOption },
): Promise<MemoryEntry>
```

Write an entry, creating it if the name is new. `description` is the line the agent sees every
turn (required for a new entry, kept when omitted). With `version` the save only lands if the
entry is still at that version, else `Conflict`; without it, it replaces whatever is there.

Parameters:

- `name` (`string`, required)
- `content` (`string`, required)
- `options.description` (`string`)
- `options.version` (`number`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The entry as saved, with its new `version`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.delete

```typescript
delete(
  name: string,
  options?: { version?: number; user?: UserOption },
): Promise<void>
```

Forget an entry; with `version`, only if it is still at that version (else `Conflict`).

Parameters:

- `name` (`string`, required)
- `options.version` (`number`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.versions

```typescript
versions(
  name: string,
  options?: { user?: UserOption },
): Promise<MemoryEntryVersion[]>
```

An entry's versions, newest first: the one it holds now, then those kept from earlier saves (its
last 50 in all), without their content. A name with no entry throws `NotFound`.

Parameters:

- `name` (`string`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Each version's number, description, who wrote it and when, without its `content`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.getVersion

```typescript
getVersion(
  name: string,
  version: number,
  options?: { user?: UserOption },
): Promise<MemoryEntryVersion>
```

One version of an entry, with its content; one it no longer keeps throws `NotFound`.

Parameters:

- `name` (`string`, required)
- `version` (`number`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: That version in full.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.restore

```typescript
restore(
  name: string,
  version: number,
  options?: { user?: UserOption },
): Promise<MemoryEntry>
```

Put an entry back as it was at `version`: a new version holding that one's content and
description, so the one it replaces is kept too.

Parameters:

- `name` (`string`, required)
- `version` (`number`, required)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: The entry as restored, at its new `version`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.entries

```typescript
entries(options?: { user?: UserOption }): Promise<MemoryEntry[]>
```

`list`, as `Memory` calls it.

Parameters:

- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: Each entry's name, description and version, by name, without its `content`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### AgentMemory.forget

```typescript
forget(
  name: string,
  options?: { version?: number; user?: UserOption },
): Promise<void>
```

`delete`, as `Memory` calls it.

Parameters:

- `name` (`string`, required)
- `options.version` (`number`)
- `options.user` (`UserOption`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

## MemoryEntry

```typescript
interface MemoryEntry
```

One named note in an agent's memory. `version` goes up with every
save; pass the one you read back to `save` or `delete` so you never
overwrite a change the agent made since. `content` is `None` in a
listing (`read` loads it). `updated_by` is `agent`, `api` or
`console`.

`conversation` is set on a conversation's checkpoint: a long
conversation keeps its older history folded into one entry, named
`context.` and a hash, which its turns read in place of that history.
Read it to see what the agent carries forward; an edit wins over the next
summary, and deleting it forgets that history for good. The agent never
sees it outside that conversation.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `description` | `string` |  |
| `content` | `string | null` |  |
| `version` | `number` |  |
| `updatedAt` | `Date | null` |  |
| `updatedBy` | `"agent" | "api" | "console" | null` |  |
| `writtenBy` | `MemoryWriter` | Who last wrote it: for an agent, which one and in which of its conversations. |
| `userId` | `string | null` |  |
| `conversation` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## MemoryEntryVersion

```typescript
interface MemoryEntryVersion
```

One version of a memory entry, as it was saved. Every save keeps the version it replaces, so an
entry keeps its last 50 versions, the one it holds now (`current`) included; a conversation's
checkpoint keeps none. `content` is null in a listing (`getVersion` loads it), and `savedAt` is
when that version was saved.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `version` | `number` |  |
| `current` | `boolean` |  |
| `description` | `string` |  |
| `content` | `string | null` |  |
| `writtenBy` | `MemoryWriter` |  |
| `userId` | `string | null` |  |
| `savedAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## MemoryWriter

```typescript
interface MemoryWriter
```

Who last wrote a memory entry: an agent's turn (which agent, in which conversation), a person in the app, or a key.

| Attribute | Type | Description |
| --- | --- | --- |
| `type` | `"agent" | "api" | "console" | null` |  |
| `agentId` | `string | null` |  |
| `agentName` | `string | null` |  |
| `conversation` | `string | null` |  |

## AgentWorkspace

```typescript
class AgentWorkspace
```

The files an agent works on (`agent.workspace()`): what it writes with its shell or its tools, and what you put
there for it. An agent has one `/workspace`, which every turn sees whoever it answers, and a clear or a resume
leaves as it is; an account agent's user has their own. (A `Workspace` is something else: channels and their
members.)

| Attribute | Type | Description |
| --- | --- | --- |
| `conversation` | `string | undefined` | The conversation it was named by, if any: accepted and ignored, since an agent has one workspace. |

### AgentWorkspace.files

```typescript
files(): Promise<WorkspaceFile[]>
```

Every file in the workspace, each with a download `url` (empty until the agent writes one).

Returns: Each file's `path` (relative to `/workspace`), size, when it last changed and a download `url`.
An empty list for a conversation whose agent hasn't written anything.

### AgentWorkspace.read

```typescript
read(path: string): Promise<Uint8Array>
```

Read one file's bytes; a missing file throws `NotFound`.

Parameters:

- `path` (`string`, required)

Returns: The file's bytes, exactly as stored; decode text yourself.

### AgentWorkspace.write

```typescript
write(path: string, data: string | Uint8Array): Promise<WorkspaceFile>
```

Put a file in the workspace (text as UTF-8), replacing one at that path; at most 100 MB. A coding
harness's sandbox stays up between turns and sees it once it starts again.

Parameters:

- `path` (`string`, required)
- `data` (`string | Uint8Array`, required)

Returns: The file as stored, with its download `url`.

### AgentWorkspace.delete

```typescript
delete(path: string): Promise<void>
```

Delete one file from the workspace; a missing file does nothing.

Parameters:

- `path` (`string`, required)

### AgentWorkspace.url

```typescript
url(path: string, options?: { expiresInS?: number }): Promise<string>
```

A link that downloads one file without a key, for `expiresInS` seconds (an hour by default, a day at most).

Parameters:

- `path` (`string`, required)
- `options.expiresInS` (`number`)

Returns: The link; it works for `expires_in_s` seconds (an hour by default, a day at most).

## WorkspaceFile

```typescript
interface WorkspaceFile
```

A file in a conversation's workspace; `url` downloads it without a key for about an hour.

| Attribute | Type | Description |
| --- | --- | --- |
| `path` | `string` | Relative to `/workspace`. |
| `sizeBytes` | `number` |  |
| `modifiedAt` | `Date | null` |  |
| `url` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## ShareLink

```typescript
class ShareLink
```

An agent's public chat page. Anyone with `url` can talk to the agent, no sign-in: each visitor
in conversations of their own, billed to you. Your brand dresses the page. `createdAt` is when
it was first shared.

| Attribute | Type | Description |
| --- | --- | --- |
| `url` | `string` |  |
| `enabled` | `boolean` |  |
| `agentId` | `string` |  |
| `createdAt` | `Date | null` |  |
| `rotatedAt` | `Date | null` | When the URL last changed (null if it never has). |

### ShareLink.disable

```typescript
disable(): Promise<this>
```

Turn the page off: visitors see the agent isn't available. `agent.share()` turns it back on at the same URL.

Returns: This link, with `enabled` false.

### ShareLink.rotate

```typescript
rotate(): Promise<this>
```

Give the page a new URL; the old one stops at once.

Returns: This link, with its new `url`.

## AgentSandbox

```typescript
class AgentSandbox
```

The machine an agent works on (`agent.sandbox()`): what it is and costs, its files and your own commands on it,
beside the agent's work. An agent has one, whoever it answers. While its sandbox runs, its files are read there with every
secret it holds taken out; while it's stopped, from what its workspace kept. Files and commands need the account's
owner: signed in, or its secret key with the `agents:terminal` scope. Sends nothing yet.

    const machine = coder.sandbox();
    if ((await machine.get()).status === "running") console.log((await machine.exec("git status --short")).stdout);

| Attribute | Type | Description |
| --- | --- | --- |
| `conversation` | `string | undefined` | The conversation it was named by; none reads it through the agent's session. |

### AgentSandbox.get

```typescript
get(): Promise<ConversationSandbox>
```

Where it runs, whether it's running and since when, what it reserved and costs.

Returns: A `ConversationSandbox`.

### AgentSandbox.files

```typescript
files(
  path?,
  options?: SandboxFilesOptions & { limit?: number },
): Promise<VolumeEntry[]>
```

What's in the folder at `path` (absolute; its workspace by default), a folder before what's in it, fetched page by
page. A path that doesn't exist throws `NotFound`.

Parameters:

- `path` (`string`, default `"/workspace"`)
- `options.recursive` (`boolean`): Everything below the folder, not just what's in it (git's objects left out unless listed by their path).
- `options.limit` (`number`): Return at most this many.

Returns: Every entry (or the first `limit`), fetched page by page.

### AgentSandbox.filesPage

```typescript
filesPage(
  path?,
  options?: SandboxFilesOptions & PageOptions,
): Promise<SandboxFilesPage>
```

One page of `files`, and where it was read; pass `nextCursor` back as `cursor`.

Parameters:

- `path` (`string`, default `"/workspace"`)
- `options.recursive` (`boolean`): Everything below the folder, not just what's in it (git's objects left out unless listed by their path).
- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.

Returns: A `SandboxFilesPage`.

### AgentSandbox.read

```typescript
read(path: string): Promise<Uint8Array>
```

One file's bytes (up to 16 MB), its secrets taken out; a missing file throws `NotFound`.

Parameters:

- `path` (`string`, required)

Returns: The file's bytes; decode text yourself.

### AgentSandbox.exec

```typescript
exec(command: string, options?: { timeoutS?: number }): Promise<ExecResult>
```

Run a bash command in its running sandbox, in the agent's working directory, beside its work: the agent isn't
stopped, and the sandbox stays up while the command runs. A stopped conversation throws `Conflict` (its next
turn starts its sandbox). `timeoutS` is 60 by default, at most 90.

Parameters:

- `command` (`string`, required)
- `options.timeoutS` (`number`)

Returns: Its `stdout`, `stderr` (the last 64 KiB of each) and `exit_code`.

### AgentSandbox.shell

```typescript
shell(): Promise<SandboxShell>
```

Your own shell (`bash -l`) on its running sandbox, in the agent's working directory, beside its work: the agent
isn't stopped, and the sandbox stays up while you type. Resolves to a single-use `token` for `url` (two minutes);
`connect()` it from the browser as a take-over's terminal is. It closes as bash exits, after `idleLimitS` with
nothing typed, or when its connection closes; while it's open, `connect` renews it by asking for the shell
again. A stopped conversation throws `Conflict`.

    const shell = await coder.sandbox().shell();
    const connection = shell.connect({ cols: term.cols, rows: term.rows, onData: (bytes) => term.write(bytes) });
    term.onData((text) => connection.write(text));

Returns: A `SandboxShell` whose `url` and single-use `token` your user's browser opens within two minutes.

## ConversationSandbox

```typescript
interface ConversationSandbox
```

The machine a conversation's agent works on, as it stands. A coding agent's sandbox starts with a turn and stops a
minute after its last; an `sdk` agent's shell lives only during a turn, so it reads `stopped`. `cpu` and `memoryMb`
are what it reserved (null while stopped), `usdPerHour` what an hour of it costs, `spentUsdToday` what its sandbox
charged since midnight UTC (null where the conversation has no sandbox of its own), and `workspace` the folder kept
between its runs.

| Attribute | Type | Description |
| --- | --- | --- |
| `agentId` | `string` |  |
| `conversation` | `string` |  |
| `harness` | `HarnessName` |  |
| `place` | `SandboxPlace` |  |
| `status` | `"running" | "stopped"` |  |
| `startedAt` | `Date | null` |  |
| `cpu` | `number | null` |  |
| `memoryMb` | `number | null` |  |
| `region` | `string | null` |  |
| `usdPerHour` | `number | null` |  |
| `spentUsdToday` | `number | null` |  |
| `machineId` | `string | null` |  |
| `projectId` | `string | null` |  |
| `workspace` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** Where a conversation's agent works: a sandbox of the conversation's own, an agent's `machine`, or an app's `live` container. */
type SandboxPlace = "sandbox" | "machine" | "live";

type JsonObject = { [key: string]: unknown };
```

## SandboxFilesPage

```typescript
interface SandboxFilesPage extends Page
```

One page of a sandbox's folder; `source` says where it was read: the running `sandbox`, or what its `workspace` kept.

| Attribute | Type | Description |
| --- | --- | --- |
| `source` | `"sandbox" | "workspace"` |  |

## SandboxShell

```typescript
class SandboxShell
```

A shell on a conversation's sandbox (`AgentSandbox.shell`): `connect()` opens it, once per token.

| Attribute | Type | Description |
| --- | --- | --- |
| `agentId` | `string` |  |
| `conversation` | `string` |  |
| `url` | `string` | The terminal websocket it opens on. |
| `token` | `string` | Opens `url` once, within two minutes: its first message's `token`. |
| `tokenExpiresAt` | `Date | null` |  |
| `idleLimitS` | `number | null` | It closes after this long with nothing typed. |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

### SandboxShell.connect

```typescript
connect(options?: TerminalConnectOptions): TerminalConnection
```

Open the shell: `onState` hears `exited` (and why) as it ends, and it closes for good (`final`).

Parameters:

- `options.cols` (`number`): The terminal's size as it opens (else the one `takeOver` was given).
- `options.rows` (`number`)
- `options.onData` (`(data: Uint8Array) => void`): What the terminal prints, as it prints it.
- `options.onReady` (`(status: TerminalStatus) => void`): It's open: what the person types reaches the terminal from now.
- `options.onState` (`(status: TerminalStatus) => void`): The take-over moved (`person`, `handing_back`, then `agent` as it closes).
- `options.onClose` (`(event: { code: number; reason: string; final: boolean }) => void`): It closed: `final` when it won't open again with this take-over (handed back, nothing running, or a used token);
otherwise take over again for a new token and connect.
- `options.renew` (`() => Promise<string>`): A new token for this same terminal. With one, the connection says it renews as it opens, and lasts 15 minutes
at a time: the server asks for a new token in the last minute, and without an answer it closes with
`TERMINAL_RENEW`. `Terminal.connect` takes over again and `SandboxShell.connect` asks for the shell again by
themselves; for a machine's shell, `async () => (await machine.shell()).token`. Without one, it has no
lifetime.
- `options.WebSocket` (`typeof WebSocket`): A WebSocket class, where the runtime has none of its own (Node before 22).

Types:

```typescript
/** Where the take-over stands, as the terminal's connection reports it. */
interface TerminalStatus {
  state: TerminalState;
  reason: TerminalEnd | null;
  raw: JsonObject;
}

/**
 * `agent` (the agent has it), `taking_over` (its turn in flight finishes first), `person` or `handing_back`; a
 * sandbox shell's (`AgentSandbox.shell`) is `open`, then `exited` as it closes.
 */
type TerminalState = "agent" | "taking_over" | "person" | "handing_back" | "open" | "exited";

/** Why a take-over (or a sandbox shell) ended: asked (`handed_back`, `canceled` while it waited), or by itself. */
type TerminalEnd = "handed_back" | "canceled" | "idle" | "detached" | "exited" | "deadline" | "failed";

type JsonObject = { [key: string]: unknown };
```

## CodingAgents

```typescript
interface CodingAgents
```

Every coding agent of the account (or its users'), what each is doing right now and where: `agents`, then `counts`
by harness, model, state and place, `byState`, `pausedByReason`, and `unread`: what couldn't be read (an app's
container, the sandbox registry), whose runs are unknown, never shown down.

| Attribute | Type | Description |
| --- | --- | --- |
| `agents` | `CodingAgent[]` |  |
| `counts` | `CodingCount[]` |  |
| `byState` | `Record<string, number>` |  |
| `pausedByReason` | `Record<string, number>` |  |
| `readAt` | `Date | null` |  |
| `unread` | `string[]` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## CodingAgent

```typescript
interface CodingAgent
```

One coding agent, as `Agent.coding()` reads it: its `state`, its `place`, whose model credential it thinks with, its current `job` and the conversations up now (`runs`).

| Attribute | Type | Description |
| --- | --- | --- |
| `agentId` | `string` |  |
| `name` | `string` |  |
| `userId` | `string | null` |  |
| `app` | `CodingApp | null` |  |
| `harness` | `HarnessName` |  |
| `model` | `string | null` |  |
| `credential` | `CodingCredential` |  |
| `place` | `CodingPlace` |  |
| `state` | `CodingState` |  |
| `paused` | `CodingPause | null` |  |
| `pauses` | `CodingPause[]` |  |
| `job` | `CodingJob | null` |  |
| `runs` | `CodingRun[]` |  |
| `spentUsdThisMonth` | `number` |  |
| `modelUsageThisMonth` | `ModelUsage` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

/** Where a coding agent's current or next turn runs. */
type CodingPlace = "live" | "sandbox" | "machine";

type CodingState = "working" | "waiting" | "warm" | "paused" | "stopped";

type JsonObject = { [key: string]: unknown };
```

## CodingApp

```typescript
interface CodingApp
```

The app a coding agent codes, by `name` (what code finds it by) and `title` (as a person reads it); `coder` for the app's own coding agent.

| Attribute | Type | Description |
| --- | --- | --- |
| `projectId` | `string` |  |
| `name` | `string | null` |  |
| `title` | `string | null` |  |
| `coder` | `boolean` |  |

## CodingCount

```typescript
interface CodingCount
```

How many coding agents run on each harness and model, in each state and place.

| Attribute | Type | Description |
| --- | --- | --- |
| `harness` | `HarnessName` |  |
| `model` | `string | null` |  |
| `state` | `CodingState` |  |
| `place` | `CodingPlace` |  |
| `count` | `number` |  |

Types:

```typescript
/** What runs an agent: NoClick's own agent loop (`sdk`), or a coding agent in a sandbox of its own. */
type HarnessName = "sdk" | "claude_code" | "codex" | "opencode" | "hermes" | "openclaw";

type CodingState = "working" | "waiting" | "warm" | "paused" | "stopped";

/** Where a coding agent's current or next turn runs. */
type CodingPlace = "live" | "sandbox" | "machine";
```

## CodingCredential

```typescript
interface CodingCredential
```

Whose model credential it thinks with: `key`, a person's `plan`, NoClick's own (`noclick`), or `pending` until it's connected.

| Attribute | Type | Description |
| --- | --- | --- |
| `kind` | `"key" | "plan" | "noclick" | "pending"` |  |
| `connection` | `string | null` |  |
| `credentialType` | `string | null` |  |
| `connected` | `boolean | null` |  |

## CodingJob

```typescript
interface CodingJob
```

Its turn in flight (or a `lost` one): `title` as whoever handed it over named it, `text` the start of what it was
asked, `workstream` the one it belongs to as it reads now (null where none was named).

| Attribute | Type | Description |
| --- | --- | --- |
| `operationId` | `string` |  |
| `conversation` | `string | null` |  |
| `status` | `string` |  |
| `step` | `string | null` |  |
| `since` | `Date | null` |  |
| `title` | `string | null` |  |
| `text` | `string` |  |
| `lost` | `boolean` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `workstream` | `NamedWorkstream | null` |  |

Types:

```typescript
type JsonObject = { [key: string]: unknown };

/** The workstream an operation's work belongs to, as it reads now. */
interface NamedWorkstream {
  id: string;
  name: string;
}
```

## CodingPause

```typescript
interface CodingPause
```

Why a coding agent isn't doing anything (`expired`, `disconnected`, `spending_paused`, `spend_cap`, `out_of_funds`, `budget`, `failed_start`, `paused`).

| Attribute | Type | Description |
| --- | --- | --- |
| `reason` | `string` |  |
| `message` | `string` |  |

## CodingRun

```typescript
interface CodingRun
```

A conversation of its with a place up now; a sandbox's `cpu` and `memoryMb` are what it reserved.

| Attribute | Type | Description |
| --- | --- | --- |
| `conversation` | `string | null` |  |
| `place` | `CodingPlace` |  |
| `since` | `Date | null` |  |
| `busy` | `boolean` |  |
| `projectId` | `string | null` |  |
| `daemon` | `boolean | null` |  |
| `cpu` | `number | null` |  |
| `memoryMb` | `number | null` |  |

Types:

```typescript
/** Where a coding agent's current or next turn runs. */
type CodingPlace = "live" | "sandbox" | "machine";
```

## AgentEvent

```typescript
interface AgentEvent
```

One moment of a streamed turn or a watched conversation. `type` is `text` (`text` is the next
piece of the reply), `tool_call` (`tool`, its wire name like `gmail__send_email_message`, and its
`arguments`; `held` when policy holds it for a person), `tool_result` (`tool`, its `result`: the
start of what it returned, up to 500 characters, or its error; and whether it `isError`), `file`
(a `file` the message carried, `role` `user`, or the turn made, `assistant`), `reasoning` (`text` is
one short line of what the model is thinking, the title of a section of its reasoning, sent as it
completes), `status` (`compacting` while a long conversation's older history is summarized, then
`compacted`), `approval` (its
`"noclick"` tools held a purchase or a deletion for the account's owner: the `approval`),
`operation` (they started a long action: the `operation`, which comes again with its `progress`
each time the work reports some and once more when it ends) or `done` (`reply` is the whole
`AgentReply`, as `message` resolves to). `agent.watch()` also yields `message` (a whole message:
its `role`, `text`, `files` and `via` or `trigger`; a reply, its `toolCalls` and `reasoning`; a `note`, its `data`), `status` (the conversation's new `status`) and
`turn_end` once a turn of the conversation ends, however it started and whether or not it saved a reply (its
`status`: `succeeded`, `failed`, `canceled` or `expired`; `text`, its reply's words, empty when it said nothing). `operationId` names
the turn an event belongs to (null for a message no turn sent, like a person's reply). `history()`
reads messages in the same shape. The type `call` is reserved for a phone call's moments. A coding harness's turn
(Codex, Claude Code and the like) also tells what its commands print as they run, `output` (`text`, its command's
`callId`, and `whole` when it replaces what came before of that command), and each file it changes, `diff` (`path`,
`change` and the `diff`). Its own steps' `tool_call` and `tool_result` say `source` `harness`, name their `callId`
and say what kind of step it is (`stepKind`), a `tool_call` what it's about (`command`, `path` or `query`), a
command's result its `exitCode` and `durationMs`: the fields a finished turn's `AgentStep` keeps. A `status` of
`events_dropped` says `count` moments its sandbox couldn't send. On a machine, a turn waiting for its harness's
image says `downloading` while it downloads (`text`, like "Downloading OpenCode for this machine: 450 MB of
1.31 GB", with `downloaded_bytes` and `total_bytes` in `raw`), then `downloaded`.

| Attribute | Type | Description |
| --- | --- | --- |
| `type` | `| "text" | "reasoning" | "tool_call" | "tool_result" | "file" | "approval" | "operation" | "done" | "message" | "status" | "output" | "diff" | "turn_end" | "group" | (string & {})` |  |
| `text` | `string | null` |  |
| `tool` | `string | null` |  |
| `arguments` | `JsonObject | null` |  |
| `result` | `unknown` |  |
| `isError` | `boolean` |  |
| `reply` | `AgentReply | null` |  |
| `role` | `"user" | "assistant" | "person" | "note" | null` | A `message`'s sender: `user`, `assistant`, `person` (someone it was handed off to) or `note` (`agent.note`). |
| `held` | `JsonObject | null` | A held `tool_call`: who `approver` is and, when the request is addressed to the scope you read as, the approval's `request_id` and page `url`. |
| `status` | `| "active" | "awaiting_human" | "handed_off" | "compacting" | "compacted" | "events_dropped" | "downloading" | "downloaded" | "succeeded" | "failed" | "canceled" | "expired" | null` | A `status` event's: the conversation's new status, or a turn's own (`compacting`, then `compacted`; a coding harness's `events_dropped`; on a machine, `downloading`, then `downloaded`). A `turn_end`'s: how the turn ended. |
| `operationId` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `file` | `Attachment | null` | A `file` event's file. |
| `files` | `Attachment[]` | A `message` event's files. |
| `toolCalls` | `JsonObject[]` | A `message` event's tool calls (a reply's): each `{tool, arguments, result, is_error}`, as its turn's events showed it. |
| `approval` | `JsonObject | null` | An `approval` event's: its `id`, `summary`, exact `price` (a purchase), `expires_at` and `sent_to`, the apps NoClick sent the account's owner its link on (never the link). |
| `operation` | `JsonObject | null` | An `operation` event's: the long action's `id` (an `Operation`'s), `kind`, `status` and `summary` and, once the work reported some, its `progress` (`Operation.progress`, with its last 3 `lines`). |
| `via` | `MessageVia | null` | A `user` message's way in, when not the API. |
| `data` | `JsonObject | null` | A `note` message's data. |
| `trigger` | `MessageTrigger | null` | A `user` message no person sent: what started its turn (`Message.trigger`). |
| `reasoning` | `ReasoningLine[]` | A `message` event's reasoning (a reply's): `Message.reasoning`. |
| `callId` | `string | null` | A coding harness's step: the `tool_call`, the `output` of its command, its `tool_result` and the `diff` of each file it changed share it. |
| `source` | `"harness" | (string & {}) | null` | `harness` for a step a coding harness took itself (its own shell, its edits), not a tool NoClick gave it. |
| `exitCode` | `number | null` | A harness command's `tool_result`: its exit code (null when it never exited). |
| `durationMs` | `number | null` | A harness command's `tool_result`: how long it ran. |
| `whole` | `boolean` | An `output` that replaces what streamed of its command so far, rather than continuing it. |
| `path` | `string | null` | A `diff`'s file, or the file (a page's URL) a harness step's `tool_call` edits or reads. |
| `change` | `"add" | "update" | "delete" | (string & {}) | null` | What happened to a `diff`'s file. |
| `diff` | `string | null` | A `diff`'s change: a unified diff, or a new file's whole content. |
| `count` | `number | null` | A `status` `events_dropped`'s: how many moments its sandbox couldn't send. |
| `stepKind` | `AgentStepKind | null` | A harness step's `tool_call` and `tool_result`: `command`, `edit`, `read`, `search` or `tool` (`AgentStep.kind`). |
| `request` | `JsonObject | null` | A `request` event's: what a coding harness asks a person (an approval or a question), as it waits and as it ends, in the shape `agent.requests` lists (answer it with `agent.answer`). |
| `command` | `string | null` | A harness command's `tool_call`: the command it runs. |
| `query` | `string | null` | A harness search's `tool_call`: what it looks for. |
| `messageId` | `string | null` | A `message`'s id in its thread (`Message.id`). |
| `author` | `MessageAuthor | null` | Who sent a `user` `message` (`Message.author`). |
| `notification` | `boolean` | A `message` an agent sent its owner from another of its conversations (`Message.notification`). |
| `space` | `MessageSpace | null` | A notification's space, when it passes on a space's news (`Message.space`). |
| `subagent` | `MessageSubagent | null` | The coding harness's subagent a `user` `message` was written for (`Message.subagent`). |
| `chat` | `string | null` | The chat a `message` of the agent's session came from, where it isn't the session's own (`Message.chat`). |
| `category` | `StepCategory | null` | A coding harness's step in words, as NoClick judged it (`tool_call` running, `tool_result` done; see `AgentStep`): its `category`, `label`, the command as shown, the fold it's in (`group`), a test run's `tests` and a count it reported (`progress`) as its `output` streams, how many lines it printed so far (`outputLines`), an edit's `diffStat` and whether it `failed`. |
| `label` | `StepLabel | null` |  |
| `displayCommand` | `string | null` |  |
| `group` | `string | null` |  |
| `tests` | `StepTests | null` |  |
| `progress` | `StepProgress | null` |  |
| `outputLines` | `number | null` |  |
| `diffStat` | `DiffStat | null` |  |
| `failed` | `boolean | null` |  |
| `stepGroup` | `StepGroup | null` | A `group` moment: a fold of the turn's reads and searches that changed, as it stands now. |
| `summary` | `TurnSummary | null` | A `turn_end`'s (or `done`'s) turn as a coding harness ran it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };

/**
 * How a `user` message reached the agent when not through the API: a text to NoClick's number on `whatsapp` or
 * `imessage`, said on a phone `call`, or `email` to one of its inboxes.
 */
type MessageVia = "whatsapp" | "imessage" | "call" | "email";

/**
 * What started the turn of a `user` message no person sent: a trigger (`kind` is its kind: `webhook`, `event`,
 * `cron`, `platform` or `queue`), a wake-up (`wakeup`), or NoClick carrying on once app testing changed
 * (`app_testing`), with its `id` and `title`; a NoClick event's (`platform`) has its `event` (`{id, type, data}`).
 */
interface MessageTrigger {
  kind: string;
  id: string;
  title?: string | null;
  event?: { id: string; type: string; data: JsonObject } | null;
}

/** One short line of what a turn's model was thinking (the title of a section of its reasoning). */
interface ReasoningLine {
  text: string;
  createdAt: Date | null;
}

/** A step's kind: a coding harness's shell `command`, file `edit`, `read` or `search`, or any other `tool` (NoClick's own among them). */
type AgentStepKind = "command" | "edit" | "read" | "search" | "tool";

/** Who sent a `user` message to an agent: the account, one of your users, another agent, or an app's code. */
interface MessageAuthor {
  type: "account" | "user" | "agent" | "app";
  id: string | null;
  name: string | null;
}

/**
 * The space a notification passes news on from: a space's NoClick alerted the person, or answered a question their
 * NoClick asked it. `label` is what that NoClick goes by outside its space ("NoClick · Launch").
 */
interface MessageSpace {
  workspaceId: string;
  name: string;
  label: string;
}

/** The coding harness's subagent a `user` message was written for (`AgentConversation.messageSubagent`): the harness's
 *  call that runs it (`id`, its step's id) and what it was asked (`title`). */
interface MessageSubagent {
  id: string;
  title: string;
}

/** What a coding harness's step did, as NoClick judged it from what it runs. */
type StepCategory = "read" | "search" | "list" | "edit" | "test" | "install" | "run" | "tool";
```

## Rehearsal

```typescript
interface Rehearsal
```

A test run: a real turn of the agent (its model, instructions and tools) where a simulated world
answers every tool call, so nothing is sent and no account is touched. `toolCalls` are the calls
it made, each with the `tool` (its tool name, like `gmail__search_emails`), its `arguments` and
the `result` the world answered (null if the world couldn't); `transcript` is the turn step by
step: `role` `assistant` steps (its `text` between calls, then the reply) and `tool` steps. On a
coding harness its own shell and file steps are `tool` steps with `source` `harness`: they ran
for real, in the run's own sandbox. `costUsd` is what the run cost you.

| Attribute | Type | Description |
| --- | --- | --- |
| `reply` | `string` |  |
| `toolCalls` | `JsonObject[]` |  |
| `transcript` | `JsonObject[]` |  |
| `scenario` | `string | null` |  |
| `costUsd` | `number | null` |  |
| `operationId` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## Wakeup

```typescript
class Wakeup
```

One time an agent will be (or was) woken in a conversation. At its moment the conversation takes
a turn whose message is the `note`, followed by what woke it: the time, the operation's outcome, a
job's update, or a NoClick event. A running turn in that conversation goes
first (one turn per conversation), and the wake-up waits behind it. Durable, delivered once, and
billed and capped like any turn; a turn the account can't pay for fails it (`status: "failed"`,
`error`).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `agentId` | `string` |  |
| `userId` | `string | null` | Whose conversation it wakes (`None`: the account's). |
| `conversation` | `string` | The conversation it wakes. |
| `note` | `string` | What the turn is told. |
| `at` | `Date | null` | When it's due (a time wake-up), or when it became due. |
| `when` | `JsonObject | null` | What it waits on: `{ operation_id }` or `{ event, filters }` (null for a time wake-up). |
| `every` | `Cron | null` | Its schedule, for a recurring wake-up (null for one that comes once); `at` is its next time. |
| `fired` | `number` | How many turns it has started (a recurring one counts up). |
| `source` | `WakeupSource` | What set it: `code` (`agent.wake`), `wake_me` (the agent's own tool), `update` (a job's update for this agent as its parent), `answer` (the link it asked its user to connect an account with is done: connected or expired), `approval` (a held call was decided), `notice` (news for the account's own assistant) or `continue` (a turn its step limit ended, carried on by itself: `turn_limits`). |
| `status` | `WakeupStatus` | `pending`, `delivered` (its turn started), `canceled` or `failed`; a recurring one stays `pending` until it's canceled. |
| `wokenBy` | `JsonObject | null` | What woke it: `{ at }` for a time (once delivered), `{ operation_id, kind, status, result | error }` once its operation settled, `{ update }` for a job's update, and `{ event }` (the event as `Event.list` reads it) for an event; null until then. |
| `operationId` | `string | null` | The turn it started (an `agent.message` operation), once delivered. |
| `depth` | `number` | How many `wake_me` wake-ups in a row led to it (0 for anything else). |
| `error` | `JsonObject | null` | Why it failed: `{ type, message }`. |
| `missed` | `JsonObject | null` | A recurring one's last missed time: `{ at, reason }`, `reason` being `credits`, `spend_cap` (the account's monthly cap) or `budget` (the agent's, its key's or its user's); null if it never missed. |
| `createdAt` | `Date | null` |  |
| `deliveredAt` | `Date | null` | When its turn started (`None` until then). |
| `operation` | `Operation<AgentReply> | null` | The turn it started, as an operation to wait on (null until delivered). |

Types:

```typescript
type JsonObject = { [key: string]: unknown };

/**
 * Who set a wake-up: `code` (`agent.wake`), `wake_me` (the agent's own tool), or NoClick: `update` (a
 * job's update for this agent as its parent), `answer` (the link it asked its user to connect an
 * account with is done: connected or expired), `approval` (a held call was approved or declined),
 * `notice` (news for the account's own assistant, such as a friend's invite reward) and `continue` (a turn its
 * step limit ended, carried on by itself: `turnLimits`).
 */
type WakeupSource = "code" | "wake_me" | "update" | "answer" | "approval" | "notice" | "continue";

/** `pending` until its moment, then `delivered` (its turn started), `canceled` or `failed`. */
type WakeupStatus = "pending" | "delivered" | "canceled" | "failed";
```

### Wakeup.cancel

```typescript
cancel(): Promise<this>
```

Cancel it while it's pending (`Conflict` once it was delivered, canceled or failed).

Returns: This wake-up, `canceled`.

### Wakeup.update

```typescript
update(
  options: { note?: string } & Pick<WakeTiming, "at" | "afterS" | "every">,
): Promise<this>
```

Change it while it's pending: its `note`, and its time with one of `at`, `afterS` and `every` (a one-off time
makes a recurring one come once more). A delivery under way of what it said before starts no turn. One waiting
on an operation or an event keeps that; `Conflict` once it was delivered, canceled or failed.

Parameters:

- `options.note` (`string`)
- `options.at` (`Date | string`): A moment: a `Date`, or an ISO 8601 string with its offset.
- `options.every` (`Cron`): A routine: it wakes the conversation at each time of this `Cron` until it's canceled (`tz: "user"` follows the
conversation's user). The note is what it's told, so the `Cron` takes no `message`.
- `options.afterS` (`number`): This many seconds from now.

Returns: This wake-up, as it is now.

## Job

```typescript
class Job extends Operation
```

Work one agent gave another: a spawned child's task (kind `agent.task`), or a
message a coordinator sent with its `agents` tools (kind `agent.message`), whose
only update is `done`. It's an `Operation`: `wait()` returns the `AgentReply`.

A task runs while the child works on it, across as many turns as it takes, and
finishes when its conversation goes quiet with nothing left to continue it: no turn
running, no wake-up pending, nothing waiting on a person. While it runs, `step` is
`working` (a turn is running) or `waiting` (only a wake-up is pending); it's
`awaiting_human` (step `blocked`) while it waits on a person: a held call, or a
connection it asked its user for. It `succeeded` once the child stopped, its last reply the result (a child
that needs a decision says so and stops; the parent's `message` to it starts a new
job in the same conversation), `failed` when a turn failed, `canceled` when
canceled (its running turn stops and its pending wake-ups are called off), and
`expired` when the child's `ttl_s` ran out first.

| Attribute | Type | Description |
| --- | --- | --- |
| `startedBy` | `string | null` | The agent whose job it is: a task's parent, whether your code spawned it or the parent did. |
| `conversation` | `string | null` | The working agent's conversation it runs in. |
| `parentConversation` | `string | null` | The parent's conversation its updates wake (null: they wake nobody and wait here). |
| `requiredUpdates` | `(string | JsonObject)[]` | The updates its parent required, as on the wire: `"done"`, `"blocked"`, `{ before }`, `{ every_s }`. |
| `latestUpdate` | `JobUpdate | null` | Its newest update, or null. |
| `agent` | `Agent | null` | The agent doing the work (a lazy reference), or null. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

### Job.list

```typescript
static list(options?: KindScopedFilters & { limit?: number }): Promise<Job[]>
```

Spawned tasks (kind `agent.task`), newest first; takes `Operation.list`'s filters except `kind`. `agent.jobs()` reads an agent's message jobs too.

Parameters:

- `options.limit` (`number`): Return at most this many.
- `options.client` (`NoClick`)
- `options.user` (`UserOption`): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.status` (`OperationStatus | "live" | readonly (OperationStatus | "live")[]`): Statuses, or `"live"` for every non-terminal one.
- `options.agent` (`string | ApiObject`): An `Agent` or agent id.
- `options.statusNot` (`OperationStatus | readonly OperationStatus[]`)
- `options.key` (`string`): The requesting key: its id or its prefix (`nk_live_ab12`).
- `options.createdAfter` (`Date | string`)
- `options.createdBefore` (`Date | string`)
- `options.updatedAfter` (`Date | string`): Rows changed since (for polling).
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).

Returns: Every matching job (or the first `limit`), each with its `status`, `step` and `latest_update`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

type OperationStatus =
  | "queued" | "running" | "awaiting_human"
  | "succeeded" | "failed" | "canceled" | "expired";

/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;
```

### Job.listPage

```typescript
static listPage(options?: KindScopedFilters & PageOptions): Promise<Page<Job>>
```

One page of jobs; pass `nextCursor` back as `cursor`.

Parameters:

- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.
- `options.client` (`NoClick`)
- `options.user` (`UserOption`): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.status` (`OperationStatus | "live" | readonly (OperationStatus | "live")[]`): Statuses, or `"live"` for every non-terminal one.
- `options.agent` (`string | ApiObject`): An `Agent` or agent id.
- `options.statusNot` (`OperationStatus | readonly OperationStatus[]`)
- `options.key` (`string`): The requesting key: its id or its prefix (`nk_live_ab12`).
- `options.createdAfter` (`Date | string`)
- `options.createdBefore` (`Date | string`)
- `options.updatedAfter` (`Date | string`): Rows changed since (for polling).
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).

Returns: A page whose `data` holds the jobs and whose `next_cursor` is `None` on the last page.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

type OperationStatus =
  | "queued" | "running" | "awaiting_human"
  | "succeeded" | "failed" | "canceled" | "expired";

/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;
```

### Job.summary

```typescript
static summary(options?: KindScopedFilters): Promise<OperationSummary>
```

How many jobs match, by status; takes `Operation.summary`'s filters except `kind`.

Parameters:

- `options.client` (`NoClick`)
- `options.user` (`UserOption`): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.status` (`OperationStatus | "live" | readonly (OperationStatus | "live")[]`): Statuses, or `"live"` for every non-terminal one.
- `options.agent` (`string | ApiObject`): An `Agent` or agent id.
- `options.statusNot` (`OperationStatus | readonly OperationStatus[]`)
- `options.key` (`string`): The requesting key: its id or its prefix (`nk_live_ab12`).
- `options.createdAfter` (`Date | string`)
- `options.createdBefore` (`Date | string`)
- `options.updatedAfter` (`Date | string`): Rows changed since (for polling).
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).

Returns: The number that match in `total`, and per operation status in `by_status`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

type OperationStatus =
  | "queued" | "running" | "awaiting_human"
  | "succeeded" | "failed" | "canceled" | "expired";

/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;
```

### Job.updates

```typescript
updates(): Promise<JobUpdate[]>
```

Every update it sent its parent, oldest first.

Returns: Each `JobUpdate` with its `kind`, the child's `text` and, by kind, the call it was about to
make, what it waits on, or the result.

### Job.jobFromId

```typescript
static jobFromId(operationId: string, options?: CallOptions): Job
```

A lazy reference to a job by operation id: pick it up anywhere (`Operation.fromId` gives a plain operation).

Parameters:

- `operationId` (`string`, required)
- `options.client` (`NoClick`)
- `options.user` (`UserOption`): `undefined` = the ambient user (`asUser`), `null` = the account itself.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

## JobUpdate

```typescript
interface JobUpdate
```

One update a job sent its parent. `text` is what the child wrote: its last reply (`done`), what it
wrote with the call, its reason (`before`; null on a coding harness, whose words NoClick sees only
when its turn ends), what it wrote when asked (`every`), its message (`message`), or NoClick's line
saying what it waits on (`blocked`). `tool` and `arguments` are the call a `before` update
announces; `result` and `error` end a `done` one; `waitingOn` says what a `blocked` one waits on
(`{ kind: "connection" | "approval" | "person" | "sign_in", url, operation_id }`: a connect link it
asked its user to open, with its `url`; a held call, never with one, so no agent approves its child's
call; a question it asked someone; or a step its browser needs a person for); `wakeupId` is the parent's
wake-up it set (null when nothing
was to be woken).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `jobId` | `string` |  |
| `agentId` | `string | null` |  |
| `kind` | `JobUpdateKind` |  |
| `text` | `string | null` |  |
| `tool` | `string | null` |  |
| `arguments` | `JsonObject | null` |  |
| `status` | `string | null` | The job's status then. |
| `result` | `unknown` |  |
| `error` | `JsonObject | null` |  |
| `waitingOn` | `JsonObject | null` | A `blocked` update's wait: `{kind, url, operation_id}`, `kind` being `connection` (a link it asked its user to connect an account with: `url`), `approval` (a held call; never a `url`, so no agent approves its child's call), `person` (a question it asked someone) or `sign_in` (a step its browser needs a person for). |
| `wakeupId` | `string | null` |  |
| `createdAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
/** What a job's update is: its end (`done`), a wait on a person (`blocked`), a call it's about to make (`before`), a timed one (`every`), or its own `tell_parent` (`message`). */
type JobUpdateKind = "done" | "blocked" | "before" | "every" | "message";

type JsonObject = { [key: string]: unknown };
```

## Before

```typescript
class Before
```

An update before a matching tool call runs: the call and what the child wrote with it, its reason.
Patterns are written as policy writes them (`"gmail.send_email_message"`, `"stripe.*"`, `"code"`).
The call runs right after (a call that must wait for someone is a policy `requireApproval` rule),
and a coding harness's own shell commands and file edits aren't tool calls NoClick sees, so it
can't match them (its words arrive only when its turn ends, so its update carries no reason).

| Attribute | Type | Description |
| --- | --- | --- |
| `tools` | `string[]` | The tool patterns it covers. |
| `tools` | `string[]` |  |

## Every

```typescript
class Every
```

An update at least every `intervalS` seconds (60 or more) while the job works: NoClick asks the
child for one once that long has passed since its last (on a coding harness by steering its
running turn, on `sdk` before its next model call), and the `tell_parent` it answers with is the
`every` update. A child that's only waiting isn't asked.

| Attribute | Type | Description |
| --- | --- | --- |
| `intervalS` | `number` | How often, at most, the parent hears while the child works. |
| `intervalS` | `number` |  |

## Agents

```typescript
class Agents
```

The `agents` capability for an agent's `tools`: `new Agents()` (the same as `"agents"`) gives it
`spawn`, `message`, `ask`, `status`, `list` and `cancel` within its own scope, in its own
conversations (in a channel, agents work by mentions), and `Agents.only(...)` some of them.
`spawn` makes its own children (their updates wake it in the conversation it spawned from);
`message` reaches the agents it can reach (a user's agent that user's and the account's, an
account agent the account's), waiting up to 50 seconds for the reply, and a reply that takes
longer, or one it doesn't wait for, is a job whose `done` update wakes it; `ask` asks one without
stopping it; `status` reads an agent or a job; `list` takes `Agent.list`'s filters; `cancel` stops
a job it started. Its children get the capability only when it lists it for them. Policy names
them `agents.spawn` ... `agents.cancel`; the model sees `agents__spawn`, ...

| Attribute | Type | Description |
| --- | --- | --- |
| `tools` | `AgentsTool[]` | The capability's tools this gives. |
| `tools` | `AgentsTool[]` |  |

Types:

```typescript
/** The tools of the `agents` capability. */
type AgentsTool = "spawn" | "message" | "ask" | "status" | "list" | "cancel";
```

### Agents.only

```typescript
static only(...tools: AgentsTool[]): Agents
```

Some of the capability's tools: `Agents.only("spawn", "status")`.

Parameters:

- `tools` (`AgentsTool[]`, required)

Returns: The capability narrowed to those tools, for `tools=` (on the wire, `"agents.spawn"`, ...).

Types:

```typescript
/** The tools of the `agents` capability. */
type AgentsTool = "spawn" | "message" | "ask" | "status" | "list" | "cancel";
```

## Platform

```typescript
class Platform
```

NoClick itself for an agent's `tools`: `new Platform()` (the same as `"noclick"`) gives it what a
connected app gets on NoClick's MCP server, `search` and `fetch` (NoClick's guides and your account's
objects), `api_describe` and `api_call` (any API operation), and `quote`, `buy` and `delete`, acting as
the turn's key and the user it acts for, never more than that key may. The same gate judges them as any
connected app: a purchase or a deletion waits for the account's owner, who approves it on NoClick with its
exact price or what goes with it (the turn waits on them, and the call's outcome is the conversation's
next turn); a secret's value never comes from the conversation; and a turn answering someone outside the
agent's scope asks a person before acting outside the account. A long action it starts is an operation,
which `wake_me` waits on, and watchers see `approval` and `operation` events. `Platform.only(...)`
narrows it by capability group (without `spend` it has no `quote` or `buy`, without `delete` no
`delete`) and by API area (a key's scopes: `"domains"`, `"phone"`, `"agents"`...), each narrowing only
its own kind. `"admin"` (`Platform.only("admin")`, or the string `"noclick.admin"` beside `"noclick"`) adds the
admin group, which nothing holds unnamed: a few administrative calls and loosening what agents may do, each off
until your approval settings switch `admin` or `elevate`; it narrows nothing. Policy names its tools
`noclick.search` ... `noclick.delete`.

| Attribute | Type | Description |
| --- | --- | --- |
| `names` | `string[]` | What it's narrowed to: capability groups and API areas (empty: all of NoClick). |
| `names` | `string[]` | What it's narrowed to: capability groups and API areas (empty: all of NoClick). |

### Platform.only

```typescript
static only(...names: (PlatformGroup | (string & {}))[]): Platform
```

Part of NoClick: `Platform.only("domains")`, `Platform.only("read")`. Names are checked when the agent is saved.

Parameters:

- `names` (`(PlatformGroup | (string & {}))[]`, required)

Returns: NoClick narrowed to those names, for `tools=` (on the wire, `"noclick.read"`, ...).

Types:

```typescript
/** NoClick's capability groups, as a connected app's grant names them; `admin` only where it's named. */
type PlatformGroup = "read" | "build" | "deploy" | "spend" | "delete" | "admin";
```

## Attachment

```typescript
interface Attachment
```

A file on a message, kept as an account file at `url`. `kind` is `image`, `audio`, `video` or `file`; a
`voice` clip has its `durationMs` and its waveform's `peaks` (loudness 0-1). Audio is kept as
transcription reads it (a browser's WebM recording as MP3). A file an agent's conversation shows (in
`history`, or a `file` event) has its `name`, `url` and `mimeType`, and no `id`: it was sent. The account's
files (`attachments()`) have their `id`, to send again, and when each was made and last changed.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `url` | `string` |  |
| `mimeType` | `string` |  |
| `id` | `string | null` |  |
| `sizeBytes` | `number | null` |  |
| `kind` | `"image" | "audio" | "video" | "file"` |  |
| `voice` | `boolean` |  |
| `durationMs` | `number | null` |  |
| `peaks` | `number[] | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `createdAt` | `Date | null` | When it was made: one of the account's files has it; a file on a message has none. |
| `updatedAt` | `Date | null` | When it last changed, as `createdAt`. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## Terminal

```typescript
class Terminal
```

A coding agent's conversation as its harness's own terminal. While it's taken over the agent's messages wait; it
hands itself back after `idleLimitS` with nobody typing, `detachedLimitS` with no terminal open, or at `endsAt`
(its sandbox's time limit). From `agent.takeOver` it carries a single-use `token` for `url`, valid two minutes:
`connect()` once; take over again (it's idempotent while taken over) for a new one.

| Attribute | Type | Description |
| --- | --- | --- |
| `agentId` | `string` |  |
| `conversation` | `string` |  |
| `harness` | `string` | `claude_code` or `codex`. |
| `state` | `TerminalState` | `agent`, `taking_over`, `person` or `handing_back`. |
| `waitingForTurn` | `boolean` | Taken over once the agent's turn in flight ends. |
| `since` | `Date | null` | When it was taken over. |
| `endsAt` | `Date | null` | When it hands itself back at the latest: its sandbox's time limit. |
| `idleLimitS` | `number | null` | It hands itself back after this long with nobody typing. |
| `detachedLimitS` | `number | null` | It hands itself back after this long with no terminal open. |
| `endedBecause` | `TerminalEnd | null` | Why the last take-over ended. |
| `url` | `string | null` | The terminal's websocket (from `takeOver` only). |
| `token` | `string | null` | Opens `url` once, within two minutes (from `takeOver` only). |
| `tokenExpiresAt` | `Date | null` |  |

Types:

```typescript
/**
 * `agent` (the agent has it), `taking_over` (its turn in flight finishes first), `person` or `handing_back`; a
 * sandbox shell's (`AgentSandbox.shell`) is `open`, then `exited` as it closes.
 */
type TerminalState = "agent" | "taking_over" | "person" | "handing_back" | "open" | "exited";

/** Why a take-over (or a sandbox shell) ended: asked (`handed_back`, `canceled` while it waited), or by itself. */
type TerminalEnd = "handed_back" | "canceled" | "idle" | "detached" | "exited" | "deadline" | "failed";
```

### Terminal.handBack

```typescript
handBack(): Promise<this>
```

Give the conversation back to the agent: the terminal closes, what was said in it joins the conversation's
history (`via: "terminal"`), and the messages that waited reach the agent.

Returns: This terminal, as it is now (`agent`, or `handing_back` while its program exits).

### Terminal.connect

```typescript
connect(options?: TerminalConnectOptions): TerminalConnection
```

Open the terminal: once per token (`takeOver` again for another).

Parameters:

- `options.cols` (`number`): The terminal's size as it opens (else the one `takeOver` was given).
- `options.rows` (`number`)
- `options.onData` (`(data: Uint8Array) => void`): What the terminal prints, as it prints it.
- `options.onReady` (`(status: TerminalStatus) => void`): It's open: what the person types reaches the terminal from now.
- `options.onState` (`(status: TerminalStatus) => void`): The take-over moved (`person`, `handing_back`, then `agent` as it closes).
- `options.onClose` (`(event: { code: number; reason: string; final: boolean }) => void`): It closed: `final` when it won't open again with this take-over (handed back, nothing running, or a used token);
otherwise take over again for a new token and connect.
- `options.renew` (`() => Promise<string>`): A new token for this same terminal. With one, the connection says it renews as it opens, and lasts 15 minutes
at a time: the server asks for a new token in the last minute, and without an answer it closes with
`TERMINAL_RENEW`. `Terminal.connect` takes over again and `SandboxShell.connect` asks for the shell again by
themselves; for a machine's shell, `async () => (await machine.shell()).token`. Without one, it has no
lifetime.
- `options.WebSocket` (`typeof WebSocket`): A WebSocket class, where the runtime has none of its own (Node before 22).

Types:

```typescript
/** Where the take-over stands, as the terminal's connection reports it. */
interface TerminalStatus {
  state: TerminalState;
  reason: TerminalEnd | null;
  raw: JsonObject;
}

/**
 * `agent` (the agent has it), `taking_over` (its turn in flight finishes first), `person` or `handing_back`; a
 * sandbox shell's (`AgentSandbox.shell`) is `open`, then `exited` as it closes.
 */
type TerminalState = "agent" | "taking_over" | "person" | "handing_back" | "open" | "exited";

/** Why a take-over (or a sandbox shell) ended: asked (`handed_back`, `canceled` while it waited), or by itself. */
type TerminalEnd = "handed_back" | "canceled" | "idle" | "detached" | "exited" | "deadline" | "failed";

type JsonObject = { [key: string]: unknown };
```

## attachments

```typescript
function attachments(options?: AttachmentsOptions): Promise<Attachment[]>
```

The account's files, newest first: what its messages carried, the images and videos it made, its calls'
recordings, what its browsers downloaded and the pages they stopped on, each `url` a link that reads it for an
hour. A message to an agent sends any of them again in its
`files`. The account's alone: read as a user, it's refused.

    const [report] = await attachments({ query: "q3" });
    await analyst.message("What changed since this?", { files: [report] });

Parameters:

- `options.query` (`string`): Keeps the files whose names contain it (any case).
- `options.limit` (`number`): How many, 1 to 100 (30 by default).
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: Each file as an `Attachment` with its `id`, `name`, `url` (a link that reads it for an hour),
`mime_type` and `kind`.

## attachmentsPage

```typescript
function attachmentsPage(
  options?: Omit<AttachmentsOptions, "limit"> & PageOptions,
): Promise<Page<Attachment>>
```

One page of the account's files, newest first; pass `nextCursor` back as `cursor`.

    let page = await attachmentsPage({ limit: 50 });
    for (;;) {
      for (const file of page.data) console.log(file.name, file.sizeBytes);
      if (!page.nextCursor) break;
      page = await attachmentsPage({ limit: 50, cursor: page.nextCursor });
    }

Parameters:

- `options.query` (`string`): Keeps the files whose names contain it (any case).
- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: A page whose `data` holds each `Attachment` and whose `next_cursor` is `None` on the last page.

## deleteAttachment

```typescript
function deleteAttachment(
  attachment: Attachment | string,
  options?: { client?: NoClick },
): Promise<void>
```

Delete one of the account's files for good (an `Attachment` or its id): its record and what it stored, with no
trash to restore it from. A message that carried it keeps its name, and its link stops working. The account's own
to do: acting for one of your users, or from an app's code, it's refused.

    for (const file of await attachments({ query: "draft" })) await deleteAttachment(file);

Parameters:

- `attachment` (`Attachment | string`, required)
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
