@opengeni/contracts 0.38.3 → 0.40.0

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/retained-output.ts

@@ -7,17 +7,30 @@ export const RETAINED_OUTPUT_DEFAULT_PAGE_BYTES = 256 * 1024;
 /** Receipts are timeline references, never an extensible metadata bag. */
 export const RETAINED_OUTPUT_RECEIPT_MAX_BYTES = 2 * 1024;
 
+/** Screenshot bytes are accounted separately from the 10k-token text policy. */
+export const COMPUTER_SCREENSHOT_MAX_BYTES = 32 * 1024 * 1024;
+export const COMPUTER_SCREENSHOT_MAX_DIMENSION = 16_384;
+export const COMPUTER_SCREENSHOT_MAX_PIXELS = 67_108_864;
+/** Canonical ready-object retention window: 30 days from successful settlement. */
+export const COMPUTER_SCREENSHOT_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
+/** Hard workspace reservation across pending + ready screenshot artifacts. */
+export const COMPUTER_SCREENSHOT_WORKSPACE_QUOTA_BYTES = 5 * 1024 * 1024 * 1024;
+
 const encoder = new TextEncoder();
 const LOWERCASE_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const LOWERCASE_SHA256 = /^[0-9a-f]{64}$/;
 const CANONICAL_MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,62}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,62}$/;
-const RETRIEVAL_PATH = /^\/v1\/workspaces\/([0-9a-f-]+)\/artifacts\/([0-9a-f-]+)\/content$/;
+const WORKSPACE_RETRIEVAL_PATH =
+  /^\/v1\/workspaces\/([0-9a-f-]+)\/artifacts\/([0-9a-f-]+)\/content$/;
+const SESSION_RETRIEVAL_PATH =
+  /^\/v1\/workspaces\/([0-9a-f-]+)\/sessions\/([0-9a-f-]+)\/artifacts\/([0-9a-f-]+)\/content$/;
 
 export const RetainedOutputKind = z.enum([
   "tool_result",
   "assistant_completion",
   "internal_update",
   "event_media",
+  "computer_screenshot",
   "file",
 ]);
 export type RetainedOutputKind = z.infer<typeof RetainedOutputKind>;
@@ -30,6 +43,9 @@ export const RetainedOutputUnavailableReason = z.enum([
   "deleted",
   "missing_storage",
   "storage_write_failed",
+  "quota_exceeded",
+  "invalid_content",
+  "oversized",
   "unsupported",
 ]);
 export type RetainedOutputUnavailableReason = z.infer<typeof RetainedOutputUnavailableReason>;
@@ -50,12 +66,27 @@ export const RetainedArtifactReferenceSchema = z
     originalBytes: z.number().int().nonnegative().safe(),
     sha256: z.string().regex(LOWERCASE_SHA256),
     retainedAt: z.string().datetime({ offset: true }),
-    retention: z
+    dimensions: z
       .object({
-        policy: z.literal("workspace_file"),
-        expiresAt: z.null(),
+        width: z.number().int().positive().max(COMPUTER_SCREENSHOT_MAX_DIMENSION),
+        height: z.number().int().positive().max(COMPUTER_SCREENSHOT_MAX_DIMENSION),
       })
-      .strict(),
+      .strict()
+      .optional(),
+    retention: z.union([
+      z
+        .object({
+          policy: z.literal("workspace_file"),
+          expiresAt: z.null(),
+        })
+        .strict(),
+      z
+        .object({
+          policy: z.literal("session_screenshot"),
+          expiresAt: z.string().datetime({ offset: true }),
+        })
+        .strict(),
+    ]),
     retrieval: z
       .object({
         method: z.literal("GET"),
@@ -67,15 +98,41 @@ export const RetainedArtifactReferenceSchema = z
   })
   .strict()
   .superRefine((value, ctx) => {
-    const match = RETRIEVAL_PATH.exec(value.retrieval.path);
-    if (!match || !LOWERCASE_UUID.test(match[1] ?? "") || match[2] !== value.artifactId) {
+    const workspaceMatch = WORKSPACE_RETRIEVAL_PATH.exec(value.retrieval.path);
+    const sessionMatch = SESSION_RETRIEVAL_PATH.exec(value.retrieval.path);
+    const workspaceId = workspaceMatch?.[1] ?? sessionMatch?.[1];
+    const sessionId = sessionMatch?.[2];
+    const artifactId = workspaceMatch?.[2] ?? sessionMatch?.[3];
+    if (
+      !workspaceId ||
+      !LOWERCASE_UUID.test(workspaceId) ||
+      (sessionId !== undefined && !LOWERCASE_UUID.test(sessionId)) ||
+      artifactId !== value.artifactId
+    ) {
       ctx.addIssue({
         code: "custom",
         path: ["retrieval", "path"],
-        message: "retrieval path must be a workspace API content path for this artifact",
+        message: "retrieval path must be a workspace/session API content path for this artifact",
       });
     }
 
+    if (value.kind === "computer_screenshot") {
+      if (!value.dimensions) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["dimensions"],
+          message: "computer screenshot receipts require exact dimensions",
+        });
+      }
+      if (value.retention.policy !== "session_screenshot" || !sessionMatch) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["retention"],
+          message: "computer screenshots require session-scoped expiring retrieval",
+        });
+      }
+    }
+
     if (encoder.encode(JSON.stringify(value)).byteLength > RETAINED_OUTPUT_RECEIPT_MAX_BYTES) {
       ctx.addIssue({
         code: "custom",
@@ -126,6 +183,13 @@ export type RetainedArtifactFileInput = {
   updatedAt: string;
 };
 
+export type RetainedScreenshotArtifactInput = RetainedArtifactFileInput & {
+  sessionId: string;
+  width: number;
+  height: number;
+  expiresAt: string;
+};
+
 /**
  * Convert a ready, integrity-addressed workspace file into the only available
  * retained-output receipt shape. Invalid, pending, or checksum-less files fail
@@ -159,6 +223,35 @@ export function retainedArtifactReferenceFromFile(
   return parsed.success ? parsed.data : null;
 }
 
+/** Build the closed, session-scoped receipt for one ready screenshot file. */
+export function retainedScreenshotReferenceFromFile(
+  file: RetainedScreenshotArtifactInput,
+): RetainedArtifactReference | null {
+  if (file.status !== "ready" || !file.sha256 || file.sizeBytes <= 0) return null;
+  const value = {
+    available: true as const,
+    artifactId: file.id,
+    kind: "computer_screenshot" as const,
+    contentType: canonicalRetainedContentType(file.contentType),
+    originalBytes: file.sizeBytes,
+    sha256: file.sha256,
+    retainedAt: file.updatedAt,
+    dimensions: { width: file.width, height: file.height },
+    retention: {
+      policy: "session_screenshot" as const,
+      expiresAt: file.expiresAt,
+    },
+    retrieval: {
+      method: "GET" as const,
+      path: `/v1/workspaces/${file.workspaceId}/sessions/${file.sessionId}/artifacts/${file.id}/content`,
+      acceptRanges: "bytes" as const,
+      maxRangeBytes: RETAINED_OUTPUT_MAX_PAGE_BYTES,
+    },
+  };
+  const parsed = RetainedArtifactReferenceSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
 function canonicalRetainedContentType(value: string): string {
   const mediaType = value.split(";", 1)[0]?.trim().toLowerCase() ?? "";
   return CANONICAL_MEDIA_TYPE.test(mediaType) ? mediaType : "application/octet-stream";

package/src/transcription-recordings.ts

@@ -0,0 +1,169 @@
+import { z } from "zod";
+
+export const TranscriptionRecordingErrorCode = z.enum([
+  "permission_denied",
+  "not_supported",
+  "network",
+  "provider",
+  "policy_blocked",
+  "timeout",
+  "cancelled",
+  "unavailable",
+  "too_large",
+  "invalid_audio",
+  "unknown",
+]);
+export type TranscriptionRecordingErrorCode = z.infer<typeof TranscriptionRecordingErrorCode>;
+
+export const TranscriptionRecordingState = z.enum([
+  "uploading",
+  "segmenting",
+  "ready",
+  "transcribing",
+  "complete",
+  "failed",
+  "discarded",
+]);
+export type TranscriptionRecordingState = z.infer<typeof TranscriptionRecordingState>;
+
+export const TranscriptionRecordingSegmentState = z.enum([
+  "preparing",
+  "pending",
+  "transcribing",
+  "complete",
+  "failed",
+]);
+export type TranscriptionRecordingSegmentState = z.infer<typeof TranscriptionRecordingSegmentState>;
+
+export const ClientResumableVoiceInputConfig = z
+  .object({
+    maxDurationSeconds: z
+      .number()
+      .int()
+      .positive()
+      .max(8 * 60 * 60),
+    maxSizeBytes: z
+      .number()
+      .int()
+      .positive()
+      .max(512 * 1024 * 1024),
+    maxChunkSizeBytes: z
+      .number()
+      .int()
+      .positive()
+      .max(25 * 1024 * 1024),
+    providerSegmentSeconds: z.number().int().positive().max(600),
+  })
+  .strict();
+export type ClientResumableVoiceInputConfig = z.infer<typeof ClientResumableVoiceInputConfig>;
+
+export const CreateTranscriptionRecordingRequest = z
+  .object({
+    recordingId: z.string().uuid(),
+    mimeType: z.string().trim().min(1).max(128),
+  })
+  .strict();
+export type CreateTranscriptionRecordingRequest = z.infer<
+  typeof CreateTranscriptionRecordingRequest
+>;
+
+export const FinalizeTranscriptionRecordingRequest = z
+  .object({
+    chunkCount: z.number().int().positive().max(100_000),
+    totalBytes: z
+      .number()
+      .int()
+      .positive()
+      .max(512 * 1024 * 1024),
+    totalDurationMilliseconds: z
+      .number()
+      .int()
+      .positive()
+      .max(8 * 60 * 60 * 1_000),
+  })
+  .strict();
+export type FinalizeTranscriptionRecordingRequest = z.infer<
+  typeof FinalizeTranscriptionRecordingRequest
+>;
+
+export const TranscriptionRecordingChunk = z
+  .object({
+    chunkNumber: z.number().int().nonnegative(),
+    byteLength: z.number().int().positive(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    startMilliseconds: z.number().int().nonnegative(),
+    durationMilliseconds: z.number().int().nonnegative(),
+    deduplicated: z.boolean(),
+  })
+  .strict();
+export type TranscriptionRecordingChunk = z.infer<typeof TranscriptionRecordingChunk>;
+
+export const TranscriptionRecordingSegment = z
+  .object({
+    segmentNumber: z.number().int().nonnegative(),
+    state: TranscriptionRecordingSegmentState,
+    startMilliseconds: z.number().int().nonnegative(),
+    durationMilliseconds: z.number().int().positive(),
+    byteLength: z.number().int().positive(),
+    errorCode: TranscriptionRecordingErrorCode.nullable(),
+    retryable: z.boolean(),
+  })
+  .strict();
+export type TranscriptionRecordingSegment = z.infer<typeof TranscriptionRecordingSegment>;
+
+export const TranscriptionRecording = z
+  .object({
+    id: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    mimeType: z.string().trim().min(1).max(128),
+    state: TranscriptionRecordingState,
+    nextChunkNumber: z.number().int().nonnegative(),
+    chunkCount: z.number().int().nonnegative(),
+    totalBytes: z.number().int().nonnegative(),
+    totalDurationMilliseconds: z.number().int().nonnegative(),
+    segmentCount: z.number().int().nonnegative(),
+    completedSegmentCount: z.number().int().nonnegative(),
+    transcriptText: z.string().max(1_000_000).nullable(),
+    languages: z.array(z.string().trim().min(1).max(64)).max(64),
+    errorCode: TranscriptionRecordingErrorCode.nullable(),
+    retryable: z.boolean(),
+    objectsCleaned: z.boolean(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    expiresAt: z.string().datetime(),
+  })
+  .strict();
+export type TranscriptionRecording = z.infer<typeof TranscriptionRecording>;
+
+export const TranscriptionRecordingResponse = z
+  .object({
+    recording: TranscriptionRecording,
+    segments: z.array(TranscriptionRecordingSegment).max(1_000),
+    retryAfterMilliseconds: z.number().int().positive().max(60_000).optional(),
+  })
+  .strict();
+export type TranscriptionRecordingResponse = z.infer<typeof TranscriptionRecordingResponse>;
+
+export const TranscriptionRecordingListResponse = z
+  .object({
+    recordings: z.array(TranscriptionRecording).max(50),
+  })
+  .strict();
+export type TranscriptionRecordingListResponse = z.infer<typeof TranscriptionRecordingListResponse>;
+
+export const UploadTranscriptionRecordingChunkResponse = z
+  .object({
+    recording: TranscriptionRecording,
+    chunk: TranscriptionRecordingChunk,
+  })
+  .strict();
+export type UploadTranscriptionRecordingChunkResponse = z.infer<
+  typeof UploadTranscriptionRecordingChunkResponse
+>;
+
+export const TRANSCRIPTION_RECORDING_MAX_DURATION_SECONDS = 2 * 60 * 60;
+export const TRANSCRIPTION_RECORDING_MAX_SIZE_BYTES = 512 * 1024 * 1024;
+export const TRANSCRIPTION_RECORDING_MAX_CHUNK_SIZE_BYTES = 8 * 1024 * 1024;
+export const TRANSCRIPTION_RECORDING_PROVIDER_SEGMENT_SECONDS = 50;
+export const TRANSCRIPTION_RECORDING_RECOVERY_RETRY_AFTER_MILLISECONDS = 5_000;
+export const TRANSCRIPTION_RECORDING_RETENTION_SECONDS = 24 * 60 * 60;