@cerebro-labs/agentnava-sdk 0.26.0 → 0.46.1

package/agent.js

@@ -1,8 +1,10 @@
 // An agent: a configuration you start conversations from.
 var _a;
-import { isBindings, providersOf, secretIdsOf, splitAttachments } from "./attach.js";
-import { toConnectionStatus } from "./connection-status.js";
+import { accountIdOf } from "./account.js";
+import { isBindings, refuseConnections, secretIdsOf, secretsIn } from "./attach.js";
 import { Conversation } from "./conversation.js";
+import { AgentNavaError } from "./errors.js";
+import { connectionForWire } from "./connection.js";
 /**
  * An agent you can configure and start conversations from.
  *
@@ -46,7 +48,9 @@ export class Agent {
         const res = await this.#http.get(`${this.base}/versions`);
         return res.versions ?? [];
     }
-    /** 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`). */
     async update(fields) {
         const data = await this.#http.post(`${this.base}/versions`, fields);
         this.snapshot = data;
@@ -78,7 +82,102 @@ export class Agent {
     async setTriggers(triggers) {
         return this.update({ triggers });
     }
+    /**
+     * 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.
+     */
+    async rotateWebhookUrl() {
+        const data = await this.#http.post(`${this.base}/webhook/rotate`, {});
+        this.snapshot = data;
+        const webhook = data.triggers.find((t) => t.kind === 'webhook');
+        if (webhook?.kind !== 'webhook' || !webhook.url) {
+            throw new AgentNavaError({
+                message: 'The webhook was rotated but no URL came back. Read it with agent.get().',
+                code: 'webhook_url_missing',
+                status: 502,
+            });
+        }
+        return webhook.url;
+    }
+    /** 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). */
+    async webhookDeliveries(options = {}) {
+        const res = await this.#http.get(`${this.base}/webhook/deliveries`, options.limit !== undefined ? { limit: options.limit } : undefined);
+        return res.deliveries ?? [];
+    }
+    /**
+     * 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.
+     */
+    async sendTestWebhook() {
+        const res = await this.#http.post(`${this.base}/webhook/test`, {});
+        return res.conversationId ? { conversationId: res.conversationId } : {};
+    }
+    // ------------------------------------------------------------ website chat
+    /**
+     * 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.
+     */
+    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: async () => {
+            const res = await this.#http.post(`${this.base}/activate`, {});
+            return {
+                chatUrl: res.chatUrl,
+                publicToken: res.publicToken,
+                embedAgentId: res.agentId,
+                versionNumber: res.versionNumber,
+            };
+        },
+        /** 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: async () => {
+            await this.#http.post(`${this.base}/deactivate`, {});
+        },
+        /** 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: async () => (await this.#http.get(`${this.base}/allowed-websites`)).websites,
+            /** 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: async (websites) => (await this.#http.put(`${this.base}/allowed-websites`, { websites })).websites,
+        },
+    };
     // --------------------------------------------------------------- knowledge
+    #readKnowledgeResponse(path) {
+        return this.#http.send(`${this.base}/knowledge/files/content`, { query: { path } });
+    }
     /**
      * The agent's knowledge: files every conversation can read.
      *
@@ -95,6 +194,16 @@ export class Agent {
             query: { path },
             ...(contentType && { contentType }),
         }),
+        /** Read an agent-owned knowledge file as bytes, without starting a turn. */
+        get: async (path) => {
+            const res = await this.#readKnowledgeResponse(path);
+            return new Uint8Array(await res.arrayBuffer());
+        },
+        /** Read UTF-8 text. JSON files remain text rather than being parsed. */
+        text: async (path) => {
+            const res = await this.#readKnowledgeResponse(path);
+            return res.text();
+        },
         list: async (path = '/') => {
             // The route returns EVERY knowledge file for the agent; it takes no
             // directory parameter. Filtering here rather than sending one the server
@@ -157,24 +266,155 @@ export class Agent {
             return current.knowledgeBases ?? [];
         },
     };
-    // ------------------------------------------------- credentials, agent tier
+    // -------------------------------------------------------------- databases
     /**
-     * Supply the credentials declared at 'fixed' scope: set once, used by every
-     * conversation. This does NOT satisfy a declaration scoped 'conversation'.
+     * The WORKSPACE databases this agent may query, by key.
      *
-     * A secret is written to this agent's own scope, so it is readable by this
-     * agent and nothing else in the workspace, and it overrides a workspace
-     * secret of the same name. Writing one twice replaces the value rather than
-     * failing, because `bind` means "this is the credential now".
+     * 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.
      *
-     * A connection value is the id of an account already attached to the
-     * workspace; use `authorize()` when there is no account yet, since that is
-     * the flow where a person signs in and no token passes through your code.
+     * 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.
+     */
+    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: async (key) => {
+            const res = await this.#http.post(`${this.base}/databases`, { key });
+            this.snapshot = res;
+            return this;
+        },
+        /** Stop this agent querying one database. The database stays registered
+         *  for every other agent that names it. */
+        detach: async (key) => {
+            const res = await this.#http.delete(`${this.base}/databases/${encodeURIComponent(key)}`);
+            if (res)
+                this.snapshot = res;
+            return this;
+        },
+        /** The keys this agent may query, in configuration order. */
+        list: async () => {
+            const current = this.snapshot ?? (await this.get());
+            return current.databases ?? [];
+        },
+    };
+    // ------------------------------------------------------------ connections
+    /**
+     * 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.
      *
-     * This used to POST the whole `{secrets, connections}` object to
-     * `/v1/agents/:id/bindings`, which answers only to `{kind, decl}` and records
-     * a DECLARATION, never a value. So the call 400'd, and had it not, it would
-     * have stored the fact that a secret is wanted rather than the secret.
+     * | 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
+     * 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));
+     * ```
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * Removing a connection never touches the account. Disconnecting an account
+     * is the other operation, on the account: `account.disconnect()`.
+     */
+    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: async (connection) => {
+            const res = await this.#http.post(`${this.base}/connections`, connectionForWire(connection));
+            this.snapshot = res;
+            return this;
+        },
+        /**
+         * 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: async (name, change) => {
+            // Read FRESH, never from the snapshot. A stale list sent back whole
+            // would silently undo whatever changed since it was read.
+            const current = (await this.get()).connections ?? [];
+            if (!current.some((c) => c.name === name)) {
+                throw new AgentNavaError({
+                    message: `This agent has no connection named "${name}". It has: ${current.map((c) => c.name).join(', ') || 'none'}.`,
+                    code: 'connection_not_found',
+                    status: 404,
+                });
+            }
+            const whose = change.endUser === true ? { endUser: true } : { account: accountIdOf(change.account) };
+            // Every other connection goes back exactly as it was read: this changes
+            // one, and must not reinterpret the rest.
+            const connections = current.map((c) => (c.name === name ? { name: c.name, app: c.app, ...whose } : c));
+            const data = await this.#http.post(`${this.base}/versions`, { connections });
+            this.snapshot = data;
+            return this;
+        },
+        /** 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: async (name) => {
+            const res = await this.#http.delete(`${this.base}/connections/${encodeURIComponent(name)}`);
+            if (res)
+                this.snapshot = res;
+            return this;
+        },
+        /**
+         * 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: async () => {
+            const res = await this.#http.get(`${this.base}/connections`);
+            return res.connections ?? [];
+        },
+    };
+    // ------------------------------------------------------ secrets, agent tier
+    /**
+     * Write secret VALUES to this agent's own scope: readable by this agent and
+     * nothing else in the workspace, overriding a workspace secret of the same
+     * name. Writing one twice replaces the value rather than failing, because
+     * attaching means "this is the credential now".
+     *
+     * This used to POST the whole object to `/v1/agents/:id/bindings`, which
+     * answers only to `{kind, decl}` and records a DECLARATION, never a value. So
+     * the call 400'd, and had it not, it would have stored the fact that a secret
+     * is wanted rather than the secret.
      */
     async #applyBindings(bindings) {
         for (const [name, value] of Object.entries(bindings.secrets ?? {})) {
@@ -185,144 +425,78 @@ export class Agent {
             else
                 await this.#http.post('/v1/secrets', { name, value, agentId: this.id });
         }
-        for (const [provider, connectionId] of Object.entries(bindings.connections ?? {})) {
-            await this.#http.post(`${this.base}/bindings`, {
-                kind: 'connection',
-                decl: { provider, connectionId, scope: 'fixed' },
-            });
-        }
         const data = await this.get();
         this.snapshot = data;
         return new _a(this.#http, this.id, data);
     }
     /**
-     * Give this agent a credential, so every conversation with it can use one.
+     * Give this agent secret values, so every conversation with it can use them.
      *
      * ```ts
-     * await agent.attach(gmail);                        // one account
-     * await agent.attach([gmail, calendar]);            // several
-     * await agent.attach({ secrets: { KEY: value } });  // a secret VALUE
+     * await agent.attach({ secrets: { APOLLO_API_KEY: value } });
      * ```
      *
-     * 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.
-     *
-     * 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.
-     */
-    async attach(what) {
-        if (isBindings(what))
-            return this.#applyBindings(what);
-        const split = splitAttachments(what);
-        const connections = await providersOf(split.connections);
-        const secretIds = await secretIdsOf(split.secrets);
-        return this.#applyBindings({
-            ...(connections && { connections }),
-            ...(secretIds && { secretIds }),
-        });
-    }
-    /** 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. */
-    async connections() {
-        // The MERGED view, not the raw connection rows. /v1/connections?agentId=
-        // lists rows that exist, so a provider the agent declares and nobody has
-        // connected is simply absent from it, which is the one case this method is
-        // most often asked about. The server merges declared against live with the
-        // same function the agent's own check_connections tool uses.
-        const res = await this.#http.get(`${this.base}/connections`);
-        return res.connections ?? [];
-    }
-    /**
-     * Attach a third-party account to this agent, at `fixed` scope: one account,
-     * used by every conversation.
-     *
-     * 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.
+     * 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.
      *
-     * 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.
+     * 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)`.
      */
-    async authorize(provider) {
-        const res = await this.#http.post('/v1/connections/connect', { provider, agentId: this.id });
-        // `url` on the way out, `authUrl` on the wire. The SDK's name is the one
-        // the reference documents and reads better at a call site.
-        return { url: res.authUrl, connectionId: res.connectionId };
-    }
-    /** 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". */
-    async disconnect(provider) {
-        const res = await this.#http.get('/v1/connections', {
-            agentId: this.id,
-        });
-        const match = (res.connections ?? [])
-            .map(toConnectionStatus)
-            .find((c) => c.provider === provider && c.connected);
-        // Nothing connected is not an error: the caller wanted this provider
-        // detached, and it is.
-        if (!match?.id)
-            return;
-        await this.#http.post(`/v1/connections/${encodeURIComponent(match.id)}/revoke`);
+    async attach(bindings) {
+        if (!isBindings(bindings)) {
+            throw new AgentNavaError({
+                message: 'agent.attach takes { secrets: { NAME: value } }. Accounts go in the agent\'s setup ' +
+                    '(agent.connections.add), and a stored secret attaches to a conversation ' +
+                    '(conversation.attach).',
+                code: 'not_a_secret',
+                status: 400,
+            });
+        }
+        refuseConnections(bindings);
+        return this.#applyBindings(bindings);
     }
     // ----------------------------------------------------------- conversations
-    /** Start a conversation. It pins the agent's version now and keeps it. */
+    /** 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`. */
     async start(options) {
-        // Resolved BEFORE the launch, because an account is named on the wire by
-        // its provider and a handle addressed by id may not know its own yet.
-        // Split first: a Connection is named on the wire by its PROVIDER and a
-        // Secret by the declared NAME it fills, so the two cannot share a map.
-        const split = splitAttachments(options.attach);
-        const connections = await providersOf(split.connections);
-        const secretIds = await secretIdsOf(split.secrets);
-        const bindings = options.secrets || connections || secretIds
+        const endUserId = requireEndUserId(options?.endUserId);
+        // Resolved BEFORE the launch: a Secret is named on the wire by the
+        // declared NAME it fills, and a handle addressed by id may not know its
+        // own yet. Anything that is not a Secret is refused here, by name.
+        const secretIds = await secretIdsOf(secretsIn(options.attach));
+        const bindings = options.secrets || secretIds
             ? {
                 ...(options.secrets && { secrets: options.secrets }),
                 ...(secretIds && { secretIds }),
-                ...(connections && { connections }),
             }
             : undefined;
         const data = await this.#http.post('/v1/conversations', {
             agentId: this.id,
             ...(options.version !== undefined && { version: options.version }),
             ...(options.parameters && { parameters: options.parameters }),
-            // `sessionBindings`, NOT `secrets` and `connections` at the top level.
+            // `sessionBindings`, NOT `secrets` at the top level.
             //
             // This sent them at the top level and the launch route reads
             // `body.sessionBindings`, so they were dropped in silence: the route's
-            // own body type has no top-level `secrets` or `connections` to read.
-            // A conversation started with a credential began without it, and the
-            // first turn failed somewhere else entirely.
+            // own body type has no top-level `secrets` to read. A conversation
+            // started with a credential began without it, and the first turn
+            // failed somewhere else entirely.
             //
             // Third place this exact envelope mistake was found in one afternoon,
             // after `agent.bind` and `conversation.bind`. The shape of the bug is
             // always the same: the SDK agrees with itself, the route agrees with
             // itself, and nothing compares the two.
             ...(bindings && { sessionBindings: bindings }),
-            // `!= null`, catching undefined as well as null. The field is REQUIRED
-            // in TypeScript, but a JavaScript caller can still omit it, and
-            // `!== null` alone then sent `user: {}`: an owner object with no id,
-            // which is neither "nobody" nor a person.
-            ...(options.endUserId != null && { user: { id: options.endUserId } }),
+            // Always present: requireEndUserId() above has already refused
+            // anything that is not a non-empty string.
+            user: { id: endUserId },
             // ALWAYS a new conversation, even when a user is named.
             //
             // The route resumes that user's most recent conversation when it is
@@ -389,6 +563,17 @@ export class Agent {
     }
 }
 _a = Agent;
-/** A connection row as `GET /v1/connections` returns it (toConnectionMeta in
- *  apps/api/src/connections/store.ts). */
+/** The end user a conversation belongs to: a non-empty string, or a thrown error before any request. */
+function requireEndUserId(value) {
+    // Checked at RUNTIME as well as in the type: a JavaScript caller, or a
+    // TypeScript one reading a nullable column, can still pass null, a number or
+    // ''. Each used to start an ownerless conversation that looked fine.
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    throw new AgentNavaError({
+        message: 'agent.start() needs endUserId: a non-empty string naming who the conversation is for (your user id, a visitor id, or a job name).',
+        code: 'end_user_required',
+        status: 400,
+    });
+}
 //# sourceMappingURL=agent.js.map