@automate.ax/api-contract 0.81.0 → 0.83.0

package/dist/runtime.js

@@ -7,6 +7,7 @@ import { automationErrorSchema } from "./errors.js";
 export const DEFAULT_GATEWAY_MODEL_ID = "openai/gpt-4.1-nano";
 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:`;
 export const CALLBACK_PROTECTION_QUERY_PARAMETER = "_axCallback";
 export const AUTOMATION_LOG_MAX_ENTRIES = 1_000;
 export const AUTOMATION_TRACE_MAX_SPANS = 250;
@@ -93,8 +94,55 @@ export const automationInvocationInputSchema = z
     }),
 ]))
     .and(automationInvocationScheduleSchema);
+const SIGNAL_DERIVATION_NODE_SCHEMA = z.discriminatedUnion("type", [
+    z.object({
+        id: z.string().min(1),
+        source: z.enum(["action", "event", "signal"]),
+        type: z.literal("source"),
+    }),
+    z.object({
+        inputs: z.number().int().nonnegative().array().min(1),
+        property: z.string(),
+        type: z.literal("property"),
+    }),
+    z.object({
+        inputs: z.number().int().nonnegative().array().min(1),
+        type: z.literal("transform"),
+    }),
+]);
+/** Compact concrete derivation graph persisted for one durable consumer. */
+export const signalDerivationSchema = z
+    .object({
+    nodes: SIGNAL_DERIVATION_NODE_SCHEMA.array().min(1),
+    roots: z.number().int().nonnegative().array().min(1),
+})
+    .superRefine(({ nodes, roots }, context) => {
+    for (const [index, node] of nodes.entries()) {
+        if (node.type === "source")
+            continue;
+        for (const input of node.inputs) {
+            if (input >= index) {
+                context.addIssue({
+                    code: "custom",
+                    message: "Derivation inputs must reference preceding nodes.",
+                    path: ["nodes", index, "inputs"],
+                });
+            }
+        }
+    }
+    for (const [index, root] of roots.entries()) {
+        if (root >= nodes.length) {
+            context.addIssue({
+                code: "custom",
+                message: "Derivation roots must reference an existing node.",
+                path: ["roots", index],
+            });
+        }
+    }
+});
 const ACTION_INVOCATION_BASE_SCHEMA = z.object({
     actionDependencyIds: z.string().array(),
+    derivation: signalDerivationSchema.nullable(),
     description: z.string().nullable(),
     eventDependencyIds: z.string().array(),
     inputHash: z.string(),
@@ -142,13 +190,16 @@ const ACTION_RUN_INVOCATION_SCHEMA = z.union([
         status: z.literal("succeeded"),
     }),
 ]);
-const SIGNAL_INVOCATION_DEPENDENCIES_SCHEMA = z.object({
+const SIGNAL_DEPENDENCIES_SCHEMA = z.object({
     actionDependencyIds: z.string().array(),
     eventDependencyIds: z.string().array(),
     scopePath: HOOK_SCOPE_PATH_SCHEMA,
     signalDependencyIds: z.string().array(),
     slot: z.number().int().nonnegative(),
 });
+const SIGNAL_INVOCATION_DEPENDENCIES_SCHEMA = SIGNAL_DEPENDENCIES_SCHEMA.extend({
+    derivation: signalDerivationSchema.nullable(),
+});
 const COORDINATION_PRIMARY_POSITION_SCHEMA = z.enum(["first", "last"]);
 const COORDINATION_DURATION_SCHEMA = z.union([
     z.string().min(1),
@@ -624,7 +675,7 @@ export const runtimeContract = {
         targetAction: TARGET_ACTION_SCHEMA.optional(),
     })),
     loadValues: oc
-        .input(SIGNAL_INVOCATION_DEPENDENCIES_SCHEMA.omit({
+        .input(SIGNAL_DEPENDENCIES_SCHEMA.omit({
         scopePath: true,
         slot: true,
     }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/api-contract",
-  "version": "0.81.0",
+  "version": "0.83.0",
   "description": "Public oRPC contract for the Automate.ax API.",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
       ".": "./src/index.ts",
       "./errors": "./src/errors.ts",
       "./permissions": "./src/permissions.ts",
+      "./runtime-protocol": "./src/runtime-protocol.ts",
       "./runtime": "./src/runtime.ts"
     },
     "cjs": false,
@@ -30,13 +31,14 @@
   },
   "dependencies": {
     "@ai-sdk/gateway": "^4.0.46",
-    "@automate.ax/codec": "0.81.0",
+    "@automate.ax/codec": "0.83.0",
+    "@automate.ax/integration-contracts": "0.83.0",
     "@orpc/contract": "1.15.0",
     "fast-json-stable-stringify": "^2.1.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@internal/config": "0.0.0",
+    "@internal/config": "0.1.0",
     "@types/bun": "latest",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@zachsents/oxlint-config": "^0.4.1",
@@ -81,6 +83,11 @@
       "types": "./dist/permissions.d.ts",
       "default": "./dist/permissions.js"
     },
+    "./runtime-protocol": {
+      "bun": "./src/runtime-protocol.ts",
+      "types": "./dist/runtime-protocol.d.ts",
+      "default": "./dist/runtime-protocol.js"
+    },
     "./runtime": {
       "bun": "./src/runtime.ts",
       "types": "./dist/runtime.d.ts",

package/src/deployment.ts

@@ -1,5 +1,6 @@
 import { oc } from "@orpc/contract"
 import * as z from "zod"
+import { AUTOMATION_RUNTIME_PROTOCOL_VERSION } from "./runtime-protocol"
 import { cursorPageOutputSchema, cursorPaginationInputSchema } from "./schemas"
 
 /** SDK compatibility version used to select the immutable runtime image. */
@@ -24,6 +25,15 @@ const DEPLOYMENT_IN_PROGRESS_ERROR = {
   status: 409,
 } as const
 
+const UNSUPPORTED_RUNTIME_PROTOCOL_ERROR = {
+  data: z.object({
+    receivedVersion: z.number().int().positive().nullable(),
+    supportedVersion: z.literal(AUTOMATION_RUNTIME_PROTOCOL_VERSION),
+  }),
+  message: "The automation bundle uses an unsupported runtime protocol.",
+  status: 400,
+} as const
+
 const GIT_SOURCE_SCHEMA = z.object({
   commitSha: z.string().regex(/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/),
   dirty: z.boolean(),
@@ -96,7 +106,10 @@ export const deploymentContract = {
     .input(z.object({ deploymentId: z.string() }))
     .output(z.void()),
   create: oc
-    .errors({ DEPLOYMENT_IN_PROGRESS: DEPLOYMENT_IN_PROGRESS_ERROR })
+    .errors({
+      DEPLOYMENT_IN_PROGRESS: DEPLOYMENT_IN_PROGRESS_ERROR,
+      UNSUPPORTED_RUNTIME_PROTOCOL: UNSUPPORTED_RUNTIME_PROTOCOL_ERROR,
+    })
     .input(
       z.object({
         artifact: z.instanceof(Blob),
@@ -123,6 +136,7 @@ export const deploymentContract = {
         mode: z.enum(["reconcile", "upsert"]),
         projectId: z.string(),
         rebindAccounts: z.boolean().default(false),
+        runtimeProtocolVersion: z.number().int().positive().optional(),
         git: GIT_SOURCE_SCHEMA.optional(),
       }),
     )
@@ -171,7 +185,10 @@ export const deploymentContract = {
     )
     .output(cursorPageOutputSchema(deploymentOutputSchema)),
   redeploy: oc
-    .errors({ DEPLOYMENT_IN_PROGRESS: DEPLOYMENT_IN_PROGRESS_ERROR })
+    .errors({
+      DEPLOYMENT_IN_PROGRESS: DEPLOYMENT_IN_PROGRESS_ERROR,
+      UNSUPPORTED_RUNTIME_PROTOCOL: UNSUPPORTED_RUNTIME_PROTOCOL_ERROR,
+    })
     .route({
       method: "POST",
       path: "/projects/{projectId}/deployments/redeploy",

package/src/events/convex.ts

@@ -0,0 +1,26 @@
+import { oc } from "@orpc/contract"
+import * as z from "zod"
+
+export const convexEventsContract = {
+  convexEvent: oc
+    .route({
+      description:
+        "Authenticates and ingests a semantic event emitted by a Convex action.",
+      method: "POST",
+      operationId: "receiveConvexEvent",
+      path: "/events/convex/{endpointKey}",
+      successStatus: 204,
+      summary: "Receive a signed Convex event",
+      tags: ["Events"],
+    })
+    .input(
+      z.object({
+        emittedAt: z.iso.datetime({ offset: true }),
+        endpointKey: z.string(),
+        id: z.string(),
+        name: z.string(),
+        payload: z.json(),
+      }),
+    )
+    .output(z.void()),
+}

package/src/events/index.ts

@@ -1,6 +1,7 @@
 import { airtableEventsContract } from "./airtable"
 import { asanaEventsContract } from "./asana"
 import { brevoEventsContract } from "./brevo"
+import { convexEventsContract } from "./convex"
 import { googleCalendarEventsContract } from "./google-calendar"
 import { googleFormsEventsContract } from "./google-forms"
 import { googleMeetEventsContract } from "./google-meet"
@@ -19,6 +20,7 @@ export const eventsContract = {
   ...airtableEventsContract,
   ...asanaEventsContract,
   ...brevoEventsContract,
+  ...convexEventsContract,
   ...googleCalendarEventsContract,
   ...googleFormsEventsContract,
   ...googleMeetEventsContract,

package/src/execution-data.ts

@@ -1,11 +1,12 @@
 import { oc } from "@orpc/contract"
 import { z } from "zod"
 
-export const EXECUTION_DATASET_VERSION = 4
+export const EXECUTION_DATASET_VERSION = 6
 
 export const executionDatasetResourceSchema = z.enum([
   "projects",
   "automations",
+  "automation-invocations",
   "contexts",
   "context-parents",
   "event-links",

package/src/index.ts

@@ -29,6 +29,7 @@ export {
   deploymentOutputSchema,
   deploymentStatusSchema,
 } from "./deployment"
+export { AUTOMATION_RUNTIME_PROTOCOL_VERSION } from "./runtime-protocol"
 export {
   AUTOMATION_ERROR_CAUSE_DEPTH,
   automationErrorSchema,

package/src/org.ts

@@ -32,10 +32,12 @@ export const organizationSummaryOutputSchema = z.object({
   pendingInvitationCount: z.number(),
   projectCount: z.number(),
   activeSubscription: activeSubscriptionOutputSchema.nullable(),
+  executionRetentionDays: z.number().int().positive(),
   plan: z.enum(["free", "pro", "enterprise"]),
   limits: z.object({
     aiSpendUsd: z.number(),
     emailSends: z.number(),
+    executionRetentionDays: z.number().int().positive(),
     projects: z.number(),
     seats: z.number(),
   }),
@@ -225,10 +227,23 @@ export const orgContract = {
       tags: ["Organizations"],
     })
     .input(
-      z.object({
-        organizationId: z.string(),
-        name: reasonableNameSchema,
-      }),
+      z
+        .object({
+          executionRetentionDays: z
+            .number()
+            .int()
+            .positive()
+            .nullable()
+            .optional(),
+          organizationId: z.string(),
+          name: reasonableNameSchema.optional(),
+        })
+        .refine(
+          (input) =>
+            input.executionRetentionDays !== undefined ||
+            input.name !== undefined,
+          "Provide an organization setting to update.",
+        ),
     )
     .output(z.void()),
 }

package/src/runtime-protocol.ts

@@ -0,0 +1,2 @@
+/** Runtime protocol required by newly built automation bundles. */
+export const AUTOMATION_RUNTIME_PROTOCOL_VERSION = 1

package/src/runtime.ts

@@ -12,6 +12,8 @@ export const DEFAULT_GATEWAY_MODEL_ID =
   "openai/gpt-4.1-nano" satisfies GatewayModelId
 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 CALLBACK_PROTECTION_QUERY_PARAMETER = "_axCallback"
 export const AUTOMATION_LOG_MAX_ENTRIES = 1_000
 export const AUTOMATION_TRACE_MAX_SPANS = 250
@@ -110,8 +112,59 @@ export const automationInvocationInputSchema = z
   )
   .and(automationInvocationScheduleSchema)
 
+const SIGNAL_DERIVATION_NODE_SCHEMA = z.discriminatedUnion("type", [
+  z.object({
+    id: z.string().min(1),
+    source: z.enum(["action", "event", "signal"]),
+    type: z.literal("source"),
+  }),
+  z.object({
+    inputs: z.number().int().nonnegative().array().min(1),
+    property: z.string(),
+    type: z.literal("property"),
+  }),
+  z.object({
+    inputs: z.number().int().nonnegative().array().min(1),
+    type: z.literal("transform"),
+  }),
+])
+
+/** Compact concrete derivation graph persisted for one durable consumer. */
+export const signalDerivationSchema = z
+  .object({
+    nodes: SIGNAL_DERIVATION_NODE_SCHEMA.array().min(1),
+    roots: z.number().int().nonnegative().array().min(1),
+  })
+  .superRefine(({ nodes, roots }, context) => {
+    for (const [index, node] of nodes.entries()) {
+      if (node.type === "source") continue
+      for (const input of node.inputs) {
+        if (input >= index) {
+          context.addIssue({
+            code: "custom",
+            message: "Derivation inputs must reference preceding nodes.",
+            path: ["nodes", index, "inputs"],
+          })
+        }
+      }
+    }
+    for (const [index, root] of roots.entries()) {
+      if (root >= nodes.length) {
+        context.addIssue({
+          code: "custom",
+          message: "Derivation roots must reference an existing node.",
+          path: ["roots", index],
+        })
+      }
+    }
+  })
+
+/** Persisted source, property, and opaque transform derivation graph. */
+export type SignalDerivation = z.infer<typeof signalDerivationSchema>
+
 const ACTION_INVOCATION_BASE_SCHEMA = z.object({
   actionDependencyIds: z.string().array(),
+  derivation: signalDerivationSchema.nullable(),
   description: z.string().nullable(),
   eventDependencyIds: z.string().array(),
   inputHash: z.string(),
@@ -163,7 +216,7 @@ const ACTION_RUN_INVOCATION_SCHEMA = z.union([
   }),
 ])
 
-const SIGNAL_INVOCATION_DEPENDENCIES_SCHEMA = z.object({
+const SIGNAL_DEPENDENCIES_SCHEMA = z.object({
   actionDependencyIds: z.string().array(),
   eventDependencyIds: z.string().array(),
   scopePath: HOOK_SCOPE_PATH_SCHEMA,
@@ -171,6 +224,12 @@ const SIGNAL_INVOCATION_DEPENDENCIES_SCHEMA = z.object({
   slot: z.number().int().nonnegative(),
 })
 
+const SIGNAL_INVOCATION_DEPENDENCIES_SCHEMA = SIGNAL_DEPENDENCIES_SCHEMA.extend(
+  {
+    derivation: signalDerivationSchema.nullable(),
+  },
+)
+
 const COORDINATION_PRIMARY_POSITION_SCHEMA = z.enum(["first", "last"])
 const COORDINATION_DURATION_SCHEMA = z.union([
   z.string().min(1),
@@ -722,7 +781,7 @@ export const runtimeContract = {
   ),
   loadValues: oc
     .input(
-      SIGNAL_INVOCATION_DEPENDENCIES_SCHEMA.omit({
+      SIGNAL_DEPENDENCIES_SCHEMA.omit({
         scopePath: true,
         slot: true,
       }),