@cerebro-labs/agentnava-sdk 0.26.0 → 0.46.1

package/README.md

@@ -19,7 +19,7 @@ const agent = await ws.agents.create({
   instructions: 'Decide whether a late delivery qualifies for a refund.',
 });
 
-const conversation = await agent.start();
+const conversation = await agent.start({ endUserId: 'u_ananya' });
 console.log(await conversation.ask('Order 4471 arrived nine days late.'));
 ```
 
@@ -30,30 +30,112 @@ only the things that are easy to get wrong.
 
 ## Connecting an account, end to end
 
-`authorize()` gives you a URL for your user to visit. `waitUntilReady()` tells
-you when they are done, so you do not have to write a polling loop or work out
-which field to believe.
+An **account** is one saved sign-in to one app. A **connection** is an entry in
+an agent's setup that names one, so the agent uses exactly that account and never
+another. `ws.accounts.connect()` gives you a URL for a person to visit, and
+`waitUntilConnected()` tells you when they are done.
 
 ```ts
-const { url } = await conversation.authorize('gmail');
+import { App, Connection } from '@cerebro-labs/agentnava-sdk';
+
+const { account, url } = await ws.accounts.connect({ app: App.GMAIL, nickname: 'Support inbox' });
 showToUser(url);                      // popup, redirect, QR code, your choice
-await conversation.waitUntilReady();  // resolves once nothing required is outstanding
+await account.waitUntilConnected();   // resolves once they have signed in
+await agent.connections.add(Connection.creatorAccount(App.GMAIL, account));
 ```
 
 How you show the URL is yours: this SDK authenticates with an API key, so it
 runs on your server, and the browser half is your application's.
 
-An OPTIONAL requirement does not hold the wait up, for the same reason it does
-not make `ready` false: the conversation genuinely works without it.
+On timeout it throws `account_not_connected` and the message names the account
+and where it stands. It is safe to call again; someone who has not finished
+signing in may just need longer. After `account.reconnect()` it waits for the
+new sign-in too: the account keeps working meanwhile, with `reconnecting` true.
 
-On timeout it throws `conversation_not_ready` and the message names what is
-still missing, e.g. `still waiting on: connection gmail`. It is safe to call
-again; someone who has not finished signing in may just need longer.
+For an app each of YOUR users signs in to themselves, the connection uses the
+end user's account. Each person signs in once, it is remembered for them, and
+nothing is attached per conversation:
 
 ```ts
-await conversation.waitUntilReady({ timeoutMs: 120_000, intervalMs: 2_000, signal });
+await agent.connections.add(Connection.endUserAccount(App.GOOGLE_CALENDAR));
+
+const conversation = await agent.start({ endUserId: user.id });
+for (const { app, url } of await conversation.accountsNeeded()) {
+  showToUser(app, url);               // the ones this person has not connected yet
+}
 ```
 
+An end user's account is an ordinary `Account`: `ws.endUser(id).accounts.connect()`
+returns one, and `waitUntilConnected()`, `ws.account(id)` and every other account
+call work on it the same way. `account.data.owner` says whose it is.
+
+The builders make plain objects, `{ app, account: '<id>' }` and
+`{ app, endUser: true }`, and either object written by hand is accepted too.
+`App.GMAIL` is the string `'gmail'`, so a plain string works anywhere a constant
+does, including for an app added after your SDK version.
+
+## 0.44.0 is a breaking change: apps and accounts
+
+Two words now mean two things. An **account** is one saved sign-in to one app.
+A **connection** is an entry in an agent's setup: a name, an app, and whose
+account it uses, built with `Connection.creatorAccount(app, account)` for the
+agent creator's account or `Connection.endUserAccount(app)` for each end user's
+own. A turn uses exactly the account the setup names. Nothing is attached to a
+conversation any more, and nothing falls back to some other account of the same
+app.
+
+Upgrade together with the production release that serves the new routes:
+0.44 calls `/v1/accounts`, `/v1/end-users/:id/accounts` and the agent connection
+routes, and the connection routes 0.43 calls are removed in that same release.
+There is no compatibility shim: this package is pre-launch, so the old names
+were removed rather than deprecated.
+
+| 0.43 | 0.44 |
+|---|---|
+| `ws.connections.create({ provider })` | `ws.accounts.connect({ app, nickname? })`, returns `{ account, url }` |
+| `ws.connections.create({ provider, agentId })` | `ws.accounts.connect({ app })`, then `agent.connections.add(Connection.creatorAccount(app, account))` |
+| `ws.connections.create({ provider, endUserId })` | `ws.endUser(id).accounts.connect({ app })` |
+| `ws.connections.list()` | `ws.accounts.list({ app? })`, each with `usedBy` |
+| `ws.connections.list({ endUserId })` | `ws.endUser(id).accounts.list()` |
+| `ws.connection(id)` | `ws.account(id)` |
+| `Connection` (class): a signed-in account | `Account` (class). The name `Connection` now builds an entry of an agent's setup |
+| `connection.get()`, returned `ConnectionStatus` | `account.get()`, returns `AccountData`; a missing account throws `account_not_found` |
+| `connection.waitUntilConnected()` | `account.waitUntilConnected()`; times out with `account_not_connected` |
+| `connection.revoke()` | `account.disconnect()`, returns `{ agents }`: the agents that lose it |
+| `connection.provider`, `.connected`, `.owner`, `.endUserId` | `account.app`, `.status`, `.data.owner`, `.data.endUserId` |
+| `connection.url` | the `url` that `connect` returns |
+| none | `account.reconnect()`, `account.rename(nickname)`, `account.check()`, `account.label`, `account.nickname`, `account.usedBy`, `account.data.reconnecting` |
+| `agent.authorize(provider)` | `ws.accounts.connect({ app })`, then `agent.connections.add(Connection.creatorAccount(app, account))` |
+| `agent.attach(connection)` | `agent.connections.add(Connection.creatorAccount(app, account, { name? }))` |
+| none | `agent.connections.add(Connection.endUserAccount(app, { name? }))` |
+| none | `agent.connections.change(name, { account })` or `(name, { endUser: true })` |
+| `agent.disconnect(provider)`, which deleted the shared account | `agent.connections.remove(name)`, which never touches the account |
+| `agent.connections()` | `agent.connections.list()` |
+| `agent.attach(secret)`, which was accepted and did nothing | refused with `not_a_secret`; attach a stored secret to a conversation instead |
+| `agent.start({ attach: connection })` | `agent.start({ endUserId })`: the setup names the accounts |
+| `conversation.authorize(provider)` | `conversation.accountsNeeded()`: the links an end user still has to sign in at |
+| `conversation.attach(connection)` | none: the agent's setup decides |
+| `endUser.connections.create({ provider })` | `endUser.accounts.connect({ app })` |
+| `endUser.connections.list()` | `endUser.accounts.list()` |
+| `endUser.revokeConnections()` | `endUser.accounts.disconnectAll()`, returns `{ disconnected }` |
+| setup `connections: [{ provider, scope: 'fixed', connectionId }]` | `Connection.creatorAccount(app, account, { name? })`, which is `{ name?, app, account: '<id>' }` |
+| setup `connections: [{ provider, scope: 'conversation' }]` | `Connection.endUserAccount(app, { name? })`, which is `{ name?, app, endUser: true }` |
+| type `ConnectionRequirement` | `AgentConnection` (as read back) and `Connection` (as you send it), with `CreatorAccountConnection` and `EndUserAccountConnection` |
+| type `ConnectionStatus`, keyed by `provider` | `ConnectionStatus`, keyed by `name`: `{ name, app, account?, endUser?, status, inDraft, removedInDraft }` |
+| type `CredentialOwner` | removed: `AccountData.owner` is `'workspace'` or `'end-user'` |
+| `Bindings.connections` | removed: `Bindings` carries `secrets` only |
+| none | `App`: every app id as a constant (`App.GMAIL`), and the type `AppId` |
+
+New error codes to branch on: `account_not_found`, `connection_name_taken`,
+`account_app_mismatch`, `connection_not_found` (from
+`agent.connections.change`), `account_not_connected` (from
+`waitUntilConnected`), `account_required` (from `Connection.creatorAccount`
+with no account), and `not_a_secret` (an account handed to `attach`).
+
+Secrets did not move: `agent.attach({ secrets })`, `conversation.attach(secret)`,
+`conversation.attach({ secrets })` and `agent.start({ attach: secret, secrets })`
+work as before.
+
 ## 0.2.0 is a breaking change. Upgrade from 0.1.1, do not stay on it.
 
 "session" is gone from everything you touch. It survives only in our storage,
@@ -77,8 +159,8 @@ moved.
 
 ## Holding an object is free
 
-`ws.agent(id)`, `ws.conversation(id)` and `ws.project(id)` make **no network
-call**. You get something you can call methods on, and the first request happens
+`ws.agent(id)`, `agent.conversation(id)`, `ws.project(id)` and `ws.account(id)`
+make **no network call**. You get something you can call methods on, and the first request happens
 when you call one.
 
 Store the `id`, not the object. A returned object is a handle, not JSON.
@@ -97,16 +179,58 @@ for await (const e of conversation.ask('...')) {      // as it happens
 ```
 
 **The message is sent when you call `ask`**, not when you await or iterate it.
-Calling `ask` twice asks twice.
+Calling `ask` twice generates two submission keys and asks twice. If you need
+to identify an explicit retry after a lost response, save a key before sending:
+
+```ts
+const idempotencyKey = crypto.randomUUID();
+const reply = await conversation.ask('...', { idempotencyKey });
+```
+
+Reuse that key only with the same content in the same conversation. The API
+refuses an already accepted turn with `turn_already_accepted` instead of running
+it again. A new intentional question needs a new key. Errors include the
+original key and instructions for checking status; a `retryable: false` error
+must not be retried as a fresh submission.
 
 You may await the same turn more than once; it is a promise, and you get the same
 answer. You may not iterate it twice, or mix the two, because the events are a
 live stream rather than a stored list and the second consumer would receive
 nothing at all. That throws instead.
 
-**The turn is not your request.** It runs on our side, so a dropped connection
-does not cancel it. Read the answer back with `conversation.messages()` rather
-than asking again.
+**The turn is not your request.** Once the server accepts it, a dropped
+connection, aborting `AskOptions.signal`, or leaving a `for await` loop early
+stops receiving the response. Accepted work can continue and normal billing
+applies; disconnecting does not cancel server work or automatically refund the
+turn. An already-aborted signal passed to `ask()` prevents submission, so no
+turn is accepted or charged for that call.
+
+Use a signal to limit how long your application waits:
+
+```ts
+const controller = new AbortController();
+const timer = setTimeout(() => controller.abort(), 10_000);
+try {
+  const reply = await conversation.ask('Summarize the report.', {
+    signal: controller.signal,
+  });
+  save(reply);
+} catch (error) {
+  if (!controller.signal.aborted) throw error;
+  // We stopped waiting. A turn already accepted by the server can still run.
+} finally {
+  clearTimeout(timer);
+}
+```
+
+After an interruption, read `await conversation.messages()` before another
+`ask()`. The answer may still be in progress, so check history again later
+instead of submitting the same question again.
+
+A successful `await` or `done` event requires the server's completion marker.
+If the stream closes early, the SDK reports a nonretryable interruption even
+when reply text already arrived; use the original submission key to check its
+status before starting more work.
 
 ## Changing an agent publishes a version
 
@@ -150,13 +274,22 @@ await conversation.ask('What are the payment terms?');
 Anywhere under the root works. `input/` is a convention here and nothing
 enforces it, because the agent and your application share one namespace.
 
-## Credentials have two tiers, and they do not substitute
+## Whose account an agent uses
+
+Each connection in an agent's setup names one account, and a turn uses exactly
+that one:
+
+| Built with | Whose | Who signs in |
+|---|---|---|
+| `Connection.creatorAccount(app, account)` | the agent creator's | you or a colleague, once; every conversation uses it |
+| `Connection.endUserAccount(app)` | the end user's | each person, once, remembered for them |
 
-`fixed` is set once on the agent and used by every conversation. `conversation`
-is supplied per conversation, so each user brings their own account.
+There is no fallback. An account that is not signed in leaves its connection
+unavailable, and the agent says so rather than reaching for another account of
+the same app.
 
-An account connected on the agent does **not** satisfy a declaration scoped
-`conversation`, and a conversation cannot supply a `fixed` one. Check
+Secrets still come in two tiers that do not substitute: `fixed` is set once on
+the agent, `conversation` is supplied per conversation. Check
 `conversation.ready` and `conversation.requires` to see what is outstanding.
 
 ## Drafting tools from an API you already describe
@@ -184,6 +317,23 @@ the big one is `description-missing`: none of the three formats contains the
 sentence a model reads to pick a tool, and a bad description does not fail, it
 makes the agent call the wrong thing.
 
+A rule in an OpenAPI document (a minimum, a length, a pattern, a format, a
+`oneOf`) does not cost you the operation. It is written into the parameter's
+description, `Rules: at least 1; at most 100.`, and your API enforces it as it
+does for any caller; its 400 reaches the agent as a failed result it can
+correct. A document that defines one security scheme and never lists it under
+`security` gets that scheme on every operation, with a `security-choice`
+warning; with several schemes, none is applied and the warning says so.
+
+### HTTP tool response limits
+
+Declarative HTTP tools retain at most 64 KiB of response data and stop reading
+when overflow is detected. The limit counts UTF-8 bytes, not characters. Oversized responses
+return `ok: false`, `truncated: true`, and a `response_too_large` error body
+with pagination/filtering guidance; the HTTP status remains the upstream
+status. Partial JSON is never presented as a complete result. Use the API's
+filters and pagination to retrieve a large dataset in bounded pages.
+
 ## Errors
 
 Every failure throws `AgentNavaError`.
@@ -220,6 +370,26 @@ Runs anywhere `fetch` exists: Node, Bun, Deno, Cloudflare Workers, the browser.
 `loadWorkflows` is the one exception; it reads a directory off disk and so needs
 Node or Bun.
 
+## Pointing at a different deployment
+
+The SDK talks to `https://api.agentnava.com` unless you say otherwise. Two ways
+to change it, and the explicit option wins over the environment variable.
+
+```ts
+// a dedicated enterprise endpoint
+const ws = AgentNava.getWorkspace({ apiKey, baseURL: 'https://acme.agentnava.example' });
+```
+
+```bash
+# staging, which is where a test key works
+AGENTNAVA_BASE_URL=https://api-staging.agentnava.com
+```
+
+**A staging key against the production URL fails with `invalid api key`**, which
+reads like a bad key rather than the wrong host. If you were given a test key,
+set the staging URL above. A trailing slash is fine, and a base with a path
+prefix works too, for an API gateway sitting in front of us.
+
 ## Licence
 
 Apache License 2.0. See `LICENSE`, and `NOTICE` for the attribution that
@@ -228,3 +398,22 @@ section 4(d) asks you to carry along.
 Free to use, modify and redistribute, including commercially, with an
 explicit patent grant. Section 6 grants no rights to the names: "AgentNava"
 and "Cerebro Labs" remain trademarks of Cerebro Labs, Inc.
+
+
+### Where an agent is live (0.41)
+
+`agent.get()` and `ws.agents.list()` carry a read-only `status`: where the agent is live, by the rule the API runs it by, and in `needs` any required account or secret not set up yet (it still runs; the tools that use them fail until they are).
+
+### Enterprise HTTP contracts (0.34)
+
+Requires the corresponding API and runtime update. Parameter types include object and array, nested properties/items, per-property required, nullable, integer and additionalProperties. Use choices for primitive enums. Supply native JSON values to paramsJson; an object body is not a JSON-encoded string.
+
+The OpenAPI importer respects operation security, document security, and security:[] (public). When a document defines exactly one supported scheme and no `security` array anywhere names one, that scheme applies to every operation that does not say `security: []`, with a `security-choice` warning; with several schemes, or one the importer cannot set up (OAuth, cookie), none is applied and the warning says the tools send no credential. Bearer, Basic and header/query API keys are supported. It preserves inherited parameters, resolves acyclic local schema references, and URL-encodes path/query values. Omitted optional query/header values and an optional whole body are not sent; missing required values still fail before HTTP. Secrets in query values use secretsEncoded.
+
+The `secretName` override can represent only one credential per operation. The importer checks each security alternative together with the operation's credential header parameters and selects the first compatible alternative. If none can use a single credential, the importer skips the operation with a warning instead of reusing the same secret for independent credentials. Omit the override to generate independent secret names, or configure the operation explicitly.
+
+Review import warnings. Schema rules never skip an operation: bounds, lengths, patterns, string formats and item or field counts are written into the parameter's description, and the API being called enforces them. `oneOf`/`anyOf` become one parameter that admits every alternative, with the alternatives described (`One of: Card (with type, token); BankTransfer (with type, iban).`); "X or null" becomes a nullable X, and a map (`additionalProperties` holding a schema) stays open to any key. When the alternatives cannot share one shape (a list or an object), the first is kept and an `unsupported-body` warning names the field. `allOf` members merge, including a rule-only member beside a type. Choosing among security alternatives produces a warning. What still skips an operation, with an `unsupported-operation` warning: a contradictory `allOf`, tuple arrays (`prefixItems`), recursive or external references, a schema with no type, structured query serialization, cookie authentication and OAuth acquisition/refresh. Schemas cannot declare a property named `__proto__`, which the Workers schema adapter cannot preserve.
+
+Keywords beside a schema `$ref` apply together with the referenced schema, as OpenAPI 3.1 defines, at every step of a reference chain: a description replaces the referenced one, a rule is described, an enum narrows the choices. Response-only properties marked `readOnly: true` are still omitted before importing their request schemas.
+
+All three execution paths share one HTTP executor. Results include lower-cased Link, Retry-After, request ID, ETag, Last-Modified, Content-Type and rate-limit headers. Credential-bearing headers are excluded and known secret values in metadata are redacted. HTTP errors and oversized responses have ok:false at the outer tool envelope too. The response byte limit remains 64 KiB: filter or paginate larger records.

package/account.d.ts

@@ -0,0 +1,154 @@
+import type { Http } from './http.ts';
+import type { AccountData, AccountStatus, UsedBy } from './types.ts';
+/**
+ * One saved sign-in to one app, that you hold and act on.
+ *
+ * AN ACCOUNT IS NOT A CONNECTION, and the two words used to be one, which is
+ * how an agent came to own a Gmail login that nothing else could see. An
+ * ACCOUNT is a sign-in: Gmail, signed in as support@example.com. A CONNECTION is
+ * an entry in an agent's setup that names one: "this agent uses Gmail, through
+ * that account". Many agents can name one account, and reconnecting it once
+ * fixes all of them.
+ *
+ * ```ts
+ * const { account, url } = await ws.accounts.connect({ app: App.GMAIL, nickname: 'Support inbox' });
+ * showToUser(url);                        // they sign in on Google's own page
+ * await account.waitUntilConnected();
+ * await agent.connections.add(Connection.creatorAccount(App.GMAIL, account));
+ * ```
+ *
+ * Nobody handles a token, you included: the person signs in on the app's own
+ * page, and this object says who they signed in as, never how.
+ *
+ * ONE KIND OF OBJECT FOR BOTH OWNERS. The agent creator's account and one of
+ * your end users' are the same class, reached by the same routes: every method
+ * here works on any account in the workspace, and `data.owner` says whose it
+ * is. So `ws.account(id).waitUntilConnected()` is how you wait for an end user
+ * to finish signing in, too.
+ *
+ * A CLASS, like `Database` and `Secret`: you hold it and act on it, rather than
+ * threading an id through calls. Holding one makes no request. `ws.account(id)`
+ * is free and the first call on it is the first round trip.
+ */
+export declare class Account {
+    #private;
+    readonly id: string;
+    private snapshot?;
+    constructor(http: Http, id: string, snapshot?: AccountData);
+    private get base();
+    /** The app's catalog id: `'gmail'`, `'hubspot'`. Named for what the person
+     *  signing in recognises, never for whoever we buy the sign-in from. */
+    get app(): string | undefined;
+    /** Who it is signed in as: the email or username the app reports. Null until
+     *  somebody has finished signing in. */
+    get label(): string | null | undefined;
+    /** Your own name for it, such as `'Support inbox'`. */
+    get nickname(): string | null | undefined;
+    /** Where the sign-in stands, from the last read: `'pending'`, `'connected'`,
+     *  `'needs_sign_in'` or `'error'`.
+     *
+     *  Reads the snapshot rather than the network. Undefined means this handle
+     *  has not read yet, NOT that the account is disconnected: call `get()`. */
+    get status(): AccountStatus | undefined;
+    /** The agents whose setup names this account, from the last read. The
+     *  question to ask before disconnecting it: who loses it? */
+    get usedBy(): UsedBy[] | undefined;
+    /** The last-known record, from whatever call produced this object. */
+    get data(): AccountData | undefined;
+    /**
+     * An account goes over the wire as its id, the way a `Date` goes as its ISO
+     * string: `JSON.stringify({ account })` sends `"acc_..."`.
+     *
+     * That is what lets a connection written as a plain object,
+     * `{ app, account }`, take the Account you are holding in
+     * `ws.agents.create()` and `agent.update()`. It also matches the rule for
+     * every handle in this SDK: store the id, not the object.
+     */
+    toJSON(): string;
+    /**
+     * Read it back.
+     *
+     * A MISSING ACCOUNT THROWS (`account_not_found`, 404), and never comes back
+     * as an empty record. An account that does not exist and one that is not
+     * signed in yet are different answers. The connection this replaced once
+     * answered a miss with a made-up blank, so storing an id and reading it back
+     * gave you something that did not know what it was.
+     */
+    get(): Promise<AccountData>;
+    /**
+     * Wait until the person has finished signing in.
+     *
+     * The companion to `ws.accounts.connect()`, `ws.endUser(id).accounts
+     * .connect()` and `reconnect()`. Those hand you a url; this tells you when
+     * the person is done, so you do not write a polling loop or guess which
+     * field to believe.
+     *
+     * DONE MEANS CONNECTED AND NOT RECONNECTING. During a reconnect the account
+     * keeps working (`status` stays `'connected'`) while `reconnecting` is true,
+     * so a check on `status` alone would return before the person had signed in
+     * again. This waits for both.
+     *
+     * THROWS on the deadline (`account_not_connected`), naming the account and
+     * where it stands, rather than returning an account that is still pending.
+     * Safe to call again: somebody who has not finished may just need longer.
+     *
+     * Polls rather than subscribing: there is a person in the middle, so a few
+     * seconds costs nothing, and it works from any runtime without a socket.
+     */
+    waitUntilConnected(options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<Account>;
+    /**
+     * Send the person to sign in again, and get the link.
+     *
+     * What to call when an account `needs_sign_in`. Every agent that names it
+     * follows, so reconnecting once fixes all of them. The sign-in that worked is
+     * kept until the new one succeeds, so an abandoned link breaks nothing:
+     * meanwhile `data.reconnecting` is true, and `waitUntilConnected()` waits
+     * for it to clear.
+     *
+     * If the person signs in as SOMEBODY ELSE, that becomes a NEW account and
+     * this one is left as it was, so no agent switches mailbox without anyone
+     * deciding it should. List accounts to find the new one, then change the
+     * connections that should use it.
+     */
+    reconnect(): Promise<{
+        url: string;
+    }>;
+    /** Give it your own name, such as `'Support inbox'`, shown beside who it is
+     *  signed in as. The app and the sign-in do not change. */
+    rename(nickname: string): Promise<Account>;
+    /** Ask the app whether the sign-in still works, and read the answer. A
+     *  revoked sign-in comes back as `needs_sign_in`, not as an exception: it is
+     *  the answer this call exists to get. */
+    check(): Promise<AccountData>;
+    /**
+     * Sign it out at the app and remove it here.
+     *
+     * ALWAYS ALLOWED, unlike deleting a database that an agent still names. It
+     * returns the agents whose setup names the account, so you can tell whoever
+     * owns them: from their next turn those connections report that the account
+     * was disconnected. Nothing switches to another account in its place.
+     *
+     * Removing a connection from an agent is the other thing, and it never
+     * touches the account: `agent.connections.remove(name)`.
+     */
+    disconnect(): Promise<{
+        agents: UsedBy[];
+    }>;
+}
+/**
+ * The account a response carries, or a thrown error. Never a blank.
+ *
+ * A 404 already throws in the transport, with the API's `account_not_found`.
+ * This covers the other way to end up with nothing: a 200 whose body has no
+ * account in it, which would otherwise become a snapshot of `undefined` that
+ * reads, at every call site, exactly like an account nobody has read yet.
+ */
+export declare function accountIn(res: {
+    account?: AccountData;
+} | undefined, path: string): AccountData;
+/** The id a connection sends for its account: an `Account` by its id, an id
+ *  as it is. */
+export declare function accountIdOf(account: Account | string): string;