@amalgm/automations 0.2.5 → 0.3.0

package/dist/src/plan.js

@@ -1,4 +1,17 @@
 import { ValidationError } from './errors.js';
+const MAX_STEPS = 100;
+const MAX_ARGUMENTS = 1_000;
+const MAX_ARGUMENT_LENGTH = 100_000;
+const MAX_SOURCE_LENGTH = 1_000_000;
+const MAX_TIMEOUT_MS = 86_400_000;
+const MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
+const RESERVED_PROCESS_ENV = new Set([
+    'AMALGM_AUTOMATION_IDEMPOTENCY_KEY',
+    'AMALGM_AUTOMATIONS_AUTHORIZATION',
+    'AMALGM_COMPUTER_AUTH_TOKEN',
+    'AMALGM_RUNTIME_TOKEN',
+    'AMALGM_TUNNEL_TOKEN',
+]);
 export function automationPlan(snapshot) {
     const root = record(snapshot, 'Automation snapshot');
     const workflow = record(root.workflow, 'Workflow snapshot');
@@ -6,28 +19,72 @@ export function automationPlan(snapshot) {
 }
 export function compiledAutomationPlan(value) {
     const compiled = record(value, 'Compiled workflow');
-    if (compiled.version !== 1 || !Array.isArray(compiled.steps)
-        || compiled.steps.length < 1 || compiled.steps.length > 100) {
-        throw new ValidationError('Compiled workflow must be a version 1 plan with 1 to 100 steps');
+    const version = compiled.version;
+    if ((version !== 1 && version !== 2) || !Array.isArray(compiled.steps)
+        || compiled.steps.length < 1 || compiled.steps.length > MAX_STEPS) {
+        throw new ValidationError(`Compiled workflow must be a version 1 or 2 plan with 1 to ${MAX_STEPS} steps`);
     }
-    const steps = compiled.steps.map((item, index) => step(item, index));
+    const steps = compiled.steps.map((item, index) => step(item, index, version));
     const ids = new Set();
     for (const item of steps) {
         if (ids.has(item.id))
             throw new ValidationError(`Workflow step id is duplicated: ${item.id}`);
         ids.add(item.id);
     }
-    return { version: 1, steps };
+    return version === 1
+        ? { version: 1, steps: steps }
+        : { version: 2, steps };
 }
-function step(value, index) {
+function step(value, index, version) {
     const item = record(value, `Workflow step ${index + 1}`);
-    if (typeof item.id !== 'string' || !item.id.trim())
-        throw new ValidationError(`Workflow step ${index + 1} needs an id`);
+    const id = requiredText(item.id, `Workflow step ${index + 1} needs an id`, 500);
+    if (version === 1 && item.kind !== undefined) {
+        throw new ValidationError(`Workflow step ${index + 1} requires plan version 2`);
+    }
+    if (item.kind === 'command')
+        return commandStep(item, id, index);
+    if (item.kind === 'script')
+        return scriptStep(item, id, index);
+    if (item.kind !== undefined) {
+        throw new ValidationError(`Workflow step ${index + 1} has an unsupported kind`);
+    }
     if (typeof item.actionId !== 'string' || !item.actionId.includes('.')) {
         throw new ValidationError(`Workflow step ${index + 1} needs a qualified actionId`);
     }
     assertJson(item.input);
-    return { id: item.id.trim(), actionId: item.actionId.trim(), input: item.input };
+    return { id, actionId: item.actionId.trim(), input: item.input };
+}
+function commandStep(item, id, index) {
+    const label = `Workflow command step ${index + 1}`;
+    return compact({
+        id,
+        kind: 'command',
+        command: requiredText(item.command, `${label} needs a command`, 10_000),
+        args: argumentsList(item.args, label),
+        cwd: workingDirectory(item.cwd, label),
+        env: environment(item.env, label),
+        stdin: jsonInput(item.stdin, label),
+        timeoutMs: boundedInteger(item.timeoutMs, 1, MAX_TIMEOUT_MS, `${label} timeoutMs`),
+        maxOutputBytes: boundedInteger(item.maxOutputBytes, 1, MAX_OUTPUT_BYTES, `${label} maxOutputBytes`),
+    });
+}
+function scriptStep(item, id, index) {
+    const label = `Workflow script step ${index + 1}`;
+    if (item.runtime !== 'shell' && item.runtime !== 'node' && item.runtime !== 'python') {
+        throw new ValidationError(`${label} runtime must be shell, node, or python`);
+    }
+    return compact({
+        id,
+        kind: 'script',
+        runtime: item.runtime,
+        source: requiredText(item.source, `${label} needs source`, MAX_SOURCE_LENGTH, false),
+        args: argumentsList(item.args, label),
+        cwd: workingDirectory(item.cwd, label),
+        env: environment(item.env, label),
+        stdin: jsonInput(item.stdin, label),
+        timeoutMs: boundedInteger(item.timeoutMs, 1, MAX_TIMEOUT_MS, `${label} timeoutMs`),
+        maxOutputBytes: boundedInteger(item.maxOutputBytes, 1, MAX_OUTPUT_BYTES, `${label} maxOutputBytes`),
+    });
 }
 function record(value, name) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -46,3 +103,62 @@ function assertJson(value) {
     }
     throw new ValidationError('Workflow step input must be JSON');
 }
+function jsonInput(value, label) {
+    if (value === undefined)
+        return undefined;
+    try {
+        assertJson(value);
+    }
+    catch {
+        throw new ValidationError(`${label} stdin must be JSON`);
+    }
+    return value;
+}
+function argumentsList(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length > MAX_ARGUMENTS
+        || value.some((argument) => typeof argument !== 'string' || argument.length > MAX_ARGUMENT_LENGTH)) {
+        throw new ValidationError(`${label} args must contain at most ${MAX_ARGUMENTS} strings`);
+    }
+    return [...value];
+}
+function workingDirectory(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !absolutePath(value)) {
+        throw new ValidationError(`${label} cwd must be an absolute path`);
+    }
+    return value;
+}
+function environment(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || Object.entries(value).some(([name, content]) => (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)
+            || RESERVED_PROCESS_ENV.has(name)
+            || typeof content !== 'string'))) {
+        throw new ValidationError(`${label} env must map non-reserved environment variable names to strings`);
+    }
+    return { ...value };
+}
+function boundedInteger(value, minimum, maximum, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || Number(value) < minimum || Number(value) > maximum) {
+        throw new ValidationError(`${label} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return Number(value);
+}
+function requiredText(value, message, maximum, trim = true) {
+    if (typeof value !== 'string' || !value.trim() || value.length > maximum) {
+        throw new ValidationError(message);
+    }
+    return trim ? value.trim() : value;
+}
+function absolutePath(value) {
+    return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\');
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}

package/dist/src/run-contract.d.ts

@@ -5,10 +5,50 @@ export interface ToolActionStep {
     actionId: string;
     input: Json;
 }
-export interface AutomationPlan {
+export interface DirectCommandStep {
+    id: string;
+    kind: 'command';
+    /** Executable name resolved by the machine PATH, or an absolute path. */
+    command: string;
+    /** Passed directly to the executable. No shell parsing occurs. */
+    args?: string[];
+    /** Absolute directory on the selected machine. */
+    cwd?: string;
+    /** Persisted, non-secret environment additions. */
+    env?: Record<string, string>;
+    /** String input is passed verbatim; other JSON values are serialized with a trailing newline. */
+    stdin?: Json;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+export type AutomationScriptRuntime = 'shell' | 'node' | 'python';
+export interface CodeScriptStep {
+    id: string;
+    kind: 'script';
+    runtime: AutomationScriptRuntime;
+    source: string;
+    args?: string[];
+    /** Absolute directory on the selected machine. */
+    cwd?: string;
+    /** Persisted, non-secret environment additions. */
+    env?: Record<string, string>;
+    /** String input is passed verbatim; other JSON values are serialized with a trailing newline. */
+    stdin?: Json;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+export type AutomationStep = ToolActionStep | DirectCommandStep | CodeScriptStep;
+/** Original workflow contract. Its meaning remains action-only forever. */
+export interface AutomationActionPlan {
     version: 1;
     steps: ToolActionStep[];
 }
+/** Typed workflow contract for Amalgm actions, native commands, and code. */
+export interface AutomationTypedPlan {
+    version: 2;
+    steps: AutomationStep[];
+}
+export type AutomationPlan = AutomationActionPlan | AutomationTypedPlan;
 export type AutomationStepStatus = 'running' | 'completed' | 'failed';
 export interface AutomationStepRun {
     id: string;

package/dist/src/run-journal.d.ts

@@ -1,6 +1,6 @@
-import type { AutomationRunJournal, AutomationStepRun, Json, ToolActionStep } from './contract.js';
+import type { AutomationRunJournal, AutomationStep, AutomationStepRun, Json } from './contract.js';
 export declare function emptyJournal(): AutomationRunJournal;
-export declare function runJournal(value: Json | undefined, plan: readonly ToolActionStep[]): AutomationRunJournal;
+export declare function runJournal(value: Json | undefined, plan: readonly AutomationStep[]): AutomationRunJournal;
 export declare function completed(journal: AutomationRunJournal, stepId: string): boolean;
 export declare function stepAttempt(journal: AutomationRunJournal, stepId: string): number;
 export declare function putStep(journal: AutomationRunJournal, step: AutomationStepRun): AutomationRunJournal;

package/dist/src/schema.d.ts

@@ -197,27 +197,27 @@ export declare const updateWorkflowSchema: z.ZodEffects<z.ZodObject<{
     allowlist: z.ZodOptional<z.ZodNullable<z.ZodType<Json, z.ZodTypeDef, Json>>>;
     limits: z.ZodOptional<z.ZodNullable<z.ZodType<Json, z.ZodTypeDef, Json>>>;
 }, "strict", z.ZodTypeAny, {
+    script?: string | undefined;
     name?: string | null | undefined;
     compiled?: Json | undefined;
-    script?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }, {
+    script?: string | undefined;
     name?: string | null | undefined;
     compiled?: Json | undefined;
-    script?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }>, {
+    script?: string | undefined;
     name?: string | null | undefined;
     compiled?: Json | undefined;
-    script?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }, {
+    script?: string | undefined;
     name?: string | null | undefined;
     compiled?: Json | undefined;
-    script?: string | undefined;
     allowlist?: Json | undefined;
     limits?: Json | undefined;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Amalgm's automation SDK: durable trigger admission and target-machine execution.",
   "license": "UNLICENSED",
   "repository": {
@@ -45,11 +45,11 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
     "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json --noEmit",
     "test": "tsx --test test/*.test.ts",
     "test:supabase": "tsx --test test/integration/postgres.test.ts",
-    "verify": "npm run check && npm test && npm run build",
+    "verify": "npm run check && npm test && npm run build && tsx scripts/check-cli-artifact.ts",
     "release:check": "npm run verify && npm run test:supabase",
     "prepack": "npm run build",
     "start": "node dist/host/main.js"

package/skills/automations/SKILL.md

@@ -8,6 +8,67 @@ description: Create, inspect, change, delete, or manually run complete Amalgm au
 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
@@ -52,13 +113,15 @@ 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.
 
-Action discovery belongs to the Tools product, not Automations.
+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 by
-placing the exact value `{ "$runInput": true }` at the desired point in that
-step's `input`. 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.
+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