@opengeni/api-router 0.12.5 → 0.12.12

package/src/mcp/server.ts

@@ -1,5 +1,7 @@
 import {
   CreateScheduledTaskRequest,
+  DEFAULT_FIRST_PARTY_MCP_TOOLS,
+  FIRST_PARTY_MCP_TOOL_NAMES,
   defaultRepositoryMountPath,
   SESSION_EVENT_RAW_DELTA_TYPES,
   SessionEventLatestClass,
@@ -15,9 +17,11 @@ import {
   VariableSetVariableName,
   type AccessGrant,
   type GitHubRepository,
+  type FirstPartyMcpToolName,
   type Permission,
   type ResourceRef,
   type SessionAuthorizationOperation,
+  type SessionAuthorizationSurface,
   type Session,
   UpdateScheduledTaskRequest,
 } from "@opengeni/contracts";
@@ -52,7 +56,6 @@ import {
   MEMORY_CORRECT_TOOL_DESCRIPTION,
   MEMORY_SAVE_TOOL_DESCRIPTION,
   MEMORY_SEARCH_TOOL_DESCRIPTION,
-  requireFile,
   requireScheduledTask,
   requireSession,
   saveWorkspaceMemory,
@@ -73,7 +76,13 @@ import {
   GitHubAppConfigurationError,
   githubAppMissingSettings,
 } from "@opengeni/github";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  McpServer,
+  type RegisteredTool,
+  type ToolCallback,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AnySchema, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import * as z4 from "zod/v4";
 import {
   hasPermission,
@@ -157,15 +166,153 @@ export type McpServerOptions = {
   workspaceMemoryEnabled?: boolean | undefined;
 };
 
+type FirstPartyToolAuthorization = {
+  sessionRequired?: true;
+  allOf?: readonly Permission[];
+  anyOf?: readonly Permission[];
+};
+
+/**
+ * Authorization is deliberately complete and separate from visibility. The
+ * `satisfies Record` check makes every catalog addition choose an explicit
+ * registration predicate before it can compile.
+ */
+const FIRST_PARTY_TOOL_AUTHORIZATION = {
+  set_session_title: { sessionRequired: true, allOf: ["sessions:control"] },
+  goal_set: { sessionRequired: true, allOf: ["goals:manage"] },
+  goal_update: { sessionRequired: true, allOf: ["goals:manage"] },
+  goal_complete: { sessionRequired: true, allOf: ["goals:manage"] },
+  goal_pause: { sessionRequired: true, allOf: ["goals:manage"] },
+  memory_search: { sessionRequired: true, allOf: ["documents:search"] },
+  memory_save: { sessionRequired: true, allOf: ["documents:search"] },
+  memory_correct: { sessionRequired: true, allOf: ["documents:search"] },
+  sandboxes_list: { sessionRequired: true, allOf: ["sessions:read"] },
+  sandbox_attach: { sessionRequired: true, allOf: ["sessions:control"] },
+  sandbox_swap: { sessionRequired: true, allOf: ["sessions:control"] },
+  run_on: { sessionRequired: true, allOf: ["sessions:control"] },
+  sandbox_provision: { sessionRequired: true, allOf: ["sessions:control"] },
+  rig_list: { allOf: ["rigs:use"] },
+  rig_get: { allOf: ["rigs:use"] },
+  rig_propose_change: { allOf: ["rigs:use"] },
+  rig_verify: { allOf: ["rigs:use"] },
+  rig_promote: { allOf: ["rigs:manage"] },
+  sessions_list: { allOf: ["sessions:read"] },
+  session_get: { allOf: ["sessions:read"] },
+  session_events: { allOf: ["sessions:read"] },
+  session_create: { allOf: ["sessions:create"] },
+  session_send_message: { allOf: ["sessions:control"] },
+  session_pause: { allOf: ["sessions:control"] },
+  session_resume: { allOf: ["sessions:control"] },
+  session_steer: { sessionRequired: true, allOf: ["sessions:control"] },
+  set_other_session_title: { allOf: ["sessions:control"] },
+  variable_set_list: { allOf: ["variable-sets:use"] },
+  environment_list: { allOf: ["variable-sets:use"] },
+  variable_set_set_variable: { allOf: ["variable-sets:manage"] },
+  environment_set_variable: { allOf: ["variable-sets:manage"] },
+  github_connect_link: { allOf: ["github:use"] },
+  github_token: { sessionRequired: true, allOf: ["github:use"] },
+  github_repositories_list: { allOf: ["github:use"] },
+  social_connections_list: { allOf: ["connections:read"] },
+  social_posts_recent: { allOf: ["connections:read"] },
+  social_daily_analysis_context: { allOf: ["connections:read"] },
+  scheduled_tasks_list: { anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"] },
+  scheduled_tasks_get: { anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"] },
+  scheduled_tasks_create: { allOf: ["scheduled_tasks:manage"] },
+  scheduled_tasks_update: { allOf: ["scheduled_tasks:manage"] },
+  scheduled_tasks_pause: { allOf: ["scheduled_tasks:manage"] },
+  scheduled_tasks_resume: { allOf: ["scheduled_tasks:manage"] },
+  scheduled_tasks_trigger: { allOf: ["scheduled_tasks:run"] },
+  scheduled_tasks_delete: { allOf: ["scheduled_tasks:manage"] },
+  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_list_users: { allOf: ["connections:read"] },
+  slack_bot_post_message: { allOf: ["connections:read"] },
+} satisfies Record<FirstPartyMcpToolName, FirstPartyToolAuthorization>;
+
+const FIRST_PARTY_MCP_TOOL_NAME_SET = new Set<string>(FIRST_PARTY_MCP_TOOL_NAMES);
+
+class PolicyMcpServer extends McpServer {
+  private registeredToolCount = 0;
+
+  constructor(
+    private readonly grant: AccessGrant,
+    private readonly sessionId: string | null,
+    private readonly selectedTools: ReadonlySet<FirstPartyMcpToolName> | null,
+    private readonly allowUncatalogued: boolean,
+  ) {
+    super({ name: "opengeni", version: "1.0.0" });
+  }
+
+  override registerTool<
+    OutputArgs extends ZodRawShapeCompat | AnySchema,
+    InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined,
+  >(
+    name: string,
+    config: {
+      title?: string;
+      description?: string;
+      inputSchema?: InputArgs;
+      outputSchema?: OutputArgs;
+      annotations?: ToolAnnotations;
+      _meta?: Record<string, unknown>;
+    },
+    cb: ToolCallback<InputArgs>,
+  ): RegisteredTool {
+    const catalogued = FIRST_PARTY_MCP_TOOL_NAME_SET.has(name);
+    let admitted = this.allowUncatalogued && !catalogued;
+    if (catalogued) {
+      const toolName = name as FirstPartyMcpToolName;
+      const policy: FirstPartyToolAuthorization = FIRST_PARTY_TOOL_AUTHORIZATION[toolName];
+      const authorized =
+        (!policy.sessionRequired || this.sessionId !== null) &&
+        (policy.allOf?.every((permission) => hasPermission(this.grant.permissions, permission)) ??
+          true) &&
+        (policy.anyOf?.some((permission) => hasPermission(this.grant.permissions, permission)) ??
+          true);
+      const selected = this.selectedTools === null || this.selectedTools.has(toolName);
+      admitted = authorized && selected;
+    }
+    if (!admitted) {
+      return {
+        ...(config.title ? { title: config.title } : {}),
+        ...(config.description ? { description: config.description } : {}),
+        ...(config.annotations ? { annotations: config.annotations } : {}),
+        ...(config._meta ? { _meta: config._meta } : {}),
+        handler: cb as RegisteredTool["handler"],
+        enabled: false,
+        enable() {},
+        disable() {},
+        update() {},
+        remove() {},
+      };
+    }
+    this.registeredToolCount += 1;
+    return super.registerTool(name, config, cb);
+  }
+
+  ensureToolsListHandler(): void {
+    if (this.registeredToolCount > 0) return;
+    super
+      .registerTool(
+        "__opengeni_empty_first_party_surface__",
+        {
+          description: "Internal disabled placeholder for an empty first-party surface.",
+          inputSchema: z4.object({}),
+        },
+        async () => ({
+          content: [{ type: "text" as const, text: '{"unavailable":true}' }],
+        }),
+      )
+      .disable();
+  }
+}
+
 export function buildOpenGeniMcpServer(
   deps: ApiRouteDeps,
   grant: AccessGrant,
   options: McpServerOptions = {},
 ): McpServer {
-  const server = new McpServer({
-    name: "opengeni",
-    version: "1.0.0",
-  });
   const json = (value: unknown) => ({
     content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }],
   });
@@ -178,6 +325,14 @@ export function buildOpenGeniMcpServer(
     typeof grant.metadata?.["sessionId"] === "string"
       ? (grant.metadata["sessionId"] as string)
       : null;
+  const selectedTools =
+    sessionId !== null && !toolspaceMode
+      ? new Set(
+          (grant.metadata?.["firstPartyMcpTools"] as FirstPartyMcpToolName[] | undefined) ??
+            DEFAULT_FIRST_PARTY_MCP_TOOLS,
+        )
+      : null;
+  const server = new PolicyMcpServer(grant, sessionId, selectedTools, toolspaceMode);
   // set_session_title names the agent's OWN session — pure session metadata,
   // not a goal operation — so it is available on every session, gated only on
   // the signed sessionId (NOT goals:manage, and NOT on a goal existing).
@@ -248,45 +403,6 @@ export function buildOpenGeniMcpServer(
     }
   }
 
-  if (!toolspaceMode || can("files:read")) {
-    server.registerTool(
-      "files_get_download_url",
-      {
-        description: "Create a short-lived download URL for a ready file asset.",
-        inputSchema: { fileId: z4.string().uuid() },
-      },
-      async ({ fileId }) => {
-        if (!deps.objectStorage) {
-          throw new Error("object storage is not configured");
-        }
-        const file = await requireFile(deps.db, grant.workspaceId, fileId);
-        if (file.status !== "ready") {
-          throw new Error(`file is ${file.status}`);
-        }
-        const signed = await deps.objectStorage.createGetUrl({
-          key: file.objectKey,
-        });
-        return json({
-          file: {
-            id: file.id,
-            filename: file.filename,
-            safeFilename: file.safeFilename,
-            contentType: file.contentType,
-            sizeBytes: file.sizeBytes,
-            sha256: file.sha256,
-            status: file.status,
-            createdAt: file.createdAt,
-            updatedAt: file.updatedAt,
-          },
-          downloadUrl: {
-            url: signed.url,
-            expiresAt: signed.expiresAt.toISOString(),
-          },
-        });
-      },
-    );
-  }
-
   if (!toolspaceMode || can("github:use")) {
     server.registerTool(
       "github_repositories_list",
@@ -604,6 +720,7 @@ export function buildOpenGeniMcpServer(
           task,
           agentRunUsageIdempotencyKey,
           triggerWorkflowId,
+          initiator: { kind: "subject", subjectId: grant.subjectId },
         });
         await recordWorkspaceUsage(deps, {
           accountId: grant.accountId,
@@ -653,6 +770,7 @@ export function buildOpenGeniMcpServer(
   }
 
   registerToolspaceProxyTools(server, options.toolspace ?? null);
+  server.ensureToolsListHandler();
 
   return server;
 }
@@ -1450,6 +1568,7 @@ function registerRigTools(
 function exactAgentCommandContext(
   grant: AccessGrant,
   callerSessionId: string,
+  authorizationSurface?: SessionAuthorizationSurface,
 ): AgentSessionCommandContext {
   const turnId = grant.metadata?.["turnId"];
   const attemptId = grant.metadata?.["attemptId"];
@@ -1471,6 +1590,7 @@ function exactAgentCommandContext(
     callerTurnId: turnId,
     callerAttemptId: attemptId,
     callerExecutionGeneration: executionGeneration,
+    ...(authorizationSurface ? { authorizationSurface } : {}),
   };
 }
 
@@ -1734,6 +1854,12 @@ function registerWorkspaceOrchestrationTools(
             .describe(
               "Optional first-party capability set for the child. Omit to inherit this session's effective permissions. An explicit set may only narrow capabilities held by this session. A goal-bearing child requires goals:manage in the resulting set; creation fails rather than adding it implicitly.",
             ),
+          firstPartyMcpTools: z4
+            .array(z4.enum(FIRST_PARTY_MCP_TOOL_NAMES))
+            .optional()
+            .describe(
+              "Exact model-visible first-party tool selection for the child. Omit to inherit this session's effective selection. This does not grant permissions.",
+            ),
           // Shared-sandbox placement (addendum 05 §D). OMIT (default) to SHARE the
           // creator's box — one filesystem/repo/desktop, N independent conversations;
           // this is the SAFE DEFAULT. Pass "new" for a fresh isolated box (a different
@@ -1792,7 +1918,7 @@ function registerWorkspaceOrchestrationTools(
       "session_send_message",
       {
         description:
-          "Send information to another session. From an OpenGeni worker this becomes a coalescible internal update, never a visible prompt-queue row; pending updates are delivered together on the target's next inference. A sessionless operator call appends one visible prompt.",
+          "Send information to another session. From an OpenGeni worker this becomes a canonical coalescible machine input: it appears in the target's compact incoming queue group, is durably added to model history when claimed, and remains visible in the timeline. A sessionless operator call appends one human/API prompt.",
         inputSchema: {
           sessionId: z4.string().uuid(),
           text: z4.string().min(1),
@@ -1830,7 +1956,6 @@ function registerWorkspaceOrchestrationTools(
           targetSessionId,
           {
             text,
-            toolsProvided: false,
             delivery: "send",
             origin: "operator",
             clientEventId: idempotencyKey,
@@ -1854,16 +1979,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",
@@ -1876,7 +1995,7 @@ function registerWorkspaceOrchestrationTools(
             effectiveControl: projectEffectiveControlForRelatedAccess(
               serializeEffectiveSessionControl(controlled.control),
               sessionId,
-              authorization?.relatedSessionAccess ?? "root",
+              controlled.authorization?.relatedSessionAccess ?? "root",
             ),
             interruptionCount: controlled.interruptionCount,
             replay: controlled.replay,
@@ -1889,6 +2008,7 @@ function registerWorkspaceOrchestrationTools(
             workspaceId: grant.workspaceId,
             sessionId,
             subjectId: grant.subjectId,
+            authorizationSurface: "first_party_mcp",
           },
           {
             action: "pause",
@@ -1896,14 +2016,7 @@ function registerWorkspaceOrchestrationTools(
             ...(reason ? { reason } : {}),
           },
         );
-        return json({
-          ...controlled,
-          effectiveControl: projectEffectiveControlForRelatedAccess(
-            controlled.effectiveControl,
-            sessionId,
-            authorization?.relatedSessionAccess ?? "root",
-          ),
-        });
+        return json(controlled);
       },
     );
 
@@ -1919,16 +2032,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",
@@ -1941,7 +2048,7 @@ function registerWorkspaceOrchestrationTools(
             effectiveControl: projectEffectiveControlForRelatedAccess(
               serializeEffectiveSessionControl(controlled.control),
               sessionId,
-              authorization?.relatedSessionAccess ?? "root",
+              controlled.authorization?.relatedSessionAccess ?? "root",
             ),
             interruptionCount: controlled.interruptionCount,
             replay: controlled.replay,
@@ -1954,6 +2061,7 @@ function registerWorkspaceOrchestrationTools(
             workspaceId: grant.workspaceId,
             sessionId,
             subjectId: grant.subjectId,
+            authorizationSurface: "first_party_mcp",
           },
           {
             action: "resume",
@@ -1961,14 +2069,7 @@ function registerWorkspaceOrchestrationTools(
             ...(reason ? { reason } : {}),
           },
         );
-        return json({
-          ...controlled,
-          effectiveControl: projectEffectiveControlForRelatedAccess(
-            controlled.effectiveControl,
-            sessionId,
-            authorization?.relatedSessionAccess ?? "root",
-          ),
-        });
+        return json(controlled);
       },
     );
 
@@ -1977,7 +2078,7 @@ function registerWorkspaceOrchestrationTools(
         "session_steer",
         {
           description:
-            "Atomically replace another session's current direction and resume it. The instruction is an internal update, never a human queue row.",
+            "Atomically replace another session's current direction and resume it. The Agent Steer is a typed machine input shown in the target queue/timeline and durably retained in model history; it never impersonates a human prompt.",
           inputSchema: {
             sessionId: z4.string().uuid(),
             instruction: z4.string().min(1),
@@ -1985,10 +2086,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({
@@ -2194,14 +2294,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);
@@ -2219,13 +2321,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/routes/files.ts

@@ -27,10 +27,21 @@ import { HTTPException } from "hono/http-exception";
 import { requireAccessGrant } from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { buildFilesMcpServer } from "../mcp/files";
 
 export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { db, objectStorage } = deps;
 
+  app.all("/v1/workspaces/:workspaceId/mcp/files", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+    const server = buildFilesMcpServer(deps, grant);
+    await server.connect(transport);
+    return await transport.handleRequest(c.req.raw);
+  });
+
   app.post("/v1/workspaces/:workspaceId/files/uploads", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "files:upload");