@relayflows/sdk 2.0.50 → 2.0.51

package/src/authored-worker-step.ts

@@ -20,6 +20,7 @@ import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 import type { StepFailedDetails } from './failure-kinds.js';
 import { LOCAL_AGENT_WORKSPACE } from './local-agent-pins.js';
 import { authoredWorkerSlots, type AuthoredWorkerSlots } from './worker-slots.js';
+import { validateStepSecrets } from './step-secrets.js';
 
 const AGENT_TIMEOUT = Symbol('declared agent timeout');
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
@@ -177,6 +178,8 @@ export function authoredWorkerRunner(
       }
     },
     async agent(id: string, options: AgentOptions, verification?: NamedGate): Promise<AgentResult> {
+      const secrets = validateStepSecrets((options as AgentOptions & { secrets?: unknown }).secrets,
+        agentEnvironment ?? process.env);
       if (options.workspace !== undefined && localAgentStream !== undefined) {
         throw new AuthoredFlowExecutionError('unsupported_workspace_permission',
           'The local agent worker accepts stream-only steps. Remove workspace or attach a worker that holds its revision pins.');
@@ -277,6 +280,7 @@ export function authoredWorkerRunner(
         : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
       const output = await run({
         id, type: 'agent', instruction: options.task,
+        ...(secrets.length ? { secrets } : {}),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
         ...(permissionsSnapshot === undefined ? {} : { permissions: permissionsSnapshot }),
         ...(localAgentStream === undefined ? {} : { surfaces: {
@@ -323,11 +327,14 @@ export function authoredWorkerRunner(
       }
       const snapshot = options === undefined ? undefined : snapshotJsonValue(options, 'f.llm options');
       if (snapshot !== undefined && (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot)
-        || Object.keys(snapshot).some(key => !['output', 'cli', 'model'].includes(key)))) {
-        throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm options accepts only output, cli, and model.');
+        || Object.keys(snapshot).some(key => !['output', 'cli', 'model', 'secrets'].includes(key)))) {
+        throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm options accepts only output, cli, model, and secrets.');
       }
+      const secrets = validateStepSecrets((snapshot as { secrets?: unknown } | undefined)?.secrets,
+        agentEnvironment ?? process.env);
       const output = await run({
         id, type: 'llm', prompt, ...snapshot as unknown as LlmOptions,
+        ...(secrets.length ? { secrets } : {}),
         ...(verification === undefined ? {} : { verification }),
       });
       if (options === undefined && typeof output !== 'string') {
@@ -358,6 +365,7 @@ export function authoredDeterministicRunner(
   function lower<T>(
     id: string, command: string, terminal: boolean, leaseMs: number | undefined,
     verification: NamedGate | undefined, onNonZero: 'record' | undefined,
+    secrets: string[] | undefined,
     read: (outcome: import('./protocol.js').RunOutcome) => Promise<T>,
   ): Promise<T> {
     const spec = toKernelSpec(compileSpec({
@@ -365,6 +373,7 @@ export function authoredDeterministicRunner(
       name: `${name}/${id}`,
       steps: [{
         id, type: 'deterministic', command,
+        ...(secrets?.length ? { secrets } : {}),
         ...(leaseMs === undefined ? {} : { lease_ms: leaseMs }),
         ...(onNonZero === undefined ? {} : { onNonZero }),
         ...(verification === undefined ? {} : { verification }),
@@ -380,12 +389,14 @@ export function authoredDeterministicRunner(
     if (terminal) return journal.runStart(spec, undefined, admissionKey).then(consume);
     return budget.execute(journal, spec, consume, admissionKey);
   }
-  const lowerRun = (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> =>
-    lower(id, command, terminal, leaseMs, verification, undefined,
+  const lowerRun = (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate,
+    secrets?: string[]): Promise<string> =>
+    lower(id, command, terminal, leaseMs, verification, undefined, secrets,
       outcome => readSuccessfulOutput(journal, outcome, id, journalSteps, context));
   /** `f.run(..., { onNonZero: 'record' })`: the exit code is the result, not a throw. */
-  lowerRun.recording = (id: string, command: string, leaseMs?: number, verification?: NamedGate): Promise<RecordedRunOutcome> =>
-    lower(id, command, false, leaseMs, verification, 'record',
+  lowerRun.recording = (id: string, command: string, leaseMs?: number, verification?: NamedGate,
+    secrets?: string[]): Promise<RecordedRunOutcome> =>
+    lower(id, command, false, leaseMs, verification, 'record', secrets,
       outcome => readRecordedOutcome(journal, outcome, id, journalSteps, context));
   return lowerRun;
 }

package/src/cli/check.ts

@@ -492,8 +492,8 @@ function findConfig(start: string): string | undefined {
 function systemProbes(flowDirectory: string, config: ProjectConfig, environment?: NodeJS.ProcessEnv): PreflightProbes {
   return {
     helper: helperReady,
-    cli: (cli, source, model, execution) => probeCli(cli,
-      source === 'project' ? config.directory : flowDirectory, model, execution, environment),
+    cli: (cli, source, model, execution, secrets) => probeCli(cli,
+      source === 'project' ? config.directory : flowDirectory, model, execution, environment, secrets),
     executor: (trigger) => config.executors.includes(trigger.executor),
     // A deterministic step runs in the daemon's working directory — the
     // directory `flows run` was invoked from, or Cloud's code mount — not in
@@ -521,7 +521,7 @@ function bindResolvedCliPaths(
       if (resolution === undefined) return step;
       const directory = resolution.source === 'project' ? configDirectory : flowDirectory;
       const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
-      const outcome = probeCache.get(cliProbeKey(resolution, managed));
+      const outcome = probeCache.get(cliProbeKey(resolution, managed, step.secrets));
       const executable = outcome !== undefined && 'result' in outcome
         ? outcome.result.executable
         : undefined;

package/src/cli/cli-probe.ts

@@ -7,6 +7,7 @@ import { adapterIdentification, authenticationProbe, classifyModelProbeFailure,
 import { MODEL_ENV } from '../worker-cli.js';
 import { CliProbeError, type CliProbeResult } from '../preflight.js';
 import { pinCliAlias, pinCliAliasSync } from './pinned-cli-alias.js';
+import { agentProbeEnvironment } from '../step-secrets.js';
 
 interface ProbeRequest {
   argv0?: string;
@@ -30,7 +31,8 @@ export async function probeCliAsync(...args: Parameters<typeof probeSequence>):
 }
 
 export function resolveExecutable(command: string, directory: string, environment: NodeJS.ProcessEnv = process.env): string | undefined {
-  return driveSync(executableSequence(command, directory, environment));
+  return driveSync(executableSequence(command, directory,
+    agentProbeEnvironment(environment, 'relayflows-wrapper-v1')));
 }
 
 function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
@@ -94,23 +96,24 @@ function* probeSequence(
   model?: string,
   execution?: 'managed',
   sourceEnvironment: NodeJS.ProcessEnv = process.env,
+  grants?: string[],
 ): Generator<ProbeRequest, CliProbeResult, ProbeOutput> {
-  const executable = yield* executableSequence(cli, directory, sourceEnvironment);
+  const kind = cliAdapterKind(cli);
+  const environment = execution === 'managed'
+    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(cli, sourceEnvironment, grants) }
+    : agentProbeEnvironment(sourceEnvironment, kind, grants);
+  const executable = yield* executableSequence(cli, directory, environment);
   if (executable === undefined) return { exists: false, authenticated: false };
   // The declaration selects the adapter; the canonical executable selects
   // the bytes. Package-manager links commonly name `claude` or `codex` while
   // targeting a generic `cli.js`, whose basename must not rewrite the adapter
   // contract after resolution.
-  const kind = cliAdapterKind(cli);
   // Relay owns interactive CLI launch/injection. Its generic PTY path is not
   // the headless wrapper protocol; do not demand that protocol from Gemini,
   // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
   if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
     return { exists: true, supported: true, authenticated: 'unverified', executable };
   }
-  const environment = execution === 'managed'
-    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(cli, sourceEnvironment) }
-    : sourceEnvironment;
   const probe = (invocation: CliInvocation): ProbeRequest => ({
     executable,
     argv0: basename(cli),

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/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
@@ -131,6 +136,16 @@ export class JournalClient extends JournalConnection {
     admissionKey?: string,
     watch = false,
   ): Promise<VerbContract['run.start']['result']> {
+    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 }),
@@ -158,10 +173,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 };
   }