@salsita-ai/sdk 0.50.0-develop.6d8967bc99 → 0.50.0-develop.6fc83d7732

package/dist/domain/application/application-config.d.ts

@@ -6,16 +6,17 @@ import type { Logger } from '@salsita-ai/common/utils';
 import type { SessionRole, SessionTokenPayload } from '@salsita-ai/contracts/api';
 import type { CellValue } from '@salsita-ai/contracts/webhook';
 import type { AdminIntegrationService } from '#package/react-sdk';
-import type { $DomainEntity, DomainEntity, DomainFactory, ProductPreset } from '../core/index.js';
-import type { AnalyticsSystem, TransformerFactory } from '../domain-context/index.js';
-import type { RegistrableTransformer } from '../domain-context/transformers/index.js';
-import type { ProjectModule } from '../project-modules/index.js';
+import type { $DomainEntity, DataCellValue, DataSchema, DomainEntity, DomainFactory, ProductPreset } from '../core/index.js';
+import type { AnalyticsSystem, RegistrableTransformer, TransformerFactory } from '../domain-context/index.js';
+import type { ElementRegistration, ProjectModule } from '../domain-runtime/index.js';
 import type { AssistantResolvedManifest } from './assistant/index.js';
 import type { WebComponentEventDescriptor } from './web-component-event.js';
 import type { WebComponentPropertyDescriptor } from './web-component-property.js';
-export type ImportedTransformer<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string> = {
+type TransformerExport = ReturnType<TransformerFactory<any, any, any, any, any, any, any>> | RegistrableTransformer<any, any, any, any, any, any, any>;
+/** The transformers one `src/transformers/` file exports, under the name of the file. */
+export type ImportedTransformer = {
     name: string;
-    transformer: ReturnType<TransformerFactory<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>> | RegistrableTransformer<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES> | ReadonlyArray<ReturnType<TransformerFactory<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>> | RegistrableTransformer<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>>;
+    transformer: TransformerExport | ReadonlyArray<TransformerExport>;
 };
 export type SpecTransformer = {
     name: string;
@@ -32,26 +33,6 @@ export interface TransformersConfig {
     readonly importedTransformers: readonly ProjectModule[];
     readonly specTransformers: readonly SpecTransformer[];
 }
-export interface DataSchemaPrimitiveField {
-    readonly type: 'string' | 'number' | 'integer' | 'boolean';
-    readonly enum?: ReadonlyArray<string | number>;
-    readonly description?: string;
-}
-export interface DataSchemaLocalizedField {
-    readonly type: 'localized';
-    readonly description?: string;
-}
-export interface DataSchemaArrayField {
-    readonly type: 'array';
-    readonly items: 'string' | 'number' | 'boolean';
-    readonly description?: string;
-}
-export type DataSchemaFieldObject = DataSchemaPrimitiveField | DataSchemaLocalizedField | DataSchemaArrayField;
-export type DataSchemaField = 'string' | 'number' | 'boolean' | readonly ['string', 'null'] | readonly ['number', 'null'] | readonly ['boolean', 'null'] | DataSchemaFieldObject;
-export type DataSchema = Record<string, DataSchemaField>;
-export type DataCellValue = CellValue | null | {
-    readonly $lang: Record<string, string>;
-} | readonly CellValue[];
 export type DataSpecEntry = {
     readonly definition: DataSchema;
     readonly chunk?: string;
@@ -311,6 +292,8 @@ export interface ApplicationConfig<ENTITIES extends DomainEntity<string>, ALLOWE
     /** The `src/handlers/` and `src/elements/` files as project modules; the runtime spec validates and flattens both. */
     readonly handlers: readonly ProjectModule[];
     readonly elements: readonly ProjectModule[];
+    /** The SDK's default element registrations; a project element with the same name replaces one. */
+    readonly defaultElements?: readonly ElementRegistration[];
     readonly mount: MountConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>;
 }
 export {};

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

@@ -0,0 +1,12 @@
+import type { AssistantDeclaredField, AssistantResolvedField } from './assistant-resolved-manifest.js';
+/** Combines the effective description with allowed string values. */
+export declare const describeAssistantValues: (description: string | undefined, values: readonly string[] | undefined) => string | undefined;
+/** Applies GraphQL field inheritance identically at parse time and after session narrowing. */
+export declare const mergeAssistantFields: (inherited: ReadonlyArray<readonly AssistantDeclaredField[]>, own: readonly AssistantDeclaredField[], ownEnumValues: (source: string) => readonly string[] | undefined, conflict: (name: string, first: string, second: string) => void) => readonly AssistantDeclaredField[];
+/**
+ * The serializable form of a merged field of one alias or type. Merging keeps the inherited entry of
+ * a field declared twice, so the lens tags are taken from `own`, the declarations of that alias or
+ * type itself: each lens condition then comes from its own declaration, at parse time and after
+ * session narrowing alike.
+ */
+export declare const resolveAssistantField: (field: AssistantDeclaredField, own: readonly AssistantDeclaredField[]) => AssistantResolvedField;

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

@@ -0,0 +1 @@
+export const describeAssistantValues=(e,s)=>{if(!s?.length)return e;let t=`One of: ${s.map(e=>`"${e}"`).join(", ")}.`;return e?`${e}${/[.!?]$/.test(e)?"":"."} ${t}`:t};export const mergeAssistantFields=(e,s,t,n)=>{let r=new Map,i=new Set(s);for(let t of[...e.flat(),...s]){let e=r.get(t.name);e?e.source!==t.source?n(t.name,e.source,t.source):r.set(t.name,{...e,...i.has(t)&&t.describedByManifest?{description:t.description,describedByManifest:!0,valueDescription:t.valueDescription}:{}}):r.set(t.name,t)}return[...r.values()].map(e=>{let s=e.enumValues&&t(e.source);return s?{...e,enumValues:s,description:describeAssistantValues(e.valueDescription,s)}:e})};export const resolveAssistantField=(e,s)=>{let t=s.find(s=>s.name===e.name&&s.source===e.source)?.lenses;return{name:e.name,source:e.source,localized:e.localized,type:e.type,...void 0===e.description?{}:{description:e.description},...t?.length?{lenses:t}:{}}};

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

@@ -1,3 +1,4 @@
+import type { AssistantFormElementDescriptor } from './form/index.js';
 /**
  * Where one exposed assistant GraphQL field reads its value on the `$` entity: a stored field name,
  * or an expression name including its `$`. `localized` marks a localizable value that resolves to a
@@ -35,6 +36,16 @@ export interface AssistantFieldOptions {
     readonly validate: boolean;
     readonly dryRuns: boolean;
 }
+/**
+ * One view the assistant manifest lets the agent take a screenshot of an entity from: `view` is the
+ * value of the `<Type>ScreenshotView` enum the agent asks for it by, `instanceName` the
+ * `agentScreenshot` component instance that renders it, and `description` what the view shows.
+ */
+export interface AssistantScreenshotView {
+    readonly view: string;
+    readonly instanceName: string;
+    readonly description: string;
+}
 /**
  * Experimental assistant manifest generated from the application spec `assistant` section. `sdl` is
  * the GraphQL schema text rebuilt from the resolved manifest; `fields` maps each GraphQL object type's exposed
@@ -46,16 +57,30 @@ export interface AssistantFieldOptions {
  * the recipe groups `meta { childRecipes }` and `addChild` expose, in manifest order, and absent
  * means none; `replaceRecipes` lists the same for `meta { replaceRecipes }` and `replaceEntity`;
  * `fieldOptions` lists, per entity type, the options edges `meta` exposes for its
- * writable fields, and absent means none; `actions` maps each custom `Mutation` field to the
- * declared action it runs, and absent means none. Consumed by the configurator GraphQL system.
+ * writable fields, and absent means none; `screenshots` lists, per entity type, the views
+ * `meta { screenshot }` renders, and absent means none; `actions` maps each custom `Mutation` field to the
+ * declared action it runs, and absent means none; `lenses` holds the generated lens fragments, and
+ * absent means none: `declarations` is the text the prompt shows, each lens once with its relations
+ * spreading the lens itself, and `definitions` the valid GraphQL injected into an operation that
+ * spreads a lens, with the copies that unroll each lens to its depth. Consumed by the configurator
+ * GraphQL system.
  */
 export interface AssistantManifest {
     readonly sdl: string;
+    /** Navigation state fields exposed by the schema; absent means none. Values stay in the SDL. */
+    readonly navigationFields?: ReadonlyArray<'navigationState' | 'viewState' | 'toolState'>;
     readonly fields: Readonly<Record<string, Readonly<Record<string, AssistantFieldSource>>>>;
     readonly deletableTypes?: readonly string[];
     readonly writableFields?: Readonly<Record<string, Readonly<Record<string, string>>>>;
     readonly childRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
+    readonly screenshots?: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
     readonly actions?: Readonly<Record<string, string>>;
+    readonly lenses?: {
+        readonly declarations: string;
+        readonly definitions: string;
+    };
+    /** The project's own form elements, in YAML order; absent means none. */
+    readonly formElements?: readonly AssistantFormElementDescriptor[];
 }

package/dist/domain/application/assistant/assistant-resolved-manifest.d.ts

@@ -1,4 +1,5 @@
-import type { AssistantFieldOptions, AssistantRecipeGroup } from './assistant-manifest.js';
+import type { AssistantFieldOptions, AssistantRecipeGroup, AssistantScreenshotView } from './assistant-manifest.js';
+import type { AssistantFormElementDescriptor } from './form/index.js';
 /** JSON description of a scalar or recursively nested list, including nullability at each level. */
 export type AssistantValueType = {
     readonly kind: 'scalar';
@@ -15,7 +16,11 @@ export interface AssistantRelationType {
     readonly target: string;
     readonly cardinality: '1-1' | '0-1' | '0-N' | '1-N';
 }
-/** A field's source and resolved type, carried in the application bundle without GraphQL instances. */
+/**
+ * A field's source and resolved type, carried in the application bundle without GraphQL instances.
+ * `lenses` names the lenses the field's own declaration on this alias or type tags it with; a field
+ * only inherited from an alias carries none here, since the alias already selects it.
+ */
 export interface AssistantResolvedField {
     readonly name: string;
     readonly source: string;
@@ -25,6 +30,7 @@ export interface AssistantResolvedField {
     } | AssistantRelationType;
     readonly localized: boolean;
     readonly description?: string;
+    readonly lenses?: readonly string[];
 }
 /** Declared UI state values used to describe the navigation query. */
 export interface AssistantStates {
@@ -34,6 +40,7 @@ export interface AssistantStates {
 }
 /** Serializable resolved whitelist from which the browser or backend constructs the assistant schema. */
 export interface AssistantResolvedManifest {
+    readonly declarations: AssistantDeclarations;
     readonly entityTypes: readonly string[];
     readonly aliases: Readonly<Record<string, readonly string[]>>;
     readonly exampleType?: string;
@@ -44,7 +51,16 @@ export interface AssistantResolvedManifest {
     readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
     readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
     readonly optionsEdges: Readonly<Record<string, readonly AssistantResolvedOptionsEdge[]>>;
+    /** The screenshot views of each entity type with at least one, aliases expanded, in manifest order. */
+    readonly screenshots: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
     readonly actionFields: readonly AssistantResolvedAction[];
+    /** The declared lenses by name: when to use each, and how many levels its tagged relations nest. */
+    readonly lenses: Readonly<Record<string, {
+        readonly description: string;
+        readonly maxDepth: number;
+    }>>;
+    /** The project's own form elements, in YAML order, which the prompt lists after the built-ins and the panel renders with their registered components. */
+    readonly formElements: readonly AssistantFormElementDescriptor[];
 }
 /** Optional mutation input for one stored field, using its exposed name. */
 export interface AssistantWritableField {
@@ -59,7 +75,8 @@ export interface AssistantWritableType {
     readonly fields: readonly AssistantWritableField[];
 }
 /** Description hints resolved from recipe/option entries; no parse context is retained. */
-export type AssistantResolvedHint = 'sameForAllInstances' | 'constantDuringSession';
+export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
+export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
 /** Recipe groups and their description hints for one entity type. */
 export interface AssistantResolvedRecipes {
     readonly groups: readonly AssistantRecipeGroup[];
@@ -93,3 +110,29 @@ export interface AssistantResolvedAction {
     }>>;
     readonly result: Readonly<Record<string, AssistantResolvedActionResult>>;
 }
+/** Immutable, validated declaration bindings retained before alias expansion for session narrowing. */
+export interface AssistantDeclarations {
+    readonly entities: Readonly<Record<string, readonly AssistantDeclaredField[]>>;
+    readonly enumValues: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+    readonly deletable: readonly string[];
+    readonly writable: Readonly<Record<string, Readonly<Record<string, AssistantDeclaredWrite>>>>;
+    readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    /** The screenshot views under the entity type or alias key that declares them. */
+    readonly screenshots: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
+}
+/** An original field declaration, including metadata needed to reapply inheritance and enum descriptions. */
+export interface AssistantDeclaredField extends AssistantResolvedField {
+    readonly describedByManifest: boolean;
+    readonly enumValues?: readonly string[];
+    readonly valueDescription?: string;
+}
+/** Stored-property types and component bindings, resolved separately for each concrete member. */
+export interface AssistantDeclaredWrite {
+    readonly members: Readonly<Record<string, {
+        readonly exposedDescription?: string;
+        readonly field: AssistantWritableField;
+        readonly options?: AssistantResolvedOptionsEdge;
+    }>>;
+    readonly defaultOptionsName: boolean;
+}

package/dist/domain/application/assistant/assistant-resolved-manifest.js

@@ -1 +1 @@
-export{};
+export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];

package/dist/domain/application/assistant/assistant-value-type.js

@@ -1 +1 @@
-import{GraphQLBoolean as e,GraphQLFloat as t,GraphQLID as a,GraphQLInt as n,GraphQLList as r,GraphQLNonNull as l,GraphQLScalarType as s,GraphQLString as i}from"graphql";export const GraphQLJSON=new s({name:"JSON",description:"Any JSON value, returned as stored. Always plain serializable data."});let o={Int:n,Float:t,String:i,Boolean:e,ID:a,JSON:GraphQLJSON};export const createAssistantValueType=e=>{let t="list"===e.kind?new r(createAssistantValueType(e.item)):o[e.name];return e.nonNull?new l(t):t};
+import{GraphQLBoolean as e,GraphQLFloat as n,GraphQLID as t,GraphQLInt as a,GraphQLList as r,GraphQLNonNull as l,GraphQLScalarType as i,GraphQLString as s}from"graphql";export const GraphQLJSON=new i({name:"JSON",description:"Any JSON value, returned unchanged as plain serializable data."});let o={Int:a,Float:n,String:s,Boolean:e,ID:t,JSON:GraphQLJSON};export const createAssistantValueType=e=>{let n="list"===e.kind?new r(createAssistantValueType(e.item)):o[e.name];return e.nonNull?new l(n):n};

package/dist/domain/application/assistant/build-assistant-lenses.d.ts

@@ -0,0 +1,14 @@
+import { type GraphQLSchema } from 'graphql';
+import type { AssistantManifest } from './assistant-manifest.js';
+import type { AssistantResolvedManifest } from './assistant-resolved-manifest.js';
+/**
+ * Generates the lens fragments of a resolved manifest for the execution schema compiled from it. A
+ * declared lens becomes one fragment on `AnyDomainEntity`; one that session narrowing left without a
+ * tagged field is dropped, so the agent is never offered a lens that selects nothing. A built-in lens
+ * is present only when the schema has its type. A tagged relation spreads the lens itself in the
+ * declarations, which GraphQL forbids, so the definitions unroll it into copies down to `maxDepth`,
+ * where relations select only `id`. The definitions are checked here against the execution schema,
+ * with every declared lens spread on one entity, so a fault in them fails the build and not the
+ * operations that spread them.
+ */
+export declare const buildAssistantLenses: (resolved: AssistantResolvedManifest, schema: GraphQLSchema) => NonNullable<AssistantManifest['lenses']>;

package/dist/domain/application/assistant/build-assistant-lenses.js

@@ -0,0 +1,5 @@
+import{NoUnusedFragmentsRule as e,parse as t,specifiedRules as i,validate as n}from"graphql";let s="AnyDomainEntity",r=[{name:"RecipeGroup",description:"A recipe group with its recipes, without their dry-runs.",selections:["groupId","name","description","recipes { ...Recipe }"]},{name:"Recipe",description:"A recipe without its dry-run.",selections:["key","name","description","imageUrl"]},{name:"FieldOption",description:"A value a field accepts, without its dry-run.",selections:["value","name","description","imageUrl","color"]},{name:"DryRun",description:"What a dry-run would do, with the ids of the entities it would change instead of the entities.",selections:["ok","deletedEntityIds","sideEffects","errors { type entityId message }","changedEntities { id }"]}],a=(e,t)=>0===t?e:`${e}__${t}`,l=e=>e.split("\n").map(e=>`# ${e}`.trimEnd()).join("\n"),o=(e,t,i)=>[`fragment ${e} on ${t} {`,...i.map(e=>`  ${e}`),"}"].join("\n"),p=(e,t,i)=>{let n=e=>"edge"===e.type.kind?`${e.name} { ${i} }`:e.name;return o(e,s,["id",...t.flatMap(({typeName:e,fields:t})=>e===s?t.map(n):[`... on ${e} {`,...t.map(e=>`  ${n(e)}`),"}"])])};export const buildAssistantLenses=(d,m)=>{let c=Object.entries(d.lenses).flatMap(([e,t])=>{let i=[s,...Object.keys(d.aliases).filter(e=>e!==s),...d.entityTypes].flatMap(t=>{let i=(d.fields[t]??[]).filter(t=>t.lenses?.includes(e));return i.length>0?[{typeName:t,fields:i}]:[]});return i.length>0?[{name:e,...t,conditions:i}]:[]}),$=r.filter(({name:e})=>void 0!==m.getType(e)),h=[...c.map(({name:e,description:t,maxDepth:i,conditions:n})=>{let s=n.some(({fields:e})=>e.some(e=>"edge"===e.type.kind));return`${l(s?`${t} ${`Nested relations carry the same selection up to ${i} ${1===i?"level":"levels"}, below that only \`id\`.`}`:t)}
+${p(e,n,`...${e}`)}`}),...$.map(({name:e,description:t,selections:i})=>`${l(t)}
+${o(e,e,i)}`)].join("\n\n"),u=[...c.flatMap(({name:e,maxDepth:t,conditions:i})=>Array.from({length:t+1},(n,s)=>p(a(e,s),i,s<t?`...${a(e,s+1)}`:"id"))),...$.map(({name:e,selections:t})=>o(e,e,t))].join("\n\n");if(""!==u){let s=c.length>0?`entities { ${c.map(({name:e})=>`...${e}`).join(" ")} }`:"__typename",r=n(m,t(`${u}
+
+{ ${s} }`),i.filter(t=>t!==e));if(r.length>0)throw Error(`The lens fragments generated from "assistant.lenses" are not valid GraphQL: ${[...new Set(r.map(e=>e.message))].join(" ")}`)}return{declarations:h,definitions:u}};

package/dist/domain/application/assistant/build-assistant-manifest.js

@@ -1 +1 @@
-import{GraphQLBoolean as e,GraphQLID as t,GraphQLInputObjectType as n,GraphQLInterfaceType as i,GraphQLList as o,GraphQLNonNull as r,GraphQLObjectType as s,GraphQLSchema as a,GraphQLString as p,printSchema as d,validateSchema as h}from"graphql";import{GraphQLJSON as c,createAssistantValueType as l}from"./assistant-value-type.js";let y="AnyDomainEntity",u="RootEntity",f={section:"childRecipes",mutation:"addChild"},g={section:"replaceRecipes",mutation:"replaceEntity"},w=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],m=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},b=({target:e,cardinality:t},n)=>{let i=n(e);switch(t){case"1-1":return new r(i);case"0-1":return i;case"0-N":case"1-N":return new r(new o(new r(i)))}},v=(e,n,i)=>{let o={id:{type:new r(t),description:i?`Unique id of the entity, e.g. "${i}-1".`:void 0},type:{type:new r(p),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let t of e)o[t.name]={type:"edge"===t.type.kind?b(t.type,n):l(t.type.type),description:t.description};return o},$=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),j={sameForAllInstances:e=>`All ${e} instances have the same recipe groups and recipes.`,constantDuringSession:()=>"They do not change during the session."},O={sameForAllInstances:e=>`All ${e} instances have the same options.`,constantDuringSession:()=>"The options do not change during the session."},E=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),R=({section:e},{groups:t,hints:n},{entityType:i,purpose:s,recipeGroup:a})=>{let p=t.filter(({dryRuns:e})=>!e).map(({groupId:e})=>e);return 0===t.length?{}:{[e]:{type:new r(new o(new r(a))),description:`The recipe groups for ${s} this ${i}: ${t.map(({groupId:e})=>e).join(", ")}. A group is listed only while the configurator offers it on the entity.${p.length>0?` Recipes of these groups cannot be dry-run: ${p.join(", ")}.`:""}${E(n,j,i)}`}}},k=({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i},{recipeGroup:a,fieldOption:p})=>new s({name:`${e}Meta`,fields:Object.assign(R(f,t,{entityType:e,purpose:"adding children to",recipeGroup:a}),R(g,n,{entityType:e,purpose:"replacing",recipeGroup:a}),...i.map(({options:{edgeName:t,field:n,validate:i,dryRuns:s},hints:a})=>({[t]:{type:new o(new r(p)),description:`The values "${n}" of this ${e} can take, as the configurator offers them in the current state of the entity. Null when the configurator does not offer a choice on this entity. ${i?`modify${e} rejects a "${n}" value that is not in the list.`:`modify${e} does not check "${n}" against the list.`}${s?"":" Its options cannot be dry-run."}${E(a,O,e)}`}})))}),I=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=b=>{var j,O,E,R,T;let A,N,D,M,{entityTypes:S,aliases:q,exampleType:W,fields:C,states:G,deletableTypes:K,writableTypes:U,actionFields:F,optionsEdges:x}=b,z=Object.fromEntries(Object.entries(b.childRecipes).map(([e,t])=>[e,t.groups])),Q=Object.fromEntries(Object.entries(b.replaceRecipes).map(([e,t])=>[e,t.groups])),B=new Map,H=new Map,J=new Map,L=e=>{let[t,...n]=Object.entries(q).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?H.get(t):void 0)??J.get(e)??V},P=e=>H.get(e)??L(e),V=new i({name:y,description:"Every domain entity.",fields:()=>v(C[y]??[],P,W)});for(let e of(J.set(y,V),Object.keys(q)))e!==y&&J.set(e,new i({name:e,interfaces:[V],fields:()=>v(C[e]??[],P)}));let X={};for(let e of S){let t=[y,...Object.entries(q).filter(([t,n])=>t!==y&&n.includes(e)).map(([e])=>e)],n=C[e]??[];X[e]=$(n),H.set(e,new s({name:e,interfaces:t.flatMap(e=>J.get(e)??[]),fields:()=>{let t=B.get(e);return{...v(n,P),...t?{meta:{type:new r(t),description:"What the configurator offers on this entity besides its fields."}}:{}}}}))}let Y=(j=()=>L(J.has(u)?u:y),O=()=>L(y),A=new s({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new r(p),description:'Kind of the problem, or "uncaught".'},entityId:{type:t,description:"The entity the problem is on, when it is on one."},message:{type:p,description:"The problem as the configurator words it for the user."}}}),new s({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new r(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:j(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new r(new o(new r(O()))),description:"Every entity the change would add or modify, read from that configuration; empty when ok is false. An entity whose id the configuration does not have yet would be added, and its id may differ in the real mutation. An entity that is written to is listed even when it gets the values it already has."},deletedEntityIds:{type:new r(new o(new r(t))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new r(new o(new r(p))),description:"What the configurator would do beyond the change itself, such as parts it would add or replace, in its own words; empty when ok is false."},errors:{type:new r(new o(new r(A))),description:"Why the change cannot be made; empty when ok is true."}})})),Z={recipeGroup:(E=[...Object.keys(z).length>0?[f.mutation]:[],...Object.keys(Q).length>0?[g.mutation]:[]],N=E.join(" or "),D=new s({name:"Recipe",description:"One recipe of a recipe group: something that can be added to the entity, or something the entity can be replaced with, depending on the edge the group is listed under.",fields:{key:{type:new r(p),description:`Identifies the recipe within its group; pass it to ${N} as recipeKey. Keys can change with the configuration and with the language, so read them from the listing rather than remembering them.`},name:{type:new r(p),description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Thumbnail shown to the user."},dryRun:{type:Y,description:"Tries the recipe out. Each selected dry-run costs a full recalculation, so select it only on the recipes you are deciding between. Null for a group whose recipes cannot be dry-run."}}}),new s({name:"RecipeGroup",description:"A group of recipes of an entity, as the configurator offers them to the user.",fields:{groupId:{type:new r(p),description:`Identifies the group on its entity; pass it to ${N} as recipeGroupId.`},name:{type:new r(p),description:"Name shown to the user."},description:{type:p},recipes:{type:new r(new o(new r(D)))}}})),fieldOption:new s({name:"FieldOption",description:"One choice of a field, as the configurator offers it to the user.",fields:{value:{type:new r(c),description:"The value to write to the field."},name:{type:p,description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Image shown to the user."},color:{type:p,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:Y,description:"Tries writing the value to the field. Each selected dry-run costs a full recalculation, so select it only on the options you are deciding between. Null for a field whose options cannot be dry-run."}}})};for(let e of S){let t=w(b.childRecipes,e)??{groups:[],hints:[]},n=w(b.replaceRecipes,e)??{groups:[],hints:[]},i=w(x,e)??[];(t.groups.length>0||n.groups.length>0||i.length>0)&&B.set(e,k({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i},Z))}let _=new a({query:(R=L(J.has(u)?u:y),T=L(y),M=(e=>{let t={};for(let[n,i,o]of[["navigationState","Active navigation state.",e.navigationStates],["viewState","Active view state.",e.viewStates],["toolState","Active tool state.",e.toolStates]])o.length>1&&(t[n]={type:new r(p),description:m(i,o)});if(0!==Object.keys(t).length)return new s({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(G),new s({name:"Query",fields:{root:{type:new r(R),description:"The root entity of the configuration."},entities:{type:new r(new o(T)),args:{ids:{type:new o(new r(t))}},description:`Every entity of the configuration, or, when ids are given, those entities in the same order with null for an unknown id. Ids have the form "<Type>-<number>"${W?`, e.g. "${W}-1"`:""}; any other id is an error.`},selectedEntity:{type:new r(T),description:"The selected entity, or the root entity when nothing is selected."},...M?{navigation:{type:new r(M)}}:{}}})),mutation:(({deletableTypes:e,writableTypes:i,childRecipes:a,replaceRecipes:d,actionFields:h,objectTypes:c,anyDomainEntity:y,targetOutputType:u})=>{let f,g;if(0!==e.length||0!==i.length||0!==Object.keys(a).length||0!==Object.keys(d).length||0!==h.length)return new s({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new r(new o(new r(t))),args:{id:{type:new r(t)}},description:`Deletes the entity with the given id, together with the entities composed into it, and returns the ids of every entity the deletion removed, the given one first. Deletable entity types: ${e.join(", ")}. Nothing can be read from removed entities afterwards, so query what you need from them before deleting.`}},0===(f=I(a)).length?{}:{addChild:{type:new r(new o(new r(y))),args:{parentId:{type:new r(t)},recipeGroupId:{type:new r(p)},recipeKey:{type:new r(p)}},description:`Adds a child to the entity with the id parentId by one recipe of one of its recipe groups. Entity types with recipe groups: ${f.join("; ")}. Read the groupId and the recipe key from "meta { childRecipes }" of the parent. Returns every entity the change added, the recipe's own first and then whatever the configurator added in response, such as a part the new child needs; the list is empty when the configurator removed them again.`}},0===(g=I(d)).length?{}:{replaceEntity:{type:new r(new o(new r(y))),args:{entityId:{type:new r(t)},recipeGroupId:{type:new r(p)},recipeKey:{type:new r(p)}},description:`Replaces the entity with the id entityId by one recipe of one of its replace recipe groups. Entity types with replace recipe groups: ${g.join("; ")}. Read the groupId and the recipe key from "meta { replaceRecipes }" of the entity. The replacement is a new entity with a new id: the id passed in no longer exists afterwards, and the replacement has the field values of its recipe, not those of the entity it replaces. Returns every entity the change added, the replacement first and then whatever the configurator added in response, such as a part the replacement needs; the list is empty when the configurator removed them again.`}},...i.flatMap(e=>{let i=c.get(e.entityType);return i?[(({entityType:e,fields:i},o)=>{let s=Object.fromEntries(i.map(({name:e,type:t,description:n})=>[e,{type:l(t),description:n}]));return{[`modify${e}`]:{type:o,args:{id:{type:new r(t)},delta:{type:new r(new n({name:`${e}Delta`,fields:s}))}},description:`Changes writable fields of the one ${e} with the given id: ${i.map(({name:e})=>e).join(", ")}. The delta sets only the fields it names and needs at least one; values are in stored units, as the field descriptions say. Returns the entity as it is after the change, including what the configurator adjusted in response, or null when the change caused the entity to be removed.`}}})(e,i)]:[]}),Object.fromEntries(h.map(e=>{var t;return[e.fieldName,{type:new r(new s({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?(({target:e,list:t,nullable:n},i)=>{let s=t?new o(new r(i(e))):i(e);return n?s:new r(s)})(t,u):l(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:l(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:K,writableTypes:U,childRecipes:z,replaceRecipes:Q,actionFields:F,objectTypes:H,anyDomainEntity:L(y),targetOutputType:P}),types:[...J.values(),...H.values()]}),ee=h(_);if(ee.length>0)throw Error(ee.map(e=>e.message).join(" "));return{sdl:d(_),fields:X,deletableTypes:K,writableFields:Object.fromEntries(U.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:z,replaceRecipes:Q,fieldOptions:Object.fromEntries(S.flatMap(e=>{let t=w(x,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),actions:Object.fromEntries(F.map(({fieldName:e,actionName:t})=>[e,t]))}};
+import{GraphQLBoolean as e,GraphQLEnumType as t,GraphQLID as n,GraphQLInputObjectType as i,GraphQLInterfaceType as s,GraphQLList as r,GraphQLNonNull as o,GraphQLObjectType as a,GraphQLSchema as p,GraphQLString as c,printSchema as d,validateSchema as l}from"graphql";import{GraphQLJSON as h,createAssistantValueType as w}from"./assistant-value-type.js";import{buildAssistantLenses as y}from"./build-assistant-lenses.js";import{createAssistantExecutionSchema as u}from"./create-assistant-execution-schema.js";let m="AnyDomainEntity",f="RootEntity",g=[["navigationState","Active navigation state.","navigationStates"],["viewState","Active view state.","viewStates"],["toolState","Active tool state.","toolStates"]],b={section:"childRecipes",mutation:"addChild"},v={section:"replaceRecipes",mutation:"replaceEntity"},j=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],$=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},O=({target:e,cardinality:t},n)=>{let i=n(e);switch(t){case"1-1":return new o(i);case"0-1":return i;case"0-N":case"1-N":return new o(new r(new o(i)))}},E=(e,t,i)=>{let s={id:{type:new o(n),description:i?`Unique id of the entity, assigned by the configurator, e.g. "${i}-1".`:void 0},type:{type:new o(c),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let n of e)s[n.name]={type:"edge"===n.type.kind?O(n.type,t):w(n.type.type),description:n.description};return s},R=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),k={sameForAllInstances:e=>`Same recipe groups and recipes for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},T={sameForAllInstances:e=>`Same for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},I=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),N=({section:e},{groups:t,hints:n},{entityType:i,purpose:s,recipeGroup:a})=>{let p=t.filter(({dryRuns:e})=>!e).map(({groupId:e})=>e);return 0===t.length?{}:{[e]:{type:new o(new r(new o(a))),description:`The recipe groups for ${s} this ${i}: ${t.map(({groupId:e})=>e).join(", ")}. A group is listed only while the configurator offers it on the entity.${p.length>0?` Recipes of these groups cannot be dry-run: ${p.join(", ")}.`:""}${I(n,k,i)}`}}},A=({entityType:e,childRecipes:n,replaceRecipes:i,optionsEdges:s,screenshots:p},{recipeGroup:c,fieldOption:d,screenshot:l})=>new a({name:`${e}Meta`,fields:Object.assign(N(b,n,{entityType:e,purpose:"adding children to",recipeGroup:c}),N(v,i,{entityType:e,purpose:"replacing",recipeGroup:c}),...s.map(({options:{edgeName:t,field:n,validate:i,dryRuns:s},hints:a})=>({[t]:{type:new r(new o(d)),description:`Values "${n}" accepts on this ${e}. Null when there is no choice to make.${i?"":" Not checked on write."}${s?"":" Cannot be dry-run."}${I(a,T,e)}`}})),0===p.length?{}:{screenshot:{type:l,args:{view:{type:new o(new t({name:`${e}ScreenshotView`,values:Object.fromEntries(p.map(({view:e,description:t})=>[e,{description:t}]))}))}},description:"Renders this entity from a predefined view. The picture follows the tool result as an image labelled with `image`. Each one costs tokens and blocks the user's configurator while it renders: ask only when seeing the design answers something the data cannot. The images of one call share a size budget; past it, further screenshots come back null. Null as well when the view does not apply to this entity right now."}})}),S=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=t=>{var O,k,T,I,N;let M,D,F,W,{entityTypes:x,aliases:C,exampleType:q,fields:G,states:U,deletableTypes:K,writableTypes:V,actionFields:z,optionsEdges:P}=t,L=Object.fromEntries(Object.entries(t.childRecipes).map(([e,t])=>[e,t.groups])),Q=Object.fromEntries(Object.entries(t.replaceRecipes).map(([e,t])=>[e,t.groups])),B=new Map,H=new Map,J=new Map,X=e=>{let[t,...n]=Object.entries(C).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?H.get(t):void 0)??J.get(e)??Z},Y=e=>H.get(e)??X(e),Z=new s({name:m,description:"Every entity of the configuration.",fields:()=>E(G[m]??[],Y,q)});for(let e of(J.set(m,Z),Object.keys(C)))e!==m&&J.set(e,new s({name:e,interfaces:[Z],fields:()=>E(G[e]??[],Y)}));let _={};for(let e of x){let t=[m,...Object.entries(C).filter(([t,n])=>t!==m&&n.includes(e)).map(([e])=>e)],n=G[e]??[];_[e]=R(n),H.set(e,new a({name:e,interfaces:t.flatMap(e=>J.get(e)??[]),fields:()=>{let t=B.get(e);return{...E(n,Y),...t?{meta:{type:new o(t),description:"What can be done to this entity right now."}}:{}}}}))}let ee=(O=()=>X(J.has(f)?f:m),k=()=>X(m),M=new a({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new o(c),description:"Kind of the problem."},entityId:{type:n,description:"The entity the problem is on, when it is on one."},message:{type:c,description:"The problem as the user would be told it."}}}),new a({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new o(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:O(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new o(new r(new o(k()))),description:"Entities the change would add or modify; empty when ok is false. One whose id is not in the configuration would be added, and its real id may differ. An entity written to is listed even when its values stay the same."},deletedEntityIds:{type:new o(new r(new o(n))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new o(new r(new o(c))),description:"The major or unexpected things the configurator would change along with it; empty when ok is false."},errors:{type:new o(new r(new o(M))),description:"Why the change cannot be made; empty when ok is true."}})})),et={recipeGroup:(T=[...Object.keys(L).length>0?[b.mutation]:[],...Object.keys(Q).length>0?[v.mutation]:[]],D=T.join(" or "),F=new a({name:"Recipe",description:`${T.includes("addChild")?"One thing that can be added to the entity (under childRecipes)":"One thing the entity can be replaced with (under replaceRecipes)"}${T.length>1?" or that it can be replaced with (under replaceRecipes)":""}.`,fields:{key:{type:new o(c),description:`Pass to ${D} as recipeKey. Valid only for the listing it came from.`},name:{type:new o(c),description:"Name shown to the user."},description:{type:c},imageUrl:{type:c,description:"Thumbnail shown to the user."},dryRun:{type:ee,description:"What using this recipe would do. Null when it cannot be tried."}}}),new a({name:"RecipeGroup",description:"A group of recipes for this entity.",fields:{groupId:{type:new o(c),description:`Pass to ${D} as recipeGroupId.`},name:{type:new o(c),description:"Name shown to the user."},description:{type:c},recipes:{type:new o(new r(new o(F)))}}})),fieldOption:new a({name:"FieldOption",description:"One value a field accepts. Writing a value outside the list is rejected unless the field description says it is not checked.",fields:{value:{type:new o(h),description:"The value to write to the field."},name:{type:c,description:"Name shown to the user."},description:{type:c},imageUrl:{type:c,description:"Image shown to the user."},color:{type:c,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:ee,description:"What writing this value would do. Null when it cannot be tried."}}}),screenshot:new a({name:"Screenshot",description:"A screenshot of an entity. The picture itself follows the tool result.",fields:{image:{type:new o(n),description:"Label of the image that follows the tool result."}}})};for(let e of x){let n=j(t.childRecipes,e)??{groups:[],hints:[]},i=j(t.replaceRecipes,e)??{groups:[],hints:[]},s=j(P,e)??[],r=j(t.screenshots,e)??[];(n.groups.length>0||i.groups.length>0||s.length>0||r.length>0)&&B.set(e,A({entityType:e,childRecipes:n,replaceRecipes:i,optionsEdges:s.map(t=>({...t,hints:(C[f]??[]).includes(e)?t.hints.filter(e=>"sameForAllInstances"!==e):t.hints})),screenshots:r},et))}let en=new p({query:(I=X(J.has(f)?f:m),N=X(m),W=(e=>{let t={};for(let[n,i,s]of g){let r=e[s];r.length>1&&(t[n]={type:new o(c),description:$(i,r)})}if(0!==Object.keys(t).length)return new a({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(U),new a({name:"Query",fields:{root:{type:new o(I),description:"The root entity of the configuration."},entities:{type:new o(new r(N)),args:{ids:{type:new r(new o(n))}},description:"Every entity, or the given ids in order with null for an unknown id."},selectedEntity:{type:new o(N),description:"The selected entity, or the root entity when nothing is selected."},...W?{navigation:{type:new o(W)}}:{}}})),mutation:(({deletableTypes:e,writableTypes:t,childRecipes:s,replaceRecipes:p,actionFields:d,objectTypes:l,anyDomainEntity:h,targetOutputType:y})=>{let u,m;if(0!==e.length||0!==t.length||0!==Object.keys(s).length||0!==Object.keys(p).length||0!==d.length)return new a({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new o(new r(new o(n))),args:{id:{type:new o(n)}},description:`Deletes the entity and everything composed into it. Deletable types: ${e.join(", ")}. Returns the ids removed, the given one first.`}},0===(u=S(s)).length?{}:{addChild:{type:new o(new r(new o(h))),args:{parentId:{type:new o(n)},recipeGroupId:{type:new o(c)},recipeKey:{type:new o(c)}},description:`Adds a child to the entity parentId from a recipe listed under its meta { childRecipes }. Types with child recipes: ${u.join("; ")}. Returns the entities added, the recipe's own first; empty when they were removed again.`}},0===(m=S(p)).length?{}:{replaceEntity:{type:new o(new r(new o(h))),args:{entityId:{type:new o(n)},recipeGroupId:{type:new o(c)},recipeKey:{type:new o(c)}},description:`Replaces the entity entityId from a recipe listed under its meta { replaceRecipes }. Types with replace recipes: ${m.join("; ")}. The replacement is a new entity: it has a new id and the field values of its recipe, and entityId no longer exists. Returns the entities added, the replacement first; empty when they were removed again.`}},...t.flatMap(e=>{let t=l.get(e.entityType);return t?[(({entityType:e,fields:t},s)=>{let r=Object.fromEntries(t.map(({name:e,type:t,description:n})=>[e,{type:w(t),description:n}]));return{[`modify${e}`]:{type:s,args:{id:{type:new o(n)},delta:{type:new o(new i({name:`${e}Delta`,fields:r}))}},description:`Sets the fields named in delta on one ${e}. Returns the entity after the change, or null when the change removed it.`}}})(e,t)]:[]}),Object.fromEntries(d.map(e=>{var t;return[e.fieldName,{type:new o(new a({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?(({target:e,list:t,nullable:n},i)=>{let s=t?new r(new o(i(e))):i(e);return n?s:new o(s)})(t,y):w(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:w(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:K,writableTypes:V,childRecipes:L,replaceRecipes:Q,actionFields:z,objectTypes:H,anyDomainEntity:X(m),targetOutputType:Y}),types:[...J.values(),...H.values()]}),ei=l(en);if(ei.length>0)throw Error(ei.map(e=>e.message).join(" "));let es=d(en);return{sdl:es,navigationFields:g.filter(([,,e])=>U[e].length>1).map(([e])=>e),fields:_,deletableTypes:K,writableFields:Object.fromEntries(V.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:L,replaceRecipes:Q,fieldOptions:Object.fromEntries(x.flatMap(e=>{let t=j(P,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),screenshots:Object.fromEntries(x.flatMap(e=>{let n=j(t.screenshots,e);return n?[[e,n]]:[]})),actions:Object.fromEntries(z.map(({fieldName:e,actionName:t})=>[e,t])),lenses:y(t,u(es)),formElements:t.formElements}};

package/dist/domain/application/assistant/create-assistant-execution-schema.d.ts

@@ -0,0 +1,32 @@
+import { type GraphQLSchema } from 'graphql';
+/** One entity type or alias exposing a field, with the field's type as the assistant schema prints it. */
+export interface AssistantFieldExposure {
+    readonly typeName: string;
+    readonly type: string;
+}
+/**
+ * Entity types or aliases expose one field name in shapes no selection can hold together: a single
+ * entity, a list of entities and a plain value cannot share a name. GraphQL rejects every operation
+ * that selects the field on both, and no common type exists to widen them to. `exposures` lists the
+ * aliases and types that declare the field, without the members that only repeat an alias's field.
+ */
+export declare class AssistantFieldClashError extends Error {
+    readonly fieldName: string;
+    readonly exposures: readonly AssistantFieldExposure[];
+    constructor(fieldName: string, exposures: readonly AssistantFieldExposure[]);
+}
+/**
+ * Compiles the schema operations are validated and executed against from the assistant SDL the agent
+ * reads. GraphQL requires fields selected under one name to have the same type, nullability included,
+ * even on entity types that can never be the same entity, so a lens or a hand-written selection that
+ * reaches such a field on two types would be rejected although its result is unambiguous. The
+ * execution schema therefore widens the type of every field name that entity types and aliases
+ * expose with different types, and leaves everything else as it is. It accepts every operation the
+ * SDL accepts and some the SDL would reject; the SDL stays the precise description of the data.
+ * Accepted: a widened field no longer enforces its SDL type on the value it resolves to. A null in a
+ * field the SDL declares non-null is returned as null instead of failing the operation, and a field
+ * widened to `JSON` is returned as it is, without the coercion of its scalar. Values that match their
+ * SDL type, which is every value a valid configuration holds, give the same result. Throws
+ * {@link AssistantFieldClashError} for the shapes nothing can widen.
+ */
+export declare const createAssistantExecutionSchema: (sdl: string) => GraphQLSchema;

package/dist/domain/application/assistant/create-assistant-execution-schema.js

@@ -0,0 +1 @@
+import{Kind as e,buildASTSchema as t,parse as n,print as a}from"graphql";let i="AnyDomainEntity",l="JSON",s=new Set(["Int","Float","String","Boolean","ID",l]);export class AssistantFieldClashError extends Error{fieldName;exposures;constructor(e,t){super(`The field "${e}" cannot be selected on every entity type that has it: ${t.map(({typeName:t,type:n})=>`${t}.${e} is ${n}`).join(", ")}.`),this.fieldName=e,this.exposures=t,this.name="AssistantFieldClashError"}}let r=t=>(t.kind===e.OBJECT_TYPE_DEFINITION||t.kind===e.INTERFACE_TYPE_DEFINITION)&&(t.name.value===i||(t.interfaces??[]).some(({name:e})=>e.value===i)),o=t=>t.kind===e.NON_NULL_TYPE?t.type:t,m=t=>t.kind===e.NAMED_TYPE?t.name.value:m(t.type),u=e=>a(e).replace(m(e),""),p={kind:e.NAMED_TYPE,name:{kind:e.NAME,value:l}},d=(t,n)=>{let i=n.map(({type:e})=>e);if(1===new Set(i.map(e=>a(e))).size)return;let l=i.map(e=>s.has(m(e)));if(l.every(Boolean))return 1===new Set(i.map(e=>a(o(e)))).size?"nullable":"json";if(!l.some(Boolean)){if(1===new Set(i.map(u)).size)return;if(i.every(t=>o(t).kind===e.NAMED_TYPE))return"nullable"}throw new AssistantFieldClashError(t,n.filter(({inherited:e})=>!e).map(({typeName:e,type:t})=>({typeName:e,type:a(t)})))};export const createAssistantExecutionSchema=a=>t((t=>{let n=t.definitions.filter(r),a=(e,t)=>n.some(n=>n.name.value===e&&(n.fields??[]).some(e=>e.name.value===t)),i=new Map;for(let e of n)for(let t of e.fields??[])i.set(t.name.value,[...i.get(t.name.value)??[],{typeName:e.name.value,type:t.type,inherited:(e.interfaces??[]).some(({name:e})=>a(e.value,t.name.value))}]);let s=new Map;for(let[e,t]of i){let n=d(e,t);n&&s.set(e,n)}let m=e=>{let t=s.get(e.name.value);return t?{...e,type:"json"===t?p:o(e.type)}:e},u=t.definitions.map(e=>r(e)?{...e,fields:e.fields?.map(m)}:e),f=u.some(t=>t.kind===e.SCALAR_TYPE_DEFINITION&&t.name.value===l),E=[...s.values()].includes("json");return{...t,definitions:E&&!f?[...u,{kind:e.SCALAR_TYPE_DEFINITION,name:{kind:e.NAME,value:l}}]:u}})(n(a)));

package/dist/domain/application/assistant/form/assistant-form-element-name.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The shape of a form element's tag, and of its attributes' names: the panel reads form markup
+ * with lowercase tag and attribute names, so a name with an upper-case letter would never match.
+ */
+export declare const ASSISTANT_FORM_NAME_PATTERN: RegExp;
+/**
+ * Whether a tag is an HTML element name, which no form element may take, so that markup in a form
+ * is never mistaken for HTML. The spec rejects a project's element by it and the panel's registry
+ * refuses one, so both read the same list.
+ */
+export declare const isHtmlElementName: (name: string) => boolean;

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;