agent-relay 4.0.0 → 4.0.2

package/packages/sdk/dist/workflows/template-resolver.js

@@ -0,0 +1,144 @@
+/**
+ * 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) {
+    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$/;
+export function resolveVariables(config, vars) {
+    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[key];
+                        if (typeof value === 'string') {
+                            step.params[key] = resolveTemplate(value, vars);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return resolved;
+}
+export function resolveTemplate(template, context) {
+    return template.replace(TEMPLATE_VARIABLE_PATTERN, (match, key) => {
+        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, context) {
+    return template.replace(TEMPLATE_VARIABLE_PATTERN, (match, key) => {
+        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, context) {
+    if (!key.includes('.')) {
+        return toTemplateScalar(context[key]);
+    }
+    const parts = key.split('.');
+    let current = context;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return toTemplateScalar(current);
+}
+export function resolveStepOutputRef(ref, stepOutputs) {
+    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, context) {
+    const stepOutputs = buildStepOutputMap(context);
+    return template.replace(STEP_OUTPUT_TEMPLATE_PATTERN, (match, ref) => {
+        try {
+            return resolveStepOutputRef(ref, stepOutputs);
+        }
+        catch {
+            return match;
+        }
+    });
+}
+function buildStepOutputMap(context) {
+    const stepOutputs = new Map();
+    const steps = context.steps;
+    if (!steps || typeof steps !== 'object') {
+        return stepOutputs;
+    }
+    for (const [stepName, stepState] of Object.entries(steps)) {
+        if (!stepState || typeof stepState !== 'object') {
+            continue;
+        }
+        const output = toTemplateScalar(stepState.output);
+        if (output !== undefined) {
+            stepOutputs.set(stepName, String(output));
+        }
+    }
+    return stepOutputs;
+}
+function toTemplateScalar(value) {
+    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, vars) {
+        return resolveVariables(config, vars);
+    }
+    interpolate(template, vars) {
+        return resolveTemplate(template, vars);
+    }
+    resolveDotPath(key, vars) {
+        return resolveDotPath(key, vars);
+    }
+    interpolateStepTask(template, context) {
+        return interpolateStepTask(template, context);
+    }
+}
+//# sourceMappingURL=template-resolver.js.map

package/packages/sdk/dist/workflows/template-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-resolver.js","sourceRoot":"","sources":["../../src/workflows/template-resolver.ts"],"names":[],"mappings":"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"}

package/packages/sdk/dist/workflows/verification.d.ts

@@ -0,0 +1,33 @@
+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 declare class WorkflowCompletionError extends Error {
+    completionReason?: WorkflowStepCompletionReason;
+    constructor(message: string, completionReason?: WorkflowStepCompletionReason);
+}
+export interface VerificationSideEffects {
+    recordStepToolSideEffect?: (stepName: string, effect: Omit<CompletionEvidenceToolSideEffect, 'observedAt'> & {
+        observedAt?: string;
+    }) => void;
+    getOrCreateStepEvidenceRecord?: (stepName: string) => {
+        evidence: {
+            coordinationSignals: CompletionEvidenceSignal[];
+        };
+    };
+    log?: (message: string) => void;
+}
+export declare function runVerification(check: VerificationCheck, output: string, stepName: string, injectedTaskText?: string, options?: VerificationOptions, sideEffects?: VerificationSideEffects): VerificationResult;
+export declare function stripInjectedTaskEcho(output: string, injectedTaskText?: string): string;
+export declare function checkExitCode(_expectedExitCode: string): boolean;
+export declare function checkOutputContains(output: string, token: string, injectedTaskText?: string): boolean;
+export declare function checkFileExists(filePath: string, cwd?: string): boolean;
+//# sourceMappingURL=verification.d.ts.map

package/packages/sdk/dist/workflows/verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../../src/workflows/verification.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,iBAAiB,EACjB,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,CAAC,EAAE,4BAA4B,CAAC;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,gBAAgB,CAAC,EAAE,4BAA4B,CAAC;gBAEpC,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,4BAA4B;CAK7E;AAED,MAAM,WAAW,uBAAuB;IACtC,wBAAwB,CAAC,EAAE,CACzB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,IAAI,CAAC,gCAAgC,EAAE,YAAY,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,KACnF,IAAI,CAAC;IACV,6BAA6B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK;QACpD,QAAQ,EAAE;YAAE,mBAAmB,EAAE,wBAAwB,EAAE,CAAA;SAAE,CAAC;KAC/D,CAAC;IACF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,EACzB,OAAO,GAAE,mBAAwB,EACjC,WAAW,GAAE,uBAA4B,GACxC,kBAAkB,CAuFpB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAmBvF;AAED,wBAAgB,aAAa,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAIhE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAKrG;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,OAAO,CAQ9E"}

package/packages/sdk/dist/workflows/verification.js

@@ -0,0 +1,122 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+export class WorkflowCompletionError extends Error {
+    completionReason;
+    constructor(message, completionReason) {
+        super(message);
+        this.name = 'WorkflowCompletionError';
+        this.completionReason = completionReason;
+    }
+}
+export function runVerification(check, output, stepName, injectedTaskText, options = {}, sideEffects = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const fail = (message) => {
+        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, injectedTaskText) {
+    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) {
+    // 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, token, injectedTaskText) {
+    if (!token) {
+        return false;
+    }
+    return stripInjectedTaskEcho(output, injectedTaskText).includes(token);
+}
+export function checkFileExists(filePath, cwd = process.cwd()) {
+    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);
+}
+//# sourceMappingURL=verification.js.map

package/packages/sdk/dist/workflows/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../../src/workflows/verification.ts"],"names":[],"mappings":"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"}

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -112,7 +112,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@agent-relay/config": "4.0.0",
+    "@agent-relay/config": "4.0.2",
     "@relaycast/sdk": "^1.1.0",
     "@sinclair/typebox": "^0.34.48",
     "chalk": "^4.1.2",

package/packages/sdk/src/broker-path.ts

@@ -7,64 +7,170 @@
  */
 
 import { existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { execSync } from 'node:child_process';
+import { join, dirname, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
 const BROKER_NAME = 'agent-relay-broker';
 
+function addUniquePath(paths: string[], candidate: string | null | undefined): void {
+  if (!candidate || paths.includes(candidate)) {
+    return;
+  }
+  paths.push(candidate);
+}
+
+function getImportMetaUrl(): string | null {
+  try {
+    return import.meta.url;
+  } catch {
+    return null;
+  }
+}
+
+function getCurrentModuleDir(): string | null {
+  if (typeof __dirname === 'string' && __dirname) {
+    return __dirname;
+  }
+  if (typeof __filename === 'string' && __filename) {
+    return dirname(__filename);
+  }
+
+  const importMetaUrl = getImportMetaUrl();
+  if (!importMetaUrl) {
+    return null;
+  }
+
+  try {
+    return dirname(fileURLToPath(importMetaUrl));
+  } catch {
+    return null;
+  }
+}
+
+function getCurrentModuleReference(): string | null {
+  if (typeof __filename === 'string' && __filename) {
+    return __filename;
+  }
+  if (typeof __dirname === 'string' && __dirname) {
+    return join(__dirname, 'broker-path.js');
+  }
+
+  return getImportMetaUrl();
+}
+
+function getSdkBinDirs(): string[] {
+  const binDirs: string[] = [];
+
+  const currentModuleDir = getCurrentModuleDir();
+  if (currentModuleDir) {
+    addUniquePath(binDirs, resolve(currentModuleDir, '..', 'bin'));
+  }
+
+  const currentModuleReference = getCurrentModuleReference();
+  if (currentModuleReference) {
+    try {
+      const sdkEntry = createRequire(currentModuleReference).resolve('@agent-relay/sdk');
+      addUniquePath(binDirs, resolve(dirname(sdkEntry), '..', 'bin'));
+    } catch {
+      // Continue with other resolution strategies.
+    }
+  }
+
+  const importMetaUrl = getImportMetaUrl();
+  if (importMetaUrl) {
+    try {
+      addUniquePath(binDirs, resolve(dirname(fileURLToPath(importMetaUrl)), '..', 'bin'));
+    } catch {
+      // Continue with other resolution strategies.
+    }
+  }
+
+  return binDirs;
+}
+
+function getDevelopmentBinaryPaths(ext: string, binDirs: string[]): string[] {
+  const binaryPaths: string[] = [];
+  const repoRoots = new Set<string>();
+
+  const addRepoRoot = (candidate: string | null | undefined): void => {
+    if (!candidate) {
+      return;
+    }
+
+    const repoRoot = resolve(candidate);
+    if (repoRoots.has(repoRoot)) {
+      return;
+    }
+    repoRoots.add(repoRoot);
+
+    addUniquePath(binaryPaths, join(repoRoot, 'target', 'release', `${BROKER_NAME}${ext}`));
+    addUniquePath(binaryPaths, join(repoRoot, 'target', 'debug', `${BROKER_NAME}${ext}`));
+  };
+
+  addRepoRoot(process.cwd());
+
+  const currentModuleDir = getCurrentModuleDir();
+  if (currentModuleDir) {
+    addRepoRoot(resolve(currentModuleDir, '..', '..', '..'));
+  }
+
+  for (const binDir of binDirs) {
+    addRepoRoot(resolve(binDir, '..', '..', '..'));
+  }
+
+  return binaryPaths;
+}
+
 /**
  * Resolve the agent-relay-broker binary path.
  *
  * Search order:
- *   1. SDK's bin/ directory (resolved via createRequire or import.meta.url)
+ *   1. SDK's bin/ directory (resolved via CJS globals, createRequire, or import.meta.url)
  *   2. Platform-specific name (agent-relay-broker-{platform}-{arch}) in bin/
- *   3. PATH lookup via `which` / `where`
+ *   3. Common Cargo development paths (target/release and target/debug)
+ *   4. PATH lookup via `which` / `where`
  *
  * @returns Absolute path to the broker binary, or null if not found
  */
 export function getBrokerBinaryPath(): string | null {
-  let binDir: string | null = null;
-  try {
-    // Use createRequire for ESM-compatible require.resolve
-    const esmRequire = createRequire(import.meta.url);
-    const sdkEntry = esmRequire.resolve('@agent-relay/sdk');
-    binDir = join(dirname(sdkEntry), '..', 'bin');
-  } catch {
-    try {
-      // Fallback: derive from import.meta.url
-      binDir = join(dirname(dirname(fileURLToPath(import.meta.url))), 'bin');
-    } catch {
-      // Neither method worked
-    }
-  }
-  if (!binDir) return null;
-
   const ext = process.platform === 'win32' ? '.exe' : '';
+  const binDirs = getSdkBinDirs();
+  const platformSpecific = `${BROKER_NAME}-${process.platform}-${process.arch}${ext}`;
 
   // 1. Exact name in bin/
-  const exactPath = join(binDir, `${BROKER_NAME}${ext}`);
-  if (existsSync(exactPath)) {
-    return exactPath;
+  for (const binDir of binDirs) {
+    const exactPath = join(binDir, `${BROKER_NAME}${ext}`);
+    if (existsSync(exactPath)) {
+      return exactPath;
+    }
   }
 
   // 2. Platform-specific name in bin/
-  const platformSpecific = `${BROKER_NAME}-${process.platform}-${process.arch}${ext}`;
-  const platformPath = join(binDir, platformSpecific);
-  if (existsSync(platformPath)) {
-    return platformPath;
+  for (const binDir of binDirs) {
+    const platformPath = join(binDir, platformSpecific);
+    if (existsSync(platformPath)) {
+      return platformPath;
+    }
+  }
+
+  // 3. Common development paths for local Cargo builds.
+  for (const developmentPath of getDevelopmentBinaryPaths(ext, binDirs)) {
+    if (existsSync(developmentPath)) {
+      return developmentPath;
+    }
   }
 
-  // 3. PATH lookup
+  // 4. PATH lookup
   try {
     const cmd = process.platform === 'win32' ? 'where' : 'which';
-    const result = execSync(`${cmd} ${BROKER_NAME}`, {
+    const result = execFileSync(cmd, [BROKER_NAME], {
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
     }).trim();
     if (result) {
-      return result.split('\n')[0].trim();
+      return result.split(/\r?\n/u)[0].trim();
     }
   } catch {
     // Not found on PATH

package/packages/sdk/src/client.ts

@@ -41,11 +41,22 @@ export interface AgentRelayClientOptions {
   requestTimeoutMs?: number;
 }
 
+export interface AgentRelayBrokerInitArgs {
+  /** Optional HTTP API port for dashboard proxy (0 = disabled). */
+  apiPort?: number;
+  /** Bind address for the HTTP API. Defaults to 127.0.0.1 in the broker. */
+  apiBind?: string;
+  /** Enable persistence for broker state under the working directory. */
+  persist?: boolean;
+  /** Override the directory used for broker state files. */
+  stateDir?: string;
+}
+
 export interface AgentRelaySpawnOptions {
   /** Path to the agent-relay-broker binary. Auto-resolved if omitted. */
   binaryPath?: string;
-  /** Extra args passed to `broker init` (e.g. ['--persist']). */
-  binaryArgs?: string[];
+  /** Structured options mapped to the broker's Rust `init` CLI flags. */
+  binaryArgs?: AgentRelayBrokerInitArgs;
   /** Broker name. Defaults to cwd basename. */
   brokerName?: string;
   /** Default channels for spawned agents. */
@@ -92,6 +103,29 @@ function isProcessRunning(pid: number): boolean {
   }
 }
 
+function buildBrokerInitArgs(args?: AgentRelayBrokerInitArgs): string[] {
+  if (!args) {
+    return [];
+  }
+
+  const cliArgs: string[] = [];
+
+  if (args.persist) {
+    cliArgs.push('--persist');
+  }
+  if (args.apiPort !== undefined) {
+    cliArgs.push('--api-port', String(args.apiPort));
+  }
+  if (args.apiBind !== undefined) {
+    cliArgs.push('--api-bind', args.apiBind);
+  }
+  if (args.stateDir !== undefined) {
+    cliArgs.push('--state-dir', args.stateDir);
+  }
+
+  return cliArgs;
+}
+
 // ── Client ─────────────────────────────────────────────────────────────
 
 export class AgentRelayClient {
@@ -172,7 +206,7 @@ export class AgentRelayClient {
     const brokerName = options?.brokerName ?? (path.basename(cwd) || 'project');
     const channels = options?.channels ?? ['general'];
     const timeoutMs = options?.startupTimeoutMs ?? 15_000;
-    const userArgs = options?.binaryArgs ?? [];
+    const userArgs = buildBrokerInitArgs(options?.binaryArgs);
 
     const apiKey = `br_${randomBytes(16).toString('hex')}`;
 

package/packages/sdk/src/index.ts

@@ -3,6 +3,7 @@ export * from './types.js';
 export { BrokerTransport, type BrokerTransportOptions, AgentRelayProtocolError } from './transport.js';
 export {
   AgentRelayClient,
+  type AgentRelayBrokerInitArgs,
   type AgentRelayClientOptions,
   type AgentRelaySpawnOptions,
   type SessionInfo,

package/packages/sdk/src/relay.ts

@@ -29,7 +29,11 @@ import path from 'node:path';
 
 import { RelayCast } from '@relaycast/sdk';
 
-import { AgentRelayClient, type AgentRelaySpawnOptions } from './client.js';
+import {
+  AgentRelayClient,
+  type AgentRelayBrokerInitArgs,
+  type AgentRelaySpawnOptions,
+} from './client.js';
 import { AgentRelayProtocolError } from './transport.js';
 import type { SendMessageInput, SpawnPtyInput } from './types.js';
 import type {
@@ -303,7 +307,7 @@ export type EventHook<T> = ((value: T) => void) | null;
 
 export interface AgentRelayOptions {
   binaryPath?: string;
-  binaryArgs?: string[];
+  binaryArgs?: AgentRelayBrokerInitArgs;
   brokerName?: string;
   channels?: string[];
   cwd?: string;