@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/mcp-receipts.ts

@@ -1,3 +1,4 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 /**
@@ -28,254 +29,253 @@ function boundedUtf8String(maxBytes: number, minLength = 0) {
     });
 }
 
-export const McpMutationReceiptOutcome = z.enum([
-  "created",
-  "updated",
-  "deleted",
-  "unchanged",
-  "accepted",
-  "triggered",
-  "repaired",
-  "replayed",
-  "partial_failure",
-]);
+export const McpMutationReceiptOutcome = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "created",
+    "updated",
+    "deleted",
+    "unchanged",
+    "accepted",
+    "triggered",
+    "repaired",
+    "replayed",
+    "partial_failure",
+  ]),
+);
 export type McpMutationReceiptOutcome = z.infer<typeof McpMutationReceiptOutcome>;
 
-export const McpMutationReceiptIdempotencyStatus = z.enum([
-  "not_supported",
-  "not_requested",
-  "applied",
-  "replayed",
-  "unknown",
-]);
+export const McpMutationReceiptIdempotencyStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["not_supported", "not_requested", "applied", "replayed", "unknown"]),
+);
 export type McpMutationReceiptIdempotencyStatus = z.infer<
   typeof McpMutationReceiptIdempotencyStatus
 >;
 
-export const McpMutationResource = z
-  .object({
-    type: boundedUtf8String(128, 1),
-    id: boundedUtf8String(256, 1),
-    version: z.union([z.number().int().nonnegative(), boundedUtf8String(128, 1)]).optional(),
-    etag: boundedUtf8String(512, 1).optional(),
-    state: boundedUtf8String(128, 1).optional(),
-  })
-  .strict();
+export const McpMutationResource = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      type: boundedUtf8String(128, 1),
+      id: boundedUtf8String(256, 1),
+      version: z.union([z.number().int().nonnegative(), boundedUtf8String(128, 1)]).optional(),
+      etag: boundedUtf8String(512, 1).optional(),
+      state: boundedUtf8String(128, 1).optional(),
+    })
+    .strict(),
+);
 export type McpMutationResource = z.infer<typeof McpMutationResource>;
 
-const McpMutationReceiptFact = z.union([
-  boundedUtf8String(512),
-  z.number().finite(),
-  z.boolean(),
-  z.null(),
-]);
+const McpMutationReceiptFact = /* @__PURE__ */ defineSchema(() =>
+  z.union([boundedUtf8String(512), z.number().finite(), z.boolean(), z.null()]),
+);
 
-const McpMutationReceiptFacts = z
-  .record(boundedUtf8String(64, 1), McpMutationReceiptFact)
-  .superRefine((value, context) => {
+const McpMutationReceiptFacts = /* @__PURE__ */ defineSchema(() =>
+  z.record(boundedUtf8String(64, 1), McpMutationReceiptFact).superRefine((value, context) => {
     if (Object.keys(value).length > 16) {
       context.addIssue({
         code: "custom",
         message: "receipt facts may contain at most 16 scalar entries",
       });
     }
-  });
+  }),
+);
 
-const McpMutationReceiptNextActionArguments = z
-  .record(boundedUtf8String(64, 1), McpMutationReceiptFact)
-  .superRefine((value, context) => {
+const McpMutationReceiptNextActionArguments = /* @__PURE__ */ defineSchema(() =>
+  z.record(boundedUtf8String(64, 1), McpMutationReceiptFact).superRefine((value, context) => {
     if (Object.keys(value).length > 8) {
       context.addIssue({
         code: "custom",
         message: "receipt nextAction arguments may contain at most 8 scalar entries",
       });
     }
-  });
+  }),
+);
 
-export const McpMutationReceipt = z
-  .object({
-    receiptVersion: z.literal(MCP_MUTATION_RECEIPT_VERSION),
-    operation: boundedUtf8String(128, 1),
-    // v1 receipts describe committed truth only. Validation/auth/conflict and
-    // fully compensated failures remain MCP errors rather than success-shaped
-    // committed=false results.
-    committed: z.literal(true),
-    outcome: McpMutationReceiptOutcome,
-    changed: z.boolean(),
-    resource: McpMutationResource,
-    relatedResources: z.array(McpMutationResource).max(8).optional(),
-    timestamp: z.string().datetime({ offset: true }),
-    idempotency: z
-      .object({
-        status: McpMutationReceiptIdempotencyStatus,
-      })
-      .strict(),
-    partialFailure: z
-      .object({
-        stage: boundedUtf8String(128, 1),
-        retryable: z.boolean(),
-      })
-      .strict()
-      .optional(),
-    warnings: z.array(boundedUtf8String(512, 1)).max(20),
-    nextAction: z
-      .object({
-        tool: boundedUtf8String(128, 1),
-        arguments: McpMutationReceiptNextActionArguments,
-      })
-      .strict()
-      .optional(),
-    /** Operation-specific outcome facts. Values are deliberately bounded scalars. */
-    facts: McpMutationReceiptFacts.optional(),
-    /**
-     * Bounded session_create compatibility aliases. Existing orchestration
-     * consumers use these server-authored lineage facts to spawn descendants
-     * without fetching the full session entity.
-     */
-    id: boundedUtf8String(256, 1).optional(),
-    rootSessionId: boundedUtf8String(256, 1).optional(),
-    nestedAgentDepth: z.number().int().nonnegative().optional(),
-    effectiveMaxNestedAgentDepth: z.number().int().nonnegative().optional(),
-    /** Bounded session_steer compatibility alias for resource.id. */
-    updateId: boundedUtf8String(256, 1).optional(),
-  })
-  .strict()
-  .superRefine((receipt, context) => {
-    const sessionCreateCompatibility = [
-      ["id", receipt.id],
-      ["rootSessionId", receipt.rootSessionId],
-      ["nestedAgentDepth", receipt.nestedAgentDepth],
-      ["effectiveMaxNestedAgentDepth", receipt.effectiveMaxNestedAgentDepth],
-    ] as const;
-    if (receipt.operation === "session_create") {
-      for (const [field, value] of sessionCreateCompatibility) {
-        if (value === undefined) {
+export const McpMutationReceipt = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      receiptVersion: z.literal(MCP_MUTATION_RECEIPT_VERSION),
+      operation: boundedUtf8String(128, 1),
+      // v1 receipts describe committed truth only. Validation/auth/conflict and
+      // fully compensated failures remain MCP errors rather than success-shaped
+      // committed=false results.
+      committed: z.literal(true),
+      outcome: McpMutationReceiptOutcome,
+      changed: z.boolean(),
+      resource: McpMutationResource,
+      relatedResources: z.array(McpMutationResource).max(8).optional(),
+      timestamp: z.string().datetime({ offset: true }),
+      idempotency: z
+        .object({
+          status: McpMutationReceiptIdempotencyStatus,
+        })
+        .strict(),
+      partialFailure: z
+        .object({
+          stage: boundedUtf8String(128, 1),
+          retryable: z.boolean(),
+        })
+        .strict()
+        .optional(),
+      warnings: z.array(boundedUtf8String(512, 1)).max(20),
+      nextAction: z
+        .object({
+          tool: boundedUtf8String(128, 1),
+          arguments: McpMutationReceiptNextActionArguments,
+        })
+        .strict()
+        .optional(),
+      /** Operation-specific outcome facts. Values are deliberately bounded scalars. */
+      facts: McpMutationReceiptFacts.optional(),
+      /**
+       * Bounded session_create compatibility aliases. Existing orchestration
+       * consumers use these server-authored lineage facts to spawn descendants
+       * without fetching the full session entity.
+       */
+      id: boundedUtf8String(256, 1).optional(),
+      rootSessionId: boundedUtf8String(256, 1).optional(),
+      nestedAgentDepth: z.number().int().nonnegative().optional(),
+      effectiveMaxNestedAgentDepth: z.number().int().nonnegative().optional(),
+      /** Bounded session_steer compatibility alias for resource.id. */
+      updateId: boundedUtf8String(256, 1).optional(),
+    })
+    .strict()
+    .superRefine((receipt, context) => {
+      const sessionCreateCompatibility = [
+        ["id", receipt.id],
+        ["rootSessionId", receipt.rootSessionId],
+        ["nestedAgentDepth", receipt.nestedAgentDepth],
+        ["effectiveMaxNestedAgentDepth", receipt.effectiveMaxNestedAgentDepth],
+      ] as const;
+      if (receipt.operation === "session_create") {
+        for (const [field, value] of sessionCreateCompatibility) {
+          if (value === undefined) {
+            context.addIssue({
+              code: "custom",
+              path: [field],
+              message: `session_create receipts require ${field}`,
+            });
+          }
+        }
+        if (receipt.id !== undefined && receipt.id !== receipt.resource.id) {
           context.addIssue({
             code: "custom",
-            path: [field],
-            message: `session_create receipts require ${field}`,
+            path: ["id"],
+            message: "session_create id must equal resource.id",
           });
         }
+      } else {
+        for (const [field, value] of sessionCreateCompatibility) {
+          if (value !== undefined) {
+            context.addIssue({
+              code: "custom",
+              path: [field],
+              message: `${field} is only valid for session_create receipts`,
+            });
+          }
+        }
       }
-      if (receipt.id !== undefined && receipt.id !== receipt.resource.id) {
-        context.addIssue({
-          code: "custom",
-          path: ["id"],
-          message: "session_create id must equal resource.id",
-        });
-      }
-    } else {
-      for (const [field, value] of sessionCreateCompatibility) {
-        if (value !== undefined) {
+
+      if (receipt.operation === "session_steer") {
+        if (receipt.updateId === undefined) {
+          context.addIssue({
+            code: "custom",
+            path: ["updateId"],
+            message: "session_steer receipts require updateId",
+          });
+        } else if (receipt.updateId !== receipt.resource.id) {
           context.addIssue({
             code: "custom",
-            path: [field],
-            message: `${field} is only valid for session_create receipts`,
+            path: ["updateId"],
+            message: "session_steer updateId must equal resource.id",
           });
         }
-      }
-    }
-
-    if (receipt.operation === "session_steer") {
-      if (receipt.updateId === undefined) {
+      } else if (receipt.updateId !== undefined) {
         context.addIssue({
           code: "custom",
           path: ["updateId"],
-          message: "session_steer receipts require updateId",
-        });
-      } else if (receipt.updateId !== receipt.resource.id) {
-        context.addIssue({
-          code: "custom",
-          path: ["updateId"],
-          message: "session_steer updateId must equal resource.id",
+          message: "updateId is only valid for session_steer receipts",
         });
       }
-    } else if (receipt.updateId !== undefined) {
-      context.addIssue({
-        code: "custom",
-        path: ["updateId"],
-        message: "updateId is only valid for session_steer receipts",
-      });
-    }
 
-    if (receipt.outcome === "partial_failure") {
-      if (!receipt.committed) {
-        context.addIssue({
-          code: "custom",
-          path: ["committed"],
-          message: "partial-failure receipts describe a committed mutation",
-        });
-      }
-      if (!receipt.partialFailure) {
+      if (receipt.outcome === "partial_failure") {
+        if (!receipt.committed) {
+          context.addIssue({
+            code: "custom",
+            path: ["committed"],
+            message: "partial-failure receipts describe a committed mutation",
+          });
+        }
+        if (!receipt.partialFailure) {
+          context.addIssue({
+            code: "custom",
+            path: ["partialFailure"],
+            message: "partial-failure receipts require stage and retryability",
+          });
+        }
+      } else if (receipt.partialFailure) {
         context.addIssue({
           code: "custom",
           path: ["partialFailure"],
-          message: "partial-failure receipts require stage and retryability",
+          message: "partialFailure is only valid for a partial_failure outcome",
         });
       }
-    } else if (receipt.partialFailure) {
-      context.addIssue({
-        code: "custom",
-        path: ["partialFailure"],
-        message: "partialFailure is only valid for a partial_failure outcome",
-      });
-    }
 
-    if (receipt.outcome === "unchanged" && receipt.changed) {
-      context.addIssue({
-        code: "custom",
-        path: ["changed"],
-        message: "unchanged receipts cannot report changed=true",
-      });
-    }
-    if (receipt.outcome === "repaired") {
-      if (!receipt.changed) {
+      if (receipt.outcome === "unchanged" && receipt.changed) {
         context.addIssue({
           code: "custom",
           path: ["changed"],
-          message: "a repair must report changed=true",
+          message: "unchanged receipts cannot report changed=true",
         });
       }
-      if (receipt.idempotency.status !== "applied") {
-        context.addIssue({
-          code: "custom",
-          path: ["idempotency", "status"],
-          message: "repaired outcomes require idempotency.status=applied",
-        });
+      if (receipt.outcome === "repaired") {
+        if (!receipt.changed) {
+          context.addIssue({
+            code: "custom",
+            path: ["changed"],
+            message: "a repair must report changed=true",
+          });
+        }
+        if (receipt.idempotency.status !== "applied") {
+          context.addIssue({
+            code: "custom",
+            path: ["idempotency", "status"],
+            message: "repaired outcomes require idempotency.status=applied",
+          });
+        }
       }
-    }
-    if (receipt.outcome === "replayed") {
-      if (receipt.changed) {
+      if (receipt.outcome === "replayed") {
+        if (receipt.changed) {
+          context.addIssue({
+            code: "custom",
+            path: ["changed"],
+            message: "a replay does not apply a new mutation",
+          });
+        }
+        if (receipt.idempotency.status !== "replayed") {
+          context.addIssue({
+            code: "custom",
+            path: ["idempotency", "status"],
+            message: "replayed outcomes require idempotency.status=replayed",
+          });
+        }
+      } else if (
+        receipt.idempotency.status === "replayed" &&
+        !(receipt.outcome === "partial_failure" && !receipt.changed)
+      ) {
         context.addIssue({
           code: "custom",
-          path: ["changed"],
-          message: "a replay does not apply a new mutation",
+          path: ["outcome"],
+          message:
+            "idempotency.status=replayed requires a replayed outcome or unchanged partial failure",
         });
       }
-      if (receipt.idempotency.status !== "replayed") {
+
+      if (utf8ByteLength(JSON.stringify(receipt, null, 2)) > MCP_MUTATION_RECEIPT_MAX_BYTES) {
         context.addIssue({
           code: "custom",
-          path: ["idempotency", "status"],
-          message: "replayed outcomes require idempotency.status=replayed",
+          message: `receipt must contain at most ${MCP_MUTATION_RECEIPT_MAX_BYTES} UTF-8 bytes when serialized as pretty JSON`,
         });
       }
-    } else if (
-      receipt.idempotency.status === "replayed" &&
-      !(receipt.outcome === "partial_failure" && !receipt.changed)
-    ) {
-      context.addIssue({
-        code: "custom",
-        path: ["outcome"],
-        message:
-          "idempotency.status=replayed requires a replayed outcome or unchanged partial failure",
-      });
-    }
-
-    if (utf8ByteLength(JSON.stringify(receipt, null, 2)) > MCP_MUTATION_RECEIPT_MAX_BYTES) {
-      context.addIssue({
-        code: "custom",
-        message: `receipt must contain at most ${MCP_MUTATION_RECEIPT_MAX_BYTES} UTF-8 bytes when serialized as pretty JSON`,
-      });
-    }
-  });
+    }),
+);
 export type McpMutationReceipt = z.infer<typeof McpMutationReceipt>;

package/src/mcp-structured-content.ts

@@ -0,0 +1,81 @@
+import type { AttemptToolResult } from "./tool-catalog";
+
+/**
+ * Remove the backwards-compatibility text copy of an MCP result's
+ * `structuredContent`.
+ *
+ * The MCP specification asks a server that returns `structuredContent` to also
+ * return the same value serialized in a text content block. Printing or sending
+ * both pays for the payload twice, and the text copy pays again for JSON string
+ * escaping inside the result envelope.
+ *
+ * The envelope (`content`, `structuredContent`, `_meta`, `isError`, extension
+ * fields) and its key order are kept. Only a plain `{type: "text", text}` block
+ * whose text parses as JSON to a value equal to `structuredContent` is removed.
+ * Prose, differing JSON, annotated text, images, resources, and every other
+ * block stay. A text block whose JSON carries an integer outside the IEEE-754
+ * safe range also stays, because its digits may be more precise than the
+ * parsed `structuredContent`. Numbers compare by IEEE-754 value.
+ *
+ * Results without a removable block are returned as the same object.
+ *
+ * Callers: the runtime's model-facing MCP projection, and the default
+ * `ogtool call` print. The native Connected Machine client implements the
+ * same rule in `agent/crates/opengeni-agent/src/codemode.rs`; keep them equal.
+ */
+export function omitStructuredContentTextDuplicates<T extends AttemptToolResult>(result: T): T {
+  const structured: unknown = result.structuredContent;
+  if (structured === undefined || structured === null) return result;
+  const content = result.content.filter(
+    (entry) => !isPlainTextBlock(entry) || !textDuplicatesStructuredContent(entry.text, structured),
+  );
+  if (content.length === result.content.length) return result;
+  return { ...result, content };
+}
+
+function isPlainTextBlock(entry: unknown): entry is { type: "text"; text: string } {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  const record = entry as Record<string, unknown>;
+  if (record.type !== "text" || typeof record.text !== "string") return false;
+  // Annotations or _meta are block-level facts the structured value lacks.
+  return Object.keys(record).every((key) => key === "type" || key === "text");
+}
+
+function textDuplicatesStructuredContent(text: string, structured: unknown): boolean {
+  const trimmed = text.replace(/^[ \t\n\r]+/u, "");
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return false;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return false;
+  }
+  return !containsUnsafeInteger(parsed) && jsonValuesEqual(parsed, structured);
+}
+
+function containsUnsafeInteger(value: unknown): boolean {
+  if (typeof value === "number") return Number.isInteger(value) && !Number.isSafeInteger(value);
+  if (Array.isArray(value)) return value.some(containsUnsafeInteger);
+  if (value && typeof value === "object") return Object.values(value).some(containsUnsafeInteger);
+  return false;
+}
+
+function jsonValuesEqual(left: unknown, right: unknown): boolean {
+  if (left === right) return true;
+  if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) {
+    return false;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) {
+      return false;
+    }
+    return left.every((entry, index) => jsonValuesEqual(entry, right[index]));
+  }
+  const leftRecord = left as Record<string, unknown>;
+  const rightRecord = right as Record<string, unknown>;
+  const leftKeys = Object.keys(leftRecord);
+  if (leftKeys.length !== Object.keys(rightRecord).length) return false;
+  return leftKeys.every(
+    (key) => Object.hasOwn(rightRecord, key) && jsonValuesEqual(leftRecord[key], rightRecord[key]),
+  );
+}