@amalgm/automations 0.2.1 → 0.2.3

package/dist/src/tool-surface.js

@@ -0,0 +1,126 @@
+import { NotFoundError, ValidationError } from './errors.js';
+export function createAutomationToolSurface(sdk) {
+    const view = async (automationId, runs = false) => {
+        const automation = await sdk.automations.get(automationId);
+        if (!automation)
+            throw new NotFoundError('Automation');
+        const [triggers, workflow, history] = await Promise.all([
+            sdk.triggers.list(automationId),
+            sdk.workflow.get(automationId),
+            runs === false ? undefined : sdk.runs.list(automationId, runs),
+        ]);
+        return { automation, triggers, workflow, ...(history ? { runs: history } : {}) };
+    };
+    const surface = {
+        async create(input) {
+            const { schedules = [], webhooks = [], workflow, ...automationInput } = input;
+            validateCreateIds(schedules, webhooks);
+            const staged = schedules.length > 0 || webhooks.length > 0 || workflow !== undefined;
+            const requestedEnabled = automationInput.enabled !== false;
+            const automation = await sdk.automations.create({
+                ...automationInput,
+                ...(staged ? { enabled: false } : {}),
+            });
+            try {
+                if (workflow)
+                    await sdk.workflow.create(automation.id, workflow);
+                for (const schedule of schedules)
+                    await sdk.triggers.schedule.create(automation.id, schedule);
+                for (const webhook of webhooks)
+                    await sdk.triggers.webhook.create(automation.id, webhook);
+                if (staged && requestedEnabled)
+                    await sdk.automations.update(automation.id, { enabled: true });
+            }
+            catch (error) {
+                throw disabledDraftError(automation.id, error);
+            }
+            return view(automation.id);
+        },
+        list: (query = {}) => sdk.automations.list(query),
+        get: view,
+        async update(automationId, input) {
+            requireChanges(input);
+            validateChanges(input.schedules, 'schedule');
+            validateChanges(input.webhooks, 'webhook');
+            const current = await sdk.automations.get(automationId);
+            if (!current)
+                throw new NotFoundError('Automation');
+            const changesResources = hasChanges(input.schedules) || hasChanges(input.webhooks) || Boolean(input.workflow);
+            const finalEnabled = input.patch?.enabled ?? current.enabled;
+            const { enabled: _enabled, ...metadata } = input.patch ?? {};
+            if (!changesResources) {
+                await sdk.automations.update(automationId, input.patch);
+                return view(automationId);
+            }
+            if (current.enabled)
+                await sdk.automations.update(automationId, { enabled: false });
+            try {
+                await applyTriggerChanges(automationId, input.schedules, sdk.triggers.schedule);
+                await applyTriggerChanges(automationId, input.webhooks, sdk.triggers.webhook);
+                await applyWorkflowChange(automationId, input.workflow, sdk.workflow);
+                await sdk.automations.update(automationId, { ...metadata, enabled: finalEnabled });
+            }
+            catch (error) {
+                throw disabledDraftError(automationId, error);
+            }
+            return view(automationId);
+        },
+        async delete(automationId) {
+            await sdk.automations.delete(automationId);
+            return { deleted: automationId };
+        },
+        runNow: (automationId, input = {}) => sdk.runs.runNow(automationId, input),
+    };
+    return Object.freeze(surface);
+}
+async function applyTriggerChanges(automationId, changes, operations) {
+    if (!changes)
+        return;
+    for (const triggerId of changes.delete ?? [])
+        await operations.delete(automationId, triggerId);
+    for (const item of changes.update ?? [])
+        await operations.update(automationId, item.id, item.patch);
+    for (const input of changes.create ?? [])
+        await operations.create(automationId, input);
+}
+async function applyWorkflowChange(automationId, change, workflow) {
+    if (!change)
+        return;
+    if ('create' in change)
+        await workflow.create(automationId, change.create);
+    else if ('update' in change)
+        await workflow.update(automationId, change.update);
+    else
+        await workflow.delete(automationId);
+}
+function requireChanges(input) {
+    if (!input.patch && !hasChanges(input.schedules) && !hasChanges(input.webhooks) && !input.workflow) {
+        throw new ValidationError('Automation update must include a change');
+    }
+}
+function hasChanges(changes) {
+    return Boolean(changes && [changes.create, changes.update, changes.delete]
+        .some((items) => items && items.length > 0));
+}
+function validateChanges(changes, label) {
+    if (!changes)
+        return;
+    const ids = [
+        ...changes.create?.flatMap(({ id }) => id ? [id] : []) ?? [],
+        ...changes.update?.map(({ id }) => id) ?? [],
+        ...changes.delete ?? [],
+    ];
+    if (new Set(ids).size !== ids.length) {
+        throw new ValidationError(`The same ${label} trigger cannot be changed twice`);
+    }
+}
+function validateCreateIds(schedules, webhooks) {
+    const ids = [...schedules, ...webhooks].flatMap(({ id }) => id ? [id] : []);
+    if (new Set(ids).size !== ids.length) {
+        throw new ValidationError('Trigger ids must be unique within an automation');
+    }
+}
+function disabledDraftError(automationId, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return new Error(`Automation ${automationId} remains disabled because configuration failed: ${reason}`);
+}

package/dist/src/types.d.ts

@@ -1,10 +1,5 @@
 import type { Json } from './contract.js';
 export type { Json } from './contract.js';
-/** The only authenticated identity Automations accepts from Core. */
-export interface AutomationTarget {
-    userId: string;
-    targetId: string;
-}
 interface StoredTriggerBase {
     userId: string;
     automationId: string;
@@ -13,9 +8,10 @@ interface StoredTriggerBase {
 }
 export interface StoredEventTrigger extends StoredTriggerBase {
     kind: 'event';
+    endpointId: string;
     source: string;
     event: string;
-    secret: string;
+    secret: string | null;
 }
 export interface DueCronTrigger extends StoredTriggerBase {
     kind: 'cron';
@@ -32,6 +28,9 @@ export type RunInput = {
 } | {
     kind: 'cron';
     scheduledFor: string;
+} | {
+    kind: 'manual';
+    payload: Json;
 };
 export type RunStatus = 'pending' | 'sent' | 'running' | 'completed' | 'failed';
 export interface AutomationRun {
@@ -51,27 +50,12 @@ export interface AutomationRun {
     output?: Json;
     error?: string;
 }
-export interface RunUpdate {
-    status: 'running' | 'completed' | 'failed';
-    startedAt?: string;
-    finishedAt?: string;
-    output?: Json;
-    error?: string;
-}
 export interface AutomationStore {
-    eventTriggers(target: AutomationTarget): Promise<StoredEventTrigger[]>;
+    eventTrigger(endpointId: string): Promise<StoredEventTrigger | null>;
     dueCronTriggers(now: Date): Promise<DueCronTrigger[]>;
     enqueueEvent(trigger: StoredEventTrigger, input: Extract<RunInput, {
         kind: 'event';
-    }>, now: Date): Promise<AutomationRun | null>;
+    }>, now: Date, deliveryKey: string | null): Promise<AutomationRun | null>;
     enqueueCron(trigger: DueCronTrigger, nextRunAt: string, now: Date): Promise<AutomationRun | null>;
-    pendingRuns(target: AutomationTarget): Promise<AutomationRun[]>;
-    markSent(runId: string, target: AutomationTarget, now: Date): Promise<boolean>;
-    updateRun(target: AutomationTarget, runId: string, update: RunUpdate): Promise<AutomationRun | null>;
-}
-/** The complete transport capability Automations needs from Core. */
-export interface AutomationTransport {
-    isOnline(target: AutomationTarget): boolean;
-    send(run: AutomationRun): Promise<boolean>;
 }
-export type AutomationLog = (event: 'event.rejected' | 'run.pending' | 'drain.started' | 'run.sent' | 'run.failed', details: Readonly<Record<string, string>>) => void;
+export type AutomationLog = (event: 'event.rejected' | 'run.pending', details: Readonly<Record<string, string>>) => void;

package/dist/src/webhook.d.ts

@@ -1,6 +1,20 @@
 import type { Json, StoredEventTrigger } from './types.js';
 export declare function normalizeHeaders(headers: Record<string, string>): Record<string, string>;
-export declare function verifyEventSecret(secret: string, headers: Record<string, string>, body: Buffer): boolean;
+export declare function verifyEventSecret(secret: string | null, headers: Record<string, string>, body: Buffer): boolean;
+/**
+ * Generates and verifies the bearer capability embedded in a webhook URL.
+ * Supabase stores only the random endpoint id; possession also requires the
+ * service-held HMAC key, so a database read cannot mint working URLs.
+ */
+export declare class WebhookEndpoints {
+    #private;
+    readonly origin: string;
+    constructor(origin: string, key: string | Buffer, randomId?: () => string);
+    createId(): string;
+    url(id: string): string;
+    resolve(token: string): string | null;
+}
+export declare function webhookDeliveryKey(headers: Record<string, string>, payload: Json): string | null;
 export declare function matchesEvent(trigger: Pick<StoredEventTrigger, 'source' | 'event'>, source: string, event: string): boolean;
 export declare function eventReferences(headers: Record<string, string>, payload: Json): {
     primary: {

package/dist/src/webhook.js

@@ -1,6 +1,16 @@
 import crypto from 'node:crypto';
 const HMAC_HEADERS = ['x-webhook-signature', 'x-hub-signature-256', 'x-hub-signature'];
 const TOKEN_HEADERS = ['x-amalgm-webhook-secret', 'x-webhook-secret', 'x-gitlab-token'];
+const DELIVERY_HEADERS = [
+    'idempotency-key',
+    'x-github-delivery',
+    'x-gitlab-event-uuid',
+    'x-linear-delivery',
+    'svix-id',
+    'webhook-id',
+];
+const ENDPOINT_ID = /^[a-f0-9]{32}$/;
+const MAX_DELIVERY_KEY_BYTES = 500;
 function equal(left, right) {
     const a = Buffer.from(left);
     const b = Buffer.from(right);
@@ -10,6 +20,8 @@ export function normalizeHeaders(headers) {
     return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
 }
 export function verifyEventSecret(secret, headers, body) {
+    if (secret === null)
+        return true;
     const normalized = normalizeHeaders(headers);
     for (const name of HMAC_HEADERS) {
         const supplied = normalized[name];
@@ -28,6 +40,63 @@ export function verifyEventSecret(secret, headers, body) {
     }
     return false;
 }
+/**
+ * Generates and verifies the bearer capability embedded in a webhook URL.
+ * Supabase stores only the random endpoint id; possession also requires the
+ * service-held HMAC key, so a database read cannot mint working URLs.
+ */
+export class WebhookEndpoints {
+    origin;
+    #key;
+    #randomId;
+    constructor(origin, key, randomId = endpointId) {
+        this.origin = webhookOrigin(origin);
+        this.#key = Buffer.isBuffer(key) ? Buffer.from(key) : Buffer.from(key, 'utf8');
+        if (this.#key.length < 32)
+            throw new Error('Webhook endpoint key must contain at least 32 bytes');
+        this.#randomId = randomId;
+    }
+    createId() {
+        const value = this.#randomId();
+        if (!ENDPOINT_ID.test(value))
+            throw new Error('Webhook endpoint id must be 128-bit lowercase hex');
+        return value;
+    }
+    url(id) {
+        if (!ENDPOINT_ID.test(id))
+            throw new Error('Invalid webhook endpoint id');
+        return `${this.origin}/e/${id}.${this.#signature(id)}`;
+    }
+    resolve(token) {
+        const separator = token.indexOf('.');
+        if (separator === -1 || token.indexOf('.', separator + 1) !== -1)
+            return null;
+        const id = token.slice(0, separator);
+        const supplied = token.slice(separator + 1);
+        if (!ENDPOINT_ID.test(id) || !supplied || !equal(supplied, this.#signature(id)))
+            return null;
+        return id;
+    }
+    #signature(id) {
+        return crypto.createHmac('sha256', this.#key).update(id).digest('base64url');
+    }
+}
+export function webhookDeliveryKey(headers, payload) {
+    const normalized = normalizeHeaders(headers);
+    for (const name of DELIVERY_HEADERS) {
+        const value = normalized[name]?.trim();
+        if (!value)
+            continue;
+        return boundedDeliveryKey(`${name}:${value}`);
+    }
+    if (normalized['stripe-signature']) {
+        const object = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : {};
+        if (typeof object.id === 'string' && object.id.trim()) {
+            return boundedDeliveryKey(`stripe-event:${object.id.trim()}`);
+        }
+    }
+    return null;
+}
 export function matchesEvent(trigger, source, event) {
     return (trigger.source === '*' || trigger.source === source)
         && (trigger.event === '*' || trigger.event === event);
@@ -58,3 +127,20 @@ export function eventReferences(headers, payload) {
 export function eventReference(headers, payload) {
     return eventReferences(headers, payload).primary;
 }
+const endpointId = () => crypto.randomBytes(16).toString('hex');
+function webhookOrigin(value) {
+    const parsed = new URL(value);
+    const local = parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1' || parsed.hostname.endsWith('.local');
+    if (parsed.protocol !== 'https:' && !(local && parsed.protocol === 'http:')) {
+        throw new Error('Webhook origin must use HTTPS');
+    }
+    if (parsed.pathname !== '/' || parsed.search || parsed.hash)
+        throw new Error('Webhook origin cannot include a path');
+    return parsed.toString().replace(/\/$/, '');
+}
+function boundedDeliveryKey(value) {
+    if (Buffer.byteLength(value) > MAX_DELIVERY_KEY_BYTES) {
+        throw Object.assign(new Error('Webhook delivery id is too long'), { status: 400 });
+    }
+    return value;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.2.1",
-  "description": "Amalgm's cloud automation SDK: Supabase-backed configuration, trigger admission, and run delivery.",
+  "version": "0.2.3",
+  "description": "Amalgm's automation SDK: durable trigger admission and target-machine execution.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
   "files": [
     "dist",
     "skills",
-    "supabase",
+    "supabase/migrations",
     "AXIOMS.md",
     "PURPOSE.md",
     "README.md"

package/skills/automations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: automations
-description: Create, inspect, change, or delete Amalgm automations, schedules, workflows, and run history through the Automations MCP tools.
+description: Create, inspect, change, delete, or manually run complete Amalgm automation definitions and inspect their run history through the Automations MCP tools.
 ---
 
 # Amalgm Automations
@@ -11,11 +11,8 @@ the agent adapter over the same hosted SDK used by the UI.
 ## Create a scheduled notification
 
 For a request such as “remind me to call my mom every minute for the next ten
-minutes,” create three resources for the current machine:
-
-1. `amalgm_automations_create` with a clear name and the current machine target.
-2. `amalgm_workflow_create` with a readable script summary and this compiled
-   plan:
+minutes,” make one `amalgm_automations_create` call containing the complete
+definition. Include a readable workflow summary and this compiled plan:
 
 ```json
 {
@@ -30,23 +27,39 @@ minutes,” create three resources for the current machine:
 }
 ```
 
-3. `amalgm_schedule_triggers_create` with cron `* * * * *`, the user's
-   timezone, and `maxOccurrences: 10`.
+Include one schedule with cron `* * * * *`, the user's timezone, and
+`maxOccurrences: 10`. Omit `targetId` in a machine-bound session; never guess
+an opaque target id.
 
-Create the automation disabled, attach its workflow and trigger, then enable it
-only after both exist. If setup fails, leave it disabled and explain which
-resource failed. Never replace a bounded occurrence count with an unbounded
-schedule plus a promise to clean it up later.
+The tool stages multi-resource configuration disabled and enables it only after
+setup succeeds. If setup fails, report the returned disabled draft id. Never
+replace a bounded occurrence count with an unbounded schedule plus a promise to
+clean it up later.
 
 ## Read and change
 
-Use list/get before changing an existing automation. Schedule and webhook
-triggers are separate resources. A workflow is zero-or-one per automation. Run
-history is read-only and remains after configuration deletion.
+Use `amalgm_automations_list` or `amalgm_automations_get` before changing an
+existing automation. Use `amalgm_automations_update` for grouped metadata,
+schedule, webhook, or workflow changes, and `amalgm_automations_delete` only
+after identifying the exact automation. Schedule and webhook triggers remain
+distinct resources inside the definition. A workflow is zero-or-one per
+automation. Run history is read-only, requested through `get`, and remains
+after configuration deletion.
+
+Use `amalgm_automations_run_now` when the user wants an enabled automation to
+run immediately. Supply `idempotency_key` when a caller may retry the same
+request. The result is a durable `pending` run, not proof that its selected
+machine has finished it; use `amalgm_automations_get` with run history when the
+user asks for the outcome.
+
+Action discovery belongs to the Tools product, not Automations.
 
 `pending` means a run is durable and waiting for its selected machine. `sent`
 or `running` means that machine holds a lease. `completed` and `failed` are
 terminal. Do not infer delivery from the schedule alone; inspect runs when the
 user asks whether it actually happened.
 
-Webhook secrets are write-only. Never echo, log, or place them in a workflow.
+Each webhook trigger returns one copyable `webhookUrl`; use that URL as the
+provider destination. A separate provider signing secret is optional and
+write-only. Never echo, log, or place either credential in a workflow. Rotate
+the URL when its bearer capability may have been exposed.