@opengeni/contracts 0.50.0 → 1.0.0

package/src/slack-rest-mcp.ts

@@ -0,0 +1,194 @@
+/** 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/";
+
+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",
+  "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_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_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/spreadsheet-artifact-commands.ts

@@ -2,6 +2,7 @@ import {
   canonicalSpreadsheetDateFromMilliseconds,
   canonicalSpreadsheetDateMilliseconds,
 } from "./spreadsheet-artifact-date";
+import { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "./editable-artifact-versions";
 
 /**
  * Canonical, identity-free spreadsheet mutation commands nested inside
@@ -10,14 +11,14 @@ import {
  * authority.
  */
 
-export const SPREADSHEET_ARTIFACT_COMMAND_VERSION = 1 as const;
+export { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "./editable-artifact-versions";
 export const SPREADSHEET_ARTIFACT_COMMAND_MAX_BYTES = 4 * 1024 * 1024;
 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;
 
-const MAGIC = new TextEncoder().encode("OGASC001");
+const MAGIC = new TextEncoder().encode("OGASC002");
 const HEADER_BYTES = 8 + 2 + 2 + 4 + 8;
 const CHECKSUM_BYTES = 8;
 const textEncoder = new TextEncoder();
@@ -78,7 +79,6 @@ export type SpreadsheetCellScalar =
   | SpreadsheetFormulaError;
 export type SpreadsheetFormulaCell = Readonly<{
   formula: string;
-  cached: SpreadsheetCellScalar;
 }>;
 export type SpreadsheetCellInput = SpreadsheetCellScalar | SpreadsheetFormulaCell;
 
@@ -491,7 +491,7 @@ function batchRecord(input: unknown): SpreadsheetArtifactCommandBatch {
   const batch = plainRecord(input, "spreadsheet command batch");
   exactKeys(batch, ["commands", "version"], "spreadsheet command batch");
   if (batch.version !== SPREADSHEET_ARTIFACT_COMMAND_VERSION) {
-    throw new TypeError("spreadsheet command batch version must be 1");
+    throw new TypeError("spreadsheet command batch version must be 2");
   }
   if (!Array.isArray(batch.commands)) throw new TypeError("commands must be an array");
   if (
@@ -770,13 +770,12 @@ class BinaryWriter {
   cell(value: unknown): void {
     if (isFormulaCell(value)) {
       const cell = plainRecord(value, "formula cell");
-      exactKeys(cell, ["cached", "formula"], "formula cell");
+      exactKeys(cell, ["formula"], "formula cell");
       if (typeof cell.formula !== "string" || cell.formula.length === 0) {
         throw new TypeError("formula source must be a nonempty string");
       }
       this.u8(1);
       this.string(cell.formula, SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES);
-      this.scalar(cell.cached);
       return;
     }
     this.u8(0);
@@ -902,12 +901,12 @@ class BinaryReader {
   cell(): SpreadsheetCellInput {
     const formulaTag = this.u8();
     if (formulaTag > 1) throw new TypeError("spreadsheet formula presence tag is invalid");
-    const formula =
-      formulaTag === 1
-        ? this.nonemptyFormula(this.string(SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES))
-        : null;
-    const cached = this.scalar();
-    return formula === null ? cached : Object.freeze({ formula, cached });
+    if (formulaTag === 1) {
+      return Object.freeze({
+        formula: this.nonemptyFormula(this.string(SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES)),
+      });
+    }
+    return this.scalar();
   }
 
   done(message: string): void {
@@ -981,7 +980,7 @@ function isFormulaError(value: unknown): value is SpreadsheetFormulaError {
     typeof value === "object" &&
     value !== null &&
     !Array.isArray(value) &&
-    typeof (value as Record<string, unknown>).error === "string"
+    Object.hasOwn(value, "error")
   );
 }
 

package/src/subscription-account-pools.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { ClaudeSubscriptionUsage } from "./claude-subscription-usage";
+
+/** Shared, secret-free account list contract for native subscription pools. */
+export const SubscriptionAccountSummary = z.object({
+  id: z.string().uuid(),
+  scope: z.enum(["organization", "workspace", "user"]),
+  subject: z.string().min(1),
+  email: z.string().email().nullable(),
+  label: z.string().nullable(),
+  plan: z.string().nullable(),
+  status: z.enum(["active", "needs_relogin", "error", "disabled"]),
+  active: z.boolean(),
+  expiresAt: z.string().datetime().nullable(),
+  lastRefreshAt: z.string().datetime().nullable(),
+  lastError: z.string().nullable(),
+  allocatorEnabled: z.boolean(),
+  allocatorVersion: z.number().int().positive(),
+  allocatorUpdatedAt: z.string().datetime().nullable(),
+});
+export type SubscriptionAccountSummary = z.infer<typeof SubscriptionAccountSummary>;
+export const SubscriptionPoolSettings = z
+  .object({
+    rotationEnabled: z.boolean(),
+    rotationStrategy: z.literal("sharded"),
+    activeCredentialId: z.string().uuid().nullable(),
+  })
+  .strict();
+export type SubscriptionPoolSettings = z.infer<typeof SubscriptionPoolSettings>;
+export const ClaudeSubscriptionAccount = SubscriptionAccountSummary.extend({
+  version: z.number().int().positive(),
+  usage: ClaudeSubscriptionUsage.optional(),
+}).strict();
+export type ClaudeSubscriptionAccount = z.infer<typeof ClaudeSubscriptionAccount>;
+export const ClaudeSubscriptionAccountsResponse = z
+  .object({
+    accounts: z.array(ClaudeSubscriptionAccount),
+    activeAccountId: z.string().uuid().nullable(),
+    source: z.enum(["organization", "workspace", "user"]),
+    organizationId: z.string().uuid(),
+    settings: SubscriptionPoolSettings,
+  })
+  .strict();
+export type ClaudeSubscriptionAccountsResponse = z.infer<typeof ClaudeSubscriptionAccountsResponse>;

package/src/task-notes.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 
 export const TASK_NOTE_TEXT_MAX_BYTES = 4_096;
 export const TASK_NOTE_REASON_MAX_BYTES = 2_048;
-export const TASK_NOTE_MAX_LIFETIME_DAYS = 30;
+export const TASK_NOTE_MAX_LIFETIME_DAYS = 90;
 export const TASK_NOTE_ACTIVE_RECORD_CAP = 500;
 export const TASK_NOTE_LIST_DEFAULT_LIMIT = 10;
 export const TASK_NOTE_LIST_MAX_LIMIT = 20;
@@ -77,6 +77,19 @@ export const TaskNoteMutationResult = z.object({
 });
 export type TaskNoteMutationResult = z.infer<typeof TaskNoteMutationResult>;
 
+/** Atomic correction lineage: archive one exact v1 note and create one v1 replacement. */
+export const TaskNoteReplacementResult = z.object({
+  operationId: z.string().uuid(),
+  inputHash: z.string().regex(/^[0-9a-f]{64}$/),
+  replaces: z.object({
+    noteId: z.string().uuid(),
+    archivedVersion: z.literal(2),
+  }),
+  replacement: TaskNote,
+  replayed: z.boolean(),
+});
+export type TaskNoteReplacementResult = z.infer<typeof TaskNoteReplacementResult>;
+
 export const TaskNoteListResponse = z
   .object({
     notes: z.array(TaskNote).max(TASK_NOTE_LIST_MAX_LIMIT),

package/src/tool-catalog.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 export const ATTEMPT_TOOL_CATALOG_VERSION = 1 as const;
+export const TOOL_GATEWAY_CATALOG_VERSION = 1 as const;
 export const ATTEMPT_TOOL_CATALOG_MAX_ENTRIES = 4_096;
 export const ATTEMPT_TOOL_CATALOG_MAX_BYTES = 16 * 1024 * 1024;
 export const ATTEMPT_TOOL_CATALOG_MAX_PATH_SEGMENTS = 8;
@@ -43,6 +44,10 @@ export const AttemptToolIdentity = z
   .strict();
 export type AttemptToolIdentity = z.infer<typeof AttemptToolIdentity>;
 
+/** Protocol-neutral tool identity shared by MCP, HTTP/SDK, agents, and Codemode. */
+export const ToolGatewayIdentity = AttemptToolIdentity;
+export type ToolGatewayIdentity = AttemptToolIdentity;
+
 export const AttemptToolCatalogIcon = z
   .object({
     src: z.string().min(1).max(8_192),
@@ -69,6 +74,16 @@ export type AttemptToolAnnotations = z.infer<typeof AttemptToolAnnotations>;
 export const AttemptToolJsonSchema = jsonObject;
 export type AttemptToolJsonSchema = z.infer<typeof AttemptToolJsonSchema>;
 
+/** Presentation only; never parsed as execution or account authority. */
+export const ToolDisplayMetadata = z
+  .object({
+    toolName: toolIdentifier,
+    title: z.string().min(1).max(512).optional(),
+    accountLabel: z.string().min(1).max(1024).optional(),
+  })
+  .strict();
+export type ToolDisplayMetadata = z.infer<typeof ToolDisplayMetadata>;
+
 export const AttemptToolCatalogEntry = z
   .object({
     identity: AttemptToolIdentity,
@@ -88,6 +103,73 @@ export const AttemptToolCatalogEntry = z
   .strict();
 export type AttemptToolCatalogEntry = z.infer<typeof AttemptToolCatalogEntry>;
 
+/** One canonical gateway entry. Adapter-specific names are projections, never authority. */
+export const ToolGatewayCatalogEntry = AttemptToolCatalogEntry;
+export type ToolGatewayCatalogEntry = AttemptToolCatalogEntry;
+
+export const ToolGatewayCatalog = z
+  .object({
+    version: z.literal(TOOL_GATEWAY_CATALOG_VERSION),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    generation: z.number().int().positive(),
+    digest: sha256,
+    createdAt: z.string().datetime({ offset: true }),
+    entries: z.array(ToolGatewayCatalogEntry).max(ATTEMPT_TOOL_CATALOG_MAX_ENTRIES),
+  })
+  .strict()
+  .superRefine((catalog, context) => {
+    const identities = new Set<string>();
+    const modelNames = new Set<string>();
+    const toolPaths = new Set<string>();
+    for (const [index, entry] of catalog.entries.entries()) {
+      const identity = `${entry.identity.serverId}\u0000${entry.identity.toolName}`;
+      const toolPath = entry.codemodePath.join(".");
+      if (identities.has(identity)) {
+        context.addIssue({
+          code: "custom",
+          path: ["entries", index, "identity"],
+          message: "duplicate tool identity",
+        });
+      }
+      if (modelNames.has(entry.modelName)) {
+        context.addIssue({
+          code: "custom",
+          path: ["entries", index, "modelName"],
+          message: "duplicate model tool name",
+        });
+      }
+      if (toolPaths.has(toolPath)) {
+        context.addIssue({
+          code: "custom",
+          path: ["entries", index, "codemodePath"],
+          message: "duplicate tool path",
+        });
+      }
+      identities.add(identity);
+      modelNames.add(entry.modelName);
+      toolPaths.add(toolPath);
+    }
+  });
+export type ToolGatewayCatalog = z.infer<typeof ToolGatewayCatalog>;
+
+export const ToolGatewayCaller = z
+  .object({
+    kind: z.enum(["model", "codemode", "http", "mcp", "browser"]),
+    subjectId: z.string().min(1).max(1_024),
+  })
+  .strict();
+export type ToolGatewayCaller = z.infer<typeof ToolGatewayCaller>;
+
+/**
+ * MCP request `_meta` key naming the attempt surface that issued a call to the
+ * first-party server: `model` for a direct model tool call, `codemode` for a
+ * Codemode script. Only the worker's own tool gateway sets it, and only for the
+ * first-party server. A read reached the model's context only when it says
+ * `model`; a Codemode script may keep the output to itself.
+ */
+export const FIRST_PARTY_MCP_CALLER_META_KEY = "opengeniCaller";
+
 export const AttemptToolCatalog = z
   .object({
     version: z.literal(ATTEMPT_TOOL_CATALOG_VERSION),
@@ -251,6 +333,79 @@ export const AttemptToolResult = z
   .loose();
 export type AttemptToolResult = z.infer<typeof AttemptToolResult>;
 
+export const ToolGatewayResult = AttemptToolResult;
+export type ToolGatewayResult = AttemptToolResult;
+
+export const ToolGatewayCallRequest = z
+  .object({
+    operationId: z.string().uuid().optional(),
+    catalogDigest: sha256,
+    identity: ToolGatewayIdentity,
+    arguments: jsonObject,
+    /** Host-owned Site context. Publisher-controlled iframe code cannot set it. */
+    siteArtifactId: z.string().uuid().optional(),
+    siteVersionId: z.string().uuid().optional(),
+    /** Opaque, server-issued, single-use capability for an approval-required call. */
+    approvalToken: z
+      .string()
+      .regex(/^ogta_[A-Za-z0-9_-]{43}$/u)
+      .optional(),
+  })
+  .strict()
+  .superRefine(requireCompleteSiteToolContext);
+export type ToolGatewayCallRequest = z.infer<typeof ToolGatewayCallRequest>;
+
+export const ToolGatewayApprovalRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    catalogDigest: sha256,
+    identity: ToolGatewayIdentity,
+    arguments: jsonObject,
+  })
+  .strict();
+export type ToolGatewayApprovalRequest = z.infer<typeof ToolGatewayApprovalRequest>;
+
+export const ToolGatewayApprovalResponse = z
+  .object({
+    operationId: z.string().uuid(),
+    catalogDigest: sha256,
+    identity: ToolGatewayIdentity,
+    approvalToken: z.string().regex(/^ogta_[A-Za-z0-9_-]{43}$/u),
+    expiresAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+export type ToolGatewayApprovalResponse = z.infer<typeof ToolGatewayApprovalResponse>;
+
+export const ToolGatewayCallResponse = z
+  .object({
+    operationId: z.string().uuid(),
+    catalogDigest: sha256,
+    result: ToolGatewayResult,
+  })
+  .strict();
+export type ToolGatewayCallResponse = z.infer<typeof ToolGatewayCallResponse>;
+
+export const ToolGatewayDeclarationsResponse = z
+  .object({
+    catalogDigest: sha256,
+    moduleSpecifier: z.string().min(1).max(512),
+    source: z.string().max(16 * 1024 * 1024),
+  })
+  .strict();
+export type ToolGatewayDeclarationsResponse = z.infer<typeof ToolGatewayDeclarationsResponse>;
+
+function requireCompleteSiteToolContext(
+  value: { siteArtifactId?: string | undefined; siteVersionId?: string | undefined },
+  context: z.RefinementCtx,
+): void {
+  if ((value.siteArtifactId === undefined) === (value.siteVersionId === undefined)) return;
+  context.addIssue({
+    code: "custom",
+    message: "siteArtifactId and siteVersionId must be provided together",
+    path: [value.siteArtifactId === undefined ? "siteArtifactId" : "siteVersionId"],
+  });
+}
+
 export const CodemodeOperationState = z.enum([
   "queued",
   "running",

package/src/tool-result-spill.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+
+/** Model-visible overflow of one tool result. Exact bytes live on a workspace File. */
+export const TOOL_RESULT_SPILLED_TYPE = "tool_result_spilled" as const;
+export const TOOL_RESULT_SPILL_MEDIA_TYPE = "application/json" as const;
+export const TOOL_RESULT_SPILL_MOUNT_PATH = "tool-results" as const;
+
+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}$/;
+
+export const ToolResultSpilledReceipt = z
+  .object({
+    type: z.literal(TOOL_RESULT_SPILLED_TYPE),
+    sandboxPath: z.string().min(1).max(4_096).nullable(),
+    fileId: z.string().regex(LOWERCASE_UUID),
+    byteSize: z.number().int().positive().safe(),
+    mediaType: z.literal(TOOL_RESULT_SPILL_MEDIA_TYPE),
+  })
+  .strict();
+export type ToolResultSpilledReceipt = z.infer<typeof ToolResultSpilledReceipt>;
+
+export function isToolResultSpilledReceipt(value: unknown): value is ToolResultSpilledReceipt {
+  return ToolResultSpilledReceipt.safeParse(value).success;
+}
+
+export function toolResultSpillSandboxPath(filename: string): string {
+  return `/workspace/${TOOL_RESULT_SPILL_MOUNT_PATH}/${filename}`;
+}
+
+export function toolResultSpillFilename(operationId: string): string {
+  const normalized = operationId.toLowerCase();
+  if (!LOWERCASE_UUID.test(normalized)) {
+    throw new Error("tool result spill filename requires a lowercase UUID operation id");
+  }
+  return `${normalized}.json`;
+}