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

package/dist/domain/application/assistant/form/assistant-form-elements.d.ts

@@ -0,0 +1,174 @@
+/**
+ * What an element of an assistant form collects: a `group` all its children, a `choice` exactly one
+ * of its options, a `choices` any number of them; an `option` is something to pick and an `input` a
+ * free value.
+ */
+export type AssistantFormRole = 'group' | 'choice' | 'choices' | 'option' | 'input';
+/** The type an attribute of a form element is validated and coerced to; the model writes every attribute as a string. */
+export interface AssistantFormAttribute {
+    readonly type: 'string' | 'number' | 'integer' | 'boolean';
+    /** The words a string, or the numbers a number, may be; a number's are written as text in the markup. */
+    readonly enum?: readonly (string | number)[];
+    /** A JSON Schema `pattern` a string attribute must match, such as a resource path or a `#rrggbb` color. */
+    readonly pattern?: string;
+    /** The bounds a number attribute must be within, as in JSON Schema. */
+    readonly minimum?: number;
+    readonly maximum?: number;
+    /** The bounds of a string attribute's length, as in JSON Schema. */
+    readonly minLength?: number;
+    readonly maxLength?: number;
+}
+/**
+ * An element the assistant can write inside a ```` ```form ```` fence of its reply to ask the user
+ * something. The panel renders it, and the SDK prompt lists it, so the model and the panel agree on
+ * one set of elements: the built-ins below, followed by the project's own, which its YAML declares
+ * under `assistant.formElements` with the fields up to `required`.
+ */
+export interface AssistantFormElementDescriptor {
+    /** The tag: lowercase, and never the name of an HTML element. */
+    readonly name: string;
+    readonly role: AssistantFormRole;
+    /** What the element is for, printed in the prompt after its signature. */
+    readonly description: string;
+    /**
+     * Attributes beyond the built-in `label`, in the order the prompt lists them. An option or an
+     * input that takes a `value` declares it like any other: by convention an option answers with
+     * it instead of its label, and an input starts with it.
+     */
+    readonly attributes: Readonly<Record<string, AssistantFormAttribute>>;
+    readonly required?: readonly string[];
+    /**
+     * An input the user answers with one action, such as a `confirm`: a form whose only question it
+     * is sends on that action, without a submit button, as a lone `choice` sends on the first pick.
+     */
+    readonly quick?: true;
+    /**
+     * The attributes an option can answer with besides `label`, in the order its component tries
+     * them. An option that declares them and has none of them, nor `label`, makes its form fail.
+     */
+    readonly identity?: readonly string[];
+}
+/** What an attribute's declaration makes of its value: one of its words, a string, a number or a boolean. */
+export type AssistantFormAttributeValue<ATTRIBUTE extends AssistantFormAttribute> = ATTRIBUTE extends {
+    readonly enum: readonly (infer WORD)[];
+} ? WORD : ATTRIBUTE['type'] extends 'string' ? string : ATTRIBUTE['type'] extends 'boolean' ? boolean : number;
+type RequiredAttributeName<DESCRIPTOR> = DESCRIPTOR extends {
+    readonly required: readonly (infer NAME)[];
+} ? NAME : never;
+/**
+ * The attributes a form element's component gets, typed from its descriptor: the declared ones,
+ * optional unless `required`. The form validates the markup against the same descriptor, so the
+ * component can rely on these types.
+ */
+export type AssistantFormElementAttributes<DESCRIPTOR extends AssistantFormElementDescriptor> = {
+    readonly [NAME in keyof DESCRIPTOR['attributes'] as NAME extends RequiredAttributeName<DESCRIPTOR> ? NAME : never]: AssistantFormAttributeValue<DESCRIPTOR['attributes'][NAME]>;
+} & {
+    readonly [NAME in keyof DESCRIPTOR['attributes'] as NAME extends RequiredAttributeName<DESCRIPTOR> ? never : NAME]?: AssistantFormAttributeValue<DESCRIPTOR['attributes'][NAME]>;
+};
+/** The elements every assistant form understands, in the order the prompt lists them. */
+export declare const ASSISTANT_BUILT_IN_FORM_ELEMENTS: readonly [{
+    readonly name: 'group';
+    readonly role: 'group';
+    readonly description: 'Puts related questions together under its label.';
+    readonly attributes: {};
+}, {
+    readonly name: 'choice';
+    readonly role: 'choice';
+    readonly description: 'The user picks exactly one of its options.';
+    readonly attributes: {};
+}, {
+    readonly name: 'choices';
+    readonly role: 'choices';
+    readonly description: 'The user picks any number of its options.';
+    readonly attributes: {};
+}, {
+    readonly name: 'reply';
+    readonly role: 'option';
+    readonly description: 'A short answer shown as a button.';
+    readonly attributes: {
+        readonly value: {
+            readonly type: 'string';
+        };
+    };
+}, {
+    readonly name: 'card';
+    readonly role: 'option';
+    readonly description: 'A tile with an optional picture over its label and a one-line `description`. `image` is a path you read on an `imageUrl` field. Without `value` or `label` it sends its `description`, or else its `image`.';
+    readonly attributes: {
+        readonly value: {
+            readonly type: 'string';
+        };
+        readonly description: {
+            readonly type: 'string';
+        };
+        readonly image: {
+            readonly type: 'string';
+            readonly pattern: string;
+        };
+    };
+    readonly identity: readonly ["value", "description", "image"];
+}, {
+    readonly name: 'swatch';
+    readonly role: 'option';
+    readonly description: 'A small tile of a color or a material, without text: its label shows on hover. `color` is `#rrggbb`, as on the `color` field of an option, and `image` a path you read on an `imageUrl` field. Without `value` or `label` it sends its `color`, or else its `image`.';
+    readonly attributes: {
+        readonly value: {
+            readonly type: 'string';
+        };
+        readonly color: {
+            readonly type: 'string';
+            readonly pattern: '^#[0-9a-fA-F]{6}$';
+        };
+        readonly image: {
+            readonly type: 'string';
+            readonly pattern: string;
+        };
+    };
+    readonly identity: readonly ["value", "color", "image"];
+}, {
+    readonly name: 'text';
+    readonly role: 'input';
+    readonly description: 'A single line the user types.';
+    readonly attributes: {
+        readonly value: {
+            readonly type: 'string';
+        };
+        readonly placeholder: {
+            readonly type: 'string';
+        };
+    };
+}, {
+    readonly name: 'number';
+    readonly role: 'input';
+    readonly description: 'A number the user types, with a slider when both `min` and `max` are given. The answer carries the `unit`, as in `Length: 240 cm`.';
+    readonly attributes: {
+        readonly value: {
+            readonly type: 'number';
+        };
+        readonly min: {
+            readonly type: 'number';
+        };
+        readonly max: {
+            readonly type: 'number';
+        };
+        readonly step: {
+            readonly type: 'number';
+        };
+        readonly unit: {
+            readonly type: 'string';
+        };
+    };
+}, {
+    readonly name: 'confirm';
+    readonly role: 'input';
+    readonly description: "A yes or no question, shown as two buttons. It answers with the user's own words for yes and no, such as `Yes` or `Ano`, and alone in a form it sends on the click.";
+    readonly attributes: {};
+    readonly quick: true;
+}];
+/** The name of a built-in form element. */
+export type AssistantBuiltInFormElementName = (typeof ASSISTANT_BUILT_IN_FORM_ELEMENTS)[number]['name'];
+/** The attributes the component of a built-in form element gets, typed from its descriptor. */
+export type AssistantBuiltInFormElementAttributes<NAME extends AssistantBuiltInFormElementName> = AssistantFormElementAttributes<Extract<(typeof ASSISTANT_BUILT_IN_FORM_ELEMENTS)[number], {
+    readonly name: NAME;
+}>>;
+export {};

package/dist/domain/application/assistant/form/assistant-form-elements.js

@@ -0,0 +1 @@
+import{ASSISTANT_RESOURCE_PATH_PATTERN as e}from"./assistant-resource-path.js";export const ASSISTANT_BUILT_IN_FORM_ELEMENTS=[{name:"group",role:"group",description:"Puts related questions together under its label.",attributes:{}},{name:"choice",role:"choice",description:"The user picks exactly one of its options.",attributes:{}},{name:"choices",role:"choices",description:"The user picks any number of its options.",attributes:{}},{name:"reply",role:"option",description:"A short answer shown as a button.",attributes:{value:{type:"string"}}},{name:"card",role:"option",description:"A tile with an optional picture over its label and a one-line `description`. `image` is a path you read on an `imageUrl` field. Without `value` or `label` it sends its `description`, or else its `image`.",attributes:{value:{type:"string"},description:{type:"string"},image:{type:"string",pattern:e}},identity:["value","description","image"]},{name:"swatch",role:"option",description:"A small tile of a color or a material, without text: its label shows on hover. `color` is `#rrggbb`, as on the `color` field of an option, and `image` a path you read on an `imageUrl` field. Without `value` or `label` it sends its `color`, or else its `image`.",attributes:{value:{type:"string"},color:{type:"string",pattern:"^#[0-9a-fA-F]{6}$"},image:{type:"string",pattern:e}},identity:["value","color","image"]},{name:"text",role:"input",description:"A single line the user types.",attributes:{value:{type:"string"},placeholder:{type:"string"}}},{name:"number",role:"input",description:"A number the user types, with a slider when both `min` and `max` are given. The answer carries the `unit`, as in `Length: 240 cm`.",attributes:{value:{type:"number"},min:{type:"number"},max:{type:"number"},step:{type:"number"},unit:{type:"string"}}},{name:"confirm",role:"input",description:"A yes or no question, shown as two buttons. It answers with the user's own words for yes and no, such as `Yes` or `Ano`, and alone in a form it sends on the click.",attributes:{},quick:!0}];

package/dist/domain/application/assistant/form/assistant-resource-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A path into the project's resources, the kind stored on `imageUrl` fields: no scheme and no host,
+ * so resolving it never leaves the resources origin. A backslash, a control character or leading
+ * whitespace is refused too, because the URL parser reads a backslash as a slash and strips the
+ * others, which would turn `\\host` or ` //host` into an address on another host.
+ *
+ * Written as a JSON Schema `pattern`, so the `image` attribute of a form element applies the same
+ * rule as the images of a reply.
+ */
+export declare const ASSISTANT_RESOURCE_PATH_PATTERN: string;

package/dist/domain/application/assistant/form/assistant-resource-path.js

@@ -0,0 +1 @@
+export const ASSISTANT_RESOURCE_PATH_PATTERN=String.raw`^(?![a-zA-Z][a-zA-Z0-9+.-]*:)(?!//)[^\s\\\x00-\x1f][^\\\x00-\x1f]*$`;

package/dist/domain/application/assistant/form/index.d.ts

@@ -0,0 +1,4 @@
+export { ASSISTANT_FORM_NAME_PATTERN, isHtmlElementName } from './assistant-form-element-name.js';
+export { ASSISTANT_BUILT_IN_FORM_ELEMENTS } from './assistant-form-elements.js';
+export type { AssistantBuiltInFormElementAttributes, AssistantBuiltInFormElementName, AssistantFormAttribute, AssistantFormAttributeValue, AssistantFormElementAttributes, AssistantFormElementDescriptor, AssistantFormRole, } from './assistant-form-elements.js';
+export { ASSISTANT_RESOURCE_PATH_PATTERN } from './assistant-resource-path.js';

package/dist/domain/application/assistant/form/index.js

@@ -0,0 +1 @@
+export{ASSISTANT_FORM_NAME_PATTERN,isHtmlElementName}from"./assistant-form-element-name.js";export{ASSISTANT_BUILT_IN_FORM_ELEMENTS}from"./assistant-form-elements.js";export{ASSISTANT_RESOURCE_PATH_PATTERN}from"./assistant-resource-path.js";

package/dist/domain/application/assistant/generate-assistant-prompt.d.ts

@@ -0,0 +1,6 @@
+import type { AssistantManifest } from './assistant-manifest.js';
+import { type AssistantFormElementDescriptor } from './form/index.js';
+/** How the prompt writes an element: its tag with each attribute and what it takes. Exported for tests. */
+export declare const formElementSignature: ({ name, role, attributes }: AssistantFormElementDescriptor) => string;
+/** SDK-version conventions for using the manifest's capabilities and reading their results. */
+export declare const generateAssistantPrompt: (assistant: AssistantManifest) => string;

package/dist/domain/application/assistant/generate-assistant-prompt.js

@@ -0,0 +1 @@
+import{ASSISTANT_BUILT_IN_FORM_ELEMENTS as e}from"./form/index.js";let t=[["Containers",["group","choice","choices"]],["Options",["option"]],["Inputs",["input"]]];export const formElementSignature=({name:e,role:t,attributes:a})=>{let n=["label",...Object.entries(a).map(([e,t])=>((e,{type:t,enum:a})=>a?`${e}="${a.join("|")}"`:"string"===t?e:`${e}="<${t}>"`)(e,t))];return"option"===t||"input"===t?`<${e} ${n.join(" ")} />`:`<${e} ${n.join(" ")}>…</${e}>`};export const generateAssistantPrompt=a=>{let n,s=Object.values(a.childRecipes??{}).some(e=>e.length>0),o=Object.values(a.replaceRecipes??{}).some(e=>e.length>0),i=Object.values(a.fieldOptions??{}).some(e=>e.length>0),r=Object.keys(a.actions??{}).length>0,h=Object.values(a.screenshots??{}).some(e=>e.length>0),l=(a.deletableTypes?.length??0)>0||Object.values(a.writableFields??{}).some(e=>Object.keys(e).length>0)||s||o||r,d=s||o||i,u=[...s?["`childRecipes` is what can be added to it"]:[],...o?["`replaceRecipes` what it can be replaced with"]:[],...i?["`<field>Options` the values a field accepts"]:[]],c=["`selected`",...(a.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",`- Give every ${l?"`query` and `apply` call":"`query` call"} a \`title\` of two to five words in the user's language that says what it does for them, e.g. ${l?'"Add two drawers"':'"Compare drawer prices"'}.`,...l?[`- Use a mutation inside \`query\` to answer a what-if about a change ${d?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead. A change the configuration does not allow fails with one error per reason, as the user would be told it.","- Warnings and notices never make anything fail. The root `warnings` field lists every current one, and `meta { warnings }` those of one entity, where its type has them."],...l?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- `warnings` lists the warnings and notices your change newly causes. They do not block it: tell the user about them, and offer a fix when one is clear.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...r?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...d?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${u.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...s||o?["recipes"]:[],...i?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,`- Select only the ${[...s||o?["recipe groups"]:[],...i?["options edges"]:[]].join(" and ")} you need. To read again only the ones you are deciding between, pass ${[...s||o?["their `key` to `recipes(keys:)`"]:[],...i?["their `value` to `<field>Options(values:)`"]:[]].join(" or ")}.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],...h?[["Seeing the design","- `meta { screenshot(view: …) { image } }` renders an entity from one of the views its `<Type>ScreenshotView` lists. The picture follows the tool result.","- Take one when the user asks how the design looks, or when you are not sure something is laid out right: what sits where, what overlaps or lines up. Otherwise rely on the data.","- Each one costs tokens and blocks the user's configurator while it renders."]]:[],["Images from the user","- The user may attach photos or reference images to a message, such as their room or a design they like.","- Sizes you read from a photo are estimates: tell the user the values you read and confirm them before you apply them."],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${c} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...l?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(a.deletableTypes?.length??0)>0||o?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${l?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."],["Links","- You may link an entity of the current configuration when you speak about that very entity: `[the left burner](entity:CookingTop-1)`. It helps the user find it in the configurator.",...d?["- Whenever you name recipes or options you read from `meta`, in a list, a table or a sentence, link each one: `[Single gas burner](recipe:KitchenRange-1/top/gas_single)` or `[Oak](option:Cabinet-2/finishOptions/oak)`. The link shows the user its picture or color and its description, so never draw previews yourself. The target is the entity id, the recipe group id or the options field you read, and the key or value, each encoded as in a URL."]:[]],["Replies","- Write Markdown only, never HTML: the panel does not render it.","- An image, `![alt](path)`, is shown only when its path is relative.","- To make a warning or a key note stand out, write a GitHub alert: a blockquote whose first line is only `[!WARNING]` or `[!NOTE]`. Use it sparingly."],["Forms","- To ask the user something they answer by picking or typing, end your reply with a form: a fenced code block with the language `form`. It holds only elements, written as lowercase tags with string attributes, without Markdown or text.","- Every element takes `label`, the text the user sees; on a container or an input it also names the answer. An option or an input whose signature lists `value` takes it: an option sends it instead of its label, and an input starts with it.",'- A bare attribute in a signature takes any text, `name="<type>"` takes a value of that type written as text, such as `min="<number>"`, and `name="a|b"` takes one of the words listed.',"- Options can also stand on their own, outside a `choice` or `choices`.","- An element or attribute not listed here, or an element other than an option inside a `choice` or `choices`, makes the whole form fail.","- The answer is the user's next message. Each container or input gives a line `Label: value`, or the bare value without a label; the lines of a labelled container are indented by two spaces under it, a `choices` lists each picked option on its own line, and `—` marks what was left unanswered.",'- Example: `<choice label="Plinth"><reply label="Black" /><reply label="Oak" /></choice>` is answered with `Plinth: Oak`.',"- The chat shows the answer as the user's own message, so a `value` reads as natural words, never as an id, key or code. Give `value` only when the label alone would be unclear as an answer, and map the answer's labels back to ids yourself.",...(n=[...e,...a.formElements??[]],t.flatMap(([e,t])=>{let a=n.filter(({role:e})=>t.includes(e));return 0===a.length?[]:[`- ${e}:`,...a.map(e=>`  - \`${formElementSignature(e)}\`: ${(({description:e,required:t=[]})=>0===t.length?e:`${e} Requires ${t.map(e=>`\`${e}\``).join(", ")}.`)(e)}`)]}))],...a.lenses?.declarations?[["Built-in fragments","- These fragments are already defined for every operation. Spread one by name on a field of its type, as in `field { ...FragmentName }`, instead of listing its fields.","- A fragment is a starting selection: add the other fields you need next to the spread, by name from the schema.","- Never define a fragment with one of these names.","",a.lenses.declarations]]:[]].map(e=>e.join("\n")).join("\n\n")};

package/dist/domain/application/assistant/index.d.ts

@@ -0,0 +1,10 @@
+export { ASSISTANT_HINTS } from './assistant-manifest.js';
+export type { AssistantResolvedManifest, AssistantDeclaredField, AssistantDeclarations, AssistantDeclaredWrite, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
+export { buildAssistantManifest } from './build-assistant-manifest.js';
+export type { AssistantFieldExposure } from './create-assistant-execution-schema.js';
+export { AssistantFieldClashError, createAssistantExecutionSchema } from './create-assistant-execution-schema.js';
+export type { AssistantFieldSource, AssistantResolvedHint, AssistantRecipeGroup, AssistantFieldOptions, AssistantScreenshotView, AssistantManifest, } from './assistant-manifest.js';
+export { generateAssistantPrompt } from './generate-assistant-prompt.js';
+export * from './session-setup/index.js';
+export { describeAssistantValues, mergeAssistantFields, resolveAssistantField } from './assistant-fields.js';
+export * from './form/index.js';

package/dist/domain/application/assistant/index.js

@@ -0,0 +1 @@
+export{ASSISTANT_HINTS}from"./assistant-manifest.js";export{buildAssistantManifest}from"./build-assistant-manifest.js";export{AssistantFieldClashError,createAssistantExecutionSchema}from"./create-assistant-execution-schema.js";export{generateAssistantPrompt}from"./generate-assistant-prompt.js";export*from"./session-setup/index.js";export{describeAssistantValues,mergeAssistantFields,resolveAssistantField}from"./assistant-fields.js";export*from"./form/index.js";

package/dist/domain/application/assistant/session-setup/AssistantSetupHandler.d.ts

@@ -0,0 +1,20 @@
+import type { AccessLevel, SessionRole } from '@salsita-ai/contracts/api';
+import type { $DomainEntity, ActionTypes, DomainEntity } from '../../../core/index.js';
+import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../../../domain-runtime/index.js';
+import type { AssistantSetupManifest } from './assistant-setup-manifest.js';
+/** Project-defined session inputs used by browser execution and the assistant setup webhook. */
+export interface AssistantSetupInputs<SESSION_DATA> {
+    readonly role: SessionRole;
+    readonly sessionData: SESSION_DATA;
+    readonly access: AccessLevel;
+}
+/** Arguments carried by the standard single-props system-handler registration. */
+export interface AssistantSetupHandlerProps<SESSION_DATA, ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes> {
+    readonly manifest: AssistantSetupManifest<ENTITIES, $MAP, ACTIONS>;
+    readonly inputs: AssistantSetupInputs<SESSION_DATA>;
+}
+/** A project setup handler is synchronous, pure and deterministic. Return null to disable the assistant. */
+export type TypedCreateAssistantSetupHandler<SESSION_DATA, ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes> = (fn: (manifest: AssistantSetupManifest<ENTITIES, $MAP, ACTIONS>, inputs: AssistantSetupInputs<SESSION_DATA>) => AssistantSetupManifest<ENTITIES, $MAP, ACTIONS> | null) => SystemPhoenixHandlerRegistration<AssistantSetupHandlerProps<SESSION_DATA, ENTITIES, $MAP, ACTIONS>, AssistantSetupManifest<ENTITIES, $MAP, ACTIONS> | null>;
+export declare const createAssistantSetupHandler: <SESSION_DATA, ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes>(fn: (manifest: AssistantSetupManifest<ENTITIES, $MAP, ACTIONS>, inputs: AssistantSetupInputs<SESSION_DATA>) => AssistantSetupManifest<ENTITIES, $MAP, ACTIONS> | null) => SystemPhoenixHandlerRegistration<AssistantSetupHandlerProps<SESSION_DATA, ENTITIES, $MAP, ACTIONS>, AssistantSetupManifest<ENTITIES, $MAP, ACTIONS> | null>;
+export declare const createAssistantSetupHandlerFactory: <SESSION_DATA, ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes>() => TypedCreateAssistantSetupHandler<SESSION_DATA, ENTITIES, $MAP, ACTIONS>;
+export declare const isAssistantSetupHandler: (handler: Pick<HandlerRegistration<never, unknown>, 'type' | 'name'>) => handler is SystemPhoenixHandlerRegistration<AssistantSetupHandlerProps<Record<string, unknown>>, AssistantSetupManifest | null>;

package/dist/domain/application/assistant/session-setup/AssistantSetupHandler.js

@@ -0,0 +1 @@
+export const createAssistantSetupHandler=t=>({type:"system",name:"AssistantSetupHandler",handler:()=>({handler:({manifest:e,inputs:s})=>t(e,s)})});export const createAssistantSetupHandlerFactory=()=>createAssistantSetupHandler;export const isAssistantSetupHandler=t=>"system"===t.type&&"AssistantSetupHandler"===t.name;

package/dist/domain/application/assistant/session-setup/apply-assistant-setup.d.ts

@@ -0,0 +1,10 @@
+import type { AssistantResolvedManifest } from '../assistant-resolved-manifest.js';
+import { type AssistantSetupManifest, type AssistantSetupSettings } from './assistant-setup-manifest.js';
+/** A project returned a setup that broadens or invalidates its declared whitelist. */
+export declare class AssistantSetupError extends Error {
+    constructor(key: string, reason: string);
+}
+export declare const applyAssistantSetup: (resolved: AssistantResolvedManifest, settings: AssistantSetupSettings | null, returned: AssistantSetupManifest | null) => {
+    readonly resolved: AssistantResolvedManifest;
+    readonly settings: AssistantSetupSettings | null;
+} | null;

package/dist/domain/application/assistant/session-setup/apply-assistant-setup.js

@@ -0,0 +1 @@
+import{ASSISTANT_AI_PROVIDERS as e,ASSISTANT_MODEL_TIERS as t,ASSISTANT_REASONING_LEVELS as i}from"@salsita-ai/contracts/assistant";import{describeAssistantValues as s,mergeAssistantFields as n,resolveAssistantField as o}from"../assistant-fields.js";import{projectAssistantSetupManifest as a}from"./assistant-setup-manifest.js";export class AssistantSetupError extends Error{constructor(e,t){super(`${e}: ${t}`),this.name="AssistantSetupError"}}let r=(e,t)=>{throw new AssistantSetupError(e,t)},l=(e,t,i)=>{for(let s of((null===t||"object"!=typeof t||Array.isArray(t))&&r(i,"expected an object; omit an entry to remove it"),Object.keys(t)))Object.hasOwn(e,s)||r(`${i}.${s}`,"not declared in the spec; remove this key")},p=(e,t)=>Object.hasOwn(e,t)?e[t]:void 0,c=(e,t,i)=>(void 0!==e&&"string"!=typeof e&&r(`${i}.description`,"expected a string"),e??t),d=(e,t,i)=>(void 0!==e&&!1!==e&&r(`${i}.allowDryRuns`,"can only disable dry-runs; omit this flag or set false"),!1!==e&&t);export const applyAssistantSetup=(f,u,m)=>{if(null===m)return null;let b=a(f,u),y=f.declarations;l({entities:{},deletable:{},writable:{},childRecipes:{},replaceRecipes:{},screenshots:{},actions:{},instructions:"",ai:{}},m,"assistant"),l(b.entities,m.entities,"assistant.entities"),l(b.deletable,m.deletable,"assistant.deletable"),l(b.writable,m.writable,"assistant.writable"),l(b.actions,m.actions,"assistant.actions"),l(b.screenshots,m.screenshots,"assistant.screenshots");let v=Object.fromEntries(Object.entries(m.entities).map(([e,t])=>{let i=`assistant.entities.${e}`;l(b.entities[e],t,i);let n=y.entities[e];return[e,Object.entries(t).map(([e,t])=>{l({description:""},t,`${i}.${e}`);let o=n.find(t=>t.source===e),a=c(t.description,o.valueDescription,`${i}.${e}`);return{...o,valueDescription:a,description:s(a,o.enumValues),describedByManifest:void 0!==t.description||o.describedByManifest}})]})),$=(e,t,i)=>r(`assistant.entities.${e}`,`conflicting sources ${t} and ${i}`),h=n([],p(v,"AnyDomainEntity")??[],()=>void 0,$),w=new Map([["AnyDomainEntity",h]]);for(let e of Object.keys(f.aliases))"AnyDomainEntity"!==e&&w.set(e,n([h],p(v,e)??[],()=>void 0,$));for(let e of f.entityTypes){let t=Object.entries(f.aliases).filter(([t,i])=>"AnyDomainEntity"!==t&&i.includes(e));w.set(e,n([h,...t.map(([e])=>w.get(e)??[])],p(v,e)??[],t=>y.enumValues[e]?.[t],$))}let g=Object.fromEntries([...w].map(([e,t])=>[e,t.map(t=>o(t,p(v,e)??[]))])),O=new Map,j=new Map;for(let[e,t]of Object.entries(m.writable)){let i=`assistant.writable.${e}`;for(let[s,n]of(l(b.writable[e],t,i),Object.entries(t))){let t=`${i}.${s}`,o=y.writable[e][s];for(let[e,{field:i,options:a,exposedDescription:c}]of(l(Object.values(o.members).some(e=>e.options)?{options:{}}:{},n,t),void 0!==n.options&&(l({validate:!0,allowDryRuns:!1},n.options,`${t}.options`),void 0!==n.options.validate&&!0!==n.options.validate&&r(`${t}.options.validate`,"can only enable validation; omit this flag or set true"),d(n.options.allowDryRuns,!0,`${t}.options`)),Object.entries(o.members))){let l=p(v,e)?.find(e=>e.source===s)?.name??w.get(e)?.find(e=>e.source===s)?.name,f=l??s;void 0===l&&w.get(e)?.some(e=>e.name===s&&e.source!==s)&&r(t,`narrowing leaves ${e}.${s} bound to another read field; retain its original exposure or remove this writable property`);let u=O.get(e)??new Map;if([...u.values()].some(e=>e.name===f&&e.property!==s)&&r(t,`narrowing maps multiple writable properties to ${e}.${f}; retain their original exposures or remove the conflicting property`),u.has(s)||u.set(s,{...i,name:f,...void 0===l?{}:{description:c}}),O.set(e,u),a){let i=o.defaultOptionsName?`${f}Options`:a.options.edgeName;j.get(e)?.some(e=>e.options.edgeName===i||e.options.field===f)&&r(`${t}.options`,`narrowing duplicates options edge ${e}.${i}; retain the original field exposures or remove the conflicting writable declaration`),j.set(e,[...j.get(e)??[],{hints:a.hints,options:{...a.options,field:f,edgeName:i,validate:n.options?.validate??a.options.validate,dryRuns:d(n.options?.allowDryRuns,a.options.dryRuns,`${t}.options`)}}])}}}}for(let[e,t]of Object.entries(f.optionsEdges))for(let i of t){let t=f.writableTypes.find(t=>t.entityType===e)?.fields.find(e=>e.name===i.options.field)?.property;if(i.options.validate&&t&&O.get(e)?.has(t)&&!j.get(e)?.some(i=>i.options.field===O.get(e)?.get(t)?.name&&i.options.validate)){let i=Object.keys(m.writable).find(i=>Object.hasOwn(m.writable[i],t)&&y.writable[i]?.[t]?.members[e]);r(`assistant.writable.${i}.${t}`,`cannot remove declared validation while another declaration keeps ${e}.${t} writable; remove all writable declarations for it`)}}let T=e=>{l(b[e],m[e],`assistant.${e}`);let t=new Map;for(let[i,s]of Object.entries(m[e])){let n=`assistant.${e}.${i}`;l(b[e][i],s,n);let o=y[e][i],a=Object.entries(s).map(([e,t])=>{let i=`${n}.${e}`;l({description:"",allowDryRuns:!1},t,i);let s=o.find(t=>t.instanceName===e);return{...s,description:c(t.description,s.description,i),dryRuns:d(t.allowDryRuns,s.dryRuns,i)}});for(let e of f.entityTypes.includes(i)?[i]:f.aliases[i]??[])t.set(e,[...t.get(e)??[],...a])}return Object.fromEntries(f.entityTypes.flatMap(e=>{let i=t.get(e);return i?.length?[[e,i]]:[]}))},x=new Map;for(let[e,t]of Object.entries(m.screenshots)){let i=`assistant.screenshots.${e}`;l(b.screenshots[e],t,i);let s=f.entityTypes.includes(e)?[e]:f.aliases[e]??[];for(let[n,o]of Object.entries(t)){let t=`${i}.${n}`;l({description:""},o,t);let a=y.screenshots[e].find(e=>e.instanceName===n),r={...a,description:c(o.description,a.description,t)??a.description};for(let e of s)x.set(e,[...x.get(e)??[],r])}}for(let[e,t]of Object.entries(m.deletable))l({},t,`assistant.deletable.${e}`);let E=new Set(Object.keys(m.deletable).flatMap(e=>f.entityTypes.includes(e)?[e]:f.aliases[e]??[])),R=f.actionFields.flatMap(e=>{let t=p(m.actions,e.actionName);if(void 0===t)return[];let i=`assistant.actions.${e.actionName}`;return l({description:""},t,i),[{...e,description:c(t.description,e.description,i)}]}),M=u;if(u){void 0!==m.ai&&l({...u.ai,maxThreadSize:void 0},m.ai,"assistant.ai");let s={...u.ai,...Object.fromEntries(Object.entries(m.ai??{}).filter(([,e])=>void 0!==e))};e.includes(s.provider)&&t.includes(s.model)&&i.includes(s.reasoning)||r("assistant.ai","expected a supported provider, model and reasoning level"),void 0!==s.maxThreadSize&&(!Number.isInteger(s.maxThreadSize)||s.maxThreadSize<=0)&&r("assistant.ai.maxThreadSize","expected a positive whole number of input tokens"),void 0!==m.instructions&&"string"!=typeof m.instructions&&r("assistant.instructions","expected a string"),M={instructions:""===m.instructions?null:m.instructions??u.instructions,ai:s}}return{resolved:{...f,fields:g,deletableTypes:f.entityTypes.filter(e=>E.has(e)),writableTypes:f.entityTypes.flatMap(e=>{let t=[...O.get(e)?.values()??[]];return t.length?[{entityType:e,fields:t}]:[]}),optionsEdges:Object.fromEntries(j),childRecipes:T("childRecipes"),replaceRecipes:T("replaceRecipes"),screenshots:Object.fromEntries(f.entityTypes.flatMap(e=>{let t=x.get(e);return t?[[e,t]]:[]})),actionFields:R},settings:M}};

package/dist/domain/application/assistant/session-setup/assistant-setup-manifest.d.ts

@@ -0,0 +1,48 @@
+import type { AssistantAiSettings } from '@salsita-ai/contracts/assistant';
+import type { $DomainEntity, ActionTypes, DomainEntity } from '../../../core/index.js';
+import type { AssistantResolvedManifest } from '../assistant-resolved-manifest.js';
+/** Declaration-shaped whitelist a project may narrow; bindings and hints stay internal. */
+export interface AssistantSetupManifest<ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes> {
+    readonly entities: string extends keyof $MAP ? Readonly<Record<string, Readonly<Record<string, AssistantSetupField>>>> : {
+        readonly [TYPE in keyof $MAP]?: Readonly<Partial<Record<Exclude<keyof $MAP[TYPE], 'id' | 'type' | '_raw' | 'meta'>, AssistantSetupField>>>;
+    };
+    readonly deletable: Readonly<Record<string, Readonly<Record<never, never>>>>;
+    readonly writable: string extends ENTITIES['type'] ? Readonly<Record<string, Readonly<Record<string, AssistantSetupWritableField>>>> : {
+        readonly [TYPE in keyof $MAP]?: Readonly<Partial<Record<Exclude<keyof $MAP[TYPE]['_raw'], 'id' | 'type'>, AssistantSetupWritableField>>>;
+    };
+    readonly childRecipes: Readonly<Record<string, AssistantSetupRecipes>>;
+    readonly replaceRecipes: Readonly<Record<string, AssistantSetupRecipes>>;
+    /** The screenshot views under their original entity or alias key, keyed by `agentScreenshot` instance name. */
+    readonly screenshots: Readonly<Record<string, Readonly<Record<string, AssistantSetupField>>>>;
+    readonly actions: {
+        readonly [ACTION in keyof ACTIONS]?: AssistantSetupField;
+    };
+    readonly instructions?: string;
+    readonly ai?: Partial<AssistantAiSettings>;
+}
+/** Optional description override; omission preserves the declaration's effective text. */
+export interface AssistantSetupField {
+    readonly description?: string;
+}
+/** Only stricter validation and disabled dry-runs are configurable. */
+export interface AssistantSetupOptions {
+    readonly validate?: true;
+    readonly allowDryRuns?: false;
+}
+/** Keeping a property also keeps its declared options binding and baseline restrictions. */
+export interface AssistantSetupWritableField {
+    readonly options?: AssistantSetupOptions;
+}
+/** A recipe group's editable description and dry-run restriction. */
+export interface AssistantSetupRecipeGroup {
+    readonly description?: string;
+    readonly allowDryRuns?: false;
+}
+/** Only explicitly declared groups appear, under their original entity or alias key, keyed by instance name. */
+export type AssistantSetupRecipes = Readonly<Record<string, AssistantSetupRecipeGroup>>;
+/** Server settings baseline, kept out of the browser spec. */
+export interface AssistantSetupSettings {
+    readonly instructions?: string | null;
+    readonly ai: AssistantAiSettings;
+}
+export declare const projectAssistantSetupManifest: (resolved: AssistantResolvedManifest, settings: AssistantSetupSettings | null) => AssistantSetupManifest;

package/dist/domain/application/assistant/session-setup/assistant-setup-manifest.js

@@ -0,0 +1 @@
+export const projectAssistantSetupManifest=(e,t)=>{let i=e=>Object.fromEntries(Object.entries(e).map(([e,t])=>[e,Object.fromEntries(t.map(e=>[e.instanceName,{...void 0===e.description?{}:{description:e.description},...!e.dryRuns?{allowDryRuns:!1}:{}}]))])),s=e.declarations;return{entities:Object.fromEntries(Object.entries(s.entities).map(([e,t])=>[e,Object.fromEntries(t.map(e=>[e.source,{...!e.describedByManifest||void 0===e.valueDescription?{}:{description:e.valueDescription}}]))])),deletable:Object.fromEntries(s.deletable.map(e=>[e,{}])),writable:Object.fromEntries(Object.entries(s.writable).map(([e,t])=>[e,Object.fromEntries(Object.entries(t).map(([e,t])=>{let i=Object.values(t.members).find(e=>e.options)?.options?.options;return[e,i?{options:{...i.validate?{validate:!0}:{},...!i.dryRuns?{allowDryRuns:!1}:{}}}:{}]}))])),childRecipes:i(s.childRecipes),replaceRecipes:i(s.replaceRecipes),screenshots:Object.fromEntries(Object.entries(s.screenshots).map(([e,t])=>[e,Object.fromEntries(t.map(({instanceName:e,description:t})=>[e,{description:t}]))])),actions:Object.fromEntries(e.actionFields.map(e=>[e.actionName,void 0===e.description?{}:{description:e.description}])),...t?{instructions:t.instructions??void 0,ai:{...t.ai}}:{}}};

package/dist/domain/application/assistant/session-setup/create-session-assistant.d.ts

@@ -0,0 +1,15 @@
+import type { AssistantManifest } from '../assistant-manifest.js';
+import type { AssistantResolvedManifest } from '../assistant-resolved-manifest.js';
+import type { AssistantSetupHandlerProps, TypedCreateAssistantSetupHandler } from './AssistantSetupHandler.js';
+/** Session-derived browser manifest; a rejected setup retains its error without exposing the baseline. */
+export interface SessionAssistantSetup {
+    readonly manifest: AssistantManifest | null;
+    readonly error: Error | null;
+}
+interface Props {
+    readonly resolved: AssistantResolvedManifest | null;
+    readonly handler: ReturnType<TypedCreateAssistantSetupHandler<Record<string, unknown>>> | undefined;
+    readonly inputs: AssistantSetupHandlerProps<Record<string, unknown>>['inputs'] | null;
+}
+export declare const createSessionAssistant: ({ resolved, handler, inputs }: Props) => SessionAssistantSetup;
+export {};

package/dist/domain/application/assistant/session-setup/create-session-assistant.js

@@ -0,0 +1 @@
+import{buildAssistantManifest as r}from"../build-assistant-manifest.js";import{applyAssistantSetup as n}from"./apply-assistant-setup.js";import{projectAssistantSetupManifest as t}from"./assistant-setup-manifest.js";export const createSessionAssistant=({resolved:e,handler:s,inputs:l})=>{if(!e)return{manifest:null,error:null};try{if(!s)return{manifest:r(e),error:null};if(!l)return{manifest:null,error:null};let i=n(e,null,s.handler().handler({manifest:t(e,null),inputs:l}));return{manifest:i?r(i.resolved):null,error:null}}catch(r){return{manifest:null,error:r instanceof Error?r:Error(String(r))}}};

package/dist/domain/application/assistant/session-setup/index.d.ts

@@ -0,0 +1,4 @@
+export * from './assistant-setup-manifest.js';
+export * from './AssistantSetupHandler.js';
+export { applyAssistantSetup, AssistantSetupError } from './apply-assistant-setup.js';
+export { createSessionAssistant, type SessionAssistantSetup } from './create-session-assistant.js';

package/dist/domain/application/assistant/session-setup/index.js

@@ -0,0 +1 @@
+export*from"./assistant-setup-manifest.js";export*from"./AssistantSetupHandler.js";export{applyAssistantSetup,AssistantSetupError}from"./apply-assistant-setup.js";export{createSessionAssistant}from"./create-session-assistant.js";

package/dist/domain/application/assistant-field-options.d.ts

@@ -1,7 +1,6 @@
-import type { DomainEntity, DomainEntityId } from '../core/model.js';
-import type { DomainState } from '../core/state.js';
-import type { AssistantFieldOptions, AssistantManifest } from './application-config.js';
+import type { DomainEntity, DomainEntityId, DomainState } from '../core/index.js';
 import type { AssistantRecipeContext } from './assistant-recipe-groups.js';
+import type { AssistantFieldOptions, AssistantManifest } from './assistant/index.js';
 type AnyDomainState = DomainState<DomainEntity<string>>;
 /**
  * One choice of a writable field as the assistant reads it, whatever component holds it: the value

package/dist/domain/application/assistant-mutations.d.ts

@@ -1,9 +1,7 @@
-import { type StateUpdate } from '../components/updates.js';
-import type { Domain } from '../core/domain.js';
-import { type $DomainEntity, type DomainEntity } from '../core/model.js';
-import type { DomainState } from '../core/state.js';
-import type { AssistantManifest } from './application-config.js';
-import { type AssistantRecipeContext } from './assistant-recipe-groups.js';
+import type { Localizable } from '@salsita-ai/common/utils';
+import { type DomainEntity, type DomainState, type StateUpdate } from '../core/index.js';
+import type { AnyActionContext } from '../domain-runtime/index.js';
+import type { AssistantManifest } from './assistant/index.js';
 type AnyDomainState = DomainState<DomainEntity<string>>;
 /**
  * Update tag of user-intended entity deletions, from the configurator's delete controls and the
@@ -12,19 +10,19 @@ type AnyDomainState = DomainState<DomainEntity<string>>;
 export declare const deleteEntityUpdateTag = "deleteEntity";
 /** Update tag of the entity modifications the assistant's `modify<Type>` mutations make. */
 export declare const modifyEntityUpdateTag = "modifyEntity";
-/** The domain of any application, as far as a mutation implementation reads it. */
-type AnyDomain = Domain<DomainEntity<string>, DomainEntity<string>, Record<string, $DomainEntity<DomainEntity<string>>>>;
 /** The arguments of one mutation field, as the GraphQL executor coerced them against the field's schema. */
 export type AssistantMutationArgs = Readonly<Record<string, unknown>>;
 /**
- * What a mutation implementation reads besides its arguments and the state it runs against. The
- * recipe context is what `addChild` and `replaceEntity` read their recipe groups and cook their recipes with, and what
- * `modify<Type>` reads the choices of a field with.
+ * What a mutation implementation reads besides its arguments and the state it runs against: the
+ * manifest, and the context the application's actions run with on that state. The built-ins and the
+ * custom mutations share it, so a built-in reads the domain, the component reader and the recipe
+ * cooker through `action.systems`, the way an action implementation does.
  */
-export interface AssistantMutationContext extends AssistantRecipeContext {
+export interface AssistantMutationContext {
     readonly manifest: AssistantManifest;
-    /** Validates a changed entity against its shape, and reads entities for the result of a field. */
-    readonly domain: Pick<AnyDomain, 'validateEntity' | 'getEntity' | 'get$Entity'>;
+    readonly action: AnyActionContext;
+    /** Resolves a title in the current language, for recipe keys and option names. */
+    readonly resolveLocalizable: (message: Localizable) => string;
 }
 /** The working state a mutation field ran against and the state its applied updates produced. */
 export interface AssistantMutationStateChange {
@@ -56,9 +54,10 @@ export interface AssistantMutationDeclaration {
     readonly implementation: AssistantMutationImplementation;
 }
 /**
- * The declaration resolving a `Mutation` field: a built-in by its name, or the shared modify
- * implementation when the name is `modify` followed by an entity type the manifest declares writable
- * fields for. `undefined` when the configurator has no implementation for the field.
+ * The declaration resolving a `Mutation` field: a built-in by its name, the action a custom mutation
+ * of that name runs, or the shared modify implementation when the name is `modify` followed by an
+ * entity type the manifest declares writable fields for. `undefined` when the configurator has no
+ * implementation for the field.
  */
 export declare const findAssistantMutation: (fieldName: string, manifest: AssistantManifest) => AssistantMutationDeclaration | undefined;
 export {};

package/dist/domain/application/assistant-mutations.js

@@ -1 +1 @@
-import{z as e}from"zod";import{systemUpdateFactory as t}from"../components/updates.js";import{DomainEntityIdSchema as i}from"../core/model.js";import{findAssistantFieldOptions as r,readAssistantFieldOptions as n}from"./assistant-field-options.js";import{assistantAddedEntityIds as o,findAssistantRecipeGroups as a,prepareAssistantRecipeUpdates as s,readAssistantRecipeGroup as d}from"./assistant-recipe-groups.js";export const deleteEntityUpdateTag="deleteEntity";export const modifyEntityUpdateTag="modifyEntity";let l=e.string().regex(new RegExp(i.pattern),'An entity id is the type name, a dash and a number, e.g. "Root-1". Query the current entities and use an id they return.'),p=e.object({id:l}),h=e.object({id:l,delta:e.record(e.unknown())}),u="modify",f=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],y=e=>Array.isArray(e)?e.map(y):"object"!=typeof e||null===e||Array.isArray(e)?e:Object.fromEntries(Object.entries(e).map(([e,t])=>[e,y(t)])),c=e.object({parentId:l,recipeGroupId:e.string(),recipeKey:e.string()}),g=e.object({entityId:l,recipeGroupId:e.string(),recipeKey:e.string()}),m=e=>e.map(e=>`"${e}"`).join(", "),$=[{name:"deleteEntity",implementation:(e,i,{manifest:r})=>{let{id:n}=p.parse(e),o=i.entities.find(e=>e.id===n);if(!o)throw Error(`Entity "${n}" does not exist, so it cannot be deleted. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let a=r.deletableTypes??[];if(!a.includes(o.type))throw Error(`Entity "${n}" is a ${o.type}, which is not deletable. ${a.length>0?`Only entities of these types can be deleted: ${a.join(", ")}.`:"No entity type is deletable."} Delete an entity of a deletable type instead.`);return{updates:[t.EntityDeletion({entityId:o.id,updateTag:"deleteEntity"})],readResult:({previousState:e,state:t})=>{var i;let r;return[o.id,...(i=o.id,r=new Set(t.entities.map(e=>e.id)),e.entities.map(e=>e.id).filter(e=>e!==i&&!r.has(e)))]}}}},{name:"addChild",implementation:(e,t,i)=>{let{parentId:r,recipeGroupId:n,recipeKey:l}=c.parse(e),p=t.entities.find(e=>e.id===r);if(!p)throw Error(`Entity "${r}" does not exist, so nothing can be added to it. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let h=a(i.manifest,"child",p.type),u=h.find(e=>e.groupId===n);if(!u)throw Error(`Entity "${r}" is a ${p.type}, which has no recipe group "${n}". ${h.length>0?`Its recipe groups are: ${m(h.map(({groupId:e})=>e))}.`:`Nothing can be added to a ${p.type}.`} Query "meta { childRecipes { groupId } }" on the entity you want to add to and use a groupId it returns.`);let f=d("child",u,p.id,t,i);if(!f)throw Error(`The recipe group "${n}" is not available on "${r}" right now, so nothing can be added from it. The configurator offers a group only in some states of the configuration. Query "meta { childRecipes { groupId } }" on "${r}" to see the groups it offers now.`);let y=f.recipes.find(e=>e.key===l);if(!y)throw Error(`The recipe group "${n}" on "${r}" has no recipe with the key "${l}". Recipes and their keys change with the configuration and with the language. List the recipes of the group again and use a key it returns.`);let g=s(y,f,p.id,t,i);return{updates:g,readResult:e=>o(g,p.id,e).map(t=>i.domain.get$Entity(t,e.state))}}},{name:"replaceEntity",implementation:(e,t,i)=>{let{entityId:r,recipeGroupId:n,recipeKey:l}=g.parse(e),p=t.entities.find(e=>e.id===r);if(!p)throw Error(`Entity "${r}" does not exist, so it cannot be replaced. It may have been deleted or replaced by an earlier operation or field; a replaced entity gets a new id. Query the current entities and use an id they return.`);let h=a(i.manifest,"replace",p.type),u=h.find(e=>e.groupId===n);if(!u)throw Error(`Entity "${r}" is a ${p.type}, which has no replace recipe group "${n}". ${h.length>0?`Its replace recipe groups are: ${m(h.map(({groupId:e})=>e))}.`:`A ${p.type} cannot be replaced.`} Query "meta { replaceRecipes { groupId } }" on the entity you want to replace and use a groupId it returns.`);let f=d("replace",u,p.id,t,i);if(!f)throw Error(`The recipe group "${n}" is not available on "${r}" right now, so it cannot be replaced from it. The configurator offers a group only in some states of the configuration. Query "meta { replaceRecipes { groupId } }" on "${r}" to see the groups it offers now.`);let y=f.recipes.find(e=>e.key===l);if(!y)throw Error(`The recipe group "${n}" on "${r}" has no recipe with the key "${l}". Recipes and their keys change with the configuration and with the language. List the recipes of the group again and use a key it returns.`);let c=s(y,f,p.id,t,i);return{updates:c,readResult:e=>o(c,p.id,e).map(t=>i.domain.get$Entity(t,e.state))}}}];export const findAssistantMutation=(e,i)=>{let o,a,s=$.find(t=>t.name===e);if(s||!e.startsWith(u))return s;let d=e.slice(u.length),l=f(i.writableFields??{},d);return l&&(o=`${u}${d}`,a=Object.keys(l).join(", "),{name:o,implementation:(e,i,s)=>{let{manifest:p,domain:c}=s,{id:g,delta:m}=h.parse(e),$=i.entities.find(e=>e.id===g);if(!$)throw Error(`Entity "${g}" does not exist, so it cannot be modified. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);if($.type!==d)throw Error(`Entity "${g}" is a ${$.type}, but ${o} modifies only ${d} entities. ${f(p.writableFields??{},$.type)?`Use ${u}${$.type} for it instead.`:`${$.type} has no writable fields, so it cannot be modified; pass the id of a ${d}.`}`);let w=Object.entries(m).flatMap(([e,t])=>{let i=f(l,e);return void 0===i?[]:[{field:e,property:i,value:y(t)}]}),b=Object.fromEntries(w.map(({property:e,value:t})=>[e,t]));if(0===Object.keys(b).length)throw Error(`The delta of ${o} is empty, so there is nothing to change on "${g}". Set at least one of its fields: ${a}.`);let E=c.validateEntity({...$,...b});if(!E.success){let e=w.filter(({field:e,property:t})=>e!==t).map(({field:e,property:t})=>`${e} is stored as ${t}`);throw Error(`The delta would make "${g}" an invalid ${d}: ${E.errors.join("; ")}. ${e.length>0?`The messages name stored properties: ${e.join(", ")}. `:""}Nothing was changed. Send values that fit the types and the allowed values the schema describes for these fields.`)}let j=r(p,d);for(let{field:e,value:t}of w){let r=j.find(t=>t.field===e);if(!r?.validate||null===t)continue;let o=n(r,$.id,i,s);if(o&&!o.some(e=>e.value===t))throw Error(`${JSON.stringify(t)} is not a value "${e}" of "${g}" can take right now. ${o.length>0?`The configurator offers these values: ${o.map(e=>JSON.stringify(e.value)).join(", ")}.`:"The configurator offers no value for it in this state."} Nothing was changed. Send one of the offered values; "meta { ${r.edgeName} }" on the entity lists them with their names. When the values depend on another field of this delta, change that field in an earlier mutation field of the same operation.`)}return{updates:[t.DomainEntityModification({entityId:$.id,stateDelta:b,updateTag:"modifyEntity"})],readResult:({state:e})=>c.getEntity($.id,e)?c.get$Entity($.id,e):null}}})};
+import{z as e}from"zod";import{DomainEntityIdSchema as t,systemUpdateFactory as i}from"../core/index.js";import{findAssistantFieldOptions as n,readAssistantFieldOptions as r}from"./assistant-field-options.js";import{assistantAddedEntityIds as o,findAssistantRecipeGroups as a,prepareAssistantRecipeUpdates as s,readAssistantRecipeGroup as d}from"./assistant-recipe-groups.js";export const deleteEntityUpdateTag="deleteEntity";export const modifyEntityUpdateTag="modifyEntity";let l=({action:e,resolveLocalizable:t})=>({componentReader:e.systems.componentReader,recipeCooker:e.systems.recipeCooker,resolveLocalizable:t}),p=e.string().regex(new RegExp(t.pattern),'An entity id is the type name, a dash and a number, e.g. "Root-1". Query the current entities and use an id they return.'),h=e.object({id:p}),u=e.object({id:p,delta:e.record(e.unknown())}),f="modify",y=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],c=e=>Array.isArray(e)?e.map(c):"object"!=typeof e||null===e||Array.isArray(e)?e:Object.fromEntries(Object.entries(e).map(([e,t])=>[e,c(t)])),m=e.object({parentId:p,recipeGroupId:e.string(),recipeKey:e.string()}),g=e.object({entityId:p,recipeGroupId:e.string(),recipeKey:e.string()}),$=e=>e.map(e=>`"${e}"`).join(", "),w=[{name:"deleteEntity",implementation:(e,t,{manifest:n})=>{let{id:r}=h.parse(e),o=t.entities.find(e=>e.id===r);if(!o)throw Error(`Entity "${r}" does not exist, so it cannot be deleted. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let a=n.deletableTypes??[];if(!a.includes(o.type))throw Error(`Entity "${r}" is a ${o.type}, which is not deletable. ${a.length>0?`Only entities of these types can be deleted: ${a.join(", ")}.`:"No entity type is deletable."} Delete an entity of a deletable type instead.`);return{updates:[i.EntityDeletion({entityId:o.id,updateTag:"deleteEntity"})],readResult:({previousState:e,state:t})=>{var i;let n;return[o.id,...(i=o.id,n=new Set(t.entities.map(e=>e.id)),e.entities.map(e=>e.id).filter(e=>e!==i&&!n.has(e)))]}}}},{name:"addChild",implementation:(e,t,i)=>{let{parentId:n,recipeGroupId:r,recipeKey:p}=m.parse(e),h=t.entities.find(e=>e.id===n);if(!h)throw Error(`Entity "${n}" does not exist, so nothing can be added to it. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let u=a(i.manifest,"child",h.type),f=u.find(e=>e.groupId===r);if(!f)throw Error(`Entity "${n}" is a ${h.type}, which has no recipe group "${r}". ${u.length>0?`Its recipe groups are: ${$(u.map(({groupId:e})=>e))}.`:`Nothing can be added to a ${h.type}.`} Query the groups under "meta { childRecipes }" on the entity you want to add to and use a groupId they return.`);let y=l(i),c=d("child",f,h.id,t,y);if(!c)throw Error(`The recipe group "${r}" is not available on "${n}" right now, so nothing can be added from it. The configurator offers a group only in some states of the configuration. Query the groups under "meta { childRecipes }" on "${n}" to see the ones it offers now; a group it does not offer is null.`);let g=c.recipes.find(e=>e.key===p);if(!g)throw Error(`The recipe group "${r}" on "${n}" has no recipe with the key "${p}". Recipes and their keys change with the configuration and with the language. List the recipes of the group again and use a key it returns.`);let w=s(g,c,h.id,t,y);return{updates:w,readResult:e=>o(w,h.id,e).map(t=>i.action.systems.domain.get$Entity(t,e.state))}}},{name:"replaceEntity",implementation:(e,t,i)=>{let{entityId:n,recipeGroupId:r,recipeKey:p}=g.parse(e),h=t.entities.find(e=>e.id===n);if(!h)throw Error(`Entity "${n}" does not exist, so it cannot be replaced. It may have been deleted or replaced by an earlier operation or field; a replaced entity gets a new id. Query the current entities and use an id they return.`);let u=a(i.manifest,"replace",h.type),f=u.find(e=>e.groupId===r);if(!f)throw Error(`Entity "${n}" is a ${h.type}, which has no replace recipe group "${r}". ${u.length>0?`Its replace recipe groups are: ${$(u.map(({groupId:e})=>e))}.`:`A ${h.type} cannot be replaced.`} Query the groups under "meta { replaceRecipes }" on the entity you want to replace and use a groupId they return.`);let y=l(i),c=d("replace",f,h.id,t,y);if(!c)throw Error(`The recipe group "${r}" is not available on "${n}" right now, so it cannot be replaced from it. The configurator offers a group only in some states of the configuration. Query the groups under "meta { replaceRecipes }" on "${n}" to see the ones it offers now; a group it does not offer is null.`);let m=c.recipes.find(e=>e.key===p);if(!m)throw Error(`The recipe group "${r}" on "${n}" has no recipe with the key "${p}". Recipes and their keys change with the configuration and with the language. List the recipes of the group again and use a key it returns.`);let w=s(m,c,h.id,t,y);return{updates:w,readResult:e=>o(w,h.id,e).map(t=>i.action.systems.domain.get$Entity(t,e.state))}}}];export const findAssistantMutation=(e,t)=>{let o,a,s=w.find(t=>t.name===e),d=y(t.actions??{},e);if(s)return s;if(void 0!==d)return{name:e,implementation:(e,t,{action:i})=>i.systems.actionSystem.prepareAction(d,c(e),t)};if(!e.startsWith(f))return;let p=e.slice(f.length),h=y(t.writableFields??{},p);return h&&(o=`${f}${p}`,a=Object.keys(h).join(", "),{name:o,implementation:(e,t,s)=>{let{manifest:d}=s,{domain:m}=s.action.systems,{id:g,delta:$}=u.parse(e),w=t.entities.find(e=>e.id===g);if(!w)throw Error(`Entity "${g}" does not exist, so it cannot be modified. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);if(w.type!==p)throw Error(`Entity "${g}" is a ${w.type}, but ${o} modifies only ${p} entities. ${y(d.writableFields??{},w.type)?`Use ${f}${w.type} for it instead.`:`${w.type} has no writable fields, so it cannot be modified; pass the id of a ${p}.`}`);let b=Object.entries($).flatMap(([e,t])=>{let i=y(h,e);return void 0===i?[]:[{field:e,property:i,value:c(t)}]}),E=Object.fromEntries(b.map(({property:e,value:t})=>[e,t]));if(0===Object.keys(E).length)throw Error(`The delta of ${o} is empty, so there is nothing to change on "${g}". Set at least one of its fields: ${a}.`);let v=m.validateEntity({...w,...E});if(!v.success){let e=b.filter(({field:e,property:t})=>e!==t).map(({field:e,property:t})=>`${e} refers to ${t}`);throw Error(`The delta would make "${g}" an invalid ${p}: ${v.errors.join("; ")}. ${e.length>0?`The messages use these field names: ${e.join(", ")}. `:""}Nothing was changed. Send values that fit the types and the allowed values the schema describes for these fields.`)}let j=n(d,p);for(let{field:e,value:i}of b){let n=j.find(t=>t.field===e);if(!n?.validate||null===i)continue;let o=r(n,w.id,t,l(s));if(o&&!o.some(e=>e.value===i))throw Error(`${JSON.stringify(i)} is not a value "${e}" of "${g}" can take right now. ${o.length>0?`The configurator offers these values: ${o.map(e=>JSON.stringify(e.value)).join(", ")}.`:"The configurator offers no value for it in this state."} Nothing was changed. Send one of the offered values; "meta { ${n.edgeName} }" on the entity lists them with their names. When the values depend on another field of this delta, change that field in an earlier mutation field of the same operation.`)}return{updates:[i.DomainEntityModification({entityId:w.id,stateDelta:E,updateTag:"modifyEntity"})],readResult:({state:e})=>m.getEntity(w.id,e)?m.get$Entity(w.id,e):null}}})};

package/dist/domain/application/assistant-recipe-groups.d.ts

@@ -1,17 +1,13 @@
 import type { Localizable } from '@salsita-ai/common/utils';
-import type { OneComponentFilter } from '../components/component-reader-types.js';
-import type { DomainEntityCreation, DomainEntityReplacement } from '../components/updates.js';
-import type { ComponentSnapshot } from '../core/component.js';
-import type { DomainEntity, DomainEntityId } from '../core/model.js';
-import type { DomainState } from '../core/state.js';
-import type { AnyRecipeCookerSystem } from '../domain-context/recipe-system/recipe-cooker-system.js';
+import type { ComponentSnapshot, DomainEntity, DomainEntityCreation, DomainEntityId, DomainEntityReplacement, DomainState, OneComponentFilter } from '../core/index.js';
+import type { AnyRecipeCookerSystem } from '../domain-context/index.js';
 import type { AttributeSelectionComponent } from '../system-components/attribute-selection.js';
 import { type ChildEntityRecipesComponent } from '../system-components/child-entity-recipes.js';
 import type { RecipeListItem } from '../system-components/common/recipes.js';
 import type { DistanceDimensionSelectComponent } from '../system-components/distance-dimension-select.js';
 import type { MaterialSwatchComponent } from '../system-components/material-swatch.js';
 import { type ReplaceEntityRecipesComponent } from '../system-components/replace-entity-recipes.js';
-import type { AssistantManifest, AssistantRecipeGroup } from './application-config.js';
+import type { AssistantManifest, AssistantRecipeGroup } from './assistant/index.js';
 type AnyDomainState = DomainState<DomainEntity<string>>;
 /** An update a recipe cooks to: the creation of an entity, or the replacement of the entity a replace recipe is for. */
 type AnyRecipeUpdate = DomainEntityCreation<DomainEntity<string>, DomainEntity<string>> | DomainEntityReplacement<DomainEntity<string>>;
@@ -45,6 +41,8 @@ export interface AssistantRecipeContext {
     /** Resolves a title in the current language, for the key of a recipe that declares none. */
     readonly resolveLocalizable: (message: Localizable) => string;
 }
+/** What reading a recipe group needs: listing never cooks, so the panel can read a group without a cooker. */
+type AssistantRecipeReadContext = Pick<AssistantRecipeContext, 'componentReader' | 'resolveLocalizable'>;
 /** One recipe of a group as the assistant addresses it: the list item and its key, unique within the group. */
 export interface AssistantRecipe {
     readonly key: string;
@@ -77,7 +75,7 @@ export declare const findAssistantRecipeGroups: (manifest: AssistantManifest, ki
  * assistant sees the groups the configurator's own controls would offer. A list item without recipes
  * adds nothing and is left out.
  */
-export declare const readAssistantRecipeGroup: (kind: AssistantRecipeKind, group: AssistantRecipeGroup, entityId: DomainEntityId<string>, state: AnyDomainState, context: AssistantRecipeContext) => AssistantRecipeGroupSnapshot | null;
+export declare const readAssistantRecipeGroup: (kind: AssistantRecipeKind, group: AssistantRecipeGroup, entityId: DomainEntityId<string>, state: AnyDomainState, context: AssistantRecipeReadContext) => AssistantRecipeGroupSnapshot | null;
 /**
  * The updates of one recipe of a group for the entity `entityId`, computed from `state`: the same
  * updates, with the same tag, the configurator's own controls make. A recipe of a child group is