@relayflows/sdk 2.0.21 → 2.0.23

package/src/permissions-preflight.ts

@@ -0,0 +1,53 @@
+import type { CompiledFlowSpec } from './compile.js';
+import type { PermissionsSpec } from './spec.js';
+import type { PreflightWarning } from './preflight.js';
+
+/** Declared fields, reported in this order so two runs read identically. */
+const PERMISSION_FIELDS = ['fileGlobs', 'networkAllowlist', 'accessPreset'] as const;
+
+/**
+ * An agent step's `permissions` block is accepted by gate 1, lowered to
+ * `file_globs` / `network_allowlist` / `access_preset`, carried in the kernel
+ * step spec and journalled with it. Nothing reads it to gate a file or network
+ * access: enforcement is gate 8 (#442). A spec that declares it therefore
+ * looks sandboxed and is not, and until this warning existed nothing said so
+ * at authoring time.
+ *
+ * Every defined declaration warns, including `{}` and empty arrays. SURFACE.md
+ * accepts those without inferring defaults, and an empty block is exactly as
+ * likely to read to an author as "a default sandbox applies". Omitting
+ * `permissions` stays silent — there is no belief to correct.
+ *
+ * Warning-only: `ok` is unaffected, the declaration stays legal, and no value
+ * is echoed back (a glob or host is often the least interesting part of the
+ * declaration and can be long). The message names which fields were declared
+ * so the author can find them, and nothing more.
+ */
+export function permissionsDiagnostics(flow: CompiledFlowSpec): PreflightWarning[] {
+  const warnings: PreflightWarning[] = [];
+  for (const step of flow.steps) {
+    if (step.type !== 'agent' || step.permissions === undefined) continue;
+    warnings.push({
+      severity: 'warning',
+      kind: 'permissions_unenforced',
+      stepId: step.id,
+      message: permissionsMessage(step.id, step.permissions),
+    });
+  }
+  return warnings;
+}
+
+function permissionsMessage(stepId: string, permissions: PermissionsSpec): string {
+  const declared = PERMISSION_FIELDS.filter((field) => permissions[field] !== undefined);
+  const fields = declared.length === 0 ? '' : ` (${declared.join(', ')})`;
+  // `readonly` is the one value whose entire meaning is a guarantee, so it is
+  // the one value worth naming: an author reading "cannot write" needs to be
+  // told, in the same breath, that today nothing stops a write.
+  const preset = permissions.accessPreset === 'readonly'
+    ? " accessPreset: 'readonly' does not prevent writes."
+    : '';
+  return `Step "${stepId}" declares permissions${fields}. `
+    + 'This declaration is validated and recorded with the step spec; it is not '
+    + 'currently enforced (gate 8 / #442). These permissions do not restrict file '
+    + `or network access.${preset}`;
+}

package/src/preflight.ts

@@ -1,9 +1,11 @@
+import { communicationInstruction } from './communication/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 { permissionsDiagnostics } from './permissions-preflight.js';
 import type { TriggerSource } from '@relayflows/surface';
 import { acceptsAnyOutput, inspectStepGate, type StepGateInspection } from './gate-contract.js';
 import { compileSpec, CompileError } from './compile.js';
@@ -31,13 +33,24 @@ export interface CliResolution {
 
 export interface CliProbeResult {
   exists: boolean;
-  authenticated: boolean;
+  authenticated: boolean | 'unverified';
   /** False when a custom executable did not identify as a wrapper adapter. */
   supported?: boolean;
   /** Exact declared model passed the CLI's model-scoped readiness probe. */
   modelAvailable?: boolean;
   authCommand?: string;
   modelCommand?: string;
+  /** Exit code of the authentication probe, when it failed. */
+  authExitCode?: number | null;
+  /**
+   * Redacted output of a FAILED authentication probe.
+   *
+   * Present only on failure. Without it a `cli_unauthenticated` refusal can
+   * state that a probe exited non-zero and never what it said, which makes an
+   * intermittent probe failure impossible to tell apart from a genuinely
+   * unauthenticated CLI.
+   */
+  authFailureDetail?: string;
 }
 
 export type CliProbeFailureDetail =
@@ -69,7 +82,7 @@ export interface PreflightProbes {
    * model in scope, so readiness answers "can this CLI use THIS model" rather
    * than the weaker "is this CLI authenticated at all".
    */
-  cli(cli: string, source: CliResolutionSource, model?: string): CliProbeResult;
+  cli(cli: string, source: CliResolutionSource, model?: string, execution?: 'managed'): CliProbeResult;
   executor(trigger: TriggerSpec): boolean;
   command(binary: string): boolean;
 }
@@ -223,6 +236,11 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
   const resolutionByStep = new Map<string, CliResolution>();
   const cliProbeResults = new Map<string, CliProbeOutcome>();
 
+  // A pure fact about the compiled snapshot, collected before anything that
+  // can return early. An unresolved CLI, an unknown model or a bad scope all
+  // refuse below without probing, and the author should still be told that the
+  // permissions they declared on the same file are not enforced.
+  diagnostics.push(...permissionsDiagnostics(compiled));
   diagnostics.push(...scopeDiagnostics(compiled, options));
   for (const server of new Set(options.mcpServers ?? [])) {
     if (options.mcp !== undefined && Object.hasOwn(options.mcp, server)) continue;
@@ -286,7 +304,8 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
       continue;
     }
     const resolution = resolutionByStep.get(step.id)!;
-    probeResolvedCli(resolution, options.probes, cliProbeResults, diagnostics);
+    probeResolvedCli(resolution, options.probes, cliProbeResults, diagnostics,
+      step.type === 'agent' && communicationInstruction(step.instruction) !== undefined);
   }
 
   for (const trigger of compiled.triggers ?? []) {
@@ -447,6 +466,7 @@ function probeResolvedCli(
   probes: PreflightProbes,
   cache: Map<string, CliProbeOutcome>,
   diagnostics: PreflightDiagnostic[],
+  managed = false,
 ): void {
   // Source is load-bearing: the same relative CLI string resolves from the
   // flow directory for step/named/flow declarations and the config directory for
@@ -454,11 +474,13 @@ function probeResolvedCli(
   // Model is part of the key: the same CLI probed with two different models
   // is two different questions, and caching on the CLI alone would let a
   // model that the CLI cannot resolve inherit an earlier model's pass.
-  const cacheKey = JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null]);
+  const cacheKey = JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
   let outcome = cache.get(cacheKey);
   if (outcome === undefined) {
     try {
-      outcome = { result: probes.cli(resolution.cli, resolution.source, resolution.model) };
+      outcome = { result: managed
+        ? probes.cli(resolution.cli, resolution.source, resolution.model, 'managed')
+        : probes.cli(resolution.cli, resolution.source, resolution.model) };
     } catch (error) {
       const detail = error instanceof CliProbeError ? error.detail : undefined;
       outcome = { failure: detail ?? null };
@@ -494,14 +516,27 @@ function probeResolvedCli(
       cli: resolution.cli,
       message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but it is neither a supported raw Claude/Codex executable nor a conforming Relayflows wrapper; custom wrappers must identify with the relayflows-agent-cli-v1 contract.`,
     });
-  } else if (!result.authenticated) {
+  } else if (managed && result.authenticated === 'unverified') {
+    diagnostics.push({ severity: 'warning', kind: 'managed_cli_unverified', stepId: resolution.stepId,
+      message: `Step "${resolution.stepId}" uses Relay's interactive CLI transport. The executable exists, but authentication${resolution.model ? ' and access to model "' + resolution.model + '"' : ''} could not be verified before startup. The managed session must execute its task and report completion; startup or task failure fails the step.` });
+  } else if (result.authenticated !== true) {
     const command = result.authCommand ?? `${resolution.cli} auth status`;
+    // Say what the probe reported. A refusal that names only the command turns
+    // a transient provider rejection and a genuinely unauthenticated CLI into
+    // the same message, and the difference decides whether retrying is
+    // correct.
+    const exitCode = result.authExitCode === undefined || result.authExitCode === null
+      ? ''
+      : ` (exit ${result.authExitCode})`;
+    const detail = result.authFailureDetail !== undefined && result.authFailureDetail.length > 0
+      ? ` It reported: ${result.authFailureDetail}`
+      : ' It produced no output, so the reason is unavailable.';
     diagnostics.push({
       severity: 'refusal',
       kind: 'cli_unauthenticated',
       stepId: resolution.stepId,
       cli: resolution.cli,
-      message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but "${command}" exited non-zero; authenticate it or repair that adapter's authentication probe.`,
+      message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but "${command}" exited non-zero${exitCode}; authenticate it or repair that adapter's authentication probe.${detail}`,
     });
   } else if (resolution.model !== undefined && result.modelAvailable !== true) {
     diagnostics.push({

package/src/protocol.ts

@@ -55,6 +55,9 @@ export type Verb =
   | 'step.wait'
   | 'event.emit'
   | 'event.submit'
+  | 'channel.append'
+  | 'channel.receive'
+  | 'channel.ack'
   | 'stream.append'
   | 'stream.read'
   | 'journal.read';
@@ -160,6 +163,8 @@ export interface WorkerAttachParams {
   step_types: StepType[];
   /** Maximum concurrent assignments. Omitted means the conservative default 1. */
   capacity?: number;
+  /** Accept only agent steps declaring every named stream (must also be pinned). */
+  required_streams?: string[];
   /**
    * The surfaces this worker holds, as opaque revisions/offsets. Required when
    * `step_types` includes `agent` — an agent attempt's start pins come from
@@ -411,7 +416,17 @@ export interface JournalReadResult {
 }
 
 /** Typed map of verb -> { params, result }. Used by the client for type-safety. */
+export interface ChannelIdentity {
+  run_id: string; step_id: string; attempt: number; idempotency_key: string; channel: string;
+}
+export interface ChannelEntry {
+  seq: number;
+  payload: { channel: string; offset: number; message?: unknown; producer?: string; consumer?: string; message_id?: string; delivery_seq?: number };
+}
 export interface VerbContract {
+  'channel.append': { params: ChannelIdentity & { message_id: string; message: unknown }; result: ChannelEntry };
+  'channel.receive': { params: ChannelIdentity; result: ChannelEntry | null };
+  'channel.ack': { params: ChannelIdentity & { delivery_seq: number }; result: ChannelEntry };
   hello: { params: HelloParams; result: HelloResult };
   'run.start': { params: RunStartParams; result: RunStartResult };
   'run.resume': { params: RunResumeParams; result: RunResumeResult };

package/src/pty-sidechannel.ts

@@ -6,6 +6,13 @@ export interface SidechannelContext {
   dataDir: string;
   runId: string;
   stepId: string;
+  /**
+   * Which attempt this is. Names the per-attempt transcript file
+   * (`agent-transcript.ts`) and the transcript tails (`transcript-tail.ts`),
+   * and is exported into the agent's environment. Optional: without it there
+   * is no attempt to name, so neither file is written.
+   */
+  attempt?: number;
   onReady?: (path: string) => void;
   onDrive: () => void;
 }

package/src/redact.ts

@@ -0,0 +1,106 @@
+// Redaction for free text an agent-facing surface may print.
+//
+// `flows status` renders gate `detail`, transcript tails and error messages
+// to a process that may be an agent, in a sandbox whose stdout is captured.
+// A direct agent inherits the worker's whole environment (worker-cli.ts), so
+// anything the operator exported can be echoed back into that text. This
+// module is the one place that decides what never reaches the page.
+//
+// Applied to free text only. Identifiers — run ids, step ids, hashes and env
+// NAMES — are never rewritten, so the view stays greppable.
+
+/** Env names whose values are treated as secret when they are long enough. */
+const SECRET_NAME = /TOKEN|SECRET|KEY|PASSWORD|PASSWD|CREDENTIAL|AUTH/i;
+
+/** Shorter values are flags and modes (`AUTH_MODE=off`), not material. */
+const MIN_SECRET_LENGTH = 8;
+
+/**
+ * Token shapes replaced wholesale. The first is the relay token family
+ * `redactRelayError` in worker-cli.ts already scrubbed; the rest are the
+ * bearer, header and vendor shapes a gate render can carry.
+ */
+const TOKEN_PATTERNS: readonly RegExp[] = [
+  /\b(?:at|rk|nt|ot|br|arr)_(?:live_)?[A-Za-z0-9_-]+/g,
+  /\bsk-[A-Za-z0-9_-]{16,}/g,
+  /\bghp_[A-Za-z0-9]{20,}/g,
+  /\bxox[abp]-[A-Za-z0-9-]+/g,
+];
+
+/**
+ * Header and assignment shapes: keep the name (and an auth scheme), replace
+ * the value. A value already replaced by an earlier pass is left as it is,
+ * so the reader still sees which env name it came from.
+ */
+const NAMED_VALUE_PATTERNS: readonly RegExp[] = [
+  /\b(authorization:\s*(?:\w+\s+)?)(?!\[redacted)\S+/gi,
+  /\b(Bearer\s+)(?!\[redacted)\S+/g,
+  /\b(x-callback-token:\s*)(?!\[redacted)\S+/gi,
+  /\b(x-nightcto-evidence-token:\s*)(?!\[redacted)\S+/gi,
+  /\b([A-Z0-9_]*(?:TOKEN|SECRET|KEY|PASSWORD)=)(?!\[redacted)\S+/gi,
+];
+
+/**
+ * Credential fields in serialized JSON. A gate detail or a transcript line
+ * often carries a request or config body, where the value is an opaque string
+ * that matches no vendor token shape and — for anything this process did not
+ * export — no environment value either: `{"authToken":"opaque-secret"}` went
+ * through untouched. The field name is kept, so the reader knows what was cut.
+ *
+ * Quoted string values only — including escaped ones: a serialized private
+ * key or nested JSON reaches these fields as `\n` and `\"`, and a value
+ * class that stopped at the first backslash left every one of them intact.
+ * Only where the field NAME ends in a credential noun. Containing one is not enough: `monkey` and `keyboard` are
+ * ordinary fields, so the name is split on separators and camelCase humps and
+ * the last word decides.
+ */
+const JSON_STRING_FIELD = /("([A-Za-z0-9_.\-]{1,64})"\s*:\s*")(?!\[redacted)((?:[^"\\]|\\.){4,})(")/g;
+const CREDENTIAL_NOUN = /^(?:token|secret|key|password|passwd|credential|cookie)s?$/i;
+
+function isCredentialName(name: string): boolean {
+  if (name.toLowerCase() === 'authorization') return true;
+  const words = name.split(/[_\-.]+/).flatMap((word) => word.split(/(?<=[a-z0-9])(?=[A-Z])/u));
+  const last = words.at(-1);
+  return last !== undefined && CREDENTIAL_NOUN.test(last);
+}
+
+/** Secret env values, longest first so a value that contains another is replaced whole. */
+function secretEnvValues(env: NodeJS.ProcessEnv): Array<[name: string, value: string]> {
+  const secrets: Array<[string, string]> = [];
+  for (const [name, value] of Object.entries(env)) {
+    if (typeof value !== 'string' || value.length < MIN_SECRET_LENGTH) continue;
+    if (SECRET_NAME.test(name)) secrets.push([name, value]);
+  }
+  return secrets.sort((a, b) => b[1].length - a[1].length);
+}
+
+/**
+ * Scrub secret env values and known token shapes out of `text`.
+ *
+ * An env value is replaced by `[redacted:<NAME>]` so the reader learns which
+ * variable leaked without learning its value. Token shapes are replaced by
+ * `[redacted]`; header and `NAME=value` shapes keep their name.
+ */
+export function redact(text: string, env: NodeJS.ProcessEnv = process.env): string {
+  let out = text;
+  for (const [name, value] of secretEnvValues(env)) out = out.replaceAll(value, `[redacted:${name}]`);
+  for (const pattern of TOKEN_PATTERNS) out = out.replace(pattern, '[redacted]');
+  for (const pattern of NAMED_VALUE_PATTERNS) out = out.replace(pattern, '$1[redacted]');
+  out = out.replace(JSON_STRING_FIELD, (match, open: string, name: string, _value: string, close: string) =>
+    isCredentialName(name) ? `${open}[redacted]${close}` : match);
+  return out;
+}
+
+/**
+ * The relay-transport error scrub `worker-cli.ts` has always applied: the two
+ * relay credential names by exact match, at any length, spelled `[redacted]`.
+ * Everything `redact` adds is applied after, so the historical output for
+ * those two names and the token pattern is unchanged.
+ */
+export function redactRelayError(message: string, env: NodeJS.ProcessEnv = process.env): string {
+  for (const key of ['RELAY_AGENT_TOKEN', 'RELAY_API_KEY']) {
+    const secret = env[key];
+    if (secret) message = message.replaceAll(secret, '[redacted]');
+  }
+  return redact(message, env);
+}