@relayflows/sdk 2.0.38 → 2.0.40

package/src/cli.ts

@@ -44,6 +44,7 @@ import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
 import { runCloudSyncCli } from './cli/cloud-sync.js';
 import { parseCloudDeployArgs, runCloudDeployCli, runCloudDeploymentsCli, runCloudUndeployCli, type CloudDeployArgs } from './cli/cloud-deploy.js';
+import { runCloudRollbackCli, runCloudVersionsCli } from './cli/cloud-versions.js';
 import { parseCloudScheduleArgs, runCloudScheduleCli, runCloudSchedulesCli, runCloudUnscheduleCli, type CloudScheduleArgs } from './cli/cloud-schedule.js';
 import { isAuthoredFlowPath } from './direct-input.js';
 import { parseDeployArgs, runDeploy, type DeployArgs } from './cli/deploy.js';
@@ -97,6 +98,8 @@ export type ParsedArgs =
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
   | { command: 'undeploy'; agentId: string; json: boolean }
+  | { command: 'versions'; flow: string; json: boolean }
+  | { command: 'rollback'; flow: string; version: string; json: boolean }
   | CloudScheduleArgs
   | { command: 'schedules'; json: boolean }
   | { command: 'unschedule'; scheduleId: string; json: boolean }
@@ -123,7 +126,10 @@ const USAGE = [
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
   'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--plugin <ref>] [--no-connect] [--json]',
+  'flows deploy <flow.ts> --flow <name|listener-id> [--plugin <ref>] [--no-connect] [--json]',
   'flows deployments [--json]',
+  'flows versions [--json] <name|listener-id>',
+  'flows rollback [--json] <name|listener-id> <version>',
   'flows undeploy [--json] <deployment-id>',
   'flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>] [--tz <IANA>] [--input <inline-json-or-file>] [--name <name>] [--no-connect] [--json]',
   'flows schedules [--json]',
@@ -244,6 +250,8 @@ export async function runCli(
   if (parsed.command === 'cloud-deploy') return runCloudDeployCli(parsed, io);
   if (parsed.command === 'deployments') return runCloudDeploymentsCli(parsed, io);
   if (parsed.command === 'undeploy') return runCloudUndeployCli(parsed, io);
+  if (parsed.command === 'versions') return runCloudVersionsCli(parsed, io);
+  if (parsed.command === 'rollback') return runCloudRollbackCli(parsed, io);
   if (parsed.command === 'schedule') return runCloudScheduleCli(parsed, io);
   if (parsed.command === 'schedules') return runCloudSchedulesCli(parsed, io);
   if (parsed.command === 'unschedule') return runCloudUnscheduleCli(parsed, io);
@@ -631,6 +639,13 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     if (json > 1 || rest.length !== 1 || rest[0]!.startsWith('-')) return undefined;
     return { command: 'undeploy', agentId: rest[0]!, json: json === 1 };
   }
+  if (command === 'versions' || command === 'rollback') {
+    const rest = args.slice(1).filter(a => a !== '--json');
+    const json = args.length - 1 - rest.length;
+    if (json > 1 || rest.some(a => a.startsWith('-'))) return undefined;
+    if (command === 'versions') return rest.length === 1 ? { command, flow: rest[0]!, json: json === 1 } : undefined;
+    return rest.length === 2 ? { command, flow: rest[0]!, version: rest[1]!, json: json === 1 } : undefined;
+  }
   if (command === 'deployments') {
     const rest = args.slice(1);
     if (rest.length > 1 || (rest.length === 1 && rest[0] !== '--json')) return undefined;

package/src/cloud-deploy.ts

@@ -11,6 +11,7 @@ import {
 } from './flow-requirements.js';
 import { readProjectConfig } from './cli/check.js';
 import { assertNoUseDependencies, collectExtensionSubmissions } from './flow-extension-submit.js';
+import { parseVersionChange, type CloudFlowVersionChange } from './cloud-versions-wire.js';
 
 /**
  * Hosted listener deployment: the CLI form of the agentrelay.com onboarding's
@@ -104,6 +105,8 @@ export interface CloudDeployment {
   requirements: FlowRequirements;
   /** Integrations connected through the prompt during this deploy. */
   connected: string[];
+  /** The listener's active version after this deploy; absent from a Cloud without versions. */
+  version?: CloudFlowVersionChange;
 }
 
 export function parseRepository(value: string): { owner: string; name: string } {
@@ -165,9 +168,18 @@ export function parseTriggerSource(value: string): FlowTriggerSource {
   return { provider: provider as FlowTriggerProvider, settings };
 }
 
-export async function deployToCloud(
-  input: DeployToCloudInput, options: CloudConnectionOptions = {},
-): Promise<CloudDeployment> {
+/** One authored source, read and loaded the way every hosted deploy sends it. */
+export interface DeploySource {
+  bytes: Buffer;
+  source: string;
+  definition: ReturnType<Awaited<ReturnType<typeof loadAuthoredFlow>>['getDefinition']>;
+  extensions: Awaited<ReturnType<typeof collectExtensionSubmissions>>;
+  projectCli: string | undefined;
+}
+
+export async function loadDeploySource(
+  input: { path: string; plugins?: readonly string[] },
+): Promise<DeploySource> {
   if (!/\.flow\.ts$/iu.test(input.path)) {
     throw new CloudFlowError('unsupported_source', 'flows deploy takes one authored .flow.ts source.');
   }
@@ -204,6 +216,13 @@ export async function deployToCloud(
   } catch {
     projectCli = undefined;
   }
+  return { bytes, source, definition, extensions, projectCli };
+}
+
+export async function deployToCloud(
+  input: DeployToCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudDeployment> {
+  const { bytes, source, definition, extensions, projectCli } = await loadDeploySource(input);
   if (input.sources.length === 0 || input.sources.length > 10) {
     throw new CloudFlowError('invalid_input', 'Give between one and ten --on trigger sources.');
   }
@@ -274,11 +293,13 @@ export async function deployToCloud(
   if (!isCloudRecord(result) || typeof result.agentId !== 'string' || typeof result.status !== 'string') {
     throw new CloudFlowError('invalid_response', 'Cloud did not return a deployment.');
   }
+  const version = parseVersionChange(result.version);
   return {
     agentId: result.agentId, name, status: result.status,
     repository: input.repository, sources,
     sourceSha256: createHash('sha256').update(bytes).digest('hex'),
     requirements, connected,
+    ...(version === undefined ? {} : { version }),
   };
 }
 

package/src/cloud-versions-wire.ts

@@ -0,0 +1,58 @@
+import { isCloudRecord } from './cloud-http.js';
+
+/**
+ * What a Cloud write did to a listener's active version (cloud#4115).
+ * `reactivated`: the bytes match an earlier version, so the pointer moved to
+ * it without a new row, and `version` can be LOWER than `previousVersion`.
+ */
+export interface CloudFlowVersionChange {
+  version: number;
+  previousVersion: number | null;
+  change: 'created' | 'reactivated' | 'unchanged';
+}
+
+export interface CloudFlowVersion {
+  version: number;
+  sourceSha256: string;
+  origin: string;
+  createdAt: string;
+}
+
+const CHANGES = ['created', 'reactivated', 'unchanged'] as const;
+
+function isVersionNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1;
+}
+
+/** Undefined for a Cloud that predates versions or a malformed field. */
+export function parseVersionChange(value: unknown): CloudFlowVersionChange | undefined {
+  if (!isCloudRecord(value) || !isVersionNumber(value.version)
+    || !(value.previousVersion === null || isVersionNumber(value.previousVersion))
+    || !(CHANGES as readonly unknown[]).includes(value.change)) return undefined;
+  return {
+    version: value.version,
+    previousVersion: value.previousVersion as number | null,
+    change: value.change as CloudFlowVersionChange['change'],
+  };
+}
+
+export function parseVersion(value: unknown): CloudFlowVersion | undefined {
+  if (!isCloudRecord(value) || !isVersionNumber(value.version) || typeof value.sourceSha256 !== 'string'
+    || typeof value.origin !== 'string' || typeof value.createdAt !== 'string') return undefined;
+  return { version: value.version, sourceSha256: value.sourceSha256, origin: value.origin, createdAt: value.createdAt };
+}
+
+/**
+ * `version 4 (was 3)`; a rollback by content says the number went down, so
+ * nobody reads v2-after-v3 as a failed deploy.
+ */
+export function describeVersionChange(change: CloudFlowVersionChange): string {
+  if (change.change === 'unchanged') return `version ${change.version} (unchanged)`;
+  const was = change.previousVersion === null ? '' : ` (was ${change.previousVersion}`;
+  if (change.change === 'reactivated') {
+    const down = change.previousVersion !== null && change.version < change.previousVersion
+      ? '; active version went down' : '';
+    return `re-activated version ${change.version}${was}${down}${was ? ')' : ''}`;
+  }
+  return `version ${change.version}${was}${was ? ')' : ''}`;
+}

package/src/cloud-versions.ts

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { ensureIntegrationsConnected, type ConnectPrompt } from './cloud-connect.js';
+import {
+  CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions,
+} from './cloud-http.js';
+import {
+  FLOW_AGENT_HARNESSES, listCloudDeployments, loadDeploySource, type FlowTriggerSource,
+} from './cloud-deploy.js';
+import {
+  parseVersion, parseVersionChange, type CloudFlowVersion, type CloudFlowVersionChange,
+} from './cloud-versions-wire.js';
+import { flowRequirements, mergeFlowExtensionRequirements, type FlowRequirements } from './flow-requirements.js';
+
+/**
+ * Versions of a hosted listener (AgentWorkforce/cloud#4115). A deployed
+ * flow's source is immutable: `flows deploy <file> --flow <name-or-id>` makes
+ * the next version and moves the listener's pointer to it, leaving the
+ * listener's repository, triggers, approver, agents and run budget untouched;
+ * `flows rollback` moves the pointer to any recorded version.
+ */
+
+const LISTENER_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+export interface CloudListener {
+  agentId: string;
+  name: string;
+  status: string;
+  repository: { owner: string; name: string; host?: 'gitlab' };
+  sources: FlowTriggerSource[];
+  activeVersion: CloudFlowVersion | null;
+  versions: CloudFlowVersion[];
+}
+
+/** A listener id as given, else the one deployment in the workspace with that name. */
+export async function resolveCloudFlow(flow: string, options: CloudConnectionOptions = {}): Promise<string> {
+  const wanted = flow.trim();
+  if (!wanted) throw new CloudFlowError('invalid_input', '--flow needs a flow name or listener id.');
+  if (LISTENER_UUID.test(wanted)) return wanted.toLowerCase();
+  const deployments = await listCloudDeployments(options);
+  // Any listener id the workspace lists, before names: ids are not all uuids.
+  const byId = deployments.find(deployment => deployment.agentId === wanted);
+  if (byId) return byId.agentId;
+  const matches = deployments.filter(deployment => deployment.name.toLowerCase() === wanted.toLowerCase());
+  if (matches.length === 1) return matches[0]!.agentId;
+  if (matches.length === 0) {
+    throw new CloudFlowError('invalid_input', `No flow named "${wanted}" in this workspace; list them with: flows deployments`);
+  }
+  throw new CloudFlowError('invalid_input',
+    `More than one flow is named "${wanted}" (${matches.map(match => match.agentId).join(', ')}); pass the listener id.`);
+}
+
+export async function getCloudListener(agentId: string, options: CloudConnectionOptions = {}): Promise<CloudListener> {
+  const payload = await cloudRequest(`/api/v1/flows/listeners/${encodeURIComponent(agentId)}`, options);
+  const listener = isCloudRecord(payload) && isCloudRecord(payload.listener) ? payload.listener : undefined;
+  if (!listener || typeof listener.name !== 'string' || typeof listener.status !== 'string'
+    || !isCloudRecord(listener.repository) || typeof listener.repository.owner !== 'string'
+    || typeof listener.repository.name !== 'string' || !Array.isArray(listener.sources)) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return the flow listener.');
+  }
+  const versions = isCloudRecord(payload) && Array.isArray(payload.versions)
+    ? payload.versions.flatMap(entry => parseVersion(entry) ?? []) : [];
+  return {
+    agentId,
+    name: listener.name,
+    status: listener.status,
+    repository: {
+      owner: listener.repository.owner, name: listener.repository.name,
+      ...(listener.repository.host === 'gitlab' ? { host: 'gitlab' as const } : {}),
+    },
+    sources: listener.sources.flatMap((entry): FlowTriggerSource[] => isCloudRecord(entry) && typeof entry.provider === 'string'
+      ? [{ provider: entry.provider as FlowTriggerSource['provider'],
+          settings: Object.fromEntries(Object.entries(isCloudRecord(entry.settings) ? entry.settings : {})
+            .flatMap(([key, value]) => typeof value === 'string' ? [[key, value]] : typeof value === 'boolean' ? [[key, String(value)]] : [])) }]
+      : []),
+    activeVersion: isCloudRecord(payload) ? parseVersion(payload.activeVersion) ?? null : null,
+    versions,
+  };
+}
+
+export interface DeployVersionInput {
+  path: string;
+  /** The flow's deployed name or its listener id. */
+  flow: string;
+  plugins?: readonly string[];
+  connect?: ConnectPrompt;
+  checkConnections?: boolean;
+}
+
+export interface CloudVersionDeployment {
+  agentId: string;
+  name: string;
+  status: string;
+  sourceSha256: string;
+  requirements: FlowRequirements;
+  connected: string[];
+  version: CloudFlowVersionChange;
+}
+
+/** `POST /api/v1/flows/listeners/<id>/versions`: the source alone becomes the next version. */
+export async function deployVersionToCloud(
+  input: DeployVersionInput, options: CloudConnectionOptions = {},
+): Promise<CloudVersionDeployment> {
+  const { bytes, source, definition, extensions, projectCli } = await loadDeploySource(input);
+  const agentId = await resolveCloudFlow(input.flow, options);
+  const listener = await getCloudListener(agentId, options);
+  options.signal?.throwIfAborted();
+  // Requirements derive from the source, read against the listener's own
+  // repository and triggers, exactly as the create form reads its flags.
+  const requirements = mergeFlowExtensionRequirements(
+    flowRequirements(definition, {
+      sources: listener.sources,
+      // A GitHub repository means every run needs GitHub; a GitLab project does not.
+      ...(listener.repository.host === 'gitlab' ? {} : { repository: listener.repository }),
+      ...(projectCli === undefined ? {} : { projectCli }),
+    }),
+    extensions.map(extension => ({ name: extension.name, permissions: extension.manifest.permissions })),
+  );
+  // As on create: a harness Cloud cannot run is refused here, not deployed.
+  // There is no --agents override beside --flow; the listener's agents stay.
+  const unsupported = requirements.harnessUses
+    .filter(use => !(FLOW_AGENT_HARNESSES as readonly string[]).includes(use.harness));
+  if (unsupported.length > 0) {
+    throw new CloudFlowError('unsupported_source',
+      `This flow declares ${unsupported.map(use => `${use.harness} (${use.detail})`).join(', ')}, which Cloud deployments cannot run yet; `
+      + `Cloud runs ${FLOW_AGENT_HARNESSES.join(' and ')}. Change the declaration before deploying a new version.`);
+  }
+  const whoami = await cloudRequest('/api/v1/auth/whoami', options);
+  const workspace = isCloudRecord(whoami) && isCloudRecord(whoami.currentWorkspace) ? whoami.currentWorkspace : undefined;
+  if (workspace === undefined || typeof workspace.id !== 'string' || !workspace.id) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not report a current workspace for this credential.');
+  }
+  // A draft activates nothing, so Cloud checks nothing; match it here.
+  const connected = listener.status !== 'listening' || input.checkConnections === false
+    ? []
+    : (await ensureIntegrationsConnected(requirements, {
+        ...options, workspaceId: workspace.id, ...(input.connect === undefined ? {} : { prompt: input.connect }),
+      })).connected;
+  options.signal?.throwIfAborted();
+  const result = await cloudFetch(`/api/v1/flows/listeners/${encodeURIComponent(agentId)}/versions`, options, {
+    method: 'POST', detail: true, body: JSON.stringify({
+      workspaceId: workspace.id,
+      source,
+      requirements: {
+        integrations: requirements.integrations.map(integration => integration.provider),
+        harnesses: requirements.harnesses,
+        mcp: requirements.mcp,
+      },
+      ...(extensions.length === 0 ? {} : { extensions }),
+    }),
+  });
+  const version = isCloudRecord(result) ? parseVersionChange(result.version) : undefined;
+  if (!isCloudRecord(result) || typeof result.status !== 'string' || version === undefined) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return the new flow version.');
+  }
+  return {
+    agentId, name: listener.name, status: result.status,
+    sourceSha256: createHash('sha256').update(bytes).digest('hex'),
+    requirements, connected, version,
+  };
+}
+
+/** `POST /api/v1/flows/listeners/<id>/versions/<n>/activate`: history is kept; only the pointer moves. */
+export async function activateCloudFlowVersion(
+  flow: string, version: number, options: CloudConnectionOptions = {},
+): Promise<{ agentId: string; status: string; version: CloudFlowVersionChange }> {
+  if (!Number.isSafeInteger(version) || version < 1) {
+    throw new CloudFlowError('invalid_input', `A version is a positive whole number, got "${version}".`);
+  }
+  const agentId = await resolveCloudFlow(flow, options);
+  const result = await cloudFetch(
+    `/api/v1/flows/listeners/${encodeURIComponent(agentId)}/versions/${version}/activate`,
+    options, { method: 'POST', detail: true },
+  );
+  const change = isCloudRecord(result) ? parseVersionChange(result.version) : undefined;
+  if (!isCloudRecord(result) || typeof result.status !== 'string' || change === undefined) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not confirm the active version.');
+  }
+  return { agentId, status: result.status, version: change };
+}

package/src/compile.ts

@@ -38,7 +38,7 @@ import type {
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 import { canonicalize, specHash } from './canonical.js';
 import { validateOutputDeclaration } from './output-schema.js';
-import { validateSpec, type ValidationResult } from './validate.js';
+import { isTransportRetries, validateSpec, type ValidationResult } from './validate.js';
 import { snapshotJsonValue } from './json-value.js';
 import { expandYamlHelpers } from './yaml-helpers.js';
 import { expandCommunication, validateCommunicationTopology } from './communication/spec.js';
@@ -74,7 +74,12 @@ export class CompileError extends Error {
  * survives float-precision (`1.1 * 1000 = 1100.0000000000002`) rather than
  * being rejected by `isSafeInteger`.
  */
-export function parseStepTimeout(timeout: unknown): number {
+export const AGENT_STEP_TIMEOUT_MAX_MS = 60 * 60_000;
+export function parseAgentStepTimeout(timeout: unknown): number {
+  return parseStepTimeout(timeout, true);
+}
+
+export function parseStepTimeout(timeout: unknown, agent = false): number {
   const unitToMs: Record<'ms' | 's' | 'm', number> = { ms: 1, s: 1000, m: 60_000 };
   let milliseconds: number;
   if (typeof timeout === 'number') {
@@ -96,10 +101,10 @@ export function parseStepTimeout(timeout: unknown): number {
     milliseconds = NaN;
   }
   if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) {
-    throw new CompileError(['f.run timeout must be a positive whole number of milliseconds or a duration such as "10s" or "5m".'], 'timeout_invalid');
+    throw new CompileError([`${agent ? 'f.agent' : 'f.run'} timeout must be a positive whole number of milliseconds or a duration such as "10s" or "5m".`], 'timeout_invalid');
   }
-  if (milliseconds > 15 * 60_000) {
-    throw new CompileError(['f.run timeout exceeds the maximum of 15 minutes declared in SURFACE.md.'], 'lease_exceeded');
+  if (milliseconds > (agent ? AGENT_STEP_TIMEOUT_MAX_MS : 15 * 60_000)) {
+    throw new CompileError([`${agent ? 'f.agent' : 'f.run'} timeout exceeds the maximum of ${agent ? 60 : 15} minutes declared in SURFACE.md.`], 'lease_exceeded');
   }
   return milliseconds;
 }
@@ -190,6 +195,8 @@ function compileStep(step: StepSpec): StepSpec {
       ? { dependsOn: step.input === undefined ? step.dependsOn : [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])] } : {}),
     ...(step.input !== undefined ? { input: step.input } : {}),
     maxIterations,
+    ...(step.transportRetries !== undefined && step.transportRetries !== DEFAULT_TRANSPORT_RETRIES
+      ? { transportRetries: step.transportRetries } : {}),
     ...(step.memory !== undefined ? { memory: step.memory } : {}),
     ...(step.requirements !== undefined ? { requirements: step.requirements } : {}),
   };
@@ -209,7 +216,7 @@ function compileStep(step: StepSpec): StepSpec {
         type: 'deterministic',
         command: s.command,
         verification: verification ?? { type: 'exit_code' as const },
-        // #138: `timeoutMs` is deterministic-only — worker-backed verbs own
+        // Timeout fields stay per-verb — worker-backed verbs own
         // their dispatch timeout. It must be spread HERE and nowhere in `base`.
         ...(s.timeoutMs !== undefined ? { timeoutMs: s.timeoutMs } : {}),
         ...(s.lease_ms !== undefined ? { lease_ms: parseStepTimeout(s.lease_ms) } : {}),
@@ -240,6 +247,7 @@ function compileStep(step: StepSpec): StepSpec {
         ...base,
         type: 'agent',
         instruction: s.instruction,
+        ...(s.timeoutMs === undefined ? {} : { timeoutMs: s.timeoutMs }),
         ...(verification !== undefined ? { verification: outputGate(verification, s.id) } : {}),
         ...(s.agent !== undefined ? { agent: s.agent } : {}),
         ...(s.cli !== undefined ? { cli: s.cli } : {}),
@@ -320,6 +328,10 @@ const KERNEL_RETRY_DEFAULTS = {
   jitter_percent: 20,
 } as const;
 
+// spec.rs `default_max_transport_retries`. The kernel serializes this value as
+// absent, so the SDK must too, or an explicit default changes the spec hash.
+const DEFAULT_TRANSPORT_RETRIES = 1;
+
 /**
  * Map an authoring `FlowSpec` to the kernel spec dialect — the single shape at
  * the SDK↔kernel boundary (`kernel/relayflowd-core/src/spec.rs`). Authoring
@@ -452,7 +464,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', 'recovery_mode', 'surfaces', 'permissions', 'cli_identity',
+    'cwd', 'recovery_mode', 'surfaces', 'permissions', 'transport', 'cli_identity',
   ] as const;
   const step = requireKernelObject(value, unionKeys, at);
   if (step['cli_identity'] !== undefined) {
@@ -467,10 +479,11 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
     : type === 'llm'
       ? ['prompt', 'model', 'cli', 'cli_identity'] as const
       : type === 'agent'
-        ? ['instruction', 'cli', 'model', 'cwd', 'recovery_mode', 'surfaces', 'permissions', 'cli_identity'] as const
+        ? ['timeout_ms', 'instruction', 'cli', 'model', 'recovery_mode', 'surfaces', 'permissions', 'cwd', 'transport', 'cli_identity'] as const
         : [];
   assertKernelKeys(step, [...commonKeys, ...typeKeys], at);
-  if (step['retry'] !== undefined) validateAuthoringRetryDefaults(step['retry'], `${at}.retry`);
+  const transportRetries = step['retry'] === undefined
+    ? undefined : validateAuthoringRetryDefaults(step['retry'], `${at}.retry`);
   const dependsOn = step['depends_on'];
   const common = {
     id: step['id'],
@@ -481,6 +494,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
       ? { dependsOn }
       : {}),
     ...(step['max_iterations'] !== undefined ? { maxIterations: step['max_iterations'] } : {}),
+    ...(transportRetries === undefined ? {} : { transportRetries }),
     ...kernelVerificationToAuthoring(type, step['verification'], `${at}.verification`),
     ...(step['memory'] !== undefined ? { memory: kernelMemoryToAuthoring(step['memory'], `${at}.memory`) } : {}),
   };
@@ -500,8 +514,9 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
     return {
       ...common,
       instruction: step['instruction'],
+      ...(step['timeout_ms'] === undefined ? {} : { timeoutMs: step['timeout_ms'] }),
       ...(step['recovery_mode'] !== undefined ? { recoveryMode: step['recovery_mode'] } : {}),
-      ...copyDefined(step, ['cli', 'model', 'cwd', 'surfaces']),
+      ...copyDefined(step, ['cli', 'model', 'surfaces', 'cwd', 'transport']),
       ...(step['permissions'] !== undefined
         ? { permissions: kernelPermissionsToAuthoring(step['permissions'], `${at}.permissions`) }
         : {}),
@@ -510,9 +525,9 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
   return common;
 }
 
-function validateAuthoringRetryDefaults(value: unknown, at: string): void {
+function validateAuthoringRetryDefaults(value: unknown, at: string): number | undefined {
   const retry = requireKernelObject(value, [
-    'initial_backoff_ms', 'max_backoff_ms', 'multiplier', 'jitter_percent',
+    'initial_backoff_ms', 'max_backoff_ms', 'multiplier', 'jitter_percent', 'max_transport_retries',
   ], at);
   for (const [field, expected] of Object.entries(KERNEL_RETRY_DEFAULTS)) {
     if (retry[field] !== expected) {
@@ -521,6 +536,12 @@ function validateAuthoringRetryDefaults(value: unknown, at: string): void {
       ]);
     }
   }
+  const transportRetries = retry['max_transport_retries'];
+  if (transportRetries === undefined) return undefined;
+  if (!isTransportRetries(transportRetries)) {
+    throw new CompileError([`${at}.max_transport_retries must be a non-negative u32 integer`]);
+  }
+  return transportRetries === DEFAULT_TRANSPORT_RETRIES ? undefined : transportRetries;
 }
 
 function kernelVerificationToAuthoring(
@@ -617,7 +638,11 @@ function toKernelStep(step: StepSpec, cliIdentity?: string): ResolvedKernelStepS
       : [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])],
     ...(step.input !== undefined ? { input: step.input } : {}),
     max_iterations: step.maxIterations ?? 1,
-    retry: { ...KERNEL_RETRY_DEFAULTS },
+    retry: {
+      ...KERNEL_RETRY_DEFAULTS,
+      ...(step.transportRetries !== undefined && step.transportRetries !== DEFAULT_TRANSPORT_RETRIES
+        ? { max_transport_retries: step.transportRetries } : {}),
+    },
     verification: toKernelVerification(step),
     ...(cliIdentity !== undefined ? { cli_identity: cliIdentity } : {}),
     ...(step.requirements !== undefined ? { requirements: {
@@ -662,6 +687,7 @@ function toKernelStep(step: StepSpec, cliIdentity?: string): ResolvedKernelStepS
         ...common,
         type: 'agent',
         instruction: step.instruction,
+        ...(step.timeoutMs === undefined ? {} : { timeout_ms: step.timeoutMs }),
         ...(step.cli !== undefined ? { cli: step.cli } : {}),
         ...(step.model !== undefined ? { model: step.model } : {}),
         ...(step.cwd !== undefined ? { cwd: step.cwd } : {}),

package/src/failure-kinds.ts

@@ -207,6 +207,12 @@ export interface StepAttemptFailure {
   /** `retry`, `step_done` or `park`: what the kernel did next, not why it failed. */
   disposition?: string;
   exitCode?: number;
+  /** This attempt's own transport evidence; see `StepFailedDetails`. */
+  transportPhase?: string;
+  transportCause?: string;
+  signal?: string;
+  errorCode?: string;
+  retryableTransport?: boolean;
   /** Redacted, terminal-safe UTF-8 excerpt, at most 256 bytes. */
   stdoutTail?: string;
   /** Redacted, terminal-safe UTF-8 excerpt, at most 256 bytes. */
@@ -277,6 +283,8 @@ export interface StepFailedDetails {
    * `retries_exhausted`.
    */
   maxIterations?: number;
+  /** Additional classified infrastructure retries declared for the step. */
+  transportRetries?: number;
   /**
    * Attempts before this one that died without a result -- the kernel
    * journaled them `crashed` or `lease_expired` itself -- and so, by design,
@@ -286,6 +294,11 @@ export interface StepFailedDetails {
    */
   unchargedAttempts?: number;
   exitCode?: number;
+  transportPhase?: string;
+  transportCause?: string;
+  signal?: string;
+  errorCode?: string;
+  retryableTransport?: boolean;
   /**
    * Terminal-safe UTF-8 excerpt of the captured stdout, at most
    * `EXCERPT_BYTES` (cli/step-excerpt.ts). The field name is kept for

package/src/pty-sidechannel.ts

@@ -31,6 +31,8 @@ export async function openSidechannel(
   canDrive: () => boolean = () => true,
 ) {
   const peers = new Map<Socket, boolean>();
+  const drivePeers = new Set<Socket>();
+  const driveIdle: Array<() => void> = [];
   let closed = false;
   const server = createServer(socket => {
     if (peers.size >= 16) { socket.destroy(); return; }
@@ -39,7 +41,12 @@ export async function openSidechannel(
     let mode: string | undefined;
     socket.setTimeout(2_000, () => socket.destroy());
     socket.on('error', () => socket.destroy());
-    socket.on('close', () => peers.delete(socket));
+    socket.on('close', () => {
+      peers.delete(socket);
+      if (drivePeers.delete(socket) && drivePeers.size === 0) {
+        for (const listener of driveIdle.splice(0)) listener();
+      }
+    });
     socket.on('data', (bytes: Buffer) => {
       if (mode === undefined) {
         hello = Buffer.concat([hello, bytes]);
@@ -52,7 +59,10 @@ export async function openSidechannel(
         socket.setTimeout(0);
         peers.set(socket, true);
         // Passthrough is a passive raw-byte view in this initial slice.
-        if (mode === 'drive') context.onDrive();
+        if (mode === 'drive') {
+          drivePeers.add(socket);
+          context.onDrive();
+        }
         bytes = hello.subarray(end + 1);
         hello = Buffer.alloc(0);
       }
@@ -89,6 +99,32 @@ export async function openSidechannel(
         if (ready && !peer.write(bytes)) peer.destroy();
       }
     },
+    /**
+     * Wait for a drive peer before the CLI is spawned.
+     *
+     * A direct headless CLI must not be handed a pipe merely because a
+     * sidechannel exists: Codex treats any non-TTY stdin as an additional
+     * prompt source and waits for its lifecycle. The caller uses this bounded
+     * enrollment window to choose `pipe` only when a driver actually joined;
+     * view and passthrough peers never change the child's stdin contract.
+     */
+    async waitForDrive(timeoutMs: number): Promise<boolean> {
+      // Enrollment is a live state, not a sticky historical event. Hold the
+      // whole bounded window so a peer that greets and then disconnects before
+      // spawn cannot leave the child with piped stdin and nobody to close it.
+      if (timeoutMs > 0) await new Promise<void>(resolve => setTimeout(resolve, timeoutMs));
+      return drivePeers.size > 0;
+    },
+    /**
+     * Run `listener` once no drive peer is live: now, or when the last one
+     * disconnects. `waitForDrive` is a snapshot, and a peer can leave the
+     * moment after it is taken; the caller that chose `pipe` on it closes the
+     * child's stdin here, so the child never waits on a pipe nobody holds.
+     */
+    whenDriveIdle(listener: () => void): void {
+      if (drivePeers.size === 0) listener();
+      else driveIdle.push(listener);
+    },
     close() {
       if (closed) return;
       closed = true;

package/src/spec.ts

@@ -228,6 +228,8 @@ export interface BaseStepSpec {
   dependsOn?: string[];
   /** Semantic retry bound (kernel DESIGN.md §1.2 `max_iterations`). Default 1. */
   maxIterations?: number;
+  /** Additional attempts after classified infrastructure loss. Default 1. */
+  transportRetries?: number;
 }
 
 export interface OutputBinding {
@@ -288,6 +290,7 @@ export interface LlmStepSpec extends BaseStepSpec {
  */
 export interface AgentStepSpec extends BaseStepSpec {
   type: 'agent';
+  timeoutMs?: number;
   instruction: string;
   verification?: OutputVerificationSpec;
   /** Named authoring declaration selected from `FlowSpec.agents`. Compiled away. */
@@ -352,7 +355,7 @@ export interface YamlHelperParams {
 type OneKey<T> = { [K in keyof T]: Pick<T, K> & Partial<Record<Exclude<keyof T, K>, never>> }[keyof T];
 
 /** Helper sugar is removed before validation of the three kernel step types. */
-export type YamlHelperStepSpec = Pick<BaseStepSpec, 'id' | 'dependsOn' | 'maxIterations'> & {
+export type YamlHelperStepSpec = Pick<BaseStepSpec, 'id' | 'dependsOn' | 'maxIterations' | 'transportRetries'> & {
   verification?: OutputVerificationSpec;
   output?: JsonOutputSchema;
 } & OneKey<{ [P in keyof YamlHelperParams]: OneKey<YamlHelperParams[P]> }>;
@@ -453,6 +456,7 @@ export interface KernelRetryPolicy {
   max_backoff_ms: number;
   multiplier: number;
   jitter_percent: number;
+  max_transport_retries?: number;
 }
 
 /**
@@ -510,6 +514,7 @@ export interface KernelPermissionsSpec {
 
 export interface KernelAgentStep extends KernelStepCommon {
   type: 'agent';
+  timeout_ms?: number;
   instruction: string;
   cli?: string;
   model?: string;