@salsita-ai/sdk 0.50.0-develop.b335a15889 → 0.50.0-develop.b47f1774a2

package/dist/domain/application/assistant/form/assistant-form-element-name.js

@@ -0,0 +1,8 @@
+let e=new Set(`a abbr acronym address applet area article aside audio b base basefont bdi bdo big blink blockquote body br
+  button canvas caption center cite code col colgroup data datalist dd del details dfn dialog dir div dl dt em
+  embed fieldset figcaption figure font footer form frame frameset h1 h2 h3 h4 h5 h6 head header hgroup hr html
+  i iframe image img input ins kbd keygen label legend li link main map mark marquee math menu menuitem meta
+  meter nav nobr noembed noframes noscript object ol optgroup option output p param picture plaintext pre
+  progress q rb rp rt rtc ruby s samp script search section select slot small source span strike strong style
+  sub summary sup svg table tbody td template textarea tfoot th thead time title tr track tt u ul var video wbr
+  xmp`.split(/\s+/));export const ASSISTANT_FORM_NAME_PATTERN=/^[a-z][a-z0-9-]*$/;export const isHtmlElementName=t=>e.has(t);

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

@@ -1,13 +1,6 @@
 import type { AssistantManifest } from './assistant-manifest.js';
-/**
- * The part of the assistant's system prompt that explains how to read the generated GraphQL schema.
- * It is generated here, by the SDK that also runs in the browser, and returned by the deployment webhook,
- * because the conventions it describes belong to this SDK version and not to the server. The part
- * about changes is left out when the schema has no `Mutation` type, the part about adding
- * entities when it has no `addChild` mutation, the part about replacing them when it has no
- * `replaceEntity` mutation, the part about the choices of a field when it has
- * no options edge, and the part about custom changes when the manifest exposes no action. The last two sections explain the
- * `query` and `apply` tools, which every run registers whatever the schema holds, and the change
- * record the `AssistantSystem` attaches to every user message.
- */
+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

@@ -1 +1 @@
-let e=["How to read the GraphQL schema of this configurator:","- A configuration is a set of entities. `root` is the root entity, `entities` lists every entity or the ones with the given ids, and `selectedEntity` is the entity the user has selected, or the root entity when nothing is selected.","- Every entity has an `id` of the form `<Type>-<number>`, for example `Table-1`, and a `type` with its entity type name. Ids are assigned by the configurator: read them from the configuration and never make one up.","- A field whose name starts with `_` is computed by the configurator from other values. It can be read like any other field and never written.","- Numbers are in the units the configuration stores them in. A field description names the unit when the product defines one.",'- A text field that only takes fixed values lists them in its description as "One of: ...". Use exactly those values.',"- A field typed as another entity type or as a list of one is a relation: select fields on it to read the related entities.","- Field and type descriptions come from the team that built the configurator and say what a value means for the product."],t=["How changes work:","- Every field of the `Mutation` type is one change. Its description says what it changes and what it returns.","- The configurator checks the whole configuration after each change. A change that would leave it invalid fails with an error that names the entities at fault, and it is not applied. Later changes of the same request are then not run.","- The configurator may adjust other values in response to a change, so read what a mutation returns instead of assuming the values you sent."],a=["How to add entities:","- Entities are added from recipes, the same ones the configurator offers the user. An entity type that can take children has a `meta` field; `meta { childRecipes }` lists its recipe groups and their recipes.","- List the recipes of the group first, pick one by its `key`, then call `addChild` with the id of the parent, the `groupId` and the `key`. Keys change with the configuration and the language, so never reuse one from memory.","- `dryRun` on a recipe shows what adding it would do without adding it: whether it is `ok`, the `changedEntities` it would add or modify, the `deletedEntityIds` it would remove, the `sideEffects` the configurator says it would have, and the `errors` when it cannot be added. An entity whose id the configuration does not have yet is new. It is costly, so select it only on the recipes you are deciding between.","- Put each `addChild` in its own operation. The recipes of a group and what they add depend on the configuration before them, so after adding something, list the group again before adding from it once more."],n=["How to replace entities:","- An entity is replaced from recipes, the same ones the configurator offers the user. An entity type that can be replaced has a `meta` field; `meta { replaceRecipes }` lists its replace recipe groups and what the entity can be replaced with.","- List the recipes of the group first, pick one by its `key`, then call `replaceEntity` with the id of the entity, the `groupId` and the `key`. `dryRun` on a replace recipe shows what replacing would do without doing it: the replacement and everything else that changes are under `changedEntities`, and the replaced entity is among the `deletedEntityIds`.","- The replacement is a new entity with a new id, and its field values come from the recipe, so they can differ from those of the entity it replaces. Read the ids and values `replaceEntity` returns, and never use the old id again.","- Put each `replaceEntity` in its own operation. The recipes of a group and what they do depend on the configuration before them, so after replacing something, list the group of the replacement again before replacing once more."],o=["How to find the values a field can take:","- Some fields store a key whose choices the configurator holds elsewhere. Such a field has an edge under `meta` named after it: `meta { <field>Options }` lists its choices, each with the `value` to write and the `name` the user sees.","- Read the choices before you write such a field or name a choice to the user, and write the `value`, not the `name`. A value outside the list is rejected unless the edge description says the field is not checked.","- `dryRun` on an option shows what writing its value would do without writing it: whether it is `ok`, the `changedEntities` it would add or modify, the `deletedEntityIds` it would remove, the `sideEffects` the configurator says it would have, and the `errors` when the value cannot be written. It is costly, so select it only on the options you are deciding between. It is null when the edge description says the options cannot be dry-run.","- The choices can depend on the entity and on its current state. Read them again after a change, unless the edge description says they are the same for all instances or do not change."],i=["How the custom changes of this configurator work:","- Besides the generic changes, the `Mutation` type has fields the team built for this product. Each runs one domain operation the configurator itself uses, so prefer it over composing the same change from generic mutations. Its description says what it does and what its arguments mean.","- Its arguments are checked against what the operation declares; an argument that does not fit, or a change the product does not allow, fails the field with a message that says what to send instead.","- It returns an object whose fields the description names; a field typed as an entity reads that entity after the change."],s=["How to use the `query` and `apply` tools:","- Both take `operations`, a list of GraphQL documents that run in order. Each document holds exactly one operation. To do several things, send several items in one call instead of several calls.","- Write values into the document as literals. Use `variables` only for a value that cannot be written as a literal.","- Select only the fields you need: results are returned whole.","- The result has one GraphQL result per operation, in the order sent. When an operation fails, its `errors` say why and the operations after it are not run.","- `query` reads the configuration the user has open and never changes it. Call it before you say anything about the configuration."],h=["- This configurator exposes no changes, so there is nothing for `apply` to run. Say so when the user asks you to change the configuration."],r=['- Mutations inside `query` answer "what if" questions. Each operation sees the changes of the ones before it, so a mutation followed by a query shows the configuration as it would be. Nothing is kept and the user sees no change.',"- `apply` makes the changes the user asked for. It is all or nothing: when any operation fails, nothing is changed; when all succeed, the user gets them as one undo step.","- `committed` in the result says whether the changes were kept. When it is false although no operation failed, `message` says why: the changes may be waiting for the approval of the user, the user may have changed the configuration meanwhile, or this session may not change the configuration at all. Without a `message`, the operations changed nothing. Never tell the user a change was made unless `committed` is true.","- `sideEffects` in the result lists what the configurator did beyond what the operations asked for, such as parts it added or replaced to keep the configuration valid, in its own words. Tell the user about them when the changes were kept. When they were not, or in `query`, it lists what the mutations that succeeded would do. `dryRun` has the same list for a single recipe or option."],d=["How to read the change record:","- Every user message starts with a change record of the configuration since your previous action. It is the complete list of the entities that were added or deleted, of the stored fields of this schema that changed, and of the selection and navigation changes, so update your picture from it and do not query those again when it does not mention them.","- Fields whose name starts with `_` are computed and are never listed. Read them again when the record lists a change they may depend on.","- `[changes: none]`: nothing changed. Do not query again what you already know.","- `[changes]` is followed by one line per change. `selected`, `navigationState`, `viewState` and `toolState` lines show `<old> -> <new>` of what `selectedEntity` and `navigation` return, with `none` for an empty value. `A <id>` is an added entity and `D <id>` a deleted one. `M <id>` is a modified entity, followed by one `<field>: <old> -> <new>` line per changed field, under the name the field has in this schema. A `reset: undo/redo` line says the user undid or redid changes.","- The `#` comment at the end of a line names the control, the transformer or the explanation of the last change to that line.","- `[changes: unavailable]`: the page was loaded since your previous action, so earlier values may be stale. `[changes: too many (n)]`: n entities changed and are not listed. In both cases query what you need."],c=["- Changes you applied are not in the record, except those that were waiting for the approval of the user: they appear in it once approved."];export const generateAssistantPrompt=l=>{let u=/^type Mutation\b/m.test(l.sdl);return[e,...u?[t]:[],.../^\s+addChild\(/m.test(l.sdl)?[a]:[],.../^\s+replaceEntity\(/m.test(l.sdl)?[n]:[],.../^type FieldOption\b/m.test(l.sdl)?[o]:[],...Object.keys(l.actions??{}).length>0?[i]:[],[...s,...u?r:h],[...d,...u?c:[]]].map(e=>e.join("\n")).join("\n\n")};
+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),i=Object.values(a.replaceRecipes??{}).some(e=>e.length>0),o=Object.values(a.fieldOptions??{}).some(e=>e.length>0),r=Object.keys(a.actions??{}).length>0,h=(a.deletableTypes?.length??0)>0||Object.values(a.writableFields??{}).some(e=>Object.keys(e).length>0)||s||i||r,l=s||i||o,d=[...s?["`childRecipes` is what can be added to it"]:[],...i?["`replaceRecipes` what it can be replaced with"]:[],...o?["`<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.",...h?[`- Use a mutation inside \`query\` to answer a what-if about a change ${l?"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."],...h?[["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.","- 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."]:[]]]:[],...l?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${d.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...s||i?["recipes"]:[],...o?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],["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.",...h?["- 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||i?["- 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${h?", 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.",...l?["- 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

@@ -1,4 +1,10 @@
-export type { AssistantResolvedManifest, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedHint, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
+export { ASSISTANT_HINTS } from './assistant-resolved-manifest.js';
+export type { AssistantResolvedManifest, AssistantDeclaredField, AssistantDeclarations, AssistantDeclaredWrite, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedHint, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
 export { buildAssistantManifest } from './build-assistant-manifest.js';
-export type { AssistantFieldSource, AssistantRecipeGroup, AssistantFieldOptions, AssistantManifest, } from './assistant-manifest.js';
+export type { AssistantFieldExposure } from './create-assistant-execution-schema.js';
+export { AssistantFieldClashError, createAssistantExecutionSchema } from './create-assistant-execution-schema.js';
+export type { AssistantFieldSource, 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

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

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

@@ -0,0 +1,50 @@
+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. */
+export interface AssistantSetupRecipes {
+    readonly groups: 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,{groups:Object.fromEntries(t.groups.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,5 +1,4 @@
-import type { DomainEntity, DomainEntityId } from '../core/model.js';
-import type { DomainState } from '../core/state.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>>;

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

@@ -1,8 +1,6 @@
 import type { Localizable } from '@salsita-ai/common/utils';
-import { type StateUpdate } from '../components/updates.js';
-import type { AnyActionContext } from '../core/action.js';
-import { type DomainEntity } from '../core/model.js';
-import type { DomainState } from '../core/state.js';
+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>>;
 /**

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 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(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.'),h=e.object({id:p}),c=e.object({id:p,delta:e.record(e.unknown())}),y="modify",u=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],f=e=>Array.isArray(e)?e.map(f):"object"!=typeof e||null===e||Array.isArray(e)?e:Object.fromEntries(Object.entries(e).map(([e,t])=>[e,f(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,i,{manifest:n})=>{let{id:r}=h.parse(e),o=i.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:[t.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 c=a(i.manifest,"child",h.type),y=c.find(e=>e.groupId===r);if(!y)throw Error(`Entity "${n}" is a ${h.type}, which has no recipe group "${r}". ${c.length>0?`Its recipe groups are: ${$(c.map(({groupId:e})=>e))}.`:`Nothing can be added to a ${h.type}.`} Query "meta { childRecipes { groupId } }" on the entity you want to add to and use a groupId it returns.`);let u=l(i),f=d("child",y,h.id,t,u);if(!f)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 "meta { childRecipes { groupId } }" on "${n}" to see the groups it offers now.`);let g=f.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,f,h.id,t,u);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 c=a(i.manifest,"replace",h.type),y=c.find(e=>e.groupId===r);if(!y)throw Error(`Entity "${n}" is a ${h.type}, which has no replace recipe group "${r}". ${c.length>0?`Its replace recipe groups are: ${$(c.map(({groupId:e})=>e))}.`:`A ${h.type} cannot be replaced.`} Query "meta { replaceRecipes { groupId } }" on the entity you want to replace and use a groupId it returns.`);let u=l(i),f=d("replace",y,h.id,t,u);if(!f)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 "meta { replaceRecipes { groupId } }" on "${n}" to see the groups it offers now.`);let m=f.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,f,h.id,t,u);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,i)=>{let o,a,s=w.find(t=>t.name===e),d=u(i.actions??{},e);if(s)return s;if(void 0!==d)return{name:e,implementation:(e,t,{action:i})=>i.systems.actionSystem.prepareAction(d,f(e),t)};if(!e.startsWith(y))return;let p=e.slice(y.length),h=u(i.writableFields??{},p);return h&&(o=`${y}${p}`,a=Object.keys(h).join(", "),{name:o,implementation:(e,i,s)=>{let{manifest:d}=s,{domain:m}=s.action.systems,{id:g,delta:$}=c.parse(e),w=i.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. ${u(d.writableFields??{},w.type)?`Use ${y}${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=u(h,e);return void 0===i?[]:[{field:e,property:i,value:f(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 j=m.validateEntity({...w,...E});if(!j.success){let e=b.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 ${p}: ${j.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 v=n(d,p);for(let{field:e,value:t}of b){let n=v.find(t=>t.field===e);if(!n?.validate||null===t)continue;let o=r(n,w.id,i,l(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 { ${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:[t.DomainEntityModification({entityId:w.id,stateDelta:E,updateTag:"modifyEntity"})],readResult:({state:e})=>m.getEntity(w.id,e)?m.get$Entity(w.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}),y=e.object({id:p,delta:e.record(e.unknown())}),c="modify",f=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],u=e=>Array.isArray(e)?e.map(u):"object"!=typeof e||null===e||Array.isArray(e)?e:Object.fromEntries(Object.entries(e).map(([e,t])=>[e,u(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 y=a(i.manifest,"child",h.type),c=y.find(e=>e.groupId===r);if(!c)throw Error(`Entity "${n}" is a ${h.type}, which has no recipe group "${r}". ${y.length>0?`Its recipe groups are: ${$(y.map(({groupId:e})=>e))}.`:`Nothing can be added to a ${h.type}.`} Query "meta { childRecipes { groupId } }" on the entity you want to add to and use a groupId it returns.`);let f=l(i),u=d("child",c,h.id,t,f);if(!u)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 "meta { childRecipes { groupId } }" on "${n}" to see the groups it offers now.`);let g=u.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,u,h.id,t,f);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 y=a(i.manifest,"replace",h.type),c=y.find(e=>e.groupId===r);if(!c)throw Error(`Entity "${n}" is a ${h.type}, which has no replace recipe group "${r}". ${y.length>0?`Its replace recipe groups are: ${$(y.map(({groupId:e})=>e))}.`:`A ${h.type} cannot be replaced.`} Query "meta { replaceRecipes { groupId } }" on the entity you want to replace and use a groupId it returns.`);let f=l(i),u=d("replace",c,h.id,t,f);if(!u)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 "meta { replaceRecipes { groupId } }" on "${n}" to see the groups it offers now.`);let m=u.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,u,h.id,t,f);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=f(t.actions??{},e);if(s)return s;if(void 0!==d)return{name:e,implementation:(e,t,{action:i})=>i.systems.actionSystem.prepareAction(d,u(e),t)};if(!e.startsWith(c))return;let p=e.slice(c.length),h=f(t.writableFields??{},p);return h&&(o=`${c}${p}`,a=Object.keys(h).join(", "),{name:o,implementation:(e,t,s)=>{let{manifest:d}=s,{domain:m}=s.action.systems,{id:g,delta:$}=y.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. ${f(d.writableFields??{},w.type)?`Use ${c}${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=f(h,e);return void 0===i?[]:[{field:e,property:i,value:u(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,10 +1,6 @@
 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';
@@ -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