@amalgm/automations 0.2.4 → 0.2.5

package/AXIOMS.md

@@ -78,3 +78,8 @@
 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.
+32. An adapter preserves the owning service's error code and status. Transport
+    errors may add presentation, but never relabel authorization as validation.

package/PURPOSE.md

@@ -27,13 +27,15 @@ The product has two composable halves over that one state:
   needs to know whether a machine is online: an unclaimed run is the complete
   offline queue.
 
-One run is one immutable plan plus one durable ordered step journal. The
+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.
+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.
 
 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/dist/src/client.js

@@ -61,9 +61,10 @@ function createRequester(baseUrl, authorization, additionalHeaders, fetch, reque
         if (response.status === 404 && nullable)
             return null;
         if (!response.ok) {
-            throw new AutomationError(payload.code === 'conflict' || payload.code === 'forbidden' || payload.code === 'internal' || payload.code === 'not_found'
-                ? payload.code
-                : response.status >= 500 ? 'internal' : 'validation', payload.error || `Automations API returned ${response.status}`);
+            const code = payload.code?.trim() || (response.status === 403 ? 'forbidden'
+                : response.status >= 500 ? 'internal'
+                    : 'validation');
+            throw new AutomationError(code, payload.error || `Automations API returned ${response.status}`, response.status);
         }
         return payload;
     };

package/dist/src/errors.d.ts

@@ -1,7 +1,8 @@
 export type AutomationErrorCode = 'conflict' | 'forbidden' | 'internal' | 'not_found' | 'validation';
 export declare class AutomationError extends Error {
-    readonly code: AutomationErrorCode;
-    constructor(code: AutomationErrorCode, message: string);
+    readonly code: AutomationErrorCode | string;
+    readonly status?: number | undefined;
+    constructor(code: AutomationErrorCode | string, message: string, status?: number | undefined);
 }
 export declare class ValidationError extends AutomationError {
     constructor(message: string);

package/dist/src/errors.js

@@ -1,8 +1,10 @@
 export class AutomationError extends Error {
     code;
-    constructor(code, message) {
+    status;
+    constructor(code, message, status) {
         super(message);
         this.code = code;
+        this.status = status;
         this.name = 'AutomationError';
     }
 }

package/dist/src/executor.js

@@ -1,3 +1,4 @@
+import { resolveActionInput } from './input-template.js';
 import { automationPlan } from './plan.js';
 import { completed, emptyJournal, journalJson, putStep, runJournal, stepAttempt, } from './run-journal.js';
 export { automationPlan } from './plan.js';
@@ -138,7 +139,7 @@ export class AutomationRunExecutor {
         try {
             const output = await this.actions.call({
                 actionId: step.actionId,
-                payload: step.input,
+                payload: resolveActionInput(step.input, run.input),
                 idempotencyKey: `${run.id}:${step.id}`,
                 signal: controller.signal,
             });

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

@@ -0,0 +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;

package/dist/src/input-template.js

@@ -0,0 +1,19 @@
+const RUN_INPUT_REFERENCE = '$runInput';
+/** Resolve the one explicit dynamic value permitted in an immutable action input. */
+export function resolveActionInput(template, runInput) {
+    if (Array.isArray(template))
+        return template.map((value) => resolveActionInput(value, runInput));
+    if (!template || typeof template !== 'object')
+        return template;
+    const entries = Object.entries(template);
+    if (entries.length === 1 && entries[0]?.[0] === RUN_INPUT_REFERENCE) {
+        if (entries[0][1] !== true) {
+            throw new Error(`Workflow ${RUN_INPUT_REFERENCE} reference must equal true`);
+        }
+        return runInput;
+    }
+    return Object.fromEntries(entries.map(([key, value]) => [
+        key,
+        resolveActionInput(value, runInput),
+    ]));
+}

package/dist/src/machine-client.js

@@ -17,7 +17,9 @@ export function createMachineRunsClient(options) {
         });
         const payload = await response.json().catch(() => ({}));
         if (!response.ok)
-            throw new AutomationError(response.status === 403 ? 'forbidden' : response.status >= 500 ? 'internal' : 'validation', payload.error ?? `Automations API returned ${response.status}`);
+            throw new AutomationError(payload.code?.trim() || (response.status === 403 ? 'forbidden'
+                : response.status >= 500 ? 'internal'
+                    : 'validation'), payload.error ?? `Automations API returned ${response.status}`, response.status);
         return payload;
     };
     return Object.freeze({

package/dist/src/mcp.js

@@ -1,5 +1,6 @@
 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 { createAutomationToolSurface } from './tool-surface.js';
 export { createAutomationToolSurface };
@@ -83,9 +84,22 @@ 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;
     return {
         isError: true,
-        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+        content: [{
+                type: 'text',
+                text: `${code}: ${message}${status === undefined ? '' : ` (HTTP ${status})`}`,
+            }],
+        structuredContent: {
+            error: {
+                code,
+                message,
+                ...(status === undefined ? {} : { status }),
+            },
+        },
     };
 }
 const read = () => ({

package/package.json

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

package/skills/automations/SKILL.md

@@ -54,6 +54,12 @@ user asks for the outcome.
 
 Action discovery belongs to the Tools product, not Automations.
 
+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.
+
 `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
@@ -63,3 +69,10 @@ 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.