@cerebro-labs/agentnava-sdk 0.26.0 → 0.46.1

package/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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","sourcesContent":["// A connection: a third-party account an agent acts through.\n\nimport type { Http } from './http.ts';\nimport type { CredentialOwner, ConnectionStatus } from './types.ts';\n\n/**\n * An account somebody attached, that you hold and act on.\n *\n * A CLASS, like `Agent`, `Conversation`, `Project` and `KnowledgeBase`. It was\n * briefly a bare `ConnectionStatus` with an id you carried around as a string,\n * which made it the only thing in this SDK you could not hold. Holding it is\n * the point: you create one, wait for the person to finish signing in, attach\n * it where it is needed, and revoke it when they leave, and each of those is a\n * method on the thing rather than a call with an id threaded through it.\n *\n * ```ts\n * const gmail = await ws.connections.create({ provider: 'gmail', endUserId: 'u_ananya' });\n * showToUser(gmail.url);\n * await gmail.waitUntilConnected();\n * await agent.attach(gmail);\n * ```\n *\n * Holding one makes no request. `ws.connection(id)` is free and the first call\n * on it is the first round trip.\n */\nexport class Connection {\n\treadonly id: string;\n\treadonly #http: Http;\n\t/** Present when the person has not finished signing in yet: the url to send\n\t *  them to. Absent on a connection you looked up rather than created. */\n\treadonly url?: string;\n\tprivate snapshot?: ConnectionStatus;\n\n\tconstructor(http: Http, id: string, snapshot?: ConnectionStatus, url?: string) {\n\t\tthis.#http = http;\n\t\tthis.id = id;\n\t\tif (snapshot) this.snapshot = snapshot;\n\t\tif (url) this.url = url;\n\t}\n\n\t/** Which third party this is: `'gmail'`, `'hubspot'`. Named for what the\n\t *  person connecting recognises, never for whoever we buy it from. */\n\tget provider(): string | undefined {\n\t\treturn this.snapshot?.provider;\n\t}\n\n\t/** True once the account is attached and usable.\n\t *\n\t *  Reads the last snapshot rather than the network, the same rule\n\t *  `conversation.ready` follows. Undefined means this handle has not read\n\t *  yet, NOT that it is disconnected. */\n\tget connected(): boolean | undefined {\n\t\tconst s = this.snapshot;\n\t\tif (!s) return undefined;\n\t\t// Belt as well as braces. Every list path now normalises before\n\t\t// constructing a Connection, but this object is also built directly from\n\t\t// server payloads elsewhere, and a pass-through here meant a row that\n\t\t// plainly said `status: 'connected'` reported `connected === undefined`.\n\t\treturn s.connected ?? s.status === 'connected';\n\t}\n\n\t/** The raw status string, for the cases where the boolean is too coarse:\n\t *  'pending' and 'error' are both \"not connected\" and mean opposite things.\n\t *  This used to be reachable only through `.data`, the whole-snapshot escape\n\t *  hatch, which is a poor thing to make a caller reach for. */\n\tget status(): string | undefined {\n\t\treturn this.snapshot?.status;\n\t}\n\n\t/**\n\t * Whose account it is: the workspace's, one agent's, one of YOUR END USERS',\n\t * or one conversation's.\n\t *\n\t * DERIVED HERE, from which id the row carries, rather than read off a field.\n\t * This getter used to return `snapshot.scope`, which is a different question\n\t * entirely: `scope` is what an agent DECLARED it needs ('fixed' or\n\t * 'conversation'), and the server never sent an ownership field at all. So\n\t * it answered `undefined` for every connection you looked up, and for one\n\t * you had just created it answered `'user'`, a value outside its own\n\t * declared type that only compiled through an `as never` cast.\n\t *\n\t * Most specific first: a conversation's own account, then an end user's,\n\t * then an agent's, then the workspace's.\n\t */\n\tget owner(): CredentialOwner | undefined {\n\t\tconst s = this.snapshot;\n\t\tif (!s) return undefined;\n\t\tif (s.conversationId) return 'conversation';\n\t\tif (s.endUserId) return 'endUser';\n\t\tif (s.agentId) return 'agent';\n\t\treturn 'workspace';\n\t}\n\n\t/** One of YOUR end users, when this account is theirs. Never a workspace\n\t *  member: the two are separate id namespaces. */\n\tget endUserId(): string | null | undefined {\n\t\treturn this.snapshot?.endUserId;\n\t}\n\n\t/** The last-known state, from whatever call produced this object. */\n\tget data(): ConnectionStatus | undefined {\n\t\treturn this.snapshot;\n\t}\n\n\t/** Read it back. */\n\tasync get(): Promise<ConnectionStatus> {\n\t\tconst res = await this.#http.get<{ connections: ConnectionStatus[] }>('/v1/connections');\n\t\tconst mine = (res.connections ?? []).find((c) => c.id === this.id);\n\t\tif (mine) this.snapshot = mine;\n\t\treturn mine ?? ({ id: this.id, provider: '', declared: false, required: false, connected: false } as ConnectionStatus);\n\t}\n\n\t/**\n\t * Wait until the person has finished signing in.\n\t *\n\t * The companion to `create()`. That hands you a url; this tells you when\n\t * they are done, so you do not write a polling loop or guess which field to\n\t * believe.\n\t *\n\t * Polls rather than subscribing: there is a human 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<Connection> {\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 already-connected account should\n\t\t// cost one request, not one request plus an interval.\n\t\tlet state = await this.get();\n\t\twhile (!state.connected) {\n\t\t\tif (Date.now() >= deadline) return this;\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 * Detach the account and drop its tokens.\n\t *\n\t * This is what off-boarding calls. Every conversation using it stops acting\n\t * as that person from the next turn; nothing is retained.\n\t */\n\tasync revoke(): Promise<void> {\n\t\tawait this.#http.post(`/v1/connections/${encodeURIComponent(this.id)}/revoke`);\n\t}\n}\n"]}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,OAAO,EAAgB,WAAW,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAiC7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACzB;uEACmE;IACnE,cAAc,CAAC,GAAU,EAAE,OAAyB,EAAE,UAA6B,EAAE;QAGpF,MAAM,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAChC,yEAAyE;QACzE,mDAAmD;QACnD,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,IAAI,cAAc,CAAC;gBACxB,OAAO,EAAE,6BAA6B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,sCAAsC;gBAC/F,IAAI,EAAE,kBAAkB;gBACxB,MAAM,EAAE,GAAG;aACX,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACxF,CAAC;IAED;;2CAEuC;IACvC,cAAc,CAAC,GAAU,EAAE,UAA6B,EAAE;QACzD,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1F,CAAC;CACD,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAsB;IACvD,MAAM,CAAC,GAAG,UAA0F,CAAC;IACrG,OAAO;QACN,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7C,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,GAAG,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;KACtD,CAAC;AACH,CAAC","sourcesContent":["// A connection: one entry in an agent's setup. An app, and whose account.\n\nimport { type Account, accountIdOf } from './account.ts';\nimport type { AppId } from './apps.generated.ts';\nimport { AgentNavaError } from './errors.ts';\n\n/** A connection that uses the AGENT CREATOR'S ACCOUNT: one account in this\n *  workspace, signed in once, used by every conversation. `account` is the\n *  `Account` you hold or its id; an `Account` goes over the wire as its id. */\nexport interface CreatorAccountConnection {\n\tname?: string;\n\tapp: AppId;\n\taccount: Account | string;\n\tendUser?: never;\n}\n\n/** A connection that uses the END USER'S ACCOUNT: each person talking to the\n *  agent signs in with their own, once, and it is remembered for them. */\nexport interface EndUserAccountConnection {\n\tname?: string;\n\tapp: AppId;\n\tendUser: true;\n\taccount?: never;\n}\n\n/**\n * One connection, as you hand it to `ws.agents.create()`, `agent.update()` or\n * `agent.connections.add()`: an app, and whose account.\n *\n * Build it with `Connection.creatorAccount()` or `Connection.endUserAccount()`,\n * which ask the same question the portal's Add a connection screen asks. Or\n * write the object yourself: `{ app, account }` or `{ app, endUser: true }`.\n * Exactly one of the two, and the type says so, so a connection with both, or\n * with neither, does not compile.\n */\nexport type Connection = CreatorAccountConnection | EndUserAccountConnection;\n\n/**\n * Build the entries of an agent's setup.\n *\n * ```ts\n * import { App, Connection } from '@cerebro-labs/agentnava-sdk';\n *\n * await ws.agents.create({\n *   name: 'Inbox helper',\n *   instructions: '...',\n *   connections: [\n *     Connection.creatorAccount(App.GMAIL, work, { name: 'work-gmail' }),\n *     Connection.creatorAccount(App.GMAIL, personal, { name: 'personal-gmail' }),\n *     Connection.endUserAccount(App.GOOGLE_CALENDAR),\n *   ],\n * });\n * ```\n *\n * WHY BUILDERS. Whose account a connection uses is the one decision that\n * matters, and it used to be spelled `scope: 'fixed'` or `scope:\n * 'conversation'`, words that answered a different question. These two names\n * are the question itself, as the screen asks it: the agent creator's account,\n * or the end user's account.\n *\n * NOT THE 0.43 `Connection`. That was a handle on a signed-in account and is\n * now `Account`. This name builds an entry for an agent's setup; it holds\n * nothing and makes no request.\n *\n * `name` tells two connections of one app apart, such as two Gmail accounts.\n * Lowercase letters, digits and dashes, up to 64 characters, unique on the\n * agent. Left out, it is the app's id.\n */\nexport const Connection = {\n\t/** A connection that uses the agent creator's account: the `Account` you\n\t *  hold, or its id. Produces `{ name?, app, account: '<id>' }`. */\n\tcreatorAccount(app: AppId, account: Account | string, options: { name?: string } = {}): CreatorAccountConnection & {\n\t\taccount: string;\n\t} {\n\t\tconst id = accountIdOf(account);\n\t\t// Thrown here, naming the mistake, rather than sent as a connection with\n\t\t// no account for the API to refuse in other words.\n\t\tif (typeof id !== 'string' || !id) {\n\t\t\tthrow new AgentNavaError({\n\t\t\t\tmessage: `Connection.creatorAccount(${JSON.stringify(app)}, ...) needs the Account, or its id.`,\n\t\t\t\tcode: 'account_required',\n\t\t\t\tstatus: 400,\n\t\t\t});\n\t\t}\n\t\treturn { ...(options.name !== undefined && { name: options.name }), app, account: id };\n\t},\n\n\t/** A connection that uses the end user's account: whichever account of\n\t *  `app` the person each conversation is for has connected. Produces\n\t *  `{ name?, app, endUser: true }`. */\n\tendUserAccount(app: AppId, options: { name?: string } = {}): EndUserAccountConnection {\n\t\treturn { ...(options.name !== undefined && { name: options.name }), app, endUser: true };\n\t},\n};\n\n/**\n * One connection as `POST /v1/agents/:id/connections` takes it: the fields it\n * declares, picked by name, and an `Account` by its id.\n *\n * Picked, never forwarded: a JavaScript caller holding 0.43 code could pass\n * `provider` or `scope`, and those must not reach the route as if they meant\n * something. Neither `account` nor `endUser` is invented here: whatever was\n * given goes, and the API names the problem when it is not exactly one.\n */\nexport function connectionForWire(connection: Connection): Record<string, unknown> {\n\tconst c = connection as { name?: string; app: AppId; account?: Account | string; endUser?: boolean };\n\treturn {\n\t\t...(c.name !== undefined && { name: c.name }),\n\t\tapp: c.app,\n\t\t...(c.account !== undefined && { account: accountIdOf(c.account) }),\n\t\t...(c.endUser !== undefined && { endUser: c.endUser }),\n\t};\n}\n"]}

package/conversation.d.ts

@@ -1,10 +1,21 @@
-import { type Attachable } from './attach.ts';
-import type { Http } from './http.ts';
+import { type Http } from './http.ts';
+import type { Secret } from './secret.ts';
 import { type Turn } from './turn.ts';
-import type { AgentConversationData, Attachment, Bindings, FileEntry, Message, Requirement } from './types.ts';
+import type { AccountNeeded, AgentConversationData, Attachment, Bindings, FileEntry, Message, Requirement } from './types.ts';
 export interface AskOptions {
     attachments?: Attachment[];
+    /**
+     * Stop receiving this turn's response. An already-aborted signal prevents
+     * submission, so no turn is accepted or charged for this call. After the
+     * server accepts a turn, aborting stops observation: accepted work can
+     * continue and normal billing applies, with no automatic refund or server
+     * cancellation. Read conversation.messages() before asking again.
+     */
     signal?: AbortSignal;
+    /** Stable identity for one submission. Reuse it only for the same content
+     * after a lost response; a new intentional turn needs a new key. Defaults to
+     * a generated key. Use 1–128 letters, digits, dots, underscores, colons or hyphens. */
+    idempotencyKey?: string;
 }
 export interface FileUrlOptions {
     download?: boolean;
@@ -43,8 +54,8 @@ export declare class Conversation {
      *
      * EVERY CONVERSATION BELONGS TO EXACTLY ONE AGENT. That is the model, and it
      * is worth stating on the object because the SDK used to hold this value and
-     * never show it: `authorize()` read it internally and nothing else could,
-     * which made a conversation look parentless from outside.
+     * never show it: a method read it internally and nothing else could, which
+     * made a conversation look parentless from outside.
      *
      * Undefined on a conversation you addressed by id and have not read yet,
      * for the same reason `ready` is: the handle has made no request. Call
@@ -64,12 +75,16 @@ export declare class Conversation {
     get ready(): boolean | undefined;
     /** What the conversation is still missing. Same caveat as `ready`. */
     get requires(): Requirement[];
+    /** The number of the agent version it runs, from the last snapshot. Same
+     *  caveat as `ready`: a schedule naming this conversation moves it to the
+     *  latest version, and only `get()` sees that. */
+    get version(): number | undefined;
     get(): Promise<AgentConversationData>;
     /**
      * Ask, and get the reply.
      *
      * The message is sent HERE, not when you await or iterate the result, so
-     * calling this twice asks twice. Await it for the answer or iterate it for
+     * calling this twice with new keys asks twice. Await it for the answer or iterate it for
      * the events; doing both to the same turn throws rather than replaying.
      */
     ask(text: string, options?: AskOptions): Turn;
@@ -77,52 +92,57 @@ export declare class Conversation {
     /** End it, and its drive with it. */
     end(): Promise<void>;
     /**
-     * Give THIS conversation a credential, and nothing else.
+     * Give THIS conversation a secret, and nothing else.
      *
      * ```ts
-     * await conversation.attach(gmail);                       // one account
-     * await conversation.attach([gmail, calendar]);           // several
-     * await conversation.attach({ secrets: { KEY: value } }); // a secret VALUE
+     * await conversation.attach(key);                          // a stored Secret, by id
+     * await conversation.attach({ secrets: { KEY: value } });  // a secret VALUE
      * ```
      *
-     * ONE VERB. `bind` used to sit beside this doing the same job in a different
-     * shape, and is gone: two names for one idea is how a surface becomes hard
-     * to learn.
+     * The narrowest scope there is: it reaches this conversation only.
      *
-     * The narrowest scope there is. It cannot overwrite the agent's shared
-     * account or the person's own (ADR 0017).
+     * SECRETS ONLY, since 0.44. An account is never attached to a conversation
+     * any more: the agent's setup names whose account each connection uses, and
+     * for the end user's account the turn uses the account of the person this
+     * conversation is for. One handed in here is refused by name
+     * (`not_a_secret`) rather than dropped. `accountsNeeded()` says which of
+     * that person's accounts are still missing.
      *
      * PREFER `agent.start({ attach })` when you already know at launch. Between
      * a start and a later attach there is a window in which the conversation
-     * exists, can be asked something, and would answer without the account.
+     * exists, can be asked something, and would answer without the secret.
      */
-    attach(what: Attachable | Attachable[] | Bindings): Promise<AgentConversationData>;
+    attach(what: Secret | Secret[] | Bindings): Promise<AgentConversationData>;
     /**
-     * Attach a third-party account to THIS conversation, at `conversation` scope.
+     * The end user's accounts this conversation still needs, each with the link
+     * that person signs in at.
+     *
+     * One for every connection to the end user's account (`endUser: true`)
+     * whose app the person this conversation is for has not connected yet.
+     * Empty when nothing is missing. They sign in ONCE: the account is remembered for
+     * them, so their next conversation does not ask again.
+     *
+     * ```ts
+     * const conversation = await agent.start({ endUserId: user.id });
+     * for (const { app, url } of await conversation.accountsNeeded()) {
+     *   showToUser(app, url);              // popup, redirect, email, your choice
+     * }
+     * ```
      *
-     * Send the person to the returned url; the conversation becomes ready when
-     * they finish. The connection gets its own row and cannot overwrite the
-     * agent's shared account, so two people connecting their own Gmail to two
-     * conversations of the same agent do not clobber each other (ADR 0017: that
-     * was a real bug, found and fixed in this flow).
+     * Ask again once they are back: an empty list means nothing is missing.
      *
-     * `agentId` is required alongside the conversation, so this reads the
-     * conversation first when it has not already.
+     * A conversation is never refused for a missing account. It starts, and
+     * the agent says what it could not reach; this is how your application
+     * finds out first.
      */
-    authorize(provider: string): Promise<{
-        url: string;
-        connectionId: string;
-    }>;
+    accountsNeeded(): Promise<AccountNeeded[]>;
     /**
-     * Wait until this conversation has everything it needs.
+     * Wait until this conversation has everything it needs: until `ready`.
      *
-     * The companion to `authorize()`. That call gives you a URL for your user to
-     * visit; this one tells you when they are done, so you do not have to invent
-     * a polling loop or work out which field to believe.
+     * So you do not have to invent a polling loop or work out which field to
+     * believe.
      *
      * ```ts
-     * const { url } = await conversation.authorize('gmail');
-     * showToUser(url);                  // popup, redirect, QR code, your choice
      * await conversation.waitUntilReady();
      * ```
      *

package/conversation.js

@@ -1,7 +1,8 @@
 // A conversation: one continuous exchange with an agent, with its own history
 // and its own filesystem. Two conversations share nothing.
-import { isBindings, providersOf, secretIdsOf, splitAttachments } from "./attach.js";
+import { isBindings, refuseConnections, secretIdsOf, secretsIn } from "./attach.js";
 import { AgentNavaError } from "./errors.js";
+import { turnRecoveryMessage } from "./http.js";
 import { makeTurn } from "./turn.js";
 /**
  * A conversation you can work with.
@@ -42,8 +43,8 @@ export class Conversation {
      *
      * EVERY CONVERSATION BELONGS TO EXACTLY ONE AGENT. That is the model, and it
      * is worth stating on the object because the SDK used to hold this value and
-     * never show it: `authorize()` read it internally and nothing else could,
-     * which made a conversation look parentless from outside.
+     * never show it: a method read it internally and nothing else could, which
+     * made a conversation look parentless from outside.
      *
      * Undefined on a conversation you addressed by id and have not read yet,
      * for the same reason `ready` is: the handle has made no request. Call
@@ -69,6 +70,12 @@ export class Conversation {
     get requires() {
         return this.snapshot?.requires ?? [];
     }
+    /** The number of the agent version it runs, from the last snapshot. Same
+     *  caveat as `ready`: a schedule naming this conversation moves it to the
+     *  latest version, and only `get()` sees that. */
+    get version() {
+        return this.snapshot?.version;
+    }
     async get() {
         const data = await this.#http.get(this.base);
         this.snapshot = data;
@@ -78,19 +85,27 @@ export class Conversation {
      * Ask, and get the reply.
      *
      * The message is sent HERE, not when you await or iterate the result, so
-     * calling this twice asks twice. Await it for the answer or iterate it for
+     * calling this twice with new keys asks twice. Await it for the answer or iterate it for
      * the events; doing both to the same turn throws rather than replaying.
      */
     ask(text, options = {}) {
+        // One key for this submission, retained in the transport request if a
+        // fetch implementation retries it. A caller may retain their own key for
+        // an explicit retry after losing the first response.
+        const idempotencyKey = options.idempotencyKey ?? newTurnKey();
+        if (!/^[A-Za-z0-9._:-]{1,128}$/.test(idempotencyKey)) {
+            throw new AgentNavaError({ message: 'idempotencyKey must contain 1–128 letters, digits, dots, underscores, colons or hyphens.', code: 'invalid_idempotency_key', status: 400 });
+        }
         const response = this.#http.send(`${this.base}/messages`, {
             method: 'POST',
+            idempotencyKey,
             body: {
                 content: text,
                 ...(options.attachments?.length && { attachments: options.attachments }),
             },
             ...(options.signal && { signal: options.signal }),
         });
-        return makeTurn(response);
+        return makeTurn(response, turnRecoveryMessage(`${this.base}/messages`, idempotencyKey));
     }
     async messages() {
         const res = await this.#http.get(`${this.base}/messages`);
@@ -100,8 +115,8 @@ export class Conversation {
     async end() {
         await this.#http.delete(this.base);
     }
-    /** Supply the credentials this conversation's agent declared at
-     *  'conversation' scope. Merges: sending one secret does not clear another.
+    /** Supply the secrets this conversation's agent declared at 'conversation'
+     *  scope. Merges: sending one secret does not clear another.
      *
      *  WRAPPED IN `sessionBindings`, and that envelope is load-bearing. This
      *  posted the object at the top level, while `addSessionBindings` reads
@@ -109,10 +124,9 @@ export class Conversation {
      *  is NOT an error there: a launch carrying no bindings is legitimate, so it
      *  normalises to `{}`.
      *
-     *  So this returned 200 and bound nothing. `conversation.attach()` sits on
-     *  top of it, which meant the documented way to grant an account to one
-     *  thread silently did nothing, and the failure appeared much later as an
-     *  agent that could not reach a mailbox somebody had plainly connected.
+     *  So this returned 200 and bound nothing, and the failure appeared much
+     *  later as an agent that could not use a credential somebody had plainly
+     *  supplied.
      *
      *  `agent.bind` had the same class of bug against its own route and its
      *  comment records it. This is the second one, found by reading both
@@ -125,66 +139,67 @@ export class Conversation {
         return data;
     }
     /**
-     * Give THIS conversation a credential, and nothing else.
+     * Give THIS conversation a secret, and nothing else.
      *
      * ```ts
-     * await conversation.attach(gmail);                       // one account
-     * await conversation.attach([gmail, calendar]);           // several
-     * await conversation.attach({ secrets: { KEY: value } }); // a secret VALUE
+     * await conversation.attach(key);                          // a stored Secret, by id
+     * await conversation.attach({ secrets: { KEY: value } });  // a secret VALUE
      * ```
      *
-     * ONE VERB. `bind` used to sit beside this doing the same job in a different
-     * shape, and is gone: two names for one idea is how a surface becomes hard
-     * to learn.
+     * The narrowest scope there is: it reaches this conversation only.
      *
-     * The narrowest scope there is. It cannot overwrite the agent's shared
-     * account or the person's own (ADR 0017).
+     * SECRETS ONLY, since 0.44. An account is never attached to a conversation
+     * any more: the agent's setup names whose account each connection uses, and
+     * for the end user's account the turn uses the account of the person this
+     * conversation is for. One handed in here is refused by name
+     * (`not_a_secret`) rather than dropped. `accountsNeeded()` says which of
+     * that person's accounts are still missing.
      *
      * PREFER `agent.start({ attach })` when you already know at launch. Between
      * a start and a later attach there is a window in which the conversation
-     * exists, can be asked something, and would answer without the account.
+     * exists, can be asked something, and would answer without the secret.
      */
     async attach(what) {
-        if (isBindings(what))
+        if (isBindings(what)) {
+            refuseConnections(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 }),
-        });
+        }
+        const secretIds = await secretIdsOf(secretsIn(what));
+        return this.#applyBindings({ ...(secretIds && { secretIds }) });
     }
     /**
-     * Attach a third-party account to THIS conversation, at `conversation` scope.
+     * The end user's accounts this conversation still needs, each with the link
+     * that person signs in at.
      *
-     * Send the person to the returned url; the conversation becomes ready when
-     * they finish. The connection gets its own row and cannot overwrite the
-     * agent's shared account, so two people connecting their own Gmail to two
-     * conversations of the same agent do not clobber each other (ADR 0017: that
-     * was a real bug, found and fixed in this flow).
+     * One for every connection to the end user's account (`endUser: true`)
+     * whose app the person this conversation is for has not connected yet.
+     * Empty when nothing is missing. They sign in ONCE: the account is remembered for
+     * them, so their next conversation does not ask again.
      *
-     * `agentId` is required alongside the conversation, so this reads the
-     * conversation first when it has not already.
+     * ```ts
+     * const conversation = await agent.start({ endUserId: user.id });
+     * for (const { app, url } of await conversation.accountsNeeded()) {
+     *   showToUser(app, url);              // popup, redirect, email, your choice
+     * }
+     * ```
+     *
+     * Ask again once they are back: an empty list means nothing is missing.
+     *
+     * A conversation is never refused for a missing account. It starts, and
+     * the agent says what it could not reach; this is how your application
+     * finds out first.
      */
-    async authorize(provider) {
-        // Free when this conversation came from `agent.start()`, one request when
-        // it was addressed by id. Every conversation HAS an agent; the handle
-        // just may not have read it yet.
-        const agentId = this.agentId ?? (await this.get()).agentId;
-        const res = await this.#http.post('/v1/connections/connect', { provider, agentId, conversationId: this.id });
-        return { url: res.authUrl, connectionId: res.connectionId };
+    async accountsNeeded() {
+        const res = await this.#http.get(`${this.base}/accounts-needed`);
+        return res.needed ?? [];
     }
     /**
-     * Wait until this conversation has everything it needs.
+     * Wait until this conversation has everything it needs: until `ready`.
      *
-     * The companion to `authorize()`. That call gives you a URL for your user to
-     * visit; this one tells you when they are done, so you do not have to invent
-     * a polling loop or work out which field to believe.
+     * So you do not have to invent a polling loop or work out which field to
+     * believe.
      *
      * ```ts
-     * const { url } = await conversation.authorize('gmail');
-     * showToUser(url);                  // popup, redirect, QR code, your choice
      * await conversation.waitUntilReady();
      * ```
      *
@@ -293,6 +308,11 @@ export class Conversation {
         return res.url;
     }
 }
+let fallbackTurnSequence = 0;
+function newTurnKey() {
+    return globalThis.crypto?.randomUUID?.() ??
+        `turn-${Date.now().toString(36)}-${++fallbackTurnSequence}-${Math.random().toString(36).slice(2)}`;
+}
 const CONTENT_TYPES = {
     txt: 'text/plain',
     md: 'text/markdown',

package/conversation.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"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","sourcesContent":["// A conversation: one continuous exchange with an agent, with its own history\n// and its own filesystem. Two conversations share nothing.\n\nimport { type Attachable, isBindings, providersOf, secretIdsOf, splitAttachments } from './attach.ts';\nimport type { Connection } from './connection.ts';\nimport { AgentNavaError } from './errors.ts';\nimport type { Http } from './http.ts';\nimport { makeTurn, type Turn } from './turn.ts';\nimport type {\n\tAgentConversationData,\n\tAttachment,\n\tBindings,\n\tFileEntry,\n\tMessage,\n\tRequirement,\n} from './types.ts';\n\nexport interface AskOptions {\n\tattachments?: Attachment[];\n\tsignal?: AbortSignal;\n}\n\nexport interface FileUrlOptions {\n\tdownload?: boolean;\n\t/** Seconds the link stays valid. */\n\tttl?: number;\n}\n\n/**\n * A conversation you can work with.\n *\n * EVERY CONVERSATION BELONGS TO EXACTLY ONE AGENT, reachable as `agentId` once\n * this handle has read anything. A conversation is an agent doing a piece of\n * work; there is no such thing as a conversation with nobody.\n *\n * ADDRESSED FROM ITS PARENT: `agent.conversation(id)`, or\n * `project.conversation(id)` for one a project owns. It used to be\n * `ws.conversation(id)`, which made the parent look optional and is how this\n * SDK came to describe conversations as parentless in its own reference. The\n * objection to moving it was that a caller would then store two ids; in\n * practice the agent id is a constant in their own code, not a per-row value.\n *\n * Holding one makes NO request. The first call on it is the first round trip,\n * because fetching a conversation just to send it a message would be a round\n * trip for nothing.\n */\nexport class Conversation {\n\treadonly id: string;\n\treadonly #http: Http;\n\t/** Whatever the call that produced this object already knew. Present when it\n\t *  came from `agent.start()`, absent when it came from `agent.conversation(id)`,\n\t *  which is exactly the difference between having made a request and not. */\n\tprivate snapshot?: AgentConversationData;\n\n\tconstructor(http: Http, id: string, snapshot?: AgentConversationData) {\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/conversations/${encodeURIComponent(this.id)}`;\n\t}\n\n\t/**\n\t * The agent whose conversation this is.\n\t *\n\t * EVERY CONVERSATION BELONGS TO EXACTLY ONE AGENT. That is the model, and it\n\t * is worth stating on the object because the SDK used to hold this value and\n\t * never show it: `authorize()` read it internally and nothing else could,\n\t * which made a conversation look parentless from outside.\n\t *\n\t * Undefined on a conversation you addressed by id and have not read yet,\n\t * for the same reason `ready` is: the handle has made no request. Call\n\t * `get()` to fill it in.\n\t *\n\t * ```ts\n\t * const conversation = await agent.start({ endUserId: row.userId });\n\t * conversation.agentId === agent.id;      // already known, no round trip\n\t * ```\n\t */\n\tget agentId(): string | undefined {\n\t\treturn this.snapshot?.agentId;\n\t}\n\n\t/** True when nothing REQUIRED is outstanding.\n\t *\n\t *  Reads from the last snapshot rather than the network, so it is a property\n\t *  and not a call. It is only meaningful on a conversation you just started\n\t *  or just refreshed; call `get()` to bring it up to date. */\n\tget ready(): boolean | undefined {\n\t\treturn this.snapshot?.ready;\n\t}\n\n\t/** What the conversation is still missing. Same caveat as `ready`. */\n\tget requires(): Requirement[] {\n\t\treturn this.snapshot?.requires ?? [];\n\t}\n\n\tasync get(): Promise<AgentConversationData> {\n\t\tconst data = await this.#http.get<AgentConversationData>(this.base);\n\t\tthis.snapshot = data;\n\t\treturn data;\n\t}\n\n\t/**\n\t * Ask, and get the reply.\n\t *\n\t * The message is sent HERE, not when you await or iterate the result, so\n\t * calling this twice asks twice. Await it for the answer or iterate it for\n\t * the events; doing both to the same turn throws rather than replaying.\n\t */\n\task(text: string, options: AskOptions = {}): Turn {\n\t\tconst response = this.#http.send(`${this.base}/messages`, {\n\t\t\tmethod: 'POST',\n\t\t\tbody: {\n\t\t\t\tcontent: text,\n\t\t\t\t...(options.attachments?.length && { attachments: options.attachments }),\n\t\t\t},\n\t\t\t...(options.signal && { signal: options.signal }),\n\t\t});\n\t\treturn makeTurn(response);\n\t}\n\n\tasync messages(): Promise<Message[]> {\n\t\tconst res = await this.#http.get<{ messages: Message[] }>(`${this.base}/messages`);\n\t\treturn res.messages ?? [];\n\t}\n\n\t/** End it, and its drive with it. */\n\tasync end(): Promise<void> {\n\t\tawait this.#http.delete(this.base);\n\t}\n\n\t/** Supply the credentials this conversation's agent declared at\n\t *  'conversation' scope. Merges: sending one secret does not clear another.\n\t *\n\t *  WRAPPED IN `sessionBindings`, and that envelope is load-bearing. This\n\t *  posted the object at the top level, while `addSessionBindings` reads\n\t *  `body.sessionBindings`. The handler therefore saw undefined, and undefined\n\t *  is NOT an error there: a launch carrying no bindings is legitimate, so it\n\t *  normalises to `{}`.\n\t *\n\t *  So this returned 200 and bound nothing. `conversation.attach()` sits on\n\t *  top of it, which meant the documented way to grant an account to one\n\t *  thread silently did nothing, and the failure appeared much later as an\n\t *  agent that could not reach a mailbox somebody had plainly connected.\n\t *\n\t *  `agent.bind` had the same class of bug against its own route and its\n\t *  comment records it. This is the second one, found by reading both\n\t *  together. */\n\tasync #applyBindings(bindings: Bindings): Promise<AgentConversationData> {\n\t\tconst data = await this.#http.post<AgentConversationData>(`${this.base}/bindings`, {\n\t\t\tsessionBindings: bindings,\n\t\t});\n\t\tthis.snapshot = data;\n\t\treturn data;\n\t}\n\n\t/**\n\t * Give THIS conversation a credential, and nothing else.\n\t *\n\t * ```ts\n\t * await conversation.attach(gmail);                       // one account\n\t * await conversation.attach([gmail, calendar]);           // several\n\t * await conversation.attach({ secrets: { KEY: value } }); // a secret VALUE\n\t * ```\n\t *\n\t * ONE VERB. `bind` used to sit beside this doing the same job in a different\n\t * shape, and is gone: two names for one idea is how a surface becomes hard\n\t * to learn.\n\t *\n\t * The narrowest scope there is. It cannot overwrite the agent's shared\n\t * account or the person's own (ADR 0017).\n\t *\n\t * PREFER `agent.start({ attach })` when you already know at launch. Between\n\t * a start and a later attach there is a window in which the conversation\n\t * exists, can be asked something, and would answer without the account.\n\t */\n\tasync attach(what: Attachable | Attachable[] | Bindings): Promise<AgentConversationData> {\n\t\tif (isBindings(what)) return this.#applyBindings(what as Bindings);\n\t\tconst split = splitAttachments(what as Attachable | Attachable[]);\n\t\tconst connections = await providersOf(split.connections);\n\t\tconst secretIds = await secretIdsOf(split.secrets);\n\t\treturn this.#applyBindings({\n\t\t\t...(connections && { connections }),\n\t\t\t...(secretIds && { secretIds }),\n\t\t});\n\t}\n\n\t/**\n\t * Attach a third-party account to THIS conversation, at `conversation` scope.\n\t *\n\t * Send the person to the returned url; the conversation becomes ready when\n\t * they finish. The connection gets its own row and cannot overwrite the\n\t * agent's shared account, so two people connecting their own Gmail to two\n\t * conversations of the same agent do not clobber each other (ADR 0017: that\n\t * was a real bug, found and fixed in this flow).\n\t *\n\t * `agentId` is required alongside the conversation, so this reads the\n\t * conversation first when it has not already.\n\t */\n\tasync authorize(provider: string): Promise<{ url: string; connectionId: string }> {\n\t\t// Free when this conversation came from `agent.start()`, one request when\n\t\t// it was addressed by id. Every conversation HAS an agent; the handle\n\t\t// just may not have read it yet.\n\t\tconst agentId = this.agentId ?? (await this.get()).agentId;\n\t\tconst res = await this.#http.post<{ authUrl: string; connectionId: string }>(\n\t\t\t'/v1/connections/connect',\n\t\t\t{ provider, agentId, conversationId: this.id },\n\t\t);\n\t\treturn { url: res.authUrl, connectionId: res.connectionId };\n\t}\n\n\t/**\n\t * Wait until this conversation has everything it needs.\n\t *\n\t * The companion to `authorize()`. That call gives you a URL for your user to\n\t * visit; this one tells you when they are done, so you do not have to invent\n\t * a polling loop or work out which field to believe.\n\t *\n\t * ```ts\n\t * const { url } = await conversation.authorize('gmail');\n\t * showToUser(url);                  // popup, redirect, QR code, your choice\n\t * await conversation.waitUntilReady();\n\t * ```\n\t *\n\t * Returns as soon as nothing REQUIRED is outstanding, and returns the\n\t * conversation so you do not need a second call. An optional requirement\n\t * left unmet does not hold this up, for the same reason it does not make\n\t * `ready` false: the conversation genuinely works without it.\n\t *\n\t * ON TIMEOUT it throws naming what is still missing, because \"timed out\" on\n\t * its own sends you looking in the wrong place. The code is\n\t * `conversation_not_ready` and it is safe to call again: a person who has\n\t * not finished signing in yet may simply need longer.\n\t *\n\t * This polls rather than subscribing. For a step with a human in the middle,\n\t * a few seconds of latency costs nothing, and it keeps the method usable\n\t * from any runtime without a socket.\n\t */\n\tasync waitUntilReady(options: {\n\t\t/** Give up after this long. Default 2 minutes, which is generous for a\n\t\t *  sign-in and short enough that a stuck flow does not hang a request. */\n\t\ttimeoutMs?: number;\n\t\t/** Gap between checks. Default 2 seconds. */\n\t\tintervalMs?: number;\n\t\t/** Cancel the wait, e.g. when the caller's own request is abandoned. */\n\t\tsignal?: AbortSignal;\n\t} = {}): Promise<AgentConversationData> {\n\t\tconst timeoutMs = options.timeoutMs ?? 120_000;\n\t\tconst intervalMs = options.intervalMs ?? 2_000;\n\t\tconst deadline = Date.now() + timeoutMs;\n\n\t\t// Checked BEFORE the first sleep. A conversation that is already ready\n\t\t// should cost one request, not one request plus an interval.\n\t\tlet data = await this.get();\n\t\twhile (!data.ready) {\n\t\t\tif (options.signal?.aborted) {\n\t\t\t\tthrow new AgentNavaError({\n\t\t\t\t\tmessage: 'waitUntilReady was cancelled',\n\t\t\t\t\tcode: 'aborted',\n\t\t\t\t\tstatus: 0,\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (Date.now() >= deadline) {\n\t\t\t\t// Name the outstanding REQUIRED items. The optional ones are not why\n\t\t\t\t// this failed and listing them would send someone after the wrong\n\t\t\t\t// thing.\n\t\t\t\tconst outstanding = data.requires\n\t\t\t\t\t.filter((r) => r.required)\n\t\t\t\t\t.map((r) => `${r.kind} ${r.name}`);\n\t\t\t\tthrow new AgentNavaError({\n\t\t\t\t\tmessage: outstanding.length\n\t\t\t\t\t\t? `Conversation ${this.id} is still waiting on: ${outstanding.join(', ')}`\n\t\t\t\t\t\t: `Conversation ${this.id} did not become ready within ${timeoutMs}ms`,\n\t\t\t\t\tcode: 'conversation_not_ready',\n\t\t\t\t\tstatus: 0,\n\t\t\t\t});\n\t\t\t}\n\t\t\t// Never sleep past the deadline, so the timeout means what it says.\n\t\t\tawait sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())), options.signal);\n\t\t\tdata = await this.get();\n\t\t}\n\t\treturn data;\n\t}\n\n\t// ---------------------------------------------------------------- the drive\n\n\t/** List one directory. `path`, not `dir`: it is the same parameter every other\n\t *  file route on this API takes, and one name for one idea beats a prettier\n\t *  name used in one place. */\n\tasync files(path = '/'): Promise<FileEntry[]> {\n\t\tconst res = await this.#http.get<{ files: DriveEntry[] }>(`${this.base}/files`, { path });\n\t\treturn (res.files ?? []).map(toFileEntry);\n\t}\n\n\t/** Read a text file. */\n\tasync readFile(path: string): Promise<string> {\n\t\t// The route answers JSON `{path, content}`, not bare text. The envelope is\n\t\t// worth keeping on the wire (the canonical path comes back with it), so the\n\t\t// unwrapping happens here: a caller asked for the file, not for a wrapper.\n\t\tconst res = await this.#http.get<{ path: string; content: string }>(\n\t\t\t`${this.base}/files/content`,\n\t\t\t{ path },\n\t\t);\n\t\treturn res.content ?? '';\n\t}\n\n\tasync readFileBytes(path: string): Promise<Uint8Array> {\n\t\tconst res = await this.#http.send(`${this.base}/files/raw`, { query: { path } });\n\t\treturn new Uint8Array(await res.arrayBuffer());\n\t}\n\n\t/**\n\t * Put a file into the conversation's drive.\n\t *\n\t * This is how an application STAGES material: write the contract in, then ask\n\t * the question about it. Anywhere under the root is fine; `input/` is a\n\t * convention in the docs and nothing enforces it, because the agent and your\n\t * application share one namespace.\n\t */\n\tasync writeFile(\n\t\tpath: string,\n\t\tbytes: Uint8Array | ArrayBuffer,\n\t\tcontentType?: string,\n\t): Promise<FileEntry> {\n\t\treturn this.#http.request<FileEntry>(`${this.base}/files`, {\n\t\t\tmethod: 'PUT',\n\t\t\tbytes,\n\t\t\tquery: { path },\n\t\t\t...(contentType && { contentType }),\n\t\t});\n\t}\n\n\tasync removeFile(path: string): Promise<void> {\n\t\tawait this.#http.delete(`${this.base}/files`, { path });\n\t}\n\n\t/**\n\t * A link to one file that carries its own authorisation.\n\t *\n\t * A browser cannot hold an API key, so a Download button has no way to prove\n\t * it is allowed. This grants that one file for `ttl` seconds and nothing\n\t * else.\n\t */\n\tasync fileUrl(path: string, options: FileUrlOptions = {}): Promise<string> {\n\t\tconst res = await this.#http.post<{ url: string }>(`${this.base}/files/url`, {\n\t\t\tpath,\n\t\t\t...(options.download !== undefined && { download: options.download }),\n\t\t\t...(options.ttl !== undefined && { ttl: options.ttl }),\n\t\t});\n\t\treturn res.url;\n\t}\n}\n\n/** One entry as the Drive returns it. */\ninterface DriveEntry {\n\tname: string;\n\tpath: string;\n\tisDir: boolean;\n\tsize: number;\n\t/** Epoch milliseconds. */\n\tmtime: number;\n}\n\nconst CONTENT_TYPES: Record<string, string> = {\n\ttxt: 'text/plain',\n\tmd: 'text/markdown',\n\tjson: 'application/json',\n\tcsv: 'text/csv',\n\thtml: 'text/html',\n\tjs: 'text/javascript',\n\tts: 'text/typescript',\n\tpng: 'image/png',\n\tjpg: 'image/jpeg',\n\tjpeg: 'image/jpeg',\n\tgif: 'image/gif',\n\twebp: 'image/webp',\n\tsvg: 'image/svg+xml',\n\tpdf: 'application/pdf',\n};\n\n/**\n * A Drive entry as the SDK's FileEntry.\n *\n * The Drive speaks `isDir` and `mtime`; the SDK speaks `kind` and an ISO\n * `modifiedAt`. Translating at the edge is the SDK's job: the Drive's shape is\n * what apps/web's DrivePane reads, and changing it to suit this would break a\n * working screen to save a mapping function.\n *\n * `mimeType` is inferred from the extension, because the Drive does not store\n * one (see apps/backend-workers/src/sandbox/drive-reader.ts, which infers it the\n * same way on read).\n */\nfunction toFileEntry(entry: DriveEntry): FileEntry {\n\tconst ext = entry.path.slice(entry.path.lastIndexOf('.') + 1).toLowerCase();\n\treturn {\n\t\tpath: entry.path,\n\t\tkind: entry.isDir ? 'directory' : 'file',\n\t\tmimeType: entry.isDir ? 'inode/directory' : (CONTENT_TYPES[ext] ?? 'application/octet-stream'),\n\t\tsize: entry.size,\n\t\tmodifiedAt: new Date(entry.mtime).toISOString(),\n\t};\n}\n\n/** Wait, and stop waiting early if the caller aborts. */\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\tif (ms <= 0) return Promise.resolve();\n\treturn new Promise((resolve) => {\n\t\tconst timer = setTimeout(done, ms);\n\t\tfunction done() {\n\t\t\tclearTimeout(timer);\n\t\t\tsignal?.removeEventListener('abort', done);\n\t\t\tresolve();\n\t\t}\n\t\tsignal?.addEventListener('abort', done, { once: true });\n\t});\n}\n"]}
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"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","sourcesContent":["// A conversation: one continuous exchange with an agent, with its own history\n// and its own filesystem. Two conversations share nothing.\n\nimport { isBindings, refuseConnections, type SessionBindings, secretIdsOf, secretsIn } from './attach.ts';\nimport { AgentNavaError } from './errors.ts';\nimport { type Http, turnRecoveryMessage } from './http.ts';\nimport type { Secret } from './secret.ts';\nimport { makeTurn, type Turn } from './turn.ts';\nimport type {\n\tAccountNeeded,\n\tAgentConversationData,\n\tAttachment,\n\tBindings,\n\tFileEntry,\n\tMessage,\n\tRequirement,\n} from './types.ts';\n\nexport interface AskOptions {\n\tattachments?: Attachment[];\n\t/**\n\t * Stop receiving this turn's response. An already-aborted signal prevents\n\t * submission, so no turn is accepted or charged for this call. After the\n\t * server accepts a turn, aborting stops observation: accepted work can\n\t * continue and normal billing applies, with no automatic refund or server\n\t * cancellation. Read conversation.messages() before asking again.\n\t */\n\tsignal?: AbortSignal;\n\t/** Stable identity for one submission. Reuse it only for the same content\n\t * after a lost response; a new intentional turn needs a new key. Defaults to\n\t * a generated key. Use 1–128 letters, digits, dots, underscores, colons or hyphens. */\n\tidempotencyKey?: string;\n}\n\nexport interface FileUrlOptions {\n\tdownload?: boolean;\n\t/** Seconds the link stays valid. */\n\tttl?: number;\n}\n\n/**\n * A conversation you can work with.\n *\n * EVERY CONVERSATION BELONGS TO EXACTLY ONE AGENT, reachable as `agentId` once\n * this handle has read anything. A conversation is an agent doing a piece of\n * work; there is no such thing as a conversation with nobody.\n *\n * ADDRESSED FROM ITS PARENT: `agent.conversation(id)`, or\n * `project.conversation(id)` for one a project owns. It used to be\n * `ws.conversation(id)`, which made the parent look optional and is how this\n * SDK came to describe conversations as parentless in its own reference. The\n * objection to moving it was that a caller would then store two ids; in\n * practice the agent id is a constant in their own code, not a per-row value.\n *\n * Holding one makes NO request. The first call on it is the first round trip,\n * because fetching a conversation just to send it a message would be a round\n * trip for nothing.\n */\nexport class Conversation {\n\treadonly id: string;\n\treadonly #http: Http;\n\t/** Whatever the call that produced this object already knew. Present when it\n\t *  came from `agent.start()`, absent when it came from `agent.conversation(id)`,\n\t *  which is exactly the difference between having made a request and not. */\n\tprivate snapshot?: AgentConversationData;\n\n\tconstructor(http: Http, id: string, snapshot?: AgentConversationData) {\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/conversations/${encodeURIComponent(this.id)}`;\n\t}\n\n\t/**\n\t * The agent whose conversation this is.\n\t *\n\t * EVERY CONVERSATION BELONGS TO EXACTLY ONE AGENT. That is the model, and it\n\t * is worth stating on the object because the SDK used to hold this value and\n\t * never show it: a method read it internally and nothing else could, which\n\t * made a conversation look parentless from outside.\n\t *\n\t * Undefined on a conversation you addressed by id and have not read yet,\n\t * for the same reason `ready` is: the handle has made no request. Call\n\t * `get()` to fill it in.\n\t *\n\t * ```ts\n\t * const conversation = await agent.start({ endUserId: row.userId });\n\t * conversation.agentId === agent.id;      // already known, no round trip\n\t * ```\n\t */\n\tget agentId(): string | undefined {\n\t\treturn this.snapshot?.agentId;\n\t}\n\n\t/** True when nothing REQUIRED is outstanding.\n\t *\n\t *  Reads from the last snapshot rather than the network, so it is a property\n\t *  and not a call. It is only meaningful on a conversation you just started\n\t *  or just refreshed; call `get()` to bring it up to date. */\n\tget ready(): boolean | undefined {\n\t\treturn this.snapshot?.ready;\n\t}\n\n\t/** What the conversation is still missing. Same caveat as `ready`. */\n\tget requires(): Requirement[] {\n\t\treturn this.snapshot?.requires ?? [];\n\t}\n\n\t/** The number of the agent version it runs, from the last snapshot. Same\n\t *  caveat as `ready`: a schedule naming this conversation moves it to the\n\t *  latest version, and only `get()` sees that. */\n\tget version(): number | undefined {\n\t\treturn this.snapshot?.version;\n\t}\n\n\tasync get(): Promise<AgentConversationData> {\n\t\tconst data = await this.#http.get<AgentConversationData>(this.base);\n\t\tthis.snapshot = data;\n\t\treturn data;\n\t}\n\n\t/**\n\t * Ask, and get the reply.\n\t *\n\t * The message is sent HERE, not when you await or iterate the result, so\n\t * calling this twice with new keys asks twice. Await it for the answer or iterate it for\n\t * the events; doing both to the same turn throws rather than replaying.\n\t */\n\task(text: string, options: AskOptions = {}): Turn {\n\t\t// One key for this submission, retained in the transport request if a\n\t\t// fetch implementation retries it. A caller may retain their own key for\n\t\t// an explicit retry after losing the first response.\n\t\tconst idempotencyKey = options.idempotencyKey ?? newTurnKey();\n\t\tif (!/^[A-Za-z0-9._:-]{1,128}$/.test(idempotencyKey)) {\n\t\t\tthrow new AgentNavaError({ message: 'idempotencyKey must contain 1–128 letters, digits, dots, underscores, colons or hyphens.', code: 'invalid_idempotency_key', status: 400 });\n\t\t}\n\t\tconst response = this.#http.send(`${this.base}/messages`, {\n\t\t\tmethod: 'POST',\n\t\t\tidempotencyKey,\n\t\t\tbody: {\n\t\t\t\tcontent: text,\n\t\t\t\t...(options.attachments?.length && { attachments: options.attachments }),\n\t\t\t},\n\t\t\t...(options.signal && { signal: options.signal }),\n\t\t});\n\t\treturn makeTurn(response, turnRecoveryMessage(`${this.base}/messages`, idempotencyKey));\n\t}\n\n\tasync messages(): Promise<Message[]> {\n\t\tconst res = await this.#http.get<{ messages: Message[] }>(`${this.base}/messages`);\n\t\treturn res.messages ?? [];\n\t}\n\n\t/** End it, and its drive with it. */\n\tasync end(): Promise<void> {\n\t\tawait this.#http.delete(this.base);\n\t}\n\n\t/** Supply the secrets this conversation's agent declared at 'conversation'\n\t *  scope. Merges: sending one secret does not clear another.\n\t *\n\t *  WRAPPED IN `sessionBindings`, and that envelope is load-bearing. This\n\t *  posted the object at the top level, while `addSessionBindings` reads\n\t *  `body.sessionBindings`. The handler therefore saw undefined, and undefined\n\t *  is NOT an error there: a launch carrying no bindings is legitimate, so it\n\t *  normalises to `{}`.\n\t *\n\t *  So this returned 200 and bound nothing, and the failure appeared much\n\t *  later as an agent that could not use a credential somebody had plainly\n\t *  supplied.\n\t *\n\t *  `agent.bind` had the same class of bug against its own route and its\n\t *  comment records it. This is the second one, found by reading both\n\t *  together. */\n\tasync #applyBindings(bindings: SessionBindings): Promise<AgentConversationData> {\n\t\tconst data = await this.#http.post<AgentConversationData>(`${this.base}/bindings`, {\n\t\t\tsessionBindings: bindings,\n\t\t});\n\t\tthis.snapshot = data;\n\t\treturn data;\n\t}\n\n\t/**\n\t * Give THIS conversation a secret, and nothing else.\n\t *\n\t * ```ts\n\t * await conversation.attach(key);                          // a stored Secret, by id\n\t * await conversation.attach({ secrets: { KEY: value } });  // a secret VALUE\n\t * ```\n\t *\n\t * The narrowest scope there is: it reaches this conversation only.\n\t *\n\t * SECRETS ONLY, since 0.44. An account is never attached to a conversation\n\t * any more: the agent's setup names whose account each connection uses, and\n\t * for the end user's account the turn uses the account of the person this\n\t * conversation is for. One handed in here is refused by name\n\t * (`not_a_secret`) rather than dropped. `accountsNeeded()` says which of\n\t * that person's accounts are still missing.\n\t *\n\t * PREFER `agent.start({ attach })` when you already know at launch. Between\n\t * a start and a later attach there is a window in which the conversation\n\t * exists, can be asked something, and would answer without the secret.\n\t */\n\tasync attach(what: Secret | Secret[] | Bindings): Promise<AgentConversationData> {\n\t\tif (isBindings(what)) {\n\t\t\trefuseConnections(what);\n\t\t\treturn this.#applyBindings(what);\n\t\t}\n\t\tconst secretIds = await secretIdsOf(secretsIn(what));\n\t\treturn this.#applyBindings({ ...(secretIds && { secretIds }) });\n\t}\n\n\t/**\n\t * The end user's accounts this conversation still needs, each with the link\n\t * that person signs in at.\n\t *\n\t * One for every connection to the end user's account (`endUser: true`)\n\t * whose app the person this conversation is for has not connected yet.\n\t * Empty when nothing is missing. They sign in ONCE: the account is remembered for\n\t * them, so their next conversation does not ask again.\n\t *\n\t * ```ts\n\t * const conversation = await agent.start({ endUserId: user.id });\n\t * for (const { app, url } of await conversation.accountsNeeded()) {\n\t *   showToUser(app, url);              // popup, redirect, email, your choice\n\t * }\n\t * ```\n\t *\n\t * Ask again once they are back: an empty list means nothing is missing.\n\t *\n\t * A conversation is never refused for a missing account. It starts, and\n\t * the agent says what it could not reach; this is how your application\n\t * finds out first.\n\t */\n\tasync accountsNeeded(): Promise<AccountNeeded[]> {\n\t\tconst res = await this.#http.get<{ needed: AccountNeeded[] }>(`${this.base}/accounts-needed`);\n\t\treturn res.needed ?? [];\n\t}\n\n\t/**\n\t * Wait until this conversation has everything it needs: until `ready`.\n\t *\n\t * So you do not have to invent a polling loop or work out which field to\n\t * believe.\n\t *\n\t * ```ts\n\t * await conversation.waitUntilReady();\n\t * ```\n\t *\n\t * Returns as soon as nothing REQUIRED is outstanding, and returns the\n\t * conversation so you do not need a second call. An optional requirement\n\t * left unmet does not hold this up, for the same reason it does not make\n\t * `ready` false: the conversation genuinely works without it.\n\t *\n\t * ON TIMEOUT it throws naming what is still missing, because \"timed out\" on\n\t * its own sends you looking in the wrong place. The code is\n\t * `conversation_not_ready` and it is safe to call again: a person who has\n\t * not finished signing in yet may simply need longer.\n\t *\n\t * This polls rather than subscribing. For a step with a human in the middle,\n\t * a few seconds of latency costs nothing, and it keeps the method usable\n\t * from any runtime without a socket.\n\t */\n\tasync waitUntilReady(options: {\n\t\t/** Give up after this long. Default 2 minutes, which is generous for a\n\t\t *  sign-in and short enough that a stuck flow does not hang a request. */\n\t\ttimeoutMs?: number;\n\t\t/** Gap between checks. Default 2 seconds. */\n\t\tintervalMs?: number;\n\t\t/** Cancel the wait, e.g. when the caller's own request is abandoned. */\n\t\tsignal?: AbortSignal;\n\t} = {}): Promise<AgentConversationData> {\n\t\tconst timeoutMs = options.timeoutMs ?? 120_000;\n\t\tconst intervalMs = options.intervalMs ?? 2_000;\n\t\tconst deadline = Date.now() + timeoutMs;\n\n\t\t// Checked BEFORE the first sleep. A conversation that is already ready\n\t\t// should cost one request, not one request plus an interval.\n\t\tlet data = await this.get();\n\t\twhile (!data.ready) {\n\t\t\tif (options.signal?.aborted) {\n\t\t\t\tthrow new AgentNavaError({\n\t\t\t\t\tmessage: 'waitUntilReady was cancelled',\n\t\t\t\t\tcode: 'aborted',\n\t\t\t\t\tstatus: 0,\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (Date.now() >= deadline) {\n\t\t\t\t// Name the outstanding REQUIRED items. The optional ones are not why\n\t\t\t\t// this failed and listing them would send someone after the wrong\n\t\t\t\t// thing.\n\t\t\t\tconst outstanding = data.requires\n\t\t\t\t\t.filter((r) => r.required)\n\t\t\t\t\t.map((r) => `${r.kind} ${r.name}`);\n\t\t\t\tthrow new AgentNavaError({\n\t\t\t\t\tmessage: outstanding.length\n\t\t\t\t\t\t? `Conversation ${this.id} is still waiting on: ${outstanding.join(', ')}`\n\t\t\t\t\t\t: `Conversation ${this.id} did not become ready within ${timeoutMs}ms`,\n\t\t\t\t\tcode: 'conversation_not_ready',\n\t\t\t\t\tstatus: 0,\n\t\t\t\t});\n\t\t\t}\n\t\t\t// Never sleep past the deadline, so the timeout means what it says.\n\t\t\tawait sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())), options.signal);\n\t\t\tdata = await this.get();\n\t\t}\n\t\treturn data;\n\t}\n\n\t// ---------------------------------------------------------------- the drive\n\n\t/** List one directory. `path`, not `dir`: it is the same parameter every other\n\t *  file route on this API takes, and one name for one idea beats a prettier\n\t *  name used in one place. */\n\tasync files(path = '/'): Promise<FileEntry[]> {\n\t\tconst res = await this.#http.get<{ files: DriveEntry[] }>(`${this.base}/files`, { path });\n\t\treturn (res.files ?? []).map(toFileEntry);\n\t}\n\n\t/** Read a text file. */\n\tasync readFile(path: string): Promise<string> {\n\t\t// The route answers JSON `{path, content}`, not bare text. The envelope is\n\t\t// worth keeping on the wire (the canonical path comes back with it), so the\n\t\t// unwrapping happens here: a caller asked for the file, not for a wrapper.\n\t\tconst res = await this.#http.get<{ path: string; content: string }>(\n\t\t\t`${this.base}/files/content`,\n\t\t\t{ path },\n\t\t);\n\t\treturn res.content ?? '';\n\t}\n\n\tasync readFileBytes(path: string): Promise<Uint8Array> {\n\t\tconst res = await this.#http.send(`${this.base}/files/raw`, { query: { path } });\n\t\treturn new Uint8Array(await res.arrayBuffer());\n\t}\n\n\t/**\n\t * Put a file into the conversation's drive.\n\t *\n\t * This is how an application STAGES material: write the contract in, then ask\n\t * the question about it. Anywhere under the root is fine; `input/` is a\n\t * convention in the docs and nothing enforces it, because the agent and your\n\t * application share one namespace.\n\t */\n\tasync writeFile(\n\t\tpath: string,\n\t\tbytes: Uint8Array | ArrayBuffer,\n\t\tcontentType?: string,\n\t): Promise<FileEntry> {\n\t\treturn this.#http.request<FileEntry>(`${this.base}/files`, {\n\t\t\tmethod: 'PUT',\n\t\t\tbytes,\n\t\t\tquery: { path },\n\t\t\t...(contentType && { contentType }),\n\t\t});\n\t}\n\n\tasync removeFile(path: string): Promise<void> {\n\t\tawait this.#http.delete(`${this.base}/files`, { path });\n\t}\n\n\t/**\n\t * A link to one file that carries its own authorisation.\n\t *\n\t * A browser cannot hold an API key, so a Download button has no way to prove\n\t * it is allowed. This grants that one file for `ttl` seconds and nothing\n\t * else.\n\t */\n\tasync fileUrl(path: string, options: FileUrlOptions = {}): Promise<string> {\n\t\tconst res = await this.#http.post<{ url: string }>(`${this.base}/files/url`, {\n\t\t\tpath,\n\t\t\t...(options.download !== undefined && { download: options.download }),\n\t\t\t...(options.ttl !== undefined && { ttl: options.ttl }),\n\t\t});\n\t\treturn res.url;\n\t}\n}\n\nlet fallbackTurnSequence = 0;\nfunction newTurnKey(): string {\n\treturn globalThis.crypto?.randomUUID?.() ??\n\t\t`turn-${Date.now().toString(36)}-${++fallbackTurnSequence}-${Math.random().toString(36).slice(2)}`;\n}\n\n/** One entry as the Drive returns it. */\ninterface DriveEntry {\n\tname: string;\n\tpath: string;\n\tisDir: boolean;\n\tsize: number;\n\t/** Epoch milliseconds. */\n\tmtime: number;\n}\n\nconst CONTENT_TYPES: Record<string, string> = {\n\ttxt: 'text/plain',\n\tmd: 'text/markdown',\n\tjson: 'application/json',\n\tcsv: 'text/csv',\n\thtml: 'text/html',\n\tjs: 'text/javascript',\n\tts: 'text/typescript',\n\tpng: 'image/png',\n\tjpg: 'image/jpeg',\n\tjpeg: 'image/jpeg',\n\tgif: 'image/gif',\n\twebp: 'image/webp',\n\tsvg: 'image/svg+xml',\n\tpdf: 'application/pdf',\n};\n\n/**\n * A Drive entry as the SDK's FileEntry.\n *\n * The Drive speaks `isDir` and `mtime`; the SDK speaks `kind` and an ISO\n * `modifiedAt`. Translating at the edge is the SDK's job: the Drive's shape is\n * what apps/web's DrivePane reads, and changing it to suit this would break a\n * working screen to save a mapping function.\n *\n * `mimeType` is inferred from the extension, because the Drive does not store\n * one (see apps/backend-workers/src/sandbox/drive-reader.ts, which infers it the\n * same way on read).\n */\nfunction toFileEntry(entry: DriveEntry): FileEntry {\n\tconst ext = entry.path.slice(entry.path.lastIndexOf('.') + 1).toLowerCase();\n\treturn {\n\t\tpath: entry.path,\n\t\tkind: entry.isDir ? 'directory' : 'file',\n\t\tmimeType: entry.isDir ? 'inode/directory' : (CONTENT_TYPES[ext] ?? 'application/octet-stream'),\n\t\tsize: entry.size,\n\t\tmodifiedAt: new Date(entry.mtime).toISOString(),\n\t};\n}\n\n/** Wait, and stop waiting early if the caller aborts. */\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\tif (ms <= 0) return Promise.resolve();\n\treturn new Promise((resolve) => {\n\t\tconst timer = setTimeout(done, ms);\n\t\tfunction done() {\n\t\t\tclearTimeout(timer);\n\t\t\tsignal?.removeEventListener('abort', done);\n\t\t\tresolve();\n\t\t}\n\t\tsignal?.addEventListener('abort', done, { once: true });\n\t});\n}\n"]}

package/database.d.ts

@@ -0,0 +1,53 @@
+import type { Http } from './http.ts';
+import type { DatabaseColumn, DatabaseData, DatabaseTable } from './types.ts';
+/**
+ * A database your agents can query: registered once in the workspace, under a
+ * key, then named in each agent configuration that should reach it.
+ *
+ * The order matters and is the whole design. `ws.databases.create()` logs in
+ * before it saves anything, so a wrong password fails there and not in the
+ * middle of a conversation; an agent then names the key in its `databases`, and
+ * only an agent that names it can query it. The agent's prompt lists its
+ * databases by key, and its `sql_*` tools take that key.
+ *
+ * ```ts
+ * const shop = await ws.databases.create({ key: 'shop', name: 'Shop DB', url: process.env.SHOP_DB_URL! });
+ * await shop.tables();                                   // [{ schema: 'public', name: 'orders', kind: 'table' }]
+ * await ws.agents.create({ name: 'Ops', instructions, databases: ['shop'] });
+ * ```
+ *
+ * The login is stored encrypted and never read back: this handle reports where
+ * the database is, never how to log in to it.
+ */
+export declare class Database {
+    #private;
+    /** Workspace-unique, and what an agent configuration stores. Not editable:
+     *  renaming it would silently cut off every agent that names it. */
+    readonly key: string;
+    private snapshot?;
+    constructor(http: Http, key: string, snapshot?: DatabaseData);
+    private get base();
+    /** The database's current record: label, engine, host, port, name. */
+    get(): Promise<DatabaseData>;
+    /** What was known when this handle was made, without a round trip.
+     *  Undefined on a handle built from a bare key. */
+    get data(): DatabaseData | undefined;
+    /** The tables and views it holds, optionally within one schema. Logs in to
+     *  ask, so this is also the quickest way to check the login still works. */
+    tables(options?: {
+        schema?: string;
+    }): Promise<DatabaseTable[]>;
+    /** One table's columns, with their types. */
+    describe(table: string, options?: {
+        schema?: string;
+    }): Promise<DatabaseColumn[]>;
+    /**
+     * Remove the database from the workspace, and its stored login with it.
+     *
+     * REFUSED while any agent's configuration still names it, with an error
+     * naming those agents. That refusal is what makes naming a key safe: an agent
+     * published against `shop` would otherwise find it gone the next morning and
+     * report that it has no data.
+     */
+    delete(): Promise<void>;
+}