@opengeni/contracts 0.40.0 → 0.50.0

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,

package/src/slack-task-policy.ts

@@ -0,0 +1,215 @@
+import { z } from "zod";
+
+export const SLACK_TASK_POLICY_ID_MAX_CHARS = 128;
+export const SLACK_TASK_POLICY_REASON_MAX_CHARS = 4_096;
+export const SLACK_TASK_POLICY_MAX_IDS = 256;
+
+const SlackOpaqueId = z.string().min(1).max(SLACK_TASK_POLICY_ID_MAX_CHARS);
+
+export const SlackSharedConversationMode = z.enum(["deny", "private_handoff"]);
+export type SlackSharedConversationMode = z.infer<typeof SlackSharedConversationMode>;
+
+export const SlackResultPublicationMode = z.enum(["never", "approval_required", "allow"]);
+export type SlackResultPublicationMode = z.infer<typeof SlackResultPublicationMode>;
+
+function uniqueSortedIds(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+export const SlackTaskPolicyContent = z
+  .object({
+    allowedTeamIds: z
+      .array(SlackOpaqueId)
+      .max(SLACK_TASK_POLICY_MAX_IDS)
+      .transform(uniqueSortedIds),
+    allowedConversationIds: z
+      .array(SlackOpaqueId)
+      .max(SLACK_TASK_POLICY_MAX_IDS)
+      .transform(uniqueSortedIds),
+    allowGuestInitiators: z.boolean(),
+    allowExternalInitiators: z.boolean(),
+    allowMpim: z.boolean(),
+    sharedConversationMode: SlackSharedConversationMode,
+    resultPublicationMode: SlackResultPublicationMode,
+  })
+  .strict();
+export type SlackTaskPolicyContent = z.infer<typeof SlackTaskPolicyContent>;
+
+export const DEFAULT_SLACK_TASK_POLICY: SlackTaskPolicyContent = Object.freeze({
+  allowedTeamIds: [],
+  allowedConversationIds: [],
+  allowGuestInitiators: false,
+  allowExternalInitiators: false,
+  allowMpim: false,
+  sharedConversationMode: "deny",
+  resultPublicationMode: "never",
+});
+
+export function canonicalizeSlackTaskPolicy(value: SlackTaskPolicyContent): SlackTaskPolicyContent {
+  const parsed = SlackTaskPolicyContent.parse(value);
+  return {
+    allowedTeamIds: parsed.allowedTeamIds,
+    allowedConversationIds: parsed.allowedConversationIds,
+    allowGuestInitiators: parsed.allowGuestInitiators,
+    allowExternalInitiators: parsed.allowExternalInitiators,
+    allowMpim: parsed.allowMpim,
+    sharedConversationMode: parsed.sharedConversationMode,
+    resultPublicationMode: parsed.resultPublicationMode,
+  };
+}
+
+export const SlackTaskPolicyRevisionIdentity = z.object({
+  id: z.string().uuid(),
+  revision: z.number().int().positive(),
+  policyHash: z.string().regex(/^[0-9a-f]{64}$/),
+});
+export type SlackTaskPolicyRevisionIdentity = z.infer<typeof SlackTaskPolicyRevisionIdentity>;
+
+export const SlackTaskPolicyRevision = SlackTaskPolicyRevisionIdentity.extend({
+  operationId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  policy: SlackTaskPolicyContent,
+  supersedesRevisionId: z.string().uuid().nullable(),
+  createdBySubjectId: z.string().min(1).max(1_024),
+  createdAt: z.string().datetime(),
+});
+export type SlackTaskPolicyRevision = z.infer<typeof SlackTaskPolicyRevision>;
+
+export const SlackTaskPolicyHead = z.object({
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  revisionId: z.string().uuid(),
+  revision: z.number().int().positive(),
+  policyHash: z.string().regex(/^[0-9a-f]{64}$/),
+  activationVersion: z.number().int().positive(),
+  activatedAt: z.string().datetime(),
+});
+export type SlackTaskPolicyHead = z.infer<typeof SlackTaskPolicyHead>;
+
+export const SlackTaskPolicyActivationEvent = z.object({
+  id: z.string().uuid(),
+  operationId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  activationVersion: z.number().int().positive(),
+  oldRevision: SlackTaskPolicyRevisionIdentity.nullable(),
+  newRevision: SlackTaskPolicyRevisionIdentity,
+  actorSubjectId: z.string().min(1).max(1_024),
+  reason: z.string().min(1).max(SLACK_TASK_POLICY_REASON_MAX_CHARS),
+  createdAt: z.string().datetime(),
+});
+export type SlackTaskPolicyActivationEvent = z.infer<typeof SlackTaskPolicyActivationEvent>;
+
+export const SlackTaskPolicyListResponse = z.object({
+  current: SlackTaskPolicyHead.nullable(),
+  activeRevision: SlackTaskPolicyRevision.nullable(),
+  revisions: z.array(SlackTaskPolicyRevision),
+  activationEvents: z.array(SlackTaskPolicyActivationEvent),
+});
+export type SlackTaskPolicyListResponse = z.infer<typeof SlackTaskPolicyListResponse>;
+
+export const UpdateSlackTaskPolicyRequest = z.object({
+  operationId: z.string().uuid().optional(),
+  policy: SlackTaskPolicyContent,
+  expectedCurrentRevisionId: z.string().uuid().nullable(),
+  expectedActivationVersion: z.number().int().nonnegative(),
+  reason: z.string().trim().min(1).max(SLACK_TASK_POLICY_REASON_MAX_CHARS),
+});
+export type UpdateSlackTaskPolicyRequest = z.infer<typeof UpdateSlackTaskPolicyRequest>;
+
+export const SlackTaskPolicyMutationResponse = z.object({
+  revision: SlackTaskPolicyRevision,
+  head: SlackTaskPolicyHead,
+  event: SlackTaskPolicyActivationEvent,
+});
+export type SlackTaskPolicyMutationResponse = z.infer<typeof SlackTaskPolicyMutationResponse>;
+
+export type SlackTaskPolicyConversationFacts = Readonly<{
+  installationTeamId: string;
+  conversationId: string;
+  contextTeamId: string | null;
+  connectedTeamIds: readonly string[] | null;
+  sharedTeamIds: readonly string[] | null;
+  isShared: boolean;
+  isExternallyShared: boolean;
+  isOrgShared: boolean;
+  isPendingExternallyShared: boolean;
+  isMpim: boolean;
+}>;
+
+export type SlackTaskPolicyInitiatorFacts = Readonly<{
+  teamId: string | null;
+  isGuest: boolean | null;
+  isExternal: boolean | null;
+}>;
+
+export type SlackTaskPolicyDecision = Readonly<{
+  disposition: "ordinary" | "deny" | "private_handoff";
+  publication: SlackResultPublicationMode;
+  reason:
+    | "ordinary_conversation"
+    | "policy_missing"
+    | "conversation_not_allowed"
+    | "team_not_allowed"
+    | "ambiguous_shared_facts"
+    | "mpim_not_allowed"
+    | "guest_not_allowed"
+    | "external_not_allowed"
+    | "allowed";
+}>;
+
+export function evaluateSlackTaskPolicy(input: {
+  policy: SlackTaskPolicyContent | null;
+  conversation: SlackTaskPolicyConversationFacts;
+  initiator: SlackTaskPolicyInitiatorFacts;
+}): SlackTaskPolicyDecision {
+  const { conversation, initiator } = input;
+  const governed =
+    conversation.isShared ||
+    conversation.isExternallyShared ||
+    conversation.isOrgShared ||
+    conversation.isPendingExternallyShared ||
+    conversation.isMpim;
+  if (!governed) {
+    return { disposition: "ordinary", publication: "allow", reason: "ordinary_conversation" };
+  }
+  if (!input.policy) return { disposition: "deny", publication: "never", reason: "policy_missing" };
+  const policy = canonicalizeSlackTaskPolicy(input.policy);
+  if (!policy.allowedConversationIds.includes(conversation.conversationId)) {
+    return { disposition: "deny", publication: "never", reason: "conversation_not_allowed" };
+  }
+  if (conversation.isMpim && !policy.allowMpim) {
+    return { disposition: "deny", publication: "never", reason: "mpim_not_allowed" };
+  }
+  if (initiator.isGuest === null || initiator.isExternal === null || initiator.teamId === null) {
+    return { disposition: "deny", publication: "never", reason: "ambiguous_shared_facts" };
+  }
+  if (initiator.isGuest && !policy.allowGuestInitiators) {
+    return { disposition: "deny", publication: "never", reason: "guest_not_allowed" };
+  }
+  if (initiator.isExternal && !policy.allowExternalInitiators) {
+    return { disposition: "deny", publication: "never", reason: "external_not_allowed" };
+  }
+  const teams = [
+    conversation.installationTeamId,
+    conversation.contextTeamId,
+    initiator.teamId,
+    ...(conversation.connectedTeamIds ?? []),
+    ...(conversation.sharedTeamIds ?? []),
+  ];
+  if (conversation.connectedTeamIds === null || conversation.sharedTeamIds === null) {
+    return { disposition: "deny", publication: "never", reason: "ambiguous_shared_facts" };
+  }
+  if (teams.some((teamId) => teamId === null || !policy.allowedTeamIds.includes(teamId))) {
+    return { disposition: "deny", publication: "never", reason: "team_not_allowed" };
+  }
+  if (policy.sharedConversationMode === "deny") {
+    return { disposition: "deny", publication: "never", reason: "allowed" };
+  }
+  return {
+    disposition: "private_handoff",
+    publication: policy.resultPublicationMode,
+    reason: "allowed",
+  };
+}