@amalgm/automations 0.3.1 → 0.4.0

package/AXIOMS.md

@@ -129,3 +129,14 @@
     action or process results become an explicit byte count plus bounded JSON
     preview before transport, so output can never strand a run outside the
     ledger it is meant to update.
+44. Agent onboarding delegates identity and runtime lifecycle to Shell and
+    proves Automations access with a successful read before declaring the
+    connection ready.
+45. A machine claims work only after notification coverage is ready, on a wakeup,
+    or while draining previously discovered work; idle machines never poll.
+46. Every run is committed before its wakeup, and every Fly host observes the
+    same private database notifications regardless of where admission occurred.
+47. Retry and expired-lease wakeups follow the earliest durable eligibility time
+    for that user and machine; a notification is never proof of execution.
+48. Losing upstream notification coverage closes downstream streams, and every
+    reconnect checks retained work before becoming idle again.

package/PURPOSE.md

@@ -27,6 +27,15 @@ The product has two composable halves over that one state:
   needs to know whether a machine is online: an unclaimed run is the complete
   offline queue.
 
+The local worker is idle when there is no work. It opens one authenticated
+HTTPS notification stream, claims retained runs when that stream becomes ready,
+and drains work when notified. Committed Supabase changes wake every Fly host;
+each host forwards only to the owning machine and schedules the next durable
+retry or lease deadline. Notifications carry no workflow data and never replace
+the run ledger. Reconnecting re-establishes notification coverage before checking
+the ledger. Connection health and active execution leases have bounded timers;
+idle machines have no periodic work-claim timer.
+
 The agent CLI is the command-line projection of the same task-level command
 surface as MCP: create, list, get, update, delete, and run-now. Each command
 accepts the same JSON object as its corresponding MCP tool and returns the same
@@ -38,6 +47,15 @@ CLI sees only the local runtime admission token. The standalone adapter may be
 composed over an already-bound SDK for tests and other hosts, but it never owns
 automation lifecycle or authorization rules.
 
+The portable Automations skill guides an agent from installation and Google
+sign-in to a verified Automations connection, then back to the user's requested
+work. Setup uses Shell's public commands and the existing browser approval;
+the skill never becomes an authentication implementation. It reuses a working
+connection, distinguishes account approval from runtime readiness, and helps
+the user reach aayush@amalgm.ai with bounded, redacted diagnostic evidence when
+the failing boundary cannot be repaired. The packaged skill is the source for
+installed copies and public setup/support guidance.
+
 The CLI is global configuration control, not directory-local state. The agent
 or person creating an automation may invoke it from any directory; the selected
 machine and the persisted workflow decide where effects occur later. A process

package/README.md

@@ -46,6 +46,11 @@ the API request.
 - `@amalgm/automations/mcp`: agent tools over the same SDK.
 - `@amalgm/automations/host`: standalone Fly service composition.
 - `amalgm-automations`: CLI adapter.
+- `skills/amalgm-automations`: portable agent skill for operating either the
+  MCP or global CLI surface, including installation, Google sign-in, runtime
+  readiness, troubleshooting, and support. The packaged skill is the source
+  for installed copies; its [setup and support reference](skills/amalgm-automations/references/setup-and-support.md)
+  supplies the public onboarding guidance.
 
 ## Agent CLI
 
@@ -198,6 +203,7 @@ The machine execution API is:
 ```text
 POST  /v1/machine/runs/claim
 PATCH /v1/machine/runs/:runId
+GET   /v1/machine/runs/notifications
 ```
 
 Public webhook admission uses the URL returned on each webhook trigger:
@@ -216,13 +222,41 @@ The target is never accepted in a machine request. It comes from the verified
 access token. Run leases expire and are safely reclaimable; terminal updates
 must present the active lease token.
 
+The machine worker opens the authenticated HTTPS notification stream before
+its first claim. `ready` and `wake` events cause it to drain retained work;
+an idle worker has no polling interval. The stream sends a comment every
+30 seconds to detect broken connections; comments never cause a claim or a
+database read. Streams reconnect with fresh authorization at token expiry
+(at most five minutes), and reconnect checks recover missed notifications.
+
+Each Fly host subscribes to the same service-only Supabase Broadcast topic.
+Run inserts and eligibility changes publish small owner/target wakeups from
+the database transaction. Fly re-reads the earliest retry/lease deadline only
+when a target connects, changes, or reaches that deadline. Losing the database
+subscription closes the machine streams so they reconnect and catch up.
+Cron scheduling remains hosted; no schedule timer runs on the user's machine.
+
+Rollout order: apply the product migrations, deploy the Fly host, publish the
+SDK, then release Shell with that exact SDK version. Shell wires
+`notifications: runs.notifications` into `createAutomationMachineRunner`.
+The polling option and `AMALGM_AUTOMATIONS_POLL_INTERVAL_MS` are removed.
+Existing installed Shell releases keep their old behavior until updated.
+
 ## Verification
 
 ```bash
 npm run verify
 TEST_DATABASE_URL=postgres://... npm run test:supabase
+npm run test:notifications
 npm pack --dry-run
 ```
 
+`test:supabase` requires an empty disposable Postgres database; its fixture
+records the Supabase Broadcast boundary inside the same transaction.
+`test:notifications` requires Node.js 22+, Docker, and Supabase CLI 2.26.9
+(also pinned in CI). It starts and removes its own local Supabase project,
+using real database Broadcast and two HTTP hosts to verify delivery, idle
+behavior, offline catch-up, retry deadlines, and abandoned claims.
+
 See [PURPOSE.md](./PURPOSE.md) and [AXIOMS.md](./AXIOMS.md) for the governing
 ownership and behavior laws.

package/dist/host/auth.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { authorizeMachineResource, } from '@amalgm/core/authorization';
-import { calculateJwkThumbprint, createRemoteJWKSet, decodeProtectedHeader, importJWK, jwtVerify, } from 'jose';
+import { calculateJwkThumbprint, createRemoteJWKSet, decodeProtectedHeader, decodeJwt, importJWK, jwtVerify, } from 'jose';
 import { ForbiddenError } from '../src/errors.js';
 export function createAutomationsAuthenticators(options) {
     const jwks = createRemoteJWKSet(new URL(`${options.issuer}/.well-known/jwks.json`));
@@ -28,10 +28,13 @@ export function createAutomationsAuthenticators(options) {
         },
         machine: async (request) => {
             const principal = await authorize(request, options.issuer, 'runs:execute', ports);
+            // The exact token above has already passed Core's signature/lifetime checks.
+            const claims = decodeJwt(request.headers.get('authorization').trim().split(/\s+/)[1]);
             return {
                 userId: principal.userId,
                 computerId: principal.computerId,
                 scopes: automationScopes(principal.scopes),
+                authorizationExpiresAt: claims.exp * 1000,
             };
         },
     });

package/dist/host/main.js

@@ -12,6 +12,8 @@ import { WebhookEndpoints } from '../src/webhook.js';
 import { createAutomationsAuthenticators } from './auth.js';
 import { automationsHostConfig } from './config.js';
 import { createAutomationsHost } from './server.js';
+import { createMachineRunNotifications } from '../src/machine-notifications.js';
+import { subscribeToRunChanges } from './notifications.js';
 const config = automationsHostConfig();
 const supabase = createClient(config.supabaseUrl, config.supabaseServiceRoleKey, {
     auth: { persistSession: false, autoRefreshToken: false },
@@ -27,9 +29,15 @@ const controlApi = createAutomationApi({
     authenticate: authentication.control,
 });
 const machineRepository = new SupabaseMachineRunRepository(supabase);
+const notifications = createMachineRunNotifications({
+    wakeDelay: (userId, computerId) => machineRepository.wakeDelay(userId, computerId),
+    log,
+});
+const closeNotifications = subscribeToRunChanges(supabase, notifications);
 const machineApi = createMachineRunsApi({
     authenticate: authentication.machine,
     runsFor: (principal) => createMachineRuns(machineRepository, principal),
+    notifications,
 });
 const eventsApi = createAutomationEventsApi({
     delivery,
@@ -46,7 +54,7 @@ const host = createAutomationsHost({
 });
 host.server.listen(config.port, '0.0.0.0', () => log('host.ready', { port: config.port }));
 for (const signal of ['SIGINT', 'SIGTERM']) {
-    process.once(signal, () => void host.close().finally(() => process.exit(0)));
+    process.once(signal, () => void closeNotifications().then(() => host.close()).finally(() => process.exit(0)));
 }
 function log(event, details = {}) {
     console.log(JSON.stringify({ service: 'amalgm-automations', event, ...details }));

package/dist/host/notifications.d.ts

@@ -0,0 +1,4 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { MachineRunNotifications } from '../src/machine-notifications.js';
+/** One private database subscription per Fly host, shared by its machine streams. */
+export declare function subscribeToRunChanges(supabase: SupabaseClient, notifications: MachineRunNotifications): () => Promise<void>;

package/dist/host/notifications.js

@@ -0,0 +1,19 @@
+/** One private database subscription per Fly host, shared by its machine streams. */
+export function subscribeToRunChanges(supabase, notifications) {
+    const channel = supabase.channel('amalgm:automations:runs', { config: { private: true } })
+        .on('broadcast', { event: 'changed' }, ({ payload }) => {
+        if (typeof payload?.userId === 'string' && typeof payload?.targetId === 'string') {
+            notifications.changed(payload.userId, payload.targetId);
+        }
+    })
+        .subscribe((status) => {
+        if (status === 'SUBSCRIBED')
+            notifications.connected();
+        else
+            notifications.disconnected();
+    });
+    return async () => {
+        notifications.close();
+        await supabase.removeChannel(channel);
+    };
+}

package/dist/host/server.js

@@ -1,7 +1,9 @@
 import { createServer } from 'node:http';
+import { once } from 'node:events';
 import { publicResourceRequestUrl } from '@amalgm/core/authorization';
 export function createAutomationsHost(options) {
     const log = options.log ?? (() => { });
+    const requests = new Set();
     let scheduling = null;
     const tick = () => {
         if (scheduling)
@@ -14,34 +16,48 @@ export function createAutomationsHost(options) {
     timer.unref();
     tick();
     const server = createServer(async (incoming, outgoing) => {
+        const controller = new AbortController();
+        requests.add(controller);
+        const abort = () => controller.abort();
+        outgoing.once('close', abort);
         try {
             if (incoming.url === '/healthz')
-                return send(outgoing, Response.json({ ok: true }));
-            const request = await webRequest(incoming, options.publicOrigin, options.maxRequestBodyBytes ?? 2 * 1024 * 1024);
+                return await send(outgoing, Response.json({ ok: true }), controller.signal);
+            const request = await webRequest(incoming, options.publicOrigin, options.maxRequestBodyBytes ?? 2 * 1024 * 1024, controller.signal);
             const pathname = new URL(request.url).pathname;
             const api = pathname.startsWith('/e/') && options.eventsApi
                 ? options.eventsApi
                 : pathname.startsWith('/v1/machine/') ? options.machineApi : options.controlApi;
-            await send(outgoing, await api(request));
+            await send(outgoing, await api(request), controller.signal);
         }
         catch (error) {
+            if (controller.signal.aborted)
+                return;
             log('request.failed', { error: safe(error) });
+            if (outgoing.headersSent)
+                return outgoing.destroy();
             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 }));
+            }, { status }), controller.signal);
+        }
+        finally {
+            outgoing.removeListener('close', abort);
+            requests.delete(controller);
         }
     });
     return {
         server,
         async close() {
             clearInterval(timer);
+            for (const request of requests)
+                request.abort();
             await scheduling;
             await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
         },
     };
 }
-async function webRequest(request, publicOrigin, maximumBodyBytes) {
+async function webRequest(request, publicOrigin, maximumBodyBytes, signal) {
     const chunks = [];
     let size = 0;
     for await (const value of request) {
@@ -55,6 +71,7 @@ async function webRequest(request, publicOrigin, maximumBodyBytes) {
     return new Request(publicResourceRequestUrl(publicOrigin, request.url ?? '/'), {
         method: request.method ?? 'GET',
         headers: request.headers,
+        signal,
         ...(body.length ? { body } : {}),
     });
 }
@@ -65,8 +82,30 @@ class HostRequestError extends Error {
         this.status = status;
     }
 }
-async function send(response, source) {
+async function send(response, source, signal) {
     response.writeHead(source.status, Object.fromEntries(source.headers));
-    response.end(Buffer.from(await source.arrayBuffer()));
+    response.flushHeaders();
+    const reader = source.body?.getReader();
+    const abort = () => {
+        void reader?.cancel().catch(() => { });
+        response.destroy();
+    };
+    signal.addEventListener('abort', abort, { once: true });
+    try {
+        signal.throwIfAborted();
+        while (reader) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            if (!response.write(value))
+                await once(response, 'drain', { signal });
+        }
+        response.end();
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        await reader?.cancel().catch(() => { });
+        reader?.releaseLock();
+    }
 }
 const safe = (error) => (error instanceof Error ? error.message : String(error)).slice(0, 500);

package/dist/src/cli/run.d.ts

@@ -8,6 +8,6 @@ export interface AutomationCliIo extends AutomationCliInputPorts {
     stdout?: Output;
     stderr?: Output;
 }
-export declare const automationCliHelp = "amalgm automations \u2014 durable automation control for agents\n\nUsage:\n  amalgm automations <command> [--input JSON | --file PATH | --stdin]\n  amalgm-automations <command> [--input JSON | --file PATH | --stdin]\n\nCommands (identical to the Automations MCP task surface):\n  create    Create one complete definition\n  list      List the user's automations\n  get       Get one complete definition and optional run history\n  update    Apply grouped definition changes\n  delete    Delete current configuration; run history remains\n  run-now   Admit one durable manual run\n\nInput is one JSON object with the corresponding MCP tool's fields. Commands\nwithout options receive {}. Output is one JSON success or error envelope.\nUse --stdin when input contains credentials such as a webhook signing secret.\n\nWorkflow step lanes:\n  version 1  action-only: {\"id\":\"...\",\"actionId\":\"product.action\",\"input\":{...}}\n  version 2  action, command, or script steps:\n    command  {\"id\":\"...\",\"kind\":\"command\",\"command\":\"codex\",\"args\":[\"exec\",\"...\"],\"cwd\":\"/absolute/path\"}\n    script   {\"id\":\"...\",\"kind\":\"script\",\"runtime\":\"shell|node|python\",\"source\":\"...\",\"cwd\":\"/absolute/path\"}\n";
+export declare const automationCliHelp = "amalgm automations \u2014 durable automation control for agents\n\nUsage:\n  amalgm automations <command> [--input JSON | --file PATH | --stdin]\n  amalgm-automations <command> [--input JSON | --file PATH | --stdin]\n\nCommands (identical to the Automations MCP task surface):\n  create    Create one complete definition\n  list      List the user's automations\n  get       Get one complete definition and optional run history\n  update    Apply grouped definition changes\n  delete    Delete current configuration; run history remains\n  run-now   Admit one durable manual run\n\nInput is one JSON object with the corresponding MCP tool's fields. Commands\nwithout options receive {}. Output is one JSON success or error envelope.\nUse --stdin when input contains credentials such as a webhook signing secret.\n\nSetup and support:\n  Already connected? Reuse the running Amalgm Shell.\n  First login: amalgm login --no-open\n    Open the printed link, sign in with Google, and approve this computer.\n    Keep the login process running; it hosts Shell after approval.\n  Check: amalgm status --user EMAIL\n  Resume a registered computer: amalgm run --user EMAIL\n  Verify access: amalgm automations list --user EMAIL --input '{\"limit\":1}'\n  No local installation? https://amalgm.ai/setup\n  Support: aayush@amalgm.ai\n  Never copy private connection credentials into a command or support email.\n\nWorkflow step lanes:\n  version 1  action-only: {\"id\":\"...\",\"actionId\":\"product.action\",\"input\":{...}}\n  version 2  action, command, or script steps:\n    command  {\"id\":\"...\",\"kind\":\"command\",\"command\":\"codex\",\"args\":[\"exec\",\"...\"],\"cwd\":\"/absolute/path\"}\n    script   {\"id\":\"...\",\"kind\":\"script\",\"runtime\":\"shell|node|python\",\"source\":\"...\",\"cwd\":\"/absolute/path\"}\n";
 export declare function runAutomationCli(argv: string[], backend: AutomationCrud | AutomationCommands, io?: AutomationCliIo): Promise<number>;
 export {};

package/dist/src/cli/run.js

@@ -20,6 +20,18 @@ Input is one JSON object with the corresponding MCP tool's fields. Commands
 without options receive {}. Output is one JSON success or error envelope.
 Use --stdin when input contains credentials such as a webhook signing secret.
 
+Setup and support:
+  Already connected? Reuse the running Amalgm Shell.
+  First login: amalgm login --no-open
+    Open the printed link, sign in with Google, and approve this computer.
+    Keep the login process running; it hosts Shell after approval.
+  Check: amalgm status --user EMAIL
+  Resume a registered computer: amalgm run --user EMAIL
+  Verify access: amalgm automations list --user EMAIL --input '{"limit":1}'
+  No local installation? https://amalgm.ai/setup
+  Support: aayush@amalgm.ai
+  Never copy private connection credentials into a command or support email.
+
 Workflow step lanes:
   version 1  action-only: {"id":"...","actionId":"product.action","input":{...}}
   version 2  action, command, or script steps:

package/dist/src/index.d.ts

@@ -19,6 +19,7 @@ export { SupabaseMachineRunRepository, type MachineRpcClient } from './supabase-
 export { createMachineRuns } from './machine.js';
 export type { AutomationMachinePrincipal, ClaimedAutomationRun, MachineRunRepository, MachineRuns, MachineRunUpdate, } from './machine.js';
 export { createMachineRunsApi } from './machine-http.js';
+export { createMachineRunNotifications, type MachineRunNotifications } from './machine-notifications.js';
 export { createMachineRunsClient, type AutomationRequestHeaders } from './machine-client.js';
 export { AutomationRunExecutor, automationPlan, type AutomationActionPort, type AutomationProcessExecution, type AutomationProcessPort, type AutomationRunExecutorOptions, } from './executor.js';
 export { createNodeAutomationProcessHost, type NodeAutomationProcessHostOptions, } from './node-process-host.js';

package/dist/src/index.js

@@ -24,6 +24,7 @@ export { SupabaseStore } from './supabase-store.js';
 export { SupabaseMachineRunRepository } from './supabase-machine.js';
 export { createMachineRuns } from './machine.js';
 export { createMachineRunsApi } from './machine-http.js';
+export { createMachineRunNotifications } from './machine-notifications.js';
 export { createMachineRunsClient } from './machine-client.js';
 export { AutomationRunExecutor, automationPlan, } from './executor.js';
 export { createNodeAutomationProcessHost, } from './node-process-host.js';

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

@@ -5,4 +5,6 @@ export declare function createMachineRunsClient(options: {
     readonly headers: AutomationRequestHeaders;
     readonly fetch?: typeof globalThis.fetch;
     readonly requestTimeoutMs?: number;
-}): MachineRuns;
+}): MachineRuns & {
+    notifications(signal: AbortSignal): AsyncIterable<void>;
+};

package/dist/src/machine-client.js

@@ -1,4 +1,5 @@
 import { AutomationError } from './errors.js';
+import { machineEventStream } from './machine-event-stream.js';
 export function createMachineRunsClient(options) {
     const baseUrl = options.baseUrl.replace(/\/$/, '');
     const fetch = options.fetch ?? globalThis.fetch;
@@ -23,6 +24,11 @@ export function createMachineRunsClient(options) {
         return payload;
     };
     return Object.freeze({
+        notifications(signal) {
+            return machineEventStream({
+                url: `${baseUrl}/v1/machine/runs/notifications`, headers: options.headers, fetch, signal,
+            });
+        },
         async claim(input = {}) {
             const result = await request('/v1/machine/runs/claim', 'POST', input);
             return result.runs;

package/dist/src/machine-event-stream.d.ts

@@ -0,0 +1,8 @@
+import type { AutomationRequestHeaders } from './machine-client.js';
+/** A wakeup stream carries no run data; every reconnect gets fresh authorization. */
+export declare function machineEventStream(options: {
+    readonly url: string;
+    readonly headers: AutomationRequestHeaders;
+    readonly fetch: typeof globalThis.fetch;
+    readonly signal: AbortSignal;
+}): AsyncGenerator<void>;

package/dist/src/machine-event-stream.js

@@ -0,0 +1,58 @@
+import { AutomationError } from './errors.js';
+/** A wakeup stream carries no run data; every reconnect gets fresh authorization. */
+export async function* machineEventStream(options) {
+    const connection = new AbortController();
+    const signal = AbortSignal.any([options.signal, connection.signal]);
+    let rejectAborted;
+    const aborted = new Promise((_, reject) => { rejectAborted = reject; });
+    const abort = () => rejectAborted(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    let timeout = setTimeout(() => connection.abort(new Error('Notification connection timed out')), 15_000);
+    timeout.unref();
+    let reader;
+    try {
+        const headers = await Promise.race([
+            Promise.resolve().then(() => { signal.throwIfAborted(); return options.headers('GET', options.url); }),
+            aborted,
+        ]);
+        signal.throwIfAborted();
+        const response = await options.fetch(options.url, {
+            headers: { ...headers, accept: 'text/event-stream' }, signal,
+        });
+        if (!response.ok)
+            throw new AutomationError('notifications_unavailable', `Automations notifications returned ${response.status}`, response.status);
+        if (!response.headers.get('content-type')?.startsWith('text/event-stream') || !response.body) {
+            throw new Error('Expected an Automations notification stream');
+        }
+        reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let pending = '';
+        while (!signal.aborted) {
+            clearTimeout(timeout);
+            timeout = setTimeout(() => connection.abort(new Error('Notification connection went silent')), 75_000);
+            timeout.unref();
+            const { value, done } = await reader.read();
+            if (done)
+                throw new Error('Automations notification connection closed');
+            pending += decoder.decode(value, { stream: true });
+            let boundary;
+            while ((boundary = /\r?\n\r?\n/.exec(pending))) {
+                const frame = pending.slice(0, boundary.index);
+                pending = pending.slice(boundary.index + boundary[0].length);
+                if (frame.length > 16_384)
+                    throw new Error('Automations notification is too large');
+                if (/^event: ?(?:ready|wake)\r?$/m.test(frame))
+                    yield;
+            }
+            if (pending.length > 16_384)
+                throw new Error('Automations notification is too large');
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        signal.removeEventListener('abort', abort);
+        connection.abort();
+        await reader?.cancel().catch(() => { });
+        reader?.releaseLock();
+    }
+}

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

@@ -1,5 +1,7 @@
 import type { AutomationMachinePrincipal, MachineRuns } from './machine.js';
+import type { MachineRunNotifications } from './machine-notifications.js';
 export declare function createMachineRunsApi(options: {
     readonly authenticate: (request: Request) => Promise<AutomationMachinePrincipal>;
     readonly runsFor: (principal: AutomationMachinePrincipal) => MachineRuns;
+    readonly notifications?: Pick<MachineRunNotifications, 'open'>;
 }): (request: Request) => Promise<Response>;

package/dist/src/machine-http.js

@@ -7,7 +7,13 @@ export function createMachineRunsApi(options) {
             if (parts[0] !== 'v1' || parts[1] !== 'machine' || parts[2] !== 'runs') {
                 return json(404, { error: 'Not found' });
             }
-            const runs = options.runsFor(await options.authenticate(request));
+            const principal = await options.authenticate(request);
+            if (parts[3] === 'notifications' && parts.length === 4 && request.method === 'GET') {
+                if (!options.notifications)
+                    throw new AutomationError('unavailable', 'Notifications unavailable', 503);
+                return options.notifications.open(principal, request.signal);
+            }
+            const runs = options.runsFor(principal);
             if (parts[3] === 'claim' && parts.length === 4 && request.method === 'POST') {
                 return json(200, { runs: await runs.claim(await body(request)) });
             }
@@ -18,7 +24,7 @@ export function createMachineRunsApi(options) {
         }
         catch (error) {
             if (error instanceof AutomationError)
-                return json(error.code === 'validation' ? 400 : 403, {
+                return json(error.status ?? (error.code === 'validation' ? 400 : 403), {
                     error: error.message, code: error.code,
                 });
             const code = error instanceof Error && 'code' in error ? String(error.code) : 'internal';

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

@@ -0,0 +1,15 @@
+import type { AutomationMachinePrincipal } from './machine.js';
+/** Ephemeral wakeups only. Supabase remains the queue and the eligibility clock. */
+export declare function createMachineRunNotifications(options: {
+    readonly wakeDelay: (userId: string, computerId: string) => Promise<number | null>;
+    readonly heartbeatMs?: number;
+    readonly maxStreamMs?: number;
+    readonly log?: (event: string, details: Readonly<Record<string, unknown>>) => void;
+}): Readonly<{
+    connected(): void;
+    disconnected: () => void;
+    close: () => void;
+    changed(userId: string, computerId: string): void;
+    open(principal: AutomationMachinePrincipal, signal: AbortSignal): Response;
+}>;
+export type MachineRunNotifications = ReturnType<typeof createMachineRunNotifications>;

package/dist/src/machine-notifications.js

@@ -0,0 +1,124 @@
+import { AutomationError } from './errors.js';
+/** Ephemeral wakeups only. Supabase remains the queue and the eligibility clock. */
+export function createMachineRunNotifications(options) {
+    const targets = new Map();
+    const encoder = new TextEncoder();
+    let connected = false;
+    const key = (userId, computerId) => JSON.stringify([userId, computerId]);
+    const refresh = async (target) => {
+        target.dirty = true;
+        if (target.refreshing)
+            return;
+        target.refreshing = true;
+        try {
+            while (target.dirty && target.listeners.size) {
+                target.dirty = false;
+                clearTimeout(target.timer);
+                const delay = await options.wakeDelay(target.userId, target.computerId);
+                if (target.dirty || !target.listeners.size)
+                    continue;
+                if (delay === null)
+                    continue;
+                if (!Number.isFinite(delay) || delay < 0)
+                    throw new Error('Invalid machine wake delay');
+                if (delay === 0) {
+                    for (const listener of target.listeners)
+                        listener.send('wake');
+                }
+                else {
+                    target.timer = setTimeout(() => void refresh(target), Math.min(delay, 2_147_483_647));
+                    target.timer.unref();
+                }
+            }
+        }
+        catch {
+            options.log?.('automations.notifications.failed', { boundary: 'wake-deadline' });
+            for (const listener of [...target.listeners])
+                listener.close();
+        }
+        finally {
+            target.refreshing = false;
+        }
+    };
+    const disconnect = () => {
+        connected = false;
+        for (const target of targets.values()) {
+            for (const listener of [...target.listeners])
+                listener.close();
+        }
+    };
+    return Object.freeze({
+        connected() { connected = true; },
+        disconnected: disconnect,
+        close: disconnect,
+        changed(userId, computerId) {
+            const target = targets.get(key(userId, computerId));
+            if (target)
+                void refresh(target);
+        },
+        open(principal, signal) {
+            if (!connected)
+                throw new AutomationError('unavailable', 'Notifications are reconnecting', 503);
+            signal.throwIfAborted();
+            const targetKey = key(principal.userId, principal.computerId);
+            let target = targets.get(targetKey);
+            if (!target) {
+                target = { ...principal, listeners: new Set(), refreshing: false, dirty: false };
+                targets.set(targetKey, target);
+            }
+            const current = target;
+            let close = (_closeStream = true) => { };
+            const body = new ReadableStream({
+                start(controller) {
+                    let closed = false;
+                    let heartbeat;
+                    let expiry;
+                    const abort = () => close();
+                    close = (closeStream = true) => {
+                        if (closed)
+                            return;
+                        closed = true;
+                        clearInterval(heartbeat);
+                        clearTimeout(expiry);
+                        signal.removeEventListener('abort', abort);
+                        current.listeners.delete(listener);
+                        if (!current.listeners.size) {
+                            clearTimeout(current.timer);
+                            targets.delete(targetKey);
+                        }
+                        if (closeStream)
+                            controller.close();
+                    };
+                    const listener = {
+                        send(event) {
+                            if (closed)
+                                return;
+                            if ((controller.desiredSize ?? 0) <= 0)
+                                return close();
+                            controller.enqueue(encoder.encode(event === 'heartbeat'
+                                ? ': keepalive\n\n' : `event: ${event}\ndata: {}\n\n`));
+                        },
+                        close,
+                    };
+                    current.listeners.add(listener);
+                    signal.addEventListener('abort', abort, { once: true });
+                    heartbeat = setInterval(() => listener.send('heartbeat'), options.heartbeatMs ?? 30_000);
+                    heartbeat.unref();
+                    const lifetime = Math.min(options.maxStreamMs ?? 300_000, (principal.authorizationExpiresAt ?? Infinity) - Date.now());
+                    expiry = setTimeout(close, Math.max(0, lifetime));
+                    expiry.unref();
+                    listener.send('ready');
+                    void refresh(current);
+                },
+                cancel() { close(false); },
+            }, { highWaterMark: 8 });
+            return new Response(body, {
+                headers: {
+                    'content-type': 'text/event-stream',
+                    'cache-control': 'no-store, no-transform',
+                    'x-accel-buffering': 'no',
+                },
+            });
+        },
+    });
+}

package/dist/src/machine.d.ts

@@ -4,6 +4,7 @@ export interface AutomationMachinePrincipal {
     readonly userId: string;
     readonly computerId: string;
     readonly scopes: readonly AutomationScope[];
+    readonly authorizationExpiresAt?: number;
 }
 export interface ClaimedAutomationRun extends AutomationRun {
     readonly leaseToken: string;

package/dist/src/runner.d.ts

@@ -1,13 +1,15 @@
 import type { ClaimedAutomationRun, MachineRuns } from './machine.js';
 export interface AutomationMachineRunnerOptions {
     readonly runs: MachineRuns;
+    readonly notifications: (signal: AbortSignal) => AsyncIterable<void>;
     readonly execute: (run: ClaimedAutomationRun) => Promise<void>;
     readonly batchSize?: number;
     readonly leaseSeconds?: number;
-    readonly pollIntervalMs?: number;
+    readonly reconnectDelayMs?: number;
     readonly maxBackoffMs?: number;
     readonly log?: (event: string, details?: Readonly<Record<string, unknown>>) => void;
 }
+/** Listen first, then drain. There is no timer that asks an idle machine for work. */
 export declare function createAutomationMachineRunner(options: AutomationMachineRunnerOptions): Readonly<{
     start(): void;
     close(): Promise<void>;