@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/skill-catalog-context.ts

@@ -0,0 +1,50 @@
+/** Durable, model-visible catalog context. Text markers survive SDK/provider replay. */
+export const SKILL_CATALOG_CONTEXT_PREFIX = "<opengeni_skill_catalog>\n";
+export const SKILL_CATALOG_CONTEXT_SUFFIX = "\n</opengeni_skill_catalog>";
+const GUIDANCE =
+  "This is the current configured Skill index and replaces earlier configured Skill indexes. " +
+  "Entries describe discoverability, not permission or full instructions. " +
+  "Use skill_read for instructions and skill_search for current discovery; tool authorization remains authoritative.\n\n";
+
+export function skillCatalogContextItem(catalog: string): Record<string, unknown> {
+  return {
+    type: "message",
+    role: "developer",
+    content: SKILL_CATALOG_CONTEXT_PREFIX + GUIDANCE + catalog + SKILL_CATALOG_CONTEXT_SUFFIX,
+  };
+}
+
+/** Accept the Chat Completions projection and SDK text-part normalization too. */
+export function readSkillCatalogContext(item: Record<string, unknown>): string | null {
+  if (item.type === "unknown" && item.providerData && typeof item.providerData === "object") {
+    const data = item.providerData as Record<string, unknown>;
+    if (data.type === "message") return readSkillCatalogContext(data);
+  }
+  if (item.type !== "message" || (item.role !== "developer" && item.role !== "system")) return null;
+  const content =
+    typeof item.content === "string"
+      ? item.content
+      : Array.isArray(item.content) &&
+          item.content.every(
+            (part) =>
+              part &&
+              (part.type === "input_text" || part.type === "output_text" || part.type === "text") &&
+              typeof part.text === "string",
+          )
+        ? item.content.map((part) => part.text).join("")
+        : null;
+  const prefix = SKILL_CATALOG_CONTEXT_PREFIX + GUIDANCE;
+  return content?.startsWith(prefix) && content.endsWith(SKILL_CATALOG_CONTEXT_SUFFIX)
+    ? content.slice(prefix.length, -SKILL_CATALOG_CONTEXT_SUFFIX.length)
+    : null;
+}
+
+export function latestSkillCatalogContext(
+  items: readonly Record<string, unknown>[],
+): Record<string, unknown> | undefined {
+  for (let index = items.length - 1; index >= 0; index--) {
+    const catalog = readSkillCatalogContext(items[index]!);
+    if (catalog !== null) return skillCatalogContextItem(catalog);
+  }
+  return undefined;
+}

package/src/skill-files.ts

@@ -1,7 +1,7 @@
 /** Shared text-folder limits for API admission, runtime imports and checkout. */
-export const SKILL_MAX_FILES = 128;
-export const SKILL_MAX_FILE_BYTES = 256 * 1024;
-export const SKILL_MAX_TOTAL_BYTES = 1024 * 1024;
+export const SKILL_MAX_FILES = 1024;
+export const SKILL_MAX_FILE_BYTES = 2 * 1024 * 1024;
+export const SKILL_MAX_TOTAL_BYTES = 8 * 1024 * 1024;
 
 export function isSafeSkillRelativePath(path: string): boolean {
   return (

package/src/skill-use.ts

@@ -0,0 +1,80 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/**
+ * `_meta` key of the content-free Skill-use fact on a model `skill_read`
+ * result. MCP `_meta` never reaches the model: it survives only into the
+ * `agent.toolCall.output` event projection, never into model history.
+ */
+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 = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["builtin", "session", "workspace", "organization", "personal"]),
+);
+export type SkillUseSource = z.infer<typeof SkillUseSource>;
+
+/**
+ * What a `skill_read` returned: `full` is the default SKILL.md read, `files`
+ * explicit paths, `list` a path inventory, and `already_in_context` the short
+ * 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 = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["full", "already_in_context", "files", "list", "refused"]),
+);
+export type SkillReadKind = z.infer<typeof SkillReadKind>;
+
+const skillUseFields = {
+  id: z.string().min(1).max(512),
+  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(),
+  /** 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(),
+  /** The Skill appeared in the Skill index the model saw this turn. */
+  inIndex: z.boolean(),
+  /** skill_search returned this Skill earlier in the same turn attempt. */
+  searchedThisTurn: z.boolean(),
+};
+const oneProvenance = (use: {
+  contentSha256?: string | undefined;
+  revisionId?: string | undefined;
+}) => use.contentSha256 === undefined || use.revisionId === undefined;
+const oneProvenanceMessage = {
+  message: "A Skill use carries a content digest or a revision, not both",
+};
+
+/**
+ * Ids, digests, and counts only. Never Skill text, user text, or a Skill's
+ * title or description. `label` is reserved for a platform display label of a
+ * 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 = /* @__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 = /* @__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 {
+  if (!output || typeof output !== "object" || Array.isArray(output)) return null;
+  const meta = (output as { _meta?: unknown })._meta;
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return null;
+  const parsed = StoredSkillUse.safeParse((meta as Record<string, unknown>)[SKILL_USE_META_KEY]);
+  return parsed.success ? parsed.data : null;
+}

package/src/skills.ts

@@ -1,29 +1,34 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 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: z.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: 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 type SkillActor = z.infer<typeof SkillActor>;
 export type SkillScope = "workspace" | "organization" | "user";
 export type SkillWriteContext = { accountId: string; workspaceId: string; actor: SkillActor };
@@ -38,6 +43,7 @@ export type SkillSaveInput = SkillWriteContext & {
   reason: string;
 };
 export type SkillRevisionInput = SkillWriteContext & {
+  removalOperationId?: string | undefined;
   operationId: string;
   skillId: string;
   revisionId: string;
@@ -45,32 +51,46 @@ export type SkillRevisionInput = SkillWriteContext & {
   expectedScopeVersion: number;
   reason: string;
 };
+export type SkillRemoveInput = SkillWriteContext & {
+  operationId: string;
+  skillId: string;
+  expectedRevisionId: string | null;
+  expectedScopeVersion: number;
+  reason: string;
+};
 export type SkillInstallInput = SkillWriteContext & {
   operationId: string;
   skillFacetId: string;
   reason: string;
 };
-export const SkillReviewReference = z.object({
-  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: z.number().int().positive(),
+  }),
+);
 export type SkillReviewReference = z.infer<typeof SkillReviewReference>;
 export function skillReviewHumanInput(skillReview: SkillReviewReference) {
+  const removing = Boolean(skillReview.removalOperationId);
   return {
     questions: [
       {
         id: `skill:${skillReview.revisionId}`,
         kind: "single_select" as const,
-        label: "Save this Skill?",
-        prompt: "Save this exact Skill revision for this workspace?",
-        helpText:
-          "Review the complete files before saving. Saving activates this revision immediately.",
+        label: removing ? "Permanently delete this Skill?" : "Save this Skill?",
+        prompt: removing
+          ? "Permanently delete this Skill and all its stored revisions?"
+          : "Save this exact Skill revision for this workspace?",
+        helpText: removing
+          ? "This cannot be undone. All stored Skill revisions will be deleted; conversations remain unchanged."
+          : "Review the complete files before saving. Saving activates this revision immediately.",
         options: [
-          { id: "save", label: "Save" },
-          { id: "skip", label: "Don't save" },
+          { id: "save", label: removing ? "Permanently delete" : "Save" },
+          { id: "skip", label: removing ? "Keep Skill" : "Don't save" },
         ],
         required: true,
         allowOther: false,
@@ -79,31 +99,39 @@ export function skillReviewHumanInput(skillReview: SkillReviewReference) {
     ],
   };
 }
-export const SkillWriteReceipt = z.object({
-  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: 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 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: z.string().nullable(),
+  }),
+);
 export type SkillSourceReleaseReceipt = z.infer<typeof SkillSourceReleaseReceipt>;
 export type SkillRecord = {
+  removalOperationId?: string | null;
   activationMode: "workspace_managed" | "session_selected";
   pendingRevisionIds: string[];
   id: string;

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",
@@ -19,6 +21,9 @@ export const OPENGENI_SLACK_BOT_REQUIRED_SCOPES = [
 /** Read-only scope needed only for the optional emoji-reaction summon surface. */
 export const OPENGENI_SLACK_REACTION_REQUIRED_SCOPE = "reactions:read" as const;
 
+/** Optional grant for explicit retained-file delivery to a task's Slack thread. */
+export const OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE = "files:write" as const;
+
 /**
  * Bot-token search scopes for Slack's Real-time Search API
  * (`assistant.search.context`). Slack accepts these as BOT scopes, so
@@ -35,17 +40,24 @@ export const OPENGENI_SLACK_BOT_SEARCH_SCOPES = [
 /**
  * Scopes requested by the managed and generated self-hosted manifests.
  *
- * `reactions:read` and the bot search scopes are deliberately not part of the
+ * `reactions:read`, `files:write`, and the bot search scopes are not part of the
  * base eligibility contract: legacy installations may continue using existing
  * Slack interactions and tools while the reaction setting stays disabled, bot
- * search stays unavailable, and the UI asks an admin to reinstall.
+ * search and file delivery stay unavailable, and the tools ask an admin to reinstall.
  */
 export const OPENGENI_SLACK_BOT_REQUESTED_SCOPES = [
   ...OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
   OPENGENI_SLACK_REACTION_REQUIRED_SCOPE,
-  ...OPENGENI_SLACK_BOT_SEARCH_SCOPES,
+  OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE,
 ] 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",
@@ -56,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;
 
@@ -92,6 +78,7 @@ export type OpenGeniSlackBotManifestOptions = Readonly<{
   botDisplayName?: string;
   slashCommand?: string;
   shortcutName?: string;
+  accessMode?: "limited" | "full";
 }>;
 
 function normalizedSlackManifestText(
@@ -134,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,
   );
@@ -160,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`,
         },
@@ -168,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",
         },
@@ -180,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],
       },
     },
@@ -202,16 +189,21 @@ export function buildOpenGeniSlackBotManifest(
 }
 
 /**
- * Optional bot grants that remain inside the shipped bot's read/identity
- * boundary. Every other unrequired scope fails closed, including unknown future
+ * Optional bot grants used by the shipped read/identity and task-file-delivery
+ * surfaces. Every other unrequired scope fails closed, including unknown future
  * Slack scopes, so verification, core routing, and UI eligibility cannot drift.
  */
 export const OPENGENI_SLACK_BOT_SAFE_OPTIONAL_SCOPES = [
   "team:read",
   OPENGENI_SLACK_REACTION_REQUIRED_SCOPE,
+  OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE,
   ...OPENGENI_SLACK_BOT_SEARCH_SCOPES,
 ] as const;
 
+export function hasOpenGeniSlackFileUploadScope(grantedScopes: readonly string[]): boolean {
+  return grantedScopes.includes(OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE);
+}
+
 export function hasOpenGeniSlackBotSearchScopes(grantedScopes: readonly string[]): boolean {
   return OPENGENI_SLACK_BOT_SEARCH_SCOPES.every((scope) => grantedScopes.includes(scope));
 }