@opengeni/contracts 0.44.1 → 1.0.0

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`;
+}

package/src/usage-allowances.ts

@@ -0,0 +1,187 @@
+import { z } from "zod";
+
+/** Credit amounts are integer USD micros (1 USD = 1,000,000), never floating-point dollars. */
+export const AllowanceCredits = z.number().int().nonnegative().safe();
+const Version = z.number().int().nonnegative().safe();
+const Timestamp = z.string().datetime({ offset: true });
+const OperationId = z
+  .string()
+  .min(1)
+  .max(256)
+  .refine(
+    (value) =>
+      value.trim().length > 0 &&
+      !value.includes("\0") &&
+      !/[\uD800-\uDFFF]/u.test(value) &&
+      new TextEncoder().encode(value).byteLength <= 256,
+  );
+const SubjectId = z
+  .string()
+  .min(1)
+  .max(1024)
+  .refine((value) => !value.includes("\0"));
+
+/**
+ * A share scales with the current workspace pool, including unexpired grants.
+ * Shares may exceed 1 and their sum may exceed 1: they are ceilings, not reserved
+ * allocations. Concurrent/in-flight calls can overshoot a ceiling; enforcement
+ * happens before the next call, after actual usage is settled.
+ * null removes the override and uses the workspace's memberDefault.
+ */
+export const MemberAllowanceRule = z.union([
+  z.object({ share: z.number().finite().nonnegative() }).strict(),
+  z.object({ credits: AllowanceCredits }).strict(),
+  z.null(),
+]);
+export type MemberAllowanceRule = z.infer<typeof MemberAllowanceRule>;
+
+export const MemberAllowanceDefault = z.union([
+  z.enum(["none", "equal_share"]),
+  z.object({ share: z.number().finite().nonnegative() }).strict(),
+  z.object({ credits: AllowanceCredits }).strict(),
+]);
+export type MemberAllowanceDefault = z.infer<typeof MemberAllowanceDefault>;
+
+const Thresholds = z.array(z.number().finite().positive().max(1)).max(16);
+/** Omitted threshold lists default to [0.8, 1]. Monthly boundaries are UTC. */
+export const WorkspaceAllowanceConfig = z
+  .object({
+    includedCredits: AllowanceCredits,
+    period: z.enum(["monthly", "none"]),
+    anchorDay: z.number().int().min(1).max(31).optional(),
+    memberDefault: MemberAllowanceDefault.optional(),
+    thresholds: z
+      .object({ workspace: Thresholds.optional(), member: Thresholds.optional() })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type WorkspaceAllowanceConfig = z.infer<typeof WorkspaceAllowanceConfig>;
+
+export const WorkspaceAllowance = WorkspaceAllowanceConfig.extend({ version: Version.min(1) });
+export type WorkspaceAllowance = z.infer<typeof WorkspaceAllowance>;
+/**
+ * Lifecycle version survives clear. version=0 means never configured; a null
+ * config with a positive version is cleared. Use this version for recreation.
+ * The existing nullable configuration read remains unchanged.
+ */
+export const WorkspaceAllowanceState = z
+  .object({ version: Version, config: WorkspaceAllowance.nullable() })
+  .strict()
+  .refine((state) => state.config === null || state.config.version === state.version, {
+    message: "Allowance configuration and lifecycle versions must match",
+    path: ["config", "version"],
+  });
+export type WorkspaceAllowanceState = z.infer<typeof WorkspaceAllowanceState>;
+export const SetWorkspaceAllowanceRequest = WorkspaceAllowanceConfig.extend({
+  expectedVersion: Version,
+});
+export type SetWorkspaceAllowanceRequest = z.infer<typeof SetWorkspaceAllowanceRequest>;
+/** Reuse operationId and the exact expectedVersion to recover a lost clear
+ * receipt. A later lifecycle change conflicts; read the state before deciding
+ * on a new mutation, never guess a version or change it for a retry. */
+export const ClearWorkspaceAllowanceRequest = z
+  .object({ expectedVersion: Version.min(1), operationId: OperationId.optional() })
+  .strict();
+export type ClearWorkspaceAllowanceRequest = z.infer<typeof ClearWorkspaceAllowanceRequest>;
+export const ClearWorkspaceAllowanceResponse = z.object({ version: Version.min(1) }).strict();
+export type ClearWorkspaceAllowanceResponse = z.infer<typeof ClearWorkspaceAllowanceResponse>;
+
+/** Reuse the operationId and exact request to recover an uncertain grant response. */
+export const GrantWorkspaceCreditsRequest = z
+  .object({
+    operationId: OperationId,
+    credits: AllowanceCredits.positive(),
+    expiresAt: Timestamp.nullable().optional(),
+  })
+  .strict();
+export type GrantWorkspaceCreditsRequest = z.infer<typeof GrantWorkspaceCreditsRequest>;
+export const WorkspaceCreditGrant = GrantWorkspaceCreditsRequest.extend({
+  remaining: AllowanceCredits,
+  expiresAt: Timestamp.nullable(),
+});
+export type WorkspaceCreditGrant = z.infer<typeof WorkspaceCreditGrant>;
+
+export const SetMemberAllowanceRequest = z
+  .object({
+    rule: MemberAllowanceRule,
+    expectedVersion: Version,
+  })
+  .strict();
+export type SetMemberAllowanceRequest = z.infer<typeof SetMemberAllowanceRequest>;
+export const MemberAllowance = z
+  .object({
+    subjectId: SubjectId,
+    rule: MemberAllowanceRule,
+    version: Version,
+  })
+  .strict();
+export type MemberAllowance = z.infer<typeof MemberAllowance>;
+
+export const UsageAllowancePeriod = z.union([
+  z.literal("current"),
+  z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/),
+]);
+export type UsageAllowancePeriod = z.infer<typeof UsageAllowancePeriod>;
+export const GetUsageRequest = z
+  .object({
+    period: UsageAllowancePeriod.optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+    cursor: z.string().min(1).max(2048).optional(),
+  })
+  .strict();
+export type GetUsageRequest = z.infer<typeof GetUsageRequest>;
+export const GetMyUsageRequest = GetUsageRequest.pick({ period: true });
+export type GetMyUsageRequest = z.infer<typeof GetMyUsageRequest>;
+
+export const UsageAllowanceStatus = z.enum(["ok", "warning", "exhausted"]);
+export type UsageAllowanceStatus = z.infer<typeof UsageAllowanceStatus>;
+export const UsageAllowanceWindow = z
+  .object({
+    start: Timestamp.nullable(),
+    end: Timestamp.nullable(),
+  })
+  .strict();
+export type UsageAllowanceWindow = z.infer<typeof UsageAllowanceWindow>;
+const Usage = z.object({
+  limit: AllowanceCredits.nullable(),
+  used: AllowanceCredits,
+  remaining: z.number().int().safe().nullable(),
+  /** Display this ratio rather than raw USD micros in human-facing products. */
+  fraction: z.number().finite().nonnegative().nullable(),
+  status: UsageAllowanceStatus,
+  resetsAt: Timestamp.nullable(),
+});
+export const WorkspaceAllowanceUsage = Usage.extend({
+  includedCredits: AllowanceCredits,
+  grantsRemaining: AllowanceCredits,
+}).strict();
+export type WorkspaceAllowanceUsage = z.infer<typeof WorkspaceAllowanceUsage>;
+export const MemberAllowanceUsage = Usage.extend({
+  subjectId: SubjectId,
+  externalIdentity: z.object({ source: z.string(), externalId: z.string() }).strict().nullable(),
+  rule: MemberAllowanceRule,
+  version: Version,
+}).strict();
+export type MemberAllowanceUsage = z.infer<typeof MemberAllowanceUsage>;
+/** /usage/me returns only the authenticated subject's member row, never the roster. */
+export const WorkspaceUsageResponse = z
+  .object({
+    period: UsageAllowanceWindow,
+    workspace: WorkspaceAllowanceUsage,
+    members: z.array(MemberAllowanceUsage),
+    nextCursor: z.string().nullable(),
+  })
+  .strict();
+export type WorkspaceUsageResponse = z.infer<typeof WorkspaceUsageResponse>;
+
+export const AllowanceExhaustedRefusal = z
+  .object({
+    code: z.literal("allowance_exhausted"),
+    scope: z.enum(["workspace", "member"]),
+    resetsAt: Timestamp.nullable(),
+    subjectId: SubjectId.optional(),
+    message: z.string(),
+  })
+  .strict();
+export type AllowanceExhaustedRefusal = z.infer<typeof AllowanceExhaustedRefusal>;

package/src/video-generation.ts

@@ -7,6 +7,7 @@ import {
 
 export const VIDEO_GENERATION_SCHEMA_VERSION = 1 as const;
 export const SEEDANCE_2_5_MODEL_ID = "bytedance/seedance-2.5" as const;
+export const GROK_IMAGINE_VIDEO_1_5_MODEL_ID = "xai/grok-imagine-video-1.5" as const;
 
 export const VideoGenerationSourceMode = z.enum([
   "text",
@@ -20,7 +21,11 @@ export type VideoGenerationSourceMode = z.infer<typeof VideoGenerationSourceMode
 export const VideoGenerationResolution = z.enum(["480p", "720p"]);
 export type VideoGenerationResolution = z.infer<typeof VideoGenerationResolution>;
 
-export const VideoGenerationFundingSource = z.enum(["opengeni_credits", "workspace_gateway"]);
+export const VideoGenerationFundingSource = z.enum([
+  "opengeni_credits",
+  "workspace_gateway",
+  "supergrok_subscription",
+]);
 export type VideoGenerationFundingSource = z.infer<typeof VideoGenerationFundingSource>;
 
 export const VideoGenerationAspectRatio = z.enum([
@@ -131,7 +136,11 @@ export const VideoGenerationCapabilities = z
   .superRefine((value, ctx) => {
     const ids = new Set(value.models.map((model) => model.modelId));
     if (ids.size !== value.models.length) {
-      ctx.addIssue({ code: "custom", path: ["models"], message: "model ids must be unique" });
+      ctx.addIssue({
+        code: "custom",
+        path: ["models"],
+        message: "model ids must be unique",
+      });
     }
     if (!ids.has(value.defaultModelId)) {
       ctx.addIssue({
@@ -205,21 +214,22 @@ export const WorkspaceVideoGenerationSettings = z
   .object({
     schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
     policy: VideoGenerationPolicy,
-    fundingOptions: z.array(VideoGenerationFundingOption).length(2),
+    fundingOptions: z.array(VideoGenerationFundingOption).length(3),
     availableModels: z.array(VideoGenerationModelCapability).max(16),
     capabilities: VideoGenerationCapabilities.nullable(),
   })
   .strict()
   .superRefine((value, ctx) => {
     if (
-      new Set(value.fundingOptions.map((option) => option.source)).size !== 2 ||
+      new Set(value.fundingOptions.map((option) => option.source)).size !== 3 ||
       !value.fundingOptions.some((option) => option.source === "opengeni_credits") ||
-      !value.fundingOptions.some((option) => option.source === "workspace_gateway")
+      !value.fundingOptions.some((option) => option.source === "workspace_gateway") ||
+      !value.fundingOptions.some((option) => option.source === "supergrok_subscription")
     ) {
       ctx.addIssue({
         code: "custom",
         path: ["fundingOptions"],
-        message: "both funding sources must be described exactly once",
+        message: "all funding sources must be described exactly once",
       });
     }
     const selected = value.fundingOptions.find(
@@ -250,6 +260,33 @@ export const VideoGenerationAcceptedReceipt = z
   .strict();
 export type VideoGenerationAcceptedReceipt = z.infer<typeof VideoGenerationAcceptedReceipt>;
 
+export const VideoGenerationRejectedCode = z.enum([
+  "invalid_reference_path",
+  "reference_not_stable",
+  "reference_too_large",
+  "reference_media_type_mismatch",
+  "unsupported_reference_media",
+]);
+export type VideoGenerationRejectedCode = z.infer<typeof VideoGenerationRejectedCode>;
+
+/** Deterministic pre-admission rejection: no provider request or durable operation was created. */
+export const VideoGenerationRejectedResult = z
+  .object({
+    schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+    status: z.literal("rejected"),
+    code: VideoGenerationRejectedCode,
+    message: z.string().min(1).max(512),
+    operationCreated: z.literal(false),
+  })
+  .strict();
+export type VideoGenerationRejectedResult = z.infer<typeof VideoGenerationRejectedResult>;
+
+export const VideoGenerationToolResult = z.discriminatedUnion("status", [
+  VideoGenerationAcceptedReceipt,
+  VideoGenerationRejectedResult,
+]);
+export type VideoGenerationToolResult = z.infer<typeof VideoGenerationToolResult>;
+
 export const GeneratedVideoFacts = z
   .object({
     durationSeconds: z.number().positive().max(120),