@memberjunction/ng-conversations 6.2.0-edge.3 → 6.2.0-edge.4

package/dist/lib/components/realtime/interactive-component/component-contract.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Derives what an agent can do with a component from the component's own specification.
+ *
+ * A component artifact already says what it accepts and emits: its `properties` (inputs), its `events`, and its
+ * `methods` (standard methods it supports plus custom ones with typed parameters). This module turns that into the
+ * channel contract's vocabulary, so an agent can operate a component nobody wrote channel code for:
+ *
+ * | spec | contract |
+ * |---|---|
+ * | `methods.customMethods[]` | a verb per method, parameters schema from the declared parameter types |
+ * | `methods.standardMethodsSupported` | `refresh`, `print`, `validate`, `is_dirty`, `reset`, `scroll_to`, `focus`, and `get_data_state` |
+ * | `methods.standardMethodsSupported.getCurrentDataState` | the instance's `data` in the channel's state (the noun) |
+ * | `events[]` | channel events, payload schema from the event parameters |
+ * | `properties[]` | the schema of the `inputs` accepted when opening it |
+ *
+ * A verb whose result carries what the component holds (`get_data_state`, `validate`, `is_dirty`, and any custom method that
+ * returns something) is marked `ReturnsChannelData: 'state'`, so the agent is refused it when it may not perceive the
+ * component's state (see `RealtimeChannelVerb.ReturnsChannelData`).
+ *
+ * Pure functions over plain data: no component is rendered and nothing is invoked here.
+ *
+ * @module @memberjunction/ng-conversations
+ */
+import type { RealtimeChannelEventSpec, RealtimeChannelSchema, RealtimeChannelVerb } from '@memberjunction/ai-core-plus';
+import type { ComponentSpec } from '@memberjunction/interactive-component-types';
+import { STANDARD_VERBS } from './interactive-component-types';
+/** How a verb reaches the component. */
+export type VerbBinding = {
+    Kind: 'standard';
+    Standard: keyof typeof STANDARD_VERBS;
+} | {
+    Kind: 'custom';
+    Method: string;
+    ParameterNames: string[];
+};
+/** One verb derived from a spec, with how to run it. */
+export interface DerivedVerb {
+    /** The verb as the agent sees it. */
+    Verb: RealtimeChannelVerb;
+    /** How the channel runs it. */
+    Binding: VerbBinding;
+}
+/** A method the contract could not expose, and why (kept so a spec problem is visible rather than silently dropped). */
+export interface SkippedMethod {
+    /** The method's name. */
+    Name: string;
+    /** Why it was not exposed. */
+    Reason: string;
+}
+/** Everything an agent can do with one component, derived from its spec. */
+export interface ComponentContract {
+    /** The verbs, standard and custom. */
+    Verbs: DerivedVerb[];
+    /** The events the component can emit. */
+    Events: RealtimeChannelEventSpec[];
+    /** The schema of the `inputs` accepted when opening it (from the spec's `properties`). */
+    InputsSchema: RealtimeChannelSchema;
+    /** Whether the component reports a data state (`getCurrentDataState` is supported), i.e. whether the instance has `data` to describe. */
+    SupportsDataState: boolean;
+    /** Methods that could not be exposed. */
+    Skipped: SkippedMethod[];
+}
+/**
+ * Derives the full contract of one component from its spec.
+ *
+ * @param spec The component's specification.
+ */
+export declare function DeriveComponentContract(spec: ComponentSpec): ComponentContract;
+/**
+ * Merges the same verb offered by several open components into the single verb the channel declares.
+ *
+ * Verbs from different components can share a name with different parameters (two components that both have
+ * `setFilter`). The channel declares one verb per name; its schema is the UNION of the parameters with nothing
+ * required, so a call that suits any of them passes the dispatcher, and the exact per-component check
+ * (against that component's own schema) happens when the verb runs. The description lists each component's signature.
+ *
+ * @param offers Each component's verb of this name, with the component's display name.
+ */
+export declare function MergeVerbOffers(offers: ReadonlyArray<{
+    Component: string;
+    Verb: RealtimeChannelVerb;
+}>): RealtimeChannelVerb;
+//# sourceMappingURL=component-contract.d.ts.map

package/dist/lib/components/realtime/interactive-component/component-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-contract.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/realtime/interactive-component/component-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACzH,OAAO,KAAK,EAAE,aAAa,EAAyB,MAAM,6CAA6C,CAAC;AACxG,OAAO,EAAE,cAAc,EAAiB,MAAM,+BAA+B,CAAC;AAE9E,wCAAwC;AACxC,MAAM,MAAM,WAAW,GACjB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,OAAO,cAAc,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEnE,wDAAwD;AACxD,MAAM,WAAW,WAAW;IACxB,qCAAqC;IACrC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,+BAA+B;IAC/B,OAAO,EAAE,WAAW,CAAC;CACxB;AAED,wHAAwH;AACxH,MAAM,WAAW,aAAa;IAC1B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAC9B,sCAAsC;IACtC,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,yCAAyC;IACzC,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACnC,0FAA0F;IAC1F,YAAY,EAAE,qBAAqB,CAAC;IACpC,yIAAyI;IACzI,iBAAiB,EAAE,OAAO,CAAC;IAC3B,yCAAyC;IACzC,OAAO,EAAE,aAAa,EAAE,CAAC;CAC5B;AA4OD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,aAAa,GAAG,iBAAiB,CAW9E;AAQD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,GAAG,mBAAmB,CAwB5H"}

package/dist/lib/components/realtime/interactive-component/component-contract.js

@@ -0,0 +1,292 @@
+/**
+ * @fileoverview Derives what an agent can do with a component from the component's own specification.
+ *
+ * A component artifact already says what it accepts and emits: its `properties` (inputs), its `events`, and its
+ * `methods` (standard methods it supports plus custom ones with typed parameters). This module turns that into the
+ * channel contract's vocabulary, so an agent can operate a component nobody wrote channel code for:
+ *
+ * | spec | contract |
+ * |---|---|
+ * | `methods.customMethods[]` | a verb per method, parameters schema from the declared parameter types |
+ * | `methods.standardMethodsSupported` | `refresh`, `print`, `validate`, `is_dirty`, `reset`, `scroll_to`, `focus`, and `get_data_state` |
+ * | `methods.standardMethodsSupported.getCurrentDataState` | the instance's `data` in the channel's state (the noun) |
+ * | `events[]` | channel events, payload schema from the event parameters |
+ * | `properties[]` | the schema of the `inputs` accepted when opening it |
+ *
+ * A verb whose result carries what the component holds (`get_data_state`, `validate`, `is_dirty`, and any custom method that
+ * returns something) is marked `ReturnsChannelData: 'state'`, so the agent is refused it when it may not perceive the
+ * component's state (see `RealtimeChannelVerb.ReturnsChannelData`).
+ *
+ * Pure functions over plain data: no component is rendered and nothing is invoked here.
+ *
+ * @module @memberjunction/ng-conversations
+ */
+import { STANDARD_VERBS, BUILTIN_VERBS } from './interactive-component-types';
+/** Verb names that belong to the channel, which a custom method may not take. */
+const RESERVED_VERB_NAMES = new Set([
+    ...Object.values(BUILTIN_VERBS),
+    ...Object.values(STANDARD_VERBS),
+    'open',
+]);
+/** The JSON-schema for a type name as a spec author writes it, or `null` when it cannot be expressed. */
+function schemaForTypeName(typeName) {
+    const type = typeName.trim().toLowerCase().replace(/\s+/g, ' ');
+    if (type === 'string') {
+        return { type: 'string' };
+    }
+    if (type === 'number' || type === 'float' || type === 'double') {
+        return { type: 'number' };
+    }
+    if (type === 'integer' || type === 'int') {
+        return { type: 'integer' };
+    }
+    if (type === 'boolean' || type === 'bool') {
+        return { type: 'boolean' };
+    }
+    if (type === 'date' || type === 'datetime') {
+        return { type: 'string', format: 'date-time' };
+    }
+    if (type === 'array' || type.startsWith('array<') || type.endsWith('[]')) {
+        return { type: 'array' };
+    }
+    if (type === 'object' || type.startsWith('record<') || type.startsWith('{')) {
+        return { type: 'object' };
+    }
+    return type === 'function' ? null : {};
+}
+/** Whether a method parameter is optional, judged from its name, type and description. */
+function isOptionalParameter(parameter) {
+    return (parameter.name.trim().endsWith('?') ||
+        /\bundefined\b/i.test(parameter.type) ||
+        /^\s*optional\b/i.test(parameter.description ?? ''));
+}
+/** The bare parameter name (a trailing `?` marks it optional and is not part of the name). */
+function parameterName(parameter) {
+    return parameter.name.trim().replace(/\?$/, '');
+}
+/** Builds the parameters schema of a custom method; `null` when a required parameter cannot be passed by a model (a function). */
+function buildParametersSchema(method) {
+    const properties = {};
+    const required = [];
+    const names = [];
+    for (const parameter of method.parameters ?? []) {
+        const name = parameterName(parameter);
+        const schema = schemaForTypeName(parameter.type ?? '');
+        const optional = isOptionalParameter(parameter);
+        if (schema === null) {
+            if (!optional) {
+                return { Problem: `parameter "${name}" is a function, which an agent cannot pass` };
+            }
+            continue;
+        }
+        const described = { ...schema, description: parameter.description ?? `${name} (${parameter.type})` };
+        if (Object.keys(schema).length === 0) {
+            described['description'] = `${parameter.description ?? name} (declared type: ${parameter.type})`;
+        }
+        properties[name] = described;
+        names.push(name);
+        if (!optional) {
+            required.push(name);
+        }
+    }
+    const schema = { type: 'object', properties, additionalProperties: false };
+    if (required.length > 0) {
+        schema['required'] = required;
+    }
+    return { Schema: schema, Names: names };
+}
+/** The verb name for a custom method: its own name, unless that is taken by the channel. */
+function customVerbName(method, taken) {
+    let name = method;
+    if (RESERVED_VERB_NAMES.has(name.toLowerCase()) || taken.has(name.toLowerCase())) {
+        name = `custom_${method}`;
+    }
+    taken.add(name.toLowerCase());
+    return name;
+}
+/** Derives the verb for each custom method. */
+function deriveCustomVerbs(spec, taken, skipped) {
+    const verbs = [];
+    for (const method of spec.methods?.customMethods ?? []) {
+        if (typeof method?.name !== 'string' || method.name.trim().length === 0) {
+            skipped.push({ Name: '(unnamed)', Reason: 'a custom method has no name' });
+            continue;
+        }
+        const built = buildParametersSchema(method);
+        if ('Problem' in built) {
+            skipped.push({ Name: method.name, Reason: built.Problem });
+            continue;
+        }
+        const returns = method.returnType && method.returnType !== 'void' ? ` Returns ${method.returnType}.` : '';
+        verbs.push({
+            Verb: {
+                Name: customVerbName(method.name, taken),
+                Description: `${method.description || `Calls the component's ${method.name} method.`}${returns}`,
+                ParametersSchema: built.Schema,
+                InvokableBy: 'both',
+                // Unsure what a method hands back, so a method that returns anything is treated as returning the component's data.
+                ...(returnsData(method) ? { ReturnsChannelData: 'state' } : {}),
+            },
+            Binding: { Kind: 'custom', Method: method.name, ParameterNames: built.Names },
+        });
+    }
+    return verbs;
+}
+/** Return types that carry nothing back. Anything else is treated as a result that carries the component's data. */
+const VOID_RETURN_TYPES = new Set(['', 'void', 'undefined', 'null', 'never', 'promise<void>', 'promise<undefined>']);
+/** Whether a custom method returns something (and so needs `state` exposure to be given to the agent). */
+function returnsData(method) {
+    return !VOID_RETURN_TYPES.has((method.returnType ?? '').trim().toLowerCase());
+}
+/** A verb with no parameters. */
+function noParameters() {
+    return { type: 'object', properties: {}, additionalProperties: false };
+}
+/** The standard verbs, in the order they are described. Each is present only when the spec says the component supports it. */
+function deriveStandardVerbs(spec) {
+    const supported = spec.methods?.standardMethodsSupported ?? {};
+    const standard = (key, description, schema = noParameters(), returnsChannelData) => ({
+        Verb: { Name: STANDARD_VERBS[key], Description: description, ParametersSchema: schema, InvokableBy: 'both', ...(returnsChannelData ? { ReturnsChannelData: returnsChannelData } : {}) },
+        Binding: { Kind: 'standard', Standard: key },
+    });
+    const verbs = [];
+    if (supported.refresh) {
+        verbs.push(standard('Refresh', 'Reloads the component\'s data.'));
+    }
+    if (supported.getCurrentDataState) {
+        verbs.push(standard('GetDataState', 'Reads what the component is showing right now (its data state: tables, rows, filters). Use it when you need detail the state notes do not carry.', noParameters(), 'state'));
+    }
+    if (supported.validate) {
+        verbs.push(standard('Validate', 'Checks whether what the user entered is valid; reports the problems.', noParameters(), 'state'));
+    }
+    if (supported.isDirty) {
+        verbs.push(standard('IsDirty', 'Reports whether the user has unsaved changes in the component.', noParameters(), 'state'));
+    }
+    if (supported.reset) {
+        verbs.push(standard('Reset', 'Discards the user\'s changes and returns the component to its initial state.'));
+    }
+    if (supported.print) {
+        verbs.push(standard('Print', 'Opens the browser\'s print dialog for the component.'));
+    }
+    if (supported.scrollTo) {
+        verbs.push(standard('ScrollTo', 'Scrolls the component to an element (a CSS selector) or position.', {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'A CSS selector of the element to scroll to.' },
+                top: { type: 'number', description: 'Vertical scroll offset in pixels (instead of a target).' },
+                left: { type: 'number', description: 'Horizontal scroll offset in pixels (instead of a target).' },
+            },
+            additionalProperties: false,
+        }));
+    }
+    if (supported.focus) {
+        verbs.push(standard('Focus', 'Moves keyboard focus to an element inside the component.', {
+            type: 'object',
+            properties: { target: { type: 'string', description: 'A CSS selector of the element to focus (default: the component\'s first focusable element).' } },
+            additionalProperties: false,
+        }));
+    }
+    return verbs;
+}
+/** The event specs from the component's declared events. */
+function deriveEvents(spec) {
+    const events = [];
+    for (const event of spec.events ?? []) {
+        if (typeof event?.name !== 'string' || event.name.length === 0) {
+            continue;
+        }
+        const properties = {};
+        for (const parameter of event.parameters ?? []) {
+            const schema = schemaForTypeName(parameter.type ?? 'any') ?? {};
+            properties[parameter.name] = { ...schema, description: parameter.description };
+        }
+        events.push({
+            Name: event.name,
+            Description: event.description,
+            PayloadSchema: { type: 'object', properties },
+        });
+    }
+    return events;
+}
+/** The schema of the opening `inputs`, from the spec's `properties`. Function-typed properties (callbacks) cannot be supplied by a model and are left out. */
+function deriveInputsSchema(spec) {
+    const properties = {};
+    const required = [];
+    for (const property of spec.properties ?? []) {
+        const schema = schemaForTypeName(property.type ?? 'any');
+        if (schema === null || typeof property.name !== 'string' || property.name.length === 0) {
+            continue;
+        }
+        const described = { ...schema, description: property.description };
+        if (Array.isArray(property.possibleValues) && property.possibleValues.length > 0 && schema['type'] === 'string') {
+            described['enum'] = property.possibleValues;
+        }
+        properties[property.name] = described;
+        if (property.required) {
+            required.push(property.name);
+        }
+    }
+    const schema = { type: 'object', properties };
+    if (required.length > 0) {
+        schema['required'] = required;
+    }
+    return schema;
+}
+/**
+ * Derives the full contract of one component from its spec.
+ *
+ * @param spec The component's specification.
+ */
+export function DeriveComponentContract(spec) {
+    const skipped = [];
+    const standardVerbs = deriveStandardVerbs(spec);
+    const taken = new Set(standardVerbs.map((v) => v.Verb.Name.toLowerCase()));
+    return {
+        Verbs: [...standardVerbs, ...deriveCustomVerbs(spec, taken, skipped)],
+        Events: deriveEvents(spec),
+        InputsSchema: deriveInputsSchema(spec),
+        SupportsDataState: spec.methods?.standardMethodsSupported?.getCurrentDataState === true,
+        Skipped: skipped,
+    };
+}
+/** Whether a verb schema is the permissive one a merge produces. */
+function schemaProperties(verb) {
+    const properties = verb.ParametersSchema['properties'];
+    return properties !== null && typeof properties === 'object' && !Array.isArray(properties) ? properties : {};
+}
+/**
+ * Merges the same verb offered by several open components into the single verb the channel declares.
+ *
+ * Verbs from different components can share a name with different parameters (two components that both have
+ * `setFilter`). The channel declares one verb per name; its schema is the UNION of the parameters with nothing
+ * required, so a call that suits any of them passes the dispatcher, and the exact per-component check
+ * (against that component's own schema) happens when the verb runs. The description lists each component's signature.
+ *
+ * @param offers Each component's verb of this name, with the component's display name.
+ */
+export function MergeVerbOffers(offers) {
+    if (offers.length === 1) {
+        return { ...offers[0].Verb };
+    }
+    const properties = {};
+    for (const offer of offers) {
+        for (const [name, schema] of Object.entries(schemaProperties(offer.Verb))) {
+            if (!(name in properties)) {
+                properties[name] = schema;
+            }
+        }
+    }
+    // The dispatcher checks the merged verb, so it may refuse only what EVERY component would refuse; the exact check against
+    // the addressed component happens when the verb runs.
+    const levels = offers.map((offer) => offer.Verb.ReturnsChannelData);
+    const returnsChannelData = levels.every((level) => level !== undefined) ? (levels.includes('state') ? 'state' : 'pixels') : undefined;
+    const signatures = offers.map((offer) => `${offer.Component}: ${Object.keys(schemaProperties(offer.Verb)).join(', ') || '(no parameters)'}`);
+    return {
+        Name: offers[0].Verb.Name,
+        Description: `${offers[0].Verb.Description} Several open components have this action; pass the instance you mean. Parameters per component — ${signatures.join('; ')}.`,
+        ParametersSchema: { type: 'object', properties, additionalProperties: false },
+        InvokableBy: 'both',
+        ...(returnsChannelData ? { ReturnsChannelData: returnsChannelData } : {}),
+    };
+}
+//# sourceMappingURL=component-contract.js.map

package/dist/lib/components/realtime/interactive-component/component-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-contract.js","sourceRoot":"","sources":["../../../../../src/lib/components/realtime/interactive-component/component-contract.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @fileoverview Derives what an agent can do with a component from the component's own specification.\n *\n * A component artifact already says what it accepts and emits: its `properties` (inputs), its `events`, and its\n * `methods` (standard methods it supports plus custom ones with typed parameters). This module turns that into the\n * channel contract's vocabulary, so an agent can operate a component nobody wrote channel code for:\n *\n * | spec | contract |\n * |---|---|\n * | `methods.customMethods[]` | a verb per method, parameters schema from the declared parameter types |\n * | `methods.standardMethodsSupported` | `refresh`, `print`, `validate`, `is_dirty`, `reset`, `scroll_to`, `focus`, and `get_data_state` |\n * | `methods.standardMethodsSupported.getCurrentDataState` | the instance's `data` in the channel's state (the noun) |\n * | `events[]` | channel events, payload schema from the event parameters |\n * | `properties[]` | the schema of the `inputs` accepted when opening it |\n *\n * A verb whose result carries what the component holds (`get_data_state`, `validate`, `is_dirty`, and any custom method that\n * returns something) is marked `ReturnsChannelData: 'state'`, so the agent is refused it when it may not perceive the\n * component's state (see `RealtimeChannelVerb.ReturnsChannelData`).\n *\n * Pure functions over plain data: no component is rendered and nothing is invoked here.\n *\n * @module @memberjunction/ng-conversations\n */\n\nimport type { JSONObject } from '@memberjunction/ai';\nimport type { RealtimeChannelEventSpec, RealtimeChannelSchema, RealtimeChannelVerb } from '@memberjunction/ai-core-plus';\nimport type { ComponentSpec, CustomComponentMethod } from '@memberjunction/interactive-component-types';\nimport { STANDARD_VERBS, BUILTIN_VERBS } from './interactive-component-types';\n\n/** How a verb reaches the component. */\nexport type VerbBinding =\n    | { Kind: 'standard'; Standard: keyof typeof STANDARD_VERBS }\n    | { Kind: 'custom'; Method: string; ParameterNames: string[] };\n\n/** One verb derived from a spec, with how to run it. */\nexport interface DerivedVerb {\n    /** The verb as the agent sees it. */\n    Verb: RealtimeChannelVerb;\n    /** How the channel runs it. */\n    Binding: VerbBinding;\n}\n\n/** A method the contract could not expose, and why (kept so a spec problem is visible rather than silently dropped). */\nexport interface SkippedMethod {\n    /** The method's name. */\n    Name: string;\n    /** Why it was not exposed. */\n    Reason: string;\n}\n\n/** Everything an agent can do with one component, derived from its spec. */\nexport interface ComponentContract {\n    /** The verbs, standard and custom. */\n    Verbs: DerivedVerb[];\n    /** The events the component can emit. */\n    Events: RealtimeChannelEventSpec[];\n    /** The schema of the `inputs` accepted when opening it (from the spec's `properties`). */\n    InputsSchema: RealtimeChannelSchema;\n    /** Whether the component reports a data state (`getCurrentDataState` is supported), i.e. whether the instance has `data` to describe. */\n    SupportsDataState: boolean;\n    /** Methods that could not be exposed. */\n    Skipped: SkippedMethod[];\n}\n\n/** Verb names that belong to the channel, which a custom method may not take. */\nconst RESERVED_VERB_NAMES: ReadonlySet<string> = new Set([\n    ...Object.values(BUILTIN_VERBS),\n    ...Object.values(STANDARD_VERBS),\n    'open',\n]);\n\n/** The JSON-schema for a type name as a spec author writes it, or `null` when it cannot be expressed. */\nfunction schemaForTypeName(typeName: string): JSONObject | null {\n    const type = typeName.trim().toLowerCase().replace(/\\s+/g, ' ');\n    if (type === 'string') {\n        return { type: 'string' };\n    }\n    if (type === 'number' || type === 'float' || type === 'double') {\n        return { type: 'number' };\n    }\n    if (type === 'integer' || type === 'int') {\n        return { type: 'integer' };\n    }\n    if (type === 'boolean' || type === 'bool') {\n        return { type: 'boolean' };\n    }\n    if (type === 'date' || type === 'datetime') {\n        return { type: 'string', format: 'date-time' };\n    }\n    if (type === 'array' || type.startsWith('array<') || type.endsWith('[]')) {\n        return { type: 'array' };\n    }\n    if (type === 'object' || type.startsWith('record<') || type.startsWith('{')) {\n        return { type: 'object' };\n    }\n    return type === 'function' ? null : {};\n}\n\n/** Whether a method parameter is optional, judged from its name, type and description. */\nfunction isOptionalParameter(parameter: { name: string; type: string; description?: string }): boolean {\n    return (\n        parameter.name.trim().endsWith('?') ||\n        /\\bundefined\\b/i.test(parameter.type) ||\n        /^\\s*optional\\b/i.test(parameter.description ?? '')\n    );\n}\n\n/** The bare parameter name (a trailing `?` marks it optional and is not part of the name). */\nfunction parameterName(parameter: { name: string }): string {\n    return parameter.name.trim().replace(/\\?$/, '');\n}\n\n/** Builds the parameters schema of a custom method; `null` when a required parameter cannot be passed by a model (a function). */\nfunction buildParametersSchema(method: CustomComponentMethod): { Schema: RealtimeChannelSchema; Names: string[] } | { Problem: string } {\n    const properties: JSONObject = {};\n    const required: string[] = [];\n    const names: string[] = [];\n    for (const parameter of method.parameters ?? []) {\n        const name = parameterName(parameter);\n        const schema = schemaForTypeName(parameter.type ?? '');\n        const optional = isOptionalParameter(parameter);\n        if (schema === null) {\n            if (!optional) {\n                return { Problem: `parameter \"${name}\" is a function, which an agent cannot pass` };\n            }\n            continue;\n        }\n        const described: JSONObject = { ...schema, description: parameter.description ?? `${name} (${parameter.type})` };\n        if (Object.keys(schema).length === 0) {\n            described['description'] = `${parameter.description ?? name} (declared type: ${parameter.type})`;\n        }\n        properties[name] = described;\n        names.push(name);\n        if (!optional) {\n            required.push(name);\n        }\n    }\n    const schema: RealtimeChannelSchema = { type: 'object', properties, additionalProperties: false };\n    if (required.length > 0) {\n        schema['required'] = required;\n    }\n    return { Schema: schema, Names: names };\n}\n\n/** The verb name for a custom method: its own name, unless that is taken by the channel. */\nfunction customVerbName(method: string, taken: Set<string>): string {\n    let name = method;\n    if (RESERVED_VERB_NAMES.has(name.toLowerCase()) || taken.has(name.toLowerCase())) {\n        name = `custom_${method}`;\n    }\n    taken.add(name.toLowerCase());\n    return name;\n}\n\n/** Derives the verb for each custom method. */\nfunction deriveCustomVerbs(spec: ComponentSpec, taken: Set<string>, skipped: SkippedMethod[]): DerivedVerb[] {\n    const verbs: DerivedVerb[] = [];\n    for (const method of spec.methods?.customMethods ?? []) {\n        if (typeof method?.name !== 'string' || method.name.trim().length === 0) {\n            skipped.push({ Name: '(unnamed)', Reason: 'a custom method has no name' });\n            continue;\n        }\n        const built = buildParametersSchema(method);\n        if ('Problem' in built) {\n            skipped.push({ Name: method.name, Reason: built.Problem });\n            continue;\n        }\n        const returns = method.returnType && method.returnType !== 'void' ? ` Returns ${method.returnType}.` : '';\n        verbs.push({\n            Verb: {\n                Name: customVerbName(method.name, taken),\n                Description: `${method.description || `Calls the component's ${method.name} method.`}${returns}`,\n                ParametersSchema: built.Schema,\n                InvokableBy: 'both',\n                // Unsure what a method hands back, so a method that returns anything is treated as returning the component's data.\n                ...(returnsData(method) ? { ReturnsChannelData: 'state' as const } : {}),\n            },\n            Binding: { Kind: 'custom', Method: method.name, ParameterNames: built.Names },\n        });\n    }\n    return verbs;\n}\n\n/** Return types that carry nothing back. Anything else is treated as a result that carries the component's data. */\nconst VOID_RETURN_TYPES: ReadonlySet<string> = new Set(['', 'void', 'undefined', 'null', 'never', 'promise<void>', 'promise<undefined>']);\n\n/** Whether a custom method returns something (and so needs `state` exposure to be given to the agent). */\nfunction returnsData(method: CustomComponentMethod): boolean {\n    return !VOID_RETURN_TYPES.has((method.returnType ?? '').trim().toLowerCase());\n}\n\n/** A verb with no parameters. */\nfunction noParameters(): RealtimeChannelSchema {\n    return { type: 'object', properties: {}, additionalProperties: false };\n}\n\n/** The standard verbs, in the order they are described. Each is present only when the spec says the component supports it. */\nfunction deriveStandardVerbs(spec: ComponentSpec): DerivedVerb[] {\n    const supported = spec.methods?.standardMethodsSupported ?? {};\n    const standard = (\n        key: keyof typeof STANDARD_VERBS,\n        description: string,\n        schema: RealtimeChannelSchema = noParameters(),\n        returnsChannelData?: 'state'\n    ): DerivedVerb => ({\n        Verb: { Name: STANDARD_VERBS[key], Description: description, ParametersSchema: schema, InvokableBy: 'both', ...(returnsChannelData ? { ReturnsChannelData: returnsChannelData } : {}) },\n        Binding: { Kind: 'standard', Standard: key },\n    });\n    const verbs: DerivedVerb[] = [];\n    if (supported.refresh) {\n        verbs.push(standard('Refresh', 'Reloads the component\\'s data.'));\n    }\n    if (supported.getCurrentDataState) {\n        verbs.push(standard('GetDataState', 'Reads what the component is showing right now (its data state: tables, rows, filters). Use it when you need detail the state notes do not carry.', noParameters(), 'state'));\n    }\n    if (supported.validate) {\n        verbs.push(standard('Validate', 'Checks whether what the user entered is valid; reports the problems.', noParameters(), 'state'));\n    }\n    if (supported.isDirty) {\n        verbs.push(standard('IsDirty', 'Reports whether the user has unsaved changes in the component.', noParameters(), 'state'));\n    }\n    if (supported.reset) {\n        verbs.push(standard('Reset', 'Discards the user\\'s changes and returns the component to its initial state.'));\n    }\n    if (supported.print) {\n        verbs.push(standard('Print', 'Opens the browser\\'s print dialog for the component.'));\n    }\n    if (supported.scrollTo) {\n        verbs.push(\n            standard('ScrollTo', 'Scrolls the component to an element (a CSS selector) or position.', {\n                type: 'object',\n                properties: {\n                    target: { type: 'string', description: 'A CSS selector of the element to scroll to.' },\n                    top: { type: 'number', description: 'Vertical scroll offset in pixels (instead of a target).' },\n                    left: { type: 'number', description: 'Horizontal scroll offset in pixels (instead of a target).' },\n                },\n                additionalProperties: false,\n            })\n        );\n    }\n    if (supported.focus) {\n        verbs.push(\n            standard('Focus', 'Moves keyboard focus to an element inside the component.', {\n                type: 'object',\n                properties: { target: { type: 'string', description: 'A CSS selector of the element to focus (default: the component\\'s first focusable element).' } },\n                additionalProperties: false,\n            })\n        );\n    }\n    return verbs;\n}\n\n/** The event specs from the component's declared events. */\nfunction deriveEvents(spec: ComponentSpec): RealtimeChannelEventSpec[] {\n    const events: RealtimeChannelEventSpec[] = [];\n    for (const event of spec.events ?? []) {\n        if (typeof event?.name !== 'string' || event.name.length === 0) {\n            continue;\n        }\n        const properties: JSONObject = {};\n        for (const parameter of event.parameters ?? []) {\n            const schema = schemaForTypeName(parameter.type ?? 'any') ?? {};\n            properties[parameter.name] = { ...schema, description: parameter.description };\n        }\n        events.push({\n            Name: event.name,\n            Description: event.description,\n            PayloadSchema: { type: 'object', properties },\n        });\n    }\n    return events;\n}\n\n/** The schema of the opening `inputs`, from the spec's `properties`. Function-typed properties (callbacks) cannot be supplied by a model and are left out. */\nfunction deriveInputsSchema(spec: ComponentSpec): RealtimeChannelSchema {\n    const properties: JSONObject = {};\n    const required: string[] = [];\n    for (const property of spec.properties ?? []) {\n        const schema = schemaForTypeName(property.type ?? 'any');\n        if (schema === null || typeof property.name !== 'string' || property.name.length === 0) {\n            continue;\n        }\n        const described: JSONObject = { ...schema, description: property.description };\n        if (Array.isArray(property.possibleValues) && property.possibleValues.length > 0 && schema['type'] === 'string') {\n            described['enum'] = property.possibleValues;\n        }\n        properties[property.name] = described;\n        if (property.required) {\n            required.push(property.name);\n        }\n    }\n    const schema: RealtimeChannelSchema = { type: 'object', properties };\n    if (required.length > 0) {\n        schema['required'] = required;\n    }\n    return schema;\n}\n\n/**\n * Derives the full contract of one component from its spec.\n *\n * @param spec The component's specification.\n */\nexport function DeriveComponentContract(spec: ComponentSpec): ComponentContract {\n    const skipped: SkippedMethod[] = [];\n    const standardVerbs = deriveStandardVerbs(spec);\n    const taken = new Set(standardVerbs.map((v) => v.Verb.Name.toLowerCase()));\n    return {\n        Verbs: [...standardVerbs, ...deriveCustomVerbs(spec, taken, skipped)],\n        Events: deriveEvents(spec),\n        InputsSchema: deriveInputsSchema(spec),\n        SupportsDataState: spec.methods?.standardMethodsSupported?.getCurrentDataState === true,\n        Skipped: skipped,\n    };\n}\n\n/** Whether a verb schema is the permissive one a merge produces. */\nfunction schemaProperties(verb: RealtimeChannelVerb): JSONObject {\n    const properties = verb.ParametersSchema['properties'];\n    return properties !== null && typeof properties === 'object' && !Array.isArray(properties) ? (properties as JSONObject) : {};\n}\n\n/**\n * Merges the same verb offered by several open components into the single verb the channel declares.\n *\n * Verbs from different components can share a name with different parameters (two components that both have\n * `setFilter`). The channel declares one verb per name; its schema is the UNION of the parameters with nothing\n * required, so a call that suits any of them passes the dispatcher, and the exact per-component check\n * (against that component's own schema) happens when the verb runs. The description lists each component's signature.\n *\n * @param offers Each component's verb of this name, with the component's display name.\n */\nexport function MergeVerbOffers(offers: ReadonlyArray<{ Component: string; Verb: RealtimeChannelVerb }>): RealtimeChannelVerb {\n    if (offers.length === 1) {\n        return { ...offers[0].Verb };\n    }\n    const properties: JSONObject = {};\n    for (const offer of offers) {\n        for (const [name, schema] of Object.entries(schemaProperties(offer.Verb))) {\n            if (!(name in properties)) {\n                properties[name] = schema;\n            }\n        }\n    }\n    // The dispatcher checks the merged verb, so it may refuse only what EVERY component would refuse; the exact check against\n    // the addressed component happens when the verb runs.\n    const levels = offers.map((offer) => offer.Verb.ReturnsChannelData);\n    const returnsChannelData = levels.every((level) => level !== undefined) ? (levels.includes('state') ? 'state' : 'pixels') : undefined;\n    const signatures = offers.map((offer) => `${offer.Component}: ${Object.keys(schemaProperties(offer.Verb)).join(', ') || '(no parameters)'}`);\n    return {\n        Name: offers[0].Verb.Name,\n        Description: `${offers[0].Verb.Description} Several open components have this action; pass the instance you mean. Parameters per component — ${signatures.join('; ')}.`,\n        ParametersSchema: { type: 'object', properties, additionalProperties: false },\n        InvokableBy: 'both',\n        ...(returnsChannelData ? { ReturnsChannelData: returnsChannelData } : {}),\n    };\n}\n"]}

package/dist/lib/components/realtime/interactive-component/component-data-state.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Bounds a component's data state before it is described to the model.
+ *
+ * A component's `getCurrentDataState()` can hold thousands of rows. A perception note that carried them all
+ * would flood the model's context and, when the component shows private data, leak far more than the model
+ * needs to answer "what is the user looking at". This turns an arbitrary data state into a small JSON summary:
+ * the per-table row count and columns always, and only the first `MaxRows` rows; long strings are clipped;
+ * the whole thing is held under a character budget.
+ *
+ * The input is whatever the component returned, so it is treated as untrusted: it may be cyclic, hold functions,
+ * dates or class instances. The output is always plain JSON.
+ *
+ * @module @memberjunction/ng-conversations
+ */
+import type { JSONObject, JSONValue } from '@memberjunction/ai';
+/** Limits applied to a data state. */
+export interface DataStateLimits {
+    /** The most rows kept per table. */
+    MaxRows: number;
+    /** The most characters of the serialized summary; beyond it rows are dropped until it fits. */
+    MaxChars: number;
+}
+/**
+ * Converts one arbitrary value into JSON, bounded in depth, breadth and string length.
+ * Functions and symbols become a marker, dates their ISO string, cycles a marker.
+ */
+export declare function ToBoundedJson(value: unknown, depth?: number, seen?: WeakSet<object>): JSONValue;
+/**
+ * Summarizes a component's data state for the model.
+ *
+ * The result is plain JSON no larger than `limits.MaxChars`: when the first attempt is over budget the per-table
+ * row cap is halved until it fits, down to zero rows (counts and columns only).
+ *
+ * @param state The value `getCurrentDataState()` returned (a `DataSnapshot` or anything else), or nothing.
+ * @param limits The row and size caps.
+ * @returns The summary, or `null` when the component has no data state.
+ */
+export declare function SummarizeDataState(state: object | null | undefined, limits: DataStateLimits): JSONObject | null;
+//# sourceMappingURL=component-data-state.d.ts.map

package/dist/lib/components/realtime/interactive-component/component-data-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-data-state.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/realtime/interactive-component/component-data-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEhE,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC5B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,CAAC;CACpB;AAmBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,GAAE,MAAU,EAAE,IAAI,GAAE,OAAO,CAAC,MAAM,CAAiB,GAAG,SAAS,CAoBjH;AA6ED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,UAAU,GAAG,IAAI,CAc/G"}

package/dist/lib/components/realtime/interactive-component/component-data-state.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Bounds a component's data state before it is described to the model.
+ *
+ * A component's `getCurrentDataState()` can hold thousands of rows. A perception note that carried them all
+ * would flood the model's context and, when the component shows private data, leak far more than the model
+ * needs to answer "what is the user looking at". This turns an arbitrary data state into a small JSON summary:
+ * the per-table row count and columns always, and only the first `MaxRows` rows; long strings are clipped;
+ * the whole thing is held under a character budget.
+ *
+ * The input is whatever the component returned, so it is treated as untrusted: it may be cyclic, hold functions,
+ * dates or class instances. The output is always plain JSON.
+ *
+ * @module @memberjunction/ng-conversations
+ */
+/** The deepest nesting kept; deeper values are replaced by a marker. */
+const MAX_DEPTH = 5;
+/** The longest string kept before it is clipped. */
+const MAX_STRING_CHARS = 200;
+/** The most keys kept per object or items per non-table array. */
+const MAX_BREADTH = 30;
+/** The most columns listed per table. */
+const MAX_COLUMNS = 40;
+/** Marker for a value the summary could not or would not carry. */
+const OMITTED = '[omitted]';
+/** True for a non-null object that is not an array. */
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Converts one arbitrary value into JSON, bounded in depth, breadth and string length.
+ * Functions and symbols become a marker, dates their ISO string, cycles a marker.
+ */
+export function ToBoundedJson(value, depth = 0, seen = new WeakSet()) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    switch (typeof value) {
+        case 'string':
+            return value.length > MAX_STRING_CHARS ? `${value.slice(0, MAX_STRING_CHARS)}… (${value.length} chars)` : value;
+        case 'number':
+            return Number.isFinite(value) ? value : null;
+        case 'boolean':
+            return value;
+        case 'bigint':
+            return value.toString();
+        case 'function':
+        case 'symbol':
+            return OMITTED;
+        default:
+            break;
+    }
+    return objectToBoundedJson(value, depth, seen);
+}
+/** The object half of {@link ToBoundedJson}. */
+function objectToBoundedJson(value, depth, seen) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value.toISOString();
+    }
+    if (seen.has(value)) {
+        return '[circular]';
+    }
+    if (depth >= MAX_DEPTH) {
+        return '[too deep]';
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const items = value.slice(0, MAX_BREADTH).map((item) => ToBoundedJson(item, depth + 1, seen));
+            return value.length > MAX_BREADTH ? [...items, `… ${value.length - MAX_BREADTH} more`] : items;
+        }
+        const out = {};
+        for (const key of Object.keys(value).slice(0, MAX_BREADTH)) {
+            // Component state is untrusted; never copy a key that would reach Object.prototype.
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+                continue;
+            }
+            out[key] = ToBoundedJson(value[key], depth + 1, seen);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** Summarizes one table-shaped entry (`{ name, columns, rows }`). */
+function summarizeTable(table, index, maxRows) {
+    if (!isRecord(table)) {
+        return { name: `table ${index + 1}`, rowCount: 0 };
+    }
+    const rows = Array.isArray(table['rows']) ? table['rows'] : [];
+    const columns = Array.isArray(table['columns']) ? table['columns'] : [];
+    const columnNames = columns
+        .map((column) => (typeof column === 'string' ? column : isRecord(column) && typeof column['name'] === 'string' ? column['name'] : null))
+        .filter((name) => name !== null)
+        .slice(0, MAX_COLUMNS);
+    const summary = {
+        name: typeof table['name'] === 'string' ? table['name'] : `table ${index + 1}`,
+        rowCount: rows.length,
+        columns: columnNames,
+        rows: rows.slice(0, maxRows).map((row) => ToBoundedJson(row, 1)),
+    };
+    if (rows.length > maxRows) {
+        summary['rowsOmitted'] = rows.length - maxRows;
+    }
+    return summary;
+}
+/** Builds the summary with at most `maxRows` rows per table. */
+function buildSummary(state, maxRows) {
+    const summary = {};
+    for (const key of ['title', 'activeTab', 'searchText', 'interpretation']) {
+        const value = state[key];
+        if (typeof value === 'string' && value.length > 0) {
+            summary[key] = ToBoundedJson(value);
+        }
+    }
+    if (Array.isArray(state['drillPath']) && state['drillPath'].length > 0) {
+        summary['drillPath'] = ToBoundedJson(state['drillPath']);
+    }
+    if (Array.isArray(state['tables'])) {
+        summary['tables'] = state['tables'].slice(0, MAX_BREADTH).map((table, i) => summarizeTable(table, i, maxRows));
+    }
+    if (isRecord(state['custom']) && Object.keys(state['custom']).length > 0) {
+        summary['custom'] = ToBoundedJson(state['custom']);
+    }
+    return summary;
+}
+/**
+ * Summarizes a component's data state for the model.
+ *
+ * The result is plain JSON no larger than `limits.MaxChars`: when the first attempt is over budget the per-table
+ * row cap is halved until it fits, down to zero rows (counts and columns only).
+ *
+ * @param state The value `getCurrentDataState()` returned (a `DataSnapshot` or anything else), or nothing.
+ * @param limits The row and size caps.
+ * @returns The summary, or `null` when the component has no data state.
+ */
+export function SummarizeDataState(state, limits) {
+    if (!isRecord(state)) {
+        return null;
+    }
+    let rows = Math.max(0, Math.floor(limits.MaxRows));
+    let summary = buildSummary(state, rows);
+    while (rows > 0 && JSON.stringify(summary).length > limits.MaxChars) {
+        rows = Math.floor(rows / 2);
+        summary = buildSummary(state, rows);
+    }
+    if (JSON.stringify(summary).length > limits.MaxChars) {
+        return { truncated: true, note: `The data state is larger than ${limits.MaxChars} characters; ask for specifics.` };
+    }
+    return summary;
+}
+//# sourceMappingURL=component-data-state.js.map