@cerebro-labs/agentnava-sdk 0.26.0 → 0.46.1

package/attach.js

@@ -1,49 +1,27 @@
-// Turning the credentials a caller is holding into what the wire speaks.
+// Turning the secrets a caller is holding into what the wire speaks.
 //
 // ITS OWN MODULE because `agent.ts` already imports `conversation.ts`, so a
 // helper living in either one and used by both is a cycle. Shared so that
 // `agent.start`, `agent.attach` and `conversation.attach` cannot drift: all
 // three had to agree on this shape, and when they did not, the disagreement was
 // invisible until a turn failed somewhere else.
-// VALUE imports, not type-only, because the split below is an `instanceof`.
-// Neither module imports anything but types, so this adds no cycle; `agent.ts`
-// and `conversation.ts` are the ones that could not import each other, which is
-// why this helper lives here in the first place.
-import { Connection as ConnectionClass } from "./connection.js";
+//
+// SECRETS ONLY, since 0.44. Accounts used to be attached here too, to an agent
+// or to one conversation, and a turn then had to work out which of several
+// attached and owned accounts to use. An agent's setup now names the account
+// each connection uses (`agent.connections.add`), so there is nothing left to
+// attach, and an account handed to any of these is refused by name rather than
+// dropped.
+import { AgentNavaError } from "./errors.js";
+// A VALUE import, not type-only, because the check below is an `instanceof`.
+// secret.ts imports nothing but types, so this adds no cycle.
 import { Secret } from "./secret.js";
 /**
- * Turn the accounts a caller is holding into the `{ provider: id }` map the
- * wire speaks.
+ * Distinguish `attach({ secrets })` from `attach(secret)`.
  *
- * A handle you created carries its provider already; one you addressed with
- * `ws.connection(id)` has to read it. That read is the only request here, and
- * only when it is unavoidable.
- */
-export async function providersOf(what) {
-    if (!what)
-        return undefined;
-    const list = Array.isArray(what) ? what : [what];
-    if (list.length === 0)
-        return undefined;
-    const out = {};
-    for (const connection of list) {
-        const provider = connection.provider ?? (await connection.get()).provider;
-        // Two different accounts for one provider in a single call is a caller
-        // mistake. A silent last-one-wins would surface much later as "the agent
-        // read the wrong mailbox", which is expensive to trace back to here.
-        if (out[provider] && out[provider] !== connection.id) {
-            throw new Error(`two different ${provider} accounts were attached in one call: ${out[provider]} and ${connection.id}`);
-        }
-        out[provider] = connection.id;
-    }
-    return out;
-}
-/**
- * Distinguish `attach({ secrets })` from `attach(connection)`.
- *
- * Structural rather than `instanceof`, so a Connection that crossed a module
- * boundary or was rebuilt from JSON is still recognised. A Connection always
- * has an `id`; a Bindings object has only `secrets` and `connections`.
+ * Structural rather than `instanceof`, so a plain object built anywhere is
+ * still recognised. A Secret always has an `id`; a Bindings object does not.
+ * `connections` is recognised too, only so it can be refused by name below.
  */
 export function isBindings(what) {
     if (Array.isArray(what) || what === null || typeof what !== 'object')
@@ -51,6 +29,43 @@ export function isBindings(what) {
     const o = what;
     return !('id' in o) && ('secrets' in o || 'connections' in o);
 }
+/** The words every refusal below uses, so an upgrader reads one explanation. */
+const ACCOUNTS_MOVED = 'Accounts are not attached any more (0.44): name the account in the agent\'s setup with ' +
+    'agent.connections.add(Connection.creatorAccount(app, account)), or use ' +
+    'Connection.endUserAccount(app) so each person signs in with their own.';
+/** Refuse `{ connections }`. A JavaScript caller still holding 0.43 code would
+ *  otherwise have it dropped in silence, and the agent would answer without the
+ *  account it was plainly given. */
+export function refuseConnections(bindings) {
+    if ('connections' in bindings) {
+        throw new AgentNavaError({ message: ACCOUNTS_MOVED, code: 'not_a_secret', status: 400 });
+    }
+}
+/**
+ * Check that everything handed to `attach` is a Secret, and hand back the list.
+ *
+ * BY `instanceof`, not by duck-typing: a Secret addressed with `ws.secret(id)`
+ * has no `name` until it reads one, so "has a name" answers wrongly for exactly
+ * the handles that need it most.
+ *
+ * Refused rather than ignored. Silently dropping an unrecognised attachment is
+ * how a conversation starts without the credential its caller plainly
+ * attached, and the failure then appears one layer down as a tool that cannot
+ * authenticate.
+ */
+export function secretsIn(what) {
+    const list = what === undefined ? [] : Array.isArray(what) ? what : [what];
+    for (const item of list) {
+        if (!(item instanceof Secret)) {
+            throw new AgentNavaError({
+                message: `attach takes a Secret. ${ACCOUNTS_MOVED}`,
+                code: 'not_a_secret',
+                status: 400,
+            });
+        }
+    }
+    return list;
+}
 /**
  * Turn stored secrets into the `{ DECLARED_NAME: secretId }` map the wire
  * speaks.
@@ -76,8 +91,7 @@ export async function secretIdsOf(what) {
         const name = secret.name ?? (await secret.get()).name;
         // Two different secrets under one name in a single call is a caller
         // mistake, and last-one-wins would surface much later as a tool failing
-        // on a credential that looks present. Same rule as two accounts for one
-        // provider, for the same reason.
+        // on a credential that looks present.
         if (out[name] && out[name] !== secret.id) {
             throw new Error(`two different secrets were attached as ${name}: ${out[name]} and ${secret.id}`);
         }
@@ -85,31 +99,4 @@ export async function secretIdsOf(what) {
     }
     return out;
 }
-/**
- * Split a mixed list into the accounts and the credentials.
- *
- * BY `instanceof`, not by duck-typing. A `Connection` addressed with
- * `ws.connection(id)` has no `provider` until it reads one, and a `Secret` from
- * `ws.secret(id)` has no `name`, so "has a provider" and "has a name" both
- * answer wrongly for exactly the handles that need splitting most.
- */
-export function splitAttachments(what) {
-    const list = what === undefined ? [] : Array.isArray(what) ? what : [what];
-    const connections = [];
-    const secrets = [];
-    for (const item of list) {
-        if (item instanceof Secret)
-            secrets.push(item);
-        else if (item instanceof ConnectionClass)
-            connections.push(item);
-        else {
-            // Refused rather than ignored. Silently dropping an unrecognised
-            // attachment is how a conversation starts without the credential its
-            // caller plainly attached, and the failure then appears one layer
-            // down as a tool that cannot authenticate.
-            throw new Error('attach takes a Connection or a Secret');
-        }
-    }
-    return { connections, secrets };
-}
 //# sourceMappingURL=attach.js.map

package/attach.js.map

@@ -1 +1 @@
-{"version":3,"file":"attach.js","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":"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","sourcesContent":["// Turning the credentials a caller is holding into what the wire speaks.\n//\n// ITS OWN MODULE because `agent.ts` already imports `conversation.ts`, so a\n// helper living in either one and used by both is a cycle. Shared so that\n// `agent.start`, `agent.attach` and `conversation.attach` cannot drift: all\n// three had to agree on this shape, and when they did not, the disagreement was\n// invisible until a turn failed somewhere else.\n\nimport type { Connection } from './connection.ts';\n// VALUE imports, not type-only, because the split below is an `instanceof`.\n// Neither module imports anything but types, so this adds no cycle; `agent.ts`\n// and `conversation.ts` are the ones that could not import each other, which is\n// why this helper lives here in the first place.\nimport { Connection as ConnectionClass } from './connection.ts';\nimport { Secret } from './secret.ts';\nimport type { Bindings } from './types.ts';\n\n/**\n * Turn the accounts a caller is holding into the `{ provider: id }` map the\n * wire speaks.\n *\n * A handle you created carries its provider already; one you addressed with\n * `ws.connection(id)` has to read it. That read is the only request here, and\n * only when it is unavoidable.\n */\nexport async function providersOf(\n\twhat: Connection | Connection[] | undefined,\n): Promise<Record<string, string> | undefined> {\n\tif (!what) return undefined;\n\tconst list = Array.isArray(what) ? what : [what];\n\tif (list.length === 0) return undefined;\n\tconst out: Record<string, string> = {};\n\tfor (const connection of list) {\n\t\tconst provider = connection.provider ?? (await connection.get()).provider;\n\t\t// Two different accounts for one provider in a single call is a caller\n\t\t// mistake. A silent last-one-wins would surface much later as \"the agent\n\t\t// read the wrong mailbox\", which is expensive to trace back to here.\n\t\tif (out[provider] && out[provider] !== connection.id) {\n\t\t\tthrow new Error(\n\t\t\t\t`two different ${provider} accounts were attached in one call: ${out[provider]} and ${connection.id}`,\n\t\t\t);\n\t\t}\n\t\tout[provider] = connection.id;\n\t}\n\treturn out;\n}\n\n/**\n * Distinguish `attach({ secrets })` from `attach(connection)`.\n *\n * Structural rather than `instanceof`, so a Connection that crossed a module\n * boundary or was rebuilt from JSON is still recognised. A Connection always\n * has an `id`; a Bindings object has only `secrets` and `connections`.\n */\nexport function isBindings(what: unknown): what is Bindings {\n\tif (Array.isArray(what) || what === null || typeof what !== 'object') return false;\n\tconst o = what as Record<string, unknown>;\n\treturn !('id' in o) && ('secrets' in o || 'connections' in o);\n}\n\n/**\n * Turn stored secrets into the `{ DECLARED_NAME: secretId }` map the wire\n * speaks.\n *\n * THE POINT OF SENDING AN ID RATHER THAN A VALUE. A secret stored against one\n * of your end users has no value you hold: the platform encrypted it when you\n * created it and never hands it back. Sending the id lets the launch resolve it\n * server-side, so attaching a credential does not require your process to have\n * read it.\n *\n * The NAME comes from the secret, because that is the name the agent declared\n * and the only thing it will look under. A handle you created carries it; one\n * you addressed by id has to read it, and that read is the only request here.\n */\nexport async function secretIdsOf(\n\twhat: Secret | Secret[] | undefined,\n): Promise<Record<string, string> | undefined> {\n\tif (!what) return undefined;\n\tconst list = Array.isArray(what) ? what : [what];\n\tif (list.length === 0) return undefined;\n\tconst out: Record<string, string> = {};\n\tfor (const secret of list) {\n\t\tconst name = secret.name ?? (await secret.get()).name;\n\t\t// Two different secrets under one name in a single call is a caller\n\t\t// mistake, and last-one-wins would surface much later as a tool failing\n\t\t// on a credential that looks present. Same rule as two accounts for one\n\t\t// provider, for the same reason.\n\t\tif (out[name] && out[name] !== secret.id) {\n\t\t\tthrow new Error(\n\t\t\t\t`two different secrets were attached as ${name}: ${out[name]} and ${secret.id}`,\n\t\t\t);\n\t\t}\n\t\tout[name] = secret.id;\n\t}\n\treturn out;\n}\n\n/** What a caller may hand to `attach`, or to `start({ attach })`. */\nexport type Attachable = Connection | Secret;\n\n/**\n * Split a mixed list into the accounts and the credentials.\n *\n * BY `instanceof`, not by duck-typing. A `Connection` addressed with\n * `ws.connection(id)` has no `provider` until it reads one, and a `Secret` from\n * `ws.secret(id)` has no `name`, so \"has a provider\" and \"has a name\" both\n * answer wrongly for exactly the handles that need splitting most.\n */\nexport function splitAttachments(\n\twhat: Attachable | Attachable[] | undefined,\n): { connections: Connection[]; secrets: Secret[] } {\n\tconst list = what === undefined ? [] : Array.isArray(what) ? what : [what];\n\tconst connections: Connection[] = [];\n\tconst secrets: Secret[] = [];\n\tfor (const item of list) {\n\t\tif (item instanceof Secret) secrets.push(item);\n\t\telse if (item instanceof ConnectionClass) connections.push(item);\n\t\telse {\n\t\t\t// Refused rather than ignored. Silently dropping an unrecognised\n\t\t\t// attachment is how a conversation starts without the credential its\n\t\t\t// caller plainly attached, and the failure then appears one layer\n\t\t\t// down as a tool that cannot authenticate.\n\t\t\tthrow new Error('attach takes a Connection or a Secret');\n\t\t}\n\t}\n\treturn { connections, secrets };\n}\n"]}
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":"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","sourcesContent":["// Turning the secrets a caller is holding into what the wire speaks.\n//\n// ITS OWN MODULE because `agent.ts` already imports `conversation.ts`, so a\n// helper living in either one and used by both is a cycle. Shared so that\n// `agent.start`, `agent.attach` and `conversation.attach` cannot drift: all\n// three had to agree on this shape, and when they did not, the disagreement was\n// invisible until a turn failed somewhere else.\n//\n// SECRETS ONLY, since 0.44. Accounts used to be attached here too, to an agent\n// or to one conversation, and a turn then had to work out which of several\n// attached and owned accounts to use. An agent's setup now names the account\n// each connection uses (`agent.connections.add`), so there is nothing left to\n// attach, and an account handed to any of these is refused by name rather than\n// dropped.\n\nimport { AgentNavaError } from './errors.ts';\n// A VALUE import, not type-only, because the check below is an `instanceof`.\n// secret.ts imports nothing but types, so this adds no cycle.\nimport { Secret } from './secret.ts';\nimport type { Bindings } from './types.ts';\n\n/** What the launch and the conversation's bindings route take: secret VALUES\n *  by declared name, and stored secrets by id. */\nexport interface SessionBindings {\n\tsecrets?: Record<string, string>;\n\tsecretIds?: Record<string, string>;\n}\n\n/**\n * Distinguish `attach({ secrets })` from `attach(secret)`.\n *\n * Structural rather than `instanceof`, so a plain object built anywhere is\n * still recognised. A Secret always has an `id`; a Bindings object does not.\n * `connections` is recognised too, only so it can be refused by name below.\n */\nexport function isBindings(what: unknown): what is Bindings {\n\tif (Array.isArray(what) || what === null || typeof what !== 'object') return false;\n\tconst o = what as Record<string, unknown>;\n\treturn !('id' in o) && ('secrets' in o || 'connections' in o);\n}\n\n/** The words every refusal below uses, so an upgrader reads one explanation. */\nconst ACCOUNTS_MOVED =\n\t'Accounts are not attached any more (0.44): name the account in the agent\\'s setup with ' +\n\t'agent.connections.add(Connection.creatorAccount(app, account)), or use ' +\n\t'Connection.endUserAccount(app) so each person signs in with their own.';\n\n/** Refuse `{ connections }`. A JavaScript caller still holding 0.43 code would\n *  otherwise have it dropped in silence, and the agent would answer without the\n *  account it was plainly given. */\nexport function refuseConnections(bindings: Bindings): void {\n\tif ('connections' in (bindings as Record<string, unknown>)) {\n\t\tthrow new AgentNavaError({ message: ACCOUNTS_MOVED, code: 'not_a_secret', status: 400 });\n\t}\n}\n\n/**\n * Check that everything handed to `attach` is a Secret, and hand back the list.\n *\n * BY `instanceof`, not by duck-typing: a Secret addressed with `ws.secret(id)`\n * has no `name` until it reads one, so \"has a name\" answers wrongly for exactly\n * the handles that need it most.\n *\n * Refused rather than ignored. Silently dropping an unrecognised attachment is\n * how a conversation starts without the credential its caller plainly\n * attached, and the failure then appears one layer down as a tool that cannot\n * authenticate.\n */\nexport function secretsIn(what: Secret | Secret[] | undefined): Secret[] {\n\tconst list = what === undefined ? [] : Array.isArray(what) ? what : [what];\n\tfor (const item of list) {\n\t\tif (!(item instanceof Secret)) {\n\t\t\tthrow new AgentNavaError({\n\t\t\t\tmessage: `attach takes a Secret. ${ACCOUNTS_MOVED}`,\n\t\t\t\tcode: 'not_a_secret',\n\t\t\t\tstatus: 400,\n\t\t\t});\n\t\t}\n\t}\n\treturn list;\n}\n\n/**\n * Turn stored secrets into the `{ DECLARED_NAME: secretId }` map the wire\n * speaks.\n *\n * THE POINT OF SENDING AN ID RATHER THAN A VALUE. A secret stored against one\n * of your end users has no value you hold: the platform encrypted it when you\n * created it and never hands it back. Sending the id lets the launch resolve it\n * server-side, so attaching a credential does not require your process to have\n * read it.\n *\n * The NAME comes from the secret, because that is the name the agent declared\n * and the only thing it will look under. A handle you created carries it; one\n * you addressed by id has to read it, and that read is the only request here.\n */\nexport async function secretIdsOf(\n\twhat: Secret | Secret[] | undefined,\n): Promise<Record<string, string> | undefined> {\n\tif (!what) return undefined;\n\tconst list = Array.isArray(what) ? what : [what];\n\tif (list.length === 0) return undefined;\n\tconst out: Record<string, string> = {};\n\tfor (const secret of list) {\n\t\tconst name = secret.name ?? (await secret.get()).name;\n\t\t// Two different secrets under one name in a single call is a caller\n\t\t// mistake, and last-one-wins would surface much later as a tool failing\n\t\t// on a credential that looks present.\n\t\tif (out[name] && out[name] !== secret.id) {\n\t\t\tthrow new Error(\n\t\t\t\t`two different secrets were attached as ${name}: ${out[name]} and ${secret.id}`,\n\t\t\t);\n\t\t}\n\t\tout[name] = secret.id;\n\t}\n\treturn out;\n}\n"]}

package/connection.d.ts

@@ -1,89 +1,86 @@
-import type { Http } from './http.ts';
-import type { CredentialOwner, ConnectionStatus } from './types.ts';
+import { type Account } from './account.ts';
+import type { AppId } from './apps.generated.ts';
+/** A connection that uses the AGENT CREATOR'S ACCOUNT: one account in this
+ *  workspace, signed in once, used by every conversation. `account` is the
+ *  `Account` you hold or its id; an `Account` goes over the wire as its id. */
+export interface CreatorAccountConnection {
+    name?: string;
+    app: AppId;
+    account: Account | string;
+    endUser?: never;
+}
+/** A connection that uses the END USER'S ACCOUNT: each person talking to the
+ *  agent signs in with their own, once, and it is remembered for them. */
+export interface EndUserAccountConnection {
+    name?: string;
+    app: AppId;
+    endUser: true;
+    account?: never;
+}
 /**
- * An account somebody attached, that you hold and act on.
+ * One connection, as you hand it to `ws.agents.create()`, `agent.update()` or
+ * `agent.connections.add()`: an app, and whose account.
  *
- * A CLASS, like `Agent`, `Conversation`, `Project` and `KnowledgeBase`. It was
- * briefly a bare `ConnectionStatus` with an id you carried around as a string,
- * which made it the only thing in this SDK you could not hold. Holding it is
- * the point: you create one, wait for the person to finish signing in, attach
- * it where it is needed, and revoke it when they leave, and each of those is a
- * method on the thing rather than a call with an id threaded through it.
+ * Build it with `Connection.creatorAccount()` or `Connection.endUserAccount()`,
+ * which ask the same question the portal's Add a connection screen asks. Or
+ * write the object yourself: `{ app, account }` or `{ app, endUser: true }`.
+ * Exactly one of the two, and the type says so, so a connection with both, or
+ * with neither, does not compile.
+ */
+export type Connection = CreatorAccountConnection | EndUserAccountConnection;
+/**
+ * Build the entries of an agent's setup.
  *
  * ```ts
- * const gmail = await ws.connections.create({ provider: 'gmail', endUserId: 'u_ananya' });
- * showToUser(gmail.url);
- * await gmail.waitUntilConnected();
- * await agent.attach(gmail);
+ * import { App, Connection } from '@cerebro-labs/agentnava-sdk';
+ *
+ * await ws.agents.create({
+ *   name: 'Inbox helper',
+ *   instructions: '...',
+ *   connections: [
+ *     Connection.creatorAccount(App.GMAIL, work, { name: 'work-gmail' }),
+ *     Connection.creatorAccount(App.GMAIL, personal, { name: 'personal-gmail' }),
+ *     Connection.endUserAccount(App.GOOGLE_CALENDAR),
+ *   ],
+ * });
  * ```
  *
- * Holding one makes no request. `ws.connection(id)` is free and the first call
- * on it is the first round trip.
+ * WHY BUILDERS. Whose account a connection uses is the one decision that
+ * matters, and it used to be spelled `scope: 'fixed'` or `scope:
+ * 'conversation'`, words that answered a different question. These two names
+ * are the question itself, as the screen asks it: the agent creator's account,
+ * or the end user's account.
+ *
+ * NOT THE 0.43 `Connection`. That was a handle on a signed-in account and is
+ * now `Account`. This name builds an entry for an agent's setup; it holds
+ * nothing and makes no request.
+ *
+ * `name` tells two connections of one app apart, such as two Gmail accounts.
+ * Lowercase letters, digits and dashes, up to 64 characters, unique on the
+ * agent. Left out, it is the app's id.
  */
-export declare class Connection {
-    #private;
-    readonly id: string;
-    /** Present when the person has not finished signing in yet: the url to send
-     *  them to. Absent on a connection you looked up rather than created. */
-    readonly url?: string;
-    private snapshot?;
-    constructor(http: Http, id: string, snapshot?: ConnectionStatus, url?: string);
-    /** Which third party this is: `'gmail'`, `'hubspot'`. Named for what the
-     *  person connecting recognises, never for whoever we buy it from. */
-    get provider(): string | undefined;
-    /** True once the account is attached and usable.
-     *
-     *  Reads the last snapshot rather than the network, the same rule
-     *  `conversation.ready` follows. Undefined means this handle has not read
-     *  yet, NOT that it is disconnected. */
-    get connected(): boolean | undefined;
-    /** The raw status string, for the cases where the boolean is too coarse:
-     *  'pending' and 'error' are both "not connected" and mean opposite things.
-     *  This used to be reachable only through `.data`, the whole-snapshot escape
-     *  hatch, which is a poor thing to make a caller reach for. */
-    get status(): string | undefined;
-    /**
-     * Whose account it is: the workspace's, one agent's, one of YOUR END USERS',
-     * or one conversation's.
-     *
-     * DERIVED HERE, from which id the row carries, rather than read off a field.
-     * This getter used to return `snapshot.scope`, which is a different question
-     * entirely: `scope` is what an agent DECLARED it needs ('fixed' or
-     * 'conversation'), and the server never sent an ownership field at all. So
-     * it answered `undefined` for every connection you looked up, and for one
-     * you had just created it answered `'user'`, a value outside its own
-     * declared type that only compiled through an `as never` cast.
-     *
-     * Most specific first: a conversation's own account, then an end user's,
-     * then an agent's, then the workspace's.
-     */
-    get owner(): CredentialOwner | undefined;
-    /** One of YOUR end users, when this account is theirs. Never a workspace
-     *  member: the two are separate id namespaces. */
-    get endUserId(): string | null | undefined;
-    /** The last-known state, from whatever call produced this object. */
-    get data(): ConnectionStatus | undefined;
-    /** Read it back. */
-    get(): Promise<ConnectionStatus>;
-    /**
-     * Wait until the person has finished signing in.
-     *
-     * The companion to `create()`. That hands you a url; this tells you when
-     * they are done, so you do not write a polling loop or guess which field to
-     * believe.
-     *
-     * Polls rather than subscribing: there is a human in the middle, so a few
-     * seconds costs nothing and it works from any runtime without a socket.
-     */
-    waitUntilConnected(options?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }): Promise<Connection>;
-    /**
-     * Detach the account and drop its tokens.
-     *
-     * This is what off-boarding calls. Every conversation using it stops acting
-     * as that person from the next turn; nothing is retained.
-     */
-    revoke(): Promise<void>;
-}
+export declare const Connection: {
+    /** A connection that uses the agent creator's account: the `Account` you
+     *  hold, or its id. Produces `{ name?, app, account: '<id>' }`. */
+    creatorAccount(app: AppId, account: Account | string, options?: {
+        name?: string;
+    }): CreatorAccountConnection & {
+        account: string;
+    };
+    /** A connection that uses the end user's account: whichever account of
+     *  `app` the person each conversation is for has connected. Produces
+     *  `{ name?, app, endUser: true }`. */
+    endUserAccount(app: AppId, options?: {
+        name?: string;
+    }): EndUserAccountConnection;
+};
+/**
+ * One connection as `POST /v1/agents/:id/connections` takes it: the fields it
+ * declares, picked by name, and an `Account` by its id.
+ *
+ * Picked, never forwarded: a JavaScript caller holding 0.43 code could pass
+ * `provider` or `scope`, and those must not reach the route as if they meant
+ * something. Neither `account` nor `endUser` is invented here: whatever was
+ * given goes, and the API names the problem when it is not exactly one.
+ */
+export declare function connectionForWire(connection: Connection): Record<string, unknown>;

package/connection.js

@@ -1,143 +1,76 @@
-// A connection: a third-party account an agent acts through.
+// A connection: one entry in an agent's setup. An app, and whose account.
+import { accountIdOf } from "./account.js";
+import { AgentNavaError } from "./errors.js";
 /**
- * An account somebody attached, that you hold and act on.
- *
- * A CLASS, like `Agent`, `Conversation`, `Project` and `KnowledgeBase`. It was
- * briefly a bare `ConnectionStatus` with an id you carried around as a string,
- * which made it the only thing in this SDK you could not hold. Holding it is
- * the point: you create one, wait for the person to finish signing in, attach
- * it where it is needed, and revoke it when they leave, and each of those is a
- * method on the thing rather than a call with an id threaded through it.
+ * Build the entries of an agent's setup.
  *
  * ```ts
- * const gmail = await ws.connections.create({ provider: 'gmail', endUserId: 'u_ananya' });
- * showToUser(gmail.url);
- * await gmail.waitUntilConnected();
- * await agent.attach(gmail);
+ * import { App, Connection } from '@cerebro-labs/agentnava-sdk';
+ *
+ * await ws.agents.create({
+ *   name: 'Inbox helper',
+ *   instructions: '...',
+ *   connections: [
+ *     Connection.creatorAccount(App.GMAIL, work, { name: 'work-gmail' }),
+ *     Connection.creatorAccount(App.GMAIL, personal, { name: 'personal-gmail' }),
+ *     Connection.endUserAccount(App.GOOGLE_CALENDAR),
+ *   ],
+ * });
  * ```
  *
- * Holding one makes no request. `ws.connection(id)` is free and the first call
- * on it is the first round trip.
+ * WHY BUILDERS. Whose account a connection uses is the one decision that
+ * matters, and it used to be spelled `scope: 'fixed'` or `scope:
+ * 'conversation'`, words that answered a different question. These two names
+ * are the question itself, as the screen asks it: the agent creator's account,
+ * or the end user's account.
+ *
+ * NOT THE 0.43 `Connection`. That was a handle on a signed-in account and is
+ * now `Account`. This name builds an entry for an agent's setup; it holds
+ * nothing and makes no request.
+ *
+ * `name` tells two connections of one app apart, such as two Gmail accounts.
+ * Lowercase letters, digits and dashes, up to 64 characters, unique on the
+ * agent. Left out, it is the app's id.
  */
-export class Connection {
-    id;
-    #http;
-    /** Present when the person has not finished signing in yet: the url to send
-     *  them to. Absent on a connection you looked up rather than created. */
-    url;
-    snapshot;
-    constructor(http, id, snapshot, url) {
-        this.#http = http;
-        this.id = id;
-        if (snapshot)
-            this.snapshot = snapshot;
-        if (url)
-            this.url = url;
-    }
-    /** Which third party this is: `'gmail'`, `'hubspot'`. Named for what the
-     *  person connecting recognises, never for whoever we buy it from. */
-    get provider() {
-        return this.snapshot?.provider;
-    }
-    /** True once the account is attached and usable.
-     *
-     *  Reads the last snapshot rather than the network, the same rule
-     *  `conversation.ready` follows. Undefined means this handle has not read
-     *  yet, NOT that it is disconnected. */
-    get connected() {
-        const s = this.snapshot;
-        if (!s)
-            return undefined;
-        // Belt as well as braces. Every list path now normalises before
-        // constructing a Connection, but this object is also built directly from
-        // server payloads elsewhere, and a pass-through here meant a row that
-        // plainly said `status: 'connected'` reported `connected === undefined`.
-        return s.connected ?? s.status === 'connected';
-    }
-    /** The raw status string, for the cases where the boolean is too coarse:
-     *  'pending' and 'error' are both "not connected" and mean opposite things.
-     *  This used to be reachable only through `.data`, the whole-snapshot escape
-     *  hatch, which is a poor thing to make a caller reach for. */
-    get status() {
-        return this.snapshot?.status;
-    }
-    /**
-     * Whose account it is: the workspace's, one agent's, one of YOUR END USERS',
-     * or one conversation's.
-     *
-     * DERIVED HERE, from which id the row carries, rather than read off a field.
-     * This getter used to return `snapshot.scope`, which is a different question
-     * entirely: `scope` is what an agent DECLARED it needs ('fixed' or
-     * 'conversation'), and the server never sent an ownership field at all. So
-     * it answered `undefined` for every connection you looked up, and for one
-     * you had just created it answered `'user'`, a value outside its own
-     * declared type that only compiled through an `as never` cast.
-     *
-     * Most specific first: a conversation's own account, then an end user's,
-     * then an agent's, then the workspace's.
-     */
-    get owner() {
-        const s = this.snapshot;
-        if (!s)
-            return undefined;
-        if (s.conversationId)
-            return 'conversation';
-        if (s.endUserId)
-            return 'endUser';
-        if (s.agentId)
-            return 'agent';
-        return 'workspace';
-    }
-    /** One of YOUR end users, when this account is theirs. Never a workspace
-     *  member: the two are separate id namespaces. */
-    get endUserId() {
-        return this.snapshot?.endUserId;
-    }
-    /** The last-known state, from whatever call produced this object. */
-    get data() {
-        return this.snapshot;
-    }
-    /** Read it back. */
-    async get() {
-        const res = await this.#http.get('/v1/connections');
-        const mine = (res.connections ?? []).find((c) => c.id === this.id);
-        if (mine)
-            this.snapshot = mine;
-        return mine ?? { id: this.id, provider: '', declared: false, required: false, connected: false };
-    }
-    /**
-     * Wait until the person has finished signing in.
-     *
-     * The companion to `create()`. That hands you a url; this tells you when
-     * they are done, so you do not write a polling loop or guess which field to
-     * believe.
-     *
-     * Polls rather than subscribing: there is a human 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 already-connected account should
-        // cost one request, not one request plus an interval.
-        let state = await this.get();
-        while (!state.connected) {
-            if (Date.now() >= deadline)
-                return this;
-            await new Promise((r) => setTimeout(r, Math.min(intervalMs, Math.max(0, deadline - Date.now()))));
-            state = await this.get();
+export const Connection = {
+    /** A connection that uses the agent creator's account: the `Account` you
+     *  hold, or its id. Produces `{ name?, app, account: '<id>' }`. */
+    creatorAccount(app, account, options = {}) {
+        const id = accountIdOf(account);
+        // Thrown here, naming the mistake, rather than sent as a connection with
+        // no account for the API to refuse in other words.
+        if (typeof id !== 'string' || !id) {
+            throw new AgentNavaError({
+                message: `Connection.creatorAccount(${JSON.stringify(app)}, ...) needs the Account, or its id.`,
+                code: 'account_required',
+                status: 400,
+            });
         }
-        return this;
-    }
-    /**
-     * Detach the account and drop its tokens.
-     *
-     * This is what off-boarding calls. Every conversation using it stops acting
-     * as that person from the next turn; nothing is retained.
-     */
-    async revoke() {
-        await this.#http.post(`/v1/connections/${encodeURIComponent(this.id)}/revoke`);
-    }
+        return { ...(options.name !== undefined && { name: options.name }), app, account: id };
+    },
+    /** A connection that uses the end user's account: whichever account of
+     *  `app` the person each conversation is for has connected. Produces
+     *  `{ name?, app, endUser: true }`. */
+    endUserAccount(app, options = {}) {
+        return { ...(options.name !== undefined && { name: options.name }), app, endUser: true };
+    },
+};
+/**
+ * One connection as `POST /v1/agents/:id/connections` takes it: the fields it
+ * declares, picked by name, and an `Account` by its id.
+ *
+ * Picked, never forwarded: a JavaScript caller holding 0.43 code could pass
+ * `provider` or `scope`, and those must not reach the route as if they meant
+ * something. Neither `account` nor `endUser` is invented here: whatever was
+ * given goes, and the API names the problem when it is not exactly one.
+ */
+export function connectionForWire(connection) {
+    const c = connection;
+    return {
+        ...(c.name !== undefined && { name: c.name }),
+        app: c.app,
+        ...(c.account !== undefined && { account: accountIdOf(c.account) }),
+        ...(c.endUser !== undefined && { endUser: c.endUser }),
+    };
 }
 //# sourceMappingURL=connection.js.map