@superpanel-sdk/runtime 0.2.2 → 0.2.3

package/dist/builder/compile/compile-agenda.js

@@ -1,5 +1,5 @@
 import { toEffectiveSchema } from '../../core/slot/compile-schema.js';
-import { collectTransferBlocks, fatalAgendaIssues, flattenAgendaPlacements, flattenAgendaTree, isAgendaTree, isSequenceAgendas, normalizeSequenceAgendas, registerTransferSessionFields, validateCompiledAgenda, } from '../../core/stage/index.js';
+import { collectIvrBlocks, collectTransferBlocks, collectTransferInterruptHeaders, fatalAgendaIssues, flattenAgendaPlacements, flattenAgendaTree, isAgendaTree, isSequenceAgendas, normalizeSequenceAgendas, registerIvrSessionFields, registerTransferSessionFields, validateCompiledAgenda, } from '../../core/stage/index.js';
 function asAgendaTrees(raw) {
     if (isAgendaTree(raw))
         return [raw];
@@ -27,8 +27,11 @@ export function compileSequenceAgendas(schema, raw, options = {}) {
     }
     const trees = asAgendaTrees(raw);
     if (trees) {
-        const transferIds = collectTransferBlocks({}, trees.flatMap((tree) => tree.tree)).map((block) => block.id);
-        const withTransfer = registerTransferSessionFields(schema, transferIds);
+        const nodes = trees.flatMap((tree) => tree.tree);
+        const transferIds = collectTransferBlocks({}, nodes).map((block) => block.id);
+        const withTransfer = registerIvrSessionFields(registerTransferSessionFields(schema, transferIds, {
+            lastResult: collectTransferInterruptHeaders(trees.map((tree) => tree.header)),
+        }), collectIvrBlocks({}, nodes).map((block) => block.id));
         const compiled = {};
         for (const tree of trees) {
             compiled[tree.id] = compileOneFlat(tree.id, tree.header, flattenAgendaTree(tree.tree, { functions: options.functions }), withTransfer, options.functions, issues);
@@ -48,7 +51,9 @@ export function compileSequenceAgendas(schema, raw, options = {}) {
         return { schema, effectiveSchema: toEffectiveSchema(schema), agendas: {}, issues };
     }
     const transferIds = collectTransferBlocks(agendasInput.blocks).map((block) => block.id);
-    const withTransfer = registerTransferSessionFields(schema, transferIds);
+    const withTransfer = registerIvrSessionFields(registerTransferSessionFields(schema, transferIds, {
+        lastResult: collectTransferInterruptHeaders(Object.values(agendasInput.agendas).map((config) => config.header)),
+    }), collectIvrBlocks(agendasInput.blocks).map((block) => block.id));
     const compiled = {};
     for (const [agendaId, config] of Object.entries(agendasInput.agendas)) {
         compiled[agendaId] = compileOneFlat(agendaId, config.header, flattenAgendaPlacements(config.placements, agendasInput.blocks, { functions: options.functions }), withTransfer, options.functions, issues);

package/dist/cli/serve/index.js

@@ -5,6 +5,7 @@ import { withCompanyImportGraph } from '../../builder/company-import-graph.js';
 import { findTsModule } from '../../builder/paths.js';
 import { listSequenceIds, loadSequenceCaseContextView, loadSequenceFunctions } from '../../builder/load.js';
 import { createSourceComputeHost } from '../../compute-host/source-compute-host.js';
+import { formatRuntimeVersion } from '../../fn-context/rpc/request-id.js';
 import { encodeOverlayMessage, OVERLAY_REPLACED_CLOSE_CODE, parseOverlayMessage, } from '../../dev-overlay/protocol.js';
 const DEFAULT_BACKEND_URL = 'http://127.0.0.1:8100';
 function env(name) {
@@ -27,6 +28,20 @@ export function overlayWebSocketUrl(raw) {
     url.hash = '';
     return url.toString();
 }
+function overlayRpcUrl(raw) {
+    const url = new URL(raw);
+    if (url.protocol === 'ws:')
+        url.protocol = 'http:';
+    else if (url.protocol === 'wss:')
+        url.protocol = 'https:';
+    else if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`unsupported backend url: ${raw}`);
+    }
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/trpc`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
 /** `sequences/<id>/…` → sequence id */
 function sequenceIdFromPath(repoRoot, file) {
     const rel = path.relative(repoRoot, file);
@@ -73,13 +88,19 @@ function send(ws, message) {
 function logField(label, value) {
     console.log(`  ${label.padEnd(10)} ${value}`);
 }
-async function handleExecute(loaded, message) {
+async function handleExecute(loaded, message, rpcUrl) {
+    const data = message.data
+        ? {
+            ...message.data,
+            config: { ...message.data.config, backendUrl: rpcUrl },
+        }
+        : undefined;
     const host = createSourceComputeHost({
         functions: loaded.functions,
         caseContextView: loaded.view,
-        data: message.data,
+        data: data,
         runToken: message.runToken,
-        runtimeVersion: loaded.build.runtimeVersion ?? loaded.build.engineVersion,
+        runtimeVersion: loaded.build.engineVersion,
         runtimeSource: loaded.build.runtimeSource ?? 'npm',
         getRequestId: () => message.logRequestId,
         getTags: () => message.logTags,
@@ -101,14 +122,36 @@ function pushOverlays(ws, sequences) {
         });
     }
 }
+function closeDetail(event) {
+    return event.reason ? `${event.code} ${event.reason}` : String(event.code);
+}
 function waitOpen(ws) {
     return new Promise((resolve, reject) => {
         if (ws.readyState === WebSocket.OPEN) {
             resolve();
             return;
         }
-        ws.addEventListener('open', () => resolve(), { once: true });
-        ws.addEventListener('error', () => reject(new Error('websocket error')), { once: true });
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            fn();
+        };
+        const onOpen = () => finish(() => resolve());
+        const onClose = (event) => finish(() => reject(new Error(`websocket closed ${closeDetail(event)}`)));
+        const onError = () => {
+            setTimeout(() => finish(() => reject(new Error('websocket error'))), 250);
+        };
+        const cleanup = () => {
+            ws.removeEventListener('open', onOpen);
+            ws.removeEventListener('close', onClose);
+            ws.removeEventListener('error', onError);
+        };
+        ws.addEventListener('open', onOpen);
+        ws.addEventListener('close', onClose);
+        ws.addEventListener('error', onError);
     });
 }
 class OverlayReplacedError extends Error {
@@ -146,7 +189,7 @@ function waitAuthOk(ws) {
             cleanup();
             reject(event.code === OVERLAY_REPLACED_CLOSE_CODE
                 ? new OverlayReplacedError()
-                : new Error('websocket closed before auth.ok'));
+                : new Error(`websocket closed before auth.ok ${closeDetail(event)}`));
         };
         const cleanup = () => {
             ws.removeEventListener('message', onMessage);
@@ -156,7 +199,7 @@ function waitAuthOk(ws) {
         ws.addEventListener('close', onClose);
     });
 }
-function attachExecuteHandler(ws, sequences) {
+function attachExecuteHandler(ws, sequences, rpcUrl) {
     ws.addEventListener('message', (event) => {
         void (async () => {
             let message;
@@ -185,7 +228,7 @@ function attachExecuteHandler(ws, sequences) {
             const started = Date.now();
             console.log(`execute ${call}`);
             try {
-                const result = await handleExecute(loaded, message);
+                const result = await handleExecute(loaded, message, rpcUrl);
                 console.log(`execute ${call} ok ${Date.now() - started}ms`);
                 send(ws, { type: 'execute.result', requestId: message.requestId, ok: true, result });
             }
@@ -205,7 +248,7 @@ function attachExecuteHandler(ws, sequences) {
 function waitSessionEnd(ws) {
     return new Promise((resolve) => {
         if (ws.readyState === WebSocket.CLOSED) {
-            resolve('closed');
+            resolve({ closed: 'already closed' });
             return;
         }
         const onMessage = (event) => {
@@ -222,7 +265,7 @@ function waitSessionEnd(ws) {
         };
         const onClose = (event) => {
             cleanup();
-            resolve(event.code === OVERLAY_REPLACED_CLOSE_CODE ? 'replaced' : 'closed');
+            resolve(event.code === OVERLAY_REPLACED_CLOSE_CODE ? 'replaced' : { closed: closeDetail(event) });
         };
         const cleanup = () => {
             ws.removeEventListener('message', onMessage);
@@ -241,6 +284,7 @@ export async function runServe(repoRoot, options = {}) {
         throw new Error('SUPERPANEL_SDK_API_KEY or --api-key is required');
     const backendUrl = options.url ?? env('SUPERPANEL_SDK_BACKEND_URL') ?? DEFAULT_BACKEND_URL;
     const url = overlayWebSocketUrl(backendUrl);
+    const rpcUrl = overlayRpcUrl(backendUrl);
     const sequenceIds = options.sequenceIds ?? listSequenceIds(repoRoot);
     if (sequenceIds.length === 0) {
         throw new Error(`No sequences with slots found under ${path.join(repoRoot, 'sequences')}`);
@@ -249,9 +293,13 @@ export async function runServe(repoRoot, options = {}) {
     const sequences = await loadSequences(repoRoot, sequenceIds, generation);
     let socket = null;
     const names = [...sequences.keys()];
+    const firstBuild = sequences.values().next().value?.build;
     console.log('Local overlay');
     logField('company', companyId);
     logField('sequences', names.join(', '));
+    if (firstBuild) {
+        logField('runtime', formatRuntimeVersion(firstBuild.engineVersion, firstBuild.runtimeSource ?? 'npm'));
+    }
     logField('backend', backendUrl);
     logField('websocket', url);
     let timer;
@@ -328,14 +376,14 @@ export async function runServe(repoRoot, options = {}) {
                 names: [...sequences.keys()],
             });
             await authOk;
-            attachExecuteHandler(ws, sequences);
+            attachExecuteHandler(ws, sequences, rpcUrl);
             pushOverlays(ws, sequences);
             delayMs = 500;
             console.log(`connected  overlay ${url}`);
             const end = await waitSessionEnd(ws);
             if (end === 'replaced')
                 throw new OverlayReplacedError();
-            console.log('disconnected  retrying');
+            console.log(`disconnected  retrying  ${end.closed}`);
         }
         catch (error) {
             if (error instanceof OverlayReplacedError)

package/dist/compute-host/index.d.ts

@@ -2,4 +2,6 @@ export { createLocalComputeHost, resolveComputeHost } from './compute-host.js';
 export type { ComputeFnMap, ComputeHost, ComputeHostOrFns, LocalComputeHostOptions } from './compute-host.js';
 export { createSourceComputeHost } from './source-compute-host.js';
 export type { SourceComputeHost, SourceComputeHostOptions } from './source-compute-host.js';
+export { readOnlyComputeNames, withReadOnlyComputeCache } from './read-only-cache.js';
+export type { ReadOnlyComputeCacheOptions } from './read-only-cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/compute-host/index.js

@@ -1,3 +1,4 @@
 export { createLocalComputeHost, resolveComputeHost } from './compute-host.js';
 export { createSourceComputeHost } from './source-compute-host.js';
+export { readOnlyComputeNames, withReadOnlyComputeCache } from './read-only-cache.js';
 //# sourceMappingURL=index.js.map

package/dist/compute-host/read-only-cache.d.ts

@@ -0,0 +1,20 @@
+import type { ComputeHost } from './compute-host.js';
+/** Names safe to cache: `caseContextView` plus every compute / boolCompute. */
+export declare function readOnlyComputeNames(functions?: Record<string, {
+    kind: string;
+}>): Set<string>;
+export type ReadOnlyComputeCacheOptions = {
+    /** Defaults to `caseContextView` only. Pass {@link readOnlyComputeNames} for compute / boolCompute too. */
+    readOnly?: Iterable<string> | ((name: string) => boolean);
+};
+/**
+ * Cache read-only `execute` results by function name + the single input object.
+ * Calls with extra args bypass the cache so a shared snapshot cannot alias
+ * two different argument lists.
+ *
+ * Do not wrap a host used by derived recompute: that path mutates one snapshot
+ * in place between `compute` calls. Stage walk / when-eval is safe (new snapshot
+ * after writes).
+ */
+export declare function withReadOnlyComputeCache(host: ComputeHost, options?: ReadOnlyComputeCacheOptions): ComputeHost;
+//# sourceMappingURL=read-only-cache.d.ts.map

package/dist/compute-host/read-only-cache.js

@@ -0,0 +1,61 @@
+const READ_ONLY_KINDS = new Set(['compute', 'boolCompute', 'caseContextView']);
+/** Names safe to cache: `caseContextView` plus every compute / boolCompute. */
+export function readOnlyComputeNames(functions) {
+    const names = new Set(['caseContextView']);
+    if (!functions)
+        return names;
+    for (const [name, entry] of Object.entries(functions)) {
+        if (READ_ONLY_KINDS.has(entry.kind))
+            names.add(name);
+    }
+    return names;
+}
+/**
+ * Cache read-only `execute` results by function name + the single input object.
+ * Calls with extra args bypass the cache so a shared snapshot cannot alias
+ * two different argument lists.
+ *
+ * Do not wrap a host used by derived recompute: that path mutates one snapshot
+ * in place between `compute` calls. Stage walk / when-eval is safe (new snapshot
+ * after writes).
+ */
+export function withReadOnlyComputeCache(host, options) {
+    const allow = resolveAllow(options?.readOnly);
+    const cache = new WeakMap();
+    return {
+        async execute(name, args = []) {
+            const input = args[0];
+            if (!allow(name) || args.length !== 1 || input == null || typeof input !== 'object') {
+                return host.execute(name, args);
+            }
+            let byName = cache.get(input);
+            if (!byName) {
+                byName = new Map();
+                cache.set(input, byName);
+            }
+            const hit = byName.get(name);
+            if (hit)
+                return hit;
+            const pending = host.execute(name, args);
+            byName.set(name, pending);
+            try {
+                return await pending;
+            }
+            catch (error) {
+                if (byName.get(name) === pending)
+                    byName.delete(name);
+                throw error;
+            }
+        },
+        dispose() {
+            host.dispose();
+        },
+    };
+}
+function resolveAllow(readOnly) {
+    if (typeof readOnly === 'function')
+        return readOnly;
+    const names = new Set(readOnly ?? ['caseContextView']);
+    return (name) => names.has(name);
+}
+//# sourceMappingURL=read-only-cache.js.map

package/dist/compute-host/source-compute-host.js

@@ -49,11 +49,16 @@ export function createSourceComputeHost(options) {
                 const caseContext = viewFn(requireSlots(name, args));
                 const ctx = await systemContext();
                 const fn = def.main;
-                return fn(caseContext, ctx);
+                return fn(caseContext, { ...ctx, params: args[1] ?? {} });
             }
             const params = resolveSystemFnParams(args);
+            const contextStarted = Date.now();
             const ctx = await systemContext();
-            return def.main({ ...ctx, params });
+            console.log(`[source timing] ${name} context ${Date.now() - contextStarted}ms`);
+            const functionStarted = Date.now();
+            const result = await def.main({ ...ctx, params });
+            console.log(`[source timing] ${name} function ${Date.now() - functionStarted}ms`);
+            return result;
         },
         dispose() { },
     };

package/dist/core/context/types.d.ts

@@ -19,7 +19,25 @@ export type Slots = Record<string, unknown>;
  * With `view.ts`, use `CaseContextOf<typeof caseContextView>` from that module.
  */
 export type CaseContext = Record<string, unknown>;
-export type Writes = Record<FieldPath, unknown>;
+/** Flat writes for single-row tables, or the current-bound row of an entity table. */
+export type FieldWrites = Record<FieldPath, unknown>;
+/** Address one row of a multi-row table (`children`, `contact`, custom arrays). */
+export type RowWrite = {
+    table: string;
+    rowId: string;
+    values: Record<string, unknown>;
+};
+/** Mix flat field writes with explicit row writes in one return. */
+export type StructuredWrites = {
+    fields?: FieldWrites;
+    rows?: RowWrite[];
+};
+/**
+ * Function / platform write payload.
+ * Flat `{ '表.字段': 值 }` for single-row (or current-party) fields;
+ * `{ table, rowId, values }` to write a specific multi-row.
+ */
+export type Writes = FieldWrites | RowWrite | StructuredWrites;
 export type Logger = {
     info: (message: string, extra?: Record<string, unknown>) => void;
     warn: (message: string, extra?: Record<string, unknown>) => void;

package/dist/core/functions/define/custom.d.ts

@@ -1,4 +1,4 @@
 import type { CustomFn, DefinedFunc, FuncOptions } from '../types.js';
 import type { CaseContext } from '../../context/types.js';
-export declare function defineCustomFunc<S = CaseContext>(main: CustomFn<S>, options?: FuncOptions): DefinedFunc;
+export declare function defineCustomFunc<S = CaseContext, P extends object = object>(main: CustomFn<S, P>, options?: FuncOptions): DefinedFunc;
 //# sourceMappingURL=custom.d.ts.map

package/dist/core/functions/types.d.ts

@@ -6,16 +6,16 @@ export type FuncOptions = {
 };
 /** First arg is CaseContext (or Slots when the sequence has no view). */
 export type ComputeFn<S = CaseContext, R = unknown> = (caseContext: S) => R | Promise<R>;
-export type CustomFn<S = CaseContext> = (caseContext: S, ctx: SystemContext) => Promise<Writes | null>;
+export type FunctionCtx<Params extends object> = SystemContext & {
+    params: Params;
+};
+export type CustomFn<S = CaseContext, P extends object = object> = (caseContext: S, ctx: FunctionCtx<P>) => Promise<Writes | null>;
 /** Inbound webhook request payload. */
 export type WebHookFunctionParams = {
     headers: Record<string, string | string[] | undefined>;
     body: unknown;
     rawBody?: string;
 };
-export type FunctionCtx<Params extends object> = SystemContext & {
-    params: Params;
-};
 export type FunctionCall<Params extends object, Return> = (ctx: FunctionCtx<Params>) => Promise<Return>;
 export type WebHookFunction = FunctionCall<WebHookFunctionParams, void>;
 export type GetFirstMessageParams<S = CaseContext> = {

package/dist/core/slot/index.d.ts

@@ -9,7 +9,7 @@ export { isValidDataTypeValue, validateExtractedField, validateBareValue } from
 export { buildSlotFillingJsonSchema, buildFieldCatalog, type SfSchemaOptions } from './sf-schema.js';
 export { validateSlotFillingOutput, type ValidateSlotFillingOptions } from './sf-validate.js';
 export { snapshotFrom, cloneSnapshot, getSingleField, getSnapshotTable, type SnapshotSeed } from './snapshot.js';
-export { applyFieldPatch, applyWrites, applySlotFilling, markAskedUnknown, type ApplySlotFillingOptions, type FieldPatchInput, } from './write.js';
+export { applyFieldPatch, applyWrites, applySlotFilling, markAskedUnknown, isRowWrite, isStructuredWrites, normalizeWrites, type ApplySlotFillingOptions, type FieldPatchInput, } from './write.js';
 export type { ComputeFnMap, ComputeHost, ComputeHostOrFns, LocalComputeHostOptions, RecomputeOptions, } from './derived.js';
 export { createLocalComputeHost, createSourceComputeHost, resolveComputeHost, recomputeDerived, applyFieldPatchAndRecompute, applyWritesAndRecompute, applySlotFillingAndRecompute, } from './derived.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/slot/index.js

@@ -9,6 +9,6 @@ export { isValidDataTypeValue, validateExtractedField, validateBareValue } from
 export { buildSlotFillingJsonSchema, buildFieldCatalog } from './sf-schema.js';
 export { validateSlotFillingOutput } from './sf-validate.js';
 export { snapshotFrom, cloneSnapshot, getSingleField, getSnapshotTable } from './snapshot.js';
-export { applyFieldPatch, applyWrites, applySlotFilling, markAskedUnknown, } from './write.js';
+export { applyFieldPatch, applyWrites, applySlotFilling, markAskedUnknown, isRowWrite, isStructuredWrites, normalizeWrites, } from './write.js';
 export { createLocalComputeHost, createSourceComputeHost, resolveComputeHost, recomputeDerived, applyFieldPatchAndRecompute, applyWritesAndRecompute, applySlotFillingAndRecompute, } from './derived.js';
 //# sourceMappingURL=index.js.map

package/dist/core/slot/types.d.ts

@@ -23,6 +23,8 @@ export type FieldValue = {
 export type HistoryAppend = {
     path: FieldPath;
     entry: FieldHistoryEntry;
+    /** Set when the write targeted a specific snapshot row. */
+    rowId?: string;
 };
 export type ExtractedField = {
     reason: string;

package/dist/core/slot/write.d.ts

@@ -1,9 +1,16 @@
-import type { FieldState, Writes } from '../context/types.js';
+import type { FieldState, FieldWrites, RowWrite, StructuredWrites, Writes } from '../context/types.js';
 import type { FieldPath } from './path.js';
 import type { ApplyWritesOptions, ApplyWritesResult, CompiledSlotSchema, RuntimeSlotsSnapshot, SlotFillingOutput, UpdatedBy } from './types.js';
+export declare function isRowWrite(value: unknown): value is RowWrite;
+export declare function isStructuredWrites(value: unknown): value is StructuredWrites;
+export declare function normalizeWrites(writes: Writes | null | undefined): {
+    fields: FieldWrites;
+    rows: RowWrite[];
+} | null;
 /**
  * Apply bare Writes (function / human / import / platform) onto a snapshot.
  * Validates type/enum and write permissions. Detects C5 changes and appends history.
+ * Multi-row tables: pass `{ table, rowId, values }` (or `rows` on StructuredWrites).
  */
 export declare function applyWrites(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, writes: Writes | null | undefined, options: ApplyWritesOptions): ApplyWritesResult;
 export type FieldPatchInput = {