chainlesschain 0.162.147 → 0.162.148

package/src/gateways/ws/ws-server.js

@@ -27,6 +27,19 @@ import {
   createRuntimeEvent,
 } from "../../runtime/runtime-events.js";
 import { createWsMessageDispatcher } from "./message-dispatcher.js";
+import {
+  RemoteSessionRegistry,
+  RemoteSessionPolicy,
+} from "../../harness/remote-session-registry.js";
+import { RemoteSessionAuditLog } from "../../harness/remote-session-audit.js";
+import { RemoteSessionAuditFileSink } from "../../harness/remote-session-audit-sink.js";
+import {
+  RemoteSessionPushDispatcher,
+  isApprovalRequestEvent,
+} from "../../harness/remote-session-push.js";
+import { createRemoteSessionPushSender } from "../../harness/remote-session-push-fcm.js";
+import { RemoteSessionRelay } from "../remote-session-relay.js";
+import { handleRemoteSessionPublish } from "./remote-session-protocol.js";
 import { handleTaskDetail, handleTaskHistory } from "./task-protocol.js";
 import {
   handleSessionCreate,
@@ -226,6 +239,63 @@ export class ChainlessChainWSServer extends EventEmitter {
 
     /** Session handlers: sessionId → WSAgentHandler | WSChatHandler */
     this.sessionHandlers = new Map();
+    /** Org-policy constraints for Remote Sessions (scopes, device cap, TTL). */
+    this.remoteSessionPolicy =
+      options.remoteSessionPolicy || RemoteSessionPolicy.fromEnv(process.env);
+    /** Local authorization state for multi-device Remote Sessions. */
+    this.remoteSessions =
+      options.remoteSessionRegistry ||
+      new RemoteSessionRegistry({ policy: this.remoteSessionPolicy });
+    /**
+     * Optional durable sink (JSONL) for the audit trail. Enabled only when a
+     * sink is injected or CHAINLESSCHAIN_REMOTE_SESSION_AUDIT_FILE is set; the
+     * in-memory ring stays the primary store and query surface.
+     */
+    this.remoteSessionAuditSink =
+      options.remoteSessionAuditSink ||
+      RemoteSessionAuditFileSink.fromEnv(process.env);
+    /** Bounded in-memory audit trail for Remote Session lifecycle + control. */
+    this.remoteSessionAudit =
+      options.remoteSessionAudit ||
+      new RemoteSessionAuditLog(
+        this.remoteSessionAuditSink
+          ? {
+              sink: this.remoteSessionAuditSink.handler,
+              // Hydrate so audit queries survive a restart; cap to the ring size.
+              initialEntries: this.remoteSessionAuditSink.readAll({
+                limit: 1000,
+              }),
+            }
+          : {},
+      );
+    /**
+     * Vendor-push dispatcher — wakes backgrounded paired devices for approval
+     * requests. Credential-free by default (a no-op until a `sender` is
+     * injected); FCM/APNs delivery is host-supplied.
+     */
+    this.remoteSessionPush =
+      options.remoteSessionPush ||
+      RemoteSessionPushDispatcher.fromEnv(process.env, {
+        // Prefer an explicitly injected sender (tests / custom transport); else
+        // build a real FCM sender from env when service-account creds are
+        // configured. Stays a no-op (null) when neither is present.
+        sender:
+          options.remoteSessionPushSender ||
+          createRemoteSessionPushSender(process.env),
+      });
+    this.remoteSessionRelayUrl = options.remoteSessionRelayUrl || null;
+    this.remoteSessionPeerId = options.remoteSessionPeerId || null;
+    this.remoteSessionCrypto = new Map();
+    this.remoteSessionPairingSecrets = new Map();
+    this.remoteSessionRelay =
+      options.remoteSessionRelay ||
+      (this.remoteSessionRelayUrl && this.remoteSessionPeerId
+        ? new RemoteSessionRelay({
+            relayUrl: this.remoteSessionRelayUrl,
+            peerId: this.remoteSessionPeerId,
+          })
+        : null);
+    this._attachRemoteSessionRelay();
     this._dispatcher = createWsMessageDispatcher(this);
 
     this._heartbeatTimer = null;
@@ -251,6 +321,12 @@ export class ChainlessChainWSServer extends EventEmitter {
           this.port = addr.port;
         }
         this._startHeartbeat();
+        this.remoteSessionRelay?.connect().catch((error) => {
+          this.emit("client-error", {
+            clientId: "remote-session-relay",
+            error: error.message,
+          });
+        });
         this.emit("listening", { port: this.port, host: this.host });
         resolve();
       });
@@ -285,6 +361,9 @@ export class ChainlessChainWSServer extends EventEmitter {
       }
     }
     this.sessionHandlers.clear();
+    this.remoteSessionCrypto.clear();
+    this.remoteSessionPairingSecrets.clear();
+    this.remoteSessionRelay?.close();
 
     // Kill all running child processes
     for (const [id, child] of this.processes) {
@@ -391,6 +470,18 @@ export class ChainlessChainWSServer extends EventEmitter {
         client.authTimer = null;
       }
       this.clients.delete(clientId);
+      for (const affected of this.remoteSessions.removeClient(clientId)) {
+        if (affected.closed)
+          this.remoteSessionCrypto.delete(affected.sessionId);
+        if (affected.closed)
+          this.remoteSessionPairingSecrets.delete(affected.sessionId);
+        this.remoteSessionAudit?.record({
+          sessionId: affected.sessionId,
+          actor: clientId,
+          action: affected.closed ? "session.closed" : "device.disconnected",
+          detail: { reason: "disconnect" },
+        });
+      }
       this.emit("disconnection", { clientId });
     });
 
@@ -975,12 +1066,220 @@ export class ChainlessChainWSServer extends EventEmitter {
     if (ws.readyState === ws.OPEN) {
       try {
         ws.send(JSON.stringify(data));
+        this._mirrorRemoteSessionEvent(ws, data);
       } catch (_err) {
         // Connection may have just closed
       }
     }
   }
 
+  /** Mirror canonical Agent Session output to paired Remote Session clients. */
+  _mirrorRemoteSessionEvent(hostWs, data) {
+    if (
+      !data ||
+      typeof data !== "object" ||
+      !data.sessionId ||
+      String(data.type || "").startsWith("remote-session-")
+    ) {
+      return;
+    }
+    let hostClientId = null;
+    for (const [clientId, client] of this.clients) {
+      if (client.ws === hostWs) {
+        hostClientId = clientId;
+        break;
+      }
+    }
+    if (!hostClientId) return;
+
+    for (const remoteSession of this.remoteSessions.findHosted(
+      data.sessionId,
+      hostClientId,
+    )) {
+      for (const member of remoteSession.members.values()) {
+        if (
+          member.clientId === hostClientId ||
+          !member.scopes.includes("observe")
+        ) {
+          continue;
+        }
+        // Wake a backgrounded device via vendor push for approval requests.
+        // Independent of the WS mirror below — a relay-paired mobile app may
+        // report a live socket while its process is suspended and will never
+        // read the mirrored event until the user taps the push.
+        if (member.pushToken && isApprovalRequestEvent(data.type)) {
+          this._dispatchApprovalPush(remoteSession, member, data);
+        }
+        const target = this.clients.get(member.clientId);
+        if (!target && this.remoteSessionRelay) {
+          const crypto = this.remoteSessionCrypto.get(remoteSession.sessionId);
+          if (crypto) {
+            this.remoteSessionRelay.sendEncrypted(
+              member.clientId,
+              crypto.encrypt(member.clientId, data),
+            );
+          }
+          continue;
+        }
+        if (!target) continue;
+        this._send(target.ws, {
+          type: "remote-session-event",
+          remoteSessionId: remoteSession.sessionId,
+          agentSessionId: remoteSession.agentSessionId,
+          event: data,
+        });
+      }
+    }
+  }
+
+  /**
+   * Fire-and-forget a vendor push to one member for an approval request, then
+   * record the outcome in the audit trail. Never throws (the dispatcher is
+   * best-effort); the WS mirror + in-app notification remain primary.
+   */
+  _dispatchApprovalPush(remoteSession, member, data) {
+    const dispatcher = this.remoteSessionPush;
+    if (!dispatcher || !dispatcher.enabled) return;
+    const requestId =
+      data.requestId || data.approvalId || data.id || `approval:${data.type}`;
+    dispatcher
+      .dispatch({
+        token: member.pushToken,
+        provider: member.pushProvider,
+        sessionId: remoteSession.sessionId,
+        clientId: member.clientId,
+        dedupeKey: requestId,
+        notification: {
+          title: "Approval requested",
+          body: "A coding session needs your approval",
+        },
+      })
+      .then((outcome) => {
+        // A vendor that reports the token as retired means the app was
+        // uninstalled / the token rotated — prune it so it is never retried.
+        if (outcome.code === "PUSH_TOKEN_UNREGISTERED") {
+          try {
+            this.remoteSessions.registerPush(
+              remoteSession.sessionId,
+              member.clientId,
+              { token: null },
+            );
+          } catch {
+            // Member may have been revoked meanwhile — nothing to prune.
+          }
+          this.remoteSessionAudit?.record({
+            sessionId: remoteSession.sessionId,
+            actor: member.clientId,
+            action: "push.unregistered",
+            detail: { provider: member.pushProvider || null },
+          });
+          return;
+        }
+        this.remoteSessionAudit?.record({
+          sessionId: remoteSession.sessionId,
+          actor: member.clientId,
+          action:
+            outcome.status === "sent"
+              ? "push.sent"
+              : outcome.status === "failed"
+                ? "push.failed"
+                : "push.skipped",
+          detail: {
+            provider: member.pushProvider || null,
+            reason: outcome.reason || null,
+            error: outcome.error || null,
+          },
+        });
+      })
+      .catch(() => {
+        // Dispatcher never rejects, but guard anyway — a failed courtesy push
+        // must not surface as an unhandled rejection.
+      });
+  }
+
+  _attachRemoteSessionRelay() {
+    if (!this.remoteSessionRelay) return;
+    this.remoteSessionRelay.on("relay-message", (message) => {
+      this._handleRemoteRelayMessage(message).catch((error) => {
+        this.emit("client-error", {
+          clientId: "remote-session-relay",
+          error: error.message,
+        });
+      });
+    });
+    this.remoteSessionRelay.on("encrypted-message", ({ from, envelope }) => {
+      this._handleRemoteEncryptedControl(from, envelope).catch((error) => {
+        this.emit("client-error", { clientId: from, error: error.message });
+      });
+    });
+  }
+
+  async _handleRemoteRelayMessage(message) {
+    if (
+      message?.type !== "message" ||
+      message.payload?.type !== "remote-session.pair"
+    )
+      return;
+    const payload = message.payload;
+    const sessionId = payload.envelope?.sessionId;
+    const crypto = this.remoteSessionCrypto.get(sessionId);
+    const token = this.remoteSessionPairingSecrets.get(sessionId);
+    if (!crypto || !token)
+      throw new Error("Remote Session pairing is unavailable or expired");
+    crypto.pair(payload.mobilePeerId, payload.mobilePublicKey, token);
+    const join = crypto.decrypt(payload.envelope);
+    if (join.type !== "pair.join" || join.token !== token) {
+      throw new Error("Invalid encrypted Remote Session pairing request");
+    }
+    const relayMember = this.remoteSessions.join({
+      sessionId,
+      clientId: payload.mobilePeerId,
+      token: join.token,
+      via: "relay",
+      pushToken: join.pushToken,
+      pushProvider: join.pushProvider,
+    });
+    this.remoteSessionAudit?.record({
+      sessionId,
+      actor: payload.mobilePeerId,
+      action: "device.joined",
+      detail: {
+        via: "relay",
+        hasPush: relayMember?.member?.pushToken ? true : false,
+      },
+    });
+    this.remoteSessionPairingSecrets.delete(sessionId);
+    this.remoteSessionRelay.sendEncrypted(
+      payload.mobilePeerId,
+      crypto.encrypt(payload.mobilePeerId, {
+        type: "pair.accepted",
+        remoteSessionId: sessionId,
+      }),
+    );
+  }
+
+  async _handleRemoteEncryptedControl(from, envelope) {
+    const crypto = this.remoteSessionCrypto.get(envelope?.sessionId);
+    if (!crypto) throw new Error("Remote Session crypto context not found");
+    const event = crypto.decrypt(envelope);
+    const virtualWs = {
+      OPEN: 1,
+      readyState: 1,
+      send: (raw) => {
+        const response = JSON.parse(raw);
+        this.remoteSessionRelay.sendEncrypted(
+          from,
+          crypto.encrypt(from, response),
+        );
+      },
+    };
+    await handleRemoteSessionPublish(this, from, virtualWs, {
+      id: `remote-${Date.now()}`,
+      remoteSessionId: envelope.sessionId,
+      event,
+    });
+  }
+
   /** @private — broadcast a message to all connected, authenticated clients */
   _broadcast(data) {
     for (const [, client] of this.clients) {

package/src/harness/golden-transcript.js

@@ -0,0 +1,65 @@
+/**
+ * Normalize runtime events before comparing them with a golden transcript.
+ *
+ * Runtime envelopes intentionally contain volatile identity and timing fields.
+ * Golden files should describe observable behavior, not a particular run, so
+ * those fields are removed recursively and platform-specific workspace paths
+ * are replaced with a stable token.
+ */
+
+const VOLATILE_KEYS = new Set([
+  "eventId",
+  "id",
+  "requestId",
+  "sessionId",
+  "sequence",
+  "timestamp",
+  "createdAt",
+  "updatedAt",
+  "duration",
+  "durationMs",
+  "toolTelemetryRecord",
+]);
+
+function normalizeString(value, workspace) {
+  if (!workspace) return value;
+  const variants = new Set([
+    workspace,
+    workspace.replaceAll("\\", "/"),
+    workspace.replaceAll("/", "\\"),
+  ]);
+  let normalized = value;
+  for (const variant of variants) {
+    normalized = normalized.split(variant).join("<WORKSPACE>");
+  }
+  return normalized.replaceAll("<WORKSPACE>\\", "<WORKSPACE>/");
+}
+
+function normalizeValue(value, workspace) {
+  if (typeof value === "string") return normalizeString(value, workspace);
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue(item, workspace));
+  }
+  if (!value || typeof value !== "object") return value;
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => !VOLATILE_KEYS.has(key))
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => [key, normalizeValue(item, workspace)]),
+  );
+}
+
+/**
+ * @param {Array<object>} events
+ * @param {{workspace?: string, ignoredTypes?: string[]}} [options]
+ */
+export function normalizeGoldenTranscript(events, options = {}) {
+  if (!Array.isArray(events)) {
+    throw new TypeError("Golden transcript input must be an array");
+  }
+  const ignored = new Set(options.ignoredTypes || ["run-started", "run-ended"]);
+  return events
+    .filter((event) => !ignored.has(event?.type))
+    .map((event) => normalizeValue(event, options.workspace));
+}

package/src/harness/mcp-client.js

@@ -10,6 +10,7 @@
 
 import { spawn } from "child_process";
 import { EventEmitter } from "events";
+import { safeJsonParse } from "../lib/safe-json.js";
 
 /**
  * Injectable dependencies — overridable from tests.
@@ -1156,8 +1157,11 @@ export class MCPServerConfig {
     return {
       name: row.name,
       command: row.command || null,
-      args: JSON.parse(row.args || "[]"),
-      env: JSON.parse(row.env || "{}"),
+      // safeJsonParse, not bare JSON.parse: list()/getAutoConnect() map every
+      // row through here, so one corrupt cell must not take down the whole
+      // MCP server list (`|| "[]"` only guards NULL, not a corrupt non-empty string).
+      args: safeJsonParse(row.args, []),
+      env: safeJsonParse(row.env, {}),
       autoConnect: row.auto_connect === 1,
       url: row.url || null,
       transport:

package/src/harness/remote-session-audit-sink.js

@@ -0,0 +1,132 @@
+// Remote Session audit log — durable JSONL sink.
+//
+// Attaches to RemoteSessionAuditLog's `sink` seam to persist the (already
+// privacy-filtered) audit trail to a newline-delimited JSON file so it survives
+// a host restart for forensics. Each entry is one JSON line; the file is
+// size-bounded with simple rotation (audit.jsonl → audit.jsonl.1 → …) so it can
+// never grow unbounded. Reads tolerate a torn last line (crash mid-append) by
+// skipping any line that will not parse.
+//
+// Deliberately dependency-free (node:fs only) and injectable — a SQLite-backed
+// sink could implement the same { handler, readAll } shape later without
+// touching the audit log or its call sites.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024; // 5 MiB
+const DEFAULT_BACKUPS = 1;
+
+export class RemoteSessionAuditFileSink {
+  constructor(options = {}) {
+    if (!options.path) {
+      throw new Error("RemoteSessionAuditFileSink requires a path");
+    }
+    this.path = options.path;
+    this.maxBytes = options.maxBytes || DEFAULT_MAX_BYTES;
+    this.backups = Number.isInteger(options.backups)
+      ? options.backups
+      : DEFAULT_BACKUPS;
+    this.fs = options.fs || fs;
+    this._ensureDir();
+  }
+
+  _ensureDir() {
+    try {
+      this.fs.mkdirSync(path.dirname(this.path), { recursive: true });
+    } catch {
+      // Best effort — a later append will surface a real error if the dir is
+      // genuinely unwritable, and the audit log swallows sink throws anyway.
+    }
+  }
+
+  /** Bound function to pass as RemoteSessionAuditLog({ sink }). */
+  get handler() {
+    return (entry) => this.append(entry);
+  }
+
+  /** Append one entry as a JSON line, rotating first if it would overflow. */
+  append(entry) {
+    const line = `${JSON.stringify(entry)}\n`;
+    this._rotateIfNeeded(Buffer.byteLength(line, "utf8"));
+    this.fs.appendFileSync(this.path, line, "utf8");
+  }
+
+  _rotateIfNeeded(incomingBytes) {
+    let size = 0;
+    try {
+      size = this.fs.statSync(this.path).size;
+    } catch {
+      return; // No file yet — nothing to rotate.
+    }
+    if (size + incomingBytes <= this.maxBytes) return;
+    if (this.backups <= 0) {
+      // No history kept — truncate by removing the active file.
+      try {
+        this.fs.rmSync(this.path);
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    // Shift backups: .(<n-1>) → .(<n>), …, active → .1, dropping the oldest.
+    for (let i = this.backups; i >= 1; i -= 1) {
+      const src = i === 1 ? this.path : `${this.path}.${i - 1}`;
+      const dst = `${this.path}.${i}`;
+      try {
+        if (this.fs.existsSync(src)) this.fs.renameSync(src, dst);
+      } catch {
+        /* ignore a single failed rotation step */
+      }
+    }
+  }
+
+  /**
+   * Read persisted entries oldest-first across the active file and its backups.
+   * Corrupt/partial lines are skipped. `limit` keeps only the newest N.
+   */
+  readAll({ limit } = {}) {
+    const files = [];
+    for (let i = this.backups; i >= 1; i -= 1) files.push(`${this.path}.${i}`);
+    files.push(this.path);
+    const entries = [];
+    for (const file of files) {
+      let raw;
+      try {
+        raw = this.fs.readFileSync(file, "utf8");
+      } catch {
+        continue; // Missing backup slot — expected.
+      }
+      for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          entries.push(JSON.parse(trimmed));
+        } catch {
+          // Torn write (crash mid-append) or manual edit — skip the line.
+        }
+      }
+    }
+    if (limit && limit > 0 && entries.length > limit) {
+      return entries.slice(entries.length - limit);
+    }
+    return entries;
+  }
+
+  /**
+   * Build a sink from env, or null when no audit file is configured. Enable with
+   * CHAINLESSCHAIN_REMOTE_SESSION_AUDIT_FILE (path); tune the rotation ceiling
+   * with CHAINLESSCHAIN_REMOTE_SESSION_AUDIT_MAX_BYTES.
+   */
+  static fromEnv(env = {}, options = {}) {
+    const filePath = env.CHAINLESSCHAIN_REMOTE_SESSION_AUDIT_FILE;
+    if (!filePath) return null;
+    const maxBytes =
+      Number(env.CHAINLESSCHAIN_REMOTE_SESSION_AUDIT_MAX_BYTES) || undefined;
+    return new RemoteSessionAuditFileSink({
+      path: filePath,
+      maxBytes,
+      ...options,
+    });
+  }
+}

package/src/harness/remote-session-audit.js

@@ -0,0 +1,110 @@
+// Remote Session audit log.
+//
+// A bounded, in-memory, privacy-respecting audit trail for one CLI host process
+// — matched to the ephemeral (in-memory, 12h TTL) nature of remote sessions.
+// Captures WHO did WHAT and WHEN across a session's lifecycle and remote control
+// events, but deliberately does NOT record prompt/tool payloads (only shapes
+// like content length), keeping the trail useful for forensics without
+// hoarding session content. A pluggable `sink` seam lets a durable backend
+// (JSONL file, SQLite audit_log) be attached later without touching call sites.
+
+const DEFAULT_MAX_ENTRIES = 1000;
+
+export const REMOTE_SESSION_AUDIT_ACTIONS = Object.freeze([
+  "session.created",
+  "pairing-token.issued",
+  "device.joined",
+  "device.revoked",
+  "device.disconnected",
+  "session.closed",
+  "control.prompt",
+  "control.approval",
+  "control.interrupt",
+  "push.registered",
+  "push.sent",
+  "push.failed",
+  "push.skipped",
+  "push.unregistered",
+]);
+
+export class RemoteSessionAuditLog {
+  constructor(options = {}) {
+    this.now = options.now || Date.now;
+    this.maxEntries = options.maxEntries || DEFAULT_MAX_ENTRIES;
+    this.sink = typeof options.sink === "function" ? options.sink : null;
+    this.entries = [];
+    this.seq = 0;
+    // Hydrate from a durable sink so audit queries survive a host restart. The
+    // persisted entries are NOT re-written to the sink (they are already
+    // there); we only pre-fill the in-memory ring and carry the seq high-water
+    // forward so new entries stay strictly monotonic.
+    if (Array.isArray(options.initialEntries)) {
+      this._hydrate(options.initialEntries);
+    }
+  }
+
+  _hydrate(entries) {
+    const recent = entries.slice(-this.maxEntries);
+    for (const entry of recent) {
+      if (!entry || !entry.action) continue;
+      this.entries.push({ ...entry });
+      if (typeof entry.seq === "number" && entry.seq > this.seq) {
+        this.seq = entry.seq;
+      }
+    }
+  }
+
+  /**
+   * Append an audit entry. Never throws into the caller — a broken sink or bad
+   * argument must not take down the live session it is auditing.
+   */
+  record({ sessionId = null, actor = null, action, detail = null } = {}) {
+    if (!action) return null;
+    const entry = {
+      seq: (this.seq += 1),
+      timestamp: this.now(),
+      sessionId,
+      actor,
+      action,
+      detail: detail && typeof detail === "object" ? { ...detail } : detail,
+    };
+    this.entries.push(entry);
+    if (this.entries.length > this.maxEntries) {
+      this.entries.splice(0, this.entries.length - this.maxEntries);
+    }
+    if (this.sink) {
+      try {
+        this.sink(entry);
+      } catch {
+        // A durable-sink failure must not break the session being audited.
+      }
+    }
+    return entry;
+  }
+
+  /** Newest-first, optionally filtered by session and/or action. */
+  list({ sessionId, action, limit } = {}) {
+    let out = this.entries;
+    if (sessionId) out = out.filter((entry) => entry.sessionId === sessionId);
+    if (action) out = out.filter((entry) => entry.action === action);
+    out = [...out].reverse();
+    if (limit && limit > 0) out = out.slice(0, limit);
+    return out.map((entry) => ({ ...entry }));
+  }
+
+  stats(sessionId) {
+    const scope = sessionId
+      ? this.entries.filter((entry) => entry.sessionId === sessionId)
+      : this.entries;
+    const byAction = {};
+    for (const entry of scope) {
+      byAction[entry.action] = (byAction[entry.action] || 0) + 1;
+    }
+    return { total: scope.length, byAction };
+  }
+
+  clear() {
+    this.entries = [];
+    this.seq = 0;
+  }
+}