@amalgm/automations 0.2.1 → 0.2.3

package/dist/src/contract.d.ts

@@ -1,6 +1,8 @@
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
+import type { AutomationRun, ListRuns, RunAutomationNow } from './run-contract.js';
+export type { AutomationPlan, AutomationRun, AutomationRunJournal, AutomationStepRun, AutomationStepStatus, ListRuns, RunAutomationNow, RunStatus, ToolActionStep, } from './run-contract.js';
 export type AutomationScope = 'automations:read' | 'automations:write' | 'runs:read' | 'runs:execute' | '*';
 /** Identity resolved by Amalgm before the SDK is bound to a caller. */
 export interface AutomationPrincipal {
@@ -66,6 +68,8 @@ export interface WebhookTrigger extends TriggerBase {
     kind: 'webhook';
     source: string;
     event: string;
+    /** Bearer-capability URL. Treat it as a credential and rotate it if exposed. */
+    webhookUrl: string;
     secretConfigured: boolean;
 }
 export type Trigger = ScheduleTrigger | WebhookTrigger;
@@ -84,26 +88,21 @@ export interface UpdateScheduleTrigger {
     /** Set a new finite budget, or null to make the schedule unbounded. */
     maxOccurrences?: number | null;
 }
-export interface ToolActionStep {
-    id: string;
-    actionId: string;
-    input: Json;
-}
-export interface AutomationPlan {
-    version: 1;
-    steps: ToolActionStep[];
-}
 export interface CreateWebhookTrigger {
     id?: string;
     source?: string;
     event?: string;
-    secret: string;
+    /** Optional provider signing secret; the generated webhook URL authenticates admission. */
+    secret?: string;
     enabled?: boolean;
 }
 export interface UpdateWebhookTrigger {
     source?: string;
     event?: string;
-    secret?: string;
+    /** Set null to remove provider-signature verification. */
+    secret?: string | null;
+    /** Invalidates the existing URL and returns its replacement. */
+    rotateUrl?: boolean;
     enabled?: boolean;
 }
 export interface Workflow {
@@ -132,25 +131,6 @@ export interface UpdateWorkflow {
     allowlist?: Json | null;
     limits?: Json | null;
 }
-export type RunStatus = 'pending' | 'sent' | 'running' | 'completed' | 'failed';
-export interface AutomationRun {
-    id: string;
-    automationId: string;
-    triggerId: string;
-    workflowId: string;
-    targetId: string;
-    status: RunStatus;
-    input: Json;
-    createdAt: string;
-    sentAt?: string;
-    startedAt?: string;
-    finishedAt?: string;
-    output?: Json;
-    error?: string;
-}
-export interface ListRuns extends PageQuery {
-    status?: RunStatus;
-}
 export interface AutomationCrud {
     readonly automations: {
         create(input: CreateAutomation): Promise<Automation>;
@@ -183,6 +163,7 @@ export interface AutomationCrud {
         delete(automationId: string): Promise<void>;
     };
     readonly runs: {
+        runNow(automationId: string, input?: RunAutomationNow): Promise<AutomationRun>;
         list(automationId: string, query?: ListRuns): Promise<Page<AutomationRun>>;
         get(automationId: string, runId: string): Promise<AutomationRun | null>;
     };
@@ -190,4 +171,3 @@ export interface AutomationCrud {
 export interface AutomationCrudService {
     for(principal: AutomationPrincipal): AutomationCrud;
 }
-export {};

package/dist/src/crud/context.d.ts

@@ -1,14 +1,16 @@
 import type { AutomationPrincipal } from '../contract.js';
 import type { AutomationCrudRepository } from './repository.js';
+import type { WebhookEndpoints } from '../webhook.js';
 export interface CrudContext {
     repository: AutomationCrudRepository;
     principal: AutomationPrincipal;
     clock: () => Date;
+    webhooks: WebhookEndpoints;
     read(): void;
     write(): void;
     runsRead(): void;
     exists(automationId: string): Promise<void>;
 }
-export declare function createContext(repository: AutomationCrudRepository, principal: AutomationPrincipal, clock: () => Date): CrudContext;
+export declare function createContext(repository: AutomationCrudRepository, principal: AutomationPrincipal, clock: () => Date, webhooks: WebhookEndpoints): CrudContext;
 export declare function assertTarget(principal: AutomationPrincipal, targetId: string): void;
 export declare function resolveTarget(principal: AutomationPrincipal, targetId?: string): string;

package/dist/src/crud/context.js

@@ -1,11 +1,12 @@
 import { ForbiddenError, NotFoundError, ValidationError } from '../errors.js';
 import { id, requiredText } from '../validation.js';
-export function createContext(repository, principal, clock) {
+export function createContext(repository, principal, clock, webhooks) {
     assertPrincipal(principal);
     return {
         repository,
         principal,
         clock,
+        webhooks,
         read: () => assertScope(principal, 'automations:read'),
         write: () => assertScope(principal, 'automations:write'),
         runsRead: () => assertScope(principal, 'runs:read'),

package/dist/src/crud/repository.d.ts

@@ -1,4 +1,4 @@
-import type { Automation, AutomationRun, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, ListAutomations, ListRuns, Page, PageQuery, ScheduleTrigger, Trigger, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow } from '../contract.js';
+import type { Automation, AutomationRun, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, Json, ListAutomations, ListRuns, Page, PageQuery, ScheduleTrigger, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow } from '../contract.js';
 export type StoredScheduleCreate = Omit<Required<CreateScheduleTrigger>, 'maxOccurrences'> & {
     maxOccurrences: number | null;
     nextRunAt: string;
@@ -7,6 +7,16 @@ export type StoredScheduleUpdate = UpdateScheduleTrigger & {
     nextRunAt?: string;
     remainingOccurrences?: number | null;
 };
+export type WebhookTriggerRecord = Omit<WebhookTrigger, 'webhookUrl'> & {
+    endpointId: string;
+};
+export type StoredWebhookCreate = Omit<Required<CreateWebhookTrigger>, 'secret'> & {
+    secret: string | null;
+    endpointId: string;
+};
+export type StoredWebhookUpdate = Omit<UpdateWebhookTrigger, 'rotateUrl'> & {
+    endpointId?: string;
+};
 export type NormalizedListAutomations = Required<PageQuery> & Omit<ListAutomations, keyof PageQuery>;
 export type NormalizedListRuns = Required<PageQuery> & Omit<ListRuns, keyof PageQuery>;
 export interface AutomationCrudRepository {
@@ -20,16 +30,17 @@ export interface AutomationCrudRepository {
     getScheduleTrigger(userId: string, automationId: string, triggerId: string): Promise<ScheduleTrigger | null>;
     updateScheduleTrigger(userId: string, automationId: string, triggerId: string, patch: StoredScheduleUpdate): Promise<ScheduleTrigger | null>;
     deleteScheduleTrigger(userId: string, automationId: string, triggerId: string): Promise<boolean>;
-    createWebhookTrigger(userId: string, automationId: string, input: Required<CreateWebhookTrigger>): Promise<WebhookTrigger>;
-    listWebhookTriggers(userId: string, automationId: string, query: Required<PageQuery>): Promise<Page<WebhookTrigger>>;
-    getWebhookTrigger(userId: string, automationId: string, triggerId: string): Promise<WebhookTrigger | null>;
-    updateWebhookTrigger(userId: string, automationId: string, triggerId: string, patch: UpdateWebhookTrigger): Promise<WebhookTrigger | null>;
+    createWebhookTrigger(userId: string, automationId: string, input: StoredWebhookCreate): Promise<WebhookTriggerRecord>;
+    listWebhookTriggers(userId: string, automationId: string, query: Required<PageQuery>): Promise<Page<WebhookTriggerRecord>>;
+    getWebhookTrigger(userId: string, automationId: string, triggerId: string): Promise<WebhookTriggerRecord | null>;
+    updateWebhookTrigger(userId: string, automationId: string, triggerId: string, patch: StoredWebhookUpdate): Promise<WebhookTriggerRecord | null>;
     deleteWebhookTrigger(userId: string, automationId: string, triggerId: string): Promise<boolean>;
-    listTriggers(userId: string, automationId: string): Promise<Trigger[]>;
+    listTriggers(userId: string, automationId: string): Promise<Array<ScheduleTrigger | WebhookTriggerRecord>>;
     createWorkflow(userId: string, automationId: string, input: Required<CreateWorkflow>): Promise<Workflow>;
     getWorkflow(userId: string, automationId: string): Promise<Workflow | null>;
     updateWorkflow(userId: string, automationId: string, patch: UpdateWorkflow): Promise<Workflow | null>;
     deleteWorkflow(userId: string, automationId: string): Promise<boolean>;
     listRuns(userId: string, automationId: string, query: NormalizedListRuns): Promise<Page<AutomationRun>>;
     getRun(userId: string, automationId: string, runId: string): Promise<AutomationRun | null>;
+    runAutomationNow(userId: string, automationId: string, input: Json, idempotencyKey: string | null, now: Date): Promise<AutomationRun | null>;
 }

package/dist/src/crud/runs.d.ts

@@ -1,3 +1,3 @@
 import type { AutomationCrud } from '../contract.js';
-import type { CrudContext } from './context.js';
+import { type CrudContext } from './context.js';
 export declare function runOperations(context: CrudContext): AutomationCrud['runs'];

package/dist/src/crud/runs.js

@@ -1,8 +1,31 @@
-import { parseListRuns } from '../schema.js';
+import { AutomationError, NotFoundError, ValidationError } from '../errors.js';
+import { compiledAutomationPlan } from '../plan.js';
+import { parseListRuns, parseRunAutomationNow } from '../schema.js';
 import { id, page } from '../validation.js';
+import { assertTarget } from './context.js';
 export function runOperations(context) {
     const { principal, repository } = context;
     return {
+        runNow: async (automationId, input = {}) => {
+            context.write();
+            const automationKey = id(automationId, 'Automation id');
+            const parsed = parseRunAutomationNow(input);
+            const automation = await repository.getAutomation(principal.userId, automationKey);
+            if (!automation)
+                throw new NotFoundError('Automation');
+            assertTarget(principal, automation.targetId);
+            if (!automation.enabled)
+                throw new ValidationError('Automation must be enabled before it can run');
+            const workflow = await repository.getWorkflow(principal.userId, automationKey);
+            if (!workflow?.compiled)
+                throw new ValidationError('Automation needs a compiled workflow before it can run');
+            compiledAutomationPlan(workflow.compiled);
+            const run = await repository.runAutomationNow(principal.userId, automationKey, { kind: 'manual', payload: parsed.input ?? {} }, parsed.idempotencyKey ?? null, context.clock());
+            if (!run) {
+                throw new AutomationError('conflict', 'Automation changed before the run was admitted; inspect it and try again');
+            }
+            return run;
+        },
         list: async (automationId, query = {}) => {
             context.runsRead();
             const parsed = parseListRuns(query);

package/dist/src/crud/triggers.js

@@ -3,7 +3,7 @@ import { parseCreateScheduleTrigger, parseCreateWebhookTrigger, parsePageQuery,
 import { nextCronAt } from '../schedule.js';
 import { id, newId, page, schedule } from '../validation.js';
 export function triggerOperations(context) {
-    const { principal, repository } = context;
+    const { principal, repository, webhooks } = context;
     const unique = async (automationId, triggerId) => {
         const exists = (await repository.listTriggers(principal.userId, automationId))
             .some((trigger) => trigger.id === triggerId);
@@ -14,7 +14,7 @@ export function triggerOperations(context) {
         list: async (automationId) => {
             context.read();
             await context.exists(automationId);
-            return repository.listTriggers(principal.userId, automationId);
+            return (await repository.listTriggers(principal.userId, automationId)).map((trigger) => (trigger.kind === 'webhook' ? publicWebhook(trigger, webhooks) : trigger));
         },
         schedule: {
             create: async (automationId, input) => {
@@ -80,31 +80,36 @@ export function triggerOperations(context) {
                 const parsed = parseCreateWebhookTrigger(input);
                 if (parsed.id)
                     await unique(automationId, parsed.id);
-                return repository.createWebhookTrigger(principal.userId, automationId, {
+                return publicWebhook(await repository.createWebhookTrigger(principal.userId, automationId, {
                     id: parsed.id ? id(parsed.id, 'Webhook trigger id') : newId('webhook'),
                     source: parsed.source || '*',
                     event: parsed.event || '*',
-                    secret: parsed.secret,
+                    secret: parsed.secret ?? null,
                     enabled: parsed.enabled !== false,
-                });
+                    endpointId: webhooks.createId(),
+                }), webhooks);
             },
             list: async (automationId, query = {}) => {
                 context.read();
                 await context.exists(automationId);
-                return repository.listWebhookTriggers(principal.userId, automationId, page(parsePageQuery(query)));
+                const result = await repository.listWebhookTriggers(principal.userId, automationId, page(parsePageQuery(query)));
+                return { ...result, items: result.items.map((trigger) => publicWebhook(trigger, webhooks)) };
             },
             get: async (automationId, triggerId) => {
                 context.read();
                 await context.exists(automationId);
-                return repository.getWebhookTrigger(principal.userId, automationId, id(triggerId, 'Webhook trigger id'));
+                const trigger = await repository.getWebhookTrigger(principal.userId, automationId, id(triggerId, 'Webhook trigger id'));
+                return trigger ? publicWebhook(trigger, webhooks) : null;
             },
             update: async (automationId, triggerId, patch) => {
                 context.write();
                 await context.exists(automationId);
-                const updated = await repository.updateWebhookTrigger(principal.userId, automationId, id(triggerId, 'Webhook trigger id'), parseUpdateWebhookTrigger(patch));
+                const parsed = parseUpdateWebhookTrigger(patch);
+                const { rotateUrl, ...changes } = parsed;
+                const updated = await repository.updateWebhookTrigger(principal.userId, automationId, id(triggerId, 'Webhook trigger id'), { ...changes, ...(rotateUrl ? { endpointId: webhooks.createId() } : {}) });
                 if (!updated)
                     throw new NotFoundError('Webhook trigger');
-                return updated;
+                return publicWebhook(updated, webhooks);
             },
             delete: async (automationId, triggerId) => {
                 context.write();
@@ -116,3 +121,7 @@ export function triggerOperations(context) {
         },
     };
 }
+function publicWebhook(trigger, webhooks) {
+    const { endpointId, ...publicTrigger } = trigger;
+    return { ...publicTrigger, webhookUrl: webhooks.url(endpointId) };
+}

package/dist/src/crud.d.ts

@@ -1,9 +1,11 @@
 import type { AutomationCrud, AutomationCrudService as AutomationCrudServiceContract, AutomationPrincipal } from './contract.js';
 import type { AutomationCrudRepository } from './crud/repository.js';
-export type { AutomationCrudRepository, NormalizedListAutomations, NormalizedListRuns, StoredScheduleCreate, StoredScheduleUpdate, } from './crud/repository.js';
+import { WebhookEndpoints } from './webhook.js';
+export type { AutomationCrudRepository, NormalizedListAutomations, NormalizedListRuns, StoredScheduleCreate, StoredScheduleUpdate, StoredWebhookCreate, StoredWebhookUpdate, WebhookTriggerRecord, } from './crud/repository.js';
 export declare class AutomationCrudService implements AutomationCrudServiceContract {
+    #private;
     private readonly repository;
     private readonly clock;
-    constructor(repository: AutomationCrudRepository, clock?: () => Date);
+    constructor(repository: AutomationCrudRepository, clock?: () => Date, webhooks?: WebhookEndpoints);
     for(principal: AutomationPrincipal): AutomationCrud;
 }

package/dist/src/crud.js

@@ -3,15 +3,18 @@ import { createContext } from './crud/context.js';
 import { runOperations } from './crud/runs.js';
 import { triggerOperations } from './crud/triggers.js';
 import { workflowOperations } from './crud/workflow.js';
+import { WebhookEndpoints } from './webhook.js';
 export class AutomationCrudService {
     repository;
     clock;
-    constructor(repository, clock = () => new Date()) {
+    #webhooks;
+    constructor(repository, clock = () => new Date(), webhooks) {
         this.repository = repository;
         this.clock = clock;
+        this.#webhooks = webhooks ?? new WebhookEndpoints('http://automations.local', Buffer.from('local-automations-webhook-key-32-bytes-minimum'));
     }
     for(principal) {
-        const context = createContext(this.repository, principal, this.clock);
+        const context = createContext(this.repository, principal, this.clock, this.#webhooks);
         return {
             automations: automationOperations(context),
             triggers: triggerOperations(context),

package/dist/src/events-http.d.ts

@@ -1,19 +1,17 @@
 import { Automations } from './automations.js';
-import type { AutomationTarget } from './types.js';
+import { type WebhookEndpoints } from './webhook.js';
 export interface AutomationEventReceipt {
     receivedAt: string;
-    targetId: string;
     source: string;
     event: string;
-    runIds: string[];
+    runId?: string;
     status: 'pending' | 'unmatched';
 }
 export interface AutomationEventsApiConfig {
     delivery: Pick<Automations, 'receiveEvent'>;
-    target(request: Request): Promise<AutomationTarget>;
+    endpoints: Pick<WebhookEndpoints, 'resolve'>;
     now?: () => Date;
     maxBodyBytes?: number;
-    recentLimit?: number;
 }
 export type AutomationEventsApi = (request: Request) => Promise<Response>;
 export declare function createAutomationEventsApi(config: AutomationEventsApiConfig): AutomationEventsApi;

package/dist/src/events-http.js

@@ -1,59 +1,55 @@
-import { Automations, EventRejectedError } from './automations.js';
-import { eventReference } from './webhook.js';
+import { Automations, EventEndpointNotFoundError, EventRejectedError } from './automations.js';
+import { webhookDeliveryKey } from './webhook.js';
 // Engine reference: amalgm-engine/runtime/scripts/amalgm-mcp/events/ingress.js.
-// The 2 MiB transport bound and safe recent-events door are preserved. The
-// authority changes deliberately: success now means matching runs are durable
-// in Supabase, never that an envelope was written to a local SQLite inbox.
+// The 2 MiB transport bound is preserved. Success means the matching run is
+// durable in Supabase, never that an envelope was written to a local inbox.
 const DEFAULT_MAX_BODY_BYTES = 2 * 1024 * 1024;
-const DEFAULT_RECENT_LIMIT = 200;
 export function createAutomationEventsApi(config) {
-    const recent = [];
     const now = config.now ?? (() => new Date());
     const maxBodyBytes = positiveInteger(config.maxBodyBytes, DEFAULT_MAX_BODY_BYTES);
-    const recentLimit = positiveInteger(config.recentLimit, DEFAULT_RECENT_LIMIT);
     return async (request) => {
         const pathname = new URL(request.url).pathname;
-        if (pathname !== '/events')
+        const token = pathname.match(/^\/e\/([^/]+)$/)?.[1];
+        if (!token)
             return json(404, { error: 'not found' });
-        if (request.method === 'GET')
-            return json(200, { events: recent.slice(-50) });
         if (request.method !== 'POST')
             return json(405, { error: 'method not allowed' });
         try {
+            const endpointId = config.endpoints.resolve(token);
+            if (!endpointId)
+                throw new EventEndpointNotFoundError();
             const body = await readLimitedBody(request, maxBodyBytes);
             const payload = parsePayload(body);
             const headers = Object.fromEntries(request.headers.entries());
-            const target = await config.target(request);
             const receivedAt = now();
-            const runs = await config.delivery.receiveEvent({
-                target,
+            const admission = await config.delivery.receiveEvent({
+                endpointId,
                 headers,
                 body,
                 payload,
+                deliveryKey: webhookDeliveryKey(headers, payload),
                 now: receivedAt,
             });
-            const firstInput = runs[0]?.input;
-            const reference = firstInput?.kind === 'event'
-                ? { source: firstInput.source, event: firstInput.event }
-                : eventReference(headers, payload);
             const receipt = {
                 receivedAt: receivedAt.toISOString(),
-                targetId: target.targetId,
-                source: reference.source,
-                event: reference.event,
-                runIds: runs.map(({ id }) => id),
-                status: runs.length ? 'pending' : 'unmatched',
+                source: admission.source,
+                event: admission.event,
+                ...(admission.run ? { runId: admission.run.id } : {}),
+                status: admission.run ? 'pending' : 'unmatched',
             };
-            recent.push(receipt);
-            if (recent.length > recentLimit)
-                recent.splice(0, recent.length - recentLimit);
             return json(202, { ok: true, accepted: true, ...receipt });
         }
         catch (error) {
+            if (error instanceof EventEndpointNotFoundError)
+                return json(404, { error: error.message });
             if (error instanceof EventRejectedError)
                 return json(401, { error: error.message });
             if (error instanceof EventHttpError)
                 return json(error.status, { error: error.message });
+            const status = Number(error?.status);
+            if (Number.isInteger(status) && status >= 400 && status <= 499) {
+                return json(status, { error: error instanceof Error ? error.message : String(error) });
+            }
             return json(500, { error: error instanceof Error ? error.message : String(error) });
         }
     };

package/dist/src/executor.d.ts

@@ -1,16 +1,25 @@
-import type { AutomationPlan, Json } from './contract.js';
+import type { Json } from './contract.js';
 import type { ClaimedAutomationRun, MachineRuns } from './machine.js';
+export { automationPlan } from './plan.js';
 export interface AutomationActionPort {
     call(input: Readonly<{
         actionId: string;
         payload: Json;
         idempotencyKey: string;
+        signal: AbortSignal;
     }>): Promise<Json>;
 }
+export interface AutomationRunExecutorOptions {
+    readonly now?: () => Date;
+    readonly heartbeatMs?: number;
+    readonly maxAttempts?: number;
+    readonly retryDelayMs?: (attempt: number) => number;
+}
 export declare class AutomationRunExecutor {
+    #private;
     private readonly runs;
     private readonly actions;
-    constructor(runs: MachineRuns, actions: AutomationActionPort);
+    constructor(runs: MachineRuns, actions: AutomationActionPort, options?: AutomationRunExecutorOptions);
     execute(run: ClaimedAutomationRun): Promise<void>;
 }
-export declare function automationPlan(snapshot: Json): AutomationPlan;
+export declare function transientFailure(error: unknown): boolean;