@relayflows/sdk 2.0.30 → 2.0.31

package/dist/worker.d.ts

@@ -9,6 +9,14 @@ export interface AgentWorkerOptions {
     requiredStreams?: string[];
     dataDir?: string;
     onPtyReady?: (path: string) => void;
+    /**
+     * The run root a step's declared `cwd` is resolved against and held inside.
+     * Defaults to this process's working directory, which is what the run root
+     * is: `flows run` attaches the worker from the directory it was invoked in,
+     * and that directory is the uploaded tree on the Cloud path. Named here so
+     * the root a dispatch is measured against is a value, not an assumption.
+     */
+    runRoot?: string;
 }
 /**
  * Executes dispatched agent steps using their declared CLI.

package/dist/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,IAAI,EAAqB,MAAM,eAAe,CAAC;AAU7D,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAY,SAAQ,YAAY;IAMzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;gBAGvC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,kBAAkB;IAKxC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB7B;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAQzB;YAEY,OAAO;CAmFtB;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAa9E"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,IAAI,EAAqB,MAAM,eAAe,CAAC;AAW7D,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAY,SAAQ,YAAY;IAMzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;gBAGvC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,kBAAkB;IAKxC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB7B;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAQzB;YAEY,OAAO;CA0FtB;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAa9E"}

package/dist/worker.js

@@ -2,6 +2,7 @@ import { communicationInstruction } from './communication/spec.js';
 import { workerSpend } from './worker-spend.js';
 import { EventEmitter } from 'node:events';
 import { runAgentCli } from './worker-cli.js';
+import { agentStepCwd } from './agent-cwd.js';
 import { resolveCliModel } from './cli-adapter.js';
 import { withWorkerLease } from './worker-lease.js';
 import { workerInstruction } from './worker-input.js';
@@ -77,7 +78,7 @@ export class AgentWorker extends EventEmitter {
         if (dispatch.step_type !== 'agent')
             return;
         const running = this.execute(dispatch).catch((error) => {
-            this.emit('error', error);
+            this.emit('error', error, dispatch);
         });
         this.inFlight.add(running);
         void running.finally(() => { this.inFlight.delete(running); });
@@ -96,18 +97,25 @@ export class AgentWorker extends EventEmitter {
             if (!this.options.dataDir)
                 throw new Error('Agent communication requires a worker data directory');
             const { completeCommunicationDispatch } = await import('./communication/worker.js');
-            await completeCommunicationDispatch(this.client, dispatch, communication, this.options.dataDir);
+            await completeCommunicationDispatch(this.client, dispatch, communication, this.options.dataDir, this.options.runRoot);
             return;
         }
         let humanIntervention = false;
         const effectiveModel = typeof spec.cli === 'string' ? resolveCliModel(spec.cli, spec.model) : spec.model;
-        const completed = await withWorkerLease(this.client, dispatch, signal => typeof spec.cli === 'string' && typeof spec.instruction === 'string'
-            ? runAgentCli(spec.cli, workerInstruction(spec.instruction, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
-                dataDir: this.options.dataDir, runId: dispatch.run_id, stepId: dispatch.step_id, attempt: dispatch.attempt,
-                onReady: this.options.onPtyReady, onDrive: () => { humanIntervention = true; },
-            }, typeof spec.cwd === 'string' ? spec.cwd : undefined, spec.transport === 'relay' ? 'relay' : 'direct', { runId: dispatch.run_id, stepId: dispatch.step_id, idempotencyKey: dispatch.idempotency_key,
-                dataDir: this.options.dataDir, resultSchema: spec.verification?.json_schema })
-            : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
+        // Resolved here, before the lease, because this is the process that shares
+        // the agent's filesystem. A refusal completes the step the way a missing
+        // CLI does — journaled as `worker_error` with the reason — rather than
+        // spawning into a directory nobody established is inside the run root.
+        const cwd = agentStepCwd(spec, dispatch.step_id, this.options.runRoot);
+        const completed = await withWorkerLease(this.client, dispatch, signal => 'refusal' in cwd
+            ? Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: cwd.refusal })
+            : typeof spec.cli === 'string' && typeof spec.instruction === 'string'
+                ? runAgentCli(spec.cli, workerInstruction(spec.instruction, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
+                    dataDir: this.options.dataDir, runId: dispatch.run_id, stepId: dispatch.step_id, attempt: dispatch.attempt,
+                    onReady: this.options.onPtyReady, onDrive: () => { humanIntervention = true; },
+                }, cwd.directory ?? (spec.transport === 'relay' ? undefined : this.options.runRoot), spec.transport === 'relay' ? 'relay' : 'direct', { runId: dispatch.run_id, stepId: dispatch.step_id, idempotencyKey: dispatch.idempotency_key,
+                    dataDir: this.options.dataDir, resultSchema: spec.verification?.json_schema })
+                : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
         const { result, usage } = workerSpend(completed, effectiveModel);
         const completionReason = result.exit_code === 0 ? 'success' : 'worker_error';
         // Output shape: if the CLI's stdout parses as JSON, promote THAT

package/dist/worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAyB,MAAM,uBAAuB,CAAC;AAEzG,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAW9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,WAAY,SAAQ,YAAY;IAMxB;IACA;IANX,QAAQ,GAAG,KAAK,CAAC;IACjB,OAAO,GAAG,KAAK,CAAC;IACP,QAAQ,GAAuB,IAAI,GAAG,EAAE,CAAC;IAE1D,YACmB,MAAqB,EACrB,OAA2B;QAE5C,KAAK,EAAE,CAAC;QAHS,WAAM,GAAN,MAAM,CAAe;QACrB,YAAO,GAAP,OAAO,CAAoB;IAG9C,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACrE,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;QACvG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,eAAe,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAC5B,IAAI,CAAC,OAAO,CAAC,QAAQ,EACrB,CAAC,OAAO,CAAC,EACT,IAAI,CAAC,OAAO,CAAC,IAAI,EACjB,IAAI,CAAC,OAAO,CAAC,QAAQ,EACrB,IAAI,CAAC,OAAO,CAAC,eAAe,CAC7B,CAAC;YACF,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YAClD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACxB,CAAC;IAEgB,UAAU,GAAG,CAAC,QAA2B,EAAQ,EAAE;QAClE,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,QAAQ,CAAC,SAAS,KAAK,OAAO;YAAE,OAAO;QAC3C,MAAM,OAAO,GAAkB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YAC7E,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC;IAEM,KAAK,CAAC,OAAO,CAAC,QAA2B;QAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAgC,CAAC;QACvD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;YACxH,MAAM,sBAAsB,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAClF,OAAO;QACT,CAAC;QACD,MAAM,aAAa,GAAG,wBAAwB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACjE,IAAI,aAAa,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;YACnG,MAAM,EAAE,6BAA6B,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;YACpF,MAAM,6BAA6B,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAChG,OAAO;QACT,CAAC;QACD,IAAI,iBAAiB,GAAG,KAAK,CAAC;QAC9B,MAAM,cAAc,GAAG,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;QACzG,MAAM,SAAS,GAAoB,MAAM,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,CACvF,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ;YAClE,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;gBACzL,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO;gBAC1G,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,iBAAiB,GAAG,IAAI,CAAC,CAAC,CAAC;aAC/E,EAAE,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EACpD,IAAI,CAAC,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,EAC/C,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,CAAC,eAAe;gBAC1F,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,CAAC;YAClF,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,gCAAgC,EAAE,CAAC,CAAC,CAAC;QAC5G,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,WAAW,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACjE,MAAM,gBAAgB,GAAG,MAAM,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC;QAE7E,iEAAiE;QACjE,6DAA6D;QAC7D,+DAA+D;QAC/D,4DAA4D;QAC5D,8DAA8D;QAC9D,+DAA+D;QAC/D,6DAA6D;QAC7D,mCAAmC;QACnC,EAAE;QACF,kEAAkE;QAClE,4DAA4D;QAC5D,+DAA+D;QAC/D,6DAA6D;QAC7D,EAAE;QACF,wEAAwE;QACxE,0EAA0E;QAC1E,0EAA0E;QAC1E,yEAAyE;QACzE,wEAAwE;QACxE,yEAAyE;QACzE,uEAAuE;QACvE,6EAA6E;QAC7E,EAAE;QACF,2EAA2E;QAC3E,uEAAuE;QACvE,kEAAkE;QAClE,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,SAAS,KAAK,CAAC;YAChF,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC;QAC9E,MAAM,cAAc,GAAG;YACrB,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE;oBACvD,aAAa,EAAE,MAAM,CAAC,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM;oBAChF,cAAc,EAAE,MAAM,CAAC,UAAU,CAAC,cAAc,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,KAAK;iBACjF,EAAE,CAAC;YACJ,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,gBAAgB,CAAC,UAAU,EAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC;SAC5G,CAAC;QAEF,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAC5B,QAAQ,CAAC,MAAM,EACf,QAAQ,CAAC,OAAO,EAChB,QAAQ,CAAC,OAAO,EAChB,QAAQ,CAAC,eAAe,EACxB,gBAAgB,EAChB;YACE,MAAM;YACN,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC;YACxF,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,YAAY,EAAE,QAAQ,CAAC,IAAI;YAC3B,QAAQ,EAAE,QAAQ,CAAC,IAAI;SACxB,CACF,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,UAA4B,EAAE,OAAe,EAAE,MAAuB;IAC9F,OAAO,qBAAqB,CAAC;QAC3B,OAAO;QACP,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,GAAG,UAAU;QACb,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE;gBACrD,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC;aACrF,EAAE,CAAC;KACL,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.30",
+  "version": "2.0.31",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,8 +49,9 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@relayfile/adapter-core": "0.6.2",
     "@relayfile/relay-helpers": "0.4.12",
-    "@relayflows/surface": "2.0.30",
+    "@relayflows/surface": "2.0.31",
     "@types/js-yaml": "^4.0.9",
+    "acorn": "^8.18.0",
     "ai-hist": "0.4.1",
     "ajv": "^8.17.1",
     "ajv-draft-04": "^1.0.0",
@@ -80,10 +81,5 @@
     "@agent-relay/sdk": {
       "optional": true
     }
-  },
-  "overrides": {
-    "@relayflows/surface": {
-      "@relayfile/relay-helpers": "$@relayfile/relay-helpers"
-    }
   }
 }

package/src/agent-artifacts.ts

@@ -1,20 +1,12 @@
 import { createHash } from 'node:crypto';
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
+import { isUnscannedEntryName } from './artifact-scan-policy.js';
 
 function isEnoent(error: unknown): boolean {
   return error instanceof Error && (error as NodeJS.ErrnoException).code === 'ENOENT';
 }
 
-/**
- * Entry names never walked and never reported, matched exactly, at any depth,
- * before the entry's type is consulted — so a `.git` *file* (a worktree's
- * gitdir pointer) is skipped as surely as a `.git` directory. Exact names, not
- * prefixes: `.github`, `.relayflowd-notes` and every other author-chosen name
- * that merely starts the same way stays eligible.
- */
-const SKIPPED_ENTRY_NAMES = new Set(['.git', '.relayflowd', 'node_modules']);
-
 /**
  * A recursive snapshot of every regular file under `dir`, keyed by its
  * `dir`-relative POSIX path, valued by a content signature (size + sha256).
@@ -55,7 +47,7 @@ async function walk(root: string, current: string, out: Map<string, string>): Pr
     throw error;
   }
   for (const entry of entries) {
-    if (SKIPPED_ENTRY_NAMES.has(entry.name)) continue;
+    if (isUnscannedEntryName(entry.name)) continue;
     const path = join(current, entry.name);
     if (entry.isDirectory()) {
       await walk(root, path, out);

package/src/agent-cwd.ts

@@ -0,0 +1,139 @@
+import { realpathSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+
+/**
+ * Where an agent step runs.
+ *
+ * A declared `cwd` is a path relative to the **run root** — the working
+ * directory of the process running the agent worker, which is the directory
+ * `flows run` was invoked from and, on the Cloud path, the uploaded tree
+ * (docs/CLOUD.md, "Code sync"). Absent, a step runs in the run root itself.
+ *
+ * Two checks, in two places, because they are two different facts:
+ *
+ * - The **declaration** is lexical and filesystem-free, so `flows check`, the
+ *   kernel's `validate()` and this worker all answer identically for the same
+ *   spec. `testdata/agent-cwd-cases.json` is the shared corpus both dialects
+ *   are tested against.
+ * - The **target** is resolved here, in the worker that spawns the CLI — the
+ *   one process provably sharing the agent's filesystem. A directory that
+ *   exists, and whose symlink-free path is inside the symlink-free run root.
+ *   Repeated at execution even when a preflight already passed, because the
+ *   filesystem moves underneath a spec.
+ *
+ * This contains a declaration; it does not sandbox an agent. Nothing stops a
+ * CLI from writing outside the directory it was started in. Per-step scoping
+ * is `permissions`, which is recorded and not enforced (gate 8 / #442).
+ */
+export class AgentCwdError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AgentCwdError';
+  }
+}
+
+/**
+ * Why a declared `cwd` is not a run-root-relative path, or `undefined` when it
+ * is one. Pure and lexical: the exact rule
+ * `relayflowd_core::spec::is_run_root_relative_path` applies at the kernel
+ * boundary, so a declaration that passes `flows check` is not refused later by
+ * the daemon for its shape.
+ */
+export function agentCwdDeclarationError(cwd: unknown): string | undefined {
+  const expected = 'expected a run-root-relative path';
+  if (typeof cwd !== 'string') return `${expected} (got ${cwd === null ? 'null' : typeof cwd})`;
+  if (cwd === '') return `${expected}, not an empty string`;
+  if (PADDING.test(cwd)) return `${expected} without surrounding whitespace`;
+  if (cwd.includes('\0')) return `${expected} without NUL`;
+  if (cwd.startsWith('/')) return `${expected}, not an absolute path`;
+  if (cwd.includes('://')) return `${expected}, not a URI-like mount identity`;
+  if (cwd.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+    return `${expected} without empty, "." or ".." components`;
+  }
+  return undefined;
+}
+
+/**
+ * Whitespace at either end, spelled so both dialects refuse the same set.
+ * JavaScript's `\s` is Unicode `White_Space` without U+0085 and with U+FEFF;
+ * Rust's `char::is_whitespace` is `White_Space` exactly. Naming U+0085 here
+ * and U+FEFF there makes both `White_Space ∪ {U+FEFF}`. Left to `trim()`
+ * alone, a path padded with either character would pass `flows check` and be
+ * refused by the kernel — the accept-then-refuse split this contract closes.
+ */
+const PADDING = /^[\s\u0085]|[\s\u0085]$/u;
+
+/**
+ * The refusal for a `cwd` declared on a step dispatched over the relay
+ * transport, or `undefined` when there is nothing to refuse.
+ *
+ * The relay agent runs on another host. This process can neither resolve that
+ * host's filesystem nor establish that the directory is inside that run's
+ * tree, and forwarding the string as `worker_cwd` would let a declaration this
+ * contract promises to contain go unchecked. Fail closed instead of pretending.
+ */
+export function agentCwdTransportError(cwd: unknown, transport: unknown): string | undefined {
+  if (cwd === undefined || transport !== 'relay') return undefined;
+  return 'cwd is not supported with transport "relay": the agent runs on another host, '
+    + 'where this worker cannot resolve the directory or hold it inside the run root';
+}
+
+/**
+ * The directory to spawn the CLI in: `root` when nothing is declared, else the
+ * symlink-free directory `cwd` names beneath `root`.
+ *
+ * @throws AgentCwdError naming the declaration and what is wrong with it.
+ */
+export function resolveAgentCwd(root: string, cwd: unknown, transport?: unknown): string | undefined {
+  if (cwd === undefined) return undefined;
+  const refusal = (detail: string): AgentCwdError =>
+    new AgentCwdError(`cwd ${JSON.stringify(cwd)}: ${detail}`);
+  const declaration = agentCwdDeclarationError(cwd);
+  if (declaration !== undefined) throw refusal(declaration);
+  const unsupported = agentCwdTransportError(cwd, transport);
+  if (unsupported !== undefined) throw new AgentCwdError(unsupported);
+
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    throw refusal(`the run root ${JSON.stringify(root)} cannot be resolved on this host`);
+  }
+  let target: string;
+  try {
+    target = realpathSync(resolve(realRoot, cwd as string));
+  } catch {
+    throw refusal(`no such directory under the run root ${JSON.stringify(realRoot)}`);
+  }
+  // Component-aware, on the symlink-free forms of both: `checkout-b-old` is
+  // not inside `checkout-b`, and a symlink pointing out of the tree is not
+  // inside it either however it is spelled.
+  const prefix = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  if (target !== realRoot && !target.startsWith(prefix)) {
+    throw refusal(`resolves to ${JSON.stringify(target)}, outside the run root ${JSON.stringify(realRoot)}`);
+  }
+  if (!statSync(target).isDirectory()) throw refusal(`${JSON.stringify(target)} is not a directory`);
+  return target;
+}
+
+/** Either the directory an agent step runs in, or why the step is refused. */
+export type AgentCwdOutcome = { directory: string | undefined } | { refusal: string };
+
+/**
+ * The dispatch-time form: resolve a dispatched agent step's `cwd` against the
+ * run root, or report the refusal for the worker to complete the step with.
+ * Reporting rather than throwing keeps the refusal on the step's completion —
+ * `worker_error`, with the reason journaled — instead of on the worker.
+ */
+export function agentStepCwd(
+  spec: { cwd?: unknown; transport?: unknown },
+  stepId: string,
+  root: string = process.cwd(),
+): AgentCwdOutcome {
+  try {
+    return { directory: resolveAgentCwd(root, spec.cwd, spec.transport) };
+  } catch (error) {
+    if (!(error instanceof AgentCwdError)) throw error;
+    return { refusal: `agent step "${stepId}": ${error.message}` };
+  }
+}

package/src/artifact-scan-policy.ts

@@ -0,0 +1,51 @@
+/**
+ * The bundled agent worker's artifact-scan policy, as a pure predicate.
+ *
+ * `agent-artifacts.ts` walks an agent step's cwd and records every regular
+ * file it finds, except entries named exactly `.git`, `.relayflowd` or
+ * `node_modules` — files as well as directories, in both cases. Dotfiles and
+ * dot-directories ARE eligible: `.workflow-artifacts/` is the conventional
+ * place a flow tells its agents to write. What that walk records is one
+ * source of the journaled `output.artifacts` list, which is the only thing an
+ * `artifact_exists` gate reads (`named-gate-lowering.ts` tests exact
+ * membership in that list and never touches disk).
+ *
+ * Static analysis needs the same rule without importing filesystem traversal,
+ * so the rule lives here and both consume it. It bounds the *scan*, not the
+ * list: `worker.ts` journals object-shaped JSON stdout and completed Relay
+ * task output verbatim instead of the scanned wrapper, and
+ * `JournalClient.stepComplete` accepts any `output` from any worker — so a
+ * path this predicate excludes can still reach the list by those routes
+ * (`named-gate-preflight.ts` warns rather than refusing for exactly that
+ * reason).
+ */
+
+/**
+ * Entry names the walk never descends into or records, matched exactly, at
+ * any depth, before the entry's type is consulted — so a `.git` *file* (a
+ * worktree's gitdir pointer) is skipped as surely as a `.git` directory.
+ * Exact names, not prefixes: `.github`, `.relayflowd-notes` and every other
+ * author-chosen name that merely starts the same way stays eligible.
+ */
+const SKIPPED_ENTRY_NAMES = new Set(['.git', '.relayflowd', 'node_modules']);
+
+export function isUnscannedEntryName(name: string): boolean {
+  return SKIPPED_ENTRY_NAMES.has(name);
+}
+
+/**
+ * The shortest `/`-prefix of a relative POSIX `path` the scan excludes, or
+ * `undefined` when every segment is scanned.
+ *
+ * Segments are compared exactly, with no normalization: the gate matches the
+ * author's literal string against the worker's literal list, so `node_modules`
+ * is excluded and `node_modules-copy` is not, and a backslash is an ordinary
+ * filename character rather than a separator. The whole prefix is returned,
+ * not the offending segment alone, because that prefix is the directory an
+ * author has to move the artifact out of.
+ */
+export function unscannedArtifactPrefix(path: string): string | undefined {
+  const segments = path.split('/');
+  const index = segments.findIndex(isUnscannedEntryName);
+  return index === -1 ? undefined : segments.slice(0, index + 1).join('/');
+}

package/src/authored-completion-record.ts

@@ -0,0 +1,119 @@
+// The authored verdict, written to the root BEFORE the marker is admitted.
+//
+// The terminal marker's command embeds the detail, and the marker run is
+// opened under a stable admission key (`authored-child:<hash(root, step)>`).
+// Those two facts together mean the detail has to be a durable decision, not a
+// recomputed one: normalization redacts against `process.env`, so a credential
+// rotated or removed while this process was down makes the SAME authored
+// sentence normalize differently. A body resumed into that environment would
+// retry the marker's admission key with a drifted spec, and the kernel refuses
+// that as `run_admission_conflict` — losing an explanation the root had
+// already journaled, for a flow whose every step succeeded.
+//
+// So the verdict is appended to a stream on the root run before the marker run
+// is opened, and a later attempt reaching the same terminal step reuses what
+// is recorded. That is exactly the durability the executor already gives a
+// predicate gate (`applyPredicateGate`): record the decision first, so the
+// spec built from it is identical on every attempt and author code is never
+// asked the question twice.
+//
+// Nothing is recorded for a `done()` with no detail. Without one the marker
+// command is a function of the reason alone — no environment, no drift, and
+// nothing to recover — so a flow that does not opt in writes exactly the
+// journal it has always written.
+
+import {
+  isDurableCompletionDetail,
+  isLoweredCompletion,
+  type LoweredCompletionReason,
+} from './authored-completion.js';
+import type { JournalClient } from './journal-client.js';
+
+export const AUTHORED_VERDICT_STREAM = 'authored-verdict';
+
+/** Versioned so a reader can tell this record from a future one. */
+const RECORD_KIND = 'relayflows.authored-verdict.v1';
+
+export interface AuthoredVerdictRecord {
+  readonly reason: LoweredCompletionReason;
+  /** Recorded only when the body passed one; see the module comment. */
+  readonly detail?: string;
+}
+
+/**
+ * Commit this body's verdict, or recover the one this root already committed.
+ *
+ * Returns the verdict the marker must be built from — the recorded one when
+ * the root holds it, this attempt's otherwise. With no root run there is
+ * nothing durable to write to (the non-durable executor seam), so that path
+ * passes straight through without a round trip. A root run is always read
+ * first: a committed record stays authoritative even for an attempt that has
+ * no detail of its own — an optional source can be present on the first
+ * execution and gone on the retry, and "this attempt has no detail" is not
+ * "this root never recorded one". Only when no record exists AND this attempt
+ * has no detail does it return without appending, preserving the no-detail
+ * marker, spec hash, and journal exactly as before.
+ */
+export async function commitAuthoredVerdict(
+  journal: JournalClient,
+  rootRunId: string | undefined,
+  step: string,
+  verdict: AuthoredVerdictRecord,
+): Promise<AuthoredVerdictRecord> {
+  if (rootRunId === undefined) return verdict;
+  const committed = await readAuthoredVerdict(journal, rootRunId, step);
+  if (committed !== undefined) return committed;
+  if (verdict.detail === undefined) return verdict;
+  await journal.streamAppend(rootRunId, AUTHORED_VERDICT_STREAM, {
+    verdict: RECORD_KIND, step, reason: verdict.reason, detail: verdict.detail,
+  });
+  return verdict;
+}
+
+/**
+ * The verdict this root recorded for `step`, or `undefined`.
+ *
+ * The FIRST valid record wins: it is the one the marker was — or was about to
+ * be — admitted from, and a later attempt's differently-redacted text must not
+ * displace it. Records this version does not recognise, and details that fail
+ * the durable check every other read boundary applies, are skipped rather than
+ * trusted; the marker then drifts and the kernel refuses it loudly, which is
+ * the right outcome for a record this process cannot read.
+ */
+export async function readAuthoredVerdict(
+  journal: JournalClient,
+  rootRunId: string,
+  step: string,
+): Promise<AuthoredVerdictRecord | undefined> {
+  let offset = 0;
+  for (;;) {
+    const page = await journal.streamRead(rootRunId, AUTHORED_VERDICT_STREAM, offset, 1000);
+    for (const message of page.messages) {
+      // `stream.read` returns either the envelope or the bare message,
+      // matching how the executor reads predicate verdicts.
+      const raw = (message as { message?: unknown }).message ?? message;
+      if (isVerdictRecord(raw) && raw.step === step) {
+        return Object.freeze({ reason: raw.reason, detail: raw.detail });
+      }
+    }
+    if (page.messages.length === 0 || page.next_offset <= offset) break;
+    offset = page.next_offset;
+  }
+  return undefined;
+}
+
+interface StoredVerdict {
+  readonly verdict: typeof RECORD_KIND;
+  readonly step: string;
+  readonly reason: LoweredCompletionReason;
+  readonly detail: string;
+}
+
+function isVerdictRecord(value: unknown): value is StoredVerdict {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Partial<StoredVerdict>;
+  return record.verdict === RECORD_KIND
+    && typeof record.step === 'string' && record.step.length > 0
+    && isLoweredCompletion(record.reason)
+    && isDurableCompletionDetail(record.detail);
+}