agent-relay 3.2.21 → 4.0.0

package/packages/sdk/src/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared input/output types for the broker SDK.
+ */
+
+import type { AgentRuntime, HeadlessProvider, MessageInjectionMode, RestartPolicy } from './protocol.js';
+
+export interface SpawnPtyInput {
+  name: string;
+  cli: string;
+  args?: string[];
+  channels?: string[];
+  task?: string;
+  model?: string;
+  cwd?: string;
+  team?: string;
+  shadowOf?: string;
+  shadowMode?: string;
+  idleThresholdSecs?: number;
+  restartPolicy?: RestartPolicy;
+  continueFrom?: string;
+  skipRelayPrompt?: boolean;
+}
+
+export interface SpawnHeadlessInput {
+  name: string;
+  provider: HeadlessProvider;
+  args?: string[];
+  channels?: string[];
+  task?: string;
+  skipRelayPrompt?: boolean;
+}
+
+export type AgentTransport = 'pty' | 'headless';
+
+export interface SpawnProviderInput {
+  name: string;
+  provider: string;
+  transport?: AgentTransport;
+  args?: string[];
+  channels?: string[];
+  task?: string;
+  model?: string;
+  cwd?: string;
+  team?: string;
+  shadowOf?: string;
+  shadowMode?: string;
+  idleThresholdSecs?: number;
+  restartPolicy?: RestartPolicy;
+  continueFrom?: string;
+  skipRelayPrompt?: boolean;
+}
+
+export interface SendMessageInput {
+  to: string;
+  text: string;
+  from?: string;
+  threadId?: string;
+  workspaceId?: string;
+  workspaceAlias?: string;
+  priority?: number;
+  data?: Record<string, unknown>;
+  mode?: MessageInjectionMode;
+}
+
+export interface ListAgent {
+  name: string;
+  runtime: AgentRuntime;
+  provider?: HeadlessProvider;
+  cli?: string;
+  model?: string;
+  team?: string;
+  channels: string[];
+  parent?: string;
+  pid?: number;
+}

package/packages/sdk/src/workflows/cli.ts

@@ -52,6 +52,21 @@ type ExecuteOptions = {
   previousRunId?: string;
 };
 
+/** Flags that consume the next argument as their value. Single source of truth for CLI parsing. */
+const FLAGS_WITH_VALUES = new Set(['--resume', '--workflow', '--start-from', '--previous-run-id']);
+
+function getYamlPathArg(args: string[]): string | undefined {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      if (FLAGS_WITH_VALUES.has(arg)) i += 1;
+      continue;
+    }
+    return arg;
+  }
+  return undefined;
+}
+
 interface RenderableTask {
   output?: string;
   title: string;
@@ -302,6 +317,7 @@ async function runWithListr(
 
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
+  const yamlPath = getYamlPathArg(args);
 
   if (args.length === 0 || args.includes('--help')) {
     printUsage();
@@ -358,7 +374,37 @@ async function main(): Promise<void> {
           break;
       }
     });
-    const result = await runner.resume(runId);
+    let result: RunnerResult;
+    try {
+      const resumeConfig = yamlPath ? await runner.parseYamlFile(yamlPath) : undefined;
+      if (resumeConfig) {
+        console.warn(
+          chalk.yellow(
+            '[workflow] warning: resuming with current config from disk — ' +
+              'if the workflow YAML changed since the original run, behaviour may differ'
+          )
+        );
+      }
+      result = await runner.resume(runId, undefined, resumeConfig);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const isRunNotFound = message.startsWith(`Run "${runId}" not found`);
+      if (isRunNotFound) {
+        if (fileDb.hasStepOutputs(runId)) {
+          console.error(
+            chalk.red(
+              `Error: ${message}. Step outputs exist for this run, but persisted run state is missing from ${dbPath}. ` +
+                `Use --start-from with --previous-run-id ${runId} to recover from the cached step outputs instead.`
+            )
+          );
+        } else {
+          console.error(chalk.red(`Error: ${message}`));
+        }
+      } else {
+        console.error(chalk.red(`Error: ${message}`));
+      }
+      process.exit(1);
+    }
 
     if (result.status === 'completed') {
       console.log(chalk.green('\nWorkflow completed successfully.'));
@@ -371,7 +417,6 @@ async function main(): Promise<void> {
   }
 
   // ── Normal / validate / dry-run mode ──────────────────────────────────────
-  const yamlPath = args[0];
   let workflowName: string | undefined;
 
   const workflowIdx = args.indexOf('--workflow');
@@ -391,6 +436,12 @@ async function main(): Promise<void> {
     previousRunId = args[prevRunIdx + 1];
   }
 
+  if (!yamlPath) {
+    console.error(chalk.red('Error: workflow YAML path is required'));
+    printUsage();
+    process.exit(1);
+  }
+
   const isValidate = args.includes('--validate');
   const isDryRun = !!process.env.DRY_RUN;
 

package/packages/sdk/src/workflows/file-db.ts

@@ -1,4 +1,4 @@
-import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import type { WorkflowRunRow, WorkflowStepRow } from './types.js';
@@ -24,6 +24,7 @@ export class JsonFileWorkflowDb implements WorkflowDb {
 
   /** Whether the storage directory is writable. False = silent no-op mode. */
   private readonly writable: boolean;
+  private appendFailedOnce = false;
 
   constructor(filePath: string) {
     this.filePath = filePath;
@@ -43,14 +44,32 @@ export class JsonFileWorkflowDb implements WorkflowDb {
     return this.writable;
   }
 
+  hasStepOutputs(runId: string): boolean {
+    try {
+      const dir = path.join(path.dirname(this.filePath), 'step-outputs', runId);
+      return existsSync(dir) && readdirSync(dir).length > 0;
+    } catch {
+      return false;
+    }
+  }
+
   // ── Private helpers ─────────────────────────────────────────────────────
 
   private append(entry: DbEntry): void {
     if (!this.writable) return;
     try {
       appendFileSync(this.filePath, JSON.stringify(entry) + '\n', 'utf8');
-    } catch {
-      // Non-critical — workflow execution continues; resume won't be available.
+    } catch (err) {
+      if (!this.appendFailedOnce) {
+        this.appendFailedOnce = true;
+        console.warn(
+          '[workflow] warning: failed to write run state to ' +
+            this.filePath +
+            ' — --resume will not be available for this run. Use --start-from instead. ' +
+            'Error: ' +
+            (err instanceof Error ? err.message : String(err))
+        );
+      }
     }
   }
 

package/packages/sdk/src/workflows/runner.ts

@@ -1952,14 +1952,25 @@ export class WorkflowRunner {
   }
 
   /** Resume a previously paused or partially completed run. */
-  async resume(runId: string, vars?: VariableContext): Promise<WorkflowRunRow> {
+  async resume(runId: string, vars?: VariableContext, config?: RelayYamlConfig): Promise<WorkflowRunRow> {
     // Set up abort controller early so callers can abort() even during setup
     this.abortController = new AbortController();
     this.paused = false;
 
-    const run = await this.db.getRun(runId);
+    let run = await this.db.getRun(runId);
+    let stepStates = new Map<string, StepState>();
     if (!run) {
-      throw new Error(`Run "${runId}" not found`);
+      const reconstructed = this.reconstructRunFromCache(runId, config);
+      if (!reconstructed) {
+        throw new Error(`Run "${runId}" not found (no database entry or cached step outputs)`);
+      }
+      this.log('[resume] Reconstructing run from cached step outputs (workflow-runs.jsonl missing)');
+      run = reconstructed.run;
+      stepStates = reconstructed.stepStates;
+      await this.db.insertRun(run);
+      for (const [, state] of stepStates) {
+        await this.db.insertStep(state.row);
+      }
     }
     this.persistRunIdHint(runId);
 
@@ -1967,25 +1978,26 @@ export class WorkflowRunner {
       throw new Error(`Run "${runId}" is in status "${run.status}" and cannot be resumed`);
     }
 
-    const config = vars ? this.resolveVariables(run.config, vars) : run.config;
+    const resolvedConfig = vars ? this.resolveVariables(run.config, vars) : run.config;
 
     // Resolve path definitions (same as execute()) so workdir lookups work on resume
-    const pathResult = this.resolvePathDefinitions(config.paths, this.cwd);
+    const pathResult = this.resolvePathDefinitions(resolvedConfig.paths, this.cwd);
     if (pathResult.errors.length > 0) {
       throw new Error(`Path validation failed:\n  ${pathResult.errors.join('\n  ')}`);
     }
     this.resolvedPaths = pathResult.resolved;
 
-    const workflows = config.workflows ?? [];
+    const workflows = resolvedConfig.workflows ?? [];
     const workflow = workflows.find((w) => w.name === run.workflowName);
     if (!workflow) {
       throw new Error(`Workflow "${run.workflowName}" not found in stored config`);
     }
 
-    const existingSteps = await this.db.getStepsByRunId(runId);
-    const stepStates = new Map<string, StepState>();
-    for (const stepRow of existingSteps) {
-      stepStates.set(stepRow.stepName, { row: stepRow });
+    if (stepStates.size === 0) {
+      const existingSteps = await this.db.getStepsByRunId(runId);
+      for (const stepRow of existingSteps) {
+        stepStates.set(stepRow.stepName, { row: stepRow });
+      }
     }
 
     // Reset failed steps to pending for retry
@@ -2006,7 +2018,7 @@ export class WorkflowRunner {
     return this.runWorkflowCore({
       run,
       workflow,
-      config,
+      config: resolvedConfig,
       stepStates,
       isResume: true,
     });
@@ -6547,8 +6559,16 @@ export class WorkflowRunner {
       .slice(0, 32);
   }
 
+  /** Validate that a runId is safe for use in file paths (no traversal). */
+  private validateRunId(runId: string): void {
+    if (/[/\\]|^\.\.?$/.test(runId) || runId.includes('..')) {
+      throw new Error(`Invalid runId: "${runId}" contains path traversal characters`);
+    }
+  }
+
   /** Directory for persisted step outputs: .agent-relay/step-outputs/{runId}/ */
   private getStepOutputDir(runId: string): string {
+    this.validateRunId(runId);
     return path.join(this.cwd, '.agent-relay', 'step-outputs', runId);
   }
 
@@ -6638,6 +6658,153 @@ export class WorkflowRunner {
     }
   }
 
+  /** Match the best workflow from config given a set of cached step names. */
+  private matchWorkflowFromCache(
+    workflows: WorkflowDefinition[],
+    cachedStepNames: Set<string>
+  ): WorkflowDefinition | null {
+    if (workflows.length === 1) return workflows[0];
+
+    if (cachedStepNames.size === 0) {
+      // No cached steps to disambiguate — ambiguous when multiple workflows exist
+      this.log('[resume] Multiple workflows in config with empty cache — cannot disambiguate');
+      return null;
+    }
+
+    // Score each workflow by how many cached steps match, excluding those with unknown steps
+    const scored = workflows
+      .map((candidate) => ({
+        workflow: candidate,
+        matchedSteps: candidate.steps.filter((step) => cachedStepNames.has(step.name)).length,
+        unknownSteps: [...cachedStepNames].filter(
+          (name) => !candidate.steps.some((step) => step.name === name)
+        ).length,
+      }))
+      .filter((candidate) => candidate.unknownSteps === 0)
+      .sort((a, b) => b.matchedSteps - a.matchedSteps);
+
+    return scored[0]?.workflow ?? null;
+  }
+
+  private reconstructRunFromCache(
+    runId: string,
+    config?: RelayYamlConfig
+  ): { run: WorkflowRunRow; stepStates: Map<string, StepState> } | null {
+    const stepOutputDir = this.getStepOutputDir(runId);
+    if (!existsSync(stepOutputDir)) return null;
+
+    let resumeConfig = config ?? this.currentConfig;
+    if (!resumeConfig) {
+      // Attempt to load config from relay.yaml on disk (resume() may call before runWorkflowCore sets currentConfig)
+      const yamlPath = path.join(this.cwd, 'relay.yaml');
+      if (existsSync(yamlPath)) {
+        try {
+          const raw = readFileSync(yamlPath, 'utf-8');
+          resumeConfig = this.parseYamlString(raw, yamlPath);
+        } catch {
+          return null;
+        }
+      } else {
+        return null;
+      }
+    }
+
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(stepOutputDir, { withFileTypes: true });
+    } catch {
+      return null;
+    }
+
+    const cachedStepNames = new Set(
+      entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+        .map((entry) => entry.name.slice(0, -3))
+        .filter(Boolean)
+    );
+    const workflows = resumeConfig.workflows ?? [];
+    if (workflows.length === 0) return null;
+
+    // Empty cache directory is valid — all steps will be re-run
+    const workflow = this.matchWorkflowFromCache(workflows, cachedStepNames);
+    if (!workflow) return null;
+
+    // Use actual file modification times from cached outputs instead of synthetic timestamps
+    const stepMtimes = new Map<string, string>();
+    let earliestMtime = Date.now();
+    for (const stepName of cachedStepNames) {
+      try {
+        const mdPath = path.join(stepOutputDir, `${stepName}.md`);
+        const reportPath = path.join(stepOutputDir, `${stepName}.report.json`);
+        const mdStat = existsSync(mdPath) ? statSync(mdPath) : null;
+        const reportStat = existsSync(reportPath) ? statSync(reportPath) : null;
+        // Use the latest mtime between .md and .report.json
+        const mtime = Math.max(mdStat?.mtimeMs ?? 0, reportStat?.mtimeMs ?? 0);
+        if (mtime > 0) {
+          stepMtimes.set(stepName, new Date(mtime).toISOString());
+          if (mtime < earliestMtime) earliestMtime = mtime;
+        }
+      } catch {
+        // Fall back to current time if stat fails
+      }
+    }
+    const fallbackTime = new Date().toISOString();
+
+    const completedSteps = new Set(workflow.steps.filter((step) => cachedStepNames.has(step.name)).map((step) => step.name));
+    // Heuristic: mark the first eligible non-completed step as failed (the likely failure point)
+    const failedStepName = workflow.steps.find(
+      (step) => !completedSteps.has(step.name) && (step.dependsOn ?? []).every((dep) => completedSteps.has(dep))
+    )?.name;
+
+    const runStartedAt = new Date(earliestMtime).toISOString();
+    const run: WorkflowRunRow = {
+      id: runId,
+      workspaceId: this.workspaceId,
+      workflowName: workflow.name,
+      pattern: resumeConfig.swarm.pattern,
+      status: 'failed',
+      config: resumeConfig,
+      startedAt: runStartedAt,
+      createdAt: runStartedAt,
+      updatedAt: fallbackTime,
+    };
+
+    const stepStates = new Map<string, StepState>();
+    for (const step of workflow.steps) {
+      const isNonAgent = step.type === 'deterministic' || step.type === 'worktree' || step.type === 'integration';
+      const cachedOutput = completedSteps.has(step.name) ? this.loadStepOutput(runId, step.name) : undefined;
+      const status: WorkflowStepStatus =
+        completedSteps.has(step.name) ? 'completed' : step.name === failedStepName ? 'failed' : 'pending';
+
+      const stepRow: WorkflowStepRow = {
+        id: this.generateId(),
+        runId,
+        stepName: step.name,
+        agentName: isNonAgent ? null : (step.agent ?? null),
+        stepType: isNonAgent ? (step.type as 'deterministic' | 'worktree' | 'integration') : 'agent',
+        status,
+        task:
+          step.type === 'deterministic'
+            ? (step.command ?? '')
+            : step.type === 'worktree'
+              ? (step.branch ?? '')
+              : step.type === 'integration'
+                ? (`${step.integration}.${step.action}`)
+                : (step.task ?? ''),
+        dependsOn: step.dependsOn ?? [],
+        output: cachedOutput,
+        error: status === 'failed' ? 'Recovered from cached step outputs' : undefined,
+        completedAt: status === 'completed' ? (stepMtimes.get(step.name) ?? fallbackTime) : undefined,
+        retryCount: 0,
+        createdAt: stepMtimes.get(step.name) ?? fallbackTime,
+        updatedAt: stepMtimes.get(step.name) ?? fallbackTime,
+      };
+      stepStates.set(step.name, { row: stepRow });
+    }
+
+    return { run, stepStates };
+  }
+
   /** Get or create the worker logs directory (.agent-relay/team/worker-logs) */
   private getWorkerLogsDir(): string {
     const logsDir = path.join(this.cwd, '.agent-relay', 'team', 'worker-logs');

package/packages/sdk/src/workflows/validator.ts

@@ -1,4 +1,5 @@
 import type { RelayYamlConfig, AgentDefinition, WorkflowStep } from './types.js';
+import { CodexModels } from '@agent-relay/config';
 
 export interface ValidationIssue {
   severity: 'error' | 'warning' | 'info';
@@ -117,7 +118,24 @@ export function validateWorkflow(config: RelayYamlConfig): ValidationIssue[] {
         });
       }
 
-      // Check 4: non-interactive agent that references relay messaging tools in task
+      // Check 4: codex-spark cannot be used in non-interactive mode
+      const CODEX_SPARK_MODELS: string[] = [CodexModels.GPT_5_3_CODEX_SPARK];
+      if (
+        def.interactive === false &&
+        def.cli === 'codex' &&
+        def.constraints?.model &&
+        (CODEX_SPARK_MODELS.includes(def.constraints.model) || /codex-spark/i.test(def.constraints.model))
+      ) {
+        issues.push({
+          severity: 'error',
+          code: 'CODEX_SPARK_NON_INTERACTIVE',
+          message: `Agent "${step.agent}" uses codex-spark model in non-interactive mode. Codex Spark does not support non-interactive (headless) execution.`,
+          fix: `Switch to a different model (e.g. gpt-5.3-codex) or set the agent to interactive mode.`,
+          location: `step:${step.name}`,
+        });
+      }
+
+      // Check 5: non-interactive agent that references relay messaging tools in task
       if (
         def.interactive === false &&
         (task.includes('mcp__relaycast__message_dm_send') || task.includes('mcp__relaycast__message_post') || task.includes('mcp__relaycast__message_inbox_check'))
@@ -132,7 +150,7 @@ export function validateWorkflow(config: RelayYamlConfig): ValidationIssue[] {
       }
     }
 
-    // Check 5: maxConcurrency vs interactive agent count
+    // Check 6: maxConcurrency vs interactive agent count
     const interactiveSteps = (workflow.steps ?? []).filter((s) => {
       if (s.type === 'deterministic') return false;
       const def = agentMap.get(s.agent ?? '');

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.2.21"
+version = "4.0.0"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"

package/packages/sdk-py/src/agent_relay/__init__.py

@@ -13,13 +13,9 @@ except ImportError:
 from .models import Models
 from .client import AgentRelayClient, AgentRelayProtocolError, AgentRelayProcessError
 from .protocol import (
-    PROTOCOL_VERSION,
     AgentRuntime,
-    AgentSpec,
     BrokerEvent,
     MessageInjectionMode,
-    ProtocolEnvelope,
-    RestartPolicy as ProtocolRestartPolicy,
 )
 
 # ── Secondary API: Workflow builder (backward compatibility) ──────────────────
@@ -89,13 +85,9 @@ __all__ = [
     "AgentRelayClient",
     "AgentRelayProtocolError",
     "AgentRelayProcessError",
-    "PROTOCOL_VERSION",
     "AgentRuntime",
-    "AgentSpec",
     "BrokerEvent",
     "MessageInjectionMode",
-    "ProtocolEnvelope",
-    "ProtocolRestartPolicy",
     # Workflow builder (backward compat)
     "workflow",
     "WorkflowBuilder",