@relayflows/sdk 2.0.49 → 2.0.51

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 };
   }

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/observer-link.ts

@@ -11,10 +11,10 @@
  * scoped, short-lived observer token on their behalf and hand *that* to the
  * URL. The workspace admin key never leaves the operator's machine.
  *
- * Everything here is best-effort. A missing workspace key means "no observer
- * link, silently" — this is a parity feature relaying v1's convenience, not a
- * requirement of a local run. A mint failure emits a labeled diagnostic to
- * stderr and continues; a run must never fail because the observer link failed.
+ * Everything here is best-effort. A missing workspace key means no observer
+ * link; the human-facing CLI explains the alternatives for a plain local run.
+ * A mint failure emits a labeled diagnostic to stderr and continues; a run
+ * must never fail because the observer link failed.
  */
 
 import { readFileSync } from 'node:fs';
@@ -165,7 +165,7 @@ export interface ResolveObserverLinkEnvOptions {
  * 2. Active workspace key from `~/.agentworkforce/relay/workspaces.json`
  *    (populated by `agent-relay cloud login` + `agent-relay workspace
  *    set_key`), when readable.
- * 3. Nothing -- silent skip, same as an unset primary env var.
+ * 3. Nothing -- the caller decides whether its output mode warrants a hint.
  *
  * `FLOWS_NO_OBSERVER=1` still suppresses regardless of source.
  */
@@ -189,7 +189,7 @@ export function resolveObserverLinkEnv(
 /**
  * Read the observer-link config from the environment. Both trims and
  * emptiness-checks the workspace key so a `RELAYCAST_WORKSPACE_KEY=` with no
- * value reads the same as unset (no observer link, silently).
+ * value reads the same as unset (no observer link).
  */
 export function readObserverLinkEnv(
   env: NodeJS.ProcessEnv = process.env,
@@ -258,7 +258,7 @@ export interface MintObserverOutcome {
   /**
    * A short diagnostic to log when mint failed. `undefined` on success or on
    * "no observer link is possible" (missing key/suppressed) so the caller can
-   * distinguish silent-skip from "warn about the miss".
+   * distinguish an unavailable link from "warn about a mint failure".
    */
   warning?: string;
 }

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',

package/src/step-secrets.ts

@@ -0,0 +1,145 @@
+import type { CliAdapterKind } from './cli-adapter.js';
+
+/** Cloud supplies this name-only manifest alongside delivered envSecrets. */
+export const SECRET_ENV_NAMES = 'RELAY_SECRET_ENV_NAMES';
+/** Cloud's name-only exception for model login it selected from delivered values. */
+export const PLATFORM_AGENT_ENV_NAMES = 'RELAY_PLATFORM_AGENT_ENV_NAMES';
+/** CLI-only hosted signal read capability. Never a run or step secret. */
+export const SIGNAL_READ_TOKEN_ENV = 'RELAYFLOW_V2_SIGNAL_READ_TOKEN';
+const VALID_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const BEDROCK_LOGIN = new Set([
+  'CLAUDE_CODE_USE_BEDROCK', 'AWS_BEARER_TOKEN_BEDROCK',
+  'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN',
+  'AWS_REGION', 'AWS_DEFAULT_REGION',
+]);
+
+const REPOSITORY_ENV = new Set([
+  'GH_TOKEN', 'GH_CONFIG_DIR', 'GH_PROMPT_DISABLED', 'GITLAB_TOKEN',
+  'RELAYFLOW_V2_GITLAB_API_URL',
+]);
+export function repositoryEnvironmentNames(source: NodeJS.ProcessEnv): string[] {
+  return Object.keys(source).filter(name => REPOSITORY_ENV.has(name) || name.startsWith('GIT_')
+    || name.startsWith('RELAYFLOW_V2_REPOSITORY_'));
+}
+
+const BASE_ENV = [
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'LANG', 'LANGUAGE',
+  'LC_ALL', 'LC_CTYPE', 'TZ', 'TMPDIR', 'TMP', 'TEMP', 'XDG_RUNTIME_DIR',
+  'XDG_CACHE_HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'HOSTNAME',
+  'NODE_PATH', 'NODE_ENV', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE',
+  'SSL_CERT_DIR', 'NVM_DIR', 'NVM_BIN', 'NVM_INC',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+  'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy',
+  'NVM_SYMLINK_CURRENT', 'PIPX_HOME', 'PIPX_BIN_DIR', 'PYTHON_PATH',
+  'PYTHON_VERSION', 'PYTHON_SHA256', 'RELAYFILE_MOUNT_PATH',
+  'RELAYFILE_MOUNT_PATHS', 'RELAYFILE_MOUNT_ROOT', 'WORKSPACE_ROOT',
+  'RELAY_BASE_URL',
+  'SystemRoot', 'ComSpec', 'PATHEXT', 'WINDIR',
+] as const;
+
+// Model login is an intrinsic capability of the selected CLI. It is not a
+// run's delivered envSecret; only that CLI gets its own login variables.
+const CLI_LOGIN: Record<CliAdapterKind, readonly string[]> = {
+  claude: [
+    'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CONFIG_DIR', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN',
+    'ANTHROPIC_BASE_URL', '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: ['CODEX_HOME', 'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_API_BASE', 'OPENROUTER_API_KEY'],
+  'relayflows-wrapper-v1': [],
+};
+
+/** A selected CLI can use its own delivered login; generic cloud credentials need a grant. */
+export function isCliLoginName(kind: string, name: string, providerNames?: readonly string[]): boolean {
+  if (BEDROCK_LOGIN.has(name) || name.startsWith('AWS_')
+    || name === 'GOOGLE_APPLICATION_CREDENTIALS' || name === 'GOOGLE_API_KEY') return false;
+  const names = providerNames ?? (Object.hasOwn(CLI_LOGIN, kind) ? CLI_LOGIN[kind as CliAdapterKind] : []);
+  return names.includes(name);
+}
+
+export function deliveredNames(source: NodeJS.ProcessEnv): ReadonlySet<string> | undefined {
+  const raw = source[SECRET_ENV_NAMES];
+  if (raw === undefined) return undefined; // self-hosted runs may grant present env names
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { throw new Error(`${SECRET_ENV_NAMES} must be a JSON array of names`); }
+  if (!Array.isArray(parsed) || !parsed.every(name => typeof name === 'string' && VALID_NAME.test(name))) {
+    throw new Error(`${SECRET_ENV_NAMES} must be a JSON array of valid names`);
+  }
+  if (new Set(parsed).size !== parsed.length || parsed.includes(SECRET_ENV_NAMES)
+    || parsed.includes(PLATFORM_AGENT_ENV_NAMES)
+    || parsed.includes(SIGNAL_READ_TOKEN_ENV)) {
+    throw new Error(`${SECRET_ENV_NAMES} contains a duplicate or reserved name`);
+  }
+  return new Set(parsed);
+}
+
+/** Only Cloud-selected Claude Bedrock login may override the delivered filter. */
+export function platformAgentNames(source: NodeJS.ProcessEnv, kind: string): ReadonlySet<string> {
+  const raw = source[PLATFORM_AGENT_ENV_NAMES];
+  if (raw === undefined) return new Set();
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { throw new Error(`${PLATFORM_AGENT_ENV_NAMES} must be a JSON array of names`); }
+  if (!Array.isArray(parsed) || !parsed.every(name => typeof name === 'string' && BEDROCK_LOGIN.has(name)
+    && typeof source[name] === 'string') || new Set(parsed).size !== parsed.length) {
+    throw new Error(`${PLATFORM_AGENT_ENV_NAMES} contains an invalid or unavailable model login name`);
+  }
+  return kind === 'claude' ? new Set(parsed) : new Set();
+}
+
+/** Refuse a misspelled, unavailable or platform-owned name before a child runs. */
+export function validateStepSecrets(declaration: unknown, source: NodeJS.ProcessEnv): string[] {
+  const known = deliveredNames(source);
+  if (declaration === undefined) return [];
+  if (!Array.isArray(declaration) || !declaration.every(name => typeof name === 'string' && VALID_NAME.test(name))) {
+    throw new Error('step secrets must be an array of environment variable names');
+  }
+  const names = declaration as string[];
+  if (new Set(names).size !== names.length) throw new Error('step secrets contain duplicate names');
+  for (const name of names) {
+    if (name === SECRET_ENV_NAMES || name === PLATFORM_AGENT_ENV_NAMES || name === SIGNAL_READ_TOKEN_ENV
+      || !Object.hasOwn(source, name) || typeof source[name] !== 'string'
+      || (known !== undefined && !known.has(name))) {
+      throw new Error(`step secret ${JSON.stringify(name)} is not available to this run`);
+    }
+  }
+  return [...names];
+}
+
+/** One provider CLI starts from an allowlist, then receives only its grants. */
+export function agentStepEnvironment(
+  source: NodeJS.ProcessEnv,
+  kind: CliAdapterKind,
+  declaration?: unknown,
+): NodeJS.ProcessEnv {
+  const known = deliveredNames(source);
+  const platform = platformAgentNames(source, kind);
+  const grants = validateStepSecrets(declaration, source);
+  const env: NodeJS.ProcessEnv = {};
+  for (const name of [...BASE_ENV, ...CLI_LOGIN[kind], ...repositoryEnvironmentNames(source)]) {
+    if (known?.has(name) && !grants.includes(name) && !platform.has(name)
+      && !isCliLoginName(kind, name)) continue;
+    if (source[name] !== undefined) env[name] = source[name];
+  }
+  for (const name of grants) env[name] = source[name];
+  return env;
+}
+
+/** Provider readiness probes run before worker attach, but obey the step's grants. */
+export function agentProbeEnvironment(
+  source: NodeJS.ProcessEnv,
+  kind: CliAdapterKind,
+  declaration?: unknown,
+): NodeJS.ProcessEnv {
+  const env = { ...source };
+  const allowed = new Set(validateStepSecrets(declaration, source));
+  const platform = platformAgentNames(source, kind);
+  for (const name of deliveredNames(source) ?? []) {
+    if (!allowed.has(name) && !platform.has(name) && !isCliLoginName(kind, name)) delete env[name];
+  }
+  delete env[SECRET_ENV_NAMES];
+  delete env[PLATFORM_AGENT_ENV_NAMES];
+  delete env[SIGNAL_READ_TOKEN_ENV];
+  delete env.RELAY_AGENT_TOKEN;
+  return env;
+}

package/src/validate.ts

@@ -388,6 +388,14 @@ class Validator {
     const type = st['type'] as StepType;
     this.checkKeys(st, [...STEP_COMMON_FIELDS, ...STEP_FIELDS_BY_TYPE[type]], at);
 
+    if (st['secrets'] !== undefined) {
+      const names = st['secrets'];
+      if (!Array.isArray(names) || !names.every(name => typeof name === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        || new Set(names).size !== names.length || names.includes('RELAY_SECRET_ENV_NAMES')) {
+        this.fail(`${at}.secrets: expected distinct environment variable names`);
+      }
+    }
+
     if (st['requirements'] !== undefined) this.validateRequirements(st['requirements'], `${at}.requirements`);
     if (st['memory'] !== undefined) this.validateMemory(st['memory'], `${at}.memory`);
 
@@ -491,6 +499,9 @@ class Validator {
   }
 
   private validateAgent(st: AgentStepSpec, at: string): void {
+    if (st.transport === 'relay' && st.secrets?.length) {
+      this.fail(`${at}.secrets: relay transport cannot deliver per-step secrets`);
+    }
     if (st.timeoutMs !== undefined) {
       if (!isPosInt(st.timeoutMs) || st.timeoutMs > 60 * 60_000) {
         this.fail(`${at}.timeoutMs: expected a positive integer at most 3600000 (60 minutes)`);

package/src/worker-cli.ts

@@ -31,6 +31,7 @@ import {
 } from './wrapper-session.js';
 import { wrapperEnvironment } from './wrapper-runtime.js';
 import { applyStepEnvironment } from './step-env.js';
+import { PLATFORM_AGENT_ENV_NAMES, SIGNAL_READ_TOKEN_ENV, agentStepEnvironment } from './step-secrets.js';
 import { TAIL_CLOSE_TIMEOUT_MS, openTranscriptTail, type TranscriptTailWriter } from './transcript-tail.js';
 import {
   isRetryableSpawnError,
@@ -139,12 +140,33 @@ export async function runAgentCli(
   stepTimeoutMs?: number,
   /** A recorded CLI session to continue (`f.agent` `resume`); agent mode only. */
   resume?: string,
+  /** Names of run secrets this step was granted by its journaled spec. */
+  secrets?: string[],
+  /** A featureless daemon retains its legacy child environment for plain runs. */
+  scopeSecrets = true,
 ): Promise<WorkerCliResult> {
   signal?.throwIfAborted();
   if (signal !== undefined && process.platform === 'win32') {
     throw new Error('Lease-bound agent execution requires macOS or Linux process-group cancellation; Windows is unsupported.');
   }
   const kind = cliAdapterKind(cliIdentity ?? cli);
+  if (!scopeSecrets && secrets?.length) {
+    return { exit_code: null, stdout_tail: '',
+      stderr_tail: 'per-step secret grants require a daemon with step_secret_scoping support' };
+  }
+  let childEnvironment: NodeJS.ProcessEnv;
+  try {
+    childEnvironment = scopeSecrets
+      ? agentStepEnvironment(processEnvironment, kind, secrets)
+      : { ...processEnvironment };
+    // The old-daemon compatibility path retains other legacy variables, but
+    // this CLI-only signal capability must never enter an agent subprocess.
+    delete childEnvironment[SIGNAL_READ_TOKEN_ENV];
+    delete childEnvironment[PLATFORM_AGENT_ENV_NAMES];
+  } catch (error) {
+    return { exit_code: null, stdout_tail: '',
+      stderr_tail: error instanceof Error ? error.message : 'step secret grant is invalid' };
+  }
   const effectiveModel = resolveCliModel(cliIdentity ?? cli, model);
   const argv0 = cliInvocationArgv0(cli, cliIdentity);
 
@@ -206,7 +228,8 @@ export async function runAgentCli(
   if (kind === 'relayflows-wrapper-v1') {
     // The closed allowlist admits no ambient RELAYFLOW_* value; the four
     // discovery names are set from this dispatch, exactly as for a direct spawn.
-    const wrapperEnv = wrapperEnvironment(processEnvironment);
+    const wrapperEnv = wrapperEnvironment(childEnvironment);
+    for (const name of secrets ?? []) wrapperEnv[name] = childEnvironment[name];
     applyStepEnvironment(wrapperEnv, sidechannel);
     const session = await runWrapperSession(
       cli,
@@ -225,7 +248,7 @@ export async function runAgentCli(
     return requirePricedUsage(session.transport?.cause === 'timeout' ? { ...decoded, stdout_tail: '' } : decoded, effectiveModel);
   }
 
-  const env: NodeJS.ProcessEnv = { ...processEnvironment };
+  const env: NodeJS.ProcessEnv = { ...childEnvironment };
   delete env[WAKE_CONTEXT_ENV];
   delete env[MODEL_ENV];
   // Where this attempt's journal is, so the agent can run `flows status` on
@@ -256,9 +279,13 @@ export async function runAgentCli(
   const args = [...invocation.args];
   args.splice(args.length - promptOperand('').length, 0, ...(kind === 'claude' ? ['--output-format', 'stream-json', '--verbose'] : ['--json']));
   const completion = kind === 'claude' ? claudeResultOutcome : undefined;
+  // Retain the source values for output redaction even though the child
+  // receives only its filtered environment. A provider can echo a value from
+  // its prompt or fixture that was not granted as an environment variable.
+  const redactionEnvironment = { ...processEnvironment, ...env };
   return requirePricedUsage(decodeProviderResult(await spawnInvocation(
-    cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion, argv0, kind,
-  ), kind, env), effectiveModel);
+    cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion, argv0, kind, redactionEnvironment,
+  ), kind, redactionEnvironment), effectiveModel);
   }
 }
 
@@ -399,6 +426,7 @@ async function spawnInvocation(
   completion?: (line: string) => { failed: boolean } | undefined,
   argv0?: string,
   kind?: CliAdapterKind,
+  redactionEnvironment: NodeJS.ProcessEnv = env,
 ): Promise<WorkerCliResult> {
   const pendingInput: Buffer[] = [];
   let acceptingDrive = true;
@@ -436,7 +464,7 @@ async function spawnInvocation(
   };
   try {
     writer = sidechannel?.attempt === undefined ? undefined
-      : await openTranscriptWriter(transcriptPath(sidechannel, sidechannel.attempt), env);
+      : await openTranscriptWriter(transcriptPath(sidechannel, sidechannel.attempt), redactionEnvironment);
     channel = sidechannel === undefined ? undefined : await openSidechannel({
       ...sidechannel,
       onDrive() { driven = true; sidechannel.onDrive(); },
@@ -597,7 +625,7 @@ async function spawnInvocation(
       const transport = transportEvidence({
         phase: 'abort', cause: 'lease_lost', exitCode: null, signal: null,
         stderr: 'Agent execution aborted: lease ownership lost.', retryable: false,
-      }, env);
+      }, redactionEnvironment);
       finishAfterStop(
         { exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.', transport },
         'kill',
@@ -635,11 +663,11 @@ async function spawnInvocation(
           phase: 'result_exit_grace', cause: 'result_exit_timeout', exitCode, signal: null,
           stderr: stderrText,
           retryable: false,
-        }, env);
+        }, redactionEnvironment);
         finishAfterStop({
           exit_code: exitCode,
           stdout_tail: Buffer.concat(stdout).toString('utf8'),
-          stderr_tail: redactText(stderrText, env),
+          stderr_tail: redactText(stderrText, redactionEnvironment),
           transport,
         }, 'terminate');
       }, RESULT_EXIT_GRACE_MS);
@@ -671,11 +699,11 @@ async function spawnInvocation(
       const transport = transportEvidence({
         phase: 'spawn', cause: child.pid === undefined ? 'spawn_error' : 'process_error',
         exitCode: null, signal: null, stderr: error.message, errorCode: code, retryable,
-      }, env);
+      }, redactionEnvironment);
       finishOnChildExit({
         exit_code: null,
         stdout_tail: Buffer.concat(stdout).toString('utf8'),
-        stderr_tail: redactText(error.message, env),
+        stderr_tail: redactText(error.message, redactionEnvironment),
         transport,
       });
     });
@@ -692,11 +720,11 @@ async function spawnInvocation(
       const retryable = codexStdinLifecycle || signalName !== null || code === null;
       const transport = transportEvidence({
         phase: 'close', cause, exitCode: code, signal: signalName, stderr: stderrText, retryable,
-      }, env);
+      }, redactionEnvironment);
       finishOnChildExit({
         exit_code: code,
         stdout_tail: Buffer.concat(stdout).toString('utf8'),
-        stderr_tail: redactText(stderrText, env),
+        stderr_tail: redactText(stderrText, redactionEnvironment),
         transport,
       });
     });
@@ -710,7 +738,7 @@ async function spawnInvocation(
           phase: 'timeout', cause: 'timeout', exitCode: null, signal: null,
           stderr: `${Buffer.concat(stderr).toString('utf8')}\n${timeoutMessage}`,
           retryable: false,
-        }, env);
+        }, redactionEnvironment);
         finishAfterStop({
           exit_code: null,
           stdout_tail: Buffer.concat(stdout).toString('utf8'),