@salsita-ai/sdk 0.50.0-develop.ea458ea381 → 0.50.0-develop.f03b563886

package/dist/client/phoenix-api.d.ts

@@ -201,10 +201,10 @@ export interface paths {
       readonly path?: never
       readonly cookie?: never
     }
-    /** @description Load the caller's latest assistant thread on the configuration with its active run, newest window first. The `x-assistant-thread-continuable` response header is `false` when the thread belongs to another deployment or is closed; a chat request then answers 409. */
+    /** @description Load the caller's latest assistant thread on the configuration with its active run, newest window first. The `x-assistant-thread-continuable` response header is `false` when the thread cannot be continued with this setup, has reached its size limit or is closed; a chat request then answers 409, and the thread continues once it is compacted. The `x-assistant-previous-thread` response header carries the id of the closed thread this one continues, when there is one. */
     readonly get: operations['getAssistantThread']
     readonly put?: never
-    /** @description Run the experimental assistant on the caller's thread of the configuration, or replay the run when the request carries `Last-Event-ID`. Answers 409 when the thread cannot be continued from this deployment or another run is still answering, and 503 while the server shuts down; sent again, the message reaches another instance. Answers 403 unless the customer has the AI Assistant feature flag on. */
+    /** @description Run the experimental assistant on the caller's thread of the configuration, or replay the run when the request carries `Last-Event-ID`. Answers 409 when the thread cannot be continued or another run is still answering, and 503 while the server shuts down; sent again, the message reaches another instance. A 409 for a thread that cannot be continued, because it is closed, was started with another setup or has reached its size limit, carries the `x-assistant-thread-continuable: false` response header; the thread continues once it is compacted. Answers 403 unless the customer has the AI Assistant feature flag on. */
     readonly post: operations['assistantChat']
     readonly delete?: never
     readonly options?: never
@@ -212,6 +212,23 @@ export interface paths {
     readonly patch?: never
     readonly trace?: never
   }
+  readonly '/configurations/{configurationId}/assistant/chat/compact': {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    readonly get?: never
+    readonly put?: never
+    /** @description Compact the caller's latest assistant thread on the configuration, which cannot be continued as it is: the thread is summarized and closed, and a new, empty thread is opened that links to it and keeps the summary. Nothing is run; the next chat request runs on the new thread, with the summary in its system prompt. Answers 409 when there is no thread, the latest one can be continued as it is, or one of its runs is still running, and 502 when the summary could not be made; nothing is closed then and the request can be sent again. */
+    readonly post: operations['compactAssistantThread']
+    readonly delete?: never
+    readonly options?: never
+    readonly head?: never
+    readonly patch?: never
+    readonly trace?: never
+  }
   readonly '/configurations/{configurationId}/assistant/chat/runs': {
     readonly parameters: {
       readonly query?: never
@@ -246,6 +263,23 @@ export interface paths {
     readonly patch?: never
     readonly trace?: never
   }
+  readonly '/configurations/{configurationId}/assistant/chat/threads/{threadId}': {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path?: never
+      readonly cookie?: never
+    }
+    /** @description Load one of the caller's assistant threads on the configuration by the id a thread read named in `x-assistant-previous-thread`, newest window first. The response carries that header again when the thread itself continues an earlier one. Answers 404 for a thread that is not the caller's on this configuration. */
+    readonly get: operations['getAssistantEarlierThread']
+    readonly put?: never
+    readonly post?: never
+    readonly delete?: never
+    readonly options?: never
+    readonly head?: never
+    readonly patch?: never
+    readonly trace?: never
+  }
   readonly '/configurations/{configurationId}/chat': {
     readonly parameters: {
       readonly query?: never
@@ -993,6 +1027,12 @@ export interface paths {
 export type webhooks = Record<string, never>
 export interface components {
   schemas: {
+    /** @description The deployment webhook failed or returned invalid assistant setup. */
+    readonly BadGatewayError: {
+      readonly message: string
+      /** @enum {number} */
+      readonly statusCode: 502
+    }
     /** @description Bad Request: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
     readonly BadRequestError: {
       /** @example Expected integer, received string! */
@@ -2443,6 +2483,15 @@ export interface operations {
           readonly 'application/json': components['schemas']['NotFoundError']
         }
       }
+      /** @description Bad Gateway! */
+      readonly 502: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadGatewayError']
+        }
+      }
       /** @description An unexpected error occurred! */
       readonly default: {
         headers: {
@@ -2527,6 +2576,15 @@ export interface operations {
           readonly 'application/json': components['schemas']['ConflictError']
         }
       }
+      /** @description Bad Gateway! */
+      readonly 502: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadGatewayError']
+        }
+      }
       /** @description Service Unavailable! */
       readonly 503: {
         headers: {
@@ -2547,6 +2605,97 @@ export interface operations {
       }
     }
   }
+  readonly compactAssistantThread: {
+    readonly parameters: {
+      readonly query?: never
+      readonly header?: never
+      readonly path: {
+        /** @description The configuration on which the caller's assistant thread is used. */
+        readonly configurationId: components['schemas']['ConfigurationUuid']
+      }
+      readonly cookie?: never
+    }
+    readonly requestBody?: never
+    readonly responses: {
+      /** @description The thread was closed and its successor opened. */
+      readonly 200: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': {
+            /** @description The closed thread the new one continues. */
+            readonly previousThreadId: string
+            /** @description The new thread, which the next chat request runs on. */
+            readonly threadId: string
+          }
+        }
+      }
+      /** @description Bad Request! */
+      readonly 400: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadRequestError']
+        }
+      }
+      /** @description Unauthorized! */
+      readonly 401: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['UnauthorizedError']
+        }
+      }
+      /** @description Forbidden! */
+      readonly 403: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['ForbiddenError']
+        }
+      }
+      /** @description Not Found! */
+      readonly 404: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['NotFoundError']
+        }
+      }
+      /** @description Conflict! */
+      readonly 409: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['ConflictError']
+        }
+      }
+      /** @description Bad Gateway! */
+      readonly 502: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadGatewayError']
+        }
+      }
+      /** @description An unexpected error occurred! */
+      readonly default: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['DefaultResponse']
+        }
+      }
+    }
+  }
   readonly replayAssistantRun: {
     readonly parameters: {
       readonly query: {
@@ -2699,6 +2848,92 @@ export interface operations {
       }
     }
   }
+  readonly getAssistantEarlierThread: {
+    readonly parameters: {
+      readonly query?: {
+        /** @description Cursor of the next older window. */
+        readonly before?: string
+        /** @description Newest window size of the thread; the whole thread when omitted. */
+        readonly limit?: number
+      }
+      readonly header?: never
+      readonly path: {
+        /** @description The configuration on which the caller's assistant thread is used. */
+        readonly configurationId: components['schemas']['ConfigurationUuid']
+        /** @description The thread to read. */
+        readonly threadId: string
+      }
+      readonly cookie?: never
+    }
+    readonly requestBody?: never
+    readonly responses: {
+      /** @description The thread transcript. */
+      readonly 200: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': {
+            readonly [key: string]: unknown
+          }
+        }
+      }
+      /** @description Bad Request! */
+      readonly 400: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadRequestError']
+        }
+      }
+      /** @description Unauthorized! */
+      readonly 401: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['UnauthorizedError']
+        }
+      }
+      /** @description Forbidden! */
+      readonly 403: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['ForbiddenError']
+        }
+      }
+      /** @description Not Found! */
+      readonly 404: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['NotFoundError']
+        }
+      }
+      /** @description Bad Gateway! */
+      readonly 502: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['BadGatewayError']
+        }
+      }
+      /** @description An unexpected error occurred! */
+      readonly default: {
+        headers: {
+          readonly [name: string]: unknown
+        }
+        content: {
+          readonly 'application/json': components['schemas']['DefaultResponse']
+        }
+      }
+    }
+  }
   readonly getChatConversation: {
     readonly parameters: {
       readonly query?: never
@@ -5370,20 +5605,23 @@ export interface operations {
           readonly adminConfigurationSchema?: components['schemas']['ConfigurationSchema']
           /** @description Semantic version (x.y.z) of the deployed application. */
           readonly applicationVersion?: string
-          /** @description What the deployment registers for its experimental assistant: the GraphQL SDL of the application spec, the prompt the SDK generates for its version, the instructions of the integrator and the AI settings. A deployment prepared without it has no assistant. */
-          readonly assistant?: {
-            readonly ai: {
-              /** @enum {string} */
-              readonly model: 'frontier' | 'advanced' | 'balanced' | 'fast'
-              /** @enum {string} */
-              readonly provider: 'openai'
-              /** @enum {string} */
-              readonly reasoning: 'low' | 'medium' | 'high'
-            }
-            readonly instructions?: string
-            readonly prompt: string
-            readonly sdl: string
-          }
+          /** @description Whether the deployment webhook provides assistant setup. Omitted or legacy object registrations disable the assistant; prepare with a current SDK to enable it. */
+          readonly assistant?:
+            | boolean
+            | {
+                readonly ai: {
+                  readonly maxThreadSize?: number
+                  /** @enum {string} */
+                  readonly model: 'frontier' | 'advanced' | 'balanced' | 'fast'
+                  /** @enum {string} */
+                  readonly provider: 'openai'
+                  /** @enum {string} */
+                  readonly reasoning: 'low' | 'medium' | 'high'
+                }
+                readonly instructions?: string
+                readonly prompt: string
+                readonly sdl: string
+              }
           /** @description Configuration of the chat functionality. */
           readonly chat?: components['schemas']['ChatConfiguration']
           readonly configurationSchema: components['schemas']['ConfigurationSchema']
@@ -5590,20 +5828,23 @@ export interface operations {
           readonly adminConfigurationSchema?: components['schemas']['ConfigurationSchema']
           /** @description Semantic version (x.y.z) of the deployed application. */
           readonly applicationVersion?: string
-          /** @description What the deployment registers for its experimental assistant: the GraphQL SDL of the application spec, the prompt the SDK generates for its version, the instructions of the integrator and the AI settings. A deployment prepared without it has no assistant. */
-          readonly assistant?: {
-            readonly ai: {
-              /** @enum {string} */
-              readonly model: 'frontier' | 'advanced' | 'balanced' | 'fast'
-              /** @enum {string} */
-              readonly provider: 'openai'
-              /** @enum {string} */
-              readonly reasoning: 'low' | 'medium' | 'high'
-            }
-            readonly instructions?: string
-            readonly prompt: string
-            readonly sdl: string
-          }
+          /** @description Whether the deployment webhook provides assistant setup. Omitted or legacy object registrations disable the assistant; prepare with a current SDK to enable it. */
+          readonly assistant?:
+            | boolean
+            | {
+                readonly ai: {
+                  readonly maxThreadSize?: number
+                  /** @enum {string} */
+                  readonly model: 'frontier' | 'advanced' | 'balanced' | 'fast'
+                  /** @enum {string} */
+                  readonly provider: 'openai'
+                  /** @enum {string} */
+                  readonly reasoning: 'low' | 'medium' | 'high'
+                }
+                readonly instructions?: string
+                readonly prompt: string
+                readonly sdl: string
+              }
           /** @description Configuration of the chat functionality. */
           readonly chat?: components['schemas']['ChatConfiguration']
           readonly configurationSchema: components['schemas']['ConfigurationSchema']

package/dist/configurator/application-runtime/extensions/selectors.js

@@ -1 +1 @@
-import{AnimationSystem as e,AssistantSystem as t,CameraControlSystem as n,CameraSystem as o,CanvasSystem as r,DragAndDropSystem as s,ExportSystem as g,GraphQLSystem as i,ImageRenderingSystem as a,LayoutSystem as m,SketchingSystem as S}from"./systems/index.js";export const createConfiguratorExtensionSelectors=y=>{let{domainContextSelectors:u,specSelectors:w,domainServicesSelectors:C,accessSelectors:c,commonServicesSelectors:f}=y,l={getConfigurationId:()=>c.getConfiguratorConfigurationId(),getAuthorizedClient:()=>f.getConfiguratorAuthorizedClient(),domainContextSelectors:u,domainServicesSelectors:C,specSelectors:w},d={getSystems:()=>G,getCanvasSystem:()=>p,getCameraControlSystem:()=>A,getAnimationSystem:()=>h,getDragAndDropSystem:()=>E,getImageRenderingSystem:()=>v,getLayoutSystem:()=>L,getSketchingSystem:()=>j,getExportSystem:()=>I,getCameraSystem:()=>k,getGraphQLSystem:()=>z,getAssistantSystem:()=>D},x={...l,configuratorExtensionSelectors:d},p=new r(l),A=new n({configuratorExtensionSelectors:d}),E=new s(x),h=new e(l),I=new g(x),z=new i(l),D=new t({configuratorExtensionSelectors:d,domainContextSelectors:u,specSelectors:w}),L=new m(l),j=new S(x),k=new o(x),v=new a(x),G={cameraControlSystem:A,layoutSystem:L,sketchingSystem:j,dragAndDropSystem:E,canvasSystem:p,cameraSystem:k,exportSystem:I,imageRenderingSystem:v,animationSystem:h,graphQLSystem:z,assistantSystem:D};return d};
+import{AnimationSystem as e,AssistantSystem as t,CameraControlSystem as n,CameraSystem as o,CanvasSystem as r,DragAndDropSystem as s,ExportSystem as g,GraphQLSystem as i,ImageRenderingSystem as a,LayoutSystem as m,SketchingSystem as S}from"./systems/index.js";export const createConfiguratorExtensionSelectors=y=>{let{domainContextSelectors:u,specSelectors:w,domainServicesSelectors:C,accessSelectors:c,commonServicesSelectors:f}=y,d={getConfigurationId:()=>c.getConfiguratorConfigurationId(),getAuthorizedClient:()=>f.getConfiguratorAuthorizedClient(),domainContextSelectors:u,domainServicesSelectors:C,specSelectors:w},l={getSystems:()=>G,getCanvasSystem:()=>p,getCameraControlSystem:()=>A,getAnimationSystem:()=>E,getDragAndDropSystem:()=>h,getImageRenderingSystem:()=>v,getLayoutSystem:()=>L,getSketchingSystem:()=>j,getExportSystem:()=>I,getCameraSystem:()=>k,getGraphQLSystem:()=>z,getAssistantSystem:()=>D},x={...d,configuratorExtensionSelectors:l},p=new r(d),A=new n({configuratorExtensionSelectors:l}),h=new s(x),E=new e(d),I=new g(x),z=new i(d),D=new t(x),L=new m(d),j=new S(x),k=new o(x),v=new a(x),G={cameraControlSystem:A,layoutSystem:L,sketchingSystem:j,dragAndDropSystem:h,canvasSystem:p,cameraSystem:k,exportSystem:I,imageRenderingSystem:v,animationSystem:E,graphQLSystem:z,assistantSystem:D};return l};

package/dist/configurator/application-runtime/extensions/systems/assistant-system/assistant-system.d.ts

@@ -1,35 +1,267 @@
 import type { AnyClientTool } from '@tanstack/ai';
-import type { DomainContextSelectors, InitializableSystem, SpecSelectors } from '#package/domain';
+import { type UIMessage } from '@tanstack/ai-client';
+import { type ObservableWithLastValue } from '@salsita-ai/common/utils';
+import { type AuthorizedPhoenixApiClient } from '#package/client';
+import type { DomainContextSelectors, DomainServicesSelectors, InitializableSystem, SpecSelectors } from '#package/domain';
 import type { ConfiguratorExtensionSelectors } from '../../selectors.js';
 /** A tool of the assistant that the model calls and the browser runs, as the chat client accepts it. */
 export type AssistantClientTool = AnyClientTool;
 /**
  * Constructor context of an `AssistantSystem`: whole selector objects, like its peers take them, so
- * the tools reach the store, the session mode and the `GraphQLSystem` when they are called.
+ * the tools reach the store, the session mode and the `GraphQLSystem` when they are called, and the
+ * chat reaches the server of the current session when it sends a request.
  */
 export interface AssistantSystemContext {
     readonly configuratorExtensionSelectors: ConfiguratorExtensionSelectors;
     readonly domainContextSelectors: DomainContextSelectors;
+    readonly domainServicesSelectors: DomainServicesSelectors;
     readonly specSelectors: SpecSelectors;
+    readonly getConfigurationId: () => string;
+    readonly getAuthorizedClient: () => AuthorizedPhoenixApiClient<any, any, any>;
 }
 /**
- * Owns the client tools of the conversational assistant: `getBrowserDetails`, `query` and `apply`.
- * They are built once, over the runtime's selectors, and offered only by a configurator whose
- * application spec has an `assistant` section, so a configurator without one has no tools to
- * register with a chat.
+ * The conversation with the assistant as the panel paints it. One value is published per change, so
+ * it changes with every chunk of a streaming reply.
+ */
+export interface AssistantChatSnapshot {
+    /** The thread as painted: hydrated from the server, then streamed. */
+    readonly messages: ReadonlyArray<UIMessage>;
+    /** True while a round of a reply streams or its browser tools run; false in the pause before the next round. */
+    readonly isLoading: boolean;
+    readonly error: Error | undefined;
+    /**
+     * HTTP status of the latest request the server answered with a failure, for telling a refusal from
+     * a dropped connection when `error` is set. Nothing when the latest answered request succeeded or
+     * the server was never reached.
+     */
+    readonly failedStatus: number | undefined;
+    /** False when the server said this session may read the thread but not add to it. */
+    readonly isContinuable: boolean;
+    /** False until the first request of the chat, the thread read, was answered or failed. */
+    readonly isLoaded: boolean;
+    /**
+     * True while a thread this session may not continue is being continued in a new one, which the
+     * user's next message starts; see {@link AssistantSystem.resume}.
+     */
+    readonly isResuming: boolean;
+    /**
+     * The closed threads the painted thread continues, oldest first: the ones that were resumed while
+     * the chat was open, and the ones loaded with {@link AssistantSystem.loadEarlierThread}.
+     */
+    readonly earlierThreads: ReadonlyArray<AssistantEarlierThreadSnapshot>;
+    /** True when the server holds a thread older than the oldest painted one. */
+    readonly hasEarlierThread: boolean;
+    /** True while that older thread is being loaded. */
+    readonly isLoadingEarlierThread: boolean;
+}
+/** A closed thread of the conversation as the panel paints it above the thread that continues it. */
+export interface AssistantEarlierThreadSnapshot {
+    readonly threadId: string;
+    readonly messages: ReadonlyArray<UIMessage>;
+}
+/**
+ * The built-in assistant panel as a layout and the toolbar button see it: whether it is open, and
+ * the few facts about it they render. It changes only when one of those does.
+ */
+export interface AssistantPanelSnapshot {
+    readonly open: boolean;
+    /** True when a reply finished while the panel was closed and the panel was not opened since. */
+    readonly hasUnreadReply: boolean;
+    /** True while the message input has focus; a phone layout gives the panel the whole screen then. */
+    readonly isInputFocused: boolean;
+}
+/**
+ * Owns the conversational assistant of a configurator: its client tools (`getBrowserDetails`,
+ * `query` and `apply`), the chat with the server, the state of the built-in panel, and the record
+ * of what changed in the configuration since the agent last acted, which every user message carries.
+ *
+ * The server owns the thread, so the chat keeps nothing in browser storage: its client hydrates
+ * from the server and rejoins a reply that is still streaming.
+ *
+ * WORKAROUND: the runtime cannot tell a system that its configuration was left, and a system cannot
+ * observe the application spec. Until it can do both, the chat is started and ended from outside,
+ * through {@link AssistantSystem.activate}; see there for what that costs.
  */
 export declare class AssistantSystem implements InitializableSystem {
     private readonly _context;
     private readonly _tools;
-    private _isInitialized;
+    private readonly _chat;
+    private readonly _panel;
+    /** Identity of the current `activate()` call; nothing while the chat is not active. */
+    private _activation;
+    /** The chat of the current activation; nothing while no chat is active. */
+    private _current;
+    /**
+     * Chats that have ended while their reply was still running and are finishing it in the
+     * background. Each leaves the set when its reply ends or when a new chat takes its thread over.
+     */
+    private readonly _finishing;
+    /**
+     * The thread before the oldest painted one, as the server named it; nothing when the painted
+     * threads start the conversation. `hasEarlierThread` of the chat says whether it is set.
+     */
+    private _olderThreadId;
+    /** The resume that is running, so two sends that find the thread locked share one. */
+    private _resuming;
+    /**
+     * The message the server refused on a chat because its thread cannot be continued, by where it
+     * starts in the chat's messages: it is painted, but it is not part of the thread, so a resume
+     * leaves it out of the closed thread it paints above the new one.
+     */
+    private _refused;
+    /**
+     * The chat a message is being sent on for the first time. When the server refuses that message
+     * because the thread cannot be continued, the refusal is not a failure of the chat: the thread is
+     * resumed and the message is sent again; see `send`.
+     */
+    private _firstAttempt;
+    /**
+     * Identity of the chain of threads that is painted. A resumed chat keeps it, because its new
+     * thread continues the same chain; any other new chat starts another one.
+     */
+    private _chain;
+    /** The earlier thread that is being loaded, so a second press loads nothing twice. */
+    private _loadingThreadId;
+    private readonly _recorder;
+    /** The recorder's subscription to the committed emissions of the store; made by the first `initialize()`. */
+    private _recording;
     constructor(_context: AssistantSystemContext);
+    /** The conversation. It never completes, and holds the empty chat whenever no chat is active. */
+    readonly chat$: ObservableWithLastValue<AssistantChatSnapshot>;
+    /** The state of the built-in panel. It never completes. */
+    readonly panel$: ObservableWithLastValue<AssistantPanelSnapshot>;
+    /**
+     * A new configuration load: the chat of the previous one is deactivated and both observables go
+     * back to their empty values. An activation that is still held outlives it and gets the chat of
+     * the new load, because the page that holds it can be mounted before this runs: a configuration
+     * that is entered again renders its page at once and initializes from an effect after the page's.
+     *
+     * Accepted cost: on such a re-entry the thread is read twice. The page's `activate()` has already
+     * created a client and started its read when this runs, and that client is replaced here, because
+     * the system cannot tell that it was created for the load that is only now being initialized.
+     *
+     * The change recorder starts over from the loaded state, so the first message after a load says
+     * that the changes are unavailable. The store is retained across loads and has already emitted the
+     * loaded state when this runs, so one subscription serves every load.
+     */
     initialize: () => void;
     /**
-     * The tools to register with the chat: all of them when the application spec has an `assistant`
-     * section, none otherwise or before the first initialization. The section is read on every call
-     * and not in `initialize()`, because editor hot reload adds or removes it by reconciliation alone.
-     * Each answer is always the same array instance, so the getter is a valid snapshot for a hook
-     * subscribed to the runtime.
+     * Starts the chat of the loaded configuration: creates the client, which reads the thread from the
+     * server and rejoins a reply that is still running. The returned function ends it.
+     *
+     * WORKAROUND, to be replaced once the runtime has teardown and spec observation for systems. Two
+     * things a system cannot learn by itself are decided by the caller, the loaded configurator page:
+     *
+     * - Whether the application spec has an `assistant` section, also after editor hot reload added or
+     *   removed it. The page calls this only while the section is there; the system does not check.
+     * - That the user left the configuration. No `initialize()` follows a route change, so without the
+     *   returned function the chat would go on working on a configuration nobody looks at.
+     *
+     * Ending the chat does not cut a running reply off: it finishes in the background, where every
+     * tool call it still makes is answered with a refusal that tells the model to stop, and it no
+     * longer reaches `chat$` or `panel$`. A tool call that is already running when the chat ends is
+     * not interrupted, so an `apply` that has started may still commit. The background reply keeps
+     * the configuration and the authorized client it started with.
+     *
+     * The background reply is disconnected when a new chat starts for the same configuration, which is
+     * what opening the configuration again does: see `_takeOverThread`.
+     */
+    activate: () => (() => void);
+    /**
+     * Sends a user message with the record of what changed in the configuration since the agent last
+     * acted, which the server puts in front of the message for the model. The record is taken only
+     * when there is a chat to send it on, because taking it moves its baseline.
+     *
+     * A thread can end in a tool call that nothing will answer: its reply parked while no page was
+     * open, or the page that ran the tool was left before the result was sent. The client refuses to
+     * send while it waits on such a call, so the wait is given up first, and the server records for
+     * the model that the call got no result.
+     *
+     * A thread this session may not continue is resumed first, in a new thread; see `resume`. When
+     * that fails the message is not sent.
+     *
+     * The chat can be out of date about that: the thread reached its size limit with the reply before
+     * this message, or the assistant's setup changed while the configurator stayed open. The server
+     * then refuses the message and says that the thread cannot be continued. The message stays
+     * painted while the thread is resumed, and is then sent again on the new thread, with the change
+     * record it was first sent with. This happens once: a refusal of the second attempt is the
+     * failure it is. When resuming fails, the message is left as any message that failed to send:
+     * painted, with the failure as the error of the chat.
+     *
+     * Accepted: when the server refuses the compaction itself with a conflict, because another tab
+     * compacted the thread or a run is still running, the thread is read again (see `resume`) and
+     * the refused message is gone without a notice. It takes two tabs or a run racing the send, and
+     * the user writes the message again, as after any reload of a thread that failed.
+     *
+     * It never rejects: a message the client could not send is reported as the error of the chat.
+     */
+    send: (content: string) => Promise<void>;
+    /**
+     * Makes the chat ready for the next message. A thread the server no longer lets this session
+     * continue, because the assistant's setup changed since it was started or the thread reached
+     * its size limit, is compacted there: the
+     * server closes it and opens a thread that starts from its summary. The messages painted so far
+     * move to `earlierThreads`, and a new client takes the new thread over.
+     *
+     * Resolves to whether a message can be sent now: at once for a thread that can continue, and
+     * `false` when there is no chat or the compaction failed, which is reported as the error of the
+     * chat. It never rejects. Calling it again runs the compaction again. A compaction the server
+     * refuses with a conflict is not a failure: the thread is read again and `false` is returned.
+     */
+    resume: () => Promise<boolean>;
+    /**
+     * Loads the thread before the oldest painted one and paints it above. Does nothing when there is
+     * none or one is being loaded. A load that fails is logged and can be asked for again.
+     */
+    loadEarlierThread: () => Promise<void>;
+    /**
+     * Stops the reply on both sides. Closing the stream alone keeps the server run going, because a
+     * closed connection is also how a reload looks and a reload must be able to rejoin the run.
+     */
+    stop: () => Promise<void>;
+    /**
+     * Loads the thread from the server again, rejoining a reply that is still running there. It never
+     * sends a message again, because the server may already hold it; a message that did not reach the
+     * server is therefore gone from the thread and has to be written again.
+     */
+    reloadThread: () => void;
+    setOpen: (open: boolean) => void;
+    setInputFocused: (isInputFocused: boolean) => void;
+    /**
+     * Where the message starts that is being sent on the chat for the first time and that the server
+     * refused because its thread cannot be continued, so it never reached the thread; `-1` when there
+     * is no such message. A refused continuation of a reply is not one: its message is stored.
+     */
+    private _findRefusedMessageIndex;
+    private _sendOn;
+    private _resume;
+    private _committedState;
+    private _patchPanel;
+    /**
+     * Disconnects every chat that is still finishing a reply on the thread of the given configuration,
+     * so the chat that is about to start is the only one on it.
+     *
+     * Two clients on one thread would both follow the same server run: the new one rejoins it when it
+     * reads the thread. Both would then handle the run's next tool call, the old one with a refusal
+     * and the new one for real, and both would send the result back, of which the server accepts one.
+     * The model could be told that nothing was run about a change that was made.
+     *
+     * Stopping a client closes its stream in the browser and cancels nothing on the server: a run that
+     * is still producing goes on there and the new chat rejoins it. The stopped client also drops the
+     * result of a tool call that is still running in it, and any continuation it has not sent yet. Such
+     * a call still finishes, so an `apply` may commit, but the server never gets its result: the run is
+     * parked on the call with nothing running for the new chat to rejoin, and the thread waits on it
+     * until the user's next message gives the wait up; see `send`.
+     *
+     * A chat that finishes a reply for another configuration is on another thread and is left alone.
+     */
+    private _takeOverThread;
+    private _startClient;
+    /**
+     * Lets go of the current chat and puts the empty chat in its place. The client itself is left as
+     * it is: whether it finishes its reply or is cut off is the caller's decision.
      */
-    getTools: () => readonly AssistantClientTool[];
+    private _retireChat;
+    /** Ends the current chat without cutting its reply off. */
+    private _endChat;
 }