@amalgm/automations 0.3.1 → 0.3.2

package/README.md

@@ -46,6 +46,8 @@ 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 safely.
 
 ## Agent CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Amalgm's automation SDK: durable trigger admission and target-machine execution.",
   "license": "UNLICENSED",
   "repository": {

package/skills/amalgm-automations/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: amalgm-automations
+description: Operate complete Amalgm automations through the Automations MCP tools or the global `amalgm automations` CLI, including schedules, webhooks, Run Now, run history, native commands, scripts, and Amalgm actions.
+---
+
+# 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.
+
+## 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.
+
+For CLI use, first check `amalgm automations --help`. A signed-in, running
+Amalgm Shell supplies authentication through its loopback runtime. Never ask
+the user to copy a runtime token, DPoP proof, device key, or machine credential.
+If the runtime is unavailable, report that Shell must be signed in and running;
+do not fall back to an invented credential 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.
+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.
+
+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.
+
+## 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.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Amalgm Automations"
+  short_description: "Create and verify durable Amalgm automations"
+  default_prompt: "Use $amalgm-automations to create and verify an automation for me."

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.

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/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.