agent-relay 4.0.0 → 4.0.2

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/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 = "4.0.0"
+version = "4.0.2"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "4.0.0"
+    "@agent-relay/config": "4.0.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/utils": "4.0.0"
+    "@agent-relay/utils": "4.0.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -112,7 +112,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@agent-relay/config": "4.0.0",
+    "@agent-relay/config": "4.0.2",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {