@opengeni/api-router 3.0.1 → 3.1.2

package/src/mcp/company-profile-agent-admin.ts

@@ -26,6 +26,15 @@ export type RegisterCompanyProfileAgentAdminToolsInput = {
   db: Database;
   attempt: CompanyProfileAgentAttempt;
   authorize: () => Promise<void>;
+  /**
+   * The refusal for a caller that may not administer the organization
+   * profile even with the owner's authority (an agent started from a Site
+   * page), or null.
+   */
+  refuseSiteAgent: () => Promise<{
+    isError: true;
+    content: Array<{ type: "text"; text: string }>;
+  } | null>;
   json: JsonResult;
   router?: Pick<ReturnType<typeof createCompanyProfileAgentAdminRouter>, "propose" | "confirm">;
 };
@@ -137,6 +146,8 @@ export function registerCompanyProfileAgentAdminTools(
     },
     async (request) => {
       await input.authorize();
+      const refused = await input.refuseSiteAgent();
+      if (refused) return refused;
       const parsed = AgentAuthoredCompanyProfileContent.safeParse({
         identity: request.identity,
         mission: request.mission,
@@ -185,6 +196,8 @@ export function registerCompanyProfileAgentAdminTools(
     },
     async (request) => {
       await input.authorize();
+      const refused = await input.refuseSiteAgent();
+      if (refused) return refused;
       try {
         return input.json(await router.confirm({ attempt: input.attempt, request }));
       } catch (error) {

package/src/mcp/contract-input.ts

@@ -0,0 +1,165 @@
+import * as z from "zod/v4";
+
+/**
+ * Publish the input side of a contract, validate it, and retain the exact call.
+ * MCP parsing must not insert defaults, trim text, or erase omitted fields before
+ * the application applies presence-sensitive inheritance and authority rules.
+ * A narrower projection may hide host-only fields; validation retains the full
+ * contract's preprocessors and cross-field checks.
+ */
+export function contractToolInput<T extends z.ZodObject>(
+  projection: T,
+  validation: z.ZodType = projection,
+  options: { jsonObjectFields?: readonly string[] } = {},
+): z.ZodType<z.input<T>, z.input<T>> {
+  const inputProjection = projection.strict();
+  const jsonSchema = z.toJSONSchema(inputProjection, {
+    io: "input",
+    target: "draft-7",
+  });
+  assertDescribedToolInput(jsonSchema);
+  for (const field of options.jsonObjectFields ?? []) {
+    const property = (jsonSchema.properties as Record<string, { type?: string }>)[field];
+    if (property?.type !== "object") {
+      throw new Error(`JSON string normalization requires an object-only input: ${field}`);
+    }
+  }
+  const normalizeObject = (value: unknown): unknown => {
+    if (typeof value !== "string") return value;
+    try {
+      const parsed: unknown = JSON.parse(value);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    } catch {
+      // The normal value-free contract error reports the expected object.
+    }
+    return value;
+  };
+  // MCP's SDK only publishes recognized object schemas. A passthrough object
+  // keeps the call intact, while metadata supplies the projected JSON Schema.
+  return z
+    .object(
+      Object.fromEntries(
+        (options.jsonObjectFields ?? []).map((field) => [
+          field,
+          z.preprocess(normalizeObject, z.unknown()).optional(),
+        ]),
+      ),
+    )
+    .catchall(z.unknown())
+    .superRefine((args, context) => {
+      const projected = inputProjection.safeParse(args);
+      const parsed = projected.success ? validation.safeParse(args) : projected;
+      if (!parsed.success) {
+        for (const issue of inputIssues(parsed.error.issues)) context.addIssue({ ...issue });
+      }
+    })
+    .meta(jsonSchema) as unknown as z.ZodType<z.input<T>, z.input<T>>;
+}
+
+/** Every named input and array element needs a schema. Dictionary values may be arbitrary JSON. */
+export function assertDescribedToolInput(schema: unknown, tool = "tool"): void {
+  const activeRefs = new Set<string>();
+  function visit(value: unknown, path: string, allowOpaque = false): void {
+    if (value === false) return;
+    if (value === true && allowOpaque) return;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error(`${tool}: invalid input schema at ${path}`);
+    }
+    const node = value as Record<string, unknown>;
+    const constraints = ["type", "$ref", "enum", "const", "anyOf", "oneOf", "allOf", "not"];
+    if (!constraints.some((key) => Object.hasOwn(node, key))) {
+      if (allowOpaque) return;
+      throw new Error(`${tool}: input ${path} has no declared structure; use its contract schema`);
+    }
+    if (typeof node.$ref === "string" && node.$ref.startsWith("#/") && !activeRefs.has(node.$ref)) {
+      const ref = node.$ref;
+      let target = schema;
+      for (const part of ref.slice(2).split("/")) {
+        target = (target as Record<string, unknown>)?.[
+          part.replace(/~1/g, "/").replace(/~0/g, "~")
+        ];
+      }
+      activeRefs.add(ref);
+      visit(target, path, allowOpaque);
+      activeRefs.delete(ref);
+    }
+    for (const [key, child] of Object.entries((node.properties ?? {}) as Record<string, unknown>)) {
+      visit(child, `${path}.${key}`);
+    }
+    if (node.type === "array" && node.items === undefined && node.prefixItems === undefined) {
+      throw new Error(
+        `${tool}: input ${path}[] has no declared structure; use its contract schema`,
+      );
+    }
+    if (Array.isArray(node.items)) {
+      node.items.forEach((child, index) => visit(child, `${path}[${index}]`));
+      if (node.additionalItems !== undefined) visit(node.additionalItems, `${path}[...]`);
+      else if (typeof node.maxItems !== "number" || node.maxItems > node.items.length) {
+        throw new Error(
+          `${tool}: input ${path}[...] has no declared structure; use its contract schema`,
+        );
+      }
+    } else if (node.items !== undefined) visit(node.items, `${path}[]`);
+    if (Array.isArray(node.prefixItems)) {
+      node.prefixItems.forEach((child, index) => visit(child, `${path}[${index}]`));
+      if (
+        node.items === undefined &&
+        (typeof node.maxItems !== "number" || node.maxItems > node.prefixItems.length)
+      ) {
+        throw new Error(
+          `${tool}: input ${path}[...] has no declared structure; use its contract schema`,
+        );
+      }
+    }
+    // An unconstrained dictionary is intentional extension data. If its values
+    // declare a structure, check that structure's fields just like named inputs.
+    const dictionary = node.additionalProperties;
+    if (dictionary && typeof dictionary === "object" && Object.keys(dictionary).length > 0) {
+      visit(dictionary, `${path}.*`, true);
+    }
+    for (const [key, child] of Object.entries(
+      (node.patternProperties ?? {}) as Record<string, unknown>,
+    )) {
+      if (child && typeof child === "object" && Object.keys(child).length === 0) continue;
+      visit(child, `${path}.[${key}]`, true);
+    }
+    for (const keyword of ["anyOf", "oneOf", "allOf"]) {
+      for (const [index, child] of ((node[keyword] ?? []) as unknown[]).entries()) {
+        visit(child, `${path}.${keyword}[${index}]`, allowOpaque);
+      }
+    }
+  }
+  visit(schema, "arguments");
+}
+
+/** Only raw contract preflight errors, never downstream provider or storage exceptions. */
+function inputIssues(issues: readonly z.core.$ZodIssue[]): z.core.$ZodIssueCustom[] {
+  const result: z.core.$ZodIssueCustom[] = [];
+  for (const issue of issues.slice(0, 8)) {
+    const path = [...issue.path];
+    let message: string;
+    if (issue.code === "invalid_type") message = `expected ${issue.expected}`;
+    else if (issue.code === "invalid_value")
+      message = `allowed values: ${JSON.stringify(issue.values)}`;
+    else if (issue.code === "invalid_union" && issue.errors.length === 0 && issue.discriminator) {
+      if (path.at(-1) !== issue.discriminator) path.push(issue.discriminator);
+      message = `allowed values: ${JSON.stringify("options" in issue ? issue.options : [])}`;
+    } else if (issue.code === "invalid_union") {
+      // These are alternatives, never cumulative requirements.
+      message = "does not match any of the declared alternative input formats";
+    } else if (issue.code === "unrecognized_keys")
+      message = `fields not declared by this tool: ${JSON.stringify(issue.keys)}`;
+    else if (issue.code === "too_small") message = `must meet minimum ${issue.minimum}`;
+    else if (issue.code === "too_big") message = `must meet maximum ${issue.maximum}`;
+    else message = issue.message;
+    result.push({ code: "custom", path, message });
+  }
+  if (issues.length > 8) {
+    result.push({
+      code: "custom",
+      path: [],
+      message: `${issues.length - 8} additional input problems`,
+    });
+  }
+  return result;
+}

package/src/mcp/documents.ts

@@ -1,4 +1,5 @@
 import { searchKnowledgeEntries } from "@opengeni/core";
+import type { Settings } from "@opengeni/config";
 import { KnowledgeEntryListRequest } from "@opengeni/contracts";
 import type { DocumentServices } from "@opengeni/documents";
 import {
@@ -17,7 +18,7 @@ export function buildDocumentsMcpServer(
   accountId: string,
   workspaceId: string,
   documentServices: DocumentServices,
-  options: { knowledge: KnowledgeContext },
+  options: { knowledge: KnowledgeContext; settings?: Settings },
 ): McpServer {
   const context = options.knowledge;
   if (context.accountId !== accountId || context.workspaceId !== workspaceId)
@@ -39,7 +40,13 @@ export function buildDocumentsMcpServer(
         {
           type: "text",
           text: JSON.stringify(
-            await searchKnowledgeEntries(db, context, input, () => documentServices.embedder),
+            await searchKnowledgeEntries(
+              db,
+              context,
+              input,
+              () => documentServices.embedder,
+              options.settings,
+            ),
           ),
         },
       ],

package/src/mcp/editable-artifacts.ts

@@ -19,6 +19,7 @@ import * as z from "zod/v4";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { editableArtifactActorForGrant } from "../routes/editable-artifacts";
 import { EditableArtifactQueryRequestSchema } from "./editable-artifact-query-schema";
+import { siteAgentEditableArtifactRefusal } from "./site-agent-clamp-tools";
 
 const ArtifactId = z
   .string()
@@ -32,12 +33,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"]),
@@ -100,6 +102,13 @@ export function registerEditableArtifactAgentTools(
     await input.authorize();
     return jsonResult(await operation());
   };
+  /** Writes: an agent started from a Site page edits only what the Site declared. */
+  const executeWrite = async <T>(operation: () => Promise<T>, artifactId?: string) => {
+    await input.authorize();
+    const refused = await siteAgentEditableArtifactRefusal(input.deps, input.grant, artifactId);
+    if (refused) return refused;
+    return jsonResult(await operation());
+  };
 
   input.server.registerTool(
     "editable_artifact_list",
@@ -135,7 +144,7 @@ export function registerEditableArtifactAgentTools(
     },
     async ({ modality, title }, extra) => {
       const invocation = context("editable_artifact_create", extra);
-      return await execute(
+      return await executeWrite(
         async () =>
           await application().create({
             ...invocation,
@@ -164,7 +173,7 @@ export function registerEditableArtifactAgentTools(
     },
     async ({ fileId, modality, title }, extra) => {
       const invocation = context("editable_artifact_import", extra);
-      return await execute(
+      return await executeWrite(
         async () =>
           await application().import({
             ...invocation,
@@ -203,13 +212,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) =>
@@ -244,7 +257,7 @@ export function registerEditableArtifactAgentTools(
     },
     async ({ artifactId, modality, expectedHeadSequence, expectedStateHash, commands }, extra) => {
       const invocation = context("editable_artifact_apply", extra);
-      return await execute(
+      return await executeWrite(
         async () =>
           await application().apply({
             ...invocation,
@@ -254,6 +267,7 @@ export function registerEditableArtifactAgentTools(
             expectedStateHash,
             batch: { modality, commands } as EditableArtifactAgentCommandBatch,
           }),
+        artifactId,
       );
     },
   );
@@ -262,11 +276,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: {
@@ -281,7 +296,8 @@ export function registerEditableArtifactAgentTools(
     },
     async ({ artifactId, format, options }, extra) => {
       const invocation = context("editable_artifact_export", extra);
-      return await execute(
+      // HTTP refuses the matching materialization for the same agent.
+      return await executeWrite(
         async () =>
           await application().startExport({
             ...invocation,
@@ -291,6 +307,7 @@ export function registerEditableArtifactAgentTools(
             ...(options ? { options } : {}),
             signal: extra.signal,
           }),
+        artifactId,
       );
     },
   );
@@ -319,7 +336,7 @@ export function registerEditableArtifactAgentTools(
       annotations: mutationAnnotations("Get artifact export", { idempotent: true }),
     },
     async ({ artifactId, versionId, jobId }, extra) =>
-      await execute(
+      await executeWrite(
         async () =>
           await application().exportStatus({
             ...context("editable_artifact_export_status", extra),
@@ -328,6 +345,7 @@ export function registerEditableArtifactAgentTools(
             jobId,
             signal: extra.signal,
           }),
+        artifactId,
       ),
   );
 }

package/src/mcp/files.ts

@@ -9,6 +9,7 @@ import {
 } 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(
@@ -63,7 +64,10 @@ export function buildFilesMcpServer(
         if (file.status !== "ready") {
           throw new Error(`file is ${file.status}`);
         }
-        const signed = await deps.objectStorage.createGetUrl({ key: file.objectKey });
+        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, {