agent-relay 3.2.22 → 4.0.1

package/packages/sdk/src/workflows/template-resolver.ts

@@ -0,0 +1,180 @@
+import type { RelayYamlConfig } from './types.js';
+
+/**
+ * Escape a string for safe inclusion in a shell command passed to `sh -c`.
+ * Wraps the value in single quotes and escapes any embedded single quotes.
+ */
+export function shellEscape(value: string): string {
+  return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+
+const TEMPLATE_VARIABLE_PATTERN = /\{\{([\w][\w.\-]*)\}\}/g;
+const STEP_OUTPUT_TEMPLATE_PATTERN = /\{\{(steps\.[\w\-]+\.output)\}\}/g;
+const STEP_OUTPUT_REF_PATTERN = /^steps\.([\w\-]+)\.output$/;
+
+/**
+ * Variable context for template resolution.
+ * Values are typed as `unknown` to accommodate dynamic step-output contexts;
+ * only scalar values (string | number | boolean) are interpolated — complex
+ * objects are coerced via String(). Shell-bound templates are escaped by
+ * {@link resolveTemplateForShell}.
+ */
+export interface VariableContext {
+  [key: string]: unknown;
+}
+
+export function resolveVariables(config: RelayYamlConfig, vars: VariableContext): RelayYamlConfig {
+  const resolved = structuredClone(config);
+
+  for (const agent of resolved.agents) {
+    if (agent.task) {
+      agent.task = resolveTemplate(agent.task, vars);
+    }
+  }
+
+  if (resolved.workflows) {
+    for (const workflow of resolved.workflows) {
+      for (const step of workflow.steps) {
+        if (step.task) {
+          step.task = resolveTemplate(step.task, vars);
+        }
+        if (step.command) {
+          step.command = resolveTemplateForShell(step.command, vars);
+        }
+        if (step.params && typeof step.params === 'object') {
+          for (const key of Object.keys(step.params)) {
+            const value = (step.params as Record<string, unknown>)[key];
+            if (typeof value === 'string') {
+              (step.params as Record<string, string>)[key] = resolveTemplate(value, vars);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return resolved;
+}
+
+export function resolveTemplate(template: string, context: VariableContext): string {
+  return template.replace(TEMPLATE_VARIABLE_PATTERN, (match, key: string) => {
+    if (key.startsWith('steps.')) {
+      return match;
+    }
+
+    const value = resolveDotPath(key, context);
+    if (value === undefined) {
+      throw new Error(`Unresolved variable: {{${key}}}`);
+    }
+    return String(value);
+  });
+}
+
+/**
+ * Like resolveTemplate but shell-escapes interpolated values.
+ * Use this when the result will be passed to `sh -c` to prevent injection.
+ */
+export function resolveTemplateForShell(template: string, context: VariableContext): string {
+  return template.replace(TEMPLATE_VARIABLE_PATTERN, (match, key: string) => {
+    if (key.startsWith('steps.')) {
+      return match;
+    }
+
+    const value = resolveDotPath(key, context);
+    if (value === undefined) {
+      throw new Error(`Unresolved variable: {{${key}}}`);
+    }
+    return shellEscape(String(value));
+  });
+}
+
+export function resolveDotPath(key: string, context: VariableContext): string | number | boolean | undefined {
+  if (!key.includes('.')) {
+    return toTemplateScalar(context[key]);
+  }
+
+  const parts = key.split('.');
+  let current: unknown = context;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return toTemplateScalar(current);
+}
+
+export function resolveStepOutputRef(ref: string, stepOutputs: Map<string, string>): string {
+  const normalizedRef = ref.startsWith('{{') && ref.endsWith('}}') ? ref.slice(2, -2).trim() : ref;
+  const match = STEP_OUTPUT_REF_PATTERN.exec(normalizedRef);
+  if (!match) {
+    throw new Error(`Invalid step output reference: ${ref}`);
+  }
+
+  const stepOutput = stepOutputs.get(match[1]);
+  if (stepOutput === undefined) {
+    throw new Error(`Unresolved step output reference: ${ref}`);
+  }
+
+  return stepOutput;
+}
+
+export function interpolateStepTask(template: string, context: VariableContext): string {
+  const stepOutputs = buildStepOutputMap(context);
+  return template.replace(STEP_OUTPUT_TEMPLATE_PATTERN, (match, ref: string) => {
+    try {
+      return resolveStepOutputRef(ref, stepOutputs);
+    } catch {
+      return match;
+    }
+  });
+}
+
+function buildStepOutputMap(context: VariableContext): Map<string, string> {
+  const stepOutputs = new Map<string, string>();
+  const steps = context.steps;
+
+  if (!steps || typeof steps !== 'object') {
+    return stepOutputs;
+  }
+
+  for (const [stepName, stepState] of Object.entries(steps as Record<string, unknown>)) {
+    if (!stepState || typeof stepState !== 'object') {
+      continue;
+    }
+
+    const output = toTemplateScalar((stepState as Record<string, unknown>).output);
+    if (output !== undefined) {
+      stepOutputs.set(stepName, String(output));
+    }
+  }
+
+  return stepOutputs;
+}
+
+function toTemplateScalar(value: unknown): string | number | boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+  return String(value);
+}
+
+export class TemplateResolver {
+  resolveVariables(config: RelayYamlConfig, vars: VariableContext): RelayYamlConfig {
+    return resolveVariables(config, vars);
+  }
+
+  interpolate(template: string, vars: VariableContext): string {
+    return resolveTemplate(template, vars);
+  }
+
+  resolveDotPath(key: string, vars: VariableContext): string | number | boolean | undefined {
+    return resolveDotPath(key, vars);
+  }
+
+  interpolateStepTask(template: string, context: VariableContext): string {
+    return interpolateStepTask(template, context);
+  }
+}

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/src/workflows/verification.ts

@@ -0,0 +1,184 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import type {
+  CompletionEvidenceSignal,
+  CompletionEvidenceToolSideEffect,
+  VerificationCheck,
+  WorkflowStepCompletionReason,
+} from './types.js';
+
+export type { VerificationCheck } from './types.js';
+
+export interface VerificationResult {
+  passed: boolean;
+  completionReason?: WorkflowStepCompletionReason;
+  error?: string;
+}
+
+export interface VerificationOptions {
+  allowFailure?: boolean;
+  completionMarkerFound?: boolean;
+  cwd?: string;
+}
+
+export class WorkflowCompletionError extends Error {
+  completionReason?: WorkflowStepCompletionReason;
+
+  constructor(message: string, completionReason?: WorkflowStepCompletionReason) {
+    super(message);
+    this.name = 'WorkflowCompletionError';
+    this.completionReason = completionReason;
+  }
+}
+
+export interface VerificationSideEffects {
+  recordStepToolSideEffect?: (
+    stepName: string,
+    effect: Omit<CompletionEvidenceToolSideEffect, 'observedAt'> & { observedAt?: string }
+  ) => void;
+  getOrCreateStepEvidenceRecord?: (stepName: string) => {
+    evidence: { coordinationSignals: CompletionEvidenceSignal[] };
+  };
+  log?: (message: string) => void;
+}
+
+export function runVerification(
+  check: VerificationCheck,
+  output: string,
+  stepName: string,
+  injectedTaskText?: string,
+  options: VerificationOptions = {},
+  sideEffects: VerificationSideEffects = {}
+): VerificationResult {
+  const cwd = options.cwd ?? process.cwd();
+
+  const fail = (message: string): VerificationResult => {
+    const observedAt = new Date().toISOString();
+    sideEffects.recordStepToolSideEffect?.(stepName, {
+      type: 'verification_observed',
+      detail: message,
+      observedAt,
+      raw: { passed: false, type: check.type, value: check.value },
+    });
+    sideEffects.getOrCreateStepEvidenceRecord?.(stepName).evidence.coordinationSignals.push({
+      kind: 'verification_failed',
+      source: 'verification',
+      text: message,
+      observedAt,
+      value: check.value,
+    });
+
+    if (options.allowFailure) {
+      return {
+        passed: false,
+        completionReason: 'failed_verification',
+        error: message,
+      };
+    }
+
+    throw new WorkflowCompletionError(message, 'failed_verification');
+  };
+
+  switch (check.type) {
+    case 'output_contains': {
+      const token = check.value;
+      if (!checkOutputContains(output, token, injectedTaskText)) {
+        return fail(`Verification failed for "${stepName}": output does not contain "${token}"`);
+      }
+      break;
+    }
+
+    case 'exit_code':
+      if (!checkExitCode(check.value)) {
+        return fail(`Verification failed for "${stepName}": exit code did not match "${check.value}"`);
+      }
+      break;
+
+    case 'file_exists':
+      if (!checkFileExists(check.value, cwd)) {
+        return fail(`Verification failed for "${stepName}": file "${check.value}" does not exist`);
+      }
+      break;
+
+    case 'custom':
+      return { passed: false };
+
+    default:
+      break;
+  }
+
+  if (options.completionMarkerFound === false) {
+    sideEffects.log?.(
+      `[${stepName}] Verification passed without legacy STEP_COMPLETE marker; allowing completion`
+    );
+  }
+
+  const observedAt = new Date().toISOString();
+  const successMessage =
+    options.completionMarkerFound === false
+      ? 'Verification passed without legacy STEP_COMPLETE marker'
+      : 'Verification passed';
+  sideEffects.recordStepToolSideEffect?.(stepName, {
+    type: 'verification_observed',
+    detail: successMessage,
+    observedAt,
+    raw: { passed: true, type: check.type, value: check.value },
+  });
+  sideEffects.getOrCreateStepEvidenceRecord?.(stepName).evidence.coordinationSignals.push({
+    kind: 'verification_passed',
+    source: 'verification',
+    text: successMessage,
+    observedAt,
+    value: check.value,
+  });
+
+  return {
+    passed: true,
+    completionReason: 'completed_verified',
+  };
+}
+
+export function stripInjectedTaskEcho(output: string, injectedTaskText?: string): string {
+  if (!injectedTaskText) {
+    return output;
+  }
+
+  const candidates = [
+    injectedTaskText,
+    injectedTaskText.replace(/\r\n/g, '\n'),
+    injectedTaskText.replace(/\n/g, '\r\n'),
+  ].filter((candidate, index, all) => candidate.length > 0 && all.indexOf(candidate) === index);
+
+  for (const candidate of candidates) {
+    const start = output.indexOf(candidate);
+    if (start !== -1) {
+      return output.slice(0, start) + output.slice(start + candidate.length);
+    }
+  }
+
+  return output;
+}
+
+export function checkExitCode(_expectedExitCode: string): boolean {
+  // Existing runner semantics treat process success as established before this
+  // verification hook runs, so this check is currently an unconditional pass.
+  return true;
+}
+
+export function checkOutputContains(output: string, token: string, injectedTaskText?: string): boolean {
+  if (!token) {
+    return false;
+  }
+  return stripInjectedTaskEcho(output, injectedTaskText).includes(token);
+}
+
+export function checkFileExists(filePath: string, cwd = process.cwd()): boolean {
+  const normalizedCwd = path.resolve(cwd);
+  const resolved = path.resolve(normalizedCwd, filePath);
+  // Prevent path traversal outside the working directory
+  if (!resolved.startsWith(normalizedCwd + path.sep) && resolved !== normalizedCwd) {
+    return false;
+  }
+  return existsSync(resolved);
+}

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.2.22"
+version = "4.0.1"
 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",