@opengeni/contracts 0.39.0 → 0.44.1

package/src/mcp-receipts.ts

@@ -0,0 +1,281 @@
+import { z } from "zod";
+
+/**
+ * Versioned, provider-neutral receipt returned by first-party MCP mutation tools.
+ *
+ * A receipt intentionally contains only server-generated identity and outcome
+ * facts. Callers already have mutation inputs in their tool-call history, so
+ * copying names, prompts, instructions, commands, evidence, or other request
+ * fields into the result wastes context and can expose data twice.
+ */
+export const MCP_MUTATION_RECEIPT_VERSION = "mcp-mutation-receipt.v1" as const;
+export const MCP_MUTATION_RECEIPT_MAX_BYTES = 64 * 1024;
+
+const utf8ByteLength = (value: string): number => new TextEncoder().encode(value).byteLength;
+
+function boundedUtf8String(maxBytes: number, minLength = 0) {
+  return z
+    .string()
+    .min(minLength)
+    .max(maxBytes)
+    .superRefine((value, context) => {
+      if (utf8ByteLength(value) > maxBytes) {
+        context.addIssue({
+          code: "custom",
+          message: `string must contain at most ${maxBytes} UTF-8 bytes`,
+        });
+      }
+    });
+}
+
+export const McpMutationReceiptOutcome = 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 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 type McpMutationResource = z.infer<typeof McpMutationResource>;
+
+const McpMutationReceiptFact = z.union([
+  boundedUtf8String(512),
+  z.number().finite(),
+  z.boolean(),
+  z.null(),
+]);
+
+const McpMutationReceiptFacts = 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) => {
+    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) {
+          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: ["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.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: ["updateId"],
+          message: "session_steer updateId must equal resource.id",
+        });
+      }
+    } 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) {
+        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: "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) {
+        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) {
+        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: ["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/memory-slack-delivery.ts

@@ -0,0 +1,183 @@
+import { z } from "zod";
+
+export const MemorySlackImportance = z.enum(["major", "normal", "minor"]);
+export type MemorySlackImportance = z.infer<typeof MemorySlackImportance>;
+
+export const MemorySlackRequestedMode = z.enum(["auto", "review", "never"]);
+export type MemorySlackRequestedMode = z.infer<typeof MemorySlackRequestedMode>;
+
+export const MemorySlackPublicationDistribution = z
+  .object({
+    importance: MemorySlackImportance,
+    audience: z.literal("workspace"),
+    slackMode: MemorySlackRequestedMode,
+    shareSummary: z.string().trim().min(1).max(4_096),
+  })
+  .strict();
+export type MemorySlackPublicationDistribution = z.infer<typeof MemorySlackPublicationDistribution>;
+
+export const MemorySlackPublicationConfiguration = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  revision: z.number().int().positive(),
+  enabled: z.boolean(),
+  connectionId: z.string().uuid().nullable(),
+  slackTeamId: z.string().min(1).max(64).nullable(),
+  slackChannelId: z.string().min(1).max(64).nullable(),
+  slackChannelName: z.string().min(1).max(256).nullable(),
+  autoImportances: z.array(MemorySlackImportance).max(3),
+  reviewImportances: z.array(MemorySlackImportance).max(3),
+  createdBySubjectId: z.string().min(1).max(1_024),
+  createdAt: z.string(),
+});
+export type MemorySlackPublicationConfiguration = z.infer<
+  typeof MemorySlackPublicationConfiguration
+>;
+
+export const UpdateMemorySlackPublicationConfigurationRequest = z
+  .object({
+    expectedRevision: z.number().int().nonnegative(),
+    enabled: z.boolean(),
+    connectionId: z.string().uuid().nullable(),
+    slackChannelId: z.string().trim().min(1).max(64).nullable(),
+    slackChannelName: z.string().trim().min(1).max(256).nullable(),
+    autoImportances: z.array(MemorySlackImportance).max(3),
+    reviewImportances: z.array(MemorySlackImportance).max(3),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const overlap = value.autoImportances.filter((importance) =>
+      value.reviewImportances.includes(importance),
+    );
+    if (overlap.length > 0) {
+      context.addIssue({
+        code: "custom",
+        message: "auto and review importance policies must not overlap",
+        path: ["reviewImportances"],
+      });
+    }
+    if (value.enabled && (!value.connectionId || !value.slackChannelId)) {
+      context.addIssue({
+        code: "custom",
+        message: "an enabled Slack publication configuration requires a connection and channel",
+      });
+    }
+  });
+export type UpdateMemorySlackPublicationConfigurationRequest = z.infer<
+  typeof UpdateMemorySlackPublicationConfigurationRequest
+>;
+
+export const MemorySlackPublicationConfigurationResponse = z.object({
+  current: MemorySlackPublicationConfiguration.nullable(),
+  history: z.array(MemorySlackPublicationConfiguration).max(100),
+});
+export type MemorySlackPublicationConfigurationResponse = z.infer<
+  typeof MemorySlackPublicationConfigurationResponse
+>;
+
+export const MemorySlackPublicationState = z.enum([
+  "review_pending",
+  "queued",
+  "delivering",
+  "retry_wait",
+  "delivered",
+  "rejected",
+  "failed",
+  "cancelled",
+]);
+export type MemorySlackPublicationState = z.infer<typeof MemorySlackPublicationState>;
+
+export const MemorySlackPublicationReceiptKind = z.enum([
+  "enqueued",
+  "review_approved",
+  "review_rejected",
+  "delivery_claimed",
+  "retry_scheduled",
+  "delivered",
+  "failed",
+  "cancelled",
+  "manual_retry",
+]);
+export type MemorySlackPublicationReceiptKind = z.infer<typeof MemorySlackPublicationReceiptKind>;
+
+export const MemorySlackPublicationReceipt = z.object({
+  id: z.string().uuid(),
+  publicationId: z.string().uuid(),
+  sequence: z.number().int().positive(),
+  kind: MemorySlackPublicationReceiptKind,
+  state: MemorySlackPublicationState,
+  attemptNumber: z.number().int().nonnegative(),
+  actorKind: z.enum(["human", "agent", "service"]),
+  actorSubjectId: z.string().min(1).max(1_024),
+  operationId: z.string().uuid(),
+  errorCode: z.string().min(1).max(128).nullable(),
+  retryAt: z.string().nullable(),
+  slackChannelId: z.string().min(1).max(64).nullable(),
+  slackMessageTimestamp: z.string().min(1).max(64).nullable(),
+  createdAt: z.string(),
+});
+export type MemorySlackPublicationReceipt = z.infer<typeof MemorySlackPublicationReceipt>;
+
+export const MemorySlackPublication = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  configurationRevision: z.number().int().positive(),
+  connectionId: z.string().uuid(),
+  slackTeamId: z.string().min(1).max(64),
+  slackChannelId: z.string().min(1).max(64),
+  sourceType: z.enum(["workspace_memory", "durable_learning"]),
+  sourceId: z.string().min(1).max(1_024),
+  sourceVersion: z.string().min(1).max(512).nullable(),
+  importance: MemorySlackImportance,
+  deliveryMode: z.enum(["auto", "review"]),
+  state: MemorySlackPublicationState,
+  summary: z.string().max(512),
+  sourceLabel: z.string().max(128),
+  authoritativePath: z.string().max(2_048).nullable(),
+  initiatorKind: z.enum(["human", "agent", "service"]),
+  initiatorSubjectId: z.string().min(1).max(1_024),
+  initiatingHumanSubjectId: z.string().min(1).max(1_024).nullable(),
+  attemptCount: z.number().int().nonnegative(),
+  retryAt: z.string().nullable(),
+  lastErrorCode: z.string().min(1).max(128).nullable(),
+  slackMessageTimestamp: z.string().min(1).max(64).nullable(),
+  deliveredAt: z.string().nullable(),
+  terminalAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  receipts: z.array(MemorySlackPublicationReceipt).max(100),
+});
+export type MemorySlackPublication = z.infer<typeof MemorySlackPublication>;
+
+export const MemorySlackPublicationHistoryResponse = z.object({
+  publications: z.array(MemorySlackPublication).max(100),
+  nextCursor: z.string().uuid().nullable(),
+});
+export type MemorySlackPublicationHistoryResponse = z.infer<
+  typeof MemorySlackPublicationHistoryResponse
+>;
+
+export const MemorySlackPublicationActionRequest = z
+  .object({
+    action: z.enum(["approve", "reject", "retry"]),
+    expectedState: MemorySlackPublicationState,
+  })
+  .strict();
+export type MemorySlackPublicationActionRequest = z.infer<
+  typeof MemorySlackPublicationActionRequest
+>;
+
+export const SlackPublicationChannel = z.object({
+  id: z.string().min(1).max(64),
+  name: z.string().min(1).max(256).nullable(),
+  isPrivate: z.boolean(),
+});
+export type SlackPublicationChannel = z.infer<typeof SlackPublicationChannel>;
+
+export const SlackPublicationChannelListResponse = z.object({
+  channels: z.array(SlackPublicationChannel).max(200),
+  nextCursor: z.string().max(1_024).nullable(),
+});
+export type SlackPublicationChannelListResponse = z.infer<
+  typeof SlackPublicationChannelListResponse
+>;