@orion-agents/orion-code 0.2.2 → 0.3.1

package/dist/web/workbench-controller.js

@@ -0,0 +1,1267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebWorkbenchController = exports.WebWorkbenchError = void 0;
+exports.pageItems = pageItems;
+exports.pageCollectionItems = pageCollectionItems;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const agent_runtime_controller_1 = require("../runtime/agent-runtime-controller");
+const durable_tool_receipt_reader_1 = require("../runtime/durable-tool-receipt-reader");
+const mcp_1 = require("../runtime/mcp");
+const product_bootstrap_1 = require("../runtime/product-bootstrap");
+const canonical_1 = require("../runtime/protocol/canonical");
+const thread_session_index_1 = require("../runtime/thread-session-index");
+const thread_session_view_1 = require("../runtime/thread-session-view");
+const tool_detail_repository_1 = require("../runtime/tool-detail-repository");
+const turn_commit_1 = require("../runtime/turn-commit");
+const global_config_1 = require("../services/global-config");
+const settings_coordinator_1 = require("../services/settings-coordinator");
+const session_storage_1 = require("../services/session-storage");
+const workspace_registry_1 = require("../services/workspace-registry");
+const errors_1 = require("./errors");
+const event_hub_1 = require("./event-hub");
+const file_read_service_1 = require("./file-read-service");
+const git_read_model_service_1 = require("./git-read-model-service");
+const protocol_1 = require("./protocol");
+const review_service_1 = require("./review-service");
+const terminal_manager_1 = require("./terminal-manager");
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "WebWorkbenchError", { enumerable: true, get: function () { return errors_2.WebWorkbenchError; } });
+const SESSION_VIEW_CACHE_BYTES = 16 * 1024 * 1024;
+const MAX_MUTATION_RESULTS = 4096;
+/** Owns the sole runtime/controller pair exposed through the local Web host. */
+class WebWorkbenchController {
+    constructor(options) {
+        this.mutationResults = new Map();
+        this.sessionViews = new Map();
+        this.sessionViewBytes = 0;
+        this.toolDetails = new tool_detail_repository_1.FileToolDetailRepository();
+        this.contextRevisionValue = (0, crypto_1.randomUUID)();
+        this.suppressContextEdges = 0;
+        this.latestStatus = 'Ready';
+        this.sessionTransition = false;
+        this.closed = false;
+        this.workspaceWatchers = [];
+        this.workspaceValue = canonicalDirectory(options.cwd);
+        this.eventHub = options.eventHub ?? new event_hub_1.WebEventHub();
+        this.workspaceRegistry = options.workspaceRegistry ?? new workspace_registry_1.WorkspaceRegistryV1();
+        this.terminalManager = new terminal_manager_1.TerminalManagerV1({
+            resolveWorkspace: workspaceId => this.workspaceRegistry.find(workspaceId)?.canonicalPath,
+            getActiveContext: () => ({
+                workspaceId: this.activeWorkspaceEntry().id,
+                contextRevision: this.contextRevisionValue,
+            }),
+            onWorkspaceMutationHint: workspaceId => {
+                if (workspaceId === this.activeWorkspaceEntry().id) {
+                    this.scheduleWorkspaceResourceInvalidation('terminal-command');
+                }
+            },
+        });
+        this.createRuntime =
+            options.createRuntime ??
+                (cwd => (0, product_bootstrap_1.createProductUiRuntime)({
+                    cwd,
+                    shutdownReason: 'Orion Web Workbench shutdown',
+                    onActiveSessionRuntime: (runtime, sessionId, activation) => this.observeThreadRuntime(runtime, sessionId, activation),
+                    onSettingsInvalidated: event => {
+                        if (this.suppressContextEdges > 0)
+                            return;
+                        this.eventHub.emit({
+                            type: 'settings_invalidated',
+                            revision: event.revision,
+                            reason: event.reason,
+                            state: event.state,
+                        }, false);
+                    },
+                }));
+    }
+    static async create(options) {
+        const workbench = new WebWorkbenchController(options);
+        workbench.initializeWorkspaceRegistry();
+        await workbench.installRuntime(workbench.workspaceValue);
+        return workbench;
+    }
+    get workspace() {
+        return this.workspaceValue;
+    }
+    get runtime() {
+        return this.runtimeValue;
+    }
+    get controller() {
+        return this.controllerValue;
+    }
+    get contextRevision() {
+        return this.contextRevisionValue;
+    }
+    bootstrap(nonce) {
+        return Object.freeze({
+            apiVersion: protocol_1.WEB_API_VERSION,
+            productVersion: this.runtimeValue.version,
+            nonce,
+            contextRevision: this.contextRevisionValue,
+            workspaceId: this.activeWorkspaceEntry().id,
+            workspace: this.workspaceValue,
+            configured: this.runtimeValue.isConfigured,
+            activeSessionId: this.runtimeValue.getSession()?.id ?? null,
+            settings: this.settings(),
+            capabilities: {
+                goal: true,
+                plan: true,
+                skills: true,
+                mcp: true,
+                diagnostics: true,
+                review: true,
+                files: true,
+                git: true,
+                terminal: this.terminalManager.available,
+            },
+        });
+    }
+    settings() {
+        this.assertSettingsAvailable();
+        const describe = this.runtimeValue.describeSettings;
+        if (!describe) {
+            throw new errors_1.WebWorkbenchError(503, 'The product Settings coordinator is unavailable.', 'settings_document_unavailable');
+        }
+        try {
+            return describe();
+        }
+        catch (error) {
+            throw mapSettingsError(error);
+        }
+    }
+    listWorkspaces() {
+        const counts = new Map();
+        for (const session of (0, session_storage_1.listSessions)()) {
+            try {
+                const path = canonicalDirectory(session.projectPath);
+                counts.set(path, (counts.get(path) ?? 0) + 1);
+            }
+            catch {
+                // Stale projects remain in session history but are not selectable workspaces.
+            }
+        }
+        return Object.freeze(this.workspaceRegistry.list().map(entry => {
+            let available = false;
+            try {
+                available = canonicalDirectory(entry.canonicalPath) === entry.canonicalPath;
+            }
+            catch {
+                available = false;
+            }
+            return Object.freeze({
+                id: entry.id,
+                path: entry.canonicalPath,
+                label: entry.label || (0, path_1.basename)(entry.canonicalPath) || entry.canonicalPath,
+                active: entry.canonicalPath === this.workspaceValue,
+                available,
+                sessionCount: counts.get(entry.canonicalPath) ?? 0,
+                lastActivatedAt: entry.lastActivatedAt,
+                ...(entry.pinnedOrder !== undefined ? { pinnedOrder: entry.pinnedOrder } : {}),
+            });
+        }));
+    }
+    listWorkspaceSessions(workspaceId) {
+        const entry = this.workspaceRegistry.find(workspaceId);
+        if (!entry) {
+            throw new errors_1.WebWorkbenchError(404, 'Workspace was not found.', 'workspace_not_found');
+        }
+        try {
+            canonicalDirectory(entry.canonicalPath);
+        }
+        catch {
+            throw new errors_1.WebWorkbenchError(409, 'Workspace is unavailable.', 'workspace_unavailable');
+        }
+        return Object.freeze((0, session_storage_1.listProjectSessions)(entry.canonicalPath).map(protocol_1.projectSessionSummary));
+    }
+    async workspaceProjectSummary(workspaceId) {
+        const entry = this.workspaceRegistry.find(workspaceId);
+        if (!entry) {
+            throw new errors_1.WebWorkbenchError(404, 'Workspace was not found.', 'workspace_not_found');
+        }
+        let workspace;
+        try {
+            workspace = canonicalDirectory(entry.canonicalPath);
+        }
+        catch {
+            throw new errors_1.WebWorkbenchError(409, 'Workspace is unavailable.', 'workspace_unavailable');
+        }
+        const status = await new git_read_model_service_1.GitReadModelServiceV1(workspace).status({ pageSize: 2000 });
+        return Object.freeze({
+            workspaceId,
+            repositoryRevision: status.repositoryRevision,
+            isRepository: status.isRepository,
+            branch: status.branch,
+            detached: status.detached,
+            head: status.head,
+            dirtyCount: status.totalFiles,
+            conflictCount: status.conflicted.length,
+        });
+    }
+    setWorkspacePinned(workspaceId, pinned, context) {
+        this.assertContextGuard(context);
+        try {
+            this.workspaceRegistry.setPinned(workspaceId, pinned);
+        }
+        catch (error) {
+            throw mapWorkspaceRegistryError(error);
+        }
+        const updated = this.listWorkspaces().find(workspace => workspace.id === workspaceId);
+        if (!updated) {
+            throw new errors_1.WebWorkbenchError(404, 'Workspace was not found.', 'workspace_not_found');
+        }
+        return updated;
+    }
+    removeWorkspace(workspaceId, context) {
+        this.assertContextGuard(context);
+        const entry = this.workspaceRegistry.find(workspaceId);
+        if (!entry) {
+            throw new errors_1.WebWorkbenchError(404, 'Workspace was not found.', 'workspace_not_found');
+        }
+        if (entry.canonicalPath === this.workspaceValue) {
+            throw new errors_1.WebWorkbenchError(409, 'The active Workspace cannot be removed.', 'workspace_active');
+        }
+        this.terminalManager.closeWorkspace(workspaceId);
+        if (!this.workspaceRegistry.remove(workspaceId)) {
+            throw new errors_1.WebWorkbenchError(404, 'Workspace was not found.', 'workspace_not_found');
+        }
+    }
+    listSessions(context) {
+        if (context)
+            this.assertContextGuard(context);
+        const result = Object.freeze((0, session_storage_1.listProjectSessions)(this.workspaceValue).map(protocol_1.projectSessionSummary));
+        if (context)
+            this.assertContextGuard(context);
+        return result;
+    }
+    sessionSnapshot(sessionId, cursor, pageSize = 50, tail = false, context) {
+        if (context)
+            this.assertContextGuard(context);
+        const session = requireSession(sessionId);
+        if (canonicalDirectory(session.projectPath) !== this.workspaceValue) {
+            throw new errors_1.WebWorkbenchError(409, 'Session belongs to another workspace.');
+        }
+        const active = this.runtimeValue.getSession()?.id === session.id;
+        const activeProjection = this.activeOrionRuntime?.sessionId === session.id
+            ? this.activeOrionRuntime.runtime.thread.getProjection()
+            : undefined;
+        let indexedPage;
+        if (tail) {
+            try {
+                indexedPage = (0, thread_session_view_1.loadThreadSessionSnapshotPageV1)(this.workspaceValue, session.id, cursor, pageSize);
+            }
+            catch (error) {
+                if (error instanceof thread_session_index_1.ThreadSessionIndexError) {
+                    throw new errors_1.WebWorkbenchError(error.code === 'ORION_THREAD_SESSION_CURSOR_STALE' ? 409 : 400, error.message, error.code === 'ORION_THREAD_SESSION_CURSOR_STALE'
+                        ? 'transcript_cursor_stale'
+                        : 'page_cursor_invalid');
+                }
+                throw error;
+            }
+        }
+        if (indexedPage &&
+            activeProjection &&
+            (indexedPage.cursor !== activeProjection.cursor ||
+                indexedPage.projectionDigest !== activeProjection.digest)) {
+            if (cursor) {
+                throw new errors_1.WebWorkbenchError(409, 'Active Thread changed after this transcript cursor was issued.', 'transcript_cursor_stale');
+            }
+            // Another process may have advanced the durable Thread before the active
+            // Runtime has adopted that head. Never combine the newer page with the
+            // older in-memory cursor/digest in one snapshot.
+            indexedPage = undefined;
+        }
+        let view;
+        if (!indexedPage && !activeProjection) {
+            try {
+                view = this.loadSessionView(session, activeProjection);
+            }
+            catch (error) {
+                if (!activeProjection)
+                    throw error;
+                view = undefined;
+            }
+        }
+        const transcriptSource = indexedPage
+            ? indexedPage.transcript.items
+            : view
+                ? view.transcriptMessages
+                : activeProjection
+                    ? Object.values(activeProjection.items)
+                        .filter(item => item.kind === 'message' &&
+                        item.status !== 'started' &&
+                        ['system', 'user', 'assistant', 'tool'].includes(item.role ?? ''))
+                        .sort((left, right) => left.startedSeq - right.startedSeq)
+                        .map(item => ({
+                        role: item.role,
+                        content: item.content ?? item.summary ?? item.error ?? '',
+                        timestamp: item.terminalSeq ?? item.startedSeq,
+                    }))
+                    : (0, session_storage_1.readSessionMessages)(session.id).map(message => ({
+                        role: message.role,
+                        content: message.content,
+                        timestamp: message.timestamp,
+                        ...(message.toolCallId ? { toolCallId: message.toolCallId } : {}),
+                        ...(message.tool_calls ? { tool_calls: message.tool_calls } : {}),
+                        ...(message.modelVisibleContent
+                            ? { modelVisibleContent: message.modelVisibleContent }
+                            : {}),
+                        ...(message.appliedSkills ? { appliedSkills: message.appliedSkills } : {}),
+                    }));
+        const tailPage = tail && !indexedPage ? pageTranscriptTail(transcriptSource, cursor, pageSize) : undefined;
+        const transcriptPage = indexedPage
+            ? {
+                items: indexedPage.transcript.items,
+                nextCursor: indexedPage.transcript.nextCursor,
+            }
+            : (tailPage ?? pageItems(transcriptSource, cursor, pageSize));
+        const transcriptOffset = indexedPage
+            ? indexedPage.transcript.offset
+            : (tailPage?.offset ?? (cursor ? decodePageCursor(cursor) : 0));
+        const transcript = Object.freeze({
+            items: Object.freeze(transcriptPage.items.map((message, index) => ({
+                ...message,
+                id: `${session.id}:message:${transcriptOffset + index + 1}`,
+            }))),
+            nextCursor: indexedPage?.transcript.nextCursor ?? transcriptPage.nextCursor,
+        });
+        const commitProjections = indexedPage
+            ? uniqueCommitProjections([indexedPage.latestPlanTurnCommit, indexedPage.latestTurnCommit])
+            : view
+                ? uniqueCommitProjections([view.latestPlanTurnCommit, view.latestTurnCommit])
+                : activeProjection
+                    ? latestAuthorityCommits(activeProjection)
+                    : [];
+        const commits = commitProjections.map(commit => (0, turn_commit_1.parseTurnCommitV1)(commit.receipt));
+        const latestCommit = commits.at(-1);
+        const planCommit = [...commits].reverse().find(commit => commit.planReceipt);
+        const plan = planCommit?.planReceipt
+            ? pickPlanReceipt((0, turn_commit_1.parsePlanReceiptV1)(planCommit.planReceipt))
+            : null;
+        const state = this.runtimeValue.store.getSnapshot();
+        const pendingPermissions = active
+            ? this.controllerValue.getPendingPermissions().map(request => ({
+                id: request.id,
+                toolName: request.name,
+                ...(request.reason ? { reason: request.reason } : {}),
+                sanitizedArguments: request.args,
+                allowedScopes: ['once', 'project', 'global'],
+            }))
+            : [];
+        const projectionStatus = activeProjection?.status ?? (indexedPage || view ? 'idle' : 'legacy');
+        const goal = latestCommit?.goalState && latestCommit.goalStateDigest
+            ? {
+                authority: 'turn_commit',
+                digest: latestCommit.goalStateDigest,
+                state: JSON.parse(latestCommit.goalState),
+            }
+            : null;
+        const snapshot = Object.freeze({
+            apiVersion: protocol_1.WEB_API_VERSION,
+            session: (0, protocol_1.projectSessionSummary)(session),
+            threadId: activeProjection?.threadId ?? indexedPage?.threadId ?? view?.threadId ?? null,
+            threadCursor: activeProjection?.cursor ?? indexedPage?.cursor ?? view?.cursor ?? 0,
+            eventCursor: this.eventHub.snapshot().latest,
+            ...(activeProjection?.digest || indexedPage?.projectionDigest || view?.projectionDigest
+                ? {
+                    projectionDigest: activeProjection?.digest ?? indexedPage?.projectionDigest ?? view?.projectionDigest,
+                }
+                : {}),
+            threadStatus: projectionStatus,
+            ...(activeProjection?.activeTurnId ? { activeTurnId: activeProjection.activeTurnId } : {}),
+            transcript,
+            runtime: {
+                active,
+                processing: active ? state.isProcessing : false,
+                agentMode: state.agentMode,
+                permissionMode: state.permissionMode,
+                status: this.latestStatus,
+                followups: active ? Object.freeze([...this.controllerValue.getFollowupQueue()]) : [],
+                followupLimit: 16,
+                contextUsage: active ? state.contextUsage : null,
+                tokenUsage: active ? state.tokenUsage : null,
+            },
+            pendingApprovals: Object.freeze(pendingPermissions),
+            goal,
+            plan,
+            recoveryDiagnostics: indexedPage ? [] : (view?.diagnostics ?? []),
+        });
+        if (context)
+            this.assertContextGuard(context);
+        return snapshot;
+    }
+    async skills() {
+        const descriptors = (await this.runtimeValue.inspectSkills?.()) ?? [];
+        return Object.freeze(descriptors.map(descriptor => Object.freeze({
+            id: descriptor.id,
+            name: descriptor.name,
+            description: descriptor.description,
+            providerId: descriptor.providerId,
+            sourceScope: descriptor.sourceScope,
+            modelInvocable: descriptor.modelInvocable,
+            userInvocable: descriptor.userInvocable,
+            requestedCapabilities: Object.freeze([...descriptor.requestedCapabilities]),
+            digest: descriptor.digest,
+        })));
+    }
+    mcp() {
+        const descriptors = this.runtimeValue.inspectMcp?.() ?? [];
+        let runtimeServers = new Map();
+        try {
+            runtimeServers = new Map((this.activeOrionRuntime?.runtime.diagnostics().mcp.servers ?? []).map(server => [
+                server.serverId,
+                server,
+            ]));
+        }
+        catch {
+            // A concurrent session transition may close the previous diagnostics graph.
+        }
+        return Object.freeze(descriptors.map(descriptor => {
+            const runtime = runtimeServers.get(descriptor.id);
+            return Object.freeze({
+                id: descriptor.id,
+                name: descriptor.name,
+                ...(descriptor.description ? { description: descriptor.description } : {}),
+                transport: descriptor.transport,
+                tags: Object.freeze([...(descriptor.tags ?? [])]),
+                disabled: descriptor.disabled ?? false,
+                state: runtime?.state ?? 'dormant',
+                generation: runtime?.generation ?? 0,
+                toolCount: runtime?.toolCount ?? 0,
+                activeCallCount: runtime?.activeCallCount ?? 0,
+                ...(runtime?.failure
+                    ? { failure: 'Runtime transport failure. See local Host diagnostics for details.' }
+                    : {}),
+            });
+        }));
+    }
+    async listToolDetails() {
+        return Object.freeze(await this.toolDetails.list(this.workspaceValue));
+    }
+    async readToolDetail(callId, offsetBytes, limitBytes) {
+        const entry = (await this.toolDetails.list(this.workspaceValue)).find(detail => detail.callId === callId || detail.artifactId === callId);
+        if (!entry?.artifactId)
+            throw new errors_1.WebWorkbenchError(404, 'Tool detail was not found.');
+        return this.toolDetails.read({
+            callId: entry.callId,
+            sequence: entry.sequence,
+            artifactId: entry.artifactId,
+            outputBytes: entry.outputBytes,
+        }, { offsetBytes, limitBytes }, this.workspaceValue);
+    }
+    listFiles(context, input) {
+        this.assertContextGuard(context);
+        const result = this.fileService.list(input);
+        this.assertContextGuard(context);
+        return result;
+    }
+    readFileContent(context, input) {
+        this.assertContextGuard(context);
+        const result = this.fileService.readContent(input);
+        this.assertContextGuard(context);
+        return result;
+    }
+    async gitStatus(context, input) {
+        this.assertContextGuard(context);
+        const result = await this.gitService.status(input);
+        this.assertContextGuard(context);
+        return result;
+    }
+    async gitLog(context, input) {
+        this.assertContextGuard(context);
+        const result = await this.gitService.log(input);
+        this.assertContextGuard(context);
+        return result;
+    }
+    async gitDiff(context, input) {
+        this.assertContextGuard(context);
+        const result = await this.gitService.diff(input);
+        this.assertContextGuard(context);
+        return result;
+    }
+    async review(context) {
+        this.assertContextGuard(context);
+        try {
+            const result = await this.reviewService.snapshot();
+            this.assertContextGuard(context);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof durable_tool_receipt_reader_1.DurableToolReceiptReaderError) {
+                throw new errors_1.WebWorkbenchError(500, 'Durable Review receipt facts failed integrity validation.', 'review_receipt_invalid');
+            }
+            throw error;
+        }
+    }
+    listTerminals(context) {
+        this.assertContextGuard(context);
+        const result = this.terminalManager.list(this.activeWorkspaceEntry().id);
+        this.assertContextGuard(context);
+        return result;
+    }
+    async createSession(name, context) {
+        this.assertReadyForTransition('create a session');
+        if (context)
+            this.assertContextGuard(context);
+        this.sessionTransition = true;
+        try {
+            // A new Session inherits the durable default; an override on the currently
+            // active Session must never leak into the next Session.
+            const session = (0, session_storage_1.createSession)(this.workspaceValue, this.settings().sections.defaults.model.effectiveValue);
+            (0, global_config_1.incrementSessionCount)();
+            const named = name?.trim() ? ((0, session_storage_1.renameSession)(session.id, name.trim()) ?? session) : session;
+            this.runtimeValue.setSession(named);
+            await this.runtimeValue.rebindSessionRuntime?.();
+            this.eventHub.emitRuntime({ type: 'transcript_clear' });
+            this.emitState();
+            return (0, protocol_1.projectSessionSummary)(named);
+        }
+        finally {
+            this.sessionTransition = false;
+        }
+    }
+    async activateSession(sessionId, context) {
+        this.assertReadyForTransition('switch sessions');
+        if (context)
+            this.assertContextGuard(context);
+        this.sessionTransition = true;
+        this.suppressContextEdges += 1;
+        let activated = false;
+        try {
+            const session = requireSession(sessionId);
+            if (canonicalDirectory(session.projectPath) !== this.workspaceValue) {
+                throw new errors_1.WebWorkbenchError(409, 'Session belongs to another workspace.');
+            }
+            const result = this.controllerValue.handle({
+                type: 'select_session',
+                sessionId: session.id,
+                source: 'programmatic',
+            });
+            await this.controllerValue.waitForIdle();
+            if (this.runtimeValue.getSession()?.id !== session.id) {
+                throw new errors_1.WebWorkbenchError(409, 'Session activation was rejected by the runtime.');
+            }
+            activated = true;
+            return { requestId: `activate:${session.id}`, result: result.type };
+        }
+        finally {
+            this.suppressContextEdges -= 1;
+            this.sessionTransition = false;
+            if (activated)
+                this.emitState();
+        }
+    }
+    renameSession(sessionId, name, context) {
+        if (context)
+            this.assertContextGuard(context);
+        const session = requireSession(sessionId);
+        if (canonicalDirectory(session.projectPath) !== this.workspaceValue) {
+            throw new errors_1.WebWorkbenchError(409, 'Session belongs to another workspace.');
+        }
+        if (name.length > 120)
+            throw new errors_1.WebWorkbenchError(400, 'Session name is too long.');
+        const updated = (0, session_storage_1.renameSession)(session.id, name);
+        if (!updated)
+            throw new errors_1.WebWorkbenchError(404, 'Session no longer exists.');
+        return (0, protocol_1.projectSessionSummary)(updated);
+    }
+    async switchWorkspace(path, context) {
+        this.assertContextGuard(context);
+        const next = canonicalDirectory(path);
+        if (next === this.workspaceValue)
+            return;
+        let entry;
+        try {
+            entry = this.workspaceRegistry.register(next);
+        }
+        catch (error) {
+            throw mapWorkspaceRegistryError(error);
+        }
+        await this.activateContext({
+            expectedContextRevision: context.expectedContextRevision,
+            workspaceId: entry.id,
+            sessionId: null,
+        });
+    }
+    async activateContext(input) {
+        if (input.expectedContextRevision !== this.contextRevisionValue) {
+            throw new errors_1.WebWorkbenchError(409, 'The active Context changed before activation was admitted.', 'context_revision_conflict');
+        }
+        const entry = this.workspaceRegistry.find(input.workspaceId);
+        if (!entry)
+            throw new errors_1.WebWorkbenchError(404, 'Workspace was not found.', 'workspace_not_found');
+        const targetWorkspace = canonicalDirectory(entry.canonicalPath);
+        const targetSession = input.sessionId ? requireSession(input.sessionId) : null;
+        if (targetSession && canonicalDirectory(targetSession.projectPath) !== targetWorkspace) {
+            throw new errors_1.WebWorkbenchError(409, 'Session does not belong to the requested Workspace.', 'context_session_mismatch');
+        }
+        const currentSessionId = this.runtimeValue.getSession()?.id ?? null;
+        if (targetWorkspace === this.workspaceValue && targetSession?.id === currentSessionId)
+            return;
+        if (targetWorkspace === this.workspaceValue && !targetSession && currentSessionId === null)
+            return;
+        this.assertReadyForTransition('activate a Context');
+        const previousWorkspace = this.workspaceValue;
+        const previousSessionId = currentSessionId;
+        const previousRuntime = this.runtimeValue;
+        const previousController = this.controllerValue;
+        const transition = (async () => {
+            this.suppressContextEdges += 1;
+            try {
+                await previousController.stopActiveTurn();
+                await previousController.waitForIdle();
+                if (targetWorkspace !== previousWorkspace) {
+                    await previousRuntime.shutdown();
+                    await this.installRuntime(targetWorkspace, false);
+                }
+                await this.restoreContextSession(targetSession?.id ?? null);
+                this.workspaceRegistry.register(targetWorkspace, { activated: true });
+            }
+            catch (activationError) {
+                try {
+                    if (targetWorkspace !== previousWorkspace) {
+                        if (this.runtimeValue !== previousRuntime)
+                            await this.runtimeValue.shutdown();
+                        await this.installRuntime(previousWorkspace, false);
+                    }
+                    await this.restoreContextSession(previousSessionId);
+                }
+                catch {
+                    throw new errors_1.WebWorkbenchError(503, 'Context activation failed and the previous Context could not be restored.', 'context_recovery_required');
+                }
+                throw activationError;
+            }
+            finally {
+                this.suppressContextEdges -= 1;
+            }
+            this.emitState();
+            this.emitWorkspaceResourceInvalidation('context-change');
+            if (targetWorkspace !== previousWorkspace)
+                this.emitSettingsWorkspaceChange();
+        })().finally(() => {
+            if (this.transition === transition)
+                this.transition = undefined;
+        });
+        this.transition = transition;
+        return transition;
+    }
+    dispatch(raw) {
+        const command = (0, protocol_1.parseWebCommand)(raw);
+        return this.executeMutation(command.requestId, 'command', command, () => {
+            this.assertCommandSession(command.expectedSessionId);
+            const runtimeResult = this.controllerValue.handle((0, protocol_1.toAgentRuntimeInput)(command));
+            return Object.freeze({
+                requestId: command.requestId,
+                result: runtimeResult.type,
+                detail: JSON.stringify(runtimeResult),
+            });
+        });
+    }
+    async updateSettings(input) {
+        this.assertSettingsAvailable();
+        const update = this.runtimeValue.updateSettings;
+        if (!update) {
+            throw new errors_1.WebWorkbenchError(503, 'The product Settings coordinator is unavailable.', 'settings_document_unavailable');
+        }
+        try {
+            const result = await update({
+                requestId: input.requestId,
+                expectedRevision: input.expectedRevision,
+                operations: input.operations,
+            });
+            return Object.freeze({
+                revision: result.revision,
+                appliedKeys: result.appliedKeys,
+                settings: result.document,
+            });
+        }
+        catch (error) {
+            throw mapSettingsError(error);
+        }
+    }
+    async openSettingsDocument() {
+        this.assertSettingsAvailable();
+        const coordinator = this.runtimeValue.settingsCoordinator;
+        if (!coordinator) {
+            throw new errors_1.WebWorkbenchError(503, 'The product Settings coordinator is unavailable.', 'settings_document_unavailable');
+        }
+        try {
+            await coordinator.openDocument();
+            return true;
+        }
+        catch (error) {
+            throw mapSettingsError(error);
+        }
+    }
+    executeMutation(requestId, operation, payload, action) {
+        if (!requestId.trim() || requestId.length > 128) {
+            throw new errors_1.WebWorkbenchError(400, 'requestId must be a non-empty string up to 128 characters.');
+        }
+        const fingerprint = (0, canonical_1.digestRuntimeValue)({ operation, payload });
+        const cached = this.mutationResults.get(requestId);
+        if (cached) {
+            if (cached.fingerprint !== fingerprint) {
+                throw new errors_1.WebWorkbenchError(409, 'requestId was already used for another mutation.', 'request_id_conflict');
+            }
+            return cached.result;
+        }
+        if (this.mutationResults.size >= MAX_MUTATION_RESULTS) {
+            throw new errors_1.WebWorkbenchError(503, 'The mutation idempotency ledger is full; restart the local Web Host before retrying.', 'mutation_capacity_exhausted');
+        }
+        const result = Promise.resolve().then(() => {
+            this.assertMutationAdmission();
+            return action();
+        });
+        this.mutationResults.set(requestId, { fingerprint, result });
+        return result;
+    }
+    async diagnostics() {
+        const state = this.runtimeValue.store.getSnapshot();
+        const mcp = (0, mcp_1.loadFirstPartyMcpConfigurationV1)();
+        const activeSessionId = this.runtimeValue.getSession()?.id ?? null;
+        // Harness diagnostics may need the lazy Session runtime. A read-only Web
+        // baseline must not manufacture a Session merely by opening the page.
+        const harness = activeSessionId
+            ? ((await this.runtimeValue.getHarnessDiagnostics?.()) ?? null)
+            : null;
+        return {
+            workspace: this.workspaceValue,
+            activeSessionId,
+            configured: this.runtimeValue.isConfigured,
+            processing: state.isProcessing,
+            agentMode: state.agentMode,
+            permissionMode: state.permissionMode,
+            contextUsage: state.contextUsage,
+            tokenUsage: state.tokenUsage,
+            plan: state.currentPlan,
+            todos: state.todos,
+            skills: {
+                configuredPaths: this.runtimeValue.config.skills?.paths ?? [],
+                loadedFromPrompt: state.skillsContent.length > 0,
+            },
+            mcp: { servers: mcpServerIds(mcp) },
+            harness,
+            eventStream: this.eventHub.snapshot(),
+        };
+    }
+    async shutdown() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.controllerValue.stopActiveTurn();
+        await this.controllerValue.waitForIdle();
+        this.closeWorkspaceWatchers();
+        await this.terminalManager.shutdown();
+        await this.runtimeValue.shutdown();
+        this.eventHub.close();
+    }
+    async installRuntime(workspace, publishState = true) {
+        const runtime = await this.createRuntime(workspace);
+        this.closeWorkspaceWatchers();
+        this.activeOrionRuntime = undefined;
+        this.sessionViews.clear();
+        this.sessionViewBytes = 0;
+        this.latestStatus = 'Ready';
+        this.workspaceValue = workspace;
+        this.runtimeValue = runtime;
+        this.fileService = new file_read_service_1.FileReadServiceV1(workspace);
+        this.gitService = new git_read_model_service_1.GitReadModelServiceV1(workspace);
+        this.reviewService = new review_service_1.ReviewServiceV1(this.gitService, () => (0, durable_tool_receipt_reader_1.listProjectDurableToolReceiptRefsV1)(this.workspaceValue));
+        const eventSink = {
+            emit: (event) => {
+                if (event.type === 'status_changed')
+                    this.latestStatus = event.message;
+                if (this.suppressContextEdges > 0)
+                    return undefined;
+                const activeSessionId = this.runtimeValue.getSession()?.id;
+                const activeThread = activeSessionId && this.activeOrionRuntime?.sessionId === activeSessionId
+                    ? this.activeOrionRuntime.runtime.thread.getProjection().threadId
+                    : undefined;
+                const envelope = this.eventHub.emitRuntime(event, {
+                    ...(activeSessionId ? { sessionId: activeSessionId } : {}),
+                    ...(activeThread ? { threadId: activeThread } : {}),
+                });
+                if (event.type === 'session_restored')
+                    this.emitState();
+                if (event.type === 'tool_finished') {
+                    this.scheduleWorkspaceResourceInvalidation('tool-finished');
+                }
+                return event.type === 'transcript_append' ? `web-entry-${envelope.cursor}` : undefined;
+            },
+        };
+        this.controllerValue = new agent_runtime_controller_1.AgentRuntimeController({
+            runtime,
+            eventSink,
+            uiRenderer: 'web',
+            // Thread events are authoritative for Web transcript projection. Echoing here
+            // would duplicate every submitted user item when the Thread observer catches up.
+            echoSubmittedInput: false,
+            useRuntimeToolPermissions: true,
+            uiCapabilities: {
+                structuredPickers: true,
+                inlineProgress: true,
+                suppressLegacyTokenMeta: true,
+                extraAssistantSpacing: true,
+                suppressAbortNotice: true,
+            },
+        });
+        this.installWorkspaceWatchers();
+        if (publishState)
+            this.emitState(false);
+    }
+    emitState(advanceRevision = true) {
+        if (this.suppressContextEdges > 0)
+            return;
+        if (advanceRevision)
+            this.contextRevisionValue = (0, crypto_1.randomUUID)();
+        const workspace = this.activeWorkspaceEntry();
+        this.eventHub.emit({
+            type: 'workbench_state',
+            contextRevision: this.contextRevisionValue,
+            workspaceId: workspace.id,
+            workspace: this.workspaceValue,
+            activeSessionId: this.runtimeValue.getSession()?.id ?? null,
+        });
+    }
+    emitWorkspaceResourceInvalidation(reason) {
+        if (this.closed || this.suppressContextEdges > 0)
+            return;
+        this.eventHub.emit({
+            type: 'workspace_resource_invalidated',
+            workspaceId: this.activeWorkspaceEntry().id,
+            resources: ['files', 'git', 'review'],
+            reason,
+        }, false);
+    }
+    scheduleWorkspaceResourceInvalidation(reason) {
+        if (this.closed)
+            return;
+        if (this.resourceInvalidationTimer)
+            clearTimeout(this.resourceInvalidationTimer);
+        const workspace = this.workspaceValue;
+        this.resourceInvalidationTimer = setTimeout(() => {
+            this.resourceInvalidationTimer = undefined;
+            if (!this.closed && this.workspaceValue === workspace) {
+                this.emitWorkspaceResourceInvalidation(reason);
+            }
+        }, 120);
+        this.resourceInvalidationTimer.unref();
+    }
+    installWorkspaceWatchers() {
+        const watchPaths = [this.workspaceValue, (0, path_1.resolve)(this.workspaceValue, '.git')].filter(path => (0, fs_1.existsSync)(path));
+        for (const path of watchPaths) {
+            try {
+                const watcher = (0, fs_1.watch)(path, { persistent: false }, () => this.scheduleWorkspaceResourceInvalidation('filesystem-change'));
+                watcher.on('error', () => {
+                    watcher.close();
+                    this.workspaceWatchers = this.workspaceWatchers.filter(item => item !== watcher);
+                });
+                this.workspaceWatchers.push(watcher);
+            }
+            catch {
+                // Watchers are only refresh hints. Revisioned reads and explicit refresh remain authoritative.
+            }
+        }
+    }
+    closeWorkspaceWatchers() {
+        if (this.resourceInvalidationTimer)
+            clearTimeout(this.resourceInvalidationTimer);
+        this.resourceInvalidationTimer = undefined;
+        for (const watcher of this.workspaceWatchers)
+            watcher.close();
+        this.workspaceWatchers = [];
+    }
+    async restoreContextSession(sessionId) {
+        if (!sessionId) {
+            this.runtimeValue.setSession(null);
+            await this.runtimeValue.rebindSessionRuntime?.();
+            if (this.suppressContextEdges === 0) {
+                this.eventHub.emitRuntime({ type: 'transcript_clear' });
+            }
+            return;
+        }
+        const result = this.controllerValue.handle({
+            type: 'select_session',
+            sessionId,
+            source: 'programmatic',
+        });
+        await this.controllerValue.waitForIdle();
+        if (this.runtimeValue.getSession()?.id !== sessionId) {
+            throw new errors_1.WebWorkbenchError(409, `Session activation was rejected by the runtime (${result.type}).`, 'context_session_rejected');
+        }
+    }
+    emitSettingsWorkspaceChange() {
+        const describe = this.runtimeValue.describeSettings;
+        if (!describe) {
+            throw new errors_1.WebWorkbenchError(503, 'The product Settings coordinator is unavailable.', 'settings_document_unavailable');
+        }
+        const settings = describe();
+        this.eventHub.emit({
+            type: 'settings_invalidated',
+            revision: settings.revision,
+            reason: 'workspace-change',
+            state: settings.state === 'ready' || settings.state === 'read-only' ? 'ready' : 'invalid',
+        }, false);
+    }
+    observeThreadRuntime(runtime, sessionId, activation) {
+        let replaying = true;
+        const pending = [];
+        const unsubscribe = runtime.thread.observeCommittedEvents(events => {
+            if (replaying)
+                pending.push(...events);
+            else
+                for (const event of events)
+                    this.eventHub.emitThread(event, sessionId);
+        });
+        try {
+            const edge = runtime.thread.getProjection().cursor;
+            // Historical transcript state comes from the cursor-bound snapshot.
+            // Publishing the entire Thread through the live SSE hub on every switch
+            // made activation O(history) and evicted the reconnect window.
+            replaying = false;
+            for (const event of pending
+                .filter(event => event.seq > edge)
+                .sort((left, right) => left.seq - right.seq)) {
+                this.eventHub.emitThread(event, sessionId);
+            }
+            if (activation?.sessionId === sessionId && activation.view) {
+                this.rememberSessionView(sessionId, activation.view);
+            }
+            this.activeOrionRuntime = { runtime, sessionId };
+        }
+        catch (error) {
+            unsubscribe();
+            throw error;
+        }
+        return () => {
+            unsubscribe();
+            if (this.activeOrionRuntime?.runtime === runtime)
+                this.activeOrionRuntime = undefined;
+        };
+    }
+    loadSessionView(session, activeProjection) {
+        const expectedFingerprint = activeProjection
+            ? threadViewFingerprint(activeProjection)
+            : session.threadReadModel
+                ? [
+                    session.threadReadModel.threadId,
+                    session.threadReadModel.cursor,
+                    session.threadReadModel.projectionDigest,
+                ].join(':')
+                : undefined;
+        const cached = expectedFingerprint ? this.sessionViews.get(session.id) : undefined;
+        if (cached && expectedFingerprint && cached.fingerprint === expectedFingerprint) {
+            this.sessionViews.delete(session.id);
+            this.sessionViews.set(session.id, cached);
+            return cached.view;
+        }
+        const view = (0, thread_session_view_1.loadThreadSessionViewV1)(this.workspaceValue, session.id);
+        if (!view)
+            return undefined;
+        return this.rememberSessionView(session.id, view);
+    }
+    rememberSessionView(sessionId, view) {
+        const previous = this.sessionViews.get(sessionId);
+        if (previous)
+            this.sessionViewBytes -= previous.bytes;
+        const entry = {
+            fingerprint: [view.threadId, view.cursor, view.projectionDigest].join(':'),
+            view,
+            bytes: estimateSessionViewBytes(view),
+        };
+        this.sessionViews.delete(sessionId);
+        this.sessionViews.set(sessionId, entry);
+        this.sessionViewBytes += entry.bytes;
+        while (this.sessionViewBytes > SESSION_VIEW_CACHE_BYTES && this.sessionViews.size > 1) {
+            const oldest = this.sessionViews.keys().next().value;
+            if (!oldest)
+                break;
+            const evicted = this.sessionViews.get(oldest);
+            this.sessionViews.delete(oldest);
+            this.sessionViewBytes -= evicted?.bytes ?? 0;
+        }
+        return view;
+    }
+    assertReadyForTransition(operation) {
+        if (this.closed)
+            throw new errors_1.WebWorkbenchError(503, 'Web Workbench is closed.');
+        if (this.transition || this.sessionTransition) {
+            throw new errors_1.WebWorkbenchError(409, 'A workspace transition is running.', 'runtime_busy');
+        }
+        if (this.controllerValue.hasActiveTurn()) {
+            throw new errors_1.WebWorkbenchError(409, `Cannot ${operation} while a turn is active.`, 'runtime_busy');
+        }
+    }
+    assertMutationAdmission() {
+        if (this.closed)
+            throw new errors_1.WebWorkbenchError(503, 'Web Workbench is closed.');
+        if (this.transition || this.sessionTransition) {
+            throw new errors_1.WebWorkbenchError(409, 'A Context transition is running.', 'runtime_busy');
+        }
+    }
+    assertContextGuard(context) {
+        this.assertMutationAdmission();
+        if (context.expectedContextRevision !== this.contextRevisionValue ||
+            context.workspaceId !== this.activeWorkspaceEntry().id) {
+            throw new errors_1.WebWorkbenchError(409, 'The active Context changed before the operation was admitted.', 'context_revision_conflict');
+        }
+    }
+    assertCommandSession(expectedSessionId) {
+        if (this.closed)
+            throw new errors_1.WebWorkbenchError(503, 'Web Workbench is closed.');
+        if (this.transition || this.sessionTransition) {
+            throw new errors_1.WebWorkbenchError(409, 'A Session transition is running.', 'runtime_busy');
+        }
+        if (this.runtimeValue.getSession()?.id !== expectedSessionId) {
+            throw new errors_1.WebWorkbenchError(409, 'The active Session changed before the command was admitted.', 'active_session_changed');
+        }
+    }
+    assertSettingsAvailable() {
+        if (this.closed) {
+            throw new errors_1.WebWorkbenchError(503, 'Web Workbench is closed.', 'settings_document_unavailable');
+        }
+        if (this.transition) {
+            throw new errors_1.WebWorkbenchError(409, 'A workspace transition is running.', 'runtime_busy');
+        }
+    }
+    initializeWorkspaceRegistry() {
+        const paths = [this.workspaceValue];
+        for (const session of (0, session_storage_1.listSessions)()) {
+            try {
+                paths.push(canonicalDirectory(session.projectPath));
+            }
+            catch {
+                // Unavailable historical projects remain in the Session catalog but
+                // are not imported as selectable Workspace registry entries.
+            }
+        }
+        try {
+            this.workspaceRegistry.registerKnown(paths, this.workspaceValue);
+        }
+        catch (error) {
+            throw mapWorkspaceRegistryError(error);
+        }
+    }
+    activeWorkspaceEntry() {
+        const entry = this.workspaceRegistry
+            .list()
+            .find(candidate => candidate.canonicalPath === this.workspaceValue);
+        if (!entry) {
+            throw new errors_1.WebWorkbenchError(503, 'Active Workspace is missing from the registry.');
+        }
+        return entry;
+    }
+}
+exports.WebWorkbenchController = WebWorkbenchController;
+function mapWorkspaceRegistryError(error) {
+    if (error instanceof errors_1.WebWorkbenchError)
+        return error;
+    if (error instanceof workspace_registry_1.WorkspaceRegistryError) {
+        const status = error.code === 'workspace_registry_invalid' ? 503 : 409;
+        return new errors_1.WebWorkbenchError(status, error.message, error.code);
+    }
+    return new errors_1.WebWorkbenchError(503, 'Workspace registry is unavailable.');
+}
+function mapSettingsError(error) {
+    if (error instanceof errors_1.WebWorkbenchError)
+        return error;
+    if (error instanceof settings_coordinator_1.SettingsCoordinatorError) {
+        return new errors_1.WebWorkbenchError(error.status, error.message, error.code);
+    }
+    return new errors_1.WebWorkbenchError(503, 'The product Settings coordinator is unavailable.', 'settings_document_unavailable');
+}
+function pickPlanReceipt(receipt) {
+    return Object.freeze({
+        body: receipt.plan,
+        returnMode: receipt.returnMode,
+        digest: receipt.digest,
+    });
+}
+function threadViewFingerprint(projection) {
+    return [projection.threadId, projection.cursor, projection.digest].join(':');
+}
+function uniqueCommitProjections(commits) {
+    return [...new Map(commits.filter(Boolean).map(commit => [commit.seq, commit])).values()].sort((left, right) => left.seq - right.seq);
+}
+function latestAuthorityCommits(projection) {
+    const commits = Object.values(projection.turns)
+        .flatMap(turn => (turn.commit ? [turn.commit] : []))
+        .sort((left, right) => left.seq - right.seq);
+    const latest = commits.at(-1);
+    const latestPlan = [...commits].reverse().find(commit => {
+        try {
+            return Boolean((0, turn_commit_1.parseTurnCommitV1)(commit.receipt).planReceipt);
+        }
+        catch {
+            return false;
+        }
+    });
+    return uniqueCommitProjections([latestPlan, latest]);
+}
+function estimateSessionViewBytes(view) {
+    let bytes = 1024;
+    for (const message of view.transcriptMessages) {
+        bytes += Buffer.byteLength(message.content, 'utf8') + 256;
+        if (message.modelVisibleContent) {
+            bytes += Buffer.byteLength(message.modelVisibleContent, 'utf8');
+        }
+    }
+    for (const message of view.modelHistory) {
+        bytes += Buffer.byteLength(JSON.stringify(message), 'utf8') + 128;
+    }
+    for (const commit of uniqueCommitProjections([
+        view.latestPlanTurnCommit,
+        view.latestTurnCommit,
+    ])) {
+        bytes += Buffer.byteLength(commit.receipt, 'utf8');
+    }
+    return bytes;
+}
+function pageItems(items, cursor, pageSize = 50) {
+    if (!Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+        throw new errors_1.WebWorkbenchError(400, 'pageSize must be an integer from 1 through 100.');
+    }
+    const offset = cursor ? decodePageCursor(cursor) : 0;
+    if (offset > items.length)
+        throw new errors_1.WebWorkbenchError(400, 'Page cursor is out of range.');
+    const page = items.slice(offset, offset + pageSize);
+    const nextOffset = offset + page.length;
+    return Object.freeze({
+        items: Object.freeze(page),
+        nextCursor: nextOffset < items.length ? encodePageCursor(nextOffset) : null,
+    });
+}
+function pageCollectionItems(scope, items, cursor, pageSize, keyOf) {
+    if (!scope || scope.length > 80 || !/^[a-z][a-z0-9_-]*$/.test(scope)) {
+        throw new errors_1.WebWorkbenchError(500, 'Collection scope is invalid.');
+    }
+    if (!Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+        throw new errors_1.WebWorkbenchError(400, 'pageSize must be an integer from 1 through 100.');
+    }
+    const keys = items.map(keyOf);
+    if (keys.some(key => !key || key.length > 4096) || new Set(keys).size !== keys.length) {
+        throw new errors_1.WebWorkbenchError(500, `Collection ${scope} has invalid or duplicate keys.`);
+    }
+    const revision = (0, canonical_1.digestRuntimeValue)(items);
+    let offset = 0;
+    if (cursor) {
+        const decoded = decodeCollectionCursor(cursor, scope);
+        if (decoded.revision !== revision) {
+            throw new errors_1.WebWorkbenchError(409, 'Collection changed after this page cursor was issued.', 'collection_cursor_stale');
+        }
+        offset = keys.indexOf(decoded.after) + 1;
+        if (offset === 0) {
+            throw new errors_1.WebWorkbenchError(409, 'Collection page boundary no longer exists.', 'collection_cursor_stale');
+        }
+    }
+    const page = items.slice(offset, offset + pageSize);
+    const nextOffset = offset + page.length;
+    return Object.freeze({
+        items: Object.freeze(page),
+        nextCursor: nextOffset < items.length && page.length > 0
+            ? encodeCollectionCursor(scope, revision, keys[nextOffset - 1])
+            : null,
+    });
+}
+function pageTranscriptTail(items, cursor, pageSize = 50) {
+    if (!Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+        throw new errors_1.WebWorkbenchError(400, 'pageSize must be an integer from 1 through 100.');
+    }
+    const end = cursor ? decodePageCursor(cursor) : items.length;
+    if (end > items.length)
+        throw new errors_1.WebWorkbenchError(400, 'Page cursor is out of range.');
+    const offset = Math.max(0, end - pageSize);
+    return Object.freeze({
+        items: Object.freeze(items.slice(offset, end)),
+        nextCursor: offset > 0 ? encodePageCursor(offset) : null,
+        offset,
+    });
+}
+function encodePageCursor(offset) {
+    return Buffer.from(JSON.stringify({ version: 1, offset })).toString('base64url');
+}
+function encodeCollectionCursor(scope, revision, after) {
+    return Buffer.from(JSON.stringify({ version: 2, kind: 'collection', scope, revision, after })).toString('base64url');
+}
+function decodeCollectionCursor(cursor, expectedScope) {
+    if (!cursor || cursor.length > 8192) {
+        throw new errors_1.WebWorkbenchError(400, 'Collection page cursor is invalid.');
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (!parsed ||
+            typeof parsed !== 'object' ||
+            Array.isArray(parsed) ||
+            parsed.version !== 2 ||
+            parsed.kind !== 'collection' ||
+            parsed.scope !== expectedScope ||
+            typeof parsed.revision !== 'string' ||
+            typeof parsed.after !== 'string') {
+            throw new Error('invalid');
+        }
+        return {
+            revision: parsed.revision,
+            after: parsed.after,
+        };
+    }
+    catch {
+        throw new errors_1.WebWorkbenchError(400, 'Collection page cursor is invalid.');
+    }
+}
+function decodePageCursor(cursor) {
+    if (!cursor || cursor.length > 512)
+        throw new errors_1.WebWorkbenchError(400, 'Page cursor is invalid.');
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (!parsed ||
+            typeof parsed !== 'object' ||
+            parsed.version !== 1 ||
+            !Number.isSafeInteger(parsed.offset) ||
+            (parsed.offset ?? -1) < 0) {
+            throw new Error('invalid cursor');
+        }
+        return parsed.offset;
+    }
+    catch {
+        throw new errors_1.WebWorkbenchError(400, 'Page cursor is invalid.');
+    }
+}
+function canonicalDirectory(path) {
+    const candidate = (0, path_1.resolve)(path);
+    let canonical;
+    try {
+        canonical = (0, fs_1.realpathSync)(candidate);
+    }
+    catch {
+        throw new errors_1.WebWorkbenchError(400, 'Workspace path does not exist.');
+    }
+    try {
+        if (!(0, fs_1.statSync)(canonical).isDirectory()) {
+            throw new errors_1.WebWorkbenchError(400, 'Workspace path must be a directory.');
+        }
+    }
+    catch (error) {
+        if (error instanceof errors_1.WebWorkbenchError)
+            throw error;
+        throw new errors_1.WebWorkbenchError(400, 'Workspace path is not readable.');
+    }
+    return canonical;
+}
+function requireSession(sessionId) {
+    if (!sessionId.trim())
+        throw new errors_1.WebWorkbenchError(400, 'Session id is required.');
+    const session = (0, session_storage_1.loadSessionMeta)(sessionId);
+    if (!session)
+        throw new errors_1.WebWorkbenchError(404, 'Session was not found.');
+    return session;
+}
+function mcpServerIds(config) {
+    const ids = new Set();
+    for (const envelope of [config.mcpServers, config.servers, config.orion?.mcp?.servers]) {
+        for (const id of Object.keys(envelope ?? {}))
+            ids.add(id);
+    }
+    return [...ids].sort();
+}
+//# sourceMappingURL=workbench-controller.js.map