Agent

Agents: hosted agents you message by name.

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.

Attributes
idstring
originAgentOrigin | null

api for an agent made through the API, app for one built in the NoClick app (an id like node:<workflow>:<node>).

namestring
modelstring | null

The model it runs, as its harness names it (sonnet, openrouter/...).

harnessHarnessName | null

What runs it: sdk, claude_code, codex, opencode, hermes or openclaw.

modelConnectionstring | 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.

instructionsstring | 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.

toolRulesToolRules

What it may do with each app it reaches (ToolRules); empty, everything its tools give is allowed.

canRequeststring[]

What it may ask its user to connect at run time.

userIdstring | null
workflowIdstring | null
nodeIdstring | null

An app agent's step in its workflow (null for an API agent).

workflowNamestring | null

An app agent's workflow, by name.

accessstring | 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).

enabledboolean | null

Whether an app agent is switched on; a disabled one takes no messages.

appUrlstring | null

Where an app agent is changed: its workflow in the NoClick app.

parentIdstring | null

Its parent, whose budget it draws on.

ttlSnumber | null

The time to live it was created with, in seconds (null if it isn't temporary); expiresAt is when it runs out.

expiresAtDate | null

When a temporary agent expires (null if it isn't): it then stays readable, expired, for 30 days.

budgetUsdPerMonthnumber | null
regionRegionName | null

The region its sandboxes run in, fixed when it was created; null: wherever NoClick has capacity.

machineIdstring | null

Invite-only beta. The Machine its harness runs on (null: a sandbox of its own).

createdAtDate | null
browserProfileIdstring | null

The browser profile its browser tool signs in with.

cardIdstring | null

Invite-only beta. The card it holds and pays with (null: none of its own).

volumesRecord<string, string>

The volumes its shell mounts: { path: volume id }.

memoryIdstring | 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).

secretIdsstring[]

The secrets in its shell's environment, in order (a later one's key wins).

timezonestring | null

The IANA timezone its turns tell the time in (null: the acting user's, else UTC).

reposJsonObject[]

The repositories cloned into its workspace: each its connection, repository, branch, path and push globs.

setupstring[]

Commands its sandbox (its container, on a machine) runs as it starts, after its repos and before its harness.

dockerboolean

Whether Docker runs in its sandbox, a VM of sandboxSize (a coding harness only).

sandboxSizeSandboxSize | null

The VM a Docker agent works in; null without Docker.

appTestingAppTesting

How it may turn Docker on for a task that needs it (AppTesting).

appTestingUsdPerHournumber | null

What an hour of app testing costs where its sandbox runs; null without a sandbox of its own.

movedFromAgentMovedFrom | null

Where a move from a laptop made it (its move, machine, folder and when); null otherwise.

networkNetworkAccess | 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.

shellboolean | null

Whether it has a shell (the code capability; false only on sdk).

turnLimitsTurnLimits | null

How far one of its turns goes, as set (null, or a limit left out: 200 steps, $1 and 30 minutes).

effortstring | null

Its conversations' reasoning effort (null: the model's own).

speed"standard" | "fast"

fast: its conversations run in fast mode.

permissionModePermissionMode

How far its coding harness goes before asking a person where a conversation sets nothing.

statusAgentStatus | 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.

lastActiveAtDate | null

When a turn of its last started or ended (null: it never ran, or hidden like status).

runningTurnsnumber | null

How many of its turns are queued, running or waiting on a person, any conversation (null: hidden like status).

childCountnumber | null

How many live (not expired) children it has (children() lists them; null: hidden like status).

jobIdstring | null

The task it was spawned with (its operation id), or null.

usedByUsedBy[]

The apps that bind it: kind (project), id, name and the binding name.

pausedboolean

Whether pause() stopped its triggers (false too for a user reading an account agent).

helperboolean

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.

noclickboolean

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>).

formerNamesstring[]

The names it went by before it was renamed, the latest first. Each still reaches it (agent:<old name>, fromName, an

jobJob | null

The task it was spawned with, as a Job to wait on, or null.

triggerKindsstring[]

The kinds of its triggers (cron, webhook, event, platform, email, call); an agent with cron is an automation.

consoleUrlstring | null

This agent in the developer console (null off the hosted API).

a2aUrlstring

The A2A JSON-RPC endpoint (message/send, tasks/get); callers authenticate with a platform key as a bearer token.

memoryAgentMemory

What it remembers across conversations: list, search, read, save and delete named entries.

Types
/** 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";

/** 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;
}

createstatic

static create(
  name: string,
  options: AgentCreateOptions & 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
namestringrequired
options.instructionsstringrequired
options.modelstring

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.harnessHarnessName

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.modelConnectionstring | 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.toolsAgentTools
options.toolRulesToolRules

What it may do with each app it reaches (ToolRules). In update, {} clears them.

options.ttlSnumber

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.budgetUsdPerMonthnumber | 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 IntegrationInfos), single "integration.operation"s, or "*". What the user connects is a grant (grants()), kept apart from the agent's fields.

options.triggersTriggerDefinition[]

What wakes it without a message: OnWebhook, OnEvent, OnPlatformEvent, Cron and OnQueue.

options.browserProfilestring | 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.cardstring | Card | nullinvite-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.volumesRecord<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.secretsSecretRef[]

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.timezonestring | 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.reposRepoCheckout[]

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.networkNetworkAccess

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.shellboolean

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.regionRegionName

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.machinestring | Machine | nullinvite-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.memoriesMemoryRef[]

The Memorys 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.skillsSkillRef[]

The Skills 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.turnLimitsTurnLimits | 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.effortstring | 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.speedAgentSpeed | null

fast runs its model in its harness's fast mode where it has one (speeds). In update, null clears it.

options.permissionModePermissionMode | 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.setupstring[]

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.dockerboolean

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.sandboxSizeSandboxSize | null

The VM a Docker agent works in (SandboxSize; small unless it says). In update, null is small again.

options.appTestingAppTesting

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.allowExistingboolean

A taken name returns the object already there, as it is: nothing about it changes.

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

options.parentstring | 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
/** 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";

/**
 * 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>;
}

fromNamestatic

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
namestringrequired
options.createIfMissingboolean
options.instructionsstring
options.modelstring

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.harnessHarnessName

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.modelConnectionstring | 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).

(omit to leave it unchanged)
options.toolsAgentTools
options.toolRulesToolRules

What it may do with each app it reaches (ToolRules). In update, {} clears them.

options.ttlSnumber

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.budgetUsdPerMonthnumber | null

In fromName, null clears it, as browserProfile and card do.

(omit to leave it unchanged)
options.canRequest(string | { name: string })[]

What it may ask its user to connect at run time (a request_connection tool): integration names (or IntegrationInfos), single "integration.operation"s, or "*". What the user connects is a grant (grants()), kept apart from the agent's fields.

options.triggersTriggerDefinition[]

What wakes it without a message: OnWebhook, OnEvent, OnPlatformEvent, Cron and OnQueue.

options.browserProfilestring | 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.

(omit to leave it unchanged)
options.cardstring | Card | nullinvite-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.

(omit to leave it unchanged)
options.volumesRecord<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.secretsSecretRef[]

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.timezonestring | 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.

(omit to leave it unchanged)
options.reposRepoCheckout[]

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.networkNetworkAccess

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.shellboolean

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.regionRegionName

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.machinestring | Machine | nullinvite-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.memoriesMemoryRef[]

The Memorys 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.skillsSkillRef[]

The Skills 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.turnLimitsTurnLimits | 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.

(omit to leave it unchanged)
options.effortstring | 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.

(omit to leave it unchanged)
options.speedAgentSpeed | null

fast runs its model in its harness's fast mode where it has one (speeds). In update, null clears it.

(omit to leave it unchanged)
options.permissionModePermissionMode | 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.

(omit to leave it unchanged)
options.setupstring[]

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.dockerboolean

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.sandboxSizeSandboxSize | null

The VM a Docker agent works in (SandboxSize; small unless it says). In update, null is small again.

options.appTestingAppTesting

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.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

options.parentstring | 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
/** 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";

/**
 * 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>;
}

fromIdstatic

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

A lazy reference to an agent by NoClick id.

Parameters
agentIdstringrequired
options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
Returns

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

Types
/** `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>;
}

getstatic

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

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

Parameters
agentIdstringrequired
options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

The agent, loaded.

Types
/** `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>;
}

liststatic

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.namestring
options.statusAgentStatus

Only agents with this status.

options.activeSinceDate | string

Only agents with a turn since then.

options.parentstring | Agent

Only the children of this agent (an Agent or id).

options.temporaryboolean

true: only agents with a ttlS; false: only agents without one.

options.harnessHarnessName

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.originAgentOrigin

Only agents made through the API (api) or built in the NoClick app (app).

options.limitnumber

Return at most this many.

options.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.clientNoClick

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
/**
 * `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;

listPagestatic

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

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

Parameters
options.cursorstring | null

The next_cursor of the page before; omit it for the first page.

options.limitnumber

Return at most this many.

options.namestring
options.statusAgentStatus

Only agents with this status.

options.activeSinceDate | string

Only agents with a turn since then.

options.parentstring | Agent

Only the children of this agent (an Agent or id).

options.temporaryboolean

true: only agents with a ttlS; false: only agents without one.

options.harnessHarnessName

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.originAgentOrigin

Only agents made through the API (api) or built in the NoClick app (app).

options.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.clientNoClick

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
/**
 * `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;

codingstatic

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.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns
Types
/**
 * 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;

statesstatic

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.workspacestring
options.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

An AgentStateRow per agent.

Types
/**
 * 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 };

harnessesstatic

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.clientNoClick

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.

harnessInfostatic

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
namestringrequired
options.clientNoClick

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.

upload

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
fileFileInputrequired
options.namestring

The file's name (a File has its own).

options.mimeTypestring

Its type (a Blob has its own; else read from the name).

options.voiceboolean

A recorded voice clip (audio).

options.peaksnumber[]

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
/** What to upload: bytes, or a `Blob` / `File` (its `name` and `type` are used when not given). */
type FileInput = Blob | Uint8Array | ArrayBuffer;

send

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
textstring | nullrequired
options.conversationstring | null
options.files(Attachment | string)[]
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
options.commandAgentCommandInput
options.deliveryMessageDelivery
Returns

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

Types
/** `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";

commands

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
conversationstringrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
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
/** `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>;
}

setPermissionMode

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
conversationstringrequired
modePermissionModerequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
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
/** 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>;
}

requests

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
conversationstringrequired
options.statusHarnessRequest["status"]
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

answer

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
conversationstringrequired
requestIdstringrequired
decisionRequestDecisionrequired
options.notestring
options.answersRecord<string, string | string[]>
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** 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>;
}

message

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
textstringrequired
options.conversationstring | null
options.files(Attachment | string)[]
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
options.timeoutSnumber
Returns

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

Types
/** `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>;
}

history

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
conversationstringrequired
options.limitnumber

The newest this many (1-200), oldest first; every message when omitted.

options.beforestring

Just before this cursor: a nextCursor of historyPage.

options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
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
/** `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>;
}

historyPage

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
conversationstringrequired
options.limitnumber

The newest this many (1-200), oldest first; every message when omitted.

options.beforestring

Just before this cursor: a nextCursor of historyPage.

options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
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
/** `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>;
}

note

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
conversationstringrequired
textstringrequired
options.dataJsonObject
options.keystring
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
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>;
}

withdrawQuestion

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
conversationstringrequired
notestringrequired
options.questionIdstring
Returns

The text of each question withdrawn.

conversation

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
namestringrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Types
/** `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>;
}

startConversation

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.conversationstring
options.titlestring
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

The new Conversation, active.

Types
/** `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>;
}

clear

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.titlestring
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

The new Conversation, active.

Types
/** `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>;
}

session

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.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

conversations

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.limitnumber

Return at most this many.

options.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.archivedboolean
options.clientNoClick
Returns

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

Types
/**
 * 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;

conversationsPage

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

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

Parameters
options.cursorstring | null

The next_cursor of the page before; omit it for the first page.

options.limitnumber

Return at most this many.

options.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.clientNoClick
options.archivedboolean
Returns

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

Types
/**
 * 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;

handBack

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
conversationstringrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Types
/** `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>;
}

takeOver

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
conversationstringrequired
options.interruptboolean
options.colsnumber
options.rowsnumber
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

terminal

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
conversationstringrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

spawn

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
taskstringrequired
options.updatesUpdateSpec[]

When NoClick makes the child report, beside "done" (always on): "blocked", new Before(...), new Every(...).

options.conversationstring

The parent's conversation its updates wake; without one they wake nobody and wait on the job.

options.instructionsstring

The child's standing instructions: what its updates should say, and when to reach out freely.

options.toolsAgentTools

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.budgetUsdnumber

Its budget, held out of what its parent's has left; omitted, it draws on its parent's as it spends.

options.ttlSnumber

It expires this many seconds after it's made.

options.modelstring

The parent's model when omitted.

options.harnessHarnessName

The parent's harness when omitted.

options.modelConnectionstring | Connection

The parent's model connection when omitted.

options.namestring

<parent>-<8 hex> when omitted.

options.userUserOption

Whose conversation conversation is (an account parent talking to a user: that user's thread).

(defaults to the current user)
Returns

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

Types
/**
 * 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";

/** `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>;
}

children

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.statusAgentStatus
options.limitnumber

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
/**
 * `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";

jobs

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.statusOperationStatus | "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.agentstring | Agent

The agent doing the work (an Agent or id).

options.conversationstring

The parent's conversation that started them.

options.limitnumber

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
type OperationStatus =
  | "queued" | "running" | "awaiting_human"
  | "succeeded" | "failed" | "canceled" | "expired";

ask

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
questionstringrequired
options.conversationstring
options.interjectboolean
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
options.timeoutSnumber
Returns

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

Types
/** `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>;
}

a2aCard

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
type JsonObject = { [key: string]: unknown };

update

update(
  changes: Omit<AgentFields, "modelConnection"> & { name?: string; budgetUsdPerMonth?: number | null; modelConnection?: string | Connection | null; } & Pick<AgentCreateOptions, "timezone" | "repos" | "network" | "shell" | "browserProfile" | "card" | "machine" | "memories" | "skills" | "turnLimits" | "secrets">,
): 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.

Parameters
changesOmit<AgentFields, "modelConnection"> & { name?: string; budgetUsdPerMonth?: number | null; modelConnection?: string | Connection | null; } & Pick<AgentCreateOptions, "timezone" | "repos" | "network" | "shell" | "browserProfile" | "card" | "machine" | "memories" | "skills" | "turnLimits" | "secrets">required
Returns

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

Types
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;
  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";

/**
 * 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";

grants

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).

toolAccess

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.

revokeGrant

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
grantstring | AgentGrantrequired

delete

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.

wake

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.

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
conversationstringrequired
options.notestringrequired

What the turn is told, 1 to 4,000 characters.

options.atDate | string

A moment: a Date, or an ISO 8601 string with its offset.

options.whenOperation<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.filtersJsonObject

With an event when: dotted paths into the event's data that must equal these values.

options.everyCron

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.userUserOption

Whose conversation it is, as message() takes it.

(defaults to the current user)
options.afterSnumber

This many seconds from now.

Returns

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

Types
/** `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 };

wakeups

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.statusWakeupStatus
options.limitnumber

Return at most this many.

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)
options.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.clientNoClick
options.conversationstring
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
/**
 * 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";

triggers

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.

addTrigger

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
triggerTriggerDefinitionrequired
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
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;

updateTrigger

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
triggerAgentTrigger | string | TriggerDefinitionrequired
changesTriggerChangesrequired
Returns

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

Types
/** 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 };

pauseTrigger

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
triggerAgentTrigger | string | TriggerDefinitionrequired
Returns

The trigger as it is now (paused is True).

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

resumeTrigger

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
triggerAgentTrigger | string | TriggerDefinitionrequired
Returns

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

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

removeTrigger

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
triggerAgentTrigger | string | TriggerDefinitionrequired
Types
/** What an agent's `triggers` take: a schedule, a webhook, an app event or a queue. */
type TriggerDefinition = Cron | OnWebhook | OnEvent | OnPlatformEvent | OnQueue;

toolServers

toolServers(): Promise<AgentToolServer[]>

Its MCP servers, each a step of its automation. In its automation's order; whether one connected is a conversation's: agent.conversation(name).toolServers().

Returns

A list of AgentToolServer, in its automation's order.

addToolServer

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). A server that asks its client to sign in throws InvalidRequest (needs_sign_in) unless 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. Up to 20. Returns the AgentToolServer as added: its id is what removeToolServer takes.

Parameters
urlstringrequired
options.namestring
options.transport"http" | "sse"default "http"
options.credentialstring
options.headersRecord<string, string>
Returns

The AgentToolServer as added: its id (what remove_tool_server takes), name, url, whether it's signed_in and its headers' names.

updateToolServer

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
serverstring | AgentToolServerrequired
headersRecord<string, string>required
Returns

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

removeToolServer

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
serverstring | AgentToolServerrequired

rehearseTrigger

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
triggerAgentTrigger | string | TriggerDefinitionrequired
options.sampleunknown
Returns

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

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

inboxes

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.

pause

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.

resume

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.

workspace

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
conversationstring
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

sandbox

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
conversationstring
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

share

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.

stream

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
textstringrequired
options.conversationstring | null
options.files(Attachment | string)[]
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
options.signalAbortSignal
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
/** `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>;
}

watch

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
conversationstringrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
options.replayboolean
options.signalAbortSignal
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
/** `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>;
}

rehearse

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
messagestringrequired
options.scenariostring
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
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
/** `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

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" });
Attributes
namestring

The conversation's key.

settings

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.

update

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
changesConversationChangesrequired
Returns

Its ConversationSettings after the change.

Types
/**
 * 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";

fork

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.messagestring
options.titlestring
Returns

The new Conversation, with forked_from.

resume

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.

revert

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
messagestringrequired
options.filesboolean
Returns

A ConversationRevert, whose text is the message's.

context

context(): Promise<ConversationContext>

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

usage

usage(): Promise<ConversationUsage>

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

toolServers

toolServers(): Promise<ToolServers>

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

Returns

reconnectToolServer

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
namestringrequired
Returns

A ToolServers, as it stands after the reconnect started.

messageSubagent

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
callIdstringrequired
textstringrequired
Returns

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

runCommand

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
namestringrequired
argsstringdefault ""
options.deliveryMessageDelivery
Returns

A CommandResult, or the command's Operation.

Types
/**
 * 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

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.

Attributes
agentIdstring
namestring
harnessHarnessName
stateAgentState
conversationstring | null
nowAgentNow | null
waiting{ asks: number; heldCalls: number; requests: number; total: number }
turnStartedAtDate | null
lastActiveAtDate | null
failed{ message: string; at: Date | null } | null
waking{ at: Date | null; why: string } | null
rawJsonObject

The response JSON exactly as the API sent it.

Types
/** 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;
}

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

CommandResult

interface CommandResult

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

Attributes
controlstring
command{ name: string; arguments: string }
resultJsonObject

The control's answer: conversation settings, a new conversation, its context, its usage, or an operation.

rawJsonObject

The response JSON exactly as the API sent it.

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

ConversationContext

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.

Attributes
modelstring | null
usedTokensnumber | null
windowTokensnumber | null
percentnumber | null
autoCompactsAtnumber | null
source"harness" | "noclick" | null
asOfDate | null
rawJsonObject

The response JSON exactly as the API sent it.

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

ConversationRevert

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.

Attributes
conversationstring
messagestring
textstring
droppedTurnsnumber
files{ restored: string[]; kept: string[]; notRestored: { path: string; why: string }[]; commandsNotUndone: number }
filesApplied"next_turn" | null
agentReads"native" | "context"
rawJsonObject

The response JSON exactly as the API sent it.

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

AgentToolServer

interface AgentToolServer

An MCP server an agent has as tools: a step of its automation (id, what removeToolServer takes), reached at its url over transport (http or sse), signedIn where a sign-in to it is set, sending the headers named (their values are never read back).

Attributes
idstring
namestring
urlstring | null
transport"http" | "sse"
signedInboolean
headersstring[]
rawJsonObject

The response JSON exactly as the API sent it.

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

ConversationUsage

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.

Attributes
costUsdnumber
modelUsageModelUsage | null
turnsnumber
paysWith"noclick" | "key" | "plan"
planLimitsPlanLimit[]
rawJsonObject

The response JSON exactly as the API sent it.

Types
/** 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

interface ToolServer

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

Attributes
namestring
status"connected" | "connecting" | "failed"

connected, connecting (its handshake hasn't finished) or failed.

toolCountnumber | null

How many tools it offers the model, where the harness says (null where it doesn't).

errorstring | null

Why it failed, in the harness's or the server's words.

ToolServers

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.

Attributes
serversToolServer[]
source"live" | "last_turn" | "none"
checkedAtDate | null
reconnect{ available: boolean; scope: "server" | "all" | null; why: string | null }
rawJsonObject

The response JSON exactly as the API sent it.

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

AgentCommand

interface AgentCommand

One command a conversation's harness offers.

Attributes
namestring
descriptionstring
argumentHintstring

What its arguments look like (<instructions>, [env]), empty when it names none.

sourceAgentCommandSource
aliasesstring[]

Other names it answers to.

Types
/** 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

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).

Attributes
harnessstring
commandsAgentCommand[]
skillsAgentSkill[]
capabilitiesRecord<string, boolean>

commands, skills, compact, review, goal, init, steer, queue.

notSupportedRecord<string, string>

What NoClick can't run on this harness, and why.

withheldstring[]

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.

asOfDate | null
readFrom"this_conversation" | "another_conversation" | null
rawJsonObject

The response JSON exactly as the API sent it.

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

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

AgentGrant

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.

Attributes
idstring
connectionstring
integrationstring
operationsstring[] | null
status"requested" | "active"
reasonstring | null
conversationstring | null
createdAtDate | null
grantedAtDate | null
rawJsonObject

The response JSON exactly as the API sent it.

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

ConversationSettings

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.

Attributes
permissionModePermissionMode
effectivePermissionModePermissionMode
permissionModesPermissionMode[]
notSupportedRecord<string, string>
rawJsonObject

The response JSON exactly as the API sent it.

conversationstring
titlestring | null
archivedboolean
harnessHarnessName | null
modelstring | null
effortstring | null

null: the model's own default (defaultEffort, when the harness says it).

effortsstring[]

The efforts its harness takes on its model, weakest first, in the harness's own words ([]: none).

defaultEffortstring | null
speedAgentSpeed
speedsAgentSpeed[]

["standard", "fast"] where its harness has a fast mode on its model; [] where it has none.

modelConnectionstring | null
accountsModelAccount[]

What can pay for it: each {name, integration, kind (key, plan or noclick), connected, usable, why}.

overriddenstring[]

What the conversation sets itself: its permission_mode.

forkedFromForkedFrom | null

{conversation, message, through}: what it was forked from (through: its own last copied message).

Types
/** 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

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).

Attributes
idstring
kind"approval" | "question"
status"pending" | "answered" | "expired" | "canceled"
actionstring | null
titlestring | null
detailstring | null
planstring | null
questionsJsonObject[]
options{ optionId: string; name: string; kind: string }[]
answerJsonObject | null
operationIdstring | null
createdAtDate | null
expiresAtDate | null
rawJsonObject

The response JSON exactly as the API sent it.

decisionstring | null

What it was answered with (allow_once, reject_once, …) and when; null until it's answered.

answeredAtDate | null
canceledReasonstring | null

Why it was closed unanswered: its turn ended first (failed, stopped, timed out).

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

AgentReply

interface AgentReply

The agent's answer to one message.

Attributes
textstring
conversationstring | null

Pass back as conversation to continue the same thread.

toolCallsJsonObject[]

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.

operationIdstring | null
rawJsonObject

The response JSON exactly as the API sent it.

modelUsageModelUsage | null

The turn's model calls on your own key or plan (null on NoClick's key, whose cost is its cost_usd).

endedByTurnLimitName | 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.

stepsAgentStep[]

toolCalls as AgentSteps.

Types
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

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.

Attributes
kindAgentStepKind
toolstring
callIdstring | null
source"harness" | (string & {}) | null
argumentsJsonObject
commandstring | null
pathstring | null
querystring | null
outputstring | null
exitCodenumber | null
durationMsnumber | null
isErrorboolean
resultunknown
diffsAgentStepDiff[]
createdAtDate | null
rawJsonObject

The response JSON exactly as the API sent it.

Types
/** 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 };

AgentStepDiff

interface AgentStepDiff

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

Attributes
pathstring
change"add" | "update" | "delete" | (string & {}) | null
diffstring

Conversation

interface Conversation

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

Attributes
conversationstring

Pass as conversation to continue it, or to history().

userIdstring | null
titlestring | null
previewstring | null
turnsnumber | null
costUsdnumber | null
lastActivityDate | null
rawJsonObject

The response JSON exactly as the API sent it.

statusConversationStatus | null

active, awaiting_human (a turn waits on a person: its question, a held call, a sign-in) or handed_off.

handedOffTostring | null

Who a handed_off conversation is with: the person's email or phone.

modelUsageModelUsage | null

Its model calls on your own key or plan, all turns together (null on NoClick's key).

lastMessageLastMessage | null

Its newest message (null before any).

peopleMessageAuthor[]

Who is in it: the people who wrote in it, the thread's own person first.

archivedboolean
forkedFromForkedFrom | 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.

activeboolean

Whether it's the agent's session now, the one conversation everyone talking to it shares; the others can be resumed.

Types
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

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).

Attributes
rolestring
textstring
createdAtDate | null
rawJsonObject

The response JSON exactly as the API sent it.

filesAttachment[]

The files it carried (a user message's, sent with files).

toolCallsJsonObject[]

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).

viaMessageVia | null

How a user message arrived when not through the API (null otherwise).

dataJsonObject | null

A note's data, as agent.note added it.

triggerMessageTrigger | null

What started the turn of a user message no person sent (null for one someone sent).

reasoningReasoningLine[]

A reply's reasoning, as its turn's reasoning events showed it.

operationIdstring | null

The turn it belongs to (an agent.message operation's id; null for a message no turn sent, like a person's).

commandAgentCommandInput | null

The harness command a user message ran in place of text (null for a message).

idstring | null

Its place in the thread, which stays (a revert marks, never removes): pass it to forkConversation or revertConversation.

authorMessageAuthor | 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.

notificationboolean

An agent's message to its owner from another of its conversations (a human__notify that joined this thread).

spaceMessageSpace | null

A notification passing on a space's news: the space it's from (null otherwise).

subagentMessageSubagent | null

A user message written for one of its coding harness's subagents: which one (null otherwise).

chatstring | 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).

stepsAgentStep[]

toolCalls as AgentSteps.

Types
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

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.

Attributes
nameHarnessName

What harness takes.

labelstring | null
versionstring | null

The version NoClick runs (null for sdk).

defaultModelstring

The model an agent on it gets when you give none.

customModelsboolean

Whether model also takes models models() doesn't offer.

modelConnection"required" | "optional"

required for every CLI harness, optional for sdk.

integrationsstring[]

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.

notesstring[]

What to know before choosing it (a model that needs a particular key, say).

rawJsonObject

The response JSON exactly as the API sent it.

effortsstring[]

The reasoning efforts it takes on its default model, weakest first ([]: none); a conversation's settings list its model's.

defaultEffortstring | null

The effort it runs at when none is set (null: the model's own).

speedsAgentSpeed[]

["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.

permissionModesPermissionMode[]

The permission modes it enforces ([]: none, as on sdk), and why it runs the others as another.

notSupportedRecord<string, string>
Types
/** 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";

models

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.limitnumber

Return at most this many.

options.searchstring
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

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.

Attributes
idstring
labelstring | null
canonicalstring
routeHarnessModelRoute
noclickKeyHarnessModelPrice | 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
/** 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

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.

Attributes
inputTokensnumber
outputTokensnumber
cachedTokensnumber
usdnumber
rawJsonObject

The response JSON exactly as the API sent it.

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

AgentToolAccess

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.

Attributes
mode"everything" | "restricted"
listedboolean
rulesToolRules
sinceDate | null
appsAgentToolApp[]
rawJsonObject

The response JSON exactly as the API sent it.

Types
/**
 * 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

interface AgentToolApp

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

Attributes
keystring | null

Its rule key; null for the web, whose two actions (search, fetch) are keys of their own.

appstring
kind"connection" | "integration" | "noclick" | "web"
integrationstring | null
credentialTypestring | null
labelstring
accountstring | null

The account it's connected as (else its name), or what it does for NoClick and the web.

statusConnectionStatus | null
onboolean

Whether anything of it may run.

callsnumber
actionsAgentToolAction[]
Types
/**
 * `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

interface AgentToolAction

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

Attributes
keystring
actionstring
titlestring
groupstring | 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).

verdictToolRule
canAskboolean

False where ask can't hold it (reading never waits for a person).

callsnumber

Its calls that ran since since.

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

AgentMemory

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.

list

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.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
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
/** `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>;
}

search

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
querystringrequired
options.limitnumber

Return at most this many.

options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
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
/** `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>;
}

read

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

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

Parameters
namestringrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

save

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
namestringrequired
contentstringrequired
options.descriptionstring
options.versionnumber
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

The entry as saved, with its new version.

Types
/** `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>;
}

delete

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
namestringrequired
options.versionnumber
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Types
/** `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>;
}

versions

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
namestringrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

getVersion

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
namestringrequired
versionnumberrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

That version in full.

Types
/** `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>;
}

restore

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
namestringrequired
versionnumberrequired
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

The entry as restored, at its new version.

Types
/** `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>;
}

entries

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

list, as Memory calls it.

Parameters
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Returns

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

Types
/** `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>;
}

forget

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

delete, as Memory calls it.

Parameters
namestringrequired
options.versionnumber
options.userUserOption

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
Types
/** `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

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.

Attributes
namestring
descriptionstring
contentstring | null
versionnumber
updatedAtDate | null
updatedBy"agent" | "api" | "console" | null
writtenByMemoryWriter

Who last wrote it: for an agent, which one and in which of its conversations.

userIdstring | null
conversationstring | null
rawJsonObject

The response JSON exactly as the API sent it.

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

MemoryEntryVersion

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.

Attributes
namestring
versionnumber
currentboolean
descriptionstring
contentstring | null
writtenByMemoryWriter
userIdstring | null
savedAtDate | null
rawJsonObject

The response JSON exactly as the API sent it.

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

MemoryWriter

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.

Attributes
type"agent" | "api" | "console" | null
agentIdstring | null
agentNamestring | null
conversationstring | null

AgentWorkspace

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.)

Attributes
conversationstring | undefined

The conversation it was named by, if any: accepted and ignored, since an agent has one workspace.

files

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.

read

read(path: string): Promise<Uint8Array>

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

Parameters
pathstringrequired
Returns

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

write

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
pathstringrequired
datastring | Uint8Arrayrequired
Returns

The file as stored, with its download url.

delete

delete(path: string): Promise<void>

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

Parameters
pathstringrequired

url

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
pathstringrequired
options.expiresInSnumber
Returns

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

WorkspaceFile

interface WorkspaceFile

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

Attributes
pathstring

Relative to /workspace.

sizeBytesnumber
modifiedAtDate | null
urlstring | null
rawJsonObject

The response JSON exactly as the API sent it.

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

AgentSandbox

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);
Attributes
conversationstring | undefined

The conversation it was named by; none reads it through the agent's session.

get

get(): Promise<ConversationSandbox>

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

files

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
pathstringdefault "/workspace"
options.recursiveboolean

Everything below the folder, not just what's in it (git's objects left out unless listed by their path).

options.limitnumber

Return at most this many.

Returns

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

filesPage

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

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

Parameters
pathstringdefault "/workspace"
options.recursiveboolean

Everything below the folder, not just what's in it (git's objects left out unless listed by their path).

options.cursorstring | null

The next_cursor of the page before; omit it for the first page.

options.limitnumber

Return at most this many.

read

read(path: string): Promise<Uint8Array>

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

Parameters
pathstringrequired
Returns

The file's bytes; decode text yourself.

exec

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
commandstringrequired
options.timeoutSnumber
Returns

Its stdout, stderr (the last 64 KiB of each) and exit_code.

shell

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. 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

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.

Attributes
agentIdstring
conversationstring
harnessHarnessName
placeSandboxPlace
status"running" | "stopped"
startedAtDate | null
cpunumber | null
memoryMbnumber | null
regionstring | null
usdPerHournumber | null
spentUsdTodaynumber | null
machineIdstring | null
projectIdstring | null
workspacestring | null
rawJsonObject

The response JSON exactly as the API sent it.

Types
/** 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

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.

Attributes
source"sandbox" | "workspace"

SandboxShell

class SandboxShell

A shell on a conversation's sandbox (AgentSandbox.shell): connect() opens it, once per token.

Attributes
agentIdstring
conversationstring
urlstring

The terminal websocket it opens on.

tokenstring

Opens url once, within two minutes: its first message's token.

tokenExpiresAtDate | null
idleLimitSnumber | null

It closes after this long with nothing typed.

rawJsonObject

The response JSON exactly as the API sent it.

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

connectTypeScript only

connect(options?: TerminalConnectOptions): TerminalConnection

Open the shell: onState hears exited (and why) as it ends, and it closes for good (final).

Parameters
options.colsnumber

The terminal's size as it opens (else the one takeOver was given).

options.rowsnumber
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.WebSockettypeof WebSocket

A WebSocket class, where the runtime has none of its own (Node before 22).

Types
/** 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

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.

Attributes
agentsCodingAgent[]
countsCodingCount[]
byStateRecord<string, number>
pausedByReasonRecord<string, number>
readAtDate | null
unreadstring[]
rawJsonObject

The response JSON exactly as the API sent it.

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

CodingAgent

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).

Attributes
agentIdstring
namestring
userIdstring | null
appCodingApp | null
harnessHarnessName
modelstring | null
credentialCodingCredential
placeCodingPlace
stateCodingState
pausedCodingPause | null
pausesCodingPause[]
jobCodingJob | null
runsCodingRun[]
spentUsdThisMonthnumber
modelUsageThisMonthModelUsage
rawJsonObject

The response JSON exactly as the API sent it.

Types
/** 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

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.

Attributes
projectIdstring
namestring | null
titlestring | null
coderboolean

CodingCount

interface CodingCount

How many coding agents run on each harness and model, in each state and place.

Attributes
harnessHarnessName
modelstring | null
stateCodingState
placeCodingPlace
countnumber
Types
/** 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

interface CodingCredential

Whose model credential it thinks with: key, a person's plan, NoClick's own (noclick), or pending until it's connected.

Attributes
kind"key" | "plan" | "noclick" | "pending"
connectionstring | null
credentialTypestring | null
connectedboolean | null

CodingJob

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.

Attributes
operationIdstring
conversationstring | null
statusstring
stepstring | null
sinceDate | null
titlestring | null
textstring
lostboolean
rawJsonObject

The response JSON exactly as the API sent it.

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

CodingPause

interface CodingPause

Why a coding agent isn't doing anything (expired, disconnected, spending_paused, spend_cap, out_of_funds, budget, failed_start, paused).

Attributes
reasonstring
messagestring

CodingRun

interface CodingRun

A conversation of its with a place up now; a sandbox's cpu and memoryMb are what it reserved.

Attributes
conversationstring | null
placeCodingPlace
sinceDate | null
busyboolean
projectIdstring | null
daemonboolean | null
cpunumber | null
memoryMbnumber | null
Types
/** Where a coding agent's current or next turn runs. */
type CodingPlace = "live" | "sandbox" | "machine";

AgentEvent

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.

Attributes
type| "text" | "reasoning" | "tool_call" | "tool_result" | "file" | "approval" | "operation" | "done" | "message" | "status" | "output" | "diff" | "turn_end" | (string & {})
textstring | null
toolstring | null
argumentsJsonObject | null
resultunknown
isErrorboolean
replyAgentReply | null
role"user" | "assistant" | "person" | "note" | null

A message's sender: user, assistant, person (someone it was handed off to) or note (agent.note).

heldJsonObject | 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.

operationIdstring | null
rawJsonObject

The response JSON exactly as the API sent it.

fileAttachment | null

A file event's file.

filesAttachment[]

A message event's files.

toolCallsJsonObject[]

A message event's tool calls (a reply's): each {tool, arguments, result, is_error}, as its turn's events showed it.

approvalJsonObject | 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).

operationJsonObject | 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).

viaMessageVia | null

A user message's way in, when not the API.

dataJsonObject | null

A note message's data.

triggerMessageTrigger | null

A user message no person sent: what started its turn (Message.trigger).

reasoningReasoningLine[]

A message event's reasoning (a reply's): Message.reasoning.

callIdstring | 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.

exitCodenumber | null

A harness command's tool_result: its exit code (null when it never exited).

durationMsnumber | null

A harness command's tool_result: how long it ran.

wholeboolean

An output that replaces what streamed of its command so far, rather than continuing it.

pathstring | 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.

diffstring | null

A diff's change: a unified diff, or a new file's whole content.

countnumber | null

A status events_dropped's: how many moments its sandbox couldn't send.

stepKindAgentStepKind | null

A harness step's tool_call and tool_result: command, edit, read, search or tool (AgentStep.kind).

requestJsonObject | 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).

commandstring | null

A harness command's tool_call: the command it runs.

querystring | null

A harness search's tool_call: what it looks for.

messageIdstring | null

A message's id in its thread (Message.id).

authorMessageAuthor | null

Who sent a user message (Message.author).

notificationboolean

A message an agent sent its owner from another of its conversations (Message.notification).

spaceMessageSpace | null

A notification's space, when it passes on a space's news (Message.space).

subagentMessageSubagent | null

The coding harness's subagent a user message was written for (Message.subagent).

chatstring | null

The chat a message of the agent's session came from, where it isn't the session's own (Message.chat).

Types
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;
}

Rehearsal

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.

Attributes
replystring
toolCallsJsonObject[]
transcriptJsonObject[]
scenariostring | null
costUsdnumber | null
operationIdstring | null
rawJsonObject

The response JSON exactly as the API sent it.

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

Wakeup

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).

Attributes
idstring
agentIdstring
userIdstring | null

Whose conversation it wakes (None: the account's).

conversationstring

The conversation it wakes.

notestring

What the turn is told.

atDate | null

When it's due (a time wake-up), or when it became due.

whenJsonObject | null

What it waits on: { operation_id } or { event, filters } (null for a time wake-up).

everyCron | null

Its schedule, for a recurring wake-up (null for one that comes once); at is its next time.

firednumber

How many turns it has started (a recurring one counts up).

sourceWakeupSource

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).

statusWakeupStatus

pending, delivered (its turn started), canceled or failed; a recurring one stays pending until it's canceled.

wokenByJsonObject | 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.

operationIdstring | null

The turn it started (an agent.message operation), once delivered.

depthnumber

How many wake_me wake-ups in a row led to it (0 for anything else).

errorJsonObject | null

Why it failed: { type, message }.

missedJsonObject | 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.

createdAtDate | null
deliveredAtDate | null

When its turn started (None until then).

operationOperation<AgentReply> | null

The turn it started, as an operation to wait on (null until delivered).

Types
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";

cancel

cancel(): Promise<this>

Cancel it while it's pending (Conflict once it was delivered, canceled or failed).

Returns

This wake-up, canceled.

update

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.notestring
options.atDate | string

A moment: a Date, or an ISO 8601 string with its offset.

options.everyCron

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.afterSnumber

This many seconds from now.

Returns

This wake-up, as it is now.

Job

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.

Attributes
startedBystring | null

The agent whose job it is: a task's parent, whether your code spawned it or the parent did.

conversationstring | null

The working agent's conversation it runs in.

parentConversationstring | 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 }.

latestUpdateJobUpdate | null

Its newest update, or null.

agentAgent | null

The agent doing the work (a lazy reference), or null.

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

liststatic

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.limitnumber

Return at most this many.

options.clientNoClick
options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

options.statusOperationStatus | "live" | readonly (OperationStatus | "live")[]

Statuses, or "live" for every non-terminal one.

options.agentstring | ApiObject

An Agent or agent id.

options.statusNotOperationStatus | readonly OperationStatus[]
options.keystring

The requesting key: its id or its prefix (nk_live_ab12).

options.createdAfterDate | string
options.createdBeforeDate | string
options.updatedAfterDate | string

Rows changed since (for polling).

options.userFilterUserFilter

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
/** `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;

listPagestatic

static listPage(options?: KindScopedFilters & PageOptions): Promise<Page<Job>>

One page of jobs; pass nextCursor back as cursor.

Parameters
options.cursorstring | null

The next_cursor of the page before; omit it for the first page.

options.limitnumber

Return at most this many.

options.clientNoClick
options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

options.statusOperationStatus | "live" | readonly (OperationStatus | "live")[]

Statuses, or "live" for every non-terminal one.

options.agentstring | ApiObject

An Agent or agent id.

options.statusNotOperationStatus | readonly OperationStatus[]
options.keystring

The requesting key: its id or its prefix (nk_live_ab12).

options.createdAfterDate | string
options.createdBeforeDate | string
options.updatedAfterDate | string

Rows changed since (for polling).

options.userFilterUserFilter

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
/** `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;

summarystatic

static summary(options?: KindScopedFilters): Promise<OperationSummary>

How many jobs match, by status; takes Operation.summary's filters except kind.

Parameters
options.clientNoClick
options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

options.statusOperationStatus | "live" | readonly (OperationStatus | "live")[]

Statuses, or "live" for every non-terminal one.

options.agentstring | ApiObject

An Agent or agent id.

options.statusNotOperationStatus | readonly OperationStatus[]
options.keystring

The requesting key: its id or its prefix (nk_live_ab12).

options.createdAfterDate | string
options.createdBeforeDate | string
options.updatedAfterDate | string

Rows changed since (for polling).

options.userFilterUserFilter

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
/** `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;

updates

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.

jobFromIdstaticTypeScript only

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
operationIdstringrequired
options.clientNoClick
options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

Types
/** `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

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).

Attributes
idstring
jobIdstring
agentIdstring | null
kindJobUpdateKind
textstring | null
toolstring | null
argumentsJsonObject | null
statusstring | null

The job's status then.

resultunknown
errorJsonObject | null
waitingOnJsonObject | 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).

wakeupIdstring | null
createdAtDate | null
rawJsonObject

The response JSON exactly as the API sent it.

Types
/** 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

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).

Attributes
toolsstring[]

The tool patterns it covers.

toolsstring[]

Every

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.

Attributes
intervalSnumber

How often, at most, the parent hears while the child works.

intervalSnumber

Agents

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, ...

Attributes
toolsAgentsTool[]

The capability's tools this gives.

toolsAgentsTool[]
Types
/** The tools of the `agents` capability. */
type AgentsTool = "spawn" | "message" | "ask" | "status" | "list" | "cancel";

onlystatic

static only(...tools: AgentsTool[]): Agents

Some of the capability's tools: Agents.only("spawn", "status").

Parameters
toolsAgentsTool[]required
Returns

The capability narrowed to those tools, for tools= (on the wire, "agents.spawn", ...).

Types
/** The tools of the `agents` capability. */
type AgentsTool = "spawn" | "message" | "ask" | "status" | "list" | "cancel";

Platform

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. Policy names its tools noclick.search ... noclick.delete.

Attributes
namesstring[]

What it's narrowed to: capability groups and API areas (empty: all of NoClick).

namesstring[]

What it's narrowed to: capability groups and API areas (empty: all of NoClick).

onlystatic

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
/** NoClick's capability groups, as a connected app's grant names them. */
type PlatformGroup = "read" | "build" | "deploy" | "spend" | "delete";

Attachment

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.

Attributes
namestring
urlstring
mimeTypestring
idstring | null
sizeBytesnumber | null
kind"image" | "audio" | "video" | "file"
voiceboolean
durationMsnumber | null
peaksnumber[] | null
rawJsonObject

The response JSON exactly as the API sent it.

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

Terminal

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.

Attributes
agentIdstring
conversationstring
harnessstring

claude_code or codex.

stateTerminalState

agent, taking_over, person or handing_back.

waitingForTurnboolean

Taken over once the agent's turn in flight ends.

sinceDate | null

When it was taken over.

endsAtDate | null

When it hands itself back at the latest: its sandbox's time limit.

idleLimitSnumber | null

It hands itself back after this long with nobody typing.

detachedLimitSnumber | null

It hands itself back after this long with no terminal open.

endedBecauseTerminalEnd | null

Why the last take-over ended.

urlstring | null

The terminal's websocket (from takeOver only).

tokenstring | null

Opens url once, within two minutes (from takeOver only).

tokenExpiresAtDate | null
Types
/**
 * `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";

handBack

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).

connectTypeScript only

connect(options?: TerminalConnectOptions): TerminalConnection

Open the terminal: once per token (takeOver again for another).

Parameters
options.colsnumber

The terminal's size as it opens (else the one takeOver was given).

options.rowsnumber
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.WebSockettypeof WebSocket

A WebSocket class, where the runtime has none of its own (Node before 22).

Types
/** 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

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. 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.querystring

Keeps the files whose names contain it (any case).

options.limitnumber

How many, 1 to 100 (30 by default).

options.clientNoClick

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, mime_type and kind.