@amalgm/automations 0.3.1 → 0.4.0

package/dist/src/runner.js

@@ -1,61 +1,84 @@
+import { setTimeout as delay } from 'node:timers/promises';
+/** Listen first, then drain. There is no timer that asks an idle machine for work. */
 export function createAutomationMachineRunner(options) {
     const batchSize = integer(options.batchSize ?? 8, 1, 20, 'batchSize');
     const leaseSeconds = integer(options.leaseSeconds ?? 60, 30, 900, 'leaseSeconds');
-    const pollIntervalMs = integer(options.pollIntervalMs ?? 1_000, 1, 60_000, 'pollIntervalMs');
-    const maxBackoffMs = integer(options.maxBackoffMs ?? Math.max(30_000, pollIntervalMs), pollIntervalMs, 300_000, 'maxBackoffMs');
-    let active = null;
-    let timer = null;
-    let stopped = true;
-    let failures = 0;
-    let nextDelay = pollIntervalMs;
-    const schedule = (delay) => {
-        if (stopped)
+    const reconnectDelayMs = integer(options.reconnectDelayMs ?? 1_000, 1, 60_000, 'reconnectDelayMs');
+    const maxBackoffMs = integer(options.maxBackoffMs ?? 30_000, reconnectDelayMs, 300_000, 'maxBackoffMs');
+    let lifetime = null;
+    let listening = null;
+    let draining = null;
+    let pending = false;
+    const wake = (connection, signal) => {
+        pending = true;
+        if (draining)
             return;
-        timer = setTimeout(drain, delay);
-        timer.unref?.();
-    };
-    const drain = () => {
-        if (stopped || active)
-            return active;
-        active = options.runs.claim({ limit: batchSize, leaseSeconds })
-            .then(async (runs) => {
-            failures = 0;
-            if (runs.length)
-                options.log?.('automations.claimed', { count: runs.length });
-            const settled = await Promise.allSettled(runs.map(options.execute));
-            settled.forEach((result) => {
-                if (result.status === 'rejected') {
-                    options.log?.('automations.run.failed', { error: safe(result.reason) });
+        draining = (async () => {
+            while (pending && !signal.aborted) {
+                pending = false;
+                const runs = await options.runs.claim({ limit: batchSize, leaseSeconds });
+                if (runs.length)
+                    options.log?.('automations.claimed', { count: runs.length });
+                const settled = await Promise.allSettled(runs.map(options.execute));
+                for (const result of settled) {
+                    if (result.status === 'rejected')
+                        options.log?.('automations.run.failed', { error: safe(result.reason) });
                 }
-            });
-            nextDelay = runs.length === batchSize ? 0 : pollIntervalMs;
-        })
-            .catch((error) => {
-            failures += 1;
-            const delayMs = Math.min(maxBackoffMs, pollIntervalMs * (2 ** Math.min(failures - 1, 10)));
-            options.log?.('automations.poll.failed', { error: safe(error), retryInMs: delayMs });
-            nextDelay = delayMs;
-        })
-            .finally(() => {
-            active = null;
-            schedule(nextDelay);
+                // Work may arrive while execution is busy, including a partial last batch.
+                pending ||= runs.length > 0;
+            }
+        })().catch((error) => {
+            options.log?.('automations.claim.failed', { error: safe(error) });
+            connection.abort(error);
+        }).finally(() => {
+            draining = null;
+            if (pending && !signal.aborted && !connection.signal.aborted)
+                wake(connection, signal);
         });
-        return active;
+    };
+    const listen = async (signal) => {
+        let failures = 0;
+        while (!signal.aborted) {
+            const connection = new AbortController();
+            const connectedSignal = AbortSignal.any([signal, connection.signal]);
+            const startedAt = Date.now();
+            try {
+                for await (const _ of options.notifications(connectedSignal)) {
+                    if (connectedSignal.aborted)
+                        break;
+                    wake(connection, signal);
+                }
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    options.log?.('automations.notifications.disconnected', { error: safe(error) });
+            }
+            finally {
+                connection.abort();
+                await draining;
+            }
+            if (signal.aborted)
+                break;
+            // A flapping stream must not reset its backoff merely by sending ready.
+            failures = Date.now() - startedAt >= 30_000 ? 0 : failures + 1;
+            const backoff = Math.min(maxBackoffMs, reconnectDelayMs * 2 ** Math.min(Math.max(0, failures - 1), 10));
+            await delay(backoff, undefined, { signal, ref: false }).catch(() => { });
+        }
     };
     return Object.freeze({
         start() {
-            if (!stopped)
+            if (lifetime)
                 return;
-            stopped = false;
-            failures = 0;
-            void drain();
+            lifetime = new AbortController();
+            pending = false;
+            listening = listen(lifetime.signal);
         },
         async close() {
-            stopped = true;
-            if (timer)
-                clearTimeout(timer);
-            timer = null;
-            await active;
+            lifetime?.abort();
+            await listening;
+            await draining;
+            lifetime = null;
+            listening = null;
         },
     });
 }

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

@@ -11,6 +11,7 @@ export declare class SupabaseMachineRunRepository implements MachineRunRepositor
     #private;
     private readonly client;
     constructor(client: MachineRpcClient);
+    wakeDelay(userId: string, computerId: string): Promise<number | null>;
     claim(input: Parameters<MachineRunRepository['claim']>[0]): Promise<ClaimedAutomationRun[]>;
     update(input: Parameters<MachineRunRepository['update']>[0]): Promise<ClaimedAutomationRun | null>;
 }

package/dist/src/supabase-machine.js

@@ -4,6 +4,9 @@ export class SupabaseMachineRunRepository {
     constructor(client) {
         this.client = client;
     }
+    wakeDelay(userId, computerId) {
+        return this.#call('amalgm_machine_wake_delay', { p_user_id: userId, p_target_id: computerId });
+    }
     async claim(input) {
         const rows = await this.#call('claim_amalgm_machine_runs', {
             p_user_id: input.userId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Amalgm's automation SDK: durable trigger admission and target-machine execution.",
   "license": "UNLICENSED",
   "repository": {
@@ -49,6 +49,7 @@
     "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json --noEmit",
     "test": "tsx --test test/*.test.ts",
     "test:supabase": "tsx --test test/integration/postgres.test.ts",
+    "test:notifications": "tsx scripts/test-notifications.ts",
     "verify": "npm run check && npm test && npm run build && tsx scripts/check-cli-artifact.ts",
     "release:check": "npm run verify && npm run test:supabase",
     "prepack": "npm run build",

package/skills/amalgm-automations/SKILL.md

@@ -0,0 +1,148 @@
+---
+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.
+---
+
+# Amalgm Automations
+
+Use this skill to turn a user's requested recurring, event-driven, or manual
+workflow into one durable Amalgm automation and verify what actually ran.
+Automations owns configuration and permanent run history; the selected Amalgm
+machine executes the workflow.
+
+Amalgm Automations is free. Guide the person through Google sign-in and computer
+approval when needed; do not introduce a payment step. A native agent or other
+external service still uses its own account and may have its own usage costs.
+
+## Choose the available adapter
+
+Prefer the six `amalgm_automations_*` MCP tools when they are callable. In a
+native local agent without that MCP server, use the matching global CLI:
+
+```text
+MCP                                 CLI
+amalgm_automations_create           amalgm automations create
+amalgm_automations_list             amalgm automations list
+amalgm_automations_get              amalgm automations get
+amalgm_automations_update           amalgm automations update
+amalgm_automations_delete           amalgm automations delete
+amalgm_automations_run_now          amalgm automations run-now
+```
+
+Both adapters accept the same JSON object and call the same SDK command
+surface. Do not translate one into a different resource-level API.
+
+Reuse a working connection. For an available MCP connection, a small `list`
+request with `{"limit":1}` proves access; do not install or log in again. For
+CLI use, check `amalgm automations --help` and use
+`amalgm automations list --input '{"limit":1}'`. An empty successful list is
+ready, not a setup failure. Respect an explicitly selected account.
+
+If the user asks to install or sign in, or that read fails, read
+[setup and support](references/setup-and-support.md). It covers the supported
+install, browser approval, account selection, runtime restart, and recovery
+commands. Carry setup through to a successful Automations read, then resume
+the original request. Do not stop at “Shell must be running.”
+
+Shell owns authentication. Never read, copy, or ask the user to supply a runtime
+token, DPoP proof, device key, or machine credential. The public connection
+commands obtain what they need; environment-variable credential setup is not
+the user login flow.
+
+Read [references/command-contract.md](references/command-contract.md) whenever
+composing `create` or `update`, or when exact fields are uncertain. Read
+[references/workflow-plans.md](references/workflow-plans.md) whenever a
+workflow runs an Amalgm action, native executable, code script, or trigger
+input.
+
+## Preserve scope and intent
+
+- List or get before changing an existing automation. Identify the exact
+  automation and preserve fields the user did not ask to change.
+- The CLI is global. Its invocation directory never scopes the automation.
+  Execution belongs to the selected target machine.
+- Omit `targetId` in a machine-bound session. Never guess or copy an opaque
+  target id. If the principal has multiple targets, let the service require an
+  explicit user choice.
+- A process `cwd`, when supplied, must be absolute. If omitted, the selected
+  machine uses its documented default (normally that user's OS home).
+- Workflow `env` is persisted ordinary configuration, not a secret store.
+  Never place Shell credentials or reusable service secrets in it.
+- Use `--stdin` for CLI payloads containing a webhook signing secret or
+  complex source. Do not expose those values in command arguments or logs.
+- Delete only after the exact id is established and deletion is within the
+  user's request. Deleting configuration intentionally retains run history.
+
+## Build one complete definition
+
+Create the automation, its schedule/webhook triggers, and its optional workflow
+in one task-level call. The service stages multi-resource changes safely and
+enables the definition only after setup succeeds. If setup fails, report the
+returned disabled draft id rather than silently creating a replacement.
+
+Use a finite `maxOccurrences` when the user's request is bounded. Do not turn
+"ten times" into an unbounded schedule plus a future cleanup promise.
+
+Choose workflow lanes explicitly:
+
+- An Amalgm tool or Amalgm agent is an action step. `chat.chat_agent_run` is
+  the Amalgm-agent path and requires a configured agent installation.
+- A user's native Codex, Claude Code, OpenCode, or other installed program is
+  a command step. Arguments are literal argv; no shell is implied.
+- Inline shell, Node.js, or Python source is a script step. Choose this lane
+  only when code or shell semantics are intentional.
+
+Version 1 is action-only. Use version 2 for command or script steps and when
+mixing lanes. Discover Amalgm action ids through the Tools product and native
+executables through the selected machine; never guess either.
+
+## Verify Run Now to completion
+
+`run-now` performs durable manual admission. Its initial `pending` result is
+not evidence that work completed.
+
+1. Supply a stable, caller-chosen `idempotency_key` whenever the request might
+   be retried.
+2. If admission is retried, send the same automation id, input, and key. The
+   returned run id must remain the same.
+3. Poll `get` with `include_runs: true` or a `run_query` until the admitted run
+   becomes `completed` or `failed`. Match the exact run id; do not assume the
+   newest unrelated run is yours. Space out reads and back off while state is
+   unchanged; a rate-limit response is a reason to wait, not to submit again.
+4. Inspect every step's status and bounded output. Report failure honestly,
+   including the failing step and service error.
+
+`pending` means durable and awaiting its machine. `sent` or `running` means the
+machine holds a lease. Only `completed` and `failed` are terminal.
+
+Keep the user informed while waiting. If the machine stays unavailable or the
+current session cannot keep waiting, report the exact run id and observed
+nonterminal state; do not claim completion, create a replacement, or promise
+background monitoring that has not been set up.
+
+Diagnose at the failing boundary. Examples: `process_execution_unavailable`
+means that machine lacks the process host; an executable-not-found error is a
+machine PATH/install problem; `Installed agent has no model` is agent
+configuration; an action-specific HTTP error belongs to that action service.
+Do not relabel these as Run Now failures or patch the automation around them.
+
+## Help when something goes wrong
+
+Use [setup and support](references/setup-and-support.md) for login/runtime
+failures, HTTP 429 or reported rate limits, and contacting support. Preserve
+the actual error code, distinguish the failing service, and use bounded retries.
+Do not invent minute/hour allowances or reset times that the service has not
+reported.
+
+For an unresolved issue, offer **Email Aayush at aayush@amalgm.ai** and prepare
+a concise, redacted draft when helpful. Send only with the user's explicit
+authorization and an available email tool; otherwise give them the draft.
+
+## Report the outcome
+
+Return the automation id, target choice if the user selected one, trigger
+summary, workflow lanes, and—when execution was requested—the exact run id and
+terminal result. Mention that run history is durable. Never claim a schedule
+fired merely because configuration creation succeeded.
+Include automation/run links when returned by the product; do not invent a
+deep link or use a private webhook URL as a viewing link.

package/skills/amalgm-automations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Amalgm Automations"
+  short_description: "Set up, run, and troubleshoot Amalgm automations"
+  default_prompt: "Use $amalgm-automations to help me connect my account and create and verify an automation."

package/skills/amalgm-automations/references/command-contract.md

@@ -0,0 +1,173 @@
+# Command contract
+
+Use the field names below exactly. MCP receives the object directly. CLI
+receives it through `--input '<json>'`, `--file <path>`, or `--stdin` and emits
+one JSON envelope:
+
+```json
+{"result": {}}
+```
+
+Failures use stderr, a nonzero exit, and:
+
+```json
+{"error":{"code":"...","message":"...","status":400}}
+```
+
+Do not scrape prose or infer success from exit code alone; parse the envelope.
+
+## create
+
+```json
+{
+  "id": "optional-readable-id",
+  "targetId": "optional-explicit-target",
+  "name": "Optional name",
+  "description": "Optional description",
+  "enabled": true,
+  "schedules": [{
+    "id": "optional-trigger-id",
+    "cron": "0 9 * * 1-5",
+    "timezone": "America/Los_Angeles",
+    "enabled": true,
+    "maxOccurrences": 10
+  }],
+  "webhooks": [{
+    "id": "optional-trigger-id",
+    "source": "github",
+    "event": "push",
+    "secret": "optional-provider-secret-at-least-16-characters",
+    "enabled": true
+  }],
+  "workflow": {
+    "id": "optional-workflow-id",
+    "name": "Optional workflow name",
+    "script": "Human-readable summary of what the workflow does.",
+    "compiled": {
+      "version": 1,
+      "steps": [{
+        "id": "notify",
+        "actionId": "channels.notify_user",
+        "input": {"title":"Reminder","message":"Call Mom"}
+      }]
+    },
+    "allowlist": null,
+    "limits": null
+  }
+}
+```
+
+At least one executable step is required when `compiled` is supplied. Omit
+`targetId` when Shell has bound the principal to one machine. The returned
+webhook URL is the provider destination; a configured signing secret is
+write-only on later reads.
+
+CLI example:
+
+```bash
+printf '%s\n' '{"name":"Weekday check","schedules":[{"cron":"0 9 * * 1-5","timezone":"America/Los_Angeles"}],"workflow":{"script":"Run the weekday check.","compiled":{"version":2,"steps":[{"id":"check","kind":"command","command":"my-check","cwd":"/absolute/project"}]}}}' \
+  | amalgm automations create --stdin
+```
+
+## list
+
+All fields are optional:
+
+```json
+{"targetId":"machine-id","enabled":true,"limit":20,"offset":0}
+```
+
+Use it to find candidates, then `get` the exact definition before mutation.
+
+## get
+
+```json
+{
+  "automation_id": "automation-id",
+  "include_runs": true,
+  "run_query": {"status":"completed","limit":20,"offset":0}
+}
+```
+
+`include_runs` and `run_query` are optional. `run_query.status` is one of
+`pending`, `sent`, `running`, `completed`, or `failed`.
+
+## update
+
+Updates are grouped so one call can change metadata and owned resources:
+
+```json
+{
+  "automation_id": "automation-id",
+  "patch": {
+    "targetId": "optional-new-target",
+    "name": "New name or null",
+    "description": "New description or null",
+    "enabled": true
+  },
+  "schedules": {
+    "create": [{"cron":"0 9 * * *","timezone":"UTC"}],
+    "update": [{"id":"schedule-id","patch":{"enabled":false}}],
+    "delete": ["old-schedule-id"]
+  },
+  "webhooks": {
+    "create": [{"source":"github","event":"push"}],
+    "update": [{"id":"webhook-id","patch":{"rotateUrl":true}}],
+    "delete": ["old-webhook-id"]
+  },
+  "workflow": {
+    "update": {
+      "name": "Updated workflow name",
+      "script": "Updated summary",
+      "compiled": {
+        "version": 2,
+        "steps": [{
+          "id": "check",
+          "kind": "command",
+          "command": "my-check",
+          "cwd": "/absolute/project"
+        }]
+      },
+      "allowlist": null,
+      "limits": null
+    }
+  }
+}
+```
+
+Every included patch must contain a real change. Workflow change is exactly one
+of `{ "create": ... }`, `{ "update": ... }`, or `{ "delete": true }`.
+Schedule and webhook changes may combine create/update/delete arrays. Preserve
+resource ids returned by `get`; ids are scoped to their automation.
+
+## delete
+
+```json
+{"automation_id":"automation-id"}
+```
+
+This deletes current configuration, triggers, and workflow. It does not delete
+historical runs.
+
+## run-now
+
+```json
+{
+  "automation_id": "automation-id",
+  "input": {"requestedBy":"user"},
+  "idempotency_key": "stable-key-for-this-logical-request"
+}
+```
+
+`input` may be any JSON value. Admission requires an enabled automation with an
+executable compiled workflow. The returned run starts as `pending`; follow it
+with `get` until terminal. Reusing the same key for the same logical request
+returns the same run rather than creating a duplicate.
+
+## Webhook completion
+
+Creating an Amalgm webhook trigger does not register it at GitHub or another
+provider. Configure the returned URL in that provider separately, use JSON
+content type, select only the requested events, and use the same optional
+signing secret on both sides. Rotating the URL invalidates the old bearer
+capability.