agent-relay-server 0.32.3 → 0.33.0

package/src/agent-lifecycle-events.ts

@@ -0,0 +1,137 @@
+import { emitRelayEvent } from "./events";
+import { getNotificationsConfig } from "./config-store";
+import { notifySystemMessage } from "./notify";
+import { getAgent } from "./db";
+import type { AgentCard } from "./types";
+
+// #308/#239 — async spawn lifecycle signals. A spawn-capable agent fires a spawn, gets its
+// spawnRequestId back immediately, and is WOKEN on ready/exit/failure instead of burning its
+// turn block-polling `waitForRegistrationMs`. Mirrors src/branch-landed.ts: always emit the
+// durable event onto the bus; gate only the agent-facing push (it wakes the recipient).
+
+// Spawned children that have fired `agent.ready` during this relay lifetime. Serves two jobs:
+// (1) dedup the ready push — it must fire exactly once per child, not on every heartbeat
+// re-registration; and (2) classify a later offline transition: a child IN this set exited
+// cleanly (`agent.exited`); one that never entered it went offline without ever becoming ready,
+// i.e. a spawn that failed to come up (`agent.spawn_failed` — the "process started ≠ ready"
+// crash-loop / onboarding-gate mode the isolated-Claude failure proves). In-memory by design: a
+// child still alive across a relay restart was ready long ago and its parent already knows, so a
+// post-restart exit reads as the benign `agent.exited` default — a restart must never manufacture
+// a spurious failure alert.
+const readyFired = new Set<string>();
+
+function describe(child: AgentCard): string {
+  return child.label ? `${child.label} (\`${child.id}\`)` : `\`${child.id}\``;
+}
+
+function providerOf(child: AgentCard): string | undefined {
+  const p = child.meta?.provider;
+  return typeof p === "string" ? p : undefined;
+}
+
+function spawnRequestIdOf(child: AgentCard): string | undefined {
+  const s = child.meta?.spawnRequestId;
+  return typeof s === "string" ? s : undefined;
+}
+
+/**
+ * A spawned child became genuinely ready (registered AND past onboarding — ready+idle, not merely
+ * process-started). Emits the durable `agent.ready` event and, unless suppressed, pushes the
+ * `spawned_by` parent a one-shot notice so it can stop block-polling. No-op for non-spawned agents
+ * and for a child whose ready was already announced (reconnect / heartbeat re-registration).
+ */
+export function notifyAgentReady(childId: string): void {
+  const child = getAgent(childId);
+  const parent = child?.spawnedBy;
+  if (!child || !parent) return;
+  if (readyFired.has(childId)) return;
+  readyFired.add(childId);
+
+  emitRelayEvent({
+    type: "agent.ready",
+    source: "server",
+    subject: childId,
+    data: { agentId: childId, parent, provider: providerOf(child), label: child.label, spawnRequestId: spawnRequestIdOf(child) },
+  });
+
+  const config = getNotificationsConfig();
+  if (!config.enabled || !config.agentReady) return;
+  notifySystemMessage(parent, {
+    subject: "Spawned agent ready",
+    body: `✅ Your spawned agent ${describe(child)} is ready and idle — send it work with relay_send_message to \`${childId}\`.`,
+    payload: { kind: "agent.ready", agentId: childId, parent, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child) },
+    replyExpected: false,
+  });
+}
+
+/**
+ * A spawned child went offline (heartbeat-reaped, or shut down). Classifies via `readyFired`: a
+ * child that had become ready exited (`agent.exited`); one that never did failed to come up
+ * (`agent.spawn_failed`). Routes to the `spawned_by` parent. No-op for non-spawned agents.
+ * `reason` is the offline cause (e.g. "heartbeat lost", "shutdown").
+ */
+export function notifyAgentOffline(childId: string, reason: string): void {
+  const child = getAgent(childId);
+  const parent = child?.spawnedBy;
+  if (!child || !parent) return;
+  const wasReady = readyFired.delete(childId);
+  const config = getNotificationsConfig();
+
+  if (wasReady) {
+    emitRelayEvent({
+      type: "agent.exited",
+      source: "server",
+      subject: childId,
+      data: { agentId: childId, parent, reason, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child) },
+    });
+    if (!config.enabled || !config.agentExited) return;
+    notifySystemMessage(parent, {
+      subject: "Spawned agent exited",
+      body: `⏹ Your spawned agent ${describe(child)} exited — ${reason}.`,
+      payload: { kind: "agent.exited", agentId: childId, parent, reason },
+      replyExpected: false,
+    });
+    return;
+  }
+
+  emitRelayEvent({
+    type: "agent.spawn_failed",
+    source: "server",
+    subject: childId,
+    data: { agentId: childId, parent, reason, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child), neverReady: true },
+  });
+  if (!config.enabled || !config.agentSpawnFailed) return;
+  notifySystemMessage(parent, {
+    subject: "Spawn failed",
+    body: `❌ Your spawned agent ${describe(child)} went offline before ever becoming ready — ${reason}. Likely a crash-loop, onboarding gate, or bad launch; call relay_spawn_targets to re-check provider availability before retrying.`,
+    payload: { kind: "agent.spawn_failed", agentId: childId, parent, reason },
+    replyExpected: false,
+  });
+}
+
+/**
+ * A spawn COMMAND failed outright — the orchestrator reported the `agent.spawn` command failed
+ * (provider unavailable, bad cwd, launch error) before any child agent registered. Routes directly
+ * to the spawning parent threaded on the command, since there is no child agent record to resolve.
+ */
+export function notifyAgentSpawnFailed(input: { parent: string; spawnRequestId?: string; provider?: string; reason: string }): void {
+  emitRelayEvent({
+    type: "agent.spawn_failed",
+    source: "server",
+    subject: input.spawnRequestId ?? input.parent,
+    data: { parent: input.parent, spawnRequestId: input.spawnRequestId, provider: input.provider, reason: input.reason },
+  });
+  const config = getNotificationsConfig();
+  if (!config.enabled || !config.agentSpawnFailed) return;
+  notifySystemMessage(input.parent, {
+    subject: "Spawn failed",
+    body: `❌ Your spawn request${input.spawnRequestId ? ` \`${input.spawnRequestId}\`` : ""} failed — ${input.reason}. Call relay_spawn_targets to check live provider/host availability before retrying.`,
+    payload: { kind: "agent.spawn_failed", parent: input.parent, spawnRequestId: input.spawnRequestId, provider: input.provider, reason: input.reason },
+    replyExpected: false,
+  });
+}
+
+/** Test seam: clear the in-memory ready-tracking set between tests. */
+export function __resetReadyTracking(): void {
+  readyFired.clear();
+}

package/src/artifact-storage.ts

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { createReadStream, existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { Readable } from "node:stream";
+import { expandTilde } from "./utils";
 
 interface ArtifactStorageBackend {
   readonly scheme: string;
@@ -19,10 +20,7 @@ interface ArtifactStorageBackend {
 const DEFAULT_MAX_ARTIFACT_BYTES = 50 * 1024 * 1024;
 
 function artifactRoot(): string {
-  const configured = process.env.AGENT_RELAY_ARTIFACTS_DIR || "~/.agent-relay/artifacts";
-  if (configured === "~") return homedir();
-  if (configured.startsWith("~/")) return join(homedir(), configured.slice(2));
-  return configured;
+  return expandTilde(process.env.AGENT_RELAY_ARTIFACTS_DIR || "~/.agent-relay/artifacts");
 }
 
 export function maxArtifactBytes(): number {

package/src/branch-landed.ts

@@ -1,9 +1,9 @@
 import { emitRelayEvent } from "./events";
 import { getNotificationsConfig } from "./config-store";
 import { notifySystemMessage } from "./notify";
-import { listAgents } from "./db";
+import { createActivityEvent, listAgents, updateWorkspaceStatus } from "./db";
 import { isAgentOnline } from "./agent-ref";
-import type { AgentCard, WorkspaceRecord } from "./types";
+import type { AgentCard, WorkspaceMergePreview, WorkspaceRecord } from "./types";
 
 export interface BranchLandedInput {
   /**
@@ -113,6 +113,42 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
   }
 }
 
+/**
+ * Finalize a workspace whose work landed in base out-of-band — a pr-strategy land whose
+ * PR merged (by anyone, incl. `gh pr merge`), or a squash/cherry-pick already in base
+ * (#304). Marks it terminal `merged`, records the merge SHA, and fires the same
+ * branch.landed push the local land path emits — a pr land never runs through the
+ * workspace.merge result handler, so without this the author never learns it shipped.
+ * Lives here (not maintenance.ts) so the giant doesn't grow and land-notify has one home.
+ */
+export function reconcileLandedWorkspace(ws: WorkspaceRecord, preview: WorkspaceMergePreview): void {
+  const sha = typeof preview.prMergeSha === "string" ? preview.prMergeSha : undefined;
+  const via = preview.prMerged === true ? "pr" : "git";
+  updateWorkspaceStatus(ws.id, "merged", {
+    autoMerged: true,
+    mergedFromStatus: ws.status,
+    landedDetectedAt: Date.now(),
+    landedVia: via,
+    ...(sha ? { landedSha: sha } : {}),
+    autoConflict: false,
+  });
+  createActivityEvent({
+    clientId: "server-workspace-" + ws.id + "-merged-" + Date.now(),
+    kind: "state",
+    title: "Workspace work landed in base",
+    body: `${ws.branch ?? ws.id} is ${via === "pr" ? "merged on the remote (PR)" : "already merged into base"} ${preview.baseRef ? `(${preview.baseRef})` : ""} — marking merged`,
+    meta: ws.branch ?? ws.id,
+    icon: "ti-git-merge",
+    view: "orchestrators",
+    metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, fromStatus: ws.status, ...(sha ? { landedSha: sha } : {}) },
+  });
+  try {
+    notifyBranchLanded({ workspace: ws, mergedSha: sha, pushed: true });
+  } catch {
+    // Notification is best-effort; the merged status + activity event still stand.
+  }
+}
+
 // An agent is "on `main`" when its registered cwd equals the repo's main checkout — i.e. it
 // works in the base, not an isolated worktree. Excludes the author, pseudo agents (system/
 // user), channels, and offline sessions.

package/src/cli/_shared.ts

@@ -0,0 +1,80 @@
+// Shared CLI infrastructure — auto-split from cli.ts (#294). Generic helpers used
+// across the command modules: relay HTTP, confirmation prompt, stdin read, and
+// small string utilities. Keep this dependency-free of the command modules so the
+// import graph stays acyclic (command modules import from here, never the reverse).
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+
+export async function apiRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+  const headers: Record<string, string> = {};
+  const token = process.env.AGENT_RELAY_TOKEN;
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+  const response = await fetch(new URL(path, baseUrl), {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  const payload = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const message = payload && typeof payload === "object" && "error" in payload ? String((payload as any).error) : text;
+    throw new Error(`agent-relay ${method} ${path} failed (${response.status}): ${message}`);
+  }
+  return payload;
+}
+
+export async function apiRawRequest(method: string, path: string, body: BodyInit, extraHeaders: Record<string, string> = {}): Promise<unknown> {
+  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+  const headers: Record<string, string> = { ...extraHeaders };
+  const token = process.env.AGENT_RELAY_TOKEN;
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
+  const response = await fetch(new URL(path, baseUrl), { method, headers, body });
+  const text = await response.text();
+  const payload = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const message = payload && typeof payload === "object" && "error" in payload ? String((payload as any).error) : text;
+    throw new Error(`agent-relay ${method} ${path} failed (${response.status}): ${message}`);
+  }
+  return payload;
+}
+
+export async function readStdin(): Promise<string> {
+  if (typeof Bun !== "undefined" && Bun.stdin && typeof Bun.stdin.text === "function") {
+    return Bun.stdin.text();
+  }
+
+  let value = "";
+  for await (const chunk of process.stdin) value += String(chunk);
+  return value;
+}
+
+export function splitTagArgs(raw: string): string[] {
+  return raw.split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+export function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+
+export function encodedLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+export function truncateText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, maxChars)}\n\n[truncated preview; full content is attached]`;
+}
+
+export async function confirm(message: string): Promise<boolean> {
+  if (!input.isTTY) return false;
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(`${message} [y/N] `);
+    return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
+  } finally {
+    rl.close();
+  }
+}

package/src/cli/agent-detect.ts

@@ -0,0 +1,188 @@
+// Agent-id detection — auto-split from cli.ts (#294). Resolves "who am I in the
+// relay" from env, on-disk context/codex state files, the Claude instance marker,
+// or a unique cwd-matched online agent. Shared by every command that needs the
+// caller's agent id (pair, message, reply, react, status, label, tags, workspace).
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { apiRequest, uniqueStrings } from "./_shared";
+
+export async function detectActivePairId(agentId: string): Promise<string | undefined> {
+  const pairs = await apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}&status=active`) as Array<{ id?: string }>;
+  return Array.isArray(pairs) && typeof pairs[0]?.id === "string" ? pairs[0].id : undefined;
+}
+
+export async function detectAgentId(): Promise<string | undefined> {
+  const explicit = process.env.AGENT_RELAY_ID;
+  if (explicit) return explicit;
+
+  const contextMatch = currentAgentContextId();
+  if (contextMatch) return contextMatch;
+
+  const cwd = process.cwd();
+  const explicitCodexState = process.env.AGENT_RELAY_CODEX_STATE_PATH
+    ? readCodexState(process.env.AGENT_RELAY_CODEX_STATE_PATH)
+    : null;
+  if (explicitCodexState?.agentId) return explicitCodexState.agentId;
+
+  const stateCandidates = [
+    resolve(cwd, "codex/runtime/live-state.json"),
+    ...collectCodexStateFiles(),
+  ].filter((path): path is string => Boolean(path));
+
+  const codexMatch = newestCodexAgentId(stateCandidates, cwd);
+  if (codexMatch) return codexMatch;
+
+  const claudeMatch = currentClaudeAgentId();
+  if (claudeMatch) return claudeMatch;
+
+  try {
+    const agents = await apiRequest("GET", "/api/agents") as Array<{ id?: string; status?: string; ready?: boolean; meta?: { cwd?: unknown }; lastSeen?: number }>;
+    const cwdAgents = agents
+      .filter((agent) => agent.status !== "offline" && agent.ready !== false && agent.meta?.cwd === cwd && typeof agent.id === "string")
+      .sort((a, b) => (b.lastSeen ?? 0) - (a.lastSeen ?? 0));
+    const uniqueAgentIds = uniqueStrings(cwdAgents.map((agent) => agent.id!));
+    return uniqueAgentIds.length === 1 ? uniqueAgentIds[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function currentAgentContextId(): string | undefined {
+  const explicitPath = process.env.AGENT_RELAY_CONTEXT_PATH;
+  if (explicitPath) {
+    const explicit = readAgentContext(explicitPath);
+    if (explicit?.agentId && contextMatchesCurrentProcess(explicit)) return explicit.agentId;
+  }
+
+  const candidates = collectAgentContextFiles();
+  const matches = candidates
+    .map((path) => readAgentContext(path))
+    .filter((context): context is AgentContextState => Boolean(context))
+    .filter((context) => contextMatchesCurrentProcess(context))
+    .filter((context) => context.matchEnv.some((match) => process.env[match.name] === match.value))
+    .sort((a, b) => b.updatedAtMs - a.updatedAtMs);
+
+  const uniqueAgentIds = uniqueStrings(matches.map((context) => context.agentId));
+  return uniqueAgentIds.length === 1 ? uniqueAgentIds[0] : undefined;
+}
+
+interface AgentContextState {
+  agentId: string;
+  cwd?: string;
+  updatedAtMs: number;
+  matchEnv: Array<{ name: string; value: string }>;
+}
+
+function contextMatchesCurrentProcess(context: AgentContextState): boolean {
+  return !context.cwd || context.cwd === process.cwd();
+}
+
+function readAgentContext(path: string): AgentContextState | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as {
+      agentId?: unknown;
+      cwd?: unknown;
+      updatedAt?: unknown;
+      matchEnv?: unknown;
+    };
+    if (typeof parsed.agentId !== "string" || !parsed.agentId) return null;
+    const matchEnv = Array.isArray(parsed.matchEnv)
+      ? parsed.matchEnv.flatMap((item) => {
+        if (!item || typeof item !== "object") return [];
+        const record = item as { name?: unknown; value?: unknown };
+        return typeof record.name === "string" && typeof record.value === "string"
+          ? [{ name: record.name, value: record.value }]
+          : [];
+      })
+      : [];
+    const stat = statSync(path);
+    const updatedAt = typeof parsed.updatedAt === "string" ? Date.parse(parsed.updatedAt) : Number.NaN;
+    return {
+      agentId: parsed.agentId,
+      cwd: typeof parsed.cwd === "string" ? parsed.cwd : undefined,
+      matchEnv,
+      updatedAtMs: Number.isFinite(updatedAt) ? updatedAt : stat.mtimeMs,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function collectAgentContextFiles(): string[] {
+  const roots = [
+    join(process.env.HOME || "", ".agent-relay", "contexts"),
+  ].filter((root) => root && existsSync(root));
+  const files: string[] = [];
+  for (const root of roots) collectFiles(root, ".json", files, 2);
+  return files;
+}
+
+function newestCodexAgentId(paths: string[], cwd: string): string | undefined {
+  const states = paths
+    .map((path) => readCodexState(path))
+    .filter((state): state is { agentId: string; cwd?: string; updatedAtMs: number } => Boolean(state))
+    .sort((a, b) => b.updatedAtMs - a.updatedAtMs);
+  const cwdAgentIds = uniqueStrings(states.filter((state) => state.cwd === cwd).map((state) => state.agentId));
+  return cwdAgentIds.length === 1 ? cwdAgentIds[0] : undefined;
+}
+
+function readCodexState(path: string): { agentId: string; cwd?: string; updatedAtMs: number } | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as { agentId?: unknown; cwd?: unknown; updatedAt?: unknown };
+    if (typeof parsed.agentId !== "string" || !parsed.agentId) return null;
+    const stat = statSync(path);
+    const updatedAt = typeof parsed.updatedAt === "string" ? Date.parse(parsed.updatedAt) : Number.NaN;
+    return {
+      agentId: parsed.agentId,
+      cwd: typeof parsed.cwd === "string" ? parsed.cwd : undefined,
+      updatedAtMs: Number.isFinite(updatedAt) ? updatedAt : stat.mtimeMs,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function collectCodexStateFiles(): string[] {
+  const roots = [
+    join(process.env.HOME || "", ".agent-relay", "codex", "runtime"),
+    resolve(process.cwd(), "codex", "runtime"),
+  ].filter((root) => root && existsSync(root));
+  const files: string[] = [];
+  for (const root of roots) collectFiles(root, "live-state.json", files, 4);
+  return files;
+}
+
+function collectFiles(dir: string, name: string, output: string[], depth: number): void {
+  if (depth < 0) return;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry);
+    try {
+      const stat = statSync(path);
+      if (stat.isDirectory()) collectFiles(path, name, output, depth - 1);
+      else if (name.startsWith(".") ? entry.endsWith(name) : entry === name) output.push(path);
+    } catch {
+      // Ignore state files that disappear while scanning.
+    }
+  }
+}
+
+function currentClaudeAgentId(): string | undefined {
+  const sessionKey = process.env.CLAUDE_CODE_SESSION_ID || String(process.ppid || "");
+  if (!sessionKey) return undefined;
+  const safeSessionKey = sessionKey.replace(/[^A-Za-z0-9_.:-]/g, "_");
+  const statePath = join("/tmp", `agent-relay-instance-${safeSessionKey}.state`);
+  if (!existsSync(statePath)) return undefined;
+  try {
+    return readFileSync(statePath, "utf8").split(/\r?\n/)[0]?.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/cli/agent-meta.ts

@@ -0,0 +1,95 @@
+// Agent-metadata commands — auto-split from cli.ts (#294). Small handlers that
+// read/update the caller's own agent record: status, label, tags.
+import { apiRequest, splitTagArgs, uniqueStrings } from "./_shared";
+import { detectAgentId } from "./agent-detect";
+
+export async function handleStatusCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown status option "${arg}"`);
+  }
+
+  const [stats, health, pairs, agent] = await Promise.all([
+    apiRequest("GET", "/api/stats"),
+    apiRequest("GET", "/api/health"),
+    agentId ? apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}`) : Promise.resolve([]),
+    agentId ? apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`).catch(() => null) : Promise.resolve(null),
+  ]);
+  const payload = { agent, stats, health, pairs };
+  if (json) console.log(JSON.stringify(payload, null, 2));
+  else console.log(formatStatus(payload));
+}
+
+export async function handleLabelCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let label: string | null | undefined;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--clear") label = null;
+    else if (arg === "--json") json = true;
+    else if (label === undefined) label = args.slice(i).join(" ");
+  }
+  if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
+  if (label === undefined) {
+    const agent = await apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`) as { label?: string };
+    console.log(agent.label ?? "(no label)");
+    return;
+  }
+  const result = await apiRequest("PATCH", `/api/agents/${encodeURIComponent(agentId)}/label`, { label });
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else console.log(label ? `Label set: ${label}` : "Label cleared.");
+}
+
+export async function handleTagsCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let json = false;
+  let listOnly = false;
+  let add: string[] = [];
+  let remove: string[] = [];
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--json") json = true;
+    else if (arg === "--list") listOnly = true;
+    else if (arg === "--add" && i + 1 < args.length) add = add.concat(splitTagArgs(args[++i]!));
+    else if (arg === "--remove" && i + 1 < args.length) remove = remove.concat(splitTagArgs(args[++i]!));
+    else positional.push(...splitTagArgs(arg!));
+  }
+  if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
+  const current = await apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`) as { tags?: string[] };
+  if (listOnly || (positional.length === 0 && add.length === 0 && remove.length === 0)) {
+    console.log((current.tags ?? []).join(", ") || "(no tags)");
+    return;
+  }
+  const next = positional.length > 0
+    ? uniqueStrings(positional)
+    : uniqueStrings([...(current.tags ?? []), ...add]).filter((tag) => !remove.includes(tag));
+  const updated = await apiRequest("PATCH", `/api/agents/${encodeURIComponent(agentId)}/tags`, { tags: next });
+  if (json) console.log(JSON.stringify(updated, null, 2));
+  else console.log(`Tags: ${next.join(", ") || "(none)"}`);
+}
+
+function formatStatus(payload: any): string {
+  const agent = payload.agent;
+  const stats = payload.stats ?? {};
+  const health = payload.health ?? {};
+  const pairs = Array.isArray(payload.pairs) ? payload.pairs : [];
+  const activePair = pairs.find((pair: any) => pair.status === "active") ?? pairs.find((pair: any) => pair.status === "pending");
+  return [
+    `Relay: ${health.status ?? "unknown"}  version=${stats.version ?? "unknown"}`,
+    `Agents: ${stats.online ?? "?"}/${stats.agents ?? "?"} online  Messages: ${stats.messages ?? "?"}  Tasks: ${stats.openTasks ?? "?"}/${stats.tasks ?? "?"} open`,
+    agent
+      ? `Current: ${agent.id}  status=${agent.status}  ready=${agent.ready ? "yes" : "no"}  label=${agent.label ?? "(none)"}  tags=${(agent.tags ?? []).join(", ") || "(none)"}`
+      : "Current: unknown",
+    activePair
+      ? `Pair: ${activePair.id}  ${activePair.status}  ${activePair.requesterId} <-> ${activePair.targetId}`
+      : "Pair: none active",
+  ].join("\n");
+}

package/src/cli/context-probe.ts

@@ -0,0 +1,88 @@
+// Context-probe command — auto-split from cli.ts (#294). Wraps a status-line
+// command (e.g. ccstatusline) so the relay can observe context usage, or emits the
+// status-line invocation for the provider settings.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runContextProbe } from "agent-relay-sdk/context-probe";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
+import { readStdin } from "./_shared";
+
+export async function handleContextProbeCommand(args: string[]): Promise<void> {
+  const printStatusLine = args[0] === "print-status-line";
+  const inputArgs = printStatusLine ? args.slice(1) : args;
+  let wrapCommand: string | undefined;
+  let wrapRequested = false;
+  let agentId: string | undefined;
+  let stateDir: string | undefined;
+  let standalone = false;
+
+  for (let i = 0; i < inputArgs.length; i++) {
+    const arg = inputArgs[i];
+    if (arg === "--wrap") {
+      wrapRequested = true;
+      const next = inputArgs[i + 1];
+      if (next && !next.startsWith("--")) {
+        wrapCommand = next;
+        i++;
+      }
+    } else if (arg === "--agent-id") {
+      agentId = inputArgs[++i];
+    } else if (arg === "--state-dir") {
+      stateDir = inputArgs[++i] ?? stateDir;
+    } else if (arg === "--standalone") {
+      standalone = true;
+    } else if (arg === "--help" || arg === "-h") {
+      console.log("Usage: agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]");
+      return;
+    } else {
+      throw new Error(`Unknown context-probe option "${arg}"`);
+    }
+  }
+
+  if (printStatusLine) {
+    const command = [
+      "agent-relay",
+      "context-probe",
+      ...(wrapRequested ? ["--wrap", ...(wrapCommand ? [shellQuote(wrapCommand)] : [])] : ["--standalone"]),
+      ...(agentId ? ["--agent-id", shellQuote(agentId)] : []),
+      ...(stateDir ? ["--state-dir", shellQuote(stateDir)] : []),
+    ].join(" ");
+    console.log(command);
+    return;
+  }
+
+  if (wrapRequested && !wrapCommand) wrapCommand = currentClaudeStatusLineCommand();
+  if (wrapCommand && commandLooksLikeContextProbe(wrapCommand)) {
+    wrapCommand = undefined;
+    standalone = true;
+  }
+  if (!wrapRequested && !standalone) {
+    throw new Error("Usage: agent-relay context-probe [--wrap COMMAND|--standalone] [--agent-id ID] [--state-dir DIR]");
+  }
+
+  const input = await readStdin();
+  const result = runContextProbe(input, { wrapCommand, agentId, stateDir, standalone });
+  if (result.wrappedStderr) process.stderr.write(result.wrappedStderr);
+  if (result.output) process.stdout.write(result.output);
+  if (result.output && !result.output.endsWith("\n")) process.stdout.write("\n");
+  if (typeof result.wrappedExitCode === "number" && result.wrappedExitCode !== 0) process.exit(result.wrappedExitCode);
+}
+
+function currentClaudeStatusLineCommand(): string | undefined {
+  const settingsPath = join(process.env.HOME || homedir(), ".claude", "settings.json");
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf8")) as unknown;
+    if (!settings || typeof settings !== "object" || Array.isArray(settings)) return undefined;
+    const statusLine = (settings as Record<string, unknown>).statusLine;
+    if (!statusLine || typeof statusLine !== "object" || Array.isArray(statusLine)) return undefined;
+    const command = (statusLine as Record<string, unknown>).command;
+    return typeof command === "string" && command.trim() ? command : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function commandLooksLikeContextProbe(command: string): boolean {
+  return /\bagent-relay\s+context-probe\b/.test(command);
+}