@opengeni/api-router 0.2.2 → 0.4.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createApp
-} from "./chunk-XSYUDIX3.js";
+} from "./chunk-I2EDWHVF.js";
 
 // src/index.ts
 import { dbSearchPath, getSettings, resolveNatsCalloutConfig, resolveNatsControlPlaneAuth, retryStartupDependency, startupRetryOptions } from "@opengeni/config";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -46,16 +46,16 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/agent-proto": "^0.2.1",
     "@opengeni/codex": "^0.2.1",
-    "@opengeni/config": "^0.2.2",
-    "@opengeni/contracts": "^0.4.0",
-    "@opengeni/core": "^0.2.2",
-    "@opengeni/db": "^0.2.2",
-    "@opengeni/documents": "^0.2.2",
-    "@opengeni/events": "^0.2.2",
-    "@opengeni/github": "^0.2.2",
+    "@opengeni/config": "^0.2.4",
+    "@opengeni/contracts": "^0.6.0",
+    "@opengeni/core": "^0.4.0",
+    "@opengeni/db": "^0.4.0",
+    "@opengeni/documents": "^0.2.4",
+    "@opengeni/events": "^0.2.4",
+    "@opengeni/github": "^0.2.4",
     "@opengeni/observability": "^0.2.1",
-    "@opengeni/runtime": "^0.2.2",
-    "@opengeni/storage": "^0.2.2",
+    "@opengeni/runtime": "^0.3.0",
+    "@opengeni/storage": "^0.2.4",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/mcp/server.ts

@@ -1,5 +1,6 @@
 import {
   CreateScheduledTaskRequest,
+  SessionMcpCredentialUpdateInput,
   WorkspaceEnvironmentVariableName,
   type AccessGrant,
   type GitHubRepository,
@@ -628,9 +629,17 @@ function registerWorkspaceOrchestrationTools(
       description: "Spawn a new agent session (a worker) with an initial message and optional goal, resources (e.g. repositories from github_repositories_list), tools, and workspace environment attachment. Environment attachment happens at creation only — it cannot be added to a running session — and requires the environments:use permission. When targetSandboxId names a machine, workingDir sets the working directory (cwd) the spawned session runs under on that machine.",
       inputSchema: {
         initialMessage: z4.string().min(1),
+        // Per-session agent persona/system instructions for the spawned worker
+        // (a per-agent-type prompt). Delivered system-level, composed AFTER the
+        // workspace persona; never shown in the worker's timeline. Trimmed,
+        // non-empty, max 32768 chars (re-validated by the contracts schema).
+        instructions: z4.string().min(1).max(32768).optional(),
         goal: z4.unknown().optional(),
         resources: z4.array(z4.unknown()).optional(),
         tools: z4.array(z4.unknown()).optional(),
+        // Per-session third-party MCP servers. Credential header values are
+        // accepted only at create and never appear in responses/events.
+        mcpServers: z4.array(z4.unknown()).optional(),
         environmentId: z4.string().uuid().optional(),
         model: z4.string().min(1).optional(),
         reasoningEffort: z4.string().optional(),
@@ -691,11 +700,15 @@ function registerWorkspaceOrchestrationTools(
       inputSchema: {
         sessionId: z4.string().uuid(),
         text: z4.string().min(1),
+        // Header-value rotation only. URL/name/tool settings are immutable
+        // after create; core enforces mcp_servers:attach on this field.
+        mcpCredentialUpdates: z4.array(z4.unknown()).optional(),
       },
-    }, async ({ sessionId, text }) => {
+    }, async ({ sessionId, text, mcpCredentialUpdates }) => {
       const { accepted, turn } = await acceptSessionUserMessage(deps, grant, grant.workspaceId, sessionId, {
         text,
         toolsProvided: false,
+        mcpCredentialUpdates: (mcpCredentialUpdates ?? []).map((update) => SessionMcpCredentialUpdateInput.parse(update)),
       });
       return json({ event: accepted, turnId: turn.id });
     });

package/src/routes/sessions.ts

@@ -56,15 +56,15 @@ import {
   updateQueuedSessionTurn,
   type AppendEventInput,
 } from "@opengeni/db";
-import { appendAndPublishEvents } from "@opengeni/events";
+import { appendAndPublishEvents, coalesceSessionEventDeltas } from "@opengeni/events";
 import { withChannelA } from "../sandbox/channel-a";
 import { negotiateCapabilities } from "@opengeni/runtime/sandbox";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { requireAccessGrant } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { attachViewer, detachViewer, heartbeatViewer, mintDesktopStream, mintTerminalStream, readGroupLease, viewerHeartbeatIntervalMs, type DesktopStreamMint, type TerminalStreamMint } from "../sandbox/viewer";
-import { settingsWithEnabledCapabilityMcpServers } from "@opengeni/core";
+import { attachViewer, detachViewer, heartbeatViewer, mintDesktopStream, mintTerminalStream, readGroupLease, resolveActiveDesktopTransport, viewerHeartbeatIntervalMs, type DesktopStreamMint, type TerminalStreamMint } from "../sandbox/viewer";
+import { settingsWithEnabledCapabilityMcpServers, settingsWithSessionMcpServerMetadata } from "@opengeni/core";
 import {
   normalizeResources,
   validateFileResources,
@@ -284,9 +284,16 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     await requireAccessGrant(c, deps, workspaceId, "sessions:read");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
-    const after = Number(c.req.query("after") ?? 0);
-    const limit = Number(c.req.query("limit") ?? 500);
-    return c.json(await listSessionEvents(db, workspaceId, sessionId, Number.isFinite(after) ? after : 0, Number.isFinite(limit) ? limit : 500));
+    const after = eventSequence(c.req.query("after"), 0);
+    const before = optionalEventSequence(c.req.query("before"));
+    const compact = compactEvents(c.req.query("compact"));
+    const limit = eventListLimit(c.req.query("limit"), compact ? 5000 : 2000);
+    const events = await listSessionEvents(db, workspaceId, sessionId, {
+      after,
+      ...(before !== undefined ? { before } : {}),
+      limit,
+    });
+    return c.json(compact ? coalesceSessionEventDeltas(events) : events);
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/events/stream", async (c) => {
@@ -317,14 +324,17 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     // A turn-update may switch the queued turn's model; reject one the host
     // does not expose (omitted leaves the existing model unchanged).
     assertConfiguredModel(settings, payload.model);
-    const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
+    const session = await requireSession(db, workspaceId, sessionId);
+    const runtimeSettings = settingsWithSessionMcpServerMetadata(
+      await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings),
+      session.mcpServers,
+    );
     const resources = payload.resources !== undefined ? normalizeResources(payload.resources) : existing.resources;
     const tools = payload.tools !== undefined ? validateToolRefs(payload.tools, runtimeSettings) : existing.tools;
     if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
       throw new HTTPException(503, { message: "object storage is not configured" });
     }
     await validateFileResources(db, workspaceId, resources);
-    const session = await requireSession(db, workspaceId, sessionId);
     await validateGitHubRepositorySelection(db, workspaceId, [...session.resources, ...resources]);
     const turn = await updateQueuedSessionTurn(db, workspaceId, turnId, {
       ...(payload.prompt !== undefined ? { prompt: payload.prompt.trim() } : {}),
@@ -388,6 +398,7 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         toolsProvided: userMessagePayloadHasOwnProperty(rawEvent, "tools"),
         model: event.payload.model ?? null,
         reasoningEffort: event.payload.reasoningEffort ?? null,
+        mcpCredentialUpdates: event.payload.mcpCredentialUpdates ?? [],
         ...(event.clientEventId ? { clientEventId: event.clientEventId } : {}),
       });
       return c.json(accepted, 202);
@@ -579,28 +590,33 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         : {}),
     });
 
-    // SWAP-CASE desktop transport: the negotiation keyed on the HOME backend, but
-    // the desktop/terminal plane actually runs on the ACTIVE sandbox when one is
-    // pinned. If that active sandbox is a SELFHOSTED machine, its desktop is the
-    // RELAY framebuffer (PNG-per-frame) — the "relay-frames"/"frames" client, NOT
-    // the home box's noVNC. Override the cell so the viewer selects the frame
-    // renderer (the mint already served the machine's relay url). Machine-PRIMARY
-    // sessions (home backend already selfhosted) negotiate relay-frames directly,
-    // so the `=== "vnc-ws"` guard skips the extra lookup for them.
+    // SWAP-CASE desktop transport (BOTH directions): negotiateCapabilities keyed on
+    // the HOME backend, but the pixel plane actually runs on the ACTIVE sandbox — and
+    // the two backends use DIFFERENT wire transports. The advertised transport MUST
+    // match where mintDesktopStream routed the pixels (relay IFF the active sandbox is
+    // a selfhosted machine), or the client picks the wrong renderer and the socket
+    // closes before it opens:
+    //   • modal-HOME swapped ONTO a selfhosted machine: negotiate says vnc-ws, but the
+    //     machine's desktop is the RELAY framebuffer (PNG-per-frame) → flip to
+    //     relay-frames/frames. (#171)
+    //   • selfhosted-HOME swapped AWAY to the cloud group box (activeSandboxId=null OR a
+    //     non-selfhosted active sandbox): negotiate says relay-frames (home=selfhosted),
+    //     but there is NO relay producer on the Modal box → the client hangs on a dead
+    //     relay socket ("desktop stream closed before it opened"). Flip to the Modal
+    //     noVNC/RFB tunnel (vnc-ws/novnc). This is the mirror of #171 and the missing
+    //     half that this fixes.
+    // The single invariant: advertise relay-frames IFF (activeSandboxId set AND the
+    // active sandbox kind is "selfhosted") — EXACTLY mintDesktopStream's routing. When
+    // the desktop is available we set the transport from the ACTIVE sandbox in one
+    // place (resolveActiveDesktopTransport), covering BOTH swap directions.
     let responseCapabilities = capabilities;
-    if (session.activeSandboxId && capabilities.DesktopStream.transport === "vnc-ws") {
-      const activeSandbox = await getSandbox(db, workspaceId, session.activeSandboxId);
-      if (activeSandbox?.kind === "selfhosted") {
-        responseCapabilities = {
-          ...capabilities,
-          DesktopStream: {
-            ...capabilities.DesktopStream,
-            transport: "relay-frames",
-            client: "frames",
-            mode: "read-only",
-          },
-        };
-      }
+    if (capabilities.DesktopStream.transport !== null) {
+      const activeSandbox = session.activeSandboxId ? await getSandbox(db, workspaceId, session.activeSandboxId) : null;
+      const wire = resolveActiveDesktopTransport(activeSandbox?.kind === "selfhosted", settings.sandboxDesktopInteractive !== false);
+      responseCapabilities = {
+        ...capabilities,
+        DesktopStream: { ...capabilities.DesktopStream, ...wire },
+      };
     }
     return c.json(responseCapabilities);
   });
@@ -774,8 +790,13 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         streamToken: stream?.token ?? null,
         streamExpiresAt: stream?.expiresAt ?? null,
         resolution: stream?.resolution ?? null,
-        transport: stream ? ("vnc-ws" as const) : null,
-        client: stream ? ("novnc" as const) : null,
+        // Transport MUST match where the pixels were minted: a selfhosted-active box
+        // serves the RELAY framebuffer (relay-frames/frames), a Modal box serves noVNC
+        // (vnc-ws/novnc). Hardcoding vnc-ws here handed a machine's relay URL to the
+        // noVNC renderer (and vice-versa on the swap-away case) → "closed before it
+        // opened". Key off the SAME selfhostedActive the mint routed on.
+        transport: stream ? (selfhostedActive ? ("relay-frames" as const) : ("vnc-ws" as const)) : null,
+        client: stream ? (selfhostedActive ? ("frames" as const) : ("novnc" as const)) : null,
         // The REAL PTY terminal address (pty-ws), null when degraded.
         terminalUrl: terminal?.url ?? null,
         terminalToken: terminal?.token ?? null,
@@ -1070,6 +1091,37 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 }
 
+function eventListLimit(raw: string | undefined, max = 2000): number {
+  const limit = Number(raw ?? 500);
+  if (!Number.isFinite(limit)) {
+    return 500;
+  }
+  return Math.min(max, Math.max(1, Math.floor(limit)));
+}
+
+function compactEvents(raw: string | undefined): boolean {
+  return raw === "1" || raw === "true";
+}
+
+function eventSequence(raw: string | undefined, fallback: number): number {
+  const sequence = Number(raw ?? fallback);
+  if (!Number.isFinite(sequence)) {
+    return fallback;
+  }
+  return Math.floor(sequence);
+}
+
+function optionalEventSequence(raw: string | undefined): number | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+  const sequence = Number(raw);
+  if (!Number.isFinite(sequence)) {
+    return undefined;
+  }
+  return Math.floor(sequence);
+}
+
 function hasOwnProperty(value: unknown, key: string): boolean {
   return Boolean(value && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, key));
 }

package/src/sandbox/viewer.ts

@@ -381,6 +381,29 @@ async function dropEstablishedHandle(established: EstablishedSandboxSession | un
 // is the out-of-band signal to the OTHER viewers of the same session.
 // ============================================================================
 
+/**
+ * The desktop WIRE transport for the session's ACTIVE sandbox — the single
+ * invariant that keeps the advertised transport in lockstep with where
+ * mintDesktopStream routed the pixels. It MUST be derived from the ACTIVE sandbox
+ * (not the session's HOME backend that negotiateCapabilities keys on): a selfhosted
+ * machine serves the RELAY framebuffer (PNG-per-frame → "relay-frames"/"frames",
+ * view-only in v1), and a Modal group box serves noVNC/RFB over the 6080 tunnel
+ * (→ "vnc-ws"/"novnc", take-control unless the deployment disabled it). Advertising
+ * relay-frames for a Modal box (the swap-away case) hands the client a dead relay
+ * socket → "desktop stream closed before it opened"; the reverse hands a machine's
+ * relay URL to the noVNC renderer. `selfhostedActive` == (activeSandboxId set AND the
+ * active sandbox kind is "selfhosted") — EXACTLY mintDesktopStream's routing predicate.
+ */
+export function resolveActiveDesktopTransport(
+  selfhostedActive: boolean,
+  interactive: boolean,
+): { transport: "relay-frames" | "vnc-ws"; client: "frames" | "novnc"; mode: "read-only" | "interactive" } {
+  if (selfhostedActive) {
+    return { transport: "relay-frames", client: "frames", mode: "read-only" };
+  }
+  return { transport: "vnc-ws", client: "novnc", mode: interactive ? "interactive" : "read-only" };
+}
+
 /** The minted pixel cell the handshake/attach folds into the DesktopStream
  *  capability. Null when degraded (no secret, headless backend, display-stack
  *  failure, provider tunnel failure) — degradation is a value, never a throw. */