Agent
Agents: hosted agents you message by name.
class AgentA 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.
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| origin | AgentOrigin | null |
|
| name | string | |
| model | string | null | The model it runs, as its harness names it ( |
| harness | HarnessName | null | What runs it: |
| modelConnection | string | null | The connection whose key or plan it thinks with, by name (null on |
| instructions | string | null | |
| tools | (string | JsonObject)[] | What it can use, as listed: refs, |
| toolRules | ToolRules | What it may do with each app it reaches ( |
| canRequest | string[] | What it may ask its user to connect at run time. |
| userId | string | null | |
| workflowId | string | null | |
| nodeId | string | null | An app agent's step in its workflow (null for an API agent). |
| workflowName | string | null | An app agent's workflow, by name. |
| access | string | null | An app agent's workflow as you hold it: |
| enabled | boolean | null | Whether an app agent is switched on; a disabled one takes no messages. |
| appUrl | string | null | Where an app agent is changed: its workflow in the NoClick app. |
| parentId | string | null | Its parent, whose budget it draws on. |
| ttlS | number | null | The time to live it was created with, in seconds (null if it isn't temporary); |
| expiresAt | Date | null | When a temporary agent expires (null if it isn't): it then stays readable, |
| budgetUsdPerMonth | number | null | |
| region | RegionName | null | The region its sandboxes run in, fixed when it was created; |
| machineId | string | null | Invite-only beta. The |
| createdAt | Date | null | |
| browserProfileId | string | null | The browser profile its |
| cardId | string | null | Invite-only beta. The card it holds and pays with (null: none of its own). |
| volumes | Record<string, string> | The volumes its shell mounts: |
| memoryId | string | null | Its own memory ( |
| skills | { id: string; pin: number | null }[] | null | Its skills: each |
| memories | { id: string; writes: boolean }[] | null | The memories it reads besides its own, in order: each |
| secretIds | string[] | The secrets in its shell's environment, in order (a later one's key wins). |
| timezone | string | null | The IANA timezone its turns tell the time in (null: the acting user's, else UTC). |
| repos | JsonObject[] | The repositories cloned into its workspace: each its |
| setup | string[] | Commands its sandbox (its container, on a machine) runs as it starts, after its repos and before its harness. |
| docker | boolean | Whether Docker runs in its sandbox, a VM of |
| sandboxSize | SandboxSize | null | The VM a Docker agent works in; null without Docker. |
| appTesting | AppTesting | How it may turn Docker on for a task that needs it ( |
| appTestingUsdPerHour | number | null | What an hour of app testing costs where its sandbox runs; null without a sandbox of its own. |
| movedFrom | AgentMovedFrom | null | Where a move from a laptop made it (its move, machine, folder and when); null otherwise. |
| network | NetworkAccess | null | What its shell and code reach: |
| shell | boolean | null | Whether it has a shell (the |
| turnLimits | TurnLimits | null | How far one of its turns goes, as set (null, or a limit left out: 200 steps, $1 and 30 minutes). |
| effort | string | null | Its conversations' reasoning effort (null: the model's own). |
| speed | "standard" | "fast" |
|
| permissionMode | PermissionMode | How far its coding harness goes before asking a person where a conversation sets nothing. |
| status | AgentStatus | null |
|
| lastActiveAt | Date | null | When a turn of its last started or ended (null: it never ran, or hidden like |
| runningTurns | number | null | How many of its turns are queued, running or waiting on a person, any conversation (null: hidden like |
| childCount | number | null | How many live (not expired) children it has ( |
| jobId | string | null | The task it was spawned with (its operation id), or null. |
| usedBy | UsedBy[] | The apps that bind it: |
| paused | boolean | Whether |
| helper | boolean | Whether it's one of NoClick's helpers, made for NoClick's own work rather than one of your agents: an app's coding agent (which NoClick hands each change to that app's code), or a child one of NoClick's own agents spawned. |
| noclick | boolean | Whether it's a NoClick, your account's own or one of your spaces', rather than one of your agents: NoClick's own
app shows it as NoClick, never by the name it's found by (a space's is |
| formerNames | string[] | The names it went by before it was renamed, the latest first. Each still reaches it ( |
| job | Job | null | The task it was spawned with, as a |
| triggerKinds | string[] | The kinds of its triggers ( |
| consoleUrl | string | null | This agent in the developer console (null off the hosted API). |
| a2aUrl | string | The A2A JSON-RPC endpoint ( |
| memory | AgentMemory | What it remembers across conversations: |
/** 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.
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.
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.
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).
What it may do with each app it reaches (ToolRules). In update, {} clears them.
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.
In fromName, null clears it, as browserProfile and card do.
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.
What wakes it without a message: OnWebhook, OnEvent, OnPlatformEvent, Cron and OnQueue.
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.
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.
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.
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.
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.
Repositories cloned into its workspace (/workspace/) 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.
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.
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.
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.
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.
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.
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.
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.
fast runs its model in its harness's fast mode where it has one (speeds). In update, null clears it.
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.
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.
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.
The VM a Docker agent works in (SandboxSize; small unless it says). In update, null is small again.
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.
A taken name returns the object already there, as it is: nothing about it changes.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
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.
The new agent, loaded.
/** 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 },
): AgentA 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 }).
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.
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.
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).
What it may do with each app it reaches (ToolRules). In update, {} clears them.
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.
In fromName, null clears it, as browserProfile and card do.
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.
What wakes it without a message: OnWebhook, OnEvent, OnPlatformEvent, Cron and OnQueue.
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.
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.
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.
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.
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.
Repositories cloned into its workspace (/workspace/) 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.
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.
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.
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.
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.
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.
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.
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.
fast runs its model in its harness's fast mode where it has one (speeds). In update, null clears it.
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.
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.
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.
The VM a Docker agent works in (SandboxSize; small unless it says). In update, null is small again.
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.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
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.
An agent that loads (or is created, or has your fields set) the first time it's used. Nothing is sent yet.
/** 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): AgentA lazy reference to an agent by NoClick id.
An agent that loads the first time it's used. Nothing is sent yet.
/** `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.
The agent, loaded.
/** `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);Only agents with this status.
Only agents with a turn since then.
Only the children of this agent (an Agent or id).
true: only agents with a ttlS; false: only agents without one.
Only agents on this harness.
created (the default: newest first) or last_active (most recently active first, those that never ran last).
Only agents made through the API (api) or built in the NoClick app (app).
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Every matching agent, newest first (or most recently active first), fetched page by page.
/**
* `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.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
Only agents with this status.
Only agents with a turn since then.
Only the children of this agent (an Agent or id).
true: only agents with a ttlS; false: only agents without one.
Only agents on this harness.
created (the default: newest first) or last_active (most recently active first, those that never ran last).
Only agents made through the API (api) or built in the NoClick app (app).
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A page whose data holds the agents and whose next_cursor is None on the last page.
/**
* `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);Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A CodingAgents.
/**
* 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);Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
An AgentStateRow per agent.
/**
* 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" });The client to send with; defaults to the module client built from NOCLICK_API_KEY.
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");The client to send with; defaults to the module client built from NOCLICK_API_KEY.
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] }).
The file's name (a File has its own).
Its type (a Blob has its own; else read from the name).
A recorded voice clip (audio).
A voice clip's waveform: loudness 0-1, at most 64 numbers.
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.
/** 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" });Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The turn's operation, started. Keep its id to pick the reply up later, from anywhere.
/** `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");Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
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).
/** `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");Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
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.
/** 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" });Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
Each HarnessRequest: an approval (what it would do) or a question, and where it stands.
/** `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." });Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The request as it stands now (answered; a cancel stops the turn, which ends it canceled).
/** 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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The reply: its text, the conversation it belongs to and the tool_calls the turn made.
/** `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.
The newest this many (1-200), oldest first; every message when omitted.
Just before this cursor: a nextCursor of historyPage.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
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.
/** `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 });The newest this many (1-200), oldest first; every message when omitted.
Just before this cursor: a nextCursor of historyPage.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
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).
/** `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" });Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
True when it was added, False when a note with key already was.
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.");The text of each question withdrawn.
conversation
conversation(name: string, options?: { user?: UserOption }): AgentConversationOne 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" });Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The new Conversation, active.
/** `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();Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The new Conversation, active.
/** `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 }));Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
Its Conversation (active), or None before the agent has one.
/** `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.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
Every matching conversation (or the first limit), fetched page by page. cost_usd
is None for a thread with no recorded turns.
/**
* 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.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
A page whose data holds the conversations and whose next_cursor is None on the last page.
/**
* 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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
/** `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) });Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
A Terminal: its url and token open it (see noclick.terminal).
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
A Terminal with its state, and no url or token.
/** `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.
When NoClick makes the child report, beside "done" (always on): "blocked", new Before(...), new Every(...).
The parent's conversation its updates wake; without one they wake nobody and wait on the job.
The child's standing instructions: what its updates should say, and when to reach out freely.
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.
Its budget, held out of what its parent's has left; omitted, it draws on its parent's as it spends.
It expires this many seconds after it's made.
The parent's model when omitted.
The parent's harness when omitted.
The parent's model connection when omitted.
<parent>-<8 hex> when omitted.
Whose conversation conversation is (an account parent talking to a user: that user's thread).
The child, loaded, with parent_id set to this agent and job its running task.
/**
* 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.
Return at most this many.
Each child with its status, last_active_at, running_turns and, if spawn
made it, the job it was started with.
/**
* `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).
Statuses, or "live" for every non-terminal one.
task (spawned), or message (sent with its agents tools).
The agent doing the work (an Agent or id).
The parent's conversation that started them.
Return at most this many.
Every matching job (or the first limit), newest first, each with its status, step and
latest_update; wait() on one gives its reply.
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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The answer as an AgentReply; with interject, the reply the turn it joined ended with.
/** `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.
The card as a dict: the agent's name, its JSON-RPC url and the skills it offers.
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.
This agent, updated. A field you leave out is unchanged, and changes apply from its next turn.
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.
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 }).
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.
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.
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." });What the turn is told, 1 to 4,000 characters.
A moment: a Date, or an ISO 8601 string with its offset.
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.
With an event when: dotted paths into the event's data that must equal these values.
Whose conversation it is, as message() takes it.
This many seconds from now.
The wake-up, pending; update() changes it, cancel() calls it 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>;
}
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.
Return at most this many.
undefined = the ambient user (asUser), null = the account itself.
Which users the read covers (user_id query), instead of acting as one (user).
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.
/**
* 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.
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.
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.
/** 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.
The trigger as it is now, with its new next_run_at.
/** 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.
The trigger as it is now (paused is True).
/** 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.
The trigger as it is now (state is live unless the agent is paused).
/** 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.
/** 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().
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.
"http"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.
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.
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.
The run's operation (kind agent.rehearse); .wait() gives the Rehearsal.
/** 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).
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.
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.
This agent, with paused false.
workspace
workspace(
conversation?: string,
options?: { user?: UserOption },
): AgentWorkspaceThe files it works on: its one /workspace (a conversation is accepted and ignored). Sends nothing yet.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
Its workspace, whose files, read, write and url reach its files.
/** `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 }): AgentSandboxThe 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();Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
Its sandbox, whose get, files, read and exec reach it.
/** `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>;
}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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
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.
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
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).
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The run's operation (kind agent.rehearse); .wait() gives the Rehearsal: the reply, and
the tool_calls it made with what the world answered.
/** `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 AgentConversationOne 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" });| name | string | 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.
Its ConversationSettings after the change.
/**
* 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.
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();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.
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.
A ToolServers.
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.
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.");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.
""A CommandResult, or the command's Operation.
/**
* 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 AgentStateRowOne 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.
| agentId | string | |
| name | string | |
| harness | HarnessName | |
| state | AgentState | |
| conversation | string | null | |
| now | AgentNow | null | |
| waiting | { asks: number; heldCalls: number; requests: number; total: number } | |
| turnStartedAt | Date | null | |
| lastActiveAt | Date | null | |
| failed | { message: string; at: Date | null } | null | |
| waking | { at: Date | null; why: string } | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
/** 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 CommandResultWhat a command NoClick has a control for came to (/model, /effort, /new, /context, /usage…).
| control | string | |
| command | { name: string; arguments: string } | |
| result | JsonObject | The control's answer: conversation settings, a new conversation, its context, its usage, or an operation. |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };ConversationContext
interface ConversationContextHow 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.
| model | string | null | |
| usedTokens | number | null | |
| windowTokens | number | null | |
| percent | number | null | |
| autoCompactsAt | number | null | |
| source | "harness" | "noclick" | null | |
| asOf | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };ConversationRevert
interface ConversationRevertA 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.
| conversation | string | |
| message | string | |
| text | string | |
| droppedTurns | number | |
| files | { restored: string[]; kept: string[]; notRestored: { path: string; why: string }[]; commandsNotUndone: number } | |
| filesApplied | "next_turn" | null | |
| agentReads | "native" | "context" | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };AgentToolServer
interface AgentToolServerAn 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).
| id | string | |
| name | string | |
| url | string | null | |
| transport | "http" | "sse" | |
| signedIn | boolean | |
| headers | string[] | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };ConversationUsage
interface ConversationUsageWhat 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.
| costUsd | number | |
| modelUsage | ModelUsage | null | |
| turns | number | |
| paysWith | "noclick" | "key" | "plan" | |
| planLimits | PlanLimit[] | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
/** 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 ToolServerOne MCP server a conversation's coding harness reaches its tools on, as it stands.
| name | string | |
| status | "connected" | "connecting" | "failed" |
|
| toolCount | number | null | How many tools it offers the model, where the harness says (null where it doesn't). |
| error | string | null | Why it failed, in the harness's or the server's words. |
ToolServers
interface ToolServersThe 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.
| servers | ToolServer[] | |
| source | "live" | "last_turn" | "none" | |
| checkedAt | Date | null | |
| reconnect | { available: boolean; scope: "server" | "all" | null; why: string | null } | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };AgentCommand
interface AgentCommandOne command a conversation's harness offers.
| name | string | |
| description | string | |
| argumentHint | string | What its arguments look like ( |
| source | AgentCommandSource | |
| aliases | string[] | Other names it answers to. |
/** 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 AgentCommandsWhat 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).
| harness | string | |
| commands | AgentCommand[] | |
| skills | AgentSkill[] | |
| capabilities | Record<string, boolean> |
|
| notSupported | Record<string, string> | What NoClick can't run on this harness, and why. |
| withheld | string[] | Commands NoClick never runs from a chat, whatever the harness offers: those that change what NoClick sets up and
guards for the agent (its MCP servers, permissions, credentials, model provider, process or settings files:
Claude Code's |
| mapped | { name: string; to: string }[] | The harness's commands NoClick has a control of its own for, each with that control ( |
| asOf | Date | null | |
| readFrom | "this_conversation" | "another_conversation" | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
/** One skill a conversation's harness has. */
interface AgentSkill {
name: string;
description: string;
}
type JsonObject = { [key: string]: unknown };AgentGrant
interface AgentGrantA 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.
| id | string | |
| connection | string | |
| integration | string | |
| operations | string[] | null | |
| status | "requested" | "active" | |
| reason | string | null | |
| conversation | string | null | |
| createdAt | Date | null | |
| grantedAt | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };ConversationSettings
interface ConversationSettingsA 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.
| permissionMode | PermissionMode | |
| effectivePermissionMode | PermissionMode | |
| permissionModes | PermissionMode[] | |
| notSupported | Record<string, string> | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| conversation | string | |
| title | string | null | |
| archived | boolean | |
| harness | HarnessName | null | |
| model | string | null | |
| effort | string | null | null: the model's own default ( |
| efforts | string[] | The efforts its harness takes on its model, weakest first, in the harness's own words ([]: none). |
| defaultEffort | string | null | |
| speed | AgentSpeed | |
| speeds | AgentSpeed[] |
|
| modelConnection | string | null | |
| accounts | ModelAccount[] | What can pay for it: each |
| overridden | string[] | What the conversation sets itself: its |
| forkedFrom | ForkedFrom | null |
|
/** 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 HarnessRequestWhat 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).
| id | string | |
| kind | "approval" | "question" | |
| status | "pending" | "answered" | "expired" | "canceled" | |
| action | string | null | |
| title | string | null | |
| detail | string | null | |
| plan | string | null | |
| questions | JsonObject[] | |
| options | { optionId: string; name: string; kind: string }[] | |
| answer | JsonObject | null | |
| operationId | string | null | |
| createdAt | Date | null | |
| expiresAt | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| decision | string | null | What it was answered with ( |
| answeredAt | Date | null | |
| canceledReason | string | null | Why it was closed unanswered: its turn ended first (failed, stopped, timed out). |
type JsonObject = { [key: string]: unknown };AgentReply
interface AgentReplyThe agent's answer to one message.
| text | string | |
| conversation | string | null | Pass back as |
| toolCalls | JsonObject[] | The turn's tool calls, each |
| operationId | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| modelUsage | ModelUsage | null | The turn's model calls on your own key or plan (null on NoClick's key, whose cost is its |
| endedBy | TurnLimitName | null | The limit that ended the turn before it finished (its |
| steps | AgentStep[] |
|
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 AgentStepOne 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.
| kind | AgentStepKind | |
| tool | string | |
| callId | string | null | |
| source | "harness" | (string & {}) | null | |
| arguments | JsonObject | |
| command | string | null | |
| path | string | null | |
| query | string | null | |
| output | string | null | |
| exitCode | number | null | |
| durationMs | number | null | |
| isError | boolean | |
| result | unknown | |
| diffs | AgentStepDiff[] | |
| createdAt | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
/** 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 AgentStepDiffOne file a step changed: a unified diff, or a new file's whole content (change add), at most 16,384 characters.
| path | string | |
| change | "add" | "update" | "delete" | (string & {}) | null | |
| diff | string |
Conversation
interface ConversationOne thread with an agent (a user's, or the account's own).
| conversation | string | Pass as |
| userId | string | null | |
| title | string | null | |
| preview | string | null | |
| turns | number | null | |
| costUsd | number | null | |
| lastActivity | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| status | ConversationStatus | null |
|
| handedOffTo | string | null | Who a |
| modelUsage | ModelUsage | null | Its model calls on your own key or plan, all turns together (null on NoClick's key). |
| lastMessage | LastMessage | null | Its newest message (null before any). |
| people | MessageAuthor[] | Who is in it: the people who wrote in it, the thread's own person first. |
| archived | boolean | |
| forkedFrom | ForkedFrom | null | The conversation it was forked from, and at which message. |
| agentReads | "native" | "context" | null | A fork's: |
| active | boolean | Whether it's the agent's session now, the one conversation everyone talking to it shares; the others can be resumed. |
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 MessageOne 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).
| role | string | |
| text | string | |
| createdAt | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| files | Attachment[] | The files it carried (a |
| toolCalls | JsonObject[] | A reply's tool calls: each |
| via | MessageVia | null | How a |
| data | JsonObject | null | A |
| trigger | MessageTrigger | null | What started the turn of a |
| reasoning | ReasoningLine[] | A reply's reasoning, as its turn's |
| operationId | string | null | The turn it belongs to (an |
| command | AgentCommandInput | null | The harness command a |
| id | string | null | Its place in the thread, which stays (a revert marks, never removes): pass it to |
| author | MessageAuthor | null | Who sent a |
| notification | boolean | An agent's message to its owner from another of its conversations (a |
| space | MessageSpace | null | A |
| subagent | MessageSubagent | null | A |
| chat | string | null | The chat a message of the agent's session came from, where it isn't the session's own: the |
| steps | AgentStep[] |
|
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 HarnessInfoWhat 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.
| name | HarnessName | What |
| label | string | null | |
| version | string | null | The version NoClick runs (null for |
| defaultModel | string | The model an agent on it gets when you give none. |
| customModels | boolean | Whether |
| modelConnection | "required" | "optional" |
|
| integrations | string[] | The model providers ( |
| streaming | "tokens" | "final" |
|
| shell | "built_in" | "code_capability" |
|
| notes | string[] | What to know before choosing it (a model that needs a particular key, say). |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| efforts | string[] | The reasoning efforts it takes on its default model, weakest first ([]: none); a conversation's settings list its model's. |
| defaultEffort | string | null | The effort it runs at when none is set (null: the model's own). |
| speeds | AgentSpeed[] |
|
| noclickKey | { runs: boolean; models: string[]; why: string | null } | Whether a coding agent on it may run on NoClick's own key ( |
| permissionModes | PermissionMode[] | The permission modes it enforces ([]: none, as on |
| notSupported | Record<string, 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";
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 });Return at most this many.
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 HarnessModelA 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.
| id | string | |
| label | string | null | |
| canonical | string | |
| route | HarnessModelRoute | |
| noclickKey | HarnessModelPrice | null | What it costs on NoClick's own key; null where the key doesn't run it on this harness, or its price can't be read now. |
/** 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 ModelUsageWhat 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.
| inputTokens | number | |
| outputTokens | number | |
| cachedTokens | number | |
| usd | number | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };AgentToolAccess
interface AgentToolAccessWhat 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.
| mode | "everything" | "restricted" | |
| listed | boolean | |
| rules | ToolRules | |
| since | Date | null | |
| apps | AgentToolApp[] | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
/**
* 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 AgentToolAppOne app in agent.toolAccess(): a connection of its scope, an integration its rules name, NoClick or the web.
| key | string | null | Its rule key; null for the web, whose two actions ( |
| app | string | |
| kind | "connection" | "integration" | "noclick" | "web" | |
| integration | string | null | |
| credentialType | string | null | |
| label | string | |
| account | string | null | The account it's connected as (else its name), or what it does for NoClick and the web. |
| status | ConnectionStatus | null | |
| on | boolean | Whether anything of it may run. |
| calls | number | |
| actions | AgentToolAction[] |
/**
* `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 AgentToolActionOne action of an app in agent.toolAccess(): its rule key, what its rules say of it and how often it ran.
| key | string | |
| action | string | |
| title | string | |
| group | string | null | Its integration's own grouping of it ( |
| kind | "read" | "send" | "change" | "delete" | "money" | What it does, from its name: |
| verdict | ToolRule | |
| canAsk | boolean | False where |
| calls | number | Its calls that ran since |
/** `allow` runs a call, `ask` holds it for the owner's yes (an approval), `off` refuses it. */
type ToolRule = "allow" | "ask" | "off";AgentMemory
class AgentMemoryagent.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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
Each entry's name, description, version and when it last changed, by name; content is
None here, so read an entry for its body.
/** `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).
Return at most this many.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
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).
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The entry with its content and the version to pass back when you change it.
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The entry as saved, with its new version.
/** `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).
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
Each version's number, description, who wrote it and when, without its content.
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
That version in full.
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The entry as restored, at its new version.
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
Each entry's name, description and version, by name, without its content.
/** `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.
Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
/** `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 MemoryEntryOne 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.
| name | string | |
| description | string | |
| content | string | null | |
| version | number | |
| updatedAt | Date | null | |
| updatedBy | "agent" | "api" | "console" | null | |
| writtenBy | MemoryWriter | Who last wrote it: for an agent, which one and in which of its conversations. |
| userId | string | null | |
| conversation | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };MemoryEntryVersion
interface MemoryEntryVersionOne 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.
| name | string | |
| version | number | |
| current | boolean | |
| description | string | |
| content | string | null | |
| writtenBy | MemoryWriter | |
| userId | string | null | |
| savedAt | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };MemoryWriter
interface MemoryWriterWho last wrote a memory entry: an agent's turn (which agent, in which conversation), a person in the app, or a key.
| type | "agent" | "api" | "console" | null | |
| agentId | string | null | |
| agentName | string | null | |
| conversation | string | null |
AgentWorkspace
class AgentWorkspaceThe 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.)
| conversation | string | 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).
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.
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.
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.
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).
The link; it works for expires_in_s seconds (an hour by default, a day at most).
WorkspaceFile
interface WorkspaceFileA file in a conversation's workspace; url downloads it without a key for about an hour.
| path | string | Relative to |
| sizeBytes | number | |
| modifiedAt | Date | null | |
| url | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };AgentSandbox
class AgentSandboxThe 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);| conversation | string | 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.
"/workspace"Everything below the folder, not just what's in it (git's objects left out unless listed by their path).
Return at most this many.
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.
"/workspace"Everything below the folder, not just what's in it (git's objects left out unless listed by their path).
The next_cursor of the page before; omit it for the first page.
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.
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.
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));A SandboxShell whose url and single-use token your user's browser opens within two minutes.
ConversationSandbox
interface ConversationSandboxThe 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.
| agentId | string | |
| conversation | string | |
| harness | HarnessName | |
| place | SandboxPlace | |
| status | "running" | "stopped" | |
| startedAt | Date | null | |
| cpu | number | null | |
| memoryMb | number | null | |
| region | string | null | |
| usdPerHour | number | null | |
| spentUsdToday | number | null | |
| machineId | string | null | |
| projectId | string | null | |
| workspace | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
/** 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 PageOne page of a sandbox's folder; source says where it was read: the running sandbox, or what its workspace kept.
- Inherits from Page.
| source | "sandbox" | "workspace" |
SandboxShell
class SandboxShellA shell on a conversation's sandbox (AgentSandbox.shell): connect() opens it, once per token.
| agentId | string | |
| conversation | string | |
| url | string | The terminal websocket it opens on. |
| token | string | Opens |
| tokenExpiresAt | Date | null | |
| idleLimitS | number | null | It closes after this long with nothing typed. |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };connectTypeScript only
connect(options?: TerminalConnectOptions): TerminalConnectionOpen the shell: onState hears exited (and why) as it ends, and it closes for good (final).
The terminal's size as it opens (else the one takeOver was given).
What the terminal prints, as it prints it.
It's open: what the person types reaches the terminal from now.
The take-over moved (person, handing_back, then agent as it closes).
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.
A WebSocket class, where the runtime has none of its own (Node before 22).
/** 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 CodingAgentsEvery 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.
| agents | CodingAgent[] | |
| counts | CodingCount[] | |
| byState | Record<string, number> | |
| pausedByReason | Record<string, number> | |
| readAt | Date | null | |
| unread | string[] | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };CodingAgent
interface CodingAgentOne 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).
| agentId | string | |
| name | string | |
| userId | string | null | |
| app | CodingApp | null | |
| harness | HarnessName | |
| model | string | null | |
| credential | CodingCredential | |
| place | CodingPlace | |
| state | CodingState | |
| paused | CodingPause | null | |
| pauses | CodingPause[] | |
| job | CodingJob | null | |
| runs | CodingRun[] | |
| spentUsdThisMonth | number | |
| modelUsageThisMonth | ModelUsage | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
/** 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 CodingAppThe 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.
| projectId | string | |
| name | string | null | |
| title | string | null | |
| coder | boolean |
CodingCount
interface CodingCountHow many coding agents run on each harness and model, in each state and place.
| harness | HarnessName | |
| model | string | null | |
| state | CodingState | |
| place | CodingPlace | |
| count | number |
/** 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 CodingCredentialWhose model credential it thinks with: key, a person's plan, NoClick's own (noclick), or pending until it's connected.
| kind | "key" | "plan" | "noclick" | "pending" | |
| connection | string | null | |
| credentialType | string | null | |
| connected | boolean | null |
CodingJob
interface CodingJobIts turn in flight (or a lost one): title as whoever handed it over named it, text the start of what it was asked.
| operationId | string | |
| conversation | string | null | |
| status | string | |
| step | string | null | |
| since | Date | null | |
| title | string | null | |
| text | string | |
| lost | boolean | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };CodingPause
interface CodingPauseWhy a coding agent isn't doing anything (expired, disconnected, spending_paused, spend_cap, out_of_funds, budget, failed_start, paused).
| reason | string | |
| message | string |
CodingRun
interface CodingRunA conversation of its with a place up now; a sandbox's cpu and memoryMb are what it reserved.
| conversation | string | null | |
| place | CodingPlace | |
| since | Date | null | |
| busy | boolean | |
| projectId | string | null | |
| daemon | boolean | null | |
| cpu | number | null | |
| memoryMb | number | null |
/** Where a coding agent's current or next turn runs. */
type CodingPlace = "live" | "sandbox" | "machine";AgentEvent
interface AgentEventOne 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.
| type | | "text" | "reasoning" | "tool_call" | "tool_result" | "file" | "approval" | "operation" | "done" | "message" | "status" | "output" | "diff" | "turn_end" | (string & {}) | |
| text | string | null | |
| tool | string | null | |
| arguments | JsonObject | null | |
| result | unknown | |
| isError | boolean | |
| reply | AgentReply | null | |
| role | "user" | "assistant" | "person" | "note" | null | A |
| held | JsonObject | null | A held |
| status | | "active" | "awaiting_human" | "handed_off" | "compacting" | "compacted" | "events_dropped" | "downloading" | "downloaded" | "succeeded" | "failed" | "canceled" | "expired" | null | A |
| operationId | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| file | Attachment | null | A |
| files | Attachment[] | A |
| toolCalls | JsonObject[] | A |
| approval | JsonObject | null | An |
| operation | JsonObject | null | An |
| via | MessageVia | null | A |
| data | JsonObject | null | A |
| trigger | MessageTrigger | null | A |
| reasoning | ReasoningLine[] | A |
| callId | string | null | A coding harness's step: the |
| source | "harness" | (string & {}) | null |
|
| exitCode | number | null | A harness command's |
| durationMs | number | null | A harness command's |
| whole | boolean | An |
| path | string | null | A |
| change | "add" | "update" | "delete" | (string & {}) | null | What happened to a |
| diff | string | null | A |
| count | number | null | A |
| stepKind | AgentStepKind | null | A harness step's |
| request | JsonObject | null | A |
| command | string | null | A harness command's |
| query | string | null | A harness search's |
| messageId | string | null | A |
| author | MessageAuthor | null | Who sent a |
| notification | boolean | A |
| space | MessageSpace | null | A notification's space, when it passes on a space's news ( |
| subagent | MessageSubagent | null | The coding harness's subagent a |
| chat | string | null | The chat a |
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 RehearsalA 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.
| reply | string | |
| toolCalls | JsonObject[] | |
| transcript | JsonObject[] | |
| scenario | string | null | |
| costUsd | number | null | |
| operationId | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };Wakeup
class WakeupOne 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).
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| agentId | string | |
| userId | string | null | Whose conversation it wakes ( |
| conversation | string | The conversation it wakes. |
| note | string | What the turn is told. |
| at | Date | null | When it's due (a time wake-up), or when it became due. |
| when | JsonObject | null | What it waits on: |
| every | Cron | null | Its schedule, for a recurring wake-up (null for one that comes once); |
| fired | number | How many turns it has started (a recurring one counts up). |
| source | WakeupSource | What set it: |
| status | WakeupStatus |
|
| wokenBy | JsonObject | null | What woke it: |
| operationId | string | null | The turn it started (an |
| depth | number | How many |
| error | JsonObject | null | Why it failed: |
| missed | JsonObject | null | A recurring one's last missed time: |
| createdAt | Date | null | |
| deliveredAt | Date | null | When its turn started ( |
| operation | Operation<AgentReply> | null | The turn it started, as an operation to wait on (null until delivered). |
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).
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.
A moment: a Date, or an ISO 8601 string with its offset.
This many seconds from now.
This wake-up, as it is now.
Job
class Job extends OperationWork 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.
- Inherits from Operation.
| startedBy | string | null | The agent whose job it is: a task's parent, whether your code spawned it or the parent did. |
| conversation | string | null | The working agent's conversation it runs in. |
| parentConversation | string | null | The parent's conversation its updates wake (null: they wake nobody and wait here). |
| requiredUpdates | (string | JsonObject)[] | The updates its parent required, as on the wire: |
| latestUpdate | JobUpdate | null | Its newest update, or null. |
| agent | Agent | null | The agent doing the work (a lazy reference), or null. |
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.
Return at most this many.
undefined = the ambient user (asUser), null = the account itself.
Statuses, or "live" for every non-terminal one.
An Agent or agent id.
The requesting key: its id or its prefix (nk_live_ab12).
Rows changed since (for polling).
Which users the read covers (user_id query), instead of acting as one (user).
Every matching job (or the first limit), each with its status, step and latest_update.
/** `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.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
undefined = the ambient user (asUser), null = the account itself.
Statuses, or "live" for every non-terminal one.
An Agent or agent id.
The requesting key: its id or its prefix (nk_live_ab12).
Rows changed since (for polling).
Which users the read covers (user_id query), instead of acting as one (user).
A page whose data holds the jobs and whose next_cursor is None on the last page.
/** `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.
undefined = the ambient user (asUser), null = the account itself.
Statuses, or "live" for every non-terminal one.
An Agent or agent id.
The requesting key: its id or its prefix (nk_live_ab12).
Rows changed since (for polling).
Which users the read covers (user_id query), instead of acting as one (user).
The number that match in total, and per operation status in by_status.
/** `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.
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): JobA lazy reference to a job by operation id: pick it up anywhere (Operation.fromId gives a plain operation).
/** `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 JobUpdateOne 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).
| id | string | |
| jobId | string | |
| agentId | string | null | |
| kind | JobUpdateKind | |
| text | string | null | |
| tool | string | null | |
| arguments | JsonObject | null | |
| status | string | null | The job's status then. |
| result | unknown | |
| error | JsonObject | null | |
| waitingOn | JsonObject | null | A |
| wakeupId | string | null | |
| createdAt | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
/** 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 BeforeAn 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).
| tools | string[] | The tool patterns it covers. |
| tools | string[] |
Every
class EveryAn 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.
| intervalS | number | How often, at most, the parent hears while the child works. |
| intervalS | number |
Agents
class AgentsThe 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, ...
| tools | AgentsTool[] | The capability's tools this gives. |
| tools | AgentsTool[] |
/** The tools of the `agents` capability. */
type AgentsTool = "spawn" | "message" | "ask" | "status" | "list" | "cancel";onlystatic
static only(...tools: AgentsTool[]): AgentsSome of the capability's tools: Agents.only("spawn", "status").
The capability narrowed to those tools, for tools= (on the wire, "agents.spawn", ...).
/** The tools of the `agents` capability. */
type AgentsTool = "spawn" | "message" | "ask" | "status" | "list" | "cancel";Platform
class PlatformNoClick 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.
| names | string[] | What it's narrowed to: capability groups and API areas (empty: all of NoClick). |
| names | string[] | What it's narrowed to: capability groups and API areas (empty: all of NoClick). |
onlystatic
static only(...names: (PlatformGroup | (string & {}))[]): PlatformPart of NoClick: Platform.only("domains"), Platform.only("read"). Names are checked when the agent is saved.
NoClick narrowed to those names, for tools= (on the wire, "noclick.read", ...).
/** NoClick's capability groups, as a connected app's grant names them. */
type PlatformGroup = "read" | "build" | "deploy" | "spend" | "delete";Attachment
interface AttachmentA 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.
| name | string | |
| url | string | |
| mimeType | string | |
| id | string | null | |
| sizeBytes | number | null | |
| kind | "image" | "audio" | "video" | "file" | |
| voice | boolean | |
| durationMs | number | null | |
| peaks | number[] | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };Terminal
class TerminalA 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.
- Like every live object, it also has hydrate(), refresh() and raw.
| agentId | string | |
| conversation | string | |
| harness | string |
|
| state | TerminalState |
|
| waitingForTurn | boolean | Taken over once the agent's turn in flight ends. |
| since | Date | null | When it was taken over. |
| endsAt | Date | null | When it hands itself back at the latest: its sandbox's time limit. |
| idleLimitS | number | null | It hands itself back after this long with nobody typing. |
| detachedLimitS | number | null | It hands itself back after this long with no terminal open. |
| endedBecause | TerminalEnd | null | Why the last take-over ended. |
| url | string | null | The terminal's websocket (from |
| token | string | null | Opens |
| tokenExpiresAt | Date | null |
/**
* `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.
This terminal, as it is now (agent, or handing_back while its program exits).
connectTypeScript only
connect(options?: TerminalConnectOptions): TerminalConnectionOpen the terminal: once per token (takeOver again for another).
The terminal's size as it opens (else the one takeOver was given).
What the terminal prints, as it prints it.
It's open: what the person types reaches the terminal from now.
The take-over moved (person, handing_back, then agent as it closes).
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.
A WebSocket class, where the runtime has none of its own (Node before 22).
/** 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] });Keeps the files whose names contain it (any case).
How many, 1 to 100 (30 by default).
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Each file as an Attachment with its id, name, url, mime_type and kind.