@amalgm/automations 0.2.1 → 0.2.2

package/AXIOMS.md

@@ -49,8 +49,24 @@
     DPoP request URL behind the Fly proxy.
 20. Machine execution consumes the immutable workflow snapshot stored on the
     run. It never rediscovers or silently updates the automation definition.
-21. A compiled workflow is a small declarative sequence of tool actions. The
+21. A compiled workflow is a small declarative sequence of one or more tool actions. The
     executor receives tool calling as a host capability and never embeds a
     Channels, Shell, CLI, or provider special case.
 22. Automations is a standalone hosted service. Gateway owns none of its API,
     scheduling, claim, execution, or persistence path.
+23. The durable run ledger is the offline queue. The platform never keeps a
+    second online-machine delivery buffer and never drops an unclaimed run.
+24. A run advances through its immutable plan in order. Every step transition
+    commits under the run's current lease before execution advances, and a
+    completed step is never intentionally invoked again.
+25. A machine may begin an action only after the service confirms its current
+    lease. It renews that lease while the action is running and stops advancing
+    when renewal fails.
+26. One run-step pair has one stable idempotency key. Step ids are unique in a
+    plan, and every action host receives that key and a cancellation signal.
+27. Only transient transport failures retry. They release the same run with a
+    bounded future retry time and retain completed step output; invalid plans,
+    missing actions, authorization failures, and other deterministic errors
+    are terminal.
+28. The selected target executes every action effect. The hosted service owns
+    only configuration, admission, leases, the step journal, and run history.

package/PURPOSE.md

@@ -23,7 +23,17 @@ The product has two composable halves over that one state:
   write path. When a machine is offline, new runs remain pending; when it
   reconnects, Shell claims pending runs directly from the Automations service
   with its machine-bound DPoP identity and executes the persisted tool-action
-  plan. Execution itself stays on the selected machine.
+  plan. Execution itself stays on the selected machine. The platform never
+  needs to know whether a machine is online: an unclaimed run is the complete
+  offline queue.
+
+One run is one immutable plan plus one durable ordered step journal. The
+machine records a step as running before invoking its action and records its
+output before advancing. Reconnect resumes at the first step that is not
+already complete. A transient network failure releases the same run back to
+the queue with a bounded future retry time; a configuration, authorization, or
+action error fails it. Stable per-step idempotency keys make an uncertain
+network acknowledgement safe to repeat.
 
 Automations is its own hosted service and Fly machine. Its API and scheduler
 share the same SDK and Supabase authority; neither is composed into, proxied by,

package/README.md

@@ -51,12 +51,15 @@ or webhook triggers and zero or one workflow. Supabase owns definitions,
 schedule clocks, immutable run snapshots, machine leases, and permanent run
 history. Webhook secrets are write-only.
 
-Compiled workflows use one small format:
+Executable workflows use one small, non-empty format:
 
 ```ts
 type AutomationPlan = {
   version: 1;
-  steps: Array<{ id: string; actionId: string; input: Json }>;
+  steps: [
+    { id: string; actionId: string; input: Json },
+    ...Array<{ id: string; actionId: string; input: Json }>,
+  ];
 };
 ```
 

package/dist/host/main.js

@@ -2,6 +2,7 @@ import { createClient } from '@supabase/supabase-js';
 import { Automations } from '../src/automations.js';
 import { AutomationCrudService } from '../src/crud.js';
 import { createAutomationApi } from '../src/http.js';
+import { createAutomationEventsApi } from '../src/events-http.js';
 import { createMachineRuns } from '../src/machine.js';
 import { createMachineRunsApi } from '../src/machine-http.js';
 import { SupabaseAutomationCrudRepository } from '../src/supabase-crud.js';
@@ -18,10 +19,7 @@ const authentication = createAutomationsAuthenticators({
     issuer: config.authorizationIssuer,
     supabase,
 });
-const delivery = new Automations(new SupabaseStore(supabase), {
-    isOnline: () => false,
-    send: async () => false,
-}, (event, details) => log(event, details));
+const delivery = new Automations(new SupabaseStore(supabase), (event, details) => log(event, details));
 const controlApi = createAutomationApi({
     service: new AutomationCrudService(new SupabaseAutomationCrudRepository(supabase)),
     authenticate: authentication.control,
@@ -31,10 +29,15 @@ const machineApi = createMachineRunsApi({
     authenticate: authentication.machine,
     runsFor: (principal) => createMachineRuns(machineRepository, principal),
 });
+const eventsApi = createAutomationEventsApi({
+    delivery,
+    target: async (request) => eventTarget(request),
+});
 const host = createAutomationsHost({
     publicOrigin: config.publicOrigin,
     controlApi,
     machineApi,
+    eventsApi,
     fireSchedules: () => delivery.fireDueCrons(),
     schedulerIntervalMs: config.schedulerIntervalMs,
     log,
@@ -46,3 +49,11 @@ for (const signal of ['SIGINT', 'SIGTERM']) {
 function log(event, details = {}) {
     console.log(JSON.stringify({ service: 'amalgm-automations', event, ...details }));
 }
+function eventTarget(request) {
+    const userId = request.headers.get('x-amalgm-user-id')?.trim() ?? '';
+    const targetId = request.headers.get('x-amalgm-target-id')?.trim() ?? '';
+    if (!/^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(userId) || !targetId) {
+        throw Object.assign(new Error('Webhook routing headers are required'), { status: 400 });
+    }
+    return { userId, targetId };
+}

package/dist/host/server.d.ts

@@ -3,8 +3,10 @@ export declare function createAutomationsHost(options: {
     readonly publicOrigin: string;
     readonly controlApi: (request: Request) => Promise<Response>;
     readonly machineApi: (request: Request) => Promise<Response>;
+    readonly eventsApi?: (request: Request) => Promise<Response>;
     readonly fireSchedules: () => Promise<unknown>;
     readonly schedulerIntervalMs: number;
+    readonly maxRequestBodyBytes?: number;
     readonly log?: (event: string, details?: Readonly<Record<string, unknown>>) => void;
 }): {
     server: import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;

package/dist/host/server.js

@@ -17,14 +17,19 @@ export function createAutomationsHost(options) {
         try {
             if (incoming.url === '/healthz')
                 return send(outgoing, Response.json({ ok: true }));
-            const request = await webRequest(incoming, options.publicOrigin);
-            const api = new URL(request.url).pathname.startsWith('/v1/machine/')
-                ? options.machineApi : options.controlApi;
+            const request = await webRequest(incoming, options.publicOrigin, options.maxRequestBodyBytes ?? 2 * 1024 * 1024);
+            const pathname = new URL(request.url).pathname;
+            const api = pathname === '/events' && options.eventsApi
+                ? options.eventsApi
+                : pathname.startsWith('/v1/machine/') ? options.machineApi : options.controlApi;
             await send(outgoing, await api(request));
         }
         catch (error) {
             log('request.failed', { error: safe(error) });
-            await send(outgoing, Response.json({ error: 'Automations service failed' }, { status: 500 }));
+            const status = error instanceof HostRequestError ? error.status : 500;
+            await send(outgoing, Response.json({
+                error: status === 500 ? 'Automations service failed' : error instanceof Error ? error.message : String(error),
+            }, { status }));
         }
     });
     return {
@@ -36,10 +41,16 @@ export function createAutomationsHost(options) {
         },
     };
 }
-async function webRequest(request, publicOrigin) {
+async function webRequest(request, publicOrigin, maximumBodyBytes) {
     const chunks = [];
-    for await (const chunk of request)
-        chunks.push(Buffer.from(chunk));
+    let size = 0;
+    for await (const value of request) {
+        const chunk = Buffer.from(value);
+        size += chunk.length;
+        if (size > maximumBodyBytes)
+            throw new HostRequestError(413, 'Request body is too large');
+        chunks.push(chunk);
+    }
     const body = Buffer.concat(chunks);
     return new Request(publicResourceRequestUrl(publicOrigin, request.url ?? '/'), {
         method: request.method ?? 'GET',
@@ -47,6 +58,13 @@ async function webRequest(request, publicOrigin) {
         ...(body.length ? { body } : {}),
     });
 }
+class HostRequestError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
 async function send(response, source) {
     response.writeHead(source.status, Object.fromEntries(source.headers));
     response.end(Buffer.from(await source.arrayBuffer()));

package/dist/src/automations.d.ts

@@ -1,13 +1,13 @@
-import type { AutomationLog, AutomationRun, AutomationStore, AutomationTarget, AutomationTransport, Json, RunUpdate } from './types.js';
+import type { AutomationLog, AutomationRun, AutomationStore, AutomationTarget, Json } from './types.js';
 export declare class EventRejectedError extends Error {
     constructor();
 }
+/** Admits trigger occurrences to the durable run ledger. It never delivers them. */
 export declare class Automations {
     #private;
     readonly store: AutomationStore;
-    readonly transport: AutomationTransport;
     readonly log: AutomationLog;
-    constructor(store: AutomationStore, transport: AutomationTransport, log?: AutomationLog);
+    constructor(store: AutomationStore, log?: AutomationLog);
     receiveEvent(input: {
         target: AutomationTarget;
         headers: Record<string, string>;
@@ -17,8 +17,5 @@ export declare class Automations {
         event?: string;
         now?: Date;
     }): Promise<AutomationRun[]>;
-    fireDueCrons(now?: Date): Promise<AutomationRun[]>;
-    targetOnline(target: AutomationTarget): Promise<number>;
-    updateRun(target: AutomationTarget, runId: string, update: RunUpdate): Promise<AutomationRun | null>;
-    drain(target: AutomationTarget): Promise<number>;
+    fireDueCrons(now?: Date, maximumRuns?: number): Promise<AutomationRun[]>;
 }

package/dist/src/automations.js

@@ -7,14 +7,12 @@ export class EventRejectedError extends Error {
         this.name = 'EventRejectedError';
     }
 }
+/** Admits trigger occurrences to the durable run ledger. It never delivers them. */
 export class Automations {
     store;
-    transport;
     log;
-    #drains = new Map();
-    constructor(store, transport, log = noop) {
+    constructor(store, log = noop) {
         this.store = store;
-        this.transport = transport;
         this.log = log;
     }
     async receiveEvent(input) {
@@ -39,15 +37,19 @@ export class Automations {
         const now = input.now || new Date();
         const runInput = { kind: 'event', ...reference, payload: input.payload };
         const runs = (await Promise.all(triggers.map((trigger) => (this.store.enqueueEvent(trigger, runInput, now))))).filter((run) => run !== null);
-        await this.#drainCreated(runs);
+        this.#logPending(runs);
         return runs;
     }
-    async fireDueCrons(now = new Date()) {
+    async fireDueCrons(now = new Date(), maximumRuns = 1_000) {
+        if (!Number.isInteger(maximumRuns) || maximumRuns < 1)
+            throw new Error('maximumRuns must be a positive integer');
         const created = [];
         for (const trigger of await this.store.dueCronTriggers(now)) {
             let scheduledFor = trigger.nextRunAt;
             let remaining = trigger.remainingOccurrences;
-            while (new Date(scheduledFor) <= now && (remaining === undefined || remaining > 0)) {
+            while (created.length < maximumRuns
+                && new Date(scheduledFor) <= now
+                && (remaining === undefined || remaining > 0)) {
                 const nextRunAt = nextCronAt(trigger.cron, trigger.timezone, scheduledFor);
                 const run = await this.store.enqueueCron({ ...trigger, nextRunAt: scheduledFor }, nextRunAt, now);
                 if (!run)
@@ -57,31 +59,13 @@ export class Automations {
                 if (remaining !== undefined)
                     remaining -= 1;
             }
+            if (created.length === maximumRuns)
+                break;
         }
-        await this.#drainCreated(created);
+        this.#logPending(created);
         return created;
     }
-    targetOnline(target) {
-        return this.drain(target);
-    }
-    updateRun(target, runId, update) {
-        if (update.output !== undefined)
-            assertJson(update.output, 'Run output');
-        return this.store.updateRun(target, runId, update);
-    }
-    drain(target) {
-        const key = `${target.userId}:${target.targetId}`;
-        const active = this.#drains.get(key);
-        if (active)
-            return active;
-        const drain = this.#drain(target).finally(() => {
-            if (this.#drains.get(key) === drain)
-                this.#drains.delete(key);
-        });
-        this.#drains.set(key, drain);
-        return drain;
-    }
-    async #drainCreated(runs) {
+    #logPending(runs) {
         for (const run of runs) {
             this.log('run.pending', {
                 runId: run.id,
@@ -89,42 +73,6 @@ export class Automations {
                 automationId: run.automationId,
             });
         }
-        const targets = new Map(runs.map((run) => [
-            `${run.userId}:${run.targetId}`,
-            { userId: run.userId, targetId: run.targetId },
-        ]));
-        await Promise.all([...targets.values()].map((target) => this.drain(target)));
-    }
-    async #drain(target) {
-        if (!this.transport.isOnline(target))
-            return 0;
-        this.log('drain.started', { targetId: target.targetId });
-        let sent = 0;
-        const failed = new Set();
-        while (this.transport.isOnline(target)) {
-            const runs = (await this.store.pendingRuns(target)).filter(({ id }) => !failed.has(id));
-            if (runs.length === 0)
-                return sent;
-            for (const run of runs) {
-                if (!this.transport.isOnline(target))
-                    return sent;
-                try {
-                    if (!await this.transport.send(run)) {
-                        this.log('run.failed', { runId: run.id, targetId: target.targetId });
-                        failed.add(run.id);
-                        continue;
-                    }
-                    if (await this.store.markSent(run.id, target, new Date()))
-                        sent += 1;
-                    this.log('run.sent', { runId: run.id, targetId: target.targetId });
-                }
-                catch {
-                    this.log('run.failed', { runId: run.id, targetId: target.targetId });
-                    failed.add(run.id);
-                }
-            }
-        }
-        return sent;
     }
 }
 function assertJson(value, label) {

package/dist/src/client.d.ts

@@ -6,4 +6,5 @@ export declare function createAutomationClient(options: {
     authorization?: AutomationAuthorization;
     headers?: AutomationHeaders;
     fetch?: typeof globalThis.fetch;
+    requestTimeoutMs?: number;
 }): AutomationCrud;

package/dist/src/client.js

@@ -1,7 +1,7 @@
 import { AutomationError } from './errors.js';
 export function createAutomationClient(options) {
     const baseUrl = options.baseUrl.replace(/\/$/, '');
-    const request = createRequester(baseUrl, options.authorization, options.headers, options.fetch || globalThis.fetch);
+    const request = createRequester(baseUrl, options.authorization, options.headers, options.fetch || globalThis.fetch, options.requestTimeoutMs ?? 15_000);
     return {
         automations: {
             create: (input) => request('/v1/automations', 'POST', input),
@@ -39,7 +39,7 @@ export function createAutomationClient(options) {
         },
     };
 }
-function createRequester(baseUrl, authorization, additionalHeaders, fetch) {
+function createRequester(baseUrl, authorization, additionalHeaders, fetch, requestTimeoutMs) {
     return async (path, method, body, nullable = false) => {
         const url = `${baseUrl}${path}`;
         const token = await authorization?.();
@@ -52,6 +52,7 @@ function createRequester(baseUrl, authorization, additionalHeaders, fetch) {
                 ...await additionalHeaders?.(method, url),
             },
             ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(requestTimeoutMs),
         });
         if (response.status === 204)
             return undefined;

package/dist/src/contract.d.ts

@@ -1,6 +1,8 @@
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
+import type { AutomationRun, ListRuns } from './run-contract.js';
+export type { AutomationPlan, AutomationRun, AutomationRunJournal, AutomationStepRun, AutomationStepStatus, ListRuns, RunStatus, ToolActionStep, } from './run-contract.js';
 export type AutomationScope = 'automations:read' | 'automations:write' | 'runs:read' | 'runs:execute' | '*';
 /** Identity resolved by Amalgm before the SDK is bound to a caller. */
 export interface AutomationPrincipal {
@@ -84,15 +86,6 @@ export interface UpdateScheduleTrigger {
     /** Set a new finite budget, or null to make the schedule unbounded. */
     maxOccurrences?: number | null;
 }
-export interface ToolActionStep {
-    id: string;
-    actionId: string;
-    input: Json;
-}
-export interface AutomationPlan {
-    version: 1;
-    steps: ToolActionStep[];
-}
 export interface CreateWebhookTrigger {
     id?: string;
     source?: string;
@@ -132,25 +125,6 @@ export interface UpdateWorkflow {
     allowlist?: Json | null;
     limits?: Json | null;
 }
-export type RunStatus = 'pending' | 'sent' | 'running' | 'completed' | 'failed';
-export interface AutomationRun {
-    id: string;
-    automationId: string;
-    triggerId: string;
-    workflowId: string;
-    targetId: string;
-    status: RunStatus;
-    input: Json;
-    createdAt: string;
-    sentAt?: string;
-    startedAt?: string;
-    finishedAt?: string;
-    output?: Json;
-    error?: string;
-}
-export interface ListRuns extends PageQuery {
-    status?: RunStatus;
-}
 export interface AutomationCrud {
     readonly automations: {
         create(input: CreateAutomation): Promise<Automation>;
@@ -190,4 +164,3 @@ export interface AutomationCrud {
 export interface AutomationCrudService {
     for(principal: AutomationPrincipal): AutomationCrud;
 }
-export {};

package/dist/src/events-http.js

@@ -54,6 +54,10 @@ export function createAutomationEventsApi(config) {
                 return json(401, { error: error.message });
             if (error instanceof EventHttpError)
                 return json(error.status, { error: error.message });
+            const status = Number(error?.status);
+            if (Number.isInteger(status) && status >= 400 && status <= 499) {
+                return json(status, { error: error instanceof Error ? error.message : String(error) });
+            }
             return json(500, { error: error instanceof Error ? error.message : String(error) });
         }
     };

package/dist/src/executor.d.ts

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