@opengeni/contracts 0.39.0 → 0.44.1

package/src/presentation-artifact-query.ts

@@ -0,0 +1,2 @@
+/** Presentation query/projection ABI lives beside commands so shared scene codecs cannot drift. */
+export * from "./presentation-artifact-commands";

package/src/retained-output.ts

@@ -7,17 +7,36 @@ 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;
+/** 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. */
+export const GENERATED_VIDEO_MAX_BYTES = 512 * 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",
+  "generated_image",
+  "generated_video",
   "file",
 ]);
 export type RetainedOutputKind = z.infer<typeof RetainedOutputKind>;
@@ -30,6 +49,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 +72,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 +104,99 @@ 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" ||
+      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
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["dimensions"],
+          message: `${value.kind} dimensions exceed the pixel limit`,
+        });
+      }
+    }
+
+    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.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") {
+      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 +247,23 @@ export type RetainedArtifactFileInput = {
   updatedAt: string;
 };
 
+export type RetainedScreenshotArtifactInput = RetainedArtifactFileInput & {
+  sessionId: string;
+  width: number;
+  height: number;
+  expiresAt: string;
+};
+
+export type RetainedGeneratedImageArtifactInput = RetainedArtifactFileInput & {
+  width: number;
+  height: number;
+};
+
+export type RetainedGeneratedVideoArtifactInput = RetainedArtifactFileInput & {
+  width: number;
+  height: number;
+};
+
 /**
  * Convert a ready, integrity-addressed workspace file into the only available
  * retained-output receipt shape. Invalid, pending, or checksum-less files fail
@@ -159,6 +297,108 @@ 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;
+}
+
+/** Build the permanent workspace receipt for one validated generated image. */
+export function retainedGeneratedImageReferenceFromFile(
+  file: RetainedGeneratedImageArtifactInput,
+): RetainedArtifactReference | null {
+  if (
+    file.status !== "ready" ||
+    !file.sha256 ||
+    file.sizeBytes <= 0 ||
+    file.sizeBytes > GENERATED_IMAGE_MAX_BYTES
+  ) {
+    return null;
+  }
+  const value = {
+    available: true as const,
+    artifactId: file.id,
+    kind: "generated_image" as const,
+    contentType: canonicalRetainedContentType(file.contentType),
+    originalBytes: file.sizeBytes,
+    sha256: file.sha256,
+    retainedAt: file.updatedAt,
+    dimensions: { width: file.width, height: file.height },
+    retention: {
+      policy: "workspace_file" as const,
+      expiresAt: null,
+    },
+    retrieval: {
+      method: "GET" as const,
+      path: `/v1/workspaces/${file.workspaceId}/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;
+}
+
+/** Build the permanent workspace receipt for one validated generated video. */
+export function retainedGeneratedVideoReferenceFromFile(
+  file: RetainedGeneratedVideoArtifactInput,
+): RetainedArtifactReference | null {
+  if (
+    file.status !== "ready" ||
+    file.contentType !== "video/mp4" ||
+    !file.sha256 ||
+    file.sizeBytes <= 0 ||
+    file.sizeBytes > GENERATED_VIDEO_MAX_BYTES
+  ) {
+    return null;
+  }
+  const value = {
+    available: true as const,
+    artifactId: file.id,
+    kind: "generated_video" as const,
+    contentType: "video/mp4" as const,
+    originalBytes: file.sizeBytes,
+    sha256: file.sha256,
+    retainedAt: file.updatedAt,
+    dimensions: { width: file.width, height: file.height },
+    retention: {
+      policy: "workspace_file" as const,
+      expiresAt: null,
+    },
+    retrieval: {
+      method: "GET" as const,
+      path: `/v1/workspaces/${file.workspaceId}/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/sandbox-snapshots.ts

@@ -6,6 +6,14 @@ export type WorkspaceTreeFingerprint = {
   entryCount: number;
   fileCount: number;
   totalFileBytes: number;
+  /**
+   * Absent means the original deterministic GNU-tar projection used by remote
+   * sandboxes. Host-backed Local/Docker sessions use the Agents SDK's portable
+   * archive projection, which intentionally contains directories and regular
+   * files only. Keeping the discriminator in the descriptor makes restores
+   * stable when a Docker image changes and preserves old descriptor behavior.
+   */
+  projection?: "sdk_local_archive_v1";
 };
 
 export type TarWorkspaceArchiveDescriptor = {
@@ -114,7 +122,8 @@ export function parseWorkspaceArchiveDescriptor(value: unknown): WorkspaceArchiv
       !SHA256.test(workspace.sha256) ||
       !nonnegativeInteger(workspace.entryCount) ||
       !nonnegativeInteger(workspace.fileCount) ||
-      !nonnegativeInteger(workspace.totalFileBytes)
+      !nonnegativeInteger(workspace.totalFileBytes) ||
+      (workspace.projection !== undefined && workspace.projection !== "sdk_local_archive_v1")
     ) {
       return null;
     }
@@ -181,6 +190,24 @@ export function decodeNativeSnapshotRef(bytes: Uint8Array): NativeSnapshotRef |
   return null;
 }
 
+export function encodeNativeSnapshotRef(ref: NativeSnapshotRef): Uint8Array {
+  const prefix = NATIVE_SNAPSHOT_PREFIXES.find((entry) => entry.provider === ref.provider)?.prefix;
+  if (!prefix || typeof ref.snapshotId !== "string" || ref.snapshotId.length === 0) {
+    throw new TypeError("Native snapshot reference requires a supported provider and snapshot id");
+  }
+  if (ref.workspacePersistence !== undefined && typeof ref.workspacePersistence !== "string") {
+    throw new TypeError("Native snapshot workspace persistence must be a string");
+  }
+  return new TextEncoder().encode(
+    `${prefix}${JSON.stringify({
+      snapshot_id: ref.snapshotId,
+      ...(ref.workspacePersistence === undefined
+        ? {}
+        : { workspace_persistence: ref.workspacePersistence }),
+    })}`,
+  );
+}
+
 export function backendForNativeSnapshotProvider(provider: NativeSnapshotProvider): string {
   return provider === "modal_snapshot_directory" || provider === "modal_snapshot_filesystem"
     ? "modal"

package/src/scoped-knowledge.ts

@@ -4,10 +4,24 @@ import { z } from "zod";
 export const ScopedKnowledgeScopeKind = z.enum(["organization", "workspace", "personal"]);
 export type ScopedKnowledgeScopeKind = z.infer<typeof ScopedKnowledgeScopeKind>;
 
-export type ScopedKnowledgeScope =
-  | { kind: "organization"; workspaceId: null; subjectId: null }
-  | { kind: "workspace"; workspaceId: string; subjectId: null }
-  | { kind: "personal"; workspaceId: string | null; subjectId: string };
+export const ScopedKnowledgeScope = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("organization"),
+    workspaceId: z.null(),
+    subjectId: z.null(),
+  }),
+  z.object({
+    kind: z.literal("workspace"),
+    workspaceId: z.string().uuid(),
+    subjectId: z.null(),
+  }),
+  z.object({
+    kind: z.literal("personal"),
+    workspaceId: z.string().uuid().nullable(),
+    subjectId: z.string().min(1).max(1024),
+  }),
+]);
+export type ScopedKnowledgeScope = z.infer<typeof ScopedKnowledgeScope>;
 
 export const ScopedKnowledgeActorKind = z.enum(["human", "service"]);
 export type ScopedKnowledgeActorKind = z.infer<typeof ScopedKnowledgeActorKind>;

package/src/slack-bot-scopes.ts

@@ -41,6 +41,35 @@ export const OPENGENI_SLACK_BOT_EVENTS = [
   "reaction_added",
 ] as const;
 
+/** Full user-token scope set for every tool currently exposed by Slack's hosted MCP server. */
+export const OPENGENI_SLACK_MCP_USER_SCOPES = [
+  "search:read.public",
+  "search:read.private",
+  "search:read.mpim",
+  "search:read.im",
+  "search:read.files",
+  "files:read",
+  "emoji:read",
+  "search:read.users",
+  "chat:write",
+  "channels:history",
+  "groups:history",
+  "mpim:history",
+  "im:history",
+  "channels:write",
+  "groups:write",
+  "im:write",
+  "mpim:write",
+  "reactions:write",
+  "canvases:read",
+  "canvases:write",
+  "users:read",
+  "users:read.email",
+  "channels:read",
+  "groups:read",
+  "mpim:read",
+] as const;
+
 export const OPENGENI_MANAGED_PUBLIC_BASE_URL = "https://app.opengeni.ai" as const;
 
 function normalizedSlackManifestBaseUrl(publicBaseUrl: string): string {
@@ -83,7 +112,10 @@ export function buildOpenGeniSlackBotManifest(publicBaseUrl: string) {
         `${baseUrl}/v1/integrations/oauth/callback`,
         `${baseUrl}/v1/integrations/slack/callback`,
       ],
-      scopes: { bot: [...OPENGENI_SLACK_BOT_REQUESTED_SCOPES] },
+      scopes: {
+        bot: [...OPENGENI_SLACK_BOT_REQUESTED_SCOPES],
+        user: [...OPENGENI_SLACK_MCP_USER_SCOPES],
+      },
     },
     settings: {
       event_subscriptions: {
@@ -94,6 +126,7 @@ export function buildOpenGeniSlackBotManifest(publicBaseUrl: string) {
         is_enabled: true,
         request_url: `${baseUrl}/v1/integrations/slack/interactions`,
       },
+      is_mcp_enabled: true,
       org_deploy_enabled: false,
       socket_mode_enabled: false,
       token_rotation_enabled: false,