@opengeni/api-router 3.0.1 → 3.1.2

package/src/mcp/session-admin-access-tools.ts

@@ -0,0 +1,163 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { organizationAccessPresetPermissions, type AccessGrant } from "@opengeni/contracts";
+import { siteAgentClamp } from "@opengeni/core";
+import { resolveSessionAdminAuthority, type Database } from "@opengeni/db";
+import * as z4 from "zod/v4";
+
+import { callOrganizationAction, describeActionResult, searchActions } from "../organization-mcp";
+
+/**
+ * How a session with admin access reaches the organization's actions: the
+ * same actions as the organization MCP server, run in this process as the
+ * owner or admin who gave the session its access.
+ */
+export type SessionAdminAccessDispatch = {
+  /** This API's own origin; calls never leave the process. */
+  origin: string;
+  /**
+   * Runs one request through the API. It must run outside the calling
+   * agent's request context, so nothing of the agent's own database or
+   * billing scope carries into the action.
+   */
+  dispatch: (request: Request) => Promise<Response>;
+  signal?: AbortSignal;
+};
+
+function text(value: unknown): CallToolResult {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+
+function failure(message: string): CallToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+/**
+ * Register the admin tools. The server admits them only while the session
+ * has admin access; every call checks it again, live, so turning it off,
+ * the organization stopping it, or the person losing their role takes effect
+ * on the very next call.
+ */
+export function registerSessionAdminAccessTools(input: {
+  server: McpServer;
+  db: Database;
+  grant: AccessGrant;
+  sessionId: string;
+  access: SessionAdminAccessDispatch;
+  authorize: () => Promise<void>;
+}): void {
+  const { server, db, grant, sessionId, access, authorize } = input;
+  const currentAuthority = async () => {
+    await authorize();
+    return await resolveSessionAdminAuthority(db, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      sessionId,
+    });
+  };
+  const ended = () =>
+    failure(
+      "This session no longer has admin access. An owner or admin can give it again from the session's menu in Opengeni.",
+    );
+
+  server.registerTool(
+    "admin_actions_search",
+    {
+      title: "Find organization actions",
+      description:
+        "This session has admin access: it can do what the person who gave it can manage across the whole organization. Search every Opengeni action (sessions and chats in every workspace, workspaces, people, connections and capabilities, knowledge, files, schedules, models, keys, billing and settings). Returns action ids for admin_action_describe and admin_action_call. An empty query lists everything, page by page.",
+      inputSchema: {
+        query: z4
+          .string()
+          .max(200)
+          .default("")
+          .describe("Words to look for, for example 'list sessions' or 'connections'."),
+        limit: z4.number().int().min(1).max(50).default(20).describe("Results per page."),
+        offset: z4.number().int().min(0).default(0).describe("Results to skip, for paging."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ query, limit, offset }) => {
+      if (!(await currentAuthority())) return ended();
+      return text(searchActions({ query, limit, offset }));
+    },
+  );
+
+  server.registerTool(
+    "admin_action_describe",
+    {
+      title: "Describe an organization action",
+      description:
+        "Show an organization action's method, path, path parameters and the JSON schema of its input, so admin_action_call can run it correctly.",
+      inputSchema: {
+        id: z4.string().min(1).max(300).describe("An action id from admin_actions_search."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ id }) => {
+      if (!(await currentAuthority())) return ended();
+      return describeActionResult(id);
+    },
+  );
+
+  server.registerTool(
+    "admin_action_call",
+    {
+      title: "Run an organization action",
+      description:
+        "Run one Opengeni action as the owner or admin who gave this session admin access, with exactly what they can manage right now, in any workspace of the organization. Pass path parameters (for example workspaceId), query parameters and a JSON body. Returns the HTTP status and response. Changes are real: confirm the target first.",
+      inputSchema: {
+        id: z4.string().min(1).max(300).describe("An action id from admin_actions_search."),
+        pathParameters: z4
+          .record(z4.string(), z4.string().min(1).max(1024))
+          .default({})
+          .describe("Values for the path's :parameters, for example { workspaceId }."),
+        query: z4
+          .record(
+            z4.string(),
+            z4.union([
+              z4.string(),
+              z4.number(),
+              z4.boolean(),
+              z4.array(z4.union([z4.string(), z4.number()])),
+            ]),
+          )
+          .default({})
+          .describe("Query string parameters."),
+        body: z4
+          .record(z4.string(), z4.unknown())
+          .optional()
+          .describe("The JSON request body, for actions that take one."),
+      },
+      annotations: { readOnlyHint: false, openWorldHint: false },
+    },
+    async ({ id, pathParameters, query, body }) => {
+      const authority = await currentAuthority();
+      if (!authority) return ended();
+      // An agent acting for a Site page (its session, an ancestor or its
+      // turn came from one) never acts as the person, even with admin access.
+      if ((await siteAgentClamp(db, grant))?.clamped)
+        return failure("An agent started from a Site page cannot run organization actions.");
+      return await callOrganizationAction(
+        {
+          caller: {
+            kind: "person",
+            accountId: grant.accountId,
+            subjectId: authority.subjectId,
+            // The cap is everything: each route still resolves this person's
+            // live role and workspace access, exactly as in their browser.
+            access: {
+              preset: "full",
+              permissions: organizationAccessPresetPermissions("full"),
+              workspaceScope: { kind: "all" },
+            },
+          },
+          origin: access.origin,
+          dispatch: access.dispatch,
+          ...(access.signal ? { signal: access.signal } : {}),
+        },
+        { id, pathParameters, query, ...(body !== undefined ? { body } : {}) },
+      );
+    },
+  );
+}

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

@@ -0,0 +1,123 @@
+import { SessionEventSemanticClass, SessionEventType } from "@opengeni/contracts";
+
+const FAMILY_LIMIT = 12;
+const CLOSEST_LIMIT = 3;
+// Registered types are under 40 characters; longer guesses compare on a prefix.
+const COMPARE_LENGTH = 40;
+// Suggestions cost an edit-distance pass over the registry, so only the first
+// few unknown values in one request get them.
+const SUGGESTED_VALUES = 3;
+
+function editDistance(left: string, right: string): number {
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= left.length; i += 1) {
+    const current = [i];
+    for (let j = 1; j <= right.length; j += 1) {
+      current[j] = Math.min(
+        previous[j]! + 1,
+        current[j - 1]! + 1,
+        previous[j - 1]! + (left[i - 1] === right[j - 1] ? 0 : 1),
+      );
+    }
+    previous = current;
+  }
+  return previous[right.length]!;
+}
+
+/**
+ * An actionable refusal for a guessed event type: the nearest registered names
+ * and the dotted family the guess belongs to, so the next call can succeed.
+ * Suggestions are advisory text; the canonical registry still decides validity.
+ */
+export function unknownSessionEventTypeMessage(value: string): string {
+  const all = SessionEventType.options as readonly string[];
+  const shown = JSON.stringify(
+    value.length > COMPARE_LENGTH ? `${value.slice(0, COMPARE_LENGTH)}...` : value,
+  );
+  const lower = value.slice(0, COMPARE_LENGTH).toLowerCase();
+  const closest = [...all]
+    .map((type) => ({
+      type,
+      distance: editDistance(lower, type.toLowerCase()),
+    }))
+    .sort((a, b) => a.distance - b.distance || a.type.localeCompare(b.type))
+    .slice(0, CLOSEST_LIMIT)
+    .map((entry) => entry.type);
+  const segments = lower.split(".");
+  let family: { prefix: string; types: string[] } | null = null;
+  for (let length = segments.length - 1; length >= 1 && !family; length -= 1) {
+    const prefix = `${segments.slice(0, length).join(".")}.`;
+    const types = all.filter((type) => type.toLowerCase().startsWith(prefix));
+    if (types.length > 0) family = { prefix: types[0]!.slice(0, prefix.length), types };
+  }
+  const familyText = family
+    ? ` Valid ${family.prefix}* types: ${family.types.slice(0, FAMILY_LIMIT).join(", ")}${
+        family.types.length > FAMILY_LIMIT ? `, and ${family.types.length - FAMILY_LIMIT} more` : ""
+      }.`
+    : "";
+  return `Unknown session event type ${shown}. Closest valid types: ${closest.join(", ")}.${familyText} For a family of events, includeClasses (${SessionEventSemanticClass.options.join(", ")}) avoids guessing type names.`;
+}
+
+/**
+ * Validate an event-type list against the canonical registry. The first few
+ * unknown values carry suggestions; the rest are counted in one issue so a long
+ * list of guesses stays cheap to check and short to read.
+ */
+export function addUnknownSessionEventTypeIssues(
+  values: readonly string[],
+  isKnown: (value: string) => boolean,
+  addIssue: (issue: { code: "custom"; message: string; path: number[] }) => void,
+): void {
+  const unknown = values.flatMap((value, index) => (isKnown(value) ? [] : [index]));
+  for (const index of unknown.slice(0, SUGGESTED_VALUES)) {
+    addIssue({
+      code: "custom",
+      message: unknownSessionEventTypeMessage(values[index]!),
+      path: [index],
+    });
+  }
+  const rest = unknown.slice(SUGGESTED_VALUES);
+  if (rest.length > 0) {
+    addIssue({
+      code: "custom",
+      message: `${rest.length} more unknown session event types (indexes ${rest.slice(0, 10).join(", ")}${rest.length > 10 ? ", ..." : ""}); fix the ones above or use includeClasses.`,
+      path: [rest[0]!],
+    });
+  }
+}
+
+const defined = (values: Record<string, unknown>) =>
+  Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+
+/**
+ * Audit selectors (mode, payloadMode, resultMode, type/class filters, latest)
+ * belong to view=debug. The refusal carries the corrected debug call plus the
+ * content-view call without them, because either may be what the agent meant.
+ */
+export function sessionEventAuditSelectorMessage(input: {
+  sessionId: string;
+  view: string | undefined;
+  cursor: string | undefined;
+  audit: Record<string, unknown>;
+  position: Record<string, unknown>;
+}): string {
+  const audit = defined(input.audit);
+  const position = defined(input.position);
+  const names = Object.keys(audit).join(", ");
+  const debugCall = JSON.stringify({
+    sessionId: input.sessionId,
+    view: "debug",
+    ...audit,
+    ...(audit.latest === undefined ? position : {}),
+  });
+  if (input.cursor !== undefined) {
+    return `Audit selectors require view=debug and cannot change a conversation cursor: a nextCursor continues its own view and keeps its selectors. For an audit read drop the cursor: ${debugCall}`;
+  }
+  const contentCall = JSON.stringify({
+    sessionId: input.sessionId,
+    view: input.view,
+    ...position,
+    ...(audit.latest !== undefined && position.limit === undefined ? { limit: 1 } : {}),
+  });
+  return `Audit selectors require view=debug; view=${input.view} does not take ${names}. Call ${debugCall}, or drop them to stay in view=${input.view}: ${contentCall}`;
+}