agent-relay-orchestrator 0.63.0 → 0.63.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.63.0",
+  "version": "0.63.2",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.41"
+    "agent-relay-sdk": "0.2.42"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/artifact-proxy.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
-import type { OrchestratorConfig } from "./config";
+import { artifactCacheDirFromEnv, type OrchestratorConfig } from "./config";
 import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 const SAFE_ARTIFACT_ID = /^[a-zA-Z0-9._-]{1,160}$/;
@@ -42,7 +42,7 @@ export function artifactProxyBaseUrl(config: Pick<OrchestratorConfig, "apiPort">
 }
 
 function artifactCacheRoot(): string {
-  const configured = process.env.AGENT_RELAY_ARTIFACT_CACHE_DIR || "~/.agent-relay/cache/artifacts";
+  const configured = artifactCacheDirFromEnv();
   if (configured === "~") return homedir();
   if (configured.startsWith("~/")) return join(homedir(), configured.slice(2));
   return configured;

package/src/config.ts

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir, hostname as osHostname } from "node:os";
 import { join, dirname } from "node:path";
+import { DEFAULT_RELAY_URL } from "agent-relay-sdk";
 
 export interface OrchestratorConfig {
   id: string;
@@ -17,6 +18,63 @@ export interface OrchestratorConfig {
 
 const DEFAULT_CONFIG_PATH = join(homedir(), ".agent-relay", "orchestrator.json");
 
+function envNumberOrDefault(name: string, fallback: number): number {
+  return Number(process.env[name]) || fallback;
+}
+
+function envNonNegativeMax(name: string, fallback: number, min: number): number {
+  return Math.max(min, envNumberOrDefault(name, fallback));
+}
+
+export function gitShaFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_GIT_SHA || process.env.GIT_SHA || undefined;
+}
+
+export function agentRelayHome(): string {
+  return process.env.AGENT_RELAY_HOME || join(homedir(), ".agent-relay");
+}
+
+export function artifactCacheDirFromEnv(): string {
+  return process.env.AGENT_RELAY_ARTIFACT_CACHE_DIR || "~/.agent-relay/cache/artifacts";
+}
+
+export function bunBinFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_BUN_BIN;
+}
+
+export function disableSystemdSupervisor(): boolean {
+  return process.env.AGENT_RELAY_DISABLE_SYSTEMD_SUPERVISOR === "1";
+}
+
+export function forceSystemdSupervisor(): boolean {
+  return process.env.AGENT_RELAY_FORCE_SYSTEMD_SUPERVISOR === "1";
+}
+
+export function logDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_LOG_DIR;
+}
+
+export function workspacePushEnabled(): boolean {
+  return process.env.AGENT_RELAY_WORKSPACE_PUSH !== "0";
+}
+
+export function workspaceDepsMode(): string {
+  return (process.env.AGENT_RELAY_WORKSPACE_DEPS || "symlink").toLowerCase();
+}
+
+export const TERMINAL_FLUSH_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_FLUSH_MS", 6, 0);
+export const TERMINAL_FLUSH_MAX_BYTES = envNonNegativeMax("AGENT_RELAY_TERMINAL_FLUSH_MAX_BYTES", 65536, 4096);
+export const TERMINAL_BACKPRESSURE_MAX_BYTES = envNonNegativeMax("AGENT_RELAY_TERMINAL_BACKPRESSURE_MAX_BYTES", 8 << 20, 1 << 20);
+export const TERMINAL_RESIZE_SETTLE_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESIZE_SETTLE_MS", 90, 0);
+export const TERMINAL_RESYNC_DEBOUNCE_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESYNC_DEBOUNCE_MS", 120, 0);
+export const TERMINAL_RESYNC_MAX_INTERVAL_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESYNC_MAX_INTERVAL_MS", 350, 0);
+export const TERMINAL_RESYNC_GROUND_RETRY_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESYNC_GROUND_RETRY_MS", 16, 1);
+export const TERMINAL_RESYNC_GROUND_DEFER_MAX_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESYNC_GROUND_DEFER_MAX_MS", 500, 0);
+export const TERMINAL_COMMAND_TIMEOUT_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_COMMAND_TIMEOUT_MS", 2000, 100);
+export const TERMINAL_GROUND_WAIT_MAX_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_GROUND_WAIT_MAX_MS", 500, 0);
+export const TERMINAL_BACKFILL_SCROLLBACK_LINES = envNonNegativeMax("AGENT_RELAY_TERMINAL_BACKFILL_SCROLLBACK", 1000, 0);
+export const TERMINAL_DEBUG = process.env.AGENT_RELAY_TERMINAL_DEBUG === "1";
+
 interface RawConfig {
   id?: string;
   hostname?: string;
@@ -40,7 +98,7 @@ export function loadConfig(path?: string): OrchestratorConfig {
 
   const id = raw.id || process.env.AGENT_RELAY_ORCHESTRATOR_ID || osHostname().replace(/\./g, "-");
   const hostname = raw.hostname || process.env.AGENT_RELAY_ORCHESTRATOR_HOSTNAME || osHostname();
-  const relayUrl = raw.relayUrl || process.env.AGENT_RELAY_URL || "http://localhost:4850";
+  const relayUrl = raw.relayUrl || process.env.AGENT_RELAY_URL || DEFAULT_RELAY_URL;
   const token = raw.token || process.env.AGENT_RELAY_TOKEN || undefined;
   const providers = (raw.providers || process.env.AGENT_RELAY_ORCHESTRATOR_PROVIDERS?.split(",") || ["claude", "codex"]) as ("claude" | "codex")[];
   const baseDir = raw.baseDir || process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR || join(homedir(), "projects");
@@ -58,7 +116,7 @@ export function initConfigFile(config: Partial<RawConfig>): string {
   const defaults: RawConfig = {
     id: osHostname().replace(/\./g, "-"),
     hostname: osHostname(),
-    relayUrl: "http://localhost:4850",
+    relayUrl: DEFAULT_RELAY_URL,
     providers: ["claude", "codex"],
     baseDir: join(homedir(), "projects"),
     apiPort: 4860,

package/src/provider-config-migration.ts

@@ -1,16 +1,13 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { homedir, hostname } from "node:os";
+import { hostname } from "node:os";
 import { join } from "node:path";
+import { agentRelayHome } from "./config";
 
 interface ProviderConfigMigrationPayload {
   host: string;
   configs: Record<string, unknown>;
 }
 
-function agentRelayHome(): string {
-  return process.env.AGENT_RELAY_HOME || join(homedir(), ".agent-relay");
-}
-
 /**
  * Read the host-local per-provider config files (`~/.agent-relay/providers/*.json`)
  * so the relay can seed the central `provider-config` rows with server authority

package/src/spawn/command.ts

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { artifactProxyBaseUrl } from "../artifact-proxy";
-import type { OrchestratorConfig } from "../config";
+import { bunBinFromEnv, type OrchestratorConfig } from "../config";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { SpawnOptions } from "./types";
 
@@ -26,7 +26,7 @@ export function defaultSpawnLabel(now = Date.now()): string {
 export function buildRunnerCommand(opts: SpawnOptions, config: OrchestratorConfig): string[] {
   const repoLauncher = resolve(import.meta.dir, "../../../runner/src/index.ts");
   const installedLauncher = resolve(import.meta.dir, "../../../agent-relay-runner/src/index.ts");
-  const bun = process.env.AGENT_RELAY_BUN_BIN
+  const bun = bunBinFromEnv()
     || (process.platform === "darwin" && existsSync("/opt/homebrew/bin/bun") ? "/opt/homebrew/bin/bun" : "bun");
   const launcher = existsSync(repoLauncher)
     ? [bun, "run", repoLauncher, opts.provider]

package/src/spawn/supervisor.ts

@@ -8,6 +8,7 @@ import { shellEscape } from "agent-relay-sdk/shell-utils";
 import { tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { SESSION_DIR } from "./constants";
+import { disableSystemdSupervisor, forceSystemdSupervisor } from "../config";
 import { logLines } from "./log-utils";
 import { currentSessionPid, ensureSessionDir, findSessionRecord, isSessionRecordAlive, loadState, logFilePath, readRunnerInfo, removeSessionRecord, sessionSupervisor } from "./runtime";
 import { systemdMainPid, systemdUnitName } from "./systemd";
@@ -45,8 +46,8 @@ export function spawnRunner(name: string, command: string[], cwd: string, env: R
 
 function shouldUseSystemdSupervisor(): boolean {
   if (process.platform !== "linux") return false;
-  if (process.env.AGENT_RELAY_DISABLE_SYSTEMD_SUPERVISOR === "1") return false;
-  if (process.env.AGENT_RELAY_FORCE_SYSTEMD_SUPERVISOR === "1") return true;
+  if (disableSystemdSupervisor()) return false;
+  if (forceSystemdSupervisor()) return true;
   const result = Bun.spawnSync(["systemctl", "--user", "show-environment"], {
     stdin: "ignore",
     stdout: "ignore",

package/src/spawn/terminal.ts

@@ -1,6 +1,6 @@
 import { dirname, join } from "node:path";
 import { readFileSync } from "node:fs";
-import type { OrchestratorConfig } from "../config";
+import { logDirFromEnv, type OrchestratorConfig } from "../config";
 import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { LOG_DIR } from "./constants";
@@ -59,7 +59,7 @@ export function captureSessionMirror(
   // The mirror log lives in the same directory as the provider log (both written
   // by the same user on this host). Derive from the record's logFile when known so
   // it tracks any per-session log relocation.
-  const logDir = record?.logFile ? dirname(record.logFile) : process.env.AGENT_RELAY_LOG_DIR || LOG_DIR;
+  const logDir = record?.logFile ? dirname(record.logFile) : logDirFromEnv() || LOG_DIR;
   const mirrorPath = join(logDir, `session-mirror-${safeMirrorLogName(agentId)}.log`);
   let content: string;
   try {

package/src/terminal-stream.ts

@@ -26,39 +26,36 @@
 // another observing client.
 
 import { sessionLiveness, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
-import type { OrchestratorConfig } from "./config";
+import { TERMINAL_BACKFILL_SCROLLBACK_LINES, TERMINAL_BACKPRESSURE_MAX_BYTES, TERMINAL_COMMAND_TIMEOUT_MS, TERMINAL_DEBUG, TERMINAL_FLUSH_MAX_BYTES, TERMINAL_FLUSH_MS, TERMINAL_GROUND_WAIT_MAX_MS, TERMINAL_RESIZE_SETTLE_MS, TERMINAL_RESYNC_DEBOUNCE_MS, TERMINAL_RESYNC_GROUND_DEFER_MAX_MS, TERMINAL_RESYNC_GROUND_RETRY_MS, TERMINAL_RESYNC_MAX_INTERVAL_MS, type OrchestratorConfig } from "./config";
 import { errMessage } from "agent-relay-sdk";
 
-const FLUSH_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_FLUSH_MS) || 6);
-const FLUSH_MAX_BYTES = Math.max(4096, Number(process.env.AGENT_RELAY_TERMINAL_FLUSH_MAX_BYTES) || 65536);
-const BACKPRESSURE_MAX_BYTES = Math.max(
-  1 << 20,
-  Number(process.env.AGENT_RELAY_TERMINAL_BACKPRESSURE_MAX_BYTES) || 8 << 20,
-);
+const FLUSH_MS = TERMINAL_FLUSH_MS;
+const FLUSH_MAX_BYTES = TERMINAL_FLUSH_MAX_BYTES;
+const BACKPRESSURE_MAX_BYTES = TERMINAL_BACKPRESSURE_MAX_BYTES;
 // After a resize the TUI repaints asynchronously; let tmux's grid settle before we
 // capture, so the backfill is the post-resize frame, not a half-reflowed one.
-const RESIZE_SETTLE_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESIZE_SETTLE_MS) || 90);
+const RESIZE_SETTLE_MS = TERMINAL_RESIZE_SETTLE_MS;
 // Live deltas are relative-cursor moves; replaying them onto a client seeded mid-stream
 // from a capture-pane snapshot can drift (lost scroll-region/SGR/wrap state → doubled
 // statusline, faded suggestion rendered solid, cursor off by a row). We can't transfer
 // full emulator state, so we periodically re-stamp tmux's authoritative grid in place to
 // snap the client back. Debounce after output settles; cap so continuous "thinking"
 // streams still correct. 0 disables the corrector.
-const RESYNC_DEBOUNCE_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_DEBOUNCE_MS) || 120);
-const RESYNC_MAX_INTERVAL_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_MAX_INTERVAL_MS) || 350);
+const RESYNC_DEBOUNCE_MS = TERMINAL_RESYNC_DEBOUNCE_MS;
+const RESYNC_MAX_INTERVAL_MS = TERMINAL_RESYNC_MAX_INTERVAL_MS;
 // When a resync falls due mid-escape-sequence we defer it (ground-state gate, #276) and
 // re-check after this short interval until the stream reaches a sequence boundary.
-const RESYNC_GROUND_RETRY_MS = Math.max(1, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_GROUND_RETRY_MS) || 16);
+const RESYNC_GROUND_RETRY_MS = TERMINAL_RESYNC_GROUND_RETRY_MS;
 // Hard cap on ground-state deferral: if the stream sits mid-sequence this long (a stalled
 // or dead pane — rare), inject the repaint anyway, CAN-prefixed to abort the client's
 // half-parsed sequence. The orphan-tail risk is accepted in that degenerate case (#276).
-const RESYNC_GROUND_DEFER_MAX_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_GROUND_DEFER_MAX_MS) || 500);
+const RESYNC_GROUND_DEFER_MAX_MS = TERMINAL_RESYNC_GROUND_DEFER_MAX_MS;
 // Per-command reply timeout for the in-band control protocol. A reply that never lands
 // means a desync; we reject and reset the reply queue so the next command starts clean.
-const COMMAND_TIMEOUT_MS = Math.max(100, Number(process.env.AGENT_RELAY_TERMINAL_COMMAND_TIMEOUT_MS) || 2000);
+const COMMAND_TIMEOUT_MS = TERMINAL_COMMAND_TIMEOUT_MS;
 // Upper bound a backfill/ready-flip waits for the live stream to reach a sequence boundary
 // before proceeding anyway (whenAtGround fallback for a stalled stream).
-const GROUND_WAIT_MAX_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_GROUND_WAIT_MAX_MS) || 500);
+const GROUND_WAIT_MAX_MS = TERMINAL_GROUND_WAIT_MAX_MS;
 // CAN (cancel) aborts a half-parsed sequence on the client.
 const CAN_BYTE = 0x18;
 
@@ -78,7 +75,7 @@ interface PendingCommand {
 // the history sits in its scroll buffer). This is a one-time per-attach paint, so it's
 // fine to be large; the live resync corrector only ever repaints the current screen, so it
 // never disturbs this history. 0 = current screen only.
-const BACKFILL_SCROLLBACK_LINES = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_BACKFILL_SCROLLBACK) || 1000);
+const BACKFILL_SCROLLBACK_LINES = TERMINAL_BACKFILL_SCROLLBACK_LINES;
 
 export interface TerminalStreamSubscriber {
   onData(bytes: Uint8Array): void;
@@ -107,7 +104,6 @@ export interface TerminalStreamHandle {
 
 const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
-const TERMINAL_DEBUG = process.env.AGENT_RELAY_TERMINAL_DEBUG === "1";
 function tdbg(...args: unknown[]): void {
   if (TERMINAL_DEBUG) console.error("[term-debug]", ...args);
 }

package/src/version.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONTRACT_VERSIONS } from "agent-relay-sdk";
+import { gitShaFromEnv } from "./config";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { name?: string; version?: string };
@@ -12,7 +13,7 @@ export const VERSION = pkg.version || "0.0.0";
 export const ORCHESTRATOR_PROTOCOL_VERSION = CONTRACT_VERSIONS.orchestratorProtocol;
 export const RUNNER_PROTOCOL_VERSION = CONTRACT_VERSIONS.runnerProtocol;
 export const PROVIDER_PLUGIN_PROTOCOL_VERSION = CONTRACT_VERSIONS.providerPluginProtocol;
-export const GIT_SHA = process.env.AGENT_RELAY_GIT_SHA || process.env.GIT_SHA || undefined;
+export const GIT_SHA = gitShaFromEnv();
 
 export const CONTRACTS = {
   orchestratorProtocol: ORCHESTRATOR_PROTOCOL_VERSION,

package/src/workspace-probe/deps.ts

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, sy
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import type { WorkspaceDepsProvision, WorkspaceDepsRefreshDir, WorkspaceDepsRefreshResult, WorkspaceSymlinkProvision } from "agent-relay-sdk";
 import { errMessage } from "agent-relay-sdk";
+import { workspaceDepsMode } from "../config";
 
 const NODE_MODULES_SCAN_DEPTH = 2;
 
@@ -220,7 +221,7 @@ function isSymlink(p: string): boolean {
  * `checkOnly` reports staleness without installing. Never throws.
  */
 export function refreshWorkspaceDeps(repoRoot: string, worktreePath: string, opts: { checkOnly?: boolean } = {}): WorkspaceDepsRefreshResult {
-  const requested = (process.env.AGENT_RELAY_WORKSPACE_DEPS || "symlink").toLowerCase();
+  const requested = workspaceDepsMode();
   if (requested === "none") return { refreshed: false, dirs: [], error: "deps provisioning disabled (AGENT_RELAY_WORKSPACE_DEPS=none)" };
 
   try {
@@ -284,7 +285,7 @@ export function refreshWorkspaceDeps(repoRoot: string, worktreePath: string, opt
  * Never throws — provisioning failure must not block the spawn.
  */
 export function provisionWorkspaceDeps(repoRoot: string, worktreePath: string): WorkspaceDepsProvision {
-  const requested = (process.env.AGENT_RELAY_WORKSPACE_DEPS || "symlink").toLowerCase();
+  const requested = workspaceDepsMode();
   if (requested === "none") return { mode: "none" };
 
   try {

package/src/workspace-probe/merge.ts

@@ -8,6 +8,7 @@ import { populateMergeState, resolveBranchRef, syncBaseFromOrigin, upstreamRef,
 import { nextBranchName } from "./names";
 import { parseWorktrees, shortBranch } from "./parse";
 import type { WorkspaceMergeInput } from "./types";
+import { workspacePushEnabled } from "../config";
 
 /** Behind-count of HEAD relative to `base`, from inside `worktreePath`. */
 function countBehind(worktreePath: string, base: string): number {
@@ -403,7 +404,7 @@ function mergeRebaseFf(
   const upstream = upstreamRef(worktreePath, base);
   const slash = upstream ? upstream.indexOf("/") : -1;
   const remote = slash > 0 ? upstream!.slice(0, slash) : undefined; // remote of a `remote/branch` upstream
-  const pushEnabled = input.push !== false && process.env.AGENT_RELAY_WORKSPACE_PUSH !== "0" && Boolean(remote);
+  const pushEnabled = input.push !== false && workspacePushEnabled() && Boolean(remote);
   if (upstream && remote && pushEnabled) {
     git(["fetch", remote, base], worktreePath); // best-effort freshness; a stale ref can only under-detect divergence
     if (!git(["merge-base", "--is-ancestor", upstream, base], worktreePath).ok) {