@amalgm/automations 0.1.2 → 0.2.0

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

@@ -0,0 +1,46 @@
+import { paged, schedule, webhook } from './mappers.js';
+import { call } from './rpc.js';
+export function triggerRepository(client) {
+    const list = async (functionName, userId, automationId, query, mapper) => paged(await call(client, functionName, {
+        p_user_id: userId,
+        p_automation_id: automationId,
+        p_limit: query.limit,
+        p_offset: query.offset,
+    }), mapper, query);
+    return {
+        createScheduleTrigger: async (userId, automationId, input) => schedule(await call(client, 'create_amalgm_schedule_trigger', { p_user_id: userId, p_automation_id: automationId, p_trigger: input })),
+        listScheduleTriggers: (userId, automationId, query) => list('list_amalgm_schedule_triggers', userId, automationId, query, schedule),
+        getScheduleTrigger: async (userId, automationId, triggerId) => {
+            const row = await call(client, 'get_amalgm_schedule_trigger', {
+                p_user_id: userId, p_automation_id: automationId, p_trigger_id: triggerId,
+            });
+            return row ? schedule(row) : null;
+        },
+        updateScheduleTrigger: async (userId, automationId, triggerId, patch) => {
+            const row = await call(client, 'update_amalgm_schedule_trigger', {
+                p_user_id: userId, p_automation_id: automationId, p_trigger_id: triggerId, p_patch: patch,
+            });
+            return row ? schedule(row) : null;
+        },
+        deleteScheduleTrigger: (userId, automationId, triggerId) => call(client, 'delete_amalgm_schedule_trigger', { p_user_id: userId, p_automation_id: automationId, p_trigger_id: triggerId }),
+        createWebhookTrigger: async (userId, automationId, input) => webhook(await call(client, 'create_amalgm_webhook_trigger', { p_user_id: userId, p_automation_id: automationId, p_trigger: input })),
+        listWebhookTriggers: (userId, automationId, query) => list('list_amalgm_webhook_triggers', userId, automationId, query, webhook),
+        getWebhookTrigger: async (userId, automationId, triggerId) => {
+            const row = await call(client, 'get_amalgm_webhook_trigger', {
+                p_user_id: userId, p_automation_id: automationId, p_trigger_id: triggerId,
+            });
+            return row ? webhook(row) : null;
+        },
+        updateWebhookTrigger: async (userId, automationId, triggerId, patch) => {
+            const row = await call(client, 'update_amalgm_webhook_trigger', {
+                p_user_id: userId, p_automation_id: automationId, p_trigger_id: triggerId, p_patch: patch,
+            });
+            return row ? webhook(row) : null;
+        },
+        deleteWebhookTrigger: (userId, automationId, triggerId) => call(client, 'delete_amalgm_webhook_trigger', { p_user_id: userId, p_automation_id: automationId, p_trigger_id: triggerId }),
+        listTriggers: async (userId, automationId) => (await call(client, 'list_amalgm_triggers', {
+            p_user_id: userId,
+            p_automation_id: automationId,
+        })).map((row) => row.kind === 'schedule' ? schedule(row) : webhook(row)),
+    };
+}

package/dist/src/supabase-crud/workflow-runs.d.ts

@@ -0,0 +1,5 @@
+import type { AutomationCrudRepository } from '../crud.js';
+import { type SupabaseRpcClient } from './rpc.js';
+type Operations = Pick<AutomationCrudRepository, 'createWorkflow' | 'getWorkflow' | 'updateWorkflow' | 'deleteWorkflow' | 'listRuns' | 'getRun'>;
+export declare function workflowRunRepository(client: SupabaseRpcClient): Operations;
+export {};

package/dist/src/supabase-crud/workflow-runs.js

@@ -0,0 +1,41 @@
+import { paged, run, workflow } from './mappers.js';
+import { call } from './rpc.js';
+export function workflowRunRepository(client) {
+    return {
+        createWorkflow: async (userId, automationId, input) => workflow(await call(client, 'create_amalgm_workflow', { p_user_id: userId, p_automation_id: automationId, p_workflow: input })),
+        getWorkflow: async (userId, automationId) => {
+            const row = await call(client, 'get_amalgm_workflow', {
+                p_user_id: userId,
+                p_automation_id: automationId,
+            });
+            return row ? workflow(row) : null;
+        },
+        updateWorkflow: async (userId, automationId, patch) => {
+            const row = await call(client, 'update_amalgm_workflow', {
+                p_user_id: userId,
+                p_automation_id: automationId,
+                p_patch: patch,
+            });
+            return row ? workflow(row) : null;
+        },
+        deleteWorkflow: (userId, automationId) => call(client, 'delete_amalgm_workflow', {
+            p_user_id: userId,
+            p_automation_id: automationId,
+        }),
+        listRuns: async (userId, automationId, query) => paged(await call(client, 'list_amalgm_runs', {
+            p_user_id: userId,
+            p_automation_id: automationId,
+            p_status: query.status || null,
+            p_limit: query.limit,
+            p_offset: query.offset,
+        }), run, query),
+        getRun: async (userId, automationId, runId) => {
+            const row = await call(client, 'get_amalgm_run', {
+                p_user_id: userId,
+                p_automation_id: automationId,
+                p_run_id: runId,
+            });
+            return row ? run(row) : null;
+        },
+    };
+}

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

@@ -1,44 +1,8 @@
-import type { Automation, AutomationRun, CreateAutomation, CreateWebhookTrigger, CreateWorkflow, Page, ScheduleTrigger, Trigger, UpdateAutomation, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow } from './contract.js';
-import type { AutomationCrudRepository, NormalizedListAutomations, NormalizedListRuns, StoredScheduleCreate, StoredScheduleUpdate } from './crud.js';
-export interface SupabaseRpcClient {
-    rpc(functionName: string, arguments_: Record<string, unknown>): PromiseLike<{
-        data: unknown;
-        error: {
-            code?: string;
-            message?: string;
-        } | null;
-    }>;
+import type { AutomationCrudRepository } from './crud.js';
+import type { SupabaseRpcClient } from './supabase-crud/rpc.js';
+export type { SupabaseRpcClient } from './supabase-crud/rpc.js';
+export interface SupabaseAutomationCrudRepository extends AutomationCrudRepository {
 }
-export declare class SupabaseAutomationCrudRepository implements AutomationCrudRepository {
-    #private;
-    private readonly client;
+export declare class SupabaseAutomationCrudRepository {
     constructor(client: SupabaseRpcClient);
-    createAutomation(userId: string, input: Required<CreateAutomation>): Promise<Automation>;
-    listAutomations(userId: string, query: NormalizedListAutomations): Promise<Page<Automation>>;
-    getAutomation(userId: string, automationId: string): Promise<Automation | null>;
-    updateAutomation(userId: string, automationId: string, patch: UpdateAutomation): Promise<Automation | null>;
-    deleteAutomation(userId: string, automationId: string): Promise<boolean>;
-    createScheduleTrigger(userId: string, automationId: string, input: StoredScheduleCreate): Promise<ScheduleTrigger>;
-    listScheduleTriggers(userId: string, automationId: string, query: Required<{
-        limit?: number;
-        offset?: number;
-    }>): Promise<Page<ScheduleTrigger>>;
-    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<{
-        limit?: number;
-        offset?: number;
-    }>): 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>;
-    deleteWebhookTrigger(userId: string, automationId: string, triggerId: string): Promise<boolean>;
-    listTriggers(userId: string, automationId: string): Promise<Trigger[]>;
-    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>;
 }

package/dist/src/supabase-crud.js

@@ -1,271 +1,8 @@
-import { ConflictError } from './errors.js';
+import { automationRepository } from './supabase-crud/automations.js';
+import { triggerRepository } from './supabase-crud/triggers.js';
+import { workflowRunRepository } from './supabase-crud/workflow-runs.js';
 export class SupabaseAutomationCrudRepository {
-    client;
     constructor(client) {
-        this.client = client;
+        Object.assign(this, automationRepository(client), triggerRepository(client), workflowRunRepository(client));
     }
-    async createAutomation(userId, input) {
-        return automation(await this.#call('create_amalgm_automation', {
-            p_user_id: userId,
-            p_automation: input,
-        }));
-    }
-    async listAutomations(userId, query) {
-        const result = await this.#call('list_amalgm_automations', {
-            p_user_id: userId,
-            p_target_id: query.targetId || null,
-            p_enabled: query.enabled ?? null,
-            p_limit: query.limit,
-            p_offset: query.offset,
-        });
-        return paged(result, automation, query);
-    }
-    async getAutomation(userId, automationId) {
-        const row = await this.#call('get_amalgm_automation', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-        });
-        return row ? automation(row) : null;
-    }
-    async updateAutomation(userId, automationId, patch) {
-        const row = await this.#call('update_amalgm_automation', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_patch: patch,
-        });
-        return row ? automation(row) : null;
-    }
-    deleteAutomation(userId, automationId) {
-        return this.#call('delete_amalgm_automation', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-        });
-    }
-    async createScheduleTrigger(userId, automationId, input) {
-        return schedule(await this.#call('create_amalgm_schedule_trigger', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_trigger: input,
-        }));
-    }
-    async listScheduleTriggers(userId, automationId, query) {
-        return this.#listTriggers('list_amalgm_schedule_triggers', userId, automationId, query, schedule);
-    }
-    async getScheduleTrigger(userId, automationId, triggerId) {
-        const row = await this.#call('get_amalgm_schedule_trigger', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_trigger_id: triggerId,
-        });
-        return row ? schedule(row) : null;
-    }
-    async updateScheduleTrigger(userId, automationId, triggerId, patch) {
-        const row = await this.#call('update_amalgm_schedule_trigger', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_trigger_id: triggerId,
-            p_patch: patch,
-        });
-        return row ? schedule(row) : null;
-    }
-    deleteScheduleTrigger(userId, automationId, triggerId) {
-        return this.#call('delete_amalgm_schedule_trigger', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_trigger_id: triggerId,
-        });
-    }
-    async createWebhookTrigger(userId, automationId, input) {
-        return webhook(await this.#call('create_amalgm_webhook_trigger', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_trigger: input,
-        }));
-    }
-    async listWebhookTriggers(userId, automationId, query) {
-        return this.#listTriggers('list_amalgm_webhook_triggers', userId, automationId, query, webhook);
-    }
-    async getWebhookTrigger(userId, automationId, triggerId) {
-        const row = await this.#call('get_amalgm_webhook_trigger', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_trigger_id: triggerId,
-        });
-        return row ? webhook(row) : null;
-    }
-    async updateWebhookTrigger(userId, automationId, triggerId, patch) {
-        const row = await this.#call('update_amalgm_webhook_trigger', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_trigger_id: triggerId,
-            p_patch: patch,
-        });
-        return row ? webhook(row) : null;
-    }
-    deleteWebhookTrigger(userId, automationId, triggerId) {
-        return this.#call('delete_amalgm_webhook_trigger', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_trigger_id: triggerId,
-        });
-    }
-    async listTriggers(userId, automationId) {
-        const rows = await this.#call('list_amalgm_triggers', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-        });
-        return rows.map((row) => row.kind === 'schedule' ? schedule(row) : webhook(row));
-    }
-    async createWorkflow(userId, automationId, input) {
-        return workflow(await this.#call('create_amalgm_workflow', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_workflow: input,
-        }));
-    }
-    async getWorkflow(userId, automationId) {
-        const row = await this.#call('get_amalgm_workflow', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-        });
-        return row ? workflow(row) : null;
-    }
-    async updateWorkflow(userId, automationId, patch) {
-        const row = await this.#call('update_amalgm_workflow', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_patch: patch,
-        });
-        return row ? workflow(row) : null;
-    }
-    deleteWorkflow(userId, automationId) {
-        return this.#call('delete_amalgm_workflow', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-        });
-    }
-    async listRuns(userId, automationId, query) {
-        const result = await this.#call('list_amalgm_runs', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_status: query.status || null,
-            p_limit: query.limit,
-            p_offset: query.offset,
-        });
-        return paged(result, run, query);
-    }
-    async getRun(userId, automationId, runId) {
-        const row = await this.#call('get_amalgm_run', {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_run_id: runId,
-        });
-        return row ? run(row) : null;
-    }
-    async #listTriggers(functionName, userId, automationId, query, mapper) {
-        const result = await this.#call(functionName, {
-            p_user_id: userId,
-            p_automation_id: automationId,
-            p_limit: query.limit,
-            p_offset: query.offset,
-        });
-        return paged(result, mapper, query);
-    }
-    async #call(functionName, arguments_) {
-        const { data, error } = await this.client.rpc(functionName, arguments_);
-        if (error) {
-            if (error.code === '23505' || /duplicate key|unique constraint/i.test(error.message || '')) {
-                throw new ConflictError(resource(functionName));
-            }
-            throw new Error(error.message || `Supabase function ${functionName} failed`);
-        }
-        return data;
-    }
-}
-function resource(functionName) {
-    if (functionName.includes('workflow'))
-        return 'Workflow';
-    if (functionName.includes('trigger'))
-        return 'Trigger';
-    if (functionName.includes('automation'))
-        return 'Automation';
-    return 'Automation resource';
-}
-function automation(row) {
-    return {
-        id: row.id,
-        targetId: row.target_id,
-        ...(row.name ? { name: row.name } : {}),
-        ...(row.description ? { description: row.description } : {}),
-        enabled: row.enabled,
-        createdAt: timestamp(row.created_at),
-        updatedAt: timestamp(row.updated_at),
-    };
-}
-function schedule(row) {
-    return {
-        id: row.id,
-        automationId: row.automation_id,
-        kind: 'schedule',
-        enabled: row.enabled,
-        cron: row.cron,
-        timezone: row.timezone,
-        createdAt: timestamp(row.created_at),
-        updatedAt: timestamp(row.updated_at),
-    };
-}
-function webhook(row) {
-    return {
-        id: row.id,
-        automationId: row.automation_id,
-        kind: 'webhook',
-        enabled: row.enabled,
-        source: row.source,
-        event: row.event,
-        secretConfigured: row.secret_configured,
-        createdAt: timestamp(row.created_at),
-        updatedAt: timestamp(row.updated_at),
-    };
-}
-function workflow(row) {
-    return {
-        id: row.id,
-        automationId: row.automation_id,
-        ...(row.name ? { name: row.name } : {}),
-        script: row.script,
-        ...(row.compiled !== null ? { compiled: row.compiled } : {}),
-        ...(row.allowlist !== null ? { allowlist: row.allowlist } : {}),
-        ...(row.limits !== null ? { limits: row.limits } : {}),
-        createdAt: timestamp(row.created_at),
-        updatedAt: timestamp(row.updated_at),
-    };
-}
-function run(row) {
-    return {
-        id: row.id,
-        automationId: row.automation_id,
-        triggerId: row.trigger_id,
-        workflowId: row.workflow_id,
-        targetId: row.target_id,
-        status: row.status,
-        input: row.input,
-        createdAt: timestamp(row.created_at),
-        ...(row.sent_at ? { sentAt: timestamp(row.sent_at) } : {}),
-        ...(row.started_at ? { startedAt: timestamp(row.started_at) } : {}),
-        ...(row.finished_at ? { finishedAt: timestamp(row.finished_at) } : {}),
-        ...(row.output !== null ? { output: row.output } : {}),
-        ...(row.error !== null ? { error: row.error } : {}),
-    };
-}
-function paged(result, mapper, query) {
-    return {
-        items: result.items.map(mapper),
-        total: result.total,
-        limit: query.limit,
-        offset: query.offset,
-        hasMore: query.offset + result.items.length < result.total,
-    };
-}
-function timestamp(value) {
-    return new Date(value).toISOString();
 }

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

@@ -0,0 +1,16 @@
+import type { ClaimedAutomationRun, MachineRunRepository } from './machine.js';
+export interface MachineRpcClient {
+    rpc(name: string, arguments_: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+}
+export declare class SupabaseMachineRunRepository implements MachineRunRepository {
+    #private;
+    private readonly client;
+    constructor(client: MachineRpcClient);
+    claim(input: Parameters<MachineRunRepository['claim']>[0]): Promise<ClaimedAutomationRun[]>;
+    update(input: Parameters<MachineRunRepository['update']>[0]): Promise<ClaimedAutomationRun | null>;
+}

package/dist/src/supabase-machine.js

@@ -0,0 +1,63 @@
+import { AutomationError } from './errors.js';
+export class SupabaseMachineRunRepository {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async claim(input) {
+        const rows = await this.#call('claim_amalgm_machine_runs', {
+            p_user_id: input.userId,
+            p_target_id: input.targetId,
+            p_limit: input.limit,
+            p_lease_seconds: input.leaseSeconds,
+        });
+        return rows.map(run);
+    }
+    async update(input) {
+        const rows = await this.#call('update_amalgm_claimed_run', {
+            p_user_id: input.userId,
+            p_target_id: input.targetId,
+            p_run_id: input.runId,
+            p_lease_token: input.update.leaseToken,
+            p_update: update(input.update),
+            p_now: input.now.toISOString(),
+        });
+        return rows[0] ? run(rows[0]) : null;
+    }
+    async #call(name, arguments_) {
+        const { data, error } = await this.client.rpc(name, arguments_);
+        if (error)
+            throw new AutomationError('internal', error.message ?? `${name} failed`);
+        return data;
+    }
+}
+function run(row) {
+    return {
+        id: row.id,
+        userId: row.user_id,
+        targetId: row.target_id,
+        automationId: row.automation_id,
+        triggerId: row.trigger_id,
+        workflowId: row.workflow_id,
+        automation: row.automation_payload,
+        input: row.input,
+        status: row.status,
+        attempts: row.attempts,
+        leaseToken: row.lease_token,
+        leaseExpiresAt: timestamp(row.lease_expires_at),
+        createdAt: timestamp(row.created_at),
+        ...(row.sent_at ? { sentAt: timestamp(row.sent_at) } : {}),
+        ...(row.started_at ? { startedAt: timestamp(row.started_at) } : {}),
+        ...(row.finished_at ? { finishedAt: timestamp(row.finished_at) } : {}),
+        ...(row.output === null ? {} : { output: row.output }),
+        ...(row.error === null ? {} : { error: row.error }),
+    };
+}
+function update(value) {
+    return {
+        status: value.status,
+        ...(value.output === undefined ? {} : { output: value.output }),
+        ...(value.error === undefined ? {} : { error: value.error }),
+    };
+}
+const timestamp = (value) => new Date(value).toISOString();

package/dist/src/supabase-store.js

@@ -49,6 +49,7 @@ export class SupabaseStore {
             cron: row.cron,
             timezone: row.timezone,
             nextRunAt: new Date(row.next_run_at).toISOString(),
+            ...(row.remaining_occurrences === null ? {} : { remainingOccurrences: row.remaining_occurrences }),
         }));
     }
     enqueueEvent(trigger, input, now) {

package/dist/src/types.d.ts

@@ -22,6 +22,7 @@ export interface DueCronTrigger extends StoredTriggerBase {
     cron: string;
     timezone: string;
     nextRunAt: string;
+    remainingOccurrences?: number;
 }
 export type RunInput = {
     kind: 'event';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Amalgm's cloud automation SDK: Supabase-backed configuration, trigger admission, and run delivery.",
   "license": "UNLICENSED",
   "repository": {
@@ -26,6 +26,10 @@
     "./mcp": {
       "types": "./dist/src/mcp.d.ts",
       "import": "./dist/src/mcp.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "import": "./dist/host/index.js"
     }
   },
   "bin": {
@@ -34,6 +38,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "supabase",
     "AXIOMS.md",
     "PURPOSE.md",
@@ -46,14 +51,18 @@
     "test:supabase": "tsx --test test/integration/postgres.test.ts",
     "verify": "npm run check && npm test && npm run build",
     "release:check": "npm run verify && npm run test:supabase",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "start": "node dist/host/main.js"
   },
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
+    "@amalgm/core": "0.4.2",
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "@supabase/supabase-js": "2.57.4",
     "cron-parser": "^5.4.0",
+    "jose": "^6.1.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/skills/automations/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: automations
+description: Create, inspect, change, or delete Amalgm automations, schedules, workflows, and run history through the Automations MCP tools.
+---
+
+# Amalgm Automations
+
+Use the Automations tools for scheduled or webhook-driven work. The tools are
+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:
+
+```json
+{
+  "version": 1,
+  "steps": [
+    {
+      "id": "notify",
+      "actionId": "channels.notify_user",
+      "input": { "title": "Reminder", "message": "Call Mom" }
+    }
+  ]
+}
+```
+
+3. `amalgm_schedule_triggers_create` with cron `* * * * *`, the user's
+   timezone, and `maxOccurrences: 10`.
+
+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.
+
+## 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.
+
+`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.