@relayflows/sdk 2.0.15 → 2.0.17

package/src/spec.ts

@@ -82,7 +82,18 @@ export interface RegexMatchGate {
   flags?: string;
 }
 
-export type NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate;
+/**
+ * Passes when the step's journaled `output.artifacts` lists `path`: a file the
+ * agent's worker measured as created or changed under its working directory.
+ * Reads the journal, never the disk, so replay and resume see the same verdict.
+ */
+export interface ArtifactExistsGate {
+  type: 'artifact_exists';
+  /** Working-directory-relative POSIX path, as the worker journals it. */
+  path: string;
+}
+
+export type NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate | ArtifactExistsGate;
 export type OutputVerificationSpec = OutputContainsGate | JsonSchemaGate | NamedDataGate;
 export type VerificationSpec = ExitCodeGate | OutputVerificationSpec;
 

package/src/trigger-executor.ts

@@ -3,7 +3,7 @@ import type { TriggerSpec } from './spec.js';
 
 /** Lower a surface subscription to the existing inbox executor contract. */
 export function webhookTriggerSpec(id: string, source: TriggerSource): TriggerSpec {
-  if (source.kind !== 'webhook') throw new TypeError('unsupported trigger kind');
+  if (source.kind !== 'webhook') throw new TypeError('unsupported trigger kind: use scheduleTriggerSpec for schedule sources');
   const trigger = webhook(source.name, source.filter);
   return {
     id,

package/src/validate.ts

@@ -446,7 +446,7 @@ class Validator {
     } else if (Object.hasOwn(NAMED_GATE_KEYS, gate.type)) {
       for (const error of namedGateErrors(v, input, at)) this.fail(error);
     } else {
-      this.fail(`${at}.type: unknown_gate_kind: expected exit_code | output_contains | json_schema | references_input | subprocess_gate | word_count_bounds | regex_match`);
+      this.fail(`${at}.type: unknown_gate_kind: expected exit_code | output_contains | json_schema | references_input | subprocess_gate | word_count_bounds | regex_match | artifact_exists`);
     }
   }
 

package/src/worker-cli.ts

@@ -1,3 +1,5 @@
+import { resolve } from 'node:path';
+import { diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
 import { decodeProviderResult, decodeWrapperResult, requirePricedUsage } from './worker-usage.js';
 import { openSidechannel, type SidechannelContext } from './pty-sidechannel.js';
 import { spawn } from 'node:child_process';
@@ -38,6 +40,16 @@ export interface WorkerCliResult {
   exit_code: number | null;
   stdout_tail: string;
   stderr_tail: string;
+  /**
+   * Files the agent created or changed under its working directory,
+   * cwd-relative POSIX paths, sorted. Measured by the worker that spawned the
+   * CLI — the one process provably sharing the agent's filesystem — as a
+   * content-hash diff of the directory before and after the run, so it is a
+   * journaled fact rather than a later guess. Present for every direct agent
+   * execution; absent for `llm` mode and for the relay transport, where the
+   * agent runs on another host.
+   */
+  artifacts?: string[];
 }
 
 /**
@@ -75,6 +87,22 @@ export async function runAgentCli(
     return runViaAgentRelay(kind, instruction, wakeContext, effectiveModel, relayContext, cwd, signal);
   }
 
+  // Artifact detection brackets the spawn: the directory the CLI runs in is
+  // snapshotted before and diffed after, by this process, on this
+  // filesystem. Only an agent execution writes artifacts; an llm step has no
+  // workspace to change. Executions sharing a working directory are
+  // serialized around their snapshot-spawn-snapshot interval, so one agent's
+  // writes are never attributed to a concurrent one in the same directory.
+  const artifactRoot = mode === 'agent' ? resolve(cwd ?? process.cwd()) : undefined;
+  return artifactRoot === undefined
+    ? execute()
+    : serializedByDirectory(artifactRoot, async () => {
+      const before = await snapshotWorkspaceFiles(artifactRoot);
+      const result = await execute();
+      return { ...result, artifacts: diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot)) };
+    });
+
+  async function execute(): Promise<WorkerCliResult> {
   if (kind === 'relayflows-wrapper-v1') {
     return requirePricedUsage(decodeWrapperResult(await runWrapperSession(
       cli,
@@ -84,6 +112,7 @@ export async function runAgentCli(
       wrapperEnvironment(process.env),
       wrapperLimits,
       signal,
+      cwd,
     )), effectiveModel);
   }
 
@@ -109,6 +138,18 @@ export async function runAgentCli(
   const args = [...invocation.args];
   args.splice(args.length - 1, 0, ...(kind === 'claude' ? ['--output-format', 'json'] : ['--json']));
   return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd), kind), effectiveModel);
+  }
+}
+
+/** One agent at a time per canonical working directory, for the artifact interval. */
+const directoryQueues = new Map<string, Promise<unknown>>();
+function serializedByDirectory<T>(directory: string, task: () => Promise<T>): Promise<T> {
+  const previous = directoryQueues.get(directory) ?? Promise.resolve();
+  const run = previous.then(task, task);
+  const settled = run.then(() => undefined, () => undefined);
+  directoryQueues.set(directory, settled);
+  void settled.then(() => { if (directoryQueues.get(directory) === settled) directoryQueues.delete(directory); });
+  return run;
 }
 
 /** Wait under the same worker lease for an authoritative task receipt. */

package/src/worker.ts

@@ -133,6 +133,15 @@ export class AgentWorker extends EventEmitter {
     // emitting an error JSON with exit 0. `completionReason` is
     // derived from exit code, so a CLI that exits 0 while emitting
     // `{"error":...}` will report success with an error payload.
+    //
+    // `artifacts` (worker-cli.ts) rides inside the CliResult wrapper, so on
+    // the wrapper path it is journaled in `output`, where the kernel's output
+    // binding — and therefore an `artifact_exists` gate — can read it. On the
+    // JSON path the author's object IS the output and is left exactly as the
+    // agent emitted it: no key is added that a schema, a downstream binding
+    // or `summary` never asked for. An agent that answers with a JSON object
+    // therefore journals no artifacts; gate such a step on a deterministic
+    // check instead. The relay transport reports none (the agent ran elsewhere).
     const output = result.relay_task?.status === 'completed' && result.exit_code === 0
       ? result.relay_task.output : parseJsonOutput(result.stdout_tail) ?? result;
 

package/src/wrapper-session.ts

@@ -49,6 +49,8 @@ export function runWrapperSession(
   env: NodeJS.ProcessEnv,
   overrides: Partial<WrapperSessionLimits> = {},
   signal?: AbortSignal,
+  /** Working directory for the wrapper process; the artifact scanner uses the same root. */
+  cwd?: string,
 ): Promise<WrapperSessionResult> {
   if (signal?.aborted) return Promise.reject(signal.reason);
   if (signal !== undefined && process.platform === 'win32') {
@@ -77,7 +79,7 @@ export function runWrapperSession(
     ));
   }
 
-  return executePinnedWrapper(cli, identity, request, env, limits, signal);
+  return executePinnedWrapper(cli, identity, request, env, limits, signal, cwd);
 }
 
 function executePinnedWrapper(
@@ -87,6 +89,7 @@ function executePinnedWrapper(
   env: NodeJS.ProcessEnv,
   limits: WrapperSessionLimits,
   signal?: AbortSignal,
+  cwd?: string,
 ): Promise<WrapperSessionResult> {
   return new Promise((resolve) => {
     const ownsGroup = ownsProcessGroup(signal);
@@ -94,6 +97,7 @@ function executePinnedWrapper(
       stdio: ['pipe', 'pipe', 'pipe'],
       env,
       detached: ownsGroup,
+      ...(cwd === undefined ? {} : { cwd }),
     });
     const stop = childStop(child, ownsGroup);
     const stdout: string[] = [];