@opengeni/api-router 0.26.1 → 0.30.0

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,8 +1,18 @@
-import { DocumentSearchResponse, ListIndexedDocumentsResponse } 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,
@@ -91,7 +101,6 @@ export function buildDocumentsMcpServer(
         documentServices,
         input,
         options.initiatingSubjectId,
-        false,
       ),
   );
 
@@ -103,17 +112,80 @@ 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",
     {
@@ -295,7 +367,6 @@ async function searchContent(
     aclTags?: string[] | undefined;
   },
   initiatingSubjectId: string,
-  wrapResponse: boolean,
 ) {
   const results = await searchEffectiveDocuments(
     db,
@@ -317,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)) },
+    ],
+  };
+}