@cerebro-labs/agentnava-sdk 0.26.0

package/agent.d.ts

@@ -0,0 +1,285 @@
+import { type Attachable } from './attach.ts';
+import { Conversation } from './conversation.ts';
+import type { Http } from './http.ts';
+import type { AgentData, AgentFields, Bindings, ConnectionStatus, FileEntry, Trigger, Workflow } from './types.ts';
+/**
+ * Turn the accounts a caller is holding into the `{ provider: id }` map the
+ * wire speaks.
+ *
+ * Shared by `start`, `agent.attach` and `conversation.attach` so the three
+ * cannot drift. A handle you created carries its provider already; one you
+ * addressed by id has to read it, which is the only request here and only when
+ * it is unavoidable.
+ */
+export interface StartOptions {
+    /**
+     * Accounts to attach AS THE CONVERSATION STARTS.
+     *
+     * The common shape for an application with many end users: the person
+     * connected Gmail once, and this thread should act as them from its first
+     * turn.
+     *
+     * ```ts
+     * const gmail = await ws.endUser(row.userId).connections.list();
+     * const c = await agent.start({ endUserId: row.userId, attach: gmail });
+     * ```
+     *
+     * Doing it here rather than with a second `conversation.attach()` call
+     * closes a real window: between `start` and the attach, the conversation
+     * exists and can be asked something, and it would answer without the
+     * account.
+     *
+     * STILL EXPLICIT. Naming `endUserId` does not attach their accounts; this
+     * line does, and you can read it.
+     *
+     * TAKES SECRETS TOO. A `Secret` from `ws.endUser(id).secrets.create(...)`
+     * attaches by id, which is the only way a stored per-person credential can
+     * reach a turn: you never hold its value. Mix them freely, they are split by
+     * type before the launch.
+     */
+    attach?: Attachable | Attachable[];
+    /**
+     * Secret VALUES for this conversation only.
+     *
+     * Not `attach`, because a secret has no id you can hand over: binding one
+     * takes the value itself. That asymmetry is in the product, not in this
+     * naming, and hiding it behind the same word would not remove it.
+     */
+    secrets?: Record<string, string>;
+    /** Pin a specific version. Defaults to the latest at the moment of starting.
+     *
+     *  A conversation pins its version for life: publishing afterwards does not
+     *  move a conversation that is already open. */
+    version?: number;
+    parameters?: Record<string, string | number>;
+    /**
+     * WHO this conversation is for: one of YOUR users, not one of ours.
+     *
+     * REQUIRED, and nullable. You must say, and `null` is a real answer: a
+     * nightly report belongs to nobody. Optional would let it be forgotten,
+     * which is the mistake worth designing against, because a conversation
+     * without an owner cannot be listed back to the person it was for.
+     *
+     * It is a LABEL on the conversation, and nothing else. It does not decide
+     * which conversation you get, because `start` always starts a new one.
+     * Later you can ask for everything belonging to that person:
+     *
+     * ```ts
+     * const conversation = await agent.start({ endUserId: row.userId });
+     * const nobody       = await agent.start({ endUserId: null });  // a nightly job
+     * const theirs       = await agent.conversations({ endUser: row.userId });
+     * ```
+     *
+     * To CONTINUE a conversation, keep its id and address it directly. That is
+     * the only way to continue one, on purpose:
+     *
+     * ```ts
+     * await ws.agent(AGENT).conversation(row.conversationId).ask('and the rest?');
+     * ```
+     *
+     * The id is YOURS and opaque to us: a row id from your database, not an
+     * email and not something we authenticate. We never verify it, so it is
+     * exactly as trustworthy as whatever holds your API key.
+     *
+     * NOT A WORKSPACE MEMBER'S ID. `ws.members()` lists the colleagues who share
+     * this account, and their `userId` is a platform id we issued. This field is
+     * a different namespace entirely. Both were once spelled `userId`, so
+     * passing a member id here was a call that could not fail: there is nothing
+     * for an end-user id to be checked against, so it just labelled the
+     * conversation with a colleague's internal id and looked fine.
+     */
+    endUserId: string | null;
+}
+/**
+ * An agent you can configure and start conversations from.
+ *
+ * Holding one makes NO request: `ws.agent(id)` is free and the first call on it
+ * is the first round trip.
+ *
+ * EVERY METHOD THAT CHANGES THE AGENT PUBLISHES A VERSION. There is no separate
+ * save. What you do not send is inherited from the current version, which is the
+ * only reason changing one field is safe: a resend that rebuilt the whole
+ * configuration would drop whatever the caller forgot, and that bug has shipped
+ * here four separate times.
+ */
+export declare class Agent {
+    #private;
+    readonly id: string;
+    private snapshot?;
+    constructor(http: Http, id: string, snapshot?: AgentData);
+    private get base();
+    /** The last-known configuration, from whatever call produced this object.
+     *  Undefined on an agent you addressed by id and have not read. */
+    get data(): AgentData | undefined;
+    get(options?: {
+        version?: number;
+    }): Promise<AgentData>;
+    /** Every version, newest first. */
+    versions(): Promise<AgentData[]>;
+    /** Publish a new version with these fields changed and everything else kept. */
+    update(fields: AgentFields): Promise<Agent>;
+    delete(): Promise<void>;
+    /**
+     * Add a workflow, or replace the one with the same name.
+     *
+     * Reads the current list and sends it back with this one in place, because
+     * the API replaces the whole list: a workflow set is a list, and there is no
+     * "merge one item" that does not have to decide what a duplicate name means.
+     * Deciding it here, once, is better than every caller deciding it.
+     */
+    setWorkflow(workflow: Workflow): Promise<Agent>;
+    removeWorkflow(name: string): Promise<Agent>;
+    /** Replace the trigger list. Sending `[]` removes every trigger, including
+     *  `chat`, which is what leaves an agent that only runs on a schedule. */
+    setTriggers(triggers: Trigger[]): Promise<Agent>;
+    /**
+     * The agent's knowledge: files every conversation can read.
+     *
+     * BY REFERENCE, not by copy. A conversation reads the knowledge as it is now,
+     * so replacing a file changes what open conversations see on their next turn.
+     * That is the opposite of how a version works, and it is deliberate: a price
+     * list that could not be corrected without republishing the agent would be
+     * useless.
+     */
+    readonly knowledge: {
+        put: (path: string, bytes: Uint8Array | ArrayBuffer, contentType?: string) => Promise<FileEntry>;
+        list: (path?: string) => Promise<FileEntry[]>;
+        remove: (path: string) => Promise<void>;
+    };
+    /**
+     * The WORKSPACE knowledge bases this agent reads.
+     *
+     * Different from `knowledge` above, and the distinction is the whole point.
+     * `agent.knowledge` is files this agent owns; nobody else has them. A
+     * knowledge base is shared: one price list, attached to nine agents, corrected
+     * in one place.
+     *
+     * Each attached base is mounted read-only at `/knowledge/<key>/` when a turn
+     * starts, so the agent reads it with `ls`, `grep` and `cat`.
+     *
+     * ATTACHING PUBLISHES A VERSION. Which bases an agent reads is part of its
+     * configuration, so the change is diffable and reversible like any other
+     * configuration change. The CONTENTS of a base are not versioned: correcting
+     * a file changes what every attached agent sees on its next turn.
+     */
+    readonly knowledgeBases: {
+        /**
+         * Attach one base by key.
+         *
+         * One call, not read-modify-write, deliberately. Two attaches racing
+         * through a read of the current list and a write of the whole list would
+         * lose one of them silently, and losing an attachment looks exactly like
+         * an agent that cannot find its knowledge. The server appends.
+         *
+         * Attaching a key that names no base is refused, naming the key. Attaching
+         * one that is already attached is a no-op, not an error.
+         */
+        attach: (key: string) => Promise<Agent>;
+        /** Detach one base. The base itself and its files are untouched: this only
+         *  stops THIS agent from reading it. Detaching one that is not attached is
+         *  a no-op. */
+        detach: (key: string) => Promise<Agent>;
+        /** The keys this agent currently reads, in configuration order. */
+        list: () => Promise<string[]>;
+    };
+    /**
+     * Give this agent a credential, so every conversation with it can use one.
+     *
+     * ```ts
+     * await agent.attach(gmail);                        // one account
+     * await agent.attach([gmail, calendar]);            // several
+     * await agent.attach({ secrets: { KEY: value } });  // a secret VALUE
+     * ```
+     *
+     * ONE VERB, NOT TWO. This and `bind` used to both exist and do the same job
+     * through different shapes, which is how a surface becomes hard to learn:
+     * two names for one idea means every reader has to work out whether the
+     * difference is meaningful. It is not, so `bind` is gone.
+     *
+     * "Attach" rather than "bind" because it is the plainer word, it is the one
+     * that pairs with `detach`, and `knowledgeBases.attach/detach` already uses
+     * it for the same shape of operation.
+     *
+     * ACCOUNTS TAKE THE OBJECT, SECRETS TAKE A VALUE, and that asymmetry is in
+     * the product rather than in the naming. An account has an id you can hand
+     * over; a secret does not, because binding one means supplying the value
+     * itself. Hiding that behind one shape would not make it go away.
+     *
+     * The counterpart to `authorize()`, which creates an account AND attaches it
+     * in one step. Use this when the account already exists: one team mailbox
+     * connected once and attached to nine agents, rather than nine sign-ins.
+     */
+    attach(what: Attachable | Attachable[] | Bindings): Promise<Agent>;
+    /** What each declared provider's actual state is: DECLARED IS NOT CONNECTED.
+     *
+     *  An agent can require Gmail with nobody signed in, and that is the state a
+     *  setup checklist has to show. Without this the only way to find the gap is
+     *  to start a conversation and watch the agent fail. */
+    connections(): Promise<ConnectionStatus[]>;
+    /**
+     * Attach a third-party account to this agent, at `fixed` scope: one account,
+     * used by every conversation.
+     *
+     * Returns a url to send a person to. They sign in there, in their own
+     * browser, and the account attaches when they finish. YOU NEVER SEE A TOKEN,
+     * which is the entire point: nobody should be pasting a Gmail credential into
+     * a config field.
+     *
+     * This does NOT satisfy a declaration scoped 'conversation'. Use
+     * `conversation.authorize()` for those, which attaches the account to that
+     * one conversation and cannot overwrite this shared one.
+     */
+    authorize(provider: string): Promise<{
+        url: string;
+        connectionId: string;
+    }>;
+    /** Detach the account connected for this provider.
+     *
+     *  Reads the raw ROWS rather than the merged status, because revoking needs
+     *  the connection's id and the merged view is keyed by provider: it answers
+     *  "is Gmail connected", not "which row is it". */
+    disconnect(provider: string): Promise<void>;
+    /** Start a conversation. It pins the agent's version now and keeps it. */
+    start(options: StartOptions): Promise<Conversation>;
+    /**
+     * Address one of this agent's conversations by id. No request.
+     *
+     * Here rather than on the workspace because a conversation belongs to an
+     * agent. You already hold the agent: it is a constant in your own code, not
+     * a per-row value, so naming it costs nothing and the ownership is visible.
+     *
+     * ```ts
+     * await ws.agent(AGENT).conversation(row.conversationId).ask('carry on');
+     * ```
+     */
+    conversation(conversationId: string): Conversation;
+    /**
+     * This agent's most recent conversations, newest first.
+     *
+     * NOT ALL OF THEM, and the previous sentence here said "every", which was
+     * wrong in the way that costs someone an afternoon. The server returns the
+     * newest 50 unless you ask for more, and refuses to return more than 200 on
+     * any single call (apps/api/src/state.ts listAgentSessions, and the Durable
+     * Object twin beside it, clamp identically).
+     *
+     * There is no cursor on this route yet, so an agent with more than 200
+     * conversations CANNOT be fully enumerated through this method. If you are
+     * counting or exporting, do not build on it; that needs a paginated route we
+     * have not added. `ws.endUser(id).conversations()` DOES have a cursor, if
+     * the question is one person's history rather than one agent's.
+     *
+     * `endUser` narrows to one of YOUR end users, which is what you want for a
+     * "your conversations" list. Leaving it out returns everyone's, so leave it
+     * out only for an operator view.
+     *
+     * ```ts
+     * const mine = await agent.conversations({ endUser: row.userId });
+     * ```
+     */
+    conversations(options?: {
+        limit?: number;
+        endUser?: string;
+    }): Promise<Conversation[]>;
+}
+/** A connection row as `GET /v1/connections` returns it (toConnectionMeta in
+ *  apps/api/src/connections/store.ts). */

package/agent.js

@@ -0,0 +1,394 @@
+// An agent: a configuration you start conversations from.
+var _a;
+import { isBindings, providersOf, secretIdsOf, splitAttachments } from "./attach.js";
+import { toConnectionStatus } from "./connection-status.js";
+import { Conversation } from "./conversation.js";
+/**
+ * An agent you can configure and start conversations from.
+ *
+ * Holding one makes NO request: `ws.agent(id)` is free and the first call on it
+ * is the first round trip.
+ *
+ * EVERY METHOD THAT CHANGES THE AGENT PUBLISHES A VERSION. There is no separate
+ * save. What you do not send is inherited from the current version, which is the
+ * only reason changing one field is safe: a resend that rebuilt the whole
+ * configuration would drop whatever the caller forgot, and that bug has shipped
+ * here four separate times.
+ */
+export class Agent {
+    id;
+    #http;
+    snapshot;
+    constructor(http, id, snapshot) {
+        this.#http = http;
+        this.id = id;
+        if (snapshot)
+            this.snapshot = snapshot;
+    }
+    get base() {
+        return `/v1/agents/${encodeURIComponent(this.id)}`;
+    }
+    /** The last-known configuration, from whatever call produced this object.
+     *  Undefined on an agent you addressed by id and have not read. */
+    get data() {
+        return this.snapshot;
+    }
+    async get(options = {}) {
+        const data = await this.#http.get(this.base, options.version !== undefined ? { version: options.version } : undefined);
+        // Only cache the CURRENT configuration. Caching a historical version would
+        // make `agent.data` mean different things depending on the last call.
+        if (options.version === undefined)
+            this.snapshot = data;
+        return data;
+    }
+    /** Every version, newest first. */
+    async versions() {
+        const res = await this.#http.get(`${this.base}/versions`);
+        return res.versions ?? [];
+    }
+    /** Publish a new version with these fields changed and everything else kept. */
+    async update(fields) {
+        const data = await this.#http.post(`${this.base}/versions`, fields);
+        this.snapshot = data;
+        return new _a(this.#http, this.id, data);
+    }
+    async delete() {
+        await this.#http.delete(this.base);
+    }
+    // --------------------------------------------------------------- workflows
+    /**
+     * Add a workflow, or replace the one with the same name.
+     *
+     * Reads the current list and sends it back with this one in place, because
+     * the API replaces the whole list: a workflow set is a list, and there is no
+     * "merge one item" that does not have to decide what a duplicate name means.
+     * Deciding it here, once, is better than every caller deciding it.
+     */
+    async setWorkflow(workflow) {
+        const current = this.snapshot?.workflows ?? (await this.get()).workflows;
+        const next = current.filter((w) => w.name !== workflow.name).concat(workflow);
+        return this.update({ workflows: next });
+    }
+    async removeWorkflow(name) {
+        const current = this.snapshot?.workflows ?? (await this.get()).workflows;
+        return this.update({ workflows: current.filter((w) => w.name !== name) });
+    }
+    /** Replace the trigger list. Sending `[]` removes every trigger, including
+     *  `chat`, which is what leaves an agent that only runs on a schedule. */
+    async setTriggers(triggers) {
+        return this.update({ triggers });
+    }
+    // --------------------------------------------------------------- knowledge
+    /**
+     * The agent's knowledge: files every conversation can read.
+     *
+     * BY REFERENCE, not by copy. A conversation reads the knowledge as it is now,
+     * so replacing a file changes what open conversations see on their next turn.
+     * That is the opposite of how a version works, and it is deliberate: a price
+     * list that could not be corrected without republishing the agent would be
+     * useless.
+     */
+    knowledge = {
+        put: async (path, bytes, contentType) => this.#http.request(`${this.base}/knowledge/files`, {
+            method: 'PUT',
+            bytes,
+            query: { path },
+            ...(contentType && { contentType }),
+        }),
+        list: async (path = '/') => {
+            // The route returns EVERY knowledge file for the agent; it takes no
+            // directory parameter. Filtering here rather than sending one the server
+            // ignores, because a call that looks filtered and is not is worse than
+            // no filter at all. Knowledge sets are small, so one read is right.
+            const res = await this.#http.get(`${this.base}/knowledge/files`);
+            const prefix = path === '/' ? '/' : `${path.replace(/\/+$/, '')}/`;
+            return (res.files ?? []).filter((f) => f.path?.startsWith(prefix));
+        },
+        remove: async (path) => {
+            await this.#http.delete(`${this.base}/knowledge/files`, { path });
+        },
+    };
+    // -------------------------------------------------------- knowledge bases
+    /**
+     * The WORKSPACE knowledge bases this agent reads.
+     *
+     * Different from `knowledge` above, and the distinction is the whole point.
+     * `agent.knowledge` is files this agent owns; nobody else has them. A
+     * knowledge base is shared: one price list, attached to nine agents, corrected
+     * in one place.
+     *
+     * Each attached base is mounted read-only at `/knowledge/<key>/` when a turn
+     * starts, so the agent reads it with `ls`, `grep` and `cat`.
+     *
+     * ATTACHING PUBLISHES A VERSION. Which bases an agent reads is part of its
+     * configuration, so the change is diffable and reversible like any other
+     * configuration change. The CONTENTS of a base are not versioned: correcting
+     * a file changes what every attached agent sees on its next turn.
+     */
+    knowledgeBases = {
+        /**
+         * Attach one base by key.
+         *
+         * One call, not read-modify-write, deliberately. Two attaches racing
+         * through a read of the current list and a write of the whole list would
+         * lose one of them silently, and losing an attachment looks exactly like
+         * an agent that cannot find its knowledge. The server appends.
+         *
+         * Attaching a key that names no base is refused, naming the key. Attaching
+         * one that is already attached is a no-op, not an error.
+         */
+        attach: async (key) => {
+            const res = await this.#http.post(`${this.base}/knowledge-bases`, { key });
+            this.snapshot = res;
+            return this;
+        },
+        /** Detach one base. The base itself and its files are untouched: this only
+         *  stops THIS agent from reading it. Detaching one that is not attached is
+         *  a no-op. */
+        detach: async (key) => {
+            const res = await this.#http.delete(`${this.base}/knowledge-bases/${encodeURIComponent(key)}`);
+            if (res)
+                this.snapshot = res;
+            return this;
+        },
+        /** The keys this agent currently reads, in configuration order. */
+        list: async () => {
+            const current = this.snapshot ?? (await this.get());
+            return current.knowledgeBases ?? [];
+        },
+    };
+    // ------------------------------------------------- credentials, agent tier
+    /**
+     * Supply the credentials declared at 'fixed' scope: set once, used by every
+     * conversation. This does NOT satisfy a declaration scoped 'conversation'.
+     *
+     * A secret is written to this agent's own scope, so it is readable by this
+     * agent and nothing else in the workspace, and it overrides a workspace
+     * secret of the same name. Writing one twice replaces the value rather than
+     * failing, because `bind` means "this is the credential now".
+     *
+     * A connection value is the id of an account already attached to the
+     * workspace; use `authorize()` when there is no account yet, since that is
+     * the flow where a person signs in and no token passes through your code.
+     *
+     * This used to POST the whole `{secrets, connections}` object to
+     * `/v1/agents/:id/bindings`, which answers only to `{kind, decl}` and records
+     * a DECLARATION, never a value. So the call 400'd, and had it not, it would
+     * have stored the fact that a secret is wanted rather than the secret.
+     */
+    async #applyBindings(bindings) {
+        for (const [name, value] of Object.entries(bindings.secrets ?? {})) {
+            const mine = (await this.#http.get('/v1/secrets', { agentId: this.id })).secrets ?? [];
+            const existing = mine.find((s) => s.name === name && s.agentId);
+            if (existing)
+                await this.#http.patch(`/v1/secrets/${encodeURIComponent(existing.id)}`, { value });
+            else
+                await this.#http.post('/v1/secrets', { name, value, agentId: this.id });
+        }
+        for (const [provider, connectionId] of Object.entries(bindings.connections ?? {})) {
+            await this.#http.post(`${this.base}/bindings`, {
+                kind: 'connection',
+                decl: { provider, connectionId, scope: 'fixed' },
+            });
+        }
+        const data = await this.get();
+        this.snapshot = data;
+        return new _a(this.#http, this.id, data);
+    }
+    /**
+     * Give this agent a credential, so every conversation with it can use one.
+     *
+     * ```ts
+     * await agent.attach(gmail);                        // one account
+     * await agent.attach([gmail, calendar]);            // several
+     * await agent.attach({ secrets: { KEY: value } });  // a secret VALUE
+     * ```
+     *
+     * ONE VERB, NOT TWO. This and `bind` used to both exist and do the same job
+     * through different shapes, which is how a surface becomes hard to learn:
+     * two names for one idea means every reader has to work out whether the
+     * difference is meaningful. It is not, so `bind` is gone.
+     *
+     * "Attach" rather than "bind" because it is the plainer word, it is the one
+     * that pairs with `detach`, and `knowledgeBases.attach/detach` already uses
+     * it for the same shape of operation.
+     *
+     * ACCOUNTS TAKE THE OBJECT, SECRETS TAKE A VALUE, and that asymmetry is in
+     * the product rather than in the naming. An account has an id you can hand
+     * over; a secret does not, because binding one means supplying the value
+     * itself. Hiding that behind one shape would not make it go away.
+     *
+     * The counterpart to `authorize()`, which creates an account AND attaches it
+     * in one step. Use this when the account already exists: one team mailbox
+     * connected once and attached to nine agents, rather than nine sign-ins.
+     */
+    async attach(what) {
+        if (isBindings(what))
+            return this.#applyBindings(what);
+        const split = splitAttachments(what);
+        const connections = await providersOf(split.connections);
+        const secretIds = await secretIdsOf(split.secrets);
+        return this.#applyBindings({
+            ...(connections && { connections }),
+            ...(secretIds && { secretIds }),
+        });
+    }
+    /** What each declared provider's actual state is: DECLARED IS NOT CONNECTED.
+     *
+     *  An agent can require Gmail with nobody signed in, and that is the state a
+     *  setup checklist has to show. Without this the only way to find the gap is
+     *  to start a conversation and watch the agent fail. */
+    async connections() {
+        // The MERGED view, not the raw connection rows. /v1/connections?agentId=
+        // lists rows that exist, so a provider the agent declares and nobody has
+        // connected is simply absent from it, which is the one case this method is
+        // most often asked about. The server merges declared against live with the
+        // same function the agent's own check_connections tool uses.
+        const res = await this.#http.get(`${this.base}/connections`);
+        return res.connections ?? [];
+    }
+    /**
+     * Attach a third-party account to this agent, at `fixed` scope: one account,
+     * used by every conversation.
+     *
+     * Returns a url to send a person to. They sign in there, in their own
+     * browser, and the account attaches when they finish. YOU NEVER SEE A TOKEN,
+     * which is the entire point: nobody should be pasting a Gmail credential into
+     * a config field.
+     *
+     * This does NOT satisfy a declaration scoped 'conversation'. Use
+     * `conversation.authorize()` for those, which attaches the account to that
+     * one conversation and cannot overwrite this shared one.
+     */
+    async authorize(provider) {
+        const res = await this.#http.post('/v1/connections/connect', { provider, agentId: this.id });
+        // `url` on the way out, `authUrl` on the wire. The SDK's name is the one
+        // the reference documents and reads better at a call site.
+        return { url: res.authUrl, connectionId: res.connectionId };
+    }
+    /** Detach the account connected for this provider.
+     *
+     *  Reads the raw ROWS rather than the merged status, because revoking needs
+     *  the connection's id and the merged view is keyed by provider: it answers
+     *  "is Gmail connected", not "which row is it". */
+    async disconnect(provider) {
+        const res = await this.#http.get('/v1/connections', {
+            agentId: this.id,
+        });
+        const match = (res.connections ?? [])
+            .map(toConnectionStatus)
+            .find((c) => c.provider === provider && c.connected);
+        // Nothing connected is not an error: the caller wanted this provider
+        // detached, and it is.
+        if (!match?.id)
+            return;
+        await this.#http.post(`/v1/connections/${encodeURIComponent(match.id)}/revoke`);
+    }
+    // ----------------------------------------------------------- conversations
+    /** Start a conversation. It pins the agent's version now and keeps it. */
+    async start(options) {
+        // Resolved BEFORE the launch, because an account is named on the wire by
+        // its provider and a handle addressed by id may not know its own yet.
+        // Split first: a Connection is named on the wire by its PROVIDER and a
+        // Secret by the declared NAME it fills, so the two cannot share a map.
+        const split = splitAttachments(options.attach);
+        const connections = await providersOf(split.connections);
+        const secretIds = await secretIdsOf(split.secrets);
+        const bindings = options.secrets || connections || secretIds
+            ? {
+                ...(options.secrets && { secrets: options.secrets }),
+                ...(secretIds && { secretIds }),
+                ...(connections && { connections }),
+            }
+            : undefined;
+        const data = await this.#http.post('/v1/conversations', {
+            agentId: this.id,
+            ...(options.version !== undefined && { version: options.version }),
+            ...(options.parameters && { parameters: options.parameters }),
+            // `sessionBindings`, NOT `secrets` and `connections` at the top level.
+            //
+            // This sent them at the top level and the launch route reads
+            // `body.sessionBindings`, so they were dropped in silence: the route's
+            // own body type has no top-level `secrets` or `connections` to read.
+            // A conversation started with a credential began without it, and the
+            // first turn failed somewhere else entirely.
+            //
+            // Third place this exact envelope mistake was found in one afternoon,
+            // after `agent.bind` and `conversation.bind`. The shape of the bug is
+            // always the same: the SDK agrees with itself, the route agrees with
+            // itself, and nothing compares the two.
+            ...(bindings && { sessionBindings: bindings }),
+            // `!= null`, catching undefined as well as null. The field is REQUIRED
+            // in TypeScript, but a JavaScript caller can still omit it, and
+            // `!== null` alone then sent `user: {}`: an owner object with no id,
+            // which is neither "nobody" nor a person.
+            ...(options.endUserId != null && { user: { id: options.endUserId } }),
+            // ALWAYS a new conversation, even when a user is named.
+            //
+            // The route resumes that user's most recent conversation when it is
+            // given an identity and not told otherwise. That default exists for
+            // our own web app, where a page reload must not leave a trail of empty
+            // conversations, and it is wrong for a method called `start`: a verb
+            // that sometimes does not do the thing is worse than two verbs. It is
+            // also ambiguous the moment a user has more than one conversation,
+            // since it silently picks the newest.
+            //
+            // So the SDK does not rely on that default. `start` starts. To
+            // continue a conversation, hold its id: `agent.conversation(id)`.
+            fresh: true,
+        });
+        return new Conversation(this.#http, data.id, data);
+    }
+    /**
+     * Address one of this agent's conversations by id. No request.
+     *
+     * Here rather than on the workspace because a conversation belongs to an
+     * agent. You already hold the agent: it is a constant in your own code, not
+     * a per-row value, so naming it costs nothing and the ownership is visible.
+     *
+     * ```ts
+     * await ws.agent(AGENT).conversation(row.conversationId).ask('carry on');
+     * ```
+     */
+    conversation(conversationId) {
+        return new Conversation(this.#http, conversationId);
+    }
+    /**
+     * This agent's most recent conversations, newest first.
+     *
+     * NOT ALL OF THEM, and the previous sentence here said "every", which was
+     * wrong in the way that costs someone an afternoon. The server returns the
+     * newest 50 unless you ask for more, and refuses to return more than 200 on
+     * any single call (apps/api/src/state.ts listAgentSessions, and the Durable
+     * Object twin beside it, clamp identically).
+     *
+     * There is no cursor on this route yet, so an agent with more than 200
+     * conversations CANNOT be fully enumerated through this method. If you are
+     * counting or exporting, do not build on it; that needs a paginated route we
+     * have not added. `ws.endUser(id).conversations()` DOES have a cursor, if
+     * the question is one person's history rather than one agent's.
+     *
+     * `endUser` narrows to one of YOUR end users, which is what you want for a
+     * "your conversations" list. Leaving it out returns everyone's, so leave it
+     * out only for an operator view.
+     *
+     * ```ts
+     * const mine = await agent.conversations({ endUser: row.userId });
+     * ```
+     */
+    async conversations(options = {}) {
+        const res = await this.#http.get('/v1/conversations', {
+            agentId: this.id,
+            ...(options.limit !== undefined && { limit: options.limit }),
+            // One end user's history. Sending this used to be silently ignored on
+            // this route, which answered with everyone's conversations, so an
+            // application rendering "your chats" showed somebody else's.
+            ...(options.endUser !== undefined && { end_user_id: options.endUser }),
+        });
+        return (res.conversations ?? []).map((c) => new Conversation(this.#http, c.id, c));
+    }
+}
+_a = Agent;
+/** A connection row as `GET /v1/connections` returns it (toConnectionMeta in
+ *  apps/api/src/connections/store.ts). */
+//# sourceMappingURL=agent.js.map