@opengeni/api-router 0.23.1 → 0.30.0

package/src/integrations/social-api.ts

@@ -39,6 +39,17 @@ type ConnectionRef = { workspaceId: string; connectionId: string; subjectId?: st
 
 const MAX_LIVE_RESULTS = 50;
 
+export function assertSocialConnectionProvider(
+  connection: Pick<SocialConnection, "provider">,
+  expected: "x" | "reddit",
+): void {
+  if (connection.provider !== expected) {
+    throw new Error(
+      `Selected account belongs to ${connection.provider}, not the ${expected} integration`,
+    );
+  }
+}
+
 export async function socialSearchLive(
   deps: SocialApiDeps,
   ref: ConnectionRef,

package/src/interaction-holder-heartbeat.ts

@@ -0,0 +1,95 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import { touchInteractionOperation, touchLeaseHolder } from "@opengeni/db";
+import type { ApiRouteDeps } from "@opengeni/core";
+
+const MAX_HEARTBEAT_INTERVAL_MS = 10_000;
+
+/**
+ * Keep one durable interaction operation—and its sandbox holder when present—
+ * live while a bounded controller mutation is in flight. Browser profile
+ * capture/restore can legitimately take minutes; without this pulse a lifecycle
+ * reaper cannot distinguish that request from a caller that disappeared.
+ */
+export async function withInteractionHolderHeartbeat<T>(
+  deps: ApiRouteDeps,
+  input: {
+    grant: AccessGrant;
+    workspaceId: string;
+    sandboxGroupId: string | null;
+    holderId: string;
+    operationId: string;
+    resourceId: string;
+    controllerGeneration: string;
+  },
+  run: () => Promise<T>,
+): Promise<T> {
+  const intervalMs = Math.max(
+    1_000,
+    Math.min(
+      MAX_HEARTBEAT_INTERVAL_MS,
+      Math.floor(deps.settings.sandboxInteractionHolderTtlMs / 3),
+    ),
+  );
+  let stopped = false;
+  let authorityLost = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let pending: Promise<void> = Promise.resolve();
+
+  const pulse = async (): Promise<void> => {
+    try {
+      const [operationAlive, holderAlive] = await Promise.all([
+        touchInteractionOperation(deps.db, {
+          accountId: input.grant.accountId,
+          workspaceId: input.workspaceId,
+          operationId: input.operationId,
+          resourceId: input.resourceId,
+          controllerGeneration: input.controllerGeneration,
+        }),
+        input.sandboxGroupId
+          ? touchLeaseHolder(deps.db, {
+              accountId: input.grant.accountId,
+              workspaceId: input.workspaceId,
+              sandboxGroupId: input.sandboxGroupId,
+              kind: "interaction",
+              holderId: input.holderId,
+            })
+          : Promise.resolve(true),
+      ]);
+      if (!operationAlive || !holderAlive) authorityLost = true;
+    } catch (error) {
+      // A transient database error does not surrender controller authority. The
+      // next pulse can recover, and the operation's authoritative settlement
+      // still goes through the database before it is exposed as complete.
+      deps.observability?.warn("interaction holder heartbeat failed", {
+        workspaceId: input.workspaceId,
+        sandboxGroupId: input.sandboxGroupId,
+        holderId: input.holderId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  };
+  const schedule = (): void => {
+    if (stopped) return;
+    timer = setTimeout(() => {
+      pending = pulse().finally(schedule);
+    }, intervalMs);
+    timer.unref?.();
+  };
+
+  await pulse();
+  if (authorityLost) {
+    throw new Error("Interaction controller placement authority was lost");
+  }
+  schedule();
+  try {
+    const result = await run();
+    if (authorityLost) {
+      throw new Error("Interaction controller placement authority was lost");
+    }
+    return result;
+  } finally {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    await pending;
+  }
+}

package/src/interaction-metrics.ts

@@ -0,0 +1,159 @@
+import type {
+  AuthRunMutationResponse,
+  BrowserActionReceipt,
+  BrowserActionRequest,
+  PublishBrowserRevisionResponse,
+  BrowserSessionMutationResponse,
+  ComputerActionReceipt,
+  ComputerActionRequest,
+  ComputerSessionMutationResponse,
+  InteractionInterventionMutationResponse,
+  ProtectedAuthFillResponse,
+} from "@opengeni/contracts";
+import {
+  interactionAuthMetricObserver,
+  interactionInterventionMetricObserver,
+  interactionOperationMetricObserver,
+  type Observability,
+} from "@opengeni/observability";
+
+type InteractionActionReceipt = BrowserActionReceipt | ComputerActionReceipt;
+type InteractionLifecycleMutation =
+  | BrowserSessionMutationResponse
+  | ComputerSessionMutationResponse;
+type AuthMutation = AuthRunMutationResponse | ProtectedAuthFillResponse;
+
+const STALE_INTERACTION_ERROR_CODES = new Set([
+  "controller_stale",
+  "target_stale",
+  "observation_stale",
+  "document_stale",
+  "frame_stale",
+  "attempt_stale",
+]);
+
+export function observeBrowserActionResult(
+  observability: Observability | null | undefined,
+  startedAtMs: number,
+  request: BrowserActionRequest,
+  receipt: BrowserActionReceipt,
+): void {
+  interactionOperationMetricObserver(observability)({
+    resource: "browser",
+    operation: "act",
+    mode: browserActionMode(request.action),
+    outcome: actionReceiptOutcome(receipt),
+    durationMs: elapsedMs(startedAtMs),
+  });
+}
+
+export function observeComputerActionResult(
+  observability: Observability | null | undefined,
+  startedAtMs: number,
+  request: ComputerActionRequest,
+  receipt: ComputerActionReceipt,
+): void {
+  interactionOperationMetricObserver(observability)({
+    resource: "computer",
+    operation: "act",
+    mode: computerActionMode(request.action.type),
+    outcome: actionReceiptOutcome(receipt),
+    durationMs: elapsedMs(startedAtMs),
+  });
+}
+
+export function observeLifecycleResult(
+  observability: Observability | null | undefined,
+  startedAtMs: number,
+  response: InteractionLifecycleMutation,
+): void {
+  interactionOperationMetricObserver(observability)({
+    resource: response.operation.resourceKind === "browser_session" ? "browser" : "computer",
+    operation: response.operation.kind,
+    mode: "lifecycle",
+    outcome: actionReceiptOutcome(response.operation),
+    durationMs: elapsedMs(startedAtMs),
+    replayed: response.operation.replayed,
+  });
+}
+
+export function observeBrowserRevisionPublication(
+  observability: Observability | null | undefined,
+  startedAtMs: number,
+  response: PublishBrowserRevisionResponse,
+): void {
+  interactionOperationMetricObserver(observability)({
+    resource: "browser",
+    operation: "publish",
+    mode: "lifecycle",
+    outcome: "completed",
+    durationMs: elapsedMs(startedAtMs),
+    replayed: response.replayed,
+  });
+}
+
+export function observeAuthMutation(
+  observability: Observability | null | undefined,
+  startedAtMs: number,
+  response: AuthMutation,
+): void {
+  interactionAuthMetricObserver(observability)({
+    state: response.run.state,
+    durationMs: elapsedMs(startedAtMs),
+    replayed: response.replayed,
+  });
+}
+
+export function observeInterventionMutation(
+  observability: Observability | null | undefined,
+  response: InteractionInterventionMutationResponse,
+): void {
+  const { intervention } = response;
+  interactionInterventionMetricObserver(observability)({
+    kind: intervention.kind,
+    outcome: intervention.status === "open" ? "opened" : intervention.status,
+    ...(intervention.settledAt
+      ? {
+          waitMs: Math.max(
+            0,
+            Date.parse(intervention.settledAt) - Date.parse(intervention.createdAt),
+          ),
+        }
+      : {}),
+    replayed: response.replayed,
+  });
+}
+
+function browserActionMode(action: BrowserActionRequest["action"]): string {
+  const actions = action.type === "batch" ? action.actions : [action];
+  if (actions.some((candidate) => candidate.type === "pointer")) return "coordinate";
+  if (actions.some((candidate) => candidate.type === "type" || candidate.type === "press")) {
+    return "keyboard";
+  }
+  if (actions.some((candidate) => candidate.type === "clipboard")) return "clipboard";
+  if (actions.some((candidate) => candidate.type === "permission")) return "permission";
+  return "semantic";
+}
+
+function computerActionMode(type: ComputerActionRequest["action"]["type"]): string {
+  if (type === "pointer") return "coordinate";
+  if (type === "keyboard") return "keyboard";
+  if (type === "clipboard") return "clipboard";
+  if (type === "launch") return "lifecycle";
+  return "semantic";
+}
+
+function actionReceiptOutcome(receipt: Pick<InteractionActionReceipt, "state" | "error">): string {
+  if (
+    receipt.state === "failed" &&
+    receipt.error &&
+    STALE_INTERACTION_ERROR_CODES.has(receipt.error.code)
+  ) {
+    return "stale";
+  }
+  return receipt.state;
+}
+
+function elapsedMs(startedAtMs: number): number {
+  return Math.max(0, performance.now() - startedAtMs);
+}

package/src/mcp/documents.ts

@@ -1,7 +1,18 @@
-import { DocumentSearchResponse } from "@opengeni/contracts";
 import {
+  KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS,
+  KnowledgeBrowseResponse,
+  KnowledgeGetResponse,
+  KnowledgeRecordId,
+  KnowledgeSearchResponse,
+  ListIndexedDocumentsResponse,
+} from "@opengeni/contracts";
+import {
+  browseEffectiveKnowledge,
+  getEffectiveKnowledgeRecord,
   getDocumentChunk,
   listDocumentBases,
+  listEffectiveIndexedDocuments,
+  searchEffectiveKnowledge,
   searchEffectiveDocuments,
   type DocumentAccessFilter,
   type DocumentServices,
@@ -90,7 +101,6 @@ export function buildDocumentsMcpServer(
         documentServices,
         input,
         options.initiatingSubjectId,
-        false,
       ),
   );
 
@@ -102,17 +112,110 @@ export function buildDocumentsMcpServer(
       inputSchema: SearchInputSchema,
     },
     async (input) =>
-      searchContent(
+      searchKnowledge(
         db,
         accountId,
         workspaceId,
         documentServices,
         input,
         options.initiatingSubjectId,
-        true,
       ),
   );
 
+  server.registerTool(
+    "knowledge_get",
+    {
+      description:
+        "Fetch one stable Knowledge record by the id returned from knowledge_search or knowledge_browse. Authorization and agent access are rechecked before content or links are returned.",
+      inputSchema: { id: KnowledgeRecordId },
+    },
+    async ({ id }) => {
+      const record = await getEffectiveKnowledgeRecord(db, {
+        accountId,
+        workspaceId,
+        initiatingSubjectId: options.initiatingSubjectId,
+        id,
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: record
+              ? JSON.stringify(KnowledgeGetResponse.parse({ record }))
+              : `knowledge record not found: ${id}`,
+          },
+        ],
+        isError: !record,
+      };
+    },
+  );
+
+  server.registerTool(
+    "knowledge_browse",
+    {
+      description:
+        "Browse authorized Knowledge without crawling folders. Omit parentId to list source documents; pass a document record id to inspect its chunks. Opaque cursors are bound to this user, workspace, parent, and filters.",
+      inputSchema: {
+        parentId: KnowledgeRecordId.optional(),
+        topic: z.string().min(1).max(256).optional(),
+        sourceKinds: SearchInputSchema.sourceKinds,
+        cursor: z.string().min(1).max(KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS).optional(),
+        limit: z.number().int().positive().max(50).optional(),
+      },
+    },
+    async ({ parentId, topic, sourceKinds, cursor, limit }) => ({
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            KnowledgeBrowseResponse.parse(
+              await browseEffectiveKnowledge(db, {
+                accountId,
+                workspaceId,
+                initiatingSubjectId: options.initiatingSubjectId,
+                ...(parentId ? { parentId } : {}),
+                ...(topic ? { topic } : {}),
+                ...(sourceKinds ? { sourceKinds } : {}),
+                ...(cursor ? { cursor } : {}),
+                ...(limit ? { limit } : {}),
+              }),
+            ),
+          ),
+        },
+      ],
+    }),
+  );
+
+  server.registerTool(
+    "list_indexed_documents",
+    {
+      description:
+        "List agent-authorized documents that became ready after an opaque checkpoint, ordered by durable indexing completion. Results include source and authority/ingestion provenance. Persist nextCheckpoint only after successfully processing the returned page, then pass it on the next scheduled run to avoid repeats.",
+      inputSchema: {
+        checkpoint: z.string().min(1).max(1_024).optional(),
+        limit: z.number().int().positive().max(100).optional(),
+      },
+    },
+    async ({ checkpoint, limit }) => ({
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            ListIndexedDocumentsResponse.parse(
+              await listEffectiveIndexedDocuments(db, {
+                accountId,
+                workspaceId,
+                initiatingSubjectId: options.initiatingSubjectId,
+                ...(checkpoint ? { checkpoint } : {}),
+                ...(limit ? { limit } : {}),
+              }),
+            ),
+          ),
+        },
+      ],
+    }),
+  );
+
   server.registerTool(
     "fetch_document_chunk",
     {
@@ -264,7 +367,6 @@ async function searchContent(
     aclTags?: string[] | undefined;
   },
   initiatingSubjectId: string,
-  wrapResponse: boolean,
 ) {
   const results = await searchEffectiveDocuments(
     db,
@@ -286,8 +388,46 @@ async function searchContent(
     content: [
       {
         type: "text" as const,
-        text: JSON.stringify(wrapResponse ? DocumentSearchResponse.parse({ results }) : results),
+        text: JSON.stringify(results),
       },
     ],
   };
 }
+
+async function searchKnowledge(
+  db: Database,
+  accountId: string,
+  workspaceId: string,
+  documentServices: DocumentServices,
+  input: {
+    query: string;
+    baseIds?: string[] | undefined;
+    limit?: number | undefined;
+    mode?: "hybrid" | "vector" | "keyword" | undefined;
+    sourceKinds?: Parameters<typeof searchContent>[4]["sourceKinds"];
+    aclTags?: string[] | undefined;
+  },
+  initiatingSubjectId: string,
+) {
+  const response = await searchEffectiveKnowledge(
+    db,
+    {
+      accountId,
+      workspaceId,
+      query: input.query,
+      ...(input.baseIds ? { baseIds: input.baseIds } : {}),
+      ...(input.limit ? { limit: input.limit } : {}),
+      ...(input.mode ? { mode: input.mode } : {}),
+      ...(input.sourceKinds ? { sourceKinds: input.sourceKinds } : {}),
+      ...(input.aclTags ? { aclTags: input.aclTags } : {}),
+      initiatingSubjectId,
+      surface: "agent",
+    },
+    documentServices,
+  );
+  return {
+    content: [
+      { type: "text" as const, text: JSON.stringify(KnowledgeSearchResponse.parse(response)) },
+    ],
+  };
+}

package/src/mcp/editable-artifact-query-schema.ts

@@ -0,0 +1,236 @@
+import {
+  DOCUMENT_ARTIFACT_QUERY_MAX_ITEMS,
+  DOCUMENT_ARTIFACT_QUERY_MAX_TABLE_CELLS,
+  DOCUMENT_ARTIFACT_QUERY_MAX_TEXT_UTF16,
+  DOCUMENT_ARTIFACT_MAX_STRUCTURAL_COUNTER,
+  PRESENTATION_ARTIFACT_MAX_COORDINATE,
+  PRESENTATION_ARTIFACT_QUERY_MAX_NODES,
+  PRESENTATION_ARTIFACT_QUERY_MAX_SLIDES,
+  PRESENTATION_ARTIFACT_QUERY_MAX_TEXT_BYTES,
+  PRESENTATION_ARTIFACT_QUERY_RESPONSE_MAX_BYTES,
+  SPREADSHEET_ARTIFACT_METADATA_MAX_SHEETS,
+  SPREADSHEET_ARTIFACT_METADATA_MIN_RESPONSE_BYTES,
+  SPREADSHEET_ARTIFACT_PROJECTION_MAX_BYTES,
+  SPREADSHEET_ARTIFACT_VIEWPORT_MAX_AREA,
+  SPREADSHEET_ARTIFACT_VIEWPORT_MAX_CELLS,
+  SPREADSHEET_ARTIFACT_VIEWPORT_MIN_RESPONSE_BYTES,
+  type EditableArtifactStableId,
+} from "@opengeni/contracts/editable-artifacts";
+import type { EditableArtifactAgentQuery } from "@opengeni/core/editable-artifacts";
+import * as z from "zod/v4";
+
+const UINT32_MAX = 0xffff_ffff;
+
+const Uint32 = z.number().int().min(0).max(UINT32_MAX);
+const PositiveUint32 = z.number().int().min(1).max(UINT32_MAX);
+const SafeCursor = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const CanonicalStableId = z
+  .string()
+  .regex(/^[0-9a-f]{32}$/u)
+  .transform((value): EditableArtifactStableId => value as EditableArtifactStableId);
+const SpreadsheetSheetId = z
+  .string()
+  .regex(/^[0-9a-f]{32}$/u)
+  .refine(
+    (value) => value.slice(0, 16) !== "0000000000000000" && value.slice(16) !== "0000000000000000",
+    "Object id must have allocated namespace and counter halves",
+  )
+  .transform((value): EditableArtifactStableId => value as EditableArtifactStableId);
+const DocumentSectionId = z
+  .string()
+  .regex(/^sec\/[0-9a-f]{32}$/u)
+  .refine((value) => {
+    const counter = BigInt(`0x${value.slice(-16)}`);
+    return counter > 0n && counter <= BigInt(DOCUMENT_ARTIFACT_MAX_STRUCTURAL_COUNTER);
+  }, "Section id counter must be allocated and within the document limit");
+
+const SpreadsheetMetadataRequest = z
+  .object({
+    kind: z.literal("workbook-metadata"),
+    query: z
+      .object({
+        maxSheets: z.number().int().min(1).max(SPREADSHEET_ARTIFACT_METADATA_MAX_SHEETS),
+        maxBytes: z
+          .number()
+          .int()
+          .min(SPREADSHEET_ARTIFACT_METADATA_MIN_RESPONSE_BYTES)
+          .max(SPREADSHEET_ARTIFACT_PROJECTION_MAX_BYTES),
+      })
+      .strict(),
+  })
+  .strict();
+
+const SpreadsheetViewportRequest = z
+  .object({
+    kind: z.literal("viewport"),
+    query: z
+      .object({
+        sheetId: SpreadsheetSheetId,
+        startRow: Uint32,
+        startColumn: Uint32,
+        rowCount: PositiveUint32,
+        columnCount: PositiveUint32,
+        maxCells: z.number().int().min(1).max(SPREADSHEET_ARTIFACT_VIEWPORT_MAX_CELLS),
+        maxBytes: z
+          .number()
+          .int()
+          .min(SPREADSHEET_ARTIFACT_VIEWPORT_MIN_RESPONSE_BYTES)
+          .max(SPREADSHEET_ARTIFACT_PROJECTION_MAX_BYTES),
+      })
+      .strict()
+      .superRefine((query, context) => {
+        const area = query.rowCount * query.columnCount;
+        if (!Number.isSafeInteger(area) || area > SPREADSHEET_ARTIFACT_VIEWPORT_MAX_AREA) {
+          context.addIssue({
+            code: "custom",
+            message: `Viewport area must not exceed ${SPREADSHEET_ARTIFACT_VIEWPORT_MAX_AREA}`,
+          });
+        }
+        if (
+          query.rowCount - 1 > UINT32_MAX - query.startRow ||
+          query.columnCount - 1 > UINT32_MAX - query.startColumn
+        ) {
+          context.addIssue({
+            code: "custom",
+            message: "Viewport extent exceeds spreadsheet coordinates",
+          });
+        }
+      }),
+  })
+  .strict();
+
+const DocumentLimits = z
+  .object({
+    maxItems: z.number().int().min(1).max(DOCUMENT_ARTIFACT_QUERY_MAX_ITEMS),
+    maxTextUtf16: z.number().int().min(1).max(DOCUMENT_ARTIFACT_QUERY_MAX_TEXT_UTF16),
+    maxTableCells: z.number().int().min(1).max(DOCUMENT_ARTIFACT_QUERY_MAX_TABLE_CELLS),
+  })
+  .strict();
+
+const DocumentSummaryRequest = z.object({ kind: z.literal("summary") }).strict();
+const DocumentBodyRequest = z
+  .object({ kind: z.literal("body"), startBlock: SafeCursor, limits: DocumentLimits })
+  .strict();
+const DocumentStoryRequest = z
+  .object({
+    kind: z.literal("story"),
+    sectionId: DocumentSectionId,
+    storyKind: z.enum(["header", "footer"]),
+    variant: z.enum(["default", "first", "even"]),
+    startBlock: SafeCursor,
+    limits: DocumentLimits,
+  })
+  .strict();
+const DocumentSectionsRequest = z
+  .object({ kind: z.literal("sections"), startSection: SafeCursor, limits: DocumentLimits })
+  .strict();
+const DocumentReviewRequest = z
+  .object({ kind: z.literal("review"), startItem: SafeCursor, limits: DocumentLimits })
+  .strict();
+
+const PresentationOwner = z
+  .object({ kind: z.enum(["master", "layout", "slide"]), id: CanonicalStableId })
+  .strict();
+const PresentationCoordinate = z
+  .number()
+  .int()
+  .min(-PRESENTATION_ARTIFACT_MAX_COORDINATE)
+  .max(PRESENTATION_ARTIFACT_MAX_COORDINATE);
+const PresentationExtent = z.number().int().min(1).max(PRESENTATION_ARTIFACT_MAX_COORDINATE);
+const PresentationRect = z
+  .object({
+    x: PresentationCoordinate,
+    y: PresentationCoordinate,
+    width: PresentationExtent,
+    height: PresentationExtent,
+  })
+  .strict()
+  .superRefine((rect, context) => {
+    if (
+      Math.abs(rect.x + rect.width) > PRESENTATION_ARTIFACT_MAX_COORDINATE ||
+      Math.abs(rect.y + rect.height) > PRESENTATION_ARTIFACT_MAX_COORDINATE
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Viewport extent exceeds presentation coordinates",
+      });
+    }
+  });
+const PresentationNodeLimit = z.number().int().min(1).max(PRESENTATION_ARTIFACT_QUERY_MAX_NODES);
+const PresentationTextLimit = z
+  .number()
+  .int()
+  .min(1)
+  .max(PRESENTATION_ARTIFACT_QUERY_MAX_TEXT_BYTES);
+const presentationResponseBytes = (minimum: number) =>
+  z.number().int().min(minimum).max(PRESENTATION_ARTIFACT_QUERY_RESPONSE_MAX_BYTES);
+
+const PresentationViewportRequest = z
+  .object({
+    kind: z.literal("viewport"),
+    owner: PresentationOwner,
+    viewport: PresentationRect,
+    maxNodes: PresentationNodeLimit,
+    maxBytes: presentationResponseBytes(89),
+  })
+  .strict();
+const PresentationHitTestRequest = z
+  .object({
+    kind: z.literal("hit-test"),
+    owner: PresentationOwner,
+    x: PresentationCoordinate,
+    y: PresentationCoordinate,
+    maxNodes: PresentationNodeLimit,
+    maxBytes: presentationResponseBytes(89),
+  })
+  .strict();
+const PresentationResolvedSlideRequest = z
+  .object({
+    kind: z.literal("resolved-slide"),
+    slideId: CanonicalStableId,
+    maxNodes: PresentationNodeLimit,
+    maxBytes: presentationResponseBytes(56),
+  })
+  .strict();
+const PresentationMetadataRequest = z
+  .object({ kind: z.literal("metadata"), maxBytes: presentationResponseBytes(84) })
+  .strict();
+const PresentationSlideCatalogRequest = z
+  .object({
+    kind: z.literal("slide-catalog"),
+    startSlide: Uint32,
+    maxSlides: z.number().int().min(1).max(PRESENTATION_ARTIFACT_QUERY_MAX_SLIDES),
+    maxTextBytes: PresentationTextLimit,
+    maxBytes: presentationResponseBytes(53),
+  })
+  .strict();
+const PresentationEditorSlideRequest = z
+  .object({
+    kind: z.literal("editor-slide"),
+    slideId: CanonicalStableId,
+    maxNodes: PresentationNodeLimit,
+    maxTextBytes: PresentationTextLimit,
+    maxBytes: presentationResponseBytes(75),
+  })
+  .strict();
+
+/** Exact bounded query union shared by the model-facing direct inspect tool. */
+export const EditableArtifactQueryRequestSchema: z.ZodType<EditableArtifactAgentQuery["query"]> = z
+  .union([
+    SpreadsheetMetadataRequest,
+    SpreadsheetViewportRequest,
+    DocumentSummaryRequest,
+    DocumentBodyRequest,
+    DocumentStoryRequest,
+    DocumentSectionsRequest,
+    DocumentReviewRequest,
+    PresentationViewportRequest,
+    PresentationHitTestRequest,
+    PresentationResolvedSlideRequest,
+    PresentationMetadataRequest,
+    PresentationSlideCatalogRequest,
+    PresentationEditorSlideRequest,
+  ])
+  .describe(
+    "Exact bounded query for the selected modality. Spreadsheet requests retain their required nested query envelope; document and presentation requests use the fields shown by this schema.",
+  );