@opengeni/api-router 0.30.3 → 1.0.0

package/src/mcp/session-event-view.ts

@@ -0,0 +1,383 @@
+import { z } from "zod";
+import {
+  assistantMessagePhase,
+  type SessionEvent,
+  type SessionEventType,
+} from "@opengeni/contracts";
+import type {
+  SessionEventSliceOptions,
+  SessionEventSlicePage,
+} from "@opengeni/db/session-event-slices";
+
+export const SESSION_EVENT_VIEW_MAX_BYTES = 16 * 1024;
+const selectionSchema = z.object({
+  sessionId: z.string().uuid(),
+  view: z.enum(["conversation", "results", "tools"]),
+  includeArguments: z.boolean(),
+  includeOutput: z.boolean(),
+  callId: z
+    .string()
+    .max(512)
+    .refine(
+      (value) => Buffer.byteLength(JSON.stringify(value), "utf8") <= 2048,
+      "callId exceeds the encoded cursor budget",
+    )
+    .nullable(),
+  toolName: z
+    .string()
+    .min(1)
+    .max(256)
+    .refine(
+      (value) => Buffer.byteLength(JSON.stringify(value), "utf8") <= 512,
+      "toolName exceeds the encoded cursor budget",
+    )
+    .nullable()
+    .default(null),
+  limit: z.number().int().min(1).max(50).optional(),
+  direction: z.enum(["before", "after"]),
+  after: z.number().int().nonnegative(),
+  before: z.number().int().positive().nullable(),
+});
+const cursorSchema = z.object({
+  v: z.union([z.literal(1), z.literal(2)]),
+  selection: selectionSchema,
+  sequence: z.number().int().positive().nullable(),
+  offset: z.number().int().nonnegative().max(2_147_483_647),
+});
+type Selection = z.infer<typeof selectionSchema>;
+export type SessionEventViewInput = {
+  sessionId: string;
+  view?: Selection["view"] | undefined;
+  after?: number | undefined;
+  before?: number | undefined;
+  direction?: Selection["direction"] | undefined;
+  limit?: number | undefined;
+  cursor?: string | undefined;
+  callId?: string | undefined;
+  toolName?: string | undefined;
+  includeArguments?: boolean | undefined;
+  includeOutput?: boolean | undefined;
+};
+type Item = { sequence: number; turnId?: string; role?: string; text?: string } & Record<
+  string,
+  unknown
+>;
+type ReadPage = (options: SessionEventSliceOptions) => Promise<SessionEventSlicePage>;
+const types: Record<Selection["view"], SessionEventType[]> = {
+  conversation: ["user.message", "agent.message.completed"],
+  // Final turn output is authoritative: do not repeat message.completed text.
+  results: ["turn.completed", "turn.failed", "goal.completed", "goal.paused", "tool.auth_needed"],
+  tools: ["agent.toolCall.created", "agent.toolCall.output"],
+};
+const record = (value: unknown): Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+const bytes = (value: unknown) => Buffer.byteLength(JSON.stringify(value, null, 2), "utf8");
+const encode = (selection: Selection, sequence: number | null = null, offset = 0, v = 2) =>
+  Buffer.from(JSON.stringify({ v, selection, sequence, offset })).toString("base64url");
+
+/** A cursor is a bounded selector, never authority. The caller reauthorizes every read. */
+export function resolveSessionEventView(input: SessionEventViewInput) {
+  let continuation: z.infer<typeof cursorSchema> | null = null;
+  if (input.cursor !== undefined) {
+    if (input.cursor.length > 4096)
+      throw new Error("session_events cursor exceeds 4096 characters");
+    try {
+      continuation = cursorSchema.parse(
+        JSON.parse(Buffer.from(input.cursor, "base64url").toString()),
+      );
+    } catch {
+      throw new Error("Invalid session_events cursor");
+    }
+    const previous = continuation.selection;
+    for (const key of [
+      "sessionId",
+      "view",
+      "includeArguments",
+      "includeOutput",
+      "callId",
+      "toolName",
+      "direction",
+      "after",
+      "before",
+    ] as const) {
+      if (input[key] !== undefined && input[key] !== previous[key]) {
+        throw new Error(`session_events cursor cannot change ${key}`);
+      }
+    }
+  }
+  const selection =
+    continuation?.selection ??
+    selectionSchema.parse({
+      sessionId: input.sessionId,
+      view: input.view ?? "conversation",
+      includeArguments: input.includeArguments ?? false,
+      includeOutput: input.includeOutput ?? false,
+      callId: input.callId ?? null,
+      toolName: input.toolName ?? null,
+      direction:
+        input.direction ??
+        (input.before !== undefined || input.after === undefined ? "before" : "after"),
+      after: input.after ?? 0,
+      before: input.before ?? null,
+    });
+  selection.limit = z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .parse(input.limit ?? selection.limit ?? 10);
+  if (selection.toolName && selection.includeOutput)
+    throw new Error(
+      "toolName selects named calls. Read a result with its callId and includeOutput=true.",
+    );
+  if (
+    selection.view !== "tools" &&
+    (selection.callId ||
+      selection.toolName ||
+      selection.includeArguments ||
+      selection.includeOutput)
+  ) {
+    throw new Error("callId/toolName/includeArguments/includeOutput require view=tools");
+  }
+  if (
+    continuation &&
+    ((continuation.sequence === null && continuation.offset !== 0) ||
+      (continuation.sequence !== null &&
+        (continuation.sequence <= selection.after ||
+          (selection.before !== null && continuation.sequence >= selection.before))))
+  )
+    throw new Error("Invalid session_events cursor position");
+  return { selection, continuation };
+}
+
+function project(event: SessionEvent, selection: Selection): Item | null {
+  if (event.duplicateOfEventId || (event.turnAssociation && event.turnAssociation !== "current"))
+    return null;
+  const p = record(event.payload);
+  const base = { sequence: event.sequence, ...(event.turnId ? { turnId: event.turnId } : {}) };
+  if (selection.view === "conversation") {
+    // Commentary stays in the conversation, labelled so a reader can tell a
+    // progress note from an answer.
+    const phase = event.type === "agent.message.completed" ? assistantMessagePhase(p) : null;
+    return typeof p.text === "string" && p.text.length > 0
+      ? {
+          ...base,
+          role: event.type === "user.message" ? "user" : "assistant",
+          ...(phase ? { phase } : {}),
+          text: p.text,
+        }
+      : null;
+  }
+  if (selection.view === "results") {
+    if (event.type === "turn.completed" && ("maintenance" in p || "segmentLimit" in p)) return null;
+    const value = event.type === "turn.completed" ? (p.output ?? p.result) : p;
+    if (value === undefined || value === "") return null;
+    return {
+      ...base,
+      type: event.type,
+      text: typeof value === "string" ? value : JSON.stringify(value),
+    };
+  }
+  if (
+    selection.toolName &&
+    (event.type !== "agent.toolCall.created" || p.name !== selection.toolName)
+  )
+    return null;
+  const callId = p.callId ?? p.call_id ?? p.id;
+  if (selection.callId !== null && selection.callId !== callId) return null;
+  const output = event.type === "agent.toolCall.output";
+  // Choose one canonical slot. Never ship the raw receipt beside its parsed copy.
+  const value = output ? p.output : (p.arguments ?? p.args);
+  return {
+    ...base,
+    callId,
+    kind: output ? "result" : "call",
+    ...(typeof p.name === "string" ? { name: p.name } : {}),
+    ...(p.identityOmitted === true ? { identityOmitted: true } : {}),
+    ...(p.isError === true || record(value).isError === true ? { isError: true } : {}),
+    ...((output ? selection.includeOutput : selection.includeArguments) && value !== undefined
+      ? {
+          text: typeof value === "string" ? value : JSON.stringify(value),
+          encoding: typeof value === "string" ? "text" : "json",
+        }
+      : {}),
+  };
+}
+
+/** Read-only projection over the existing RLS/audit query. No command observations. */
+export async function readSessionEventView(input: SessionEventViewInput, read: ReadPage) {
+  const { selection, continuation } = resolveSessionEventView(input);
+  const limit = selection.limit!;
+  let after =
+    continuation?.sequence && selection.direction === "after"
+      ? continuation.sequence - 1
+      : selection.after;
+  let before =
+    continuation?.sequence && selection.direction === "before"
+      ? continuation.sequence + 1
+      : selection.before;
+  const events: Item[] = [];
+  let hasMore = false;
+  let nextCursor: string | null = null;
+  let sourceExact = true;
+  let edge: number | null = null;
+  let legacyActive = continuation?.v === 1 && continuation.sequence !== null;
+  const page = () => ({
+    view: selection.view,
+    effectiveLimit: limit,
+    direction: selection.direction,
+    events,
+    nextAfter: selection.direction === "after" ? (edge ?? selection.after) : null,
+    nextBefore: selection.direction === "before" ? (edge ?? selection.before) : null,
+    hasMore,
+    nextCursor,
+    sourceExact,
+    ...(!sourceExact
+      ? {
+          sourceLoss: {
+            reason: "structured_value_exceeds_budget" as const,
+            completeTextAvailable: false as const,
+            message:
+              "An oversized structured value was omitted. Scalar text remains retrievable through continuation; omitted structured values are not complete JSON results.",
+          },
+        }
+      : {}),
+    maxBytes: SESSION_EVENT_VIEW_MAX_BYTES,
+  });
+  const resume = (sequence: number, offset = 0) => {
+    hasMore = true;
+    nextCursor = encode(
+      { ...selection, after, before },
+      sequence,
+      offset,
+      legacyActive && sequence === continuation?.sequence ? 1 : 2,
+    );
+  };
+  // Bound work even when a sparse exact callId lookup matches nothing. The
+  // returned cursor advances the scan without claiming the lookup is exhausted.
+  for (let scan = 0; scan < 64; scan += 1) {
+    const source = await read({
+      after,
+      ...(before === null ? {} : { before }),
+      direction: selection.direction,
+      limit: 8,
+      includeTypes: selection.toolName ? ["agent.toolCall.created"] : types[selection.view],
+      ...(selection.toolName ? { toolName: selection.toolName } : {}),
+      ...(selection.callId ? { callId: selection.callId } : {}),
+      payloadMode: "full",
+      excludeUnclaimedHumanPrompts: true,
+      maxBytes: 1024 * 1024,
+      legacyUtf16: legacyActive,
+      view: selection.view,
+      includeArguments: selection.includeArguments,
+      includeOutput: selection.includeOutput,
+      ...(continuation?.sequence
+        ? { sourceSequence: continuation.sequence, sourceOffset: continuation.offset }
+        : {}),
+    });
+    sourceExact &&= source.fullPayloadsExact;
+    const ordered = selection.direction === "before" ? [...source.events].reverse() : source.events;
+    for (const event of ordered) {
+      const slice = source.slices?.[event.sequence];
+      const item = project(event, selection);
+      if (item) {
+        const offset = continuation?.sequence === event.sequence ? continuation.offset : 0;
+        if (slice?.omitted) {
+          delete item.text;
+          item.sourceOmitted = { reason: "structured_value_exceeds_budget", complete: false };
+        }
+        const advance = (text: string) =>
+          slice?.unit === "codepoint" ? Array.from(text).length : text.length;
+        if (!slice && offset > (item.text?.length ?? 0))
+          throw new Error("Invalid message continuation offset");
+        if (
+          !slice &&
+          offset > 0 &&
+          item.text &&
+          /[\uD800-\uDBFF]/.test(item.text[offset - 1]!) &&
+          /[\uDC00-\uDFFF]/.test(item.text[offset] ?? "")
+        ) {
+          throw new Error("Invalid message continuation offset: splits a surrogate pair");
+        }
+        if (!slice && offset > 0 && item.text) item.text = item.text.slice(offset);
+        events.push(item);
+        // Reserve enough for the bounded cursor and fragment facts.
+        if (bytes(page()) > SESSION_EVENT_VIEW_MAX_BYTES - 4096) {
+          events.pop();
+          if (events.length > 0) {
+            resume(event.sequence, offset);
+            if (selection.direction === "before") events.reverse();
+            return page();
+          }
+          if (!item.text) throw new Error("Session event identity exceeds page budget");
+          const text = item.text;
+          let low = 0;
+          let high = text.length;
+          while (low < high) {
+            const mid = Math.ceil((low + high) / 2);
+            if (bytes({ ...item, text: text.slice(0, mid) }) <= SESSION_EVENT_VIEW_MAX_BYTES - 6000)
+              low = mid;
+            else high = mid - 1;
+          }
+          // Do not split a UTF-16 surrogate pair (UTF-8 remains lossless).
+          if (low > 0 && /[\uD800-\uDBFF]/.test(text[low - 1]!)) low -= 1;
+          if (low === 0) throw new Error("Session event identity exceeds page budget");
+          events.push({
+            ...item,
+            text: text.slice(0, low),
+            fragment: {
+              offset,
+              nextOffset: offset + advance(text.slice(0, low)),
+              complete: false,
+              unit: slice?.unit ?? "utf16",
+            },
+          });
+          resume(event.sequence, offset + advance(text.slice(0, low)));
+          return page();
+        }
+        const nextOffset = offset + advance(item.text ?? "");
+        if (slice && !slice.omitted && nextOffset < slice.total) {
+          item.fragment = { offset, nextOffset, complete: false, unit: slice.unit };
+          resume(event.sequence, nextOffset);
+          if (selection.direction === "before") events.reverse();
+          return page();
+        }
+        if (offset > 0)
+          item.fragment = {
+            offset,
+            nextOffset,
+            complete: true,
+            unit: slice?.unit ?? "utf16",
+          };
+      }
+      edge = event.sequence;
+      legacyActive = false;
+      if (selection.direction === "after") after = event.sequence;
+      else before = event.sequence;
+      if (events.length >= limit) {
+        hasMore = source.hasMore || event !== ordered.at(-1);
+        nextCursor = hasMore ? encode({ ...selection, after, before }) : null;
+        if (selection.direction === "before") events.reverse();
+        return page();
+      }
+    }
+    // Metadata selection can advance over stale/duplicate rows without a
+    // projected payload. Use its covered edge rather than repeating the page.
+    if (source.coveredSequence) {
+      if (selection.direction === "after") after = Math.max(after, source.coveredSequence.last);
+      else before = Math.min(before ?? Infinity, source.coveredSequence.first);
+    }
+    if (!source.hasMore) {
+      hasMore = false;
+      nextCursor = null;
+      if (selection.direction === "before") events.reverse();
+      return page();
+    }
+    hasMore = true;
+    nextCursor = encode({ ...selection, after, before });
+  }
+  if (selection.direction === "before") events.reverse();
+  return page();
+}

package/src/mcp/session-view.ts

@@ -17,11 +17,14 @@ import type {
   SessionEventPayloadMode,
   SessionEventReadDirection,
   SessionEventReadMode,
+  SessionMcpMonitoringSource,
+  SessionQueueSnapshot,
 } from "@opengeni/contracts";
 import {
   boundSessionEventPayload,
   measureSessionEventJson,
   sessionEventJsonBytes,
+  compactSessionMcpDetail,
 } from "@opengeni/contracts";
 
 export const SESSION_EVENT_MCP_MAX_BYTES = 64 * 1024;
@@ -479,12 +482,82 @@ function projectMonitoringContainer(
   };
 }
 
-/** Purpose-built, flat, model-facing detail projection for `session_get`. */
+const SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT = 12;
+
+function projectEffectiveToolPolicy(value: Session["effectiveToolPolicy"]): {
+  value: unknown;
+  fact: SessionDetailFieldFact;
+  details: string[];
+} {
+  if (!value) return projectMonitoringContainer(null, 16_000);
+  const sample = (ids: string[]) => ids.slice(0, SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT);
+  const sampled =
+    value.selectedIds.length > SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT ||
+    value.effectiveIds.length > SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT ||
+    value.mandatoryIds.length > SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT ||
+    value.lazyRouter.deferredIds.length > SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT ||
+    value.configuredIds.length > SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT ||
+    value.droppedIds.length > SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT;
+  const bounded = {
+    ...value,
+    selectedIds: sample(value.selectedIds),
+    effectiveIds: sample(value.effectiveIds),
+    mandatoryIds: sample(value.mandatoryIds),
+    lazyRouter: { ...value.lazyRouter, deferredIds: sample(value.lazyRouter.deferredIds) },
+    configuredIds: sample(value.configuredIds),
+    droppedIds: sample(value.droppedIds),
+    idsTruncated: value.idsTruncated || sampled,
+  };
+  const projected = projectMonitoringContainer(bounded, 16_000);
+  const sourceMeasurement = measureSessionEventJson(value);
+  return {
+    ...projected,
+    fact: {
+      ...projected.fact,
+      truncated:
+        sampled ||
+        projected.fact.truncated ||
+        sourceMeasurement.bytes === null ||
+        sourceMeasurement.bytes !== projected.fact.deliveredBytes,
+      originalBytes: sourceMeasurement.bytes,
+      ...(sourceMeasurement.bytes === null ? { measurementBounded: true } : {}),
+    },
+    details: sampled
+      ? [
+          `effectiveToolPolicy: ids sampled at ${SESSION_DETAIL_EFFECTIVE_TOOL_POLICY_ID_LIMIT} per set; counts remain exact`,
+          ...projected.details,
+        ]
+      : projected.details,
+  };
+}
+
+/** Compact management state; configuration is deliberately excluded, not truncated. */
+export function boundSessionCompactDetailMcp(
+  session: Session,
+  monitoring: SessionMcpMonitoringSource,
+  queue: SessionQueueSnapshot | null,
+  maxBytes = SESSION_DETAIL_MCP_MAX_BYTES,
+) {
+  const result = compactSessionMcpDetail(session, monitoring, queue);
+  // Never drop a goal outcome or blocker to fit. The ordinary closed shape fits;
+  // an unsupported envelope must fail explicitly rather than erase management truth.
+  if (prettyJsonBytes(result) > maxBytes) {
+    throw new RangeError(`session_get compact projection exceeds its ${maxBytes}-byte envelope`);
+  }
+  return result;
+}
+
+/** Legacy bounded configuration projection for explicit `session_get detail=full`. */
 export function boundSessionDetailMcp(
   session: Session,
   effectiveControl: unknown = session.effectiveControl,
   maxBytes = SESSION_DETAIL_MCP_MAX_BYTES,
 ) {
+  const variableSetIds = session.variableSetIds;
+  // The plural selection is authoritative. Keep the singular/environment
+  // fields only as final-entry compatibility aliases so they cannot be read as
+  // complete attachment membership by newer consumers.
+  const variableSetId = variableSetIds.at(-1) ?? null;
   const title = session.title === null ? null : modelStringProjection(session.title, 512);
   const initialMessage = modelStringProjection(session.initialMessage, 4_000);
   const instructions =
@@ -494,6 +567,7 @@ export function boundSessionDetailMcp(
   const tools = projectMonitoringContainer(session.tools, 4_000);
   const mcpServers = projectMonitoringContainer(session.mcpServers, 3_000);
   const permissions = projectMonitoringContainer(session.firstPartyMcpPermissions, 1_500);
+  const effectiveToolPolicy = projectEffectiveToolPolicy(session.effectiveToolPolicy);
   const control = projectMonitoringContainer(effectiveControl, 2_000);
   const fieldFacts: Record<string, SessionDetailFieldFact> = {
     title: title?.fact ?? {
@@ -512,6 +586,7 @@ export function boundSessionDetailMcp(
     tools: tools.fact,
     mcpServers: mcpServers.fact,
     firstPartyMcpPermissions: permissions.fact,
+    effectiveToolPolicy: effectiveToolPolicy.fact,
     effectiveControl: control.fact,
   };
   const details = [
@@ -520,6 +595,7 @@ export function boundSessionDetailMcp(
     ...tools.details,
     ...mcpServers.details,
     ...permissions.details,
+    ...effectiveToolPolicy.details,
     ...control.details,
   ].slice(0, 32);
   const result = {
@@ -535,16 +611,20 @@ export function boundSessionDetailMcp(
     tools: tools.value,
     metadata: metadata.value,
     model: modelStringProjection(session.model, 512).value,
+    reasoningEffort: session.reasoningEffort,
+    latencyMode: session.latencyMode,
     sandboxBackend: modelStringProjection(session.sandboxBackend, 128).value,
     sandboxOs: session.sandboxOs,
     sandboxGroupId: session.sandboxGroupId,
     activeSandboxId: session.activeSandboxId,
     activeEpoch: session.activeEpoch,
-    variableSetId: session.variableSetId,
-    environmentId: session.environmentId,
+    variableSetIds,
+    variableSetId,
+    environmentId: variableSetId,
     rigId: session.rigId,
     rigVersionId: session.rigVersionId,
     firstPartyMcpPermissions: permissions.value,
+    effectiveToolPolicy: effectiveToolPolicy.value,
     mcpServers: mcpServers.value,
     parentSessionId: session.parentSessionId,
     createIdempotencyKey:
@@ -594,6 +674,7 @@ export function boundSessionDetailMcp(
     ["mcpServers", fieldFacts.mcpServers!],
     ["effectiveControl", fieldFacts.effectiveControl!],
     ["firstPartyMcpPermissions", fieldFacts.firstPartyMcpPermissions!],
+    ["effectiveToolPolicy", fieldFacts.effectiveToolPolicy!],
   ];
   for (const [field, fact] of fallbackContainers) {
     if (result.projection.bytes <= maxBytes) break;