@cerebro-labs/agentnava-sdk 0.53.2 → 0.75.0

package/types.d.ts

@@ -191,11 +191,14 @@ export type AgentConnection = {
     /** An account id in this workspace whose app is `app`. */
     account: string;
     endUser?: never;
+    /** Which of the app's own tools the agent may use; absent for the app's default. */
+    tools?: string[];
 } | {
     name: string;
     app: AppId;
     endUser: true;
     account?: never;
+    tools?: string[];
 };
 /** What an agent NEEDS, not the stored value. `Secret` is the value. */
 export interface SecretRequirement {
@@ -227,6 +230,40 @@ export interface HttpToolParam {
     properties?: Record<string, HttpToolParam>;
     items?: HttpToolParam;
     additionalProperties?: boolean;
+    /**
+     * A regular expression the whole value must match (strings only). Checked
+     * before the call; a value that does not match is refused, so what a person
+     * typed cannot change the request it is written into. Patterns that repeat a
+     * repeating group, like `(a+)+`, are refused when saved.
+     *
+     * ```ts
+     * order_number: { type: 'string', required: true, pattern: '[0-9]{1,10}' }
+     * ```
+     */
+    pattern?: string;
+    /** The longest value accepted (strings only). 2000 when a pattern is set
+     *  and this is not. */
+    maxLength?: number;
+}
+/** One check on an HTTP tool's answer: the value at `field` (a dotted path,
+ *  numbers for list positions) must equal `equals`, which may use
+ *  `{{params.NAME}}`. */
+export interface HttpToolMatch {
+    field: string;
+    equals: string;
+    ignoreCase?: boolean;
+}
+/** Something the agent may ask the website page to do, such as add to cart.
+ *  The page carries it out with `window.AgentNava.page.handle(name, fn)`, and
+ *  what `fn` returns goes back to the agent. Only a website chat has a page; in
+ *  any other conversation the agent is told it cannot. */
+export interface PageAction {
+    /** Lowercase letters, digits and `_`; never one of the agent's HTTP tool names. */
+    name: string;
+    /** What it does and when the agent should use it. */
+    description: string;
+    /** What the agent fills in; the page's handler receives these as its argument. */
+    params?: Record<string, HttpToolParam>;
 }
 export interface HttpTool {
     name: string;
@@ -238,6 +275,46 @@ export interface HttpTool {
     params?: Record<string, HttpToolParam>;
     secrets?: string[];
     timeoutMs?: number;
+    /**
+     * Checks on the answer, all of which must pass. If any fails, or the call
+     * answers with an error or a body that is not JSON, the agent gets only
+     * `notFound`, never the answer. Use it for "show an order only when the
+     * number and the email both match":
+     *
+     * ```ts
+     * requireMatch: [
+     *   { field: 'data.orders.nodes.0.name', equals: '#{{params.order_number}}' },
+     *   { field: 'data.orders.nodes.0.email', equals: '{{params.email}}', ignoreCase: true },
+     * ],
+     * notFound: 'No order matches that number and email.',
+     * ```
+     */
+    requireMatch?: HttpToolMatch[];
+    /** What the agent gets when a check fails. Default: "Not found." */
+    notFound?: string;
+    /**
+     * Sign the request in with one of the agent's connections (its `name`)
+     * instead of a stored key. The connection's provider adds a current
+     * credential and keeps it fresh, so the credential never leaves it. The
+     * address must start with `https://` and a written-out host, and that host
+     * must be the connected account's own API; leave out `Authorization`.
+     *
+     * ```ts
+     * { name: 'look_up_order', method: 'POST', signInWith: 'shopify',
+     *   url: 'https://my-store.myshopify.com/admin/api/2026-04/graphql.json', ... }
+     * ```
+     */
+    signInWith?: string;
+    /**
+     * Values the website page supplies for this visitor, used as
+     * `{{pageEncoded.NAME}}` in the address, `{{pageJson.NAME}}` in a JSON body,
+     * or `{{page.NAME}}` for a plain token (letters, digits, `- _ . ~` only).
+     * On the page, the chat script's public call sets them:
+     * `window.AgentNava.page.set('cart_id', value)`. They are kept per
+     * conversation and filled in at call time; the model sees one only if the
+     * API's answer repeats it, and logs redact them. Names: lowercase letters, digits, `_`.
+     */
+    pageValues?: string[];
 }
 /**
  * Guardrails: what the platform enforces on an agent, even when someone tries to
@@ -303,6 +380,8 @@ export interface AgentData {
     triggers: Trigger[];
     mcpServers: McpServer[];
     httpTools: HttpTool[];
+    /** Always a list, empty when the agent has none. */
+    pageActions: PageAction[];
     /** Workspace knowledge bases this agent reads, by key. Always present, empty
      *  when none are attached, so a caller never has to distinguish "none" from
      *  "an older server that did not send the field". */
@@ -361,6 +440,20 @@ export interface AgentStatus {
         name: string;
     }[];
 }
+/**
+ * One of an app's own ready-made tools, as `ws.apps.tools(app)` lists it: what
+ * a connection's `tools` chooses from.
+ */
+export interface AppTool {
+    /** What a connection's `tools` names: `SLACK_SEND_MESSAGE`. */
+    id: string;
+    /** The tool service's name for it: "Send message". */
+    name: string;
+    /** Its description's first sentence. */
+    summary: string;
+    /** It removes something (a message, a file, a record). */
+    deletes?: true;
+}
 /**
  * One of an agent's connections as it stands right now: the account it names,
  * and whether that account works. What `agent.connections.list()` returns.
@@ -384,6 +477,8 @@ export interface ConnectionStatus {
     account?: AccountData;
     /** True when each person talking to the agent signs in with their own. */
     endUser?: true;
+    /** Which of the app's own tools the agent may use; absent for the app's default. */
+    tools?: string[];
     /** Whether the connection works now, as the API reports it. For an agent
      *  creator's account it follows that account's status. */
     status: string;
@@ -600,6 +695,18 @@ export type TurnEvent =
  | {
     type: 'reset';
     text: string;
+}
+/** Sent at the start of a turn, once per name: a secret the agent declared
+ *  for each conversation, and one of its tools uses, has no usable value
+ *  here. `expired`: the value you pushed has run out. `missing`: none was
+ *  given, or the stored secret attached under that name was deleted or no
+ *  longer belongs to this person. The turn still runs; the tool says it
+ *  cannot sign in. Push a fresh value (`ask(text, { secrets })`) and ask
+ *  again. */
+ | {
+    type: 'credential_needed';
+    name: string;
+    reason: 'missing' | 'expired';
 } | {
     type: 'done';
     reply: string;
@@ -788,6 +895,8 @@ export interface AgentFields {
     triggers?: Trigger[];
     mcpServers?: McpServer[];
     httpTools?: HttpTool[];
+    /** Things the agent may ask the website page to do (see PageAction). */
+    pageActions?: PageAction[];
 }
 export interface ProjectFields {
     name?: string;
@@ -905,6 +1014,19 @@ export interface SecretMeta {
      *  it. A secret with one can only be attached to a conversation launched for
      *  that same person. */
     endUserId?: string | null;
+    /** The only hosts a tool may send this key to. Empty until the first tool
+     *  saved with it pins its own host; add one on purpose with
+     *  `secret.setAllowedHosts([...])`. */
+    allowedHosts?: string[];
+    /** Who created it and who last changed its value or hosts: a member's id,
+     *  `api_key:<id>`, or `system`. A tool save that pins its hosts is not a
+     *  change to it. Null on a secret from before these were kept. */
+    createdBy?: string | null;
+    updatedBy?: string | null;
+    /** The same, in words: a member's first name or "API key <name>"; null
+     *  for our own system or someone no longer in the workspace. */
+    createdByName?: string | null;
+    updatedByName?: string | null;
     createdAt?: string;
     updatedAt?: string;
     lastUsedAt?: string | null;
@@ -1012,6 +1134,15 @@ export type DatabaseTestResult = {
         message: string;
     };
 };
+/** An agent as its draft holds it, from `agent.draft()`. */
+export interface AgentDraft {
+    /** An unpublished draft exists. */
+    exists: boolean;
+    /** The draft differs from the live version. */
+    hasUnpublishedChanges: boolean;
+    /** The configuration the draft holds, or the live one when there is no draft. */
+    config: AgentFields;
+}
 /**
  * How an agent's website chat looks (the share link, and the chat the embed
  * script opens on a website). Every setting is optional; one left out keeps the
@@ -1034,4 +1165,17 @@ export interface WebsiteChatAppearance {
     /** Whether the embed script opens the chat when a page loads, on screens
      *  wider than a phone. New agents start `open`; absent means closed. */
     opens?: 'open' | 'closed';
+    /** Up to three short ways in (60 characters each), shown on the chat's
+     *  welcome card before a visitor's first message, such as "Book a visit".
+     *  A tap sends its words as the visitor's message. The Agent Builder writes
+     *  them from the agent's job; without them the card shows the greeting. */
+    starters?: string[];
+    /** `false` hides the "Made with AgentNava" link under the chat; the
+     *  "<name> is an AI assistant." notice always stays. Shown by default.
+     *  Hiding it needs a paid plan (Team and up): on a free plan the update is
+     *  refused with 403 `plan_required`. A workspace a partner app works in whose
+     *  marketplace forbids "powered by" marks (the Wix App Market) may hide it on
+     *  every plan. When a paid plan ends, the link shows again and this choice is
+     *  kept. */
+    showMadeWith?: boolean;
 }

package/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D;AAkB5D;;;mCAGmC;AACnC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC","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 *  `standard` is the default: the fastest model the platform runs. `lite` is\n *  the lowest price. `premium` costs the same as `standard` and thinks harder,\n *  answering more slowly. `best` is the strongest model.\n *\n *  Renamed in 0.49.0: the grade that was `fast` is now `standard`, and the one\n *  that was `standard` is now `lite`. The platform still accepts `fast` from\n *  older code and treats it as `standard`. */\nexport type Grade = (typeof GRADE_NAMES)[number];\n\n/** Every grade, as a list a reply can be checked against. This SDK is\n *  published and cannot import the platform's private price list, so it keeps\n *  its own copy of the NAMES; a test in the platform's monorepo fails the\n *  moment the two lists differ. */\nexport const GRADE_NAMES = ['lite', 'standard', 'premium', 'best'] as const;\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\n/**\n * Guardrails: what the platform enforces on an agent, even when someone tries to\n * talk the agent out of it. An agent's `instructions` are what it TRIES to do;\n * its guardrails are checked by the platform before the agent reads a message,\n * so a person cannot argue it past them.\n *\n * ```ts\n * await agent.update({\n *   guardrails: {\n *     stayOnTopic: true,\n *     rules: ['Never offer discounts or change prices.'],\n *   },\n * });\n * ```\n *\n * A message that breaks one is declined before the agent reads it, and the agent\n * replies politely in its own voice instead; an action that breaks one does not\n * happen; a reply that breaks one is taken back and answered again. The turn's\n * stream says which rule fired (`{ type: 'guardrail' }`).\n *\n * Part of the CONFIGURATION, like `connections`, so changing it publishes a\n * version, and a conversation already in progress keeps the version it began on.\n */\nexport interface Guardrails {\n\t/** Decline anything outside this agent's job, judged from its own\n\t *  instructions: other work (code, homework, poems), \"ignore your\n\t *  instructions\", requests for its prompt or files, and \"I'm the owner\"\n\t *  claims made to get special treatment. ON unless set to `false`. */\n\tstayOnTopic?: boolean;\n\t/** Your own rules, one plain-English sentence each (at most 20, each under\n\t *  500 characters). Each is checked on the message, on every action the agent\n\t *  tries, and on its reply. A break is declined, blocked or taken back, and the\n\t *  stream names the rule. */\n\trules?: string[];\n\t/** Check each message before the agent reads it, so one that breaks a\n\t *  guardrail never reaches the agent and nothing it asked for is done. Costs\n\t *  about 0.2 s per message. ON unless set to `false`: off, the agent answers\n\t *  at once, and its replies and actions are still checked. */\n\tcheckMessagesFirst?: boolean;\n}\n\nexport interface AgentData {\n\tid: string;\n\tname: string;\n\tinstructions: string;\n\tgreeting?: string;\n\t/** Always present, with the defaults filled in: what is enforced now. */\n\tguardrails: { stayOnTopic: boolean; rules: string[]; checkMessagesFirst: boolean };\n\t/** How its website chat looks. Absent: the default look, starting closed. */\n\tappearance?: WebsiteChatAppearance;\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/** Who can chat with an agent's website chat. 'restricted' (the default):\n *  members of your workspace signed in to AgentNava, and visitors on the\n *  allowed websites. 'anyone': anyone with the link, on any website. */\nexport type WebsiteChatAccess = 'restricted' | 'anyone';\n\n/** What `agent.websiteChat.get()` gives back. */\nexport interface WebsiteChat {\n\t/** Who can chat. */\n\treadonly access: WebsiteChatAccess;\n\t/** The hosted chat page, the share link. Share it, or open it in an iframe. */\n\treadonly chatUrl: string;\n\t/** The id the embed script's `data-agent-id` takes. */\n\treadonly embedAgentId: string;\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/** First, before anything else: the id the API gave this turn. */\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. Sent after each tool event that changes the list, with the steps\n\t *  and words the portal shows. */\n\t| { type: 'progress'; steps: Step[] }\n\t/** `name` is the tool's identifier, for code. `label` is what a person sees,\n\t *  the portal's words (\"Searching the web: <query>\"). */\n\t| { type: 'tool'; name: string; state: 'start' | 'end'; label?: string; ok?: boolean }\n\t/** A fragment, not a line. Append; do not assemble. */\n\t| { type: 'text'; text: string }\n\t/** A file the agent wrote in the conversation's drive. Pass `path` to\n\t *  conversation.readFile(). Sent once per file per turn. */\n\t| { type: 'file'; path: string }\n\t/** A widget the agent is drawing inside its reply, sent whole each time it\n\t *  grows: replace the one with the same `surfaceId`. Only on a conversation\n\t *  started with `widgets: true`. */\n\t| { type: 'widget'; widget: Widget }\n\t/** `widgets` is the reply's final widget list, present when it has any:\n\t *  what to keep, whatever arrived live. */\n\t/** One of the agent's guardrails fired. `rule` is the one, as you wrote it,\n\t *  or 'Stay on topic'.\n\t *  - `message`: the person's message broke it and was declined. The agent\n\t *    never read it; the words that follow are its polite refusal.\n\t *  - `reply`: the agent's reply broke it and was taken back (a `reset` came\n\t *    first); the words that follow are its answer within the rule.\n\t *  - `tool`: an action the agent tried (`tool`) broke one of your rules and\n\t *    did not happen; the agent explains in the words that follow. Which rule\n\t *    is not reported for this stage. */\n\t| { type: 'guardrail'; stage: 'message'; rule: string; action: 'declined' }\n\t| { type: 'guardrail'; stage: 'reply'; rule: string; action: 'replaced' }\n\t| { type: 'guardrail'; stage: 'tool'; tool: string; action: 'blocked' }\n\t/** Replace the words you have shown for this reply with `text`, often empty:\n\t *  earlier words were withdrawn (a guardrail) or a step was retried. Clear the\n\t *  reply's widgets too; any that still belong are sent again. */\n\t| { type: 'reset'; text: string }\n\t| { type: 'done'; reply: string; widgets?: Widget[] }\n\t| { type: 'error'; message: string; retryable: boolean };\n\n/**\n * One part of a widget, in Google's open A2UI v0.9 format with AgentNava's own\n * set of parts: an id, which kind of\n * part it is (`Column`, `Row`, `Card`, `Text`, `Stat`, `KeyValue`, `Table`,\n * `Chart`, `Image`, `List`, `Note`, `Badge`, `Link`, `Button`, `Suggestions`,\n * `Divider`), and that kind's props. A container lists its children by id.\n */\nexport interface WidgetPart {\n\tid: string;\n\tcomponent: string;\n\t[prop: string]: unknown;\n}\n\n/**\n * A card, table or chart the agent drew inside a reply. Draw it with `WidgetView`\n * from `@cerebro-labs/agentnava-sdk/react`, or your own components starting\n * from the part with id `root`.\n * `at` is where it sits in the reply's text, as a character count, so it goes\n * between the right sentences.\n */\nexport interface Widget {\n\tsurfaceId: string;\n\tat: number;\n\tcomponents: WidgetPart[];\n\t/** Every part arrived. False only while it streams, or on a reply cut short. */\n\tclosed: boolean;\n}\n\nexport interface Message {\n\trole: 'user' | 'assistant';\n\tcontent: string;\n\tat: string;\n\t/** The widgets in an assistant reply, when it has any. */\n\twidgets?: Widget[];\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\t/** What the platform enforces on every incoming message. See `Guardrails`. */\n\tguardrails?: Guardrails;\n\t/**\n\t * How the agent's website chat looks, on the share link and through the\n\t * embed script. Merged by setting: `{ accent: '#B4532A' }` changes the colour\n\t * and keeps the rest; `null` clears one setting, and `appearance: null` goes\n\t * back to the default look. See `WebsiteChatAppearance`.\n\t */\n\tappearance?: { [K in keyof WebsiteChatAppearance]?: WebsiteChatAppearance[K] | null } | null;\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\t/**\n\t * \"Answer with widgets\": on unless `false`. When on, the agent draws cards,\n\t * tables and charts inside its answers, on a conversation started with\n\t * `widgets: true`. Set `false` for an agent that should answer in text only.\n\t */\n\twidgets?: boolean;\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\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\n/**\n * How an agent's website chat looks (the share link, and the chat the embed\n * script opens on a website). Every setting is optional; one left out keeps the\n * default. Part of the agent's configuration, so a change is published with a\n * version like any other field.\n */\nexport interface WebsiteChatAppearance {\n\t/** An image id from `agent.websiteChat.uploadLogo()`, shown in a circle in\n\t *  the chat's header. Without one, the name's first letter. */\n\tlogo?: string;\n\t/** The name the chat shows, up to 40 characters. Without one, the agent's name. */\n\ttitle?: string;\n\ttheme?: 'light' | 'dark';\n\t/** One colour, written like `#B4532A`: the avatar, the visitor's messages,\n\t *  the send button, chips, prices on cards, and the round button. Where it\n\t *  is too light to read as text, words use a darker shade of it. */\n\taccent?: string;\n\t/** `clean` is the default. */\n\tfont?: 'clean' | 'friendly' | 'classic' | 'elegant';\n\t/** Whether the embed script opens the chat when a page loads, on screens\n\t *  wider than a phone. New agents start `open`; absent means closed. */\n\topens?: 'open' | 'closed';\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D;AAkB5D;;;mCAGmC;AACnC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC","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 *  `standard` is the default: the fastest model the platform runs. `lite` is\n *  the lowest price. `premium` costs the same as `standard` and thinks harder,\n *  answering more slowly. `best` is the strongest model.\n *\n *  Renamed in 0.49.0: the grade that was `fast` is now `standard`, and the one\n *  that was `standard` is now `lite`. The platform still accepts `fast` from\n *  older code and treats it as `standard`. */\nexport type Grade = (typeof GRADE_NAMES)[number];\n\n/** Every grade, as a list a reply can be checked against. This SDK is\n *  published and cannot import the platform's private price list, so it keeps\n *  its own copy of the NAMES; a test in the platform's monorepo fails the\n *  moment the two lists differ. */\nexport const GRADE_NAMES = ['lite', 'standard', 'premium', 'best'] as const;\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\t\t/** Which of the app's own tools the agent may use; absent for the app's default. */\n\t\t\ttools?: string[];\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\t\ttools?: string[];\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\t/**\n\t * A regular expression the whole value must match (strings only). Checked\n\t * before the call; a value that does not match is refused, so what a person\n\t * typed cannot change the request it is written into. Patterns that repeat a\n\t * repeating group, like `(a+)+`, are refused when saved.\n\t *\n\t * ```ts\n\t * order_number: { type: 'string', required: true, pattern: '[0-9]{1,10}' }\n\t * ```\n\t */\n\tpattern?: string;\n\t/** The longest value accepted (strings only). 2000 when a pattern is set\n\t *  and this is not. */\n\tmaxLength?: number;\n}\n\n/** One check on an HTTP tool's answer: the value at `field` (a dotted path,\n *  numbers for list positions) must equal `equals`, which may use\n *  `{{params.NAME}}`. */\nexport interface HttpToolMatch {\n\tfield: string;\n\tequals: string;\n\tignoreCase?: boolean;\n}\n\n/** Something the agent may ask the website page to do, such as add to cart.\n *  The page carries it out with `window.AgentNava.page.handle(name, fn)`, and\n *  what `fn` returns goes back to the agent. Only a website chat has a page; in\n *  any other conversation the agent is told it cannot. */\nexport interface PageAction {\n\t/** Lowercase letters, digits and `_`; never one of the agent's HTTP tool names. */\n\tname: string;\n\t/** What it does and when the agent should use it. */\n\tdescription: string;\n\t/** What the agent fills in; the page's handler receives these as its argument. */\n\tparams?: Record<string, HttpToolParam>;\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\t/**\n\t * Checks on the answer, all of which must pass. If any fails, or the call\n\t * answers with an error or a body that is not JSON, the agent gets only\n\t * `notFound`, never the answer. Use it for \"show an order only when the\n\t * number and the email both match\":\n\t *\n\t * ```ts\n\t * requireMatch: [\n\t *   { field: 'data.orders.nodes.0.name', equals: '#{{params.order_number}}' },\n\t *   { field: 'data.orders.nodes.0.email', equals: '{{params.email}}', ignoreCase: true },\n\t * ],\n\t * notFound: 'No order matches that number and email.',\n\t * ```\n\t */\n\trequireMatch?: HttpToolMatch[];\n\t/** What the agent gets when a check fails. Default: \"Not found.\" */\n\tnotFound?: string;\n\t/**\n\t * Sign the request in with one of the agent's connections (its `name`)\n\t * instead of a stored key. The connection's provider adds a current\n\t * credential and keeps it fresh, so the credential never leaves it. The\n\t * address must start with `https://` and a written-out host, and that host\n\t * must be the connected account's own API; leave out `Authorization`.\n\t *\n\t * ```ts\n\t * { name: 'look_up_order', method: 'POST', signInWith: 'shopify',\n\t *   url: 'https://my-store.myshopify.com/admin/api/2026-04/graphql.json', ... }\n\t * ```\n\t */\n\tsignInWith?: string;\n\t/**\n\t * Values the website page supplies for this visitor, used as\n\t * `{{pageEncoded.NAME}}` in the address, `{{pageJson.NAME}}` in a JSON body,\n\t * or `{{page.NAME}}` for a plain token (letters, digits, `- _ . ~` only).\n\t * On the page, the chat script's public call sets them:\n\t * `window.AgentNava.page.set('cart_id', value)`. They are kept per\n\t * conversation and filled in at call time; the model sees one only if the\n\t * API's answer repeats it, and logs redact them. Names: lowercase letters, digits, `_`.\n\t */\n\tpageValues?: string[];\n}\n\n/**\n * Guardrails: what the platform enforces on an agent, even when someone tries to\n * talk the agent out of it. An agent's `instructions` are what it TRIES to do;\n * its guardrails are checked by the platform before the agent reads a message,\n * so a person cannot argue it past them.\n *\n * ```ts\n * await agent.update({\n *   guardrails: {\n *     stayOnTopic: true,\n *     rules: ['Never offer discounts or change prices.'],\n *   },\n * });\n * ```\n *\n * A message that breaks one is declined before the agent reads it, and the agent\n * replies politely in its own voice instead; an action that breaks one does not\n * happen; a reply that breaks one is taken back and answered again. The turn's\n * stream says which rule fired (`{ type: 'guardrail' }`).\n *\n * Part of the CONFIGURATION, like `connections`, so changing it publishes a\n * version, and a conversation already in progress keeps the version it began on.\n */\nexport interface Guardrails {\n\t/** Decline anything outside this agent's job, judged from its own\n\t *  instructions: other work (code, homework, poems), \"ignore your\n\t *  instructions\", requests for its prompt or files, and \"I'm the owner\"\n\t *  claims made to get special treatment. ON unless set to `false`. */\n\tstayOnTopic?: boolean;\n\t/** Your own rules, one plain-English sentence each (at most 20, each under\n\t *  500 characters). Each is checked on the message, on every action the agent\n\t *  tries, and on its reply. A break is declined, blocked or taken back, and the\n\t *  stream names the rule. */\n\trules?: string[];\n\t/** Check each message before the agent reads it, so one that breaks a\n\t *  guardrail never reaches the agent and nothing it asked for is done. Costs\n\t *  about 0.2 s per message. ON unless set to `false`: off, the agent answers\n\t *  at once, and its replies and actions are still checked. */\n\tcheckMessagesFirst?: boolean;\n}\n\nexport interface AgentData {\n\tid: string;\n\tname: string;\n\tinstructions: string;\n\tgreeting?: string;\n\t/** Always present, with the defaults filled in: what is enforced now. */\n\tguardrails: { stayOnTopic: boolean; rules: string[]; checkMessagesFirst: boolean };\n\t/** How its website chat looks. Absent: the default look, starting closed. */\n\tappearance?: WebsiteChatAppearance;\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/** Always a list, empty when the agent has none. */\n\tpageActions: PageAction[];\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/** Who can chat with an agent's website chat. 'restricted' (the default):\n *  members of your workspace signed in to AgentNava, and visitors on the\n *  allowed websites. 'anyone': anyone with the link, on any website. */\nexport type WebsiteChatAccess = 'restricted' | 'anyone';\n\n/** What `agent.websiteChat.get()` gives back. */\nexport interface WebsiteChat {\n\t/** Who can chat. */\n\treadonly access: WebsiteChatAccess;\n\t/** The hosted chat page, the share link. Share it, or open it in an iframe. */\n\treadonly chatUrl: string;\n\t/** The id the embed script's `data-agent-id` takes. */\n\treadonly embedAgentId: string;\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 app's own ready-made tools, as `ws.apps.tools(app)` lists it: what\n * a connection's `tools` chooses from.\n */\nexport interface AppTool {\n\t/** What a connection's `tools` names: `SLACK_SEND_MESSAGE`. */\n\tid: string;\n\t/** The tool service's name for it: \"Send message\". */\n\tname: string;\n\t/** Its description's first sentence. */\n\tsummary: string;\n\t/** It removes something (a message, a file, a record). */\n\tdeletes?: true;\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/** Which of the app's own tools the agent may use; absent for the app's default. */\n\ttools?: string[];\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/** First, before anything else: the id the API gave this turn. */\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. Sent after each tool event that changes the list, with the steps\n\t *  and words the portal shows. */\n\t| { type: 'progress'; steps: Step[] }\n\t/** `name` is the tool's identifier, for code. `label` is what a person sees,\n\t *  the portal's words (\"Searching the web: <query>\"). */\n\t| { type: 'tool'; name: string; state: 'start' | 'end'; label?: string; ok?: boolean }\n\t/** A fragment, not a line. Append; do not assemble. */\n\t| { type: 'text'; text: string }\n\t/** A file the agent wrote in the conversation's drive. Pass `path` to\n\t *  conversation.readFile(). Sent once per file per turn. */\n\t| { type: 'file'; path: string }\n\t/** A widget the agent is drawing inside its reply, sent whole each time it\n\t *  grows: replace the one with the same `surfaceId`. Only on a conversation\n\t *  started with `widgets: true`. */\n\t| { type: 'widget'; widget: Widget }\n\t/** `widgets` is the reply's final widget list, present when it has any:\n\t *  what to keep, whatever arrived live. */\n\t/** One of the agent's guardrails fired. `rule` is the one, as you wrote it,\n\t *  or 'Stay on topic'.\n\t *  - `message`: the person's message broke it and was declined. The agent\n\t *    never read it; the words that follow are its polite refusal.\n\t *  - `reply`: the agent's reply broke it and was taken back (a `reset` came\n\t *    first); the words that follow are its answer within the rule.\n\t *  - `tool`: an action the agent tried (`tool`) broke one of your rules and\n\t *    did not happen; the agent explains in the words that follow. Which rule\n\t *    is not reported for this stage. */\n\t| { type: 'guardrail'; stage: 'message'; rule: string; action: 'declined' }\n\t| { type: 'guardrail'; stage: 'reply'; rule: string; action: 'replaced' }\n\t| { type: 'guardrail'; stage: 'tool'; tool: string; action: 'blocked' }\n\t/** Replace the words you have shown for this reply with `text`, often empty:\n\t *  earlier words were withdrawn (a guardrail) or a step was retried. Clear the\n\t *  reply's widgets too; any that still belong are sent again. */\n\t| { type: 'reset'; text: string }\n\t/** Sent at the start of a turn, once per name: a secret the agent declared\n\t *  for each conversation, and one of its tools uses, has no usable value\n\t *  here. `expired`: the value you pushed has run out. `missing`: none was\n\t *  given, or the stored secret attached under that name was deleted or no\n\t *  longer belongs to this person. The turn still runs; the tool says it\n\t *  cannot sign in. Push a fresh value (`ask(text, { secrets })`) and ask\n\t *  again. */\n\t| { type: 'credential_needed'; name: string; reason: 'missing' | 'expired' }\n\t| { type: 'done'; reply: string; widgets?: Widget[] }\n\t| { type: 'error'; message: string; retryable: boolean };\n\n/**\n * One part of a widget, in Google's open A2UI v0.9 format with AgentNava's own\n * set of parts: an id, which kind of\n * part it is (`Column`, `Row`, `Card`, `Text`, `Stat`, `KeyValue`, `Table`,\n * `Chart`, `Image`, `List`, `Note`, `Badge`, `Link`, `Button`, `Suggestions`,\n * `Divider`), and that kind's props. A container lists its children by id.\n */\nexport interface WidgetPart {\n\tid: string;\n\tcomponent: string;\n\t[prop: string]: unknown;\n}\n\n/**\n * A card, table or chart the agent drew inside a reply. Draw it with `WidgetView`\n * from `@cerebro-labs/agentnava-sdk/react`, or your own components starting\n * from the part with id `root`.\n * `at` is where it sits in the reply's text, as a character count, so it goes\n * between the right sentences.\n */\nexport interface Widget {\n\tsurfaceId: string;\n\tat: number;\n\tcomponents: WidgetPart[];\n\t/** Every part arrived. False only while it streams, or on a reply cut short. */\n\tclosed: boolean;\n}\n\nexport interface Message {\n\trole: 'user' | 'assistant';\n\tcontent: string;\n\tat: string;\n\t/** The widgets in an assistant reply, when it has any. */\n\twidgets?: Widget[];\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\t/** What the platform enforces on every incoming message. See `Guardrails`. */\n\tguardrails?: Guardrails;\n\t/**\n\t * How the agent's website chat looks, on the share link and through the\n\t * embed script. Merged by setting: `{ accent: '#B4532A' }` changes the colour\n\t * and keeps the rest; `null` clears one setting, and `appearance: null` goes\n\t * back to the default look. See `WebsiteChatAppearance`.\n\t */\n\tappearance?: { [K in keyof WebsiteChatAppearance]?: WebsiteChatAppearance[K] | null } | null;\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\t/**\n\t * \"Answer with widgets\": on unless `false`. When on, the agent draws cards,\n\t * tables and charts inside its answers, on a conversation started with\n\t * `widgets: true`. Set `false` for an agent that should answer in text only.\n\t */\n\twidgets?: boolean;\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\t/** Things the agent may ask the website page to do (see PageAction). */\n\tpageActions?: PageAction[];\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\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\t/** The only hosts a tool may send this key to. Empty until the first tool\n\t *  saved with it pins its own host; add one on purpose with\n\t *  `secret.setAllowedHosts([...])`. */\n\tallowedHosts?: string[];\n\t/** Who created it and who last changed its value or hosts: a member's id,\n\t *  `api_key:<id>`, or `system`. A tool save that pins its hosts is not a\n\t *  change to it. Null on a secret from before these were kept. */\n\tcreatedBy?: string | null;\n\tupdatedBy?: string | null;\n\t/** The same, in words: a member's first name or \"API key <name>\"; null\n\t *  for our own system or someone no longer in the workspace. */\n\tcreatedByName?: string | null;\n\tupdatedByName?: 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\n/** An agent as its draft holds it, from `agent.draft()`. */\nexport interface AgentDraft {\n\t/** An unpublished draft exists. */\n\texists: boolean;\n\t/** The draft differs from the live version. */\n\thasUnpublishedChanges: boolean;\n\t/** The configuration the draft holds, or the live one when there is no draft. */\n\tconfig: AgentFields;\n}\n\n/**\n * How an agent's website chat looks (the share link, and the chat the embed\n * script opens on a website). Every setting is optional; one left out keeps the\n * default. Part of the agent's configuration, so a change is published with a\n * version like any other field.\n */\nexport interface WebsiteChatAppearance {\n\t/** An image id from `agent.websiteChat.uploadLogo()`, shown in a circle in\n\t *  the chat's header. Without one, the name's first letter. */\n\tlogo?: string;\n\t/** The name the chat shows, up to 40 characters. Without one, the agent's name. */\n\ttitle?: string;\n\ttheme?: 'light' | 'dark';\n\t/** One colour, written like `#B4532A`: the avatar, the visitor's messages,\n\t *  the send button, chips, prices on cards, and the round button. Where it\n\t *  is too light to read as text, words use a darker shade of it. */\n\taccent?: string;\n\t/** `clean` is the default. */\n\tfont?: 'clean' | 'friendly' | 'classic' | 'elegant';\n\t/** Whether the embed script opens the chat when a page loads, on screens\n\t *  wider than a phone. New agents start `open`; absent means closed. */\n\topens?: 'open' | 'closed';\n\t/** Up to three short ways in (60 characters each), shown on the chat's\n\t *  welcome card before a visitor's first message, such as \"Book a visit\".\n\t *  A tap sends its words as the visitor's message. The Agent Builder writes\n\t *  them from the agent's job; without them the card shows the greeting. */\n\tstarters?: string[];\n\t/** `false` hides the \"Made with AgentNava\" link under the chat; the\n\t *  \"<name> is an AI assistant.\" notice always stays. Shown by default.\n\t *  Hiding it needs a paid plan (Team and up): on a free plan the update is\n\t *  refused with 403 `plan_required`. A workspace a partner app works in whose\n\t *  marketplace forbids \"powered by\" marks (the Wix App Market) may hide it on\n\t *  every plan. When a paid plan ends, the link shows again and this choice is\n\t *  kept. */\n\tshowMadeWith?: boolean;\n}\n"]}

package/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.53.2";
+export declare const SDK_VERSION = "0.75.0";

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.53.2';
+export const SDK_VERSION = '0.75.0';
 //# 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.53.2';\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.75.0';\n"]}

package/workspace.d.ts

@@ -1,4 +1,5 @@
 import { Account } from './account.ts';
+import { PartnerApp, type PartnerAppOptions } from './partner-app.ts';
 import { Agent } from './agent.ts';
 import type { AppId } from './apps.generated.ts';
 import { type ClientOptions } from './http.ts';
@@ -7,7 +8,7 @@ import { EndUser } from './end-user.ts';
 import { Database } from './database.ts';
 import { KnowledgeBase } from './knowledge-base.ts';
 import { Project } from './project.ts';
-import type { AgentFields, Credits, DatabaseFields, DatabaseLogin, DatabaseTestResult, ProjectFields, SeatPlan, WorkspaceInfo, WorkspaceMember } from './types.ts';
+import type { AppTool, AgentFields, Credits, DatabaseFields, DatabaseLogin, DatabaseTestResult, ProjectFields, SeatPlan, WorkspaceInfo, WorkspaceMember } from './types.ts';
 /**
  * Your workspace: the account an API key names.
  *
@@ -83,6 +84,11 @@ export declare class Workspace {
              *
              *  `conversation.attach(secret)` is the route that was missing. */
             endUserId?: string;
+            /** The only hosts a tool may send this key to, like
+             *  `["api.example.com"]`. Left out, the first tool saved with it pins
+             *  its own host, and a tool sending it anywhere else is refused with
+             *  SecretHostNotAllowed. */
+            allowedHosts?: string[];
         }) => Promise<Secret>;
         /** Every secret this WORKSPACE holds, values excluded. Pass `agentId` to
          *  include that agent's own secrets alongside the workspace ones.
@@ -132,6 +138,21 @@ export declare class Workspace {
             app?: AppId;
         }) => Promise<Account[]>;
     };
+    /**
+     * The apps an agent can connect, and each one's own ready-made tools: what a
+     * connection's `tools` chooses from.
+     *
+     * ```ts
+     * const tools = await ws.apps.tools(App.SLACK);
+     * const send = tools.find((t) => t.name === 'Send message');
+     * await agent.connections.change('slack', { tools: [send!.id] });
+     * ```
+     */
+    readonly apps: {
+        /** One app's current tools, the common ones first. A tool marked `deletes`
+         *  removes something; leave those out unless the agent needs them. */
+        tools: (app: AppId) => Promise<AppTool[]>;
+    };
     /**
      * Knowledge bases: named folders of files your agents read.
      *
@@ -188,6 +209,17 @@ export declare class Workspace {
          *  `db.delete()`. */
         get: (key: string) => Promise<Database>;
     };
+    /**
+     * Whether this workspace's agents may call outside services. `'off'` refuses
+     * every HTTP tool and leaves out web search and opening web pages, on every
+     * agent, from their next call or turn. MCP servers and connections are not
+     * covered yet. Anyone can read it; only an owner or admin, signed in, can
+     * change it (an API key gets 403).
+     */
+    readonly outsideCalls: {
+        get: () => Promise<"on" | "off">;
+        set: (value: "on" | "off") => Promise<"on" | "off">;
+    };
     readonly projects: {
         create: (fields: ProjectFields) => Promise<Project>;
         list: () => Promise<Project[]>;
@@ -305,4 +337,6 @@ export declare class Workspace {
  */
 export declare const AgentNava: {
     getWorkspace(options?: string | ClientOptions): Workspace;
+    /** For a partner app's server: Sign in with AgentNava, then a workspace key (partner-app.ts). */
+    partnerApp(options: PartnerAppOptions): PartnerApp;
 };

package/workspace.js

@@ -1,6 +1,7 @@
 // The entry point. `AgentNava.getWorkspace()` is a workspace, because an API key already
 // names one: there is nothing to select and nothing to pass.
 import { Account, accountIn } from "./account.js";
+import { PartnerApp } from "./partner-app.js";
 import { Agent } from "./agent.js";
 import { Http } from "./http.js";
 import { Secret } from "./secret.js";
@@ -92,6 +93,7 @@ export class Workspace {
                 ...(input.description !== undefined && { description: input.description }),
                 ...(input.agentId !== undefined && { agentId: input.agentId }),
                 ...(input.endUserId !== undefined && { endUserId: input.endUserId }),
+                ...(input.allowedHosts !== undefined && { allowedHosts: input.allowedHosts }),
             });
             const meta = res.secret ?? res;
             return new Secret(this.#http, meta.id, meta);
@@ -155,6 +157,24 @@ export class Workspace {
             return (res.accounts ?? []).map((a) => new Account(this.#http, a.id, a));
         },
     };
+    /**
+     * The apps an agent can connect, and each one's own ready-made tools: what a
+     * connection's `tools` chooses from.
+     *
+     * ```ts
+     * const tools = await ws.apps.tools(App.SLACK);
+     * const send = tools.find((t) => t.name === 'Send message');
+     * await agent.connections.change('slack', { tools: [send!.id] });
+     * ```
+     */
+    apps = {
+        /** One app's current tools, the common ones first. A tool marked `deletes`
+         *  removes something; leave those out unless the agent needs them. */
+        tools: async (app) => {
+            const res = await this.#http.get(`/v1/connections/apps/${encodeURIComponent(app)}/tools`);
+            return res.tools ?? [];
+        },
+    };
     /**
      * Knowledge bases: named folders of files your agents read.
      *
@@ -225,6 +245,17 @@ export class Workspace {
             return new Database(this.#http, res.database.key, res.database);
         },
     };
+    /**
+     * Whether this workspace's agents may call outside services. `'off'` refuses
+     * every HTTP tool and leaves out web search and opening web pages, on every
+     * agent, from their next call or turn. MCP servers and connections are not
+     * covered yet. Anyone can read it; only an owner or admin, signed in, can
+     * change it (an API key gets 403).
+     */
+    outsideCalls = {
+        get: async () => (await this.#http.get('/v1/workspace/outside-calls')).outsideCalls,
+        set: async (value) => (await this.#http.put('/v1/workspace/outside-calls', { outsideCalls: value })).outsideCalls,
+    };
     projects = {
         create: async (fields) => {
             const data = toProjectData(await this.#http.post('/v1/projects', fields));
@@ -403,5 +434,9 @@ export const AgentNava = {
     getWorkspace(options = {}) {
         return new Workspace(typeof options === 'string' ? { apiKey: options } : options);
     },
+    /** For a partner app's server: Sign in with AgentNava, then a workspace key (partner-app.ts). */
+    partnerApp(options) {
+        return new PartnerApp(options);
+    },
 };
 //# sourceMappingURL=workspace.js.map