@bbigbang/core 0.1.0

package/dist/services/scenarioRuntimeService.js

@@ -0,0 +1,1130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { log, resolveWorkspacePath, } from '@bbigbang/runtime-acp';
+import { listRuntimeDrivers, } from '@bbigbang/protocol';
+import { ensureLocalWorkspaceScaffold } from './workspaceScaffold.js';
+const DEFAULT_SCENARIO_NODE_ID = 'scenario-node';
+const DEFAULT_SCENARIO_HOSTNAME = 'scenario-node.local';
+const DEFAULT_SCENARIO_VERSION = 'scenario-runtime@phase1';
+const DEFAULT_SCENARIO_ID = 'default';
+const DEFAULT_CHANNEL_SPECS = [
+    { name: 'scenario-main', description: 'Scenario main channel', collaborationMode: 'mention_only' },
+    { name: 'scenario-review', description: 'Scenario review channel', collaborationMode: 'mention_only' },
+];
+const DEFAULT_AGENT_SPECS = [
+    { name: 'ScenarioAlice', agentType: 'codex_app_server', homeChannel: 'scenario-main' },
+    { name: 'ScenarioBob', agentType: 'codex_app_server', homeChannel: 'scenario-main' },
+    { name: 'ScenarioCarol', agentType: 'codex_app_server', homeChannel: 'scenario-review' },
+];
+function normalizeScenarioLibraryRelativePath(rawPath) {
+    const trimmed = rawPath.trim().replace(/\\/g, '/');
+    const normalized = path.posix.normalize(trimmed).replace(/^\/+/, '').replace(/\/+$/, '');
+    if (!normalized
+        || normalized === '.'
+        || normalized === '..'
+        || normalized.startsWith('../')
+        || normalized.includes('/../')) {
+        throw new Error('Invalid library path');
+    }
+    return normalized;
+}
+export class ScenarioRuntimeService {
+    db;
+    conversationManager;
+    nodeRegistry;
+    workspaceBroker;
+    inspectBroker;
+    workspaceRoot;
+    internalAgentAuthToken;
+    scripts = new Map();
+    activeRuns = new Set();
+    app = null;
+    nodeId = DEFAULT_SCENARIO_NODE_ID;
+    hostname = DEFAULT_SCENARIO_HOSTNAME;
+    version = DEFAULT_SCENARIO_VERSION;
+    constructor(params) {
+        this.db = params.db;
+        this.conversationManager = params.conversationManager;
+        this.nodeRegistry = params.nodeRegistry;
+        this.workspaceBroker = params.workspaceBroker;
+        this.inspectBroker = params.inspectBroker;
+        this.workspaceRoot = params.workspaceRoot;
+        this.internalAgentAuthToken = params.internalAgentAuthToken ?? null;
+        this.ensureRegisteredNode();
+    }
+    bindApp(app) {
+        this.app = app;
+    }
+    bootstrapScenario(request) {
+        const scenarioId = normalizeScenarioId(request?.scenarioId ?? DEFAULT_SCENARIO_ID);
+        this.nodeId = request?.nodeId?.trim() || DEFAULT_SCENARIO_NODE_ID;
+        this.hostname = request?.hostname?.trim() || DEFAULT_SCENARIO_HOSTNAME;
+        this.ensureRegisteredNode();
+        const channels = (request?.channels?.length ? request.channels : DEFAULT_CHANNEL_SPECS).map((channel) => ({
+            name: channel.name.trim(),
+            description: channel.description?.trim() || `Scenario channel: ${channel.name.trim()}`,
+            collaborationMode: channel.collaborationMode ?? 'mention_only',
+        }));
+        const createdChannels = channels.map((channel) => this.ensureChannel(channel));
+        const agents = (request?.agents?.length ? request.agents : DEFAULT_AGENT_SPECS).map((agent) => ({
+            ...agent,
+            name: agent.name.trim(),
+        }));
+        const createdAgents = agents.map((agent) => this.ensureAgent({
+            scenarioId,
+            agent,
+            fallbackChannelName: channels[0]?.name ?? DEFAULT_CHANNEL_SPECS[0].name,
+        }));
+        for (const spec of agents) {
+            const createdAgent = createdAgents.find((agent) => agent.name === spec.name);
+            if (!createdAgent)
+                continue;
+            this.setScript(createdAgent.agentId, spec.script);
+        }
+        this.refreshInventory();
+        return {
+            scenarioId,
+            nodeId: this.nodeId,
+            channels: createdChannels.map((channel) => ({
+                channelId: channel.channelId,
+                name: channel.name,
+            })),
+            agents: createdAgents.map((agent) => ({
+                agentId: agent.agentId,
+                name: agent.name,
+                workspacePath: agent.workspacePath ?? null,
+            })),
+        };
+    }
+    ensureRegisteredNode() {
+        const supportedAgentTypes = listRuntimeDrivers().map((driver) => driver.agentType);
+        this.nodeRegistry.register({
+            nodeId: this.nodeId,
+            hostname: this.hostname,
+            agentTypes: supportedAgentTypes,
+            version: this.version,
+            terminalBackendAvailable: false,
+            localSend: (msg) => this.handleCoreMessage(msg),
+            lastSeen: Date.now(),
+        });
+        const now = Date.now();
+        this.db.prepare(`INSERT INTO nodes(node_id, hostname, agent_types_json, version, status, last_seen, created_at, provisioned_at, display_name, env_var_keys)
+       VALUES(?, ?, ?, ?, 'online', ?, ?, ?, ?, '[]')
+       ON CONFLICT(node_id) DO UPDATE SET
+         hostname = excluded.hostname,
+         agent_types_json = excluded.agent_types_json,
+         version = excluded.version,
+         status = 'online',
+         last_seen = excluded.last_seen,
+         display_name = excluded.display_name`).run(this.nodeId, this.hostname, JSON.stringify(supportedAgentTypes), this.version, now, now, now, this.hostname);
+        persistScenarioRuntimeSnapshot(this.db, {
+            nodeId: this.nodeId,
+            snapshotAt: now,
+            runtime: {
+                workspaceRoot: this.workspaceRoot,
+                terminalBackendAvailable: false,
+                runtimeDrivers: listRuntimeDrivers().map((driver) => ({
+                    agentType: driver.agentType,
+                    command: driver.command,
+                    args: [...driver.args],
+                    supportsResume: driver.supportsResume,
+                    supportsPushNotifications: driver.supportsPushNotifications,
+                    capabilities: [...driver.capabilities],
+                    nativeMemoryBackend: driver.nativeMemoryBackend,
+                    supportsClaudeSessionControls: driver.agentType === 'claude_sdk',
+                })),
+                capabilities: {
+                    workspaceRpc: true,
+                    workspaceInspect: true,
+                    workspaceGit: false,
+                    terminals: false,
+                    skills: false,
+                    codexAppServerRpc: false,
+                    codexTranscripts: false,
+                    claudeTranscripts: false,
+                    claudeControls: false,
+                    agentSurfaceMode: 'bigbang',
+                    bigbangCliAvailable: true,
+                },
+            },
+        });
+    }
+    handleCoreMessage(msg) {
+        this.nodeRegistry.heartbeat(this.nodeId);
+        this.db.prepare(`UPDATE nodes SET status = 'online', last_seen = ? WHERE node_id = ?`).run(Date.now(), this.nodeId);
+        switch (msg.type) {
+            case 'run.dispatch':
+                void this.handleRunDispatch(msg);
+                return true;
+            case 'run.cancel':
+                this.activeRuns.delete(msg.runId);
+                this.refreshInventory();
+                return true;
+            case 'workspace.list.request':
+                this.handleWorkspaceList(msg);
+                return true;
+            case 'workspace.read.request':
+                this.handleWorkspaceRead(msg);
+                return true;
+            case 'fs.read_path.request':
+                this.handleFsReadPath(msg);
+                return true;
+            case 'http.fetch_text.request':
+                this.workspaceBroker.handleHttpFetchTextResponse({
+                    type: 'http.fetch_text.response',
+                    requestId: msg.requestId,
+                    url: msg.url,
+                    error: 'Scenario runtime does not support panel api_jsonl HTTP fetch.',
+                    errorCode: 'invalid_request',
+                });
+                return true;
+            case 'workspace.write.request':
+                this.handleWorkspaceWrite(msg);
+                return true;
+            case 'library.mirror.apply.request':
+                this.workspaceBroker.handleLibraryMirrorApplyResponse({
+                    type: 'library.mirror.apply.response',
+                    requestId: msg.requestId,
+                    ok: true,
+                });
+                return true;
+            case 'library.mirror.snapshot.request':
+                this.workspaceBroker.handleLibraryMirrorSnapshotResponse({
+                    type: 'library.mirror.snapshot.response',
+                    requestId: msg.requestId,
+                    shared: null,
+                    personal: null,
+                });
+                return true;
+            case 'library.authority.delete.request':
+                this.handleLibraryAuthorityDelete(msg);
+                return true;
+            case 'library.authority.rename.request':
+                this.handleLibraryAuthorityRename(msg);
+                return true;
+            case 'workspace.inspect.request':
+                this.handleWorkspaceInspect(msg);
+                return true;
+            case 'workspace.reset.request':
+                this.handleWorkspaceReset(msg);
+                return true;
+            case 'host.close':
+                return true;
+            default:
+                return false;
+        }
+    }
+    async handleRunDispatch(msg) {
+        const agentId = msg.channelBridgeConfig?.agentId;
+        if (!agentId) {
+            log.warn('[scenario-runtime] run.dispatch missing channelBridgeConfig.agentId', { runId: msg.runId });
+            return;
+        }
+        const accepted = this.conversationManager.handleRunAccepted(msg.runId, msg.conversationId);
+        if (!accepted) {
+            log.debug('[scenario-runtime] ignoring run.dispatch without pending waiter', {
+                runId: msg.runId,
+                conversationId: msg.conversationId,
+            });
+            return;
+        }
+        this.activeRuns.add(msg.runId);
+        this.refreshInventory();
+        try {
+            const script = this.scripts.get(agentId);
+            if (!script || script.index >= script.steps.length) {
+                await this.finishRun(msg.runId, msg.conversationId);
+                return;
+            }
+            const currentStep = script.steps[script.index];
+            this.assertStepMatches(msg, currentStep.when);
+            script.index += 1;
+            for (const action of currentStep.actions) {
+                if (!this.activeRuns.has(msg.runId))
+                    break;
+                await this.executeAction(agentId, msg, action);
+            }
+            await this.finishRun(msg.runId, msg.conversationId);
+        }
+        catch (error) {
+            log.warn('[scenario-runtime] scripted run failed', {
+                runId: msg.runId,
+                conversationId: msg.conversationId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            await this.finishRun(msg.runId, msg.conversationId, error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            this.activeRuns.delete(msg.runId);
+            this.refreshInventory();
+        }
+    }
+    async executeAction(agentId, dispatch, action) {
+        const agent = this.conversationManager.getAgent(agentId);
+        if (!agent)
+            throw new Error(`Scenario agent not found: ${agentId}`);
+        switch (action.type) {
+            case 'send_message': {
+                const response = await this.injectJson(`/api/internal/agent/${agentId}/send`, {
+                    target: action.target,
+                    content: action.content,
+                    kind: action.kind,
+                    conversationId: dispatch.conversationId,
+                });
+                if (response.statusCode >= 400) {
+                    throw new Error(`send_message failed: ${JSON.stringify(response.body)}`);
+                }
+                return;
+            }
+            case 'create_tasks': {
+                const response = await this.injectJson(`/api/internal/agent/${agentId}/tasks`, {
+                    channel: action.channel ?? this.defaultChannelTarget(agent.channelId),
+                    tasks: action.tasks,
+                    conversationId: dispatch.conversationId,
+                    collaborator_names: action.collaborator_names,
+                });
+                if (response.statusCode >= 400) {
+                    throw new Error(`create_tasks failed: ${JSON.stringify(response.body)}`);
+                }
+                return;
+            }
+            case 'claim_tasks': {
+                const response = await this.injectJson(`/api/internal/agent/${agentId}/tasks/claim`, {
+                    channel: action.channel ?? this.defaultChannelTarget(agent.channelId),
+                    task_numbers: action.task_numbers,
+                    message_ids: action.message_ids,
+                    conversationId: dispatch.conversationId,
+                    collaborator_names: action.collaborator_names,
+                });
+                if (response.statusCode >= 400) {
+                    throw new Error(`claim_tasks failed: ${JSON.stringify(response.body)}`);
+                }
+                return;
+            }
+            case 'update_task_status': {
+                const response = await this.injectJson(`/api/internal/agent/${agentId}/tasks/update-status`, {
+                    channel: action.channel ?? this.defaultChannelTarget(agent.channelId),
+                    task_number: action.task_number,
+                    status: action.status,
+                    conversationId: dispatch.conversationId,
+                });
+                if (response.statusCode >= 400) {
+                    throw new Error(`update_task_status failed: ${JSON.stringify(response.body)}`);
+                }
+                return;
+            }
+            case 'write_memory': {
+                if (!agent.workspacePath) {
+                    throw new Error(`Agent has no workspace: ${agent.name}`);
+                }
+                await this.workspaceBroker.writeFile(this.nodeId, agent.workspacePath, action.relativePath, action.content, action.mode ?? 'append', { agentName: agent.name });
+                return;
+            }
+            case 'read_history': {
+                const params = new URLSearchParams({ channel: action.channel });
+                if (action.limit !== undefined)
+                    params.set('limit', String(action.limit));
+                if (action.around)
+                    params.set('around', action.around);
+                if (action.before !== undefined)
+                    params.set('before', String(action.before));
+                if (action.after !== undefined)
+                    params.set('after', String(action.after));
+                if (action.include_root)
+                    params.set('include_root', 'true');
+                const response = await this.injectGet(`/api/internal/agent/${agentId}/history?${params.toString()}`);
+                if (response.statusCode >= 400) {
+                    throw new Error(`read_history failed: ${JSON.stringify(response.body)}`);
+                }
+                this.assertTextIncludes('read_history', response.body, action.expect_text_includes);
+                return;
+            }
+            case 'get_self_state': {
+                const response = await this.injectGet(`/api/internal/agent/${agentId}/self-state?conversationId=${encodeURIComponent(dispatch.conversationId)}`);
+                if (response.statusCode >= 400) {
+                    throw new Error(`get_self_state failed: ${JSON.stringify(response.body)}`);
+                }
+                this.assertTextIncludes('get_self_state', response.body, action.expect_text_includes);
+                return;
+            }
+            case 'get_runtime_presence': {
+                const response = await this.injectGet(`/api/internal/agent/${agentId}/runtime-presence?conversationId=${encodeURIComponent(dispatch.conversationId)}`);
+                if (response.statusCode >= 400) {
+                    throw new Error(`get_runtime_presence failed: ${JSON.stringify(response.body)}`);
+                }
+                this.assertTextIncludes('get_runtime_presence', response.body, action.expect_text_includes);
+                return;
+            }
+            case 'get_context_bundle': {
+                const response = await this.injectJson(`/api/internal/agent/${agentId}/context-bundle`, {
+                    conversationId: dispatch.conversationId,
+                    maxSurfaces: action.maxSurfaces,
+                    maxTasks: action.maxTasks,
+                    maxHandoffs: action.maxHandoffs,
+                });
+                if (response.statusCode >= 400) {
+                    throw new Error(`get_context_bundle failed: ${JSON.stringify(response.body)}`);
+                }
+                this.assertTextIncludes('get_context_bundle', response.body, action.expect_text_includes);
+                return;
+            }
+            case 'handoff_to_target': {
+                const response = await this.injectJson(`/api/internal/agent/${agentId}/handoff`, {
+                    conversationId: dispatch.conversationId,
+                    target: action.target,
+                    mode: action.mode ?? 'delegate_only',
+                    goal: action.goal,
+                    context: {
+                        why_now: action.why_now,
+                        constraints: action.constraints,
+                        already_done: action.already_done,
+                        expected_output: action.expected_output,
+                        related_task_ref: action.related_task_ref,
+                        optional_refs: action.optional_refs,
+                    },
+                });
+                if (response.statusCode >= 400) {
+                    throw new Error(`handoff_to_target failed: ${JSON.stringify(response.body)}`);
+                }
+                this.assertTextIncludes('handoff_to_target', response.body, action.expect_text_includes);
+                return;
+            }
+            default: {
+                const neverAction = action;
+                throw new Error(`Unsupported scenario action: ${JSON.stringify(neverAction)}`);
+            }
+        }
+    }
+    handleWorkspaceList(msg) {
+        try {
+            const result = listWorkspaceDirectory(msg.workspaceRoot, msg.relativePath, msg.scaffold !== false, msg.agentName, {
+                cursor: msg.cursor,
+                limit: msg.limit,
+            });
+            this.workspaceBroker.handleWorkspaceListResponse({
+                type: 'workspace.list.response',
+                requestId: msg.requestId,
+                relativePath: result.relativePath,
+                entries: result.entries,
+                directoryPage: result.directoryPage,
+            });
+        }
+        catch (error) {
+            this.workspaceBroker.handleWorkspaceListResponse({
+                type: 'workspace.list.response',
+                requestId: msg.requestId,
+                relativePath: msg.relativePath,
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: 'io_error',
+            });
+        }
+    }
+    handleWorkspaceRead(msg) {
+        try {
+            const result = readWorkspaceFile(msg.workspaceRoot, msg.relativePath, msg.scaffold !== false, msg.agentName);
+            this.workspaceBroker.handleWorkspaceReadResponse({
+                type: 'workspace.read.response',
+                requestId: msg.requestId,
+                relativePath: result.relativePath,
+                content: result.content,
+                mimeType: result.mimeType,
+                size: result.size,
+                modifiedAt: result.modifiedAt,
+            });
+        }
+        catch (error) {
+            this.workspaceBroker.handleWorkspaceReadResponse({
+                type: 'workspace.read.response',
+                requestId: msg.requestId,
+                relativePath: msg.relativePath,
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: 'io_error',
+            });
+        }
+    }
+    handleFsReadPath(msg) {
+        try {
+            const resolved = resolveWorkspacePath(this.workspaceRoot, msg.absolutePath);
+            const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+            if (!stat)
+                throw new Error('Path not found.');
+            if (stat.isDirectory()) {
+                const result = listAbsoluteDirectoryPage(resolved, msg.cursor, msg.limit);
+                this.workspaceBroker.handleFsReadPathResponse({
+                    type: 'fs.read_path.response',
+                    requestId: msg.requestId,
+                    absolutePath: resolved,
+                    kind: 'directory',
+                    entries: result.entries,
+                    directoryPage: result.directoryPage,
+                    modifiedAt: Math.floor(stat.mtimeMs),
+                });
+                return;
+            }
+            const result = readWorkspaceFile(path.dirname(resolved), path.basename(resolved), false);
+            this.workspaceBroker.handleFsReadPathResponse({
+                type: 'fs.read_path.response',
+                requestId: msg.requestId,
+                absolutePath: resolved,
+                kind: 'file',
+                content: result.content,
+                mimeType: result.mimeType,
+                size: result.size,
+                modifiedAt: result.modifiedAt,
+            });
+        }
+        catch (error) {
+            this.workspaceBroker.handleFsReadPathResponse({
+                type: 'fs.read_path.response',
+                requestId: msg.requestId,
+                absolutePath: msg.absolutePath,
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: 'io_error',
+            });
+        }
+    }
+    handleWorkspaceWrite(msg) {
+        try {
+            const result = writeWorkspaceFile(msg.workspaceRoot, msg.relativePath, msg.content, msg.mode, msg.scaffold !== false, msg.agentName);
+            this.workspaceBroker.handleWorkspaceWriteResponse({
+                type: 'workspace.write.response',
+                requestId: msg.requestId,
+                relativePath: result.relativePath,
+                modifiedAt: result.modifiedAt,
+                ok: true,
+            });
+        }
+        catch (error) {
+            this.workspaceBroker.handleWorkspaceWriteResponse({
+                type: 'workspace.write.response',
+                requestId: msg.requestId,
+                relativePath: msg.relativePath,
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: 'io_error',
+            });
+        }
+    }
+    handleLibraryAuthorityDelete(msg) {
+        try {
+            const libraryRoot = path.resolve(msg.libraryRoot);
+            const normalized = normalizeScenarioLibraryRelativePath(msg.relativePath);
+            const target = path.resolve(libraryRoot, normalized);
+            if (target !== libraryRoot && !target.startsWith(`${libraryRoot}${path.sep}`)) {
+                throw new Error('Invalid library path');
+            }
+            const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+            if (stat) {
+                if (stat.isDirectory()) {
+                    if (msg.recursive !== true) {
+                        throw new Error('Directory deletion requires recursive=true');
+                    }
+                    fs.rmSync(target, { recursive: true, force: true });
+                }
+                else {
+                    fs.rmSync(target, { force: true });
+                }
+            }
+            this.workspaceBroker.handleLibraryAuthorityDeleteResponse({
+                type: 'library.authority.delete.response',
+                requestId: msg.requestId,
+                ok: true,
+            });
+        }
+        catch (error) {
+            this.workspaceBroker.handleLibraryAuthorityDeleteResponse({
+                type: 'library.authority.delete.response',
+                requestId: msg.requestId,
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: 'io_error',
+            });
+        }
+    }
+    handleLibraryAuthorityRename(msg) {
+        try {
+            const libraryRoot = path.resolve(msg.libraryRoot);
+            const normalized = normalizeScenarioLibraryRelativePath(msg.relativePath);
+            const normalizedNext = normalizeScenarioLibraryRelativePath(msg.nextRelativePath);
+            const target = path.resolve(libraryRoot, normalized);
+            const nextTarget = path.resolve(libraryRoot, normalizedNext);
+            if ((target !== libraryRoot && !target.startsWith(`${libraryRoot}${path.sep}`))
+                || (nextTarget !== libraryRoot && !nextTarget.startsWith(`${libraryRoot}${path.sep}`))) {
+                throw new Error('Invalid library path');
+            }
+            const sourceStat = fs.lstatSync(target, { throwIfNoEntry: false });
+            if (!sourceStat) {
+                throw new Error('Path not found');
+            }
+            if (fs.lstatSync(nextTarget, { throwIfNoEntry: false })) {
+                throw new Error('Destination already exists');
+            }
+            fs.mkdirSync(path.dirname(nextTarget), { recursive: true });
+            fs.renameSync(target, nextTarget);
+            this.workspaceBroker.handleLibraryAuthorityRenameResponse({
+                type: 'library.authority.rename.response',
+                requestId: msg.requestId,
+                ok: true,
+            });
+        }
+        catch (error) {
+            this.workspaceBroker.handleLibraryAuthorityRenameResponse({
+                type: 'library.authority.rename.response',
+                requestId: msg.requestId,
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: 'io_error',
+            });
+        }
+    }
+    handleWorkspaceInspect(msg) {
+        try {
+            this.inspectBroker.handleInspectResponse({
+                type: 'workspace.inspect.response',
+                requestId: msg.requestId,
+                inspect: inspectWorkspace(msg.workspaceRoot),
+            });
+        }
+        catch (error) {
+            this.inspectBroker.handleInspectResponse({
+                type: 'workspace.inspect.response',
+                requestId: msg.requestId,
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: 'io_error',
+            });
+        }
+    }
+    handleWorkspaceReset(msg) {
+        try {
+            resetWorkspaceDirectory(msg.workspaceRoot, msg.agentName);
+            this.workspaceBroker.handleWorkspaceResetResponse({
+                type: 'workspace.reset.response',
+                requestId: msg.requestId,
+                workspaceRoot: msg.workspaceRoot,
+                ok: true,
+            });
+        }
+        catch (error) {
+            this.workspaceBroker.handleWorkspaceResetResponse({
+                type: 'workspace.reset.response',
+                requestId: msg.requestId,
+                workspaceRoot: msg.workspaceRoot,
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: 'io_error',
+            });
+        }
+    }
+    ensureChannel(channel) {
+        const existing = this.conversationManager.listChannels().find((entry) => entry.name === channel.name);
+        if (existing) {
+            this.conversationManager.updateChannel(existing.channelId, {
+                description: channel.description,
+                collaborationMode: channel.collaborationMode,
+            });
+            return existing;
+        }
+        return this.conversationManager.createChannel({
+            name: channel.name,
+            description: channel.description,
+            collaborationMode: channel.collaborationMode,
+            workspacePath: path.join(this.workspaceRoot, 'scenarios', 'channels', channel.name),
+        });
+    }
+    ensureAgent(params) {
+        const existing = this.conversationManager.listAgents().find((entry) => entry.name === params.agent.name);
+        const homeChannelName = params.agent.homeChannel?.trim()
+            || params.agent.channel?.trim()
+            || params.fallbackChannelName;
+        const homeChannel = this.requireChannelByName(homeChannelName);
+        if (existing) {
+            const joinedChannels = new Set(existing.channelIds ?? [existing.channelId]);
+            for (const channelName of params.agent.channels ?? []) {
+                const channel = this.requireChannelByName(channelName);
+                this.conversationManager.joinChannel(existing.agentId, channel.channelId);
+                joinedChannels.add(channel.channelId);
+            }
+            this.conversationManager.joinChannel(existing.agentId, homeChannel.channelId);
+            for (const channelId of joinedChannels) {
+                this.conversationManager.openAgentChannelThread(existing.agentId, channelId, null);
+            }
+            return existing;
+        }
+        const workspacePath = path.join(this.workspaceRoot, 'scenarios', params.scenarioId, slugify(params.agent.name));
+        ensureLocalWorkspaceScaffold(workspacePath, params.agent.name);
+        const created = this.conversationManager.createAgent({
+            name: params.agent.name,
+            agentType: params.agent.agentType ?? 'codex_app_server',
+            channelId: homeChannel.channelId,
+            nodeId: this.nodeId,
+            workspacePath,
+            systemPrompt: params.agent.systemPrompt ?? 'Scenario fake agent. Actions are scripted; platform execution is real.',
+            description: params.agent.description ?? 'Scenario-mode fake agent for scripted collaboration tests.',
+        });
+        const allChannelNames = new Set([
+            homeChannel.name,
+            ...(params.agent.channels ?? []),
+        ]);
+        for (const channelName of allChannelNames) {
+            const channel = this.requireChannelByName(channelName);
+            this.conversationManager.joinChannel(created.agentId, channel.channelId);
+            this.conversationManager.openAgentChannelThread(created.agentId, channel.channelId, null);
+        }
+        return created;
+    }
+    requireChannelByName(name) {
+        const channel = this.conversationManager.listChannels().find((entry) => entry.name === name);
+        if (!channel) {
+            throw new Error(`Scenario channel not found: ${name}`);
+        }
+        return channel;
+    }
+    setScript(agentId, script) {
+        if (!script) {
+            this.scripts.delete(agentId);
+            return;
+        }
+        this.scripts.set(agentId, {
+            steps: script.steps ?? [],
+            index: 0,
+        });
+    }
+    assertStepMatches(dispatch, when) {
+        if (!when)
+            return;
+        const conversation = this.conversationManager.getConversation(dispatch.conversationId);
+        const replyTarget = conversation?.replyTarget ?? null;
+        if (when.target && replyTarget !== when.target) {
+            throw new Error(`Scenario step target mismatch: expected ${when.target}, got ${replyTarget ?? 'null'}`);
+        }
+        for (const fragment of when.promptIncludes ?? []) {
+            if (!dispatch.prompt.includes(fragment)) {
+                throw new Error(`Scenario step prompt mismatch: missing "${fragment}"`);
+            }
+        }
+        for (const fragment of when.contextIncludes ?? []) {
+            if (!(dispatch.contextText ?? '').includes(fragment)) {
+                throw new Error(`Scenario step context mismatch: missing "${fragment}"`);
+            }
+        }
+    }
+    async finishRun(runId, conversationId, error) {
+        const endedAt = Date.now();
+        if (error) {
+            this.db.prepare(`UPDATE runs
+            SET ended_at = ?, error = ?
+          WHERE run_id = ?`).run(endedAt, error, runId);
+            this.db.prepare(`UPDATE conversations SET status = 'failed', updated_at = ? WHERE id = ?`).run(endedAt, conversationId);
+        }
+        else {
+            this.db.prepare(`UPDATE runs
+            SET ended_at = ?, stop_reason = COALESCE(stop_reason, 'end_turn')
+          WHERE run_id = ?`).run(endedAt, runId);
+            this.db.prepare(`UPDATE conversations SET status = 'idle', updated_at = ? WHERE id = ?`).run(endedAt, conversationId);
+        }
+        await this.conversationManager.onConversationSettled(conversationId);
+    }
+    refreshInventory() {
+        const now = Date.now();
+        this.db.prepare(`UPDATE nodes SET last_seen = ?, status = 'online' WHERE node_id = ?`).run(now, this.nodeId);
+        const hostRows = this.db.prepare(`SELECT c.id as conversationId,
+              c.session_key as sessionKey,
+              c.workspace_path as workspacePath,
+              c.agent_type as agentType,
+              c.status,
+              r.run_id as currentRunId
+       FROM conversations c
+       LEFT JOIN runs r ON r.run_id = (
+         SELECT run_id
+         FROM runs
+         WHERE session_key = c.session_key AND ended_at IS NULL
+         ORDER BY started_at DESC
+         LIMIT 1
+       )
+       WHERE c.node_id = ?`).all(this.nodeId);
+        persistScenarioHostSnapshots(this.db, {
+            nodeId: this.nodeId,
+            snapshotAt: now,
+            hosts: hostRows.map((row) => ({
+                hostKey: `conversation:${row.conversationId}:${row.agentType}`,
+                sessionKey: row.sessionKey,
+                workspaceRoot: row.workspacePath ?? '',
+                agentType: row.agentType,
+                state: scenarioHostStateForConversationStatus(row.status),
+                currentRunId: row.currentRunId,
+                hasPendingApproval: false,
+                inboxSize: 0,
+                pendingDispatchCount: 0,
+                lastWakeAt: now,
+                lastSleepAt: row.currentRunId ? null : now,
+                lastError: null,
+                resumable: true,
+            })),
+        });
+    }
+    async injectJson(url, body) {
+        if (!this.app) {
+            throw new Error('Scenario runtime is not bound to Fastify yet.');
+        }
+        const headers = {
+            'content-type': 'application/json',
+        };
+        if (this.internalAgentAuthToken) {
+            headers.authorization = `Bearer ${this.internalAgentAuthToken}`;
+        }
+        const response = await this.app.inject({
+            method: 'POST',
+            url,
+            payload: body,
+            headers,
+        });
+        return {
+            statusCode: response.statusCode,
+            body: response.body ? response.json() : {},
+        };
+    }
+    async injectGet(url) {
+        if (!this.app) {
+            throw new Error('Scenario runtime is not bound to Fastify yet.');
+        }
+        const headers = {};
+        if (this.internalAgentAuthToken) {
+            headers.authorization = `Bearer ${this.internalAgentAuthToken}`;
+        }
+        const response = await this.app.inject({
+            method: 'GET',
+            url,
+            headers,
+        });
+        return {
+            statusCode: response.statusCode,
+            body: response.body ? response.json() : {},
+        };
+    }
+    assertTextIncludes(label, value, fragments) {
+        if (!fragments?.length)
+            return;
+        const haystack = JSON.stringify(value);
+        for (const fragment of fragments) {
+            if (!haystack.includes(fragment)) {
+                throw new Error(`${label} assertion failed: missing "${fragment}" in ${haystack}`);
+            }
+        }
+    }
+    defaultChannelTarget(channelId) {
+        const channel = this.conversationManager.getChannel(channelId);
+        if (!channel)
+            throw new Error(`Scenario channel not found: ${channelId}`);
+        return `#${channel.name}`;
+    }
+}
+function normalizeScenarioId(value) {
+    const normalized = value.trim().toLowerCase();
+    return normalized || DEFAULT_SCENARIO_ID;
+}
+function slugify(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        || 'scenario-agent';
+}
+function scenarioHostStateForConversationStatus(status) {
+    switch (status) {
+        case 'active':
+            return 'running';
+        case 'queued':
+            return 'queued';
+        case 'failed':
+            return 'error';
+        default:
+            return 'idle';
+    }
+}
+function listWorkspaceDirectory(workspaceRoot, relativePath, scaffold, agentName, options = {}) {
+    if (scaffold)
+        ensureLocalWorkspaceScaffold(workspaceRoot, agentName);
+    const resolved = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+    if (!stat || !stat.isDirectory())
+        throw new Error('Path is not a directory.');
+    const candidates = fs.readdirSync(resolved, { withFileTypes: true })
+        .map((entry) => {
+        const absoluteEntry = path.join(resolved, entry.name);
+        return classifyWorkspaceEntryCandidate(entry, absoluteEntry);
+    })
+        .sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind === 'directory' ? -1 : 1;
+        return a.dirent.name.localeCompare(b.dirent.name);
+    });
+    const { candidates: pageCandidates, directoryPage } = paginateWorkspaceEntryCandidates(candidates, options);
+    const entries = pageCandidates.map((candidate) => workspaceEntryFromCandidate(workspaceRoot, candidate));
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        entries,
+        directoryPage,
+    };
+}
+function readWorkspaceFile(workspaceRoot, relativePath, scaffold, agentName) {
+    if (scaffold)
+        ensureLocalWorkspaceScaffold(workspaceRoot, agentName);
+    const resolved = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+    if (!stat || !stat.isFile())
+        throw new Error('Path is not a file.');
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        content: fs.readFileSync(resolved, 'utf8'),
+        mimeType: resolved.toLowerCase().endsWith('.md') ? 'text/markdown' : 'text/plain',
+        size: stat.size,
+        modifiedAt: Math.floor(stat.mtimeMs),
+    };
+}
+function writeWorkspaceFile(workspaceRoot, relativePath, content, mode, scaffold, agentName) {
+    if (scaffold)
+        ensureLocalWorkspaceScaffold(workspaceRoot, agentName);
+    const resolved = resolveRelativeWorkspacePath(workspaceRoot, relativePath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    if (mode === 'append') {
+        fs.appendFileSync(resolved, content, 'utf8');
+    }
+    else {
+        fs.writeFileSync(resolved, content, 'utf8');
+    }
+    const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+    return {
+        relativePath: normalizeRelativePath(relativePath),
+        modifiedAt: stat?.mtimeMs ? Math.floor(stat.mtimeMs) : null,
+    };
+}
+function resetWorkspaceDirectory(workspaceRoot, agentName) {
+    const resolvedRoot = path.resolve(workspaceRoot);
+    fs.mkdirSync(resolvedRoot, { recursive: true });
+    for (const entry of fs.readdirSync(resolvedRoot, { withFileTypes: true })) {
+        const target = path.join(resolvedRoot, entry.name);
+        fs.rmSync(target, { recursive: true, force: true });
+    }
+    ensureLocalWorkspaceScaffold(resolvedRoot, agentName);
+}
+function inspectWorkspace(workspaceRoot) {
+    const resolvedRoot = path.resolve(workspaceRoot);
+    const gitDir = findGitDir(resolvedRoot);
+    return {
+        workspaceRoot: resolvedRoot,
+        isGit: Boolean(gitDir),
+        repoRoot: gitDir,
+        workspaceKind: 'directory',
+        branchName: null,
+        remoteUrl: null,
+    };
+}
+function findGitDir(startPath) {
+    let current = path.resolve(startPath);
+    while (true) {
+        if (fs.existsSync(path.join(current, '.git')))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function resolveRelativeWorkspacePath(workspaceRoot, relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    const absoluteRequested = normalized
+        ? path.resolve(workspaceRoot, normalized)
+        : path.resolve(workspaceRoot);
+    return resolveWorkspacePath(workspaceRoot, absoluteRequested);
+}
+function normalizeRelativePath(relativePath) {
+    return relativePath.replace(/^\/+/, '').trim();
+}
+function toRelativeWorkspacePath(workspaceRoot, absolutePath) {
+    const relative = path.relative(path.resolve(workspaceRoot), path.resolve(absolutePath));
+    return relative === '.' ? '' : relative.split(path.sep).join('/');
+}
+function persistScenarioHostSnapshots(db, params) {
+    db.transaction(() => {
+        if (params.hosts.length === 0) {
+            db.prepare(`DELETE FROM node_host_snapshots WHERE node_id = ?`).run(params.nodeId);
+            return;
+        }
+        const placeholders = params.hosts.map(() => '?').join(', ');
+        db.prepare(`DELETE FROM node_host_snapshots WHERE node_id = ? AND host_key NOT IN (${placeholders})`).run(params.nodeId, ...params.hosts.map((host) => host.hostKey));
+        const upsert = db.prepare(`INSERT INTO node_host_snapshots(
+         node_id, host_key, session_key, workspace_root, agent_type, state, current_run_id,
+         has_pending_approval, inbox_size, pending_dispatch_count, last_wake_at, last_sleep_at,
+         last_error, resumable, snapshot_at
+       ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id, host_key) DO UPDATE SET
+         session_key = excluded.session_key,
+         workspace_root = excluded.workspace_root,
+         agent_type = excluded.agent_type,
+         state = excluded.state,
+         current_run_id = excluded.current_run_id,
+         has_pending_approval = excluded.has_pending_approval,
+         inbox_size = excluded.inbox_size,
+         pending_dispatch_count = excluded.pending_dispatch_count,
+         last_wake_at = excluded.last_wake_at,
+         last_sleep_at = excluded.last_sleep_at,
+         last_error = excluded.last_error,
+         resumable = excluded.resumable,
+         snapshot_at = excluded.snapshot_at`);
+        for (const host of params.hosts) {
+            upsert.run(params.nodeId, host.hostKey, host.sessionKey, host.workspaceRoot, host.agentType, host.state, host.currentRunId, host.hasPendingApproval ? 1 : 0, host.inboxSize, host.pendingDispatchCount, host.lastWakeAt, host.lastSleepAt, host.lastError, host.resumable ? 1 : 0, params.snapshotAt);
+        }
+    })();
+}
+function persistScenarioRuntimeSnapshot(db, params) {
+    db.prepare(`INSERT INTO node_runtime_snapshots(
+       node_id, workspace_root, terminal_backend_available, runtime_drivers_json, capabilities_json, snapshot_at
+     ) VALUES(?, ?, ?, ?, ?, ?)
+     ON CONFLICT(node_id) DO UPDATE SET
+       workspace_root = excluded.workspace_root,
+       terminal_backend_available = excluded.terminal_backend_available,
+       runtime_drivers_json = excluded.runtime_drivers_json,
+       capabilities_json = excluded.capabilities_json,
+       snapshot_at = excluded.snapshot_at`).run(params.nodeId, params.runtime.workspaceRoot, params.runtime.terminalBackendAvailable ? 1 : 0, JSON.stringify(params.runtime.runtimeDrivers), JSON.stringify(params.runtime.capabilities), params.snapshotAt);
+}
+function listAbsoluteDirectoryPage(absolutePath, cursor, rawLimit) {
+    const limit = normalizeDirectoryLimit(rawLimit);
+    const sorted = fs
+        .readdirSync(absolutePath, { withFileTypes: true })
+        .filter((entry) => !entry.isSymbolicLink())
+        .sort(compareDirents);
+    const offset = parseDirectoryCursor(cursor, sorted);
+    const pageDirents = sorted.slice(offset, offset + limit);
+    const entries = pageDirents
+        .map((entry) => {
+        const entryPath = path.join(absolutePath, entry.name);
+        const stat = fs.lstatSync(entryPath, { throwIfNoEntry: false });
+        if (!stat || stat.isSymbolicLink())
+            return null;
+        return {
+            name: entry.name,
+            path: entryPath,
+            kind: stat.isDirectory() ? 'directory' : 'file',
+            size: stat.isDirectory() ? null : stat.size,
+            modifiedAt: stat.mtimeMs ? Math.floor(stat.mtimeMs) : null,
+        };
+    })
+        .filter((entry) => entry != null);
+    const nextOffset = offset + pageDirents.length;
+    const hasMore = nextOffset < sorted.length;
+    return {
+        entries,
+        directoryPage: {
+            nextCursor: hasMore && pageDirents.length ? encodeDirectoryCursor(pageDirents[pageDirents.length - 1]) : null,
+            hasMore,
+            limit,
+        },
+    };
+}
+const DIRECTORY_CURSOR_PREFIX = 'k:';
+function classifyWorkspaceEntryCandidate(entry, absolutePath) {
+    const isSymlink = entry.isSymbolicLink();
+    if (isSymlink) {
+        const targetStat = fs.statSync(absolutePath, { throwIfNoEntry: false });
+        return {
+            dirent: entry,
+            absolutePath,
+            kind: targetStat?.isDirectory() ? 'directory' : 'file',
+            isSymlink,
+        };
+    }
+    return {
+        dirent: entry,
+        absolutePath,
+        kind: entry.isDirectory() ? 'directory' : 'file',
+        isSymlink,
+    };
+}
+function workspaceEntryFromCandidate(workspaceRoot, candidate) {
+    const stat = fs.statSync(candidate.absolutePath, { throwIfNoEntry: false });
+    return {
+        name: candidate.dirent.name,
+        path: toRelativeWorkspacePath(workspaceRoot, candidate.absolutePath),
+        kind: candidate.kind,
+        size: candidate.kind === 'directory' ? null : (stat?.size ?? null),
+        modifiedAt: stat?.mtimeMs ? Math.floor(stat.mtimeMs) : null,
+        ...(candidate.isSymlink ? { isSymlink: true } : {}),
+    };
+}
+function paginateWorkspaceEntryCandidates(candidates, options) {
+    const limit = normalizeWorkbenchDirectoryLimit(options.limit);
+    const offset = parseWorkspaceEntryCursor(options.cursor, candidates);
+    const pageCandidates = candidates.slice(offset, offset + limit);
+    const nextOffset = offset + pageCandidates.length;
+    const hasMore = nextOffset < candidates.length;
+    return {
+        candidates: pageCandidates,
+        directoryPage: {
+            nextCursor: hasMore && pageCandidates.length ? encodeWorkspaceEntryCursor(pageCandidates[pageCandidates.length - 1]) : null,
+            hasMore,
+            limit,
+        },
+    };
+}
+function compareDirents(left, right) {
+    return compareDirectoryEntryKeys(direntKind(left), left.name, direntKind(right), right.name);
+}
+function direntKind(entry) {
+    return entry.isDirectory() ? 'directory' : 'file';
+}
+function compareDirectoryEntryKeys(leftKind, leftName, rightKind, rightName) {
+    if (leftKind !== rightKind)
+        return leftKind === 'directory' ? -1 : 1;
+    return leftName.localeCompare(rightName);
+}
+function encodeDirectoryCursor(entry) {
+    const payload = { kind: direntKind(entry), name: entry.name };
+    return `${DIRECTORY_CURSOR_PREFIX}${Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')}`;
+}
+function normalizeDirectoryLimit(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 100;
+    return Math.min(200, Math.max(1, Math.floor(value)));
+}
+function normalizeWorkbenchDirectoryLimit(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 500;
+    return Math.min(1000, Math.max(1, Math.floor(value)));
+}
+function parseWorkspaceEntryCursor(value, candidates) {
+    const decoded = decodeDirectoryCursor(value);
+    if (!decoded)
+        return 0;
+    const index = candidates.findIndex((entry) => compareDirectoryEntryKeys(entry.kind, entry.dirent.name, decoded.kind, decoded.name) > 0);
+    return index === -1 ? candidates.length : index;
+}
+function parseDirectoryCursor(value, entries) {
+    if (!value)
+        return 0;
+    const decoded = decodeDirectoryCursor(value);
+    if (decoded) {
+        const index = entries.findIndex((entry) => compareDirectoryEntryKeys(direntKind(entry), entry.name, decoded.kind, decoded.name) > 0);
+        return index === -1 ? entries.length : index;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 0;
+    return parsed;
+}
+function encodeWorkspaceEntryCursor(entry) {
+    const payload = { kind: entry.kind, name: entry.dirent.name };
+    return `${DIRECTORY_CURSOR_PREFIX}${Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')}`;
+}
+function decodeDirectoryCursor(value) {
+    if (!value?.startsWith(DIRECTORY_CURSOR_PREFIX))
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(value.slice(DIRECTORY_CURSOR_PREFIX.length), 'base64url').toString('utf8'));
+        const cursorKind = parsed.kind;
+        const cursorName = parsed.name;
+        if ((cursorKind === 'directory' || cursorKind === 'file') && typeof cursorName === 'string') {
+            return { kind: cursorKind, name: cursorName };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}