@opengeni/contracts 0.40.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

@@ -15,6 +15,10 @@ export const COMPUTER_SCREENSHOT_MAX_PIXELS = 67_108_864;
 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}$/;
@@ -31,6 +35,8 @@ export const RetainedOutputKind = z.enum([
   "internal_update",
   "event_media",
   "computer_screenshot",
+  "generated_image",
+  "generated_video",
   "file",
 ]);
 export type RetainedOutputKind = z.infer<typeof RetainedOutputKind>;
@@ -116,14 +122,72 @@ export const RetainedArtifactReferenceSchema = z
       });
     }
 
-    if (value.kind === "computer_screenshot") {
+    if (
+      value.kind === "computer_screenshot" ||
+      value.kind === "generated_image" ||
+      value.kind === "generated_video"
+    ) {
       if (!value.dimensions) {
         ctx.addIssue({
           code: "custom",
           path: ["dimensions"],
-          message: "computer screenshot receipts require exact 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",
@@ -190,6 +254,16 @@ export type RetainedScreenshotArtifactInput = RetainedArtifactFileInput & {
   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
@@ -252,6 +326,79 @@ export function retainedScreenshotReferenceFromFile(
   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,