@relayflows/sdk 2.0.9 → 2.0.11

package/src/cloud-run.ts

@@ -0,0 +1,137 @@
+import { RUN_COMPLETION_REASONS } from '@relayflows/surface';
+import type { RunCompletionReason } from './protocol.js';
+import { readFile } from 'node:fs/promises';
+import { setTimeout } from 'node:timers/promises';
+import { parse as parseYaml } from 'yaml';
+import { canonicalize, specHash } from './canonical.js';
+import { CompileError, compileSpec, kernelToAuthoring, toKernelSpec } from './compile.js';
+import type { FlowSpec } from './spec.js';
+import {
+  CloudFlowError, cloudConnection, cloudRequest, cloudRunId, isCloudRecord,
+  type CloudConnectionOptions,
+} from './cloud-http.js';
+
+export type CloudFlowSource = FlowSpec | { path: string };
+export interface RunInCloudOptions extends CloudConnectionOptions {
+  /** Existing Cloud workspace to run in; provisioning/authorization remains server-side. */
+  workspaceId?: string;
+}
+export interface CloudRunReceipt {
+  runId: string;
+  status: 'pending' | 'running';
+  /** Local correlation hash of the compiled spec; NOT server attestation or a sealed bundle digest. */
+  specHash: string;
+  /** Authenticated run API resource; this is not a public sharing URL. */
+  apiUrl: string;
+}
+export type CloudRunState =
+  | { runId: string; status: 'pending' | 'running' }
+  | { runId: string; status: 'completed' | 'failed' | 'cancelled'; completionReason: RunCompletionReason };
+
+/**
+ * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
+ * happens here; Cloud owns provisioning and the Rust engine owns execution.
+ * Returns acceptance, not completion. No local daemon, CLI probe, or node up.
+ */
+export async function runInCloud(
+  flow: CloudFlowSource,
+  options: RunInCloudOptions = {},
+): Promise<CloudRunReceipt> {
+  const { baseUrl } = cloudConnection(options);
+  let spec: FlowSpec;
+  try {
+    options.signal?.throwIfAborted();
+    if ('path' in flow) {
+      if (!/\.(?:ya?ml|json)$/iu.test(flow.path)) {
+        throw new CloudFlowError('unsupported_source',
+          'Cloud v2 currently accepts declarative YAML or JSON specs; authored TypeScript flows are not supported by the hosted runtime.');
+      }
+      const parsed: unknown = parseYaml(await readFile(flow.path, 'utf8'));
+      try {
+        spec = compileSpec(parsed);
+      } catch (error) {
+        if (!(error instanceof CompileError)) throw error;
+        // Prefer the authoring dialect; accept compiled kernel JSON for local-CLI
+        // compatibility. If both fail, retain the original authoring diagnostic.
+        try {
+          spec = compileSpec(kernelToAuthoring(parsed));
+        } catch {
+          throw error;
+        }
+      }
+    } else {
+      spec = compileSpec(flow);
+    }
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    if (error instanceof CloudFlowError) throw error;
+    throw new CloudFlowError('invalid_input', 'Cannot read or compile the declarative flow. Check the file path and YAML/JSON spec.');
+  }
+  options.signal?.throwIfAborted();
+  const hash = specHash(toKernelSpec(spec));
+  const result = await cloudRequest('/api/v1/workflows/run', options, {
+    // JSON is a YAML subset. Sending canonical data preserves the exact spec
+    // while using the server's existing YAML-to-config admission path.
+    workflow: canonicalize(spec),
+    fileType: 'yaml',
+    relayflowVersion: 'v2',
+    ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+  });
+  if (!isCloudRecord(result) || (result.status !== 'pending' && result.status !== 'running')) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return an accepted run.');
+  }
+  const runId = cloudRunId(result.runId);
+  return { runId, status: result.status, specHash: hash, apiUrl: `${baseUrl}/api/v1/workflows/runs/${runId}` };
+}
+
+export async function getCloudFlowRun(
+  runId: string,
+  options: CloudConnectionOptions = {},
+): Promise<CloudRunState> {
+  cloudRunId(runId);
+  const result = await cloudRequest(`/api/v1/workflows/runs/${runId}`, options);
+  if (!isCloudRecord(result) || result.runId !== runId || result.relayflowVersion !== 'v2'
+    || typeof result.status !== 'string'
+    || !['pending', 'running', 'completed', 'failed', 'cancelled'].includes(result.status)) {
+    throw new CloudFlowError('invalid_response', 'Cloud returned an invalid v2 run record.');
+  }
+  if (result.status === 'pending' || result.status === 'running') return { runId, status: result.status };
+  const report = result.result;
+  const reason = isCloudRecord(report) ? report.completionReason : undefined;
+  if (typeof reason !== 'string' || !(RUN_COMPLETION_REASONS as readonly string[]).includes(reason)
+    || (result.status === 'completed' && (reason !== 'success' || !isCloudRecord(report) || report.ok !== true || report.status !== 'completed'))
+    || (result.status === 'failed' && !['step_failed', 'budget_exceeded'].includes(reason))
+    || (result.status === 'cancelled' && reason !== 'canceled')) {
+    throw new CloudFlowError('invalid_response', 'Cloud terminal record lacks a valid, consistent run completionReason; no execution outcome is attested.');
+  }
+  return { runId, status: result.status as 'completed' | 'failed' | 'cancelled', completionReason: reason as RunCompletionReason };
+}
+
+/** Wait without a fixed execution deadline. Abort stops observation, not the hosted run. */
+export async function waitForCloudFlowRun(
+  runId: string,
+  options: CloudConnectionOptions & { pollIntervalMs?: number } = {},
+): Promise<CloudRunState> {
+  const interval = options.pollIntervalMs ?? 2_000;
+  if (!Number.isSafeInteger(interval) || interval < 1 || interval > 60_000) {
+    throw new CloudFlowError('configuration', 'pollIntervalMs must be an integer from 1 to 60000.');
+  }
+  let failures = 0;
+  for (;;) {
+    options.signal?.throwIfAborted();
+    try {
+      const run = await getCloudFlowRun(runId, options);
+      failures = 0;
+      if (run.status !== 'pending' && run.status !== 'running') return run;
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      const transient = error instanceof CloudFlowError && (error.code === 'transient_error'
+        || (error.code === 'http_error' && [408, 429, 500, 502, 503, 504].includes(error.status ?? 0)));
+      if (!transient) throw error;
+      // Only safe GET observation retries. Delay caps at 30s; no overall run deadline.
+      failures = Math.min(failures + 1, 16);
+    }
+    await setTimeout(failures ? Math.min(interval * 2 ** (failures - 1), 30_000) : interval,
+      undefined, { signal: options.signal });
+  }
+}

package/src/compile.ts

@@ -15,6 +15,10 @@
 // `tests/spec_parity.rs` pin both sides to the same `testdata/` fixture.
 
 import { parse as parseYaml } from 'yaml';
+import { parseBudget, toKernelBudget } from './budget.js';
+import { bindingDependencies } from './input-binding.js';
+import { namedGateFailure } from './named-gates.js';
+import { lowerNamedGates } from './named-gate-lowering.js';
 import type {
   AgentStepSpec,
   DeterministicStepSpec,
@@ -38,21 +42,67 @@ import { canonicalize, specHash } from './canonical.js';
 import { validateOutputDeclaration } from './output-schema.js';
 import { validateSpec, type ValidationResult } from './validate.js';
 import { snapshotJsonValue } from './json-value.js';
+import { expandYamlHelpers } from './yaml-helpers.js';
 
 export class CompileError extends Error {
   readonly errors: string[];
-  constructor(errors: string[]) {
+  /** Optional diagnostic kind for callers that classify refusals (e.g. preflight). */
+  readonly kind?: string;
+  constructor(errors: string[], kind?: string) {
     super('spec compile failed:\n  - ' + errors.join('\n  - '));
     this.name = 'CompileError';
     this.errors = errors;
+    if (kind !== undefined) this.kind = kind;
   }
 }
 
+/**
+ * Parse the f.run timeout before submitting any command to the kernel.
+ *
+ * Accepts a positive whole-millisecond `number`, or a duration string of the
+ * form `<coefficient><unit>` where unit is `ms` / `s` / `m` — matched by an
+ * anchored regex that captures the coefficient first (group 1) and the unit
+ * second (group 2), so a future edit cannot silently swap them. Fractional
+ * coefficients that resolve to integer milliseconds are accepted; the
+ * multiplication is rounded to the nearest integer so `1.1s → 1100`
+ * survives float-precision (`1.1 * 1000 = 1100.0000000000002`) rather than
+ * being rejected by `isSafeInteger`.
+ */
+export function parseStepTimeout(timeout: unknown): number {
+  const unitToMs: Record<'ms' | 's' | 'm', number> = { ms: 1, s: 1000, m: 60_000 };
+  let milliseconds: number;
+  if (typeof timeout === 'number') {
+    milliseconds = timeout;
+  } else if (typeof timeout === 'string') {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(timeout);
+    if (match === null) {
+      milliseconds = NaN;
+    } else {
+      const coefficient = Number(match[1]);
+      const unit = match[2] as 'ms' | 's' | 'm';
+      // Round to defeat float precision (1.1 * 1000 = 1100.0000000000002).
+      // Fractional milliseconds themselves (e.g. `1.5ms`) still round to `2`,
+      // which the isSafeInteger check below accepts. Sub-ms precision is not
+      // a supported unit — authors expressing "1.5ms" get the closest int.
+      milliseconds = Math.round(coefficient * unitToMs[unit]);
+    }
+  } else {
+    milliseconds = NaN;
+  }
+  if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) {
+    throw new CompileError(['f.run timeout must be a positive whole number of milliseconds or a duration such as "10s" or "5m".'], 'timeout_invalid');
+  }
+  if (milliseconds > 15 * 60_000) {
+    throw new CompileError(['f.run timeout exceeds the maximum of 15 minutes declared in SURFACE.md.'], 'lease_exceeded');
+  }
+  return milliseconds;
+}
+
 /**
  * Compile a YAML string into a validated authoring `FlowSpec`.
  * Throws `CompileError` on a YAML parse error or any validation failure.
  */
-export function compileYaml(yaml: string): FlowSpec {
+export function compileYaml(yaml: string): CompiledFlowSpec {
   const parsed = parseYaml(yaml);
   if (parsed === null || typeof parsed !== 'object') {
     throw new CompileError(['YAML: expected a mapping at the top level']);
@@ -69,24 +119,43 @@ export function compileYamlToCanonicalJson(yaml: string): string {
  * Validate a parsed spec object and apply authoring defaults, returning a
  * normalized `FlowSpec`. Throws `CompileError` on validation failure.
  */
-export function compileSpec(spec: unknown): FlowSpec {
+export type CompiledFlowSpec = Omit<FlowSpec, 'budget'> & { budget?: import('./spec.js').BudgetSpec };
+
+export function compileSpec(spec: unknown): CompiledFlowSpec {
   let snapshot: unknown;
   try {
     snapshot = snapshotJsonValue(spec, 'spec');
+    snapshot = expandYamlHelpers(snapshot);
   } catch (error) {
     throw new CompileError([
       error instanceof Error ? error.message : 'spec: expected JSON-compatible data',
     ]);
   }
+  if (snapshot !== null && typeof snapshot === 'object' && !Array.isArray(snapshot) && 'budget' in snapshot && snapshot.budget !== undefined) {
+    // parseBudget throws BudgetSyntaxError on any malformed header. Without
+    // this wrap, that throw escaped compileSpec's own CompileError contract,
+    // so callers (validate, cli/check) that only catch CompileError would
+    // surface the budget error as an uncaught exception instead of a
+    // diagnostic. Rewrap as CompileError so it flows through the same
+    // gate-1 refusal path as every other invalid spec.
+    try {
+      snapshot = { ...snapshot, budget: parseBudget(snapshot.budget) };
+    } catch (error) {
+      throw new CompileError(
+        [`spec.budget: ${error instanceof Error ? error.message : 'budget_syntax_invalid'}`],
+        'budget_syntax_invalid',
+      );
+    }
+  }
   const validation: ValidationResult = validateSpec(snapshot);
-  if (!validation.ok) throw new CompileError(validation.errors);
+  if (!validation.ok) throw new CompileError(validation.errors, namedGateFailure(validation.errors));
 
-  const input = snapshot as FlowSpec;
+  const input = snapshot as CompiledFlowSpec;
   // Preserve named declarations and selectors through authoring normalization.
   // They are resolved exactly once at the kernel boundary, after public
   // preflight has validated every declaration with truthful provenance.
   const steps = input.steps.map(compileStep);
-  const flow: FlowSpec = {
+  const flow: CompiledFlowSpec = {
     version: input.version,
     ...(input.name !== undefined ? { name: input.name } : {}),
     ...(input.description !== undefined ? { description: input.description } : {}),
@@ -97,6 +166,8 @@ export function compileSpec(spec: unknown): FlowSpec {
     ...(input.triggers?.length ? { triggers: input.triggers } : {}),
     steps,
     ...(input.budget !== undefined ? { budget: input.budget } : {}),
+    ...(input.workspace !== undefined ? { workspace: input.workspace } : {}),
+    ...(input.tools !== undefined ? { tools: input.tools } : {}),
   };
   return flow;
 }
@@ -107,7 +178,9 @@ function compileStep(step: StepSpec): StepSpec {
   const base = {
     id: step.id,
     type: step.type,
-    ...(step.dependsOn !== undefined ? { dependsOn: step.dependsOn } : {}),
+    ...((step.dependsOn !== undefined || step.input !== undefined)
+      ? { dependsOn: step.input === undefined ? step.dependsOn : [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])] } : {}),
+    ...(step.input !== undefined ? { input: step.input } : {}),
     maxIterations,
     ...(step.memory !== undefined ? { memory: step.memory } : {}),
     ...(step.requirements !== undefined ? { requirements: step.requirements } : {}),
@@ -131,6 +204,7 @@ function compileStep(step: StepSpec): StepSpec {
         // #138: `timeoutMs` is deterministic-only — worker-backed verbs own
         // their dispatch timeout. It must be spread HERE and nowhere in `base`.
         ...(s.timeoutMs !== undefined ? { timeoutMs: s.timeoutMs } : {}),
+        ...(s.lease_ms !== undefined ? { lease_ms: parseStepTimeout(s.lease_ms) } : {}),
       };
     }
     case 'llm': {
@@ -158,6 +232,8 @@ function compileStep(step: StepSpec): StepSpec {
         ...(s.agent !== undefined ? { agent: s.agent } : {}),
         ...(s.cli !== undefined ? { cli: s.cli } : {}),
         ...(s.model !== undefined ? { model: s.model } : {}),
+        ...(s.cwd !== undefined ? { cwd: s.cwd } : {}),
+        ...(s.transport !== undefined ? { transport: s.transport } : {}),
         recoveryMode,
         ...(s.surfaces !== undefined ? { surfaces: s.surfaces } : {}),
         ...(s.permissions !== undefined ? { permissions: s.permissions } : {}),
@@ -252,16 +328,8 @@ export function toKernelSpec(flow: FlowSpec): KernelRunSpec {
     // reverts the other, and `validateSpec` and `flows check` would both still
     // look correct. See ops/reviews/20260903-pr139-repair-0903.md section 10.
     ...(compiled.triggers?.length ? { triggers: compiled.triggers.map(toKernelTrigger) } : {}),
-    steps: compiled.steps.map((step) => toKernelStep(resolveNamedAgent(step, compiled.agents))),
-    ...(compiled.budget !== undefined
-      ? {
-          budget: {
-            ...(compiled.budget.maxTokensIn !== undefined ? { max_tokens_in: compiled.budget.maxTokensIn } : {}),
-            ...(compiled.budget.maxTokensOut !== undefined ? { max_tokens_out: compiled.budget.maxTokensOut } : {}),
-            ...(compiled.budget.maxDollars !== undefined ? { max_dollars: compiled.budget.maxDollars } : {}),
-          },
-        }
-      : {}),
+    steps: lowerNamedGates(compiled.steps).map((step) => toKernelStep(resolveNamedAgent(step, compiled.agents))),
+    ...(compiled.budget !== undefined ? { budget: toKernelBudget(compiled.budget) } : {}),
   };
 }
 
@@ -354,15 +422,15 @@ function kernelTriggerToAuthoring(value: unknown, at: string): unknown {
 
 function kernelStepToAuthoring(value: unknown, at: string): unknown {
   const unionKeys = [
-    'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements',
-    'command', 'timeout_ms', 'prompt', 'model', 'cli', 'instruction',
+    'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input',
+    'command', 'timeout_ms', 'lease_ms', 'prompt', 'model', 'cli', 'instruction',
     'recovery_mode', 'surfaces', 'permissions',
   ] as const;
   const step = requireKernelObject(value, unionKeys, at);
   const type = step['type'];
-  const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements'] as const;
+  const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input'] as const;
   const typeKeys = type === 'deterministic'
-    ? ['command', 'timeout_ms'] as const
+    ? ['command', 'timeout_ms', 'lease_ms'] as const
     : type === 'llm'
       ? ['prompt', 'model', 'cli'] as const
       : type === 'agent'
@@ -374,6 +442,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
   const common = {
     id: step['id'],
     type,
+    ...(step['input'] !== undefined ? { input: step['input'] } : {}),
     ...(step['requirements'] !== undefined ? { requirements: kernelRequirementsToAuthoring(step['requirements'], `${at}.requirements`) } : {}),
     ...(dependsOn !== undefined && (!Array.isArray(dependsOn) || dependsOn.length > 0)
       ? { dependsOn }
@@ -387,6 +456,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
       ...common,
       command: step['command'],
       ...(step['timeout_ms'] !== undefined ? { timeoutMs: step['timeout_ms'] } : {}),
+      ...(step['lease_ms'] !== undefined ? { lease_ms: step['lease_ms'] } : {}),
     };
   }
   if (type === 'llm') {
@@ -447,8 +517,12 @@ function kernelMemoryToAuthoring(value: unknown, at: string): unknown {
 }
 
 function kernelBudgetToAuthoring(value: unknown, at: string): unknown {
-  const budget = requireKernelObject(value, ['max_tokens_in', 'max_tokens_out', 'max_dollars'], at);
+  const budget = requireKernelObject(value, ['max_tokens_in', 'max_tokens_out', 'max_dollars', 'max_tokens', 'max_wallclock_ms', 'window', 'pricing'], at);
   return {
+    ...(budget['pricing'] !== undefined ? { pricing: budget['pricing'] } : {}),
+    ...(budget['max_tokens'] !== undefined ? { maxTokens: budget['max_tokens'] } : {}),
+    ...(budget['max_wallclock_ms'] !== undefined ? { maxWallclockMs: budget['max_wallclock_ms'] } : {}),
+    ...(budget['window'] !== undefined ? { window: budget['window'] } : {}),
     ...(budget['max_tokens_in'] !== undefined ? { maxTokensIn: budget['max_tokens_in'] } : {}),
     ...(budget['max_tokens_out'] !== undefined ? { maxTokensOut: budget['max_tokens_out'] } : {}),
     ...(budget['max_dollars'] !== undefined ? { maxDollars: budget['max_dollars'] } : {}),
@@ -505,7 +579,9 @@ function isObject(value: unknown): value is Record<string, unknown> {
 function toKernelStep(step: StepSpec): KernelStepSpec {
   const common: KernelStepCommon = {
     id: step.id,
-    depends_on: step.dependsOn ?? [],
+    depends_on: step.input === undefined ? step.dependsOn ?? []
+      : [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])],
+    ...(step.input !== undefined ? { input: step.input } : {}),
     max_iterations: step.maxIterations ?? 1,
     retry: { ...KERNEL_RETRY_DEFAULTS },
     verification: toKernelVerification(step),
@@ -530,6 +606,7 @@ function toKernelStep(step: StepSpec): KernelStepSpec {
         type: 'deterministic',
         command: step.command,
         ...(step.timeoutMs !== undefined ? { timeout_ms: step.timeoutMs } : {}),
+        ...(step.lease_ms !== undefined ? { lease_ms: parseStepTimeout(step.lease_ms) } : {}),
       };
     case 'llm': {
       return {
@@ -547,6 +624,8 @@ function toKernelStep(step: StepSpec): KernelStepSpec {
         instruction: step.instruction,
         ...(step.cli !== undefined ? { cli: step.cli } : {}),
         ...(step.model !== undefined ? { model: step.model } : {}),
+        ...(step.cwd !== undefined ? { cwd: step.cwd } : {}),
+        ...(step.transport !== undefined ? { transport: step.transport } : {}),
         recovery_mode: step.recoveryMode ?? 'reset',
       };
       const surfaces = {

package/src/create-flow.ts

@@ -0,0 +1,82 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+
+export interface CreateFlowOptions {
+  name?: string;
+  template?: 'agent' | 'deterministic';
+  /** CLI used by future f.agent steps. It must already be authenticated. */
+  cli?: string;
+  /** Install project dependencies (default true). */
+  install?: boolean;
+}
+
+export interface CreatedFlow {
+  directory: string;
+  flowPath: string;
+  configPath: string;
+  installed: boolean;
+}
+
+/** Scaffold a new project. Existing directories are never overwritten. */
+export async function createFlow(target: string, opts: CreateFlowOptions = {}): Promise<CreatedFlow> {
+  if (!target.trim()) throw new Error('Choose a new directory, for example: create-flow my-flow');
+  const directory = resolve(target);
+  const name = opts.name ?? basename(directory);
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
+    throw new Error('Flow name must be 1–64 lowercase letters, numbers or hyphens, starting with a letter or number.');
+  }
+  const template = opts.template ?? 'agent';
+  if (template !== 'agent' && template !== 'deterministic') throw new Error('Template must be agent or deterministic.');
+  const cli = opts.cli ?? 'claude';
+  if (!cli.trim() || /[\x00-\x1f\x7f]/.test(cli)) throw new Error('CLI must be a nonempty command or path.');
+  const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')) as { version: string };
+  await mkdir(dirname(directory), { recursive: true });
+  try {
+    await mkdir(directory);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+      throw new Error(`Directory already exists: ${directory}. Choose a new directory; no files were changed.`);
+    }
+    throw error;
+  }
+  const flowFile = `${name}.flow.ts`;
+  const agentStep = template === 'agent'
+    ? `  const answer = await f.agent('greeter', { task: 'Reply with one short hello sentence. Do not use tools or modify files.' });\n  console.log(answer.summary);\n`
+    : '';
+  const runFlags = template === 'agent' ? ' --local-agent' : '';
+  const files: Record<string, string> = {
+    [flowFile]: `import { flow } from '@relayflows/surface';\n\nexport default flow(${JSON.stringify(name)}, async (f) => {\n  const greeting = await f.run('echo "Hello from Relayflows"');\n  console.log(greeting.trim());\n${agentStep}  f.done('success');\n});\n`,
+    'flows.json': JSON.stringify({ cli }, null, 2) + '\n',
+    'package.json': JSON.stringify({
+      name, private: true, type: 'module',
+      scripts: { start: `flows run ${flowFile}${runFlags} --input '{}'` },
+      engines: { node: '>=22.18.0' },
+      dependencies: { relayflows: version, '@relayflows/surface': version },
+    }, null, 2) + '\n',
+    '.gitignore': 'node_modules/\n.relayflowd/\n',
+    'README.md': `# ${name}\n\nRun \`npm start\` (or \`npx flows run ${flowFile}${runFlags} --input '{}'\`).\n\n${template === 'agent' ? `Requires ${JSON.stringify(cli)} installed and authenticated. The local agent worker runs\non this machine with the CLI's existing access; it provides no workspace isolation.\n` : 'This starter needs no model credentials.\n'}\n\`flows.json\` selects the CLI for agent steps. Steps execute through the local\njournal; authored TypeScript bodies are not yet durably resumable as a whole.\n`,
+  };
+  for (const [file, contents] of Object.entries(files)) {
+    await writeFile(join(directory, file), contents, { flag: 'wx' });
+  }
+  if (opts.install !== false) {
+    try {
+      await installDependencies(directory);
+    } catch (error) {
+      throw new Error(`Created ${directory}, but dependency installation failed. Run npm install there to retry.`, { cause: error });
+    }
+  }
+  return { directory, flowPath: join(directory, flowFile), configPath: join(directory, 'flows.json'), installed: opts.install !== false };
+}
+
+function installDependencies(cwd: string): Promise<void> {
+  return new Promise((resolveInstall, reject) => {
+    const child = spawn('npm', ['install', '--no-audit', '--no-fund'], { cwd, stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('close', (code, signal) => {
+      if (code === 0) resolveInstall();
+      else reject(new Error(`npm install exited ${signal ?? code}`));
+    });
+  });
+}

package/src/daemon-connection.ts

@@ -13,6 +13,7 @@
 // what a file says about itself.
 
 import { spawn, type ChildProcess, type SpawnOptions } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import {
   closeSync,
   mkdirSync,
@@ -20,6 +21,7 @@ import {
   readFileSync,
   rmSync,
 } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { JournalClient, JournalProtocolError } from './journal-client.js';
 import { PROTOCOL_VERSION } from './protocol.js';
@@ -145,8 +147,37 @@ export const defaultDaemonLifecycleDeps: DaemonLifecycleDeps = {
   }),
 };
 
+/**
+ * Derive the daemon socket path from the data dir.
+ *
+ * The socket lives outside the data dir at a short hashed path so that a deep
+ * working directory cannot push the full socket path past `SUN_LEN` (~104
+ * bytes on macOS, ~108 on Linux) — the first-run papercut in #262. Anti-hijack
+ * still holds because the daemon derives the same path from the same input;
+ * this function and Rust's `crate::socket_path::derive_socket_path` must stay
+ * in lockstep. Both use `resolve()` / `std::path::absolute` (lexical, no
+ * symlink resolution) so `/var` vs macOS's `/private/var` can never diverge.
+ *
+ * `SOCKET_FILE` is retained as the exported constant name for compatibility,
+ * but is no longer the *entire* socket filename — see the derivation below.
+ */
 export function socketPathFor(dataDir: string): string {
-  return join(resolve(dataDir), SOCKET_FILE);
+  const absolute = resolve(dataDir);
+  // 12 hex chars = 6 bytes of SHA-256. Enough separation between data dirs on
+  // one machine, small enough to leave headroom under SUN_LEN.
+  const hash = createHash('sha256').update(absolute).digest('hex').slice(0, 12);
+  return join(runtimeDir(), `relayflowd-${hash}.sock`);
+}
+
+function runtimeDir(): string {
+  // XDG first (Linux, typically `/run/user/<uid>/`, ~14 chars — the shortest
+  // per-user private option). TMPDIR next (macOS, `/var/folders/xx/YYY/T/`,
+  // per-user private). Only fall back to os.tmpdir() when neither is set.
+  const xdg = process.env['XDG_RUNTIME_DIR'];
+  if (xdg && xdg.length > 0) return xdg;
+  const tmp = process.env['TMPDIR'];
+  if (tmp && tmp.length > 0) return tmp;
+  return tmpdir();
 }
 
 export function connectionPathFor(dataDir: string): string {

package/src/demo-hn-monitor.ts

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { socketPathFor } from './daemon-connection.js';
 import { pollHackerNewsOnce, type EventSink } from './hn-poller.js';
 import { JournalClient } from './journal-client.js';
 import type { EventSubmitResult } from './protocol.js';
@@ -8,7 +9,7 @@ import type { EventSubmitResult } from './protocol.js';
 const sdkRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const repositoryRoot = resolve(sdkRoot, '..');
 const dataDir = resolve(process.env.RELAYFLOW_DATA_DIR ?? join(repositoryRoot, '.relayflowd'));
-const socketPath = join(dataDir, 'relayflowd.sock');
+const socketPath = socketPathFor(dataDir);
 const specPath = join(repositoryRoot, 'testdata', 'hn-monitor.spec.canonical.json');
 
 interface Submission {

package/src/effect-channel.ts

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto';
+import { compileSpec, toKernelSpec } from './compile.js';
+import type { JournalClient } from './journal-client.js';
+import type { StepDispatchEvent } from './protocol.js';
+import { SPEC_SCHEMA_VERSION } from './spec.js';
+import { withWorkerLease } from './worker-lease.js';
+import { snapshotJsonValue } from './json-value.js';
+
+/** Structural subset of Agent Relay's messages.dm; credentials stay in the client. */
+export interface ChannelBroker {
+  messages: {
+    dm(input: {
+      to: string;
+      text: string;
+      idempotencyKey: string;
+      metadata: { channel: string; messageId: string };
+    }): Promise<unknown>;
+  };
+}
+
+export interface ChannelPost {
+  channel: string;
+  to: string;
+  text: string;
+}
+
+function validatePost(post: ChannelPost, participants: readonly string[]): void {
+  if (typeof post.channel !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(post.channel)) {
+    throw new Error('channel_invalid');
+  }
+  if (typeof post.to !== 'string' || !post.to.trim() || !participants.includes(post.to)) {
+    throw new Error(`channel_participant_unresolved: ${post.to}`);
+  }
+  if (typeof post.text !== 'string') throw new Error('channel_text_invalid');
+}
+
+/** One message boundary per step. Participant resolution precedes journal submission. */
+export function channelPostSpec(
+  name: string, stepId: string, post: ChannelPost, participants: readonly string[],
+) {
+  post = snapshotJsonValue(post, 'channel post') as unknown as ChannelPost;
+  validatePost(post, participants);
+  return toKernelSpec(compileSpec({
+    version: SPEC_SCHEMA_VERSION, name,
+    steps: [{ id: stepId, type: 'agent',
+      instruction: JSON.stringify({ type: 'effect', provider: 'channel', verb: 'post',
+        channel: post.channel, to: post.to, text: post.text }),
+      maxIterations: 3, recoveryMode: 'reset',
+      surfaces: { streams: [{ stream: `channel-${post.channel}` }], external: [`/channel/${post.channel}`] },
+    }],
+  }));
+}
+
+/**
+ * Internal post-only proof, for an already provisioned run-scoped broker client.
+ * The broker must honor idempotencyKey across worker retries. The application
+ * message ID is deliberately distinct from any provider-generated record ID.
+ */
+export async function completeChannelPost(
+  client: JournalClient, dispatch: StepDispatchEvent, broker: ChannelBroker,
+  participants: readonly string[],
+): Promise<void> {
+  const spec = dispatch.spec as { instruction?: string; surfaces?: { external?: string[] } };
+  if (dispatch.step_type !== 'agent' || typeof spec.instruction !== 'string') {
+    throw new Error('channel_dispatch_invalid');
+  }
+  const call = JSON.parse(spec.instruction) as ChannelPost & { type: string; provider: string; verb: string };
+  if (call.type !== 'effect' || call.provider !== 'channel' || call.verb !== 'post') {
+    throw new Error('channel_dispatch_invalid');
+  }
+  validatePost(call, participants);
+  const surfacePath = `/channel/${call.channel}`;
+  if (!spec.surfaces?.external?.includes(surfacePath)) throw new Error('channel_surface_undeclared');
+  const messageId = createHash('sha256')
+    .update(JSON.stringify([dispatch.run_id, dispatch.step_id, call.channel])).digest('hex');
+  await withWorkerLease(client, dispatch, async signal => {
+    await client.performEffect({
+      runId: dispatch.run_id, stepId: dispatch.step_id, attempt: dispatch.attempt,
+      idempotencyKey: dispatch.idempotency_key, surfacePath,
+      revisionBefore: 'pending', revisionAfter: messageId,
+    }, async () => {
+      signal.throwIfAborted();
+      await broker.messages.dm({ to: call.to, text: call.text, idempotencyKey: messageId,
+        metadata: { channel: call.channel, messageId } });
+      signal.throwIfAborted();
+    });
+  });
+  // All receipt fields already exist in the journaled spec and stable run identity.
+  // A crash after confirm needs neither a local receipt cache nor a broker read.
+  await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
+    dispatch.idempotency_key, 'success', {
+      output: { type: 'effect', provider: 'channel', verb: 'post',
+        messageId, channel: call.channel, to: call.to, text: call.text },
+      started_pins: dispatch.pins, end_pins: dispatch.pins,
+      effects: [{ surface_path: surfacePath, idempotency_key: dispatch.idempotency_key }],
+    });
+}