fix(cli): pre-parse workflow script files with actionable error hints (#727)

khaliqgant · claude · web-flow · commit da4f2c4c7666 · 2026-04-13T10:58:14.000+02:00
* fix(cli): pre-parse workflow script files with actionable error hints

agent-relay run workflows/foo.ts previously shipped template-literal
parse errors straight through as cryptic esbuild TransformError output
("Expected '}' but found '&lt;token&gt;'") that didn't hint at the actual
cause. Workflow authors kept hitting the same class of mistakes inside
command: and task: template literals:

- raw backticks inside prose or commit messages terminating the outer
  JavaScript template literal early
- unescaped ${...} triggering JS interpolation when a shell variable
  was intended
- literal \n inside shell comments getting eaten as a real newline and
  turning the rest of the "comment" into broken shell

Pre-parse workflow .ts files with esbuild.transformSync BEFORE spawning
tsx, catch the error, and wrap it with a specific diagnostic pointing
at the likely cause. Non-parse errors are rethrown unchanged.

New preParseWorkflowFile() is exported so it can be unit-tested and
reused by other workflow-loading code paths.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

* fix(cli): resolve workspace key via direct broker HTTP fetch

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/cli/commands/messaging.ts b/src/cli/commands/messaging.ts
@@ -1,3 +1,5 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { Command } from 'commander';
 import { RelayCast, AgentRelayClient } from '@agent-relay/sdk';
 import { getProjectPaths } from '@agent-relay/config';
@@ -314,28 +316,56 @@ async function resolveRelaycastApiKey(cwd: string): Promise<string> {
     return envApiKey;
   }
 
-  let client: AgentRelayClient | undefined;
+  const connectionPath = path.join(getProjectPaths(cwd).dataDir, 'connection.json');
+  let raw: string;
   try {
-    client = AgentRelayClient.connect({ cwd });
+    raw = fs.readFileSync(connectionPath, 'utf-8');
   } catch {
     throw new Error(
-      'Relaycast workspace key is not configured. Set RELAY_API_KEY, or start the local broker with `agent-relay up --workspace-key <key>`.'
+      'Failed to read broker connection metadata. Start the broker with `agent-relay up` or set RELAY_API_KEY.'
     );
   }
 
+  let parsed: { port?: unknown; api_key?: unknown };
   try {
-    const session = await client.getSession();
-    const brokerApiKey = session.workspace_key?.trim();
-    if (brokerApiKey) {
-      return brokerApiKey;
+    parsed = JSON.parse(raw) as { port?: unknown; api_key?: unknown };
+  } catch {
+    throw new Error(
+      'Invalid broker connection metadata. Start the broker with `agent-relay up` or set RELAY_API_KEY.'
+    );
+  }
+
+  const port = parsed.port;
+  const apiKey = parsed.api_key;
+  if (typeof port !== 'number' || !Number.isInteger(port) || typeof apiKey !== 'string' || !apiKey.trim()) {
+    throw new Error(
+      'Invalid broker connection metadata. Start the broker with `agent-relay up` or set RELAY_API_KEY.'
+    );
+  }
+
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/session`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+
+    if (!response.ok) {
+      throw new Error(`broker session request failed (${response.status})`);
+    }
+
+    const session = (await response.json()) as {
+      workspaceKey?: string | null;
+      workspace_key?: string | null;
+    };
+    const workspaceKey = session.workspaceKey ?? session.workspace_key;
+    if (workspaceKey && typeof workspaceKey === 'string' && workspaceKey.trim()) {
+      return workspaceKey.trim();
     }
-  } finally {
-    client.disconnect();
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to query broker session: ${detail}`);
   }
 
-  throw new Error(
-    'The running local broker has no Relaycast workspace key, so history and inbox are unavailable in local-only mode. Restart with RELAY_API_KEY or `agent-relay up --workspace-key <key>`.'
-  );
+  throw new Error('No Relaycast workspace key found. Set RELAY_API_KEY or start broker with agent-relay up.');
 }
 
 async function createDefaultRelaycastClient(options: {
diff --git a/src/cli/commands/setup.test.ts b/src/cli/commands/setup.test.ts
@@ -5,7 +5,13 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import { ensureLocalSdkWorkflowRuntime, findLocalSdkWorkspace, registerSetupCommands, type SetupDependencies } from './setup.js';
+import {
+  ensureLocalSdkWorkflowRuntime,
+  findLocalSdkWorkspace,
+  preParseWorkflowFile,
+  registerSetupCommands,
+  type SetupDependencies,
+} from './setup.js';
 
 class ExitSignal extends Error {
   constructor(public readonly code: number) {
@@ -83,7 +89,7 @@ describe('local SDK workflow runtime bootstrapping', () => {
     expect(execRunner).toHaveBeenCalledWith(
       'npm',
       ['run', 'build:sdk'],
-      expect.objectContaining({ cwd: tempRoot, stdio: 'inherit' }),
+      expect.objectContaining({ cwd: tempRoot, stdio: 'inherit' })
     );
     fs.rmSync(tempRoot, { recursive: true, force: true });
   });
@@ -125,7 +131,16 @@ describe('registerSetupCommands', () => {
     const { program, deps } = createHarness();
 
     await runCommand(program, ['run', 'workflow.yaml', '--workflow', 'main']);
-    await runCommand(program, ['run', 'workflow.py', '--resume', 'run-123', '--start-from', 'step-a', '--previous-run-id', 'run-122']);
+    await runCommand(program, [
+      'run',
+      'workflow.py',
+      '--resume',
+      'run-123',
+      '--start-from',
+      'step-a',
+      '--previous-run-id',
+      'run-122',
+    ]);
 
     expect(deps.runYamlWorkflow).toHaveBeenCalledWith('workflow.yaml', {
       workflow: 'main',
@@ -178,3 +193,65 @@ describe('registerSetupCommands', () => {
     expect(exitCode).toBe(1);
   });
 });
+
+describe('preParseWorkflowFile', () => {
+  function writeTempWorkflow(name: string, contents: string): string {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'preparse-'));
+    const full = path.join(dir, name);
+    fs.writeFileSync(full, contents, 'utf8');
+    return full;
+  }
+
+  it('returns silently for a valid TypeScript workflow file', () => {
+    const file = writeTempWorkflow(
+      'valid.ts',
+      `
+import { workflow } from '@agent-relay/sdk/workflows';
+workflow('w')
+  .pattern('dag')
+  .step('one', {
+    type: 'deterministic',
+    command: 'echo hi',
+  });
+`.trim()
+    );
+    expect(() => preParseWorkflowFile(file)).not.toThrow();
+  });
+
+  it('wraps a raw backtick inside a template literal with an actionable hint', () => {
+    // A raw backtick inside a command: template literal terminates
+    // the outer JS template literal early and produces an esbuild
+    // parse error. We want the error message to tell the user how
+    // to fix it.
+    const file = writeTempWorkflow(
+      'bad-backtick.ts',
+      ['const step = {', '  command: `git commit -m "use `npm install` here"`,', '};'].join('\n')
+    );
+    expect(() => preParseWorkflowFile(file)).toThrow(/Workflow file failed to parse/);
+    try {
+      preParseWorkflowFile(file);
+    } catch (err) {
+      const msg = (err as Error).message;
+      expect(msg).toMatch(/Hint:/);
+      expect(msg).toMatch(/single quotes/);
+    }
+  });
+
+  it('wraps an unescaped ${} interpolation with an actionable hint', () => {
+    // Not strictly a parse error in isolation, but combined with a
+    // bad identifier makes esbuild fail. We mostly want to verify the
+    // hint path fires for the common error text.
+    const file = writeTempWorkflow(
+      'bad-dollar.ts',
+      ['const step = {', '  command: `echo ${NOT a valid JS expression}`,', '};'].join('\n')
+    );
+    expect(() => preParseWorkflowFile(file)).toThrow(/Workflow file failed to parse/);
+  });
+
+  it('propagates non-parse errors unchanged', () => {
+    // Non-existent file should throw the fs-level error, not a fake parse wrapper.
+    expect(() => preParseWorkflowFile('/tmp/does-not-exist-' + Date.now() + '.ts')).toThrow(
+      /Cannot read workflow file/
+    );
+  });
+});
diff --git a/src/cli/commands/setup.ts b/src/cli/commands/setup.ts
@@ -3,6 +3,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { execFileSync, spawn as spawnProcess } from 'node:child_process';
 import { Command } from 'commander';
+import { transformSync } from 'esbuild';
 import { getProjectPaths } from '@agent-relay/config';
 import { readBrokerConnection } from '../lib/broker-lifecycle.js';
 import { enableTelemetry, disableTelemetry, getStatus, isDisabledByEnv } from '@agent-relay/telemetry';
@@ -155,6 +156,106 @@ export function ensureLocalSdkWorkflowRuntime(
   }
 }
 
+/**
+ * Pre-parse a TypeScript workflow file with esbuild to catch template-literal
+ * and syntax errors before handing off to tsx. Wraps the raw esbuild error
+ * with hints targeting the most common mistakes in workflow `command:` /
+ * `task:` blocks — raw backticks in prose, unescaped `${...}` that was meant
+ * as a shell variable, etc.
+ *
+ * These all produce cryptic esbuild errors (`Expected "}" but found "<word>"`,
+ * `Unterminated template literal`) that don't hint at the actual cause when
+ * you're writing workflow files.
+ */
+export function preParseWorkflowFile(filePath: string): void {
+  let source: string;
+  try {
+    source = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(`Cannot read workflow file ${filePath}: ${(err as Error).message}`);
+  }
+
+  try {
+    transformSync(source, {
+      loader: 'ts',
+      sourcemap: false,
+      logLevel: 'silent',
+    });
+    return;
+  } catch (err) {
+    const errors = (err as { errors?: EsbuildError[] }).errors;
+    if (!Array.isArray(errors) || errors.length === 0) {
+      throw err;
+    }
+    throw formatWorkflowParseError(filePath, errors[0]!);
+  }
+}
+
+interface EsbuildError {
+  text: string;
+  location?: {
+    file?: string;
+    line?: number;
+    column?: number;
+    lineText?: string;
+  };
+}
+
+function formatWorkflowParseError(filePath: string, e: EsbuildError): Error {
+  const loc = e.location ?? {};
+  const where =
+    loc.line !== undefined
+      ? `${filePath}:${loc.line}${loc.column !== undefined ? `:${loc.column}` : ''}`
+      : filePath;
+
+  const hints: string[] = [];
+  const text = e.text ?? '';
+
+  if (/Expected "\}" but found/i.test(text) || /Unterminated template literal/i.test(text)) {
+    hints.push(
+      'Likely a JavaScript template literal metacharacter inside a `command:` or `task:` block. ' +
+        'Inside workflow .ts files every `command: \\`...\\`` is a JavaScript template literal — ' +
+        'backticks terminate it and `${...}` triggers JS interpolation before the shell ever sees the string.',
+      'Fixes: use single quotes instead of backticks in prose/commit messages; ' +
+        'for shell variables use `$VAR` (no braces) or escape as `\\${VAR}`; ' +
+        'never write literal `\\n` inside a shell comment (it becomes a real newline).'
+    );
+  }
+
+  if (/Unexpected "\$"/.test(text)) {
+    hints.push(
+      'Unexpected `$` inside a template literal usually means `${...}` was interpreted as JS interpolation. ' +
+        'Escape it as `\\${...}` or drop the braces and use plain `$VAR`.'
+    );
+  }
+
+  if (/Expected identifier/.test(text) && /template/i.test(text)) {
+    hints.push(
+      'A template literal interpolation `${...}` needs a valid JS expression inside. ' +
+        'If you meant a shell variable, escape the `$` or drop the braces.'
+    );
+  }
+
+  const lines = ['', `Workflow file failed to parse: ${where}`, `  ${text}`];
+  if (loc.lineText) {
+    lines.push(`  | ${loc.lineText}`);
+    if (loc.column !== undefined && loc.column >= 0) {
+      lines.push(`  | ${' '.repeat(loc.column)}^`);
+    }
+  }
+  if (hints.length > 0) {
+    lines.push('');
+    for (const hint of hints) {
+      lines.push(`Hint: ${hint}`);
+    }
+  }
+  lines.push('');
+
+  const wrapped = new Error(lines.join('\n'));
+  (wrapped as Error & { code?: string }).code = 'WORKFLOW_PARSE_ERROR';
+  return wrapped;
+}
+
 function runScriptFile(
   filePath: string,
   options: { dryRun?: boolean; resume?: string; startFrom?: string; previousRunId?: string } = {}
@@ -211,6 +312,17 @@ Run ID: ${runId}`;
   if (ext === '.ts' || ext === '.tsx') {
     ensureLocalSdkWorkflowRuntime(path.dirname(resolved));
 
+    // Pre-parse the file with esbuild so template-literal mistakes (raw
+    // backticks inside prose, unescaped ${} in shell commands, etc.) fail
+    // fast with an actionable error message instead of a cryptic tsx
+    // TransformError dumped mid-run.
+    try {
+      preParseWorkflowFile(resolved);
+    } catch (err) {
+      cleanupRunIdFile();
+      throw err;
+    }
+
     const runners = ['tsx', 'ts-node'];
     for (const runner of runners) {
       try {
