@amalgm/automations 0.2.6 → 0.3.1

package/dist/src/executor.d.ts

@@ -1,20 +1,8 @@
-import type { Json } from './contract.js';
+import type { AutomationActionPort, AutomationRunExecutorOptions } from './execution-contract.js';
 import type { ClaimedAutomationRun, MachineRuns } from './machine.js';
 export { automationPlan } from './plan.js';
-export interface AutomationActionPort {
-    call(input: Readonly<{
-        actionId: string;
-        payload: Json;
-        idempotencyKey: string;
-        signal: AbortSignal;
-    }>): Promise<Json>;
-}
-export interface AutomationRunExecutorOptions {
-    readonly now?: () => Date;
-    readonly heartbeatMs?: number;
-    readonly maxAttempts?: number;
-    readonly retryDelayMs?: (attempt: number) => number;
-}
+export { transientFailure } from './execution-errors.js';
+export type { AutomationActionPort, AutomationProcessExecution, AutomationProcessPort, AutomationRunExecutorOptions, } from './execution-contract.js';
 export declare class AutomationRunExecutor {
     #private;
     private readonly runs;
@@ -22,4 +10,3 @@ export declare class AutomationRunExecutor {
     constructor(runs: MachineRuns, actions: AutomationActionPort, options?: AutomationRunExecutorOptions);
     execute(run: ClaimedAutomationRun): Promise<void>;
 }
-export declare function transientFailure(error: unknown): boolean;

package/dist/src/executor.js

@@ -1,7 +1,9 @@
-import { resolveActionInput } from './input-template.js';
+import { resolveInputTemplate } from './input-template.js';
 import { automationPlan } from './plan.js';
+import { errorOutput, safeError, transientFailure } from './execution-errors.js';
 import { completed, emptyJournal, journalJson, putStep, runJournal, stepAttempt, } from './run-journal.js';
 export { automationPlan } from './plan.js';
+export { transientFailure } from './execution-errors.js';
 export class AutomationRunExecutor {
     runs;
     actions;
@@ -9,6 +11,7 @@ export class AutomationRunExecutor {
     #heartbeatMs;
     #maxAttempts;
     #retryDelayMs;
+    #processes;
     constructor(runs, actions, options = {}) {
         this.runs = runs;
         this.actions = actions;
@@ -16,6 +19,7 @@ export class AutomationRunExecutor {
         this.#heartbeatMs = integer(options.heartbeatMs ?? 20_000, 1, 'heartbeatMs');
         this.#maxAttempts = integer(options.maxAttempts ?? 5, 1, 'maxAttempts');
         this.#retryDelayMs = options.retryDelayMs ?? defaultRetryDelayMs;
+        this.#processes = options.processes;
     }
     async execute(run) {
         const confirmed = await this.runs.update(run.id, {
@@ -60,6 +64,7 @@ export class AutomationRunExecutor {
                         finishedAt: this.#now().toISOString(),
                         error,
                         failureKind,
+                        ...errorOutput(action.error),
                     });
                     if (failureKind === 'transient' && run.attempts < this.#maxAttempts) {
                         await this.runs.update(run.id, {
@@ -137,12 +142,7 @@ export class AutomationRunExecutor {
         const timer = setInterval(renew, this.#heartbeatMs);
         timer.unref?.();
         try {
-            const output = await this.actions.call({
-                actionId: step.actionId,
-                payload: resolveActionInput(step.input, run.input),
-                idempotencyKey: `${run.id}:${step.id}`,
-                signal: controller.signal,
-            });
+            const output = await this.#executeStep(run, step, controller.signal);
             return leaseLost ? { leaseLost: true } : { leaseLost: false, output };
         }
         catch (error) {
@@ -154,35 +154,30 @@ export class AutomationRunExecutor {
             await heartbeat;
         }
     }
-}
-export function transientFailure(error) {
-    for (let current = error, depth = 0; current && depth < 4; depth += 1) {
-        if (typeof current !== 'object')
-            break;
-        const item = current;
-        const status = Number(item.status);
-        if (status === 408 || status === 429 || status >= 500)
-            return true;
-        const code = String(item.code ?? '');
-        if (TRANSIENT_CODES.has(code))
-            return true;
-        current = item.cause;
+    #executeStep(run, step, signal) {
+        const idempotencyKey = `${run.id}:${step.id}`;
+        if ('kind' in step) {
+            if (!this.#processes) {
+                throw Object.assign(new Error('Automation process execution is not installed on this machine'), {
+                    code: 'process_execution_unavailable',
+                });
+            }
+            const { id: _id, stdin, ...execution } = step;
+            return this.#processes.execute({
+                ...execution,
+                ...(stdin === undefined ? {} : { stdin: processStdin(resolveInputTemplate(stdin, run.input)) }),
+                idempotencyKey,
+                signal,
+            });
+        }
+        return this.actions.call({
+            actionId: step.actionId,
+            payload: resolveInputTemplate(step.input, run.input),
+            idempotencyKey,
+            signal,
+        });
     }
-    const message = safeError(error).toLowerCase();
-    return message.includes('fetch failed') || message.includes('network error');
 }
-const TRANSIENT_CODES = new Set([
-    'ECONNREFUSED',
-    'ECONNRESET',
-    'EAI_AGAIN',
-    'ENETDOWN',
-    'ENETUNREACH',
-    'ETIMEDOUT',
-    'UND_ERR_CONNECT_TIMEOUT',
-    'UND_ERR_HEADERS_TIMEOUT',
-    'UND_ERR_SOCKET',
-    'internal',
-]);
 function defaultRetryDelayMs(attempt) {
     return Math.min(5 * 60_000, 2_000 * (2 ** Math.max(0, attempt - 1)));
 }
@@ -191,6 +186,6 @@ function integer(value, minimum, name) {
         throw new Error(`${name} must be an integer of at least ${minimum}`);
     return value;
 }
-function safeError(error) {
-    return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, ' ').slice(0, 1_000);
+function processStdin(value) {
+    return typeof value === 'string' ? value : `${JSON.stringify(value)}\n`;
 }

package/dist/src/index.d.ts

@@ -2,10 +2,14 @@ export { createAutomationClient, type AutomationAuthorization, type AutomationHe
 export { AutomationCrudService, type AutomationCrudRepository } from './crud.js';
 export { AutomationError, ConflictError, ForbiddenError, NotFoundError, ValidationError, type AutomationErrorCode, } from './errors.js';
 export { createAutomationApi, type AuthenticateAutomationRequest, type AutomationApi } from './http.js';
-export { runAutomationCli } from './cli.js';
+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';
-export type { Automation, AutomationCrud, AutomationCrudService as AutomationCrudServiceContract, AutomationPrincipal, AutomationPlan, AutomationRunJournal, AutomationStepRun, AutomationStepStatus, AutomationRun, AutomationScope, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, Json, ListAutomations, ListRuns, Page, PageQuery, RunStatus, RunAutomationNow, ScheduleTrigger, Trigger, ToolActionStep, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow, } from './contract.js';
+export type { Automation, AutomationActionPlan, AutomationCrud, AutomationCrudService as AutomationCrudServiceContract, AutomationPrincipal, AutomationPlan, AutomationRunJournal, AutomationScriptRuntime, AutomationStep, AutomationTypedPlan, AutomationStepRun, AutomationStepStatus, AutomationRun, AutomationScope, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, CodeScriptStep, DirectCommandStep, Json, ListAutomations, ListRuns, Page, PageQuery, RunStatus, RunAutomationNow, ScheduleTrigger, Trigger, ToolActionStep, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow, } from './contract.js';
 export { Automations, EventEndpointNotFoundError, EventRejectedError } from './automations.js';
 export { createAutomationEventsApi, type AutomationEventReceipt, type AutomationEventsApi, type AutomationEventsApiConfig, } from './events-http.js';
 export { nextCronAt, validateCron } from './schedule.js';
@@ -16,7 +20,8 @@ export { createMachineRuns } from './machine.js';
 export type { AutomationMachinePrincipal, ClaimedAutomationRun, MachineRunRepository, MachineRuns, MachineRunUpdate, } from './machine.js';
 export { createMachineRunsApi } from './machine-http.js';
 export { createMachineRunsClient, type AutomationRequestHeaders } from './machine-client.js';
-export { AutomationRunExecutor, automationPlan, type AutomationActionPort } from './executor.js';
+export { AutomationRunExecutor, automationPlan, type AutomationActionPort, type AutomationProcessExecution, type AutomationProcessPort, type AutomationRunExecutorOptions, } from './executor.js';
+export { createNodeAutomationProcessHost, type NodeAutomationProcessHostOptions, } from './node-process-host.js';
 export { createAutomationMachineRunner, type AutomationMachineRunnerOptions, } from './runner.js';
 export { compiledAutomationPlan } from './plan.js';
 export type { SupabaseRpcClient as SupabaseStoreRpcClient } from './supabase-store.js';

package/dist/src/index.js

@@ -9,8 +9,12 @@ export { createAutomationClient } from './client.js';
 export { AutomationCrudService } from './crud.js';
 export { AutomationError, ConflictError, ForbiddenError, NotFoundError, ValidationError, } from './errors.js';
 export { createAutomationApi } from './http.js';
-export { runAutomationCli } from './cli.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';
 export { Automations, EventEndpointNotFoundError, EventRejectedError } from './automations.js';
 export { createAutomationEventsApi, } from './events-http.js';
@@ -21,6 +25,7 @@ export { SupabaseMachineRunRepository } from './supabase-machine.js';
 export { createMachineRuns } from './machine.js';
 export { createMachineRunsApi } from './machine-http.js';
 export { createMachineRunsClient } from './machine-client.js';
-export { AutomationRunExecutor, automationPlan } from './executor.js';
+export { AutomationRunExecutor, automationPlan, } from './executor.js';
+export { createNodeAutomationProcessHost, } from './node-process-host.js';
 export { createAutomationMachineRunner, } from './runner.js';
 export { compiledAutomationPlan } from './plan.js';

package/dist/src/input-template.d.ts

@@ -1,3 +1,3 @@
 import type { Json } from './contract.js';
-/** Resolve the one explicit dynamic value permitted in an immutable action input. */
-export declare function resolveActionInput(template: Json, runInput: Json): Json;
+/** Resolve the one explicit dynamic value permitted in immutable step input. */
+export declare function resolveInputTemplate(template: Json, runInput: Json): Json;

package/dist/src/input-template.js

@@ -1,8 +1,8 @@
 const RUN_INPUT_REFERENCE = '$runInput';
-/** Resolve the one explicit dynamic value permitted in an immutable action input. */
-export function resolveActionInput(template, runInput) {
+/** Resolve the one explicit dynamic value permitted in immutable step input. */
+export function resolveInputTemplate(template, runInput) {
     if (Array.isArray(template))
-        return template.map((value) => resolveActionInput(value, runInput));
+        return template.map((value) => resolveInputTemplate(value, runInput));
     if (!template || typeof template !== 'object')
         return template;
     const entries = Object.entries(template);
@@ -14,6 +14,6 @@ export function resolveActionInput(template, runInput) {
     }
     return Object.fromEntries(entries.map(([key, value]) => [
         key,
-        resolveActionInput(value, runInput),
+        resolveInputTemplate(value, runInput),
     ]));
 }

package/dist/src/mcp.js

@@ -1,75 +1,34 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod/v3';
-import { AutomationError } from './errors.js';
-import { createAutomationSchema, createScheduleTriggerSchema, createWebhookTriggerSchema, createWorkflowSchema, identifierSchema, listAutomationsSchema, listRunsSchema, runAutomationNowSchema, updateAutomationSchema, updateScheduleTriggerSchema, updateWebhookTriggerSchema, updateWorkflowSchema, } from './schema.js';
+import { automationCommandDefinitions, createAutomationCommands, } from './command-surface.js';
+import { automationFailure } from './command-result.js';
 import { createAutomationToolSurface } from './tool-surface.js';
 export { createAutomationToolSurface };
-const resultSchema = { result: z.unknown() };
-const scheduleChangesSchema = z.object({
-    create: z.array(createScheduleTriggerSchema).max(100).optional(),
-    update: z.array(z.object({ id: identifierSchema, patch: updateScheduleTriggerSchema }).strict()).max(100).optional(),
-    delete: z.array(identifierSchema).max(100).optional(),
-}).strict();
-const webhookChangesSchema = z.object({
-    create: z.array(createWebhookTriggerSchema).max(100).optional(),
-    update: z.array(z.object({ id: identifierSchema, patch: updateWebhookTriggerSchema }).strict()).max(100).optional(),
-    delete: z.array(identifierSchema).max(100).optional(),
-}).strict();
-const workflowChangeSchema = z.union([
-    z.object({ create: createWorkflowSchema }).strict(),
-    z.object({ update: updateWorkflowSchema }).strict(),
-    z.object({ delete: z.literal(true) }).strict(),
-]);
+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 tools = createAutomationToolSurface(sdk);
-    register(server, 'amalgm_automations_create', 'Create automation', 'Create one complete automation definition, including its schedules, webhooks, and optional workflow. The service stages configuration disabled and enables it only after setup succeeds. Omit targetId in a machine-bound session; never guess a target id.', {
-        ...createAutomationSchema.shape,
-        schedules: z.array(createScheduleTriggerSchema).max(100).optional(),
-        webhooks: z.array(createWebhookTriggerSchema).max(100).optional(),
-        workflow: createWorkflowSchema.optional(),
-    }, write(false), (input) => tools.create(input));
-    register(server, 'amalgm_automations_list', 'List automations', 'List the caller\'s automations with optional target, enabled-state, and pagination filters.', {
-        ...listAutomationsSchema.shape,
-    }, read(), (query) => tools.list(query));
-    register(server, 'amalgm_automations_get', 'Get automation', 'Get one complete automation definition with its typed triggers and workflow. Recent run history is optional.', {
-        automation_id: identifierSchema,
-        include_runs: z.boolean().optional(),
-        run_query: listRunsSchema.optional(),
-    }, read(), ({ automation_id, include_runs, run_query }) => (tools.get(automation_id, include_runs || run_query ? (run_query ?? { limit: 20 }) : false)));
-    register(server, 'amalgm_automations_update', 'Update automation', 'Update an automation and grouped trigger or workflow changes in one task-level call. Resource changes are staged while the automation is disabled; a failed change leaves a safe disabled draft.', {
-        automation_id: identifierSchema,
-        patch: updateAutomationSchema.optional(),
-        schedules: scheduleChangesSchema.optional(),
-        webhooks: webhookChangesSchema.optional(),
-        workflow: workflowChangeSchema.optional(),
-    }, write(false), ({ automation_id, ...input }) => tools.update(automation_id, input));
-    register(server, 'amalgm_automations_delete', 'Delete automation', 'Delete an automation and its current triggers and workflow. Historical runs remain.', {
-        automation_id: identifierSchema,
-    }, destructive(), ({ automation_id }) => tools.delete(automation_id));
-    register(server, 'amalgm_automations_run_now', 'Run automation now', 'Durably admit one manual run using the automation\'s current enabled configuration and compiled workflow. The selected machine executes it through the normal pending-run queue; this call never executes the workflow inline.', {
-        automation_id: identifierSchema,
-        input: runAutomationNowSchema.shape.input,
-        idempotency_key: runAutomationNowSchema.shape.idempotencyKey,
-    }, write(false), ({ automation_id, input, idempotency_key }) => tools.runNow(automation_id, {
-        ...(input === undefined ? {} : { input }),
-        ...(idempotency_key === undefined ? {} : { idempotencyKey: idempotency_key }),
-    }));
+    const commands = createAutomationCommands(sdk);
+    for (const definition of automationCommandDefinitions)
+        register(server, commands, definition);
     return server;
 }
-function register(server, name, title, description, inputSchema, annotations, handler) {
-    registerUnchecked(server, name, title, description, inputSchema, annotations, async (input) => (handler(input)));
-}
-function registerUnchecked(server, name, title, description, inputSchema, annotations, handler) {
-    server.registerTool(name, {
-        title,
-        description,
-        inputSchema,
+function register(server, commands, definition) {
+    server.registerTool(definition.mcpName, {
+        title: definition.title,
+        description: definition.description,
+        inputSchema: definition.inputShape,
         outputSchema: resultSchema,
-        annotations,
+        annotations: definition.annotations,
     }, async (input) => {
         try {
-            const result = await handler(input);
+            const result = await commands.execute(definition.name, input);
             return toolSuccess(result);
         }
         catch (error) {
@@ -84,30 +43,14 @@ function toolSuccess(result) {
     };
 }
 function toolFailure(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const code = error instanceof AutomationError ? error.code : 'internal';
-    const status = error instanceof AutomationError ? error.status : undefined;
+    const failure = automationFailure(error);
+    const { code, message, status } = failure.error;
     return {
         isError: true,
         content: [{
                 type: 'text',
                 text: `${code}: ${message}${status === undefined ? '' : ` (HTTP ${status})`}`,
             }],
-        structuredContent: {
-            error: {
-                code,
-                message,
-                ...(status === undefined ? {} : { status }),
-            },
-        },
+        structuredContent: { ...failure },
     };
 }
-const read = () => ({
-    readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false,
-});
-const write = (idempotentHint) => ({
-    readOnlyHint: false, destructiveHint: false, idempotentHint, openWorldHint: false,
-});
-const destructive = () => ({
-    readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false,
-});

package/dist/src/node-process-host.d.ts

@@ -0,0 +1,13 @@
+import type { AutomationProcessPort } from './execution-contract.js';
+export interface NodeAutomationProcessHostOptions {
+    /** Used only when a step omits cwd. Shell should supply the user's OS home. */
+    readonly defaultCwd?: string;
+    /** Machine-host environment inherited by child processes. */
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly shellCommand?: string;
+    readonly nodeCommand?: string;
+    readonly pythonCommand?: string;
+    readonly terminateGraceMs?: number;
+}
+/** Node machine adapter for the SDK's process capability. */
+export declare function createNodeAutomationProcessHost(options?: NodeAutomationProcessHostOptions): AutomationProcessPort;

package/dist/src/node-process-host.js

@@ -0,0 +1,116 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { captureProcess, processError, processOutput, stringEnvironment, } from './node-process-runner.js';
+const DEFAULT_TIMEOUT_MS = 30 * 60_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+const DEFAULT_TERMINATE_GRACE_MS = 1_000;
+/** Node machine adapter for the SDK's process capability. */
+export function createNodeAutomationProcessHost(options = {}) {
+    const defaultCwd = options.defaultCwd ?? process.cwd();
+    if (!isAbsolute(defaultCwd))
+        throw new Error('Automation process defaultCwd must be absolute');
+    const environment = stringEnvironment(options.environment ?? process.env);
+    const terminateGraceMs = positiveInteger(options.terminateGraceMs ?? DEFAULT_TERMINATE_GRACE_MS, 'terminateGraceMs');
+    return Object.freeze({
+        execute: (input) => executeProcess(input, {
+            defaultCwd,
+            environment,
+            shellCommand: options.shellCommand,
+            nodeCommand: options.nodeCommand,
+            pythonCommand: options.pythonCommand,
+            terminateGraceMs,
+        }),
+    });
+}
+async function executeProcess(input, options) {
+    input.signal.throwIfAborted();
+    const prepared = await prepareProcess(input, options);
+    let result;
+    try {
+        result = await captureProcess(prepared.invocation, {
+            ...input,
+            cwd: input.cwd ?? options.defaultCwd,
+            env: {
+                ...options.environment,
+                ...input.env,
+                AMALGM_AUTOMATION_IDEMPOTENCY_KEY: input.idempotencyKey,
+            },
+        }, {
+            timeoutMs: DEFAULT_TIMEOUT_MS,
+            maximumBytes: DEFAULT_MAX_OUTPUT_BYTES,
+            terminateGraceMs: options.terminateGraceMs,
+        });
+    }
+    finally {
+        await prepared.cleanup();
+    }
+    const output = processOutput(result);
+    if (result.aborted)
+        throw processError('process_aborted', 'Automation process was cancelled', output);
+    if (result.timedOut) {
+        throw processError('process_timeout', `Automation process timed out after ${input.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms`, output);
+    }
+    if (result.code !== 0) {
+        const detail = (result.stderr || result.stdout).trim();
+        throw processError('process_exit', `Automation process exited with ${result.code ?? result.signal ?? 'unknown'}${detail ? `: ${oneLine(detail)}` : ''}`, output);
+    }
+    return output;
+}
+async function prepareProcess(input, options) {
+    if (input.kind === 'command') {
+        return {
+            invocation: { command: input.command, args: [...(input.args ?? [])] },
+            cleanup: async () => undefined,
+        };
+    }
+    const directory = await mkdtemp(join(tmpdir(), 'amalgm-automation-'));
+    const extension = input.runtime === 'node' ? 'mjs' : input.runtime === 'python' ? 'py' : 'sh';
+    const script = join(directory, `step.${extension}`);
+    try {
+        await writeFile(script, input.source, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+    const cleanup = () => rm(directory, { recursive: true, force: true });
+    if (input.runtime === 'node') {
+        return {
+            invocation: {
+                command: options.nodeCommand ?? process.execPath,
+                args: [script, ...(input.args ?? [])],
+            },
+            cleanup,
+        };
+    }
+    if (input.runtime === 'python') {
+        return {
+            invocation: {
+                command: options.pythonCommand ?? 'python3',
+                args: [script, ...(input.args ?? [])],
+            },
+            cleanup,
+        };
+    }
+    return {
+        invocation: process.platform === 'win32'
+            ? {
+                command: options.shellCommand ?? 'powershell.exe',
+                args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-File', script, ...(input.args ?? [])],
+            }
+            : {
+                command: options.shellCommand ?? '/bin/sh',
+                args: [script, ...(input.args ?? [])],
+            },
+        cleanup,
+    };
+}
+function positiveInteger(value, label) {
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error(`${label} must be a positive integer`);
+    return value;
+}
+function oneLine(value) {
+    return value.replace(/[\r\n]+/g, ' ').slice(0, 500);
+}

package/dist/src/node-process-runner.d.ts

@@ -0,0 +1,23 @@
+import type { Json } from './contract.js';
+import type { AutomationProcessExecution } from './execution-contract.js';
+export interface ProcessInvocation {
+    readonly command: string;
+    readonly args: string[];
+}
+export interface CapturedProcess {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly truncated: boolean;
+    readonly timedOut: boolean;
+    readonly aborted: boolean;
+}
+export declare function captureProcess(invocation: ProcessInvocation, input: AutomationProcessExecution, defaults: Readonly<{
+    timeoutMs: number;
+    maximumBytes: number;
+    terminateGraceMs: number;
+}>): Promise<CapturedProcess>;
+export declare function processOutput(result: CapturedProcess): Json;
+export declare function processError(code: string, message: string, output: Json): Error;
+export declare function stringEnvironment(source: NodeJS.ProcessEnv): Record<string, string>;

package/dist/src/node-process-runner.js

@@ -0,0 +1,140 @@
+import { spawn } from 'node:child_process';
+export function captureProcess(invocation, input, defaults) {
+    const maximumBytes = input.maxOutputBytes ?? defaults.maximumBytes;
+    const timeoutMs = input.timeoutMs ?? defaults.timeoutMs;
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(invocation.command, invocation.args, {
+                cwd: input.cwd ?? process.cwd(),
+                env: input.env,
+                detached: process.platform !== 'win32',
+                shell: false,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            reject(spawnError(error));
+            return;
+        }
+        const stdout = [];
+        const stderr = [];
+        let capturedBytes = 0;
+        let truncated = false;
+        let timedOut = false;
+        let aborted = false;
+        let terminating = false;
+        let escalation;
+        let settled = false;
+        const capture = (target) => (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const remaining = maximumBytes - capturedBytes;
+            if (remaining > 0) {
+                const kept = bytes.subarray(0, remaining);
+                target.push(kept);
+                capturedBytes += kept.byteLength;
+            }
+            if (bytes.byteLength > remaining)
+                truncated = true;
+        };
+        child.stdout?.on('data', capture(stdout));
+        child.stderr?.on('data', capture(stderr));
+        child.stdin?.on('error', () => undefined);
+        const terminate = () => {
+            if (terminating)
+                return;
+            terminating = true;
+            stopProcess(child, 'SIGTERM');
+            escalation = setTimeout(() => stopProcess(child, 'SIGKILL'), defaults.terminateGraceMs);
+            escalation.unref?.();
+        };
+        const onAbort = () => {
+            aborted = true;
+            terminate();
+        };
+        input.signal.addEventListener('abort', onAbort, { once: true });
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            terminate();
+        }, timeoutMs);
+        timeout.unref?.();
+        child.once('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(spawnError(error));
+        });
+        child.once('close', (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve({
+                code,
+                signal,
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+                truncated,
+                timedOut,
+                aborted,
+            });
+        });
+        child.stdin?.end(input.stdin);
+        if (input.signal.aborted)
+            onAbort();
+        function cleanup() {
+            clearTimeout(timeout);
+            if (escalation)
+                clearTimeout(escalation);
+            input.signal.removeEventListener('abort', onAbort);
+        }
+    });
+}
+export function processOutput(result) {
+    return {
+        exitCode: result.code,
+        signal: result.signal,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        truncated: result.truncated,
+    };
+}
+export function processError(code, message, output) {
+    return Object.assign(new Error(message), { code, output });
+}
+export function stringEnvironment(source) {
+    return Object.fromEntries(Object.entries(source).filter((entry) => (typeof entry[1] === 'string' && !PRIVATE_HOST_ENV.has(entry[0]))));
+}
+const PRIVATE_HOST_ENV = new Set([
+    'AMALGM_AUTOMATIONS_AUTHORIZATION',
+    'AMALGM_COMPUTER_AUTH_TOKEN',
+    'AMALGM_RUNTIME_TOKEN',
+    'AMALGM_TUNNEL_TOKEN',
+]);
+function spawnError(error) {
+    const source = error instanceof Error ? error : new Error(String(error));
+    return Object.assign(new Error(`Automation process could not start: ${source.message}`), {
+        code: source.code ?? 'process_spawn_failed',
+    });
+}
+function stopProcess(child, signal) {
+    if (child.exitCode !== null)
+        return;
+    if (process.platform !== 'win32' && child.pid) {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // The child may not have established its process group yet.
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // The close event remains authoritative.
+    }
+}