@amalgm/automations 0.2.0 → 0.2.2

package/dist/src/executor.js

@@ -1,76 +1,195 @@
+import { automationPlan } from './plan.js';
+import { completed, emptyJournal, journalJson, putStep, runJournal, stepAttempt, } from './run-journal.js';
+export { automationPlan } from './plan.js';
 export class AutomationRunExecutor {
     runs;
     actions;
-    constructor(runs, actions) {
+    #now;
+    #heartbeatMs;
+    #maxAttempts;
+    #retryDelayMs;
+    constructor(runs, actions, options = {}) {
         this.runs = runs;
         this.actions = actions;
+        this.#now = options.now ?? (() => new Date());
+        this.#heartbeatMs = integer(options.heartbeatMs ?? 20_000, 1, 'heartbeatMs');
+        this.#maxAttempts = integer(options.maxAttempts ?? 5, 1, 'maxAttempts');
+        this.#retryDelayMs = options.retryDelayMs ?? defaultRetryDelayMs;
     }
     async execute(run) {
-        await this.runs.update(run.id, { leaseToken: run.leaseToken, status: 'running' });
+        const confirmed = await this.runs.update(run.id, {
+            leaseToken: run.leaseToken,
+            status: 'running',
+        });
+        if (!confirmed)
+            return;
+        let journal = emptyJournal();
         try {
             const plan = automationPlan(run.automation);
-            const steps = [];
+            journal = runJournal(run.output, plan.steps);
             for (const step of plan.steps) {
-                const output = await this.actions.call({
-                    actionId: step.actionId,
-                    payload: step.input,
-                    idempotencyKey: `${run.id}:${step.id}`,
+                if (completed(journal, step.id))
+                    continue;
+                const attempt = stepAttempt(journal, step.id) + 1;
+                const startedAt = this.#now().toISOString();
+                journal = putStep(journal, {
+                    id: step.id,
+                    status: 'running',
+                    attempts: attempt,
+                    startedAt,
                 });
-                steps.push({ id: step.id, output });
+                const started = await this.runs.update(run.id, {
+                    leaseToken: run.leaseToken,
+                    status: 'running',
+                    output: journalJson(journal),
+                });
+                if (!started)
+                    return;
+                const action = await this.#callWithHeartbeat(run, step);
+                if (action.leaseLost)
+                    return;
+                if ('error' in action) {
+                    const error = safeError(action.error);
+                    const failureKind = transientFailure(action.error) ? 'transient' : 'permanent';
+                    journal = putStep(journal, {
+                        id: step.id,
+                        status: 'failed',
+                        attempts: attempt,
+                        startedAt,
+                        finishedAt: this.#now().toISOString(),
+                        error,
+                        failureKind,
+                    });
+                    if (failureKind === 'transient' && run.attempts < this.#maxAttempts) {
+                        await this.runs.update(run.id, {
+                            leaseToken: run.leaseToken,
+                            status: 'pending',
+                            retryAt: new Date(this.#now().getTime() + this.#retryDelayMs(run.attempts)).toISOString(),
+                            output: journalJson(journal),
+                            error,
+                        });
+                    }
+                    else {
+                        await this.runs.update(run.id, {
+                            leaseToken: run.leaseToken,
+                            status: 'failed',
+                            output: journalJson(journal),
+                            error,
+                        });
+                    }
+                    return;
+                }
+                journal = putStep(journal, {
+                    id: step.id,
+                    status: 'completed',
+                    attempts: attempt,
+                    startedAt,
+                    finishedAt: this.#now().toISOString(),
+                    output: action.output,
+                });
+                const committed = await this.runs.update(run.id, {
+                    leaseToken: run.leaseToken,
+                    status: 'running',
+                    output: journalJson(journal),
+                });
+                if (!committed)
+                    return;
             }
             await this.runs.update(run.id, {
                 leaseToken: run.leaseToken,
                 status: 'completed',
-                output: { steps },
+                output: journalJson(journal),
             });
         }
         catch (error) {
             await this.runs.update(run.id, {
                 leaseToken: run.leaseToken,
                 status: 'failed',
+                output: journalJson(journal),
                 error: safeError(error),
             });
         }
     }
-}
-export function automationPlan(snapshot) {
-    const root = record(snapshot, 'Automation snapshot');
-    const workflow = record(root.workflow, 'Workflow snapshot');
-    const compiled = record(workflow.compiled, 'Compiled workflow');
-    if (compiled.version !== 1 || !Array.isArray(compiled.steps) || compiled.steps.length > 100) {
-        throw new Error('Compiled workflow must be a version 1 plan with at most 100 steps');
+    async #callWithHeartbeat(run, step) {
+        const controller = new AbortController();
+        let leaseLost = false;
+        let stopped = false;
+        let heartbeat = null;
+        const renew = () => {
+            if (stopped || heartbeat)
+                return;
+            heartbeat = this.runs.update(run.id, {
+                leaseToken: run.leaseToken,
+                status: 'running',
+            }).then((current) => {
+                if (!current) {
+                    leaseLost = true;
+                    controller.abort(new Error('Automation run lease was lost'));
+                }
+            }).catch(() => {
+                leaseLost = true;
+                controller.abort(new Error('Automation run lease renewal failed'));
+            }).finally(() => {
+                heartbeat = null;
+            });
+        };
+        const timer = setInterval(renew, this.#heartbeatMs);
+        timer.unref?.();
+        try {
+            const output = await this.actions.call({
+                actionId: step.actionId,
+                payload: step.input,
+                idempotencyKey: `${run.id}:${step.id}`,
+                signal: controller.signal,
+            });
+            return leaseLost ? { leaseLost: true } : { leaseLost: false, output };
+        }
+        catch (error) {
+            return leaseLost ? { leaseLost: true } : { leaseLost: false, error };
+        }
+        finally {
+            stopped = true;
+            clearInterval(timer);
+            await heartbeat;
+        }
     }
-    return {
-        version: 1,
-        steps: compiled.steps.map((value, index) => step(value, index)),
-    };
 }
-function step(value, index) {
-    const item = record(value, `Workflow step ${index + 1}`);
-    if (typeof item.id !== 'string' || !item.id.trim())
-        throw new Error(`Workflow step ${index + 1} needs an id`);
-    if (typeof item.actionId !== 'string' || !item.actionId.includes('.')) {
-        throw new Error(`Workflow step ${index + 1} needs a qualified actionId`);
+export function transientFailure(error) {
+    for (let current = error, depth = 0; current && depth < 4; depth += 1) {
+        if (typeof current !== 'object')
+            break;
+        const item = current;
+        const status = Number(item.status);
+        if (status === 408 || status === 429 || status >= 500)
+            return true;
+        const code = String(item.code ?? '');
+        if (TRANSIENT_CODES.has(code))
+            return true;
+        current = item.cause;
     }
-    assertJson(item.input);
-    return { id: item.id, actionId: item.actionId, input: item.input };
+    const message = safeError(error).toLowerCase();
+    return message.includes('fetch failed') || message.includes('network error');
+}
+const TRANSIENT_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'EAI_AGAIN',
+    'ENETDOWN',
+    'ENETUNREACH',
+    'ETIMEDOUT',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_SOCKET',
+    'internal',
+]);
+function defaultRetryDelayMs(attempt) {
+    return Math.min(5 * 60_000, 2_000 * (2 ** Math.max(0, attempt - 1)));
 }
-function record(value, name) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        throw new Error(`${name} is missing`);
+function integer(value, minimum, name) {
+    if (!Number.isInteger(value) || value < minimum)
+        throw new Error(`${name} must be an integer of at least ${minimum}`);
     return value;
 }
-function assertJson(value) {
-    if (value === null || typeof value === 'string' || typeof value === 'boolean')
-        return;
-    if (typeof value === 'number' && Number.isFinite(value))
-        return;
-    if (Array.isArray(value))
-        return void value.forEach(assertJson);
-    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
-        return void Object.values(value).forEach(assertJson);
-    }
-    throw new Error('Workflow step input must be JSON');
+function safeError(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, ' ').slice(0, 1_000);
 }
-const safeError = (error) => (error instanceof Error ? error.message : String(error))
-    .replace(/[\r\n]+/g, ' ').slice(0, 1_000);

package/dist/src/http.js

@@ -99,6 +99,10 @@ export function createAutomationApi(options) {
         catch (error) {
             if (error instanceof AutomationError)
                 return response(status(error), { error: error.message, code: error.code });
+            const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+            if (code.startsWith('dpop_') || code.includes('access_token') || code.includes('authorization')) {
+                return response(401, { error: 'Authorization denied', code });
+            }
             return response(500, { error: 'Automations service failed' });
         }
     };

package/dist/src/index.d.ts

@@ -5,7 +5,7 @@ export { createAutomationApi, type AuthenticateAutomationRequest, type Automatio
 export { runAutomationCli } from './cli.js';
 export { createAutomationMcpServer } from './mcp.js';
 export { SupabaseAutomationCrudRepository, type SupabaseRpcClient } from './supabase-crud.js';
-export type { Automation, AutomationCrud, AutomationCrudService as AutomationCrudServiceContract, AutomationPrincipal, AutomationPlan, AutomationRun, AutomationScope, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, Json, ListAutomations, ListRuns, Page, PageQuery, RunStatus, ScheduleTrigger, Trigger, ToolActionStep, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow, } from './contract.js';
+export type { Automation, AutomationCrud, AutomationCrudService as AutomationCrudServiceContract, AutomationPrincipal, AutomationPlan, AutomationRunJournal, AutomationStepRun, AutomationStepStatus, AutomationRun, AutomationScope, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, Json, ListAutomations, ListRuns, Page, PageQuery, RunStatus, ScheduleTrigger, Trigger, ToolActionStep, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow, } from './contract.js';
 export { Automations, EventRejectedError } from './automations.js';
 export { createAutomationEventsApi, type AutomationEventReceipt, type AutomationEventsApi, type AutomationEventsApiConfig, } from './events-http.js';
 export { nextCronAt, validateCron } from './schedule.js';
@@ -17,5 +17,7 @@ export type { AutomationMachinePrincipal, ClaimedAutomationRun, MachineRunReposi
 export { createMachineRunsApi } from './machine-http.js';
 export { createMachineRunsClient, type AutomationRequestHeaders } from './machine-client.js';
 export { AutomationRunExecutor, automationPlan, type AutomationActionPort } from './executor.js';
+export { createAutomationMachineRunner, type AutomationMachineRunnerOptions, } from './runner.js';
+export { compiledAutomationPlan } from './plan.js';
 export type { SupabaseRpcClient as SupabaseStoreRpcClient } from './supabase-store.js';
-export type { AutomationLog, AutomationRun as AutomationRunRecord, AutomationStore, AutomationTarget, AutomationTransport, DueCronTrigger, RunInput, RunUpdate, StoredEventTrigger, } from './types.js';
+export type { AutomationLog, AutomationRun as AutomationRunRecord, AutomationStore, AutomationTarget, DueCronTrigger, RunInput, StoredEventTrigger, } from './types.js';

package/dist/src/index.js

@@ -1,8 +1,8 @@
 // The automation product has two composable halves:
 //  - the configuration service (contract/crud/http/mcp/cli) — Supabase owns
 //    everything except execution;
-//  - the delivery rail (automations/webhook/schedule/store) — authenticated
-//    admission, schedule claims, reconnect drain, and run-state transitions.
+//  - the durable rail (automations/webhook/schedule/store/machine/executor) —
+//    admission, schedule claims, machine leases, retry, and step journals.
 // Colliding names keep the contract's spelling; the rail's store-level
 // records are exported under Store-scoped aliases.
 export { createAutomationClient } from './client.js';
@@ -22,3 +22,5 @@ export { createMachineRuns } from './machine.js';
 export { createMachineRunsApi } from './machine-http.js';
 export { createMachineRunsClient } from './machine-client.js';
 export { AutomationRunExecutor, automationPlan } from './executor.js';
+export { createAutomationMachineRunner, } from './runner.js';
+export { compiledAutomationPlan } from './plan.js';

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

@@ -4,4 +4,5 @@ export declare function createMachineRunsClient(options: {
     readonly baseUrl: string;
     readonly headers: AutomationRequestHeaders;
     readonly fetch?: typeof globalThis.fetch;
+    readonly requestTimeoutMs?: number;
 }): MachineRuns;

package/dist/src/machine-client.js

@@ -2,6 +2,7 @@ import { AutomationError } from './errors.js';
 export function createMachineRunsClient(options) {
     const baseUrl = options.baseUrl.replace(/\/$/, '');
     const fetch = options.fetch ?? globalThis.fetch;
+    const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
     const request = async (path, method, body) => {
         const url = `${baseUrl}${path}`;
         const response = await fetch(url, {
@@ -12,6 +13,7 @@ export function createMachineRunsClient(options) {
                 ...await options.headers(method, url),
             },
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(requestTimeoutMs),
         });
         const payload = await response.json().catch(() => ({}));
         if (!response.ok)

package/dist/src/machine.d.ts

@@ -12,7 +12,8 @@ export interface ClaimedAutomationRun extends AutomationRun {
 }
 export interface MachineRunUpdate {
     readonly leaseToken: string;
-    readonly status: Extract<RunStatus, 'running' | 'completed' | 'failed'>;
+    readonly status: Extract<RunStatus, 'pending' | 'running' | 'completed' | 'failed'>;
+    readonly retryAt?: string;
     readonly output?: Json;
     readonly error?: string;
 }

package/dist/src/machine.js

@@ -18,9 +18,14 @@ export function createMachineRuns(repository, principal, now = () => new Date())
             if (!runId.trim() || !update.leaseToken.trim()) {
                 throw new ValidationError('Run id and lease token are required');
             }
-            if (!['running', 'completed', 'failed'].includes(update.status)) {
+            if (!['pending', 'running', 'completed', 'failed'].includes(update.status)) {
                 throw new ValidationError('Run status is invalid');
             }
+            if (update.retryAt !== undefined) {
+                if (update.status !== 'pending' || !Number.isFinite(Date.parse(update.retryAt))) {
+                    throw new ValidationError('retryAt requires a pending run and an ISO timestamp');
+                }
+            }
             return repository.update({
                 userId: principal.userId,
                 targetId: principal.computerId,

package/dist/src/mcp.d.ts

@@ -1,3 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AutomationCrud } from './contract.js';
+import { createAutomationToolSurface } from './tool-surface.js';
+export { createAutomationToolSurface };
+export type { AutomationToolSurface, AutomationView, CreateAutomationDefinition, UpdateAutomationDefinition, WorkflowChange, } from './tool-surface.js';
 export declare function createAutomationMcpServer(sdk: AutomationCrud): McpServer;

package/dist/src/mcp.js

@@ -1,52 +1,55 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod/v3';
-import { createAutomationSchema, createScheduleTriggerSchema, createWebhookTriggerSchema, createWorkflowSchema, identifierSchema, listAutomationsSchema, listRunsSchema, pageQuerySchema, updateAutomationSchema, updateScheduleTriggerSchema, updateWebhookTriggerSchema, updateWorkflowSchema, } from './schema.js';
+import { createAutomationSchema, createScheduleTriggerSchema, createWebhookTriggerSchema, createWorkflowSchema, identifierSchema, listAutomationsSchema, listRunsSchema, updateAutomationSchema, updateScheduleTriggerSchema, updateWebhookTriggerSchema, updateWorkflowSchema, } from './schema.js';
+import { createAutomationToolSurface } from './tool-surface.js';
+export { createAutomationToolSurface };
 const resultSchema = { result: z.unknown() };
-const automationIdInput = { automation_id: identifierSchema };
-const triggerIdInput = { ...automationIdInput, trigger_id: identifierSchema };
-const runIdInput = { ...automationIdInput, run_id: identifierSchema };
+const scheduleChangesSchema = z.object({
+    create: z.array(createScheduleTriggerSchema).max(100).optional(),
+    update: z.array(z.object({ id: identifierSchema, patch: updateScheduleTriggerSchema }).strict()).max(100).optional(),
+    delete: z.array(identifierSchema).max(100).optional(),
+}).strict();
+const webhookChangesSchema = z.object({
+    create: z.array(createWebhookTriggerSchema).max(100).optional(),
+    update: z.array(z.object({ id: identifierSchema, patch: updateWebhookTriggerSchema }).strict()).max(100).optional(),
+    delete: z.array(identifierSchema).max(100).optional(),
+}).strict();
+const workflowChangeSchema = z.union([
+    z.object({ create: createWorkflowSchema }).strict(),
+    z.object({ update: updateWorkflowSchema }).strict(),
+    z.object({ delete: z.literal(true) }).strict(),
+]);
 export function createAutomationMcpServer(sdk) {
     const server = new McpServer({ name: 'amalgm-automations-mcp-server', version: '0.1.0' });
-    register(server, 'amalgm_automations_create', 'Create automation', 'Create an automation configuration without triggers or workflow.', { input: createAutomationSchema }, write(false), ({ input }) => sdk.automations.create(input));
-    register(server, 'amalgm_automations_list', 'List automations', 'List the caller\'s automations with optional target and enabled filters.', { query: listAutomationsSchema.optional() }, read(), ({ query }) => sdk.automations.list(query));
-    register(server, 'amalgm_automations_get', 'Get automation', 'Get one automation by id.', automationIdInput, read(), ({ automation_id }) => sdk.automations.get(automation_id));
-    register(server, 'amalgm_automations_update', 'Update automation', 'Update automation metadata, target, or enabled state.', { automation_id: identifierSchema, patch: updateAutomationSchema }, write(true), ({ automation_id, patch }) => sdk.automations.update(automation_id, patch));
-    register(server, 'amalgm_automations_delete', 'Delete automation', 'Delete an automation and its current triggers and workflow. Historical runs remain.', automationIdInput, destructive(), async ({ automation_id }) => {
-        await sdk.automations.delete(automation_id);
-        return { deleted: automation_id };
-    });
-    register(server, 'amalgm_automation_triggers_list', 'List automation triggers', 'List all schedule and webhook triggers belonging to one automation.', automationIdInput, read(), ({ automation_id }) => sdk.triggers.list(automation_id));
-    register(server, 'amalgm_schedule_triggers_create', 'Create schedule trigger', 'Create a cron schedule trigger for one automation. Set maxOccurrences for a bounded request such as “every minute for ten minutes”; the service disables it after exactly that many admitted runs.', { automation_id: identifierSchema, input: createScheduleTriggerSchema }, write(false), ({ automation_id, input }) => sdk.triggers.schedule.create(automation_id, input));
-    register(server, 'amalgm_schedule_triggers_list', 'List schedule triggers', 'List schedule triggers for one automation.', { automation_id: identifierSchema, query: pageQuerySchema.optional() }, read(), ({ automation_id, query }) => sdk.triggers.schedule.list(automation_id, query));
-    register(server, 'amalgm_schedule_triggers_get', 'Get schedule trigger', 'Get one schedule trigger by automation and trigger id.', triggerIdInput, read(), ({ automation_id, trigger_id }) => sdk.triggers.schedule.get(automation_id, trigger_id));
-    register(server, 'amalgm_schedule_triggers_update', 'Update schedule trigger', 'Update a cron schedule trigger without changing its type.', { automation_id: identifierSchema, trigger_id: identifierSchema, patch: updateScheduleTriggerSchema }, write(true), ({ automation_id, trigger_id, patch }) => sdk.triggers.schedule.update(automation_id, trigger_id, patch));
-    register(server, 'amalgm_schedule_triggers_delete', 'Delete schedule trigger', 'Delete one schedule trigger. The automation and its workflow remain.', triggerIdInput, destructive(), async ({ automation_id, trigger_id }) => {
-        await sdk.triggers.schedule.delete(automation_id, trigger_id);
-        return { deleted: trigger_id };
-    });
-    register(server, 'amalgm_webhook_triggers_create', 'Create webhook trigger', 'Create a webhook trigger. The secret is accepted only on writes and never returned.', { automation_id: identifierSchema, input: createWebhookTriggerSchema }, write(false), ({ automation_id, input }) => sdk.triggers.webhook.create(automation_id, input));
-    register(server, 'amalgm_webhook_triggers_list', 'List webhook triggers', 'List webhook triggers for one automation. Secrets are never returned.', { automation_id: identifierSchema, query: pageQuerySchema.optional() }, read(), ({ automation_id, query }) => sdk.triggers.webhook.list(automation_id, query));
-    register(server, 'amalgm_webhook_triggers_get', 'Get webhook trigger', 'Get one webhook trigger by automation and trigger id. The secret is never returned.', triggerIdInput, read(), ({ automation_id, trigger_id }) => sdk.triggers.webhook.get(automation_id, trigger_id));
-    register(server, 'amalgm_webhook_triggers_update', 'Update webhook trigger', 'Update webhook matching, secret, or enabled state without changing its type.', { automation_id: identifierSchema, trigger_id: identifierSchema, patch: updateWebhookTriggerSchema }, write(true), ({ automation_id, trigger_id, patch }) => sdk.triggers.webhook.update(automation_id, trigger_id, patch));
-    register(server, 'amalgm_webhook_triggers_delete', 'Delete webhook trigger', 'Delete one webhook trigger. The automation and its workflow remain.', triggerIdInput, destructive(), async ({ automation_id, trigger_id }) => {
-        await sdk.triggers.webhook.delete(automation_id, trigger_id);
-        return { deleted: trigger_id };
-    });
-    register(server, 'amalgm_workflow_create', 'Create automation workflow', 'Create the one workflow owned by an automation. For tool execution, compiled must be {version:1,steps:[{id,actionId,input}]}; for a reminder use actionId “channels.notify_user” and input {message,title?}.', { automation_id: identifierSchema, input: createWorkflowSchema }, write(false), ({ automation_id, input }) => sdk.workflow.create(automation_id, input));
-    register(server, 'amalgm_workflow_get', 'Get automation workflow', 'Get the workflow script owned by an automation.', automationIdInput, read(), ({ automation_id }) => sdk.workflow.get(automation_id));
-    register(server, 'amalgm_workflow_update', 'Update automation workflow', 'Update the workflow script or its configuration.', { automation_id: identifierSchema, patch: updateWorkflowSchema }, write(true), ({ automation_id, patch }) => sdk.workflow.update(automation_id, patch));
-    register(server, 'amalgm_workflow_delete', 'Delete automation workflow', 'Delete the workflow script. The automation and its triggers remain.', automationIdInput, destructive(), async ({ automation_id }) => {
-        await sdk.workflow.delete(automation_id);
-        return { deleted: automation_id };
-    });
-    register(server, 'amalgm_automation_runs_list', 'List automation runs', 'List historical runs for one automation. This tool never changes run state.', { automation_id: identifierSchema, query: listRunsSchema.optional() }, read(), ({ automation_id, query }) => sdk.runs.list(automation_id, query));
-    register(server, 'amalgm_automation_runs_get', 'Get automation run', 'Get one historical run for an automation. This tool never changes run state.', runIdInput, read(), ({ automation_id, run_id }) => sdk.runs.get(automation_id, run_id));
+    const tools = createAutomationToolSurface(sdk);
+    register(server, 'amalgm_automations_create', 'Create automation', 'Create one complete automation definition, including its schedules, webhooks, and optional workflow. The service stages configuration disabled and enables it only after setup succeeds. Omit targetId in a machine-bound session; never guess a target id.', {
+        ...createAutomationSchema.shape,
+        schedules: z.array(createScheduleTriggerSchema).max(100).optional(),
+        webhooks: z.array(createWebhookTriggerSchema).max(100).optional(),
+        workflow: createWorkflowSchema.optional(),
+    }, write(false), (input) => tools.create(input));
+    register(server, 'amalgm_automations_list', 'List automations', 'List the caller\'s automations with optional target, enabled-state, and pagination filters.', {
+        ...listAutomationsSchema.shape,
+    }, read(), (query) => tools.list(query));
+    register(server, 'amalgm_automations_get', 'Get automation', 'Get one complete automation definition with its typed triggers and workflow. Recent run history is optional.', {
+        automation_id: identifierSchema,
+        include_runs: z.boolean().optional(),
+        run_query: listRunsSchema.optional(),
+    }, read(), ({ automation_id, include_runs, run_query }) => (tools.get(automation_id, include_runs || run_query ? (run_query ?? { limit: 20 }) : false)));
+    register(server, 'amalgm_automations_update', 'Update automation', 'Update an automation and grouped trigger or workflow changes in one task-level call. Resource changes are staged while the automation is disabled; a failed change leaves a safe disabled draft.', {
+        automation_id: identifierSchema,
+        patch: updateAutomationSchema.optional(),
+        schedules: scheduleChangesSchema.optional(),
+        webhooks: webhookChangesSchema.optional(),
+        workflow: workflowChangeSchema.optional(),
+    }, write(false), ({ automation_id, ...input }) => tools.update(automation_id, input));
+    register(server, 'amalgm_automations_delete', 'Delete automation', 'Delete an automation and its current triggers and workflow. Historical runs remain.', {
+        automation_id: identifierSchema,
+    }, destructive(), ({ automation_id }) => tools.delete(automation_id));
     return server;
 }
 function register(server, name, title, description, inputSchema, annotations, handler) {
-    registerUnchecked(server, name, title, description, inputSchema, annotations, async (input) => {
-        return handler(input);
-    });
+    registerUnchecked(server, name, title, description, inputSchema, annotations, async (input) => (handler(input)));
 }
 function registerUnchecked(server, name, title, description, inputSchema, annotations, handler) {
     server.registerTool(name, {
@@ -77,12 +80,12 @@ function toolFailure(error) {
         content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
     };
 }
-function read() {
-    return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-}
-function write(idempotentHint) {
-    return { readOnlyHint: false, destructiveHint: false, idempotentHint, openWorldHint: false };
-}
-function destructive() {
-    return { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
-}
+const read = () => ({
+    readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false,
+});
+const write = (idempotentHint) => ({
+    readOnlyHint: false, destructiveHint: false, idempotentHint, openWorldHint: false,
+});
+const destructive = () => ({
+    readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false,
+});

package/dist/src/plan.d.ts

@@ -0,0 +1,3 @@
+import type { AutomationPlan, Json } from './contract.js';
+export declare function automationPlan(snapshot: Json): AutomationPlan;
+export declare function compiledAutomationPlan(value: unknown): AutomationPlan;

package/dist/src/plan.js

@@ -0,0 +1,48 @@
+import { ValidationError } from './errors.js';
+export function automationPlan(snapshot) {
+    const root = record(snapshot, 'Automation snapshot');
+    const workflow = record(root.workflow, 'Workflow snapshot');
+    return compiledAutomationPlan(workflow.compiled);
+}
+export function compiledAutomationPlan(value) {
+    const compiled = record(value, 'Compiled workflow');
+    if (compiled.version !== 1 || !Array.isArray(compiled.steps)
+        || compiled.steps.length < 1 || compiled.steps.length > 100) {
+        throw new ValidationError('Compiled workflow must be a version 1 plan with 1 to 100 steps');
+    }
+    const steps = compiled.steps.map((item, index) => step(item, index));
+    const ids = new Set();
+    for (const item of steps) {
+        if (ids.has(item.id))
+            throw new ValidationError(`Workflow step id is duplicated: ${item.id}`);
+        ids.add(item.id);
+    }
+    return { version: 1, steps };
+}
+function step(value, index) {
+    const item = record(value, `Workflow step ${index + 1}`);
+    if (typeof item.id !== 'string' || !item.id.trim())
+        throw new ValidationError(`Workflow step ${index + 1} needs an id`);
+    if (typeof item.actionId !== 'string' || !item.actionId.includes('.')) {
+        throw new ValidationError(`Workflow step ${index + 1} needs a qualified actionId`);
+    }
+    assertJson(item.input);
+    return { id: item.id.trim(), actionId: item.actionId.trim(), input: item.input };
+}
+function record(value, name) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ValidationError(`${name} is missing`);
+    return value;
+}
+function assertJson(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (Array.isArray(value))
+        return void value.forEach(assertJson);
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        return void Object.values(value).forEach(assertJson);
+    }
+    throw new ValidationError('Workflow step input must be JSON');
+}

package/dist/src/run-contract.d.ts

@@ -0,0 +1,46 @@
+import type { Json, PageQuery } from './contract.js';
+export type RunStatus = 'pending' | 'sent' | 'running' | 'completed' | 'failed';
+export interface ToolActionStep {
+    id: string;
+    actionId: string;
+    input: Json;
+}
+export interface AutomationPlan {
+    version: 1;
+    steps: ToolActionStep[];
+}
+export type AutomationStepStatus = 'running' | 'completed' | 'failed';
+export interface AutomationStepRun {
+    id: string;
+    status: AutomationStepStatus;
+    attempts: number;
+    startedAt: string;
+    finishedAt?: string;
+    output?: Json;
+    error?: string;
+    failureKind?: 'transient' | 'permanent';
+}
+export interface AutomationRunJournal {
+    version: 1;
+    steps: AutomationStepRun[];
+}
+export interface AutomationRun {
+    id: string;
+    automationId: string;
+    triggerId: string;
+    workflowId: string;
+    targetId: string;
+    status: RunStatus;
+    attempts?: number;
+    retryAt?: string;
+    input: Json;
+    createdAt: string;
+    sentAt?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    output?: Json;
+    error?: string;
+}
+export interface ListRuns extends PageQuery {
+    status?: RunStatus;
+}

package/dist/src/run-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/src/run-journal.d.ts

@@ -0,0 +1,8 @@
+import type { AutomationRunJournal, AutomationStepRun, Json, ToolActionStep } from './contract.js';
+export declare function emptyJournal(): AutomationRunJournal;
+export declare function runJournal(value: Json | undefined, plan: readonly ToolActionStep[]): AutomationRunJournal;
+export declare function completed(journal: AutomationRunJournal, stepId: string): boolean;
+export declare function stepAttempt(journal: AutomationRunJournal, stepId: string): number;
+export declare function putStep(journal: AutomationRunJournal, step: AutomationStepRun): AutomationRunJournal;
+/** Journals are constructed from JSON fields only; this is the persistence boundary. */
+export declare function journalJson(journal: AutomationRunJournal): Json;