@salsita-ai/sdk 0.50.0-develop.dfac20c66b → 0.50.0-develop.ea0d8e208d

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 has a different setup or is closed; a chat request then answers 409. */
     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 with this setup 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. */
     readonly post: operations['assistantChat']
     readonly delete?: never
     readonly options?: never
@@ -993,6 +993,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 +2449,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 +2542,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: {
@@ -5370,20 +5394,22 @@ 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: {
+                  /** @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 +5616,22 @@ 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: {
+                  /** @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,180 @@
 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;
+}
+/**
+ * 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;
+    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 ends early 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.
+     *
+     * It never rejects: a message the client could not send is reported as the error of the chat.
+     */
+    send: (content: string) => 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;
+    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;
 }

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

@@ -1 +1 @@
-import{createBrowserDetailsClientTool as t}from"./browser-details.js";import{createApplyClientTool as e,createQueryClientTool as s}from"./graphql-tools.js";let i=[];export class AssistantSystem{_context;_tools;_isInitialized=!1;constructor(i){this._context=i;let{configuratorExtensionSelectors:o,domainContextSelectors:l}=i,r={getGraphQLSystem:()=>o.getGraphQLSystem(),getStoreSystem:()=>l.getStoreSystem(),getActiveMode:()=>l.getActiveMode()};this._tools=[t(),s(r),e(r)]}initialize=()=>{this._isInitialized=!0};getTools=()=>this._isInitialized&&this._context.specSelectors.getAssistant()?this._tools:i}
+import{ChatClient as t,fetchServerSentEvents as e}from"@tanstack/ai-client";import{BehaviorSubject as i}from"rxjs";import{skip as s}from"rxjs/operators";import{isShallowEqual as a}from"@salsita-ai/common/utils";import{createBrowserDetailsClientTool as r}from"./browser-details.js";import{ChangeRecorder as n}from"./change-recorder.js";import{createApplyClientTool as o,createQueryClientTool as c}from"./graphql-tools.js";let l=Object.freeze({messages:Object.freeze([]),isLoading:!1,error:void 0,failedStatus:void 0,isContinuable:!0,isLoaded:!1}),h=Object.freeze({open:!1,hasUnreadReply:!1,isInputFocused:!1}),d=Object.freeze({}),g=Object.freeze({results:Object.freeze([]),committed:!1,sideEffects:Object.freeze([]),message:"Nothing was run, because the user closed the configurator while this reply was being written. Do not call any more tools in this reply and end it now. The tools work again as soon as the user writes the next message."}),u=t=>{if(t.getError())return!0;let e=t.getMessages().at(-1)?.parts.at(-1);return e?.type!=="tool-call"&&e?.type!=="tool-result"};export class AssistantSystem{_context;_tools;_chat=new i(l);_panel=new i(h);_activation=null;_current=null;_finishing=new Set;_recorder;_recording=null;constructor(t){this._context=t;let{configuratorExtensionSelectors:e,domainContextSelectors:i,domainServicesSelectors:s,specSelectors:a}=t;this._recorder=new n({maxEntities:30},{readers:{selectedEntityId:t=>i.getNavigationSystem().getActiveSelectionState(t),navigationState:t=>i.getNavigationSystem().getActiveNavigationState(t),viewState:t=>i.getNavigationSystem().getActiveViewState(t),toolState:t=>i.getNavigationSystem().getActiveToolState(t)},getExposedFields:()=>a.getAssistant()?.fields??d,resolveLocalizable:t=>s.getResolveLocalizable()(t)});let l={getGraphQLSystem:()=>e.getGraphQLSystem(),getStoreSystem:()=>i.getStoreSystem(),getActiveMode:()=>i.getActiveMode(),clearChanges:()=>this._recorder.clear(this._committedState())};this._tools=[r(),c(l),o(l)]}chat$=this._chat;panel$=this._panel;initialize=()=>{let{committed:t}=this._context.domainContextSelectors.getStoreSystem().stateSlices;this._recording??=t.pipe(s(1)).subscribe(this._recorder.record),this._recorder.reset(t.value.state),this._endChat(),this._patchPanel(h),this._activation&&this._startClient()};activate=()=>{this._endChat();let t={};return this._activation=t,this._startClient(),()=>{this._activation===t&&(this._activation=null,this._endChat())}};send=async t=>{let e=this._current;if(!e)return;let{client:i}=e;i.getIsLoading()||null===i.getResumeState()||i.stop();let s={changes:this._recorder.take(this._committedState())};try{await i.sendMessage({content:t,metadata:s})}catch(i){let t=i instanceof Error?i:Error(String(i));e.generation.active&&this._chat.next({...this._chat.value,error:t}),this._context.domainServicesSelectors.getLogger().error("The assistant message could not be sent",{},t)}};stop=async()=>{let t=this._current;if(!t)return;let e=t.client.getCurrentRunId();if(t.client.stop(),null!=e)try{let i=t.getConnection();await fetch(`${i.url}/runs/${encodeURIComponent(e)}/cancel`,{method:"POST",headers:await i.headers()})}catch(t){this._context.domainServicesSelectors.getLogger().warn("Could not cancel the assistant run on the server",{error:t})}};reloadThread=()=>{if(!this._activation)return;let t=this._retireChat();t?.client.stop(),t?.dispose(),this._recorder.reset(this._committedState()),this._startClient()};setOpen=t=>{this._patchPanel(t?{open:t,hasUnreadReply:!1}:{open:t,isInputFocused:!1})};setInputFocused=t=>{this._patchPanel({isInputFocused:t})};_committedState=()=>this._context.domainContextSelectors.getStoreSystem().stateSlices.committed.value.state;_patchPanel=t=>{let e={...this._panel.value,...t};a(e,this._panel.value)||this._panel.next(e)};_takeOverThread=t=>{for(let e of this._finishing)e.configurationId===t&&(e.client.stop(),e.dispose())};_startClient=()=>{let i={active:!0},s=this._context.getConfigurationId();this._takeOverThread(s);let r=this._context.getAuthorizedClient(),n=()=>r.getAssistantChatConnection(s),o=t=>{if(!i.active)return;let e={...this._chat.value,...t};a(e,this._chat.value)||this._chat.next(e)},c=async(t,e)=>{let i=await fetch(t,e).finally(()=>o({isLoaded:!0})),s=i.headers.get("x-assistant-thread-continuable");return o({failedStatus:i.ok?void 0:i.status,...null!=s&&{isContinuable:"false"!==s}}),i},l=async()=>({headers:await n().headers(),fetchClient:c}),h=e(()=>n().url,l),d=e(()=>`${n().url}/runs`,l),_=this._tools.map(t=>({...t,execute:(e,s)=>i.active?t.execute?.(e,s):g})),m=new t({threadId:`assistant:${s}`,connection:{...h,joinRun:d.joinRun},persistence:!0,history:{pageSize:50},tools:_,onMessagesChange:t=>o({messages:t}),onLoadingChange:t=>{let e=i.active&&this._chat.value.isLoading;o({isLoading:t}),!t&&u(m)&&(i.active?e&&!this._panel.value.open&&this._patchPanel({hasUnreadReply:!0}):v())},onErrorChange:t=>{i.active&&t!==this._chat.value.error&&(o({error:t}),t&&this._context.domainServicesSelectors.getLogger().error("The assistant request failed",{status:this._chat.value.failedStatus},t))}}),p=!1,v=()=>{p||(p=!0,this._finishing.delete(S),m.dispose())},S={client:m,configurationId:s,generation:i,getConnection:n,dispose:v};this._current=S,m.attach()};_retireChat=()=>{let t=this._current;return this._current=null,t&&(t.generation.active=!1),this._chat.value!==l&&this._chat.next(l),t};_endChat=()=>{let t=this._retireChat();if(t){if(!t.client.getIsLoading()&&u(t.client))return void t.dispose();this._finishing.add(t)}}}

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

@@ -0,0 +1,85 @@
+import type { Localizable } from '@salsita-ai/common/utils';
+import { type $DomainEntity, type AssistantManifest, type DomainEntity, type DomainState, type StateEmission } from '#package/domain';
+type AnyDomainEntity = DomainEntity<string>;
+type AnyDomainState = DomainState<AnyDomainEntity>;
+type AnyStateEmission = StateEmission<AnyDomainEntity, Record<string, $DomainEntity<AnyDomainEntity>>>;
+/**
+ * What the change record compares besides the entities: the values the `Query` root of the
+ * assistant's schema exposes as `selectedEntity` and `navigation`, read off a state.
+ */
+export interface ChangeRecorderStateReaders {
+    readonly selectedEntityId: (state: AnyDomainState) => string | undefined;
+    readonly navigationState: (state: AnyDomainState) => string | undefined;
+    readonly viewState: (state: AnyDomainState) => string | undefined;
+    readonly toolState: (state: AnyDomainState) => string | undefined;
+}
+/** What a {@link ChangeRecorder} reads from the running configurator. */
+export interface ChangeRecorderContext {
+    readonly readers: ChangeRecorderStateReaders;
+    /**
+     * The field table of the assistant manifest: per entity type of the schema, each exposed field
+     * name with the stored field or expression it reads. The record lists nothing the table does not
+     * hold, so the agent is shown only what it could also query. Read at every take, because editor
+     * hot reload replaces the manifest.
+     */
+    readonly getExposedFields: () => AssistantManifest['fields'];
+    readonly resolveLocalizable: (message: Localizable) => string;
+}
+export interface ChangeRecorderProps {
+    /** More differing entities than this are counted and not listed. */
+    readonly maxEntities: number;
+}
+/**
+ * Records what changed in the committed configuration since the assistant agent last acted, and
+ * prints it as the change record a user message carries to the agent.
+ *
+ * The record is a net diff: the committed state at the last take or clear is kept as the baseline
+ * and compared with the current one, so a value that was changed and changed back is not listed.
+ * Of the emissions in between, only the last update that touched each entity and each entity field
+ * is kept, to say why a line is there. Selection and navigation are read off the two states and
+ * never from their updates.
+ *
+ * Only what the assistant manifest exposes is listed: entities of the types its schema has, and of
+ * their stored fields the exposed ones, under their exposed names and localized like the schema
+ * returns them. A change of anything else is not in the record.
+ */
+export declare class ChangeRecorder {
+    private readonly _props;
+    private readonly _context;
+    private _baseline;
+    /** True from a reset until the first take: what happened before the baseline is not known. */
+    private _isUnavailable;
+    private readonly _touches;
+    private _lastReset;
+    private _wasUndoneOrRedone;
+    constructor(_props: ChangeRecorderProps, _context: ChangeRecorderContext);
+    /** Starts over from this committed state; the next take reports `unavailable`. */
+    reset: (state: AnyDomainState) => void;
+    /** Records one committed emission: the last update that touched each entity and field, or the reset. */
+    record: (emission: AnyStateEmission) => void;
+    /** The change record since the last take or clear, as the prompt describes it; moves the baseline. */
+    take: (state: AnyDomainState) => string;
+    /** Forgets what was recorded and makes this committed state the baseline. */
+    clear: (state: AnyDomainState) => void;
+    private _touchesOf;
+    private _touchFields;
+    private _print;
+    private _diffStates;
+    /** Added and modified entities in the order of the current state, then the deleted ones in the order they had. */
+    private _diffEntities;
+    /**
+     * The lines of the exposed stored fields that differ, in manifest order. A field no update
+     * touched since its entity was created or replaced under an id that existed before is explained
+     * by that creation.
+     */
+    private _diffFields;
+    /** Why a line is in the record; a line no recorded update explains was left by a reset. */
+    private _comment;
+    /**
+     * What the agent is told about an update, else what the user was told, else the update tag. As
+     * for `sideEffects`, an `agentHint` replaces the `hint` whatever it holds: `null` or empty text
+     * hides the wording from the agent, not the change, so the tag stands in.
+     */
+    private _explain;
+}
+export {};

package/dist/configurator/application-runtime/extensions/systems/assistant-system/change-recorder.js

@@ -0,0 +1 @@
+import{match as e}from"ts-pattern";import{isUndoRedoReset as t}from"#package/domain";import{localize as i}from"../graphql-system/graphql-system.js";let s=[["selected","selectedEntityId"],["navigationState","navigationState"],["viewState","viewState"],["toolState","toolState"]],n=e=>e.length>80?`${e.slice(0,80)}…`:e,a=e=>void 0===e||""===e?"none":e,r=e=>new Map(Object.entries(e)),l=["id","type"];export class ChangeRecorder{_props;_context;_baseline;_isUnavailable=!0;_touches=new Map;_lastReset;_wasUndoneOrRedone=!1;constructor(e,t){this._props=e,this._context=t}reset=e=>{this.clear(e),this._isUnavailable=!0};record=i=>{if("reset"===i.kind){this._touches.clear(),this._lastReset=t(i)?"undo/redo":"reset",this._wasUndoneOrRedone||="undo/redo"===this._lastReset;return}for(let t of i.updates)e(t).with({kind:"createDomainEntity"},e=>{this._touchesOf(e.entityId).created=e}).with({kind:"deleteEntity"},e=>{let t=this._touchesOf(e.entityId);t.fields.clear(),t.deleted=e}).with({kind:"modifyDomainEntity"},e=>{this._touchFields(e.entityId,Object.keys(e.stateDelta),e)}).with({kind:"replaceDomainEntity"},e=>{let{replacementEntity:t}=e;this._touchesOf(e.entityId).fields.clear(),this._touchesOf(e.entityId).deleted=e,this._touchesOf(t.id).created=e}).with({kind:"createEphemeralRecord"},{kind:"modifyEphemeralRecord"},{kind:"deleteEphemeralRecord"},()=>{}).exhaustive()};take=e=>{let t=this._print(e);return this.clear(e),this._isUnavailable=!1,t};clear=e=>{this._baseline=e,this._touches.clear(),this._lastReset=void 0,this._wasUndoneOrRedone=!1};_touchesOf=e=>{let t=this._touches.get(e);if(t)return t;let i={created:void 0,deleted:void 0,fields:new Map};return this._touches.set(e,i),i};_touchFields=(e,t,i)=>{let s=this._touchesOf(e);for(let e of t)s.fields.set(e,i)};_print=e=>{let t=this._baseline;if(this._isUnavailable||!t)return"[changes: unavailable]";let{lines:i,count:s}=this._diffEntities(t,e);if(s>this._props.maxEntities)return`[changes: too many (${s})]`;let n=[...this._diffStates(t,e),...i];return 0===n.length?"[changes: none]":["[changes]",...this._wasUndoneOrRedone?["reset: undo/redo"]:[],...n].join("\n")};_diffStates=(e,t)=>s.flatMap(([i,s])=>{let n=a(this._context.readers[s](e)),r=a(this._context.readers[s](t));return n===r?[]:[`${i}: ${n} -> ${r}`]});_diffEntities=(e,t)=>{let i=this._context.getExposedFields(),s=new Map(e.entities.map(e=>[e.id,e])),n=new Set(t.entities.map(e=>e.id)),a=t.entities.flatMap(e=>{let t=i[e.type],n=s.get(e.id);if(!t)return[];if(!n)return[[`A ${e.id}${this._comment(this._touches.get(e.id)?.created)}`]];let a=n===e?[]:this._diffFields(n,e,t);return a.length>0?[[`M ${e.id}`,...a]]:[]}),r=e.entities.filter(e=>i[e.type]&&!n.has(e.id)).map(e=>[`D ${e.id}${this._comment(this._touches.get(e.id)?.deleted)}`]);return{lines:[...a,...r].flat(),count:a.length+r.length}};_diffFields=(e,t,s)=>{let a=r(e),d=r(t),o=this._touches.get(t.id);return Object.entries(s).flatMap(([e,{source:t,localized:s}])=>{if(!(!t.startsWith("$")&&!l.includes(t)))return[];let r=e=>{let t;return void 0===(t=s?i(e,this._context.resolveLocalizable):e)?"undefined":JSON.stringify(t)},h=r(a.get(t)),c=r(d.get(t));return h===c?[]:[`  ${e}: ${n(h)} -> ${n(c)}${this._comment(o?.fields.get(t)??o?.created)}`]})};_comment=e=>e?` # ${this._explain(e).replace(/\s*\n\s*/g," ")}`:this._lastReset?` # ${this._lastReset}`:"";_explain=({agentHint:e,hint:t,updateTag:i})=>void 0!==e?null===e||""===e?i:e:t?this._context.resolveLocalizable(t):i}

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

@@ -6,7 +6,7 @@ import type { GraphQLSystem } from '../graphql-system/graphql-system.js';
  * that moment, never against ones captured when its reply began streaming.
  */
 export interface AssistantToolDependencies {
-    readonly getGraphQLSystem: () => Pick<GraphQLSystem, 'prepare' | 'execute'>;
+    readonly getGraphQLSystem: () => Pick<GraphQLSystem, 'prepare' | 'execute' | 'readSideEffects'>;
     readonly getStoreSystem: () => {
         readonly isInitialized: boolean;
         readonly stateSlices: {
@@ -18,11 +18,14 @@ export interface AssistantToolDependencies {
         };
     };
     readonly getActiveMode: () => DomainMode;
+    /** Forgets the changes recorded for the next change record, so it never lists what the agent itself changed. */
+    readonly clearChanges: () => void;
 }
 /**
  * Browser implementation of the assistant's `query` tool: prepares the operations from the
  * committed state and drops their emissions, so mutations in the list show a hypothetical state and
- * the configuration, the undo stack and the saved revision stay as they were.
+ * the configuration, the undo stack and the saved revision stay as they were. The side effects of
+ * the dropped emissions are still reported, as what the changes would do.
  */
 export declare const createQueryClientTool: (dependencies: AssistantToolDependencies) => import("@tanstack/ai").ClientTool<{
     type: string;
@@ -88,7 +91,9 @@ export declare const createQueryClientTool: (dependencies: AssistantToolDependen
 /**
  * Browser implementation of the assistant's `apply` tool: hands the operations to
  * `GraphQLSystem.execute`, which commits their changes as one undo step, and returns its result,
- * including why nothing was committed when a commit was held or lost to a conflict. Only an owner
+ * including why nothing was committed when a commit was held or lost to a conflict. A commit clears
+ * the recorded changes; a held one does not, so it shows in the next change record once the user
+ * approves it. Only an owner
  * session may change the configuration; the check lives here and not in the `GraphQLSystem`, whose
  * other caller, the editor panel, has its own rules.
  */

package/dist/configurator/application-runtime/extensions/systems/assistant-system/graphql-tools.js

@@ -1 +1 @@
-import{AssistantGraphQLToolInput as e,applyTool as t,queryTool as o}from"@salsita-ai/contracts/assistant";let a=e=>({results:[],committed:!1,message:e}),i=e=>JSON.parse(JSON.stringify(e)),s=t=>{let o=e.safeParse(t);if(!o.success){let e=o.error.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join("; ");return{ok:!1,refusal:a(`Nothing was run, because the tool input is not a list of operations (${e}). Send { "operations": [{ "query": "<one GraphQL operation>" }] } with at least one item.`)}}return{ok:!0,operations:o.data.operations.map(({query:e,variables:t,operationName:o})=>({document:e,variables:t??void 0,operationName:o??void 0}))}};export const createQueryClientTool=e=>o.client(async t=>{let o=s(t);if(!o.ok)return o.refusal;let n=e.getStoreSystem();return n.isInitialized?i({results:(await e.getGraphQLSystem().prepare(n.stateSlices.committed.value.state,o.operations)).map(({result:e})=>e),committed:!1}):a("Nothing was run, because the configuration is not loaded yet, so there is no state to query. Call the tool again once the configurator has finished loading.")});export const createApplyClientTool=e=>t.client(async t=>{if("owner"!==e.getActiveMode())return a("Nothing was run, because changes cannot be applied in this session: the user may view this configuration but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it.");let o=s(t);return o.ok?i(await e.getGraphQLSystem().execute(o.operations)):o.refusal});
+import{AssistantGraphQLToolInput as e,applyTool as t,queryTool as o}from"@salsita-ai/contracts/assistant";let a=e=>({results:[],committed:!1,message:e,sideEffects:[]}),i=e=>JSON.parse(JSON.stringify(e)),s=t=>{let o=e.safeParse(t);if(!o.success){let e=o.error.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join("; ");return{ok:!1,refusal:a(`Nothing was run, because the tool input is not a list of operations (${e}). Send { "operations": [{ "query": "<one GraphQL operation>" }] } with at least one item.`)}}return{ok:!0,operations:o.data.operations.map(({query:e,variables:t,operationName:o})=>({document:e,variables:t??void 0,operationName:o??void 0}))}};export const createQueryClientTool=e=>o.client(async t=>{let o=s(t);if(!o.ok)return o.refusal;let n=e.getStoreSystem();if(!n.isInitialized)return a("Nothing was run, because the configuration is not loaded yet, so there is no state to query. Call the tool again once the configurator has finished loading.");let r=e.getGraphQLSystem(),l=await r.prepare(n.stateSlices.committed.value.state,o.operations);return i({results:l.map(({result:e})=>e),committed:!1,sideEffects:r.readSideEffects(l)})});export const createApplyClientTool=e=>t.client(async t=>{if("owner"!==e.getActiveMode())return a("Nothing was run, because changes cannot be applied in this session: the user may view this configuration but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it.");let o=s(t);if(!o.ok)return o.refusal;let n=await e.getGraphQLSystem().execute(o.operations);return n.committed&&e.clearChanges(),i(n)});

package/dist/configurator/application-runtime/extensions/systems/graphql-system/entity-meta.d.ts

@@ -47,12 +47,14 @@ export declare const createEntityMeta: (source: EntityMetaSource, context: Entit
                 root: null;
                 changedEntities: never[];
                 deletedEntityIds: never[];
+                sideEffects: never[];
                 errors: readonly DryRunError[];
             } | {
                 ok: boolean;
                 root: unknown;
                 changedEntities: {}[];
                 deletedEntityIds: DomainEntityId<string>[];
+                sideEffects: readonly string[];
                 errors: never[];
             } | null;
         }[];
@@ -71,12 +73,14 @@ export declare const createEntityMeta: (source: EntityMetaSource, context: Entit
                 root: null;
                 changedEntities: never[];
                 deletedEntityIds: never[];
+                sideEffects: never[];
                 errors: readonly DryRunError[];
             } | {
                 ok: boolean;
                 root: unknown;
                 changedEntities: {}[];
                 deletedEntityIds: DomainEntityId<string>[];
+                sideEffects: readonly string[];
                 errors: never[];
             } | null;
         }[];

package/dist/configurator/application-runtime/extensions/systems/graphql-system/entity-meta.js

@@ -1 +1 @@
-import{findAssistantFieldOptions as e,findAssistantRecipeGroups as t,modifyEntityUpdateTag as i,prepareAssistantRecipeUpdates as r,readAssistantFieldOptions as n,readAssistantRecipeGroup as s,systemUpdateFactory as a}from"#package/domain";let o=e=>({ok:!1,root:null,changedEntities:[],deletedEntityIds:[],errors:e}),d=(e,{state:t},{recipes:i,prepareStateEmission:r,find$Entity:n})=>{let{validity:s,state:a}=r(e,t,"committed");if(s.valid){let e=new Map(t.entities.map(e=>[e.id,e])),i=new Set(a.entities.map(e=>e.id));return{ok:!0,root:n(a.rootEntityId,a),changedEntities:a.entities.filter(t=>e.get(t.id)!==t).flatMap(e=>n(e.id,a)??[]),deletedEntityIds:t.entities.map(e=>e.id).filter(e=>!i.has(e)),errors:[]}}return o("uncaught"===s.severity?[{type:"uncaught",entityId:null,message:s.error.message}]:s.entityViolations.filter(({violation:e})=>e.severity===s.severity).map(({entityId:e,violation:t})=>({type:t.type,entityId:e,message:void 0===t.message?null:i.resolveLocalizable(t.message)})))};export const createEntityMeta=(l,c)=>{let p=e=>()=>t(c.manifest,e,l.entity.type).flatMap(t=>{let i=s(e,t,l.entity.id,l.state,c.recipes);return i?[((e,t,i)=>{let{group:n,label:s,description:a,recipes:l}=e,{resolveLocalizable:c}=i.recipes;return{groupId:n.groupId,name:void 0===s?n.instanceName:c(s),description:n.description??(void 0===a?null:c(a)),recipes:l.map(n=>((e,t,i,n)=>{let{key:s,item:a}=e,{resolveLocalizable:l}=n.recipes;return{key:s,name:l(a.title),description:void 0===a.description?null:l(a.description),imageUrl:void 0===a.thumbnailUrl?null:l(a.thumbnailUrl),dryRun:()=>t.group.dryRuns?((e,t,i,n)=>{let{updates:s,error:a}=((e,t,{entity:i,state:n},{recipes:s})=>{try{return{updates:r(e,t,i.id,n,s),error:void 0}}catch(e){if("child"===t.target.kind)throw e;return{updates:void 0,error:e instanceof Error?e.message:String(e)}}})(e,t,i,n);return void 0===s?o([{type:"uncaught",entityId:null,message:a}]):d(s,i,n)})(e,t,i,n):null}})(n,e,t,i))}})(i,l,c)]:[]});return{...Object.fromEntries(e(c.manifest,l.entity.type).map(e=>[e.edgeName,()=>n(e,l.entity.id,l.state,c.recipes)?.map(t=>({...t,dryRun:()=>e.dryRuns?(({field:e},{value:t},r,n)=>{let{entity:s}=r,l=Object.entries(Object.entries(n.manifest.writableFields??{}).find(([e])=>e===s.type)?.[1]??{}).find(([t])=>t===e)?.[1];if(void 0===l)throw Error(`The options of "${e}" on "${s.id}" cannot be dry-run: the schema lists them, but the configurator has no writable field "${e}" on ${s.type}. Regenerate the application so the schema matches the configurator.`);let c=r.state.entities.find(e=>e.id===s.id),p={[l]:t},u=c?n.validateEntity({...c,...p}):{success:!0};return u.success?d([a.DomainEntityModification({entityId:s.id,stateDelta:p,updateTag:i})],r,n):o([{type:"uncaught",entityId:s.id,message:`Writing ${JSON.stringify(t)} to "${e}" would make "${s.id}" an invalid ${s.type}: ${u.errors.join("; ")}.${e===l?"":` The message names the stored property: ${e} is stored as ${l}.`} The option comes from the configurator and cannot be corrected from here, so do not write it.`}])})(e,t,l,c):null}))??null])),childRecipes:p("child"),replaceRecipes:p("replace")}};
+import{findAssistantFieldOptions as e,findAssistantRecipeGroups as t,modifyEntityUpdateTag as i,prepareAssistantRecipeUpdates as r,readAssistantFieldOptions as n,readAssistantRecipeGroup as s,systemUpdateFactory as a}from"#package/domain";import{readSideEffects as o}from"./side-effects.js";let d=e=>({ok:!1,root:null,changedEntities:[],deletedEntityIds:[],sideEffects:[],errors:e}),l=(e,{state:t},{recipes:i,prepareStateEmission:r,find$Entity:n})=>{let{validity:s,state:a,updates:l}=r(e,t,"committed");if(s.valid){let e=new Map(t.entities.map(e=>[e.id,e])),r=new Set(a.entities.map(e=>e.id));return{ok:!0,root:n(a.rootEntityId,a),changedEntities:a.entities.filter(t=>e.get(t.id)!==t).flatMap(e=>n(e.id,a)??[]),deletedEntityIds:t.entities.map(e=>e.id).filter(e=>!r.has(e)),sideEffects:o(l,i.resolveLocalizable),errors:[]}}return d("uncaught"===s.severity?[{type:"uncaught",entityId:null,message:s.error.message}]:s.entityViolations.filter(({violation:e})=>e.severity===s.severity).map(({entityId:e,violation:t})=>({type:t.type,entityId:e,message:void 0===t.message?null:i.resolveLocalizable(t.message)})))};export const createEntityMeta=(o,c)=>{let p=e=>()=>t(c.manifest,e,o.entity.type).flatMap(t=>{let i=s(e,t,o.entity.id,o.state,c.recipes);return i?[((e,t,i)=>{let{group:n,label:s,description:a,recipes:o}=e,{resolveLocalizable:c}=i.recipes;return{groupId:n.groupId,name:void 0===s?n.instanceName:c(s),description:n.description??(void 0===a?null:c(a)),recipes:o.map(n=>((e,t,i,n)=>{let{key:s,item:a}=e,{resolveLocalizable:o}=n.recipes;return{key:s,name:o(a.title),description:void 0===a.description?null:o(a.description),imageUrl:void 0===a.thumbnailUrl?null:o(a.thumbnailUrl),dryRun:()=>t.group.dryRuns?((e,t,i,n)=>{let{updates:s,error:a}=((e,t,{entity:i,state:n},{recipes:s})=>{try{return{updates:r(e,t,i.id,n,s),error:void 0}}catch(e){if("child"===t.target.kind)throw e;return{updates:void 0,error:e instanceof Error?e.message:String(e)}}})(e,t,i,n);return void 0===s?d([{type:"uncaught",entityId:null,message:a}]):l(s,i,n)})(e,t,i,n):null}})(n,e,t,i))}})(i,o,c)]:[]});return{...Object.fromEntries(e(c.manifest,o.entity.type).map(e=>[e.edgeName,()=>n(e,o.entity.id,o.state,c.recipes)?.map(t=>({...t,dryRun:()=>e.dryRuns?(({field:e},{value:t},r,n)=>{let{entity:s}=r,o=Object.entries(Object.entries(n.manifest.writableFields??{}).find(([e])=>e===s.type)?.[1]??{}).find(([t])=>t===e)?.[1];if(void 0===o)throw Error(`The options of "${e}" on "${s.id}" cannot be dry-run: the schema lists them, but the configurator has no writable field "${e}" on ${s.type}. Regenerate the application so the schema matches the configurator.`);let c=r.state.entities.find(e=>e.id===s.id),p={[o]:t},u=c?n.validateEntity({...c,...p}):{success:!0};return u.success?l([a.DomainEntityModification({entityId:s.id,stateDelta:p,updateTag:i})],r,n):d([{type:"uncaught",entityId:s.id,message:`Writing ${JSON.stringify(t)} to "${e}" would make "${s.id}" an invalid ${s.type}: ${u.errors.join("; ")}.${e===o?"":` The message names the stored property: ${e} is stored as ${o}.`} The option comes from the configurator and cannot be corrected from here, so do not write it.`}])})(e,t,o,c):null}))??null])),childRecipes:p("child"),replaceRecipes:p("replace")}};

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

@@ -1,4 +1,5 @@
 import { type ExecutionResult } from 'graphql';
+import { type Localizable } from '@salsita-ai/common/utils';
 import { type $DomainEntity, type DomainContextSelectors, type DomainEntity, type DomainServicesSelectors, type DomainState, type SpecSelectors, type StateUpdateEmission } from '#package/domain';
 /** One single-operation GraphQL document with its own variables, as executed by {@link GraphQLSystem}. */
 export interface GraphQLOperation {
@@ -26,13 +27,22 @@ export interface PreparedOperation {
 /**
  * What {@link GraphQLSystem.execute} returns: the results of the operations as prepared from the
  * committed state, whether their changes were committed as one undo step, and, when the operations
- * succeeded but their changes were not committed, the reason addressed to the caller.
+ * succeeded but their changes were not committed, the reason addressed to the caller. `sideEffects`
+ * describes the prepared changes whether or not they were committed, so a caller can weigh a held
+ * commit before the user approves it.
  */
 export interface GraphQLExecution {
     readonly results: readonly ExecutionResult[];
     readonly committed: boolean;
     readonly message?: string;
+    /** What the configurator did, or would do, beyond what the operations asked for, in applied order. */
+    readonly sideEffects: readonly string[];
 }
+/**
+ * Resolves a localizable value, or each item of a list of them, to a string in the current locale.
+ * `null` and values that are not localizable pass through, so the schema's nullability decides.
+ */
+export declare const localize: (value: unknown, resolveLocalizable: (message: Localizable) => string) => unknown;
 /**
  * Executes GraphQL operations against the schema generated from the application spec `assistant`
  * manifest, resolving it against the committed domain state. Agent-independent: the assistant's
@@ -75,6 +85,11 @@ export declare class GraphQLSystem {
      * "not run" error instead.
      */
     prepare: (originalState: AnyDomainState, operations: readonly GraphQLOperation[]) => Promise<readonly PreparedOperation[]>;
+    /**
+     * The side effects of prepared operations: the hints of every update of their emissions, as the
+     * agent is told them, in applied order.
+     */
+    readSideEffects: (prepared: readonly PreparedOperation[]) => readonly string[];
     private readonly _prepareAndCommit;
     /**
      * Prepares the operations from the committed state and commits their changes as one emission,