@go-go-golems/os-scripting 0.1.0

package/plugin-runtime/jsSessionService.js

@@ -0,0 +1,136 @@
+import { createQuickJsSessionVm, disposeQuickJsSessionVm, evalQuickJsCodeOrThrow, evalQuickJsToNative, } from './quickJsSessionCore';
+import { evaluateQuickJsSessionJs, getQuickJsSessionGlobalNames, installJsEvalBridge, } from './jsEvalSupport';
+const DEFAULT_OPTIONS = {
+    memoryLimitBytes: 32 * 1024 * 1024,
+    stackLimitBytes: 1024 * 1024,
+    loadTimeoutMs: 1000,
+    evalTimeoutMs: 100,
+    inspectTimeoutMs: 50,
+};
+function normalizeOptions(options) {
+    return {
+        ...DEFAULT_OPTIONS,
+        ...options,
+    };
+}
+function toCoreOptions(options) {
+    return {
+        memoryLimitBytes: options.memoryLimitBytes,
+        stackLimitBytes: options.stackLimitBytes,
+        loadTimeoutMs: options.loadTimeoutMs,
+    };
+}
+export class JsSessionService {
+    options;
+    sessions = new Map();
+    constructor(options = {}) {
+        this.options = normalizeOptions(options);
+    }
+    getRecordOrThrow(sessionId) {
+        const record = this.sessions.get(sessionId);
+        if (!record) {
+            throw new Error(`JS session not found: ${sessionId}`);
+        }
+        return record;
+    }
+    async createRecord(request) {
+        const bootstrapSources = [
+            ...(request.bootstrapSources ?? []),
+        ];
+        if (request.preludeCode && request.preludeCode.trim().length > 0) {
+            bootstrapSources.push({
+                code: request.preludeCode,
+                filename: `${request.sessionId}.prelude.js`,
+            });
+        }
+        const vm = await createQuickJsSessionVm(request.scopeId?.trim() || 'js-repl', request.sessionId, toCoreOptions(this.options), bootstrapSources);
+        installJsEvalBridge(vm, 'js-repl-bootstrap.js', this.options.loadTimeoutMs);
+        return {
+            vm,
+            title: request.title?.trim() || request.sessionId,
+            createdAt: new Date().toISOString(),
+            scopeId: request.scopeId?.trim() || 'js-repl',
+            preludeCode: request.preludeCode,
+            bootstrapSources: [...(request.bootstrapSources ?? [])],
+        };
+    }
+    async createSession(request) {
+        if (this.sessions.has(request.sessionId)) {
+            throw new Error(`JS session already exists: ${request.sessionId}`);
+        }
+        const record = await this.createRecord(request);
+        this.sessions.set(request.sessionId, record);
+        return this.getSummary(request.sessionId);
+    }
+    getSummary(sessionId) {
+        const record = this.getRecordOrThrow(sessionId);
+        return {
+            sessionId,
+            title: record.title,
+            createdAt: record.createdAt,
+            globalNames: this.getGlobalNames(sessionId),
+        };
+    }
+    listSessions() {
+        return Array.from(this.sessions.keys())
+            .sort()
+            .map((sessionId) => this.getSummary(sessionId));
+    }
+    evaluate(sessionId, code) {
+        const record = this.getRecordOrThrow(sessionId);
+        return evaluateQuickJsSessionJs(record.vm, code, `${sessionId}.eval.js`, this.options.evalTimeoutMs, this.options.inspectTimeoutMs);
+    }
+    evaluateToNative(sessionId, code, filename, timeoutMs) {
+        const record = this.getRecordOrThrow(sessionId);
+        return evalQuickJsToNative(record.vm, code, filename, timeoutMs);
+    }
+    runCode(sessionId, code, filename, timeoutMs) {
+        const record = this.getRecordOrThrow(sessionId);
+        evalQuickJsCodeOrThrow(record.vm, code, filename, timeoutMs);
+    }
+    getGlobalNames(sessionId) {
+        const record = this.getRecordOrThrow(sessionId);
+        return getQuickJsSessionGlobalNames(record.vm, `${sessionId}.globals.js`, this.options.inspectTimeoutMs);
+    }
+    async resetSession(sessionId) {
+        const record = this.getRecordOrThrow(sessionId);
+        disposeQuickJsSessionVm(record.vm);
+        const nextRecord = await this.createRecord({
+            sessionId,
+            title: record.title,
+            scopeId: record.scopeId,
+            preludeCode: record.preludeCode,
+            bootstrapSources: record.bootstrapSources,
+        });
+        this.sessions.set(sessionId, {
+            ...nextRecord,
+            createdAt: record.createdAt,
+        });
+        return this.getSummary(sessionId);
+    }
+    disposeSession(sessionId) {
+        const record = this.sessions.get(sessionId);
+        if (!record) {
+            return false;
+        }
+        this.sessions.delete(sessionId);
+        disposeQuickJsSessionVm(record.vm);
+        return true;
+    }
+    clear() {
+        for (const record of this.sessions.values()) {
+            disposeQuickJsSessionVm(record.vm);
+        }
+        this.sessions.clear();
+    }
+    health() {
+        return {
+            ready: true,
+            sessions: Array.from(this.sessions.keys()).sort(),
+        };
+    }
+    installPrelude(sessionId, code) {
+        const record = this.getRecordOrThrow(sessionId);
+        evalQuickJsCodeOrThrow(record.vm, code, `${sessionId}.install-prelude.js`, this.options.loadTimeoutMs);
+    }
+}

package/plugin-runtime/quickJsSessionCore.d.ts

@@ -0,0 +1,24 @@
+import type { QuickJSContext, QuickJSRuntime, QuickJSWASMModule } from 'quickjs-emscripten-core';
+export interface QuickJsSessionCoreOptions {
+    memoryLimitBytes: number;
+    stackLimitBytes: number;
+    loadTimeoutMs: number;
+}
+export interface QuickJsSessionVm {
+    scopeId: string;
+    sessionId: string;
+    runtime: QuickJSRuntime;
+    context: QuickJSContext;
+    deadlineMs: number;
+}
+export declare function getSharedQuickJsModule(): Promise<QuickJSWASMModule>;
+export declare function toJsLiteral(value: unknown): string;
+export declare function formatQuickJSError(errorDump: unknown): string;
+export declare function withDeadline<T>(vm: QuickJsSessionVm, timeoutMs: number, fn: () => T): T;
+export declare function evalQuickJsToNative<T>(vm: QuickJsSessionVm, code: string, filename: string, timeoutMs: number): T;
+export declare function evalQuickJsCodeOrThrow(vm: QuickJsSessionVm, code: string, filename: string, timeoutMs: number): void;
+export declare function createQuickJsSessionVm(scopeId: string, sessionId: string, options: QuickJsSessionCoreOptions, bootstrapSources?: Array<{
+    code: string;
+    filename: string;
+}>): Promise<QuickJsSessionVm>;
+export declare function disposeQuickJsSessionVm(vm: QuickJsSessionVm): void;

package/plugin-runtime/quickJsSessionCore.js

@@ -0,0 +1,92 @@
+import SINGLEFILE_RELEASE_SYNC from '@jitl/quickjs-singlefile-mjs-release-sync';
+import { newQuickJSWASMModule } from 'quickjs-emscripten';
+let quickJsModulePromise = null;
+export function getSharedQuickJsModule() {
+    if (!quickJsModulePromise) {
+        quickJsModulePromise = newQuickJSWASMModule(SINGLEFILE_RELEASE_SYNC);
+    }
+    return quickJsModulePromise;
+}
+export function toJsLiteral(value) {
+    const encoded = JSON.stringify(value);
+    return encoded === undefined ? 'undefined' : encoded;
+}
+export function formatQuickJSError(errorDump) {
+    if (typeof errorDump === 'string') {
+        return errorDump;
+    }
+    if (errorDump && typeof errorDump === 'object') {
+        const details = errorDump;
+        if (details.name && details.message) {
+            return `${details.name}: ${details.message}`;
+        }
+        if (details.message) {
+            return details.message;
+        }
+    }
+    return 'Unknown QuickJS runtime error';
+}
+export function withDeadline(vm, timeoutMs, fn) {
+    vm.deadlineMs = Date.now() + timeoutMs;
+    try {
+        return fn();
+    }
+    finally {
+        vm.deadlineMs = Number.POSITIVE_INFINITY;
+    }
+}
+export function evalQuickJsToNative(vm, code, filename, timeoutMs) {
+    const context = vm.context;
+    const result = withDeadline(vm, timeoutMs, () => context.evalCode(code, filename));
+    if (result.error) {
+        const dumped = context.dump(result.error);
+        result.error.dispose();
+        throw new Error(formatQuickJSError(dumped));
+    }
+    try {
+        return context.dump(result.value);
+    }
+    finally {
+        result.value.dispose();
+    }
+}
+export function evalQuickJsCodeOrThrow(vm, code, filename, timeoutMs) {
+    const context = vm.context;
+    const result = withDeadline(vm, timeoutMs, () => context.evalCode(code, filename));
+    if (result.error) {
+        const dumped = context.dump(result.error);
+        result.error.dispose();
+        throw new Error(formatQuickJSError(dumped));
+    }
+    result.value.dispose();
+}
+export async function createQuickJsSessionVm(scopeId, sessionId, options, bootstrapSources = []) {
+    const QuickJS = await getSharedQuickJsModule();
+    const runtime = QuickJS.newRuntime();
+    const context = runtime.newContext();
+    const vm = {
+        scopeId,
+        sessionId,
+        runtime,
+        context,
+        deadlineMs: Number.POSITIVE_INFINITY,
+    };
+    runtime.setMemoryLimit(options.memoryLimitBytes);
+    runtime.setMaxStackSize(options.stackLimitBytes);
+    runtime.setInterruptHandler(() => Date.now() > vm.deadlineMs);
+    try {
+        for (const source of bootstrapSources) {
+            evalQuickJsCodeOrThrow(vm, source.code, source.filename, options.loadTimeoutMs);
+        }
+        return vm;
+    }
+    catch (error) {
+        context.dispose();
+        runtime.dispose();
+        throw error;
+    }
+}
+export function disposeQuickJsSessionVm(vm) {
+    vm.context.dispose();
+    vm.runtime.dispose();
+}

package/plugin-runtime/runtimeService.d.ts

@@ -0,0 +1,34 @@
+import type { RuntimeSurfaceId, RuntimeBundleMeta, RuntimeErrorPayload, RuntimeAction, SessionId, StackId } from './contracts';
+import { type JsEvalResult } from './jsSessionService';
+export interface QuickJSRuntimeServiceOptions {
+    memoryLimitBytes?: number;
+    stackLimitBytes?: number;
+    loadTimeoutMs?: number;
+    renderTimeoutMs?: number;
+    eventTimeoutMs?: number;
+}
+export declare function toRuntimeError(error: unknown): RuntimeErrorPayload;
+export declare class QuickJSRuntimeService {
+    private readonly options;
+    private readonly sessionService;
+    private readonly bundles;
+    private readonly instanceId;
+    constructor(options?: QuickJSRuntimeServiceOptions);
+    private getBundleOrThrow;
+    private readRuntimeBundleMeta;
+    private installRuntimePackages;
+    loadRuntimeBundle(stackId: StackId, sessionId: SessionId, packageIds: string[], code: string): Promise<RuntimeBundleMeta>;
+    defineRuntimeSurface(sessionId: SessionId, surfaceId: RuntimeSurfaceId, code: string, packId: string): RuntimeBundleMeta;
+    defineRuntimeSurfaceRender(sessionId: SessionId, surfaceId: RuntimeSurfaceId, code: string): RuntimeBundleMeta;
+    defineRuntimeSurfaceHandler(sessionId: SessionId, surfaceId: RuntimeSurfaceId, handler: string, code: string): RuntimeBundleMeta;
+    getRuntimeBundleMeta(sessionId: SessionId): RuntimeBundleMeta;
+    evaluateSessionJs(sessionId: SessionId, code: string): JsEvalResult;
+    getSessionGlobalNames(sessionId: SessionId): string[];
+    renderRuntimeSurface(sessionId: SessionId, surfaceId: RuntimeSurfaceId, state: unknown): unknown;
+    eventRuntimeSurface(sessionId: SessionId, surfaceId: RuntimeSurfaceId, handler: string, args: unknown, state: unknown): RuntimeAction[];
+    disposeSession(sessionId: SessionId): boolean;
+    health(): {
+        ready: true;
+        sessions: string[];
+    };
+}

package/plugin-runtime/runtimeService.js

@@ -0,0 +1,248 @@
+import { validateRuntimeActions } from './intentSchema';
+import { getRuntimePackageOrThrow, resolveRuntimePackageInstallOrder } from '../runtime-packages';
+import { getRuntimeSurfaceTypeOrThrow } from '../runtime-packs';
+import stackBootstrapSource from './stack-bootstrap.vm.js?raw';
+import { toJsLiteral } from './quickJsSessionCore';
+import { JsSessionService } from './jsSessionService';
+const DEFAULT_OPTIONS = {
+    memoryLimitBytes: 32 * 1024 * 1024,
+    stackLimitBytes: 1024 * 1024,
+    loadTimeoutMs: 1000,
+    renderTimeoutMs: 100,
+    eventTimeoutMs: 100,
+};
+let runtimeServiceInstanceCounter = 1;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validateRuntimeBundleMeta(stackId, sessionId, value) {
+    if (!isRecord(value)) {
+        throw new Error('Runtime bundle metadata must be an object');
+    }
+    const packageIds = value.packageIds;
+    if (!Array.isArray(packageIds) || packageIds.some((packageId) => typeof packageId !== 'string')) {
+        throw new Error('Runtime bundle metadata packageIds must be string[]');
+    }
+    const surfaces = value.surfaces;
+    if (!Array.isArray(surfaces) || surfaces.some((surfaceId) => typeof surfaceId !== 'string')) {
+        throw new Error('Runtime bundle metadata surfaces must be string[]');
+    }
+    const initialSurfaceState = value.initialSurfaceState;
+    if (initialSurfaceState !== undefined && !isRecord(initialSurfaceState)) {
+        throw new Error('Runtime bundle metadata initialSurfaceState must be an object when provided');
+    }
+    const surfaceTypes = value.surfaceTypes;
+    if (surfaceTypes !== undefined) {
+        if (!isRecord(surfaceTypes)) {
+            throw new Error('Runtime bundle metadata surfaceTypes must be an object when provided');
+        }
+        for (const [surfaceId, surfaceTypeId] of Object.entries(surfaceTypes)) {
+            if (typeof surfaceId !== 'string' || typeof surfaceTypeId !== 'string') {
+                throw new Error('Runtime bundle metadata surfaceTypes must be Record<string, string>');
+            }
+        }
+    }
+    return {
+        stackId,
+        sessionId,
+        declaredId: typeof value.declaredId === 'string' ? value.declaredId : undefined,
+        title: typeof value.title === 'string' ? value.title : 'Untitled Stack',
+        description: typeof value.description === 'string' ? value.description : undefined,
+        packageIds: packageIds.filter((packageId) => typeof packageId === 'string'),
+        initialSessionState: value.initialSessionState,
+        initialSurfaceState,
+        surfaces,
+        surfaceTypes: isRecord(surfaceTypes) ? Object.fromEntries(Object.entries(surfaceTypes).filter((entry) => typeof entry[1] === 'string')) : undefined,
+    };
+}
+export function toRuntimeError(error) {
+    if (error instanceof Error) {
+        const interrupted = error.message.includes('interrupted');
+        return {
+            code: interrupted ? 'RUNTIME_TIMEOUT' : 'RUNTIME_ERROR',
+            message: error.message,
+        };
+    }
+    return {
+        code: 'UNKNOWN_ERROR',
+        message: String(error),
+    };
+}
+export class QuickJSRuntimeService {
+    options;
+    sessionService;
+    bundles = new Map();
+    instanceId;
+    constructor(options = {}) {
+        this.instanceId = `runtime-service-${runtimeServiceInstanceCounter++}`;
+        this.options = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+        };
+        this.sessionService = new JsSessionService({
+            memoryLimitBytes: this.options.memoryLimitBytes,
+            stackLimitBytes: this.options.stackLimitBytes,
+            loadTimeoutMs: this.options.loadTimeoutMs,
+            evalTimeoutMs: this.options.eventTimeoutMs,
+            inspectTimeoutMs: this.options.loadTimeoutMs,
+        });
+        console.log('[QuickJSRuntimeService] Created service instance', {
+            instanceId: this.instanceId,
+            options: this.options,
+        });
+    }
+    getBundleOrThrow(sessionId) {
+        const bundle = this.bundles.get(sessionId);
+        if (!bundle) {
+            console.error('[QuickJSRuntimeService] Runtime session not found', {
+                instanceId: this.instanceId,
+                sessionId,
+                availableSessions: Array.from(this.bundles.keys()),
+            });
+            throw new Error(`Runtime session not found: ${sessionId}`);
+        }
+        return bundle;
+    }
+    readRuntimeBundleMeta(stackId, sessionId) {
+        const meta = this.sessionService.evaluateToNative(sessionId, 'globalThis.__runtimeBundleHost.getMeta()', 'runtime-bundle-meta.js', this.options.loadTimeoutMs);
+        return validateRuntimeBundleMeta(stackId, sessionId, meta);
+    }
+    installRuntimePackages(sessionId, packageIds) {
+        const orderedPackageIds = resolveRuntimePackageInstallOrder(packageIds);
+        for (const packageId of orderedPackageIds) {
+            const runtimePackage = getRuntimePackageOrThrow(packageId);
+            this.sessionService.installPrelude(sessionId, runtimePackage.installPrelude);
+        }
+        return orderedPackageIds;
+    }
+    async loadRuntimeBundle(stackId, sessionId, packageIds, code) {
+        if (this.bundles.has(sessionId)) {
+            console.warn('[QuickJSRuntimeService] Refusing to load duplicate runtime session', {
+                instanceId: this.instanceId,
+                stackId,
+                sessionId,
+                availableSessions: Array.from(this.bundles.keys()),
+            });
+            throw new Error(`Runtime session already exists: ${sessionId}`);
+        }
+        console.log('[QuickJSRuntimeService] Loading runtime bundle', {
+            instanceId: this.instanceId,
+            stackId,
+            sessionId,
+            packageIds,
+            codeLength: code.length,
+            beforeSessions: Array.from(this.bundles.keys()),
+        });
+        try {
+            await this.sessionService.createSession({
+                sessionId,
+                title: stackId,
+                scopeId: stackId,
+                bootstrapSources: [{ code: stackBootstrapSource, filename: 'stack-bootstrap.js' }],
+            });
+            const installedPackageIds = this.installRuntimePackages(sessionId, packageIds);
+            this.sessionService.runCode(sessionId, code, `${sessionId}.runtime-bundle.js`, this.options.loadTimeoutMs);
+            const bundle = this.readRuntimeBundleMeta(stackId, sessionId);
+            const declared = Array.from(new Set(bundle.packageIds)).sort();
+            const installed = Array.from(new Set(installedPackageIds)).sort();
+            if (declared.length !== installed.length || declared.some((packageId, index) => packageId !== installed[index])) {
+                throw new Error(`Runtime bundle packageIds mismatch. Declared: ${declared.join(', ') || '(none)'}; installed: ${installed.join(', ') || '(none)'}`);
+            }
+            this.bundles.set(sessionId, bundle);
+            console.log('[QuickJSRuntimeService] Loaded runtime bundle', {
+                instanceId: this.instanceId,
+                stackId,
+                sessionId,
+                declaredPackageIds: bundle.packageIds,
+                surfaces: bundle.surfaces,
+                afterSessions: Array.from(this.bundles.keys()),
+            });
+            return bundle;
+        }
+        catch (error) {
+            console.error('[QuickJSRuntimeService] Failed to load runtime bundle', {
+                instanceId: this.instanceId,
+                stackId,
+                sessionId,
+                packageIds,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            this.sessionService.disposeSession(sessionId);
+            this.bundles.delete(sessionId);
+            throw error;
+        }
+    }
+    defineRuntimeSurface(sessionId, surfaceId, code, packId) {
+        const bundle = this.getBundleOrThrow(sessionId);
+        const normalizedPackId = typeof packId === 'string' ? packId.trim() : '';
+        if (!normalizedPackId) {
+            throw new Error(`Runtime surface packId is required for ${surfaceId}`);
+        }
+        getRuntimeSurfaceTypeOrThrow(normalizedPackId);
+        this.sessionService.runCode(sessionId, `globalThis.__runtimeBundleHost.defineRuntimeSurface(${toJsLiteral(surfaceId)}, (${code}), ${toJsLiteral(normalizedPackId)})`, `${sessionId}.define-runtime-surface.js`, this.options.loadTimeoutMs);
+        const next = this.readRuntimeBundleMeta(bundle.stackId, sessionId);
+        this.bundles.set(sessionId, next);
+        return next;
+    }
+    defineRuntimeSurfaceRender(sessionId, surfaceId, code) {
+        const bundle = this.getBundleOrThrow(sessionId);
+        this.sessionService.runCode(sessionId, `globalThis.__runtimeBundleHost.defineRuntimeSurfaceRender(${toJsLiteral(surfaceId)}, (${code}))`, `${sessionId}.define-runtime-surface-render.js`, this.options.loadTimeoutMs);
+        const next = this.readRuntimeBundleMeta(bundle.stackId, sessionId);
+        this.bundles.set(sessionId, next);
+        return next;
+    }
+    defineRuntimeSurfaceHandler(sessionId, surfaceId, handler, code) {
+        const bundle = this.getBundleOrThrow(sessionId);
+        this.sessionService.runCode(sessionId, `globalThis.__runtimeBundleHost.defineRuntimeSurfaceHandler(${toJsLiteral(surfaceId)}, ${toJsLiteral(handler)}, (${code}))`, `${sessionId}.define-runtime-surface-handler.js`, this.options.loadTimeoutMs);
+        const next = this.readRuntimeBundleMeta(bundle.stackId, sessionId);
+        this.bundles.set(sessionId, next);
+        return next;
+    }
+    getRuntimeBundleMeta(sessionId) {
+        const bundle = this.getBundleOrThrow(sessionId);
+        const next = this.readRuntimeBundleMeta(bundle.stackId, sessionId);
+        this.bundles.set(sessionId, next);
+        return next;
+    }
+    evaluateSessionJs(sessionId, code) {
+        this.getBundleOrThrow(sessionId);
+        return this.sessionService.evaluate(sessionId, code);
+    }
+    getSessionGlobalNames(sessionId) {
+        this.getBundleOrThrow(sessionId);
+        return this.sessionService.getGlobalNames(sessionId);
+    }
+    renderRuntimeSurface(sessionId, surfaceId, state) {
+        this.getBundleOrThrow(sessionId);
+        return this.sessionService.evaluateToNative(sessionId, `globalThis.__runtimeBundleHost.renderRuntimeSurface(${toJsLiteral(surfaceId)}, ${toJsLiteral(state)})`, `${sessionId}.render-runtime-surface.js`, this.options.renderTimeoutMs);
+    }
+    eventRuntimeSurface(sessionId, surfaceId, handler, args, state) {
+        this.getBundleOrThrow(sessionId);
+        const actions = this.sessionService.evaluateToNative(sessionId, `globalThis.__runtimeBundleHost.eventRuntimeSurface(${toJsLiteral(surfaceId)}, ${toJsLiteral(handler)}, ${toJsLiteral(args)}, ${toJsLiteral(state)})`, `${sessionId}.event-runtime-surface.js`, this.options.eventTimeoutMs);
+        return validateRuntimeActions(actions);
+    }
+    disposeSession(sessionId) {
+        if (!this.bundles.has(sessionId)) {
+            console.warn('[QuickJSRuntimeService] disposeSession missed', {
+                instanceId: this.instanceId,
+                sessionId,
+                availableSessions: Array.from(this.bundles.keys()),
+            });
+            return false;
+        }
+        this.bundles.delete(sessionId);
+        this.sessionService.disposeSession(sessionId);
+        console.log('[QuickJSRuntimeService] Disposed runtime session', {
+            instanceId: this.instanceId,
+            sessionId,
+            remainingSessions: Array.from(this.bundles.keys()),
+        });
+        return true;
+    }
+    health() {
+        return {
+            ready: true,
+            sessions: Array.from(this.bundles.keys()),
+        };
+    }
+}

package/plugin-runtime/runtimeSurfaceRegistry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Global registry of runtime surface definitions that need to be injected
+ * into runtime sessions after bundle loading.
+ *
+ * Flow:
+ * 1. Chat receives card.v2 event → calls registerRuntimeSurface(surfaceId, code, packId)
+ * 2. RuntimeSurfaceSessionHost finishes loadRuntimeBundle → calls injectPendingRuntimeSurfaces(service, sessionId)
+ * 3. injectPendingRuntimeSurfaces iterates the registry, calls service.defineRuntimeSurface() for each
+ */
+export interface RuntimeSurfaceDefinition {
+    surfaceId: string;
+    code: string;
+    packId: string;
+    registeredAt: number;
+}
+export interface RuntimeSurfaceInjectionFailure {
+    surfaceId: string;
+    error: string;
+}
+export interface RuntimeSurfaceInjectionResult {
+    injected: string[];
+    failed: RuntimeSurfaceInjectionFailure[];
+}
+/** Register a runtime surface definition for injection into future sessions. */
+export declare function registerRuntimeSurface(surfaceId: string, code: string, packId: string): void;
+/** Remove a runtime surface definition. */
+export declare function unregisterRuntimeSurface(surfaceId: string): void;
+/** Get all pending runtime surface definitions. */
+export declare function getPendingRuntimeSurfaces(): RuntimeSurfaceDefinition[];
+/** Check if a specific runtime surface is registered. */
+export declare function hasRuntimeSurface(surfaceId: string): boolean;
+/** Subscribe to registry changes. Returns unsubscribe function. */
+export declare function onRegistryChange(fn: () => void): () => void;
+/** Clear all registered runtime surfaces (for testing). */
+export declare function clearRuntimeSurfaceRegistry(): void;
+/**
+ * Inject all pending runtime surfaces into a session.
+ * Returns the list of surface IDs that were successfully injected.
+ */
+export declare function injectPendingRuntimeSurfaces(service: {
+    defineRuntimeSurface(sessionId: string, surfaceId: string, code: string, packId: string): unknown;
+}, sessionId: string): string[];
+export declare function injectPendingRuntimeSurfacesWithReport(service: {
+    defineRuntimeSurface(sessionId: string, surfaceId: string, code: string, packId: string): unknown;
+}, sessionId: string): RuntimeSurfaceInjectionResult;

package/plugin-runtime/runtimeSurfaceRegistry.js

@@ -0,0 +1,73 @@
+/**
+ * Global registry of runtime surface definitions that need to be injected
+ * into runtime sessions after bundle loading.
+ *
+ * Flow:
+ * 1. Chat receives card.v2 event → calls registerRuntimeSurface(surfaceId, code, packId)
+ * 2. RuntimeSurfaceSessionHost finishes loadRuntimeBundle → calls injectPendingRuntimeSurfaces(service, sessionId)
+ * 3. injectPendingRuntimeSurfaces iterates the registry, calls service.defineRuntimeSurface() for each
+ */
+const registry = new Map();
+const listeners = new Set();
+/** Register a runtime surface definition for injection into future sessions. */
+export function registerRuntimeSurface(surfaceId, code, packId) {
+    const normalizedPackId = typeof packId === 'string' ? packId.trim() : '';
+    if (!normalizedPackId) {
+        throw new Error(`runtime surface packId is required for ${surfaceId}`);
+    }
+    registry.set(surfaceId, {
+        surfaceId,
+        code,
+        packId: normalizedPackId,
+        registeredAt: Date.now(),
+    });
+    listeners.forEach((fn) => fn());
+}
+/** Remove a runtime surface definition. */
+export function unregisterRuntimeSurface(surfaceId) {
+    registry.delete(surfaceId);
+    listeners.forEach((fn) => fn());
+}
+/** Get all pending runtime surface definitions. */
+export function getPendingRuntimeSurfaces() {
+    return Array.from(registry.values());
+}
+/** Check if a specific runtime surface is registered. */
+export function hasRuntimeSurface(surfaceId) {
+    return registry.has(surfaceId);
+}
+/** Subscribe to registry changes. Returns unsubscribe function. */
+export function onRegistryChange(fn) {
+    listeners.add(fn);
+    return () => listeners.delete(fn);
+}
+/** Clear all registered runtime surfaces (for testing). */
+export function clearRuntimeSurfaceRegistry() {
+    registry.clear();
+    listeners.forEach((fn) => fn());
+}
+/**
+ * Inject all pending runtime surfaces into a session.
+ * Returns the list of surface IDs that were successfully injected.
+ */
+export function injectPendingRuntimeSurfaces(service, sessionId) {
+    return injectPendingRuntimeSurfacesWithReport(service, sessionId).injected;
+}
+export function injectPendingRuntimeSurfacesWithReport(service, sessionId) {
+    const injected = [];
+    const failed = [];
+    for (const def of registry.values()) {
+        try {
+            service.defineRuntimeSurface(sessionId, def.surfaceId, def.code, def.packId);
+            injected.push(def.surfaceId);
+        }
+        catch (err) {
+            console.error(`[runtimeSurfaceRegistry] Failed to inject runtime surface ${def.surfaceId} into ${sessionId}:`, err);
+            failed.push({
+                surfaceId: def.surfaceId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { injected, failed };
+}