@cerebro-labs/agentnava-sdk 0.44.1 → 0.46.1

package/types.d.ts

@@ -57,7 +57,56 @@ export type Trigger = {
      * replaces the URL.
      */
     url?: string;
+    /**
+     * Check WHO sent each delivery, beyond knowing the URL. See
+     * WebhookVerify for the schemes and an example. Leave it out to keep
+     * what the webhook has. The secret is stored encrypted and never read
+     * back: a read says `secretSet: true` instead.
+     */
+    verify?: WebhookVerify;
 } & TriggerTarget);
+/**
+ * How a webhook checks its sender. Platforms that send webhooks sign every
+ * delivery with a secret they show you when you add the URL there; give it
+ * here, and a delivery whose signature does not match is refused (401) and
+ * never runs the agent.
+ *
+ * ```ts
+ * { kind: 'webhook', verify: { kind: 'stripe', secret: 'whsec_...' } }
+ * { kind: 'webhook', verify: { kind: 'header', header: 'X-Webhook-Secret', secret: '...' } }
+ * ```
+ *
+ * The schemes: `stripe`, `github`, `shopify`, `slack` and
+ * `standard` (the Standard Webhooks spec) check that platform's signature;
+ * `header` checks a header your sender adds (Zapier, Make, n8n, your own code
+ * can all add one); `none` relies on the URL alone.
+ */
+export type WebhookVerify = {
+    kind: 'none';
+} | {
+    kind: 'stripe' | 'github' | 'shopify' | 'slack' | 'standard';
+    secret?: string;
+    secretSet?: boolean;
+} | {
+    kind: 'header';
+    header: string;
+    secret?: string;
+    secretSet?: boolean;
+};
+/** One delivery a webhook received, newest first from `agent.webhookDeliveries()`. */
+export interface WebhookDelivery {
+    id: string;
+    receivedAt: string;
+    /** `pending`: checked and starting. `repeat`: the sender retried a delivery
+     *  already accepted; the agent did not run again. */
+    outcome: 'pending' | 'accepted' | 'refused' | 'repeat' | 'test';
+    /** Why it was refused. */
+    reason?: string;
+    /** The sender's own id for it, when it gave one. */
+    deliveryId?: string;
+    /** The conversation it ran in. */
+    conversationId?: string;
+}
 /**
  * WHERE a schedule or webhook runs. Name a conversation, or an end user, or
  * neither; never both.
@@ -712,8 +761,12 @@ export interface SecretMeta {
 }
 /** A SQL engine AgentNava can query. */
 export type DatabaseEngine = 'postgres' | 'mysql' | 'sqlserver';
-/** How the connection to a database is encrypted. `require` is the default. */
-export type DatabaseTls = 'disable' | 'require' | 'verify-full';
+/** How the connection to a database is encrypted. `verify` (the default)
+ *  encrypts and always checks the server's certificate: against public and
+ *  cloud CAs and the host name, or, for a database with its own home-made CA,
+ *  against the CA AgentNava trusted the first time it connected. `disable` is
+ *  for a server with no SSL at all. */
+export type DatabaseTls = 'verify' | 'disable';
 /**
  * How to log in to a database: a connection string, OR the same login as
  * separate fields. Never both; a request with both is refused.

package/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D","sourcesContent":["// The shapes this SDK hands back. Transcribed from design/sdk-design.md's own\n// Types section so the reference and the code cannot drift.\n\n// Type-only: erased from the emitted JavaScript, so these add no runtime cycle\n// with the modules that import their own shapes from here.\nimport type { AppId } from './apps.generated.ts';\nimport type { Connection } from './connection.ts';\n\n/** The quality of model an agent's turns run on, and what each turn costs.\n *\n *  `fast` is the one that surprises people: it buys LATENCY rather than\n *  capability, runs a smaller model on silicon built for time-to-first-token,\n *  and costs MORE than `premium` while being less capable. Pick it for voice\n *  and interactive agents, not to save money. `best` is the strongest model. */\nexport type Grade = 'standard' | 'premium' | 'fast' | 'best';\nexport type Filesystem = 'drive' | 'none';\n\n/** Where a SECRET is supplied.\n *\n *  'fixed' is set once on the agent and used by every conversation. 'conversation'\n *  is asked for when a conversation starts, so each user brings their own. The\n *  two DO NOT substitute for each other: a value set on the agent does not\n *  satisfy a declaration scoped 'conversation'.\n *\n *  Connections stopped using this in 0.44. A connection says WHOSE ACCOUNT it\n *  uses instead: the agent creator's (`account`) or each end user's own\n *  (`endUser: true`). See `AgentConnection`. */\nexport type Scope = 'fixed' | 'conversation';\n\nexport interface WorkspaceInfo {\n\tid: string;\n\tname: string;\n\tcredits: number;\n\tcreatedAt: string;\n}\n\n/** One procedure the agent follows when its `when` matches what is in front of\n *  it. `when` is one line and is not optional: it is what the agent reads to\n *  decide the workflow applies, so a vague one makes a good workflow invisible. */\nexport interface Workflow {\n\tname: string;\n\twhen: string;\n\tcontent: string;\n}\n\n// `SessionMode` is deliberately NOT exposed.\n//\n// The API has one ('per-user' | 'per-call') and 'per-user' makes the server\n// resume a person's most recent conversation. That is the behaviour `start`\n// refuses to have: a verb that sometimes returns something you already had, and\n// which has to guess which one the moment a person has two.\n//\n// Its other effect, fanning a scheduled firing out across the people who have\n// conversations with an agent, is real and worth exposing one day. It should\n// arrive under a name that says THAT, not under a mode that also silently\n// changes what `start` returns.\n\nexport type Trigger =\n\t| { kind: 'chat' }\n\t| ({ kind: 'schedule'; enabled?: boolean; cron: string; timezone?: string; message: string } & TriggerTarget)\n\t| { kind: 'interval'; seconds: number; maxRuns?: number; message: string }\n\t| ({\n\t\t\tkind: 'webhook';\n\t\t\tmessage?: string;\n\t\t\t/**\n\t\t\t * Where your system POSTs, set by the platform. Read it from the agent\n\t\t\t * that `setTriggers()` returns: `agent.data?.triggers`. Anything you\n\t\t\t * send here is ignored, so passing back a list you read is safe and\n\t\t\t * keeps the same URL. One webhook per agent; `rotateWebhookUrl()`\n\t\t\t * replaces the URL.\n\t\t\t */\n\t\t\turl?: string;\n\t  } & TriggerTarget);\n\n/**\n * WHERE a schedule or webhook runs. Name a conversation, or an end user, or\n * neither; never both.\n *\n * ```ts\n * const conversation = await agent.start({ endUserId: 'ops-app' });\n * await agent.setTriggers([\n *   { kind: 'chat' },\n *   // Every firing lands in THIS conversation: its history, its drive.\n *   { kind: 'schedule', cron: '0 15 * * *', message: 'REFRESH', conversationId: conversation.id },\n * ]);\n * ```\n */\nexport type TriggerTarget =\n\t| {\n\t\t\t/**\n\t\t\t * The conversation every firing CONTINUES: it sees that conversation's\n\t\t\t * history and its drive, and its end user comes with it. Each firing\n\t\t\t * also moves the conversation to the agent's latest version, so a fix\n\t\t\t * you publish reaches it.\n\t\t\t *\n\t\t\t * This is the ONLY way a trigger continues one of your conversations.\n\t\t\t * One end user can have many, so naming the end user cannot say which.\n\t\t\t *\n\t\t\t * Must be a conversation of this agent, started for one of your end\n\t\t\t * users (the id `agent.start()` returned). Anything else is refused\n\t\t\t * when you set the trigger. If the conversation is deleted later, the\n\t\t\t * firings fail and say so; none is opened in its place.\n\t\t\t */\n\t\t\tconversationId: string;\n\t\t\tuserId?: undefined;\n\t  }\n\t| {\n\t\t\tconversationId?: undefined;\n\t\t\t/**\n\t\t\t * The end user each firing is for, when it names no conversation. Each\n\t\t\t * firing STARTS A NEW CONVERSATION for them, with an empty drive, and it\n\t\t\t * is listed by `agent.conversations({ endUser })`. To keep adding to\n\t\t\t * one conversation instead, name it with `conversationId`.\n\t\t\t *\n\t\t\t * Your id, as in `agent.start({ endUserId })`; the platform's prefixes\n\t\t\t * (`member:`, `visitor:`, `job:`) are refused.\n\t\t\t *\n\t\t\t * Name neither and the trigger keeps one conversation of its own that\n\t\t\t * every firing continues.\n\t\t\t */\n\t\t\tuserId?: string;\n\t  };\n\n/**\n * One connection in an agent's setup, as it reads back: a NAME, an APP, and\n * WHOSE ACCOUNT. Exactly one of these two:\n *\n * | the connection says | whose account | the person signs in |\n * |---|---|---|\n * | `account: '<id>'` | the agent creator's: one account in this workspace, from `ws.accounts.connect()` | once, and every conversation uses it |\n * | `endUser: true` | the end user's: each person talking to the agent | once each, remembered for them |\n *\n * A turn uses EXACTLY the account the setup names, and never another one.\n * There is no fallback to some other account of the same app: an account that\n * is not signed in leaves the connection unavailable, and the agent says so.\n *\n * `name` tells two connections of one app apart, such as `work-gmail` and\n * `personal-gmail`. 1 to 64 characters, lowercase letters, digits and dashes,\n * no dash at either end, unique on the agent. Left out when sent, it is the\n * app's id.\n *\n * Part of the agent's CONFIGURATION, so changing a connection publishes a\n * version. The account itself is not versioned: signing in again reaches every\n * agent that names it. To send one, build it with `Connection.creatorAccount()`\n * or `Connection.endUserAccount()`.\n */\nexport type AgentConnection =\n\t| {\n\t\t\tname: string;\n\t\t\t/** The app's id: `App.GMAIL` is `'gmail'`. */\n\t\t\tapp: AppId;\n\t\t\t/** An account id in this workspace whose app is `app`. */\n\t\t\taccount: string;\n\t\t\tendUser?: never;\n\t  }\n\t| {\n\t\t\tname: string;\n\t\t\tapp: AppId;\n\t\t\tendUser: true;\n\t\t\taccount?: never;\n\t  };\n\n/** What an agent NEEDS, not the stored value. `Secret` is the value. */\nexport interface SecretRequirement {\n\tname: string;\n\tscope: Scope;\n\trequired?: boolean;\n}\n\nexport interface Parameter {\n\tname: string;\n\ttype: 'string' | 'number' | 'date' | 'choice';\n\trequired?: boolean;\n\tdefault?: string;\n\tchoices?: string[];\n}\n\nexport interface McpServer {\n\tname: string;\n\turl: string;\n\ttransport?: 'http' | 'sse';\n\theaders?: Record<string, string>;\n\ttimeoutMs?: number;\n}\n\nexport interface HttpToolParam {\n\ttype: 'string' | 'number' | 'boolean' | 'object' | 'array';\n\tdescription?: string;\n\trequired?: boolean;\n\tchoices?: (string | number | boolean | null)[];\n\tnullable?: boolean;\n\tinteger?: boolean;\n\tproperties?: Record<string, HttpToolParam>;\n\titems?: HttpToolParam;\n\tadditionalProperties?: boolean;\n}\n\nexport interface HttpTool {\n\tname: string;\n\tdescription: string;\n\tmethod: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';\n\turl: string;\n\theaders?: Record<string, string>;\n\tbody?: string;\n\tparams?: Record<string, HttpToolParam>;\n\tsecrets?: string[];\n\ttimeoutMs?: number;\n}\n\nexport interface AgentData {\n\tid: string;\n\tname: string;\n\tinstructions: string;\n\tgreeting?: string;\n\tgrade: Grade;\n\tfilesystem: Filesystem;\n\ttools: string[];\n\tworkflows: Workflow[];\n\t/** The apps it uses, each saying whose account. See `AgentConnection`. */\n\tconnections: AgentConnection[];\n\tsecrets: SecretRequirement[];\n\tparameters: Parameter[];\n\ttriggers: Trigger[];\n\tmcpServers: McpServer[];\n\thttpTools: HttpTool[];\n\t/** Workspace knowledge bases this agent reads, by key. Always present, empty\n\t *  when none are attached, so a caller never has to distinguish \"none\" from\n\t *  \"an older server that did not send the field\". */\n\tknowledgeBases: string[];\n\t/** Workspace databases this agent may query, by key. Always present, like\n\t *  `knowledgeBases`. */\n\tdatabases: string[];\n\tversion: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n\t/** Where it is live, as the portal shows it. The API works it out by the\n\t *  same rule it runs the agent by, so `channels.api === 'on'` is exactly\n\t *  \"a turn will be taken\". Read-only: nothing sets it. Sent by `agent.get()`\n\t *  and `ws.agents.list()`; absent from what create and update return, so\n\t *  call `get()` for it. */\n\treadonly status?: AgentStatus;\n}\n\n/** What `agent.websiteChat.turnOn()` gives back: what to put on a website. */\nexport interface WebsiteChat {\n\t/** The hosted chat page. Share it, or open it in an iframe. */\n\treadonly chatUrl: string;\n\t/** The publishable token for the embed script. Safe in a public web page:\n\t *  it can only talk to this one agent. Your API key never goes there. */\n\treadonly publicToken: string;\n\t/** The id the embed script's `data-agent-id` takes. */\n\treadonly embedAgentId: string;\n\t/** The version the website chat serves from now on. */\n\treadonly versionNumber: number;\n}\n\n/** Where an agent is live. See `AgentData.status`. */\nexport interface AgentStatus {\n\t/** True when any channel is on. */\n\treadonly live: boolean;\n\t/** Paused by its owner: nothing runs it until it is resumed. */\n\treadonly paused: boolean;\n\t/** Archived: nothing runs it again. */\n\treadonly archived: boolean;\n\treadonly channels: {\n\t\t/** 'on' when the API takes new turns for it. */\n\t\treadonly api: 'on' | 'off';\n\t\t/** 'on' when its website chat page answers visitors. 'unavailable' when it\n\t\t *  needs what each user brings (`eachUserBrings`), which a visitor cannot. */\n\t\treadonly websiteChat: 'on' | 'off' | 'unavailable';\n\t};\n\t/** Required accounts and secrets of its own that are not set up yet, on the\n\t *  version a new conversation runs. It still runs: the tools that use them\n\t *  fail until they are set up. Empty when nothing is missing. */\n\treadonly needs: readonly { kind: 'connection' | 'secret'; name: string }[];\n\t/** The accounts and secrets each user supplies for themselves. */\n\treadonly eachUserBrings: readonly { kind: 'connection' | 'secret'; name: string }[];\n}\n\n/**\n * One of an agent's connections as it stands right now: the account it names,\n * and whether that account works. What `agent.connections.list()` returns.\n *\n * DECLARED IS NOT CONNECTED, and this is the read that tells them apart. A\n * connection can name an account nobody has finished signing in to, or one that\n * was disconnected since; that is the state a setup checklist has to show, and\n * without this the only way to find it is to start a conversation and watch\n * the agent fail.\n *\n * Reshaped in 0.44: it used to be keyed by `provider`, with `declared`,\n * `required`, `scope` and `suppliedBy`. A connection is now keyed by its\n * `name`, and it says whose account it uses instead of where one might come\n * from.\n */\nexport interface ConnectionStatus {\n\tname: string;\n\tapp: AppId;\n\t/** The agent creator's account the connection names, read fresh. Absent on\n\t *  an end user's connection, and on one whose account is gone. */\n\taccount?: AccountData;\n\t/** True when each person talking to the agent signs in with their own. */\n\tendUser?: true;\n\t/** Whether the connection works now, as the API reports it. For an agent\n\t *  creator's account it follows that account's status. */\n\tstatus: string;\n\t/** Only in the agent's unpublished draft, so no conversation uses it yet. */\n\tinDraft: boolean;\n\t/** Removed in the agent's unpublished draft, and still used until the draft\n\t *  is published. */\n\tremovedInDraft: boolean;\n}\n\n/** Where one account's sign-in stands.\n *\n *   'pending'        made, and nobody has finished signing in yet\n *   'connected'      signed in and working\n *   'needs_sign_in'  it worked, and the app now wants the person to sign in again\n *   'error'          the app refused it for another reason\n */\nexport type AccountStatus = 'pending' | 'connected' | 'needs_sign_in' | 'error';\n\n/** An agent whose setup names an account, and the connection that names it.\n *  Counted from the agent's latest published version and its draft, never\n *  from older versions. */\nexport interface UsedBy {\n\t/** The agent's id: the same value as `Agent.id`, so compare this one. */\n\tid: string;\n\t/** AgentNava's internal handle for the same agent (`agt_...`), not `Agent.id`. */\n\tagentId: string;\n\tagentName: string;\n\tconnectionName: string;\n\t/** Named in the agent's unpublished draft. */\n\tinDraft: boolean;\n\t/** Named in the agent's latest published version. */\n\tpublished: boolean;\n}\n\n/**\n * One saved sign-in to one app.\n *\n * TWO OWNERS, and the difference is who signs in:\n *\n * | `owner` | whose | a connection uses it as |\n * |---|---|---|\n * | `'workspace'` | the agent creator's, signed in once, usable by any agent | `Connection.creatorAccount(app, account)` |\n * | `'end-user'` | one of YOUR end users', remembered for that person | `Connection.endUserAccount(app)`, in that person's conversations |\n *\n * Both owners are read and changed through the same routes and the same\n * `Account` handle; `owner` says which this is.\n *\n * Nobody handles a token: the person signs in on the app's own page, and this\n * record says who they signed in as, never how.\n */\nexport interface AccountData {\n\tid: string;\n\t/** The app's id: `App.GMAIL` is `'gmail'`. */\n\tapp: AppId;\n\t/** Who it is signed in as: the email or username the app reports. Null until\n\t *  somebody has finished signing in. */\n\tlabel: string | null;\n\t/** Your own name for it, such as `'Support inbox'`. Null when none was given. */\n\tnickname: string | null;\n\tstatus: AccountStatus;\n\t/** True while a reconnect waits for the person to sign in again. The\n\t *  account keeps working meanwhile, so `status` can still say\n\t *  `'connected'`; `waitUntilConnected()` waits for this to clear. */\n\treconnecting: boolean;\n\towner: 'workspace' | 'end-user';\n\t/** The end user it belongs to, when `owner` is `'end-user'`. An id from YOUR\n\t *  database, never a workspace member's. */\n\tendUserId?: string;\n\tconnectedAt: string | null;\n\tlastCheckedAt: string | null;\n\t/** The agents whose setup names this account. Empty for an end user's\n\t *  account, which a setup never names by id. */\n\tusedBy: UsedBy[];\n}\n\n/** An end user's account a conversation still needs, with the link that\n *  person signs in at. From `conversation.accountsNeeded()`. */\nexport interface AccountNeeded {\n\t/** The connection's name on the agent. */\n\tname: string;\n\tapp: AppId;\n\t/** Send the person here. They sign in once, and every later conversation\n\t *  of theirs has it. */\n\turl: string;\n}\n\n/** Something a conversation is still missing before it can work. */\nexport interface Requirement {\n\tkind: 'secret' | 'connection';\n\tname: string;\n\trequired: boolean;\n}\n\nexport interface AgentConversationData {\n\tid: string;\n\tagentId: string;\n\t/** The number of the agent version this conversation runs, as `agent.version`\n\t *  numbers them. Fixed at start, except that a schedule or webhook naming the\n\t *  conversation moves it to the latest version at each firing. */\n\tversion: number;\n\tstartedAt: string;\n\ttitle?: string;\n\t/** True when nothing REQUIRED is outstanding. An optional gap leaves this\n\t *  true, because the conversation genuinely does work without it. */\n\tready: boolean;\n\trequires: Requirement[];\n}\n\nexport interface ProjectConversationData {\n\tid: string;\n\tprojectId: string;\n\tstartedAt: string;\n\ttitle?: string;\n\tready: boolean;\n\trequires: Requirement[];\n}\n\n/** An AGENT on a project, not a person.\n *\n *  Called `ProjectAgent` and not `Member`, which is what it was. `Member` is\n *  the word this product uses for a HUMAN on the account, so a public type of\n *  that name holding an `agentId` was the same trap as `userId` meaning two\n *  populations: `import { Member }` handed you the agent one, and the human one\n *  had to carry a prefix to get out of its way.\n *\n *  The people are `WorkspaceMember`, from `ws.members()`. Nothing here is a\n *  person. */\nexport interface ProjectAgent {\n\tagentId: string;\n\tname: string;\n\taddedAt: string;\n}\n\nexport interface ProjectData {\n\tid: string;\n\tname: string;\n\tgoal: string | null;\n\tmanagerInstructions: string | null;\n\tgrade: Grade;\n\tstatus: 'active' | 'archived';\n\tagents: ProjectAgent[];\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\nexport interface Step {\n\tid: string;\n\tlabel: string;\n\tkind: 'read' | 'write' | 'edit' | 'search' | 'shell' | 'web' | 'data' | 'task' | 'plan' | 'other';\n\tstatus: 'active' | 'done' | 'error';\n}\n\nexport type TurnEvent =\n\t| { type: 'start'; turnId: string }\n\t/** Carries the WHOLE step list every time, not a change to it. Replace what\n\t *  you are showing rather than merging; that is what makes reconnecting\n\t *  safe. */\n\t| { type: 'progress'; steps: Step[] }\n\t| { type: 'tool'; name: string; state: 'start' | 'end'; ok?: boolean }\n\t/** A fragment, not a line. Append; do not assemble. */\n\t| { type: 'text'; text: string }\n\t| { type: 'file'; path: string }\n\t| { type: 'done'; reply: string }\n\t| { type: 'error'; message: string; retryable: boolean };\n\nexport interface Message {\n\trole: 'user' | 'assistant';\n\tcontent: string;\n\tat: string;\n}\n\n/** An image goes to the model as an image. Anything else is written into the\n *  conversation's drive before the turn starts, so the agent can parse it,\n *  compute over it, and still have it next turn. */\nexport interface Attachment {\n\tkind: 'image' | 'file';\n\tname?: string;\n\tmimeType: string;\n\t/** base64, without a data: prefix. */\n\tdata: string;\n}\n\n/** A knowledge base: a named folder of files at WORKSPACE scope that an agent\n *  configuration attaches by key. */\nexport interface KnowledgeBaseData {\n\t/** Workspace-unique. This is what an agent configuration stores, and it is\n\t *  not editable, because renaming it would move every attachment silently. */\n\tkey: string;\n\tname: string;\n\tdescription?: string;\n\t/** Counted when read, so it never disagrees with the files it counts. */\n\tfileCount: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\n/** One file in a knowledge base. PATH, not a flat name: a base is a folder, and\n *  the session mount reproduces the shape verbatim. */\n/**\n * Whether an agent can read a file in a knowledge base.\n *\n * Text and markdown are readable as they stand. A PDF, a scan or a spreadsheet\n * has to be turned into text first, which happens when the file is uploaded\n * rather than when a question is asked, so an agent never waits on it.\n *\n *   'readable'    an agent can read this now\n *   'processing'  being prepared, check back shortly\n *   'unreadable'  cannot be read, and `reason` says why\n */\nexport type KnowledgeFileStatus = 'readable' | 'processing' | 'unreadable';\n\nexport interface KnowledgeFileEntry {\n\tpath: string;\n\tmimeType: string;\n\tsize: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n\t/** Whether an agent can read this file. */\n\tstatus: KnowledgeFileStatus;\n\t/** Why it cannot be read, as a sentence you could show someone.\n\t *\n\t *  The same text reaches the agent in place of the file, so a developer\n\t *  reading this and a model reading the base get one explanation rather than\n\t *  two that can drift apart. Absent unless `status` is 'unreadable'. */\n\treason?: string;\n}\n\nexport interface FileEntry {\n\tpath: string;\n\tkind: 'file' | 'directory';\n\tmimeType: string;\n\tsize: number;\n\tmodifiedAt: string;\n}\n\n/** Fields accepted when creating or updating an agent. Everything is optional on\n *  an update: what you do not send is inherited from the current version, which\n *  is the whole reason updating is safe. */\nexport interface AgentFields {\n\tid?: string;\n\tname?: string;\n\tinstructions?: string;\n\tgreeting?: string;\n\tgrade?: Grade;\n\tfilesystem?: Filesystem;\n\t/**\n\t * Knowledge bases this agent reads, by workspace-unique key.\n\t *\n\t * Mounted READ-ONLY at `/knowledge/<key>/` when a session starts, so the\n\t * agent finds things with `ls`, `grep` and `cat` rather than a retrieval API.\n\t *\n\t * Which bases an agent reads is part of its CONFIGURATION, so changing this\n\t * publishes a version you can diff and roll back. The CONTENTS of a base are\n\t * not versioned: correcting a file changes what every attached agent sees on\n\t * its next turn, which is the same by-reference promise `agent.knowledge`\n\t * already makes.\n\t *\n\t * A key that names no base is refused when the configuration is saved, and\n\t * deleting a base is refused while any agent attaches it, so an attachment\n\t * that was valid stays valid.\n\t */\n\tknowledgeBases?: string[];\n\t/**\n\t * Workspace databases this agent may query, by key.\n\t *\n\t * Register the database first with `ws.databases.create()`, which logs in\n\t * and gives it the key; then name the key here. Naming it is the grant: a\n\t * database answers only the agents whose configuration names it, and the\n\t * agent's prompt lists them so it knows what to query.\n\t *\n\t * Part of the CONFIGURATION, so changing it publishes a version. A key that\n\t * names no database is refused when the configuration is saved, and\n\t * removing a database is refused while any agent names it.\n\t */\n\tdatabases?: string[];\n\ttools?: string[];\n\tworkflows?: Workflow[];\n\t/**\n\t * The apps this agent uses, each a NAMED connection that says whose account\n\t * it uses: the agent creator's account, or each end user's own. See\n\t * `Connection` and `AgentConnection`.\n\t *\n\t * ```ts\n\t * connections: [\n\t *   Connection.creatorAccount(App.GMAIL, work, { name: 'work-gmail' }),\n\t *   Connection.creatorAccount(App.GMAIL, personal, { name: 'personal-gmail' }),\n\t *   Connection.endUserAccount(App.GOOGLE_CALENDAR),\n\t * ]\n\t * ```\n\t *\n\t * The builders make plain objects, `{ app, account: '<id>' }` and\n\t * `{ app, endUser: true }`, and those objects are accepted as they are.\n\t * `App.GMAIL` is the string `'gmail'`, so a plain app id works too.\n\t *\n\t * Part of the CONFIGURATION, like `databases`, so changing it publishes a\n\t * version. An unknown account id, an account of a different app, a repeated\n\t * name or a name of the wrong shape is refused when the configuration is\n\t * saved, naming the problem.\n\t */\n\tconnections?: Connection[];\n\tsecrets?: SecretRequirement[];\n\tparameters?: Parameter[];\n\ttriggers?: Trigger[];\n\tmcpServers?: McpServer[];\n\thttpTools?: HttpTool[];\n}\n\nexport interface ProjectFields {\n\tname?: string;\n\tgoal?: string;\n\tmanagerInstructions?: string;\n\tgrade?: Grade;\n\tagents?: string[];\n}\n\n/** Secret VALUES supplied to an agent (`agent.attach`) or to one conversation\n *  (`conversation.attach`): the secrets its agent declared.\n *\n *  Accounts are no longer supplied this way (0.44). An agent's setup names the\n *  account each connection uses, so there is nothing left to attach. */\nexport interface Bindings {\n\tsecrets?: Record<string, string>;\n}\n\n/** One markdown file read off disk: a workflow or a subagent.\n *\n *  `when` is OPTIONAL here and required at publish. A file on disk has no `when`\n *  until someone writes one, and refusing to read it would be the wrong place to\n *  say so; the API says it at publish, with a message naming the file. */\nexport interface SpecFile {\n\tname: string;\n\tcontent: string;\n\twhen?: string;\n}\n\n/** What a loaded agent directory produces: the fields `ws.agents.create()` takes,\n *  plus the id the caller chose and the few legacy names the loader still reads\n *  off an existing directory. */\nexport interface SpecInput extends Omit<AgentFields, 'workflows'> {\n\tkey: string;\n\tworkflows?: SpecFile[];\n\tsubagents?: SpecFile[];\n\twidgets?: { name: string; [k: string]: unknown }[];\n\tsandbox?: Filesystem;\n\trole?: string;\n\t/** Retired in favour of `tools: ['web_search']`, still read off an existing\n\t *  agent directory so one written before the rename still loads. */\n\twebSearch?: boolean;\n}\n\n/** A PERSON with access to this workspace: your colleague, on a seat.\n *\n *  NOT one of your end users, and the difference is the sharpest naming trap in\n *  this SDK. A workspace member signs in here, we issued their id, and we\n *  authenticate it. A `EndUser` is the person YOUR application serves, never\n *  signs in here, and carries an id from YOUR database that we store verbatim\n *  and never check.\n *\n *  `userId` below is therefore a PLATFORM id and is not interchangeable with\n *  `agent.start({ endUserId })`. Both fields were once spelled `userId`, which\n *  made passing one where the other belonged a call that could not fail: a\n  *  end-user id is never validated against anything, so it silently labelled a\n *  conversation with a colleague's internal id. The two names now differ.\n *\n *  Named WorkspaceMember rather than Member because a public `Member` type used\n *  to mean an AGENT attached to a project. That one is now `ProjectAgent`, so\n *  the prefix here is no longer load-bearing; it stays because it says which of\n *  the two populations this is at every call site, and that is worth four\n *  characters.\n *\n *  Read-only, like everything else on the account surface: the SDK can see who\n *  is on the account and what they may do, and cannot add, remove or re-role\n *  anyone. Those are decisions a person makes while signed in, not something a\n *  key should be able to do on their behalf. */\nexport interface WorkspaceMember {\n\t/** A PLATFORM user id (`usr_...`), issued by us. Never pass this to\n\t *  `agent.start({ endUserId })` or `ws.endUser()`. */\n\tuserId: string;\n\temail: string;\n\tname: string | null;\n\t/** 'owner' is the account's creator; 'admin' can manage it; 'member' cannot. */\n\trole: 'owner' | 'admin' | 'member';\n\t/** Unix seconds. */\n\tjoinedAt: number;\n}\n\n/** What is left to spend.\n *\n *  `credits` is the balance in credits, where one credit is one US dollar. The\n *  turn counts are the same balance expressed in the unit people actually\n *  reason with, because \"12.5 credits\" answers nothing on its own. */\nexport interface Credits {\n\tcredits: number;\n\tstandardTurnsRemaining: number;\n\tpremiumTurnsRemaining: number;\n}\n\n/** The seat plan this workspace is on.\n *\n *  Seats are a SEPARATE purchase from credits: a plan says how many people may\n *  share the account, credits pay for the work their agents do. Being on the\n *  free plan does not make turns free. */\nexport interface SeatPlan {\n\tkey: string;\n\tlabel: string;\n\t/** People allowed. `null` means negotiated, which is NOT unlimited and\n\t *  should never be shown to anyone as a number. */\n\tseats: number | null;\n\t/** Monthly price in US cents. `null` means there is no published price and\n\t *  the answer is a conversation, which is the opposite fact from 0 (free). */\n\tusdCentsPerMonth: number | null;\n}\n\n/** A stored secret, WITHOUT its value.\n *\n *  The value is never returned by any read. It is written once, encrypted at\n *  rest, and substituted into an HTTP tool's url, headers or body server-side at\n *  call time, so it is never part of anything the model can see or repeat. To\n *  change one, write it again; to be sure of one, replace it. */\nexport interface SecretMeta {\n\tid: string;\n\tname: string;\n\tdescription?: string | null;\n\t/** The agent this secret is scoped to, or null when the whole workspace\n\t *  reads it. An agent-scoped secret of the same name wins. */\n\tagentId?: string | null;\n\t/** The end user this secret belongs to, or null when it is the workspace's.\n\t *  One of YOUR user ids, stored verbatim: we never resolve or authenticate\n\t *  it. A secret with one can only be attached to a conversation launched for\n\t *  that same person. */\n\tendUserId?: string | null;\n\tcreatedAt?: string;\n\tupdatedAt?: string;\n\tlastUsedAt?: string | null;\n}\n\n/** A SQL engine AgentNava can query. */\nexport type DatabaseEngine = 'postgres' | 'mysql' | 'sqlserver';\n\n/** How the connection to a database is encrypted. `require` is the default. */\nexport type DatabaseTls = 'disable' | 'require' | 'verify-full';\n\n/**\n * How to log in to a database: a connection string, OR the same login as\n * separate fields. Never both; a request with both is refused.\n *\n * Read-only unless `writable: true`, which no SQL the agent sends can override.\n */\nexport type DatabaseLogin =\n\t| {\n\t\t\t/** `postgres://`, `postgresql://` or `mysql://`, with the user (and the\n\t\t\t *  password, when there is one) in it. An `sslmode` in the string sets `tls`. */\n\t\t\turl: string;\n\t\t\tengine?: DatabaseEngine;\n\t\t\t/** Overrides the string's `sslmode`. */\n\t\t\ttls?: DatabaseTls;\n\t\t\twritable?: boolean;\n\t  }\n\t| {\n\t\t\tengine: DatabaseEngine;\n\t\t\thost: string;\n\t\t\tport: number;\n\t\t\tdatabase: string;\n\t\t\tusername: string;\n\t\t\t/** Leave it out for a database that takes a user name alone. */\n\t\t\tpassword?: string;\n\t\t\ttls?: DatabaseTls;\n\t\t\twritable?: boolean;\n\t  };\n\n/** What `ws.databases.create()` takes: the key agents will name it by, an\n *  optional label, and a login. */\nexport type DatabaseFields = DatabaseLogin & {\n\t/** Lowercase letters, digits and dashes, like `shop` or `sales-db`. What an\n\t *  agent configuration stores, so it is not editable afterwards. */\n\tkey: string;\n\t/** A label for people. Defaults to the key. */\n\tname?: string;\n};\n\n/** A registered database as AgentNava reports it: where it is, never how to\n *  log in. Neither the password nor the connection string is ever returned. */\nexport interface DatabaseData {\n\tkey: string;\n\t/** The underlying connection's id. */\n\tid: string;\n\tname: string;\n\tengine: DatabaseEngine | null;\n\thost: string | null;\n\tport: number | null;\n\tdatabase: string | null;\n\ttls: DatabaseTls | null;\n\twritable: boolean;\n\tstatus: string;\n\tcreatedAt: string;\n\t/** The agents whose configuration names this database. */\n\tusedBy: DatabaseUsedBy[];\n}\n\n/** An agent whose configuration names a database: in its latest published\n *  version, in its draft, or in both. */\nexport interface DatabaseUsedBy {\n\t/** The agent's id: the same value as `Agent.id`, so compare this one. */\n\tid: string;\n\t/** AgentNava's internal handle for the same agent (`agt_...`), not `Agent.id`. */\n\tagentId: string;\n\t/** The agent's display name. */\n\tname: string;\n\t/** Named in the agent's latest published version, so its conversations can\n\t *  query the database now. */\n\tpublished: boolean;\n\t/** Named in the configuration being edited: the draft when there is one,\n\t *  else the published version itself. */\n\tdraft: boolean;\n}\n\n/** One table or view in a database. */\nexport interface DatabaseTable {\n\tschema: string;\n\tname: string;\n\tkind: 'table' | 'view';\n}\n\n/** One column of a table. */\nexport interface DatabaseColumn {\n\tname: string;\n\tdataType: string;\n\tnullable: boolean;\n\tisPrimaryKey: boolean;\n}\n\n/** What `ws.databases.test()` reports. A refused login is an answer, not an\n *  exception, because it is the answer the call exists to get. */\nexport type DatabaseTestResult =\n\t| { ok: true; engine: DatabaseEngine; tableCount: number; tables: DatabaseTable[] }\n\t| { ok: false; error: { code: string; message: string } };\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D","sourcesContent":["// The shapes this SDK hands back. Transcribed from design/sdk-design.md's own\n// Types section so the reference and the code cannot drift.\n\n// Type-only: erased from the emitted JavaScript, so these add no runtime cycle\n// with the modules that import their own shapes from here.\nimport type { AppId } from './apps.generated.ts';\nimport type { Connection } from './connection.ts';\n\n/** The quality of model an agent's turns run on, and what each turn costs.\n *\n *  `fast` is the one that surprises people: it buys LATENCY rather than\n *  capability, runs a smaller model on silicon built for time-to-first-token,\n *  and costs MORE than `premium` while being less capable. Pick it for voice\n *  and interactive agents, not to save money. `best` is the strongest model. */\nexport type Grade = 'standard' | 'premium' | 'fast' | 'best';\nexport type Filesystem = 'drive' | 'none';\n\n/** Where a SECRET is supplied.\n *\n *  'fixed' is set once on the agent and used by every conversation. 'conversation'\n *  is asked for when a conversation starts, so each user brings their own. The\n *  two DO NOT substitute for each other: a value set on the agent does not\n *  satisfy a declaration scoped 'conversation'.\n *\n *  Connections stopped using this in 0.44. A connection says WHOSE ACCOUNT it\n *  uses instead: the agent creator's (`account`) or each end user's own\n *  (`endUser: true`). See `AgentConnection`. */\nexport type Scope = 'fixed' | 'conversation';\n\nexport interface WorkspaceInfo {\n\tid: string;\n\tname: string;\n\tcredits: number;\n\tcreatedAt: string;\n}\n\n/** One procedure the agent follows when its `when` matches what is in front of\n *  it. `when` is one line and is not optional: it is what the agent reads to\n *  decide the workflow applies, so a vague one makes a good workflow invisible. */\nexport interface Workflow {\n\tname: string;\n\twhen: string;\n\tcontent: string;\n}\n\n// `SessionMode` is deliberately NOT exposed.\n//\n// The API has one ('per-user' | 'per-call') and 'per-user' makes the server\n// resume a person's most recent conversation. That is the behaviour `start`\n// refuses to have: a verb that sometimes returns something you already had, and\n// which has to guess which one the moment a person has two.\n//\n// Its other effect, fanning a scheduled firing out across the people who have\n// conversations with an agent, is real and worth exposing one day. It should\n// arrive under a name that says THAT, not under a mode that also silently\n// changes what `start` returns.\n\nexport type Trigger =\n\t| { kind: 'chat' }\n\t| ({ kind: 'schedule'; enabled?: boolean; cron: string; timezone?: string; message: string } & TriggerTarget)\n\t| { kind: 'interval'; seconds: number; maxRuns?: number; message: string }\n\t| ({\n\t\t\tkind: 'webhook';\n\t\t\tmessage?: string;\n\t\t\t/**\n\t\t\t * Where your system POSTs, set by the platform. Read it from the agent\n\t\t\t * that `setTriggers()` returns: `agent.data?.triggers`. Anything you\n\t\t\t * send here is ignored, so passing back a list you read is safe and\n\t\t\t * keeps the same URL. One webhook per agent; `rotateWebhookUrl()`\n\t\t\t * replaces the URL.\n\t\t\t */\n\t\t\turl?: string;\n\t\t\t/**\n\t\t\t * Check WHO sent each delivery, beyond knowing the URL. See\n\t\t\t * WebhookVerify for the schemes and an example. Leave it out to keep\n\t\t\t * what the webhook has. The secret is stored encrypted and never read\n\t\t\t * back: a read says `secretSet: true` instead.\n\t\t\t */\n\t\t\tverify?: WebhookVerify;\n\t  } & TriggerTarget);\n\n/**\n * How a webhook checks its sender. Platforms that send webhooks sign every\n * delivery with a secret they show you when you add the URL there; give it\n * here, and a delivery whose signature does not match is refused (401) and\n * never runs the agent.\n *\n * ```ts\n * { kind: 'webhook', verify: { kind: 'stripe', secret: 'whsec_...' } }\n * { kind: 'webhook', verify: { kind: 'header', header: 'X-Webhook-Secret', secret: '...' } }\n * ```\n *\n * The schemes: `stripe`, `github`, `shopify`, `slack` and\n * `standard` (the Standard Webhooks spec) check that platform's signature;\n * `header` checks a header your sender adds (Zapier, Make, n8n, your own code\n * can all add one); `none` relies on the URL alone.\n */\nexport type WebhookVerify =\n\t| { kind: 'none' }\n\t| { kind: 'stripe' | 'github' | 'shopify' | 'slack' | 'standard'; secret?: string; secretSet?: boolean }\n\t| { kind: 'header'; header: string; secret?: string; secretSet?: boolean };\n\n/** One delivery a webhook received, newest first from `agent.webhookDeliveries()`. */\nexport interface WebhookDelivery {\n\tid: string;\n\treceivedAt: string;\n\t/** `pending`: checked and starting. `repeat`: the sender retried a delivery\n\t *  already accepted; the agent did not run again. */\n\toutcome: 'pending' | 'accepted' | 'refused' | 'repeat' | 'test';\n\t/** Why it was refused. */\n\treason?: string;\n\t/** The sender's own id for it, when it gave one. */\n\tdeliveryId?: string;\n\t/** The conversation it ran in. */\n\tconversationId?: string;\n}\n\n/**\n * WHERE a schedule or webhook runs. Name a conversation, or an end user, or\n * neither; never both.\n *\n * ```ts\n * const conversation = await agent.start({ endUserId: 'ops-app' });\n * await agent.setTriggers([\n *   { kind: 'chat' },\n *   // Every firing lands in THIS conversation: its history, its drive.\n *   { kind: 'schedule', cron: '0 15 * * *', message: 'REFRESH', conversationId: conversation.id },\n * ]);\n * ```\n */\nexport type TriggerTarget =\n\t| {\n\t\t\t/**\n\t\t\t * The conversation every firing CONTINUES: it sees that conversation's\n\t\t\t * history and its drive, and its end user comes with it. Each firing\n\t\t\t * also moves the conversation to the agent's latest version, so a fix\n\t\t\t * you publish reaches it.\n\t\t\t *\n\t\t\t * This is the ONLY way a trigger continues one of your conversations.\n\t\t\t * One end user can have many, so naming the end user cannot say which.\n\t\t\t *\n\t\t\t * Must be a conversation of this agent, started for one of your end\n\t\t\t * users (the id `agent.start()` returned). Anything else is refused\n\t\t\t * when you set the trigger. If the conversation is deleted later, the\n\t\t\t * firings fail and say so; none is opened in its place.\n\t\t\t */\n\t\t\tconversationId: string;\n\t\t\tuserId?: undefined;\n\t  }\n\t| {\n\t\t\tconversationId?: undefined;\n\t\t\t/**\n\t\t\t * The end user each firing is for, when it names no conversation. Each\n\t\t\t * firing STARTS A NEW CONVERSATION for them, with an empty drive, and it\n\t\t\t * is listed by `agent.conversations({ endUser })`. To keep adding to\n\t\t\t * one conversation instead, name it with `conversationId`.\n\t\t\t *\n\t\t\t * Your id, as in `agent.start({ endUserId })`; the platform's prefixes\n\t\t\t * (`member:`, `visitor:`, `job:`) are refused.\n\t\t\t *\n\t\t\t * Name neither and the trigger keeps one conversation of its own that\n\t\t\t * every firing continues.\n\t\t\t */\n\t\t\tuserId?: string;\n\t  };\n\n/**\n * One connection in an agent's setup, as it reads back: a NAME, an APP, and\n * WHOSE ACCOUNT. Exactly one of these two:\n *\n * | the connection says | whose account | the person signs in |\n * |---|---|---|\n * | `account: '<id>'` | the agent creator's: one account in this workspace, from `ws.accounts.connect()` | once, and every conversation uses it |\n * | `endUser: true` | the end user's: each person talking to the agent | once each, remembered for them |\n *\n * A turn uses EXACTLY the account the setup names, and never another one.\n * There is no fallback to some other account of the same app: an account that\n * is not signed in leaves the connection unavailable, and the agent says so.\n *\n * `name` tells two connections of one app apart, such as `work-gmail` and\n * `personal-gmail`. 1 to 64 characters, lowercase letters, digits and dashes,\n * no dash at either end, unique on the agent. Left out when sent, it is the\n * app's id.\n *\n * Part of the agent's CONFIGURATION, so changing a connection publishes a\n * version. The account itself is not versioned: signing in again reaches every\n * agent that names it. To send one, build it with `Connection.creatorAccount()`\n * or `Connection.endUserAccount()`.\n */\nexport type AgentConnection =\n\t| {\n\t\t\tname: string;\n\t\t\t/** The app's id: `App.GMAIL` is `'gmail'`. */\n\t\t\tapp: AppId;\n\t\t\t/** An account id in this workspace whose app is `app`. */\n\t\t\taccount: string;\n\t\t\tendUser?: never;\n\t  }\n\t| {\n\t\t\tname: string;\n\t\t\tapp: AppId;\n\t\t\tendUser: true;\n\t\t\taccount?: never;\n\t  };\n\n/** What an agent NEEDS, not the stored value. `Secret` is the value. */\nexport interface SecretRequirement {\n\tname: string;\n\tscope: Scope;\n\trequired?: boolean;\n}\n\nexport interface Parameter {\n\tname: string;\n\ttype: 'string' | 'number' | 'date' | 'choice';\n\trequired?: boolean;\n\tdefault?: string;\n\tchoices?: string[];\n}\n\nexport interface McpServer {\n\tname: string;\n\turl: string;\n\ttransport?: 'http' | 'sse';\n\theaders?: Record<string, string>;\n\ttimeoutMs?: number;\n}\n\nexport interface HttpToolParam {\n\ttype: 'string' | 'number' | 'boolean' | 'object' | 'array';\n\tdescription?: string;\n\trequired?: boolean;\n\tchoices?: (string | number | boolean | null)[];\n\tnullable?: boolean;\n\tinteger?: boolean;\n\tproperties?: Record<string, HttpToolParam>;\n\titems?: HttpToolParam;\n\tadditionalProperties?: boolean;\n}\n\nexport interface HttpTool {\n\tname: string;\n\tdescription: string;\n\tmethod: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';\n\turl: string;\n\theaders?: Record<string, string>;\n\tbody?: string;\n\tparams?: Record<string, HttpToolParam>;\n\tsecrets?: string[];\n\ttimeoutMs?: number;\n}\n\nexport interface AgentData {\n\tid: string;\n\tname: string;\n\tinstructions: string;\n\tgreeting?: string;\n\tgrade: Grade;\n\tfilesystem: Filesystem;\n\ttools: string[];\n\tworkflows: Workflow[];\n\t/** The apps it uses, each saying whose account. See `AgentConnection`. */\n\tconnections: AgentConnection[];\n\tsecrets: SecretRequirement[];\n\tparameters: Parameter[];\n\ttriggers: Trigger[];\n\tmcpServers: McpServer[];\n\thttpTools: HttpTool[];\n\t/** Workspace knowledge bases this agent reads, by key. Always present, empty\n\t *  when none are attached, so a caller never has to distinguish \"none\" from\n\t *  \"an older server that did not send the field\". */\n\tknowledgeBases: string[];\n\t/** Workspace databases this agent may query, by key. Always present, like\n\t *  `knowledgeBases`. */\n\tdatabases: string[];\n\tversion: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n\t/** Where it is live, as the portal shows it. The API works it out by the\n\t *  same rule it runs the agent by, so `channels.api === 'on'` is exactly\n\t *  \"a turn will be taken\". Read-only: nothing sets it. Sent by `agent.get()`\n\t *  and `ws.agents.list()`; absent from what create and update return, so\n\t *  call `get()` for it. */\n\treadonly status?: AgentStatus;\n}\n\n/** What `agent.websiteChat.turnOn()` gives back: what to put on a website. */\nexport interface WebsiteChat {\n\t/** The hosted chat page. Share it, or open it in an iframe. */\n\treadonly chatUrl: string;\n\t/** The publishable token for the embed script. Safe in a public web page:\n\t *  it can only talk to this one agent. Your API key never goes there. */\n\treadonly publicToken: string;\n\t/** The id the embed script's `data-agent-id` takes. */\n\treadonly embedAgentId: string;\n\t/** The version the website chat serves from now on. */\n\treadonly versionNumber: number;\n}\n\n/** Where an agent is live. See `AgentData.status`. */\nexport interface AgentStatus {\n\t/** True when any channel is on. */\n\treadonly live: boolean;\n\t/** Paused by its owner: nothing runs it until it is resumed. */\n\treadonly paused: boolean;\n\t/** Archived: nothing runs it again. */\n\treadonly archived: boolean;\n\treadonly channels: {\n\t\t/** 'on' when the API takes new turns for it. */\n\t\treadonly api: 'on' | 'off';\n\t\t/** 'on' when its website chat page answers visitors. 'unavailable' when it\n\t\t *  needs what each user brings (`eachUserBrings`), which a visitor cannot. */\n\t\treadonly websiteChat: 'on' | 'off' | 'unavailable';\n\t};\n\t/** Required accounts and secrets of its own that are not set up yet, on the\n\t *  version a new conversation runs. It still runs: the tools that use them\n\t *  fail until they are set up. Empty when nothing is missing. */\n\treadonly needs: readonly { kind: 'connection' | 'secret'; name: string }[];\n\t/** The accounts and secrets each user supplies for themselves. */\n\treadonly eachUserBrings: readonly { kind: 'connection' | 'secret'; name: string }[];\n}\n\n/**\n * One of an agent's connections as it stands right now: the account it names,\n * and whether that account works. What `agent.connections.list()` returns.\n *\n * DECLARED IS NOT CONNECTED, and this is the read that tells them apart. A\n * connection can name an account nobody has finished signing in to, or one that\n * was disconnected since; that is the state a setup checklist has to show, and\n * without this the only way to find it is to start a conversation and watch\n * the agent fail.\n *\n * Reshaped in 0.44: it used to be keyed by `provider`, with `declared`,\n * `required`, `scope` and `suppliedBy`. A connection is now keyed by its\n * `name`, and it says whose account it uses instead of where one might come\n * from.\n */\nexport interface ConnectionStatus {\n\tname: string;\n\tapp: AppId;\n\t/** The agent creator's account the connection names, read fresh. Absent on\n\t *  an end user's connection, and on one whose account is gone. */\n\taccount?: AccountData;\n\t/** True when each person talking to the agent signs in with their own. */\n\tendUser?: true;\n\t/** Whether the connection works now, as the API reports it. For an agent\n\t *  creator's account it follows that account's status. */\n\tstatus: string;\n\t/** Only in the agent's unpublished draft, so no conversation uses it yet. */\n\tinDraft: boolean;\n\t/** Removed in the agent's unpublished draft, and still used until the draft\n\t *  is published. */\n\tremovedInDraft: boolean;\n}\n\n/** Where one account's sign-in stands.\n *\n *   'pending'        made, and nobody has finished signing in yet\n *   'connected'      signed in and working\n *   'needs_sign_in'  it worked, and the app now wants the person to sign in again\n *   'error'          the app refused it for another reason\n */\nexport type AccountStatus = 'pending' | 'connected' | 'needs_sign_in' | 'error';\n\n/** An agent whose setup names an account, and the connection that names it.\n *  Counted from the agent's latest published version and its draft, never\n *  from older versions. */\nexport interface UsedBy {\n\t/** The agent's id: the same value as `Agent.id`, so compare this one. */\n\tid: string;\n\t/** AgentNava's internal handle for the same agent (`agt_...`), not `Agent.id`. */\n\tagentId: string;\n\tagentName: string;\n\tconnectionName: string;\n\t/** Named in the agent's unpublished draft. */\n\tinDraft: boolean;\n\t/** Named in the agent's latest published version. */\n\tpublished: boolean;\n}\n\n/**\n * One saved sign-in to one app.\n *\n * TWO OWNERS, and the difference is who signs in:\n *\n * | `owner` | whose | a connection uses it as |\n * |---|---|---|\n * | `'workspace'` | the agent creator's, signed in once, usable by any agent | `Connection.creatorAccount(app, account)` |\n * | `'end-user'` | one of YOUR end users', remembered for that person | `Connection.endUserAccount(app)`, in that person's conversations |\n *\n * Both owners are read and changed through the same routes and the same\n * `Account` handle; `owner` says which this is.\n *\n * Nobody handles a token: the person signs in on the app's own page, and this\n * record says who they signed in as, never how.\n */\nexport interface AccountData {\n\tid: string;\n\t/** The app's id: `App.GMAIL` is `'gmail'`. */\n\tapp: AppId;\n\t/** Who it is signed in as: the email or username the app reports. Null until\n\t *  somebody has finished signing in. */\n\tlabel: string | null;\n\t/** Your own name for it, such as `'Support inbox'`. Null when none was given. */\n\tnickname: string | null;\n\tstatus: AccountStatus;\n\t/** True while a reconnect waits for the person to sign in again. The\n\t *  account keeps working meanwhile, so `status` can still say\n\t *  `'connected'`; `waitUntilConnected()` waits for this to clear. */\n\treconnecting: boolean;\n\towner: 'workspace' | 'end-user';\n\t/** The end user it belongs to, when `owner` is `'end-user'`. An id from YOUR\n\t *  database, never a workspace member's. */\n\tendUserId?: string;\n\tconnectedAt: string | null;\n\tlastCheckedAt: string | null;\n\t/** The agents whose setup names this account. Empty for an end user's\n\t *  account, which a setup never names by id. */\n\tusedBy: UsedBy[];\n}\n\n/** An end user's account a conversation still needs, with the link that\n *  person signs in at. From `conversation.accountsNeeded()`. */\nexport interface AccountNeeded {\n\t/** The connection's name on the agent. */\n\tname: string;\n\tapp: AppId;\n\t/** Send the person here. They sign in once, and every later conversation\n\t *  of theirs has it. */\n\turl: string;\n}\n\n/** Something a conversation is still missing before it can work. */\nexport interface Requirement {\n\tkind: 'secret' | 'connection';\n\tname: string;\n\trequired: boolean;\n}\n\nexport interface AgentConversationData {\n\tid: string;\n\tagentId: string;\n\t/** The number of the agent version this conversation runs, as `agent.version`\n\t *  numbers them. Fixed at start, except that a schedule or webhook naming the\n\t *  conversation moves it to the latest version at each firing. */\n\tversion: number;\n\tstartedAt: string;\n\ttitle?: string;\n\t/** True when nothing REQUIRED is outstanding. An optional gap leaves this\n\t *  true, because the conversation genuinely does work without it. */\n\tready: boolean;\n\trequires: Requirement[];\n}\n\nexport interface ProjectConversationData {\n\tid: string;\n\tprojectId: string;\n\tstartedAt: string;\n\ttitle?: string;\n\tready: boolean;\n\trequires: Requirement[];\n}\n\n/** An AGENT on a project, not a person.\n *\n *  Called `ProjectAgent` and not `Member`, which is what it was. `Member` is\n *  the word this product uses for a HUMAN on the account, so a public type of\n *  that name holding an `agentId` was the same trap as `userId` meaning two\n *  populations: `import { Member }` handed you the agent one, and the human one\n *  had to carry a prefix to get out of its way.\n *\n *  The people are `WorkspaceMember`, from `ws.members()`. Nothing here is a\n *  person. */\nexport interface ProjectAgent {\n\tagentId: string;\n\tname: string;\n\taddedAt: string;\n}\n\nexport interface ProjectData {\n\tid: string;\n\tname: string;\n\tgoal: string | null;\n\tmanagerInstructions: string | null;\n\tgrade: Grade;\n\tstatus: 'active' | 'archived';\n\tagents: ProjectAgent[];\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\nexport interface Step {\n\tid: string;\n\tlabel: string;\n\tkind: 'read' | 'write' | 'edit' | 'search' | 'shell' | 'web' | 'data' | 'task' | 'plan' | 'other';\n\tstatus: 'active' | 'done' | 'error';\n}\n\nexport type TurnEvent =\n\t| { type: 'start'; turnId: string }\n\t/** Carries the WHOLE step list every time, not a change to it. Replace what\n\t *  you are showing rather than merging; that is what makes reconnecting\n\t *  safe. */\n\t| { type: 'progress'; steps: Step[] }\n\t| { type: 'tool'; name: string; state: 'start' | 'end'; ok?: boolean }\n\t/** A fragment, not a line. Append; do not assemble. */\n\t| { type: 'text'; text: string }\n\t| { type: 'file'; path: string }\n\t| { type: 'done'; reply: string }\n\t| { type: 'error'; message: string; retryable: boolean };\n\nexport interface Message {\n\trole: 'user' | 'assistant';\n\tcontent: string;\n\tat: string;\n}\n\n/** An image goes to the model as an image. Anything else is written into the\n *  conversation's drive before the turn starts, so the agent can parse it,\n *  compute over it, and still have it next turn. */\nexport interface Attachment {\n\tkind: 'image' | 'file';\n\tname?: string;\n\tmimeType: string;\n\t/** base64, without a data: prefix. */\n\tdata: string;\n}\n\n/** A knowledge base: a named folder of files at WORKSPACE scope that an agent\n *  configuration attaches by key. */\nexport interface KnowledgeBaseData {\n\t/** Workspace-unique. This is what an agent configuration stores, and it is\n\t *  not editable, because renaming it would move every attachment silently. */\n\tkey: string;\n\tname: string;\n\tdescription?: string;\n\t/** Counted when read, so it never disagrees with the files it counts. */\n\tfileCount: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\n/** One file in a knowledge base. PATH, not a flat name: a base is a folder, and\n *  the session mount reproduces the shape verbatim. */\n/**\n * Whether an agent can read a file in a knowledge base.\n *\n * Text and markdown are readable as they stand. A PDF, a scan or a spreadsheet\n * has to be turned into text first, which happens when the file is uploaded\n * rather than when a question is asked, so an agent never waits on it.\n *\n *   'readable'    an agent can read this now\n *   'processing'  being prepared, check back shortly\n *   'unreadable'  cannot be read, and `reason` says why\n */\nexport type KnowledgeFileStatus = 'readable' | 'processing' | 'unreadable';\n\nexport interface KnowledgeFileEntry {\n\tpath: string;\n\tmimeType: string;\n\tsize: number;\n\tcreatedAt: string;\n\tupdatedAt: string;\n\t/** Whether an agent can read this file. */\n\tstatus: KnowledgeFileStatus;\n\t/** Why it cannot be read, as a sentence you could show someone.\n\t *\n\t *  The same text reaches the agent in place of the file, so a developer\n\t *  reading this and a model reading the base get one explanation rather than\n\t *  two that can drift apart. Absent unless `status` is 'unreadable'. */\n\treason?: string;\n}\n\nexport interface FileEntry {\n\tpath: string;\n\tkind: 'file' | 'directory';\n\tmimeType: string;\n\tsize: number;\n\tmodifiedAt: string;\n}\n\n/** Fields accepted when creating or updating an agent. Everything is optional on\n *  an update: what you do not send is inherited from the current version, which\n *  is the whole reason updating is safe. */\nexport interface AgentFields {\n\tid?: string;\n\tname?: string;\n\tinstructions?: string;\n\tgreeting?: string;\n\tgrade?: Grade;\n\tfilesystem?: Filesystem;\n\t/**\n\t * Knowledge bases this agent reads, by workspace-unique key.\n\t *\n\t * Mounted READ-ONLY at `/knowledge/<key>/` when a session starts, so the\n\t * agent finds things with `ls`, `grep` and `cat` rather than a retrieval API.\n\t *\n\t * Which bases an agent reads is part of its CONFIGURATION, so changing this\n\t * publishes a version you can diff and roll back. The CONTENTS of a base are\n\t * not versioned: correcting a file changes what every attached agent sees on\n\t * its next turn, which is the same by-reference promise `agent.knowledge`\n\t * already makes.\n\t *\n\t * A key that names no base is refused when the configuration is saved, and\n\t * deleting a base is refused while any agent attaches it, so an attachment\n\t * that was valid stays valid.\n\t */\n\tknowledgeBases?: string[];\n\t/**\n\t * Workspace databases this agent may query, by key.\n\t *\n\t * Register the database first with `ws.databases.create()`, which logs in\n\t * and gives it the key; then name the key here. Naming it is the grant: a\n\t * database answers only the agents whose configuration names it, and the\n\t * agent's prompt lists them so it knows what to query.\n\t *\n\t * Part of the CONFIGURATION, so changing it publishes a version. A key that\n\t * names no database is refused when the configuration is saved, and\n\t * removing a database is refused while any agent names it.\n\t */\n\tdatabases?: string[];\n\ttools?: string[];\n\tworkflows?: Workflow[];\n\t/**\n\t * The apps this agent uses, each a NAMED connection that says whose account\n\t * it uses: the agent creator's account, or each end user's own. See\n\t * `Connection` and `AgentConnection`.\n\t *\n\t * ```ts\n\t * connections: [\n\t *   Connection.creatorAccount(App.GMAIL, work, { name: 'work-gmail' }),\n\t *   Connection.creatorAccount(App.GMAIL, personal, { name: 'personal-gmail' }),\n\t *   Connection.endUserAccount(App.GOOGLE_CALENDAR),\n\t * ]\n\t * ```\n\t *\n\t * The builders make plain objects, `{ app, account: '<id>' }` and\n\t * `{ app, endUser: true }`, and those objects are accepted as they are.\n\t * `App.GMAIL` is the string `'gmail'`, so a plain app id works too.\n\t *\n\t * Part of the CONFIGURATION, like `databases`, so changing it publishes a\n\t * version. An unknown account id, an account of a different app, a repeated\n\t * name or a name of the wrong shape is refused when the configuration is\n\t * saved, naming the problem.\n\t */\n\tconnections?: Connection[];\n\tsecrets?: SecretRequirement[];\n\tparameters?: Parameter[];\n\ttriggers?: Trigger[];\n\tmcpServers?: McpServer[];\n\thttpTools?: HttpTool[];\n}\n\nexport interface ProjectFields {\n\tname?: string;\n\tgoal?: string;\n\tmanagerInstructions?: string;\n\tgrade?: Grade;\n\tagents?: string[];\n}\n\n/** Secret VALUES supplied to an agent (`agent.attach`) or to one conversation\n *  (`conversation.attach`): the secrets its agent declared.\n *\n *  Accounts are no longer supplied this way (0.44). An agent's setup names the\n *  account each connection uses, so there is nothing left to attach. */\nexport interface Bindings {\n\tsecrets?: Record<string, string>;\n}\n\n/** One markdown file read off disk: a workflow or a subagent.\n *\n *  `when` is OPTIONAL here and required at publish. A file on disk has no `when`\n *  until someone writes one, and refusing to read it would be the wrong place to\n *  say so; the API says it at publish, with a message naming the file. */\nexport interface SpecFile {\n\tname: string;\n\tcontent: string;\n\twhen?: string;\n}\n\n/** What a loaded agent directory produces: the fields `ws.agents.create()` takes,\n *  plus the id the caller chose and the few legacy names the loader still reads\n *  off an existing directory. */\nexport interface SpecInput extends Omit<AgentFields, 'workflows'> {\n\tkey: string;\n\tworkflows?: SpecFile[];\n\tsubagents?: SpecFile[];\n\twidgets?: { name: string; [k: string]: unknown }[];\n\tsandbox?: Filesystem;\n\trole?: string;\n\t/** Retired in favour of `tools: ['web_search']`, still read off an existing\n\t *  agent directory so one written before the rename still loads. */\n\twebSearch?: boolean;\n}\n\n/** A PERSON with access to this workspace: your colleague, on a seat.\n *\n *  NOT one of your end users, and the difference is the sharpest naming trap in\n *  this SDK. A workspace member signs in here, we issued their id, and we\n *  authenticate it. A `EndUser` is the person YOUR application serves, never\n *  signs in here, and carries an id from YOUR database that we store verbatim\n *  and never check.\n *\n *  `userId` below is therefore a PLATFORM id and is not interchangeable with\n *  `agent.start({ endUserId })`. Both fields were once spelled `userId`, which\n *  made passing one where the other belonged a call that could not fail: a\n  *  end-user id is never validated against anything, so it silently labelled a\n *  conversation with a colleague's internal id. The two names now differ.\n *\n *  Named WorkspaceMember rather than Member because a public `Member` type used\n *  to mean an AGENT attached to a project. That one is now `ProjectAgent`, so\n *  the prefix here is no longer load-bearing; it stays because it says which of\n *  the two populations this is at every call site, and that is worth four\n *  characters.\n *\n *  Read-only, like everything else on the account surface: the SDK can see who\n *  is on the account and what they may do, and cannot add, remove or re-role\n *  anyone. Those are decisions a person makes while signed in, not something a\n *  key should be able to do on their behalf. */\nexport interface WorkspaceMember {\n\t/** A PLATFORM user id (`usr_...`), issued by us. Never pass this to\n\t *  `agent.start({ endUserId })` or `ws.endUser()`. */\n\tuserId: string;\n\temail: string;\n\tname: string | null;\n\t/** 'owner' is the account's creator; 'admin' can manage it; 'member' cannot. */\n\trole: 'owner' | 'admin' | 'member';\n\t/** Unix seconds. */\n\tjoinedAt: number;\n}\n\n/** What is left to spend.\n *\n *  `credits` is the balance in credits, where one credit is one US dollar. The\n *  turn counts are the same balance expressed in the unit people actually\n *  reason with, because \"12.5 credits\" answers nothing on its own. */\nexport interface Credits {\n\tcredits: number;\n\tstandardTurnsRemaining: number;\n\tpremiumTurnsRemaining: number;\n}\n\n/** The seat plan this workspace is on.\n *\n *  Seats are a SEPARATE purchase from credits: a plan says how many people may\n *  share the account, credits pay for the work their agents do. Being on the\n *  free plan does not make turns free. */\nexport interface SeatPlan {\n\tkey: string;\n\tlabel: string;\n\t/** People allowed. `null` means negotiated, which is NOT unlimited and\n\t *  should never be shown to anyone as a number. */\n\tseats: number | null;\n\t/** Monthly price in US cents. `null` means there is no published price and\n\t *  the answer is a conversation, which is the opposite fact from 0 (free). */\n\tusdCentsPerMonth: number | null;\n}\n\n/** A stored secret, WITHOUT its value.\n *\n *  The value is never returned by any read. It is written once, encrypted at\n *  rest, and substituted into an HTTP tool's url, headers or body server-side at\n *  call time, so it is never part of anything the model can see or repeat. To\n *  change one, write it again; to be sure of one, replace it. */\nexport interface SecretMeta {\n\tid: string;\n\tname: string;\n\tdescription?: string | null;\n\t/** The agent this secret is scoped to, or null when the whole workspace\n\t *  reads it. An agent-scoped secret of the same name wins. */\n\tagentId?: string | null;\n\t/** The end user this secret belongs to, or null when it is the workspace's.\n\t *  One of YOUR user ids, stored verbatim: we never resolve or authenticate\n\t *  it. A secret with one can only be attached to a conversation launched for\n\t *  that same person. */\n\tendUserId?: string | null;\n\tcreatedAt?: string;\n\tupdatedAt?: string;\n\tlastUsedAt?: string | null;\n}\n\n/** A SQL engine AgentNava can query. */\nexport type DatabaseEngine = 'postgres' | 'mysql' | 'sqlserver';\n\n/** How the connection to a database is encrypted. `verify` (the default)\n *  encrypts and always checks the server's certificate: against public and\n *  cloud CAs and the host name, or, for a database with its own home-made CA,\n *  against the CA AgentNava trusted the first time it connected. `disable` is\n *  for a server with no SSL at all. */\nexport type DatabaseTls = 'verify' | 'disable';\n\n/**\n * How to log in to a database: a connection string, OR the same login as\n * separate fields. Never both; a request with both is refused.\n *\n * Read-only unless `writable: true`, which no SQL the agent sends can override.\n */\nexport type DatabaseLogin =\n\t| {\n\t\t\t/** `postgres://`, `postgresql://` or `mysql://`, with the user (and the\n\t\t\t *  password, when there is one) in it. An `sslmode` in the string sets `tls`. */\n\t\t\turl: string;\n\t\t\tengine?: DatabaseEngine;\n\t\t\t/** Overrides the string's `sslmode`. */\n\t\t\ttls?: DatabaseTls;\n\t\t\twritable?: boolean;\n\t  }\n\t| {\n\t\t\tengine: DatabaseEngine;\n\t\t\thost: string;\n\t\t\tport: number;\n\t\t\tdatabase: string;\n\t\t\tusername: string;\n\t\t\t/** Leave it out for a database that takes a user name alone. */\n\t\t\tpassword?: string;\n\t\t\ttls?: DatabaseTls;\n\t\t\twritable?: boolean;\n\t  };\n\n/** What `ws.databases.create()` takes: the key agents will name it by, an\n *  optional label, and a login. */\nexport type DatabaseFields = DatabaseLogin & {\n\t/** Lowercase letters, digits and dashes, like `shop` or `sales-db`. What an\n\t *  agent configuration stores, so it is not editable afterwards. */\n\tkey: string;\n\t/** A label for people. Defaults to the key. */\n\tname?: string;\n};\n\n/** A registered database as AgentNava reports it: where it is, never how to\n *  log in. Neither the password nor the connection string is ever returned. */\nexport interface DatabaseData {\n\tkey: string;\n\t/** The underlying connection's id. */\n\tid: string;\n\tname: string;\n\tengine: DatabaseEngine | null;\n\thost: string | null;\n\tport: number | null;\n\tdatabase: string | null;\n\ttls: DatabaseTls | null;\n\twritable: boolean;\n\tstatus: string;\n\tcreatedAt: string;\n\t/** The agents whose configuration names this database. */\n\tusedBy: DatabaseUsedBy[];\n}\n\n/** An agent whose configuration names a database: in its latest published\n *  version, in its draft, or in both. */\nexport interface DatabaseUsedBy {\n\t/** The agent's id: the same value as `Agent.id`, so compare this one. */\n\tid: string;\n\t/** AgentNava's internal handle for the same agent (`agt_...`), not `Agent.id`. */\n\tagentId: string;\n\t/** The agent's display name. */\n\tname: string;\n\t/** Named in the agent's latest published version, so its conversations can\n\t *  query the database now. */\n\tpublished: boolean;\n\t/** Named in the configuration being edited: the draft when there is one,\n\t *  else the published version itself. */\n\tdraft: boolean;\n}\n\n/** One table or view in a database. */\nexport interface DatabaseTable {\n\tschema: string;\n\tname: string;\n\tkind: 'table' | 'view';\n}\n\n/** One column of a table. */\nexport interface DatabaseColumn {\n\tname: string;\n\tdataType: string;\n\tnullable: boolean;\n\tisPrimaryKey: boolean;\n}\n\n/** What `ws.databases.test()` reports. A refused login is an answer, not an\n *  exception, because it is the answer the call exists to get. */\nexport type DatabaseTestResult =\n\t| { ok: true; engine: DatabaseEngine; tableCount: number; tables: DatabaseTable[] }\n\t| { ok: false; error: { code: string; message: string } };\n"]}

package/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.44.1";
+export declare const SDK_VERSION = "0.46.1";

package/version.js

@@ -1,5 +1,5 @@
 // GENERATED by scripts/regen-version.mjs. Do not edit: run `bun run regen:version`
 // after bumping the version in package.json. tests/version.test.ts fails if
 // this drifts.
-export const SDK_VERSION = '0.44.1';
+export const SDK_VERSION = '0.46.1';
 //# sourceMappingURL=version.js.map

package/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,4EAA4E;AAC5E,eAAe;AACf,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC","sourcesContent":["// GENERATED by scripts/regen-version.mjs. Do not edit: run `bun run regen:version`\n// after bumping the version in package.json. tests/version.test.ts fails if\n// this drifts.\nexport const SDK_VERSION = '0.44.1';\n"]}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,4EAA4E;AAC5E,eAAe;AACf,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC","sourcesContent":["// GENERATED by scripts/regen-version.mjs. Do not edit: run `bun run regen:version`\n// after bumping the version in package.json. tests/version.test.ts fails if\n// this drifts.\nexport const SDK_VERSION = '0.46.1';\n"]}