@amalgm/automations 0.3.0 → 0.3.2

package/AXIOMS.md

@@ -41,7 +41,9 @@
     state; it never owns a second automation-definition API.
 15. Admitting a run atomically verifies the current enabled configuration,
     stores a secret-free snapshot, and, for a schedule, advances exactly the
-    firing instant that was claimed.
+    firing instant that was claimed. Manual, schedule, and webhook admission
+    derive executability from the same declared set of supported workflow
+    versions.
 16. Legacy local automation storage is not a compatibility authority. Engine
     is deprecated read-only evidence; active callers use this SDK and its
     standalone service, and no old store may run beside them.
@@ -123,3 +125,7 @@
     credential, tunnel credential, or a standalone Automations authorization
     value. Native tool authentication comes from that tool's own user-level
     setup, not from Amalgm's private transport authority.
+43. The durable step journal has one SDK-owned serialized size bound. Oversized
+    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.

package/PURPOSE.md

@@ -58,7 +58,9 @@ the selected machine host supplies every effectful capability.
 
 The machine records a step as running before invoking it and records its output
 before advancing. Reconnect resumes at the first step that is not already
-complete. A transient network failure releases the same run back to the queue
+complete. One serialized journal bound applies to action and process output;
+oversized results retain their byte count and a bounded preview, so evidence
+cannot make its own durable update impossible. A transient network failure releases the same run back to the queue
 with a bounded future retry time; a configuration, authorization, or execution
 error fails it. Every execution capability receives a stable per-step
 idempotency key. Amalgm actions can use it to make an uncertain acknowledgement

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
 
@@ -169,7 +171,10 @@ newline. Either action `input` or process `stdin` may contain the exact template
 Shell injects action and process capabilities into the shared executor. Process
 results record exit code, signal, stdout, stderr, and truncation in run history;
 timeouts, cancellation, and output limits are enforced on the selected
-machine. Children inherit the user's ordinary machine environment so installed
+machine. The durable journal begins compacting after 1 MiB and stores oversized
+results as an explicit original byte count plus a bounded JSON preview, keeping
+every run update within the service transport bound. Children inherit the
+user's ordinary machine environment so installed
 CLI auth continues to work, but never inherit Shell's private runtime, tunnel,
 or machine credentials. Values in workflow `env` are persisted non-secret
 configuration.

package/dist/src/cli/shell-runtime.js

@@ -1,4 +1,5 @@
 import { automationCommandDefinition, } from '../command-surface.js';
+import { MAX_CLI_RUNTIME_RESPONSE_BYTES } from '../execution-limits.js';
 import { AutomationError, ValidationError } from '../errors.js';
 export function createShellAutomationCommands(options) {
     const endpoint = shellAutomationEndpoint(options.runtimeUrl);
@@ -68,21 +69,49 @@ export function shellAutomationEndpoint(runtimeUrl) {
 async function jsonResponse(response) {
     let bytes;
     try {
-        bytes = new Uint8Array(await response.arrayBuffer());
+        bytes = await boundedResponse(response, MAX_CLI_RUNTIME_RESPONSE_BYTES);
     }
     catch (error) {
+        if (error instanceof AutomationError)
+            throw error;
         throw new AutomationError('runtime_transport', `Cannot read Amalgm Shell runtime response: ${message(error)}`);
     }
-    if (bytes.byteLength > 2 * 1024 * 1024) {
-        throw new AutomationError('runtime_protocol', 'Amalgm Shell runtime response is too large');
-    }
     try {
-        return JSON.parse(Buffer.from(bytes).toString('utf8'));
+        return JSON.parse(bytes.toString('utf8'));
     }
     catch {
         return null;
     }
 }
+async function boundedResponse(response, maximumBytes) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maximumBytes) {
+        throw new AutomationError('runtime_protocol', 'Amalgm Shell runtime response is too large');
+    }
+    if (!response.body)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let size = 0;
+    const reader = response.body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = Buffer.from(value);
+            size += chunk.byteLength;
+            if (size > maximumBytes) {
+                await reader.cancel();
+                throw new AutomationError('runtime_protocol', 'Amalgm Shell runtime response is too large');
+            }
+            chunks.push(chunk);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, size);
+}
 function toolResult(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new AutomationError('runtime_protocol', 'Automations MCP returned an invalid tool result');

package/dist/src/execution-limits.d.ts

@@ -0,0 +1,6 @@
+/** Start compacting step output before metadata can approach the service body bound. */
+export declare const RUN_JOURNAL_OUTPUT_BUDGET_BYTES: number;
+/** One persisted journal, including step metadata, must remain below 1.5 MiB. */
+export declare const MAX_RUN_JOURNAL_BYTES: number;
+/** A get response can contain the default page of twenty maximum-sized journals. */
+export declare const MAX_CLI_RUNTIME_RESPONSE_BYTES: number;

package/dist/src/execution-limits.js

@@ -0,0 +1,6 @@
+/** Start compacting step output before metadata can approach the service body bound. */
+export const RUN_JOURNAL_OUTPUT_BUDGET_BYTES = 1024 * 1024;
+/** One persisted journal, including step metadata, must remain below 1.5 MiB. */
+export const MAX_RUN_JOURNAL_BYTES = 1536 * 1024;
+/** A get response can contain the default page of twenty maximum-sized journals. */
+export const MAX_CLI_RUNTIME_RESPONSE_BYTES = 32 * 1024 * 1024;

package/dist/src/index.d.ts

@@ -5,6 +5,7 @@ export { createAutomationApi, type AuthenticateAutomationRequest, type Automatio
 export { automationCliHelp, createShellAutomationCommands, runAutomationCli, runAutomationCliMain, shellAutomationEndpoint, type AutomationCliIo, type AutomationCliMainOptions, type ShellAutomationCommandOptions, } from './cli.js';
 export { automationCommandDefinition, automationCommandDefinitions, createAutomationCommands, type AutomationCommandAnnotations, type AutomationCommandDefinition, type AutomationCommandName, type AutomationCommands, } from './command-surface.js';
 export { automationFailure, type AutomationFailureEnvelope } from './command-result.js';
+export { MAX_CLI_RUNTIME_RESPONSE_BYTES, MAX_RUN_JOURNAL_BYTES, RUN_JOURNAL_OUTPUT_BUDGET_BYTES, } from './execution-limits.js';
 export { createAutomationMcpServer } from './mcp.js';
 export { createAutomationToolSurface, type AutomationToolSurface, type AutomationView, type CreateAutomationDefinition, type UpdateAutomationDefinition, type WorkflowChange, } from './tool-surface.js';
 export { SupabaseAutomationCrudRepository, type SupabaseRpcClient } from './supabase-crud.js';

package/dist/src/index.js

@@ -12,6 +12,7 @@ export { createAutomationApi } from './http.js';
 export { automationCliHelp, createShellAutomationCommands, runAutomationCli, runAutomationCliMain, shellAutomationEndpoint, } from './cli.js';
 export { automationCommandDefinition, automationCommandDefinitions, createAutomationCommands, } from './command-surface.js';
 export { automationFailure } from './command-result.js';
+export { MAX_CLI_RUNTIME_RESPONSE_BYTES, MAX_RUN_JOURNAL_BYTES, RUN_JOURNAL_OUTPUT_BUDGET_BYTES, } from './execution-limits.js';
 export { createAutomationMcpServer } from './mcp.js';
 export { createAutomationToolSurface, } from './tool-surface.js';
 export { SupabaseAutomationCrudRepository } from './supabase-crud.js';

package/dist/src/mcp.js

@@ -4,7 +4,14 @@ import { automationCommandDefinitions, createAutomationCommands, } from './comma
 import { automationFailure } from './command-result.js';
 import { createAutomationToolSurface } from './tool-surface.js';
 export { createAutomationToolSurface };
-const resultSchema = { result: z.unknown() };
+const resultSchema = {
+    result: z.unknown().optional(),
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+        status: z.number().optional(),
+    }).strict().optional(),
+};
 export function createAutomationMcpServer(sdk) {
     const server = new McpServer({ name: 'amalgm-automations-mcp-server', version: '0.1.0' });
     const commands = createAutomationCommands(sdk);

package/dist/src/run-journal.js

@@ -1,9 +1,13 @@
+import { MAX_RUN_JOURNAL_BYTES, RUN_JOURNAL_OUTPUT_BUDGET_BYTES, } from './execution-limits.js';
+const MAX_OUTPUT_PREVIEW_CHARACTERS = 64 * 1024;
 export function emptyJournal() {
     return { version: 1, steps: [] };
 }
 export function runJournal(value, plan) {
     if (value === undefined)
         return emptyJournal();
+    if (jsonBytes(value) > MAX_RUN_JOURNAL_BYTES)
+        throw new Error('Run step journal exceeds its persistence bound');
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Run step journal is invalid');
     const source = value;
@@ -34,12 +38,63 @@ export function putStep(journal, step) {
         steps.push(step);
     else
         steps[index] = step;
-    return { version: 1, steps };
+    let candidate = { version: 1, steps };
+    if (jsonBytes(candidate) > RUN_JOURNAL_OUTPUT_BUDGET_BYTES && step.output !== undefined) {
+        const compacted = { ...step, output: compactOutput(step.output) };
+        if (index === -1)
+            steps[steps.length - 1] = compacted;
+        else
+            steps[index] = compacted;
+        candidate = { version: 1, steps };
+    }
+    if (jsonBytes(candidate) > MAX_RUN_JOURNAL_BYTES) {
+        candidate = removeStoredPreviews(candidate);
+    }
+    if (jsonBytes(candidate) > MAX_RUN_JOURNAL_BYTES) {
+        throw new Error('Run step journal exceeds its persistence bound');
+    }
+    return candidate;
 }
 /** Journals are constructed from JSON fields only; this is the persistence boundary. */
 export function journalJson(journal) {
+    if (jsonBytes(journal) > MAX_RUN_JOURNAL_BYTES)
+        throw new Error('Run step journal exceeds its persistence bound');
     return journal;
 }
+function compactOutput(output) {
+    const serialized = json(output);
+    return {
+        $amalgmTruncated: true,
+        originalBytes: Buffer.byteLength(serialized),
+        jsonPreview: serialized.slice(0, MAX_OUTPUT_PREVIEW_CHARACTERS),
+    };
+}
+function removeStoredPreviews(journal) {
+    return {
+        version: 1,
+        steps: journal.steps.map((step) => {
+            if (!isCompactedOutput(step.output))
+                return step;
+            const { jsonPreview: _preview, ...output } = step.output;
+            return { ...step, output };
+        }),
+    };
+}
+function isCompactedOutput(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const item = value;
+    return item.$amalgmTruncated === true && typeof item.jsonPreview === 'string';
+}
+function jsonBytes(value) {
+    return Buffer.byteLength(json(value));
+}
+function json(value) {
+    const serialized = JSON.stringify(value);
+    if (typeof serialized !== 'string')
+        throw new Error('Run step output must be JSON');
+    return serialized;
+}
 function runStep(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Run step is invalid');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.3.0",
+  "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/supabase/migrations/20260904010000_typed_workflow_admission.sql

@@ -0,0 +1,272 @@
+-- Every delivery path admits the same declared workflow versions. The SDK owns
+-- shape validation; this transaction-bound predicate prevents incomplete or
+-- unsupported definitions from entering the durable execution ledger.
+
+CREATE OR REPLACE FUNCTION public.amalgm_workflow_is_executable(p_compiled jsonb)
+RETURNS boolean
+LANGUAGE sql
+IMMUTABLE
+SET search_path = public
+AS $$
+  SELECT jsonb_typeof(p_compiled) = 'object'
+    AND p_compiled->>'version' IN ('1', '2')
+    AND jsonb_typeof(p_compiled->'steps') = 'array'
+    AND jsonb_array_length(
+      CASE WHEN jsonb_typeof(p_compiled->'steps') = 'array'
+        THEN p_compiled->'steps' ELSE '[]'::jsonb END
+    ) BETWEEN 1 AND 100;
+$$;
+
+CREATE OR REPLACE FUNCTION public.list_amalgm_event_triggers(p_user_id uuid, p_target_id text)
+RETURNS TABLE (
+  user_id uuid,
+  automation_id text,
+  trigger_id text,
+  target_id text,
+  source text,
+  event text,
+  secret text
+)
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT t.user_id, t.automation_id, t.id, a.target_id, t.source, t.event, t.secret
+  FROM public.amalgm_automation_triggers t
+  JOIN public.amalgm_automations a
+    ON a.user_id = t.user_id AND a.id = t.automation_id
+  JOIN public.amalgm_automation_workflows w
+    ON w.user_id = a.user_id AND w.automation_id = a.id
+  WHERE t.kind = 'webhook' AND t.user_id = p_user_id
+    AND a.target_id = p_target_id AND t.enabled AND a.enabled
+    AND public.amalgm_workflow_is_executable(w.compiled);
+$$;
+
+CREATE OR REPLACE FUNCTION public.list_due_amalgm_crons(p_now timestamptz)
+RETURNS TABLE (
+  user_id uuid,
+  automation_id text,
+  trigger_id text,
+  target_id text,
+  cron text,
+  timezone text,
+  next_run_at timestamptz,
+  remaining_occurrences integer
+)
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT t.user_id, t.automation_id, t.id, a.target_id,
+    t.cron, t.timezone, t.next_run_at, t.remaining_occurrences
+  FROM public.amalgm_automation_triggers t
+  JOIN public.amalgm_automations a
+    ON a.user_id = t.user_id AND a.id = t.automation_id
+  JOIN public.amalgm_automation_workflows w
+    ON w.user_id = a.user_id AND w.automation_id = a.id
+  WHERE t.kind = 'schedule' AND t.next_run_at <= p_now
+    AND (t.remaining_occurrences IS NULL OR t.remaining_occurrences > 0)
+    AND t.enabled AND a.enabled
+    AND public.amalgm_workflow_is_executable(w.compiled)
+  ORDER BY t.next_run_at, t.user_id, t.automation_id, t.id;
+$$;
+
+CREATE OR REPLACE FUNCTION public.resolve_amalgm_webhook(p_endpoint_id text)
+RETURNS TABLE (
+  user_id uuid,
+  automation_id text,
+  trigger_id text,
+  target_id text,
+  endpoint_id text,
+  source text,
+  event text,
+  secret text
+)
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT t.user_id, t.automation_id, t.id, a.target_id,
+    t.endpoint_id, t.source, t.event, t.secret
+  FROM public.amalgm_automation_triggers t
+  JOIN public.amalgm_automations a
+    ON a.user_id = t.user_id AND a.id = t.automation_id
+  JOIN public.amalgm_automation_workflows w
+    ON w.user_id = a.user_id AND w.automation_id = a.id
+  WHERE t.kind = 'webhook' AND t.endpoint_id = p_endpoint_id
+    AND t.enabled AND a.enabled
+    AND public.amalgm_workflow_is_executable(w.compiled);
+$$;
+
+CREATE OR REPLACE FUNCTION public.enqueue_amalgm_run(
+  p_kind text,
+  p_user_id uuid,
+  p_automation_id text,
+  p_trigger_id text,
+  p_target_id text,
+  p_endpoint_id text,
+  p_delivery_key text,
+  p_expected_next_run_at timestamptz,
+  p_next_run_at timestamptz,
+  p_input jsonb,
+  p_now timestamptz
+) RETURNS SETOF public.amalgm_automation_runs
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_inserted integer := 0;
+BEGIN
+  IF p_kind = 'cron' THEN
+    IF p_endpoint_id IS NOT NULL OR p_delivery_key IS NOT NULL THEN
+      RAISE EXCEPTION 'Schedule admission cannot carry webhook identity';
+    END IF;
+    PERFORM 1
+    FROM public.amalgm_automation_triggers t
+    JOIN public.amalgm_automations a
+      ON a.user_id = t.user_id AND a.id = t.automation_id
+    WHERE t.user_id = p_user_id AND t.automation_id = p_automation_id
+      AND t.id = p_trigger_id AND a.target_id = p_target_id
+      AND t.kind = 'schedule' AND t.next_run_at = p_expected_next_run_at
+      AND (t.remaining_occurrences IS NULL OR t.remaining_occurrences > 0)
+      AND t.enabled AND a.enabled
+    FOR UPDATE OF t;
+  ELSIF p_kind = 'event' THEN
+    IF p_endpoint_id IS NULL THEN RAISE EXCEPTION 'Webhook endpoint is required'; END IF;
+    PERFORM 1
+    FROM public.amalgm_automation_triggers t
+    JOIN public.amalgm_automations a
+      ON a.user_id = t.user_id AND a.id = t.automation_id
+    WHERE t.user_id = p_user_id AND t.automation_id = p_automation_id
+      AND t.id = p_trigger_id AND a.target_id = p_target_id
+      AND t.kind = 'webhook' AND t.endpoint_id = p_endpoint_id
+      AND t.enabled AND a.enabled;
+  ELSE
+    RAISE EXCEPTION 'Invalid automation trigger kind';
+  END IF;
+  IF NOT FOUND THEN RETURN; END IF;
+
+  RETURN QUERY
+  INSERT INTO public.amalgm_automation_runs (
+    user_id, target_id, automation_id, trigger_id, workflow_id,
+    automation_payload, input, status, delivery_key, created_at
+  )
+  SELECT a.user_id, a.target_id, a.id, t.id, w.id,
+    jsonb_strip_nulls(jsonb_build_object(
+      'id', a.id, 'targetId', a.target_id, 'name', a.name,
+      'description', a.description, 'enabled', a.enabled,
+      'trigger', jsonb_strip_nulls(jsonb_build_object(
+        'id', t.id,
+        'kind', CASE WHEN t.kind = 'schedule' THEN 'cron' ELSE 'event' END,
+        'enabled', t.enabled, 'cron', t.cron, 'timezone', t.timezone,
+        'source', t.source, 'event', t.event
+      )),
+      'workflow', jsonb_strip_nulls(jsonb_build_object(
+        'id', w.id, 'name', w.name, 'script', w.script,
+        'compiled', w.compiled, 'allowlist', w.allowlist, 'limits', w.limits
+      ))
+    )),
+    p_input, 'pending', p_delivery_key, p_now
+  FROM public.amalgm_automations a
+  JOIN public.amalgm_automation_triggers t
+    ON t.user_id = a.user_id AND t.automation_id = a.id
+  JOIN public.amalgm_automation_workflows w
+    ON w.user_id = a.user_id AND w.automation_id = a.id
+  WHERE a.user_id = p_user_id AND a.id = p_automation_id AND t.id = p_trigger_id
+    AND a.target_id = p_target_id AND t.enabled AND a.enabled
+    AND (p_kind = 'cron' OR (t.kind = 'webhook' AND t.endpoint_id = p_endpoint_id))
+    AND public.amalgm_workflow_is_executable(w.compiled)
+  ON CONFLICT (user_id, automation_id, trigger_id, delivery_key)
+    WHERE delivery_key IS NOT NULL
+  DO UPDATE SET delivery_key = EXCLUDED.delivery_key
+  RETURNING *;
+  GET DIAGNOSTICS v_inserted = ROW_COUNT;
+
+  IF p_kind = 'cron' AND v_inserted = 1 THEN
+    UPDATE public.amalgm_automation_triggers SET
+      next_run_at = p_next_run_at,
+      remaining_occurrences = CASE WHEN remaining_occurrences IS NULL
+        THEN NULL ELSE remaining_occurrences - 1 END,
+      enabled = CASE WHEN remaining_occurrences = 1 THEN false ELSE enabled END,
+      updated_at = p_now
+    WHERE user_id = p_user_id AND automation_id = p_automation_id
+      AND id = p_trigger_id AND kind = 'schedule'
+      AND next_run_at = p_expected_next_run_at;
+  END IF;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.enqueue_amalgm_manual_run(
+  p_user_id uuid,
+  p_automation_id text,
+  p_input jsonb,
+  p_idempotency_key text,
+  p_now timestamptz
+) RETURNS SETOF public.amalgm_automation_runs
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  IF p_idempotency_key IS NOT NULL THEN
+    RETURN QUERY
+    SELECT r.*
+    FROM public.amalgm_automation_runs r
+    WHERE r.user_id = p_user_id
+      AND r.automation_id = p_automation_id
+      AND r.trigger_id = '@manual'
+      AND r.delivery_key = p_idempotency_key;
+    IF FOUND THEN RETURN; END IF;
+  END IF;
+
+  RETURN QUERY
+  INSERT INTO public.amalgm_automation_runs (
+    user_id, target_id, automation_id, trigger_id, workflow_id,
+    automation_payload, input, status, delivery_key, created_at
+  )
+  SELECT a.user_id, a.target_id, a.id, '@manual', w.id,
+    jsonb_strip_nulls(jsonb_build_object(
+      'id', a.id, 'targetId', a.target_id, 'name', a.name,
+      'description', a.description, 'enabled', a.enabled,
+      'trigger', jsonb_build_object(
+        'id', '@manual', 'kind', 'manual', 'enabled', true
+      ),
+      'workflow', jsonb_strip_nulls(jsonb_build_object(
+        'id', w.id, 'name', w.name, 'script', w.script,
+        'compiled', w.compiled, 'allowlist', w.allowlist, 'limits', w.limits
+      ))
+    )),
+    p_input, 'pending', p_idempotency_key, p_now
+  FROM public.amalgm_automations a
+  JOIN public.amalgm_automation_workflows w
+    ON w.user_id = a.user_id AND w.automation_id = a.id
+  WHERE a.user_id = p_user_id AND a.id = p_automation_id AND a.enabled
+    AND public.amalgm_workflow_is_executable(w.compiled)
+  ON CONFLICT (user_id, automation_id, trigger_id, delivery_key)
+    WHERE delivery_key IS NOT NULL
+  DO UPDATE SET delivery_key = EXCLUDED.delivery_key
+  RETURNING *;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.amalgm_workflow_is_executable(jsonb) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.list_amalgm_event_triggers(uuid, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.list_due_amalgm_crons(timestamptz) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.resolve_amalgm_webhook(text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.enqueue_amalgm_run(
+  text, uuid, text, text, text, text, text, timestamptz, timestamptz, jsonb, timestamptz
+) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.enqueue_amalgm_manual_run(
+  uuid, text, jsonb, text, timestamptz
+) FROM PUBLIC;
+
+GRANT EXECUTE ON FUNCTION public.list_amalgm_event_triggers(uuid, text) TO service_role;
+GRANT EXECUTE ON FUNCTION public.list_due_amalgm_crons(timestamptz) TO service_role;
+GRANT EXECUTE ON FUNCTION public.resolve_amalgm_webhook(text) TO service_role;
+GRANT EXECUTE ON FUNCTION public.enqueue_amalgm_run(
+  text, uuid, text, text, text, text, text, timestamptz, timestamptz, jsonb, timestamptz
+) TO service_role;
+GRANT EXECUTE ON FUNCTION public.enqueue_amalgm_manual_run(
+  uuid, text, jsonb, text, timestamptz
+) TO service_role;

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.