@opengeni/api-router 0.7.3 → 0.11.1

package/src/mcp/server.ts

@@ -2,11 +2,15 @@ import {
   CreateScheduledTaskRequest,
   defaultRepositoryMountPath,
   SESSION_EVENT_RAW_DELTA_TYPES,
+  SessionEventLatestClass,
   SessionEventPayloadMode,
   SessionEventReadDirection,
   SessionEventReadMode,
+  SessionEventResultMode,
   SessionEventSemanticClass,
   SessionEventType,
+  compactSessionEventResult,
+  sessionEventLatestClassToSemanticClass,
   SessionMcpCredentialUpdateInput,
   VariableSetVariableName,
   type AccessGrant,
@@ -14,6 +18,7 @@ import {
   type Permission,
   type ResourceRef,
   type SessionAuthorizationOperation,
+  type Session,
   UpdateScheduledTaskRequest,
 } from "@opengeni/contracts";
 import {
@@ -53,15 +58,15 @@ import {
   saveWorkspaceMemory,
   searchWorkspaceMemories,
   serializeEffectiveSessionControl,
-  setSessionGoalStatus,
+  setSessionGoalStatusWithEvent,
   setVariableSetVariable,
   updateScheduledTask,
-  updateSessionGoal,
-  upsertSessionGoal,
+  updateSessionGoalWithEvent,
+  upsertSessionGoalWithEvent,
   RigChangeAlreadyVerifyingError,
   RigChangeTransitionError,
 } from "@opengeni/db";
-import { appendAndPublishEvents } from "@opengeni/events";
+import { appendAndPublishEvents, publishDurableSessionEvents } from "@opengeni/events";
 import {
   createGitHubAppInstallationToken,
   GitHubAppConfigurationError,
@@ -104,9 +109,14 @@ import {
   controlAgentSessionWorkstream,
   controlHumanSessionWorkstream,
   createSessionForRequest,
+  SessionSpawnDeniedError,
+  sessionSpawnDenialEnvelope,
   sendAgentSessionMessage,
   steerAgentSession,
   updateSessionTitle,
+  sessionWithEffectiveToolPolicy,
+  workspaceSessionToolPolicyDefaultServerIds,
+  workspaceSessionToolPolicyServerIds,
   type AgentSessionCommandContext,
 } from "@opengeni/core";
 import {
@@ -120,12 +130,14 @@ import {
   type RunOnOp,
 } from "@opengeni/core";
 import {
+  boundSessionEventCompactResult,
   boundSessionEventMcpPage,
   boundSessionDetailMcp,
   boundRigDetailMcp,
   SESSION_EVENT_MCP_MAX_BYTES,
 } from "./session-view";
 import type { ToolspaceMcpSurface } from "./toolspace";
+import { ensureSessionGroupReady as ensureViewerSessionGroupReady } from "../sandbox/viewer";
 
 export type McpServerOptions = {
   // Origin of the HTTP request that reached the MCP route. Retained in the
@@ -730,7 +742,7 @@ function registerGoalTools(
           ? (grant.metadata["turnId"] as string)
           : null;
       await assertGoalReactivationAllowed(deps, grant.workspaceId, sessionId, callerTurnId);
-      const { goal, replaced } = await upsertSessionGoal(deps.db, {
+      const { goal, events } = await upsertSessionGoalWithEvent(deps.db, {
         accountId: grant.accountId,
         workspaceId: grant.workspaceId,
         sessionId,
@@ -738,20 +750,11 @@ function registerGoalTools(
         successCriteria: successCriteria ?? null,
         maxAutoContinuations: maxAutoContinuations ?? null,
         createdBy: "agent",
+        actor: "agent",
       });
-      await appendAndPublishEvents(deps.db, deps.bus, grant.workspaceId, sessionId, [
-        {
-          type: "goal.set",
-          payload: {
-            goalId: goal.id,
-            text: goal.text,
-            ...(goal.successCriteria ? { successCriteria: goal.successCriteria } : {}),
-            version: goal.version,
-            actor: "agent",
-            replaced,
-          },
-        },
-      ]);
+      if (events.length > 0) {
+        await deps.bus.publish(grant.workspaceId, sessionId, events);
+      }
       return json(goal);
     },
   );
@@ -765,36 +768,36 @@ function registerGoalTools(
         text: z4.string().min(1).optional(),
         successCriteria: z4.string().min(1).optional(),
         progressNote: z4.string().min(1).optional(),
+        idempotencyKey: z4.string().uuid(),
       },
     },
-    async ({ text, successCriteria, progressNote }) => {
+    async ({ text, successCriteria, progressNote, idempotencyKey }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
-      await requireSession(deps.db, grant.workspaceId, sessionId);
-      const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
-      if (!existing) {
-        throw new Error("this session has no goal; use goal_set first");
-      }
-      if (existing.status === "completed") {
-        throw new Error("session goal is completed; use goal_set to start a new goal");
-      }
-      const goal = await updateSessionGoal(deps.db, grant.workspaceId, sessionId, {
-        ...(text !== undefined ? { text } : {}),
-        ...(successCriteria !== undefined ? { successCriteria } : {}),
-      });
-      await appendAndPublishEvents(deps.db, deps.bus, grant.workspaceId, sessionId, [
+      const context = exactAgentCommandContext(grant, sessionId);
+      const { goal, events, operationId, replay } = await updateSessionGoalWithEvent(
+        deps.db,
+        grant.workspaceId,
+        sessionId,
         {
-          type: "goal.updated",
-          payload: {
-            goalId: goal.id,
-            text: goal.text,
-            ...(goal.successCriteria ? { successCriteria: goal.successCriteria } : {}),
-            ...(progressNote ? { progressNote } : {}),
-            version: goal.version,
-            actor: "agent",
+          ...(text !== undefined ? { text } : {}),
+          ...(successCriteria !== undefined ? { successCriteria } : {}),
+          ...(progressNote !== undefined ? { progressNote } : {}),
+          actor: "agent",
+          command: {
+            accountId: grant.accountId,
+            actor: {
+              type: "agent_attempt",
+              attemptId: context.callerAttemptId,
+              sessionId: context.callerSessionId,
+              turnId: context.callerTurnId,
+              executionGeneration: context.callerExecutionGeneration,
+            },
+            operationKey: idempotencyKey,
           },
         },
-      ]);
-      return json(goal);
+      );
+      await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, events);
+      return json({ ...goal, operationId, replay });
     },
   );
 
@@ -812,17 +815,18 @@ function registerGoalTools(
       if (!existing) {
         throw new Error("this session has no goal; use goal_set first");
       }
-      const { goal, changed } = await setSessionGoalStatus(deps.db, grant.workspaceId, sessionId, {
-        status: "completed",
-        evidence,
-      });
-      if (changed) {
-        await appendAndPublishEvents(deps.db, deps.bus, grant.workspaceId, sessionId, [
-          {
-            type: "goal.completed",
-            payload: { goalId: goal.id, evidence, version: goal.version },
-          },
-        ]);
+      const { goal, events } = await setSessionGoalStatusWithEvent(
+        deps.db,
+        grant.workspaceId,
+        sessionId,
+        {
+          status: "completed",
+          evidence,
+          event: { type: "goal.completed", evidence },
+        },
+      );
+      if (events.length > 0) {
+        await deps.bus.publish(grant.workspaceId, sessionId, events);
       }
       return json(goal);
     },
@@ -842,25 +846,24 @@ function registerGoalTools(
       if (!existing) {
         throw new Error("this session has no goal; use goal_set first");
       }
-      const { goal, changed } = await setSessionGoalStatus(deps.db, grant.workspaceId, sessionId, {
-        status: "paused",
-        rationale,
-        pausedReason: "agent",
-      });
-      if (changed) {
-        await appendAndPublishEvents(deps.db, deps.bus, grant.workspaceId, sessionId, [
-          {
+      const { goal, events } = await setSessionGoalStatusWithEvent(
+        deps.db,
+        grant.workspaceId,
+        sessionId,
+        {
+          status: "paused",
+          rationale,
+          pausedReason: "agent",
+          event: {
             type: "goal.paused",
-            payload: {
-              goalId: goal.id,
-              actor: "agent",
-              reason: "agent",
-              rationale,
-              autoContinuations: goal.autoContinuations,
-              noProgressStreak: goal.noProgressStreak,
-            },
+            actor: "agent",
+            reason: "agent",
+            rationale,
           },
-        ]);
+        },
+      );
+      if (events.length > 0) {
+        await deps.bus.publish(grant.workspaceId, sessionId, events);
       }
       return json(goal);
     },
@@ -1029,6 +1032,13 @@ function registerFleetTools(
     db: deps.db,
     settings: deps.settings,
     bus: deps.bus,
+    ensureSessionGroupReady: async (ctx) => {
+      const session = await requireSession(deps.db, ctx.workspaceId, ctx.sessionId);
+      return await ensureViewerSessionGroupReady(
+        { db: deps.db, settings: deps.settings, bus: deps.bus },
+        { accountId: ctx.accountId, workspaceId: ctx.workspaceId, session },
+      );
+    },
   };
 
   // Resolve the session's group sandbox (the default/home fleet member) at
@@ -1046,7 +1056,7 @@ function registerFleetTools(
     "sandboxes_list",
     {
       description:
-        "List the sandboxes this session can run on: its own session sandbox (the Modal box) PLUS the workspace's enrolled selfhosted machines, each with liveness (online/reconnecting/offline) and an `active` marker for the currently-routed one. Use before sandbox_attach/sandbox_swap to pick a target. The `id` of any entry is the `target` for attach/swap/run_on.",
+        "List the sandboxes this session can run on: its own session sandbox plus enrolled selfhosted machines. `liveness` is conservative: online requires observed provider existence and verified workspace readiness. Provider, lease, route, archive, restore, workspace, lease epoch, and route epoch are also reported separately. Use an entry `id` as an attach/swap/run_on target.",
       inputSchema: {},
     },
     async () => json(await listFleet(services, await fleetContext())),
@@ -1056,7 +1066,7 @@ function registerFleetTools(
     "sandbox_attach",
     {
       description:
-        'Attach this session to a sandbox (make it the active sandbox the agent\'s next tool calls run on). Heterogeneous: a Modal box or an enrolled selfhosted machine. Validates the target is owned by this workspace and online, then repoints under an epoch fence. Identical mechanic to sandbox_swap; use `target` = a sandboxes_list `id`, or "session"/"default" for this session\'s own box.',
+        'Attach this session to a sandbox for the next tool call. The target must be owned and verified ready. A same-target attach is a repair request: it revalidates readiness and advances the route epoch rather than returning unchanged success. Recovery-in-progress/degraded/unrecoverable outcomes are typed. Use a sandboxes_list `id`, or "session"/"default" for home.',
       inputSchema: { target: z4.string().min(1) },
     },
     async ({ target }) => json(await swapActiveSandbox(services, await fleetContext(), target)),
@@ -1066,7 +1076,7 @@ function registerFleetTools(
     "sandbox_swap",
     {
       description:
-        'Swap the active sandbox for this session mid-conversation (the next tool call runs on the new box). Heterogeneous Modal<->selfhosted<->selfhosted, single active at a time, flippable as many times as you like. Validates ownership + liveness, then bumps the active epoch (fencing any in-flight op, which retries against the new box). `target` = a sandboxes_list `id`, or "session"/"default" to swap back to this session\'s own box.',
+        'Swap the active sandbox for this session mid-conversation. Validates ownership and verified readiness, then advances the route epoch. Same-target swaps also revalidate and fence stale route caches. An operation that encountered provider disappearance is not replayed; retry only after a typed recovery-ready result. Use a sandboxes_list `id`, or "session"/"default" for home.',
       inputSchema: { target: z4.string().min(1) },
     },
     async ({ target }) => json(await swapActiveSandbox(services, await fleetContext(), target)),
@@ -1401,7 +1411,14 @@ function registerWorkspaceOrchestrationTools(
           },
           authorization?.relatedSessionAccess ?? "root",
         );
-        return json(boundSessionDetailMcp(projected));
+        return json(
+          boundSessionDetailMcp(
+            await withMcpEffectivePolicy(deps, grant.workspaceId, {
+              ...projected,
+              effectiveControl: queue?.effectiveControl ?? projected.effectiveControl,
+            }),
+          ),
+        );
       },
     );
 
@@ -1409,7 +1426,7 @@ function registerWorkspaceOrchestrationTools(
       "session_events",
       {
         description:
-          "Read a compact semantic tail only when session_get status is insufficient. With no cursor, this returns the newest matching events and excludes raw message/reasoning/command/PTY deltas. Use `latest` as an exclusive lookup for the newest event in exactly one semantic class; it cannot be combined with type or class filters. Use nextBefore to page older or explicit after/nextAfter to page forward. Type/class filters run in the RLS-scoped database query. payloadMode none|summary|full controls retained audit payload projection, but every model result is independently byte-capped with explicit truncation and exact covered sequence bounds. Exact retained forensic payloads require the access-controlled REST/SDK events API with mode=forensic&payloadMode=full; generic source bytes never retained by the audit boundary remain unavailable.",
+          "Read a compact semantic tail only when session_get status is insufficient. With no cursor, this returns the newest matching events and excludes raw message/reasoning/command/PTY deltas. Use `latest` as an exclusive lookup for the authoritative newest durable sequence in exactly one semantic class; `receipt` is the concise alias for `tool_receipt`, and latest cannot be combined with type or class filters. Add `resultMode=compact` to latest for one bounded result-bearing completion/checkpoint/receipt without another inference. Use nextBefore to page older or explicit after/nextAfter to page forward. Type/class filters run in the RLS-scoped database query. payloadMode none|summary|full controls retained audit payload projection, but every model result is independently byte-capped with explicit truncation and exact covered sequence bounds. Exact retained forensic payloads require the access-controlled REST/SDK events API with mode=forensic&payloadMode=full; generic source bytes never retained by the audit boundary remain unavailable.",
         inputSchema: {
           sessionId: z4.string().uuid(),
           after: z4.number().int().nonnegative().optional(),
@@ -1418,6 +1435,7 @@ function registerWorkspaceOrchestrationTools(
           direction: z4.enum(SessionEventReadDirection.options).optional(),
           mode: z4.enum(SessionEventReadMode.options).optional(),
           payloadMode: z4.enum(SessionEventPayloadMode.options).optional(),
+          resultMode: z4.enum(SessionEventResultMode.options).optional(),
           includeTypes: z4.array(z4.enum(SessionEventType.options)).max(100).optional(),
           excludeTypes: z4.array(z4.enum(SessionEventType.options)).max(100).optional(),
           includeClasses: z4
@@ -1428,7 +1446,7 @@ function registerWorkspaceOrchestrationTools(
             .array(z4.enum(SessionEventSemanticClass.options))
             .max(SessionEventSemanticClass.options.length)
             .optional(),
-          latest: z4.enum(SessionEventSemanticClass.options).optional(),
+          latest: z4.enum(SessionEventLatestClass.options).optional(),
         },
       },
       async ({
@@ -1439,6 +1457,7 @@ function registerWorkspaceOrchestrationTools(
         direction: requestedDirection,
         mode: requestedMode,
         payloadMode: requestedPayloadMode,
+        resultMode: requestedResultMode,
         includeTypes,
         excludeTypes,
         includeClasses,
@@ -1446,6 +1465,11 @@ function registerWorkspaceOrchestrationTools(
         latest,
       }) => {
         await authorizeFirstPartySession(deps, grant, sessionId, "session.events.read");
+        const latestClass =
+          latest === undefined ? undefined : sessionEventLatestClassToSemanticClass(latest);
+        if (requestedResultMode === "compact" && latestClass === undefined) {
+          throw new Error("resultMode=compact requires latest");
+        }
         await requireSession(deps.db, grant.workspaceId, sessionId);
         if (
           latest &&
@@ -1456,24 +1480,42 @@ function registerWorkspaceOrchestrationTools(
           throw new Error("latest cannot be combined with event filters");
         }
         const mode = requestedMode ?? (after !== undefined ? "forensic" : "monitoring");
-        const direction = latest
+        const direction = latestClass
           ? "before"
           : (requestedDirection ??
             (before !== undefined ? "before" : after !== undefined ? "after" : "before"));
-        const payloadMode = requestedPayloadMode ?? (mode === "monitoring" ? "summary" : "full");
+        const payloadMode =
+          requestedResultMode === "compact"
+            ? "full"
+            : (requestedPayloadMode ?? (mode === "monitoring" ? "summary" : "full"));
         const dbPage = await listSessionEventPage(deps.db, grant.workspaceId, sessionId, {
           after: after ?? 0,
           ...(before !== undefined ? { before } : {}),
           direction,
-          limit: latest ? 1 : boundedSessionEventMcpLimit(limit),
+          limit: latestClass ? 1 : boundedSessionEventMcpLimit(limit),
           payloadMode,
           includeTypes: includeTypes ?? [],
           excludeTypes: excludeTypes ?? [],
-          includeClasses: latest ? [latest] : (includeClasses ?? []),
+          includeClasses: latestClass ? [latestClass] : (includeClasses ?? []),
           excludeClasses: excludeClasses ?? [],
           ...(mode === "monitoring" ? { defaultExcludeTypes: SESSION_EVENT_RAW_DELTA_TYPES } : {}),
+          ...(latestClass ? { authoritativeLatest: true } : {}),
           maxBytes: SESSION_EVENT_MCP_MAX_BYTES * 4,
         });
+        if (requestedResultMode === "compact") {
+          const event = dbPage.events[0];
+          return json(
+            event
+              ? boundSessionEventCompactResult(
+                  compactSessionEventResult(
+                    event,
+                    latestClass!,
+                    dbPage.coveredSequence ?? { first: event.sequence, last: event.sequence },
+                  ),
+                )
+              : null,
+          );
+        }
         return json(
           boundSessionEventMcpPage({
             events: dbPage.events,
@@ -1534,6 +1576,9 @@ function registerWorkspaceOrchestrationTools(
           // Workspace-scoped CREATE idempotency key: a retried session_create with
           // the same key returns the already-spawned worker instead of a duplicate.
           idempotencyKey: z4.string().min(1).max(200).optional(),
+          // Per-session/agent descendant policy. Reductions need only create;
+          // increases are authorized server-side with workspace:admin.
+          maxNestedAgentDepth: z4.number().int().nonnegative().optional(),
           // First-party MCP token permissions for the spawned session; every
           // permission must be held by this grant (validated in the domain).
           // A goal requires goals:manage in the resulting set; it is never
@@ -1578,10 +1623,21 @@ function registerWorkspaceOrchestrationTools(
         },
       },
       async (args) => {
-        if (callerSessionId !== null) {
-          await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
+        try {
+          if (callerSessionId !== null) {
+            await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
+          }
+          const created = await createSessionForRequest(deps, grant, grant.workspaceId, args);
+          return json(await withMcpEffectivePolicy(deps, grant.workspaceId, created));
+        } catch (error) {
+          if (error instanceof SessionSpawnDeniedError) {
+            return {
+              ...json(sessionSpawnDenialEnvelope(error)),
+              isError: true,
+            };
+          }
+          throw error;
         }
-        return json(await createSessionForRequest(deps, grant, grant.workspaceId, args));
       },
     );
   }
@@ -2542,3 +2598,15 @@ function parseMcpDate(raw: string, label: string): Date {
   }
   return date;
 }
+
+async function withMcpEffectivePolicy(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  session: Session,
+): Promise<Session> {
+  const [workspaceServerIds, workspaceDefaultServerIds] = await Promise.all([
+    workspaceSessionToolPolicyServerIds(deps.db, workspaceId, deps.settings),
+    workspaceSessionToolPolicyDefaultServerIds(deps.db, workspaceId, deps.settings),
+  ]);
+  return sessionWithEffectiveToolPolicy(session, workspaceServerIds, workspaceDefaultServerIds);
+}

package/src/mcp/session-view.ts

@@ -13,11 +13,16 @@ import type {
   Rig,
   Session,
   SessionEvent,
+  SessionEventCompactResult,
   SessionEventPayloadMode,
   SessionEventReadDirection,
   SessionEventReadMode,
 } from "@opengeni/contracts";
-import { measureSessionEventJson } from "@opengeni/contracts";
+import {
+  boundSessionEventPayload,
+  measureSessionEventJson,
+  sessionEventJsonBytes,
+} from "@opengeni/contracts";
 
 export const SESSION_EVENT_MCP_MAX_BYTES = 64 * 1024;
 export const SESSION_EVENT_MCP_FIELD_MAX_CHARS = 4_000;
@@ -25,6 +30,102 @@ export const DEFAULT_SESSION_DETAIL_CHARS = 6_000;
 export const SESSION_DETAIL_MCP_MAX_BYTES = 64 * 1024;
 export const RIG_DETAIL_MCP_MAX_BYTES = 64 * 1024;
 
+/**
+ * Keep the single-result MCP response below the same pretty-JSON envelope as
+ * event pages. The contracts projection bounds each value independently for
+ * HTTP/SDK use; this second boundary accounts for the result identity,
+ * failure/truncation metadata, and MCP's pretty-printing overhead.
+ */
+export function boundSessionEventCompactResult(
+  result: SessionEventCompactResult,
+  maxBytes = SESSION_EVENT_MCP_MAX_BYTES,
+): SessionEventCompactResult {
+  const envelopeMaxBytes = Math.max(8 * 1024, maxBytes);
+
+  const project = (budget: number): SessionEventCompactResult => {
+    const noValues = budget <= 0;
+    const text =
+      noValues || result.text === null ? null : clampString(result.text, Math.max(128, budget));
+    const boundValue = (value: unknown): unknown =>
+      noValues || value === null
+        ? null
+        : boundSessionEventPayload(value, {
+            surface: "http_projection",
+            maxBytes: Math.max(1_024, budget),
+          });
+    const output = boundValue(result.output);
+    const resultValue = boundValue(result.result);
+    const checkpoint = boundValue(result.checkpoint);
+    const receipt = boundValue(result.receipt);
+    const failure =
+      noValues || result.failure === null
+        ? null
+        : {
+            error:
+              clampString(result.failure.error ?? "", Math.max(128, Math.floor(budget / 3))) ||
+              null,
+            code:
+              clampString(result.failure.code ?? "", Math.max(128, Math.floor(budget / 6))) || null,
+            retryable: result.failure.retryable,
+            recovery:
+              clampString(result.failure.recovery ?? "", Math.max(128, Math.floor(budget / 3))) ||
+              null,
+          };
+    const changed =
+      text !== result.text ||
+      output !== result.output ||
+      resultValue !== result.result ||
+      checkpoint !== result.checkpoint ||
+      receipt !== result.receipt ||
+      JSON.stringify(failure) !== JSON.stringify(result.failure);
+    // A compact result can inherit a source-payload boundary without any of
+    // its already-bounded slots changing at the MCP boundary. Keep that loss
+    // visible on the model-facing result, but do not manufacture a new byte
+    // count: the source projection owns the original/delivered accounting.
+    const inheritedSourceBoundary = result.truncation.fields.includes("payload");
+    const mcpBoundaryRecorded = changed || inheritedSourceBoundary;
+    const deliveredBytes = sessionEventJsonBytes({
+      text,
+      output,
+      result: resultValue,
+      failure,
+      checkpoint,
+      receipt,
+    });
+    return {
+      ...result,
+      text,
+      output,
+      result: resultValue,
+      failure,
+      checkpoint,
+      receipt,
+      truncation: {
+        ...result.truncation,
+        truncated: result.truncation.truncated || changed,
+        fields: mcpBoundaryRecorded
+          ? [...new Set([...result.truncation.fields, "mcp_envelope"])]
+          : result.truncation.fields,
+        originalBytes: changed
+          ? (result.truncation.originalBytes ?? result.truncation.deliveredBytes)
+          : result.truncation.originalBytes,
+        deliveredBytes,
+      },
+    };
+  };
+
+  // Start with a generous budget and tighten only if the full compact result
+  // would exceed MCP's envelope. This preserves as much result-bearing data
+  // as possible while guaranteeing a truthful bounded response.
+  for (const budget of [12_000, 8_000, 4_000, 2_000, 1_000, 0]) {
+    const candidate = project(budget);
+    if (prettyJsonBytes(candidate) <= envelopeMaxBytes) return candidate;
+  }
+  throw new RangeError(
+    `Session-event compact result exceeds its ${envelopeMaxBytes}-byte envelope`,
+  );
+}
+
 function safeStringify(value: unknown): string {
   if (typeof value === "string") return value;
   try {