@automatalabs/workflows 0.5.0 → 0.6.0

package/README.md

@@ -177,6 +177,14 @@ return value.
 > programmatic option wins per name). A `schema` is forwarded to custom backends as turn-level
 > `_meta.outputSchema` and the result is JSON-parsed off the final message — agents that ignore the
 > schema channel still work via the validate/re-prompt ladder.
+>
+> A workflow **script** can also declare backends itself via `meta.backends` (same config shape,
+> keyed by name). Because script-declared backends spawn commands on your machine, they are inert
+> unless you approve them: pass `allowScriptBackends: true` to `runDynamicWorkflow`, or a callback
+> `(backend) => boolean | Promise<boolean>` to decide per backend — an unapproved declaration
+> throws with guidance, and a declined backend aborts the run (it would otherwise silently reroute
+> its `agent()` calls to the default backend). Host-registered names always win over script
+> declarations. Lower-level callers can thread a pre-approved registry via `exec.scriptBackends`.
 
 ### c) `WorkflowManager` — stateful / resumable runs
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { ExecOptions } from "@automatalabs/workflow-engine";
-import type { AgentRunner, WorkflowRunResult } from "@automatalabs/shared-types";
+import type { AgentRunner, WorkflowBackendConfig, WorkflowRunResult } from "@automatalabs/shared-types";
 export { runWorkflow, parseWorkflowScript, WorkflowManager } from "@automatalabs/workflow-engine";
 export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot, } from "@automatalabs/workflow-engine";
 export { WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
@@ -8,7 +8,19 @@ export type { AcpPoolOptions, AcpRunnerOptions, BackendRegistry, CustomBackendCo
 export { TypedEventEmitter } from "@automatalabs/acp-agents";
 export type { AcpRunnerEventMap, AcpEventName, AcpEventListener, AcpEventContext, AcpSessionUpdate, AcpUpdateKind, AcpPermissionEvent, AcpRawMessageEvent, AcpBackendErrorEvent, } from "@automatalabs/acp-agents";
 export type { AgentRunner, RunOptions, AgentResult, AgentUsage } from "@automatalabs/shared-types";
-export type { JournalEntry } from "@automatalabs/shared-types";
+export type { JournalEntry, WorkflowBackendConfig, WorkflowMeta } from "@automatalabs/shared-types";
+/**
+ * Approval policy for SCRIPT-DECLARED custom ACP backends (`meta.backends`). Script backends
+ * spawn arbitrary commands on this machine, so they are INERT unless the embedder approves
+ * them: `true` approves everything the script declares; a callback is asked per backend (and
+ * a single decline aborts the run — a declined backend would otherwise silently reroute its
+ * agent() calls to the default backend). Omitted/false + a script that declares backends =>
+ * runDynamicWorkflow THROWS with guidance rather than running a script whose declared
+ * dependencies were dropped.
+ */
+export type ScriptBackendApproval = boolean | ((backend: {
+    name: string;
+} & WorkflowBackendConfig) => boolean | Promise<boolean>);
 /** Options for {@link runDynamicWorkflow}. */
 export interface RunDynamicWorkflowOptions {
     /**
@@ -21,6 +33,8 @@ export interface RunDynamicWorkflowOptions {
     args?: unknown;
     /** Per-execution options forwarded to `WorkflowManager.runSync` (timeouts, signal, budget, …). */
     exec?: ExecOptions;
+    /** Approval policy for script-declared `meta.backends` (see {@link ScriptBackendApproval}). */
+    allowScriptBackends?: ScriptBackendApproval;
 }
 /**
  * Run a dynamic workflow script to a TERMINAL result, with the AgentRunner seam

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIjF,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAClG,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAOvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACnG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kGAAkG;IAClG,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAE5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIxG,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAClG,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAOvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACnG,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAEpG;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAC7B,OAAO,GACP,CAAC,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,qBAAqB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAExF,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kGAAkG;IAClG,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,+FAA+F;IAC/F,mBAAmB,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAe5B"}

package/dist/index.js

@@ -10,7 +10,7 @@
 // vm-realm globals, NOT importable symbols; they are documented for author IntelliSense
 // in ./dsl.d.ts (referenced above), not exported here.
 import { createAcpRunner } from "@automatalabs/acp-agents";
-import { WorkflowManager } from "@automatalabs/workflow-engine";
+import { parseWorkflowScript, WorkflowError, WorkflowErrorCode, WorkflowManager } from "@automatalabs/workflow-engine";
 // ── Engine: run entry, script parsing, the managed-run lifecycle, and the
 //    option/result + error types the host composes against. ──
 export { runWorkflow, parseWorkflowScript, WorkflowManager } from "@automatalabs/workflow-engine";
@@ -36,6 +36,39 @@ export { TypedEventEmitter } from "@automatalabs/acp-agents";
  * `WorkflowRunResult` (status `completed | paused | failed | aborted`) — never throwing
  * for an ordinary pause/fail — so the caller can read `result.status` directly.
  */
-export function runDynamicWorkflow(script, opts = {}) {
-    return new WorkflowManager({ agent: opts.runner ?? createAcpRunner() }).runSync(script, opts.args, opts.exec);
+export async function runDynamicWorkflow(script, opts = {}) {
+    // Script-declared backends need explicit approval BEFORE the run. A malformed script is
+    // deliberately not diagnosed here — runSync re-parses and throws the engine's own parse
+    // error (its pre-existing contract), so the approval gate never masks a parse message.
+    let declared;
+    try {
+        declared = parseWorkflowScript(script).meta.backends;
+    }
+    catch {
+        declared = undefined;
+    }
+    let exec = opts.exec;
+    if (declared && Object.keys(declared).length > 0) {
+        exec = { ...(exec ?? {}), scriptBackends: await approveScriptBackends(declared, opts.allowScriptBackends) };
+    }
+    return new WorkflowManager({ agent: opts.runner ?? createAcpRunner() }).runSync(script, opts.args, exec);
+}
+/** Resolve the embedder's approval policy over the declared backends; throw with guidance when
+ *  approval is missing or any backend is declined (an unapproved dependency must abort, never
+ *  silently reroute). */
+async function approveScriptBackends(declared, approval) {
+    const names = Object.keys(declared).join(", ");
+    if (approval === undefined || approval === false) {
+        throw new WorkflowError(`script declares custom ACP backends (meta.backends: ${names}) — these spawn commands on this machine and require explicit approval. ` +
+            `Pass allowScriptBackends: true (or a per-backend approval callback) to runDynamicWorkflow, ` +
+            `or thread an approved registry yourself via exec.scriptBackends.`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
+    }
+    if (approval === true)
+        return declared;
+    for (const [name, config] of Object.entries(declared)) {
+        if (!(await approval({ name, ...config }))) {
+            throw new WorkflowError(`script backend "${name}" (command: ${config.command}) was declined by the allowScriptBackends callback — aborting the run`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
+        }
+    }
+    return declared;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/workflows",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -24,9 +24,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@automatalabs/shared-types": "0.4.0",
-    "@automatalabs/workflow-engine": "0.2.0",
-    "@automatalabs/acp-agents": "0.5.0"
+    "@automatalabs/shared-types": "0.5.0",
+    "@automatalabs/workflow-engine": "0.3.0",
+    "@automatalabs/acp-agents": "0.6.0"
   },
   "scripts": {
     "build": "tsc -b",