@opengeni/api-router 0.12.7 → 0.14.3

package/src/mcp/server.ts

@@ -21,6 +21,7 @@ import {
   type Permission,
   type ResourceRef,
   type SessionAuthorizationOperation,
+  type SessionAuthorizationSurface,
   type Session,
   UpdateScheduledTaskRequest,
 } from "@opengeni/contracts";
@@ -35,6 +36,8 @@ import {
   getSessionGoal,
   getSessionQueueSnapshot,
   getSessionTurn,
+  getOrCreatePreferenceRegistrySnapshot,
+  getPreferenceRegistryFullContent,
   getVariableSet,
   getVariableSetByName,
   areGitHubRepositoriesAllowedForWorkspace,
@@ -185,6 +188,8 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   memory_search: { sessionRequired: true, allOf: ["documents:search"] },
   memory_save: { sessionRequired: true, allOf: ["documents:search"] },
   memory_correct: { sessionRequired: true, allOf: ["documents:search"] },
+  preference_registry_summary: { sessionRequired: true, allOf: ["workspace:read"] },
+  preference_registry_get: { sessionRequired: true, allOf: ["workspace:read"] },
   sandboxes_list: { sessionRequired: true, allOf: ["sessions:read"] },
   sandbox_attach: { sessionRequired: true, allOf: ["sessions:control"] },
   sandbox_swap: { sessionRequired: true, allOf: ["sessions:control"] },
@@ -225,8 +230,13 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   scheduled_task_runs_list: { anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"] },
   slack_bot_list_channels: { allOf: ["connections:read"] },
   slack_bot_channel_history: { allOf: ["connections:read"] },
+  slack_bot_thread_replies: { allOf: ["connections:read"] },
   slack_bot_list_users: { allOf: ["connections:read"] },
+  slack_bot_list_files: { allOf: ["connections:read"] },
+  slack_bot_file_info: { allOf: ["connections:read"] },
+  slack_bot_file_content: { allOf: ["connections:read"] },
   slack_bot_post_message: { allOf: ["connections:read"] },
+  slack_bot_delete_message: { allOf: ["connections:read"] },
 } satisfies Record<FirstPartyMcpToolName, FirstPartyToolAuthorization>;
 
 const FIRST_PARTY_MCP_TOOL_NAME_SET = new Set<string>(FIRST_PARTY_MCP_TOOL_NAMES);
@@ -365,6 +375,9 @@ export function buildOpenGeniMcpServer(
   if (!toolspaceMode && sessionId !== null && options.workspaceMemoryEnabled === true) {
     registerMemoryTools(server, deps, grant, sessionId, json);
   }
+  if (!toolspaceMode && sessionId !== null && preferenceAttemptClaims(grant) !== null) {
+    registerPreferenceRegistryTools(server, deps, grant, json);
+  }
 
   // Fleet tools (M7 bring-your-own-compute): list / attach / swap / run_on /
   // provision over the session's Modal box + the workspace's enrolled machines.
@@ -837,6 +850,32 @@ function registerSlackBotTools(
       ),
   );
 
+  server.registerTool(
+    "slack_bot_thread_replies",
+    {
+      description:
+        "Read a Slack thread as the workspace-shared OpenGeni bot. Pass the channel ID and the parent message timestamp returned by channel history. The result includes the parent followed by its replies.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        channelId: z4.string().min(1).max(64),
+        threadTimestamp: z4.string().min(1).max(64),
+        cursor: z4.string().max(1024).optional(),
+        limit: z4.number().int().min(1).max(100).optional(),
+      },
+    },
+    async ({ connectionId, channelId, threadTimestamp, cursor, limit }) =>
+      json(
+        await (
+          await clientFor(connectionId)
+        ).threadReplies({
+          channelId,
+          threadTimestamp,
+          ...(cursor ? { cursor } : {}),
+          ...(limit !== undefined ? { limit } : {}),
+        }),
+      ),
+  );
+
   server.registerTool(
     "slack_bot_list_users",
     {
@@ -858,20 +897,95 @@ function registerSlackBotTools(
       ),
   );
 
+  server.registerTool(
+    "slack_bot_list_files",
+    {
+      description:
+        "List Slack files and canvases shared with a channel where the workspace-shared OpenGeni bot is already a member.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        channelId: z4.string().min(1).max(64),
+        cursor: z4.string().max(1024).optional(),
+        limit: z4.number().int().min(1).max(200).optional(),
+      },
+    },
+    async ({ connectionId, channelId, cursor, limit }) =>
+      json(
+        await (
+          await clientFor(connectionId)
+        ).listFiles({
+          channelId,
+          ...(cursor ? { cursor } : {}),
+          ...(limit !== undefined ? { limit } : {}),
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "slack_bot_file_info",
+    {
+      description:
+        "Read safe metadata for a Slack file or canvas shared with a channel where the workspace-shared OpenGeni bot is already a member. For an embedded huddle transcript, also pass the shared canvas file ID as parentFileId so OpenGeni can verify the indirect share.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        channelId: z4.string().min(1).max(64),
+        fileId: z4.string().min(1).max(64),
+        parentFileId: z4.string().min(1).max(64).optional(),
+      },
+    },
+    async ({ connectionId, channelId, fileId, parentFileId }) =>
+      json(
+        await (
+          await clientFor(connectionId)
+        ).fileInfo({
+          channelId,
+          fileId,
+          ...(parentFileId ? { parentFileId } : {}),
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "slack_bot_file_content",
+    {
+      description:
+        "Read a bounded page of UTF-8 text from a Slack file or canvas shared with a channel where the workspace-shared OpenGeni bot is already a member. For an embedded huddle transcript, also pass the shared canvas file ID as parentFileId so OpenGeni can verify the channel-to-canvas-to-transcript chain. Slack may still restrict a huddle transcript body to participants; that returns huddle_transcript_requires_participant_access. Private Slack URLs and credentials are never returned. Continue with nextOffset when truncated is true.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        channelId: z4.string().min(1).max(64),
+        fileId: z4.string().min(1).max(64),
+        parentFileId: z4.string().min(1).max(64).optional(),
+        offset: z4.number().int().min(0).max(4_000_000).optional(),
+      },
+    },
+    async ({ connectionId, channelId, fileId, parentFileId, offset }) =>
+      json(
+        await (
+          await clientFor(connectionId)
+        ).fileContent({
+          channelId,
+          fileId,
+          ...(parentFileId ? { parentFileId } : {}),
+          ...(offset !== undefined ? { offset } : {}),
+        }),
+      ),
+  );
+
   server.registerTool(
     "slack_bot_post_message",
     {
       description:
-        "Post as the workspace-shared OpenGeni bot. Pass channelId for a channel where the bot is already a member, or userId to open/post a DM; pass exactly one. Generate one operationId UUID per intended message and reuse that same UUID on every retry.",
+        "Post as the workspace-shared OpenGeni bot. Pass channelId for a channel where the bot is already a member, or userId to open/post a DM; pass exactly one. To reply in a thread, also pass its parent message timestamp as threadTimestamp. Generate one operationId UUID per intended message and reuse that same UUID on every retry.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         operationId: z4.string().uuid(),
         channelId: z4.string().min(1).max(64).optional(),
         userId: z4.string().min(1).max(64).optional(),
+        threadTimestamp: z4.string().min(1).max(64).optional(),
         text: z4.string().min(1).max(40_000),
       },
     },
-    async ({ connectionId, operationId, channelId, userId, text }) => {
+    async ({ connectionId, operationId, channelId, userId, threadTimestamp, text }) => {
       if (Boolean(channelId) === Boolean(userId)) {
         throw new Error("exactly one of channelId or userId is required");
       }
@@ -882,11 +996,30 @@ function registerSlackBotTools(
           operationId,
           ...(channelId ? { channelId } : {}),
           ...(userId ? { userId } : {}),
+          ...(threadTimestamp ? { threadTimestamp } : {}),
           text,
         }),
       );
     },
   );
+
+  server.registerTool(
+    "slack_bot_delete_message",
+    {
+      description:
+        "Delete a message authored by the workspace-shared OpenGeni bot. Pass the channel ID and exact message timestamp returned by a prior post or channel/thread read. Generate one operationId UUID per intended deletion and reuse it on every retry, including after an unknown outcome. Slack refuses deletion of messages not authored by this bot.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        operationId: z4.string().uuid(),
+        channelId: z4.string().min(1).max(64),
+        timestamp: z4.string().min(1).max(64),
+      },
+    },
+    async ({ connectionId, operationId, channelId, timestamp }) =>
+      json(
+        await (await clientFor(connectionId)).deleteMessage({ operationId, channelId, timestamp }),
+      ),
+  );
 }
 
 function registerToolspaceProxyTools(server: McpServer, surface: ToolspaceMcpSurface | null): void {
@@ -1149,6 +1282,70 @@ async function authorizeFirstPartySession(
   });
 }
 
+function preferenceAttemptClaims(grant: AccessGrant): {
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+} | null {
+  const metadata = grant.metadata ?? {};
+  if (
+    typeof metadata["sessionId"] !== "string" ||
+    typeof metadata["turnId"] !== "string" ||
+    typeof metadata["attemptId"] !== "string" ||
+    typeof metadata["executionGeneration"] !== "number" ||
+    !Number.isSafeInteger(metadata["executionGeneration"]) ||
+    metadata["executionGeneration"] < 1 ||
+    metadata["executionGeneration"] > 2_147_483_647
+  ) {
+    return null;
+  }
+  return {
+    sessionId: metadata["sessionId"],
+    turnId: metadata["turnId"],
+    attemptId: metadata["attemptId"],
+    executionGeneration: metadata["executionGeneration"],
+  };
+}
+
+function registerPreferenceRegistryTools(
+  server: McpServer,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  json: JsonResult,
+): void {
+  const attemptClaims = () => {
+    const resolved = preferenceAttemptClaims(grant);
+    if (!resolved) throw new Error("Exact signed preference attempt authority is required.");
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      ...resolved,
+    };
+  };
+
+  server.registerTool(
+    "preference_registry_summary",
+    {
+      description:
+        "List bounded deterministic descriptors for organization, workspace, and immutable initiating-human preferences frozen to this exact attempt. Full content is omitted; retrieve only a relevant returned handle.",
+      inputSchema: {},
+    },
+    async () => json(await getOrCreatePreferenceRegistrySnapshot(deps.db, attemptClaims())),
+  );
+
+  server.registerTool(
+    "preference_registry_get",
+    {
+      description:
+        "Retrieve full content for one preference in this exact attempt snapshot. Handles from another account, workspace, human, or attempt are rejected.",
+      inputSchema: { retrievalHandle: z4.string().min(1).max(512) },
+    },
+    async ({ retrievalHandle }) =>
+      json(await getPreferenceRegistryFullContent(deps.db, attemptClaims(), retrievalHandle)),
+  );
+}
+
 const MemoryKindSchema = z4.enum(["preference", "semantic", "procedural", "decision", "episodic"]);
 
 function memoryPreview(text: string): string {
@@ -1348,7 +1545,7 @@ function registerFleetTools(
     "run_on",
     {
       description:
-        "Run a ONE-OFF op on a SPECIFIC enrolled selfhosted machine WITHOUT changing this session's active sandbox (a side-channel to another machine). Ops: exec (run a command), read (read a file), write (write a file). `target` = a selfhosted sandboxes_list `id`. To make a machine the active sandbox instead, use sandbox_swap.",
+        "Run a ONE-OFF op on a SPECIFIC enrolled selfhosted machine WITHOUT changing this session's active sandbox (a side-channel to another machine). Ops: exec (run a command), read (read a file), write (write a file). Exec returns exact exitCode plus typed timedOut and the effective deadlineMs; a deadline kill or missing exit proof is never ok:true, and an ambiguous transport loss is not replayed. `target` = a selfhosted sandboxes_list `id`. To make a machine the active sandbox instead, use sandbox_swap.",
       inputSchema: {
         target: z4.string().min(1),
         op: z4.discriminatedUnion("kind", [
@@ -1567,6 +1764,7 @@ function registerRigTools(
 function exactAgentCommandContext(
   grant: AccessGrant,
   callerSessionId: string,
+  authorizationSurface?: SessionAuthorizationSurface,
 ): AgentSessionCommandContext {
   const turnId = grant.metadata?.["turnId"];
   const attemptId = grant.metadata?.["attemptId"];
@@ -1588,6 +1786,7 @@ function exactAgentCommandContext(
     callerTurnId: turnId,
     callerAttemptId: attemptId,
     callerExecutionGeneration: executionGeneration,
+    ...(authorizationSurface ? { authorizationSurface } : {}),
   };
 }
 
@@ -1822,6 +2021,7 @@ function registerWorkspaceOrchestrationTools(
           rigId: z4.string().uuid().optional(),
           model: z4.string().min(1).optional(),
           reasoningEffort: z4.string().optional(),
+          latencyMode: z4.enum(["standard", "priority", "fast"]).optional(),
           sandboxBackend: z4.string().optional(),
           // Create-time machine targeting: an enrolled sandbox id (from
           // sandboxes_list) to run the spawned session on. Seeds the active-sandbox
@@ -1953,7 +2153,6 @@ function registerWorkspaceOrchestrationTools(
           targetSessionId,
           {
             text,
-            toolsProvided: false,
             delivery: "send",
             origin: "operator",
             clientEventId: idempotencyKey,
@@ -1977,16 +2176,10 @@ function registerWorkspaceOrchestrationTools(
         },
       },
       async ({ sessionId, idempotencyKey, reason }) => {
-        const authorization = await authorizeFirstPartySession(
-          deps,
-          grant,
-          sessionId,
-          "session.control",
-        );
         if (callerSessionId !== null) {
           const controlled = await controlAgentSessionWorkstream(
             deps,
-            exactAgentCommandContext(grant, callerSessionId),
+            exactAgentCommandContext(grant, callerSessionId, "first_party_mcp"),
             {
               targetSessionId: sessionId,
               action: "pause",
@@ -1999,7 +2192,7 @@ function registerWorkspaceOrchestrationTools(
             effectiveControl: projectEffectiveControlForRelatedAccess(
               serializeEffectiveSessionControl(controlled.control),
               sessionId,
-              authorization?.relatedSessionAccess ?? "root",
+              controlled.authorization?.relatedSessionAccess ?? "root",
             ),
             interruptionCount: controlled.interruptionCount,
             replay: controlled.replay,
@@ -2012,6 +2205,7 @@ function registerWorkspaceOrchestrationTools(
             workspaceId: grant.workspaceId,
             sessionId,
             subjectId: grant.subjectId,
+            authorizationSurface: "first_party_mcp",
           },
           {
             action: "pause",
@@ -2019,14 +2213,7 @@ function registerWorkspaceOrchestrationTools(
             ...(reason ? { reason } : {}),
           },
         );
-        return json({
-          ...controlled,
-          effectiveControl: projectEffectiveControlForRelatedAccess(
-            controlled.effectiveControl,
-            sessionId,
-            authorization?.relatedSessionAccess ?? "root",
-          ),
-        });
+        return json(controlled);
       },
     );
 
@@ -2042,16 +2229,10 @@ function registerWorkspaceOrchestrationTools(
         },
       },
       async ({ sessionId, idempotencyKey, reason }) => {
-        const authorization = await authorizeFirstPartySession(
-          deps,
-          grant,
-          sessionId,
-          "session.control",
-        );
         if (callerSessionId !== null) {
           const controlled = await controlAgentSessionWorkstream(
             deps,
-            exactAgentCommandContext(grant, callerSessionId),
+            exactAgentCommandContext(grant, callerSessionId, "first_party_mcp"),
             {
               targetSessionId: sessionId,
               action: "resume",
@@ -2064,7 +2245,7 @@ function registerWorkspaceOrchestrationTools(
             effectiveControl: projectEffectiveControlForRelatedAccess(
               serializeEffectiveSessionControl(controlled.control),
               sessionId,
-              authorization?.relatedSessionAccess ?? "root",
+              controlled.authorization?.relatedSessionAccess ?? "root",
             ),
             interruptionCount: controlled.interruptionCount,
             replay: controlled.replay,
@@ -2077,6 +2258,7 @@ function registerWorkspaceOrchestrationTools(
             workspaceId: grant.workspaceId,
             sessionId,
             subjectId: grant.subjectId,
+            authorizationSurface: "first_party_mcp",
           },
           {
             action: "resume",
@@ -2084,14 +2266,7 @@ function registerWorkspaceOrchestrationTools(
             ...(reason ? { reason } : {}),
           },
         );
-        return json({
-          ...controlled,
-          effectiveControl: projectEffectiveControlForRelatedAccess(
-            controlled.effectiveControl,
-            sessionId,
-            authorization?.relatedSessionAccess ?? "root",
-          ),
-        });
+        return json(controlled);
       },
     );
 
@@ -2108,10 +2283,9 @@ function registerWorkspaceOrchestrationTools(
           },
         },
         async ({ sessionId, instruction, idempotencyKey }) => {
-          await authorizeFirstPartySession(deps, grant, sessionId, "session.steer");
           const result = await steerAgentSession(
             deps,
-            exactAgentCommandContext(grant, callerSessionId),
+            exactAgentCommandContext(grant, callerSessionId, "first_party_mcp"),
             { targetSessionId: sessionId, instruction, idempotencyKey },
           );
           return json({
@@ -2317,14 +2491,16 @@ function registerGitHubConnectTool(
       const { settings } = deps;
       const missing = githubAppMissingSettings(settings);
       const slug = settings.githubAppSlug?.trim() || null;
+      const setupMode = settings.productAccessMode === "managed" ? "platform" : "operator";
       if (missing.length > 0 || !slug) {
         return json({
           configured: false,
           status: "disabled",
-          appSlug: slug,
+          setupMode,
+          appSlug: setupMode === "operator" ? slug : null,
           installUrl: null,
           linkUrl: null,
-          missing,
+          missing: setupMode === "operator" ? missing : [],
         });
       }
       const installations = await listWorkspaceGitHubInstallationBindings(deps, grant.workspaceId);
@@ -2342,13 +2518,21 @@ function registerGitHubConnectTool(
       const connectUrl = state
         ? `${baseUrl}/v1/workspaces/${grant.workspaceId}/github/connect?state=${encodeURIComponent(state)}`
         : null;
+      const installationViews = installations.map((installation) => ({
+        ...installation,
+        configureUrl:
+          state && baseUrl
+            ? `${baseUrl}/v1/workspaces/${grant.workspaceId}/github/installations/${installation.installationId}/configure?state=${encodeURIComponent(state)}`
+            : null,
+      }));
       return json({
         configured: true,
         status,
-        appSlug: slug,
+        setupMode,
+        appSlug: setupMode === "operator" ? slug : null,
         installUrl: connectUrl,
         linkUrl: connectUrl,
-        installations,
+        installations: installationViews,
         missing: [],
       });
     },

package/src/mcp/session-view.ts

@@ -564,6 +564,7 @@ export function boundSessionDetailMcp(
     lastSequence: session.lastSequence,
     codexPinnedCredentialId: session.codexPinnedCredentialId,
     codexLastCredentialId: session.codexLastCredentialId,
+    codexCompactionMode: session.codexCompactionMode,
     pinned: session.pinned,
     pinnedAt: session.pinnedAt,
     pinVersion: session.pinVersion,

package/src/mcp/toolspace.ts

@@ -76,9 +76,12 @@ type McpTool = {
 };
 
 const APPROVAL_REQUIRED_MESSAGE = "requires approval - invoke via the agent";
-const TOOLSPACE_AUTH_NEEDED_ERROR_CODE = -32001;
-const TOOLSPACE_AUTH_NEEDED_MESSAGE =
-  "Authentication required - a connection link was posted to the session.";
+const TOOLSPACE_AUTH_NEEDED_ERROR = {
+  // OpenGeni application-defined JSON-RPC code. Keep this positive so it cannot
+  // collide with MCP SDK transport errors such as RequestTimeout (-32001).
+  code: 40_101,
+  message: "Authentication required - a connection link was posted to the session.",
+} as const;
 const TOOLSPACE_NO_ACTIVE_TURN_MESSAGE =
   "no active turn - toolspace calls require an in-flight turn";
 // First-party OpenGeni MCP proxies (files/docs) route back through the same
@@ -721,7 +724,7 @@ async function callRemoteTool(
       return mcpError("upstream tool result exceeded the safety limit");
     }
     if (isToolspaceAuthNeededError(error)) {
-      return mcpError(TOOLSPACE_AUTH_NEEDED_MESSAGE);
+      return mcpError(TOOLSPACE_AUTH_NEEDED_ERROR.message);
     }
     // The raw upstream error can carry provider-specific detail; log it
     // server-side and return only a generic result to the sandbox so no header
@@ -1037,8 +1040,8 @@ async function authNeededFetchResponse(
         jsonrpc: "2.0",
         id: request.id ?? null,
         error: {
-          code: TOOLSPACE_AUTH_NEEDED_ERROR_CODE,
-          message: TOOLSPACE_AUTH_NEEDED_MESSAGE,
+          code: TOOLSPACE_AUTH_NEEDED_ERROR.code,
+          message: TOOLSPACE_AUTH_NEEDED_ERROR.message,
         },
       }),
       {
@@ -1110,9 +1113,14 @@ function fetchInputForAttempt(input: string | URL | Request): string | URL | Req
 }
 
 function isToolspaceAuthNeededError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const code = (error as { code?: unknown }).code;
   return (
-    error instanceof Error &&
-    ((error as { code?: unknown }).code === TOOLSPACE_AUTH_NEEDED_ERROR_CODE ||
-      error.message.includes(TOOLSPACE_AUTH_NEEDED_MESSAGE))
+    code === TOOLSPACE_AUTH_NEEDED_ERROR.code &&
+    (error.message === TOOLSPACE_AUTH_NEEDED_ERROR.message ||
+      error.message ===
+        `MCP error ${TOOLSPACE_AUTH_NEEDED_ERROR.code}: ${TOOLSPACE_AUTH_NEEDED_ERROR.message}`)
   );
 }