@rynx-ai/server 0.1.11-beta.3 → 0.1.11-beta.30

package/dist/remote-runtime-dispatcher.d.ts

@@ -34,7 +34,7 @@ export interface RemoteRuntimeProjectHost {
     update(projectId: string, input: RemoteRuntimeProjectCreateParams): RemoteRuntimeProject | undefined | Promise<RemoteRuntimeProject | undefined>;
     remove(projectId: string): boolean | Promise<boolean>;
 }
-export type RemoteRuntimeSessionHost = Pick<MachineSessionService, "list" | "snapshot" | "watch" | "interrupt" | "agentOptions" | "launchOptions" | "create" | "fork" | "sendMessage" | "resourcePolicy" | "beginResourceUpload" | "writeResourceUploadChunk" | "commitResourceUpload" | "getResource" | "readResource" | "deleteResource" | "enqueueMessage" | "startTerminal" | "delete" | "resolveInteraction">;
+export type RemoteRuntimeSessionHost = Pick<MachineSessionService, "list" | "snapshot" | "watch" | "interrupt" | "agentOptions" | "launchOptions" | "executionSettings" | "updateExecutionSettings" | "create" | "fork" | "sendMessage" | "resourcePolicy" | "beginResourceUpload" | "writeResourceUploadChunk" | "commitResourceUpload" | "getResource" | "readResource" | "deleteResource" | "getFile" | "readFile" | "getWorkspaceFile" | "readWorkspaceFile" | "enqueueMessage" | "startTerminal" | "delete" | "resolveInteraction">;
 export type RemoteRuntimeBrowserHost = Pick<SessionBrowserService, "getState" | "open" | "close" | "createPage" | "closePage" | "activatePage" | "navigatePage" | "goBack" | "goForward" | "reload">;
 export type RemoteRuntimeSessionEmulatorHost = Pick<SessionEmulatorService, "getState" | "listDevices" | "attach" | "detach" | "tap" | "type" | "button" | "rotate" | "launch" | "gesture" | "releaseDevice" | "stopDevice">;
 export interface OpenRemoteRuntimeSessionEvents {

package/dist/remote-runtime-dispatcher.js

@@ -125,6 +125,10 @@ export class RemoteRuntimeDispatcher {
                     return await this.withSessions(request, (sessions) => sessions.agentOptions());
                 case "session.launchOptions.list":
                     return await this.withSessions(request, (sessions) => sessions.launchOptions());
+                case "session.execution.get":
+                    return await this.withSessions(request, (sessions) => sessions.executionSettings(request.params.sessionId));
+                case "session.execution.update":
+                    return await this.withSessions(request, (sessions) => sessions.updateExecutionSettings(request.params));
                 case "session.create":
                     return await this.withSessions(request, (sessions) => sessions.create(request.params));
                 case "session.fork":
@@ -150,6 +154,14 @@ export class RemoteRuntimeDispatcher {
                     return await this.withSessions(request, (sessions) => sessions.readResource(request.params));
                 case "session.resource.delete":
                     return await this.withSessions(request, (sessions) => sessions.deleteResource(request.params));
+                case "session.file.get":
+                    return await this.withSessions(request, (sessions) => sessions.getFile(request.params));
+                case "session.file.read":
+                    return await this.withSessions(request, (sessions) => sessions.readFile(request.params));
+                case "session.workspace.file.get":
+                    return await this.withSessions(request, (sessions) => sessions.getWorkspaceFile(request.params));
+                case "session.workspace.file.read":
+                    return await this.withSessions(request, (sessions) => sessions.readWorkspaceFile(request.params));
                 case "session.message.enqueue":
                     return await this.withSessions(request, (sessions) => sessions.enqueueMessage(request.params.sessionId, request.params.message));
                 case "session.terminal.start":
@@ -343,7 +355,10 @@ function mapHostError(request, error) {
                 : error.code === "conflict"
                     ? "Remote Session resource conflicts with existing state"
                     : "Remote Session operation may have been applied";
-        return { code: error.code, message };
+        // Native lifecycle failures are already reduced to a user-safe phase and
+        // concrete Provider cause. Preserve that text over Direct Runtime so the
+        // remote UI does not collapse every startup failure into one wrapper.
+        return { code: error.code, message: error.runtimeFailure?.message ?? message };
     }
     if (request.method === "session.interrupt") {
         return {

package/dist/remote-runtime-session-projection.js

@@ -65,6 +65,9 @@ function projectRuntimeSnapshot(value) {
     const projected = {
         status: runtime.status,
         ...(runtime.statusKind === undefined ? {} : { statusKind: runtime.statusKind }),
+        ...(runtime.backgroundTaskCount === undefined
+            ? {}
+            : { backgroundTaskCount: runtime.backgroundTaskCount }),
         activeResponseIds: [],
         pendingInteractions: [],
     };
@@ -530,10 +533,12 @@ function assertEventScope(event, expectedSessionId) {
     let actual;
     switch (event.type) {
         case "session.status":
+        case "session.collaboration_mode":
         case "response.created":
         case "session.interaction.requested":
         case "session.interaction.resolved":
         case "session.interaction.cancelled":
+        case "session.interrupted":
         case "session.todos":
         case "session.rotated":
             actual = event.sessionId;

package/dist/server.d.ts

@@ -1,10 +1,10 @@
 import type { Server as HttpServer } from "node:http";
 import Koa from "koa";
 import { ConversationRuntime, type AdmissionReservation, type AgentCapabilities, type AgentSessionStore, type AppConfig, type SessionEvent, type SessionBus, type SessionLogStore, type SessionRegistry } from "@rynx-ai/core";
-import type { SessionInteractionResolution } from "@rynx-ai/protocol";
+import type { SessionImageFileReference, SessionInteractionResolution } from "@rynx-ai/protocol";
 import type { ControlRuntimeShareAddress, DaemonBrowserArtifactCleanResult, DaemonBrowserArtifactInstallInput, DaemonBrowserArtifactInstallResult, DaemonBrowserArtifactUpdateInput, DaemonBrowserArtifactVersionResult, DaemonCleanupSessionsInput, DaemonCleanupSessionsResult, DaemonChromeInspectionConfigureInput, DaemonChromeInspectionStatus, DaemonShutdownIfIdleResult } from "@rynx-ai/protocol/control";
 import type { PluginInstallCommitInput, PluginInstallCommitResult, PluginInstallPreparation, PluginInstallPrepareInput, PluginManagementItem, PluginMarketplaceAddInput, PluginMarketplaceItem } from "@rynx-ai/protocol/plugin-management";
-import type { PluginJsonValue } from "@rynx-ai/plugin-sdk";
+import type { PluginAgentSummary, PluginJsonValue, PluginResolvedSessionExecution, PluginSessionActivitySnapshot, PluginSessionExecutionSnapshot } from "@rynx-ai/plugin-sdk";
 import type { PairingOffer } from "@rynx-ai/protocol/direct-runtime";
 import type { DaemonStatus } from "@rynx-ai/protocol/remote-runtime";
 import type { RuntimeBrowserBootstrapCredential, RuntimeBrowserEndpointDescriptor } from "@rynx-ai/protocol/runtime-browser-bootstrap";
@@ -12,12 +12,14 @@ import type { RuntimeBrowserInspectMessage, RuntimeBrowserInspectTarget } from "
 import type { RuntimeBrowserSurfaceClientFrame, RuntimeBrowserSurfaceImageFrame, RuntimeBrowserSurfaceOpenFrame, RuntimeBrowserSurfaceReadyFrame, RuntimeBrowserSurfaceServerFrame } from "@rynx-ai/protocol/runtime-browser-surface";
 import type { RuntimeEmulatorSurfaceImageFrame, RuntimeEmulatorSurfaceReadyFrame } from "@rynx-ai/protocol/runtime-emulator-surface";
 import type { RemoteRuntimeRpcMethod, RemoteRuntimeRpcParams, RemoteRuntimeRpcResultFor, RemoteRuntimeSequencedSessionEvent } from "@rynx-ai/protocol/remote-runtime-rpc";
-import type { PluginAgentSummary, PluginResolvedSessionExecution, PluginSessionExecutionSnapshot } from "@rynx-ai/plugin-sdk";
 import { RunnerManager, type CodexSessionStore, type RunnerSessionContextProvider } from "@rynx-ai/runtime";
 import { type ControlPlaneDeps, type LocalSessionResourceHost, type SessionResourceLifecycle } from "./control-api.js";
 import type { MachineSessionService } from "./machine-session-service.js";
 import type { DaemonRuntimeHost } from "./remote-runtime.js";
 import { type AttachDesktopBrowserHostServerOptions } from "./desktop-browser-host.js";
+import { type SessionPortalAuthorizationPorts } from "./session-portal.js";
+export { createSessionPortalApp, startSessionPortal } from "./session-portal.js";
+export type { SessionPortalAuthorization, SessionPortalAuthorizationPorts, SessionPortalOptions, SessionPortalServer, } from "./session-portal.js";
 import { SessionRuntimeIndex } from "./session-runtime-index.js";
 import type { SessionEmulatorService } from "./session-emulator-service.js";
 import { type SessionTerminalHost } from "./session-terminal-host.js";
@@ -25,7 +27,7 @@ import type { ProviderCliManagementHost } from "./provider-cli-host.js";
 import { type RuntimeWebAccessPolicy } from "./runtime-web-auth.js";
 export type { ProviderCliManagementHost, ProviderCliStatusHost, } from "./provider-cli-host.js";
 export { MachineSessionService, MachineSessionServiceFailure, MachineSessionServiceInputError, synthesizeSessionTitle, } from "./machine-session-service.js";
-export type { MachineSessionAgentCatalogPort, MachineSessionCreateInput, MachineSessionCreateResult, MachineSessionDeleteResult, MachineSessionForkInput, MachineSessionForkOperationRecord, MachineSessionForkOperationState, MachineSessionForkResult, MachineSessionForkStorePort, MachineSessionNativeRotationInput, MachineSessionInterruptPort, MachineSessionInterruptResult, MachineSessionInteractionResult, MachineSessionListInput, MachineSessionListPage, MachineSessionMessageResult, MachineSessionMessageEnqueueResult, MachineSessionMessageInput, MachineSessionMessageOperationState, MachineSessionPendingMessage, MachineSessionPendingMessagePort, MachineSessionPreparedInput, MachineSessionResourcePort, MachineSessionRunnerPort, MachineSessionRuntimeStatePort, MachineSessionServiceFailureCode, MachineSessionServiceOptions, MachineSessionServicePorts, MachineSessionSnapshotInput, MachineSessionSnapshotPage, MachineSessionWatch, } from "./machine-session-service.js";
+export type { MachineSessionAgentCatalogPort, MachineSessionCreateInput, MachineSessionCreateResult, MachineSessionDeleteResult, MachineSessionForkInput, MachineSessionForkOperationRecord, MachineSessionForkOperationState, MachineSessionForkResult, MachineSessionForkStorePort, MachineSessionNativeRotationInput, MachineSessionInterruptPort, MachineSessionInterruptResult, MachineSessionInteractionResult, MachineSessionListInput, MachineSessionListPage, MachineSessionMessageResult, MachineSessionMessageEnqueueResult, MachineSessionMessageInput, MachineSessionMessageOperationState, MachineSessionPendingMessage, MachineSessionPendingMessagePort, MachineSessionPreparedInput, MachineSessionResourcePort, MachineSessionRunExecutionSelection, MachineSessionRunExecutionSnapshot, MachineSessionRunnerPort, MachineSessionRuntimeStatePort, MachineSessionServiceFailureCode, MachineSessionServiceOptions, MachineSessionServicePorts, MachineSessionSnapshotInput, MachineSessionSnapshotPage, MachineSessionWatch, StartedMachineSessionRun, } from "./machine-session-service.js";
 export { SessionBrowserHostError, SessionBrowserService, SessionBrowserServiceError, SessionBrowserSurfaceUnsupportedError, } from "./session-browser-service.js";
 export type { SessionBrowserHost, SessionBrowserHostCreateInput, SessionBrowserHostErrorCode, SessionBrowserHostEvent, SessionBrowserHostHandle, SessionBrowserHostPage, SessionBrowserHostSurfaceFrame, SessionBrowserHostSurfaceOpenInput, SessionBrowserHostSurfaceSource, SessionBrowserHostSurfaceTrustedInput, SessionBrowserHostSurfaceViewport, SessionBrowserHostSnapshot, SessionBrowserInspectionEndpoint, SessionBrowserInspectionTarget, SessionBrowserRegistryPort, SessionBrowserServiceErrorCode, SessionBrowserServiceOptions, SessionBrowserServicePorts, SessionBrowserSurfaceOpenInput, SessionBrowserSurfaceSource, } from "./session-browser-service.js";
 export { SessionEmulatorBindingConflictError, SessionEmulatorService, SessionEmulatorServiceError, } from "./session-emulator-service.js";
@@ -132,6 +134,9 @@ export interface StartServerOptions {
     providerClis?: ProviderCliManagementHost;
     /** Private resident-app Browser Host socket, authenticated by daemonManagement. */
     desktopBrowserHost?: Omit<AttachDesktopBrowserHostServerOptions, "managementToken">;
+    /** Hashed ticket/grant authority for the native Session Portal. Required
+     * when RYNX_SESSION_PORTAL_PORT enables that listener. */
+    sessionPortalAuthorization?: SessionPortalAuthorizationPorts;
 }
 export interface SessionRuntimeServices {
     sessionStore: CodexSessionStore;
@@ -142,10 +147,11 @@ export interface SessionRuntimeServices {
     publishSessionEvent: (sessionId: string, event: SessionEvent) => Promise<void>;
 }
 export interface PluginRuntimeHostServices {
-    conversationRuntime: ConversationRuntime;
     capabilities: AgentCapabilities;
     sessionStore: AgentSessionStore;
     sessionRegistry: SessionRegistry;
+    sessionRuns: Pick<MachineSessionService, "startRun">;
+    sessionFiles: Pick<MachineSessionService, "resolveResourcePath">;
     agentCatalog: {
         list(): Promise<PluginAgentSummary[]>;
         get(id: string): Promise<PluginAgentSummary | null>;
@@ -154,6 +160,7 @@ export interface PluginRuntimeHostServices {
             session: PluginSessionExecutionSnapshot;
         }): Promise<PluginResolvedSessionExecution>;
     };
+    sessionActivity(sessionId: string): PluginSessionActivitySnapshot;
     interruptSession(sessionId: string): Promise<boolean>;
     terminateSession?(sessionId: string): Promise<boolean>;
     resolveSessionInteraction(sessionId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<{
@@ -163,6 +170,11 @@ export interface PluginRuntimeHostServices {
      * closed, but cannot provision Sessions or begin Turns. */
     admissionOpen?: () => boolean;
     admissionReserve?: () => AdmissionReservation | undefined;
+    sessionPortal?: {
+        scheme: "http" | "https";
+        bindHost: string;
+        port: number;
+    };
 }
 export interface PluginRuntimeLifecycle {
     bindHostServices(services: PluginRuntimeHostServices): void;
@@ -339,7 +351,7 @@ export interface RuntimeConnectionLease {
     };
     call<M extends RemoteRuntimeRpcMethod>(method: M, params: RemoteRuntimeRpcParams<M>, options?: {
         signal?: AbortSignal;
-        timeoutMs?: number;
+        timeoutMs?: number | null;
     }): Promise<RemoteRuntimeRpcResultFor<M>>;
     subscribeSessionEvents(sessionId: string, options?: {
         signal?: AbortSignal;
@@ -426,6 +438,11 @@ export declare function createSessionRuntimeServices(input: {
     sessionContextProvider?: RunnerSessionContextProvider;
     admissionOpen?: () => boolean;
     admissionReserve?: () => AdmissionReservation | undefined;
+    materializeGeneratedImage?: (input: {
+        sessionId: string;
+        sourceId: string;
+        result: string;
+    }) => Promise<SessionImageFileReference>;
 }): SessionRuntimeServices;
 /**
  * The HTTP surface is just a liveness probe for container orchestration — all
@@ -434,4 +451,4 @@ export declare function createSessionRuntimeServices(input: {
  * no agent request / response / SSE endpoints are exposed here.
  */
 export declare function createApp({ config, control }?: CreateAppOptions): Koa<Koa.DefaultState, Koa.DefaultContext>;
-export declare function startServer({ config, control, sessionLog, sessionRegistry, pluginRuntime, daemonManagement, remoteRuntime, remoteRuntimeAdmin, runtimeTargetControl, runtimeConnectionResolver, localSessionResources, localMachineSessions, sessionEmulators, sessionRuntimeServices, sessionLifecycle, sessionTerminals, runtimeLocalBrowser, providerClis, desktopBrowserHost, }?: StartServerOptions): Promise<RynxServer>;
+export declare function startServer({ config, control, sessionLog, sessionRegistry, pluginRuntime, daemonManagement, remoteRuntime, remoteRuntimeAdmin, runtimeTargetControl, runtimeConnectionResolver, localSessionResources, localMachineSessions, sessionEmulators, sessionRuntimeServices, sessionLifecycle, sessionTerminals, runtimeLocalBrowser, providerClis, desktopBrowserHost, sessionPortalAuthorization, }?: StartServerOptions): Promise<RynxServer>;

package/dist/server.js

@@ -1,3 +1,4 @@
+import { basename, extname, isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
 import Koa from "koa";
 import Router from "@koa/router";
@@ -10,6 +11,8 @@ import { attachBrowserSurfaceWs } from "./browser-surface-ws.js";
 import { attachEmulatorSurfaceWs } from "./emulator-surface-ws.js";
 import { attachDesktopBrowserHostServer, } from "./desktop-browser-host.js";
 import { resolveControlWebDist, sendSpaFile } from "./control-web-dist.js";
+import { startSessionPortal, } from "./session-portal.js";
+export { createSessionPortalApp, startSessionPortal } from "./session-portal.js";
 import { SessionRuntimeIndex } from "./session-runtime-index.js";
 import { createRunnerSessionTerminalHost, } from "./session-terminal-host.js";
 import { runtimeWebAccessPolicyForBindHost, } from "./runtime-web-auth.js";
@@ -64,19 +67,24 @@ export function createSessionRuntimeServices(input) {
     });
     const sessionBus = new InMemorySessionBus();
     const sessionRuntimeIndex = new SessionRuntimeIndex();
-    const sessionMirrorQueue = new SessionMirrorQueue((sessionId, event) => persistSessionEvent(sessionId, event, { sessionLog: input.sessionLog, sessionBus }));
+    const sessionMirrorQueue = new SessionMirrorQueue(async (sessionId, event) => {
+        const finalized = await finalizeGeneratedImageEvent(sessionId, event, input);
+        sessionRuntimeIndex.observe(sessionId, finalized);
+        await persistSessionEvent(sessionId, finalized, {
+            sessionLog: input.sessionLog,
+            sessionBus,
+        });
+    });
     const mirrorSessionEvent = (sessionId, event) => {
-        sessionRuntimeIndex.observe(sessionId, event);
         return sessionMirrorQueue.enqueue(sessionId, event);
     };
     const conversationRuntime = new ConversationRuntime({
         config: input.config,
         executor: runnerManager,
         sessionBus,
-        sessionEventSink: mirrorSessionEvent,
     });
     runnerManager.onMirror((sessionId, event) => {
-        void mirrorSessionEvent(sessionId, event).catch((error) => {
+        return mirrorSessionEvent(sessionId, event).catch((error) => {
             input.onMirrorError?.(error, sessionId);
         });
     });
@@ -89,6 +97,72 @@ export function createSessionRuntimeServices(input) {
         publishSessionEvent: mirrorSessionEvent,
     };
 }
+async function finalizeGeneratedImageEvent(sessionId, event, input) {
+    if (event.type !== "response.output_item.done" ||
+        event.item.type !== "function_call_output") {
+        return event;
+    }
+    const rawData = event.item.data;
+    const pending = rawData.__rynxGeneratedImage;
+    if (!pending)
+        return event;
+    const { __rynxGeneratedImage: _omitted, ...data } = rawData;
+    try {
+        const pathMediaType = pending.savedPath && isAbsolute(pending.savedPath)
+            ? imageMediaTypeFromPath(pending.savedPath)
+            : undefined;
+        const generatedImage = pathMediaType && pending.savedPath
+            ? {
+                path: pending.savedPath,
+                filename: basename(pending.savedPath),
+                mediaType: pathMediaType,
+            }
+            : pending.result && input.materializeGeneratedImage
+                ? await input.materializeGeneratedImage({
+                    sessionId,
+                    sourceId: event.item.id,
+                    result: pending.result,
+                })
+                : undefined;
+        return {
+            ...event,
+            item: {
+                ...event.item,
+                data: {
+                    ...data,
+                    ...(generatedImage ? { generatedImage } : {}),
+                    ...(!generatedImage && pending.savedPath && !isAbsolute(pending.savedPath)
+                        ? { output: `${data.output}\nImage path was not absolute; preview omitted.`.trim() }
+                        : {}),
+                },
+            },
+        };
+    }
+    catch (error) {
+        input.onMirrorError?.(error, sessionId);
+        return {
+            ...event,
+            item: {
+                ...event.item,
+                data: {
+                    ...data,
+                    output: `${data.output}\nImage preview unavailable.`.trim(),
+                },
+            },
+        };
+    }
+}
+function imageMediaTypeFromPath(path) {
+    switch (extname(path).toLowerCase()) {
+        case ".png": return "image/png";
+        case ".jpg":
+        case ".jpeg": return "image/jpeg";
+        case ".webp": return "image/webp";
+        case ".gif": return "image/gif";
+        case ".svg": return "image/svg+xml";
+        default: return undefined;
+    }
+}
 /**
  * The HTTP surface is just a liveness probe for container orchestration — all
  * agent capabilities are forwarded through the mounted channel plugins (the
@@ -137,7 +211,7 @@ export function createApp({ config = loadConfig(), control } = {}) {
     }
     return app;
 }
-export async function startServer({ config = loadConfig(), control, sessionLog, sessionRegistry, pluginRuntime, daemonManagement, remoteRuntime, remoteRuntimeAdmin, runtimeTargetControl, runtimeConnectionResolver, localSessionResources, localMachineSessions, sessionEmulators, sessionRuntimeServices, sessionLifecycle, sessionTerminals, runtimeLocalBrowser, providerClis, desktopBrowserHost, } = {}) {
+export async function startServer({ config = loadConfig(), control, sessionLog, sessionRegistry, pluginRuntime, daemonManagement, remoteRuntime, remoteRuntimeAdmin, runtimeTargetControl, runtimeConnectionResolver, localSessionResources, localMachineSessions, sessionEmulators, sessionRuntimeServices, sessionLifecycle, sessionTerminals, runtimeLocalBrowser, providerClis, desktopBrowserHost, sessionPortalAuthorization, } = {}) {
     const runtimeWebAccess = runtimeWebAccessPolicyForBindHost(config.HOST);
     const desktopBrowserManagementToken = desktopBrowserHost
         ? requireDaemonManagementToken(daemonManagement)
@@ -160,14 +234,58 @@ export async function startServer({ config = loadConfig(), control, sessionLog,
                 return { cwd: session.workspace.cwd };
             },
         });
+    const controlShutdown = new AbortController();
+    const controlSurface = control
+        ? {
+            deps: control,
+            runtime: conversationRuntime,
+            sessionBus,
+            sessionLog,
+            runnerManager,
+            sessionStore,
+            pluginRuntimeStatus: pluginRuntime
+                ? () => pluginRuntime.statusSnapshot()
+                : undefined,
+            daemonManagement,
+            remoteRuntime,
+            remoteRuntimeAdmin,
+            runtimeTargetControl,
+            runtimeConnectionResolver,
+            localSessionResources,
+            localMachineSessions,
+            sessionEmulators,
+            shutdownSignal: controlShutdown.signal,
+            sessionRuntimeIndex,
+            sessionLifecycle,
+            runtimeLocalBrowser,
+            providerClis,
+        }
+        : undefined;
+    const sessionPortalConfig = config.RYNX_SESSION_PORTAL_PORT !== undefined
+        ? (() => {
+            if (runtimeWebAccess.mode !== "loopback") {
+                throw new Error("Session Portal requires the ordinary Control listener to bind loopback only");
+            }
+            const controlWebDist = resolveControlWebDist();
+            if (!sessionPortalAuthorization || !controlSurface || !controlWebDist) {
+                throw new Error("Session Portal requires authorization, Control services, and the native Control Web build");
+            }
+            return { authorization: sessionPortalAuthorization, controlWebDist };
+        })()
+        : undefined;
+    let sessionPortalServer;
     if (pluginRuntime) {
         if (!sessionRegistry)
             throw new Error("plugin runtime requires a machine session registry");
+        if (!localMachineSessions) {
+            throw new Error("plugin runtime requires the machine Session service");
+        }
         pluginRuntime.bindHostServices({
-            conversationRuntime,
             capabilities: runnerManager,
             sessionStore,
             sessionRegistry,
+            sessionRuns: localMachineSessions,
+            sessionFiles: localMachineSessions,
             agentCatalog: {
                 list: async () => (await listAgentSpecs()).map(toPluginAgentSummary),
                 get: async (id) => {
@@ -180,9 +298,27 @@ export async function startServer({ config = loadConfig(), control, sessionLog,
                     session: input.session,
                 }),
             },
+            sessionActivity: (sessionId) => {
+                const snapshot = sessionRuntimeIndex.snapshot(sessionId);
+                return {
+                    ...snapshot,
+                    status: snapshot.pendingInteractions.length > 0
+                        ? "waiting"
+                        : snapshot.status,
+                };
+            },
             interruptSession: (sessionId) => runnerManager.interruptLiveSession(sessionId),
             terminateSession: (sessionId) => runnerManager.terminateLiveSession(sessionId),
             resolveSessionInteraction: (sessionId, interactionId, resolution) => runnerManager.resolveInteraction(sessionId, interactionId, resolution),
+            ...(sessionPortalConfig
+                ? {
+                    sessionPortal: {
+                        scheme: "http",
+                        bindHost: config.RYNX_SESSION_PORTAL_HOST,
+                        port: config.RYNX_SESSION_PORTAL_PORT,
+                    },
+                }
+                : {}),
         });
     }
     // Provider TUI `/clear`·`/fork` uses the same publication boundary as an
@@ -198,38 +334,37 @@ export async function startServer({ config = loadConfig(), control, sessionLog,
             kind: r.kind,
         });
     });
-    const controlShutdown = new AbortController();
+    if (localMachineSessions) {
+        runnerManager.onCollaborationMode((sessionId, mode) => {
+            localMachineSessions.recordNativeCollaborationMode(sessionId, mode);
+        });
+    }
     const app = createApp({
         config,
-        control: control
-            ? {
-                deps: control,
-                runtime: conversationRuntime,
-                sessionBus,
-                sessionLog,
-                runnerManager,
-                sessionStore,
-                pluginRuntimeStatus: pluginRuntime
-                    ? () => pluginRuntime.statusSnapshot()
-                    : undefined,
-                daemonManagement,
-                remoteRuntime,
-                remoteRuntimeAdmin,
-                runtimeTargetControl,
-                runtimeConnectionResolver,
-                localSessionResources,
-                localMachineSessions,
-                sessionEmulators,
-                shutdownSignal: controlShutdown.signal,
-                sessionRuntimeIndex,
-                sessionLifecycle,
-                runtimeLocalBrowser,
-                providerClis,
-            }
-            : undefined,
+        control: controlSurface,
     });
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
+        let startupWebSocketServers = [];
+        const rejectBeforeListening = (error) => reject(error);
         const server = app.listen(config.PORT, config.HOST, () => {
+            server.off("error", rejectBeforeListening);
+            void finishStartup(server).catch(async (error) => {
+                controlShutdown.abort(asError(error));
+                sessionPortalServer?.stopAccepting();
+                server.closeAllConnections?.();
+                await Promise.allSettled([
+                    closeWebSocketServers(startupWebSocketServers),
+                    sessionPortalServer?.shutdown() ?? Promise.resolve(),
+                    new Promise((done) => server.close(() => done())),
+                    Promise.resolve(daemonManagement?.pluginManagement?.dispose?.()),
+                    Promise.resolve(pluginRuntime?.dispose()),
+                    runnerManager.stop(),
+                ]);
+                reject(error);
+            });
+        });
+        server.once("error", rejectBeforeListening);
+        const finishStartup = async (server) => {
             console.log(JSON.stringify({
                 level: config.LOG_LEVEL,
                 msg: "Harness agent server listening",
@@ -238,15 +373,6 @@ export async function startServer({ config = loadConfig(), control, sessionLog,
                 runtime: config.DEFAULT_RUNTIME,
                 model: resolveRuntimeModel(config, config.DEFAULT_RUNTIME),
             }));
-            const startup = pluginRuntime?.startPluginRuntimes() ?? Promise.resolve();
-            void startup.catch((error) => {
-                console.error(JSON.stringify({
-                    level: "error",
-                    type: "plugin-runtime",
-                    event: "startup_failed",
-                    error: error instanceof Error ? error.message : String(error),
-                }));
-            });
             const webSocketServers = [
                 attachTerminalWs(server, {
                     runtimeConnectionResolver,
@@ -265,9 +391,36 @@ export async function startServer({ config = loadConfig(), control, sessionLog,
             if (control?.emulator) {
                 webSocketServers.push(attachEmulatorTouchWs(server, { emulator: control.emulator }));
             }
+            startupWebSocketServers = webSocketServers;
+            if (sessionPortalConfig) {
+                sessionPortalServer = await startSessionPortal({
+                    host: config.RYNX_SESSION_PORTAL_HOST,
+                    port: config.RYNX_SESSION_PORTAL_PORT,
+                    scheme: "http",
+                    authorization: sessionPortalConfig.authorization,
+                    controlOrigin: listeningHttpOrigin(server),
+                    controlWebDist: sessionPortalConfig.controlWebDist,
+                    shutdownSignal: controlShutdown.signal,
+                });
+            }
+            const startup = pluginRuntime?.startPluginRuntimes() ?? Promise.resolve();
+            void startup.catch((error) => {
+                console.error(JSON.stringify({
+                    level: "error",
+                    type: "plugin-runtime",
+                    event: "startup_failed",
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            });
             resolve(bindServerLifecycle(server, {
-                fence: () => controlShutdown.abort(new Error("Rynx server is shutting down")),
-                closeUpgrades: () => closeWebSocketServers(webSocketServers),
+                fence: () => {
+                    controlShutdown.abort(new Error("Rynx server is shutting down"));
+                    sessionPortalServer?.stopAccepting();
+                },
+                closeUpgrades: () => Promise.all([
+                    closeWebSocketServers(webSocketServers),
+                    sessionPortalServer?.shutdown() ?? Promise.resolve(),
+                ]).then(() => undefined),
                 cleanup: async () => runCleanupSteps([
                     () => startup.catch(() => undefined),
                     () => Promise.resolve(daemonManagement?.pluginManagement?.dispose?.()),
@@ -275,9 +428,17 @@ export async function startServer({ config = loadConfig(), control, sessionLog,
                     () => runnerManager.stop(),
                 ]),
             }));
-        });
+        };
     });
 }
+function listeningHttpOrigin(server) {
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        throw new Error("Control listener did not expose an HTTP address");
+    }
+    const host = address.address.includes(":") ? `[${address.address}]` : address.address;
+    return `http://${host}:${address.port}`;
+}
 function requireDaemonManagementToken(host) {
     const token = host?.managementToken;
     const bytes = typeof token === "string" ? Buffer.byteLength(token, "utf8") : 0;

package/dist/session-portal.d.ts

@@ -0,0 +1,42 @@
+import { type IncomingMessage, type Server as HttpServer } from "node:http";
+import type { Duplex } from "node:stream";
+import Koa from "koa";
+export declare const SESSION_PORTAL_HEADER = "x-rynx-session-portal";
+export declare const SESSION_PORTAL_QUERY = "portal";
+export interface SessionPortalAuthorization {
+    portalId: string;
+    pluginId: string;
+    scope: "plugin_sessions" | "single_session";
+    access: "read_only" | "read_write";
+    sessionId?: string;
+    expiresAt: string;
+}
+export interface SessionPortalAuthorizationPorts {
+    redeem(ticket: string): (SessionPortalAuthorization & {
+        secret: string;
+    }) | undefined;
+    authorize(portalId: string, secret: string): SessionPortalAuthorization | undefined;
+    ownsSession(pluginId: string, sessionId: string): boolean;
+}
+export interface SessionPortalOptions {
+    host: string;
+    port: number;
+    scheme: "http" | "https";
+    authorization: SessionPortalAuthorizationPorts;
+    controlOrigin: string;
+    controlWebDist: string;
+    shutdownSignal?: AbortSignal;
+}
+export interface SessionPortalServer {
+    server: HttpServer;
+    stopAccepting(): void;
+    shutdown(): Promise<void>;
+}
+/** Session Portal is a narrow adapter in front of the one Control service. It
+ * serves the native SPA, validates Portal grants, and forwards only authorized
+ * Session HTTP calls to Control; it owns no Session or Runtime handlers. */
+export declare function createSessionPortalApp(options: SessionPortalOptions): Koa;
+export declare function startSessionPortal(options: SessionPortalOptions): Promise<SessionPortalServer>;
+export declare function authorizeSessionPortalWebSocket(request: IncomingMessage, ports: SessionPortalAuthorizationPorts, runtimeSelector: string, sessionId: string): SessionPortalAuthorization | undefined;
+export declare function rejectSessionPortalUpgrade(socket: Duplex): void;
+export declare function scheduleSessionPortalExpiry(expiresAt: string, onExpire: () => void): () => void;