@amalgm/automations 0.3.2 → 0.4.1

package/AXIOMS.md

@@ -91,7 +91,8 @@
 33. MCP and CLI project one task-level command catalog: create, list, get,
     update, delete, and run-now. Command names, input schemas, and invocation
     behavior are defined once and neither adapter invents resource-level
-    lifecycle operations.
+    lifecycle operations. Unknown configuration fields are rejected, never
+    discarded by an adapter; declared JSON payloads remain open data.
 34. A CLI running for a signed-in user reaches Automations through Shell's
     authenticated loopback MCP route. It may possess the local runtime admission
     token, but never a durable machine credential, device key, cached access
@@ -129,3 +130,17 @@
     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.
+49. A complete definition validates all supplied configuration before its
+    first write; a later service failure preserves an identifiable disabled
+    draft and the original failure code.

package/PURPOSE.md

@@ -27,6 +27,21 @@ 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.
+
+Complete create and update requests validate their supplied schedules, workflow
+plans, and field names before writing configuration. Unknown fields cannot
+silently become a different request. If a service fails after staging begins,
+the disabled draft remains inspectable and the error keeps that service's code,
+so the agent can repair the same definition rather than repeat its creation.
+
 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 +53,21 @@ 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 standalone service publishes a public skill discovery index and an
+integrity-checked archive built from that same packaged skill. Installation
+needs no private repository access, and the archive includes its referenced
+instructions. Public distribution owns no copy of authentication or workflow
+behavior.
+
 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

@@ -47,7 +47,10 @@ the API request.
 - `@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 safely.
+  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
 
@@ -95,15 +98,32 @@ one JSON line on stderr shaped as
 `status`, and exits nonzero. Use `--stdin` for inputs containing credentials;
 `--input` and `--file` are also supported.
 
-When Shell invokes the adapter, it supplies `AMALGM_MCP_URL` and
-`AMALGM_RUNTIME_TOKEN` from its running user runtime. The CLI sends that
-runtime token only to the loopback `/mcp/automations` route. Shell retains the
+Shell supplies the selected running user's loopback connection directly to
+the SDK adapter. The CLI sends its runtime token only to the loopback
+`/mcp/automations` route. Shell retains the
 durable machine credential and device key and creates the short-lived access
 token and fresh DPoP proof for the hosted request. For transition
 compatibility, the standalone entry point still accepts the prior paired
 `AMALGM_AUTOMATIONS_API_URL` and `AMALGM_AUTOMATIONS_AUTHORIZATION`
 environment variables.
 
+For public local MCP clients, Shell 0.1.176+ provides
+`amalgm automations mcp --user person@example.com`. It exposes the same six
+tools over stdio and discovers the current runtime connection per call.
+`amalgm status --all` lists local account registrations. No pasted token or
+private repository access is part of either flow; the standalone
+`amalgm-automations-mcp` entry point remains for custom authenticated hosts.
+
+Install the complete portable skill with Node.js 22.20+:
+
+```bash
+npx skills add https://automations.amalgm.ai --skill amalgm-automations
+```
+
+The host serves standard discovery at `/.well-known/agent-skills/index.json`
+and a checksum-addressed archive built from `skills/amalgm-automations`.
+The archive includes its references and agent metadata and requires no login.
+
 The hosted service accepts verified Supabase user sessions for browser control
 and Core-issued `amalgm-automations` DPoP grants for Shell. It does not run in
 or depend on Amalgm Gateway.
@@ -200,6 +220,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:
@@ -218,13 +239,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,9 @@ 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';
+import { createPublicSkillApi } from './skill.js';
 const config = automationsHostConfig();
 const supabase = createClient(config.supabaseUrl, config.supabaseServiceRoleKey, {
     auth: { persistSession: false, autoRefreshToken: false },
@@ -27,9 +30,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,
@@ -40,13 +49,14 @@ const host = createAutomationsHost({
     controlApi,
     machineApi,
     eventsApi,
+    publicSkillApi: createPublicSkillApi(),
     fireSchedules: () => delivery.fireDueCrons(),
     schedulerIntervalMs: config.schedulerIntervalMs,
     log,
 });
 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.d.ts

@@ -4,6 +4,7 @@ export declare function createAutomationsHost(options: {
     readonly controlApi: (request: Request) => Promise<Response>;
     readonly machineApi: (request: Request) => Promise<Response>;
     readonly eventsApi?: (request: Request) => Promise<Response>;
+    readonly publicSkillApi?: (request: Request) => Promise<Response>;
     readonly fireSchedules: () => Promise<unknown>;
     readonly schedulerIntervalMs: number;
     readonly maxRequestBodyBytes?: number;

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,50 @@ 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));
+            const api = pathname.startsWith('/.well-known/agent-skills/') && options.publicSkillApi
+                ? options.publicSkillApi
+                : pathname.startsWith('/e/') && options.eventsApi
+                    ? options.eventsApi
+                    : pathname.startsWith('/v1/machine/') ? options.machineApi : options.controlApi;
+            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 +73,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 +84,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/host/skill.d.ts

@@ -0,0 +1,2 @@
+/** Only the two packaged public artifacts are addressable; no arbitrary file reads. */
+export declare function createPublicSkillApi(directory?: URL): (request: Request) => Promise<Response>;

package/dist/host/skill.js

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+const prefix = '/.well-known/agent-skills/';
+/** Only the two packaged public artifacts are addressable; no arbitrary file reads. */
+export function createPublicSkillApi(directory = new URL('../skills/', import.meta.url)) {
+    const index = readFileSync(new URL('index.json', directory));
+    const entry = JSON.parse(index.toString('utf8')).skills[0];
+    const filename = entry.url.replace(/^\.\//, '');
+    if (!/^amalgm-automations\.[a-f0-9]{64}\.tgz$/.test(filename))
+        throw new Error('Invalid skill artifact');
+    const files = new Map([
+        [`${prefix}index.json`, { bytes: index, type: 'application/json', cache: 'no-cache' }],
+        [`${prefix}${filename}`, {
+                bytes: readFileSync(new URL(filename, directory)), type: 'application/gzip',
+                cache: 'public, max-age=31536000, immutable',
+            }],
+    ]);
+    return async (request) => {
+        const file = files.get(new URL(request.url).pathname);
+        if (!file)
+            return new Response('Not found', { status: 404 });
+        if (request.method !== 'GET' && request.method !== 'HEAD') {
+            return new Response('Method not allowed', { status: 405, headers: { allow: 'GET, HEAD' } });
+        }
+        return new Response(request.method === 'HEAD' ? null : new Uint8Array(file.bytes), {
+            headers: {
+                'content-type': file.type,
+                'content-length': String(file.bytes.byteLength),
+                'cache-control': file.cache,
+                'x-content-type-options': 'nosniff',
+            },
+        });
+    };
+}

package/dist/skills/index.json

@@ -0,0 +1 @@
+{"$schema":"https://schemas.agentskills.io/discovery/0.2.0/schema.json","skills":[{"name":"amalgm-automations","description":"Set up, operate, and troubleshoot Amalgm Automations through MCP or the amalgm automations CLI. Use for installation, Google sign-in, scheduled or webhook workflows, Run Now, run history, and Automations support.","type":"archive","url":"./amalgm-automations.5e4e14f0ace632c8383cd014e1f0f34b24ec0d5c5600132a840abc4c313b31d4.tgz","digest":"sha256:5e4e14f0ace632c8383cd014e1f0f34b24ec0d5c5600132a840abc4c313b31d4"}]}

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  List local accounts: amalgm status --all\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\nExternal agent MCP setup (after Shell login):\n  amalgm automations mcp --user EMAIL\n  Configure your client to launch this stdio command. No credential fields.\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,23 @@ 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
+  List local accounts: amalgm status --all
+  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.
+
+External agent MCP setup (after Shell login):
+  amalgm automations mcp --user EMAIL
+  Configure your client to launch this stdio command. No credential fields.
+
 Workflow step lanes:
   version 1  action-only: {"id":"...","actionId":"product.action","input":{...}}
   version 2  action, command, or script steps:

package/dist/src/crud/triggers.js

@@ -22,7 +22,6 @@ export function triggerOperations(context) {
                 await context.exists(automationId);
                 const parsed = parseCreateScheduleTrigger(input);
                 const timezone = parsed.timezone || 'UTC';
-                schedule(parsed.cron, timezone);
                 if (parsed.id)
                     await unique(automationId, parsed.id);
                 return repository.createScheduleTrigger(principal.userId, automationId, {

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>;