@automate.ax/api-contract 0.84.0 → 0.86.1

package/src/runtime.ts

@@ -1,24 +1,57 @@
-import { encodableSchema } from "@automate.ax/codec"
-import type { GatewayModelId } from "@ai-sdk/gateway"
+import {
+  encodableSchema,
+  isSensitivityMask,
+  type SensitivityMask,
+} from "@automate.ax/codec"
+import type { GatewayImageModelId, GatewayModelId } from "@ai-sdk/gateway"
 import { oc } from "@orpc/contract"
 import stableStringify from "fast-json-stable-stringify"
 import * as z from "zod"
 import { automationErrorSchema } from "./errors"
 
-export type { GatewayModelId } from "@ai-sdk/gateway"
+export type { GatewayImageModelId, GatewayModelId } from "@ai-sdk/gateway"
 
 /** Default model used by the platform Vercel AI Gateway account. */
 export const DEFAULT_GATEWAY_MODEL_ID =
   "openai/gpt-4.1-nano" satisfies GatewayModelId
+
+/** Default image model used by the platform Vercel AI Gateway account. */
+export const DEFAULT_GATEWAY_IMAGE_MODEL_ID =
+  "bfl/flux-2-flex" satisfies GatewayImageModelId
 export const AUTOMATION_INVOCATION_DEFAULT_ENTRYPOINT = "default"
 export const AUTOMATION_INVOCATION_RESERVED_ENTRYPOINT_PREFIX = "__$"
 export const AUTOMATION_DELAY_ENTRYPOINT_PREFIX =
   `${AUTOMATION_INVOCATION_RESERVED_ENTRYPOINT_PREFIX}delay:` as const
+export const AUTOMATION_IMAGE_GENERATION_ENTRYPOINT_PREFIX =
+  `${AUTOMATION_INVOCATION_RESERVED_ENTRYPOINT_PREFIX}generate-image:` as const
 export const CALLBACK_PROTECTION_QUERY_PARAMETER = "_axCallback"
 export const AUTOMATION_LOG_MAX_ENTRIES = 1_000
 export const AUTOMATION_TRACE_MAX_SPANS = 250
 export const AUTOMATION_OBSERVABILITY_MAX_FIELDS = 64
 export const AUTOMATION_OBSERVABILITY_MAX_ENCODED_BYTES = 64 * 1_024
+
+const RUNTIME_BLOB_JSON_SERIALIZER_TYPE = 8
+
+/** Blob wrappers that should use oRPC's native multipart serialization. */
+const runtimeBlobTransportValues = new WeakSet<Blob>()
+
+/** Preserves Blob media types while oRPC carries the bytes as multipart data. */
+export const runtimeBlobJsonSerializer = {
+  type: RUNTIME_BLOB_JSON_SERIALIZER_TYPE,
+  condition: (value: unknown) =>
+    value instanceof Blob && !runtimeBlobTransportValues.has(value),
+  serialize(value: Blob) {
+    const transportValue = new Blob([value])
+    runtimeBlobTransportValues.add(transportValue)
+    return { transportValue, type: value.type }
+  },
+  deserialize(value: unknown) {
+    const { transportValue, type } = z
+      .object({ transportValue: z.instanceof(Blob), type: z.string() })
+      .parse(value)
+    return new Blob([transportValue], { type })
+  },
+}
 export const AUTOMATION_LOG_MAX_MESSAGE_LENGTH = 16_384
 export const AUTOMATION_TRACE_MAX_NAME_LENGTH = 256
 
@@ -42,6 +75,12 @@ const TRACE_SPAN_INDEX_SCHEMA = z
   .min(0)
   .max(AUTOMATION_TRACE_MAX_SPANS - 1)
 
+/** Runtime-validated structural policy for author-visible value projection. */
+export const sensitivityMaskSchema = z.custom<SensitivityMask>(
+  isSensitivityMask,
+  { message: "Invalid structural sensitivity mask" },
+)
+
 const AUTOMATION_INVOCATION_RUN_AT_SCHEMA = z.union([
   z.date(),
   z.string().min(1),
@@ -169,6 +208,7 @@ const ACTION_INVOCATION_BASE_SCHEMA = z.object({
   eventDependencyIds: z.string().array(),
   inputHash: z.string(),
   name: z.string(),
+  outputSensitivity: sensitivityMaskSchema.nullable().optional(),
   scopePath: HOOK_SCOPE_PATH_SCHEMA,
   signalDependencyIds: z.string().array(),
   slot: z.number().int().nonnegative(),
@@ -445,6 +485,7 @@ const ACTION_VALUE_OUTCOME_SCHEMA = z.union([
   }),
   ACTION_VALUE_OUTCOME_BASE_SCHEMA.extend({
     output: encodableSchema,
+    outputSensitivity: sensitivityMaskSchema.nullable().optional(),
     status: z.literal("succeeded"),
   }),
 ])
@@ -540,7 +581,7 @@ const TARGET_ACTION_SCHEMA = z.union([
   }),
 ])
 
-const GENERATION_WARNING_SCHEMA = z.discriminatedUnion("type", [
+const AI_WARNING_SCHEMA = z.discriminatedUnion("type", [
   z.object({
     details: z.string().optional(),
     feature: z.string(),
@@ -648,7 +689,7 @@ export const generationResultSchema = z.object({
   }),
   text: z.string(),
   usage: GENERATION_USAGE_SCHEMA,
-  warnings: GENERATION_WARNING_SCHEMA.array().optional(),
+  warnings: AI_WARNING_SCHEMA.array().optional(),
 })
 
 export type GenerationInput = z.output<typeof generationInputSchema>
@@ -675,6 +716,106 @@ export type RuntimeGenerationInput = z.output<
   typeof RUNTIME_GENERATION_INPUT_SCHEMA
 >
 
+const IMAGE_DATA_CONTENT_SCHEMA = z.union([
+  z.string(),
+  z.custom<Uint8Array>((value) => value instanceof Uint8Array),
+  z.instanceof(ArrayBuffer),
+  z.instanceof(Blob),
+])
+
+const IMAGE_GENERATION_PROMPT_SCHEMA = z.union([
+  z.string(),
+  z.object({
+    images: IMAGE_DATA_CONTENT_SCHEMA.array(),
+    mask: IMAGE_DATA_CONTENT_SCHEMA.optional(),
+    text: z.string().optional(),
+  }),
+])
+
+const GATEWAY_IMAGE_MODEL_ID_SCHEMA = z
+  .custom<GatewayImageModelId>(
+    (value) => typeof value === "string" && value.length > 0,
+    "Model must be a nonempty AI Gateway image model ID.",
+  )
+  .default(DEFAULT_GATEWAY_IMAGE_MODEL_ID)
+
+/** Shared options accepted by the built-in image-generation action. */
+export const imageGenerationInputSchema = z.object({
+  aspectRatio: z
+    .custom<`${number}:${number}`>((value) => typeof value === "string" && /^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(value), "Aspect ratio must use the format {width}:{height}.")
+    .optional(),
+  headers: z.record(z.string(), z.string()).optional(),
+  maxImagesPerCall: z.number().int().positive().optional(),
+  maxRetries: z.number().int().nonnegative().optional(),
+  model: GATEWAY_IMAGE_MODEL_ID_SCHEMA,
+  n: z.number().int().positive().optional(),
+  prompt: IMAGE_GENERATION_PROMPT_SCHEMA,
+  providerOptions: z
+    .record(z.string(), z.record(z.string(), z.json()))
+    .optional(),
+  seed: z.number().int().optional(),
+  size: z
+    .custom<`${number}x${number}`>((value) => typeof value === "string" && /^\d+x\d+$/.test(value), "Size must use the format {width}x{height}.")
+    .optional(),
+})
+
+const IMAGE_PROVIDER_METADATA_SCHEMA = z
+  .object({ images: z.json().array().optional() })
+  .catchall(z.json())
+
+/** Serializable subset of the AI SDK image-generation result. */
+export const imageGenerationResultSchema = z.object({
+  images: z.instanceof(Blob).array().min(1),
+  providerMetadata: z.record(z.string(), IMAGE_PROVIDER_METADATA_SCHEMA),
+  responses: z
+    .object({
+      headers: z.record(z.string(), z.string()).optional(),
+      modelId: z.string(),
+      timestamp: z.iso.datetime(),
+    })
+    .array(),
+  usage: z.object({
+    inputTokens: z.number().optional(),
+    outputTokens: z.number().optional(),
+    totalTokens: z.number().optional(),
+  }),
+  warnings: AI_WARNING_SCHEMA.array(),
+})
+
+/** Internal terminal delivery emitted by a platform image-generation job. */
+export const imageGenerationCompletionSchema = z.object({
+  key: z.string().min(1),
+  outcome: z.discriminatedUnion("status", [
+    z.object({
+      result: imageGenerationResultSchema,
+      status: z.literal("succeeded"),
+    }),
+    z.object({ failure: automationErrorSchema, status: z.literal("failed") }),
+  ]),
+})
+
+/** Starts platform image generation for one reserved internal entrypoint. */
+export const platformImageGenerationInputSchema =
+  imageGenerationInputSchema.extend({
+    entrypoint: z
+      .string()
+      .startsWith(AUTOMATION_IMAGE_GENERATION_ENTRYPOINT_PREFIX),
+  })
+
+/** Durable identity returned after platform image generation is queued. */
+export const platformImageGenerationStartSchema = z.object({
+  key: z.string().min(1),
+})
+
+export type ImageGenerationInput = z.output<typeof imageGenerationInputSchema>
+export type ImageGenerationResult = z.output<typeof imageGenerationResultSchema>
+export type ImageGenerationCompletion = z.output<
+  typeof imageGenerationCompletionSchema
+>
+export type PlatformImageGenerationInput = z.output<
+  typeof platformImageGenerationInputSchema
+>
+
 /**
  * Hashes one coordinator definition exactly as the runtime stores it.
  *
@@ -766,6 +907,9 @@ export const runtimeContract = {
   generate: oc
     .input(RUNTIME_GENERATION_INPUT_SCHEMA)
     .output(generationResultSchema),
+  startImageGeneration: oc
+    .input(platformImageGenerationInputSchema)
+    .output(platformImageGenerationStartSchema),
   createCallbackToken: oc
     .input(z.object({ endpointKey: z.string().min(1) }))
     .output(z.string()),
@@ -809,6 +953,7 @@ export const runtimeContract = {
           type: z.string().min(1),
         }),
         outputIndex: z.number().int().nonnegative(),
+        sensitivity: sensitivityMaskSchema.optional(),
       }),
     )
     .output(z.void()),
@@ -819,6 +964,7 @@ export const runtimeContract = {
         level: z.enum(["debug", "info", "warn", "error"]),
         logIndex: LOG_INDEX_SCHEMA,
         message: z.string().min(1).max(AUTOMATION_LOG_MAX_MESSAGE_LENGTH),
+        sensitivity: sensitivityMaskSchema.optional(),
         spanIndex: TRACE_SPAN_INDEX_SCHEMA.optional(),
         timestamp: z.date(),
       }),
@@ -829,6 +975,7 @@ export const runtimeContract = {
       z.object({
         attributes: OBSERVABILITY_FIELDS_SCHEMA.optional(),
         name: z.string().min(1).max(AUTOMATION_TRACE_MAX_NAME_LENGTH),
+        sensitivity: sensitivityMaskSchema.optional(),
         parentSpanIndex: TRACE_SPAN_INDEX_SCHEMA.optional(),
         spanIndex: TRACE_SPAN_INDEX_SCHEMA,
         startedAt: z.date(),