@amalgm/automations 0.2.1 → 0.2.2

package/dist/src/run-journal.js

@@ -0,0 +1,56 @@
+export function emptyJournal() {
+    return { version: 1, steps: [] };
+}
+export function runJournal(value, plan) {
+    if (value === undefined)
+        return emptyJournal();
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Run step journal is invalid');
+    const source = value;
+    if (source.version !== 1 || !Array.isArray(source.steps))
+        throw new Error('Run step journal is invalid');
+    const planIds = new Set(plan.map(({ id }) => id));
+    const steps = source.steps.map(runStep);
+    const ids = new Set();
+    for (const step of steps) {
+        if (!planIds.has(step.id))
+            throw new Error(`Run step is not in the immutable plan: ${step.id}`);
+        if (ids.has(step.id))
+            throw new Error(`Run step journal has a duplicate id: ${step.id}`);
+        ids.add(step.id);
+    }
+    return { version: 1, steps };
+}
+export function completed(journal, stepId) {
+    return journal.steps.some((step) => step.id === stepId && step.status === 'completed');
+}
+export function stepAttempt(journal, stepId) {
+    return journal.steps.find((step) => step.id === stepId)?.attempts ?? 0;
+}
+export function putStep(journal, step) {
+    const index = journal.steps.findIndex(({ id }) => id === step.id);
+    const steps = [...journal.steps];
+    if (index === -1)
+        steps.push(step);
+    else
+        steps[index] = step;
+    return { version: 1, steps };
+}
+/** Journals are constructed from JSON fields only; this is the persistence boundary. */
+export function journalJson(journal) {
+    return journal;
+}
+function runStep(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Run step is invalid');
+    const item = value;
+    if (typeof item.id !== 'string' || !item.id)
+        throw new Error('Run step id is invalid');
+    if (item.status !== 'running' && item.status !== 'completed' && item.status !== 'failed') {
+        throw new Error(`Run step status is invalid: ${item.id}`);
+    }
+    if (!Number.isInteger(item.attempts) || Number(item.attempts) < 1 || typeof item.startedAt !== 'string') {
+        throw new Error(`Run step attempt is invalid: ${item.id}`);
+    }
+    return item;
+}

package/dist/src/runner.d.ts

@@ -0,0 +1,14 @@
+import type { ClaimedAutomationRun, MachineRuns } from './machine.js';
+export interface AutomationMachineRunnerOptions {
+    readonly runs: MachineRuns;
+    readonly execute: (run: ClaimedAutomationRun) => Promise<void>;
+    readonly batchSize?: number;
+    readonly leaseSeconds?: number;
+    readonly pollIntervalMs?: number;
+    readonly maxBackoffMs?: number;
+    readonly log?: (event: string, details?: Readonly<Record<string, unknown>>) => void;
+}
+export declare function createAutomationMachineRunner(options: AutomationMachineRunnerOptions): Readonly<{
+    start(): void;
+    close(): Promise<void>;
+}>;

package/dist/src/runner.js

@@ -0,0 +1,70 @@
+export function createAutomationMachineRunner(options) {
+    const batchSize = integer(options.batchSize ?? 8, 1, 20, 'batchSize');
+    const leaseSeconds = integer(options.leaseSeconds ?? 60, 30, 900, 'leaseSeconds');
+    const pollIntervalMs = integer(options.pollIntervalMs ?? 1_000, 1, 60_000, 'pollIntervalMs');
+    const maxBackoffMs = integer(options.maxBackoffMs ?? Math.max(30_000, pollIntervalMs), pollIntervalMs, 300_000, 'maxBackoffMs');
+    let active = null;
+    let timer = null;
+    let stopped = true;
+    let failures = 0;
+    let nextDelay = pollIntervalMs;
+    const schedule = (delay) => {
+        if (stopped)
+            return;
+        timer = setTimeout(drain, delay);
+        timer.unref?.();
+    };
+    const drain = () => {
+        if (stopped || active)
+            return active;
+        active = options.runs.claim({ limit: batchSize, leaseSeconds })
+            .then(async (runs) => {
+            failures = 0;
+            if (runs.length)
+                options.log?.('automations.claimed', { count: runs.length });
+            const settled = await Promise.allSettled(runs.map(options.execute));
+            settled.forEach((result) => {
+                if (result.status === 'rejected') {
+                    options.log?.('automations.run.failed', { error: safe(result.reason) });
+                }
+            });
+            nextDelay = runs.length === batchSize ? 0 : pollIntervalMs;
+        })
+            .catch((error) => {
+            failures += 1;
+            const delayMs = Math.min(maxBackoffMs, pollIntervalMs * (2 ** Math.min(failures - 1, 10)));
+            options.log?.('automations.poll.failed', { error: safe(error), retryInMs: delayMs });
+            nextDelay = delayMs;
+        })
+            .finally(() => {
+            active = null;
+            schedule(nextDelay);
+        });
+        return active;
+    };
+    return Object.freeze({
+        start() {
+            if (!stopped)
+                return;
+            stopped = false;
+            failures = 0;
+            void drain();
+        },
+        async close() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+            await active;
+        },
+    });
+}
+function integer(value, minimum, maximum, name) {
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`${name} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return value;
+}
+function safe(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, ' ').slice(0, 500);
+}

package/dist/src/schema.d.ts

@@ -173,15 +173,15 @@ export declare const createWorkflowSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     script: string;
     name?: string | undefined;
-    id?: string | undefined;
     compiled?: Json | undefined;
+    id?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }, {
     script: string;
     name?: string | undefined;
-    id?: string | undefined;
     compiled?: Json | undefined;
+    id?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }>;
@@ -193,26 +193,26 @@ export declare const updateWorkflowSchema: z.ZodEffects<z.ZodObject<{
     limits: z.ZodOptional<z.ZodNullable<z.ZodType<Json, z.ZodTypeDef, Json>>>;
 }, "strict", z.ZodTypeAny, {
     name?: string | null | undefined;
-    script?: string | undefined;
     compiled?: Json | undefined;
+    script?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }, {
     name?: string | null | undefined;
-    script?: string | undefined;
     compiled?: Json | undefined;
+    script?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }>, {
     name?: string | null | undefined;
-    script?: string | undefined;
     compiled?: Json | undefined;
+    script?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }, {
     name?: string | null | undefined;
-    script?: string | undefined;
     compiled?: Json | undefined;
+    script?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }>;

package/dist/src/schema.js

@@ -1,5 +1,6 @@
 import { z } from 'zod/v3';
 import { ValidationError } from './errors.js';
+import { compiledAutomationPlan } from './plan.js';
 import { IDENTIFIER } from './validation.js';
 const maxPageSize = 100;
 const identifierMessage = 'Identifier is invalid';
@@ -102,10 +103,16 @@ export function parseUpdateWebhookTrigger(value) {
     return parse(updateWebhookTriggerSchema, value);
 }
 export function parseCreateWorkflow(value) {
-    return parse(createWorkflowSchema, value);
+    const workflow = parse(createWorkflowSchema, value);
+    if (workflow.compiled !== undefined)
+        validateCompiledPlan(workflow.compiled);
+    return workflow;
 }
 export function parseUpdateWorkflow(value) {
-    return parse(updateWorkflowSchema, value);
+    const workflow = parse(updateWorkflowSchema, value);
+    if (workflow.compiled !== undefined && workflow.compiled !== null)
+        validateCompiledPlan(workflow.compiled);
+    return workflow;
 }
 export function parsePageQuery(value) {
     return parse(pageQuerySchema, value);
@@ -119,3 +126,11 @@ export function parse(schema, value) {
         return result.data;
     throw new ValidationError(result.error.issues[0]?.message || 'Input is invalid');
 }
+function validateCompiledPlan(value) {
+    try {
+        compiledAutomationPlan(value);
+    }
+    catch (error) {
+        throw new ValidationError(error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/src/supabase-crud/mappers.js

@@ -58,6 +58,8 @@ export function run(row) {
         workflowId: row.workflow_id,
         targetId: row.target_id,
         status: row.status,
+        attempts: row.attempts,
+        ...(row.retry_at ? { retryAt: timestamp(row.retry_at) } : {}),
         input: row.input,
         createdAt: timestamp(row.created_at),
         ...(row.sent_at ? { sentAt: timestamp(row.sent_at) } : {}),

package/dist/src/supabase-crud/rows.d.ts

@@ -42,6 +42,8 @@ export type RunRow = {
     workflow_id: string;
     target_id: string;
     status: AutomationRun['status'];
+    attempts: number;
+    retry_at: Date | string | null;
     input: AutomationRun['input'];
     created_at: Date | string;
     sent_at: Date | string | null;

package/dist/src/supabase-machine.js

@@ -43,6 +43,7 @@ function run(row) {
         input: row.input,
         status: row.status,
         attempts: row.attempts,
+        ...(row.retry_at ? { retryAt: timestamp(row.retry_at) } : {}),
         leaseToken: row.lease_token,
         leaseExpiresAt: timestamp(row.lease_expires_at),
         createdAt: timestamp(row.created_at),
@@ -56,6 +57,7 @@ function run(row) {
 function update(value) {
     return {
         status: value.status,
+        ...(value.retryAt === undefined ? {} : { retryAt: value.retryAt }),
         ...(value.output === undefined ? {} : { output: value.output }),
         ...(value.error === undefined ? {} : { error: value.error }),
     };

package/dist/src/supabase-store.d.ts

@@ -1,4 +1,4 @@
-import type { AutomationStore, AutomationTarget, AutomationRun, DueCronTrigger, RunInput, RunUpdate, StoredEventTrigger } from './types.js';
+import type { AutomationStore, AutomationTarget, AutomationRun, DueCronTrigger, RunInput, StoredEventTrigger } from './types.js';
 export interface SupabaseRpcClient {
     rpc(functionName: string, arguments_: Record<string, unknown>): PromiseLike<{
         data: unknown;
@@ -17,7 +17,4 @@ export declare class SupabaseStore implements AutomationStore {
         kind: 'event';
     }>, now: Date): 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>;
 }

package/dist/src/supabase-store.js

@@ -61,30 +61,6 @@ export class SupabaseStore {
             scheduledFor: trigger.nextRunAt,
         }, now, nextRunAt);
     }
-    async pendingRuns(target) {
-        const rows = await this.#call('list_amalgm_pending_runs', {
-            p_user_id: target.userId,
-            p_target_id: target.targetId,
-        });
-        return rows.map(automationRun);
-    }
-    markSent(runId, target, now) {
-        return this.#call('mark_amalgm_run_sent', {
-            p_run_id: runId,
-            p_user_id: target.userId,
-            p_target_id: target.targetId,
-            p_now: now.toISOString(),
-        });
-    }
-    async updateRun(target, runId, update) {
-        const rows = await this.#call('update_amalgm_run', {
-            p_run_id: runId,
-            p_user_id: target.userId,
-            p_target_id: target.targetId,
-            p_update: update,
-        });
-        return rows[0] ? automationRun(rows[0]) : null;
-    }
     async #enqueue(trigger, input, now, nextRunAt) {
         const rows = await this.#call('enqueue_amalgm_run', {
             p_kind: trigger.kind,

package/dist/src/tool-surface.d.ts

@@ -0,0 +1,46 @@
+import type { Automation, AutomationCrud, AutomationRun, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, ListAutomations, ListRuns, Page, Trigger, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, Workflow } from './contract.js';
+export interface AutomationView {
+    automation: Automation;
+    triggers: Trigger[];
+    workflow: Workflow | null;
+    runs?: Page<AutomationRun>;
+}
+export interface CreateAutomationDefinition extends CreateAutomation {
+    schedules?: CreateScheduleTrigger[];
+    webhooks?: CreateWebhookTrigger[];
+    workflow?: CreateWorkflow;
+}
+interface Changes<Create extends {
+    id?: string;
+}, Update> {
+    create?: Create[];
+    update?: Array<{
+        id: string;
+        patch: Update;
+    }>;
+    delete?: string[];
+}
+export type WorkflowChange = {
+    create: CreateWorkflow;
+} | {
+    update: UpdateWorkflow;
+} | {
+    delete: true;
+};
+export interface UpdateAutomationDefinition {
+    patch?: UpdateAutomation;
+    schedules?: Changes<CreateScheduleTrigger, UpdateScheduleTrigger>;
+    webhooks?: Changes<CreateWebhookTrigger, UpdateWebhookTrigger>;
+    workflow?: WorkflowChange;
+}
+export interface AutomationToolSurface {
+    create(input: CreateAutomationDefinition): Promise<AutomationView>;
+    list(query?: ListAutomations): Promise<Page<Automation>>;
+    get(automationId: string, runs?: false | ListRuns): Promise<AutomationView>;
+    update(automationId: string, input: UpdateAutomationDefinition): Promise<AutomationView>;
+    delete(automationId: string): Promise<{
+        deleted: string;
+    }>;
+}
+export declare function createAutomationToolSurface(sdk: AutomationCrud): AutomationToolSurface;
+export {};

package/dist/src/tool-surface.js

@@ -0,0 +1,125 @@
+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 };
+        },
+    };
+    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

@@ -51,13 +51,6 @@ 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[]>;
     dueCronTriggers(now: Date): Promise<DueCronTrigger[]>;
@@ -65,13 +58,5 @@ export interface AutomationStore {
         kind: 'event';
     }>, now: Date): 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/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.2",
+  "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, or delete 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,19 +27,27 @@ 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.
+
+Action discovery belongs to the Tools product, not Automations. Manual
+execution is not advertised until the delivery SDK supports it.
 
 `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