@nocobase/app-plugin-agents 0.1.0-beta.9 → 1.0.0-beta.15

package/dist/shared/agents.js

@@ -1,130 +1,64 @@
-/**
- * Agents as the browser and the server's admin API exchange them.
- *
- * An agent is who works and how: its name and instructions, its type, the business actions it may perform. Its type is
- * chosen when it is created and never changes:
- *
- * - `runner`: it drives a coding tool on a runner, with its skills, its tool policy and its own
- *   variables. Where it runs is not configured beyond an optional list of runners: a run goes to any online runner that
- *   has one of its tools installed and signed in, may run the waking person's work, and has a free slot.
- * - `online`: it talks to a model of a model service directly, on the server: no runner, no working directory, no
- *   variables. Its tools are the application's commands it may run, and whatever else the application offers
- *   (knowledge search). It answers in seconds and runs only on subjects that need no working directory, such as
- *   conversations.
- *
- * Which tool or model it works with, and with what reasoning effort, is an ordered list (`modelEntries`), the first
- * being its default. A runner takes a runner agent's run with the first entry whose tool it has enabled and signed in;
- * nobody chooses. An online agent's runs use the first entry, except in a conversation, whose owner may pick another of
- * its entries. The run records the entry it used (`Run.tool`, `Run.modelService`, `Run.model`, `Run.effort`).
- *
- * An online agent with no entry is not configured yet (such as an application's built-in assistant before a model service exists): it is
- * kept, shown as needing a model, and offered no work until an entry is added. A runner agent always has one.
- */
 import { TOOL_EFFORTS, } from '@nocobase/agent-protocol';
-/** Who may wake an agent: its owner, the listed users, or everyone. */
-export const AGENT_ACCESS = ['ownerOnly', 'users', 'everyone'];
-/** What kind of agent it is; chosen at creation and never changed (`runner`: a coding tool on a runner, `online`: a model on the server). */
-export const AGENT_TYPES = ['online', 'runner'];
+/** Where an agent comes from: discovered from what runners report, or kept by the application. */
+export const AGENT_SOURCES = ['runner', 'system'];
 /**
- * When an agent in a conversation asks the person before changing data for them: `always` (every change goes through an
- * operation plan they confirm) or `larger` (small changes are made directly, within the application's direct-write
- * rules, and anything larger goes through a plan). There is no "never": what the rules call larger (waking an agent,
- * finishing an issue, changing an owner, …) always needs the person's confirmation.
+ * Whether an agent is offered work: `pending` (discovered, nobody enabled it yet), `enabled`, `disabled`. Only enabled
+ * agents are offered work, mentioned or chatted with.
  */
+export const AGENT_STATUSES = ['pending', 'enabled', 'disabled'];
+/** How long a tool and model may go unreported by every runner before its agent shows as having no runner. */
+export const AGENT_UNREPORTED_AFTER_MS = 14 * 24 * 60 * 60_000;
+/** When in a conversation an agent asks before changing data: every change, or only larger ones. */
 export const CONFIRM_CHANGES = ['always', 'larger'];
-/** The reasoning efforts an online agent's entry may name, weakest first, as the model gateway passes them to providers. */
-export const ONLINE_EFFORTS = [
-    'minimal',
-    'low',
-    'medium',
-    'high',
-    'xhigh',
-];
 /** The most entries an agent's list holds. */
 export const MAX_MODEL_ENTRIES = 20;
-export function isRunnerEntry(entry) {
-    return 'tool' in entry;
-}
-export function isOnlineEntry(entry) {
-    return 'modelService' in entry;
-}
-/** The reasoning efforts `entry` may name: its tool's for a runner entry, `ONLINE_EFFORTS` for an online one. */
+/** The reasoning efforts `entry`'s tool takes. */
 export function effortsFor(entry) {
-    return 'tool' in entry ? TOOL_EFFORTS[entry.tool] : ONLINE_EFFORTS;
-}
-/** A runner agent's entries, in order; empty for an online agent. */
-export function runnerEntries(agent) {
-    return agent.modelEntries.filter(isRunnerEntry);
-}
-/** An online agent's entries, in order; empty for a runner agent. */
-export function onlineEntries(agent) {
-    return agent.modelEntries.filter(isOnlineEntry);
-}
-/**
- * The entries an online agent answers with: its own, or, when it lists none, the system default chat model
- * (`DefaultModels`) as its only one; empty for a runner agent or when there is no default either.
- */
-export function onlineEntriesOrDefault(agent, defaultModel) {
-    if (agent.type !== 'online')
-        return [];
-    const own = onlineEntries(agent);
-    if (own.length > 0)
-        return own;
-    return defaultModel
-        ? [{ modelService: defaultModel.modelService, model: defaultModel.model }]
-        : [];
+    return TOOL_EFFORTS[entry.tool];
 }
-/** The coding tools a runner agent's entries name, in order and once each; empty for an online agent. */
+/** The coding tools an agent's entries name, in order and once each. */
 export function entryTools(agent) {
-    return [...new Set(runnerEntries(agent).map((entry) => entry.tool))];
+    return [...new Set(agent.modelEntries.map((entry) => entry.tool))];
 }
-/** Whether two entries name the same tool or service and model, whatever their efforts. */
+/** Whether two entries name the same tool and model, whatever their efforts. */
 export function sameEntry(a, b) {
-    if (isRunnerEntry(a))
-        return (isRunnerEntry(b) &&
-            a.tool === b.tool &&
-            (a.model ?? null) === (b.model ?? null));
-    return (isOnlineEntry(b) && a.modelService === b.modelService && a.model === b.model);
+    return a.tool === b.tool && (a.model ?? null) === (b.model ?? null);
 }
-/** What a change to an agent's configuration was. */
+/**
+ * Why an agent cannot take the caller's work now: `pending` and `disabled` (not enabled), `unreported` (no runner
+ * reported its tool and model for `AGENT_UNREPORTED_AFTER_MS`), `notConfigured` (an application's own agent with no
+ * tool and model yet), `noRunner` (no runner online that has it and would take the caller's work), `othersPersonal`
+ * (only other people's personal runners have it).
+ */
+export const AGENT_UNUSABLE_REASONS = [
+    'pending',
+    'disabled',
+    'unreported',
+    'notConfigured',
+    'noRunner',
+    'othersPersonal',
+];
+/** What a change to an agent was. */
 export const AGENT_CHANGE_ACTIONS = [
     'created',
     'updated',
+    'enabled',
+    'disabled',
+    'variables',
+    // Recorded by earlier versions, which kept agents people configured.
     'archived',
     'restored',
-    'variables',
 ];
 /** The fields of an agent whose changes its history records, in the order the history shows them. */
 export const AGENT_HISTORY_FIELDS = [
     'name',
     'description',
-    'avatar',
-    'instructions',
-    'type',
+    'status',
     'modelEntries',
-    'skillIds',
+    'instructions',
     'actions',
-    'confirmChanges',
-    'toolPolicy',
-    'runnerIds',
-    'maxConcurrentRuns',
-    'maxAttempts',
-    'access',
-    'userIds',
-    'ownerUserId',
-];
-/** Fields no longer recorded that older history entries still carry, so the history can still name them. */
-export const RETIRED_AGENT_HISTORY_FIELDS = [
-    'tool',
-    'model',
-    'llmService',
-    'modelService',
-    'reasoningEffort',
 ];
-/**
- * The tool policy an agent starts from; an agent's `toolPolicy` overrides fields of it. The editor shows it so people
- * see what they override.
- */
+/** The tool policy every agent runs with; an agent's `toolPolicy` overrides fields of it. */
 export const DEFAULT_TOOL_POLICY = {
     permissionMode: 'acceptEdits',
     allowedCommands: [

package/dist/shared/agents.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../shared/agents.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../shared/agents.ts"],"names":[],"mappings":"AAiBA,OAAO,EACL,YAAY,GAGb,MAAM,0BAA0B,CAAC;AAIlC,kGAAkG;AAClG,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAI3D;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAI1E,8GAA8G;AAC9G,MAAM,CAAC,MAAM,yBAAyB,GAAW,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;AAEvE,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAc7D,8CAA8C;AAC9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,kDAAkD;AAClD,MAAM,UAAU,UAAU,CAAC,KAE1B;IACC,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,UAAU,CAAC,KAE1B;IACC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,CAAmB,EAAE,CAAmB;IAChE,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;AACtE,CAAC;AA4CD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS;IACT,UAAU;IACV,YAAY;IACZ,eAAe;IACf,UAAU;IACV,gBAAgB;CACR,CAAC;AA4FX,qCAAqC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS;IACT,SAAS;IACT,SAAS;IACT,UAAU;IACV,WAAW;IACX,qEAAqE;IACrE,UAAU;IACV,UAAU;CACF,CAAC;AAIX,qGAAqG;AACrG,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,MAAM;IACN,aAAa;IACb,QAAQ;IACR,cAAc;IACd,cAAc;IACd,SAAS;CACD,CAAC;AA8DX,6FAA6F;AAC7F,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,cAAc,EAAE,aAAa;IAC7B,eAAe,EAAE;QACf,8GAA8G;QAC9G,kGAAkG;KACnG;IACD,cAAc,EAAE;QACd,uCAAuC;QACvC,YAAY;QACZ,wCAAwC;QACxC,oCAAoC;QACpC,0BAA0B;KAC3B;IACD,aAAa,EAAE,EAAE,GAAG,MAAM;CAC3B,CAAC"}

package/dist/shared/conversations.d.ts

@@ -1,72 +1,17 @@
 /**
- * Conversations: a person chatting with an agent from the chat panel, as the browser, the server's API and the
- * application exchange them. This file is the contract; the panel (client), the application's extensions and the
- * conversation domain build on it and on nothing else.
- *
- * ## Model
- *
- * - A **conversation** belongs to one person (its owner) and is bound to one agent. Its **mode** is the type of the agent
- *   it answers with now (`online`: a model on the server answers in seconds; `runner`: a coding agent on a runner). It
- *   changes only while a runner conversation uses the online fallback agent in its agent's place (see Availability); a
- *   person who needs the other kind of agent otherwise starts another conversation. Only the owner reads its content:
- *   the API answers 404 to everyone else, administrators included, and the runs a conversation starts are hidden from
- *   anyone the run does not involve. Administrators see usage only.
- * - A **message** is what the owner sent (`user`), what the agent replied (`assistant`), or a notice the server wrote
- *   (`system`: the agent was switched, a run failed). Field names follow the platform AI employee's
- *   `aiConversations` / `aiMessages`, so the two stores can be merged later.
- * - Each message the owner sends wakes the agent: a run with the subject `{ kind: 'conversation', id }`, woken by the
- *   owner (whose permissions bound it). A message sent while the agent is working joins that run as input; a message
- *   sent while it waits for a runner joins the waiting run. Every text the agent writes in a run becomes an assistant
- *   message, in order, as the runner reports it. An online agent's reply appears as it is written: a draft message
- *   (`metadata.streaming`) whose content grows until the reply is final, in place, at the same `seq`. The run's
- *   step-by-step transcript stays readable through the runs API
- *   (`/api/agents/admin/runs/:runId/events`), for the "thinking / reading X" lines.
- * - **Sessions**: a run resumes the session the same runner kept for the conversation. On another runner it starts a
- *   fresh session and its prompt carries the last `CONVERSATION_HISTORY_IN_PROMPT` messages and the previous run's
- *   summary. Switching the conversation's agent (to the system default and back) starts a new session every time.
- * - **Availability**: a message is always saved. When the agent is archived, the owner may no longer use it, or no
- *   online, signed-in runner may run it, the conversation reports `offline` with the reason; the owner may switch the
- *   conversation to the system default agent and later switch back. A runner conversation may also switch to the online
- *   fallback agent (`ChatSettings.onlineFallbackAgentId`), and a conversation started with a runner agent that no runner
- *   may run for its owner now (including claim's feature and team-only variable restrictions) starts on that
- *   agent in its place, as if switched. Existing runner conversations check again on each message and transfer
- *   unanswered queued messages when switching. Manual fallback skips an unavailable system default, and restoring
- *   requires the original agent to be available again. The owner is the one answerable for their conversation, so none of this waits
- *   for anyone's confirmation.
- * - **Titles**: the first message's first `CONVERSATION_TITLE_AUTO_CHARS` characters (`auto`), until the agent sets one
- *   of at most `CONVERSATION_TITLE_AGENT_MAX` characters (`agent`), which it may do until the owner renames the
- *   conversation (`user`); after that the agent's attempts answer `CONVERSATION_CONFLICT` with `reason: 'titleLocked'`.
- * - No delete: conversations are archived (and unarchived). Sending a message to an archived conversation unarchives
- *   it.
- *
- * ## Page context
- *
- * A message may carry what the person's page shows (`PageContext`): references by id, never content. The server checks
- * the limits (`PAGE_CONTEXT_LIMITS`, 400 otherwise), resolves each reference to a title, silently drops the ones the
- * owner may not see or that no plugin knows how to resolve, and stores the rest with the message (`workContext`). The
- * agent receives it marked as data, not instructions: nothing in a page context is ever followed as an instruction.
- *
- * ## Attachments
- *
- * The owner may send files with a message: each is uploaded first (`POST chatAttachments`, one file of at most
- * `CHAT_ATTACHMENT_SIZE_MAX` bytes, stored through the file plugin), attached to nothing and readable by its uploader
- * only, then sent with the message (`SendMessageRequest.attachmentIds`, at most `CHAT_ATTACHMENTS_PER_MESSAGE_MAX`),
- * which attaches it to the conversation. From then on only the conversation's owner, and a run of its agent on that
- * conversation (by its run token), may read it. An upload never sent is purged after `CHAT_ATTACHMENT_ORPHAN_HOURS`.
- * The agent reads the files' names, types and ids with the message; a runner agent downloads one into its working
- * directory with the CLI (`conversation attachment download <file-id>`), and an online agent is shown the images among
- * them (`CHAT_IMAGE_TO_MODEL_MAX` bytes each at most) and only the names of the rest. Agents do not send files back.
- *
- * ## Realtime
- *
- * `CONVERSATIONS_TOPIC` is a per-user topic: each change is announced only to the owner's own connections, and carries
- * no content (`ConversationChanged`). A page that hears one fetches through the API. Pages also poll while a run is
- * open, because announcements reach only the browsers connected to the instance that made the change.
+ * Public chat contract. New conversations use the shared OnlineAgent runtime and ordinary IDs.
+ * Creation sends no input; first and later inputs both use messages. clientId only correlates
+ * display echoes, never durable request deduplication. Timeouts have unknown outcomes and must
+ * not trigger hidden resends. Current-stream events support the first subscription only;
+ * disconnects leave server execution running and require explicit saved-history refresh.
+ * Legacy IDs/text/files remain readable; unknown Runner effects are never automatically replayed.
+ * Internal SDK envelopes, tool payloads and provider metadata never enter this public DTO.
  */
+import type { QuotaLocation } from './quota.js';
 import type { FailureReason, RunStatus } from '@nocobase/agent-protocol';
-import type { OnlineModelEntry } from './agents.js';
 import type { I18nText } from './i18n.js';
-import type { ModelCatalog } from './models.js';
+import type { PageUIContext } from './page-ui-context.js';
+export type { PageUIContext, PageUIItem } from './page-ui-context.js';
 /** The run subject kind of a conversation. */
 export declare const CONVERSATION_SUBJECT = "conversation";
 /** The automatic title: the first message's first characters, without Markdown punctuation. */
@@ -83,8 +28,6 @@ export declare const CHAT_ATTACHMENT_SIZE_MAX: number;
 export declare const CHAT_ATTACHMENTS_PER_MESSAGE_MAX = 10;
 /** How long an upload not sent with a message is kept. */
 export declare const CHAT_ATTACHMENT_ORPHAN_HOURS = 24;
-/** The largest image an online agent's model is shown; a larger one is listed by name only. */
-export declare const CHAT_IMAGE_TO_MODEL_MAX: number;
 /** The raster images shown inline, by extension: the declared type must be the one listed. */
 export declare const INLINE_IMAGE_TYPES: Readonly<Record<string, string>>;
 /** A safe raster image, whose declared type matches its extension; anything else is only downloaded. */
@@ -143,10 +86,12 @@ export interface PageContextRef {
     readonly id: string;
 }
 /**
- * What the person's page shows when they send a message, as the browser sends it: ids and the visible filter, never
- * content. Data, not instructions.
+ * What the person's page shows when they send a message: authorized business ids, visible filters and explicitly
+ * selected browser UI snapshots. All browser-supplied values are untrusted data, never instructions.
  */
 export interface PageContext {
+    /** Explicitly selected, untrusted browser UI snapshots; never resolved as business resources. */
+    readonly ui?: PageUIContext;
     /** The page's route (path and query), at most `PAGE_CONTEXT_LIMITS.route` characters. */
     readonly route: string;
     /** The objects the page shows or the person pinned, at most `PAGE_CONTEXT_LIMITS.items`. */
@@ -176,8 +121,10 @@ export interface ResolvedPageContextItem extends PageContextRef {
     /** Where it opens in the application, when it has a page. */
     readonly url: string | null;
 }
-/** A page context as stored with a message (`workContext`) and handed to the agent. */
+/** A page context stored with the message. Follow-ups may reauthorize only its references, never replay its stale page parameters. */
 export interface ResolvedPageContext {
+    /** Detached browser data; its presence grants no resource or tool access. */
+    readonly ui?: PageUIContext;
     readonly route: string;
     readonly items: readonly ResolvedPageContextItem[];
     readonly filter?: PageContext['filter'];
@@ -199,17 +146,17 @@ export interface ConversationAgent {
     readonly archived: boolean;
 }
 /** Why a conversation's agent cannot answer now. */
-export declare const OFFLINE_REASONS: readonly ["agentMissing", "agentArchived", "forbidden", "noRunner", "modelUnavailable"];
+export declare const OFFLINE_REASONS: readonly ["noModel", "agentMissing", "agentArchived", "forbidden", "noRunner", "othersPersonal"];
 export type OfflineReason = (typeof OFFLINE_REASONS)[number];
 /** Whether the agent can answer now. */
 export interface ChatAvailability {
     readonly online: boolean;
     /** Null when online. */
     readonly reason: OfflineReason | null;
-    /** Runners that may run the agent for the owner now; for an online agent, 1 while its model is offered. */
+    /** Runners that may run the agent for the owner now. */
     readonly onlineRunners: number;
 }
-/** A conversation's mode: the type of the agent it answers with now (`AgentType`). */
+/** A conversation's mode: `runner`, or `online` for a conversation an earlier version answered with an online agent. */
 export type ConversationMode = 'online' | 'runner';
 /** The conversation's open run: queued, waiting for a runner, or working. */
 export interface ConversationRun {
@@ -220,26 +167,27 @@ export interface ConversationRun {
 }
 /** A conversation in the history list. */
 export interface ConversationSummary {
+    readonly execution?: {
+        readonly status: 'running' | 'idle';
+        readonly outcome?: 'completed' | 'cancelled' | 'failed';
+        readonly requiresEffectReview?: boolean;
+        readonly waitingApproval?: boolean;
+        readonly interrupted?: boolean;
+        readonly messageId?: string;
+        readonly revision?: number;
+    };
     readonly id: string;
     /** Null until the first message gives it one. */
     readonly title: string | null;
     readonly titleSource: TitleSource;
     readonly category: ConversationCategory;
+    /** Visibility in the default chat list; direct owned reads remain available. */
+    readonly showInChatList: boolean;
     readonly source: ConversationSource;
-    /** `online` or `runner`: the type of `agent`. */
     readonly mode: ConversationMode;
     readonly agent: ConversationAgent;
-    /**
-     * While the conversation uses the system default or the online fallback agent in place of its own (`fallback`, or a
-     * new conversation whose runner agent could not run): the agent it switches back to. Null otherwise.
-     */
+    /** While the conversation uses the system default agent in place of its own (`fallback`): the agent it switches back to. */
     readonly fallbackFrom: ConversationAgent | null;
-    /**
-     * An online conversation: the entry of its agent's list it answers with, the owner's choice
-     * (`ConversationPatch.model`) while the agent lists it, else the agent's first. Null for a runner conversation, or
-     * when the agent is gone.
-     */
-    readonly model: OnlineModelEntry | null;
     /** False when the agent wrote since the owner last marked it read. */
     readonly read: boolean;
     readonly lastMessageAt: string;
@@ -249,24 +197,10 @@ export interface ConversationSummary {
     /** The open run, if any: the panel shows "working" and offers to stop. */
     readonly run: ConversationRun | null;
 }
-/** An entry a conversation may answer with, named as the person reads it: its service's title and the model's label. */
-export interface ChatModelChoice extends OnlineModelEntry {
-    /** Its service's title; its name when no enabled service has it any more. */
-    readonly serviceTitle: string;
-    /** The model's label in its service; its id when the service no longer offers it. */
-    readonly modelLabel: string;
-}
-/** The entries named from the catalog (`ChatModelChoice`); what the catalog no longer has keeps its ids. */
-export declare function chatModelChoices(entries: readonly OnlineModelEntry[], catalog: Pick<ModelCatalog, 'services'>): ChatModelChoice[];
 /** One conversation as the panel opens it. */
 export interface ConversationDetail extends ConversationSummary {
     readonly availability: ChatAvailability;
-    /** An online conversation: the entries of its agent's list the owner may choose from, in order; empty otherwise. */
-    readonly models: readonly ChatModelChoice[];
-    /**
-     * Another agent may take over (`POST …/fallback`): an available system default of the conversation's mode, else,
-     * for a runner conversation, the online fallback agent (`ChatSettings.onlineFallbackAgentId`).
-     */
+    /** Another agent may take over (`POST …/fallback`): the system default agent, when it can answer. */
     readonly canFallback: boolean;
     /** The conversation uses another agent and its original agent can answer again (`POST …/restore`). */
     readonly canRestore: boolean;
@@ -288,13 +222,13 @@ export type ConversationNotice =
     readonly agentId: string;
     readonly fromAgentId: string;
 }
-/** The conversation now uses the online fallback agent in place of its runner agent, until switched back. */
+/** Written by earlier versions: the conversation used the online fallback agent in place of its runner agent. */
  | {
     readonly code: 'switchedToOnline';
     readonly agentId: string;
     readonly fromAgentId: string;
 }
-/** The configured online fallback cannot answer; the conversation stays with its runner agent. */
+/** Written by earlier versions: the configured online fallback could not answer. */
  | {
     readonly code: 'onlineFallbackUnavailable';
     readonly fromAgentId: string;
@@ -312,7 +246,7 @@ export type ConversationNotice =
     readonly runId: string;
     readonly reason: FailureReason | null;
 }
-/** The owner stopped the run. */
+/** Cancellation was requested; this notice does not confirm the run has ended. */
  | {
     readonly code: 'runCancelled';
     readonly runId: string;
@@ -332,11 +266,12 @@ export type ConversationNotice =
 export declare const CONSULTATION_STATES: readonly ["running", "completed", "failed", "refused"];
 export type ConsultationState = (typeof CONSULTATION_STATES)[number];
 /**
- * The agent consulted another one (`ask_agent`) while answering: one card per call, rewritten in place (same id and
- * `seq`, `metadata.streaming` while it runs) as the consultation goes. The consulted agent's own run (`runId`) has its
- * transcript and usage.
+ * Written by earlier versions: the online agent consulted another one (`ask_agent`) while answering, one card per call.
+ * The consulted agent's own run (`runId`) has its transcript and usage.
  */
 export interface ConsultationNotice {
+    /** Display-only marker: the requested subject could not be resolved; agentName is a historical snapshot. */
+    readonly identitySnapshot?: boolean;
     readonly code: 'consultation';
     /** The tool call: one card per call. */
     readonly callId: string;
@@ -370,16 +305,13 @@ export interface MessageMetadata {
     readonly runEventSeq?: number;
     /** A system message: what happened. */
     readonly notice?: ConversationNotice;
-    /** An earlier online fallback failure no longer applies after availability recovered or changed. */
+    /** Written by earlier versions: an online fallback failure no longer applied. */
     readonly onlineFallbackResolved?: boolean;
     /** The id the browser gave a message it sent, echoed so it can replace its optimistic copy. */
     readonly clientId?: string;
-    /**
-     * An assistant message an online agent is still writing: its content grows in place (same id and `seq`) until the reply
-     * is final, when the flag goes. Fetch messages again from before the first streaming one to see it grow.
-     */
+    /** Written by earlier versions: an online agent's reply still being written. */
     readonly streaming?: boolean;
-    /** A draft whose run ended before the reply was final: what it had written. */
+    /** Written by earlier versions: a draft whose run ended before the reply was final. */
     readonly interrupted?: boolean;
 }
 /** A file sent with a message (`SendMessageRequest.attachmentIds`), or an upload not sent yet. */
@@ -425,17 +357,13 @@ export interface ConversationMessage {
  * | ------ | --------------- | ------------------------------------------------- | -------------------------- |
  * | GET    | `conversations` | `ConversationListQuery` (cursor paging)           | `ConversationSummary[]`    |
  * | POST   | `conversations` | `CreateConversationRequest`                       | `ConversationDetail` (201) |
- * | POST   | `start`         | `StartConversationRequest`                        | `SendMessageResult`        |
  * | GET    | `conversation`  |                                                   | `ConversationDetail`       |
  * | PATCH  | `conversation`  | `ConversationPatch` (rename, archive / unarchive) | `ConversationDetail`       |
  * | GET    | `messages`      | `MessageListQuery` (cursor paging)                | `ConversationMessage[]`    |
  * | POST   | `messages`      | `SendMessageRequest`                              | `SendMessageResult` (201)  |
  * | POST   | `markRead`      |                                                   | `ConversationDetail`       |
  * | POST   | `stop`          |                                                   | `ConversationDetail`       |
- * | POST   | `fallback`      |                                                   | `ConversationDetail`       |
- * | POST   | `restore`       |                                                   | `ConversationDetail`       |
  * | GET    | `agents`        |                                                   | `ChatAgent[]`              |
- * | POST   | `copyAgent`     | `CopyAgentRequest`                                | `Agent`                    |
  * | GET    | `preferences`   |                                                   | `ChatPreferences`          |
  * | PATCH  | `preferences`   | `ChatPreferencesPatch`                            | `ChatPreferences`          |
  * | GET    | `settings`      |                                                   | `ChatSettings`             |
@@ -451,13 +379,11 @@ export declare const CHAT_ROUTES: {
     readonly conversations: "agents/conversations";
     readonly conversation: "agents/conversations/:conversationId";
     readonly messages: "agents/conversations/:conversationId/messages";
+    readonly events: "agents/conversations/:conversationId/events";
+    readonly config: "agents/conversations/:conversationId/config";
     readonly markRead: "agents/conversations/:conversationId/markRead";
     readonly stop: "agents/conversations/:conversationId/stop";
-    readonly fallback: "agents/conversations/:conversationId/fallback";
-    readonly restore: "agents/conversations/:conversationId/restore";
-    readonly start: "agents/conversations/start";
     readonly agents: "agents/chatAgents";
-    readonly copyAgent: "agents/:agentId/copy";
     readonly preferences: "agents/chatPreferences";
     readonly settings: "agents/chatSettings";
     readonly attachments: "agents/chatAttachments";
@@ -489,36 +415,49 @@ export interface ConversationPage {
     readonly nextCursor: string | null;
 }
 /** `POST conversations`. Creating starts no run; the first message does. */
+export type OnlineChatJson = null | boolean | number | string | OnlineChatJson[] | {
+    [key: string]: OnlineChatJson;
+};
+export interface OnlineChatConfigSnapshot {
+    readonly agentId?: string;
+    readonly selectedModel: {
+        modelService: string;
+        model: string;
+    } | null;
+    readonly scope: string[];
+    readonly model: string[];
+    readonly thinking?: string;
+    readonly tool: string[];
+    readonly toolVersions: Record<string, string>;
+    readonly systemPrompt: string;
+    readonly variable?: OnlineChatJson;
+}
 export interface CreateConversationRequest {
-    /**
-     * The agent to chat with, which the person must be allowed to wake; its type becomes the conversation's initial mode.
-     * Without one: the person's default online agent
-     * (`ChatPreferences.defaultAgentId`) while they may still wake it, else the system default
-     * (`ChatSettings.defaultAgentId`), else `CONVERSATION_CONFLICT` `noChatAgent`. A runner agent that no runner may
-     * run for the person now is replaced by the online fallback agent (`ChatSettings.onlineFallbackAgentId`) when one is
-     * set and usable, without `model`; the conversation starts on it with `fallbackFrom` naming the runner agent.
-     */
+    /** Defaults to true; background SDK sessions are always hidden. */
+    readonly showInChatList?: boolean;
+    readonly config?: {
+        agentId?: string;
+        context?: {
+            variable?: OnlineChatJson;
+        };
+        scope?: string[];
+        thinking?: string;
+    };
+    readonly selectedModel?: {
+        modelService: string;
+        model: string;
+    };
+    /** Selects the native `online` executor or a callable Runner agent for a new conversation. */
     readonly agentId?: string;
     /** An explicit title (`user`); otherwise the first message gives one. */
     readonly title?: string;
     /** `panel` by default; otherwise a registered source. */
     readonly source?: ConversationSource;
-    /**
-     * An online agent: the entry of its list (`ChatAgent.models`) the conversation answers with, as `ConversationPatch.model`
-     * sets it later; null or left out for the agent's default. 400 `INVALID_REQUEST` (`MODEL_NOT_LISTED`) for one the
-     * agent does not list.
-     */
-    readonly model?: OnlineModelEntry | null;
 }
-/**
- * `PATCH conversation`: rename (the title becomes `user`'s and the agent may no longer change it), archive, or choose
- * the model an online conversation answers with: one of `ConversationDetail.models`, or null for the agent's default.
- * The choice applies from the next run; a model that fails fails the run, nothing falls back to another.
- */
+/** `PATCH conversation`: rename (the title becomes `user`'s and the agent may no longer change it), or archive. */
 export interface ConversationPatch {
     readonly title?: string;
     readonly archived?: boolean;
-    readonly model?: OnlineModelEntry | null;
 }
 /**
  * `GET messages`: without a page token, the newest `pageSize` messages; `meta.nextPageToken` pages back through older
@@ -526,6 +465,8 @@ export interface ConversationPatch {
  * highest `seq` in the conversation now.
  */
 export interface MessageListQuery {
+    /** Native UIMessage IDs to reread after a message revision notification, comma-separated (at most 100). */
+    readonly ids?: string;
     /** Messages with a higher `seq`. */
     readonly after?: number;
     /** The `meta.nextPageToken` of the previous page: older messages. */
@@ -541,7 +482,7 @@ export interface MessagePage {
     /** The highest `seq` in the conversation now, to ask `after` with. */
     readonly lastSeq: number;
 }
-/** `POST messages`: an unavailable runner may first switch to the configured usable online fallback agent. */
+/** `POST messages`. */
 export interface SendMessageRequest {
     /** Markdown, at most `MESSAGE_CONTENT_MAX` characters; empty only when files are sent. */
     readonly content: string;
@@ -579,6 +520,8 @@ export interface SendMessageResult {
  * `CreateConversationRequest`). The text is at most `MESSAGE_CONTENT_MAX` characters: 400 `INVALID_REQUEST` otherwise.
  */
 export interface StartConversationRequest {
+    /** The caller's own unattached chat uploads for the first message. */
+    readonly attachmentIds?: readonly string[];
     readonly source: Exclude<ConversationSource, 'panel'>;
     readonly text: string;
     readonly agentId?: string;
@@ -588,6 +531,9 @@ export interface StartConversationRequest {
 }
 /** An agent the person may chat with (`GET agents`). */
 export interface ChatAgent {
+    readonly quota?: readonly QuotaLocation[];
+    /** Viewer-visible eligible runtimes, for partial quota availability. */
+    readonly runnerNames: readonly string[];
     readonly id: string;
     readonly name: string;
     readonly description: string | null;
@@ -595,34 +541,11 @@ export interface ChatAgent {
     readonly nameText: I18nText | null;
     readonly descriptionText: I18nText | null;
     readonly avatar: string | null;
-    /** `online` or `runner`: the mode of the conversations it is started in. */
-    readonly type: 'online' | 'runner';
-    /**
-     * An online agent: the entries of its list a new conversation may answer with (`CreateConversationRequest.model`), in
-     * order, the first its default; empty for a runner agent.
-     */
-    readonly models: readonly ChatModelChoice[];
-    /** The person's own agent, which only they may use (a "copy for myself"). */
-    readonly personal: boolean;
     readonly isSystemDefault: boolean;
     readonly isMyDefault: boolean;
     readonly availability: ChatAvailability;
-    /**
-     * A runner agent that no runner may run for the person now: the online agent a new conversation with it starts on
-     * instead (`ChatSettings.onlineFallbackAgentId`). Null otherwise.
-     */
-    readonly fallbackAgentId: string | null;
-}
-/**
- * `POST copyAgent`: a private copy of an agent the person may wake, owned by them and usable only by them. The copy
- * takes the agent's description, avatar, tool, model, instructions, business actions, skills, runners and limits, not
- * its variables.
- */
-export interface CopyAgentRequest {
-    /** The copy's name; `<name> (copy)` by default. */
-    readonly name?: string;
-    /** Also make the copy the person's default online agent. */
-    readonly makeDefault?: boolean;
+    /** Only personal runners have it: it takes only their owners' work. */
+    readonly personalOnly: boolean;
 }
 /** The person's own chat settings ("Profile › Agent"). */
 export interface ChatPreferences {
@@ -634,11 +557,6 @@ export type ChatPreferencesPatch = Partial<ChatPreferences>;
 export interface ChatSettings {
     /** The agent new conversations go to when a person has no default of their own; null when none is set. */
     readonly defaultAgentId: string | null;
-    /**
-     * The online agent that answers in place of a runner agent no runner may run for the person now: a new conversation
-     * with that runner agent starts on it, and a runner conversation may switch to it. Null when none is set.
-     */
-    readonly onlineFallbackAgentId: string | null;
 }
 export type ChatSettingsPatch = Partial<ChatSettings>;
 /** A per-user topic: each announcement reaches only the conversation owner's connections. */
@@ -648,6 +566,11 @@ export declare const CONVERSATIONS_TOPIC = "agents:conversations";
  * `after`); `conversation`: its title, agent, run, archive or read state changed (fetch it, and the list).
  */
 export type ConversationChanged = {
+    readonly kind: 'conversation.messageUpdated';
+    readonly conversationId: string;
+    readonly messageId: string;
+    readonly revision: number;
+} | {
     readonly kind: 'conversation.messages';
     readonly conversationId: string;
     readonly lastSeq: number;