@amalgm/automations 0.2.3 → 0.2.5

package/AXIOMS.md

@@ -24,9 +24,11 @@
 9. Supabase is authoritative for automations, triggers, workflow source, and
    permanent run history. A definition edit or deletion never rewrites prior
    runs.
-10. A webhook URL is a rotatable bearer capability for exactly one trigger. Its
-    random locator is not sufficient without the hosted service's HMAC, and
-    caller input never supplies an owner or target.
+10. A webhook URL is a rotatable bearer capability for exactly one trigger.
+    Possession plus any configured provider proof admits that trigger; source
+    and event labels never form a second routing gate. Its random locator is not
+    sufficient without the hosted service's HMAC, and caller input never
+    supplies an owner or target.
 11. Optional provider signing secrets are persisted but write-only: normal
     reads reveal only that a secret is configured.
 12. Run history is read-only in the control plane and always scoped to its
@@ -76,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,
@@ -47,9 +49,10 @@ trigger owns one opaque URL under `automations.amalgm.ai`; the URL resolves the
 trigger, owner, and target, so a caller never supplies routing identity. The
 adapter bounds and parses the body, optionally verifies the provider's signing
 secret, deduplicates explicit provider delivery ids, and returns only after the
-run has been stored in Supabase. The signed URL can be rotated without changing
-the automation, and its usable bearer token cannot be reconstructed from the
-database alone.
+run has been stored in Supabase. Provider source and event labels describe the
+occurrence; they are not a second routing gate after the URL has selected the
+trigger. The signed URL can be rotated without changing the automation, and its
+usable bearer token cannot be reconstructed from the database alone.
 
 Amalgm supplies a resolved authenticated principal from its user session or
 HMAC-refresh flow; future API keys resolve to the same principal capability.

package/README.md

@@ -99,6 +99,8 @@ Public webhook admission uses the URL returned on each webhook trigger:
 POST https://automations.amalgm.ai/e/<opaque-capability>
 ```
 
+That URL selects the exact trigger. Provider source and event labels are
+recorded as occurrence metadata, not used as another routing condition.
 `Idempotency-Key` and common provider delivery-id headers deduplicate retries
 against the same trigger. The caller never supplies a user or target id.
 

package/dist/src/automations.js

@@ -1,5 +1,5 @@
 import { nextCronAt } from './schedule.js';
-import { eventReferences, matchesEvent, verifyEventSecret } from './webhook.js';
+import { eventReferences, verifyEventSecret } from './webhook.js';
 const noop = () => { };
 export class EventRejectedError extends Error {
     constructor() {
@@ -33,14 +33,7 @@ export class Automations {
         const references = input.source && input.event
             ? { primary: { source: input.source, event: input.event } }
             : eventReferences(input.headers, input.payload);
-        let reference = references.primary;
-        let matches = matchesEvent(trigger, reference.source, reference.event);
-        if (!matches && references.fallback) {
-            reference = references.fallback;
-            matches = matchesEvent(trigger, reference.source, reference.event);
-        }
-        if (!matches)
-            return { run: null, ...reference };
+        const reference = references.primary;
         const now = input.now || new Date();
         const runInput = { kind: 'event', ...reference, payload: input.payload };
         const run = await this.store.enqueueEvent(trigger, runInput, now, input.deliveryKey);

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.3",
+  "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.