@cerebro-labs/agentnava-sdk 0.26.0 → 0.46.1

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, WebhookDelivery } 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,73 @@ 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>;
+    /** What the webhook received, newest first: accepted, refused (and why), a
+     *  sender's retry recognised as a repeat, or a test. Up to `limit` (200). */
+    webhookDeliveries(options?: {
+        limit?: number;
+    }): Promise<WebhookDelivery[]>;
+    /**
+     * Send the webhook a sample event and run the agent on it, the way a real
+     * delivery would (the signature check aside). A real turn, charged like
+     * one. Returns the conversation it ran in.
+     */
+    sendTestWebhook(): Promise<{
+        conversationId?: 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 +218,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 +262,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.
-     *
-     * "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.
+     * 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.
      *
-     * 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.
+     * 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.
      *
-     * 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.
+    attach(bindings: Bindings): Promise<Agent>;
+    /** Start a conversation. It pins the agent's version now and keeps it.
      *
-     *  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. */
+     *  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 +425,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). */