jsfe 0.9.86 → 0.9.87

package/README.md

@@ -310,6 +310,28 @@ async function aiCallback(systemInstruction, userMessage, jsonSchema, request) {
 run its text model alongside the classifier (for example, for free-text parameters). A callback that
 ignores the 4th argument behaves exactly as before; every other call still receives three arguments.
 
+**Host helpers — `jsfe/host`:**
+Pure functions for the host side of `aiCallback`, so a production host and a local test harness
+share one implementation. Loading `jsfe/host` never loads the engine.
+
+```javascript
+import { buildAiRequest, isDetectFlowRequest, toFlowRequest, fromFlowAnswers } from 'jsfe/host';
+
+// An OpenAI-compatible chat-completions body from a model description. It picks the right
+// response_format for each kind of jsonSchema argument, and never sends `response_format: null`.
+const body = buildAiRequest(
+  { name: 'gpt-4o-mini', reservedReplySize: 1024, supportsSchema: true },
+  systemInstruction, userMessage, jsonSchema);
+```
+
+- `buildAiRequest(model, systemInstruction, userMessage, jsonSchema)`, `parseSchemaArg`, `schemaName`.
+  `model` fields: `name`, `reservedReplySize`, and the optional `tokenParam`, `supportsSchema`,
+  `fixedSampling` and `extraParams`.
+- `isDetectFlowRequest`, `toFlowRequest` / `fromFlowAnswers` (which flow), `toParameterRequest` /
+  `fromParameterAnswers` (its enum and boolean parameters), `freeTextParameters`,
+  `mergeTextParameters`, `INTENT_YES_THRESHOLD`: these map the structured intent-detection
+  request to TypeSafe System One and back. The host sends the requests.
+
 **Alternative AI Services:**
 You can integrate any AI service (Claude, Gemini, local LLMs, etc.) by implementing this same interface. The engine only requires a function that takes system instructions and user input, then returns an AI response.
 

package/dist/host/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * jsfe/host — pure helpers for the HOST side of aiCallback, so a production host and a local
+ * test harness share one implementation instead of copying it. Zero runtime imports: loading
+ * `jsfe/host` never loads the engine.
+ *
+ *   import { buildAiRequest, isDetectFlowRequest, toFlowRequest } from 'jsfe/host';
+ */
+export * from './request.js';
+export * from './systemone-intent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC"}

package/dist/host/index.js

@@ -0,0 +1,9 @@
+/**
+ * jsfe/host — pure helpers for the HOST side of aiCallback, so a production host and a local
+ * test harness share one implementation instead of copying it. Zero runtime imports: loading
+ * `jsfe/host` never loads the engine.
+ *
+ *   import { buildAiRequest, isDetectFlowRequest, toFlowRequest } from 'jsfe/host';
+ */
+export * from './request.js';
+export * from './systemone-intent.js';

package/dist/host/request.d.ts

@@ -0,0 +1,57 @@
+/**
+ * aiCallback request shaping for an OpenAI-compatible host — pure, zero imports.
+ *
+ * jsfe calls the host's aiCallback(systemInstruction, userMessage, jsonSchema, request?). These
+ * helpers turn that call into a chat-completions request body, so a production host and a local
+ * test harness build byte-identical requests from one implementation.
+ */
+/**
+ * The request-relevant description of one model. Every field but `name` is optional:
+ *   tokenParam     — 'max_completion_tokens' for models that reject `max_tokens` (GPT-5 family).
+ *   reservedReplySize — the reply's token cap.
+ *   supportsSchema — the model honours a json_schema `response_format`.
+ *   fixedSampling  — the model rejects any non-default temperature/top_p/penalties.
+ *   extraParams    — raw body pass-through (e.g. `reasoning_effort`, `thinking`).
+ */
+export interface HostModel {
+    name: string;
+    tokenParam?: string;
+    reservedReplySize?: number;
+    supportsSchema?: boolean;
+    fixedSampling?: boolean;
+    extraParams?: Record<string, unknown>;
+}
+export interface ResponseFormatWrapper {
+    type?: string;
+    json_schema?: {
+        name?: string;
+        strict?: boolean;
+        schema?: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Parse aiCallback's `jsonSchema` argument, which is NOT always JSON. jsfe passes:
+ *   - a JSON `response_format` wrapper, e.g. {type:'json_schema', json_schema:{name:'detect_flow',…}}
+ *   - a PLAIN-TEXT schema description ("city: string (required) - …") on the tool-argument path
+ *   - nothing at all (voice cleanup, language detection)
+ * Returns null for the last two.
+ */
+export declare function parseSchemaArg(jsonSchema: unknown): ResponseFormatWrapper | null;
+/** The schema's name, or null. `detect_flow` and `intent_analysis` are the two jsfe uses. */
+export declare function schemaName(jsonSchema: unknown): string | null;
+/**
+ * Build the chat-completions request body for one model.
+ *
+ * `response_format` rules:
+ *   - detect_flow: omitted. Its schema carries dynamic per-flow parameters that json mode
+ *     rejects; the host still has the schema to validate the answer.
+ *   - a response_format wrapper + a model that supports schemas: sent as-is.
+ *   - any other JSON schema, or a model without schema support: `{type:'json_object'}`.
+ *   - NOT parseable as JSON (the plain-text description): omitted entirely — never
+ *     `response_format: null`, whose handling is undefined across vendors.
+ *
+ * Sampling is deterministic (temperature 0, a fixed seed) unless the model is `fixedSampling`.
+ */
+export declare function buildAiRequest(model: HostModel, systemInstruction: string, userMessage: string, jsonSchema?: unknown): Record<string, unknown>;
+//# sourceMappingURL=request.d.ts.map

package/dist/host/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/host/request.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACpE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,OAAO,GAAG,qBAAqB,GAAG,IAAI,CAYhF;AAED,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,OAAO,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA6BzB"}

package/dist/host/request.js

@@ -0,0 +1,75 @@
+/**
+ * aiCallback request shaping for an OpenAI-compatible host — pure, zero imports.
+ *
+ * jsfe calls the host's aiCallback(systemInstruction, userMessage, jsonSchema, request?). These
+ * helpers turn that call into a chat-completions request body, so a production host and a local
+ * test harness build byte-identical requests from one implementation.
+ */
+/**
+ * Parse aiCallback's `jsonSchema` argument, which is NOT always JSON. jsfe passes:
+ *   - a JSON `response_format` wrapper, e.g. {type:'json_schema', json_schema:{name:'detect_flow',…}}
+ *   - a PLAIN-TEXT schema description ("city: string (required) - …") on the tool-argument path
+ *   - nothing at all (voice cleanup, language detection)
+ * Returns null for the last two.
+ */
+export function parseSchemaArg(jsonSchema) {
+    if (!jsonSchema) {
+        return null;
+    }
+    else {
+        // a schema argument was supplied — it may still not be JSON
+    }
+    try {
+        const parsed = JSON.parse(String(jsonSchema));
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null; // plain-text schema description — an instruction for the prompt, not a response_format
+    }
+}
+/** The schema's name, or null. `detect_flow` and `intent_analysis` are the two jsfe uses. */
+export function schemaName(jsonSchema) {
+    return parseSchemaArg(jsonSchema)?.json_schema?.name ?? null;
+}
+/**
+ * Build the chat-completions request body for one model.
+ *
+ * `response_format` rules:
+ *   - detect_flow: omitted. Its schema carries dynamic per-flow parameters that json mode
+ *     rejects; the host still has the schema to validate the answer.
+ *   - a response_format wrapper + a model that supports schemas: sent as-is.
+ *   - any other JSON schema, or a model without schema support: `{type:'json_object'}`.
+ *   - NOT parseable as JSON (the plain-text description): omitted entirely — never
+ *     `response_format: null`, whose handling is undefined across vendors.
+ *
+ * Sampling is deterministic (temperature 0, a fixed seed) unless the model is `fixedSampling`.
+ */
+export function buildAiRequest(model, systemInstruction, userMessage, jsonSchema) {
+    const parsedSchema = parseSchemaArg(jsonSchema);
+    const useResponseFormat = parsedSchema !== null && parsedSchema.json_schema?.name !== 'detect_flow';
+    const tokenParam = model.tokenParam || 'max_tokens';
+    return {
+        messages: [
+            { role: 'system', content: systemInstruction },
+            { role: 'user', content: userMessage },
+        ],
+        model: model.name,
+        [tokenParam]: model.reservedReplySize,
+        stream: false,
+        ...(model.extraParams || {}),
+        ...(model.fixedSampling ? {} : {
+            top_p: 0.000000001,
+            seed: 1024,
+            temperature: 0,
+            n: 1,
+            presence_penalty: 0,
+            frequency_penalty: 0,
+            logit_bias: {},
+        }),
+        ...(useResponseFormat
+            ? (model.supportsSchema && parsedSchema.json_schema
+                ? { response_format: parsedSchema }
+                : { response_format: { type: 'json_object' } })
+            : {}),
+    };
+}

package/dist/host/systemone-intent.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Intent detection (`detect_flow`) ⇄ TypeSafe System One — mapping only, zero imports.
+ *
+ * jsfe hands aiCallback a 4th argument on intent detection: the call in structured form,
+ * `{ task: 'detect_flow', input, conversation, flows }`, each flow with its parameters and any
+ * declared `enum`. That is what a classifier needs, so this module maps it to System One questions
+ * and the answers back to the reply jsfe expects: `{ flowName, parameters }`. Two stages:
+ *
+ *   1. one noul per flow: "should `latest_message` start this workflow?" — argmax, if it clears
+ *      INTENT_YES_THRESHOLD, else "None".
+ *   2. only for the chosen flow, and only if it declares one: a noul per ENUM value and per
+ *      BOOLEAN parameter.
+ *   Every other parameter (free text: a city, an account number…) is not the classifier's; the
+ *   host decides whether to take it from a text model — see freeTextParameters().
+ *
+ * The host sends the bodies (POST …/v1/systemone) and owns the HTTP, the key and the timeouts.
+ *
+ * A question that comes back without a usable answer FAILS the call, so the host can fall back
+ * to a text model. A missing flow answer read as "no" would silently send the turn nowhere.
+ */
+import type { DetectFlowRequest } from '../index.js';
+/** One flow entry of the structured intent-detection request. */
+export type DetectFlowRequestFlow = DetectFlowRequest['flows'][number];
+/** A noul at or above this is a yes. */
+export declare const INTENT_YES_THRESHOLD = 0.5;
+/** One System One request body plus the index that maps each question id back to what it asks. */
+export interface SystemOneCall<I> {
+    body: {
+        model: string;
+        state: Record<string, unknown>;
+        questions: Record<string, unknown>;
+    };
+    index: I[];
+}
+export interface FlowQuestion {
+    id: string;
+    flow: number;
+}
+export type ParameterQuestion = {
+    id: string;
+    kind: 'enum';
+    param: string;
+    value: string;
+} | {
+    id: string;
+    kind: 'boolean';
+    param: string;
+};
+/** System One's answers, keyed by question id. */
+export type SystemOneAnswers = Record<string, {
+    noul?: unknown;
+} | undefined> | undefined;
+export interface IntentReply {
+    flowName: string;
+    parameters: Record<string, unknown>;
+}
+export interface MapOptions {
+    model: string;
+    assistantInstructions: string;
+}
+/** Is this a jsfe intent-detection request this module can map? */
+export declare function isDetectFlowRequest(request: unknown): request is DetectFlowRequest;
+/** Parameters of `flow` the classifier does not answer: neither an enum nor a boolean. */
+export declare function freeTextParameters(flow: DetectFlowRequestFlow | null | undefined): string[];
+/**
+ * STAGE 1 — which flow. One noul per flow. `assistantInstructions` is jsfe's own task + rules (the
+ * text prompt's system instruction without its JSON-schema tail), so a classifier and a text model
+ * judge by one rule set.
+ */
+export declare function toFlowRequest(request: DetectFlowRequest, { model, assistantInstructions }: MapOptions): SystemOneCall<FlowQuestion>;
+/**
+ * Decodes stage 1. Throws if any question is unanswered. Returns `{ flow, scores }` — `flow` is the
+ * chosen request entry, or null for "None"; `scores` the top three, for logging.
+ */
+export declare function fromFlowAnswers(answers: SystemOneAnswers, index: FlowQuestion[], request: DetectFlowRequest, threshold?: number): {
+    flow: DetectFlowRequestFlow | null;
+    scores: {
+        name: string;
+        p: number;
+    }[];
+};
+/** Does `flow` declare anything stage 2 answers (an enum or a boolean)? */
+export declare function hasJevParameters(flow: DetectFlowRequestFlow | null | undefined): boolean;
+/**
+ * STAGE 2 — the chosen flow's enum and boolean parameters: one noul per enum value, one per
+ * boolean. Each parameter's description is its rule. Free text is not asked.
+ *
+ * The flow and the rules are stated ONCE, in `assistant_instructions`; each question names its
+ * parameter only. Repeating a long rule in every question of its enum multiplies the body size
+ * and the latency for identical answers.
+ */
+export declare function toParameterRequest(request: DetectFlowRequest, flow: DetectFlowRequestFlow, { model, assistantInstructions }: MapOptions): SystemOneCall<ParameterQuestion>;
+/**
+ * Decodes stage 2 into parameters: an enum takes its argmax value if it clears the cut, a boolean is
+ * true if it clears it; otherwise the parameter is OMITTED (the flow asks / its default applies),
+ * never set false. Throws if any question is unanswered.
+ */
+export declare function fromParameterAnswers(answers: SystemOneAnswers, index: ParameterQuestion[], threshold?: number): Record<string, unknown>;
+/**
+ * Merges a text model's free-text parameters into the classifier's reply — only when the text model
+ * chose the SAME flow (its parameters were extracted for its own choice), and only the parameters
+ * the classifier does not answer. The classifier's enum/boolean values always win.
+ */
+export declare function mergeTextParameters(jevReply: IntentReply, jevFlow: DetectFlowRequestFlow | null | undefined, textReply: {
+    flowName?: unknown;
+    parameters?: Record<string, unknown>;
+} | null | undefined): IntentReply;
+//# sourceMappingURL=systemone-intent.d.ts.map

package/dist/host/systemone-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemone-intent.d.ts","sourceRoot":"","sources":["../../src/host/systemone-intent.ts"],"names":[],"mappings":"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"}

package/dist/host/systemone-intent.js

@@ -0,0 +1,188 @@
+/**
+ * Intent detection (`detect_flow`) ⇄ TypeSafe System One — mapping only, zero imports.
+ *
+ * jsfe hands aiCallback a 4th argument on intent detection: the call in structured form,
+ * `{ task: 'detect_flow', input, conversation, flows }`, each flow with its parameters and any
+ * declared `enum`. That is what a classifier needs, so this module maps it to System One questions
+ * and the answers back to the reply jsfe expects: `{ flowName, parameters }`. Two stages:
+ *
+ *   1. one noul per flow: "should `latest_message` start this workflow?" — argmax, if it clears
+ *      INTENT_YES_THRESHOLD, else "None".
+ *   2. only for the chosen flow, and only if it declares one: a noul per ENUM value and per
+ *      BOOLEAN parameter.
+ *   Every other parameter (free text: a city, an account number…) is not the classifier's; the
+ *   host decides whether to take it from a text model — see freeTextParameters().
+ *
+ * The host sends the bodies (POST …/v1/systemone) and owns the HTTP, the key and the timeouts.
+ *
+ * A question that comes back without a usable answer FAILS the call, so the host can fall back
+ * to a text model. A missing flow answer read as "no" would silently send the turn nowhere.
+ */
+/** A noul at or above this is a yes. */
+export const INTENT_YES_THRESHOLD = 0.5;
+const FLOW_QUESTION = 'Should `latest_message` start the workflow described in `flow`?';
+const FLOW_CRITERIA = {
+    true: "`latest_message`, read with `conversation`, is what `flow`'s description says should trigger it: the user asks for its action or information, or raises the problem it exists to handle.",
+    false: "It only shares a topic with `flow`, is something `flow`'s description does not cover, or is a greeting, acknowledgement or fragment that asks for nothing. A question about an available balance or credit is not a request to pay, and a complaint about a charge is not a request to pay.",
+};
+const ENUM_CRITERIA = (value) => ({
+    true: `The rules for \`parameter\` make \`${value}\` the correct value for what the customer said.`,
+    false: 'Another value, or none, is correct; or the customer has not said enough to tell.',
+});
+const BOOLEAN_CRITERIA = {
+    true: 'The rules for `parameter` make it true for what the customer said.',
+    false: 'The rules do not make it true, or the customer has not said enough to tell.',
+};
+const isEnum = (p) => Array.isArray(p.enum) && p.enum.length > 0;
+const isBoolean = (p) => p.type === 'boolean';
+/** Is this a jsfe intent-detection request this module can map? */
+export function isDetectFlowRequest(request) {
+    const r = request;
+    return !!r && r.task === 'detect_flow' && Array.isArray(r.flows) && r.flows.length > 0;
+}
+/** Parameters of `flow` the classifier does not answer: neither an enum nor a boolean. */
+export function freeTextParameters(flow) {
+    return (flow?.parameters || []).filter(p => !isEnum(p) && !isBoolean(p)).map(p => p.name);
+}
+const stateOf = (request, assistantInstructions) => ({
+    assistant_instructions: assistantInstructions,
+    conversation: (request.conversation || []).map(t => ({ role: t.role, content: t.content })),
+    latest_message: request.input,
+});
+function answersOf(answers, index) {
+    const p = new Map();
+    for (const q of index) {
+        const noul = Number(answers?.[q.id]?.noul);
+        if (!Number.isFinite(noul)) {
+            throw new Error(`System One intent: question ${q.id} unanswered`);
+        }
+        else {
+            p.set(q.id, noul);
+        }
+    }
+    return p;
+}
+/**
+ * STAGE 1 — which flow. One noul per flow. `assistantInstructions` is jsfe's own task + rules (the
+ * text prompt's system instruction without its JSON-schema tail), so a classifier and a text model
+ * judge by one rule set.
+ */
+export function toFlowRequest(request, { model, assistantInstructions }) {
+    const questions = {};
+    const index = [];
+    request.flows.forEach((flow, f) => {
+        const id = `f${f}`;
+        questions[id] = {
+            type: 'noul', criteria: FLOW_CRITERIA,
+            instructions: { flow: { name: flow.name, description: String(flow.description ?? '') }, question: FLOW_QUESTION },
+        };
+        index.push({ id, flow: f });
+    });
+    return { body: { model, state: stateOf(request, assistantInstructions), questions }, index };
+}
+/**
+ * Decodes stage 1. Throws if any question is unanswered. Returns `{ flow, scores }` — `flow` is the
+ * chosen request entry, or null for "None"; `scores` the top three, for logging.
+ */
+export function fromFlowAnswers(answers, index, request, threshold = INTENT_YES_THRESHOLD) {
+    const p = answersOf(answers, index);
+    const ranked = index
+        .map(q => ({ name: request.flows[q.flow].name, f: q.flow, p: p.get(q.id) }))
+        .sort((a, b) => b.p - a.p);
+    const scores = ranked.slice(0, 3).map(({ name, p: prob }) => ({ name, p: prob }));
+    return { flow: ranked[0] && ranked[0].p >= threshold ? request.flows[ranked[0].f] : null, scores };
+}
+/** Does `flow` declare anything stage 2 answers (an enum or a boolean)? */
+export function hasJevParameters(flow) {
+    return (flow?.parameters || []).some(p => isEnum(p) || isBoolean(p));
+}
+/**
+ * STAGE 2 — the chosen flow's enum and boolean parameters: one noul per enum value, one per
+ * boolean. Each parameter's description is its rule. Free text is not asked.
+ *
+ * The flow and the rules are stated ONCE, in `assistant_instructions`; each question names its
+ * parameter only. Repeating a long rule in every question of its enum multiplies the body size
+ * and the latency for identical answers.
+ */
+export function toParameterRequest(request, flow, { model, assistantInstructions }) {
+    const questions = {};
+    const index = [];
+    const flowRef = { name: flow.name };
+    const rules = {};
+    (flow.parameters || []).forEach((p, k) => {
+        const parameter = { name: p.name };
+        if (isEnum(p)) {
+            p.enum.forEach((value, v) => {
+                const id = `p${k}v${v}`;
+                questions[id] = {
+                    type: 'noul', criteria: ENUM_CRITERIA(value), instructions: {
+                        flow: flowRef, parameter, candidate_value: value,
+                        question: `Is \`${value}\` the correct value of \`${p.name}\` for \`latest_message\`?`,
+                    },
+                };
+                index.push({ id, kind: 'enum', param: p.name, value });
+            });
+        }
+        else if (isBoolean(p)) {
+            const id = `p${k}`;
+            questions[id] = {
+                type: 'noul', criteria: BOOLEAN_CRITERIA, instructions: {
+                    flow: flowRef, parameter, question: `Should \`${p.name}\` be true for \`latest_message\`?`,
+                },
+            };
+            index.push({ id, kind: 'boolean', param: p.name });
+        }
+        else {
+            return; // free text — not the classifier's; see freeTextParameters()
+        }
+        rules[p.name] = String(p.description ?? '');
+    });
+    const instructions = `${assistantInstructions}\n\nThe workflow \`${flow.name}\` starts for \`latest_message\`: ${String(flow.description ?? '')}\n\n` +
+        `Each question asks for one of its parameters. The rules for each parameter, by name:\n${JSON.stringify(rules, null, 1)}`;
+    return { body: { model, state: stateOf(request, instructions), questions }, index };
+}
+/**
+ * Decodes stage 2 into parameters: an enum takes its argmax value if it clears the cut, a boolean is
+ * true if it clears it; otherwise the parameter is OMITTED (the flow asks / its default applies),
+ * never set false. Throws if any question is unanswered.
+ */
+export function fromParameterAnswers(answers, index, threshold = INTENT_YES_THRESHOLD) {
+    const p = answersOf(answers, index);
+    const parameters = {};
+    const best = new Map();
+    for (const q of index) {
+        const prob = p.get(q.id);
+        if (q.kind === 'boolean') {
+            if (prob >= threshold)
+                parameters[q.param] = true;
+            else { /* omitted */ }
+        }
+        else {
+            const cur = best.get(q.param);
+            if (!cur || prob > cur.p)
+                best.set(q.param, { value: q.value, p: prob });
+            else { /* lower */ }
+        }
+    }
+    for (const [param, { value, p: prob }] of best) {
+        if (prob >= threshold)
+            parameters[param] = value;
+        else { /* omitted: the flow asks */ }
+    }
+    return parameters;
+}
+/**
+ * Merges a text model's free-text parameters into the classifier's reply — only when the text model
+ * chose the SAME flow (its parameters were extracted for its own choice), and only the parameters
+ * the classifier does not answer. The classifier's enum/boolean values always win.
+ */
+export function mergeTextParameters(jevReply, jevFlow, textReply) {
+    if (!jevFlow || !textReply || String(textReply.flowName).toLowerCase() !== jevFlow.name.toLowerCase()) {
+        return jevReply;
+    }
+    else {
+        const free = new Set(freeTextParameters(jevFlow));
+        const extra = Object.fromEntries(Object.entries(textReply.parameters || {}).filter(([k]) => free.has(k)));
+        return { flowName: jevReply.flowName, parameters: { ...extra, ...jevReply.parameters } };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsfe",
-  "version": "0.9.86",
+  "version": "0.9.87",
   "description": "TypeScript workflow engine for conversational/automation apps: multi-flow orchestration, interrupt/resume, stack-based control, robust errors, and flexible tool/REST integration.",
   "license": "MIT",
   "author": "Ron Pinkas",
@@ -14,6 +14,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "import": "./dist/host/index.js"
     }
   },
   "main": "./dist/index.js",