@opengeni/api-router 0.30.1 → 1.0.0

package/src/mcp/documents.ts

@@ -1,433 +1,121 @@
+import { searchKnowledgeEntries } from "@opengeni/core";
+import type { Settings } from "@opengeni/config";
+import { KnowledgeEntryListRequest } from "@opengeni/contracts";
+import type { DocumentServices } from "@opengeni/documents";
 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,
-} from "@opengeni/documents";
-import { createKnowledgeMemory, listKnowledgeMemories, type Database } from "@opengeni/db";
+  getKnowledgeEntry,
+  listKnowledgeEntries,
+  type KnowledgeContext,
+  type Database,
+} from "@opengeni/db";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod/v4";
-import { mcpMutationReceipt } from "./receipts";
-
-const SearchInputSchema = {
-  query: z.string().min(1),
-  baseIds: z.array(z.string().uuid()).optional(),
-  limit: z.number().int().positive().max(50).optional(),
-  mode: z.enum(["hybrid", "vector", "keyword"]).optional(),
-  sourceKinds: z
-    .array(
-      z.enum([
-        "manual_upload",
-        "meeting_transcript",
-        "repository",
-        "email",
-        "chat",
-        "document",
-        "web",
-        "other",
-      ]),
-    )
-    .optional(),
-  aclTags: z.array(z.string().min(1)).optional(),
-};
-
-const MemoryKindSchema = z.enum(["semantic", "episodic", "procedural", "decision", "preference"]);
-const SourceRefSchema = z.object({
-  kind: z.enum(["document_chunk", "document", "session_event", "memory", "external"]),
-  id: z.string().min(1),
-  uri: z.string().min(1).optional(),
-  title: z.string().min(1).optional(),
-  metadata: z.record(z.string(), z.unknown()).optional(),
-});
 
+/** The docs endpoint is a transport for canonical Knowledge retrieval. Legacy
+ * chunk/base retrieval is retired: it cannot bypass pending Knowledge review. */
 export function buildDocumentsMcpServer(
   db: Database,
   accountId: string,
   workspaceId: string,
   documentServices: DocumentServices,
-  options: {
-    createdBySessionId?: string | undefined;
-    /** Immutable human subject whose agent is making this retrieval request. */
-    initiatingSubjectId: string;
-  },
+  options: { knowledge: KnowledgeContext; settings?: Settings },
 ): McpServer {
-  const server = new McpServer({
-    name: "opengeni-documents",
-    version: "1.0.0",
-  });
-  // This server is the agent retrieval surface. Agent-disabled documents are
-  // never reachable. Workspace-visible documents are shared; private
-  // documents are available only to the creating subject's agent.
-  const agentAccess: DocumentAccessFilter = {
-    agentOnly: true,
-    viewerSubjectId: options.initiatingSubjectId,
-  };
-
-  server.registerTool(
-    "list_document_bases",
-    {
-      description: "List document bases available for retrieval.",
-      inputSchema: {},
-    },
-    async () => ({
-      content: [{ type: "text", text: JSON.stringify(await listDocumentBases(db, workspaceId)) }],
-    }),
-  );
-
-  server.registerTool(
-    "search_documents",
-    {
-      description: "Search indexed documents with hybrid, vector, or keyword retrieval.",
-      inputSchema: SearchInputSchema,
-    },
-    async (input) =>
-      searchContent(
-        db,
-        accountId,
-        workspaceId,
-        documentServices,
-        input,
-        options.initiatingSubjectId,
-      ),
-  );
-
+  const context = options.knowledge;
+  if (context.accountId !== accountId || context.workspaceId !== workspaceId)
+    throw new Error("Knowledge gateway authority mismatch");
+  const server = new McpServer({ name: "opengeni-knowledge", version: "2.0.0" });
   server.registerTool(
     "knowledge_search",
     {
       description:
-        "Search the effective authorized organization, current-workspace, and immutable initiating-user personal document scope. Authorization is applied before ranking and every result retains source and authority provenance.",
-      inputSchema: SearchInputSchema,
-    },
-    async (input) =>
-      searchKnowledge(
-        db,
-        accountId,
-        workspaceId,
-        documentServices,
-        input,
-        options.initiatingSubjectId,
-      ),
-  );
-
-  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 }) => ({
+        "Search published structured Knowledge and retained source text in the current authorized scope. Use a concise subject or entity name first (for example Acme); omit scope to search all authorized scopes. If a query returns no entries, retry the key name alone in the same scope or browse groups before concluding the information is absent.",
+      inputSchema: KnowledgeEntryListRequest.omit({
+        view: true,
+        sessionId: true,
+        reviewBatchId: true,
+      }).shape,
+    },
+    async (input) => ({
       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 } : {}),
-              }),
+            await searchKnowledgeEntries(
+              db,
+              context,
+              input,
+              () => documentServices.embedder,
+              options.settings,
             ),
           ),
         },
       ],
     }),
   );
-
   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",
-    {
-      description: "Fetch one indexed document chunk by id.",
-      inputSchema: {
-        chunkId: z.string().uuid(),
-      },
-    },
-    async ({ chunkId }) => {
-      const found = await getDocumentChunk(db, accountId, workspaceId, chunkId, agentAccess);
-      return {
-        content: [
-          { type: "text", text: found ? JSON.stringify(found) : `chunk not found: ${chunkId}` },
-        ],
-        isError: !found,
-      };
-    },
-  );
-
-  server.registerTool(
-    "knowledge_fetch",
-    {
-      description: "Fetch one knowledge source chunk by id.",
-      inputSchema: {
-        chunkId: z.string().uuid(),
-      },
-    },
-    async ({ chunkId }) => {
-      const found = await getDocumentChunk(db, accountId, workspaceId, chunkId, agentAccess);
-      return {
-        content: [
-          { type: "text", text: found ? JSON.stringify(found) : `chunk not found: ${chunkId}` },
-        ],
-        isError: !found,
-      };
-    },
-  );
-
-  server.registerTool(
-    "memory_search",
+    "knowledge_browse",
     {
-      description: "Search approved company memory records.",
+      description: "Browse Knowledge groups or entries in one group, across sources.",
       inputSchema: {
-        query: z.string().min(1).optional(),
-        kind: MemoryKindSchema.optional(),
-        scope: z.string().min(1).optional(),
-        limit: z.number().int().positive().max(100).optional(),
+        groupId: z.uuid().optional(),
+        cursor: z.string().optional(),
+        limit: z.number().int().positive().max(50).optional(),
       },
     },
-    async ({ query, kind, scope, limit }) => ({
+    async (input) => ({
       content: [
         {
           type: "text",
           text: JSON.stringify(
-            await listKnowledgeMemories(db, workspaceId, {
-              ...(query ? { query } : {}),
-              status: ["active", "approved"],
-              ...(kind ? { kind } : {}),
-              ...(scope ? { scope } : {}),
-              ...(limit ? { limit } : {}),
+            await listKnowledgeEntries(db, context, {
+              ...input,
+              ...(input.groupId ? {} : { kind: "group" }),
             }),
           ),
         },
       ],
     }),
   );
-
   server.registerTool(
-    "memory_propose",
+    "knowledge_get",
     {
-      description: "Propose a company memory record for human review.",
+      description:
+        "Read an exact published Knowledge revision and its evidence. Long source text is paginated.",
       inputSchema: {
-        text: z.string().min(1),
-        kind: MemoryKindSchema.optional(),
-        scope: z.string().min(1).optional(),
-        sourceRefs: z.array(SourceRefSchema).optional(),
-        confidence: z.number().min(0).max(1).optional(),
-        metadata: z.record(z.string(), z.unknown()).optional(),
+        entryId: z.uuid(),
+        revisionId: z.uuid().optional(),
+        offset: z.number().int().nonnegative().default(0),
+        maxChars: z.number().int().positive().max(16000).default(8000),
       },
     },
-    async ({ text, kind, scope, sourceRefs, confidence, metadata }) => {
-      const memory = await createKnowledgeMemory(db, {
-        accountId,
-        workspaceId,
-        status: "proposed",
-        kind: kind ?? "semantic",
-        scope: scope ?? "workspace",
-        text,
-        sourceRefs:
-          sourceRefs?.map((sourceRef) => ({
-            ...sourceRef,
-            metadata: sourceRef.metadata ?? {},
-          })) ?? [],
-        confidence: confidence ?? 0.5,
-        metadata: metadata ?? {},
-        createdBySessionId: options.createdBySessionId,
+    async (input) => {
+      const record = await getKnowledgeEntry(db, context, input.entryId, {
+        revisionId: input.revisionId,
       });
+      if (!record) return { content: [{ type: "text", text: JSON.stringify({ found: false }) }] };
+      const text = record.revision.entry.content;
+      const end = Math.min(text.length, input.offset + input.maxChars);
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify(
-              mcpMutationReceipt({
-                operation: "memory_propose",
-                committed: true,
-                outcome: "created",
-                changed: true,
-                resource: {
-                  type: "knowledge_memory",
-                  id: memory.id,
-                  state: memory.status,
-                },
-                timestamp: memory.updatedAt,
-                idempotency: { status: "not_supported" },
-                nextAction: { tool: "memory_search", arguments: {} },
-              }),
-            ),
+            text: JSON.stringify({
+              ...record,
+              revision: {
+                ...record.revision,
+                entry: { ...record.revision.entry, content: text.slice(input.offset, end) },
+              },
+              contentRange: {
+                start: input.offset,
+                end,
+                total: text.length,
+                nextOffset: end < text.length ? end : null,
+              },
+            }),
           },
         ],
       };
     },
   );
-
   return server;
 }
-
-async function searchContent(
-  db: Database,
-  accountId: string,
-  workspaceId: string,
-  documentServices: DocumentServices,
-  input: {
-    query: string;
-    baseIds?: string[] | undefined;
-    limit?: number | undefined;
-    mode?: "hybrid" | "vector" | "keyword" | undefined;
-    sourceKinds?:
-      | Array<
-          | "manual_upload"
-          | "meeting_transcript"
-          | "repository"
-          | "email"
-          | "chat"
-          | "document"
-          | "web"
-          | "other"
-        >
-      | undefined;
-    aclTags?: string[] | undefined;
-  },
-  initiatingSubjectId: string,
-) {
-  const results = await searchEffectiveDocuments(
-    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(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-artifacts.ts

@@ -32,12 +32,13 @@ const ArtifactCommand = z
   .object({ kind: z.string().min(1).max(128) })
   .passthrough()
   .describe(
-    "One canonical modality command. Use the exact OpenGeni document, spreadsheet, or presentation skill command contract; never send local-file facade calls here.",
+    "One canonical modality command. Use the exact Opengeni document, spreadsheet, or presentation skill command contract; never send local-file facade calls here.",
   );
 
 const ArtifactMetadata = z
   .object({
     id: ArtifactId,
+    artifactReference: z.string(),
     modality: Modality,
     title: z.string(),
     lifecycle: z.enum(["active", "archived"]),
@@ -203,13 +204,17 @@ export function registerEditableArtifactAgentTools(
     {
       title: "Inspect editable artifact",
       description:
-        "Query the artifact's current canonical head through the same native kernel used by the browser. Use bounded modality queries; results are current, not a sandbox-file snapshot.",
+        "Query the artifact's current canonical head through the same native kernel used by the browser. Use bounded modality queries; results are current, not a sandbox-file snapshot. Native document queries return a server-issued inspectionReceiptId; use a post-edit body inspection receipt for declared report completion. If the document changes during inspection, retry against its current head.",
       inputSchema: {
         artifactId: ArtifactId,
         modality: Modality,
         request: EditableArtifactQueryRequestSchema,
       },
-      outputSchema: { artifact: ArtifactMetadata, projection: z.unknown() },
+      outputSchema: {
+        artifact: ArtifactMetadata,
+        projection: z.unknown(),
+        inspectionReceiptId: z.string().uuid().optional(),
+      },
       annotations: readOnlyAnnotations("Inspect editable artifact"),
     },
     async ({ artifactId, modality, request }, extra) =>
@@ -262,11 +267,12 @@ export function registerEditableArtifactAgentTools(
     "editable_artifact_export",
     {
       title: "Export editable artifact",
-      description:
-        "Pin the current artifact head and start an immutable Office/PDF/image export. This does not write into the sandbox. Poll opengeni__editable_artifact_export_status for the resulting workspace file ID.",
+      description: `Pin the current artifact head and start an immutable file export. ${input.deps.editableArtifactAgent?.describeExportFormats?.() ?? "No exporter capability description is available; query this deployment before promising a format."} This does not write into the sandbox. Poll opengeni__editable_artifact_export_status for the resulting workspace file ID.`,
       inputSchema: {
         artifactId: ArtifactId,
-        format: Format,
+        format: Format.describe(
+          "Target file format. Only the formats listed in this tool's description are served; any other combination is refused with unsupported_format.",
+        ),
         options: JsonRecord.optional(),
       },
       outputSchema: {

package/src/mcp/files.ts

@@ -1,11 +1,23 @@
 import type { AccessGrant } from "@opengeni/contracts";
-import { requireFile } from "@opengeni/db";
-import { hasPermission, type ApiRouteDeps } from "@opengeni/core";
+import { recordAuditEvent, requireFileForSubject, withSessionRlsActorContext } from "@opengeni/db";
+import {
+  hasPermission,
+  fileOwnerContextForAccess,
+  fileOwnerContextForAgent,
+  type AccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod/v4";
+import { userContentSignedGetUrlOptions } from "../http/user-content";
 
 /** Dedicated file MCP surface. The broad `opengeni` server never registers it. */
-export function buildFilesMcpServer(deps: ApiRouteDeps, grant: AccessGrant): McpServer {
+export function buildFilesMcpServer(
+  deps: ApiRouteDeps,
+  authority: AccessGrant | AccessGrantAuthorization,
+): McpServer {
+  const access = "grant" in authority ? authority : undefined;
+  const grant = access ? access.grant : (authority as AccessGrant);
   const server = new McpServer({
     name: "opengeni-files",
     version: "1.0.0",
@@ -34,42 +46,72 @@ export function buildFilesMcpServer(deps: ApiRouteDeps, grant: AccessGrant): Mcp
       inputSchema: { fileId: z.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 {
-        content: [
-          {
-            type: "text" as const,
-            text: JSON.stringify(
-              {
-                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(),
-                },
-              },
-              null,
-              2,
-            ),
+      const actor = access
+        ? await fileOwnerContextForAccess(deps, access, "files:read")
+        : grant.principalKind === "agent_attempt"
+          ? await fileOwnerContextForAgent(deps, grant, "files:read")
+          : { subjectId: grant.subjectId, privateFileOwnerSubjectId: null };
+      return withSessionRlsActorContext(actor, async () => {
+        if (!deps.objectStorage) {
+          throw new Error("object storage is not configured");
+        }
+        const file = await requireFileForSubject(deps.db, {
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          subjectId: grant.subjectId,
+          fileId,
+        });
+        if (file.status !== "ready") {
+          throw new Error(`file is ${file.status}`);
+        }
+        const signed = await deps.objectStorage.createGetUrl({
+          key: file.objectKey,
+          ...userContentSignedGetUrlOptions(file.contentType, file.filename),
+        });
+        // Principal-facing signed URL issuance is a metadata-only audit
+        // fact, awaited before the URL leaves the platform. Never the URL/key.
+        await recordAuditEvent(deps.db, {
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          subjectId: grant.subjectId,
+          action: "file.signed_url.issued",
+          targetType: "workspace_file",
+          targetId: file.id,
+          metadata: {
+            fileId: file.id,
+            kind: "mcp_download",
+            expiresAt: signed.expiresAt.toISOString(),
           },
-        ],
-      };
+        });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  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(),
+                  },
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      });
     },
   );