@cerebro-labs/agentnava-sdk 0.26.0

package/conversation.d.ts

@@ -0,0 +1,177 @@
+import { type Attachable } from './attach.ts';
+import type { Http } from './http.ts';
+import { type Turn } from './turn.ts';
+import type { AgentConversationData, Attachment, Bindings, FileEntry, Message, Requirement } from './types.ts';
+export interface AskOptions {
+    attachments?: Attachment[];
+    signal?: AbortSignal;
+}
+export interface FileUrlOptions {
+    download?: boolean;
+    /** Seconds the link stays valid. */
+    ttl?: number;
+}
+/**
+ * A conversation you can work with.
+ *
+ * EVERY CONVERSATION BELONGS TO EXACTLY ONE AGENT, reachable as `agentId` once
+ * this handle has read anything. A conversation is an agent doing a piece of
+ * work; there is no such thing as a conversation with nobody.
+ *
+ * ADDRESSED FROM ITS PARENT: `agent.conversation(id)`, or
+ * `project.conversation(id)` for one a project owns. It used to be
+ * `ws.conversation(id)`, which made the parent look optional and is how this
+ * SDK came to describe conversations as parentless in its own reference. The
+ * objection to moving it was that a caller would then store two ids; in
+ * practice the agent id is a constant in their own code, not a per-row value.
+ *
+ * Holding one makes NO request. The first call on it is the first round trip,
+ * because fetching a conversation just to send it a message would be a round
+ * trip for nothing.
+ */
+export declare class Conversation {
+    #private;
+    readonly id: string;
+    /** Whatever the call that produced this object already knew. Present when it
+     *  came from `agent.start()`, absent when it came from `agent.conversation(id)`,
+     *  which is exactly the difference between having made a request and not. */
+    private snapshot?;
+    constructor(http: Http, id: string, snapshot?: AgentConversationData);
+    private get base();
+    /**
+     * The agent whose conversation this is.
+     *
+     * 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.
+     *
+     * 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
+     * `get()` to fill it in.
+     *
+     * ```ts
+     * const conversation = await agent.start({ endUserId: row.userId });
+     * conversation.agentId === agent.id;      // already known, no round trip
+     * ```
+     */
+    get agentId(): string | undefined;
+    /** True when nothing REQUIRED is outstanding.
+     *
+     *  Reads from the last snapshot rather than the network, so it is a property
+     *  and not a call. It is only meaningful on a conversation you just started
+     *  or just refreshed; call `get()` to bring it up to date. */
+    get ready(): boolean | undefined;
+    /** What the conversation is still missing. Same caveat as `ready`. */
+    get requires(): Requirement[];
+    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
+     * the events; doing both to the same turn throws rather than replaying.
+     */
+    ask(text: string, options?: AskOptions): Turn;
+    messages(): Promise<Message[]>;
+    /** End it, and its drive with it. */
+    end(): Promise<void>;
+    /**
+     * Give THIS conversation a credential, 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
+     * ```
+     *
+     * 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 cannot overwrite the agent's shared
+     * account or the person's own (ADR 0017).
+     *
+     * 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.
+     */
+    attach(what: Attachable | Attachable[] | Bindings): Promise<AgentConversationData>;
+    /**
+     * Attach a third-party account to THIS conversation, at `conversation` scope.
+     *
+     * 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).
+     *
+     * `agentId` is required alongside the conversation, so this reads the
+     * conversation first when it has not already.
+     */
+    authorize(provider: string): Promise<{
+        url: string;
+        connectionId: string;
+    }>;
+    /**
+     * Wait until this conversation has everything it needs.
+     *
+     * 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.
+     *
+     * ```ts
+     * const { url } = await conversation.authorize('gmail');
+     * showToUser(url);                  // popup, redirect, QR code, your choice
+     * await conversation.waitUntilReady();
+     * ```
+     *
+     * Returns as soon as nothing REQUIRED is outstanding, and returns the
+     * conversation so you do not need a second call. An optional requirement
+     * left unmet does not hold this up, for the same reason it does not make
+     * `ready` false: the conversation genuinely works without it.
+     *
+     * ON TIMEOUT it throws naming what is still missing, because "timed out" on
+     * its own sends you looking in the wrong place. The code is
+     * `conversation_not_ready` and it is safe to call again: a person who has
+     * not finished signing in yet may simply need longer.
+     *
+     * This polls rather than subscribing. For a step with a human in the middle,
+     * a few seconds of latency costs nothing, and it keeps the method usable
+     * from any runtime without a socket.
+     */
+    waitUntilReady(options?: {
+        /** Give up after this long. Default 2 minutes, which is generous for a
+         *  sign-in and short enough that a stuck flow does not hang a request. */
+        timeoutMs?: number;
+        /** Gap between checks. Default 2 seconds. */
+        intervalMs?: number;
+        /** Cancel the wait, e.g. when the caller's own request is abandoned. */
+        signal?: AbortSignal;
+    }): Promise<AgentConversationData>;
+    /** List one directory. `path`, not `dir`: it is the same parameter every other
+     *  file route on this API takes, and one name for one idea beats a prettier
+     *  name used in one place. */
+    files(path?: string): Promise<FileEntry[]>;
+    /** Read a text file. */
+    readFile(path: string): Promise<string>;
+    readFileBytes(path: string): Promise<Uint8Array>;
+    /**
+     * Put a file into the conversation's drive.
+     *
+     * This is how an application STAGES material: write the contract in, then ask
+     * the question about it. Anywhere under the root is fine; `input/` is a
+     * convention in the docs and nothing enforces it, because the agent and your
+     * application share one namespace.
+     */
+    writeFile(path: string, bytes: Uint8Array | ArrayBuffer, contentType?: string): Promise<FileEntry>;
+    removeFile(path: string): Promise<void>;
+    /**
+     * A link to one file that carries its own authorisation.
+     *
+     * A browser cannot hold an API key, so a Download button has no way to prove
+     * it is allowed. This grants that one file for `ttl` seconds and nothing
+     * else.
+     */
+    fileUrl(path: string, options?: FileUrlOptions): Promise<string>;
+}

package/conversation.js

@@ -0,0 +1,348 @@
+// 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 { AgentNavaError } from "./errors.js";
+import { makeTurn } from "./turn.js";
+/**
+ * A conversation you can work with.
+ *
+ * EVERY CONVERSATION BELONGS TO EXACTLY ONE AGENT, reachable as `agentId` once
+ * this handle has read anything. A conversation is an agent doing a piece of
+ * work; there is no such thing as a conversation with nobody.
+ *
+ * ADDRESSED FROM ITS PARENT: `agent.conversation(id)`, or
+ * `project.conversation(id)` for one a project owns. It used to be
+ * `ws.conversation(id)`, which made the parent look optional and is how this
+ * SDK came to describe conversations as parentless in its own reference. The
+ * objection to moving it was that a caller would then store two ids; in
+ * practice the agent id is a constant in their own code, not a per-row value.
+ *
+ * Holding one makes NO request. The first call on it is the first round trip,
+ * because fetching a conversation just to send it a message would be a round
+ * trip for nothing.
+ */
+export class Conversation {
+    id;
+    #http;
+    /** Whatever the call that produced this object already knew. Present when it
+     *  came from `agent.start()`, absent when it came from `agent.conversation(id)`,
+     *  which is exactly the difference between having made a request and not. */
+    snapshot;
+    constructor(http, id, snapshot) {
+        this.#http = http;
+        this.id = id;
+        if (snapshot)
+            this.snapshot = snapshot;
+    }
+    get base() {
+        return `/v1/conversations/${encodeURIComponent(this.id)}`;
+    }
+    /**
+     * The agent whose conversation this is.
+     *
+     * 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.
+     *
+     * 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
+     * `get()` to fill it in.
+     *
+     * ```ts
+     * const conversation = await agent.start({ endUserId: row.userId });
+     * conversation.agentId === agent.id;      // already known, no round trip
+     * ```
+     */
+    get agentId() {
+        return this.snapshot?.agentId;
+    }
+    /** True when nothing REQUIRED is outstanding.
+     *
+     *  Reads from the last snapshot rather than the network, so it is a property
+     *  and not a call. It is only meaningful on a conversation you just started
+     *  or just refreshed; call `get()` to bring it up to date. */
+    get ready() {
+        return this.snapshot?.ready;
+    }
+    /** What the conversation is still missing. Same caveat as `ready`. */
+    get requires() {
+        return this.snapshot?.requires ?? [];
+    }
+    async get() {
+        const data = await this.#http.get(this.base);
+        this.snapshot = data;
+        return data;
+    }
+    /**
+     * 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
+     * the events; doing both to the same turn throws rather than replaying.
+     */
+    ask(text, options = {}) {
+        const response = this.#http.send(`${this.base}/messages`, {
+            method: 'POST',
+            body: {
+                content: text,
+                ...(options.attachments?.length && { attachments: options.attachments }),
+            },
+            ...(options.signal && { signal: options.signal }),
+        });
+        return makeTurn(response);
+    }
+    async messages() {
+        const res = await this.#http.get(`${this.base}/messages`);
+        return res.messages ?? [];
+    }
+    /** End it, and its drive with it. */
+    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.
+     *
+     *  WRAPPED IN `sessionBindings`, and that envelope is load-bearing. This
+     *  posted the object at the top level, while `addSessionBindings` reads
+     *  `body.sessionBindings`. The handler therefore saw undefined, and undefined
+     *  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.
+     *
+     *  `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
+     *  together. */
+    async #applyBindings(bindings) {
+        const data = await this.#http.post(`${this.base}/bindings`, {
+            sessionBindings: bindings,
+        });
+        this.snapshot = data;
+        return data;
+    }
+    /**
+     * Give THIS conversation a credential, 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
+     * ```
+     *
+     * 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 cannot overwrite the agent's shared
+     * account or the person's own (ADR 0017).
+     *
+     * 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.
+     */
+    async attach(what) {
+        if (isBindings(what))
+            return this.#applyBindings(what);
+        const split = splitAttachments(what);
+        const connections = await providersOf(split.connections);
+        const secretIds = await secretIdsOf(split.secrets);
+        return this.#applyBindings({
+            ...(connections && { connections }),
+            ...(secretIds && { secretIds }),
+        });
+    }
+    /**
+     * Attach a third-party account to THIS conversation, at `conversation` scope.
+     *
+     * 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).
+     *
+     * `agentId` is required alongside the conversation, so this reads the
+     * conversation first when it has not already.
+     */
+    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 };
+    }
+    /**
+     * Wait until this conversation has everything it needs.
+     *
+     * 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.
+     *
+     * ```ts
+     * const { url } = await conversation.authorize('gmail');
+     * showToUser(url);                  // popup, redirect, QR code, your choice
+     * await conversation.waitUntilReady();
+     * ```
+     *
+     * Returns as soon as nothing REQUIRED is outstanding, and returns the
+     * conversation so you do not need a second call. An optional requirement
+     * left unmet does not hold this up, for the same reason it does not make
+     * `ready` false: the conversation genuinely works without it.
+     *
+     * ON TIMEOUT it throws naming what is still missing, because "timed out" on
+     * its own sends you looking in the wrong place. The code is
+     * `conversation_not_ready` and it is safe to call again: a person who has
+     * not finished signing in yet may simply need longer.
+     *
+     * This polls rather than subscribing. For a step with a human in the middle,
+     * a few seconds of latency costs nothing, and it keeps the method usable
+     * from any runtime without a socket.
+     */
+    async waitUntilReady(options = {}) {
+        const timeoutMs = options.timeoutMs ?? 120_000;
+        const intervalMs = options.intervalMs ?? 2_000;
+        const deadline = Date.now() + timeoutMs;
+        // Checked BEFORE the first sleep. A conversation that is already ready
+        // should cost one request, not one request plus an interval.
+        let data = await this.get();
+        while (!data.ready) {
+            if (options.signal?.aborted) {
+                throw new AgentNavaError({
+                    message: 'waitUntilReady was cancelled',
+                    code: 'aborted',
+                    status: 0,
+                });
+            }
+            if (Date.now() >= deadline) {
+                // Name the outstanding REQUIRED items. The optional ones are not why
+                // this failed and listing them would send someone after the wrong
+                // thing.
+                const outstanding = data.requires
+                    .filter((r) => r.required)
+                    .map((r) => `${r.kind} ${r.name}`);
+                throw new AgentNavaError({
+                    message: outstanding.length
+                        ? `Conversation ${this.id} is still waiting on: ${outstanding.join(', ')}`
+                        : `Conversation ${this.id} did not become ready within ${timeoutMs}ms`,
+                    code: 'conversation_not_ready',
+                    status: 0,
+                });
+            }
+            // Never sleep past the deadline, so the timeout means what it says.
+            await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())), options.signal);
+            data = await this.get();
+        }
+        return data;
+    }
+    // ---------------------------------------------------------------- the drive
+    /** List one directory. `path`, not `dir`: it is the same parameter every other
+     *  file route on this API takes, and one name for one idea beats a prettier
+     *  name used in one place. */
+    async files(path = '/') {
+        const res = await this.#http.get(`${this.base}/files`, { path });
+        return (res.files ?? []).map(toFileEntry);
+    }
+    /** Read a text file. */
+    async readFile(path) {
+        // The route answers JSON `{path, content}`, not bare text. The envelope is
+        // worth keeping on the wire (the canonical path comes back with it), so the
+        // unwrapping happens here: a caller asked for the file, not for a wrapper.
+        const res = await this.#http.get(`${this.base}/files/content`, { path });
+        return res.content ?? '';
+    }
+    async readFileBytes(path) {
+        const res = await this.#http.send(`${this.base}/files/raw`, { query: { path } });
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    /**
+     * Put a file into the conversation's drive.
+     *
+     * This is how an application STAGES material: write the contract in, then ask
+     * the question about it. Anywhere under the root is fine; `input/` is a
+     * convention in the docs and nothing enforces it, because the agent and your
+     * application share one namespace.
+     */
+    async writeFile(path, bytes, contentType) {
+        return this.#http.request(`${this.base}/files`, {
+            method: 'PUT',
+            bytes,
+            query: { path },
+            ...(contentType && { contentType }),
+        });
+    }
+    async removeFile(path) {
+        await this.#http.delete(`${this.base}/files`, { path });
+    }
+    /**
+     * A link to one file that carries its own authorisation.
+     *
+     * A browser cannot hold an API key, so a Download button has no way to prove
+     * it is allowed. This grants that one file for `ttl` seconds and nothing
+     * else.
+     */
+    async fileUrl(path, options = {}) {
+        const res = await this.#http.post(`${this.base}/files/url`, {
+            path,
+            ...(options.download !== undefined && { download: options.download }),
+            ...(options.ttl !== undefined && { ttl: options.ttl }),
+        });
+        return res.url;
+    }
+}
+const CONTENT_TYPES = {
+    txt: 'text/plain',
+    md: 'text/markdown',
+    json: 'application/json',
+    csv: 'text/csv',
+    html: 'text/html',
+    js: 'text/javascript',
+    ts: 'text/typescript',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    pdf: 'application/pdf',
+};
+/**
+ * A Drive entry as the SDK's FileEntry.
+ *
+ * The Drive speaks `isDir` and `mtime`; the SDK speaks `kind` and an ISO
+ * `modifiedAt`. Translating at the edge is the SDK's job: the Drive's shape is
+ * what apps/web's DrivePane reads, and changing it to suit this would break a
+ * working screen to save a mapping function.
+ *
+ * `mimeType` is inferred from the extension, because the Drive does not store
+ * one (see apps/backend-workers/src/sandbox/drive-reader.ts, which infers it the
+ * same way on read).
+ */
+function toFileEntry(entry) {
+    const ext = entry.path.slice(entry.path.lastIndexOf('.') + 1).toLowerCase();
+    return {
+        path: entry.path,
+        kind: entry.isDir ? 'directory' : 'file',
+        mimeType: entry.isDir ? 'inode/directory' : (CONTENT_TYPES[ext] ?? 'application/octet-stream'),
+        size: entry.size,
+        modifiedAt: new Date(entry.mtime).toISOString(),
+    };
+}
+/** Wait, and stop waiting early if the caller aborts. */
+function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        }
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+//# sourceMappingURL=conversation.js.map

package/conversation.js.map

@@ -0,0 +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"]}