@amalgm/automations 0.2.6 → 0.3.1

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.
@@ -55,9 +57,11 @@
     DPoP request URL behind the Fly proxy.
 21. Machine execution consumes the immutable workflow snapshot stored on the
     run. It never rediscovers or silently updates the automation definition.
-22. A compiled workflow is a small declarative sequence of one or more tool actions. The
-    executor receives tool calling as a host capability and never embeds a
-    Channels, Shell, CLI, or provider special case.
+22. Workflow version 1 remains action-only. Version 2 is a small declarative
+    sequence of one or more typed steps: `action` invokes an Amalgm action,
+    `command` starts an executable directly, and `script` evaluates explicit
+    shell, Node.js, or Python source. These are separate execution lanes, never
+    aliases for one another.
 23. Automations is a standalone hosted service. Gateway owns none of its API,
     scheduling, claim, execution, or persistence path.
 24. The durable run ledger is the offline queue. The platform never keeps a
@@ -69,18 +73,59 @@
     lease. It renews that lease while the action is running and stops advancing
     when renewal fails.
 27. One run-step pair has one stable idempotency key. Step ids are unique in a
-    plan, and every action host receives that key and a cancellation signal.
+    plan, and every execution host receives that key and a cancellation signal.
 28. Only transient transport failures retry. They release the same run with a
     bounded future retry time and retain completed step output; invalid plans,
     missing actions, authorization failures, and other deterministic errors
     are terminal.
-29. The selected target executes every action effect. The hosted service owns
+29. The selected target executes every workflow effect. The hosted service owns
     only configuration, admission, leases, the step journal, and run history.
 30. Run Now is triggerless manual admission. It atomically snapshots the
     current enabled automation and compiled workflow into the pending ledger;
     it never executes inline or changes a trigger's schedule state.
-31. A step input is an immutable JSON template. The exact singleton
-    `{ "$runInput": true }` explicitly resolves to the run's immutable input;
-    no trigger payload is ambient and no action rediscovers it.
+31. Action input and process stdin are immutable JSON templates. The exact
+    singleton `{ "$runInput": true }` explicitly resolves to the run's
+    immutable input; no trigger payload is ambient and no step rediscovers it.
 32. An adapter preserves the owning service's error code and status. Transport
     errors may add presentation, but never relabel authorization as validation.
+33. MCP and CLI project one task-level command catalog: create, list, get,
+    update, delete, and run-now. Command names, input schemas, and invocation
+    behavior are defined once and neither adapter invents resource-level
+    lifecycle operations.
+34. A CLI running for a signed-in user reaches Automations through Shell's
+    authenticated loopback MCP route. It may possess the local runtime admission
+    token, but never a durable machine credential, device key, cached access
+    token, or reusable DPoP proof.
+35. Every CLI command consumes one JSON object and emits one JSON envelope. A
+    success is `{ "result": ... }`; a failure is
+    `{ "error": { "code": ..., "message": ..., "status"?: ... } }` and a
+    nonzero exit, so agents never have to scrape prose for command state.
+36. CLI invocation is global configuration control. It never scopes an
+    automation to the caller's current directory, and a scheduled process never
+    inherits the directory from which its definition was created.
+37. Every process step may persist an explicit `cwd`; omission means the
+    selected machine host's documented default. Relative working directories
+    are invalid because their future meaning would depend on ambient state.
+38. A `command` step supplies an executable and argv directly and never passes
+    through an implicit shell. Shell parsing, pipelines, redirection, and
+    interpolation require either an explicit `script` step or a command whose
+    executable is itself a shell.
+39. Process environment values stored in a workflow are ordinary persisted
+    configuration, never an implicit secret store. A host may add its own
+    baseline process environment, but adapters never capture the creator
+    process's environment into the definition.
+40. Automations owns step types, validation, ordering, leases, retry, and
+    journals; the target machine host owns action calls and process spawning.
+    MCP, CLI, HTTP, and hosted control-plane code execute neither.
+41. Direct process effects are at-least-once across an uncertain machine
+    failure. The host exposes the stable step key as
+    `AMALGM_AUTOMATION_IDEMPOTENCY_KEY`; a program that requires exactly-once
+    behavior must durably deduplicate it.
+42. A child process never inherits Shell's runtime admission token, machine
+    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

@@ -22,20 +22,56 @@ The product has two composable halves over that one state:
   plane's persisted configuration; it does not expose another definition
   write path. When a machine is offline, new runs remain pending; when it
   reconnects, Shell claims pending runs directly from the Automations service
-  with its machine-bound DPoP identity and executes the persisted tool-action
-  plan. Execution itself stays on the selected machine. The platform never
+  with its machine-bound DPoP identity and executes the persisted plan.
+  Execution itself stays on the selected machine. The platform never
   needs to know whether a machine is online: an unclaimed run is the complete
   offline queue.
 
-One run is one immutable plan, one immutable trigger input, plus one durable ordered step journal. The
-machine records a step as running before invoking its action 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 with a bounded future retry time; a configuration, authorization, or
-action error fails it. Stable per-step idempotency keys make an uncertain
-network acknowledgement safe to repeat. A workflow can place that run input in
-an action payload only through the explicit `{ "$runInput": true }` template
-value, so static configuration and occurrence data never blur together.
+The agent CLI is the command-line projection of the same task-level command
+surface as MCP: create, list, get, update, delete, and run-now. Each command
+accepts the same JSON object as its corresponding MCP tool and returns the same
+structured success or error envelope. In a signed-in installation the CLI
+reaches that surface through Shell's authenticated loopback MCP route. Shell
+keeps the durable machine credential and device key, and continues to mint the
+short-lived access token and fresh DPoP proof used by the hosted SDK client; the
+CLI sees only the local runtime admission token. The standalone adapter may be
+composed over an already-bound SDK for tests and other hosts, but it never owns
+automation lifecycle or authorization rules.
+
+The CLI is global configuration control, not directory-local state. The agent
+or person creating an automation may invoke it from any directory; the selected
+machine and the persisted workflow decide where effects occur later. A process
+step may persist an explicit working directory, or deliberately use that
+machine host's documented default, but it never inherits the creator CLI's
+ambient working directory.
+
+One run is one immutable plan, one immutable trigger input, plus one durable
+ordered step journal. Version 1 retains its original action-only meaning;
+version 2 explicitly opts into three execution lanes: an `action`
+step invokes an Amalgm action such as a tool or `chat.chat_agent_run`; a
+`command` step starts an installed executable directly with argv semantics,
+which includes native agents such as `codex exec` or `claude -p`; and a
+`script` step evaluates persisted shell, Node.js, or Python source. These lanes
+share ordering, leases, retries, journaling, and idempotency, but never disguise
+one execution model as another. Automations describes and validates the lanes;
+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. 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
+safe to repeat; process steps also receive it in
+`AMALGM_AUTOMATION_IDEMPOTENCY_KEY`, but arbitrary programs remain at-least-once
+effects across a machine crash unless the program deduplicates that key. A
+workflow can place run input into an action payload or process stdin only
+through the explicit `{ "$runInput": true }` template value, so static
+configuration and occurrence data never blur together. Direct commands never
+invoke a shell; shell expansion is available only by choosing the visibly
+distinct `script` lane.
 
 Automations is its own hosted service and Fly machine. Its API and scheduler
 share the same SDK and Supabase authority; neither is composed into, proxied by,

package/README.md

@@ -34,7 +34,7 @@ const run = await sdk.runs.runNow(automation.id, {
 
 That schedule admits exactly ten durable runs, then disables itself. If the
 machine is offline, the runs remain pending. Shell later claims only work whose
-target matches its DPoP `computer_id`, executes the immutable tool-action plan,
+target matches its DPoP `computer_id`, executes the immutable typed plan,
 and commits the result. Run Now returns the newly admitted `pending` run; it
 uses that same machine execution path and never executes workflow effects in
 the API request.
@@ -42,11 +42,66 @@ the API request.
 ## Surfaces
 
 - `@amalgm/automations`: SDK, API/client, scheduler, machine claim client, and
-  generic tool-action executor.
+  generic typed-step executor plus its optional Node process host adapter.
 - `@amalgm/automations/mcp`: agent tools over the same SDK.
 - `@amalgm/automations/host`: standalone Fly service composition.
 - `amalgm-automations`: CLI adapter.
 
+## Agent CLI
+
+The CLI has the same six task-level operations and JSON input objects as MCP:
+`create`, `list`, `get`, `update`, `delete`, and `run-now`. Its Shell-facing
+argument form is `amalgm automations`; the package also ships the directly
+executable `amalgm-automations` adapter.
+
+It is global configuration control. Invoke it from any directory; automation
+state is owned by the service and execution is owned by the selected machine.
+The directory in which an agent creates a definition is never captured. Put an
+absolute `cwd` on a command or script when location matters. When `cwd` is
+omitted, Amalgm Shell deliberately uses the user's OS home on that machine.
+
+```bash
+amalgm automations create --stdin <<'JSON'
+{
+  "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" }
+      }]
+    }
+  }
+}
+JSON
+
+amalgm automations get \
+  --input '{"automation_id":"<id>","include_runs":true}'
+```
+
+Every success is one JSON line shaped as `{ "result": ... }`. Every failure is
+one JSON line on stderr shaped as
+`{ "error": { "code": "...", "message": "..." } }`, with an optional HTTP
+`status`, and exits nonzero. Use `--stdin` for inputs containing credentials;
+`--input` and `--file` are also supported.
+
+When Shell invokes the adapter, it supplies `AMALGM_MCP_URL` and
+`AMALGM_RUNTIME_TOKEN` from its running user runtime. The CLI sends that
+runtime token only to the loopback `/mcp/automations` route. Shell retains the
+durable machine credential and device key and creates the short-lived access
+token and fresh DPoP proof for the hosted request. For transition
+compatibility, the standalone entry point still accepts the prior paired
+`AMALGM_AUTOMATIONS_API_URL` and `AMALGM_AUTOMATIONS_AUTHORIZATION`
+environment variables.
+
 The hosted service accepts verified Supabase user sessions for browser control
 and Core-issued `amalgm-automations` DPoP grants for Shell. It does not run in
 or depend on Amalgm Gateway.
@@ -62,18 +117,70 @@ signing secret is write-only.
 Executable workflows use one small, non-empty format:
 
 ```ts
-type AutomationPlan = {
-  version: 1;
-  steps: [
-    { id: string; actionId: string; input: Json },
-    ...Array<{ id: string; actionId: string; input: Json }>,
-  ];
-};
+type AutomationPlan =
+  | { version: 1; steps: [ToolActionStep, ...ToolActionStep[]] }
+  | { version: 2; steps: [AutomationStep, ...AutomationStep[]] };
+
+type AutomationStep =
+  // Amalgm action/tool/agent path
+  | { id: string; actionId: string; input: Json }
+  // Native executable path: no shell parsing
+  | {
+      id: string; kind: 'command'; command: string; args?: string[];
+      cwd?: string; // absolute path
+      env?: Record<string, string>; stdin?: Json;
+      timeoutMs?: number; maxOutputBytes?: number;
+    }
+  // Explicit persisted code path
+  | {
+      id: string; kind: 'script'; runtime: 'shell' | 'node' | 'python';
+      source: string; args?: string[]; cwd?: string; // absolute path
+      env?: Record<string, string>; stdin?: Json;
+      timeoutMs?: number; maxOutputBytes?: number;
+    };
+```
+
+Version 1 remains the original action-only contract. Version 2 opts into the
+typed execution contract and is required for command or script steps. The
+separation is intentional. An Amalgm agent is an action step using
+`chat.chat_agent_run`. A user's native Codex, Claude Code, or OpenCode is a
+command step using the installed `codex`, `claude`, or `opencode` executable:
+
+```json
+{
+  "version": 2,
+  "steps": [{
+    "id": "native-review",
+    "kind": "command",
+    "command": "codex",
+    "args": ["exec", "Review this repository and write REVIEW.md"],
+    "cwd": "/Users/me/src/project",
+    "timeoutMs": 1800000
+  }]
+}
 ```
 
-The executor does not know about Channels or any other product. Shell injects
-one action-calling capability, and each step receives the stable idempotency key
-`<run-id>:<step-id>`.
+Command args are passed literally with no shell. Use a `script` step when the
+user explicitly wants shell parsing, a pipeline, or inline Node/Python code.
+String `stdin` is passed verbatim; other JSON is serialized with a trailing
+newline. Either action `input` or process `stdin` may contain the exact template
+`{ "$runInput": true }` to receive that run's durable trigger input.
+
+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. 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.
+
+Each step receives the stable key `<run-id>:<step-id>`. The Node process host
+also exposes it as `AMALGM_AUTOMATION_IDEMPOTENCY_KEY`. Arbitrary processes are
+at-least-once across a machine crash; programs with non-repeatable effects must
+durably deduplicate that key.
 
 ## HTTP
 

package/dist/src/cli/arguments.d.ts

@@ -0,0 +1,20 @@
+import type { AutomationCommandName } from '../command-surface.js';
+export type AutomationCliInput = {
+    kind: 'empty';
+} | {
+    kind: 'inline';
+    value: string;
+} | {
+    kind: 'file';
+    filename: string;
+} | {
+    kind: 'stdin';
+};
+export type ParsedAutomationCli = {
+    kind: 'help';
+} | {
+    kind: 'command';
+    command: AutomationCommandName;
+    input: AutomationCliInput;
+};
+export declare function parseAutomationCliArguments(argv: readonly string[]): ParsedAutomationCli;

package/dist/src/cli/arguments.js

@@ -0,0 +1,49 @@
+import { ValidationError } from '../errors.js';
+const commandNames = new Set([
+    'create', 'list', 'get', 'update', 'delete', 'run-now',
+]);
+export function parseAutomationCliArguments(argv) {
+    const args = [...argv];
+    if (args[0] === 'automations')
+        args.shift();
+    if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+        if (args.length > 1)
+            throw new ValidationError('Help does not accept additional arguments');
+        return { kind: 'help' };
+    }
+    const command = args.shift();
+    if (!commandNames.has(command)) {
+        throw new ValidationError(`Unknown Automations command: ${command ?? ''}`);
+    }
+    let input = { kind: 'empty' };
+    while (args.length > 0) {
+        const argument = args.shift();
+        if (argument === '--stdin') {
+            input = oneInput(input, { kind: 'stdin' });
+            continue;
+        }
+        const [flag, inline] = splitOption(argument);
+        if (flag !== '--input' && flag !== '--file') {
+            throw new ValidationError(`Unknown Automations CLI option: ${flag}`);
+        }
+        const value = inline ?? args.shift();
+        if (value === undefined || value === '')
+            throw new ValidationError(`${flag} requires a value`);
+        input = oneInput(input, flag === '--input'
+            ? { kind: 'inline', value }
+            : { kind: 'file', filename: value });
+    }
+    return { kind: 'command', command: command, input };
+}
+function oneInput(current, next) {
+    if (current.kind !== 'empty') {
+        throw new ValidationError('Provide command input exactly once with --input, --file, or --stdin');
+    }
+    return next;
+}
+function splitOption(value) {
+    const separator = value.indexOf('=');
+    return separator === -1
+        ? [value, undefined]
+        : [value.slice(0, separator), value.slice(separator + 1)];
+}

package/dist/src/cli/input.d.ts

@@ -0,0 +1,6 @@
+import type { AutomationCliInput } from './arguments.js';
+export interface AutomationCliInputPorts {
+    readFile?(filename: string): Promise<string>;
+    readStdin?(): Promise<string>;
+}
+export declare function readAutomationCliInput(input: AutomationCliInput, ports: AutomationCliInputPorts): Promise<Record<string, unknown>>;

package/dist/src/cli/input.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs/promises';
+import { ValidationError } from '../errors.js';
+export async function readAutomationCliInput(input, ports) {
+    if (input.kind === 'empty')
+        return {};
+    let source;
+    if (input.kind === 'inline')
+        source = input.value;
+    else if (input.kind === 'file') {
+        try {
+            source = await (ports.readFile ?? readFile)(input.filename);
+        }
+        catch (error) {
+            throw new ValidationError(`Cannot read Automations input file: ${message(error)}`);
+        }
+    }
+    else {
+        try {
+            source = await (ports.readStdin ?? readStdin)();
+        }
+        catch (error) {
+            throw new ValidationError(`Cannot read Automations input from stdin: ${message(error)}`);
+        }
+    }
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new ValidationError('Automations command input must be valid JSON');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ValidationError('Automations command input must be a JSON object');
+    }
+    return value;
+}
+function readFile(filename) {
+    return fs.readFile(filename, 'utf8');
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/cli/main.d.ts

@@ -0,0 +1,7 @@
+import { type AutomationCliIo } from './run.js';
+export interface AutomationCliMainOptions extends AutomationCliIo {
+    argv?: string[];
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof globalThis.fetch;
+}
+export declare function runAutomationCliMain(options?: AutomationCliMainOptions): Promise<number>;

package/dist/src/cli/main.js

@@ -0,0 +1,39 @@
+import { createAutomationClient } from '../client.js';
+import { createAutomationCommands, } from '../command-surface.js';
+import { AutomationError } from '../errors.js';
+import { runAutomationCli } from './run.js';
+import { createShellAutomationCommands } from './shell-runtime.js';
+export async function runAutomationCliMain(options = {}) {
+    const argv = options.argv ?? process.argv.slice(2);
+    const env = options.env ?? process.env;
+    return runAutomationCli(argv, lazyCommands(() => commandsFromEnvironment(env, options.fetch)), options);
+}
+function commandsFromEnvironment(env, fetch) {
+    const runtimeUrl = env.AMALGM_AUTOMATIONS_RUNTIME_URL || env.AMALGM_MCP_URL;
+    const runtimeToken = env.AMALGM_RUNTIME_TOKEN;
+    if (runtimeUrl || runtimeToken) {
+        if (!runtimeUrl || !runtimeToken) {
+            throw new AutomationError('runtime_unavailable', 'AMALGM_MCP_URL and AMALGM_RUNTIME_TOKEN must both come from the running Amalgm Shell runtime');
+        }
+        return createShellAutomationCommands({ runtimeUrl, runtimeToken, ...(fetch ? { fetch } : {}) });
+    }
+    const baseUrl = env.AMALGM_AUTOMATIONS_API_URL;
+    const authorization = env.AMALGM_AUTOMATIONS_AUTHORIZATION;
+    if (baseUrl && authorization) {
+        return createAutomationCommands(createAutomationClient({
+            baseUrl,
+            authorization: () => authorization,
+            ...(fetch ? { fetch } : {}),
+        }));
+    }
+    throw new AutomationError('runtime_unavailable', 'A running Amalgm Shell runtime is required (AMALGM_MCP_URL and AMALGM_RUNTIME_TOKEN)');
+}
+function lazyCommands(open) {
+    let commands;
+    return {
+        execute(name, input) {
+            commands ??= open();
+            return commands.execute(name, input);
+        },
+    };
+}

package/dist/src/cli/run.d.ts

@@ -0,0 +1,13 @@
+import { type AutomationCommands } from '../command-surface.js';
+import type { AutomationCrud } from '../contract.js';
+import { type AutomationCliInputPorts } from './input.js';
+interface Output {
+    write(chunk: string): unknown;
+}
+export interface AutomationCliIo extends AutomationCliInputPorts {
+    stdout?: Output;
+    stderr?: Output;
+}
+export declare const automationCliHelp = "amalgm automations \u2014 durable automation control for agents\n\nUsage:\n  amalgm automations <command> [--input JSON | --file PATH | --stdin]\n  amalgm-automations <command> [--input JSON | --file PATH | --stdin]\n\nCommands (identical to the Automations MCP task surface):\n  create    Create one complete definition\n  list      List the user's automations\n  get       Get one complete definition and optional run history\n  update    Apply grouped definition changes\n  delete    Delete current configuration; run history remains\n  run-now   Admit one durable manual run\n\nInput is one JSON object with the corresponding MCP tool's fields. Commands\nwithout options receive {}. Output is one JSON success or error envelope.\nUse --stdin when input contains credentials such as a webhook signing secret.\n\nWorkflow step lanes:\n  version 1  action-only: {\"id\":\"...\",\"actionId\":\"product.action\",\"input\":{...}}\n  version 2  action, command, or script steps:\n    command  {\"id\":\"...\",\"kind\":\"command\",\"command\":\"codex\",\"args\":[\"exec\",\"...\"],\"cwd\":\"/absolute/path\"}\n    script   {\"id\":\"...\",\"kind\":\"script\",\"runtime\":\"shell|node|python\",\"source\":\"...\",\"cwd\":\"/absolute/path\"}\n";
+export declare function runAutomationCli(argv: string[], backend: AutomationCrud | AutomationCommands, io?: AutomationCliIo): Promise<number>;
+export {};

package/dist/src/cli/run.js

@@ -0,0 +1,51 @@
+import { createAutomationCommands, } from '../command-surface.js';
+import { automationFailure } from '../command-result.js';
+import { parseAutomationCliArguments } from './arguments.js';
+import { readAutomationCliInput, } from './input.js';
+export const automationCliHelp = `amalgm automations — durable automation control for agents
+
+Usage:
+  amalgm automations <command> [--input JSON | --file PATH | --stdin]
+  amalgm-automations <command> [--input JSON | --file PATH | --stdin]
+
+Commands (identical to the Automations MCP task surface):
+  create    Create one complete definition
+  list      List the user's automations
+  get       Get one complete definition and optional run history
+  update    Apply grouped definition changes
+  delete    Delete current configuration; run history remains
+  run-now   Admit one durable manual run
+
+Input is one JSON object with the corresponding MCP tool's fields. Commands
+without options receive {}. Output is one JSON success or error envelope.
+Use --stdin when input contains credentials such as a webhook signing secret.
+
+Workflow step lanes:
+  version 1  action-only: {"id":"...","actionId":"product.action","input":{...}}
+  version 2  action, command, or script steps:
+    command  {"id":"...","kind":"command","command":"codex","args":["exec","..."],"cwd":"/absolute/path"}
+    script   {"id":"...","kind":"script","runtime":"shell|node|python","source":"...","cwd":"/absolute/path"}
+`;
+export async function runAutomationCli(argv, backend, io = {}) {
+    const stdout = io.stdout ?? process.stdout;
+    const stderr = io.stderr ?? process.stderr;
+    try {
+        const parsed = parseAutomationCliArguments(argv);
+        if (parsed.kind === 'help') {
+            stdout.write(automationCliHelp);
+            return 0;
+        }
+        const input = await readAutomationCliInput(parsed.input, io);
+        const commands = isCommands(backend) ? backend : createAutomationCommands(backend);
+        const result = await commands.execute(parsed.command, input);
+        stdout.write(`${JSON.stringify({ result })}\n`);
+        return 0;
+    }
+    catch (error) {
+        stderr.write(`${JSON.stringify(automationFailure(error))}\n`);
+        return 1;
+    }
+}
+function isCommands(value) {
+    return 'execute' in value && typeof value.execute === 'function';
+}

package/dist/src/cli/shell-runtime.d.ts

@@ -0,0 +1,9 @@
+import { type AutomationCommands } from '../command-surface.js';
+export interface ShellAutomationCommandOptions {
+    runtimeUrl: string;
+    runtimeToken: string;
+    fetch?: typeof globalThis.fetch;
+    requestTimeoutMs?: number;
+}
+export declare function createShellAutomationCommands(options: ShellAutomationCommandOptions): AutomationCommands;
+export declare function shellAutomationEndpoint(runtimeUrl: string): string;