@opengeni/api-router 0.7.3 → 0.9.0

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 {
@@ -107,6 +112,9 @@ import {
   sendAgentSessionMessage,
   steerAgentSession,
   updateSessionTitle,
+  sessionWithEffectiveToolPolicy,
+  workspaceSessionToolPolicyDefaultServerIds,
+  workspaceSessionToolPolicyServerIds,
   type AgentSessionCommandContext,
 } from "@opengeni/core";
 import {
@@ -120,6 +128,7 @@ import {
   type RunOnOp,
 } from "@opengeni/core";
 import {
+  boundSessionEventCompactResult,
   boundSessionEventMcpPage,
   boundSessionDetailMcp,
   boundRigDetailMcp,
@@ -1401,7 +1410,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 +1425,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 +1434,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 +1445,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 +1456,7 @@ function registerWorkspaceOrchestrationTools(
         direction: requestedDirection,
         mode: requestedMode,
         payloadMode: requestedPayloadMode,
+        resultMode: requestedResultMode,
         includeTypes,
         excludeTypes,
         includeClasses,
@@ -1446,6 +1464,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 +1479,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,
@@ -1581,7 +1622,8 @@ function registerWorkspaceOrchestrationTools(
         if (callerSessionId !== null) {
           await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
         }
-        return json(await createSessionForRequest(deps, grant, grant.workspaceId, args));
+        const created = await createSessionForRequest(deps, grant, grant.workspaceId, args);
+        return json(await withMcpEffectivePolicy(deps, grant.workspaceId, created));
       },
     );
   }
@@ -2542,3 +2584,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 {