@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/slack-rest-mcp.ts

@@ -0,0 +1,222 @@
+/** The catalog and OAuth identity stay stable while calls use the ordinary Web API. */
+export const OFFICIAL_SLACK_MCP_URL = "https://mcp.slack.com/mcp";
+export const SLACK_REST_API_BASE = "https://slack.com/api/";
+/** Private Slack file bytes are served only from this origin and path. */
+export const SLACK_PRIVATE_FILE_ORIGIN = "https://files.slack.com";
+export const SLACK_PRIVATE_FILE_PATH_PREFIX = "/files-pri/";
+
+/** A private Slack file download URL that may carry a Slack user token. */
+export function isSlackPrivateFileUrl(value: string | URL): boolean {
+  try {
+    const url = new URL(value);
+    return (
+      url.origin === SLACK_PRIVATE_FILE_ORIGIN &&
+      !url.username &&
+      !url.password &&
+      !url.hash &&
+      url.pathname.startsWith(SLACK_PRIVATE_FILE_PATH_PREFIX) &&
+      !url.pathname.split("/").some((segment) => segment === "." || segment === "..")
+    );
+  } catch {
+    return false;
+  }
+}
+
+export const OPENGENI_SLACK_REST_USER_SCOPES = [
+  "channels:read",
+  "groups:read",
+  "im:read",
+  "mpim:read",
+  "channels:history",
+  "groups:history",
+  "im:history",
+  "mpim:history",
+  "users:read",
+  "files:read",
+  "im:write",
+  "chat:write",
+] as const;
+
+/** Slack returns comma-delimited scopes, including in existing saved grants. */
+export function normalizeSlackScopes(
+  scopes: readonly string[] | string | undefined | null,
+): string[] {
+  return [
+    ...new Set(
+      (typeof scopes === "string" ? [scopes] : (scopes ?? []))
+        .flatMap((entry) => entry.split(/[\s,]+/u))
+        .filter(Boolean),
+    ),
+  ].sort();
+}
+
+export type SlackRestMcpTool = {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+    additionalProperties: false;
+  };
+  annotations: {
+    readOnlyHint: boolean;
+    destructiveHint: false;
+    idempotentHint: boolean;
+    openWorldHint: true;
+  };
+};
+
+const conversationScopes = ["channels:read", "groups:read", "im:read", "mpim:read"];
+const historyScopes = ["channels:history", "groups:history", "im:history", "mpim:history"];
+const channel = { type: "string", description: "Slack conversation ID, such as C123 or D123." };
+const cursor = { type: "string", maxLength: 4096, description: "Cursor from the previous page." };
+const directoryPage = { type: "integer", minimum: 1, maximum: 100, default: 100 };
+const historyPage = { type: "integer", minimum: 1, maximum: 15, default: 15 };
+const timestamp = { type: "string", pattern: "^[0-9]+\\.[0-9]+$" };
+
+function tool(
+  name: string,
+  description: string,
+  properties: Record<string, unknown>,
+  required: string[] = [],
+  mutation = false,
+): SlackRestMcpTool {
+  return {
+    name,
+    description,
+    inputSchema: { type: "object", properties, required, additionalProperties: false },
+    annotations: {
+      readOnlyHint: !mutation,
+      destructiveHint: false,
+      idempotentHint: !mutation,
+      openWorldHint: true,
+    },
+  };
+}
+
+/** Static reviewed pilot surface. Each call reads only one explicitly requested page. */
+export const SLACK_REST_MCP_TOOLS: SlackRestMcpTool[] = [
+  tool(
+    "slack_list_channels",
+    "Lists one page of conversations visible to your connected Slack account. Conversation types without a granted read scope are omitted.",
+    {
+      types: {
+        type: "array",
+        items: { type: "string", enum: ["public_channel", "private_channel", "im", "mpim"] },
+        minItems: 1,
+        maxItems: 4,
+      },
+      cursor,
+      limit: directoryPage,
+      exclude_archived: { type: "boolean", default: true },
+    },
+  ),
+  tool(
+    "slack_get_channel_info",
+    "Gets metadata for one conversation visible to your connected Slack account.",
+    { channel },
+    ["channel"],
+  ),
+  tool(
+    "slack_list_channel_members",
+    "Lists one page of members in a visible channel or group conversation.",
+    { channel, cursor, limit: directoryPage },
+    ["channel"],
+  ),
+  tool("slack_list_users", "Lists one page of users in the connected Slack workspace.", {
+    cursor,
+    limit: directoryPage,
+  }),
+  tool(
+    "slack_get_user_info",
+    "Gets a user's profile by their Slack user ID. Email is included only when Slack has granted that scope.",
+    { user: { type: "string" } },
+    ["user"],
+  ),
+  tool(
+    "slack_read_channel",
+    "Reads one page of at most 15 messages from a selected conversation. Slack history limits are shared across the workspace. No automatic pagination or backfill.",
+    {
+      channel,
+      cursor,
+      limit: historyPage,
+      oldest: timestamp,
+      latest: timestamp,
+      inclusive: { type: "boolean", default: false },
+    },
+    ["channel"],
+  ),
+  tool(
+    "slack_read_thread",
+    "Reads one page of at most 15 messages in a selected thread. Slack thread limits are shared across the workspace. No automatic pagination or backfill.",
+    {
+      channel,
+      ts: { ...timestamp, description: "Thread root message timestamp." },
+      cursor,
+      limit: historyPage,
+    },
+    ["channel", "ts"],
+  ),
+  tool(
+    "slack_download_file",
+    "Downloads one file shared in Slack, such as a PDF or image, into your workspace like an attachment and returns its path. Use the file ID (F...) from a message's files.",
+    { file: { type: "string", pattern: "^F[A-Z0-9]+$", description: "Slack file ID." } },
+    ["file"],
+  ),
+  tool(
+    "slack_open_dm",
+    "Opens or resumes a direct message with one Slack user as your connected account.",
+    { user: { type: "string" } },
+    ["user"],
+    true,
+  ),
+  tool(
+    "slack_send_message",
+    "Sends a message as your connected Slack account. Supply thread_ts to reply in a thread. Review the recipient and text before approving. An uncertain submission is never automatically retried.",
+    {
+      channel,
+      text: { type: "string", minLength: 1, maxLength: 40000 },
+      thread_ts: { ...timestamp, description: "Optional thread root timestamp for a reply." },
+      unfurl_links: { type: "boolean", default: false },
+      unfurl_media: { type: "boolean", default: false },
+    },
+    ["channel", "text"],
+    true,
+  ),
+];
+
+const REQUIRED_ANY_SCOPES: Readonly<Record<string, readonly string[]>> = {
+  slack_list_channels: conversationScopes,
+  slack_get_channel_info: conversationScopes,
+  slack_list_channel_members: ["channels:read", "groups:read", "mpim:read"],
+  slack_list_users: ["users:read"],
+  slack_get_user_info: ["users:read"],
+  slack_read_channel: historyScopes,
+  slack_read_thread: historyScopes,
+  slack_download_file: ["files:read"],
+  slack_open_dm: ["im:write"],
+  slack_send_message: ["chat:write"],
+};
+
+export function slackRestMcpToolsForScopes(scopes: readonly string[] | string): SlackRestMcpTool[] {
+  const granted = new Set(normalizeSlackScopes(scopes));
+  return SLACK_REST_MCP_TOOLS.filter((entry) =>
+    REQUIRED_ANY_SCOPES[entry.name]?.some((scope) => granted.has(scope)),
+  ).map((entry) => ({
+    ...entry,
+    inputSchema: {
+      ...entry.inputSchema,
+      required: [...entry.inputSchema.required],
+      properties: { ...entry.inputSchema.properties },
+    },
+    annotations: { ...entry.annotations },
+  }));
+}
+
+export const SLACK_CONVERSATION_READ_SCOPE_BY_TYPE = {
+  public_channel: "channels:read",
+  private_channel: "groups:read",
+  im: "im:read",
+  mpim: "mpim:read",
+} as const;

package/src/slack-task-policy.ts

@@ -1,38 +1,47 @@
+import { defineSchema } from "./define-schema";
 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);
+const SlackOpaqueId = /* @__PURE__ */ defineSchema(() =>
+  z.string().min(1).max(SLACK_TASK_POLICY_ID_MAX_CHARS),
+);
 
-export const SlackSharedConversationMode = z.enum(["deny", "private_handoff"]);
+export const SlackSharedConversationMode = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["deny", "private_handoff"]),
+);
 export type SlackSharedConversationMode = z.infer<typeof SlackSharedConversationMode>;
 
-export const SlackResultPublicationMode = z.enum(["never", "approval_required", "allow"]);
+export const SlackResultPublicationMode = /* @__PURE__ */ defineSchema(() =>
+  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 const SlackTaskPolicyContent = /* @__PURE__ */ defineSchema(() =>
+  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({
@@ -58,71 +67,85 @@ export function canonicalizeSlackTaskPolicy(value: SlackTaskPolicyContent): Slac
   };
 }
 
-export const SlackTaskPolicyRevisionIdentity = z.object({
-  id: z.string().uuid(),
-  revision: z.number().int().positive(),
-  policyHash: z.string().regex(/^[0-9a-f]{64}$/),
-});
+export const SlackTaskPolicyRevisionIdentity = /* @__PURE__ */ defineSchema(() =>
+  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 const SlackTaskPolicyRevision = /* @__PURE__ */ defineSchema(() =>
+  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 const SlackTaskPolicyHead = /* @__PURE__ */ defineSchema(() =>
+  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 const SlackTaskPolicyActivationEvent = /* @__PURE__ */ defineSchema(() =>
+  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 const SlackTaskPolicyListResponse = /* @__PURE__ */ defineSchema(() =>
+  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 const UpdateSlackTaskPolicyRequest = /* @__PURE__ */ defineSchema(() =>
+  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 const SlackTaskPolicyMutationResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    revision: SlackTaskPolicyRevision,
+    head: SlackTaskPolicyHead,
+    event: SlackTaskPolicyActivationEvent,
+  }),
+);
 export type SlackTaskPolicyMutationResponse = z.infer<typeof SlackTaskPolicyMutationResponse>;
 
 export type SlackTaskPolicyConversationFacts = Readonly<{

package/src/spreadsheet-artifact-commands.ts

@@ -17,6 +17,9 @@ export const SPREADSHEET_ARTIFACT_COMMAND_MAX_COMMANDS = 4_096;
 export const SPREADSHEET_ARTIFACT_COMMAND_MAX_CELLS = 1_000_000;
 export const SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES = 1 * 1024 * 1024;
 export const SPREADSHEET_ARTIFACT_SHEET_NAME_MAX_UTF16_UNITS = 31;
+export const SPREADSHEET_DEFAULT_ROW_HEIGHT = 24;
+export const SPREADSHEET_DEFAULT_COLUMN_WIDTH = 96;
+export const SPREADSHEET_MAX_DIMENSION_PIXELS = 4096;
 
 const MAGIC = new TextEncoder().encode("OGASC002");
 const HEADER_BYTES = 8 + 2 + 2 + 4 + 8;
@@ -121,7 +124,19 @@ export type SpreadsheetArtifactCommand =
   | SpreadsheetRenameSheetCommand
   | SpreadsheetDeleteSheetCommand
   | SpreadsheetSetCellsCommand
-  | SpreadsheetClearRangeCommand;
+  | SpreadsheetClearRangeCommand
+  | Readonly<{
+      kind: "row.height.set";
+      sheet: SpreadsheetSheetPrecondition;
+      row: number;
+      height: number | null;
+    }>
+  | Readonly<{
+      kind: "column.width.set";
+      sheet: SpreadsheetSheetPrecondition;
+      column: number;
+      width: number | null;
+    }>;
 
 export type SpreadsheetArtifactCommandBatch = Readonly<{
   version: typeof SPREADSHEET_ARTIFACT_COMMAND_VERSION;
@@ -331,6 +346,27 @@ function encodeCommand(
       writer.u32(range.end.column);
       break;
     }
+    case "row.height.set":
+    case "column.width.set": {
+      const row = command.kind === "row.height.set";
+      const coordinate = row ? "row" : "column";
+      const size = row ? "height" : "width";
+      exactKeys(
+        command,
+        ["kind", "sheet", coordinate, size].sort(),
+        `spreadsheet command ${index}`,
+      );
+      writer.u8(row ? 5 : 6);
+      encodeSheetPrecondition(writer, command.sheet, index, context);
+      writer.u32(nonnegativeU32(command[coordinate], coordinate));
+      writer.u32(
+        dimensionPixels(
+          command[size],
+          row ? SPREADSHEET_DEFAULT_ROW_HEIGHT : SPREADSHEET_DEFAULT_COLUMN_WIDTH,
+        ),
+      );
+      break;
+    }
     default:
       throw commandError(index, "unknown command kind");
   }
@@ -341,7 +377,8 @@ function decodeCommand(
   index: number,
   context: CommandContext,
 ): SpreadsheetArtifactCommand {
-  switch (reader.u8()) {
+  const tag = reader.u8();
+  switch (tag) {
     case 0: {
       const sheetId = reader.sheetObjectId();
       const name = decodedSheetName(
@@ -400,11 +437,45 @@ function decodeCommand(
         range: Object.freeze({ start, end }),
       });
     }
+    case 5:
+    case 6: {
+      const sheet = decodeSheetPrecondition(reader, index, context);
+      const coordinate = reader.u32();
+      const pixels = reader.u32();
+      const defaultPixels =
+        tag === 5 ? SPREADSHEET_DEFAULT_ROW_HEIGHT : SPREADSHEET_DEFAULT_COLUMN_WIDTH;
+      if (pixels === defaultPixels || pixels > SPREADSHEET_MAX_DIMENSION_PIXELS) {
+        throw commandError(index, "dimension pixels are noncanonical or outside bounds");
+      }
+      return tag === 5
+        ? Object.freeze({ kind: "row.height.set", sheet, row: coordinate, height: pixels || null })
+        : Object.freeze({
+            kind: "column.width.set",
+            sheet,
+            column: coordinate,
+            width: pixels || null,
+          });
+    }
     default:
       throw commandError(index, "unknown binary command tag");
   }
 }
 
+function dimensionPixels(value: unknown, defaultPixels: number): number {
+  if (value === null) return 0;
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > SPREADSHEET_MAX_DIMENSION_PIXELS
+  ) {
+    throw new RangeError(
+      "dimension pixels must be an integer from 1 through 4096, or null to reset",
+    );
+  }
+  return value === defaultPixels ? 0 : value;
+}
+
 function encodeSheetPrecondition(
   writer: BinaryWriter,
   value: unknown,