very-happy-cli 0.2.156 → 0.2.157

package/dist/{agentGuidance-C-CmV03f.cjs → agentGuidance-Db76O1kw.cjs}

@@ -2,7 +2,7 @@
 
 var z = require('zod');
 var node_crypto = require('node:crypto');
-var persistence = require('./limits-o29KXBgj.cjs');
+var persistence = require('./limits-CyuIt-Vl.cjs');
 var promises = require('node:fs/promises');
 var node_fs = require('node:fs');
 var path = require('node:path');
@@ -884,7 +884,7 @@ async function resolvePermissionRequest(sessionId, requestId, verdict, deps = {}
       `No local key for session ${sessionId} \u2014 approve/deny needs the session key from ~/.happy/sessions.json (the RPC payload is encrypted with it), so only sessions this machine's daemon spawned within 14 days can be answered from here.`
     );
   }
-  const token = await (deps.bearerToken ?? bearerToken$1)();
+  const token = await (deps.bearerToken ?? bearerToken$2)();
   const fetchState = deps.fetchAgentState ?? fetchDecryptedAgentState;
   const before = pendingRequestsOf(await fetchState(sessionId, persisted, token), now());
   if (!before.some((request) => request.id === requestId)) {
@@ -934,7 +934,7 @@ async function resolvePermissionRequest(sessionId, requestId, verdict, deps = {}
   }
   return { sessionId, requestId, payload, outcome, settled };
 }
-async function bearerToken$1() {
+async function bearerToken$2() {
   const credentials = await persistence.readCredentialsForConfiguredRelay();
   if (!credentials) throw new Error("CLI is not authenticated (no ~/.happy/access.key)");
   return credentials.token;
@@ -963,6 +963,18 @@ async function fetchDecryptedAgentState(sessionId, persisted, token) {
 const SESSION_OPS_CLIENT = "session-ops";
 const DEFAULT_RECENT_LIMIT = 15;
 const MAX_READ_LIMIT = 100;
+function backgroundTasksOf(child) {
+  const raw = child.backgroundTasks;
+  if (!raw || typeof raw !== "object") return void 0;
+  const r = raw;
+  if (typeof r.count !== "number" || !Array.isArray(r.tasks)) return void 0;
+  return {
+    count: r.count,
+    tasks: r.tasks.filter((task) => !!task && typeof task === "object" && typeof task.id === "string"),
+    ...typeof r.reportedAt === "number" ? { reportedAt: r.reportedAt } : {},
+    ...r.stale === true ? { stale: true } : {}
+  };
+}
 function mergeSessionSummaries(live, persisted, options = {}) {
   const recentLimit = Math.max(0, options.recentLimit ?? DEFAULT_RECENT_LIMIT);
   const seen = /* @__PURE__ */ new Set();
@@ -982,7 +994,8 @@ function mergeSessionSummaries(live, persisted, options = {}) {
   return summaries.filter((summary) => summary.tags?.includes(wanted) === true);
 }
 function livenessOf(child) {
-  return { live: true, pid: typeof child.pid === "number" ? child.pid : void 0 };
+  const backgroundTasks = backgroundTasksOf(child);
+  return { live: true, pid: typeof child.pid === "number" ? child.pid : void 0, ...backgroundTasks ? { backgroundTasks } : {} };
 }
 function sessionLiveness(live, sessionId) {
   const child = live.find((entry) => entry.happySessionId === sessionId);
@@ -994,6 +1007,7 @@ function toSummary(id, persisted, extra) {
     id,
     live: extra.live,
     ...extra.pid !== void 0 ? { pid: extra.pid } : {},
+    ...extra.backgroundTasks ? { backgroundTasks: extra.backgroundTasks } : {},
     ...meta?.summary?.text ? { title: meta.summary.text } : {},
     ...meta?.path ? { cwd: meta.path } : {},
     ...meta?.flavor ? { flavor: meta.flavor } : {},
@@ -1013,6 +1027,7 @@ function summarizeAccountSession(row, persisted, liveIds, now) {
     live: liveIds.has(row.id),
     url: sessionWebUrl(row.id),
     decryptable: false,
+    readable: false,
     active: row.active === true,
     archived: typeof row.archivedAt === "number",
     ...typeof row.activeAt === "number" ? { activeAt: row.activeAt } : {},
@@ -1032,9 +1047,12 @@ function summarizeAccountSession(row, persisted, liveIds, now) {
   if (!metadata) return base;
   const meta = metadata;
   const pending = pendingRequestsOf(agentState, now);
+  const backgroundTasks = persistence.backgroundTasksReport(agentState?.backgroundTasks, now, { active: row.active === true });
   return {
     ...base,
     decryptable: true,
+    readable: true,
+    backgroundTasks,
     ...meta.summary?.text ? { title: meta.summary.text } : {},
     ...meta.path ? { cwd: meta.path } : {},
     ...meta.flavor ? { flavor: meta.flavor } : {},
@@ -1064,7 +1082,7 @@ function orderAccountSessions(summaries, options = {}) {
   return rows.filter((summary) => rank(summary) < 2 || idleKept++ < recentLimit);
 }
 async function listAccountSessions(options = {}) {
-  const token = await bearerToken();
+  const token = await bearerToken$1();
   const response = await axios.get(`${persistence.configuration.serverUrl}/v1/sessions`, {
     headers: {
       "Authorization": `Bearer ${token}`,
@@ -1080,7 +1098,7 @@ async function listAccountSessions(options = {}) {
   const summaries = rows.filter((row) => typeof row?.id === "string").map((row) => summarizeAccountSession(row, persisted[row.id], liveIds, now)).filter((summary) => options.includeArchived || !summary.archived);
   return orderAccountSessions(summaries, options);
 }
-async function bearerToken() {
+async function bearerToken$1() {
   const credentials = await persistence.readCredentialsForConfiguredRelay();
   if (!credentials) throw new Error("CLI is not authenticated (no ~/.happy/access.key)");
   return credentials.token;
@@ -1095,7 +1113,7 @@ function requirePersisted(sessionId) {
   return persisted;
 }
 async function readSessionLog(sessionId, persisted, limit) {
-  const token = await bearerToken();
+  const token = await bearerToken$1();
   const response = await axios.get(
     `${persistence.configuration.serverUrl}/v3/sessions/${encodeURIComponent(sessionId)}/messages`,
     {
@@ -1134,7 +1152,7 @@ async function readSessionTranscript(sessionId, limit, options = {}) {
   };
 }
 async function readSessionMetadata(sessionId, persisted) {
-  const token = await bearerToken();
+  const token = await bearerToken$1();
   const response = await axios.get(`${persistence.configuration.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}`, {
     headers: {
       "Authorization": `Bearer ${token}`,
@@ -1147,7 +1165,7 @@ async function readSessionMetadata(sessionId, persisted) {
   return persistence.decrypt(persistence.decodeBase64(persisted.encryptionKey), persisted.encryptionVariant, persistence.decodeBase64(ciphertext));
 }
 async function readSessionState(sessionId, persisted) {
-  const token = await bearerToken();
+  const token = await bearerToken$1();
   const response = await axios.get(`${persistence.configuration.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}`, {
     headers: {
       "Authorization": `Bearer ${token}`,
@@ -1199,7 +1217,7 @@ async function stopSession(sessionId) {
   return await persistence.stopDaemonSession(sessionId);
 }
 async function archiveSession(sessionId) {
-  const token = await bearerToken();
+  const token = await bearerToken$1();
   await axios.post(
     `${persistence.configuration.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}/archive`,
     {},
@@ -1213,7 +1231,7 @@ async function archiveSession(sessionId) {
   );
 }
 async function unarchiveSession(sessionId) {
-  const token = await bearerToken();
+  const token = await bearerToken$1();
   await axios.post(
     `${persistence.configuration.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}/unarchive`,
     {},
@@ -1249,7 +1267,7 @@ function explainNotLive(sessionId, status, resumeHint) {
   }
 }
 const CLI_RESUME_HINT = "Use --resume to bring it back on this machine, or spawn a new session.";
-const defaultDeps = {
+const defaultDeps$1 = {
   listLive: () => persistence.listDaemonSessions(),
   readState: (sessionId, persisted) => readSessionState(sessionId, persisted),
   send: (sessionId, persisted, text, client, options) => sendUserMessage(sessionId, persisted, text, client, options),
@@ -1260,7 +1278,7 @@ const defaultDeps = {
   now: () => Date.now()
 };
 async function deliverToSession(sessionId, persisted, text, client, options = {}, deps = {}) {
-  const d = { ...defaultDeps, ...deps };
+  const d = { ...defaultDeps$1, ...deps };
   const resumeHint = options.resumeHint ?? CLI_RESUME_HINT;
   const classify = async () => {
     const [live, server] = await Promise.all([d.listLive(), d.readState(sessionId, persisted)]);
@@ -1351,6 +1369,10 @@ async function waitUntilLive(classify, d, options) {
 const SESSION_PEER_SENT_FROM = "session-peer";
 const CLI_PEER_SENDER_ID = "cli";
 const MESSAGE_FOOTER = "This message comes from another agent session on this machine, not from the user.";
+const MESSAGE_FOOTER_PREFIX = "This message comes from another agent session";
+function messageFooterFor(sender) {
+  return sender.machine ? `${MESSAGE_FOOTER_PREFIX} on machine ${sanitizeHeaderValue(sender.machine, 128)}, not from the user.` : MESSAGE_FOOTER;
+}
 function sanitizeHeaderValue(value, max = 200) {
   if (!value) return "";
   const collapsed = value.replace(/\s+/g, " ").trim().slice(0, max);
@@ -1360,6 +1382,7 @@ function senderFields(sender) {
   const parts = [];
   if (sender.flavor) parts.push(`agent ${sanitizeHeaderValue(sender.flavor, 32)}`);
   if (sender.cwd) parts.push(`cwd ${sanitizeHeaderValue(sender.cwd, 400)}`);
+  if (sender.machine) parts.push(`machine ${sanitizeHeaderValue(sender.machine, 128)}`);
   return parts.map((part) => `; ${part}`).join("");
 }
 function quotedTitle(sender) {
@@ -1367,7 +1390,9 @@ function quotedTitle(sender) {
 }
 function formatSessionPeerMessage(input) {
   const header = `[Very Happy session message ${input.id} from ${quotedTitle(input.from)} ${input.from.sessionId}${senderFields(input.from)}${input.replyTo ? `; re ${sanitizeHeaderValue(input.replyTo, 64)}` : ""}]`;
-  const footer = input.from.sessionId === CLI_PEER_SENDER_ID ? `${MESSAGE_FOOTER} It was sent from the command line (\`very-happy sessions message\`), so there is no session to reply to; act on it here.` : `${MESSAGE_FOOTER} Reply with session_message(to: "${input.from.sessionId}") \u2014 or \`very-happy sessions message ${input.from.sessionId} "<text>"\` \u2014 only when you have something to add (a question, a decision, a heads-up). Do not reply just to acknowledge or thank; the exchange ends when nothing is left to coordinate.`;
+  const base = messageFooterFor(input.from);
+  const routed = input.from.machine ? " (it is routed to that machine for you)" : "";
+  const footer = input.from.sessionId === CLI_PEER_SENDER_ID ? `${base} It was sent from the command line (\`very-happy sessions message\`), so there is no session to reply to; act on it here.` : `${base} Reply with session_message(to: "${input.from.sessionId}")${routed} \u2014 or \`very-happy sessions message ${input.from.sessionId} "<text>"\` \u2014 only when you have something to add (a question, a decision, a heads-up). Do not reply just to acknowledge or thank; the exchange ends when nothing is left to coordinate.`;
   return `${header}
 ${input.body.trim()}
 
@@ -1429,7 +1454,7 @@ function resolveRepoIdentity(cwd, fs = realFs) {
   }
   return { root: null, common: null };
 }
-const PEER_SCOPES = ["repo", "cwd", "machine"];
+const PEER_SCOPES$1 = ["repo", "cwd", "machine"];
 function isPeerInScope(scope, self, other) {
   if (scope === "machine") return true;
   if (scope === "cwd") return path.resolve(self.cwd) === path.resolve(other.cwd);
@@ -1437,24 +1462,508 @@ function isPeerInScope(scope, self, other) {
   return path.resolve(self.cwd) === path.resolve(other.cwd);
 }
 
+const REMOTE_SESSION_OPS_MIN_CLI_VERSION = "0.2.157";
+const REMOTE_OPS_PROTOCOL_VERSION = 1;
+const REMOTE_TEXT_MAX_BYTES = 64 * 1024;
+const REMOTE_TRANSCRIPT_MAX_BYTES = 200 * 1024;
+const REMOTE_CALLS_PER_MINUTE = 60;
+const REMOTE_WRITE_CALLS_PER_MINUTE = 30;
+const REMOTE_LOCATE_MAX_IDS = 200;
+const REMOTE_OP_DEADLINE_MS = 25e3;
+const REMOTE_SEND_COMMIT_DEADLINE_MS = 18e3;
+const REMOTE_RESUME_WAIT_MS = 1e4;
+const REMOTE_WAIT_POLL_MS = 5e3;
+const REMOTE_ANSWER_MAX_BYTES = 64 * 1024;
+const REMOTE_TITLE_MAX_BYTES = 1024;
+const REMOTE_SENT_FROM_ALLOWED = ["cli", "assistant", "automation"];
+const LOCAL_ID_RE = /^[a-zA-Z0-9_.:-]{1,128}$/;
+function remoteError(code, message) {
+  return { ok: false, error: { code, message } };
+}
+const SESSION_ID_RE = /^[a-zA-Z0-9_-]{1,128}$/;
+const PEER_SCOPES = ["repo", "cwd", "machine"];
+function isSessionId(value) {
+  return typeof value === "string" && SESSION_ID_RE.test(value);
+}
+function utf8Bytes(text) {
+  return Buffer.byteLength(text, "utf8");
+}
+function sanitizeSender(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  if (typeof r.sessionId !== "string" || r.sessionId.length === 0 || r.sessionId.length > 128) return null;
+  const optional = (key, max) => typeof r[key] === "string" && r[key].length > 0 ? { [key]: r[key].slice(0, max) } : {};
+  return {
+    sessionId: r.sessionId,
+    ...optional("title", 200),
+    ...optional("flavor", 32),
+    ...optional("cwd", 1024),
+    ...optional("machine", 128)
+  };
+}
+function guardRemoteSessionOpsRequest(method, raw, options) {
+  if (!options.enabled) {
+    return remoteError("disabled", 'Remote session operations are turned off on this machine (settings.json remoteSessionOps = "off")');
+  }
+  if (!raw || typeof raw !== "object") return remoteError("bad_request", "Request must be an object");
+  const r = raw;
+  if (r.v !== REMOTE_OPS_PROTOCOL_VERSION) return remoteError("bad_request", `Unsupported protocol version ${String(r.v)} (this daemon speaks v${REMOTE_OPS_PROTOCOL_VERSION})`);
+  const from = r.from;
+  if (!from || typeof from !== "object" || typeof from.host !== "string" || from.host.length === 0 || typeof from.cli !== "string") {
+    return remoteError("bad_request", "from.host and from.cli are required");
+  }
+  const caller = {
+    host: from.host.slice(0, 128),
+    cli: from.cli.slice(0, 32),
+    ...typeof from.machineId === "string" && from.machineId.length > 0 ? { machineId: from.machineId.slice(0, 128) } : {},
+    ...isSessionId(from.sessionId) ? { sessionId: from.sessionId } : {}
+  };
+  const args = r.args && typeof r.args === "object" ? r.args : {};
+  const limit = typeof args.limit === "number" && Number.isFinite(args.limit) && args.limit >= 1 ? Math.floor(args.limit) : void 0;
+  let clean;
+  switch (method) {
+    case "sessions.list": {
+      if (args.ids !== void 0) {
+        if (!Array.isArray(args.ids) || !args.ids.every(isSessionId)) return remoteError("bad_request", "ids must be an array of session ids");
+        if (args.ids.length > REMOTE_LOCATE_MAX_IDS) return remoteError("too_large", `ids: at most ${REMOTE_LOCATE_MAX_IDS} per call`);
+      }
+      const out = {
+        ...args.ids !== void 0 ? { ids: args.ids } : {},
+        ...args.all === true ? { all: true } : {},
+        ...typeof args.tag === "string" && args.tag.length > 0 ? { tag: args.tag.slice(0, 128) } : {},
+        ...limit !== void 0 ? { limit } : {}
+      };
+      clean = out;
+      break;
+    }
+    case "sessions.read": {
+      if (!isSessionId(args.sessionId)) return remoteError("bad_request", "sessionId is required");
+      const out = { sessionId: args.sessionId, ...limit !== void 0 ? { limit } : {}, ...args.full === true ? { full: true } : {} };
+      clean = out;
+      break;
+    }
+    case "sessions.send": {
+      if (!isSessionId(args.sessionId)) return remoteError("bad_request", "sessionId is required");
+      if (typeof args.text !== "string" || args.text.trim().length === 0) return remoteError("bad_request", "text must be non-empty");
+      if (utf8Bytes(args.text) > REMOTE_TEXT_MAX_BYTES) return remoteError("too_large", `text exceeds ${REMOTE_TEXT_MAX_BYTES} bytes`);
+      if (args.localId !== void 0 && (typeof args.localId !== "string" || !LOCAL_ID_RE.test(args.localId))) return remoteError("bad_request", "localId must be a short id");
+      const out = {
+        sessionId: args.sessionId,
+        text: args.text,
+        ...args.resume === true ? { resume: true } : {},
+        ...args.model === null || typeof args.model === "string" && args.model.length <= 128 ? { model: args.model } : {},
+        ...REMOTE_SENT_FROM_ALLOWED.includes(args.sentFrom) ? { sentFrom: args.sentFrom } : {},
+        ...typeof args.localId === "string" ? { localId: args.localId } : {}
+      };
+      clean = out;
+      break;
+    }
+    case "sessions.peers": {
+      if (args.scope !== void 0 && !PEER_SCOPES.includes(args.scope)) return remoteError("bad_request", `scope must be one of ${PEER_SCOPES.join(", ")}`);
+      const out = {
+        ...args.scope !== void 0 ? { scope: args.scope } : {},
+        ...typeof args.cwd === "string" && args.cwd.length > 0 ? { cwd: args.cwd.slice(0, 4096) } : {}
+      };
+      clean = out;
+      break;
+    }
+    case "sessions.message": {
+      if (!isSessionId(args.to)) return remoteError("bad_request", "to is required");
+      if (typeof args.body !== "string" || args.body.trim().length === 0) return remoteError("bad_request", "body must be non-empty");
+      if (utf8Bytes(args.body) > REMOTE_TEXT_MAX_BYTES) return remoteError("too_large", `body exceeds ${REMOTE_TEXT_MAX_BYTES} bytes`);
+      const sender = sanitizeSender(args.from);
+      if (!sender) return remoteError("bad_request", "from.sessionId (the sender) is required");
+      const out = {
+        to: args.to,
+        body: args.body,
+        ...typeof args.replyTo === "string" && args.replyTo.length > 0 ? { replyTo: args.replyTo.slice(0, 64) } : {},
+        // The recipient's header names the machine the call came
+        // from, as the caller identified itself — never a value the
+        // sender picked for someone else.
+        from: { ...sender, machine: caller.host }
+      };
+      clean = out;
+      break;
+    }
+  }
+  return { ok: true, request: { v: REMOTE_OPS_PROTOCOL_VERSION, from: caller, args: clean } };
+}
+class RemoteCallBudget {
+  constructor(perMinute = REMOTE_CALLS_PER_MINUTE, now = Date.now) {
+    this.perMinute = perMinute;
+    this.now = now;
+    this.tokens = perMinute;
+    this.lastRefill = now();
+  }
+  tokens;
+  lastRefill;
+  /** Take one token; false = over budget (with ms until the next token). */
+  take() {
+    if (this.perMinute <= 0) return { ok: true };
+    const t = this.now();
+    const refill = (t - this.lastRefill) / 6e4 * this.perMinute;
+    if (refill > 0) {
+      this.tokens = Math.min(this.perMinute, this.tokens + refill);
+      this.lastRefill = t;
+    }
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return { ok: true };
+    }
+    return { ok: false, retryAfterMs: Math.ceil((1 - this.tokens) / this.perMinute * 6e4) };
+  }
+}
+function sanitizeAuditValue(value, max = 64) {
+  if (typeof value !== "string" || value.length === 0) return "?";
+  return value.slice(0, max).replace(/[^\x20-\x7e]/g, "?");
+}
+function formatRemoteAuditLine(input) {
+  const from = input.from;
+  const opt = (value) => value === void 0 ? "-" : sanitizeAuditValue(value);
+  return `[REMOTE SESSION OPS] ${sanitizeAuditValue(input.method)} from machine=${sanitizeAuditValue(from?.machineId)} host=${sanitizeAuditValue(from?.host)} cli=${sanitizeAuditValue(from?.cli, 32)} session=${opt(from?.sessionId)} target=${opt(input.sessionId)} \u2192 ${input.outcome} (${Math.max(0, Math.round(input.durationMs))}ms)`;
+}
+function capRemoteText(text, maxBytes, keep = "head") {
+  if (utf8Bytes(text) <= maxBytes) return text;
+  const buffer = Buffer.from(text, "utf8");
+  const marker = "\u2026";
+  const room = Math.max(0, maxBytes - Buffer.byteLength(marker));
+  const slice = keep === "head" ? buffer.subarray(0, room) : buffer.subarray(buffer.length - room);
+  const clean = slice.toString("utf8").replace(/^�+|�+$/g, "");
+  return keep === "head" ? clean + marker : marker + clean;
+}
+function capRemoteTranscript(transcript, maxBytes = REMOTE_TRANSCRIPT_MAX_BYTES) {
+  if (utf8Bytes(transcript) <= maxBytes) return { transcript, truncated: false };
+  const buffer = Buffer.from(transcript, "utf8");
+  const marker = "\u2026 [truncated by the remote machine: transcript exceeded the RPC budget; use --limit] \u2026\n";
+  const tail = buffer.subarray(buffer.length - (maxBytes - Buffer.byteLength(marker))).toString("utf8");
+  return { transcript: marker + tail.replace(/^�+/, ""), truncated: true };
+}
+function parseHappyClientVersion(value) {
+  if (typeof value !== "string") return null;
+  const match = value.match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+function supportsRemoteSessionOps(cliVersion) {
+  if (!cliVersion) return null;
+  return compareVersions(cliVersion, REMOTE_SESSION_OPS_MIN_CLI_VERSION) >= 0;
+}
+
+const REMOTE_CLIENT_TAG = "session-ops";
+const REMOTE_RPC_TIMEOUT_MS = 3e4;
+const REMOTE_LOCATE_MAX_MACHINES = 8;
+class RemoteSessionOpsError extends Error {
+  constructor(code, message, machineId, ambiguous = false) {
+    super(message);
+    this.code = code;
+    this.machineId = machineId;
+    this.ambiguous = ambiguous;
+  }
+}
+async function bearerToken() {
+  const credentials = await persistence.readCredentialsForConfiguredRelay();
+  if (!credentials) throw new Error("CLI is not authenticated (no ~/.happy/access.key)");
+  return credentials.token;
+}
+async function listAccountMachines() {
+  const token = await bearerToken();
+  const response = await axios.get(`${persistence.configuration.serverUrl}/v1/machines`, {
+    headers: { "Authorization": `Bearer ${token}`, "X-Happy-Client": `${REMOTE_CLIENT_TAG}/${persistence.configuration.currentCliVersion}` },
+    timeout: 15e3
+  });
+  const rows = Array.isArray(response.data) ? response.data : [];
+  return rows.filter((row) => !!row && typeof row === "object" && typeof row.id === "string").map((row) => ({
+    id: row.id,
+    active: row.active === true,
+    ...typeof row.activeAt === "number" ? { activeAt: row.activeAt } : {},
+    cliVersion: parseHappyClientVersion(row.lastHappyClient)
+  }));
+}
+async function callerIdentity(env = process.env) {
+  const settings = await persistence.readSettings().catch(() => null);
+  const sessionId = env.VH_PEER_SESSION_ID;
+  return {
+    ...settings?.machineId ? { machineId: settings.machineId } : {},
+    host: os.hostname(),
+    cli: persistence.configuration.currentCliVersion,
+    ...sessionId && /^[a-zA-Z0-9_-]{1,128}$/.test(sessionId) ? { sessionId } : {}
+  };
+}
+const defaultDeps = {
+  listMachines: listAccountMachines,
+  selfMachineId: async () => (await persistence.readSettings().catch(() => null))?.machineId,
+  openTransport: async () => {
+    const socket = await openUserScopedSocket(await bearerToken());
+    return {
+      call: (method, paramsJson) => socket.rpcCall({ method, params: paramsJson }, REMOTE_RPC_TIMEOUT_MS),
+      close: () => socket.close()
+    };
+  },
+  caller: () => callerIdentity(),
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now: () => Date.now()
+};
+function withDefaults(deps) {
+  return { ...defaultDeps, ...deps };
+}
+function pickRemoteCandidates(machines, selfId) {
+  const candidates = [];
+  const skipped = [];
+  for (const machine of machines) {
+    if (selfId && machine.id === selfId) {
+      skipped.push({ machine, reason: "self" });
+      continue;
+    }
+    if (!machine.active) {
+      skipped.push({ machine, reason: "offline" });
+      continue;
+    }
+    if (supportsRemoteSessionOps(machine.cliVersion) === false) {
+      skipped.push({ machine, reason: "too_old" });
+      continue;
+    }
+    candidates.push(machine);
+  }
+  candidates.sort((a, b) => (b.activeAt ?? 0) - (a.activeAt ?? 0));
+  return { candidates: candidates.slice(0, REMOTE_LOCATE_MAX_MACHINES), skipped };
+}
+function describeAge(activeAt, now) {
+  if (activeAt === void 0) return "never seen";
+  const minutes = Math.round((now - activeAt) / 6e4);
+  if (minutes < 2) return "seen just now";
+  if (minutes < 120) return `last seen ${minutes}m ago`;
+  if (minutes < 48 * 60) return `last seen ${Math.round(minutes / 60)}h ago`;
+  return `last seen ${Math.round(minutes / 1440)}d ago`;
+}
+async function resolveExplicitMachine(machineId, deps) {
+  const machines = await deps.listMachines();
+  const machine = machines.find((row) => row.id === machineId);
+  if (!machine) throw new RemoteSessionOpsError("unknown_machine", `Machine ${machineId} is not on this account`, machineId);
+  if (!machine.active) throw new RemoteSessionOpsError("offline", `Machine ${machineId} is offline (${describeAge(machine.activeAt, deps.now())}); its sessions cannot be reached until its daemon reconnects`, machineId);
+  if (supportsRemoteSessionOps(machine.cliVersion) === false) {
+    throw new RemoteSessionOpsError("too_old", `Machine ${machineId} runs CLI ${machine.cliVersion}; cross-machine session operations need \u2265 ${REMOTE_SESSION_OPS_MIN_CLI_VERSION} on the target`, machineId);
+  }
+  return machine;
+}
+async function callRemoteSessionOp(transport, machineId, method, args, from) {
+  const params = JSON.stringify({ v: REMOTE_OPS_PROTOCOL_VERSION, from, args });
+  let ack;
+  try {
+    ack = await transport.call(`${machineId}:${method}`, params);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new RemoteSessionOpsError("unreachable", `Machine ${machineId} did not answer ${method} (${reason})`, machineId, true);
+  }
+  if (!ack?.ok) {
+    const reason = ack?.error ?? "no ack";
+    if (/not available/i.test(reason)) {
+      throw new RemoteSessionOpsError("unreachable", `Machine ${machineId} did not answer ${method}: its daemon is offline, restarting, or runs a CLI older than ${REMOTE_SESSION_OPS_MIN_CLI_VERSION}`, machineId);
+    }
+    throw new RemoteSessionOpsError("unreachable", `Machine ${machineId}: ${reason}`, machineId, true);
+  }
+  let envelope;
+  try {
+    envelope = typeof ack.result === "string" ? JSON.parse(ack.result) : ack.result;
+  } catch {
+    throw new RemoteSessionOpsError("unreachable", `Machine ${machineId} returned an unreadable ${method} response`, machineId);
+  }
+  if (!envelope || typeof envelope !== "object") throw new RemoteSessionOpsError("unreachable", `Machine ${machineId} returned an empty ${method} response`, machineId);
+  if ("ok" in envelope) {
+    if (envelope.ok) return envelope.result;
+    throw new RemoteSessionOpsError(envelope.error.code, `Machine ${machineId}: ${envelope.error.message}`, machineId);
+  }
+  throw new RemoteSessionOpsError("internal", `Machine ${machineId}: ${envelope.error ?? "remote handler failed"}`, machineId);
+}
+async function locateRemoteSession(transport, sessionId, options, deps) {
+  const from = await deps.caller();
+  if (options.machineId) {
+    const machine = await resolveExplicitMachine(options.machineId, deps);
+    const listing = await callRemoteSessionOp(transport, machine.id, "sessions.list", { ids: [sessionId] }, from);
+    if (!listing.sessions.some((row) => row.id === sessionId)) {
+      throw new RemoteSessionOpsError("no_local_key", `Machine ${machine.id} (${listing.host}) has no key for session ${sessionId}: it was not spawned there (or is older than 14 days)`, machine.id);
+    }
+    return { machine, host: listing.host };
+  }
+  const { candidates, skipped } = pickRemoteCandidates(await deps.listMachines(), await deps.selfMachineId());
+  const failures = [];
+  for (const machine of candidates) {
+    try {
+      const listing = await callRemoteSessionOp(transport, machine.id, "sessions.list", { ids: [sessionId] }, from);
+      if (listing.sessions.some((row) => row.id === sessionId)) return { machine, host: listing.host };
+      failures.push(`${listing.host || machine.id}: not there`);
+    } catch (error) {
+      failures.push(`${machine.id}: ${error instanceof RemoteSessionOpsError ? error.code : error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const skippedText = skipped.filter((s) => s.reason !== "self").map((s) => `${s.machine.id}: ${s.reason}`);
+  const detail = [...failures, ...skippedText];
+  throw new RemoteSessionOpsError(
+    "not_located",
+    `Session ${sessionId} is not on this machine and no online machine of this account reports it${detail.length ? ` (${detail.join("; ")})` : " (no other machines are online)"}. Pass --machine <id> to name one, or bring its machine online.`
+  );
+}
+async function withRemoteTransport(deps, fn) {
+  const transport = await deps.openTransport();
+  try {
+    return await fn(transport);
+  } finally {
+    try {
+      transport.close();
+    } catch {
+    }
+  }
+}
+async function readRemoteTranscript(sessionId, options = {}, overrides = {}) {
+  const deps = withDefaults(overrides);
+  return withRemoteTransport(deps, async (transport) => {
+    const located = await locateRemoteSession(transport, sessionId, { machineId: options.machineId }, deps);
+    return callRemoteSessionOp(transport, located.machine.id, "sessions.read", {
+      sessionId,
+      ...options.limit !== void 0 ? { limit: options.limit } : {},
+      ...options.full ? { full: true } : {}
+    }, await deps.caller());
+  });
+}
+async function waitForRemoteTurnEnd(sessionId, options, overrides = {}) {
+  const deps = withDefaults(overrides);
+  const pollMs = options.pollMs ?? REMOTE_WAIT_POLL_MS;
+  return withRemoteTransport(deps, async (transport) => {
+    const located = await locateRemoteSession(transport, sessionId, { machineId: options.machineId }, deps);
+    const from = await deps.caller();
+    const deadline = deps.now() + options.timeoutMs;
+    const args = { sessionId, ...options.limit !== void 0 ? { limit: options.limit } : {}, ...options.full ? { full: true } : {} };
+    while (true) {
+      const read = await callRemoteSessionOp(transport, located.machine.id, "sessions.read", args, from);
+      if (read.turn.ended) return { read, timedOut: false };
+      if (deps.now() + pollMs > deadline) return { read, timedOut: true };
+      await deps.sleep(pollMs);
+    }
+  });
+}
+async function sendRemoteMessage(sessionId, text, options = {}, overrides = {}) {
+  const deps = withDefaults(overrides);
+  return withRemoteTransport(deps, async (transport) => {
+    const located = await locateRemoteSession(transport, sessionId, { machineId: options.machineId }, deps);
+    const from = await deps.caller();
+    const localId = options.localId ?? `remote-send-${node_crypto.randomUUID()}`;
+    const args = {
+      sessionId,
+      text,
+      localId,
+      ...options.resume ? { resume: true } : {},
+      ...options.model !== void 0 ? { model: options.model } : {},
+      ...options.sentFrom !== void 0 ? { sentFrom: options.sentFrom } : {}
+    };
+    const attempt = () => callRemoteSessionOp(transport, located.machine.id, "sessions.send", args, from);
+    let result;
+    try {
+      result = await attempt();
+    } catch (error) {
+      const retryable = error instanceof RemoteSessionOpsError && (error.ambiguous || error.code === "timeout");
+      if (!retryable) throw error;
+      result = await attempt();
+    }
+    return { ...result, machine: { id: located.machine.id, host: located.host } };
+  });
+}
+async function sendRemotePeerMessage(args, options = {}, overrides = {}) {
+  const deps = withDefaults(overrides);
+  return withRemoteTransport(deps, async (transport) => {
+    const located = await locateRemoteSession(transport, args.to, { machineId: options.machineId }, deps);
+    const caller = await deps.caller();
+    const result = await callRemoteSessionOp(transport, located.machine.id, "sessions.message", {
+      to: args.to,
+      body: args.body,
+      ...args.replyTo ? { replyTo: args.replyTo } : {},
+      from: { ...args.from, machine: args.from.machine ?? caller.host }
+    }, caller);
+    return { ...result, machine: { id: located.machine.id, host: located.host } };
+  });
+}
+async function listRemotePeers(machineId, options = {}, overrides = {}) {
+  const deps = withDefaults(overrides);
+  return withRemoteTransport(deps, async (transport) => {
+    const machine = await resolveExplicitMachine(machineId, deps);
+    return callRemoteSessionOp(transport, machine.id, "sessions.peers", {
+      ...options.scope ? { scope: options.scope } : {},
+      ...options.cwd ? { cwd: options.cwd } : {}
+    }, await deps.caller());
+  });
+}
+async function listRemoteSessions(machineId, options = {}, overrides = {}) {
+  const deps = withDefaults(overrides);
+  return withRemoteTransport(deps, async (transport) => {
+    const machine = await resolveExplicitMachine(machineId, deps);
+    return callRemoteSessionOp(transport, machine.id, "sessions.list", {
+      ...options.tag ? { tag: options.tag } : {},
+      ...options.limit !== void 0 ? { limit: options.limit } : {}
+    }, await deps.caller());
+  });
+}
+async function fillForeignAccountRows(rows, overrides = {}) {
+  const deps = withDefaults(overrides);
+  const pending = new Set(rows.filter((row) => !row.decryptable).map((row) => row.id));
+  const asked = [];
+  if (pending.size === 0) return { rows, asked, skipped: [] };
+  const { candidates, skipped } = pickRemoteCandidates(await deps.listMachines(), await deps.selfMachineId());
+  const filled = /* @__PURE__ */ new Map();
+  if (candidates.length > 0) {
+    await withRemoteTransport(deps, async (transport) => {
+      const from = await deps.caller();
+      for (const machine of candidates) {
+        if (pending.size === 0) break;
+        try {
+          const listing = await callRemoteSessionOp(transport, machine.id, "sessions.list", { ids: [...pending], all: true }, from);
+          let count = 0;
+          for (const row of listing.sessions) {
+            if (!pending.has(row.id)) continue;
+            pending.delete(row.id);
+            count++;
+            filled.set(row.id, { ...row, decryptable: false, readable: true, via: machine.id, machine: { id: machine.id, host: listing.host } });
+          }
+          asked.push({ machineId: machine.id, host: listing.host, filled: count });
+        } catch (error) {
+          asked.push({ machineId: machine.id, filled: 0, error: error instanceof Error ? error.message : String(error) });
+        }
+      }
+    });
+  }
+  return {
+    rows: rows.map((row) => filled.get(row.id) ?? row),
+    asked,
+    skipped: skipped.filter((s) => s.reason !== "self").map((s) => ({ machineId: s.machine.id, reason: s.reason }))
+  };
+}
+
 const SESSION_PEER_TOOL_NAMES = ["session_message", "session_peers"];
 const SESSION_PEER_TOOL_SCHEMAS = {
   session_message: {
     title: "Message Another Session",
     readOnly: false,
-    description: "Send a message to another agent session running on this machine (find ids with session_peers). It lands in that session's chat with your title, session id and cwd, and tells the peer how to reply to you. Use it to coordinate when you both edit the same files: say what you are changing and ask what they are changing. Returns as soon as the message is queued; the reply arrives later as a message from that session. Only sessions this machine's daemon runs can be reached; terminal-mirror sessions cannot receive messages.",
+    description: "Send a message to another agent session (find ids with session_peers). It lands in that session's chat with your title, session id and cwd, and tells the peer how to reply to you. Use it to coordinate when you both edit the same files: say what you are changing and ask what they are changing. Returns as soon as the message is queued; the reply arrives later as a message from that session. Sessions on this machine are reached directly; a session spawned by another machine of this account is routed to that machine's daemon (it must be online). Terminal-mirror sessions cannot receive messages.",
     inputSchema: {
       to: z.z.string().min(1).max(128).describe("Target session id (from session_peers, or a peer's message header)"),
       body: z.z.string().min(1).max(16e3).describe("The message text"),
-      replyTo: z.z.string().min(1).max(64).optional().describe("Id of the peer message you are answering (from its header), if any")
+      replyTo: z.z.string().min(1).max(64).optional().describe("Id of the peer message you are answering (from its header), if any"),
+      machineId: z.z.string().min(1).max(128).optional().describe("Machine id the target session runs on, when known (skips the lookup across the account's machines)")
     }
   },
   session_peers: {
     title: "List Peer Sessions",
     readOnly: true,
-    description: 'List the other agent sessions running on this machine and the files each edited in the last 30 minutes. Default scope "repo": sessions in the same git repository, including its other worktrees (sameWorktree says whether they share your checkout). "cwd": the same directory only. "machine": every live session here.',
+    description: 'List the other agent sessions running on this machine and the files each edited in the last 30 minutes. Default scope "repo": sessions in the same git repository, including its other worktrees (sameWorktree says whether they share your checkout). "cwd": the same directory only. "machine": every live session here. With machineId, list the live sessions on that other machine of this account instead (scope "machine" unless you pass a cwd that exists there).',
     inputSchema: {
-      scope: z.z.enum(["repo", "cwd", "machine"]).optional().describe("repo (default) | cwd | machine")
+      scope: z.z.enum(["repo", "cwd", "machine"]).optional().describe("repo (default) | cwd | machine"),
+      machineId: z.z.string().min(1).max(128).optional().describe("Another machine of this account (from the web's machine list) to list instead of this one"),
+      cwd: z.z.string().min(1).max(4096).optional().describe("With machineId: a directory on that machine to compute repo/cwd scope from")
     }
   }
 };
@@ -1495,19 +2004,27 @@ async function sendPeerMessage(context, args) {
   if (args.to === self.sessionId) throw new Error("That is this session; message a peer instead");
   const body = typeof args.body === "string" ? args.body.trim() : "";
   if (!body) throw new Error("body must be non-empty");
+  const now = (context.now ?? Date.now)();
   const persisted = (context.readPersisted ?? persistence.readPersistedSessions)()[args.to];
-  if (!persisted) {
-    throw new Error(`Session ${args.to} is not on this machine (no local key); messaging sessions on other machines is not supported yet`);
+  if (!persisted || args.machineId) {
+    const remote = context.remoteMessage === void 0 ? sendRemotePeerMessage : context.remoteMessage;
+    if (remote === null) {
+      throw new Error(`Session ${args.to} is not on this machine (no local key)`);
+    }
+    if (context.sentTo) {
+      const budget = checkPeerSendBudget(context.sentTo, args.to, now);
+      if (!budget.ok) throw new Error(replyLoopRefusal(budget.count, args.to));
+    }
+    const result2 = await remote({ to: args.to, body, replyTo: args.replyTo, from: self, machineId: args.machineId });
+    context.sentTo?.get(args.to)?.push(now);
+    return result2;
   }
   const live = (await (context.listPeers ?? persistence.listDaemonPeers)()).find((session) => session.sessionId === args.to);
   if (!live) throw new Error(`Session ${args.to} is not running on this machine; nothing would read the message`);
   if (live.kind === "mirror") throw new Error(`Session ${args.to} is a terminal mirror (a person typing claude in a terminal); it cannot receive messages`);
-  const now = (context.now ?? Date.now)();
   if (context.sentTo) {
     const budget = checkPeerSendBudget(context.sentTo, args.to, now);
-    if (!budget.ok) {
-      throw new Error(`Refused: this session already sent ${budget.count} messages to ${args.to} in the last ${Math.round(PEER_MESSAGE_RATE_WINDOW_MS / 6e4)} minutes. That is a reply loop, not coordination \u2014 STOP replying to that session now; do not send acknowledgements or thanks. Continue your own work.`);
-    }
+    if (!budget.ok) throw new Error(replyLoopRefusal(budget.count, args.to));
   }
   const messageId = node_crypto.randomUUID().slice(0, 8);
   const text = formatSessionPeerMessage({ id: messageId, from: self, body, replyTo: args.replyTo });
@@ -1523,13 +2040,27 @@ async function sendPeerMessage(context, args) {
     ...result.error ? { error: result.error } : {}
   };
 }
+function replyLoopRefusal(count, to) {
+  return `Refused: this session already sent ${count} messages to ${to} in the last ${Math.round(PEER_MESSAGE_RATE_WINDOW_MS / 6e4)} minutes. That is a reply loop, not coordination \u2014 STOP replying to that session now; do not send acknowledgements or thanks. Continue your own work.`;
+}
 async function executeSessionPeerTool(name, args, context) {
   switch (name) {
     case "session_message":
-      return sendPeerMessage(context, { to: String(args?.to ?? ""), body: String(args?.body ?? ""), ...args?.replyTo ? { replyTo: String(args.replyTo) } : {} });
+      return sendPeerMessage(context, {
+        to: String(args?.to ?? ""),
+        body: String(args?.body ?? ""),
+        ...args?.replyTo ? { replyTo: String(args.replyTo) } : {},
+        ...args?.machineId ? { machineId: String(args.machineId) } : {}
+      });
     case "session_peers": {
       const scope = args?.scope;
-      if (scope !== void 0 && !PEER_SCOPES.includes(scope)) throw new Error(`scope must be one of ${PEER_SCOPES.join(", ")}`);
+      if (scope !== void 0 && !PEER_SCOPES$1.includes(scope)) throw new Error(`scope must be one of ${PEER_SCOPES$1.join(", ")}`);
+      if (args?.machineId) {
+        return (context.remotePeers ?? listRemotePeers)(String(args.machineId), {
+          ...scope !== void 0 ? { scope } : {},
+          ...typeof args.cwd === "string" && args.cwd ? { cwd: args.cwd } : {}
+        });
+      }
       return listPeerSessions(context, scope ?? "repo");
     }
   }
@@ -1616,15 +2147,24 @@ exports.AGENT_GUIDANCE = AGENT_GUIDANCE;
 exports.AUTOMATIONS_UNAVAILABLE_MESSAGE = AUTOMATIONS_UNAVAILABLE_MESSAGE;
 exports.AUTOMATION_TOOL_NAMES = AUTOMATION_TOOL_NAMES;
 exports.AutomationsRequestError = AutomationsRequestError;
+exports.CLI_PEER_SENDER_ID = CLI_PEER_SENDER_ID;
 exports.DEFAULT_RECENT_LIMIT = DEFAULT_RECENT_LIMIT;
 exports.MAX_READ_LIMIT = MAX_READ_LIMIT;
-exports.PEER_SCOPES = PEER_SCOPES;
+exports.PEER_SCOPES = PEER_SCOPES$1;
 exports.PREVIEW_TOOL_DESCRIPTION = PREVIEW_TOOL_DESCRIPTION;
 exports.PREVIEW_TOOL_NAME = PREVIEW_TOOL_NAME;
 exports.PREVIEW_TOOL_TITLE = PREVIEW_TOOL_TITLE;
+exports.REMOTE_ANSWER_MAX_BYTES = REMOTE_ANSWER_MAX_BYTES;
+exports.REMOTE_OP_DEADLINE_MS = REMOTE_OP_DEADLINE_MS;
+exports.REMOTE_RESUME_WAIT_MS = REMOTE_RESUME_WAIT_MS;
+exports.REMOTE_SEND_COMMIT_DEADLINE_MS = REMOTE_SEND_COMMIT_DEADLINE_MS;
+exports.REMOTE_TITLE_MAX_BYTES = REMOTE_TITLE_MAX_BYTES;
+exports.REMOTE_WRITE_CALLS_PER_MINUTE = REMOTE_WRITE_CALLS_PER_MINUTE;
 exports.REPORT_PROGRESS_TOOL_DESCRIPTION = REPORT_PROGRESS_TOOL_DESCRIPTION;
 exports.REPORT_PROGRESS_TOOL_NAME = REPORT_PROGRESS_TOOL_NAME;
 exports.REPORT_PROGRESS_TOOL_TITLE = REPORT_PROGRESS_TOOL_TITLE;
+exports.RemoteCallBudget = RemoteCallBudget;
+exports.RemoteSessionOpsError = RemoteSessionOpsError;
 exports.SESSION_PEER_SENT_FROM = SESSION_PEER_SENT_FROM;
 exports.SESSION_PEER_TOOL_NAMES = SESSION_PEER_TOOL_NAMES;
 exports.TEAM_TOOL_NAMES = TEAM_TOOL_NAMES;
@@ -1635,16 +2175,24 @@ exports.analyzeLatestTurn = analyzeLatestTurn;
 exports.archiveSession = archiveSession;
 exports.authenticatedAutomationsClient = authenticatedAutomationsClient;
 exports.automationRunIdFromEnv = automationRunIdFromEnv;
+exports.capRemoteText = capRemoteText;
+exports.capRemoteTranscript = capRemoteTranscript;
 exports.cliPeerSelf = cliPeerSelf;
 exports.createAutomationsClient = createAutomationsClient;
 exports.createSessionPeerToolExecutor = createSessionPeerToolExecutor;
 exports.createTeamsClient = createTeamsClient;
 exports.deliverToSession = deliverToSession;
+exports.fillForeignAccountRows = fillForeignAccountRows;
 exports.formatEditConflictNotice = formatEditConflictNotice;
+exports.formatRemoteAuditLine = formatRemoteAuditLine;
+exports.guardRemoteSessionOpsRequest = guardRemoteSessionOpsRequest;
 exports.isAutomationsUnavailable = isAutomationsUnavailable;
 exports.listAccountSessions = listAccountSessions;
 exports.listPeerSessions = listPeerSessions;
+exports.listRemotePeers = listRemotePeers;
+exports.listRemoteSessions = listRemoteSessions;
 exports.listSessions = listSessions;
+exports.readRemoteTranscript = readRemoteTranscript;
 exports.readSessionLog = readSessionLog;
 exports.readSessionMetadata = readSessionMetadata;
 exports.readSessionTranscript = readSessionTranscript;
@@ -1652,8 +2200,10 @@ exports.readTeamScope = readTeamScope;
 exports.registerAutomationTools = registerAutomationTools;
 exports.registerSessionPeerTools = registerSessionPeerTools;
 exports.registerTeamsTools = registerTeamsTools;
+exports.remoteError = remoteError;
 exports.resolvePermissionRequest = resolvePermissionRequest;
 exports.sendPeerMessage = sendPeerMessage;
+exports.sendRemoteMessage = sendRemoteMessage;
 exports.sendUserMessage = sendUserMessage;
 exports.sessionWebUrl = sessionWebUrl;
 exports.stopSession = stopSession;
@@ -1661,5 +2211,6 @@ exports.teamRequest = teamRequest;
 exports.teamScopePath = teamScopePath;
 exports.trimIdent = trimIdent;
 exports.userPromptText = userPromptText;
+exports.waitForRemoteTurnEnd = waitForRemoteTurnEnd;
 exports.waitForSessionKey = waitForSessionKey;
 exports.waitForTurnEnd = waitForTurnEnd;