@amalgm/automations 0.3.1 → 0.4.0

package/skills/amalgm-automations/references/setup-and-support.md

@@ -0,0 +1,195 @@
+# Setup and support
+
+Read this when installing, signing in, repairing a connection, or helping with
+an error. Use Shell's commands for setup and Automations reads to verify access.
+The agent handles the commands; the person chooses their Google account and
+approves connecting their computer in the browser.
+
+## Start with the connection you have
+
+If Automations MCP already answers `list` with `{"limit":1}`, continue the task.
+Do not require a local CLI for a working remote MCP connection. If that remote
+connection requires authorization, use its actual sign-in/reconnect link. A
+cloud agent cannot repair the user's computer by installing Shell on its own
+temporary machine.
+
+For local CLI work, use the existing `amalgm` executable or the exact Shell
+launcher supplied by Amalgm's installer/app. The examples below use `amalgm`
+as shorthand for that executable. Keep the same installation and account
+throughout setup and verification.
+
+```bash
+amalgm --version
+amalgm --help
+amalgm automations --help
+amalgm automations list --input '{"limit":1}'
+```
+
+When the user has chosen an account, add `--user` with that actual email to
+Shell commands, including `amalgm automations ...`. An email selects a local
+account; it does not authenticate it. `targetId` selects an execution computer,
+not an account. Never substitute one for the other.
+
+A successful Automations response is a JSON `result` envelope; an empty list
+is valid. The six Automations commands use that envelope. Shell's `status`
+returns a different JSON shape; `login` and `run` report progress as text.
+
+## Install only when needed
+
+Check for an existing app-managed installation before adding another copy.
+If the desktop app already manages this computer, use its setup/connection
+flow. A missing PATH entry is not proof that Amalgm is uninstalled.
+
+On a fresh computer with Node.js and npm, the Shell package supplies the
+global command. Check the published package's requirements before installing:
+
+```bash
+node --version
+npm view @amalgm/shell version engines --json
+npm install --global @amalgm/shell
+amalgm --version
+amalgm automations --help
+```
+
+Do not install `@amalgm/automations` alone as a substitute for Shell: its direct
+CLI/MCP executables do not perform the user's Shell login. Do not change an
+existing app's exact runtime binding or install a second runner to fix a
+version mismatch. If the installed Shell lacks `automations`, report that
+version and use its supported update path; do not invent `amalgm update`.
+
+If Node/npm is unavailable or global installation is denied, use
+[Amalgm computer setup](https://amalgm.ai/setup). The person signs in with
+Google and the page supplies the current platform-specific install command.
+That installer includes a private Node runtime and a one-time setup code.
+Execute the command supplied by the trusted setup page when the user has
+authorized connecting this computer. Do not invent a code, run a code-less
+`install.sh`, or use sudo as an automatic workaround. Keep the code private
+to this setup session.
+
+The web installer places Shell under
+`~/.amalgm/runtime-packages/shell/<installed-version>/bin/amalgm` on macOS/Linux.
+If it is absent from PATH, use the exact launcher/version identified by the
+installer or app, not whichever version directory happens to sort last.
+
+## Sign in and connect the computer
+
+For a first login through the CLI:
+
+```bash
+amalgm login --no-open
+```
+
+Run it in a persistent terminal/process session. Show the **verification URL
+printed by that process** to the user as a clickable link; do not construct
+the URL yourself. Omit `--no-open` only when the command should open the browser
+on the same computer. The approval link and setup code are short-lived setup
+information, not material for logs or support emails.
+
+Tell the person: “Continue with Google, choose your Amalgm account, and approve
+connecting this computer. I'll check the connection and continue afterward.”
+Show the computer name when known. The browser owns sign-in and consent; do
+not ask for passwords, provider tokens, or a credit card. Existing accounts
+can use their existing supported sign-in method rather than creating a second
+account just to use Google.
+
+Keep that process alive while the person approves. Follow its progress until
+`AMALGM_READY` appears or it reports an error. `login` continues hosting the
+runtime after readiness; it is not expected to exit successfully. Do not kill
+it after approval or use `--exit-after-ready` for real setup.
+
+An already approved, unexpired code can be passed to
+`amalgm login --setup-code CODE` if the original waiting process ended. Use
+only the actual code from this setup attempt. If approval expired, finish the
+old attempt and start a fresh login. If the person cancels, stop that attempt;
+do not reopen approval until they choose to continue.
+
+## Reuse or resume a registered computer
+
+Once the account email is known, inspect it explicitly. Replace the example
+email below with the user's actual selected account:
+
+```bash
+amalgm status --user person@example.com
+```
+
+| Observed state | Next action |
+| --- | --- |
+| `registration: "ready"`, `running: true` | Reuse this runtime; verify Automations access. |
+| `registration: "ready"`, `running: false` | Run `amalgm run --user person@example.com` in a persistent session, then verify. |
+| `registration: "absent"` or `"incomplete"` | Complete the supported login/setup flow for this account; preserve existing registration files. |
+| Shell requests `--user` or lists several accounts | Ask which account to use if it is not already established. Supply that email consistently. |
+| Status fails | Diagnose the actual error; a failed read is not proof that registration is absent. |
+
+After login or resume, require both ready/running status and a successful read:
+
+```bash
+amalgm automations list --user person@example.com --input '{"limit":1}'
+```
+
+Then return to the user's original automation request. This proves connection
+and access, not that a future workflow ran or that every executable is installed.
+MCP results can independently prove hosted access, but do not prove the selected
+execution computer is online.
+
+Use an existing app/installer-managed background runtime when possible. A
+foreground `login`/`run` process must remain alive for local execution; do not
+promise it survives terminal closure, logout, or reboot without evidence. If
+the agent's process sessions cannot persist, use the app/setup-managed path or
+explain the remaining requirement. An offline target leaves admitted runs
+pending; it does not erase their history.
+
+## Diagnose the failing boundary
+
+Read the error's code, message, and status together; some Shell failures are
+wrapped as `internal`. Keep automation and run ids when available. Try the
+appropriate repair and verify again. If the same failure persists with no new
+evidence, explain it and offer support rather than looping through login,
+reinstallation, or repeated writes.
+
+| Failure | What to do |
+| --- | --- |
+| `runtime_unavailable`, connection refused, or Shell says it is not running | Inspect the selected account's status and use the resume/setup decision above. A standalone adapter asking for environment credentials should be replaced by the global `amalgm automations` path. |
+| `runtime_unauthorized` | Retry the read once through the public Shell command, which obtains the current local connection. If it still fails, keep the error for support; never extract or replace tokens manually. |
+| `runtime_transport` or `runtime_protocol` | Check local readiness, connectivity, and the installed version. A timeout or service outage is not evidence that the user needs a new account. |
+| Wrong account, `forbidden`, or a target authorization error | Verify the chosen account and computer. Do not change ownership, guess another target, or treat every 403 as an expired login. |
+| Missing/corrupt device key or an explicit recovery-required error | Explain key recovery and use `amalgm auth recover --user person@example.com` only when the user chooses recovery. It requires its own browser approval. Never delete identity files or silently re-register. After recovery, inspect status and resume if needed. |
+| HTTP 429 or a reported rate limit | Honor a supplied retry delay/reset time and reduce request frequency. Limits are per minute/hour; do not invent numeric allowances or a reset time. If no delay is supplied, back off conservatively with a bounded retry, then report the unresolved limit. Never switch accounts to bypass it. |
+| An installed native agent needs login, or its model/provider rejects work | Use that program/service's own supported login. Amalgm Google sign-in does not sign into Codex, Claude, or other providers. Do not add Amalgm credits as a guessed fix. |
+| Missing executable, failed step, or invalid workflow | Read [workflow diagnoses](workflow-plans.md#common-boundary-diagnoses); repair the actual step/configuration without replacing the automation to hide the failure. |
+
+For a failed mutation, inspect existing state before retrying. Reuse the same
+Run Now input and idempotency key after an uncertain response. Preserve a
+returned disabled draft id. A retry must not turn one requested automation or
+run into several.
+
+## Get support
+
+Support is **Aayush, aayush@amalgm.ai**:
+[Email Aayush](mailto:aayush@amalgm.ai?subject=Amalgm%20Automations%20help).
+Offer this as soon as the user asks, or when the supported repair does not
+resolve their problem. They do not need to complete a troubleshooting checklist
+to contact a person.
+
+Prepare a short email when helpful:
+
+```text
+To: aayush@amalgm.ai
+Subject: Amalgm Automations — <short problem>
+
+I was trying to: <intended result>
+What happened: <failure and approximate time, including timezone>
+Setup: <OS, agent/client, and Amalgm version if available>
+Error: <code/status and a short redacted message>
+Automation/run: <ids or viewing links, if available>
+Already tried: <relevant checks or repair>
+```
+
+Use only relevant evidence. Do not attach raw runtime logs, browser cookies,
+private auth files, setup links/codes, webhook URLs/signing secrets, or the
+user's code, prompts, file paths, and workflow output without reviewing and
+redacting them. Status output can contain private local paths; summarize its
+registration/running fields instead of copying the entire object.
+
+Send through an available email tool only if the user has explicitly authorized
+the email; otherwise provide the draft and mail link. Do not invent a support
+ticket, response-time promise, or claim that an email was sent.

package/skills/amalgm-automations/references/workflow-plans.md

@@ -0,0 +1,152 @@
+# Workflow plans
+
+The compiled plan is an immutable, ordered snapshot when a run is admitted.
+Step ids must be unique and the plan must contain 1–100 steps.
+
+## Step forms
+
+Version 1 accepts action steps only:
+
+```json
+{
+  "version": 1,
+  "steps": [{
+    "id": "notify",
+    "actionId": "channels.notify_user",
+    "input": {"title":"Reminder","message":"Call Mom"}
+  }]
+}
+```
+
+Version 2 accepts any ordered mix of these three forms:
+
+```text
+Amalgm action
+{ id, actionId, input }
+
+Native command
+{ id, kind:"command", command, args?, cwd?, env?, stdin?,
+  timeoutMs?, maxOutputBytes? }
+
+Code script
+{ id, kind:"script", runtime:"shell"|"node"|"python", source,
+  args?, cwd?, env?, stdin?, timeoutMs?, maxOutputBytes? }
+```
+
+`id`, `actionId`, `command`, every `args` element, environment keys and values,
+and `runtime` are strings. `timeoutMs` and `maxOutputBytes` are positive
+integers. `cwd` is optional but must be absolute when present.
+
+## Amalgm actions and agents
+
+Action steps run through the selected machine's installed Amalgm Tools/action
+catalog. Discover an action before using it. Do not derive action ids from MCP
+tool names.
+
+The Amalgm-agent action is distinct from a native CLI agent:
+
+```json
+{
+  "id": "review-with-amalgm-agent",
+  "actionId": "chat.chat_agent_run",
+  "input": {
+    "agent_installation_id": "configured-installation-id",
+    "message": "Review this occurrence.",
+    "context": {"$runInput":true}
+  }
+}
+```
+
+The installation must exist and declare a usable model/provider binding. Do
+not guess an installation id from an adapter name such as `codex`.
+
+## Native CLI agents
+
+Use a command step for the user's independently installed CLI:
+
+```json
+{
+  "id": "native-codex-review",
+  "kind": "command",
+  "command": "codex",
+  "args": ["exec", "Review this repository and write REVIEW.md"],
+  "cwd": "/Users/me/src/project",
+  "timeoutMs": 1800000,
+  "maxOutputBytes": 1048576
+}
+```
+
+The executable is resolved from the target machine's PATH and uses its own
+user-level login. Args are passed directly with `shell:false`; `$HOME`, pipes,
+redirection, globbing, and quoting syntax are literal arguments. If shell
+syntax is intended, choose the script lane explicitly.
+
+Equivalent installed programs such as `claude -p ...` or `opencode ...` use
+the same command form. Their accepted args and authentication belong to those
+programs, not Automations.
+
+## Scripts
+
+Scripts persist source in the workflow and execute through a temporary file on
+the selected machine. The temporary file is removed after execution.
+
+```json
+{
+  "id": "process-event",
+  "kind": "script",
+  "runtime": "node",
+  "source": "let s=''; process.stdin.on('data', c => s += c).on('end', () => console.log(JSON.parse(s)));",
+  "cwd": "/absolute/project",
+  "stdin": {"$runInput":true},
+  "env": {"MODE":"automation"},
+  "timeoutMs": 30000,
+  "maxOutputBytes": 262144
+}
+```
+
+Use `runtime:"shell"` for POSIX shell semantics on Unix and PowerShell file
+execution on Windows. Use `node` or `python` for explicit code in those
+runtimes. Account for target-machine portability when selecting a runtime or
+absolute path.
+
+## Run input
+
+The exact singleton object below is the only template marker:
+
+```json
+{"$runInput":true}
+```
+
+It resolves recursively inside action `input`. In process steps it may be used
+as `stdin`; strings are passed verbatim and other JSON values are serialized
+with a trailing newline. Trigger payloads are never ambient.
+
+## Execution and retries
+
+Each step is recorded as running before its effect and committed as completed
+before the next step begins. Completed steps are skipped after reconnect.
+
+Every run-step pair receives the stable key `<run-id>:<step-id>`. Process steps
+receive it as `AMALGM_AUTOMATION_IDEMPOTENCY_KEY`. Shell's private runtime,
+tunnel, device, and machine credentials are stripped from child environments.
+
+An uncertain machine crash can repeat the current effect. Amalgm actions can
+deduplicate the step key; an arbitrary command or script is at-least-once and
+must durably deduplicate that environment value when exactly-once effects are
+required.
+
+Process output records exit code, signal, stdout, stderr, and whether capture
+was truncated. Timeouts, cancellation, and output bounds are enforced on the
+machine. The durable journal compacts oversized results rather than allowing
+large output to strand the run update.
+
+## Common boundary diagnoses
+
+- `process_execution_unavailable`: selected machine host lacks process support.
+- Spawn/not-found error: executable or runtime is absent from that machine PATH.
+- Nonzero exit: inspect bounded stdout/stderr; the automation correctly failed.
+- Timeout: adjust only when the intended command legitimately needs longer.
+- `Installed agent has no model`: select or configure an actual Amalgm agent
+  installation with a model; this is not a native CLI-auth failure.
+- Action-specific HTTP/authorization error: verify that action's owning service
+  and input contract without changing Run Now semantics.

package/supabase/migrations/20260904020000_machine_run_notifications.sql

@@ -0,0 +1,52 @@
+-- Commit the run and its private wakeup together. Every Fly host observes the
+-- same change; local processes never subscribe with Supabase credentials.
+CREATE OR REPLACE FUNCTION public.notify_amalgm_machine_run()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+BEGIN
+  IF TG_OP = 'UPDATE' AND
+    (OLD.status, OLD.retry_at, OLD.lease_expires_at) IS NOT DISTINCT FROM
+    (NEW.status, NEW.retry_at, NEW.lease_expires_at) THEN
+    RETURN NEW;
+  END IF;
+  PERFORM realtime.send(
+    jsonb_build_object('userId', NEW.user_id, 'targetId', NEW.target_id),
+    'changed', 'amalgm:automations:runs', true
+  );
+  RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.notify_amalgm_machine_run() FROM PUBLIC;
+CREATE TRIGGER amalgm_machine_run_notification
+AFTER INSERT OR UPDATE ON public.amalgm_automation_runs
+FOR EACH ROW EXECUTE FUNCTION public.notify_amalgm_machine_run();
+
+-- Remain private even if a different product permits broad authenticated
+-- Broadcast access. service_role is the only subscriber and bypasses RLS.
+CREATE POLICY amalgm_run_notifications_service_only
+ON realtime.messages AS RESTRICTIVE FOR ALL TO PUBLIC
+USING (topic <> 'amalgm:automations:runs')
+WITH CHECK (topic <> 'amalgm:automations:runs');
+
+-- Use the database clock, exactly as claim_amalgm_machine_runs does. The host
+-- sleeps until this deadline; no deadline means no work-check timer at all.
+CREATE OR REPLACE FUNCTION public.amalgm_machine_wake_delay(p_user_id uuid, p_target_id text)
+RETURNS double precision
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT CASE WHEN count(*) = 0 THEN NULL ELSE
+    greatest(0, ceil(extract(epoch FROM (min(CASE WHEN status = 'pending'
+      THEN coalesce(retry_at, now()) ELSE coalesce(lease_expires_at, now()) END) - now())) * 1000))
+  END
+  FROM public.amalgm_automation_runs
+  WHERE user_id = p_user_id AND target_id = p_target_id
+    AND status IN ('pending', 'sent', 'running');
+$$;
+REVOKE ALL ON FUNCTION public.amalgm_machine_wake_delay(uuid, text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION public.amalgm_machine_wake_delay(uuid, text) TO service_role;

package/supabase/migrations/20260904030000_machine_notification_permissions.sql

@@ -0,0 +1,4 @@
+-- Supabase can grant EXECUTE directly through schema default privileges;
+-- revoking PUBLIC alone does not remove those explicit grants.
+REVOKE ALL ON FUNCTION public.notify_amalgm_machine_run() FROM anon, authenticated;
+REVOKE ALL ON FUNCTION public.amalgm_machine_wake_delay(uuid, text) FROM anon, authenticated;

package/skills/automations/SKILL.md

@@ -1,141 +0,0 @@
----
-name: automations
-description: Create, inspect, change, delete, or manually run complete Amalgm automation definitions and inspect their run history through the Automations MCP tools.
----
-
-# Amalgm Automations
-
-Use the Automations tools for scheduled or webhook-driven work. The tools are
-the agent adapter over the same hosted SDK used by the UI.
-
-When MCP is unavailable but the authenticated Amalgm Shell CLI is available,
-use the command with the matching suffix (`create`, `list`, `get`, `update`,
-`delete`, or `run-now`). Pass the exact MCP input object as JSON, preferably on
-stdin when it contains a provider secret:
-
-```bash
-printf '%s\n' '{"name":"Call Mom","schedules":[{"cron":"* * * * *","timezone":"America/Los_Angeles","maxOccurrences":10}],"workflow":{"script":"Notify me to call Mom.","compiled":{"version":1,"steps":[{"id":"notify","actionId":"channels.notify_user","input":{"title":"Reminder","message":"Call Mom"}}]}}}' \
-  | amalgm automations create --stdin
-```
-
-The CLI returns `{ "result": ... }` on stdout or a structured `error` object
-on stderr with a nonzero exit. It has no separate low-level trigger or workflow
-commands; complete definitions and grouped changes use the same task-level
-surface as MCP.
-
-The CLI is global. Its current directory does not scope or modify the
-automation. Process location belongs in an absolute workflow-step `cwd`; when
-it is omitted, Shell uses the selected machine user's OS home.
-
-## Choose the execution lane deliberately
-
-Use exactly one of these shapes for each compiled workflow step:
-
-Version 1 remains action-only. Use plan version 2 for every workflow containing
-a native command or code script; version 2 may mix all three lanes.
-
-- **Amalgm action** — `{ "id", "actionId", "input" }`. Use this for Amalgm
-  tools, Channels, or the Amalgm agent path. `chat.chat_agent_run` is an Amalgm
-  agent, not the user's native CLI agent.
-- **Native command** — `{ "id", "kind":"command", "command", "args"?,
-  "cwd"?, "env"?, "stdin"?, "timeoutMs"?, "maxOutputBytes"? }`. Use this for
-  installed executables such as `codex exec`, `claude -p`, `opencode`, or a
-  script file. Args are literal argv and never pass through a shell.
-- **Code script** — `{ "id", "kind":"script", "runtime":"shell"|"node"|
-  "python", "source", "args"?, "cwd"?, "env"?, "stdin"?, "timeoutMs"?,
-  "maxOutputBytes"? }`. Use this only when inline code or shell semantics are
-  desired explicitly.
-
-For a native Codex run on the selected machine:
-
-```json
-{
-  "version": 2,
-  "steps": [{
-    "id": "native-review",
-    "kind": "command",
-    "command": "codex",
-    "args": ["exec", "Review this repository and write REVIEW.md"],
-    "cwd": "/absolute/path/to/repository",
-    "timeoutMs": 1800000
-  }]
-}
-```
-
-Installed CLI authentication comes from that CLI's own user setup on the
-selected machine. Never put Shell runtime, tunnel, or machine credentials in a
-workflow. `env` is persisted ordinary configuration, not a secret store.
-Process results and bounded stdout/stderr appear in run history. A native
-process may repeat after an uncertain machine crash; it receives
-`AMALGM_AUTOMATION_IDEMPOTENCY_KEY` for durable deduplication when needed.
-
-## Create a scheduled notification
-
-For a request such as “remind me to call my mom every minute for the next ten
-minutes,” make one `amalgm_automations_create` call containing the complete
-definition. Include a readable workflow summary and this compiled plan:
-
-```json
-{
-  "version": 1,
-  "steps": [
-    {
-      "id": "notify",
-      "actionId": "channels.notify_user",
-      "input": { "title": "Reminder", "message": "Call Mom" }
-    }
-  ]
-}
-```
-
-Include one schedule with cron `* * * * *`, the user's timezone, and
-`maxOccurrences: 10`. Omit `targetId` in a machine-bound session; never guess
-an opaque target id.
-
-The tool stages multi-resource configuration disabled and enables it only after
-setup succeeds. If setup fails, report the returned disabled draft id. Never
-replace a bounded occurrence count with an unbounded schedule plus a promise to
-clean it up later.
-
-## Read and change
-
-Use `amalgm_automations_list` or `amalgm_automations_get` before changing an
-existing automation. Use `amalgm_automations_update` for grouped metadata,
-schedule, webhook, or workflow changes, and `amalgm_automations_delete` only
-after identifying the exact automation. Schedule and webhook triggers remain
-distinct resources inside the definition. A workflow is zero-or-one per
-automation. Run history is read-only, requested through `get`, and remains
-after configuration deletion.
-
-Use `amalgm_automations_run_now` when the user wants an enabled automation to
-run immediately. Supply `idempotency_key` when a caller may retry the same
-request. The result is a durable `pending` run, not proof that its selected
-machine has finished it; use `amalgm_automations_get` with run history when the
-user asks for the outcome.
-
-Amalgm action discovery belongs to the Tools product. Native command discovery
-belongs to the selected machine's PATH and installed user environment.
-
-For webhook-driven work, pass the admitted provider payload into an action or
-process by placing the exact value `{ "$runInput": true }` at the desired point
-in action `input` or process `stdin`. For example, an agent-review action can
-use a static `message` and set `context` to `{ "$runInput": true }`. Never paste
-an example delivery into the workflow: every admitted run must use its own
-durable input.
-
-`pending` means a run is durable and waiting for its selected machine. `sent`
-or `running` means that machine holds a lease. `completed` and `failed` are
-terminal. Do not infer delivery from the schedule alone; inspect runs when the
-user asks whether it actually happened.
-
-Each webhook trigger returns one copyable `webhookUrl`; use that URL as the
-provider destination. A separate provider signing secret is optional and
-write-only. Never echo, log, or place either credential in a workflow. Rotate
-the URL when its bearer capability may have been exposed.
-
-For GitHub, register the returned URL as a repository webhook with JSON content
-type and select only the requested events (normally `push`). If a provider
-secret was configured on the trigger, use the same value as GitHub's webhook
-secret. Creating the Amalgm trigger does not silently mutate GitHub; finish the
-provider registration in the authenticated GitHub surface available to the
-agent, then report both sides as configured.