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

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

@@ -0,0 +1,267 @@
+import type { AnyClientTool } from '@tanstack/ai';
+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, 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>;
+}
+/**
+ * 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 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;
+    /**
+     * 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.
+     */
+    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

@@ -0,0 +1 @@
+import{ChatClient as e,fetchServerSentEvents as t}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{AssistantRequestError as r}from"#package/client";import{createBrowserDetailsClientTool as n}from"./browser-details.js";import{ChangeRecorder as h}from"./change-recorder.js";import{createApplyClientTool as o,createQueryClientTool as l}from"./graphql-tools.js";let c=Object.freeze({messages:Object.freeze([]),isLoading:!1,error:void 0,failedStatus:void 0,isContinuable:!0,isLoaded:!1,isResuming:!1,earlierThreads:Object.freeze([]),hasEarlierThread:!1,isLoadingEarlierThread:!1}),d=Object.freeze({open:!1,hasUnreadReply:!1,isInputFocused:!1}),u=Object.freeze({}),_=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."}),g=e=>{if(e.getError())return!0;let t=e.getMessages().at(-1)?.parts.at(-1);return t?.type!=="tool-call"&&t?.type!=="tool-result"};export class AssistantSystem{_context;_tools;_chat=new i(c);_panel=new i(d);_activation=null;_current=null;_finishing=new Set;_olderThreadId=null;_resuming=null;_refused=null;_firstAttempt=null;_chain={};_loadingThreadId=null;_recorder;_recording=null;constructor(e){this._context=e;let{configuratorExtensionSelectors:t,domainContextSelectors:i,domainServicesSelectors:s,specSelectors:a}=e;this._recorder=new h({maxEntities:30},{readers:{selectedEntityId:e=>i.getNavigationSystem().getActiveSelectionState(e),navigationState:e=>i.getNavigationSystem().getActiveNavigationState(e),viewState:e=>i.getNavigationSystem().getActiveViewState(e),toolState:e=>i.getNavigationSystem().getActiveToolState(e)},getExposedFields:()=>a.getAssistant()?.fields??u,resolveLocalizable:e=>s.getResolveLocalizable()(e)});let r={getGraphQLSystem:()=>t.getGraphQLSystem(),getStoreSystem:()=>i.getStoreSystem(),getActiveMode:()=>i.getActiveMode(),clearChanges:()=>this._recorder.clear(this._committedState())};this._tools=[n(),l(r),o(r)]}chat$=this._chat;panel$=this._panel;initialize=()=>{let{committed:e}=this._context.domainContextSelectors.getStoreSystem().stateSlices;this._recording??=e.pipe(s(1)).subscribe(this._recorder.record),this._recorder.reset(e.value.state),this._endChat(),this._patchPanel(d),this._activation&&this._startClient()};activate=()=>{this._endChat();let e={};return this._activation=e,this._startClient(),()=>{this._activation===e&&(this._activation=null,this._endChat())}};send=async e=>{if(!this._chat.value.isContinuable&&!await this.resume())return;let t=this._current;if(!t)return;let i={changes:this._recorder.take(this._committedState())};this._firstAttempt=t;try{await this._sendOn(t,e,i);let s=this._findRefusedMessageIndex(t);if(-1===s)return;this._refused={chat:t,index:s}}finally{this._firstAttempt===t&&(this._firstAttempt=null)}if(!await this.resume())return;let s=this._current;s&&await this._sendOn(s,e,i)};resume=async()=>{let e=this._current;if(!e)return!1;if(this._chat.value.isContinuable)return!0;if(this._resuming)return this._resuming;let t=this._resume(e).finally(()=>{this._resuming===t&&(this._resuming=null)});return this._resuming=t,t};loadEarlierThread=async()=>{let e=this._current,t=this._olderThreadId;if(!e||null===t||this._loadingThreadId===t)return;let i=this._chain;this._loadingThreadId=t,this._chat.next({...this._chat.value,isLoadingEarlierThread:!0});try{let s=await e.authorizedClient.getAssistantEarlierThread(e.configurationId,t,50);if(this._chain!==i||this._olderThreadId!==t)return;this._olderThreadId=s.previousThreadId,this._chat.next({...this._chat.value,earlierThreads:[{threadId:t,messages:s.messages},...this._chat.value.earlierThreads],hasEarlierThread:null!==s.previousThreadId})}catch(e){this._context.domainServicesSelectors.getLogger().warn("Could not load the earlier assistant conversation",{error:e})}finally{this._chain===i&&this._loadingThreadId===t&&(this._loadingThreadId=null,this._chat.next({...this._chat.value,isLoadingEarlierThread:!1}))}};stop=async()=>{let e=this._current;if(!e)return;let t=e.client.getCurrentRunId();if(e.client.stop(),null!=t)try{let i=e.getConnection();await fetch(`${i.url}/runs/${encodeURIComponent(t)}/cancel`,{method:"POST",headers:await i.headers()})}catch(e){this._context.domainServicesSelectors.getLogger().warn("Could not cancel the assistant run on the server",{error:e})}};reloadThread=()=>{if(!this._activation)return;let e=this._retireChat();e?.client.stop(),e?.dispose(),this._recorder.reset(this._committedState()),this._startClient()};setOpen=e=>{this._patchPanel(e?{open:e,hasUnreadReply:!1}:{open:e,isInputFocused:!1})};setInputFocused=e=>{this._patchPanel({isInputFocused:e})};_findRefusedMessageIndex=e=>{var t;let i,{failedStatus:s,isContinuable:a}=this._chat.value;return this._firstAttempt===e&&e.generation.active&&409===s&&!a?(i=(t=e.client.getMessages()).map(e=>e.role).lastIndexOf("user"),t.slice(i+1).every(e=>0===e.parts.length)?i:-1):-1};_sendOn=async(e,t,i)=>{let{client:s}=e;s.getIsLoading()||null===s.getResumeState()||s.stop();try{await s.sendMessage({content:t,metadata:i})}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)}};_resume=async e=>{this._chat.next({...this._chat.value,isResuming:!0,error:void 0,failedStatus:void 0});try{let{previousThreadId:t}=await e.authorizedClient.compactAssistantThread(e.configurationId);if(!e.generation.active)return!1;let{messages:i,earlierThreads:s,hasEarlierThread:a}=this._chat.value,r=this._refused?.chat===e?i.slice(0,this._refused.index):i;return e.generation.active=!1,this._current=null,e.client.stop(),e.dispose(),this._chat.next({...c,earlierThreads:[...s,{threadId:t,messages:r}],hasEarlierThread:a,isLoadingEarlierThread:null!==this._loadingThreadId}),this._startClient(),!0}catch(i){let t=i instanceof Error?i:Error(String(i));if(t instanceof r&&409===t.status)return e.generation.active&&this.reloadThread(),!1;return e.generation.active&&this._chat.next({...this._chat.value,isResuming:!1,error:t,failedStatus:t instanceof r?t.status:void 0}),this._context.domainServicesSelectors.getLogger().error("The assistant thread could not be resumed",{},t),!1}};_committedState=()=>this._context.domainContextSelectors.getStoreSystem().stateSlices.committed.value.state;_patchPanel=e=>{let t={...this._panel.value,...e};a(t,this._panel.value)||this._panel.next(t)};_takeOverThread=e=>{for(let t of this._finishing)t.configurationId===e&&(t.client.stop(),t.dispose())};_startClient=()=>{let i={active:!0},s=this._context.getConfigurationId();this._takeOverThread(s);let r=this._context.getAuthorizedClient(),n=()=>r.getAssistantChatConnection(s),h=e=>{if(!i.active)return;let t={...this._chat.value,...e};a(t,this._chat.value)||this._chat.next(t)},o=async(e,t)=>{let s=await fetch(e,t).finally(()=>h({isLoaded:!0})),a=s.headers.get("x-assistant-thread-continuable");return null!=a&&s.ok&&i.active&&0===this._chat.value.earlierThreads.length&&(this._olderThreadId=s.headers.get("x-assistant-previous-thread")),h({failedStatus:s.ok?void 0:s.status,...null!=a&&{isContinuable:"false"!==a,hasEarlierThread:null!==this._olderThreadId}}),s},l=async()=>({headers:await n().headers(),fetchClient:o}),c=t(()=>n().url,l),d=t(()=>`${n().url}/runs`,l),u=this._tools.map(e=>({...e,execute:(t,s)=>i.active?e.execute?.(t,s):_})),m=new e({threadId:`assistant:${s}`,connection:{...c,joinRun:d.joinRun},persistence:!0,history:{pageSize:50},tools:u,onMessagesChange:e=>h({messages:e}),onLoadingChange:e=>{let t=i.active&&this._chat.value.isLoading;h({isLoading:e}),!e&&g(m)&&(i.active?t&&!this._panel.value.open&&this._patchPanel({hasUnreadReply:!0}):v())},onErrorChange:e=>{i.active&&e!==this._chat.value.error&&(!e||-1===this._findRefusedMessageIndex(p))&&(h({error:e}),e&&this._context.domainServicesSelectors.getLogger().error("The assistant request failed",{status:this._chat.value.failedStatus},e))}}),f=!1,v=()=>{f||(f=!0,this._finishing.delete(p),m.dispose())},p={client:m,configurationId:s,generation:i,authorizedClient:r,getConnection:n,dispose:v};this._current=p,m.attach()};_retireChat=()=>{let e=this._current;return this._current=null,e&&(e.generation.active=!1),this._chain={},this._olderThreadId=null,this._resuming=null,this._refused=null,this._loadingThreadId=null,this._chat.value!==c&&this._chat.next(c),e};_endChat=()=>{let e=this._retireChat();if(e){if(!e.client.getIsLoading()&&g(e.client))return void e.dispose();this._finishing.add(e)}}}

package/dist/configurator/{assistant → application-runtime/extensions/systems/assistant-system}/browser-details.d.ts

@@ -2,7 +2,7 @@
  * Browser implementation of the assistant's `getBrowserDetails` tool: draws the browser details onto
  * a canvas and returns the capture as a PNG image part, so the model reads them from an image.
  */
-export declare const browserDetailsClientTool: import("@tanstack/ai").ClientTool<{
+export declare const createBrowserDetailsClientTool: () => import("@tanstack/ai").ClientTool<{
     type: string;
     properties: {};
     required: never[];

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

@@ -0,0 +1 @@
+import{browserDetailsTool as e}from"@salsita-ai/contracts/assistant";let t=e=>{let t=[];for(let i=0;i<e.length;i+=64)t.push(e.slice(i,i+64));return t};export const createBrowserDetailsClientTool=()=>e.client(()=>{let e=(()=>{let e=[`User agent: ${navigator.userAgent}`,`Viewport: ${window.innerWidth} x ${window.innerHeight} px`,`Screen: ${window.screen.width} x ${window.screen.height} px`,`Device pixel ratio: ${window.devicePixelRatio}`,`Language: ${navigator.language}`,`Time zone: ${Intl.DateTimeFormat().resolvedOptions().timeZone}`].flatMap(t),i=document.createElement("canvas");i.width=720,i.height=48+26*e.length;let n=i.getContext("2d");if(!n)throw Error("The browser details capture failed because the canvas has no 2D context. Retry in another browser.");return n.fillStyle="#ffffff",n.fillRect(0,0,i.width,i.height),n.fillStyle="#111111",n.font="16px monospace",n.textBaseline="top",e.forEach((e,t)=>n.fillText(e,24,24+26*t)),i.toDataURL("image/png")})();return[{type:"image",source:{type:"data",value:e.slice(e.indexOf(",")+1),mimeType:"image/png"}}]});

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/{assistant → application-runtime/extensions/systems/assistant-system}/graphql-tools.d.ts

@@ -1,14 +1,13 @@
 import type { DomainEntity, DomainMode, DomainState } from '#package/domain';
-import type { GraphQLSystem } from '../application-runtime/index.js';
+import type { GraphQLSystem } from '../graphql-system/graphql-system.js';
 /**
- * What the assistant's client tools need from the running configurator. The chat hook passes it as
- * the client context of `useChat`, which captures it when a request starts: a tool call reads the
- * systems as they were when its reply began streaming. A runtime replaced in between (dev hot
- * reload) fails that call, which is accepted.
+ * What the assistant's client tools need from the running configurator, as accessors they call when
+ * the model calls them: a tool call always runs against the systems and the session mode current at
+ * that moment, never against ones captured when its reply began streaming.
  */
-export interface AssistantToolContext {
-    readonly graphQLSystem: Pick<GraphQLSystem, 'prepare' | 'execute'>;
-    readonly storeSystem: {
+export interface AssistantToolDependencies {
+    readonly getGraphQLSystem: () => Pick<GraphQLSystem, 'prepare' | 'execute' | 'readSideEffects'>;
+    readonly getStoreSystem: () => {
         readonly isInitialized: boolean;
         readonly stateSlices: {
             readonly committed: {
@@ -19,13 +18,16 @@ export interface AssistantToolContext {
         };
     };
     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 queryClientTool: import("@tanstack/ai").ClientTool<{
+export declare const createQueryClientTool: (dependencies: AssistantToolDependencies) => import("@tanstack/ai").ClientTool<{
     type: string;
     properties: {
         operations: {
@@ -53,7 +55,7 @@ export declare const queryClientTool: import("@tanstack/ai").ClientTool<{
         };
     };
     required: string[];
-}, undefined, "query", AssistantToolContext, false, undefined> & {
+}, undefined, "query", unknown, false, undefined> & {
     inputSchema: {
         type: string;
         properties: {
@@ -89,11 +91,13 @@ export declare const queryClientTool: import("@tanstack/ai").ClientTool<{
 /**
  * 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
- * session may change the configuration; the check lives here and not in the system, whose other
- * caller, the editor panel, has its own rules.
+ * 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.
  */
-export declare const applyClientTool: import("@tanstack/ai").ClientTool<{
+export declare const createApplyClientTool: (dependencies: AssistantToolDependencies) => import("@tanstack/ai").ClientTool<{
     type: string;
     properties: {
         operations: {
@@ -121,7 +125,7 @@ export declare const applyClientTool: import("@tanstack/ai").ClientTool<{
         };
     };
     required: string[];
-}, undefined, "apply", AssistantToolContext, false, undefined> & {
+}, undefined, "apply", unknown, false, undefined> & {
     inputSchema: {
         type: string;
         properties: {

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

@@ -0,0 +1 @@
+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 o,systemUpdateFactory as s}from"#package/domain";import{readSideEffects as a}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:o,state:s,updates:l}=r(e,t,"committed");if(o.valid){let e=new Map(t.entities.map(e=>[e.id,e])),r=new Set(s.entities.map(e=>e.id));return{ok:!0,root:n(s.rootEntityId,s),changedEntities:s.entities.filter(t=>e.get(t.id)!==t).flatMap(e=>n(e.id,s)??[]),deletedEntityIds:t.entities.map(e=>e.id).filter(e=>!r.has(e)),sideEffects:a(l,i.resolveLocalizable),errors:[]}}return d("uncaught"===o.severity?[{type:"uncaught",entityId:null,message:o.error.message}]:o.entityViolations.filter(({violation:e})=>e.severity===o.severity).map(({entityId:e,violation:t})=>({type:t.type,entityId:e,message:void 0===t.message?null:i.resolveLocalizable(t.message)})))};export const createEntityMeta=(a,u)=>{let c=e=>()=>t(u.manifest,e,a.entity.type).flatMap(t=>{let i=o(e,t,a.entity.id,a.state,u.recipes);return i?[((e,t,i)=>{let{group:n,label:o,description:s,recipes:a}=e,{resolveLocalizable:u}=i.recipes;return{groupId:n.groupId,name:void 0===o?n.instanceName:u(o),description:n.description??(void 0===s?null:u(s)),recipes:a.map(n=>((e,t,i,n)=>{let{key:o,item:s}=e,{resolveLocalizable:a}=n.recipes;return{key:o,name:a(s.title),description:void 0===s.description?null:a(s.description),imageUrl:void 0===s.thumbnailUrl?null:a(s.thumbnailUrl),dryRun:()=>t.group.dryRuns?((e,t,i,n)=>{let{updates:o,error:s}=((e,t,{entity:i,state:n},{recipes:o})=>{try{return{updates:r(e,t,i.id,n,o),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===o?d([{type:"uncaught",entityId:null,message:s}]):l(o,i,n)})(e,t,i,n):null}})(n,e,t,i))}})(i,a,u)]:[]});return{...Object.fromEntries(e(u.manifest,a.entity.type).map(e=>[e.edgeName,()=>n(e,a.entity.id,a.state,u.recipes)?.map(t=>({...t,dryRun:()=>e.dryRuns?(({field:e},{value:t},r,n)=>{let{entity:o}=r,a=Object.entries(Object.entries(n.manifest.writableFields??{}).find(([e])=>e===o.type)?.[1]??{}).find(([t])=>t===e)?.[1];if(void 0===a)throw Error(`The options of "${e}" on "${o.id}" cannot be dry-run: the schema lists them, but the configurator has no writable field "${e}" on ${o.type}. This is a fault in the configurator, not in your request. Tell the user this is not available.`);let u=r.state.entities.find(e=>e.id===o.id);if(!u)throw Error(`The options of "${e}" on "${o.id}" cannot be dry-run: entity "${o.id}" does not exist. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let c={[a]:t},p=n.validateEntity({...u,...c});return p.success?l([s.DomainEntityModification({entityId:o.id,stateDelta:c,updateTag:i})],r,n):d([{type:"uncaught",entityId:o.id,message:`Writing ${JSON.stringify(t)} to "${e}" would make "${o.id}" an invalid ${o.type}: ${p.errors.join("; ")}. The option comes from the configurator and cannot be corrected from here, so do not write it.`}])})(e,t,a,u):null}))??null])),childRecipes:c("child"),replaceRecipes:c("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,