@relayflows/sdk 2.0.50 → 2.0.52

package/src/cloud-http.ts

@@ -290,7 +290,7 @@ export function isCloudRecord(value: unknown): value is Record<string, unknown>
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function transportError(error: unknown): CloudFlowError {
+export function transportError(error: unknown): CloudFlowError {
   const cause = error instanceof Error ? error.cause : undefined;
   const code = isCloudRecord(cause) ? cause.code : undefined;
   const transient = (error instanceof Error && error.name === 'TimeoutError')

package/src/cloud-run.ts

@@ -14,7 +14,7 @@ import {
   type CloudConnectionOptions,
 } from './cloud-http.js';
 import { cloudRunState, isCloudRunActive, type CloudRunState } from './cloud-run-record.js';
-import { packWorkingTree, prepareCloudSync, uploadCloudCode } from './cloud-sync.js';
+import { canUseCodeCache, packWorkingTree, prepareCloudSync, sha256PackedTree, uploadCloudCode } from './cloud-sync.js';
 
 export type CloudFlowSource = FlowSpec | { path: string };
 export const MIN_CLOUD_RUN_BUDGET_MINUTES = 30;
@@ -65,7 +65,7 @@ export interface CloudRunReceipt {
   specHash: string;
   /** Authenticated run API resource; this is not a public sharing URL. */
   apiUrl: string;
-  /** Present when a working tree was synced: what was uploaded, by count and size. */
+  /** Present when a working tree was synced: its file count and uncompressed size. */
   synced?: { files: number; bytes: number; skippedLinks: string[] };
 }
 export interface CloudAuthoredAuthority {
@@ -119,6 +119,31 @@ function snapshotEnvSecrets(value: unknown): Record<string, string> | undefined
   return Object.keys(copy).length === 0 ? undefined : copy;
 }
 
+/**
+ * A Cloud refusal is Cloud's own text. Should any of it ever quote an
+ * envSecrets value — the message, or a field such as `expected`/`received` —
+ * keep only a safe refusal code and drop the rest, so the value never reaches
+ * an error message, a log line or a caller's error report.
+ */
+function withheldIfQuotingSecret(error: unknown, envSecrets: Record<string, string> | undefined): unknown {
+  if (envSecrets === undefined || !(error instanceof CloudFlowError) || error.refusal === undefined) return error;
+  const values = Object.values(envSecrets).filter(value => value.length > 0);
+  const quotes = (text: string): boolean => values.some(value => text.includes(value));
+  if (!quotes(error.message) && !refusalStrings(error.refusal).some(quotes)) return error;
+  const code = quotes(error.refusal.code) ? 'withheld' : error.refusal.code;
+  return new CloudFlowError(error.code,
+    `Cloud refused (${code}); its message was withheld because it quoted an envSecrets value.`,
+    error.status, { code, error: 'withheld: quoted an envSecrets value' });
+}
+
+/** Every string anywhere in a refusal, so a field added later is checked too. */
+function refusalStrings(value: unknown): string[] {
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value)) return value.flatMap(refusalStrings);
+  if (value !== null && typeof value === 'object') return Object.values(value).flatMap(refusalStrings);
+  return [];
+}
+
 /**
  * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
  * happens here; Cloud owns provisioning and the Rust engine owns execution.
@@ -275,32 +300,44 @@ export async function runInCloud(
   // under it, so the run request below names code Cloud already holds. A
   // refused backend or failed upload therefore never leaves a launched run
   // pointing at a tree that is not there.
-  let synced: { runId: string; codeKey: string; files: number; bytes: number; skippedLinks: string[] } | undefined;
+  let synced: { runId: string; codeKey: string; codeCacheHit: boolean; files: number; bytes: number; skippedLinks: string[] } | undefined;
   if (options.syncCode !== undefined) {
-    const prepared = await prepareCloudSync(options);
     options.signal?.throwIfAborted();
     const packed = await packWorkingTree(options.syncCode.root);
+    let prepared: Awaited<ReturnType<typeof prepareCloudSync>>;
     try {
       options.signal?.throwIfAborted();
-      await uploadCloudCode(prepared, packed, options);
+      const digest = canUseCodeCache(packed) ? await sha256PackedTree(packed) : undefined;
+      prepared = await prepareCloudSync(options, digest);
+      options.signal?.throwIfAborted();
+      if (!prepared.codeCacheHit) await uploadCloudCode(prepared, packed, options);
     } finally {
       packed.dispose();
     }
-    synced = { runId: prepared.runId, codeKey: prepared.codeKey, files: packed.files.length, bytes: packed.bytes,
+    synced = { runId: prepared.runId, codeKey: prepared.codeKey, codeCacheHit: prepared.codeCacheHit === true,
+      files: packed.files.length, bytes: packed.bytes,
       skippedLinks: packed.skippedLinks };
   }
   options.signal?.throwIfAborted();
   options.onSubmit?.();
   let result: unknown;
   try {
-    result = await cloudFetch('/api/v1/workflows/run', options, { method: 'POST', detail: true, body: JSON.stringify({
+    // A cache hit is copied into the run prefix after admission. The R2 copy
+    // may outlast the normal 30s request budget; explicit caller limits win.
+    const submitOptions = synced?.codeCacheHit
+      ? { ...options, requestTimeoutMs: options.requestTimeoutMs ?? 300_000 }
+      : options;
+    result = await cloudFetch('/api/v1/workflows/run', submitOptions, { method: 'POST', detail: true, body: JSON.stringify({
       ...cloudSubmissionBody(submission),
       ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
       ...(options.runBudgetMinutes === undefined ? {} : { relayflowV2RunBudgetMinutes: options.runBudgetMinutes }),
       ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
       ...(envSecrets === undefined ? {} : { envSecrets }),
     }) });
-  } catch (error) {
+  } catch (caught) {
+    // Withhold first: every error thrown from here, including the rewrite
+    // below, carries only a refusal that quotes no envSecrets value.
+    const error = withheldIfQuotingSecret(caught, envSecrets);
     // Cloud accepts exactly one authored Surface (the one its sandbox runs).
     // A CLI on another release is refused with this code; say which side is
     // which instead of leaving the user with a bare 400 (flows#461).

package/src/cloud-signal.ts

@@ -0,0 +1,110 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { CloudFlowError, cloudFetch, cloudRunId, isCloudRecord, resolveCloudConnection,
+  transportError, type CloudConnectionOptions } from './cloud-http.js';
+
+const SIGNAL_NAME = /^[A-Za-z0-9_-]{1,80}$/u;
+const MAX_BYTES = 4 * 1024;
+const HELD_GET_MS = 25_000;
+const HOSTED_SIGNAL_READ_TOKEN_ENV = 'RELAYFLOW_V2_SIGNAL_READ_TOKEN';
+
+function signalPath(runId: string, name: string): string {
+  cloudRunId(runId);
+  if (!SIGNAL_NAME.test(name)) {
+    throw new CloudFlowError('invalid_input', 'Signal name must contain only letters, digits, underscores, or hyphens (1–80 characters).');
+  }
+  return `/api/v1/workflows/runs/${runId}/signals/${name}`;
+}
+
+/** Store a run-scoped completion. Retrying the same JSON payload is safe. */
+export async function postCloudSignal(
+  runId: string, name: string, payload: unknown, options: CloudConnectionOptions = {},
+): Promise<{ accepted: true; duplicate: boolean }> {
+  const path = signalPath(runId, name);
+  if (payload === undefined) throw new CloudFlowError('invalid_input', 'Signal payload must be present.');
+  let body: string;
+  try { body = JSON.stringify({ payload }); }
+  catch { throw new CloudFlowError('invalid_input', 'Signal payload must be JSON serializable.'); }
+  // JSON.stringify omits a function, symbol, or toJSON() result of undefined.
+  // This envelope has only one field, so {} means the payload was lost.
+  if (body === '{}') throw new CloudFlowError('invalid_input', 'Signal payload must be JSON serializable.');
+  if (new TextEncoder().encode(body).byteLength > MAX_BYTES) {
+    throw new CloudFlowError('invalid_input', 'Signal payload exceeds 4 KiB.');
+  }
+  const result = await cloudFetch(path, options, { method: 'POST', body, detail: true });
+  if (!isCloudRecord(result) || result.accepted !== true || typeof result.duplicate !== 'boolean') {
+    throw new CloudFlowError('invalid_response', 'Cloud returned an invalid signal receipt.');
+  }
+  return { accepted: true, duplicate: result.duplicate };
+}
+
+/**
+ * Wait on Cloud's held GET. A normally held 204 re-arms immediately. A fast
+ * 204 backs off so a proxy or broken server cannot turn this into a hot loop.
+ */
+export async function waitForCloudSignal(
+  runId: string, name: string, options: CloudConnectionOptions = {},
+): Promise<unknown> {
+  const path = signalPath(runId, name);
+  const requestTimeout = options.requestTimeoutMs ?? 30_000;
+  if (!Number.isSafeInteger(requestTimeout) || requestTimeout <= HELD_GET_MS) {
+    throw new CloudFlowError('invalid_input', 'Signal requestTimeoutMs must exceed 25 seconds.');
+  }
+  let fast204BackoffMs = 250;
+  for (;;) {
+    options.signal?.throwIfAborted();
+    let connection: { baseUrl: string; token: string };
+    try {
+      connection = await resolveCloudConnection(options);
+    } catch (error) {
+      // The hosted run's read-only credential is only a fallback for waits.
+      // Explicit Cloud credentials and stored logins retain precedence, and
+      // postCloudSignal never sees this token.
+      const hostedToken = process.env[HOSTED_SIGNAL_READ_TOKEN_ENV];
+      if (!(error instanceof CloudFlowError) || error.code !== 'configuration'
+        || error.reason !== 'auth_missing' || options.token !== undefined
+        || process.env['FLOWS_CLOUD_TOKEN'] !== undefined || hostedToken === undefined) throw error;
+      connection = await resolveCloudConnection({ ...options, token: hostedToken });
+    }
+    const { baseUrl, token } = connection;
+    const deadline = AbortSignal.timeout(requestTimeout);
+    const requestStartedAt = performance.now();
+    let response: Response;
+    try {
+      response = await fetch(`${baseUrl}${path}?waitMs=${HELD_GET_MS}`, {
+        method: 'GET',
+        headers: { authorization: `Bearer ${token}` },
+        signal: options.signal ? AbortSignal.any([options.signal, deadline]) : deadline,
+        redirect: 'error',
+      });
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      throw transportError(deadline.aborted ? deadline.reason : error);
+    }
+    if (response.status === 204) {
+      if (performance.now() - requestStartedAt < 1_000) {
+        try {
+          await delay(fast204BackoffMs, undefined, { signal: options.signal });
+        } catch (error) {
+          options.signal?.throwIfAborted();
+          throw error;
+        }
+        fast204BackoffMs = Math.min(fast204BackoffMs * 2, 5_000);
+      } else {
+        fast204BackoffMs = 250;
+      }
+      continue;
+    }
+    if (!response.ok) throw new CloudFlowError('http_error', `Cloud signal wait failed with HTTP ${response.status}.`, response.status);
+    let body: unknown;
+    try { body = await response.json(); }
+    catch (error) {
+      options.signal?.throwIfAborted();
+      if (!(error instanceof SyntaxError)) throw transportError(deadline.aborted ? deadline.reason : error);
+      throw new CloudFlowError('invalid_response', 'Cloud returned an invalid signal.');
+    }
+    if (!isCloudRecord(body) || !Object.hasOwn(body, 'payload') || typeof body.acceptedAt !== 'number') {
+      throw new CloudFlowError('invalid_response', 'Cloud returned an invalid signal.');
+    }
+    return body.payload;
+  }
+}

package/src/cloud-sync.ts

@@ -1,11 +1,12 @@
 import { spawnSync } from 'node:child_process';
-import { createReadStream, createWriteStream, existsSync, lstatSync, mkdtempSync, readdirSync, readlinkSync, rmSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { createReadStream, createWriteStream, existsSync, lstatSync, mkdtempSync, readdirSync, readlinkSync, rmSync, statSync } from 'node:fs';
+import { open, readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createGzip } from 'node:zlib';
+import { createHash } from 'node:crypto';
 import {
   CloudFlowError, cloudFetch, cloudRequest, cloudRunId, isCloudRecord, type CloudConnectionOptions,
 } from './cloud-http.js';
@@ -25,6 +26,8 @@ import {
 
 /** Uncompressed bytes. Matches the sandbox's extraction budget with headroom. */
 export const MAX_SYNC_BYTES = 256 * 1024 * 1024;
+/** Above this compressed size, use the unchanged legacy upload path. */
+export const MAX_CACHED_CODE_BYTES = 64 * 1024 * 1024;
 const ALWAYS_SKIPPED = new Set(['.git', 'node_modules']);
 const CODE_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 
@@ -33,11 +36,14 @@ export interface PreparedCloudSync {
   codeKey: string;
   /** Run-scoped upload credential from `prepare`; falls back to the session token. */
   uploadToken?: string;
+  /** Cloud confirmed the immutable archive already exists in this workspace. */
+  codeCacheHit?: boolean;
 }
 
 /** `POST /api/v1/workflows/prepare`, refusing every non-Cloud-API storage backend. */
-export async function prepareCloudSync(options: CloudConnectionOptions): Promise<PreparedCloudSync> {
-  const receipt = await cloudFetch('/api/v1/workflows/prepare', options, { method: 'POST' });
+export async function prepareCloudSync(options: CloudConnectionOptions, codeSha256?: string): Promise<PreparedCloudSync> {
+  const receipt = await cloudFetch('/api/v1/workflows/prepare', options,
+    { method: 'POST', ...(codeSha256 ? { body: JSON.stringify({ codeSha256 }) } : {}) });
   if (!isCloudRecord(receipt)) throw new CloudFlowError('invalid_response', 'Cloud prepare returned a non-object.');
   const storage = isCloudRecord(receipt.workflowStorage) ? receipt.workflowStorage : undefined;
   const credentials = isCloudRecord(receipt.s3Credentials) ? receipt.s3Credentials : undefined;
@@ -49,6 +55,15 @@ export async function prepareCloudSync(options: CloudConnectionOptions): Promise
   }
   const codeKey = typeof receipt.s3CodeKey === 'string' ? receipt.s3CodeKey : '';
   if (!CODE_KEY.test(codeKey)) throw new CloudFlowError('invalid_response', 'Cloud prepare returned an unusable code key.');
+  const codeCache = isCloudRecord(receipt.codeCache) ? receipt.codeCache : undefined;
+  let codeCacheHit: boolean | undefined;
+  if (codeSha256 && (codeCache !== undefined || codeKey.startsWith('code-sha256-'))) {
+    if (!codeCache || codeCache.sha256 !== codeSha256 || typeof codeCache.hit !== 'boolean'
+      || codeKey !== `code-sha256-${codeSha256}.tar.gz`) {
+      throw new CloudFlowError('invalid_response', 'Cloud prepare returned an inconsistent code cache receipt.');
+    }
+    codeCacheHit = codeCache.hit;
+  }
   const uploadToken = credentials?.cloudApiAccessToken;
   if (uploadToken !== undefined && typeof uploadToken !== 'string') {
     throw new CloudFlowError('invalid_response', 'Cloud prepare returned an unusable storage credential.');
@@ -56,9 +71,17 @@ export async function prepareCloudSync(options: CloudConnectionOptions): Promise
   return {
     runId: cloudRunId(receipt.runId), codeKey,
     ...(uploadToken === undefined ? {} : { uploadToken }),
+    ...(codeCacheHit === undefined ? {} : { codeCacheHit }),
   };
 }
 
+/** Hash the deterministic compressed archive without loading it into memory. */
+export async function sha256PackedTree(packed: PackedTree): Promise<string> {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(packed.archivePath)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
 export interface PackedTree {
   /** The gzip'd ustar, spooled to a temporary file; `dispose()` removes it. */
   archivePath: string;
@@ -125,6 +148,14 @@ export async function packWorkingTree(root: string): Promise<PackedTree> {
   }
   try {
     await pipeline(Readable.from(flatten(entries())), createGzip({ level: 6 }), createWriteStream(archivePath));
+    // zlib's OS byte can vary by platform while the tar contents are equal.
+    // 255 means unknown OS and does not affect decompression.
+    const archive = await open(archivePath, 'r+');
+    try {
+      await archive.write(Buffer.from([255]), 0, 1, 9);
+    } finally {
+      await archive.close();
+    }
   } catch (error) {
     dispose();
     throw error;
@@ -132,6 +163,10 @@ export async function packWorkingTree(root: string): Promise<PackedTree> {
   return { archivePath, files: members, bytes, skippedLinks, dispose };
 }
 
+export function canUseCodeCache(packed: PackedTree): boolean {
+  return statSync(packed.archivePath).size <= MAX_CACHED_CODE_BYTES;
+}
+
 /** Yield file streams chunk by chunk so `Readable.from` never buffers a whole file. */
 async function* flatten(source: AsyncGenerator<Buffer | NodeJS.ReadableStream>): AsyncGenerator<Buffer> {
   for await (const part of source) {

package/src/communication/environment.ts

@@ -1,14 +1,20 @@
 import { basename } from 'node:path';
 import { wrapperEnvironment } from '../wrapper-runtime.js';
+import { deliveredNames, isCliLoginName, platformAgentNames, repositoryEnvironmentNames,
+  validateStepSecrets } from '../step-secrets.js';
 
 const terminalNames = ['TERM', 'COLORTERM', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME'];
+const networkNames = ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+  'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy'];
 const relayNames = ['RELAY_API_KEY', 'RELAY_WORKSPACE_KEY', 'AGENT_RELAY_WORKSPACE_KEY',
   'RELAY_BROKER_API_KEY', 'RELAY_AGENT_TOKEN', 'RELAY_NODE_TOKEN', 'RELAY_WORKSPACES_JSON'];
 // Multi-provider CLIs select their provider in their own configuration.
 const multiProvider = ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL',
   'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'OPENROUTER_API_KEY'] as const;
 const providerNames: Readonly<Record<string, readonly string[]>> = {
-  claude: ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CONFIG_DIR'],
+  claude: ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CONFIG_DIR',
+    'CLAUDE_CODE_USE_BEDROCK', 'AWS_BEARER_TOKEN_BEDROCK', 'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN', 'AWS_REGION', 'AWS_DEFAULT_REGION'],
   codex: ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'CODEX_HOME'],
   gemini: ['GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GOOGLE_APPLICATION_CREDENTIALS', 'GOOGLE_CLOUD_PROJECT', 'GOOGLE_CLOUD_LOCATION'],
   // AgentWorkforce/cloud#4026 passes both endpoint names unchanged as aliases
@@ -32,9 +38,28 @@ export function brokerEnvironment(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv
   return { ...Object.fromEntries(Object.keys(source).map(name => [name, undefined])),
     ...wrapperEnvironment(source), ...selected(source, [...terminalNames, 'RELAY_BASE_URL']) };
 }
-export function agentEnvironment(cli: string, source: NodeJS.ProcessEnv = process.env): Record<string, string> {
+export function agentEnvironment(cli: string, source: NodeJS.ProcessEnv = process.env,
+  grants?: string[], scopeSecrets = true): Record<string, string> {
   // Broker transport credentials must not become CLI credentials. The harness
   // protocol accepts string values, so clear those inherited names explicitly.
+  const cliName = basename(cli).replace(/\.exe$/i, '');
+  const credentials = { ...selected(source, providerNames[cliName] ?? []),
+    ...selected(source, [...repositoryEnvironmentNames(source), ...networkNames]) };
+  if (!scopeSecrets && grants?.length) {
+    throw new Error('per-step secret grants require a daemon with step_secret_scoping support');
+  }
+  const names = deliveredNames(source);
+  const platform = platformAgentNames(source, cliName);
+  const allowed = scopeSecrets ? validateStepSecrets(grants, source) : [];
+  if (allowed.some(name => relayNames.includes(name))) {
+    throw new Error('Relay broker credentials cannot be granted to a communication agent');
+  }
+  for (const name of names ?? []) {
+    if (!allowed.includes(name) && !platform.has(name)
+      && !isCliLoginName(cliName, name, providerNames[cliName])) {
+      delete credentials[name];
+    }
+  }
   return { ...Object.fromEntries(relayNames.map(name => [name, ''])),
-    ...selected(source, providerNames[basename(cli).replace(/\.exe$/i, '')] ?? []) } as Record<string, string>;
+    ...credentials, ...selected(source, allowed) } as Record<string, string>;
 }

package/src/communication/worker.ts

@@ -103,7 +103,8 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
     handle = await relay.broker.spawnPty({ name, cli: basename(cliIdentity).replace(/\.exe$/i, ''), task: prompt, channels: [], skipRelayPrompt: true,
       model: resolveCliModel(cliIdentity, spec.model), cwd: directory,
       harnessConfig: { runtime: 'pty', command: quote(command), args: [],
-        cwd: directory, env: { ...agentEnvironment(cliIdentity, environment ?? process.env),
+        cwd: directory, env: { ...agentEnvironment(cliIdentity, environment ?? process.env,
+          spec.secrets, client.supportsFeature?.('step_secret_scoping') ?? true),
           RELAYFLOW_COMMUNICATION_SOCKET: tools.path, RELAYFLOW_COMMUNICATION_TOKEN: tools.token },
         delivery: { mode: 'pty-injection', format: 'relay-block' } } });
     const ready = await handle.waitForReady(Math.min(instruction.timeoutMs, 90_000));

package/src/compile.ts

@@ -192,6 +192,7 @@ function compileStep(step: StepSpec): StepSpec {
   const base = {
     id: step.id,
     type: step.type,
+    ...(step.secrets?.length ? { secrets: step.secrets } : {}),
     ...((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 } : {}),
@@ -466,7 +467,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
   const unionKeys = [
     'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input',
     'command', 'timeout_ms', 'lease_ms', 'on_non_zero', 'prompt', 'model', 'cli', 'instruction',
-    'cwd', 'resume', 'recovery_mode', 'surfaces', 'permissions', 'transport', 'cli_identity',
+    'cwd', 'resume', 'recovery_mode', 'surfaces', 'permissions', 'transport', 'cli_identity', 'secrets',
   ] as const;
   const step = requireKernelObject(value, unionKeys, at);
   if (step['cli_identity'] !== undefined) {
@@ -475,7 +476,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
     ], 'untrusted_cli_identity');
   }
   const type = step['type'];
-  const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input'] as const;
+  const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input', 'secrets'] as const;
   const typeKeys = type === 'deterministic'
     ? ['command', 'timeout_ms', 'lease_ms', 'on_non_zero'] as const
     : type === 'llm'
@@ -491,6 +492,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
     id: step['id'],
     type,
     ...(step['input'] !== undefined ? { input: step['input'] } : {}),
+    ...(step['secrets'] !== undefined ? { secrets: step['secrets'] } : {}),
     ...(step['requirements'] !== undefined ? { requirements: kernelRequirementsToAuthoring(step['requirements'], `${at}.requirements`) } : {}),
     ...(dependsOn !== undefined && (!Array.isArray(dependsOn) || dependsOn.length > 0)
       ? { dependsOn }
@@ -636,6 +638,7 @@ function isObject(value: unknown): value is Record<string, unknown> {
 function toKernelStep(step: StepSpec, cliIdentity?: string): ResolvedKernelStepSpec {
   const common: ResolvedKernelStepCommon = {
     id: step.id,
+    ...(step.secrets?.length ? { secrets: step.secrets } : {}),
     depends_on: step.input === undefined ? step.dependsOn ?? []
       : [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])],
     ...(step.input !== undefined ? { input: step.input } : {}),

package/src/failure-kinds.ts

@@ -134,6 +134,8 @@ export const RUN_FAILURE_KINDS = [
   'run_parked',
   'run_declined',
   'run_unavailable',
+  /** A pinned parallel root is still active, but this process cannot safely dispatch it. */
+  'unsafe_parallel_runtime',
   /** A predicate `.gate(fn)` judged false; the verdict is journaled as `<step>.gate`. */
   'gate_failed',
   /** `flows answer` named a wait the run is not asking: unknown, or already answered. */

package/src/index.ts

@@ -81,6 +81,7 @@ export {
 } from './flow-extension-loader.js';
 
 export { CloudFlowError, type CloudConnectionOptions, type CloudConfigurationReason } from './cloud-http.js';
+export { postCloudSignal, waitForCloudSignal } from './cloud-signal.js';
 export {
   listCloudRuns, getCloudRunDetail, getCloudRunSteps, getCloudRunLog,
   type CloudRunSummary, type CloudRunList, type CloudRunDetail, type CloudStep, type CloudStepAttempt,

package/src/journal-client.ts

@@ -25,6 +25,8 @@ import {
   type StepUsage,
 } from './protocol.js';
 import type { KernelRunSpec, StepType } from './spec.js';
+import { PLATFORM_AGENT_ENV_NAMES, SECRET_ENV_NAMES, SIGNAL_READ_TOKEN_ENV,
+  deliveredNames, validateStepSecrets } from './step-secrets.js';
 
 export interface JournalClientOptions {
   /** Opt-in total budget for read-only requests; interactive clients stay single-shot. */
@@ -78,6 +80,9 @@ export class JournalClient extends JournalConnection {
     });
   }
 
+  /** Additive daemon capability negotiated by this session's hello. */
+  supportsFeature(name: string): boolean { return this.features.has(name); }
+
   private request<V extends keyof VerbContract>(verb: V, params: VerbContract[V]['params'],
     timeoutMs: number | null = this.requestTimeoutMs, signal?: AbortSignal): Promise<VerbContract[V]['result']> {
     // Every allowlisted read takes the policy, even after the primary dropped: its
@@ -130,7 +135,22 @@ export class JournalClient extends JournalConnection {
     reuseFromRunId?: string,
     admissionKey?: string,
     watch = false,
+    isolated = false,
   ): Promise<VerbContract['run.start']['result']> {
+    if (isolated) {
+      if (watch) throw new Error('an isolated run.start cannot keep a watch on its temporary session');
+      return this.runStartIsolated(spec, reuseFromRunId, admissionKey);
+    }
+    for (const step of spec.steps) {
+      for (const name of validateStepSecrets(step.secrets, process.env)) {
+        if (this.withheld.has(name)) {
+          throw new Error(`step secret ${JSON.stringify(name)} is withheld by the daemon`);
+        }
+      }
+    }
+    if (!this.features.has('step_secret_scoping') && spec.steps.some(step => step.secrets?.length)) {
+      throw new Error('per-step secret grants require a daemon with step_secret_scoping support');
+    }
     return this.request('run.start', {
       spec,
       ...(reuseFromRunId === undefined ? {} : { reuse_from_run_id: reuseFromRunId }),
@@ -140,6 +160,20 @@ export class JournalClient extends JournalConnection {
     }, null);
   }
 
+  /** Drive a blocking deterministic child on its own socket, then close it. */
+  private async runStartIsolated(
+    spec: KernelRunSpec, reuseFromRunId?: string, admissionKey?: string,
+  ): Promise<VerbContract['run.start']['result']> {
+    const peer = this.createPeer();
+    try {
+      await peer.connect();
+      await peer.hello('flows-authored-deterministic');
+      return await peer.runStart(spec, reuseFromRunId, admissionKey);
+    } finally {
+      peer.close();
+    }
+  }
+
   /** §3 memoized resume. */
   runResume(runId: string, allowHumanInfluenced = false): Promise<VerbContract['run.resume']['result']> {
     return this.request('run.resume', {
@@ -158,10 +192,22 @@ export class JournalClient extends JournalConnection {
    * alike, so their values never cross the socket from this client.
    */
   private stepEnv(): { env?: Record<string, string> } {
-    if (!this.features.has('step_env')) return {};
+    if (!this.features.has('step_env')) {
+      // A client with no declared grants keeps compatibility with the
+      // currently pinned hosted runtime until Cloud upgrades the artifact.
+      return {};
+    }
     const env: Record<string, string> = {};
+    const delivered = deliveredNames(process.env);
+    if (delivered !== undefined && this.withheld.has(SECRET_ENV_NAMES)) {
+      throw new Error(`${SECRET_ENV_NAMES} is withheld by the daemon; delivered secrets cannot be scoped`);
+    }
     for (const [key, value] of Object.entries(process.env)) {
-      if (value !== undefined && !this.withheld.has(key)) env[key] = value;
+      if (value !== undefined && key !== SIGNAL_READ_TOKEN_ENV && key !== PLATFORM_AGENT_ENV_NAMES
+        && !this.withheld.has(key)) {
+        env[key] = key === SECRET_ENV_NAMES && delivered !== undefined
+          ? JSON.stringify([...delivered].filter(name => !this.withheld.has(name))) : value;
+      }
     }
     return { env };
   }

package/src/llm-worker.ts

@@ -64,7 +64,8 @@ export class LlmWorker extends EventEmitter {
     const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>
       typeof spec.cli === 'string' && typeof spec.prompt === 'string'
         ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'llm',
-          undefined, undefined, 'direct', undefined, this.environment, spec.cli_identity)
+          undefined, undefined, 'direct', undefined, this.environment, spec.cli_identity,
+          undefined, undefined, spec.secrets, this.client.supportsFeature?.('step_secret_scoping') ?? true)
         : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'llm step has no declared CLI' }));
     const { result, usage } = workerSpend(completed, effectiveModel);
     const cost = reportedCost(completed, effectiveModel);

package/src/preflight.ts

@@ -91,7 +91,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, execution?: 'managed'): CliProbeResult;
+  cli(cli: string, source: CliResolutionSource, model?: string, execution?: 'managed', secrets?: string[]): CliProbeResult;
   executor(trigger: TriggerSpec): boolean;
   command(binary: string): boolean;
 }
@@ -340,7 +340,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     }
     const resolution = resolutionByStep.get(step.id)!;
     probeResolvedCli(resolution, options.probes, cliProbeResults, diagnostics,
-      step.type === 'agent' && communicationInstruction(step.instruction) !== undefined);
+      step.type === 'agent' && communicationInstruction(step.instruction) !== undefined, step.secrets);
   }
 
   for (const trigger of compiled.triggers ?? []) {
@@ -529,8 +529,9 @@ function resolveCli(
   return undefined;
 }
 
-export function cliProbeKey(resolution: CliResolution, managed = false): string {
-  return JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
+export function cliProbeKey(resolution: CliResolution, managed = false, secrets?: readonly string[]): string {
+  return JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed,
+    ...(secrets?.length ? [[...secrets].sort()] : [])]);
 }
 
 function probeResolvedCli(
@@ -539,6 +540,7 @@ function probeResolvedCli(
   cache: Map<string, CliProbeOutcome>,
   diagnostics: PreflightDiagnostic[],
   managed = false,
+  secrets?: string[],
 ): 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
@@ -546,13 +548,17 @@ 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 = cliProbeKey(resolution, managed);
+  const cacheKey = cliProbeKey(resolution, managed, secrets);
   let outcome = cache.get(cacheKey);
   if (outcome === undefined) {
     try {
       outcome = { result: managed
-        ? probes.cli(resolution.cli, resolution.source, resolution.model, 'managed')
-        : probes.cli(resolution.cli, resolution.source, resolution.model) };
+        ? secrets?.length
+          ? probes.cli(resolution.cli, resolution.source, resolution.model, 'managed', secrets)
+          : probes.cli(resolution.cli, resolution.source, resolution.model, 'managed')
+        : secrets?.length
+          ? probes.cli(resolution.cli, resolution.source, resolution.model, undefined, secrets)
+          : probes.cli(resolution.cli, resolution.source, resolution.model) };
     } catch (error) {
       const detail = error instanceof CliProbeError ? error.detail : undefined;
       outcome = { failure: detail ?? null };

package/src/spec.ts

@@ -217,6 +217,8 @@ export interface KernelPlacementRequirements extends Omit<PlacementRequirements,
 
 /** Fields shared by every step on the ladder. */
 export interface BaseStepSpec {
+  /** Names of run secrets granted to this step; values never enter the spec. */
+  secrets?: string[];
   /** Named values selected from earlier steps' declared, verified outputs. */
   input?: Record<string, OutputBinding>;
   requirements?: PlacementRequirements;
@@ -478,6 +480,8 @@ export interface KernelVerificationSpec {
 }
 
 export interface KernelStepCommon {
+  /** Names only; the worker/kernel selects values from the run environment. */
+  secrets?: string[];
   input?: Record<string, OutputBinding>;
   requirements?: KernelPlacementRequirements;
   memory?: KernelMemorySpec;

package/src/step-fields.ts

@@ -21,6 +21,7 @@ export const AGENT_DECLARATION_FIELDS = ['cli', 'model'] as const;
 export const STEP_COMMON_FIELDS = [
   'id',
   'type',
+  'secrets',
   'dependsOn',
   'input',
   'verification',