agent-relay-sdk 0.2.8 → 0.2.10

package/src/bus-client.ts

@@ -10,6 +10,7 @@ import {
 } from "./protocol.js";
 import { ReconnectionManager } from "./reconnect.js";
 import type { ContextState, ProviderCapabilities } from "./types.js";
+import { isRecord } from "./types.js";
 
 export interface CursorStore {
   load(): Promise<number | null>;
@@ -503,7 +504,3 @@ export class RelayBusClient extends EventEmitter {
     return Object.keys(meta).length ? meta : undefined;
   }
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}

package/src/context-probe.ts

@@ -3,6 +3,8 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import type { ContextProbeMetrics } from "./types.js";
+import { sanitizeFsName } from "./fs-name.js";
+import { isRecord, stringValue } from "./types.js";
 
 export interface ContextProbeOptions {
   wrapCommand?: string;
@@ -208,7 +210,7 @@ function formatTokens(tokens: number): string {
 }
 
 function safeStateId(agentId: string): string {
-  return basename(agentId).replace(/[^a-zA-Z0-9._-]/g, "-") || "unknown";
+  return sanitizeFsName(basename(agentId), { replacement: "-", collapse: false, fallback: "unknown" });
 }
 
 function envAgentId(env: Record<string, string | undefined> | undefined): string | undefined {
@@ -225,10 +227,6 @@ function numberValue(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value ? value : undefined;
-}
-
 function sumNumbers(...values: unknown[]): number | undefined {
   let total = 0;
   let seen = false;
@@ -251,7 +249,3 @@ function isContextProbeMetrics(value: unknown): value is ContextProbeMetrics {
     typeof value.contextPercent === "number" &&
     typeof value.timestamp === "number";
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/contracts.ts

@@ -1,5 +1,9 @@
 import type { ContractCompatibility, ContractCompatibilityIssue, RuntimeContractName, RuntimeContracts } from "./types.js";
 
+/** HTTP header carrying an Agent Relay token. Single source of truth — import this
+ * instead of hand-writing the literal (duplication ratchet, docs/dry-audit.md). */
+export const RELAY_TOKEN_HEADER = "X-Agent-Relay-Token";
+
 export const CONTRACT_VERSIONS = {
   relayApi: 1,
   orchestratorProtocol: 3,

package/src/fs-name.ts

@@ -0,0 +1,47 @@
+// Filesystem-name sanitizer shared by the runner and orchestrator. Replaces a
+// pile of near-identical `safe*`/`sanitize*` helpers whose subtle differences
+// (replacement char, run-collapsing, edge-trimming, length cap, empty fallback)
+// are now explicit options. Crucially this single home guarantees the runner's
+// session-mirror log filename and the orchestrator's reader resolve to the SAME
+// string — previously kept in sync by hand-copied comments.
+//
+// Allowed characters (everything else is replaced): a-z A-Z 0-9 . _ -
+
+export interface SanitizeFsNameOptions {
+  /** Truncate the result to this many chars. Omit for no truncation. */
+  maxLen?: number;
+  /** Character substituted for disallowed input. Default "_". */
+  replacement?: string;
+  /** Collapse a run of disallowed chars into one replacement. Default true. */
+  collapse?: boolean;
+  /** Also collapse runs of the replacement char itself (incl. pre-existing). Default false. */
+  collapseReplacement?: boolean;
+  /** Trim surrounding whitespace before sanitizing. Default false. */
+  trimWhitespace?: boolean;
+  /** Strip leading/trailing replacement chars from the result. Default false. */
+  trimEdge?: boolean;
+  /** Lowercase the result — for tmux/session labels. Default false. */
+  lowercase?: boolean;
+  /** Returned when the sanitized result is empty. Default "". */
+  fallback?: string;
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+}
+
+export function sanitizeFsName(value: string, opts: SanitizeFsNameOptions = {}): string {
+  const repl = opts.replacement ?? "_";
+  let s = opts.trimWhitespace ? value.trim() : value;
+  s = s.replace(opts.collapse === false ? /[^a-zA-Z0-9._-]/g : /[^a-zA-Z0-9._-]+/g, repl);
+  if (opts.collapseReplacement) {
+    s = s.replace(new RegExp(`${escapeRe(repl)}+`, "g"), repl);
+  }
+  if (opts.trimEdge) {
+    const e = escapeRe(repl);
+    s = s.replace(new RegExp(`^(?:${e})+|(?:${e})+$`, "g"), "");
+  }
+  if (opts.lowercase) s = s.toLowerCase();
+  if (opts.maxLen !== undefined) s = s.slice(0, opts.maxLen);
+  return s || opts.fallback || "";
+}

package/src/http-client.ts

@@ -1,4 +1,5 @@
 import type { AgentCard, Artifact, ArtifactKind, ArtifactSensitivity, PollQuery, RegisterAgentInput, SendMessageInput, Message, MessageDeliveryState, MessageDeliveryStatus, ReplyObligation, Task, TaskStatusInput } from "./types.js";
+import { RELAY_TOKEN_HEADER } from "./contracts.js";
 
 export interface HttpClientOptions {
   baseUrl: string;
@@ -322,7 +323,7 @@ export class RelayHttpClient {
 
   private headers(base: Record<string, string> = {}): Record<string, string> {
     const token = this.token ?? process.env.AGENT_RELAY_TOKEN;
-    return token ? { ...base, "X-Agent-Relay-Token": token } : base;
+    return token ? { ...base, [RELAY_TOKEN_HEADER]: token } : base;
   }
 
   private url(path: string): URL {

package/src/index.ts

@@ -8,3 +8,7 @@ export * from "./bus-client.js";
 export * from "./provider-base.js";
 export * from "./claim-tracker.js";
 export * from "./context-probe.js";
+export * from "./process-utils.js";
+export * from "./shell-utils.js";
+export * from "./tmux-utils.js";
+export * from "./fs-name.js";

package/src/process-utils.ts

@@ -0,0 +1,54 @@
+import { readFileSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+
+// Process-liveness primitives shared by the runner and orchestrator. A zombie
+// process still has a PID-table entry, so kill(pid, 0) succeeds even though it
+// is dead and unreapable — we never wait() our spawned children, so they linger
+// as zombies. isPidAlive treats them as not-alive (Linux-only via /proc).
+//
+// Kept Node-portable (no Bun-only APIs) so agent-relay-client can use it too.
+
+/** Parse a /proc/<pid>/status blob; true iff the process State is `Z` (zombie). */
+export function parseProcStateIsZombie(statusText: string): boolean {
+  const match = statusText.match(/^State:\s+(\w)/m);
+  return match?.[1] === "Z";
+}
+
+/** True iff <pid> exists and its /proc state is zombie. Non-Linux → false. */
+export function isZombie(pid: number): boolean {
+  try {
+    return parseProcStateIsZombie(readFileSync(`/proc/${pid}/status`, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/** True iff <pid> is alive AND not a zombie. */
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  return !isZombie(pid);
+}
+
+/** Send <signal> to <pid>, swallowing ESRCH/EPERM. */
+export function killPid(pid: number, signal: "SIGTERM" | "SIGKILL"): void {
+  try {
+    process.kill(pid, signal);
+  } catch {}
+}
+
+/**
+ * Poll until every pid in <pids> has exited (zombie-aware), or <timeoutMs>
+ * elapses. Returns true if all exited within the window.
+ */
+export async function waitForPidsExit(pids: number[], timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!pids.some(isPidAlive)) return true;
+    await delay(100);
+  }
+  return !pids.some(isPidAlive);
+}

package/src/protocol.ts

@@ -1,3 +1,5 @@
+import { isRecord } from "./types.js";
+
 export interface BusFrame {
   type: string;
   id?: string;
@@ -290,7 +292,3 @@ function invalidPayload(field: string): BusProtocolError {
 function isRole(value: unknown): value is BusRole {
   return value === "provider" || value === "channel" || value === "orchestrator" || value === "integration";
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}

package/src/provider-catalog.ts

@@ -1,6 +1,11 @@
 import type { SpawnProvider } from "./types.js";
 
-export type ProviderEffort = "low" | "medium" | "high" | "xhigh" | "max";
+/** Valid reasoning-effort levels — runtime tuple is the single source of truth. */
+export const VALID_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type ProviderEffort = (typeof VALID_EFFORTS)[number];
+export function isProviderEffort(value: unknown): value is ProviderEffort {
+  return typeof value === "string" && (VALID_EFFORTS as readonly string[]).includes(value);
+}
 export type ProviderCatalogValueSource = "catalog" | "provider" | "runtime" | "override";
 export type ProviderCatalogConfidence = "declared" | "verified" | "estimated" | "unknown";
 

package/src/shell-utils.ts

@@ -0,0 +1,28 @@
+// POSIX shell argument quoting, shared by the server, runner, and orchestrator.
+//
+// Two variants, because the callers genuinely want two behaviours — the
+// single-quote fallback (wrap in '...' and rewrite embedded ' as '\'') is the
+// canonical-safe core of both:
+//
+//   shellQuote  — ALWAYS quotes. Used when generating files (env files,
+//                 systemd/launchd units) where uniform `KEY='value'` quoting is
+//                 the convention and readability/consistency matter.
+//
+//   shellEscape — quotes ONLY when needed, returning strings built entirely
+//                 from shell-safe characters unquoted. Used for command-arg
+//                 assembly where clean tokens read better bare.
+//
+// The fast-path allowlist is the reconciled superset of the prior copies; every
+// character was audited non-special in POSIX sh, and the fallback would quote
+// correctly even if one weren't.
+const SHELL_SAFE = /^[a-zA-Z0-9_@%+=:,./-]+$/;
+
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+export function shellEscape(value: string): string {
+  if (value.length === 0) return "''";
+  if (SHELL_SAFE.test(value)) return value;
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/tmux-utils.ts

@@ -0,0 +1,18 @@
+// tmux command helpers shared by the runner and orchestrator. Both run under
+// Bun; `Bun.spawnSync` is referenced only inside tmuxHasSession's body, so the
+// module is import-safe under Node (the client never calls tmuxHasSession).
+
+/** Build a `tmux` argv, threading the optional `-L <socket>` selector. */
+export function tmuxCommand(socketName: string | undefined, ...args: string[]): string[] {
+  return socketName ? ["tmux", "-L", socketName, ...args] : ["tmux", ...args];
+}
+
+/** True iff a tmux session named `sessionName` exists on the (optional) socket. */
+export function tmuxHasSession(sessionName: string, socketName?: string): boolean {
+  const result = Bun.spawnSync(tmuxCommand(socketName, "has-session", "-t", sessionName), {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return result.exitCode === 0;
+}

package/src/types.ts

@@ -1130,10 +1130,33 @@ export interface ActivityEventInput {
 // --- Orchestrators ---
 
 export type OrchestratorStatus = "online" | "offline";
-export type SpawnProvider = "claude" | "codex";
-export type SpawnApprovalMode = "open" | "guarded" | "read-only";
+
+/** Spawn providers — the runtime tuple is the single source of truth; the type derives from it. */
+export const SPAWN_PROVIDERS = ["claude", "codex"] as const;
+export type SpawnProvider = (typeof SPAWN_PROVIDERS)[number];
+export function isSpawnProvider(value: unknown): value is SpawnProvider {
+  return typeof value === "string" && (SPAWN_PROVIDERS as readonly string[]).includes(value);
+}
+
+/** Approval modes — runtime tuple + derived type. */
+export const APPROVAL_MODES = ["open", "guarded", "read-only"] as const;
+export type SpawnApprovalMode = (typeof APPROVAL_MODES)[number];
+export function isApprovalMode(value: unknown): value is SpawnApprovalMode {
+  return typeof value === "string" && (APPROVAL_MODES as readonly string[]).includes(value);
+}
+
 export type SpawnEffort = "low" | "medium" | "high" | "xhigh" | "max";
-export type WorkspaceMode = "isolated" | "shared" | "inherit";
+
+/** Workspace modes — runtime tuple + derived type + guard. */
+export const VALID_WORKSPACE_MODES = ["isolated", "shared", "inherit"] as const;
+export type WorkspaceMode = (typeof VALID_WORKSPACE_MODES)[number];
+export function isWorkspaceMode(value: unknown): value is WorkspaceMode {
+  return typeof value === "string" && (VALID_WORKSPACE_MODES as readonly string[]).includes(value);
+}
+/** Narrow an unknown to a WorkspaceMode, or undefined if it isn't one. */
+export function normalizeWorkspaceMode(value: unknown): WorkspaceMode | undefined {
+  return isWorkspaceMode(value) ? value : undefined;
+}
 export type WorkspaceStatus = "active" | "ready" | "conflict" | "review_requested" | "merge_planned" | "merged" | "abandoned" | "cleanup_requested" | "cleaned";
 
 /** How a workspace's work is integrated back into its base branch. */
@@ -1194,6 +1217,8 @@ export interface WorkspaceGitState {
   lastCommit?: WorkspaceGitCommit;
   /** Ref/sha the ahead/behind counts were computed against. */
   baseRef?: string;
+  /** Branch currently checked out in the worktree (for recorded-vs-live mismatch). */
+  branch?: string;
   /** Set when the worktree path no longer exists on disk. */
   missing?: boolean;
   /** Populated when git interrogation failed. */
@@ -1262,12 +1287,47 @@ export interface WorkspaceMergeResult {
   mergedSha?: string;
   branchDeleted?: boolean;
   worktreeRemoved?: boolean;
+  /** Fresh branch the worktree was recycled onto after a land-and-continue merge
+   * (#206) — the relay repoints the workspace row at it. Absent for terminal lands. */
+  newBranch?: string;
+  /** True when the landed base branch was pushed to its upstream (origin). */
+  pushed?: boolean;
   /** Resulting workspace status the relay should record. */
   status: WorkspaceStatus;
+  /** Deps re-provisioned after a land-and-continue recycle when the advanced base
+   *  brought new dependencies (issue #51). Absent when nothing was stale. */
+  depsRefresh?: WorkspaceDepsRefreshResult;
   /** Populated when the merge could not complete. */
   error?: string;
 }
 
+/**
+ * Joined steward briefing for one workspace (#208): the row, owner + orchestrator
+ * liveness, live git state, recorded-vs-live branch mismatch, any active steward
+ * claim, and a recommended next action — so a steward (or release agent) doesn't
+ * reconstruct it from ad-hoc shell + API calls.
+ */
+export interface WorkspaceDiagnostics {
+  workspaceId: string;
+  status: WorkspaceStatus;
+  mode: WorkspaceMode;
+  repoRoot: string;
+  worktreePath?: string;
+  recordedBranch?: string;
+  liveBranch?: string;
+  baseRef?: string;
+  branchMismatch?: boolean;
+  owner?: { id?: string; status?: string; online: boolean };
+  orchestrator?: { id?: string; online: boolean };
+  /** Active claim that auto-merge yields to (#208), if held and unexpired. */
+  claim?: { by?: string; purpose?: string; expiresAt?: number };
+  /** Live worktree git state (proxied from the host); absent when unavailable. */
+  gitState?: WorkspaceGitState;
+  /** Why git state is absent (host offline, no worktree, …). */
+  gitStateUnavailable?: string;
+  recommendation: { action: "merge" | "rebase" | "cleanup" | "review" | "wait" | "none"; confidence: "high" | "medium" | "low"; reason: string };
+}
+
 /** One changed file in a workspace diff against its base. */
 export interface WorkspaceDiffFile {
   path: string;
@@ -1328,6 +1388,36 @@ export interface WorkspaceSymlinkProvision {
   errors?: string[];
 }
 
+/** One project dir's outcome in a workspace deps refresh (issue #51). */
+export interface WorkspaceDepsRefreshDir {
+  /** Relative dir from repo root (`.` for root, e.g. `dashboard`). */
+  dir: string;
+  /** ok — declared deps already present; stale — missing (check-only, not installed);
+   *  installed — re-installed in isolation; failed — install errored. */
+  status: "ok" | "stale" | "installed" | "failed";
+  /** Declared deps (dependencies + devDependencies) missing from node_modules, capped sample. */
+  missing?: string[];
+  /** True when the dir's node_modules was a shared symlink replaced with a real install. */
+  wasSymlink?: boolean;
+  packageManager?: string;
+  error?: string;
+}
+
+/**
+ * Outcome of refreshing an isolated worktree's deps (issue #51). The default symlink
+ * provisioning shares the source checkout's node_modules, so a dep added to the base
+ * AFTER worktree creation is missing in the worktree. Refresh promotes each stale dir
+ * to a real, isolated install — never mutating the shared source node_modules.
+ */
+export interface WorkspaceDepsRefreshResult {
+  /** True when at least one dir was actually (re)installed. */
+  refreshed: boolean;
+  /** True (check-only) when any dir is stale, or (refresh) when any install left deps missing. */
+  stale?: boolean;
+  dirs: WorkspaceDepsRefreshDir[];
+  error?: string;
+}
+
 export interface WorkspaceMetadata {
   id?: string;
   mode: WorkspaceMode;
@@ -2094,3 +2184,33 @@ export interface HealthReport {
   generatedAt: number;
   checks: HealthCheck[];
 }
+
+// --- Shared micro-helpers (single source of truth; do not re-declare per file) ---
+
+/** True for a non-null, non-array object. The canonical type guard for the whole repo. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Narrow `unknown` to a non-empty trimmed string, else `undefined`.
+ * Settled semantics: whitespace-only is treated as empty (returns `undefined`).
+ */
+export function stringValue(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/** Extract a human-readable message from any thrown value. */
+export function errMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// --- Relay connection defaults ---
+
+/** Default port the relay server listens on. */
+export const DEFAULT_RELAY_PORT = 4850;
+
+/** Default relay base URL. Loopback spelling settled on `127.0.0.1` (not `localhost`). */
+export const DEFAULT_RELAY_URL = `http://127.0.0.1:${DEFAULT_RELAY_PORT}`;