@relayflows/sdk 2.0.9 → 2.0.10

package/src/plugin-manifest.ts

@@ -0,0 +1,76 @@
+import { Ajv } from 'ajv';
+import { snapshotJsonValue } from './json-value.js';
+
+export const PLUGIN_FAILURE_KINDS = [
+  'plugin_unknown', 'plugin_unlisted', 'plugin_install_failed', 'plugin_manifest_missing',
+  'plugin_manifest_invalid', 'plugin_preflight_missing', 'plugin_verb_unknown_primitive',
+  'plugin_unsupported', 'plugin_credential_missing', 'plugin_server_unreachable',
+] as const;
+export type PluginFailureKind = typeof PLUGIN_FAILURE_KINDS[number];
+export class PluginError extends Error {
+  constructor(readonly code: PluginFailureKind, message: string) { super(message); }
+}
+export interface PluginVerb {
+  namespace: string;
+  method: string;
+  lowersTo: 'run' | 'llm' | 'agent' | 'effect' | 'wait';
+  args: Record<string, unknown>;
+}
+export interface PluginManifest {
+  name: string;
+  version: string;
+  verbs: readonly PluginVerb[];
+  triggers: readonly unknown[];
+  gates: readonly unknown[];
+  preflight: { credentials: readonly string[]; servers: readonly string[] };
+}
+const identifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const reserved = new Set(['run', 'llm', 'agent', 'human', 'dispatch', 'done', 'cloud', 'memory', 'mcp', 'slack', '__proto__', 'constructor', 'prototype', 'then']);
+const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const strings = (v: unknown): v is string[] => Array.isArray(v) && v.every(s => typeof s === 'string' && s.trim().length > 0);
+export function pluginPackageName(name: string): string {
+  const bare = name.replace(/^@flows\//, '');
+  if (!/^helper-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(bare)) {
+    throw new PluginError('plugin_manifest_invalid', 'Expected helper-<name> or @flows/helper-<name>.');
+  }
+  return `@flows/${bare}`;
+}
+export function validatePluginManifest(input: unknown, packageName?: string): PluginManifest {
+  let v: unknown;
+  try { v = snapshotJsonValue(input, 'plugin manifest'); }
+  catch { throw new PluginError('plugin_manifest_invalid', 'Plugin manifest must be JSON data.'); }
+  const invalid = (message: string): never => { throw new PluginError('plugin_manifest_invalid', message); };
+  if (!object(v)) return invalid('Expected a plugin manifest object.');
+  if (!Object.hasOwn(v, 'preflight')) throw new PluginError('plugin_preflight_missing', 'Plugin must declare preflight.');
+  if (typeof v.name !== 'string' || typeof v.version !== 'string' || !v.version.trim()) return invalid('Plugin name and version are required.');
+  const resolved = pluginPackageName(v.name);
+  if (packageName !== undefined && resolved !== packageName) return invalid('Plugin name does not match its package.');
+  if (!Array.isArray(v.verbs) || !Array.isArray(v.triggers) || !Array.isArray(v.gates)) return invalid('Expected verbs, triggers, and gates arrays.');
+  if (!object(v.preflight) || !strings(v.preflight.credentials) || !strings(v.preflight.servers)) return invalid('Preflight requires credentials and servers arrays.');
+  if (!v.preflight.credentials.every(s => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s))) return invalid('Invalid credential environment variable.');
+  for (const server of v.preflight.servers) {
+    try { if (!['http:', 'https:'].includes(new URL(server).protocol)) return invalid('Servers must be HTTP(S) URLs.'); }
+    catch { return invalid('Servers must be HTTP(S) URLs.'); }
+  }
+  const seen = new Set<string>();
+  const ajv = new Ajv({ strict: false });
+  for (const verb of v.verbs) {
+    if (!object(verb) || typeof verb.namespace !== 'string' || typeof verb.method !== 'string'
+      || !identifier.test(verb.namespace) || !identifier.test(verb.method)
+      || reserved.has(verb.namespace) || ['__proto__', 'constructor', 'prototype', 'then'].includes(verb.method)) return invalid('Invalid or reserved plugin verb.');
+    if (!['run', 'llm', 'agent', 'effect', 'wait'].includes(String(verb.lowersTo))) {
+      throw new PluginError('plugin_verb_unknown_primitive', `Unknown primitive for ${verb.namespace}.${verb.method}.`);
+    }
+    if (!object(verb.args)) return invalid('Verb args must be a JSON Schema.');
+    try { ajv.compile(verb.args); } catch { return invalid('Invalid verb argument JSON Schema.'); }
+    const key = `${verb.namespace}.${verb.method}`;
+    if (seen.has(key)) return invalid(`Duplicate verb ${key}.`);
+    seen.add(key);
+  }
+  return v as unknown as PluginManifest;
+}
+export function assertSupportedPlugin(manifest: PluginManifest): void {
+  if (manifest.triggers.length || manifest.gates.length || manifest.verbs.some(v => v.lowersTo !== 'effect')) {
+    throw new PluginError('plugin_unsupported', 'This slice supports effect verbs; trigger, gate, run, llm, agent and wait dispatch are follow-ups.');
+  }
+}

package/src/preflight.ts

@@ -1,6 +1,16 @@
-import type { FlowSpec, StepSpec, TriggerSpec } from './spec.js';
+import { loadPlugins, type LoadedPlugin } from './plugin-loader.js';
+import { PluginError } from './plugin-manifest.js';
+import type { FlowSpec, StepSpec, TriggerSpec, McpServerConfig } from './spec.js';
+import { McpError, openMcpSession, type McpDiagnostic } from './mcp-client.js';
+import { BudgetSyntaxError } from './budget.js';
+import { budgetDiagnostics } from './budget-preflight.js';
+import type { TriggerSource } from '@relayflows/surface';
 import { acceptsAnyOutput, inspectStepGate, type StepGateInspection } from './gate-contract.js';
 import { compileSpec, CompileError } from './compile.js';
+import { helperCall } from './yaml-helpers.js';
+import { isNamedGate, NAMED_GATE_FAILURE_KINDS, type NamedGateFailureKind } from './named-gates.js';
+import { compileScopes, type ScopeInput, type MountRegistry } from './scope-compiler.js';
+import { readMountRegistry } from './mount-registry.js';
 import type {
   PreflightFailureKind,
   PreflightWarningKind,
@@ -48,6 +58,8 @@ type CliProbeOutcome =
  * emits `probe_failed` (or `command_unprovable` for a deterministic command).
  */
 export interface PreflightProbes {
+  /** Whether the provider's relayfile mount is available to the helper worker. */
+  helper?(provider: string): boolean;
   /**
    * Resolve relative paths against the file implied by `source`, then probe
    * `auth status`. When the step declared a `model`, the probe runs with that
@@ -60,6 +72,10 @@ export interface PreflightProbes {
 }
 
 export interface PreflightOptions {
+  pluginSearchStart?: string;
+  /** Validated tools.mcp header and nearest flows.json connections. */
+  mcpServers?: readonly string[];
+  mcp?: Readonly<Record<string, McpServerConfig>>;
   projectCli?: string;
   projectConfigPath?: string;
   projectSearchStart?: string;
@@ -70,6 +86,8 @@ export interface PreflightOptions {
 }
 
 export interface PreflightRefusal {
+  server?: string;
+  cause?: McpDiagnostic;
   severity: 'refusal';
   kind: PreflightFailureKind;
   message: string;
@@ -94,13 +112,65 @@ export interface PreflightWarning {
 export type PreflightDiagnostic = PreflightRefusal | PreflightWarning;
 
 export interface PreflightResult {
+  plugins?: readonly LoadedPlugin[];
+  mcpTools?: Readonly<Record<string, readonly string[]>>;
   ok: boolean;
   gates: StepGateInspection[];
   resolutions: CliResolution[];
   diagnostics: PreflightDiagnostic[];
 }
 
-export function preflight(flow: FlowSpec, options: PreflightOptions): PreflightResult {
+/** Pure declared-surface check, before opening a receiver or journal. */
+export function preflightWebhookTriggers(
+  triggers: readonly TriggerSource[],
+  executors: readonly string[],
+): PreflightRefusal[] {
+  return [...new Set(triggers.map(trigger => trigger.name))]
+    .filter(name => !executors.includes(name))
+    .map(name => ({
+      severity: 'refusal',
+      kind: 'no_executor',
+      executor: name,
+      message: `webhook trigger "${name}" is not registered in flows.json`,
+    }));
+}
+
+// Preserve the synchronous declarative API; an authored MCP declaration opts
+// into asynchronous connection probes after the same pure refusal pass.
+export function preflight(flow: FlowSpec, options: PreflightOptions & { mcpServers: readonly string[] }): Promise<PreflightResult>;
+export function preflight(flow: FlowSpec, options: PreflightOptions & { mcpServers?: undefined }): PreflightResult;
+export function preflight(flow: FlowSpec, options: PreflightOptions): PreflightResult | Promise<PreflightResult>;
+export function preflight(flow: unknown, options: PreflightOptions): PreflightResult | Promise<PreflightResult> {
+  const result = preflightSync(flow, options);
+  if (options.mcpServers === undefined) return result;
+  return probeMcp(result, options).then(async checked => {
+    if (!checked.ok || options.pluginSearchStart === undefined) return checked;
+    try { return { ...checked, plugins: await loadPlugins(options.pluginSearchStart) }; }
+    catch (error) {
+      if (!(error instanceof PluginError)) throw error;
+      return { ...checked, ok: false, diagnostics: [...checked.diagnostics, { severity: 'refusal' as const, kind: error.code, message: error.message }] };
+    }
+  });
+}
+
+async function probeMcp(result: PreflightResult, options: PreflightOptions): Promise<PreflightResult> {
+  if (!result.ok) return result;
+  const inventory: Record<string, readonly string[]> = Object.create(null);
+  for (const server of new Set(options.mcpServers)) {
+    try {
+      const session = await openMcpSession(options.mcp![server]!, 10_000);
+      try { inventory[server] = Object.freeze(await session.listTools()); }
+      finally { await session.close(); }
+    } catch (error) {
+      const cause = error instanceof McpError ? error.code : 'handshake_rejected';
+      result.diagnostics.push({ severity: 'refusal', kind: 'mcp_unreachable', server, cause,
+        message: `MCP server "${server}" is unreachable: ${cause}.` });
+    }
+  }
+  return { ...result, ok: !result.diagnostics.some(d => d.severity === 'refusal'), mcpTools: Object.freeze(inventory) };
+}
+
+function preflightSync(flow: unknown, options: PreflightOptions): PreflightResult {
   // Compile before touching any environment fact. `compileSpec` snapshots raw
   // input into inert data, validates it against the closed authoring schema,
   // and lowers `output` sugar into its json_schema gate — so the gate plan
@@ -108,20 +178,30 @@ export function preflight(flow: FlowSpec, options: PreflightOptions): PreflightR
   // inspection ever reads a live accessor. The failure is a named refusal
   // rather than a thrown error (RFC covenant 2), which is the contract main
   // settled for this boundary.
-  let compiled: FlowSpec;
+  let compiled: import('./compile.js').CompiledFlowSpec;
   try {
     compiled = compileSpec(flow);
   } catch (error) {
     const errors = error instanceof CompileError
       ? error.errors
       : [error instanceof Error ? error.message : 'spec: expected JSON-compatible data'];
+    // BudgetSyntaxError now flows through CompileError with kind on it; the
+    // legacy raw-throw instanceof is preserved as a fallback so a caller that
+    // constructs preflight input through a different path still classifies.
+    const kind: PreflightDiagnostic['kind'] = error instanceof CompileError && error.kind === 'budget_syntax_invalid'
+      ? 'budget_syntax_invalid'
+      : error instanceof CompileError && NAMED_GATE_FAILURE_KINDS.includes(error.kind as NamedGateFailureKind)
+        ? error.kind as NamedGateFailureKind
+      : error instanceof BudgetSyntaxError
+        ? 'budget_syntax_invalid'
+        : 'invalid_spec';
     return {
       ok: false,
       gates: [],
       resolutions: [],
       diagnostics: [{
         severity: 'refusal',
-        kind: 'invalid_spec',
+        kind,
         message: `Relayflow spec is invalid: ${errors.join('; ')}`,
         errors,
       }],
@@ -133,11 +213,19 @@ export function preflight(flow: FlowSpec, options: PreflightOptions): PreflightR
   const cliProbeResults = new Map<string, CliProbeOutcome>();
 
   diagnostics.push(...unknownModelDiagnostics(compiled, options));
+  diagnostics.push(...scopeDiagnostics(compiled, options));
+  for (const server of new Set(options.mcpServers ?? [])) {
+    if (options.mcp !== undefined && Object.hasOwn(options.mcp, server)) continue;
+    diagnostics.push({ severity: 'refusal', kind: 'mcp_undeclared_server', server,
+      message: `MCP server "${server}" is not declared in the nearest flows.json mcp map.` });
+  }
+  diagnostics.push(...budgetDiagnostics(compiled));
   // Resolve the complete flow before touching any environment fact. A later
   // statically unresolved CLI makes the whole submission impossible, so no
   // earlier command, provider/model, or trigger probe may run first.
   for (const step of compiled.steps) {
     if (step.type === 'deterministic') continue;
+    if (step.type === 'agent' && helperCall(step) !== undefined) continue;
     const resolution = resolveCli(step, compiled, options.projectCli);
     if (resolution === undefined) {
       diagnostics.push({
@@ -156,9 +244,26 @@ export function preflight(flow: FlowSpec, options: PreflightOptions): PreflightR
   }
 
   for (const step of compiled.steps) {
+    probeNamedGate(step, options.probes, diagnostics);
     warnOnVacuousGate(step, diagnostics);
     warnOnUnprovableEffects(step, options.probes, diagnostics);
     if (step.type === 'deterministic') continue;
+    const helper = step.type === 'agent' ? helperCall(step) : undefined;
+    if (helper !== undefined) {
+      try {
+        if (options.probes.helper === undefined) {
+          diagnostics.push({ severity: 'warning', kind: 'unprovable_effects', stepId: step.id,
+            message: `${helper.provider} helper requires a relayfile mount and an SDK agent worker.` });
+        } else if (!options.probes.helper(helper.provider)) {
+          diagnostics.push({ severity: 'refusal', kind: 'helper_mount_required', stepId: step.id,
+            message: `${helper.provider} helper requires a relayfile mount.` });
+        }
+      } catch {
+        diagnostics.push({ severity: 'refusal', kind: 'probe_failed', stepId: step.id,
+          message: `${helper.provider} helper mount could not be checked.` });
+      }
+      continue;
+    }
     const resolution = resolutionByStep.get(step.id)!;
     probeResolvedCli(resolution, options.probes, cliProbeResults, diagnostics);
   }
@@ -175,18 +280,55 @@ export function preflight(flow: FlowSpec, options: PreflightOptions): PreflightR
   };
 }
 
+/**
+ * Compile author-declared `workspace:` / `tools.fs:` grants against the nearest
+ * relayfile mount manifest. The compiler is pure; only mount discovery reads a
+ * fact about the filesystem. Missing manifest means no known mounts — a grant
+ * still parses but refuses as `mount_unknown` in that case.
+ */
+function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightRefusal[] {
+  const workspace = flow.workspace;
+  const toolsFs = flow.tools?.fs;
+  if (workspace === undefined && toolsFs === undefined) return [];
+  const input: ScopeInput = {
+    ...(workspace === undefined ? {} : { workspace }),
+    ...(toolsFs === undefined ? {} : { tools: { fs: toolsFs } }),
+  };
+  let mounts: MountRegistry | undefined;
+  if (options.projectSearchStart !== undefined) {
+    try { mounts = readMountRegistry(options.projectSearchStart); }
+    catch { mounts = {}; /* fail closed — unreadable manifest treats every mount as unknown */ }
+  }
+  return compileScopes(input, mounts).diagnostics.map(refusal => ({
+    severity: 'refusal',
+    kind: refusal.kind,
+    message: refusal.message,
+    ...(refusal.stepId === undefined ? {} : { stepId: refusal.stepId }),
+  }));
+}
+
 /** Pure authoring validation: no executable, command, trigger, or daemon probe. */
 function unknownModelDiagnostics(
   flow: FlowSpec,
   options: PreflightOptions,
 ): PreflightRefusal[] {
   const diagnostics: PreflightRefusal[] = [];
+  // model_unknown is a governance check: it exists to enforce a project's
+  // registry-declared allowlist. When no flows.json is found, `check.ts` sends
+  // `models: []` with `modelRegistryPath: undefined` — an empty list not
+  // because the project forbids everything, but because no policy exists.
+  // Refusing an inline `agents: { drafter: { cli, model } }` declaration in
+  // that state forces every self-contained example flow to ship a second file.
+  // A real allowlist (even an empty one from a found flows.json) still
+  // enforces; that state is signalled by modelRegistryPath.
+  const enforceRegistry = options.modelRegistryPath !== undefined;
 
   // Named declarations remain in the normalized authoring object until this
   // boundary so even unused or step-shadowed models are checked. toKernelSpec
   // erases the map and selector only after this pass has had a chance to fail.
   for (const [agent, declaration] of Object.entries(flow.agents ?? {})) {
     if (isKnownModel(declaration.model, options.models)) continue;
+    if (!enforceRegistry) continue;
     diagnostics.push({
       severity: 'refusal',
       kind: 'model_unknown',
@@ -480,3 +622,35 @@ function firstCommandWord(command: string): string | undefined {
   const match = rest.match(/^(?:"([^"]+)"|'([^']+)'|([^\s]+))/);
   return match?.[1] ?? match?.[2] ?? match?.[3];
 }
+
+function probeNamedGate(step: StepSpec, probes: PreflightProbes, diagnostics: PreflightDiagnostic[]): void {
+  const gate = step.verification;
+  if (!isNamedGate(gate)) return;
+  const commands = ['node', ...(gate.type === 'word_count_bounds' ? ['wc'] : [])];
+  if (gate.type === 'subprocess_gate') commands.push(firstCommandWord(gate.command) ?? '');
+  for (const command of commands) {
+    let exists = false;
+    try { exists = command !== '' && probes.command(command); } catch { /* Fail closed on an unprovable gate. */ }
+    if (exists) continue;
+    diagnostics.push({ severity: 'refusal', kind: 'gate_command_missing', stepId: step.id,
+      message: `Step "${step.id}" ${gate.type} command "${command}" does not resolve as an executable.` });
+  }
+}
+
+export { preflightHelpers } from './helper-preflight.js';
+
+/** Authored memory probes run before invoking the body or contacting the journal. */
+export async function preflightMemory(
+  probe: () => Promise<void>,
+): Promise<PreflightRefusal | undefined> {
+  try {
+    await probe();
+    return undefined;
+  } catch {
+    return {
+      severity: 'refusal',
+      kind: 'memory_unreachable',
+      message: 'Script memory requires the ai-hist Node SDK and a readable SQLite database at AI_HIST_DB (or defaultDbPath()). Run ai-hist sync first.',
+    };
+  }
+}

package/src/progress.ts

@@ -0,0 +1,51 @@
+import type { CompletionReason } from './protocol.js';
+import type { StepType } from './spec.js';
+
+export interface ProgressEvent {
+  type: 'step.started' | 'step.running' | 'step.completed' | 'step.failed';
+  stepId: string;
+  stepType: StepType;
+  elapsedMs: number;
+  completionReason?: CompletionReason;
+}
+
+/** Pure terminal rendering: caller owns the event source, clock, and output. */
+export function renderProgress(events: Iterable<ProgressEvent>): string[] {
+  return Array.from(events, event => {
+    const icon = { 'step.started': '○', 'step.running': '↻', 'step.completed': '✓', 'step.failed': '✗' }[event.type];
+    const state = event.type.slice('step.'.length);
+    const agent = event.stepType === 'agent' ? ` [agent: ${state === 'started' ? 'preparing' : state}]` : '';
+    const reason = event.completionReason ? ` completionReason: ${event.completionReason}` : '';
+    // Agent-authored names cannot inject terminal control sequences.
+    const name = event.stepId.replace(/[\x00-\x1f\x7f-\x9f]/g, '?');
+    return `${icon} ${name} (${event.stepType})${agent} ${(Math.max(0, event.elapsedMs) / 1000).toFixed(2)}s${reason}`;
+  });
+}
+
+/** Observe the existing executor; success is emitted only after its journal read. */
+export async function observeStep<T>(
+  stepId: string,
+  stepType: StepType,
+  execute: () => Promise<T>,
+  emit?: (event: ProgressEvent) => void,
+): Promise<T> {
+  const publish = (event: ProgressEvent): void => {
+    try { emit?.(event); } catch {
+      // A projection failure must not turn a journaled success into a retry,
+      // or replace the executor's original failure. Surface it separately.
+      process.emitWarning(`Progress observer failed for ${event.type}.`, {
+        code: 'FLOWS_PROGRESS_OBSERVER_ERROR',
+      });
+    }
+  };
+  const started = performance.now();
+  publish({ type: 'step.started', stepId, stepType, elapsedMs: 0 });
+  try {
+    const result = await execute();
+    publish({ type: 'step.completed', stepId, stepType, elapsedMs: performance.now() - started, completionReason: 'success' });
+    return result;
+  } catch (error) {
+    publish({ type: 'step.failed', stepId, stepType, elapsedMs: performance.now() - started });
+    throw error;
+  }
+}

package/src/protocol.ts

@@ -69,7 +69,15 @@ export interface HelloResult {
   server: string;
 }
 
+export interface StepSpend {
+  tokens_input: number;
+  tokens_output: number;
+  dollars: number;
+  wallclock_ms: number;
+}
+
 export interface RunStartParams {
+  reuse_from_run_id?: string;
   /**
    * The kernel spec dialect — the ONE boundary shape `RunSpec::parse`
    * accepts (snake_case, flat v0 verification, defaults materialized).
@@ -90,6 +98,7 @@ export interface RunOutcome {
 export type RunStartResult = RunOutcome;
 
 export interface RunResumeParams {
+  allow_human_influenced?: boolean;
   run_id: string;
 }
 export type RunResumeResult = RunOutcome;
@@ -179,6 +188,8 @@ export interface RoutingDecision {
 }
 
 export interface StepDispatchEvent {
+  /** Selected successful outputs, resolved by the kernel from the journal. */
+  input?: Record<string, unknown>;
   /** Durable choice; optional only for older kernel protocol compatibility. */
   routing?: RoutingDecision;
   /** Already journaled and charged; completion usage excludes this cost. */
@@ -287,6 +298,7 @@ export interface EffectConfirmResult {
 }
 
 export interface StepCompleteParams {
+  human_intervention?: boolean;
   run_id: string;
   step_id: string;
   attempt: number;

package/src/pty-sidechannel.ts

@@ -0,0 +1,92 @@
+import { createServer, type Socket } from 'node:net';
+import { chmod, mkdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+export interface SidechannelContext {
+  dataDir: string;
+  runId: string;
+  stepId: string;
+  onReady?: (path: string) => void;
+  onDrive: () => void;
+}
+
+export function ptySocketPath(context: Pick<SidechannelContext, 'dataDir' | 'runId' | 'stepId'>): string {
+  for (const id of [context.runId, context.stepId]) {
+    if (!id || id === '.' || id === '..' || /[/\\\0]/.test(id)) throw new Error('Invalid sidechannel path component');
+  }
+  return join(resolve(context.dataDir), 'runs', context.runId, 'steps', context.stepId, 'pty.sock');
+}
+
+/** Best-effort live bytes. Slow peers are dropped; they never pause execution. */
+export async function openSidechannel(
+  context: SidechannelContext,
+  input: (bytes: Buffer) => boolean | Promise<boolean>,
+  canDrive: () => boolean = () => true,
+) {
+  const peers = new Map<Socket, boolean>();
+  let closed = false;
+  const server = createServer(socket => {
+    if (peers.size >= 16) { socket.destroy(); return; }
+    peers.set(socket, false);
+    let hello = Buffer.alloc(0);
+    let mode: string | undefined;
+    socket.setTimeout(2_000, () => socket.destroy());
+    socket.on('error', () => socket.destroy());
+    socket.on('close', () => peers.delete(socket));
+    socket.on('data', (bytes: Buffer) => {
+      if (mode === undefined) {
+        hello = Buffer.concat([hello, bytes]);
+        const end = hello.indexOf(10);
+        if (end < 0) { if (hello.length > 32) socket.destroy(); return; }
+        const line = hello.subarray(0, end).toString('utf8');
+        if (!['HELLO view', 'HELLO drive', 'HELLO passthrough'].includes(line)) { socket.destroy(); return; }
+        mode = line.slice(6);
+        if (mode === 'drive' && !canDrive()) { socket.destroy(); return; }
+        socket.setTimeout(0);
+        peers.set(socket, true);
+        // Passthrough is a passive raw-byte view in this initial slice.
+        if (mode === 'drive') context.onDrive();
+        bytes = hello.subarray(end + 1);
+        hello = Buffer.alloc(0);
+      }
+      if (mode === 'drive' && bytes.length > 0) {
+        socket.pause();
+        void Promise.resolve().then(() => input(bytes)).then(accepted => {
+          if (!accepted) socket.destroy();
+          else if (!socket.destroyed) socket.resume();
+        }, () => socket.destroy());
+      }
+    });
+  });
+  server.on('error', () => { for (const peer of peers.keys()) peer.destroy(); });
+  try {
+    const path = ptySocketPath(context);
+    // Restrict traversal as well as socket access to the worker's OS user.
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await chmod(dirname(path), 0o700);
+    await new Promise<void>((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(path, () => { server.off('error', reject); resolve(); });
+    });
+    await chmod(path, 0o600);
+    context.onReady?.(path);
+  } catch {
+    // Never unlink a pre-existing socket: it may belong to a live attempt.
+    if (server.listening) server.close();
+    return undefined;
+  }
+  return {
+    publish(bytes: Buffer) {
+      if (closed) return;
+      for (const [peer, ready] of peers) {
+        if (ready && !peer.write(bytes)) peer.destroy();
+      }
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      for (const peer of peers.keys()) peer.destroy();
+      server.close();
+    },
+  };
+}

package/src/scope-compiler.ts

@@ -0,0 +1,105 @@
+import { snapshotJsonValue } from './json-value.js';
+
+export const SCOPE_MODES = ['readonly', 'readwrite', 'append'] as const;
+export type ScopeMode = (typeof SCOPE_MODES)[number];
+export type ScopeGrants = string | readonly string[];
+
+/** Inert path-prefix permission; paths are relative to the named mount. */
+export interface ScopeDescriptor {
+  mount: string;
+  path: string;
+  mode: ScopeMode;
+}
+
+/** Facts supplied by relayfile's mount manifest, never an author-side ACL. */
+export type MountRegistry = Readonly<Record<string, readonly {
+  path: string;
+  modes: readonly ScopeMode[];
+}[]>>;
+
+export interface ScopeDeclaration {
+  source: string;
+  stepId?: string;
+  grant: string;
+  scope: ScopeDescriptor;
+}
+
+export interface ScopeRefusal {
+  severity: 'refusal';
+  kind: 'scope_syntax_invalid' | 'mount_unknown' | 'scope_ungrantable';
+  message: string;
+  source: string;
+  stepId?: string;
+  grant?: string;
+  scope?: ScopeDescriptor;
+}
+
+export interface ScopeCompilation {
+  scopes: ScopeDeclaration[];
+  diagnostics: ScopeRefusal[];
+}
+
+export interface ScopeInput {
+  workspace?: ScopeGrants;
+  tools?: { fs?: ScopeGrants };
+  steps?: readonly { id: string; workspace?: ScopeGrants; tools?: { fs?: ScopeGrants } }[];
+}
+
+/** Reject ambiguous or traversing paths instead of normalizing permissions. */
+export function isScopePath(path: unknown): path is string {
+  return typeof path === 'string' && path.length > 0
+    && path.split('/').every(part => /^[A-Za-z0-9._-]+$/.test(part)
+      && part !== '.' && part !== '..');
+}
+
+export function parseScopeGrant(grant: string): ScopeDescriptor | undefined {
+  const match = /^([A-Za-z0-9_-]+)\/(.+):\s*(readonly|readwrite|append)$/.exec(grant);
+  if (match === null || match[0] !== grant || !isScopePath(match[2])) return undefined;
+  return { mount: match[1]!, path: match[2]!, mode: match[3] as ScopeMode };
+}
+
+/** One pure pass collects every declaration error before any live probe. */
+export function compileScopes(input: ScopeInput, mounts?: MountRegistry): ScopeCompilation {
+  const result: ScopeCompilation = { scopes: [], diagnostics: [] };
+  // Public callers may be JS: never run a getter while collecting permissions.
+  const flow = snapshotJsonValue(input, 'scope declarations') as unknown as ScopeInput;
+  function collect(value: unknown, source: string, stepId?: string): void {
+    if (value === undefined) return;
+    const location = { source, ...(stepId === undefined ? {} : { stepId }) };
+    const grants = Array.isArray(value) ? value : [value];
+    for (const grant of grants) {
+      const scope = typeof grant === 'string' ? parseScopeGrant(grant) : undefined;
+      if (scope === undefined) {
+        result.diagnostics.push({
+          ...location, severity: 'refusal', kind: 'scope_syntax_invalid',
+          ...(typeof grant === 'string' ? { grant } : {}),
+          message: `${source}: expected "<mount>/<path>: readonly|readwrite|append" with a canonical path prefix.`,
+        });
+        continue;
+      }
+      const declaration = { ...location, grant: grant as string, scope };
+      result.scopes.push(declaration);
+      if (mounts === undefined) continue; // Compiler does not invent environment facts.
+      if (!Object.hasOwn(mounts, scope.mount)) {
+        result.diagnostics.push({
+          ...declaration, severity: 'refusal', kind: 'mount_unknown',
+          message: `${source}: mount "${scope.mount}" is not present in the relayfile mount manifest.`,
+        });
+      } else if (!mounts[scope.mount]!.some(available =>
+        available.modes.includes(scope.mode)
+        && (scope.path === available.path || scope.path.startsWith(`${available.path}/`)))) {
+        result.diagnostics.push({
+          ...declaration, severity: 'refusal', kind: 'scope_ungrantable',
+          message: `${source}: relayfile cannot grant "${grant}" from the mount's available path permissions.`,
+        });
+      }
+    }
+  }
+  collect(flow.workspace, 'workspace');
+  collect(flow.tools?.fs, 'tools.fs');
+  for (const step of flow.steps ?? []) {
+    collect(step.workspace, `step "${step.id}".workspace`, step.id);
+    collect(step.tools?.fs, `step "${step.id}".tools.fs`, step.id);
+  }
+  return result;
+}

package/src/slack-preflight.ts

@@ -0,0 +1,25 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { helperProviders } from '@relayflows/surface/runtime';
+import { preflightHelpers } from './preflight.js';
+
+export function providerMount(provider: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const root = [env.RELAYFILE_MOUNT_PATH, env.WORKSPACE_ROOT, env.WORKFORCE_SANDBOX_ROOT,
+    env.RELAYFILE_MOUNT_ROOT, env.RELAYFILE_ROOT].find(value => value?.trim());
+  if (!root?.trim()) return undefined;
+  try { return statSync(join(root, provider)).isDirectory() ? root : undefined; }
+  catch { return undefined; }
+}
+
+export const slackMount = (env: NodeJS.ProcessEnv = process.env) => providerMount('slack', env);
+
+export function checkProviderHelpers(definition: Parameters<typeof preflightHelpers>[0]) {
+  return preflightHelpers(definition, {
+    providers: Object.fromEntries(helperProviders.map(p => [p.provider, {
+      mount: providerMount(p.provider) !== undefined,
+      mock: process.env[p.mockEnv] === '1',
+      token: p.provider === 'slack' ? process.env.SLACK_BOT_TOKEN : undefined,
+    }])),
+  });
+}
+export const checkSlackHelpers = checkProviderHelpers;