@amalgm/automations 0.2.0 → 0.2.2

package/AXIOMS.md

@@ -10,42 +10,63 @@
    key authentication all resolve to the same principal shape.
 4. An automation belongs to exactly one user and exactly one target. It may
    have zero or more triggers and zero or one workflow.
-5. Scheduled triggers and webhook triggers are distinct first-class resources
+5. A principal bound to exactly one target supplies that target implicitly on
+   create. Unbound or multi-target principals must choose explicitly; adapters
+   and models never guess opaque target ids.
+6. Scheduled triggers and webhook triggers are distinct first-class resources
    with their own CRUD operations and validation rules.
-6. A workflow is the one script resource owned by its automation. It may be
+7. A workflow is the one script resource owned by its automation. It may be
    created, read, updated, or deleted independently of the automation and its
    triggers.
-7. An incomplete automation is valid configuration. Future execution behavior
+8. An incomplete automation is valid configuration. Future execution behavior
    must be derived from its persisted configuration rather than repaired by the
    CRUD layer.
-8. Supabase is authoritative for automations, triggers, workflow source, and
+9. Supabase is authoritative for automations, triggers, workflow source, and
    permanent run history. A definition edit or deletion never rewrites prior
    runs.
-9. Webhook secrets are persisted but write-only: normal reads reveal only that
+10. Webhook secrets are persisted but write-only: normal reads reveal only that
    a secret is configured.
-10. Run history is read-only in the control plane and always scoped to its
+11. Run history is read-only in the control plane and always scoped to its
     automation's owner.
-11. Storage records, Supabase RPCs, HTTP details, and MCP protocol details are
+12. Storage records, Supabase RPCs, HTTP details, and MCP protocol details are
     implementation concerns, not SDK concepts.
-12. The control-plane SDK is the only configuration write path. The delivery
+13. The control-plane SDK is the only configuration write path. The delivery
     rail reads that configuration and writes only schedule clocks and run
     state; it never owns a second automation-definition API.
-13. Admitting a run atomically verifies the current enabled configuration,
+14. Admitting a run atomically verifies the current enabled configuration,
     stores a secret-free snapshot, and, for a schedule, advances exactly the
     firing instant that was claimed.
-14. Legacy local automation storage is not a compatibility authority. Engine
+15. Legacy local automation storage is not a compatibility authority. Engine
     cutover migrates callers to this SDK and then deletes the old store.
-15. Event ingress returns success only after every admitted run is durable in
+16. Event ingress returns success only after every admitted run is durable in
     Supabase. Its recent-event list is a bounded, secret-free operational view,
     never a second event or run authority.
-16. A finite schedule decrements its durable remaining occurrence count in the
+17. A finite schedule decrements its durable remaining occurrence count in the
     same transaction that admits a run; zero disables the trigger.
-17. A machine receives work only by exclusively leasing runs whose persisted
+18. A machine receives work only by exclusively leasing runs whose persisted
     target equals the `computer_id` in its DPoP-bound access token.
-18. Machine execution consumes the immutable workflow snapshot stored on the
+19. The configured public origin, never forwarding headers, reconstructs the
+    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.
-19. 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.
-20. Automations is a standalone hosted service. Gateway owns none of its API,
+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,
@@ -39,6 +49,9 @@ recent-event response is an ephemeral, secret-free operational projection.
 
 Amalgm supplies a resolved authenticated principal from its user session or
 HMAC-refresh flow; future API keys resolve to the same principal capability.
+When that principal is bound to exactly one machine, automation creation uses
+that target without asking a human or model to copy an opaque machine id. An
+explicit target remains mandatory for unbound or multi-target principals.
 Core provides authenticated user identity, opaque machine identity,
 connectivity, and narrow host capabilities. The product receives identity and
 scopes — never raw credentials or Core storage — and neither side reaches into

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/config.d.ts

@@ -1,5 +1,6 @@
 export interface AutomationsHostConfig {
     readonly port: number;
+    readonly publicOrigin: string;
     readonly supabaseUrl: string;
     readonly supabaseServiceRoleKey: string;
     readonly authorizationIssuer: string;

package/dist/host/config.js

@@ -1,6 +1,7 @@
 export function automationsHostConfig(env = process.env) {
     return Object.freeze({
         port: integer(env.PORT, 8080, 1, 65_535),
+        publicOrigin: url(env.AMALGAM_PUBLIC_ORIGIN, 'AMALGAM_PUBLIC_ORIGIN'),
         supabaseUrl: url(env.SUPABASE_URL ?? env.NEXT_PUBLIC_SUPABASE_URL, 'SUPABASE_URL'),
         supabaseServiceRoleKey: required(env.SUPABASE_SERVICE_ROLE_KEY, 'SUPABASE_SERVICE_ROLE_KEY'),
         authorizationIssuer: url(env.AMALGM_AUTHORIZATION_ISSUER, 'AMALGM_AUTHORIZATION_ISSUER'),

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,9 +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,
@@ -45,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

@@ -1,9 +1,12 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 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

@@ -1,4 +1,5 @@
 import { createServer } from 'node:http';
+import { publicResourceRequestUrl } from '@amalgm/core/authorization';
 export function createAutomationsHost(options) {
     const log = options.log ?? (() => { });
     let scheduling = null;
@@ -16,14 +17,19 @@ export function createAutomationsHost(options) {
         try {
             if (incoming.url === '/healthz')
                 return send(outgoing, Response.json({ ok: true }));
-            const request = await webRequest(incoming);
-            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 {
@@ -35,17 +41,30 @@ export function createAutomationsHost(options) {
         },
     };
 }
-async function webRequest(request) {
+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(new URL(request.url ?? '/', `http://${request.headers.host ?? '127.0.0.1'}`), {
+    return new Request(publicResourceRequestUrl(publicOrigin, request.url ?? '/'), {
         method: request.method ?? 'GET',
         headers: request.headers,
         ...(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 {
@@ -31,7 +33,8 @@ export interface Automation {
 }
 export interface CreateAutomation {
     id?: string;
-    targetId: string;
+    /** Omit when the authenticated principal resolves exactly one target. */
+    targetId?: string;
     name?: string;
     description?: string;
     enabled?: boolean;
@@ -83,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;
@@ -131,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>;
@@ -189,4 +164,3 @@ export interface AutomationCrud {
 export interface AutomationCrudService {
     for(principal: AutomationPrincipal): AutomationCrud;
 }
-export {};

package/dist/src/crud/automations.js

@@ -1,20 +1,20 @@
 import { ConflictError, NotFoundError } from '../errors.js';
 import { parseCreateAutomation, parseListAutomations, parseUpdateAutomation } from '../schema.js';
 import { id, newId, page } from '../validation.js';
-import { assertTarget } from './context.js';
+import { assertTarget, resolveTarget } from './context.js';
 export function automationOperations(context) {
     const { principal, repository } = context;
     return {
         create: async (input) => {
             context.write();
             const parsed = parseCreateAutomation(input);
-            assertTarget(principal, parsed.targetId);
+            const targetId = resolveTarget(principal, parsed.targetId);
             if (parsed.id && await repository.getAutomation(principal.userId, id(parsed.id, 'Automation id'))) {
                 throw new ConflictError('Automation');
             }
             return repository.createAutomation(principal.userId, {
                 id: parsed.id ? id(parsed.id, 'Automation id') : newId('automation'),
-                targetId: parsed.targetId,
+                targetId,
                 name: parsed.name || '',
                 description: parsed.description || '',
                 enabled: parsed.enabled !== false,

package/dist/src/crud/context.d.ts

@@ -11,3 +11,4 @@ export interface CrudContext {
 }
 export declare function createContext(repository: AutomationCrudRepository, principal: AutomationPrincipal, clock: () => Date): CrudContext;
 export declare function assertTarget(principal: AutomationPrincipal, targetId: string): void;
+export declare function resolveTarget(principal: AutomationPrincipal, targetId?: string): string;

package/dist/src/crud/context.js

@@ -1,4 +1,4 @@
-import { ForbiddenError, NotFoundError } from '../errors.js';
+import { ForbiddenError, NotFoundError, ValidationError } from '../errors.js';
 import { id, requiredText } from '../validation.js';
 export function createContext(repository, principal, clock) {
     assertPrincipal(principal);
@@ -21,6 +21,15 @@ export function assertTarget(principal, targetId) {
         throw new ForbiddenError('This credential cannot access that target');
     }
 }
+export function resolveTarget(principal, targetId) {
+    if (targetId) {
+        assertTarget(principal, targetId);
+        return id(targetId, 'targetId');
+    }
+    if (principal.targetIds?.length === 1)
+        return principal.targetIds[0];
+    throw new ValidationError('targetId is required unless the credential resolves exactly one target');
+}
 function assertPrincipal(principal) {
     requiredText(principal.userId, 'Authenticated user id');
     if (!Array.isArray(principal.scopes))

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;