@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/retained-output.ts

@@ -1,3 +1,5 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 /** Hard server-side ceiling for one retained-output response body. */
@@ -13,8 +15,6 @@ 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;
 /** Generated images are permanent workspace files, never inline history blobs. */
 export const GENERATED_IMAGE_MAX_BYTES = 64 * 1024 * 1024;
 /** Generated videos are permanent workspace files and are always streamed. */
@@ -29,183 +29,193 @@ const WORKSPACE_RETRIEVAL_PATH =
 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",
-  "browser_screenshot",
-  "generated_image",
-  "generated_video",
-  "file",
-]);
+export const RetainedOutputKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "tool_result",
+    "assistant_completion",
+    "internal_update",
+    "event_media",
+    "computer_screenshot",
+    "browser_screenshot",
+    "generated_image",
+    "generated_video",
+    "file",
+  ]),
+);
 export type RetainedOutputKind = z.infer<typeof RetainedOutputKind>;
 
-export const RetainedOutputUnavailableReason = z.enum([
-  "not_retained",
-  "pending",
-  "failed",
-  "expired",
-  "deleted",
-  "missing_storage",
-  "storage_write_failed",
-  "quota_exceeded",
-  "invalid_content",
-  "oversized",
-  "unsupported",
-]);
+export const RetainedOutputUnavailableReason = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "not_retained",
+    "pending",
+    "failed",
+    "expired",
+    "deleted",
+    "missing_storage",
+    "storage_write_failed",
+    "quota_exceeded",
+    "invalid_content",
+    "oversized",
+    "unsupported",
+    // The file exists but is Only me for someone else. Never says whose.
+    "private",
+  ]),
+);
 export type RetainedOutputUnavailableReason = z.infer<typeof RetainedOutputUnavailableReason>;
 
-const RetainedOutputUnavailableEvidenceSchema = z
-  .object({
-    available: z.literal(false),
-    reason: RetainedOutputUnavailableReason,
-  })
-  .strict();
-
-export const RetainedArtifactReferenceSchema = z
-  .object({
-    available: z.literal(true),
-    artifactId: z.string().regex(LOWERCASE_UUID),
-    kind: RetainedOutputKind,
-    contentType: z.string().max(127).regex(CANONICAL_MEDIA_TYPE),
-    originalBytes: z.number().int().nonnegative().safe(),
-    sha256: z.string().regex(LOWERCASE_SHA256),
-    retainedAt: z.string().datetime({ offset: true }),
-    dimensions: z
-      .object({
-        width: z.number().int().positive().max(COMPUTER_SCREENSHOT_MAX_DIMENSION),
-        height: z.number().int().positive().max(COMPUTER_SCREENSHOT_MAX_DIMENSION),
-      })
-      .strict()
-      .optional(),
-    retention: z.union([
-      z
+const RetainedOutputUnavailableEvidenceSchema = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      available: z.literal(false),
+      reason: RetainedOutputUnavailableReason,
+    })
+    .strict(),
+);
+
+export const RetainedArtifactReferenceSchema = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      available: z.literal(true),
+      artifactId: primitives.string.regex(LOWERCASE_UUID),
+      kind: RetainedOutputKind,
+      contentType: z.string().max(127).regex(CANONICAL_MEDIA_TYPE),
+      originalBytes: primitives.nonnegativeInteger.safe(),
+      sha256: primitives.string.regex(LOWERCASE_SHA256),
+      retainedAt: primitives.string.datetime({ offset: true }),
+      dimensions: z
         .object({
-          policy: z.literal("workspace_file"),
-          expiresAt: z.null(),
+          width: primitives.positiveInteger.max(COMPUTER_SCREENSHOT_MAX_DIMENSION),
+          height: primitives.positiveInteger.max(COMPUTER_SCREENSHOT_MAX_DIMENSION),
         })
-        .strict(),
-      z
+        .strict()
+        .optional(),
+      retention: z.union([
+        z
+          .object({
+            policy: z.literal("workspace_file"),
+            expiresAt: z.null(),
+          })
+          .strict(),
+        z
+          .object({
+            policy: z.literal("session_screenshot"),
+            expiresAt: primitives.string.datetime({ offset: true }),
+          })
+          .strict(),
+      ]),
+      retrieval: z
         .object({
-          policy: z.literal("session_screenshot"),
-          expiresAt: z.string().datetime({ offset: true }),
+          method: z.literal("GET"),
+          path: z.string().max(256),
+          acceptRanges: z.literal("bytes"),
+          maxRangeBytes: primitives.positiveInteger.max(RETAINED_OUTPUT_MAX_PAGE_BYTES),
         })
         .strict(),
-    ]),
-    retrieval: z
-      .object({
-        method: z.literal("GET"),
-        path: z.string().max(256),
-        acceptRanges: z.literal("bytes"),
-        maxRangeBytes: z.number().int().positive().max(RETAINED_OUTPUT_MAX_PAGE_BYTES),
-      })
-      .strict(),
-  })
-  .strict()
-  .superRefine((value, ctx) => {
-    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/session API content path for this artifact",
-      });
-    }
-
-    if (
-      value.kind === "computer_screenshot" ||
-      value.kind === "browser_screenshot" ||
-      value.kind === "generated_image" ||
-      value.kind === "generated_video"
-    ) {
-      if (!value.dimensions) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["dimensions"],
-          message: `${value.kind} receipts require exact dimensions`,
-        });
-      } else if (
-        value.dimensions.width * value.dimensions.height >
-        COMPUTER_SCREENSHOT_MAX_PIXELS
+    })
+    .strict()
+    .superRefine((value, ctx) => {
+      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: ["dimensions"],
-          message: `${value.kind} dimensions exceed the pixel limit`,
+          path: ["retrieval", "path"],
+          message: "retrieval path must be a workspace/session API content path for this artifact",
         });
       }
-    }
 
-    if (value.kind === "generated_image") {
-      if (value.retention.policy !== "workspace_file" || !workspaceMatch || sessionMatch) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["retention"],
-          message: "generated images require permanent workspace-file retrieval",
-        });
-      }
       if (
-        !["image/png", "image/jpeg", "image/webp"].includes(value.contentType) ||
-        value.originalBytes <= 0 ||
-        value.originalBytes > GENERATED_IMAGE_MAX_BYTES
+        value.kind === "computer_screenshot" ||
+        value.kind === "browser_screenshot" ||
+        value.kind === "generated_image" ||
+        value.kind === "generated_video"
       ) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["contentType"],
-          message: "generated image media metadata is invalid",
-        });
+        if (!value.dimensions) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["dimensions"],
+            message: `${value.kind} receipts require exact dimensions`,
+          });
+        } else if (
+          value.dimensions.width * value.dimensions.height >
+          COMPUTER_SCREENSHOT_MAX_PIXELS
+        ) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["dimensions"],
+            message: `${value.kind} dimensions exceed the pixel limit`,
+          });
+        }
       }
-    }
 
-    if (value.kind === "generated_video") {
-      if (value.retention.policy !== "workspace_file" || !workspaceMatch || sessionMatch) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["retention"],
-          message: "generated videos require permanent workspace-file retrieval",
-        });
+      if (value.kind === "generated_image") {
+        if (value.retention.policy !== "workspace_file" || !workspaceMatch || sessionMatch) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["retention"],
+            message: "generated images require permanent workspace-file retrieval",
+          });
+        }
+        if (
+          !["image/png", "image/jpeg", "image/webp"].includes(value.contentType) ||
+          value.originalBytes <= 0 ||
+          value.originalBytes > GENERATED_IMAGE_MAX_BYTES
+        ) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["contentType"],
+            message: "generated image media metadata is invalid",
+          });
+        }
       }
-      if (
-        value.contentType !== "video/mp4" ||
-        value.originalBytes <= 0 ||
-        value.originalBytes > GENERATED_VIDEO_MAX_BYTES
-      ) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["contentType"],
-          message: "generated video media metadata is invalid",
-        });
+
+      if (value.kind === "generated_video") {
+        if (value.retention.policy !== "workspace_file" || !workspaceMatch || sessionMatch) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["retention"],
+            message: "generated videos require permanent workspace-file retrieval",
+          });
+        }
+        if (
+          value.contentType !== "video/mp4" ||
+          value.originalBytes <= 0 ||
+          value.originalBytes > GENERATED_VIDEO_MAX_BYTES
+        ) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["contentType"],
+            message: "generated video media metadata is invalid",
+          });
+        }
+      }
+
+      if (value.kind === "computer_screenshot" || value.kind === "browser_screenshot") {
+        if (value.retention.policy !== "session_screenshot" || !sessionMatch) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["retention"],
+            message: "session screenshots require session-scoped expiring retrieval",
+          });
+        }
       }
-    }
 
-    if (value.kind === "computer_screenshot" || value.kind === "browser_screenshot") {
-      if (value.retention.policy !== "session_screenshot" || !sessionMatch) {
+      if (encoder.encode(JSON.stringify(value)).byteLength > RETAINED_OUTPUT_RECEIPT_MAX_BYTES) {
         ctx.addIssue({
           code: "custom",
-          path: ["retention"],
-          message: "session screenshots require session-scoped expiring retrieval",
+          message: "retained-output receipt exceeds its byte envelope",
         });
       }
-    }
-
-    if (encoder.encode(JSON.stringify(value)).byteLength > RETAINED_OUTPUT_RECEIPT_MAX_BYTES) {
-      ctx.addIssue({
-        code: "custom",
-        message: "retained-output receipt exceeds its byte envelope",
-      });
-    }
-  });
+    }),
+);
 
 /**
  * Canonical evidence fact carried by bounded audit/NATS/SSE/UI previews.
@@ -214,29 +224,32 @@ export const RetainedArtifactReferenceSchema = z
  * object key, signed URL, arbitrary metadata, or producer-controlled labels can
  * cross this boundary.
  */
-export const RetainedOutputEvidenceSchema = z.discriminatedUnion("available", [
-  RetainedOutputUnavailableEvidenceSchema,
-  RetainedArtifactReferenceSchema,
-]);
+export const RetainedOutputEvidenceSchema = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("available", [
+    RetainedOutputUnavailableEvidenceSchema,
+    RetainedArtifactReferenceSchema,
+  ]),
+);
 export type RetainedOutputEvidence = z.infer<typeof RetainedOutputEvidenceSchema>;
 export type RetainedArtifactReference = z.infer<typeof RetainedArtifactReferenceSchema>;
 /** @deprecated use RetainedArtifactReference. */
 export type RetainedOutputAvailableEvidence = RetainedArtifactReference;
 
-export const RetainedArtifactUnavailableSchema = z
-  .object({
-    available: z.literal(false),
-    artifactId: z.string().regex(LOWERCASE_UUID),
-    reason: RetainedOutputUnavailableReason,
-  })
-  .strict();
+export const RetainedArtifactUnavailableSchema = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      available: z.literal(false),
+      artifactId: primitives.string.regex(LOWERCASE_UUID),
+      reason: RetainedOutputUnavailableReason,
+    })
+    .strict(),
+);
 export type RetainedArtifactUnavailable = z.infer<typeof RetainedArtifactUnavailableSchema>;
 
 /** Authenticated metadata result for one opaque workspace file identity. */
-export const RetainedArtifactMetadataSchema = z.union([
-  RetainedArtifactReferenceSchema,
-  RetainedArtifactUnavailableSchema,
-]);
+export const RetainedArtifactMetadataSchema = /* @__PURE__ */ defineSchema(() =>
+  z.union([RetainedArtifactReferenceSchema, RetainedArtifactUnavailableSchema]),
+);
 export type RetainedArtifactMetadata = z.infer<typeof RetainedArtifactMetadataSchema>;
 
 export type RetainedArtifactFileInput = {

package/src/sandbox-file-artifacts.ts

@@ -1,73 +1,94 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 import { RetainedArtifactReferenceSchema } from "./retained-output";
+import { WorkspaceArtifactVisibility } from "./artifacts";
+import { FileAccess } from "./file-access";
 
 /**
- * Channel-A currently returns one bounded binary-safe read. Keep publication
+ * Largest publishable sandbox file: one object-storage PUT. Files up to
+ * SANDBOX_FILE_ARTIFACT_INLINE_MAX_BYTES are read through Channel-A; larger
+ * files are hashed and uploaded by the box itself.
+ */
+export const SANDBOX_FILE_ARTIFACT_MAX_BYTES = 5_000_000_000;
+
+/**
+ * Channel-A returns one bounded binary-safe read. Keep inline publication
  * below that ceiling so an extra sentinel byte can distinguish an exact file
  * from a truncated prefix.
  */
-export const SANDBOX_FILE_ARTIFACT_MAX_BYTES = 25 * 1024 * 1024 - 1;
+export const SANDBOX_FILE_ARTIFACT_INLINE_MAX_BYTES = 25 * 1024 * 1024 - 1;
 
-export const PublishSandboxFileArtifactRequest = z
-  .object({
-    path: z.string().min(1).max(4_096),
-  })
-  .strict();
+export const PublishSandboxFileArtifactRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      path: z.string().min(1).max(4_096),
+      /**
+       * Who can open the published file. Omitted: the chat's own audience
+       * (Only me in an Only me chat, else the workspace).
+       */
+      visibility: WorkspaceArtifactVisibility.optional(),
+    })
+    .strict(),
+);
 export type PublishSandboxFileArtifactRequest = z.infer<typeof PublishSandboxFileArtifactRequest>;
 
 /**
  * Closed model/UI receipt for one exact sandbox-file publication. Storage
  * locators and signed URLs never cross this boundary.
  */
-export const SandboxFileArtifactReceipt = z
-  .object({
-    type: z.literal("sandbox_file"),
-    sandboxPath: z.string().min(1).max(4_096),
-    filename: z.string().min(1).max(1_024),
-    artifact: RetainedArtifactReferenceSchema,
-  })
-  .strict()
-  .superRefine((value, context) => {
-    const pathSegments = value.sandboxPath.split("/");
-    // This is a receipt, not read authority. The publisher confines the path
-    // against its resolved provider root; receipts preserve that native path.
-    const unc = value.sandboxPath.startsWith("//");
-    const absolute = unc
-      ? /^\/\/[^/]+\/[^/]+\/.+/u.test(value.sandboxPath) && !value.sandboxPath.startsWith("//?/")
-      : value.sandboxPath.startsWith("/") || /^[A-Z]:\//u.test(value.sandboxPath);
-    if (
-      !absolute ||
-      /[\\\u0000-\u001f\u007f]/u.test(value.sandboxPath) ||
-      pathSegments.some(
-        (segment, index) =>
-          index >= (unc ? 2 : 1) && (!segment || segment === "." || segment === ".."),
-      ) ||
-      pathSegments.at(-1) !== value.filename
-    ) {
-      context.addIssue({
-        code: "custom",
-        path: ["sandboxPath"],
-        message:
-          "sandbox path must canonically identify the published filename at an absolute host path",
-      });
-    }
-    if (value.artifact.kind !== "file" || value.artifact.retention.policy !== "workspace_file") {
-      context.addIssue({
-        code: "custom",
-        path: ["artifact"],
-        message: "sandbox files require a permanent workspace-file artifact",
-      });
-    }
-    if (
-      value.artifact.originalBytes < 1 ||
-      value.artifact.originalBytes > SANDBOX_FILE_ARTIFACT_MAX_BYTES
-    ) {
-      context.addIssue({
-        code: "custom",
-        path: ["artifact", "originalBytes"],
-        message: "sandbox file size is outside the publication byte limit",
-      });
-    }
-  });
+export const SandboxFileArtifactReceipt = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      type: z.literal("sandbox_file"),
+      sandboxPath: z.string().min(1).max(4_096),
+      filename: z.string().min(1).max(1_024),
+      artifact: RetainedArtifactReferenceSchema,
+      /** Who can open the file. Absent from receipts made before files had audiences. */
+      access: FileAccess.optional(),
+    })
+    .strict()
+    .superRefine((value, context) => {
+      const pathSegments = value.sandboxPath.split("/");
+      // This is a receipt, not read authority. The publisher confines the path
+      // against its resolved provider root; receipts preserve that native path.
+      const unc = value.sandboxPath.startsWith("//");
+      const absolute = unc
+        ? /^\/\/[^/]+\/[^/]+\/.+/u.test(value.sandboxPath) && !value.sandboxPath.startsWith("//?/")
+        : value.sandboxPath.startsWith("/") || /^[A-Z]:\//u.test(value.sandboxPath);
+      if (
+        !absolute ||
+        /[\\\u0000-\u001f\u007f]/u.test(value.sandboxPath) ||
+        pathSegments.some(
+          (segment, index) =>
+            index >= (unc ? 2 : 1) && (!segment || segment === "." || segment === ".."),
+        ) ||
+        pathSegments.at(-1) !== value.filename
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: ["sandboxPath"],
+          message:
+            "sandbox path must canonically identify the published filename at an absolute host path",
+        });
+      }
+      if (value.artifact.kind !== "file" || value.artifact.retention.policy !== "workspace_file") {
+        context.addIssue({
+          code: "custom",
+          path: ["artifact"],
+          message: "sandbox files require a permanent workspace-file artifact",
+        });
+      }
+      if (
+        value.artifact.originalBytes < 1 ||
+        value.artifact.originalBytes > SANDBOX_FILE_ARTIFACT_MAX_BYTES
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: ["artifact", "originalBytes"],
+          message: "sandbox file size is outside the publication byte limit",
+        });
+      }
+    }),
+);
 export type SandboxFileArtifactReceipt = z.infer<typeof SandboxFileArtifactReceipt>;