@uniformdev/automations-sdk 20.72.3-alpha.40 → 20.72.3-alpha.45

package/dist/api/index.d.mts

@@ -417,6 +417,13 @@ interface paths {
                                 name: string;
                                 /** @description Optional description. */
                                 description: string | null;
+                                /**
+                                 * @description How the automation behaves: a bundled TypeScript handler, or Scout instructions.
+                                 * @enum {string}
+                                 */
+                                kind: "typescript" | "scout";
+                                /** @description The stored instructions for a `scout` automation; null for any other kind. */
+                                instructions: string | null;
                                 /** @description The triggers this automation subscribes to. */
                                 triggers: {
                                     /** @description How the automation is triggered. */
@@ -492,6 +499,8 @@ interface paths {
          * @deprecated
          * @description Deploys (creates or updates) an automation.
          *
+         *     Set `kind` to `typescript` to deploy a bundled handler module, or to `scout` to have the automation run the Scout agent against stored natural-language instructions on each trigger.
+         *
          *     This is experimental functionality that is subject to change without notice.
          */
         put: {
@@ -550,10 +559,69 @@ interface paths {
                                 [key: string]: string | string[];
                             };
                         };
+                        /**
+                         * @description Runs a bundled TypeScript handler module.
+                         * @enum {string}
+                         */
+                        kind: "typescript";
                         /** @description Bundled JavaScript module for the automation handler. */
                         code: string;
                         /** @description Target date for runtime compatibility. Runtime changes after this date may not apply to this automation. */
                         compatibilityDate?: string;
+                    } | {
+                        /** @description The project ID. */
+                        projectId: string;
+                        /** @description Stable public identifier for the automation. */
+                        publicId: string;
+                        /** @description Display name of the automation. */
+                        name: string;
+                        /** @description For automations triggered as an AI tool, this is used to determine when an LLM should call the automation. For other triggers, this is for your reference and optional. */
+                        description?: string;
+                        /** @description The triggers this automation subscribes to. */
+                        triggers: ({
+                            /**
+                             * @description The internal webhook event name that triggers this automation.
+                             * @enum {string}
+                             */
+                            type: "asset.deleted" | "asset.published" | "composition.changed" | "composition.deleted" | "composition.published" | "composition.release.changed" | "composition.release.deleted" | "composition.release.published" | "composition.release.restored" | "entry.changed" | "entry.deleted" | "entry.published" | "entry.release.changed" | "entry.release.deleted" | "entry.release.published" | "entry.release.restored" | "manifest.published" | "notification.created" | "projectmap.delete" | "projectmap.node.delete" | "projectmap.node.insert" | "projectmap.node.update" | "projectmap.update" | "redirect.delete" | "redirect.insert" | "redirect.update" | "release.changed" | "release.deleted" | "release.launch_started" | "release.launched" | "workflow.transition";
+                            /** @description Optional CEL boolean expression evaluated against { input, trigger }; the automation runs only when it is true. */
+                            filter?: string;
+                        } | {
+                            /** @enum {string} */
+                            type: "schedule";
+                            /** @description RFC 5545 recurrence rule for when the automation runs. */
+                            rrule: string;
+                            /** @description IANA timezone used to evaluate the recurrence rule. */
+                            timezone: string;
+                        } | {
+                            /** @enum {string} */
+                            type: "incomingWebhook";
+                            /** @description Optional CEL boolean expression evaluated against { input, trigger }; the automation runs only when it is true. */
+                            filter?: string;
+                        } | {
+                            /** @enum {string} */
+                            type: "aiTool";
+                            /** @description JSON Schema describing the AI tool arguments. */
+                            inputSchema: {
+                                [key: string]: unknown;
+                            };
+                        })[];
+                        /** @description Role grants for the automation identity. The caller must hold each requested role (or be a team admin). Required: a Scout automation acts solely through its machine identity, so without a role grant it has no authority to act. */
+                        permissions: {
+                            /** @description Role grant(s) on the project the automation is deployed to. */
+                            role: string | string[];
+                            /** @description Additional project role grants keyed by project ID for cross-project access within the same team. */
+                            projects?: {
+                                [key: string]: string | string[];
+                            };
+                        };
+                        /**
+                         * @description Runs the Scout agent headlessly against stored instructions.
+                         * @enum {string}
+                         */
+                        kind: "scout";
+                        /** @description The instructions Scout runs on each trigger. */
+                        instructions: string;
                     };
                 };
             };
@@ -749,8 +817,21 @@ type AutomationSummary = AutomationsListResponse['automations'][number];
 type AutomationTrigger = AutomationSummary['triggers'][number];
 type AutomationTriggerType = AutomationTrigger['config']['type'];
 type AutomationsDeployBody = paths['/api/v1/automations']['put']['requestBody']['content']['application/json'];
+/**
+ * `Omit` over each member of a union separately, so the `kind` discriminant still narrows the
+ * result. Plain `Omit` would flatten the union into one object type and lose that.
+ */
+type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
 /** Deploy input without the project ID, which the client injects from its options. */
-type AutomationsDeployInput = Omit<AutomationsDeployBody, 'projectId'>;
+type AutomationsDeployInput = DistributiveOmit<AutomationsDeployBody, 'projectId'>;
+/** The `typescript` member of the deploy input — an automation with a bundled handler module. */
+type TypeScriptAutomationDeployInput = Extract<AutomationsDeployInput, {
+    kind: 'typescript';
+}>;
+/** The `scout` member of the deploy input — an automation Scout runs from stored instructions. */
+type ScoutAutomationDeployInput = Extract<AutomationsDeployInput, {
+    kind: 'scout';
+}>;
 type AutomationRunsListResponse = paths$1['/api/v1/automation-runs']['get']['responses']['200']['content']['application/json'];
 type AutomationRunSummary = AutomationRunsListResponse['runs'][number];
 type AutomationRunStatus = AutomationRunSummary['status'];
@@ -779,8 +860,6 @@ declare class AutomationsClient extends ApiClient<AutomationsClientOptions> {
     list(): Promise<AutomationsListResponse>;
     /**
      * Deploys (creates or updates) a single automation.
-     *
-     * @param input - The automation definition + bundled code.
      */
     deploy(input: AutomationsDeployInput): Promise<void>;
     /**
@@ -822,4 +901,4 @@ declare class AutomationsClient extends ApiClient<AutomationsClientOptions> {
     listRunLogs(runId: string): Promise<AutomationRunLogEntry[]>;
 }
 
-export { type AutomationRunLogEntry, type AutomationRunStatus, type AutomationRunSummary, type AutomationRunTriggerResponse, type AutomationRunsListResponse, type AutomationSummary, type AutomationTrigger, type AutomationTriggerType, AutomationsClient, type AutomationsClientOptions, type AutomationsDeployBody, type AutomationsDeployInput, type AutomationsListResponse };
+export { type AutomationRunLogEntry, type AutomationRunStatus, type AutomationRunSummary, type AutomationRunTriggerResponse, type AutomationRunsListResponse, type AutomationSummary, type AutomationTrigger, type AutomationTriggerType, AutomationsClient, type AutomationsClientOptions, type AutomationsDeployBody, type AutomationsDeployInput, type AutomationsListResponse, type ScoutAutomationDeployInput, type TypeScriptAutomationDeployInput };

package/dist/api/index.mjs

@@ -40,8 +40,6 @@ var _AutomationsClient = class _AutomationsClient extends ApiClient {
   }
   /**
    * Deploys (creates or updates) a single automation.
-   *
-   * @param input - The automation definition + bundled code.
    */
   async deploy(input) {
     const { projectId } = this.options;

package/dist/index.d.mts

@@ -75,6 +75,16 @@ type JsonSchemaObject = Record<string, unknown>;
  * Note: non-zod standard schema providers are not supported.
  */
 type AiToolInputSchema = StandardSchemaV1 | JsonSchemaObject;
+/**
+ * Maximum length of a Scout automation's instructions, in UTF-16 code units (what `String.length`
+ * counts, and what the deploy API's `z.string().max()` measures).
+ *
+ * The instructions travel in the run's Cloudflare Queues message, which is hard-capped at 128 KB and
+ * already carries up to 64 KB of captured input plus credentials. 16 K is far more than authored
+ * instructions need and leaves the envelope with ample headroom. Like any ingress cap this can be
+ * raised later but never lowered.
+ */
+declare const AUTOMATION_INSTRUCTIONS_MAX_LENGTH: number;
 /**
  * Role grants for the automation's identity.
  */
@@ -131,6 +141,28 @@ type AiToolAutomationMetadata = AutomationMetadataBase & {
 };
 /** Authored metadata declared via {@link defineAutomation}. */
 type AutomationMetadata = ComposedAutomationMetadata | AiToolAutomationMetadata;
+/**
+ * Authored metadata for a Scout automation — one with no handler, whose behavior is the instructions
+ * the agent runs on each trigger.
+ *
+ * Two fields differ from a handler automation, both because the automation has no code of its own:
+ * - `permissions` is **required**. A Scout automation's only actions are the agent's tool calls, and
+ *   every one of them acts as the automation's machine identity. With no role grant there is no
+ *   identity, so the run has no authority to do anything at all.
+ * - there is no `compatibilityDate`. The runtime the agent runs on is Uniform's, not yours.
+ *
+ * `aiTool` is also absent from the trigger union: an `aiTool` automation *is* a tool the agent calls,
+ * so an agent-driven one would be circular.
+ */
+type ScoutAutomationMetadata = {
+    /** Display name surfaced in the dashboard and run history. */
+    name: string;
+    description?: string;
+    /** One or more triggers this automation subscribes to. */
+    triggers: [ComposableTriggerConfig, ...ComposableTriggerConfig[]];
+    /** Role grants for the automation's identity. Required — see {@link ScoutAutomationMetadata}. */
+    permissions: AutomationPermissions;
+};
 
 /**
  * Per-run Uniform API connection parameters.
@@ -332,6 +364,8 @@ type TriggersOf<M extends AutomationMetadata> = M extends {
 type HandlerFromAutomationMetadata<M extends AutomationMetadata> = AutomationHandler<InputFromAutomationMetadata<M>, TriggerFromAutomationMetadata<M>, CredentialsFromAutomationMetadata<M>>;
 /** A fully defined automation module: a callable invoke function with authored metadata attached. */
 type AutomationDefinition<M extends AutomationMetadata = AutomationMetadata> = AutomationInvoker & {
+    /** Discriminates a handler automation module from a Scout one (see `defineScoutAutomation`). */
+    kind: 'typescript';
     metadata: M;
 };
 /**
@@ -371,6 +405,29 @@ declare function defineAutomation<const M extends AutomationMetadata>(config: {
     handler: HandlerFromAutomationMetadata<M>;
 }): AutomationDefinition<M>;
 
+/**
+ * A fully defined Scout automation module: authored metadata plus the instructions the agent runs.
+ *
+ * Unlike {@link AutomationDefinition} this is *not* callable — a Scout automation has no local
+ * handler to invoke. The deploy API generates the runner from the instructions, so the module exists
+ * only to declare them.
+ */
+type ScoutAutomationDefinition<M extends ScoutAutomationMetadata = ScoutAutomationMetadata> = {
+    /** Discriminates a Scout automation module from a handler one. */
+    kind: 'scout';
+    metadata: M;
+    /** The instructions the agent runs on each trigger. */
+    instructions: string;
+};
+/**
+ * Defines an automation that uses Scout to perform a task.
+ *
+ * @param metadata - Name, triggers, and the role grants the run acts under. `permissions` is required.
+ * @param instructions - What the agent should do on each trigger.
+ * @returns A default-exportable Scout automation definition.
+ */
+declare function defineScoutAutomation<const M extends ScoutAutomationMetadata>(metadata: M, instructions: string): ScoutAutomationDefinition<M>;
+
 interface paths {
     "/api/v1/notifications": {
         parameters: {
@@ -755,4 +812,4 @@ declare class NotificationsClient extends ApiClient {
     setReadState(body: NotificationPatchParameters): Promise<void>;
 }
 
-export { type AiToolAutomationMetadata, type AiToolInputSchema, type AiToolTriggerConfig, type AutomationContext, type AutomationDefinition, type AutomationHandler, type AutomationInvokePayload, type AutomationInvoker, AutomationLogEntry, type AutomationLogLevel, type AutomationLogger, type AutomationMetadata, type AutomationPermissions, AutomationResult, type ComposableTriggerConfig, type ComposedAutomationMetadata, type CredentialsFromAutomationMetadata, type EventTriggerConfig, type HandlerFromAutomationMetadata, type IncomingWebhookInput, type IncomingWebhookTriggerConfig, type InputFromAutomationMetadata, type JsonSchemaObject, type Notification, type NotificationEntity, type NotificationPatchParameters, type NotificationPostParameters, type NotificationPostResponse, NotificationsClient, type NotificationsGetParameters, type NotificationsGetResponse, type ScheduleRunInput, type ScheduleTriggerConfig, type TriggerConfig, type TriggerFromAutomationMetadata, type UniformConnectionParams, defineAutomation };
+export { AUTOMATION_INSTRUCTIONS_MAX_LENGTH, type AiToolAutomationMetadata, type AiToolInputSchema, type AiToolTriggerConfig, type AutomationContext, type AutomationDefinition, type AutomationHandler, type AutomationInvokePayload, type AutomationInvoker, AutomationLogEntry, type AutomationLogLevel, type AutomationLogger, type AutomationMetadata, type AutomationPermissions, AutomationResult, type ComposableTriggerConfig, type ComposedAutomationMetadata, type CredentialsFromAutomationMetadata, type EventTriggerConfig, type HandlerFromAutomationMetadata, type IncomingWebhookInput, type IncomingWebhookTriggerConfig, type InputFromAutomationMetadata, type JsonSchemaObject, type Notification, type NotificationEntity, type NotificationPatchParameters, type NotificationPostParameters, type NotificationPostResponse, NotificationsClient, type NotificationsGetParameters, type NotificationsGetResponse, type ScheduleRunInput, type ScheduleTriggerConfig, type ScoutAutomationDefinition, type ScoutAutomationMetadata, type TriggerConfig, type TriggerFromAutomationMetadata, type UniformConnectionParams, defineAutomation, defineScoutAutomation };

package/dist/index.mjs

@@ -66,9 +66,29 @@ function metadataRequiresUniformCredentials(metadata) {
 function defineAutomation(config) {
   const requireUniformCredentials = metadataRequiresUniformCredentials(config.metadata);
   const invoker = (payload) => runAutomationHandler(config.handler, payload, { requireUniformCredentials });
-  return Object.assign(invoker, { metadata: config.metadata });
+  return Object.assign(invoker, { kind: "typescript", metadata: config.metadata });
 }
 
+// src/defineScoutAutomation.ts
+function defineScoutAutomation(metadata, instructions) {
+  var _a;
+  if (!instructions.trim()) {
+    throw new Error("A Scout automation must be given instructions.");
+  }
+  if (!((_a = metadata.triggers) == null ? void 0 : _a.length)) {
+    throw new Error("A Scout automation must declare at least one trigger.");
+  }
+  if (metadata.triggers.some((trigger) => (trigger == null ? void 0 : trigger.type) === "aiTool")) {
+    throw new Error(
+      "A Scout automation cannot use an aiTool trigger: an aiTool automation is itself a tool the agent calls. Use defineAutomation for that."
+    );
+  }
+  return { kind: "scout", metadata, instructions };
+}
+
+// src/metadata.ts
+var AUTOMATION_INSTRUCTIONS_MAX_LENGTH = 16 * 1024;
+
 // src/NotificationsClient.ts
 import { ApiClient } from "@uniformdev/context/api";
 var _url;
@@ -115,7 +135,9 @@ _url = new WeakMap();
 __privateAdd(_NotificationsClient, _url, "/api/v1/notifications");
 var NotificationsClient = _NotificationsClient;
 export {
+  AUTOMATION_INSTRUCTIONS_MAX_LENGTH,
   NotificationsClient,
   defineAutomation,
+  defineScoutAutomation,
   formatAutomationWebhookUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniformdev/automations-sdk",
-  "version": "20.72.3-alpha.40+ffbec41570",
+  "version": "20.72.3-alpha.45+2b8b05d58a",
   "description": "Uniform Automations SDK",
   "license": "SEE LICENSE IN LICENSE.txt",
   "exports": {
@@ -40,8 +40,8 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@uniformdev/context": "20.72.3-alpha.40+ffbec41570",
-    "@uniformdev/webhooks": "20.72.3-alpha.40+ffbec41570"
+    "@uniformdev/context": "20.72.3-alpha.45+2b8b05d58a",
+    "@uniformdev/webhooks": "20.72.3-alpha.45+2b8b05d58a"
   },
   "peerDependencies": {
     "ai": "^6.0.0",
@@ -62,5 +62,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "ffbec41570c4266c69674871c97146bf7bf86383"
+  "gitHead": "2b8b05d58ab275b4d29a9647feeaad47b0ab5cce"
 }