@cerebro-labs/agentnava-sdk 0.26.0 → 0.46.1

package/types.d.ts

@@ -1,20 +1,24 @@
-export type Grade = 'standard' | 'premium';
+import type { AppId } from './apps.generated.ts';
+import type { Connection } from './connection.ts';
+/** The quality of model an agent's turns run on, and what each turn costs.
+ *
+ *  `fast` is the one that surprises people: it buys LATENCY rather than
+ *  capability, runs a smaller model on silicon built for time-to-first-token,
+ *  and costs MORE than `premium` while being less capable. Pick it for voice
+ *  and interactive agents, not to save money. `best` is the strongest model. */
+export type Grade = 'standard' | 'premium' | 'fast' | 'best';
 export type Filesystem = 'drive' | 'none';
-/** Where a credential is supplied.
+/** Where a SECRET is supplied.
  *
  *  'fixed' is set once on the agent and used by every conversation. 'conversation'
  *  is asked for when a conversation starts, so each user brings their own. The
- *  two DO NOT substitute for each other: an account connected on the agent does
- *  not satisfy a declaration scoped 'conversation'. */
-export type Scope = 'fixed' | 'conversation';
-/** WHOSE credential a stored account or value is, which is a different question
- *  from `Scope` above. `Scope` is what an agent DECLARES it needs; this is who
- *  a row that exists actually belongs to.
+ *  two DO NOT substitute for each other: a value set on the agent does not
+ *  satisfy a declaration scoped 'conversation'.
  *
- *  'endUser' is one of YOUR end users: the person your application serves,
- *  never a member of this workspace. The two are separate populations with
- *  separate id namespaces: see `EndUser`. */
-export type CredentialOwner = 'workspace' | 'agent' | 'endUser' | 'conversation';
+ *  Connections stopped using this in 0.44. A connection says WHOSE ACCOUNT it
+ *  uses instead: the agent creator's (`account`) or each end user's own
+ *  (`endUser: true`). See `AgentConnection`. */
+export type Scope = 'fixed' | 'conversation';
 export interface WorkspaceInfo {
     id: string;
     name: string;
@@ -31,37 +35,160 @@ export interface Workflow {
 }
 export type Trigger = {
     kind: 'chat';
-} | {
+} | ({
     kind: 'schedule';
+    enabled?: boolean;
     cron: string;
     timezone?: string;
     message: string;
-} | {
+} & TriggerTarget) | {
     kind: 'interval';
     seconds: number;
     maxRuns?: number;
     message: string;
-} | {
+} | ({
     kind: 'webhook';
     message?: string;
+    /**
+     * Where your system POSTs, set by the platform. Read it from the agent
+     * that `setTriggers()` returns: `agent.data?.triggers`. Anything you
+     * send here is ignored, so passing back a list you read is safe and
+     * keeps the same URL. One webhook per agent; `rotateWebhookUrl()`
+     * replaces the URL.
+     */
     url?: string;
-};
+    /**
+     * Check WHO sent each delivery, beyond knowing the URL. See
+     * WebhookVerify for the schemes and an example. Leave it out to keep
+     * what the webhook has. The secret is stored encrypted and never read
+     * back: a read says `secretSet: true` instead.
+     */
+    verify?: WebhookVerify;
+} & TriggerTarget);
 /**
- * What an agent NEEDS, not what it has.
+ * How a webhook checks its sender. Platforms that send webhooks sign every
+ * delivery with a secret they show you when you add the URL there; give it
+ * here, and a delivery whose signature does not match is refused (401) and
+ * never runs the agent.
  *
- * Named `Connection` until the actual account became an object you hold. Two
- * different things cannot share one name: this one says "this agent requires
- * Gmail, supplied per conversation", and says nothing about whether anybody has
- * connected. `Connection` is the account itself, with tokens behind it.
+ * ```ts
+ * { kind: 'webhook', verify: { kind: 'stripe', secret: 'whsec_...' } }
+ * { kind: 'webhook', verify: { kind: 'header', header: 'X-Webhook-Secret', secret: '...' } }
+ * ```
  *
- * The distinction is the one `ConnectionStatus.declared` versus `.connected`
- * already draws, now in the type names too.
+ * The schemes: `stripe`, `github`, `shopify`, `slack` and
+ * `standard` (the Standard Webhooks spec) check that platform's signature;
+ * `header` checks a header your sender adds (Zapier, Make, n8n, your own code
+ * can all add one); `none` relies on the URL alone.
  */
-export interface ConnectionRequirement {
-    provider: string;
-    scope: Scope;
-    required?: boolean;
+export type WebhookVerify = {
+    kind: 'none';
+} | {
+    kind: 'stripe' | 'github' | 'shopify' | 'slack' | 'standard';
+    secret?: string;
+    secretSet?: boolean;
+} | {
+    kind: 'header';
+    header: string;
+    secret?: string;
+    secretSet?: boolean;
+};
+/** One delivery a webhook received, newest first from `agent.webhookDeliveries()`. */
+export interface WebhookDelivery {
+    id: string;
+    receivedAt: string;
+    /** `pending`: checked and starting. `repeat`: the sender retried a delivery
+     *  already accepted; the agent did not run again. */
+    outcome: 'pending' | 'accepted' | 'refused' | 'repeat' | 'test';
+    /** Why it was refused. */
+    reason?: string;
+    /** The sender's own id for it, when it gave one. */
+    deliveryId?: string;
+    /** The conversation it ran in. */
+    conversationId?: string;
 }
+/**
+ * WHERE a schedule or webhook runs. Name a conversation, or an end user, or
+ * neither; never both.
+ *
+ * ```ts
+ * const conversation = await agent.start({ endUserId: 'ops-app' });
+ * await agent.setTriggers([
+ *   { kind: 'chat' },
+ *   // Every firing lands in THIS conversation: its history, its drive.
+ *   { kind: 'schedule', cron: '0 15 * * *', message: 'REFRESH', conversationId: conversation.id },
+ * ]);
+ * ```
+ */
+export type TriggerTarget = {
+    /**
+     * The conversation every firing CONTINUES: it sees that conversation's
+     * history and its drive, and its end user comes with it. Each firing
+     * also moves the conversation to the agent's latest version, so a fix
+     * you publish reaches it.
+     *
+     * This is the ONLY way a trigger continues one of your conversations.
+     * One end user can have many, so naming the end user cannot say which.
+     *
+     * Must be a conversation of this agent, started for one of your end
+     * users (the id `agent.start()` returned). Anything else is refused
+     * when you set the trigger. If the conversation is deleted later, the
+     * firings fail and say so; none is opened in its place.
+     */
+    conversationId: string;
+    userId?: undefined;
+} | {
+    conversationId?: undefined;
+    /**
+     * The end user each firing is for, when it names no conversation. Each
+     * firing STARTS A NEW CONVERSATION for them, with an empty drive, and it
+     * is listed by `agent.conversations({ endUser })`. To keep adding to
+     * one conversation instead, name it with `conversationId`.
+     *
+     * Your id, as in `agent.start({ endUserId })`; the platform's prefixes
+     * (`member:`, `visitor:`, `job:`) are refused.
+     *
+     * Name neither and the trigger keeps one conversation of its own that
+     * every firing continues.
+     */
+    userId?: string;
+};
+/**
+ * One connection in an agent's setup, as it reads back: a NAME, an APP, and
+ * WHOSE ACCOUNT. Exactly one of these two:
+ *
+ * | the connection says | whose account | the person signs in |
+ * |---|---|---|
+ * | `account: '<id>'` | the agent creator's: one account in this workspace, from `ws.accounts.connect()` | once, and every conversation uses it |
+ * | `endUser: true` | the end user's: each person talking to the agent | once each, remembered for them |
+ *
+ * A turn uses EXACTLY the account the setup names, and never another one.
+ * There is no fallback to some other account of the same app: an account that
+ * is not signed in leaves the connection unavailable, and the agent says so.
+ *
+ * `name` tells two connections of one app apart, such as `work-gmail` and
+ * `personal-gmail`. 1 to 64 characters, lowercase letters, digits and dashes,
+ * no dash at either end, unique on the agent. Left out when sent, it is the
+ * app's id.
+ *
+ * Part of the agent's CONFIGURATION, so changing a connection publishes a
+ * version. The account itself is not versioned: signing in again reaches every
+ * agent that names it. To send one, build it with `Connection.creatorAccount()`
+ * or `Connection.endUserAccount()`.
+ */
+export type AgentConnection = {
+    name: string;
+    /** The app's id: `App.GMAIL` is `'gmail'`. */
+    app: AppId;
+    /** An account id in this workspace whose app is `app`. */
+    account: string;
+    endUser?: never;
+} | {
+    name: string;
+    app: AppId;
+    endUser: true;
+    account?: never;
+};
 /** What an agent NEEDS, not the stored value. `Secret` is the value. */
 export interface SecretRequirement {
     name: string;
@@ -83,10 +210,15 @@ export interface McpServer {
     timeoutMs?: number;
 }
 export interface HttpToolParam {
-    type: 'string' | 'number' | 'boolean';
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
     description?: string;
     required?: boolean;
-    choices?: (string | number)[];
+    choices?: (string | number | boolean | null)[];
+    nullable?: boolean;
+    integer?: boolean;
+    properties?: Record<string, HttpToolParam>;
+    items?: HttpToolParam;
+    additionalProperties?: boolean;
 }
 export interface HttpTool {
     name: string;
@@ -108,7 +240,8 @@ export interface AgentData {
     filesystem: Filesystem;
     tools: string[];
     workflows: Workflow[];
-    connections: ConnectionRequirement[];
+    /** The apps it uses, each saying whose account. See `AgentConnection`. */
+    connections: AgentConnection[];
     secrets: SecretRequirement[];
     parameters: Parameter[];
     triggers: Trigger[];
@@ -118,59 +251,163 @@ export interface AgentData {
      *  when none are attached, so a caller never has to distinguish "none" from
      *  "an older server that did not send the field". */
     knowledgeBases: string[];
+    /** Workspace databases this agent may query, by key. Always present, like
+     *  `knowledgeBases`. */
+    databases: string[];
     version: number;
     createdAt: string;
     updatedAt: string;
+    /** Where it is live, as the portal shows it. The API works it out by the
+     *  same rule it runs the agent by, so `channels.api === 'on'` is exactly
+     *  "a turn will be taken". Read-only: nothing sets it. Sent by `agent.get()`
+     *  and `ws.agents.list()`; absent from what create and update return, so
+     *  call `get()` for it. */
+    readonly status?: AgentStatus;
+}
+/** What `agent.websiteChat.turnOn()` gives back: what to put on a website. */
+export interface WebsiteChat {
+    /** The hosted chat page. Share it, or open it in an iframe. */
+    readonly chatUrl: string;
+    /** The publishable token for the embed script. Safe in a public web page:
+     *  it can only talk to this one agent. Your API key never goes there. */
+    readonly publicToken: string;
+    /** The id the embed script's `data-agent-id` takes. */
+    readonly embedAgentId: string;
+    /** The version the website chat serves from now on. */
+    readonly versionNumber: number;
+}
+/** Where an agent is live. See `AgentData.status`. */
+export interface AgentStatus {
+    /** True when any channel is on. */
+    readonly live: boolean;
+    /** Paused by its owner: nothing runs it until it is resumed. */
+    readonly paused: boolean;
+    /** Archived: nothing runs it again. */
+    readonly archived: boolean;
+    readonly channels: {
+        /** 'on' when the API takes new turns for it. */
+        readonly api: 'on' | 'off';
+        /** 'on' when its website chat page answers visitors. 'unavailable' when it
+         *  needs what each user brings (`eachUserBrings`), which a visitor cannot. */
+        readonly websiteChat: 'on' | 'off' | 'unavailable';
+    };
+    /** Required accounts and secrets of its own that are not set up yet, on the
+     *  version a new conversation runs. It still runs: the tools that use them
+     *  fail until they are set up. Empty when nothing is missing. */
+    readonly needs: readonly {
+        kind: 'connection' | 'secret';
+        name: string;
+    }[];
+    /** The accounts and secrets each user supplies for themselves. */
+    readonly eachUserBrings: readonly {
+        kind: 'connection' | 'secret';
+        name: string;
+    }[];
 }
-/** Whether a provider is actually usable right now, as opposed to declared.
+/**
+ * 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.
+ *
+ * DECLARED IS NOT CONNECTED, and this is the read that tells them apart. A
+ * connection can name an account nobody has finished signing in to, or one that
+ * was disconnected since; that is the state a setup checklist has to show, and
+ * without this the only way to find it is to start a conversation and watch
+ * the agent fail.
  *
- *  `declared` and `connected` are separate on purpose: an agent can declare
- *  HubSpot and have nobody connected, which is the state worth showing on a
- *  setup checklist. */
+ * Reshaped in 0.44: it used to be keyed by `provider`, with `declared`,
+ * `required`, `scope` and `suppliedBy`. A connection is now keyed by its
+ * `name`, and it says whose account it uses instead of where one might come
+ * from.
+ */
 export interface ConnectionStatus {
-    /** The connection row's id, which `disconnect()` revokes by. */
-    id?: string;
-    provider: string;
-    /** 'connected' once the account is attached; anything else means it is not
-     *  usable yet. `connected` below is the boolean form of this. */
-    status?: string;
-    /** The conversation this account belongs to, or null for the agent's shared
-     *  account. `scope` and `suppliedBy` are both derived from it. */
-    conversationId?: string | null;
-    /** The agent this account belongs to. */
-    agentId?: string | null;
-    /** One of YOUR end users, when the account is theirs. Their id, from your
-     *  database, never a workspace member's. Null on a shared account. */
-    endUserId?: string | null;
-    /** Whether the AGENT DECLARES it needs this provider, and whether it is
-     *  mandatory.
-     *
-     *  OPTIONAL because only one of the two endpoints can answer. `agent
-     *  .connections()` reads the MERGED view (`/v1/agents/<id>/connections`),
-     *  where the server has joined the agent's declarations against the live
-     *  rows, and both are real there. `ws.connections.list()` and
-     *  `endUser(id).connections.list()` read raw rows (`/v1/connections`), which
-     *  know nothing about any agent's configuration, so both are absent.
-     *
-     *  They used to be declared as required booleans, which meant the raw-row
-     *  paths had to invent them. They were filled with the constants `true` and
-     *  `false`, so every row claimed to be declared and none claimed to be
-     *  required. Absent is the honest answer, and undefined reads as "this
-     *  endpoint cannot tell you" rather than as "no". */
-    declared?: boolean;
-    required?: boolean;
-    /** What the agent DECLARED it needs. Whose account this actually is, is
-     *  `owner`, and the two are not the same question. */
-    scope?: Scope;
-    /** Whose account this is. Derived from which of the three id fields above
-     *  is set, so it is correct even on a server that does not send it. */
-    owner?: CredentialOwner;
-    connected: boolean;
-    /** Which of the three scopes supplied the account. 'endUser' is one of YOUR
-     *  users, whose account outlives any single conversation. */
-    suppliedBy?: 'conversation' | 'agent' | 'endUser' | 'workspace';
-    accountLabel?: string;
-    error?: string;
+    name: string;
+    app: AppId;
+    /** The agent creator's account the connection names, read fresh. Absent on
+     *  an end user's connection, and on one whose account is gone. */
+    account?: AccountData;
+    /** True when each person talking to the agent signs in with their own. */
+    endUser?: true;
+    /** Whether the connection works now, as the API reports it. For an agent
+     *  creator's account it follows that account's status. */
+    status: string;
+    /** Only in the agent's unpublished draft, so no conversation uses it yet. */
+    inDraft: boolean;
+    /** Removed in the agent's unpublished draft, and still used until the draft
+     *  is published. */
+    removedInDraft: boolean;
+}
+/** Where one account's sign-in stands.
+ *
+ *   'pending'        made, and nobody has finished signing in yet
+ *   'connected'      signed in and working
+ *   'needs_sign_in'  it worked, and the app now wants the person to sign in again
+ *   'error'          the app refused it for another reason
+ */
+export type AccountStatus = 'pending' | 'connected' | 'needs_sign_in' | 'error';
+/** An agent whose setup names an account, and the connection that names it.
+ *  Counted from the agent's latest published version and its draft, never
+ *  from older versions. */
+export interface UsedBy {
+    /** The agent's id: the same value as `Agent.id`, so compare this one. */
+    id: string;
+    /** AgentNava's internal handle for the same agent (`agt_...`), not `Agent.id`. */
+    agentId: string;
+    agentName: string;
+    connectionName: string;
+    /** Named in the agent's unpublished draft. */
+    inDraft: boolean;
+    /** Named in the agent's latest published version. */
+    published: boolean;
+}
+/**
+ * One saved sign-in to one app.
+ *
+ * TWO OWNERS, and the difference is who signs in:
+ *
+ * | `owner` | whose | a connection uses it as |
+ * |---|---|---|
+ * | `'workspace'` | the agent creator's, signed in once, usable by any agent | `Connection.creatorAccount(app, account)` |
+ * | `'end-user'` | one of YOUR end users', remembered for that person | `Connection.endUserAccount(app)`, in that person's conversations |
+ *
+ * Both owners are read and changed through the same routes and the same
+ * `Account` handle; `owner` says which this is.
+ *
+ * Nobody handles a token: the person signs in on the app's own page, and this
+ * record says who they signed in as, never how.
+ */
+export interface AccountData {
+    id: string;
+    /** The app's id: `App.GMAIL` is `'gmail'`. */
+    app: AppId;
+    /** Who it is signed in as: the email or username the app reports. Null until
+     *  somebody has finished signing in. */
+    label: string | null;
+    /** Your own name for it, such as `'Support inbox'`. Null when none was given. */
+    nickname: string | null;
+    status: AccountStatus;
+    /** True while a reconnect waits for the person to sign in again. The
+     *  account keeps working meanwhile, so `status` can still say
+     *  `'connected'`; `waitUntilConnected()` waits for this to clear. */
+    reconnecting: boolean;
+    owner: 'workspace' | 'end-user';
+    /** The end user it belongs to, when `owner` is `'end-user'`. An id from YOUR
+     *  database, never a workspace member's. */
+    endUserId?: string;
+    connectedAt: string | null;
+    lastCheckedAt: string | null;
+    /** The agents whose setup names this account. Empty for an end user's
+     *  account, which a setup never names by id. */
+    usedBy: UsedBy[];
+}
+/** An end user's account a conversation still needs, with the link that
+ *  person signs in at. From `conversation.accountsNeeded()`. */
+export interface AccountNeeded {
+    /** The connection's name on the agent. */
+    name: string;
+    app: AppId;
+    /** Send the person here. They sign in once, and every later conversation
+     *  of theirs has it. */
+    url: string;
 }
 /** Something a conversation is still missing before it can work. */
 export interface Requirement {
@@ -181,6 +418,9 @@ export interface Requirement {
 export interface AgentConversationData {
     id: string;
     agentId: string;
+    /** The number of the agent version this conversation runs, as `agent.version`
+     *  numbers them. Fixed at start, except that a schedule or webhook naming the
+     *  conversation moves it to the latest version at each firing. */
     version: number;
     startedAt: string;
     title?: string;
@@ -351,9 +591,44 @@ export interface AgentFields {
      * that was valid stays valid.
      */
     knowledgeBases?: string[];
+    /**
+     * Workspace databases this agent may query, by key.
+     *
+     * Register the database first with `ws.databases.create()`, which logs in
+     * and gives it the key; then name the key here. Naming it is the grant: a
+     * database answers only the agents whose configuration names it, and the
+     * agent's prompt lists them so it knows what to query.
+     *
+     * Part of the CONFIGURATION, so changing it publishes a version. A key that
+     * names no database is refused when the configuration is saved, and
+     * removing a database is refused while any agent names it.
+     */
+    databases?: string[];
     tools?: string[];
     workflows?: Workflow[];
-    connections?: ConnectionRequirement[];
+    /**
+     * The apps this agent uses, each a NAMED connection that says whose account
+     * it uses: the agent creator's account, or each end user's own. See
+     * `Connection` and `AgentConnection`.
+     *
+     * ```ts
+     * connections: [
+     *   Connection.creatorAccount(App.GMAIL, work, { name: 'work-gmail' }),
+     *   Connection.creatorAccount(App.GMAIL, personal, { name: 'personal-gmail' }),
+     *   Connection.endUserAccount(App.GOOGLE_CALENDAR),
+     * ]
+     * ```
+     *
+     * The builders make plain objects, `{ app, account: '<id>' }` and
+     * `{ app, endUser: true }`, and those objects are accepted as they are.
+     * `App.GMAIL` is the string `'gmail'`, so a plain app id works too.
+     *
+     * Part of the CONFIGURATION, like `databases`, so changing it publishes a
+     * version. An unknown account id, an account of a different app, a repeated
+     * name or a name of the wrong shape is refused when the configuration is
+     * saved, naming the problem.
+     */
+    connections?: Connection[];
     secrets?: SecretRequirement[];
     parameters?: Parameter[];
     triggers?: Trigger[];
@@ -367,13 +642,15 @@ export interface ProjectFields {
     grade?: Grade;
     agents?: string[];
 }
-/** Values supplied when a conversation starts: the credentials its agent
- *  declared at 'conversation' scope, plus any parameters. */
+/** Secret VALUES supplied to an agent (`agent.attach`) or to one conversation
+ *  (`conversation.attach`): the secrets its agent declared.
+ *
+ *  Accounts are no longer supplied this way (0.44). An agent's setup names the
+ *  account each connection uses, so there is nothing left to attach. */
 export interface Bindings {
     secrets?: Record<string, string>;
-    connections?: Record<string, string>;
 }
-/** One markdown file read off disk: a workflow, a subagent, an imported skill.
+/** One markdown file read off disk: a workflow or a subagent.
  *
  *  `when` is OPTIONAL here and required at publish. A file on disk has no `when`
  *  until someone writes one, and refusing to read it would be the wrong place to
@@ -389,7 +666,6 @@ export interface SpecFile {
 export interface SpecInput extends Omit<AgentFields, 'workflows'> {
     key: string;
     workflows?: SpecFile[];
-    skills?: SpecFile[];
     subagents?: SpecFile[];
     widgets?: {
         name: string;
@@ -483,3 +759,106 @@ export interface SecretMeta {
     updatedAt?: string;
     lastUsedAt?: string | null;
 }
+/** A SQL engine AgentNava can query. */
+export type DatabaseEngine = 'postgres' | 'mysql' | 'sqlserver';
+/** How the connection to a database is encrypted. `verify` (the default)
+ *  encrypts and always checks the server's certificate: against public and
+ *  cloud CAs and the host name, or, for a database with its own home-made CA,
+ *  against the CA AgentNava trusted the first time it connected. `disable` is
+ *  for a server with no SSL at all. */
+export type DatabaseTls = 'verify' | 'disable';
+/**
+ * How to log in to a database: a connection string, OR the same login as
+ * separate fields. Never both; a request with both is refused.
+ *
+ * Read-only unless `writable: true`, which no SQL the agent sends can override.
+ */
+export type DatabaseLogin = {
+    /** `postgres://`, `postgresql://` or `mysql://`, with the user (and the
+     *  password, when there is one) in it. An `sslmode` in the string sets `tls`. */
+    url: string;
+    engine?: DatabaseEngine;
+    /** Overrides the string's `sslmode`. */
+    tls?: DatabaseTls;
+    writable?: boolean;
+} | {
+    engine: DatabaseEngine;
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    /** Leave it out for a database that takes a user name alone. */
+    password?: string;
+    tls?: DatabaseTls;
+    writable?: boolean;
+};
+/** What `ws.databases.create()` takes: the key agents will name it by, an
+ *  optional label, and a login. */
+export type DatabaseFields = DatabaseLogin & {
+    /** Lowercase letters, digits and dashes, like `shop` or `sales-db`. What an
+     *  agent configuration stores, so it is not editable afterwards. */
+    key: string;
+    /** A label for people. Defaults to the key. */
+    name?: string;
+};
+/** A registered database as AgentNava reports it: where it is, never how to
+ *  log in. Neither the password nor the connection string is ever returned. */
+export interface DatabaseData {
+    key: string;
+    /** The underlying connection's id. */
+    id: string;
+    name: string;
+    engine: DatabaseEngine | null;
+    host: string | null;
+    port: number | null;
+    database: string | null;
+    tls: DatabaseTls | null;
+    writable: boolean;
+    status: string;
+    createdAt: string;
+    /** The agents whose configuration names this database. */
+    usedBy: DatabaseUsedBy[];
+}
+/** An agent whose configuration names a database: in its latest published
+ *  version, in its draft, or in both. */
+export interface DatabaseUsedBy {
+    /** The agent's id: the same value as `Agent.id`, so compare this one. */
+    id: string;
+    /** AgentNava's internal handle for the same agent (`agt_...`), not `Agent.id`. */
+    agentId: string;
+    /** The agent's display name. */
+    name: string;
+    /** Named in the agent's latest published version, so its conversations can
+     *  query the database now. */
+    published: boolean;
+    /** Named in the configuration being edited: the draft when there is one,
+     *  else the published version itself. */
+    draft: boolean;
+}
+/** One table or view in a database. */
+export interface DatabaseTable {
+    schema: string;
+    name: string;
+    kind: 'table' | 'view';
+}
+/** One column of a table. */
+export interface DatabaseColumn {
+    name: string;
+    dataType: string;
+    nullable: boolean;
+    isPrimaryKey: boolean;
+}
+/** What `ws.databases.test()` reports. A refused login is an answer, not an
+ *  exception, because it is the answer the call exists to get. */
+export type DatabaseTestResult = {
+    ok: true;
+    engine: DatabaseEngine;
+    tableCount: number;
+    tables: DatabaseTable[];
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};