@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/skill-use.ts

@@ -1,3 +1,5 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 /**
@@ -8,13 +10,9 @@ import { z } from "zod";
 export const SKILL_USE_META_KEY = "opengeni/skillUse" as const;
 
 /** Where the Skill a read resolved to comes from. `personal` is a user-scope Skill. */
-export const SkillUseSource = z.enum([
-  "builtin",
-  "session",
-  "workspace",
-  "organization",
-  "personal",
-]);
+export const SkillUseSource = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["builtin", "session", "workspace", "organization", "personal"]),
+);
 export type SkillUseSource = z.infer<typeof SkillUseSource>;
 
 /**
@@ -23,7 +21,9 @@ export type SkillUseSource = z.infer<typeof SkillUseSource>;
  * repeat receipt. `refused` means the read returned an error instead of Skill
  * text; it has no result, so it appears only in metrics.
  */
-export const SkillReadKind = z.enum(["full", "already_in_context", "files", "list", "refused"]);
+export const SkillReadKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["full", "already_in_context", "files", "list", "refused"]),
+);
 export type SkillReadKind = z.infer<typeof SkillReadKind>;
 
 const skillUseFields = {
@@ -31,19 +31,16 @@ const skillUseFields = {
   source: SkillUseSource,
   label: z.string().min(1).max(128).optional(),
   /** Whole-artifact digest, for a Skill without a ledger revision. */
-  contentSha256: z
-    .string()
-    .regex(/^[0-9a-f]{64}$/u)
-    .optional(),
+  contentSha256: primitives.string.regex(/^[0-9a-f]{64}$/u).optional(),
   /** Ledger revision of a workspace, organization, or personal Skill. */
   revisionId: z.string().min(1).max(128).optional(),
   kind: SkillReadKind.exclude(["refused"]),
   /** UTF-8 bytes of the result text the read returned, before model tool-output truncation. */
-  bytes: z.number().int().nonnegative(),
+  bytes: primitives.nonnegativeInteger,
   /** The Skill appeared in the Skill index the model saw this turn. */
-  inIndex: z.boolean(),
+  inIndex: primitives.boolean,
   /** skill_search returned this Skill earlier in the same turn attempt. */
-  searchedThisTurn: z.boolean(),
+  searchedThisTurn: primitives.boolean,
 };
 const oneProvenance = (use: {
   contentSha256?: string | undefined;
@@ -59,13 +56,17 @@ const oneProvenanceMessage = {
  * built-in; user-authored Skills never set it. This is the writer's closed
  * shape: an unknown field fails the parse, so nothing else can be attached.
  */
-export const SkillUse = z.strictObject(skillUseFields).refine(oneProvenance, oneProvenanceMessage);
+export const SkillUse = /* @__PURE__ */ defineSchema(() =>
+  z.strictObject(skillUseFields).refine(oneProvenance, oneProvenanceMessage),
+);
 export type SkillUse = z.infer<typeof SkillUse>;
 
 // Stored events outlive the worker that wrote them. A reader drops fields a
 // newer writer added instead of dropping the whole fact, and what it returns
 // still holds only the known, content-free fields.
-const StoredSkillUse = z.object(skillUseFields).refine(oneProvenance, oneProvenanceMessage);
+const StoredSkillUse = /* @__PURE__ */ defineSchema(() =>
+  z.object(skillUseFields).refine(oneProvenance, oneProvenanceMessage),
+);
 
 /** The Skill-use fact on a tool result or its event projection, when present and valid. */
 export function skillUseFromToolOutput(output: unknown): SkillUse | null {

package/src/skills.ts

@@ -1,31 +1,78 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
+import { SKILL_MAX_FILES } from "./skill-files";
 export { parseSkillFrontmatter, readSkillMetadata } from "./skill-metadata";
 export * from "./skill-files";
 
 /** Files are UTF-8 text, relative to the Skill root. No executable authority. */
-export const SkillFile = z.object({ path: z.string().min(1).max(512), content: z.string() });
+export const SkillFile = /* @__PURE__ */ defineSchema(() =>
+  z.object({ path: z.string().min(1).max(512), content: primitives.string }),
+);
 export type SkillFile = z.infer<typeof SkillFile>;
-export const SkillActor = z.discriminatedUnion("kind", [
-  z.object({
-    kind: z.literal("service"),
-    subjectId: z.string().min(1),
-    principalKind: z.enum(["service", "api_key", "configured_key"]),
-  }),
-  z.object({
-    kind: z.literal("human"),
-    subjectId: z.string().min(1),
-    principalKind: z.literal("human_session"),
-  }),
-  z.object({
-    kind: z.literal("agent"),
-    sessionId: z.uuid(),
-    turnId: z.uuid(),
-    attemptId: z.uuid(),
-    executionGeneration: z.number().int().positive(),
-  }),
-]);
+export const SkillActor = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("service"),
+      subjectId: primitives.nonEmptyString,
+      principalKind: z.enum(["service", "api_key", "configured_key"]),
+    }),
+    z.object({
+      kind: z.literal("human"),
+      subjectId: primitives.nonEmptyString,
+      principalKind: z.literal("human_session"),
+    }),
+    z.object({
+      kind: z.literal("agent"),
+      sessionId: z.uuid(),
+      turnId: z.uuid(),
+      attemptId: z.uuid(),
+      executionGeneration: primitives.positiveInteger,
+    }),
+  ]),
+);
 export type SkillActor = z.infer<typeof SkillActor>;
 export type SkillScope = "workspace" | "organization" | "user";
+
+/** Save a personal, workspace or organization Skill folder (`saveWorkspaceSkill`). */
+export const SaveWorkspaceSkillRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: z.uuid(),
+      skillId: z.uuid(),
+      expectedRevisionId: z.uuid().nullable(),
+      expectedScopeVersion: z.number().int().nonnegative(),
+      scope: z.enum(["workspace", "organization", "user"]).default("workspace"),
+      stableKey: z.string().min(1).max(96),
+      files: z.array(SkillFile).max(SKILL_MAX_FILES),
+      deletions: z.array(z.string().min(1).max(512)).max(SKILL_MAX_FILES).default([]),
+      reason: z.string().min(1).max(2000),
+    })
+    .strict(),
+);
+export type SaveWorkspaceSkillRequest = z.infer<typeof SaveWorkspaceSkillRequest>;
+
+/** Approve, reject or restore one Skill revision. */
+export const ApplyWorkspaceSkillRevisionRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      removalOperationId: z.uuid().optional(),
+      operationId: z.uuid(),
+      revisionId: z.uuid(),
+      expectedRevisionId: z.uuid().nullable(),
+      expectedScopeVersion: z.number().int().nonnegative(),
+      reason: z.string().min(1).max(2000),
+    })
+    .strict(),
+);
+export type ApplyWorkspaceSkillRevisionRequest = z.infer<typeof ApplyWorkspaceSkillRevisionRequest>;
+
+/** Permanently remove a Skill and all its saved revisions. */
+export const RemoveWorkspaceSkillRequest = /* @__PURE__ */ defineSchema(() =>
+  ApplyWorkspaceSkillRevisionRequest.omit({ revisionId: true, removalOperationId: true }),
+);
+export type RemoveWorkspaceSkillRequest = z.infer<typeof RemoveWorkspaceSkillRequest>;
+
 export type SkillWriteContext = { accountId: string; workspaceId: string; actor: SkillActor };
 export type SkillSaveInput = SkillWriteContext & {
   operationId: string;
@@ -58,14 +105,16 @@ export type SkillInstallInput = SkillWriteContext & {
   skillFacetId: string;
   reason: string;
 };
-export const SkillReviewReference = z.object({
-  removalOperationId: z.uuid().optional(),
-  sourceOperationId: z.uuid(),
-  skillId: z.uuid(),
-  revisionId: z.uuid(),
-  expectedRevisionId: z.uuid().nullable(),
-  expectedScopeVersion: z.number().int().positive(),
-});
+export const SkillReviewReference = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    removalOperationId: z.uuid().optional(),
+    sourceOperationId: z.uuid(),
+    skillId: z.uuid(),
+    revisionId: z.uuid(),
+    expectedRevisionId: z.uuid().nullable(),
+    expectedScopeVersion: primitives.positiveInteger,
+  }),
+);
 export type SkillReviewReference = z.infer<typeof SkillReviewReference>;
 export function skillReviewHumanInput(skillReview: SkillReviewReference) {
   const removing = Boolean(skillReview.removalOperationId);
@@ -92,30 +141,36 @@ export function skillReviewHumanInput(skillReview: SkillReviewReference) {
     ],
   };
 }
-export const SkillWriteReceipt = z.object({
-  removed: z.boolean().optional(),
-  operationId: z.uuid(),
-  skillId: z.uuid(),
-  revisionId: z.uuid(),
-  outcome: z.enum(["applied", "pending", "preserved"]),
-  decision: z.literal("rejected").optional(),
-  pendingReason: z.enum(["approval", "source_finalization"]).optional(),
-  skillReview: SkillReviewReference.optional(),
-  replayed: z.boolean(),
-});
+export const SkillWriteReceipt = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    removed: primitives.optionalBoolean,
+    operationId: z.uuid(),
+    skillId: z.uuid(),
+    revisionId: z.uuid(),
+    outcome: z.enum(["applied", "pending", "preserved"]),
+    decision: z.literal("rejected").optional(),
+    pendingReason: z.enum(["approval", "source_finalization"]).optional(),
+    skillReview: SkillReviewReference.optional(),
+    replayed: primitives.boolean,
+  }),
+);
 export type SkillWriteReceipt = z.infer<typeof SkillWriteReceipt>;
-export const SkillPublicationReceipt = SkillWriteReceipt.extend({
-  sourceOperationId: z.uuid(),
-  activationEventId: z.uuid().nullable(),
-});
+export const SkillPublicationReceipt = /* @__PURE__ */ defineSchema(() =>
+  SkillWriteReceipt.extend({
+    sourceOperationId: z.uuid(),
+    activationEventId: z.uuid().nullable(),
+  }),
+);
 export type SkillPublicationReceipt = z.infer<typeof SkillPublicationReceipt>;
-export const SkillSourceReleaseReceipt = z.object({
-  skillId: z.uuid(),
-  revisionId: z.uuid().nullable(),
-  disposition: z.enum(["deactivated", "preserved", "inactive"]),
-  eventId: z.uuid().nullable(),
-  warning: z.string().nullable(),
-});
+export const SkillSourceReleaseReceipt = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    skillId: z.uuid(),
+    revisionId: z.uuid().nullable(),
+    disposition: z.enum(["deactivated", "preserved", "inactive"]),
+    eventId: z.uuid().nullable(),
+    warning: primitives.nullableString,
+  }),
+);
 export type SkillSourceReleaseReceipt = z.infer<typeof SkillSourceReleaseReceipt>;
 export type SkillRecord = {
   removalOperationId?: string | null;

package/src/slack-bot-scopes.ts

@@ -1,3 +1,5 @@
+import { OPENGENI_SLACK_REST_USER_SCOPES } from "./slack-rest-mcp";
+
 export const OPENGENI_SLACK_BOT_REQUIRED_SCOPES = [
   "app_mentions:read",
   "canvases:read",
@@ -47,9 +49,15 @@ export const OPENGENI_SLACK_BOT_REQUESTED_SCOPES = [
   ...OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
   OPENGENI_SLACK_REACTION_REQUIRED_SCOPE,
   OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE,
-  ...OPENGENI_SLACK_BOT_SEARCH_SCOPES,
 ] as const;
 
+export function openGeniSlackBotRequestedScopes(mode: "limited" | "full" = "limited"): string[] {
+  return [
+    ...OPENGENI_SLACK_BOT_REQUESTED_SCOPES,
+    ...(mode === "full" ? OPENGENI_SLACK_BOT_SEARCH_SCOPES : []),
+  ];
+}
+
 export const OPENGENI_SLACK_BOT_EVENTS = [
   "app_home_opened",
   "app_mention",
@@ -60,34 +68,8 @@ 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;
+/** User grants required by the reviewed Slack API MCP tools. */
+export const OPENGENI_SLACK_MCP_USER_SCOPES = OPENGENI_SLACK_REST_USER_SCOPES;
 
 export const OPENGENI_MANAGED_PUBLIC_BASE_URL = "https://app.opengeni.ai" as const;
 
@@ -96,6 +78,7 @@ export type OpenGeniSlackBotManifestOptions = Readonly<{
   botDisplayName?: string;
   slashCommand?: string;
   shortcutName?: string;
+  accessMode?: "limited" | "full";
 }>;
 
 function normalizedSlackManifestText(
@@ -138,17 +121,17 @@ export function buildOpenGeniSlackBotManifest(
   options: OpenGeniSlackBotManifestOptions = {},
 ) {
   const baseUrl = normalizedSlackManifestBaseUrl(publicBaseUrl);
-  const appName = normalizedSlackManifestText(options.appName, "OpenGeni", "app name", 35);
+  const appName = normalizedSlackManifestText(options.appName, "Opengeni", "app name", 35);
   const botDisplayName = normalizedSlackManifestText(
     options.botDisplayName,
-    "OpenGeni",
+    "Opengeni",
     "bot display name",
     80,
   );
   const slashCommand = normalizedSlackCommand(options.slashCommand);
   const shortcutName = normalizedSlackManifestText(
     options.shortcutName,
-    "Open in OpenGeni",
+    "Open in Opengeni",
     "shortcut name",
     35,
   );
@@ -164,7 +147,7 @@ export function buildOpenGeniSlackBotManifest(
       slash_commands: [
         {
           command: slashCommand,
-          description: "Start an OpenGeni task in this channel",
+          description: "Start an Opengeni task in this channel",
           should_escape: false,
           url: `${baseUrl}/v1/integrations/slack/commands`,
         },
@@ -172,7 +155,7 @@ export function buildOpenGeniSlackBotManifest(
       shortcuts: [
         {
           callback_id: "opengeni_message",
-          description: "Start an OpenGeni task from this Slack message",
+          description: "Start an Opengeni task from this Slack message",
           name: shortcutName,
           type: "message",
         },
@@ -184,7 +167,7 @@ export function buildOpenGeniSlackBotManifest(
         `${baseUrl}/v1/integrations/slack/callback`,
       ],
       scopes: {
-        bot: [...OPENGENI_SLACK_BOT_REQUESTED_SCOPES],
+        bot: openGeniSlackBotRequestedScopes(options.accessMode),
         user: [...OPENGENI_SLACK_MCP_USER_SCOPES],
       },
     },

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;