@cerebro-labs/agentnava-sdk 0.26.0 → 0.44.1

package/account.js

@@ -0,0 +1,219 @@
+// An account: one saved sign-in to one app.
+import { AgentNavaError } from "./errors.js";
+/**
+ * One saved sign-in to one app, that you hold and act on.
+ *
+ * AN ACCOUNT IS NOT A CONNECTION, and the two words used to be one, which is
+ * how an agent came to own a Gmail login that nothing else could see. An
+ * ACCOUNT is a sign-in: Gmail, signed in as support@example.com. A CONNECTION is
+ * an entry in an agent's setup that names one: "this agent uses Gmail, through
+ * that account". Many agents can name one account, and reconnecting it once
+ * fixes all of them.
+ *
+ * ```ts
+ * const { account, url } = await ws.accounts.connect({ app: App.GMAIL, nickname: 'Support inbox' });
+ * showToUser(url);                        // they sign in on Google's own page
+ * await account.waitUntilConnected();
+ * await agent.connections.add(Connection.creatorAccount(App.GMAIL, account));
+ * ```
+ *
+ * Nobody handles a token, you included: the person signs in on the app's own
+ * page, and this object says who they signed in as, never how.
+ *
+ * ONE KIND OF OBJECT FOR BOTH OWNERS. The agent creator's account and one of
+ * your end users' are the same class, reached by the same routes: every method
+ * here works on any account in the workspace, and `data.owner` says whose it
+ * is. So `ws.account(id).waitUntilConnected()` is how you wait for an end user
+ * to finish signing in, too.
+ *
+ * A CLASS, like `Database` and `Secret`: you hold it and act on it, rather than
+ * threading an id through calls. Holding one makes no request. `ws.account(id)`
+ * is free and the first call on it is the first round trip.
+ */
+export class Account {
+    id;
+    #http;
+    snapshot;
+    constructor(http, id, snapshot) {
+        this.#http = http;
+        this.id = id;
+        if (snapshot)
+            this.snapshot = snapshot;
+    }
+    get base() {
+        return `/v1/accounts/${encodeURIComponent(this.id)}`;
+    }
+    /** The app's catalog id: `'gmail'`, `'hubspot'`. Named for what the person
+     *  signing in recognises, never for whoever we buy the sign-in from. */
+    get app() {
+        return this.snapshot?.app;
+    }
+    /** Who it is signed in as: the email or username the app reports. Null until
+     *  somebody has finished signing in. */
+    get label() {
+        return this.snapshot?.label;
+    }
+    /** Your own name for it, such as `'Support inbox'`. */
+    get nickname() {
+        return this.snapshot?.nickname;
+    }
+    /** Where the sign-in stands, from the last read: `'pending'`, `'connected'`,
+     *  `'needs_sign_in'` or `'error'`.
+     *
+     *  Reads the snapshot rather than the network. Undefined means this handle
+     *  has not read yet, NOT that the account is disconnected: call `get()`. */
+    get status() {
+        return this.snapshot?.status;
+    }
+    /** The agents whose setup names this account, from the last read. The
+     *  question to ask before disconnecting it: who loses it? */
+    get usedBy() {
+        return this.snapshot?.usedBy;
+    }
+    /** The last-known record, from whatever call produced this object. */
+    get data() {
+        return this.snapshot;
+    }
+    /**
+     * An account goes over the wire as its id, the way a `Date` goes as its ISO
+     * string: `JSON.stringify({ account })` sends `"acc_..."`.
+     *
+     * That is what lets a connection written as a plain object,
+     * `{ app, account }`, take the Account you are holding in
+     * `ws.agents.create()` and `agent.update()`. It also matches the rule for
+     * every handle in this SDK: store the id, not the object.
+     */
+    toJSON() {
+        return this.id;
+    }
+    /**
+     * Read it back.
+     *
+     * A MISSING ACCOUNT THROWS (`account_not_found`, 404), and never comes back
+     * as an empty record. An account that does not exist and one that is not
+     * signed in yet are different answers. The connection this replaced once
+     * answered a miss with a made-up blank, so storing an id and reading it back
+     * gave you something that did not know what it was.
+     */
+    async get() {
+        const res = await this.#http.get(this.base);
+        this.snapshot = accountIn(res, this.base);
+        return this.snapshot;
+    }
+    /**
+     * Wait until the person has finished signing in.
+     *
+     * The companion to `ws.accounts.connect()`, `ws.endUser(id).accounts
+     * .connect()` and `reconnect()`. Those hand you a url; this tells you when
+     * the person is done, so you do not write a polling loop or guess which
+     * field to believe.
+     *
+     * DONE MEANS CONNECTED AND NOT RECONNECTING. During a reconnect the account
+     * keeps working (`status` stays `'connected'`) while `reconnecting` is true,
+     * so a check on `status` alone would return before the person had signed in
+     * again. This waits for both.
+     *
+     * THROWS on the deadline (`account_not_connected`), naming the account and
+     * where it stands, rather than returning an account that is still pending.
+     * Safe to call again: somebody who has not finished may just need longer.
+     *
+     * Polls rather than subscribing: there is a person in the middle, so a few
+     * seconds costs nothing, and it works from any runtime without a socket.
+     */
+    async waitUntilConnected(options = {}) {
+        const timeoutMs = options.timeoutMs ?? 120_000;
+        const intervalMs = options.intervalMs ?? 2_000;
+        const deadline = Date.now() + timeoutMs;
+        // Checked before the first sleep: an account that is already connected
+        // should cost one request, not one request plus an interval.
+        let state = await this.get();
+        while (state.status !== 'connected' || state.reconnecting) {
+            if (Date.now() >= deadline) {
+                throw new AgentNavaError({
+                    message: `Account ${this.id} (${state.app}) was not connected within ${timeoutMs}ms; it is still ${state.status}${state.reconnecting ? ', with a reconnect waiting for the person' : ''}`,
+                    code: 'account_not_connected',
+                    status: 0,
+                });
+            }
+            await new Promise((r) => setTimeout(r, Math.min(intervalMs, Math.max(0, deadline - Date.now()))));
+            state = await this.get();
+        }
+        return this;
+    }
+    /**
+     * Send the person to sign in again, and get the link.
+     *
+     * What to call when an account `needs_sign_in`. Every agent that names it
+     * follows, so reconnecting once fixes all of them. The sign-in that worked is
+     * kept until the new one succeeds, so an abandoned link breaks nothing:
+     * meanwhile `data.reconnecting` is true, and `waitUntilConnected()` waits
+     * for it to clear.
+     *
+     * If the person signs in as SOMEBODY ELSE, that becomes a NEW account and
+     * this one is left as it was, so no agent switches mailbox without anyone
+     * deciding it should. List accounts to find the new one, then change the
+     * connections that should use it.
+     */
+    async reconnect() {
+        const res = await this.#http.post(`${this.base}/reconnect`);
+        return { url: res.url };
+    }
+    /** Give it your own name, such as `'Support inbox'`, shown beside who it is
+     *  signed in as. The app and the sign-in do not change. */
+    async rename(nickname) {
+        const res = await this.#http.patch(this.base, { nickname });
+        this.snapshot = accountIn(res, this.base);
+        return this;
+    }
+    /** Ask the app whether the sign-in still works, and read the answer. A
+     *  revoked sign-in comes back as `needs_sign_in`, not as an exception: it is
+     *  the answer this call exists to get. */
+    async check() {
+        const res = await this.#http.post(`${this.base}/check`);
+        this.snapshot = accountIn(res, `${this.base}/check`);
+        return this.snapshot;
+    }
+    /**
+     * Sign it out at the app and remove it here.
+     *
+     * ALWAYS ALLOWED, unlike deleting a database that an agent still names. It
+     * returns the agents whose setup names the account, so you can tell whoever
+     * owns them: from their next turn those connections report that the account
+     * was disconnected. Nothing switches to another account in its place.
+     *
+     * Removing a connection from an agent is the other thing, and it never
+     * touches the account: `agent.connections.remove(name)`.
+     */
+    async disconnect() {
+        // The same route for either owner. An end user's account is never named
+        // by an agent's setup (that says `endUser: true`), so for one of those
+        // the list of agents is empty, which is the true answer.
+        const res = await this.#http.delete(this.base);
+        return { agents: res?.agents ?? [] };
+    }
+}
+/**
+ * The account a response carries, or a thrown error. Never a blank.
+ *
+ * A 404 already throws in the transport, with the API's `account_not_found`.
+ * This covers the other way to end up with nothing: a 200 whose body has no
+ * account in it, which would otherwise become a snapshot of `undefined` that
+ * reads, at every call site, exactly like an account nobody has read yet.
+ */
+export function accountIn(res, path) {
+    const account = res?.account;
+    if (!account || typeof account.id !== 'string') {
+        throw new AgentNavaError({
+            message: `Expected an account from ${path}, got: ${JSON.stringify(res ?? null).slice(0, 200)}`,
+            code: 'bad_response',
+            status: 200,
+        });
+    }
+    return account;
+}
+/** The id a connection sends for its account: an `Account` by its id, an id
+ *  as it is. */
+export function accountIdOf(account) {
+    return typeof account === 'string' ? account : account?.id;
+}
+//# sourceMappingURL=account.js.map

package/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"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","sourcesContent":["// An account: one saved sign-in to one app.\n\nimport { AgentNavaError } from './errors.ts';\nimport type { Http } from './http.ts';\nimport type { AccountData, AccountStatus, UsedBy } from './types.ts';\n\n/**\n * One saved sign-in to one app, that you hold and act on.\n *\n * AN ACCOUNT IS NOT A CONNECTION, and the two words used to be one, which is\n * how an agent came to own a Gmail login that nothing else could see. An\n * ACCOUNT is a sign-in: Gmail, signed in as support@example.com. A CONNECTION is\n * an entry in an agent's setup that names one: \"this agent uses Gmail, through\n * that account\". Many agents can name one account, and reconnecting it once\n * fixes all of them.\n *\n * ```ts\n * const { account, url } = await ws.accounts.connect({ app: App.GMAIL, nickname: 'Support inbox' });\n * showToUser(url);                        // they sign in on Google's own page\n * await account.waitUntilConnected();\n * await agent.connections.add(Connection.creatorAccount(App.GMAIL, account));\n * ```\n *\n * Nobody handles a token, you included: the person signs in on the app's own\n * page, and this object says who they signed in as, never how.\n *\n * ONE KIND OF OBJECT FOR BOTH OWNERS. The agent creator's account and one of\n * your end users' are the same class, reached by the same routes: every method\n * here works on any account in the workspace, and `data.owner` says whose it\n * is. So `ws.account(id).waitUntilConnected()` is how you wait for an end user\n * to finish signing in, too.\n *\n * A CLASS, like `Database` and `Secret`: you hold it and act on it, rather than\n * threading an id through calls. Holding one makes no request. `ws.account(id)`\n * is free and the first call on it is the first round trip.\n */\nexport class Account {\n\treadonly id: string;\n\treadonly #http: Http;\n\tprivate snapshot?: AccountData;\n\n\tconstructor(http: Http, id: string, snapshot?: AccountData) {\n\t\tthis.#http = http;\n\t\tthis.id = id;\n\t\tif (snapshot) this.snapshot = snapshot;\n\t}\n\n\tprivate get base(): string {\n\t\treturn `/v1/accounts/${encodeURIComponent(this.id)}`;\n\t}\n\n\t/** The app's catalog id: `'gmail'`, `'hubspot'`. Named for what the person\n\t *  signing in recognises, never for whoever we buy the sign-in from. */\n\tget app(): string | undefined {\n\t\treturn this.snapshot?.app;\n\t}\n\n\t/** Who it is signed in as: the email or username the app reports. Null until\n\t *  somebody has finished signing in. */\n\tget label(): string | null | undefined {\n\t\treturn this.snapshot?.label;\n\t}\n\n\t/** Your own name for it, such as `'Support inbox'`. */\n\tget nickname(): string | null | undefined {\n\t\treturn this.snapshot?.nickname;\n\t}\n\n\t/** Where the sign-in stands, from the last read: `'pending'`, `'connected'`,\n\t *  `'needs_sign_in'` or `'error'`.\n\t *\n\t *  Reads the snapshot rather than the network. Undefined means this handle\n\t *  has not read yet, NOT that the account is disconnected: call `get()`. */\n\tget status(): AccountStatus | undefined {\n\t\treturn this.snapshot?.status;\n\t}\n\n\t/** The agents whose setup names this account, from the last read. The\n\t *  question to ask before disconnecting it: who loses it? */\n\tget usedBy(): UsedBy[] | undefined {\n\t\treturn this.snapshot?.usedBy;\n\t}\n\n\t/** The last-known record, from whatever call produced this object. */\n\tget data(): AccountData | undefined {\n\t\treturn this.snapshot;\n\t}\n\n\t/**\n\t * An account goes over the wire as its id, the way a `Date` goes as its ISO\n\t * string: `JSON.stringify({ account })` sends `\"acc_...\"`.\n\t *\n\t * That is what lets a connection written as a plain object,\n\t * `{ app, account }`, take the Account you are holding in\n\t * `ws.agents.create()` and `agent.update()`. It also matches the rule for\n\t * every handle in this SDK: store the id, not the object.\n\t */\n\ttoJSON(): string {\n\t\treturn this.id;\n\t}\n\n\t/**\n\t * Read it back.\n\t *\n\t * A MISSING ACCOUNT THROWS (`account_not_found`, 404), and never comes back\n\t * as an empty record. An account that does not exist and one that is not\n\t * signed in yet are different answers. The connection this replaced once\n\t * answered a miss with a made-up blank, so storing an id and reading it back\n\t * gave you something that did not know what it was.\n\t */\n\tasync get(): Promise<AccountData> {\n\t\tconst res = await this.#http.get<{ account?: AccountData }>(this.base);\n\t\tthis.snapshot = accountIn(res, this.base);\n\t\treturn this.snapshot;\n\t}\n\n\t/**\n\t * Wait until the person has finished signing in.\n\t *\n\t * The companion to `ws.accounts.connect()`, `ws.endUser(id).accounts\n\t * .connect()` and `reconnect()`. Those hand you a url; this tells you when\n\t * the person is done, so you do not write a polling loop or guess which\n\t * field to believe.\n\t *\n\t * DONE MEANS CONNECTED AND NOT RECONNECTING. During a reconnect the account\n\t * keeps working (`status` stays `'connected'`) while `reconnecting` is true,\n\t * so a check on `status` alone would return before the person had signed in\n\t * again. This waits for both.\n\t *\n\t * THROWS on the deadline (`account_not_connected`), naming the account and\n\t * where it stands, rather than returning an account that is still pending.\n\t * Safe to call again: somebody who has not finished may just need longer.\n\t *\n\t * Polls rather than subscribing: there is a person in the middle, so a few\n\t * seconds costs nothing, and it works from any runtime without a socket.\n\t */\n\tasync waitUntilConnected(options: { timeoutMs?: number; intervalMs?: number } = {}): Promise<Account> {\n\t\tconst timeoutMs = options.timeoutMs ?? 120_000;\n\t\tconst intervalMs = options.intervalMs ?? 2_000;\n\t\tconst deadline = Date.now() + timeoutMs;\n\t\t// Checked before the first sleep: an account that is already connected\n\t\t// should cost one request, not one request plus an interval.\n\t\tlet state = await this.get();\n\t\twhile (state.status !== 'connected' || state.reconnecting) {\n\t\t\tif (Date.now() >= deadline) {\n\t\t\t\tthrow new AgentNavaError({\n\t\t\t\t\tmessage: `Account ${this.id} (${state.app}) was not connected within ${timeoutMs}ms; it is still ${state.status}${\n\t\t\t\t\t\tstate.reconnecting ? ', with a reconnect waiting for the person' : ''\n\t\t\t\t\t}`,\n\t\t\t\t\tcode: 'account_not_connected',\n\t\t\t\t\tstatus: 0,\n\t\t\t\t});\n\t\t\t}\n\t\t\tawait new Promise((r) => setTimeout(r, Math.min(intervalMs, Math.max(0, deadline - Date.now()))));\n\t\t\tstate = await this.get();\n\t\t}\n\t\treturn this;\n\t}\n\n\t/**\n\t * Send the person to sign in again, and get the link.\n\t *\n\t * What to call when an account `needs_sign_in`. Every agent that names it\n\t * follows, so reconnecting once fixes all of them. The sign-in that worked is\n\t * kept until the new one succeeds, so an abandoned link breaks nothing:\n\t * meanwhile `data.reconnecting` is true, and `waitUntilConnected()` waits\n\t * for it to clear.\n\t *\n\t * If the person signs in as SOMEBODY ELSE, that becomes a NEW account and\n\t * this one is left as it was, so no agent switches mailbox without anyone\n\t * deciding it should. List accounts to find the new one, then change the\n\t * connections that should use it.\n\t */\n\tasync reconnect(): Promise<{ url: string }> {\n\t\tconst res = await this.#http.post<{ url: string }>(`${this.base}/reconnect`);\n\t\treturn { url: res.url };\n\t}\n\n\t/** Give it your own name, such as `'Support inbox'`, shown beside who it is\n\t *  signed in as. The app and the sign-in do not change. */\n\tasync rename(nickname: string): Promise<Account> {\n\t\tconst res = await this.#http.patch<{ account?: AccountData }>(this.base, { nickname });\n\t\tthis.snapshot = accountIn(res, this.base);\n\t\treturn this;\n\t}\n\n\t/** Ask the app whether the sign-in still works, and read the answer. A\n\t *  revoked sign-in comes back as `needs_sign_in`, not as an exception: it is\n\t *  the answer this call exists to get. */\n\tasync check(): Promise<AccountData> {\n\t\tconst res = await this.#http.post<{ account?: AccountData }>(`${this.base}/check`);\n\t\tthis.snapshot = accountIn(res, `${this.base}/check`);\n\t\treturn this.snapshot;\n\t}\n\n\t/**\n\t * Sign it out at the app and remove it here.\n\t *\n\t * ALWAYS ALLOWED, unlike deleting a database that an agent still names. It\n\t * returns the agents whose setup names the account, so you can tell whoever\n\t * owns them: from their next turn those connections report that the account\n\t * was disconnected. Nothing switches to another account in its place.\n\t *\n\t * Removing a connection from an agent is the other thing, and it never\n\t * touches the account: `agent.connections.remove(name)`.\n\t */\n\tasync disconnect(): Promise<{ agents: UsedBy[] }> {\n\t\t// The same route for either owner. An end user's account is never named\n\t\t// by an agent's setup (that says `endUser: true`), so for one of those\n\t\t// the list of agents is empty, which is the true answer.\n\t\tconst res = await this.#http.delete<{ disconnected?: boolean; agents?: UsedBy[] }>(this.base);\n\t\treturn { agents: res?.agents ?? [] };\n\t}\n}\n\n/**\n * The account a response carries, or a thrown error. Never a blank.\n *\n * A 404 already throws in the transport, with the API's `account_not_found`.\n * This covers the other way to end up with nothing: a 200 whose body has no\n * account in it, which would otherwise become a snapshot of `undefined` that\n * reads, at every call site, exactly like an account nobody has read yet.\n */\nexport function accountIn(res: { account?: AccountData } | undefined, path: string): AccountData {\n\tconst account = res?.account;\n\tif (!account || typeof account.id !== 'string') {\n\t\tthrow new AgentNavaError({\n\t\t\tmessage: `Expected an account from ${path}, got: ${JSON.stringify(res ?? null).slice(0, 200)}`,\n\t\t\tcode: 'bad_response',\n\t\t\tstatus: 200,\n\t\t});\n\t}\n\treturn account;\n}\n\n/** The id a connection sends for its account: an `Account` by its id, an id\n *  as it is. */\nexport function accountIdOf(account: Account | string): string {\n\treturn typeof account === 'string' ? account : account?.id;\n}\n"]}

package/agent.d.ts

@@ -1,43 +1,34 @@
-import { type Attachable } from './attach.ts';
+import { type Account } from './account.ts';
 import { Conversation } from './conversation.ts';
 import type { Http } from './http.ts';
-import type { AgentData, AgentFields, Bindings, ConnectionStatus, FileEntry, Trigger, Workflow } from './types.ts';
-/**
- * Turn the accounts a caller is holding into the `{ provider: id }` map the
- * wire speaks.
- *
- * Shared by `start`, `agent.attach` and `conversation.attach` so the three
- * cannot drift. A handle you created carries its provider already; one you
- * addressed by id has to read it, which is the only request here and only when
- * it is unavoidable.
- */
+import type { Secret } from './secret.ts';
+import { type Connection } from './connection.ts';
+import type { AgentData, AgentFields, Bindings, ConnectionStatus, FileEntry, Trigger, WebsiteChat, Workflow } from './types.ts';
 export interface StartOptions {
     /**
-     * Accounts to attach AS THE CONVERSATION STARTS.
+     * Stored secrets to attach AS THE CONVERSATION STARTS.
      *
-     * The common shape for an application with many end users: the person
-     * connected Gmail once, and this thread should act as them from its first
-     * turn.
+     * A `Secret` from `ws.endUser(id).secrets.create(...)` attaches by id, which
+     * is the only way a stored per-person credential can reach a turn: you never
+     * hold its value.
      *
      * ```ts
-     * const gmail = await ws.endUser(row.userId).connections.list();
-     * const c = await agent.start({ endUserId: row.userId, attach: gmail });
+     * const key = await ws.endUser(row.userId).secrets.create({ name: 'ZENDESK_TOKEN', value });
+     * const conversation = await agent.start({ endUserId: row.userId, attach: key });
      * ```
      *
      * Doing it here rather than with a second `conversation.attach()` call
      * closes a real window: between `start` and the attach, the conversation
-     * exists and can be asked something, and it would answer without the
-     * account.
-     *
-     * STILL EXPLICIT. Naming `endUserId` does not attach their accounts; this
-     * line does, and you can read it.
-     *
-     * TAKES SECRETS TOO. A `Secret` from `ws.endUser(id).secrets.create(...)`
-     * attaches by id, which is the only way a stored per-person credential can
-     * reach a turn: you never hold its value. Mix them freely, they are split by
-     * type before the launch.
+     * exists and can be asked something, and it would answer without it.
+     *
+     * ACCOUNTS ARE NOT ATTACHED HERE any more (0.44), and one handed in is
+     * refused. The agent's setup names the account each connection uses; for a
+     * connection to the end user's account (`Connection.endUserAccount`), the
+     * turn uses the account of the person this conversation is for, found by
+     * `endUserId`. Ask
+     * `conversation.accountsNeeded()` for the ones they have not connected yet.
      */
-    attach?: Attachable | Attachable[];
+    attach?: Secret | Secret[];
     /**
      * Secret VALUES for this conversation only.
      *
@@ -49,24 +40,32 @@ export interface StartOptions {
     /** Pin a specific version. Defaults to the latest at the moment of starting.
      *
      *  A conversation pins its version for life: publishing afterwards does not
-     *  move a conversation that is already open. */
+     *  move a conversation that is already open. The one exception is a schedule
+     *  or webhook that names the conversation (`conversationId`): each firing
+     *  moves it to the latest version, so a fix you publish reaches it. */
     version?: number;
     parameters?: Record<string, string | number>;
     /**
      * WHO this conversation is for: one of YOUR users, not one of ours.
      *
-     * REQUIRED, and nullable. You must say, and `null` is a real answer: a
-     * nightly report belongs to nobody. Optional would let it be forgotten,
-     * which is the mistake worth designing against, because a conversation
-     * without an owner cannot be listed back to the person it was for.
-     *
-     * It is a LABEL on the conversation, and nothing else. It does not decide
-     * which conversation you get, because `start` always starts a new one.
-     * Later you can ask for everything belonging to that person:
+     * REQUIRED, and never null. Every conversation belongs to someone. The id
+     * is yours to choose: a user's row id, an anonymous visitor's random id, or
+     * a name for a job such as `'nightly-report'`. Only a non-empty string is
+     * accepted; anything else throws before a request is sent. (Decided
+     * 2026-09-26, AGE-161: a conversation with no owner cannot be listed back to
+     * the person it was for, and the accounts connected inside it could not be
+     * revoked with that person.)
+     *
+     * It LABELS the conversation, and it decides one thing more: a connection
+     * to the end user's account (`Connection.endUserAccount`) uses THIS
+     * person's account for that app.
+     * It does not decide which conversation you get, because `start` always
+     * starts a new one. Later you can ask for everything belonging to that
+     * person:
      *
      * ```ts
      * const conversation = await agent.start({ endUserId: row.userId });
-     * const nobody       = await agent.start({ endUserId: null });  // a nightly job
+     * const nightly      = await agent.start({ endUserId: 'nightly-report' }); // a job has an id too
      * const theirs       = await agent.conversations({ endUser: row.userId });
      * ```
      *
@@ -81,6 +80,13 @@ export interface StartOptions {
      * email and not something we authenticate. We never verify it, so it is
      * exactly as trustworthy as whatever holds your API key.
      *
+     * The platform's prefixes are refused with a 400 (`end_user_reserved`):
+     * `member:`, `visitor:` and `job:`, which name a member in the web app, an
+     * embed visitor and work nobody is typing, and the older `webhook:`,
+     * `builder:` and `librarian:`. Case and spacing do not matter to the check
+     * (`MEMBER:x` is refused too). An id you chose must never be mistaken for
+     * one of ours.
+     *
      * NOT A WORKSPACE MEMBER'S ID. `ws.members()` lists the colleagues who share
      * this account, and their `userId` is a platform id we issued. This field is
      * a different namespace entirely. Both were once spelled `userId`, so
@@ -88,7 +94,7 @@ export interface StartOptions {
      * for an end-user id to be checked against, so it just labelled the
      * conversation with a colleague's internal id and looked fine.
      */
-    endUserId: string | null;
+    endUserId: string;
 }
 /**
  * An agent you can configure and start conversations from.
@@ -116,7 +122,9 @@ export declare class Agent {
     }): Promise<AgentData>;
     /** Every version, newest first. */
     versions(): Promise<AgentData[]>;
-    /** Publish a new version with these fields changed and everything else kept. */
+    /** Publish a new version with these fields changed and everything else kept.
+     *  `connections`, when sent, replaces the whole list; an `Account` in it goes
+     *  over the wire as its id (`Account.toJSON`). */
     update(fields: AgentFields): Promise<Agent>;
     delete(): Promise<void>;
     /**
@@ -132,6 +140,60 @@ export declare class Agent {
     /** Replace the trigger list. Sending `[]` removes every trigger, including
      *  `chat`, which is what leaves an agent that only runs on a schedule. */
     setTriggers(triggers: Trigger[]): Promise<Agent>;
+    /**
+     * Replace the webhook's URL and return the new one.
+     *
+     * The old URL stops working the moment this returns, so update the system
+     * that calls it. Use it when a URL leaked. The webhook's `message` and who it
+     * runs for are kept. Publishes a version. Throws `no_webhook` (409) when the
+     * agent has no webhook trigger.
+     */
+    rotateWebhookUrl(): Promise<string>;
+    /**
+     * The agent's website chat: a public chat page, and the embed script that
+     * puts it on your website. ON from the moment the agent is created, for
+     * every agent, however it was made (here, through the API, or in the portal),
+     * until you turn it off. The one exception is an agent that needs each
+     * user's own account or secret, which a visitor cannot bring: it has none.
+     *
+     * You never need it to use the agent from code: the agent answers your API
+     * key, and the portal's Test, as soon as it exists.
+     *
+     * Anyone with the page link can talk to the agent, and each of their turns is
+     * charged to your workspace, so turn it off for an agent only your own code
+     * should reach. `turnOn()` on a new agent changes nothing and hands back what
+     * to put on a website. The portal has no switch for it; its Website chat panel
+     * holds the share link and the allowed websites (`allowedWebsites` below).
+     * Publishing a newer version does not move the page: call `turnOn()` while it
+     * is on to serve the newer one. Turned off and on again, it serves the
+     * version it served before.
+     */
+    readonly websiteChat: {
+        /** Turn it on and get what to put on a website. The first time, and when
+         *  it is already on, the page serves the current version; after
+         *  `turnOff()`, the version it served before. Refused (400) for an agent
+         *  that needs each user's own account or secret, which a visitor cannot
+         *  bring. */
+        turnOn: () => Promise<WebsiteChat>;
+        /** Turn it off. Visitors are refused from the next message, follow-ups a
+         *  visitor's conversation booked are cancelled, and nothing more is
+         *  charged for them. The agent keeps answering your API key, its schedules
+         *  and its webhooks. The publishable token is kept, so turning it on again
+         *  revives a snippet already on a website. Turning off a chat that is
+         *  already off is not an error. */
+        turnOff: () => Promise<void>;
+        /** The websites the chat may be shown on through the embed script. A
+         *  domain covers its subdomains; an empty list means no other website.
+         *  The share link opened directly always works. */
+        allowedWebsites: {
+            /** The list as it stands. */
+            get: () => Promise<string[]>;
+            /** Replace the list. Each entry is normalised ("https://acme.com/page"
+             *  becomes "acme.com"; "localhost" is allowed for testing), and one that
+             *  is not a website is refused (400). Returns the list as stored. */
+            set: (websites: string[]) => Promise<string[]>;
+        };
+    };
     /**
      * The agent's knowledge: files every conversation can read.
      *
@@ -143,6 +205,10 @@ export declare class Agent {
      */
     readonly knowledge: {
         put: (path: string, bytes: Uint8Array | ArrayBuffer, contentType?: string) => Promise<FileEntry>;
+        /** Read an agent-owned knowledge file as bytes, without starting a turn. */
+        get: (path: string) => Promise<Uint8Array>;
+        /** Read UTF-8 text. JSON files remain text rather than being parsed. */
+        text: (path: string) => Promise<string>;
         list: (path?: string) => Promise<FileEntry[]>;
         remove: (path: string) => Promise<void>;
     };
@@ -183,63 +249,128 @@ export declare class Agent {
         list: () => Promise<string[]>;
     };
     /**
-     * Give this agent a credential, so every conversation with it can use one.
+     * The WORKSPACE databases this agent may query, by key.
+     *
+     * Register a database first with `ws.databases.create()`, which gives it its
+     * key; attaching names that key in this agent's configuration. Naming it is
+     * the grant: the database answers this agent's `sql_*` calls and no agent
+     * that does not name it, and the agent's prompt lists it by key.
+     *
+     * ATTACHING PUBLISHES A VERSION, like a knowledge base: which databases an
+     * agent reaches is part of its configuration, so the change is diffable and
+     * reversible. Detaching takes effect on the agent's next query, including in
+     * a conversation already under way.
+     */
+    readonly databases: {
+        /** Attach one database by key. The server appends, so two attaches cannot
+         *  lose each other. A key that names no database is refused; one already
+         *  attached is a no-op. */
+        attach: (key: string) => Promise<Agent>;
+        /** Stop this agent querying one database. The database stays registered
+         *  for every other agent that names it. */
+        detach: (key: string) => Promise<Agent>;
+        /** The keys this agent may query, in configuration order. */
+        list: () => Promise<string[]>;
+    };
+    /**
+     * The apps this agent uses: each a NAMED connection that says WHOSE ACCOUNT
+     * it uses, built the way the portal's Add a connection screen asks.
+     *
+     * | built with | whose account | the person signs in |
+     * |---|---|---|
+     * | `Connection.creatorAccount(app, account)` | the agent creator's, from `ws.accounts.connect()` | once, and every conversation uses it |
+     * | `Connection.endUserAccount(app)` | the end user's: each person talking to the agent | once each, remembered for them |
      *
      * ```ts
-     * await agent.attach(gmail);                        // one account
-     * await agent.attach([gmail, calendar]);            // several
-     * await agent.attach({ secrets: { KEY: value } });  // a secret VALUE
+     * const { account: work } = await ws.accounts.connect({ app: App.GMAIL, nickname: 'Work' });
+     * await agent.connections.add(Connection.creatorAccount(App.GMAIL, work, { name: 'work-gmail' }));
+     * await agent.connections.add(Connection.endUserAccount(App.GOOGLE_CALENDAR));
      * ```
      *
-     * ONE VERB, NOT TWO. This and `bind` used to both exist and do the same job
-     * through different shapes, which is how a surface becomes hard to learn:
-     * two names for one idea means every reader has to work out whether the
-     * difference is meaningful. It is not, so `bind` is gone.
+     * A turn uses EXACTLY the account the setup names, and never another one.
+     * There is no fallback to whichever account of that app happens to exist:
+     * that fallback is what this replaced, and it meant reading an agent's code
+     * told you nothing about whose mailbox it read.
      *
-     * "Attach" rather than "bind" because it is the plainer word, it is the one
-     * that pairs with `detach`, and `knowledgeBases.attach/detach` already uses
-     * it for the same shape of operation.
+     * EVERY CHANGE PUBLISHES A VERSION, like `databases`: which accounts an
+     * agent reaches is part of its configuration, so the change is diffable and
+     * reversible. A conversation uses the connections of the version it runs.
+     * The ACCOUNTS are not versioned: signing one in again reaches every agent
+     * that names it, from the next turn.
      *
-     * ACCOUNTS TAKE THE OBJECT, SECRETS TAKE A VALUE, and that asymmetry is in
-     * the product rather than in the naming. An account has an id you can hand
-     * over; a secret does not, because binding one means supplying the value
-     * itself. Hiding that behind one shape would not make it go away.
-     *
-     * The counterpart to `authorize()`, which creates an account AND attaches it
-     * in one step. Use this when the account already exists: one team mailbox
-     * connected once and attached to nine agents, rather than nine sign-ins.
+     * Removing a connection never touches the account. Disconnecting an account
+     * is the other operation, on the account: `account.disconnect()`.
      */
-    attach(what: Attachable | Attachable[] | Bindings): Promise<Agent>;
-    /** What each declared provider's actual state is: DECLARED IS NOT CONNECTED.
-     *
-     *  An agent can require Gmail with nobody signed in, and that is the state a
-     *  setup checklist has to show. Without this the only way to find the gap is
-     *  to start a conversation and watch the agent fail. */
-    connections(): Promise<ConnectionStatus[]>;
+    readonly connections: {
+        /**
+         * Add one connection. One call that publishes, not read-modify-write, so
+         * two adds racing cannot lose each other.
+         *
+         * Takes what `Connection.creatorAccount()` or `Connection.endUserAccount()`
+         * builds, or the same plain object. Refused, naming the problem, when the
+         * name is taken on this agent (`connection_name_taken`), when the account
+         * is of a different app (`account_app_mismatch`), or when no account has
+         * that id (`account_not_found`).
+         */
+        add: (connection: Connection) => Promise<Agent>;
+        /**
+         * Point one connection at another account: `{ account }` for the agent
+         * creator's (the `Account` you hold, or its id), or `{ endUser: true }`
+         * for each end user's own. The name and the app stay; an account of a
+         * different app is refused (`account_app_mismatch`).
+         *
+         * READ-MODIFY-WRITE, unlike `add` and `remove`, because there is no
+         * route that changes one connection in place: this reads the current
+         * version and publishes it again with the one connection changed. Two
+         * changes racing can therefore lose one, so make them one after the
+         * other. A name the agent does not have throws
+         * (`connection_not_found`) before anything is sent.
+         */
+        change: (name: string, change: {
+            account: Account | string;
+            endUser?: never;
+        } | {
+            endUser: true;
+            account?: never;
+        }) => Promise<Agent>;
+        /** Remove one connection by name. Publishes a version. NEVER touches the
+         *  account: it stays connected for every other agent that names it, and
+         *  for this one if you add it back. */
+        remove: (name: string) => Promise<Agent>;
+        /**
+         * Each connection with the account it uses and whether that account works
+         * now: DECLARED IS NOT CONNECTED. An agent can name an account nobody has
+         * finished signing in to, or one that was disconnected since, and that is
+         * the state a setup checklist has to show.
+         *
+         * Includes what an unpublished draft adds (`inDraft`) and removes
+         * (`removedInDraft`), so it matches the portal.
+         */
+        list: () => Promise<ConnectionStatus[]>;
+    };
     /**
-     * Attach a third-party account to this agent, at `fixed` scope: one account,
-     * used by every conversation.
+     * Give this agent secret values, so every conversation with it can use them.
      *
-     * Returns a url to send a person to. They sign in there, in their own
-     * browser, and the account attaches when they finish. YOU NEVER SEE A TOKEN,
-     * which is the entire point: nobody should be pasting a Gmail credential into
-     * a config field.
+     * ```ts
+     * await agent.attach({ secrets: { APOLLO_API_KEY: value } });
+     * ```
      *
-     * This does NOT satisfy a declaration scoped 'conversation'. Use
-     * `conversation.authorize()` for those, which attaches the account to that
-     * one conversation and cannot overwrite this shared one.
+     * SECRETS ONLY, since 0.44. Accounts used to be attached here, and a turn
+     * then had to guess which of the accounts attached and owned around it to
+     * use. The agent's setup now names them: `agent.connections.add()`. One
+     * handed in here is refused by name (`not_a_secret`) rather than dropped.
+     *
+     * A stored `Secret` is not attached to an agent either. It never was: one
+     * was accepted here and nothing was done with it. Store one for the agent
+     * with `ws.secrets.create({ name, value, agentId })`, or attach one of your
+     * end user's to their conversation with `conversation.attach(secret)`.
      */
-    authorize(provider: string): Promise<{
-        url: string;
-        connectionId: string;
-    }>;
-    /** Detach the account connected for this provider.
-     *
-     *  Reads the raw ROWS rather than the merged status, because revoking needs
-     *  the connection's id and the merged view is keyed by provider: it answers
-     *  "is Gmail connected", not "which row is it". */
-    disconnect(provider: string): Promise<void>;
-    /** Start a conversation. It pins the agent's version now and keeps it. */
+    attach(bindings: Bindings): Promise<Agent>;
+    /** Start a conversation. It pins the agent's version now and keeps it.
+     *
+     *  Nothing about accounts is passed here: the version's connections name
+     *  them, and a connection to the end user's account uses the account of
+     *  the person named by `endUserId`. */
     start(options: StartOptions): Promise<Conversation>;
     /**
      * Address one of this agent's conversations by id. No request.
@@ -281,5 +412,3 @@ export declare class Agent {
         endUser?: string;
     }): Promise<Conversation[]>;
 }
-/** A connection row as `GET /v1/connections` returns it (toConnectionMeta in
- *  apps/api/src/connections/store.ts). */