@opengeni/contracts 0.50.0 → 1.0.0

package/dist/skills.d.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+export { parseSkillFrontmatter, readSkillMetadata } from "./skill-metadata.js";
+export * from "./skill-files.js";
+/** Files are UTF-8 text, relative to the Skill root. No executable authority. */
+export declare const SkillFile: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type SkillFile = z.infer<typeof SkillFile>;
+export declare const SkillActor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"service">;
+    subjectId: z.ZodString;
+    principalKind: z.ZodEnum<{
+        api_key: "api_key";
+        configured_key: "configured_key";
+        service: "service";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"human">;
+    subjectId: z.ZodString;
+    principalKind: z.ZodLiteral<"human_session">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"agent">;
+    sessionId: z.ZodUUID;
+    turnId: z.ZodUUID;
+    attemptId: z.ZodUUID;
+    executionGeneration: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+export type SkillActor = z.infer<typeof SkillActor>;
+export type SkillScope = "workspace" | "organization" | "user";
+export type SkillWriteContext = {
+    accountId: string;
+    workspaceId: string;
+    actor: SkillActor;
+};
+export type SkillSaveInput = SkillWriteContext & {
+    operationId: string;
+    skillId: string;
+    expectedRevisionId: string | null;
+    expectedScopeVersion: number;
+    stableKey: string;
+    files: SkillFile[];
+    scope?: SkillScope;
+    reason: string;
+};
+export type SkillRevisionInput = SkillWriteContext & {
+    removalOperationId?: string | undefined;
+    operationId: string;
+    skillId: string;
+    revisionId: string;
+    expectedRevisionId: string | null;
+    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 declare const SkillReviewReference: z.ZodObject<{
+    removalOperationId: z.ZodOptional<z.ZodUUID>;
+    sourceOperationId: z.ZodUUID;
+    skillId: z.ZodUUID;
+    revisionId: z.ZodUUID;
+    expectedRevisionId: z.ZodNullable<z.ZodUUID>;
+    expectedScopeVersion: z.ZodNumber;
+}, z.core.$strip>;
+export type SkillReviewReference = z.infer<typeof SkillReviewReference>;
+export declare function skillReviewHumanInput(skillReview: SkillReviewReference): {
+    questions: {
+        id: string;
+        kind: "single_select";
+        label: string;
+        prompt: string;
+        helpText: string;
+        options: {
+            id: string;
+            label: string;
+        }[];
+        required: boolean;
+        allowOther: boolean;
+        skillReview: {
+            removalOperationId?: string | undefined;
+            sourceOperationId: string;
+            skillId: string;
+            revisionId: string;
+            expectedRevisionId: string | null;
+            expectedScopeVersion: number;
+        };
+    }[];
+};
+export declare const SkillWriteReceipt: z.ZodObject<{
+    removed: z.ZodOptional<z.ZodBoolean>;
+    operationId: z.ZodUUID;
+    skillId: z.ZodUUID;
+    revisionId: z.ZodUUID;
+    outcome: z.ZodEnum<{
+        applied: "applied";
+        pending: "pending";
+        preserved: "preserved";
+    }>;
+    decision: z.ZodOptional<z.ZodLiteral<"rejected">>;
+    pendingReason: z.ZodOptional<z.ZodEnum<{
+        approval: "approval";
+        source_finalization: "source_finalization";
+    }>>;
+    skillReview: z.ZodOptional<z.ZodObject<{
+        removalOperationId: z.ZodOptional<z.ZodUUID>;
+        sourceOperationId: z.ZodUUID;
+        skillId: z.ZodUUID;
+        revisionId: z.ZodUUID;
+        expectedRevisionId: z.ZodNullable<z.ZodUUID>;
+        expectedScopeVersion: z.ZodNumber;
+    }, z.core.$strip>>;
+    replayed: z.ZodBoolean;
+}, z.core.$strip>;
+export type SkillWriteReceipt = z.infer<typeof SkillWriteReceipt>;
+export declare const SkillPublicationReceipt: z.ZodObject<{
+    removed: z.ZodOptional<z.ZodBoolean>;
+    operationId: z.ZodUUID;
+    skillId: z.ZodUUID;
+    revisionId: z.ZodUUID;
+    outcome: z.ZodEnum<{
+        applied: "applied";
+        pending: "pending";
+        preserved: "preserved";
+    }>;
+    decision: z.ZodOptional<z.ZodLiteral<"rejected">>;
+    pendingReason: z.ZodOptional<z.ZodEnum<{
+        approval: "approval";
+        source_finalization: "source_finalization";
+    }>>;
+    skillReview: z.ZodOptional<z.ZodObject<{
+        removalOperationId: z.ZodOptional<z.ZodUUID>;
+        sourceOperationId: z.ZodUUID;
+        skillId: z.ZodUUID;
+        revisionId: z.ZodUUID;
+        expectedRevisionId: z.ZodNullable<z.ZodUUID>;
+        expectedScopeVersion: z.ZodNumber;
+    }, z.core.$strip>>;
+    replayed: z.ZodBoolean;
+    sourceOperationId: z.ZodUUID;
+    activationEventId: z.ZodNullable<z.ZodUUID>;
+}, z.core.$strip>;
+export type SkillPublicationReceipt = z.infer<typeof SkillPublicationReceipt>;
+export declare const SkillSourceReleaseReceipt: z.ZodObject<{
+    skillId: z.ZodUUID;
+    revisionId: z.ZodNullable<z.ZodUUID>;
+    disposition: z.ZodEnum<{
+        deactivated: "deactivated";
+        inactive: "inactive";
+        preserved: "preserved";
+    }>;
+    eventId: z.ZodNullable<z.ZodUUID>;
+    warning: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SkillSourceReleaseReceipt = z.infer<typeof SkillSourceReleaseReceipt>;
+export type SkillRecord = {
+    removalOperationId?: string | null;
+    activationMode: "workspace_managed" | "session_selected";
+    pendingRevisionIds: string[];
+    id: string;
+    stableKey: string;
+    scope: SkillScope;
+    scopeVersion: number;
+    status: string;
+    activeRevisionId: string | null;
+    revisionId: string | null;
+    title: string | null;
+    description: string | null;
+    contentHash: string | null;
+    files: SkillFile[];
+    source: {
+        pluginId: string;
+        facetKey: string;
+        skillFacetId: string;
+    } | null;
+};

package/dist/slack-bot-scopes.d.ts

@@ -1,52 +1,75 @@
 export declare const OPENGENI_SLACK_BOT_REQUIRED_SCOPES: readonly ["app_mentions:read", "canvases:read", "channels:history", "channels:read", "chat:write", "commands", "files:read", "groups:history", "groups:read", "im:history", "im:read", "im:write", "mpim:history", "mpim:read", "users:read"];
 /** Read-only scope needed only for the optional emoji-reaction summon surface. */
 export declare const OPENGENI_SLACK_REACTION_REQUIRED_SCOPE: "reactions:read";
+/** Optional grant for explicit retained-file delivery to a task's Slack thread. */
+export declare const OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE: "files:write";
+/**
+ * Bot-token search scopes for Slack's Real-time Search API
+ * (`assistant.search.context`). Slack accepts these as BOT scopes, so
+ * workspace-wide public search runs under the bot identity and never needs a
+ * human proxy token. Private-channel, DM, and MPIM search remain user-token
+ * only and belong exclusively to the personal hosted-MCP grant.
+ */
+export declare const OPENGENI_SLACK_BOT_SEARCH_SCOPES: readonly ["search:read.public", "search:read.files", "search:read.users"];
 /**
  * Scopes requested by the managed and generated self-hosted manifests.
  *
- * `reactions:read` is deliberately not part of the base eligibility contract:
- * legacy installations may continue using existing Slack interactions and
- * tools while the reaction setting stays disabled and the UI asks an admin to
- * reinstall.
+ * `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 and file delivery stay unavailable, and the tools ask an admin to reinstall.
  */
-export declare const OPENGENI_SLACK_BOT_REQUESTED_SCOPES: readonly ["app_mentions:read", "canvases:read", "channels:history", "channels:read", "chat:write", "commands", "files:read", "groups:history", "groups:read", "im:history", "im:read", "im:write", "mpim:history", "mpim:read", "users:read", "reactions:read"];
-export declare const OPENGENI_SLACK_BOT_EVENTS: readonly ["app_mention", "message.channels", "message.groups", "message.im", "message.mpim", "reaction_added"];
-/** Full user-token scope set for every tool currently exposed by Slack's hosted MCP server. */
-export declare const OPENGENI_SLACK_MCP_USER_SCOPES: readonly ["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"];
+export declare const OPENGENI_SLACK_BOT_REQUESTED_SCOPES: readonly ["app_mentions:read", "canvases:read", "channels:history", "channels:read", "chat:write", "commands", "files:read", "groups:history", "groups:read", "im:history", "im:read", "im:write", "mpim:history", "mpim:read", "users:read", "reactions:read", "files:write"];
+export declare function openGeniSlackBotRequestedScopes(mode?: "limited" | "full"): string[];
+export declare const OPENGENI_SLACK_BOT_EVENTS: readonly ["app_home_opened", "app_mention", "message.channels", "message.groups", "message.im", "message.mpim", "reaction_added"];
+/** User grants required by the reviewed Slack API MCP tools. */
+export declare const OPENGENI_SLACK_MCP_USER_SCOPES: readonly ["channels:read", "groups:read", "im:read", "mpim:read", "channels:history", "groups:history", "im:history", "mpim:history", "users:read", "im:write", "chat:write"];
 export declare const OPENGENI_MANAGED_PUBLIC_BASE_URL: "https://app.opengeni.ai";
+export type OpenGeniSlackBotManifestOptions = Readonly<{
+    appName?: string;
+    botDisplayName?: string;
+    slashCommand?: string;
+    shortcutName?: string;
+    accessMode?: "limited" | "full";
+}>;
 /** Canonical managed/self-hosted Slack app manifest. Slack accepts JSON manifests. */
-export declare function buildOpenGeniSlackBotManifest(publicBaseUrl: string): {
+export declare function buildOpenGeniSlackBotManifest(publicBaseUrl: string, options?: OpenGeniSlackBotManifestOptions): {
     readonly display_information: {
-        readonly name: "OpenGeni";
+        readonly name: string;
     };
     readonly features: {
+        readonly app_home: {
+            readonly home_tab_enabled: true;
+            readonly messages_tab_enabled: true;
+            readonly messages_tab_read_only_enabled: false;
+        };
         readonly bot_user: {
-            readonly display_name: "OpenGeni";
+            readonly display_name: string;
             readonly always_online: false;
         };
         readonly slash_commands: readonly [{
-            readonly command: "/opengeni";
-            readonly description: "Start an OpenGeni task in this channel";
+            readonly command: string;
+            readonly description: "Start an Opengeni task in this channel";
             readonly should_escape: false;
             readonly url: `${string}/v1/integrations/slack/commands`;
         }];
         readonly shortcuts: readonly [{
             readonly callback_id: "opengeni_message";
-            readonly description: "Start an OpenGeni task from this Slack message";
-            readonly name: "Open in OpenGeni";
+            readonly description: "Start an Opengeni task from this Slack message";
+            readonly name: string;
             readonly type: "message";
         }];
     };
     readonly oauth_config: {
         readonly redirect_urls: readonly [`${string}/v1/integrations/oauth/callback`, `${string}/v1/integrations/slack/callback`];
         readonly scopes: {
-            readonly bot: readonly ["app_mentions:read", "canvases:read", "channels:history", "channels:read", "chat:write", "commands", "files:read", "groups:history", "groups:read", "im:history", "im:read", "im:write", "mpim:history", "mpim:read", "users:read", "reactions:read"];
-            readonly user: readonly ["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"];
+            readonly bot: string[];
+            readonly user: readonly ["channels:read", "groups:read", "im:read", "mpim:read", "channels:history", "groups:history", "im:history", "mpim:history", "users:read", "im:write", "chat:write"];
         };
     };
     readonly settings: {
         readonly event_subscriptions: {
-            readonly bot_events: readonly ["app_mention", "message.channels", "message.groups", "message.im", "message.mpim", "reaction_added"];
+            readonly bot_events: readonly ["app_home_opened", "app_mention", "message.channels", "message.groups", "message.im", "message.mpim", "reaction_added"];
             readonly request_url: `${string}/v1/integrations/slack/events`;
         };
         readonly interactivity: {
@@ -60,11 +83,13 @@ export declare function buildOpenGeniSlackBotManifest(publicBaseUrl: string): {
     };
 };
 /**
- * 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 declare const OPENGENI_SLACK_BOT_SAFE_OPTIONAL_SCOPES: readonly ["team:read", "reactions:read"];
+export declare const OPENGENI_SLACK_BOT_SAFE_OPTIONAL_SCOPES: readonly ["team:read", "reactions:read", "files:write", "search:read.public", "search:read.files", "search:read.users"];
+export declare function hasOpenGeniSlackFileUploadScope(grantedScopes: readonly string[]): boolean;
+export declare function hasOpenGeniSlackBotSearchScopes(grantedScopes: readonly string[]): boolean;
 /** @deprecated Use evaluateOpenGeniSlackBotScopes; an allowlist is the policy. */
 export declare const OPENGENI_SLACK_BOT_FORBIDDEN_SCOPES: readonly ["channels:join", "chat:write.public"];
 export type OpenGeniSlackBotScopePolicy = {

package/dist/slack-bot-scopes.js

@@ -5,13 +5,19 @@ import {
   OPENGENI_SLACK_BOT_REQUESTED_SCOPES,
   OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
   OPENGENI_SLACK_BOT_SAFE_OPTIONAL_SCOPES,
+  OPENGENI_SLACK_BOT_SEARCH_SCOPES,
+  OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE,
   OPENGENI_SLACK_MCP_USER_SCOPES,
   OPENGENI_SLACK_REACTION_REQUIRED_SCOPE,
   areOpenGeniSlackBotScopesAccepted,
   buildOpenGeniSlackBotManifest,
   evaluateOpenGeniSlackBotScopes,
-  hasOpenGeniSlackReactionScope
-} from "./chunk-5UDNP7AO.js";
+  hasOpenGeniSlackBotSearchScopes,
+  hasOpenGeniSlackFileUploadScope,
+  hasOpenGeniSlackReactionScope,
+  openGeniSlackBotRequestedScopes
+} from "./chunk-FZ6BXQHL.js";
+import "./chunk-MZLBPKFE.js";
 export {
   OPENGENI_MANAGED_PUBLIC_BASE_URL,
   OPENGENI_SLACK_BOT_EVENTS,
@@ -19,11 +25,16 @@ export {
   OPENGENI_SLACK_BOT_REQUESTED_SCOPES,
   OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
   OPENGENI_SLACK_BOT_SAFE_OPTIONAL_SCOPES,
+  OPENGENI_SLACK_BOT_SEARCH_SCOPES,
+  OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE,
   OPENGENI_SLACK_MCP_USER_SCOPES,
   OPENGENI_SLACK_REACTION_REQUIRED_SCOPE,
   areOpenGeniSlackBotScopesAccepted,
   buildOpenGeniSlackBotManifest,
   evaluateOpenGeniSlackBotScopes,
-  hasOpenGeniSlackReactionScope
+  hasOpenGeniSlackBotSearchScopes,
+  hasOpenGeniSlackFileUploadScope,
+  hasOpenGeniSlackReactionScope,
+  openGeniSlackBotRequestedScopes
 };
 //# sourceMappingURL=slack-bot-scopes.js.map

package/dist/slack-rest-mcp.d.ts

@@ -0,0 +1,31 @@
+/** The catalog and OAuth identity stay stable while calls use the ordinary Web API. */
+export declare const OFFICIAL_SLACK_MCP_URL = "https://mcp.slack.com/mcp";
+export declare const SLACK_REST_API_BASE = "https://slack.com/api/";
+export declare const OPENGENI_SLACK_REST_USER_SCOPES: readonly ["channels:read", "groups:read", "im:read", "mpim:read", "channels:history", "groups:history", "im:history", "mpim:history", "users:read", "im:write", "chat:write"];
+/** Slack returns comma-delimited scopes, including in existing saved grants. */
+export declare function normalizeSlackScopes(scopes: readonly string[] | string | undefined | null): string[];
+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;
+    };
+};
+/** Static reviewed pilot surface. Each call reads only one explicitly requested page. */
+export declare const SLACK_REST_MCP_TOOLS: SlackRestMcpTool[];
+export declare function slackRestMcpToolsForScopes(scopes: readonly string[] | string): SlackRestMcpTool[];
+export declare const SLACK_CONVERSATION_READ_SCOPE_BY_TYPE: {
+    readonly public_channel: "channels:read";
+    readonly private_channel: "groups:read";
+    readonly im: "im:read";
+    readonly mpim: "mpim:read";
+};

package/dist/slack-rest-mcp.js

@@ -0,0 +1,19 @@
+import {
+  OFFICIAL_SLACK_MCP_URL,
+  OPENGENI_SLACK_REST_USER_SCOPES,
+  SLACK_CONVERSATION_READ_SCOPE_BY_TYPE,
+  SLACK_REST_API_BASE,
+  SLACK_REST_MCP_TOOLS,
+  normalizeSlackScopes,
+  slackRestMcpToolsForScopes
+} from "./chunk-MZLBPKFE.js";
+export {
+  OFFICIAL_SLACK_MCP_URL,
+  OPENGENI_SLACK_REST_USER_SCOPES,
+  SLACK_CONVERSATION_READ_SCOPE_BY_TYPE,
+  SLACK_REST_API_BASE,
+  SLACK_REST_MCP_TOOLS,
+  normalizeSlackScopes,
+  slackRestMcpToolsForScopes
+};
+//# sourceMappingURL=slack-rest-mcp.js.map

package/dist/slack-rest-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/spreadsheet-artifact-commands.d.ts

@@ -1,10 +1,11 @@
+import { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "./editable-artifact-versions.js";
 /**
  * Canonical, identity-free spreadsheet mutation commands nested inside
  * `OGATX001`. Artifact, actor, transaction, delivery, and causal identity must
  * never be added here: the outer authored-intent envelope is their sole wire
  * authority.
  */
-export declare const SPREADSHEET_ARTIFACT_COMMAND_VERSION: 1;
+export { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "./editable-artifact-versions.js";
 export declare const SPREADSHEET_ARTIFACT_COMMAND_MAX_BYTES: number;
 export declare const SPREADSHEET_ARTIFACT_COMMAND_MAX_COMMANDS = 4096;
 export declare const SPREADSHEET_ARTIFACT_COMMAND_MAX_CELLS = 1000000;
@@ -53,7 +54,6 @@ export type SpreadsheetDateValue = Readonly<{
 export type SpreadsheetCellScalar = null | boolean | number | string | SpreadsheetDateValue | SpreadsheetFormulaError;
 export type SpreadsheetFormulaCell = Readonly<{
     formula: string;
-    cached: SpreadsheetCellScalar;
 }>;
 export type SpreadsheetCellInput = SpreadsheetCellScalar | SpreadsheetFormulaCell;
 export type SpreadsheetCreateSheetCommand = Readonly<{
@@ -98,4 +98,3 @@ export declare function encodeSpreadsheetArtifactCommandBatch(input: Spreadsheet
 export declare function decodeSpreadsheetArtifactCommandBatch(bytes: Uint8Array): SpreadsheetArtifactCommandBatch;
 /** Decodes, re-encodes, and proves byte-for-byte canonicality. */
 export declare function assertCanonicalSpreadsheetArtifactCommandBytes(bytes: Uint8Array): Uint8Array;
-export {};

package/dist/spreadsheet-artifact-commands.js

@@ -3,14 +3,16 @@ import {
   SPREADSHEET_ARTIFACT_COMMAND_MAX_CELLS,
   SPREADSHEET_ARTIFACT_COMMAND_MAX_COMMANDS,
   SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES,
-  SPREADSHEET_ARTIFACT_COMMAND_VERSION,
   SPREADSHEET_ARTIFACT_SHEET_NAME_MAX_UTF16_UNITS,
   assertCanonicalSpreadsheetArtifactCommandBytes,
   decodeSpreadsheetArtifactCommandBatch,
   editableArtifactStableId,
   encodeSpreadsheetArtifactCommandBatch,
   spreadsheetSheetId
-} from "./chunk-LSB7GRLG.js";
+} from "./chunk-TXTQIYCV.js";
+import {
+  SPREADSHEET_ARTIFACT_COMMAND_VERSION
+} from "./chunk-PX3VCKAU.js";
 export {
   SPREADSHEET_ARTIFACT_COMMAND_MAX_BYTES,
   SPREADSHEET_ARTIFACT_COMMAND_MAX_CELLS,

package/dist/spreadsheet-artifact-query.js

@@ -20,8 +20,9 @@ import {
   encodeSpreadsheetMetadataKernelQuery,
   encodeSpreadsheetViewportKernelProjection,
   encodeSpreadsheetViewportKernelQuery
-} from "./chunk-CADSX6UN.js";
-import "./chunk-LSB7GRLG.js";
+} from "./chunk-Y3KNXVTD.js";
+import "./chunk-TXTQIYCV.js";
+import "./chunk-PX3VCKAU.js";
 export {
   SPREADSHEET_ARTIFACT_METADATA_MAX_SHEETS,
   SPREADSHEET_ARTIFACT_METADATA_MIN_RESPONSE_BYTES,