@relayflows/sdk 2.0.48 → 2.0.50

package/src/cli.ts

@@ -48,6 +48,7 @@ import { runCloudLogsFollow, runCloudStatusWatch } from './cli/cloud-live.js';
 import { transcriptTailSource } from './transcript-tail.js';
 import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
+import { isCloudRunBudgetMinutes } from './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';
@@ -100,7 +101,7 @@ export type ParsedArgs =
   | BuildArgs
   | DeployArgs
   | { command: 'serve-webhook'; dataDir: string; port: number; admitted?: readonly string[] }
-  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect: boolean }
+  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect: boolean; budgetMinutes: number | undefined }
   | { command: 'sync'; runId: string; json: boolean; root: string; dryRun: boolean }
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
@@ -147,8 +148,8 @@ const USAGE = [
   'flows check [--against-daemon|--no-daemon-check] [--watch] [--json] [--explain-warnings] <flow.ts|flow.yaml|spec.json>',
   'flows serve-webhook --data-dir <dir> --port <p> [--allow <name>[,<name>]]',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--detach] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] [--reuse-from <run-id>] <flow.yaml|spec.json>',
-  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.yaml|spec.json>',
-  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.ts> --input <inline-json-or-file>',
+  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] [--budget-minutes <n>] <flow.yaml|spec.json>',
+  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] [--budget-minutes <n>] <flow.ts> --input <inline-json-or-file>',
   'flows sync [--json] [--dry-run] [--dir <path>] <run-id>',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--detach] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] <flow.ts> --input <inline-json-or-file>',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
@@ -253,6 +254,15 @@ export async function runCli(
     return 2;
   }
 
+  if (parsed.command === 'run' && !parsed.json && !parsed.noObserverLink
+    && !(parsed.cloudMirror || cloudMirrorRequested(process.env))) {
+    const link = resolveObserverLinkEnv(process.env);
+    if (!link.suppressed && link.workspaceKey === undefined) {
+      io.stderr('Observer unavailable: no workspace key configured; set RELAYCAST_WORKSPACE_KEY or configure '
+        + '~/.agentworkforce/relay/workspaces.json for an Observer link, or pass --cloud-mirror for the Cloud dashboard');
+    }
+  }
+
   if ((parsed.command === 'run' || parsed.command === 'resume') && parsed.detach) {
     const result = await startDetachedRun(args, {
       ...parsed, ...(options.selfCommand === undefined ? {} : { selfCommand: options.selfCommand }),
@@ -536,9 +546,9 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
 
 /**
  * Resolve the pending observer-mint into a URL (or nothing), and route any
- * mint warning to stderr under a `[observer]` label. Silent-skip (`undefined`
- * input) prints nothing at all, so a workspace with no observer configured
- * produces no observer output on stderr or stdout.
+ * mint warning to stderr under a `[observer]` label. An `undefined` input
+ * prints nothing here; any missing-key hint was already emitted while the
+ * observer session was configured.
  */
 async function observerUrlFrom(
   mint: Promise<{ observerUrl?: string; warning?: string }> | undefined,
@@ -729,6 +739,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   let wait = false;
   let syncCode = false;
   let noConnect = false;
+  let budgetMinutes: number | undefined;
   let localAgent = false;
   let detach = false;
   let agentCapacity: number | undefined;
@@ -754,6 +765,13 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
       else noConnect = true;
       continue;
     }
+    if (argument === '--budget-minutes') {
+      const value = args[++index];
+      if (command !== 'run' || budgetMinutes !== undefined || value === undefined || !/^[0-9]+$/.test(value)) return undefined;
+      budgetMinutes = Number(value);
+      if (!isCloudRunBudgetMinutes(budgetMinutes)) return undefined;
+      continue;
+    }
     if (argument === '--detach') {
       if (command === 'check' || detach) return undefined;
       detach = true;
@@ -865,9 +883,9 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     if (detach || allowHumanInfluenced || sawDataDir || !spawn || localAgent || noObserverLink || cloudMirror
       || reuseFromRunId !== undefined) return undefined;
     if (sawInput && !isAuthoredFlowPath(positionals[0]!)) return undefined;
-    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode, noConnect };
+    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode, noConnect, budgetMinutes };
   }
-  if (wait || syncCode || noConnect) return undefined;
+  if (wait || syncCode || noConnect || budgetMinutes !== undefined) return undefined;
   if (reuseFromRunId !== undefined && isAuthoredFlowPath(positionals[0]!)) return undefined;
 
   if (command === 'run' && input !== undefined && !isAuthoredFlowPath(positionals[0]!)) return undefined;

package/src/cloud-run.ts

@@ -17,9 +17,20 @@ import { cloudRunState, isCloudRunActive, type CloudRunState } from './cloud-run
 import { packWorkingTree, prepareCloudSync, uploadCloudCode } from './cloud-sync.js';
 
 export type CloudFlowSource = FlowSpec | { path: string };
+export const MIN_CLOUD_RUN_BUDGET_MINUTES = 30;
+export const MAX_CLOUD_RUN_BUDGET_MINUTES = 180;
+
+export function isCloudRunBudgetMinutes(value: number): boolean {
+  return Number.isSafeInteger(value)
+    && value >= MIN_CLOUD_RUN_BUDGET_MINUTES
+    && value <= MAX_CLOUD_RUN_BUDGET_MINUTES;
+}
+
 export interface RunInCloudOptions extends CloudConnectionOptions {
   /** Existing Cloud workspace to run in; provisioning/authorization remains server-side. */
   workspaceId?: string;
+  /** Hosted run deadline in minutes. Applies to this admission only, not a later resume. */
+  runBudgetMinutes?: number;
   /** Exact JSON input. Required at runtime for authored .flow.ts; refused for declarative source. */
   input?: JsonValue;
   /**
@@ -252,6 +263,10 @@ export async function runInCloud(
 ): Promise<CloudRunReceipt> {
   // Validate locally first: resolving the connection may refresh a stored
   // login, which posts the refresh token and rotates the credential file.
+  if (options.runBudgetMinutes !== undefined && !isCloudRunBudgetMinutes(options.runBudgetMinutes)) {
+    throw new CloudFlowError('configuration',
+      `runBudgetMinutes must be an integer from ${MIN_CLOUD_RUN_BUDGET_MINUTES} to ${MAX_CLOUD_RUN_BUDGET_MINUTES}.`);
+  }
   const envSecrets = snapshotEnvSecrets(options.envSecrets);
   const submission = await prepareCloudSubmission(flow, options);
   const { baseUrl } = await resolveCloudConnection(options);
@@ -281,6 +296,7 @@ export async function runInCloud(
     result = await cloudFetch('/api/v1/workflows/run', options, { 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 }),
     }) });

package/src/local-agent-pins.ts

@@ -0,0 +1,7 @@
+/** Surface a timed-out local agent pins so a fresh worker at the clean tree
+ *  cannot take the continuation. The local worker always holds it. A step
+ *  declares it only when a deadline can continue. */
+export const LOCAL_AGENT_WORKSPACE = 'local-workspace';
+
+/** Revision the local worker reports before a deadline stamps the dirty tree. */
+export const LOCAL_AGENT_REVISION = 'local';

package/src/local-agent.ts

@@ -4,9 +4,10 @@ import type { JournalClient } from './journal-client.js';
 import { AgentWorker } from './worker.js';
 import type { KernelRunSpec } from './spec.js';
 import { communicationInstruction } from './communication/spec.js';
+import { LOCAL_AGENT_REVISION, LOCAL_AGENT_WORKSPACE } from './local-agent-pins.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
 
-/** A local worker for stream-only steps; no workspace recovery is claimed. */
+/** A local worker. It holds `local-workspace` at `local` so a deadline can stamp the dirty tree. */
 export async function attachLocalAgent(
   client: JournalClient,
   dataDir?: string,
@@ -24,7 +25,8 @@ export async function attachLocalAgent(
   // This worker has consumed no messages: its read offsets are zero, including
   // named declarative streams. The kernel retains ownership of dispatch pins
   // and rejects a resume whose required offsets this worker does not hold.
-  // No worktree revision is invented.
+  // `local-workspace` starts at `local`. A deadline stamps that revision from
+  // the dirty tree, so a replacement worker still at `local` cannot take it.
   const stream = requestedStream ?? `local-agent-${randomUUID()}`;
   const worker = new AgentWorker(client, {
     workerId: stream,
@@ -33,8 +35,10 @@ export async function attachLocalAgent(
     // this same number (worker-slots.ts), so they never ask for more.
     capacity,
     dataDir, onPtyReady, runRoot, environment,
-    pins: { workspace: [], streams: [...new Set([stream, ...declaredStreams])]
-      .map(stream => ({ stream, read_offset: 0 })) },
+    pins: {
+      workspace: [{ surface: LOCAL_AGENT_WORKSPACE, revision_id: LOCAL_AGENT_REVISION }],
+      streams: [...new Set([stream, ...declaredStreams])].map(stream => ({ stream, read_offset: 0 })),
+    },
   });
   let failure: unknown;
   // The cause travels with the close, so the flow's next request names it.

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/worker-cli.ts

@@ -1,6 +1,6 @@
 import { realpathSync } from 'node:fs';
 import { basename, dirname, join, resolve, sep } from 'node:path';
-import { diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
+import { deadlineWorkspaceStamp, deletedWorkspaceFiles, diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
 import { claudeResultOutcome, decodeProviderResult, decodeWrapperResult, requirePricedUsage } from './worker-usage.js';
 import { openSidechannel, type SidechannelContext } from './pty-sidechannel.js';
 import {
@@ -87,6 +87,18 @@ export interface WorkerCliResult {
    * agent runs on another host.
    */
   artifacts?: string[];
+  /**
+   * Content-and-deletion identity of the dirty tree, 16 hex characters.
+   * Present when the workspace changed. A deadline appends it to the end-pin
+   * revision so two different edits of the same paths, and a deletion with no
+   * new file, do not look like the clean start.
+   */
+  workspace_stamp?: string;
+  /**
+   * Paths removed during the attempt, cwd-relative and sorted. Journaled
+   * beside `artifacts`. Absent when nothing was deleted.
+   */
+  deleted?: string[];
   /**
    * The attempt's transcript digest (`agent-transcript.ts`): provider result
    * metadata, tool calls summarized, final text, failure excerpt, and — when
@@ -167,9 +179,27 @@ export async function runAgentCli(
       const before = await snapshotWorkspaceFiles(artifactRoot);
       const result = await execute();
       const kernelData = sidechannel === undefined ? undefined : realPath(resolve(sidechannel.dataDir));
-      const artifacts = diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot))
-        .filter(path => !under(realPath(resolve(artifactRoot, path)), kernelData));
-      return { ...result, artifacts };
+      const after = await snapshotWorkspaceFiles(artifactRoot);
+      const visible = (files: Map<string, string>) => {
+        const out = new Map<string, string>();
+        for (const [path, signature] of files) {
+          // `canonicalTree` keeps a deleted path under the data dir excluded:
+          // the file is gone, so a plain realpath falls back to the spelling
+          // and can miss a symlinked data dir.
+          if (!under(canonicalTree(resolve(artifactRoot, path)), kernelData)) out.set(path, signature);
+        }
+        return out;
+      };
+      const stampBefore = visible(before);
+      const stampAfter = visible(after);
+      const workspace_stamp = deadlineWorkspaceStamp(stampBefore, stampAfter);
+      const deleted = deletedWorkspaceFiles(stampBefore, stampAfter);
+      return {
+        ...result,
+        artifacts: diffWorkspaceFiles(stampBefore, stampAfter),
+        ...(workspace_stamp === undefined ? {} : { workspace_stamp }),
+        ...(deleted.length === 0 ? {} : { deleted }),
+      };
     });
 
   async function execute(): Promise<WorkerCliResult> {

package/src/worker-input.ts

@@ -4,12 +4,24 @@ import type { StepDispatchEvent } from './protocol.js';
 export function workerInstruction(instruction: string, dispatch: StepDispatchEvent): string {
   const withMemory = dispatch.memory === undefined ? instruction
     : `${instruction}\n\nMemory context (journaled):\n${JSON.stringify(dispatch.memory.pack)}`;
+  const noted = `${withMemory}${recoveryNote(dispatch)}`;
   if (dispatch.input === undefined) {
     if (typeof dispatch.spec === 'object' && dispatch.spec !== null
       && 'input' in dispatch.spec) {
       throw new Error('Step declares input bindings but the kernel did not resolve them; upgrade relayflowd.');
     }
-    return withMemory;
+    return noted;
   }
-  return `${withMemory}\n\ninput:\n${JSON.stringify(dispatch.input)}`;
+  return `${noted}\n\ninput:\n${JSON.stringify(dispatch.input)}`;
+}
+
+/** Absent on the first attempt. Null and undefined are both "the kernel had nothing". */
+function recoveryNote(dispatch: StepDispatchEvent): string {
+  const reason = dispatch.recovery?.previous_completion_reason;
+  const tail = dispatch.recovery?.trajectory_tail;
+  if ((reason === undefined || reason === null) && (tail === undefined || tail === null)) return '';
+  return `\n\nPrevious attempt (journaled):\n${JSON.stringify({
+    completion_reason: reason ?? null,
+    trajectory_tail: tail ?? null,
+  })}`;
 }

package/src/worker.ts

@@ -222,12 +222,32 @@ export class AgentWorker extends EventEmitter {
         ...(usage !== undefined ? { usage } : {}),
         ...(cost === undefined ? {} : { reported_cost: cost }),
         started_pins: dispatch.pins,
-        end_pins: dispatch.pins,
+        end_pins: completionReason === 'timeout'
+          ? deadlineEndPins(dispatch.pins, result.workspace_stamp)
+          : dispatch.pins,
       },
     );
   }
 }
 
+/**
+ * A deadline's end pin names the dirty tree the next attempt must inspect.
+ * The stamp covers file contents and deletions, not the file bytes: the tail
+ * is capped and the bytes stay on this worker's disk. An empty diff keeps
+ * the start pin.
+ */
+function deadlineEndPins(pins: Pins, stamp: string | undefined): Pins {
+  const workspace = pins.workspace ?? [];
+  if (stamp === undefined || workspace.length === 0) return pins;
+  if (workspace.every(pin => pin.revision_id === '')) return pins;
+  return {
+    ...pins,
+    workspace: workspace.map(pin => pin.revision_id === ''
+      ? pin
+      : { ...pin, revision_id: `${pin.revision_id}+${stamp}` }),
+  };
+}
+
 /**
  * The digest as journaled: the attempt and exit code (dropped from `output` on
  * the JSON path by design) and the artifact paths folded in, then bounded to
@@ -238,9 +258,15 @@ function transcriptDigest(transcript: TranscriptDigest, attempt: number, result:
     attempt,
     exit_code: result.exit_code,
     ...transcript,
-    ...(result.artifacts === undefined ? {} : { artifacts: {
-      count: result.artifacts.length, paths: result.artifacts.slice(0, ARTIFACT_PATHS_MAX),
-    } }),
+    ...(result.artifacts === undefined && (result.deleted === undefined || result.deleted.length === 0) ? {} : {
+      artifacts: {
+        count: result.artifacts?.length ?? 0,
+        paths: (result.artifacts ?? []).slice(0, ARTIFACT_PATHS_MAX),
+        ...(result.deleted === undefined || result.deleted.length === 0 ? {} : {
+          deleted: result.deleted.slice(0, ARTIFACT_PATHS_MAX),
+        }),
+      },
+    }),
   });
 }