@superpanel-sdk/runtime 0.2.1 → 0.2.3

package/dist/builder/codegen/generate.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { withCompanyImportGraph } from '../company-import-graph.js';
 import { listSequenceIds, loadCompanySchema, loadSequenceSlots } from '../load.js';
 import { mergeEffectiveSchema } from '../merge.js';
 import { findTsModule, resolveTsModule } from '../paths.js';
@@ -12,6 +13,9 @@ function sequenceCaseContextGenPath(repoRoot, sequenceId) {
     return path.join(repoRoot, 'sequences', sequenceId, '__gen', 'case-context.type.ts');
 }
 export async function generateSequence(repoRoot, sequenceId, options = {}) {
+    return withCompanyImportGraph(repoRoot, () => generateSequenceInGraph(repoRoot, sequenceId, options));
+}
+async function generateSequenceInGraph(repoRoot, sequenceId, options) {
     const schemaPath = resolveTsModule(repoRoot, 'schema', `No company schema found. Expected schema.ts or schema/index.ts under ${repoRoot}`);
     const slotsPath = resolveTsModule(path.join(repoRoot, 'sequences', sequenceId), 'slots', `No sequence slots found. Expected sequences/${sequenceId}/slots.ts or sequences/${sequenceId}/slots/index.ts`);
     const company = await loadCompanySchema(schemaPath);
@@ -38,15 +42,17 @@ export async function generateSequence(repoRoot, sequenceId, options = {}) {
     };
 }
 export async function generateAll(repoRoot, options = {}) {
-    const ids = options.sequenceIds ?? listSequenceIds(repoRoot);
-    if (ids.length === 0) {
-        throw new Error(`No sequences with slots found under ${path.join(repoRoot, 'sequences')} (expected slots.ts or slots/index.ts)`);
-    }
-    const results = [];
-    for (const sequenceId of ids) {
-        results.push(await generateSequence(repoRoot, sequenceId, options));
-    }
-    return results;
+    return withCompanyImportGraph(repoRoot, async () => {
+        const ids = options.sequenceIds ?? listSequenceIds(repoRoot);
+        if (ids.length === 0) {
+            throw new Error(`No sequences with slots found under ${path.join(repoRoot, 'sequences')} (expected slots.ts or slots/index.ts)`);
+        }
+        const results = [];
+        for (const sequenceId of ids) {
+            results.push(await generateSequence(repoRoot, sequenceId, options));
+        }
+        return results;
+    });
 }
 function assertFileMatches(outPath, next, repoRoot) {
     let current = '';

package/dist/builder/company-import-graph.d.ts

@@ -0,0 +1,11 @@
+/** Stamp a company-repo entry URL, or return it unchanged outside a graph. */
+export declare function companyImportGraphHref(fileHref: string): string;
+/**
+ * Load company-repo modules as one ESM graph.
+ *
+ * Nested calls (same async context) reuse the graph so compile + overlay
+ * `loadSequenceFunctions` share object identity. Overlapping outer calls wait
+ * their turn, then bump generation so watch sees new source.
+ */
+export declare function withCompanyImportGraph<T>(repoRoot: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=company-import-graph.d.ts.map

package/dist/builder/company-import-graph.js

@@ -0,0 +1,105 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { realpathSync } from 'node:fs';
+import { registerHooks } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const COMPANY_GRAPH_GEN_QUERY = 'spgen';
+const COMPANY_GRAPH_ROOT_QUERY = 'sproot';
+const graph = new AsyncLocalStorage();
+let generation = 0;
+let registered = false;
+let outerTail = Promise.resolve();
+function filePathFromUrl(url) {
+    const parsed = new URL(url);
+    parsed.search = '';
+    parsed.hash = '';
+    return fileURLToPath(parsed);
+}
+function realPath(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return path.resolve(filePath);
+    }
+}
+function underRoot(filePath, root) {
+    const resolved = realPath(filePath);
+    const base = realPath(root);
+    return resolved === base || resolved.startsWith(`${base}${path.sep}`);
+}
+function inNodeModules(filePath, url) {
+    return (url.includes('/node_modules/') ||
+        url.includes('\\node_modules\\') ||
+        filePath.includes(`${path.sep}node_modules${path.sep}`));
+}
+function stampCompanyResolve(specifier, context, nextResolve) {
+    const result = nextResolve(specifier, context);
+    if (!result.url.startsWith('file:'))
+        return result;
+    const resolved = new URL(result.url);
+    if (resolved.searchParams.has(COMPANY_GRAPH_GEN_QUERY))
+        return result;
+    const parent = context.parentURL ? new URL(context.parentURL) : null;
+    const graphGeneration = parent?.searchParams.get(COMPANY_GRAPH_GEN_QUERY);
+    const repoRoot = parent?.searchParams.get(COMPANY_GRAPH_ROOT_QUERY);
+    if (!graphGeneration || !repoRoot)
+        return result;
+    let resolvedFile;
+    try {
+        resolvedFile = filePathFromUrl(result.url);
+    }
+    catch {
+        return result;
+    }
+    if (inNodeModules(resolvedFile, result.url))
+        return result;
+    if (!underRoot(resolvedFile, repoRoot))
+        return result;
+    resolved.searchParams.set(COMPANY_GRAPH_GEN_QUERY, graphGeneration);
+    resolved.searchParams.set(COMPANY_GRAPH_ROOT_QUERY, repoRoot);
+    return { ...result, url: resolved.href };
+}
+function ensureHookRegistered() {
+    if (registered)
+        return;
+    registered = true;
+    registerHooks({ resolve: stampCompanyResolve });
+}
+/** Stamp a company-repo entry URL, or return it unchanged outside a graph. */
+export function companyImportGraphHref(fileHref) {
+    const store = graph.getStore();
+    if (!store)
+        return fileHref;
+    const url = new URL(fileHref);
+    url.searchParams.set(COMPANY_GRAPH_GEN_QUERY, String(store.generation));
+    url.searchParams.set(COMPANY_GRAPH_ROOT_QUERY, store.repoRoot);
+    return url.href;
+}
+/**
+ * Load company-repo modules as one ESM graph.
+ *
+ * Nested calls (same async context) reuse the graph so compile + overlay
+ * `loadSequenceFunctions` share object identity. Overlapping outer calls wait
+ * their turn, then bump generation so watch sees new source.
+ */
+export async function withCompanyImportGraph(repoRoot, fn) {
+    ensureHookRegistered();
+    if (graph.getStore())
+        return fn();
+    const root = realpathSync(path.resolve(repoRoot));
+    let release;
+    const previous = outerTail;
+    outerTail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    generation += 1;
+    try {
+        return await graph.run({ generation, repoRoot: root }, fn);
+    }
+    finally {
+        release();
+    }
+}
+//# sourceMappingURL=company-import-graph.js.map

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/builder/compile/compile-sequence.d.ts

@@ -1,8 +1,9 @@
 import type { FuncMap } from '../../core/functions/types.js';
 import type { CompanySchema } from '../../core/slot/schema.js';
-import type { SequenceBuild } from '../types.js';
+import type { RuntimePackageSource, SequenceBuild } from '../types.js';
 /** SequenceBuild / SequenceConfigBuild cache key. Bump when compiled `code` shape changes. */
 export declare function runtimePackageVersion(): string;
+export declare function runtimePackageSource(repoRoot: string): RuntimePackageSource;
 /** Deep-clone company schema with derived computeFn normalized to string names. */
 export declare function snapshotCompanySchema(company: CompanySchema, functions?: FuncMap): CompanySchema;
 export declare function sequenceBuildPath(repoRoot: string, sequenceId: string): string;
@@ -12,6 +13,8 @@ export type CompileSequenceOptions = {
     includeCode?: boolean;
     /** Persist on SequenceBuild.sha. Defaults to `local`. */
     sha?: string;
+    /** Dependency source captured before deployment rewrites package.json. */
+    runtimeSource?: RuntimePackageSource;
 };
 export type CompileSequenceResult = {
     sequenceId: string;

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

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { resolveCaseContextViewFn } from '../../core/functions/define/case-context.js';
 import { resolveFuncName } from '../../core/functions/func-ref.js';
 import { compileSlotSchema } from '../../core/slot/compile-schema.js';
+import { withCompanyImportGraph } from '../company-import-graph.js';
 import { listSequenceIds, loadCompanySchema, loadSequenceAgendas, loadSequenceCaseContextView, loadSequenceFunctions, loadSequenceSlots, } from '../load.js';
 import { findTsModule, resolveTsModule } from '../paths.js';
 import { compileSequenceAgendas, fatalAgendaIssues } from './compile-agenda.js';
@@ -27,6 +28,18 @@ export function runtimePackageVersion() {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
     return pkg.version ?? '0.0.0';
 }
+export function runtimePackageSource(repoRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+        const spec = pkg.dependencies?.['@superpanel-sdk/runtime'] ??
+            pkg.devDependencies?.['@superpanel-sdk/runtime'] ??
+            pkg.optionalDependencies?.['@superpanel-sdk/runtime'];
+        return spec?.startsWith('file:') || spec?.startsWith('workspace:') ? 'local-file' : 'npm';
+    }
+    catch {
+        return 'npm';
+    }
+}
 /** Deep-clone company schema with derived computeFn normalized to string names. */
 export function snapshotCompanySchema(company, functions) {
     const tables = {};
@@ -51,6 +64,9 @@ export function sequenceBuildPath(repoRoot, sequenceId) {
     return path.join(repoRoot, 'sequences', sequenceId, 'build', 'sequence-build.json');
 }
 export async function compileSequence(repoRoot, sequenceId, options = {}) {
+    return withCompanyImportGraph(repoRoot, () => compileSequenceInGraph(repoRoot, sequenceId, options));
+}
+async function compileSequenceInGraph(repoRoot, sequenceId, options) {
     const schemaPath = resolveTsModule(repoRoot, 'schema', `No company schema found. Expected schema.ts or schema/index.ts under ${repoRoot}`);
     const sequenceDir = path.join(repoRoot, 'sequences', sequenceId);
     const slotsPath = resolveTsModule(sequenceDir, 'slots', `No sequence slots found. Expected sequences/${sequenceId}/slots.ts or sequences/${sequenceId}/slots/index.ts`);
@@ -92,6 +108,7 @@ export async function compileSequence(repoRoot, sequenceId, options = {}) {
         sequenceId,
         sha: options.sha ?? 'local',
         engineVersion: runtimePackageVersion(),
+        runtimeSource: options.runtimeSource ?? runtimePackageSource(repoRoot),
         compiledAt: new Date().toISOString(),
         companySchemaSnapshot: snapshotCompanySchema(company, functions),
         schema: compiledAgendas.schema,
@@ -108,14 +125,16 @@ export async function compileSequence(repoRoot, sequenceId, options = {}) {
     return { sequenceId, outPath, build, wrote: !options.dryRun };
 }
 export async function compileAll(repoRoot, options = {}) {
-    const ids = options.sequenceIds ?? listSequenceIds(repoRoot);
-    if (ids.length === 0) {
-        throw new Error(`No sequences with slots found under ${path.join(repoRoot, 'sequences')} (expected slots.ts or slots/index.ts)`);
-    }
-    const results = [];
-    for (const sequenceId of ids) {
-        results.push(await compileSequence(repoRoot, sequenceId, options));
-    }
-    return results;
+    return withCompanyImportGraph(repoRoot, async () => {
+        const ids = options.sequenceIds ?? listSequenceIds(repoRoot);
+        if (ids.length === 0) {
+            throw new Error(`No sequences with slots found under ${path.join(repoRoot, 'sequences')} (expected slots.ts or slots/index.ts)`);
+        }
+        const results = [];
+        for (const sequenceId of ids) {
+            results.push(await compileSequence(repoRoot, sequenceId, options));
+        }
+        return results;
+    });
 }
 //# sourceMappingURL=compile-sequence.js.map

package/dist/builder/load.js

@@ -3,11 +3,11 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { resolveCaseContextViewFn } from '../core/functions/define/case-context.js';
 import { isAgendaTree, isSequenceAgendas } from '../core/stage/flatten.js';
+import { companyImportGraphHref } from './company-import-graph.js';
 import { findTsModule } from './paths.js';
 async function importModule(filePath) {
-    const href = pathToFileURL(filePath).href;
-    // Cache-bust so --watch reloads edited TS modules.
-    const mod = await import(`${href}?t=${Date.now()}`);
+    const href = companyImportGraphHref(pathToFileURL(filePath).href);
+    const mod = await import(href);
     return mod;
 }
 function isFuncMap(value) {

package/dist/builder/types.d.ts

@@ -2,6 +2,7 @@ import type { CaseContextViewRegistryEntry, FunctionRegistry } from '../core/fun
 import type { CompanySchema, EffectiveSchema } from '../core/slot/schema.js';
 import type { CompiledSlotSchema } from '../core/slot/types.js';
 import type { CompiledAgenda } from '../core/stage/types.js';
+export type RuntimePackageSource = 'local-file' | 'npm';
 /**
  * Compiled sequence artifact (Manual §9 subset; grows over time).
  * Omitted for now: paramsDefaults, schedulers, caseManual.
@@ -13,6 +14,10 @@ export type SequenceBuild = {
     sequenceId: string;
     sha: string;
     engineVersion: string;
+    /** Installed @superpanel-sdk/runtime version resolved from the company repo. */
+    runtimeVersion?: string;
+    /** Dependency source declared by the company repo. Optional for legacy persisted builds. */
+    runtimeSource?: RuntimePackageSource;
     compiledAt: string;
     companySchemaSnapshot: CompanySchema;
     /** SlotEngine runtime schema (tables + derivedOrder / reverseDeps). */

package/dist/cli/serve/index.js

@@ -1,9 +1,11 @@
 import path from 'node:path';
 import chokidar from 'chokidar';
 import { compileAll } from '../../builder/compile/compile-sequence.js';
+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) {
@@ -26,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);
@@ -37,30 +53,34 @@ function isSchemaPath(repoRoot, file) {
     return rel === 'schema.ts' || rel.startsWith(`schema${path.sep}`) || rel.startsWith('schema/');
 }
 async function loadOne(repoRoot, sequenceId, generation) {
-    const [compiled] = await compileAll(repoRoot, {
-        sequenceIds: [sequenceId],
-        dryRun: true,
-        includeCode: false,
+    return withCompanyImportGraph(repoRoot, async () => {
+        const [compiled] = await compileAll(repoRoot, {
+            sequenceIds: [sequenceId],
+            dryRun: true,
+            includeCode: false,
+        });
+        if (!compiled) {
+            throw new Error(`Failed to compile sequence ${sequenceId}`);
+        }
+        const sequenceDir = path.join(repoRoot, 'sequences', sequenceId);
+        const functionsPath = findTsModule(sequenceDir, 'functions');
+        if (!functionsPath) {
+            throw new Error(`No functions module for sequence ${sequenceId}`);
+        }
+        const functions = await loadSequenceFunctions(functionsPath);
+        const viewPath = findTsModule(sequenceDir, 'view');
+        const view = viewPath ? await loadSequenceCaseContextView(viewPath) : undefined;
+        return { build: compiled.build, functions, view, generation };
     });
-    if (!compiled) {
-        throw new Error(`Failed to compile sequence ${sequenceId}`);
-    }
-    const sequenceDir = path.join(repoRoot, 'sequences', sequenceId);
-    const functionsPath = findTsModule(sequenceDir, 'functions');
-    if (!functionsPath) {
-        throw new Error(`No functions module for sequence ${sequenceId}`);
-    }
-    const functions = await loadSequenceFunctions(functionsPath);
-    const viewPath = findTsModule(sequenceDir, 'view');
-    const view = viewPath ? await loadSequenceCaseContextView(viewPath) : undefined;
-    return { build: compiled.build, functions, view, generation };
 }
 async function loadSequences(repoRoot, sequenceIds, generation) {
-    const out = new Map();
-    for (const sequenceId of sequenceIds) {
-        out.set(sequenceId, await loadOne(repoRoot, sequenceId, generation));
-    }
-    return out;
+    return withCompanyImportGraph(repoRoot, async () => {
+        const out = new Map();
+        for (const sequenceId of sequenceIds) {
+            out.set(sequenceId, await loadOne(repoRoot, sequenceId, generation));
+        }
+        return out;
+    });
 }
 function send(ws, message) {
     ws.send(encodeOverlayMessage(message));
@@ -68,12 +88,20 @@ 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.engineVersion,
+        runtimeSource: loaded.build.runtimeSource ?? 'npm',
         getRequestId: () => message.logRequestId,
         getTags: () => message.logTags,
     });
@@ -94,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 {
@@ -139,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);
@@ -149,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;
@@ -178,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 });
             }
@@ -198,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) => {
@@ -215,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);
@@ -234,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')}`);
@@ -242,39 +293,48 @@ 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;
     let pending = { all: false, ids: new Set() };
+    let flushing = false;
     const flush = () => {
-        const job = pending;
-        pending = { all: false, ids: new Set() };
+        if (flushing)
+            return;
+        flushing = true;
         void (async () => {
             try {
-                generation += 1;
-                const ids = job.all ? sequenceIds : [...job.ids];
-                if (job.all) {
-                    const next = await loadSequences(repoRoot, sequenceIds, generation);
-                    sequences.clear();
+                while (pending.all || pending.ids.size > 0) {
+                    const job = pending;
+                    pending = { all: false, ids: new Set() };
+                    generation += 1;
+                    const ids = job.all ? sequenceIds : [...job.ids];
+                    const next = await loadSequences(repoRoot, ids, generation);
+                    if (job.all)
+                        sequences.clear();
                     for (const [id, loaded] of next)
                         sequences.set(id, loaded);
-                }
-                else {
-                    for (const sequenceId of ids) {
-                        sequences.set(sequenceId, await loadOne(repoRoot, sequenceId, generation));
+                    if (socket && socket.readyState === WebSocket.OPEN) {
+                        pushOverlays(socket, sequences);
+                        console.log(`reloaded sequences ${ids.join(', ')}`);
                     }
                 }
-                if (socket && socket.readyState === WebSocket.OPEN) {
-                    pushOverlays(socket, sequences);
-                    console.log(`reloaded sequences ${ids.join(', ')}`);
-                }
             }
             catch (error) {
                 console.error('reload failed:', error instanceof Error ? error.message : error);
             }
+            finally {
+                flushing = false;
+                if (pending.all || pending.ids.size > 0)
+                    flush();
+            }
         })();
     };
     chokidar
@@ -316,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