@hotmeshio/long-tail 0.19.1 → 0.21.0

package/build/shared/form-validation/index.d.ts

@@ -20,3 +20,5 @@ export * from './ctx-path';
 export * from './field-validator';
 export * from './validate-resolver-payload';
 export * from './invoke-context';
+export * from './display-only-widgets';
+export * from './x-lt-invoke';

package/build/shared/form-validation/index.js

@@ -36,3 +36,5 @@ __exportStar(require("./ctx-path"), exports);
 __exportStar(require("./field-validator"), exports);
 __exportStar(require("./validate-resolver-payload"), exports);
 __exportStar(require("./invoke-context"), exports);
+__exportStar(require("./display-only-widgets"), exports);
+__exportStar(require("./x-lt-invoke"), exports);

package/build/shared/form-validation/invoke-context.d.ts

@@ -1,7 +1,8 @@
 import type { ResolverValidationContext } from './validate-resolver-payload';
 /**
  * The context an invoke form validates and renders against. The pass itself
- * supplies the live values under `input` and `resolver`; the envelope
- * metadata is the only other domain an invoke form can reference.
+ * supplies the live values under `input` and `resolver`; `metadata` is the
+ * envelope metadata and `lookup` holds resolved versioned knowledge editions
+ * keyed by `as ?? key`. The lookup domain is present only when supplied.
  */
-export declare function buildInvokeFormContext(metadata: Record<string, unknown> | null | undefined): ResolverValidationContext;
+export declare function buildInvokeFormContext(metadata: Record<string, unknown> | null | undefined, lookup?: Record<string, unknown> | null): ResolverValidationContext;

package/build/shared/form-validation/invoke-context.js

@@ -3,9 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildInvokeFormContext = buildInvokeFormContext;
 /**
  * The context an invoke form validates and renders against. The pass itself
- * supplies the live values under `input` and `resolver`; the envelope
- * metadata is the only other domain an invoke form can reference.
+ * supplies the live values under `input` and `resolver`; `metadata` is the
+ * envelope metadata and `lookup` holds resolved versioned knowledge editions
+ * keyed by `as ?? key`. The lookup domain is present only when supplied.
  */
-function buildInvokeFormContext(metadata) {
-    return { metadata: metadata ?? {} };
+function buildInvokeFormContext(metadata, lookup) {
+    return { metadata: metadata ?? {}, ...(lookup ? { lookup } : {}) };
 }

package/build/shared/form-validation/x-lt-bind.d.ts

@@ -1,16 +1,3 @@
-/**
- * x-lt-bind — maps the escalation FORM (flat field values the user edits) to and
- * from the PAYLOAD (the nested JSON the workflow consumes). A form_schema property
- * may declare `x-lt-bind: "a.b[0].c"`, the path its value occupies in the payload;
- * a property with no bind sits at its own name at the root (1:1). This module is
- * isomorphic — the dashboard renders forms with it, and the API layer inverts a
- * submitted payload through it to validate against the form contract. One
- * implementation, both sides.
- *
- *   mapPayloadToForm  — payload → flat form values, to PREFILL/display the form
- *                       (server-side: to validate a submitted payload)
- *   mapFormToPayload  — flat form values → payload, the shape submitted/stored
- */
 type PathSeg = {
     key: string;
 } | {
@@ -27,7 +14,8 @@ export declare function bindPathFor(propName: string, propDef: Record<string, an
 /**
  * Assemble the payload from the form's flat values. A field absent from
  * `formValues` is omitted (so clearing/deleting a field drops it from the
- * payload). Unknown keys not declared in the schema are dropped. With no schema
+ * payload). Unknown keys not declared in the schema are dropped, and so are
+ * display-only widget fields, which carry no answer. With no schema
  * properties, values pass through unchanged.
  */
 export declare function mapFormToPayload(formValues: Record<string, any>, formSchema: Record<string, any> | null | undefined): Record<string, any>;

package/build/shared/form-validation/x-lt-bind.js

@@ -1,4 +1,11 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePath = parsePath;
+exports.setDeep = setDeep;
+exports.getDeep = getDeep;
+exports.bindPathFor = bindPathFor;
+exports.mapFormToPayload = mapFormToPayload;
+exports.mapPayloadToForm = mapPayloadToForm;
 /**
  * x-lt-bind — maps the escalation FORM (flat field values the user edits) to and
  * from the PAYLOAD (the nested JSON the workflow consumes). A form_schema property
@@ -12,13 +19,7 @@
  *                       (server-side: to validate a submitted payload)
  *   mapFormToPayload  — flat form values → payload, the shape submitted/stored
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parsePath = parsePath;
-exports.setDeep = setDeep;
-exports.getDeep = getDeep;
-exports.bindPathFor = bindPathFor;
-exports.mapFormToPayload = mapFormToPayload;
-exports.mapPayloadToForm = mapPayloadToForm;
+const display_only_widgets_1 = require("./display-only-widgets");
 const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 /** Parse a bind path — dot keys with optional `[n]` indices. Rejects pollution keys. */
 function parsePath(path) {
@@ -75,7 +76,8 @@ function bindPathFor(propName, propDef) {
 /**
  * Assemble the payload from the form's flat values. A field absent from
  * `formValues` is omitted (so clearing/deleting a field drops it from the
- * payload). Unknown keys not declared in the schema are dropped. With no schema
+ * payload). Unknown keys not declared in the schema are dropped, and so are
+ * display-only widget fields, which carry no answer. With no schema
  * properties, values pass through unchanged.
  */
 function mapFormToPayload(formValues, formSchema) {
@@ -86,6 +88,8 @@ function mapFormToPayload(formValues, formSchema) {
     for (const [name, def] of Object.entries(props)) {
         if (!(name in formValues))
             continue;
+        if ((0, display_only_widgets_1.isDisplayOnlyField)(def))
+            continue;
         setDeep(payload, bindPathFor(name, def), formValues[name]);
     }
     return payload;

package/build/shared/form-validation/x-lt-invoke.d.ts

@@ -0,0 +1,38 @@
+export declare const X_LT_INVOKE = "x-lt-invoke";
+export declare const INVOKE_WIDGET: "invoke";
+export declare const INVOKE_VARIANTS: {
+    readonly LINK: "link";
+    readonly BUTTON: "button";
+};
+export type InvokeVariant = (typeof INVOKE_VARIANTS)[keyof typeof INVOKE_VARIANTS];
+export interface InvokeConfig {
+    /** The workflow_type to start. */
+    workflow: string;
+    /** Nested invoke `data` template; leaves interpolate against the context. */
+    data: Record<string, unknown>;
+    /** Extra run metadata template, merged over the workflow's declared metadata. */
+    metadata: Record<string, unknown>;
+    /** Open the workflow's input form prefilled instead of posting directly. */
+    modal: boolean;
+    /** Direct mode only: a prompt to confirm before posting; tokens interpolate. */
+    confirm: string | null;
+    variant: InvokeVariant;
+    /** Lead the label with the workflow's registered icon. */
+    icon: boolean;
+}
+export interface InvokePayload {
+    data: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+}
+type Ctx = Record<string, unknown> | null | undefined;
+/** The field's invoke declaration, or null when it names no workflow. */
+export declare function readInvokeConfig(fieldSchema: Record<string, unknown> | null | undefined): InvokeConfig | null;
+/**
+ * Resolve one template value against the context, keeping the type of a
+ * whole-token leaf. Returns undefined for a token with no value so the
+ * caller omits the key.
+ */
+export declare function interpolateInvokeValue(value: unknown, ctx: Ctx): unknown;
+/** The invoke payload for one context: `data` and `metadata` fully resolved. */
+export declare function resolveInvokePayload(config: InvokeConfig, ctx: Ctx): InvokePayload;
+export {};

package/build/shared/form-validation/x-lt-invoke.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INVOKE_VARIANTS = exports.INVOKE_WIDGET = exports.X_LT_INVOKE = void 0;
+exports.readInvokeConfig = readInvokeConfig;
+exports.interpolateInvokeValue = interpolateInvokeValue;
+exports.resolveInvokePayload = resolveInvokePayload;
+/**
+ * x-lt-invoke: start a workflow from inside a form. A display-only field
+ * declares the target workflow and how the form's context maps into the
+ * invoke payload:
+ *
+ *   "x-lt-widget": "invoke",
+ *   "x-lt-invoke": {
+ *     "workflow": "printPamphlet",
+ *     "data": { "order": { "id": "{{metadata.orderId}}" }, "copies": 1 },
+ *     "metadata": { "escalationId": "{{escalation.id}}" },
+ *     "modal": true,
+ *     "confirm": "Print a pamphlet for {{metadata.orderId}}?",
+ *     "variant": "link",
+ *     "icon": true
+ *   }
+ *
+ * `data` is the nested payload the invoke API receives. In direct mode it is
+ * posted as resolved; in modal mode it prefills the workflow's own input form
+ * through the x-lt-bind inversion. One declaration serves both.
+ *
+ * Interpolation keeps types: a leaf that is exactly one `{{domain.path}}`
+ * token becomes the raw context value (a number stays a number); a leaf that
+ * mixes text and tokens becomes a string; a token with no value drops its key
+ * so the target's own defaults apply. Objects and arrays recurse; every other
+ * leaf passes through unchanged.
+ */
+const display_only_widgets_1 = require("./display-only-widgets");
+const ctx_path_1 = require("./ctx-path");
+exports.X_LT_INVOKE = 'x-lt-invoke';
+exports.INVOKE_WIDGET = display_only_widgets_1.DISPLAY_ONLY_WIDGET_NAMES.INVOKE;
+exports.INVOKE_VARIANTS = {
+    LINK: 'link',
+    BUTTON: 'button',
+};
+const WHOLE_TOKEN_PATTERN = /^\{\{\s*([^{}]+?)\s*\}\}$/;
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isVariant(value) {
+    return value === exports.INVOKE_VARIANTS.LINK || value === exports.INVOKE_VARIANTS.BUTTON;
+}
+/** The field's invoke declaration, or null when it names no workflow. */
+function readInvokeConfig(fieldSchema) {
+    const raw = fieldSchema?.[exports.X_LT_INVOKE];
+    if (!isPlainObject(raw))
+        return null;
+    const workflow = raw.workflow;
+    if (typeof workflow !== 'string' || workflow.trim().length === 0)
+        return null;
+    const confirm = raw.confirm;
+    return {
+        workflow: workflow.trim(),
+        data: isPlainObject(raw.data) ? raw.data : {},
+        metadata: isPlainObject(raw.metadata) ? raw.metadata : {},
+        modal: raw.modal === true,
+        confirm: typeof confirm === 'string' && confirm.trim().length > 0 ? confirm : null,
+        variant: isVariant(raw.variant) ? raw.variant : exports.INVOKE_VARIANTS.LINK,
+        icon: raw.icon !== false,
+    };
+}
+/**
+ * Resolve one template value against the context, keeping the type of a
+ * whole-token leaf. Returns undefined for a token with no value so the
+ * caller omits the key.
+ */
+function interpolateInvokeValue(value, ctx) {
+    if (typeof value === 'string') {
+        const whole = WHOLE_TOKEN_PATTERN.exec(value);
+        if (whole) {
+            const resolved = (0, ctx_path_1.resolveCtxPath)(whole[1], ctx ?? undefined);
+            return resolved === null ? undefined : resolved;
+        }
+        if ((0, ctx_path_1.hasInterpolation)(value))
+            return (0, ctx_path_1.interpolatePath)(value, ctx ?? undefined) ?? undefined;
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => interpolateInvokeValue(v, ctx)).filter((v) => v !== undefined);
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            const resolved = interpolateInvokeValue(v, ctx);
+            if (resolved !== undefined)
+                out[key] = resolved;
+        }
+        return out;
+    }
+    return value;
+}
+/** The invoke payload for one context: `data` and `metadata` fully resolved. */
+function resolveInvokePayload(config, ctx) {
+    return {
+        data: interpolateInvokeValue(config.data, ctx),
+        metadata: interpolateInvokeValue(config.metadata, ctx),
+    };
+}

package/build/shared/form-validation/x-lt-options.d.ts

@@ -1,12 +1,12 @@
 export declare const X_LT_OPTIONS = "x-lt-options";
-export type OptionValue = string | number;
+export type OptionValue = string | number | boolean;
 /** One resolved option: the payload value and the rendered label. */
 export interface ResolvedOption {
     value: OptionValue;
     label: string;
 }
 /**
- * The field's effective option list: the static `enum` when present, else the
- * entries at the token's `"domain.path"`.
+ * The field's effective option list: the static `enum` when present, else an
+ * inline literal list, else the entries at the token's `"domain.path"`.
  */
 export declare function resolveFieldOptions(fieldSchema: Record<string, unknown> | null | undefined, ctx: Record<string, unknown> | undefined): ResolvedOption[] | undefined;

package/build/shared/form-validation/x-lt-options.js

@@ -10,7 +10,9 @@ exports.resolveFieldOptions = resolveFieldOptions;
  * offer a different legal set per escalation (e.g. `[1..N]` where N rides the
  * envelope, or a versioned knowledge lookup under the `lookup` domain).
  *
- *   x-lt-options   "domain.path" or an ORDERED array of paths — e.g.
+ *   x-lt-options   "domain.path", an ORDERED array of paths, or an inline
+ *                  literal list (an array with no string entries: `{ value,
+ *                  label }` objects, numbers, or booleans) — e.g.
  *                  "envelope.left_quantity_options" or
  *                  ["lookup.reasons.items", "envelope.reject_reason_items"].
  *                  With an array, the first entry that resolves to options
@@ -42,7 +44,15 @@ exports.resolveFieldOptions = resolveFieldOptions;
 const ctx_path_1 = require("./ctx-path");
 exports.X_LT_OPTIONS = 'x-lt-options';
 function isScalar(v) {
-    return typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v));
+    return typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v));
+}
+/**
+ * An array token with no string entries is the option list itself, written
+ * inline. A bare string is always a context path, so a literal string value
+ * is written as `{ value, label }`.
+ */
+function isLiteralList(token) {
+    return Array.isArray(token) && token.length > 0 && !token.some((e) => typeof e === 'string');
 }
 /** Normalize one array entry, mixed arrays resolving each entry independently. */
 function toOption(entry) {
@@ -58,19 +68,23 @@ function toOption(entry) {
     return null;
 }
 /**
- * The field's effective option list: the static `enum` when present, else the
- * entries at the token's `"domain.path"`.
+ * The field's effective option list: the static `enum` when present, else an
+ * inline literal list, else the entries at the token's `"domain.path"`.
  */
 function resolveFieldOptions(fieldSchema, ctx) {
     if (!fieldSchema)
         return undefined;
     // Enum entries pass through verbatim as values (whatever their type), each
-    // labeled by its string form — the legacy membership contract is unchanged.
+    // labeled by its string form.
     const staticEnum = fieldSchema.enum;
     if (Array.isArray(staticEnum) && staticEnum.length > 0) {
         return staticEnum.map((v) => ({ value: v, label: String(v) }));
     }
     const token = fieldSchema[exports.X_LT_OPTIONS];
+    if (isLiteralList(token)) {
+        const options = token.map(toOption).filter((o) => o !== null);
+        return options.length > 0 ? options : undefined;
+    }
     const paths = (typeof token === 'string' ? [token] : Array.isArray(token) ? token : [])
         .filter((p) => typeof p === 'string' && p.length > 0);
     if (paths.length === 0)

package/build/shared/form-validation/x-lt-show-if.d.ts

@@ -6,3 +6,8 @@ export type ShowIfContext = HelpTokenContext;
  * An array of conditions shows the field only when every one holds.
  */
 export declare function evaluateShowIf(condition: unknown, ctx: ShowIfContext | null | undefined): boolean;
+/**
+ * `x-lt-hide-if-empty`: the field is suppressed while its value is empty
+ * (null, undefined, '', false, or 0). Render and validation share this test.
+ */
+export declare function isHiddenIfEmpty(fieldSchema: Record<string, unknown> | undefined, value: unknown): boolean;

package/build/shared/form-validation/x-lt-show-if.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluateShowIf = evaluateShowIf;
+exports.isHiddenIfEmpty = isHiddenIfEmpty;
 /**
  * x-lt-showIf — conditional field visibility. A form_schema property may
  * declare `x-lt-showIf: "domain.path"` to show the field only when the value
@@ -85,3 +86,12 @@ function evaluateShowIf(condition, ctx) {
         return true;
     return negate ? !isTruthy(value) : isTruthy(value);
 }
+/**
+ * `x-lt-hide-if-empty`: the field is suppressed while its value is empty
+ * (null, undefined, '', false, or 0). Render and validation share this test.
+ */
+function isHiddenIfEmpty(fieldSchema, value) {
+    if (fieldSchema?.['x-lt-hide-if-empty'] !== true)
+        return false;
+    return value === null || value === undefined || value === '' || value === false || value === 0;
+}

package/build/start/workers.js

@@ -51,6 +51,8 @@ const mcp_1 = require("../services/mcp");
 const yamlWorkflowWorkers = __importStar(require("../services/yaml-workflow/workers"));
 const migrate_1 = require("../lib/db/migrate");
 const apply_report_1 = require("./apply-report");
+const escalation_2 = require("../types/escalation");
+const lookup_refs_1 = require("../services/knowledge/lookup-refs");
 /**
  * Create a named no-op workflow function for readonly/observer workers.
  * The function name is used by `registerWorker` for discovery.
@@ -221,6 +223,13 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
                 for (const w of workersWithConfig) {
                     const workflowType = w.workflow.name;
                     const c = w.config;
+                    if (c.inputLookups !== undefined) {
+                        (0, escalation_2.assertLookupRefs)(c.inputLookups);
+                        // Editions may be seeded after registration; a missing pin warns here and surfaces on the Invoke Tool page.
+                        for (const problem of await (0, lookup_refs_1.describeMissingLookupRefs)(c.inputLookups)) {
+                            logger_1.loggerRegistry.warn(`[long-tail] ${workflowType}: ${problem}`);
+                        }
+                    }
                     const declaration = {
                         workflow_type: workflowType,
                         task_queue: w.taskQueue,
@@ -235,6 +244,7 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
                         envelope_schema: c.envelopeSchema ?? null,
                         input_schema: c.inputSchema ?? null,
                         icon: c.icon ?? null,
+                        input_lookups: c.inputLookups ?? null,
                         resolver_schema: c.resolverSchema ?? null,
                         cron_schedule: c.cronSchedule ?? null,
                         execute_as: c.executeAs ?? null,

package/build/system/mcp-servers/admin/escalations.js

@@ -218,6 +218,45 @@ function registerEscalationTools(server) {
         }
         return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
     });
+    // mirrors POST /api/escalations/:id/accumulate
+    server.registerTool('accumulate_item', {
+        title: 'Accumulate Item',
+        description: 'Add ONE item to an open accumulator escalation. Interim adds answer outcome "accepted" with the ' +
+            'count held and remaining slots; the add that reaches max completes the row and wakes the waiting ' +
+            'workflow with the ordered collection. A reciprocal row is written in the same statement, both or neither.',
+        inputSchema: schemas_1.accumulateItemSchema,
+    }, async (args) => {
+        const result = await escalationApi.accumulateItem({ id: args.id, itemKey: args.itemKey, payload: args.payload, metadata: args.metadata, reciprocal: args.reciprocal }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error, ...(result.data ?? {}) }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/:id/remove-item
+    server.registerTool('remove_item', {
+        title: 'Remove Item',
+        description: 'Remove ONE held item from a pending open accumulator escalation. The row stays pending and the ' +
+            'waiting workflow is never woken.',
+        inputSchema: schemas_1.removeItemSchema,
+    }, async (args) => {
+        const result = await escalationApi.removeItem({ id: args.id, itemKey: args.itemKey, reciprocal: args.reciprocal }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error, ...(result.data ?? {}) }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors GET /api/escalations/:id/items
+    server.registerTool('get_escalation_items', {
+        title: 'Get Escalation Items',
+        description: 'The held items of an accumulator or batch escalation in arrival order, with the count and max.',
+        inputSchema: schemas_1.getEscalationItemsSchema,
+    }, async (args) => {
+        const result = await escalationApi.getEscalationItems({ id: args.id }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
     // mirrors POST /api/escalations/resolve-by-signal-key
     server.registerTool('resolve_by_signal_key', {
         title: 'Resolve by Signal Key',