chainlesschain 0.162.147 → 0.162.149

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-senders.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/prompt-compressor.js

@@ -251,8 +251,25 @@ export class PromptCompressor {
       };
     }
 
+    // Pinned facts — a DETERMINISTIC fact-retention guarantee. A message marked
+    // `pinned:true` (or matched by an `options.isPinned` predicate) MUST survive
+    // compaction verbatim regardless of any strategy or the non-deterministic LLM
+    // summary. Every other retention here is positional (system / recent-N / last
+    // user) or summary-dependent, so an important fact that scrolls out of the
+    // recent window would otherwise survive only if the summary happens to keep
+    // it. We pull pins out BEFORE any strategy runs (so nothing can drop them),
+    // then re-insert them as a sticky block right after the system messages.
+    const isPinned =
+      typeof options.isPinned === "function"
+        ? options.isPinned
+        : (m) => m && (m.pinned === true || m._pin === true);
+    const pinned = messages.filter((m) => isPinned(m));
+    const working = pinned.length
+      ? messages.filter((m) => !isPinned(m))
+      : messages;
+
     const originalTokens = estimateMessagesTokens(messages);
-    let result = [...messages];
+    let result = [...working];
     const applied = [];
 
     if (feature("CONTEXT_SNIP")) {
@@ -288,6 +305,15 @@ export class PromptCompressor {
       }
     }
 
+    // Re-insert pinned facts verbatim (order preserved) right after the leading
+    // system messages, so they end up as a sticky facts block at the top.
+    if (pinned.length) {
+      const sys = result.filter((m) => m.role === "system");
+      const nonSys = result.filter((m) => m.role !== "system");
+      result = [...sys, ...pinned, ...nonSys];
+      applied.push("pinned");
+    }
+
     // Tool-pair repair (opt-in) — callers compacting tool-laden histories
     // (e.g. the headless agent loop) pass this so truncation/snip never leaves
     // an orphaned tool result or unanswered tool_call for a strict API.

package/src/harness/remote-command-ledger.js

@@ -0,0 +1,158 @@
+/**
+ * RemoteCommandLedger (Phase 5, Remote Control) — application-level idempotency
+ * + total ordering + device revocation for commands arriving from remote
+ * endpoints (terminal / web / mobile).
+ *
+ * The transport layer (remote-session-crypto) already rejects a replayed or
+ * out-of-order ENVELOPE within one connection — but a reconnect starts a fresh
+ * crypto session with a reset sequence baseline, so a command the client
+ * re-sends after a dropped ACK would sail through and EXECUTE A SECOND TIME. That
+ * is exactly the Phase 5 acceptance this guards: "断网恢复后不会重复执行工具调用".
+ *
+ * Guarantees:
+ *   - Idempotency: a command carries a stable `commandId`; the side effect runs
+ *     AT MOST ONCE. A re-delivered command returns its cached result flagged
+ *     `replayed` — it never re-executes.
+ *   - Total order: every applied command gets a monotonic `applyIndex`, so all
+ *     three endpoints agree on one order; `appliedSince(cursor)` lets a
+ *     reconnecting endpoint catch up deterministically.
+ *   - Revocation: a revoked device's commands are rejected (can't read/control).
+ *
+ * Pure + injectable clock → fully unit-testable without any transport/hardware.
+ */
+
+export class RemoteCommandLedger {
+  constructor({ now = () => Date.now(), revokedDevices = [] } = {}) {
+    this._now = typeof now === "function" ? now : () => now;
+    this._applied = new Map(); // commandId → { applyIndex, result, deviceId, ts }
+    this._order = []; // applyIndex → commandId (total order)
+    this._revoked = new Set(revokedDevices);
+    this._perDeviceSeq = new Map(); // deviceId → highest accepted seq
+  }
+
+  isRevoked(deviceId) {
+    return this._revoked.has(deviceId);
+  }
+
+  revokeDevice(deviceId) {
+    this._revoked.add(deviceId);
+  }
+
+  /**
+   * Apply a command idempotently. `execute` (async, side-effecting) runs AT MOST
+   * ONCE per commandId; a re-delivery returns the cached result without calling
+   * it again.
+   *
+   * @param {{commandId:string, deviceId:string, seq?:number, payload?:any}} command
+   * @param {(command)=>Promise<any>|any} execute
+   * @returns {Promise<{status:"applied"|"replayed"|"rejected", result?, reason?, applyIndex?}>}
+   */
+  async apply(command, execute) {
+    if (
+      !command ||
+      typeof command.commandId !== "string" ||
+      !command.commandId
+    ) {
+      return { status: "rejected", reason: "missing commandId" };
+    }
+    const { commandId, deviceId } = command;
+
+    // A revoked device can neither read nor control the session.
+    if (deviceId != null && this._revoked.has(deviceId)) {
+      return { status: "rejected", reason: "device revoked" };
+    }
+
+    // Idempotent replay: already applied → return the cached result, DO NOT
+    // re-run the side effect. This is the reconnect-safety guarantee.
+    const prior = this._applied.get(commandId);
+    if (prior) {
+      return {
+        status: "replayed",
+        result: prior.result,
+        applyIndex: prior.applyIndex,
+      };
+    }
+
+    // Optional per-device monotonic sequence check: a STALE seq (below what we've
+    // already accepted from this device) with a NEW commandId is a protocol
+    // violation (a genuine reconnect resends the SAME commandId, caught above).
+    if (
+      deviceId != null &&
+      Number.isFinite(command.seq) &&
+      this._perDeviceSeq.has(deviceId) &&
+      command.seq <= this._perDeviceSeq.get(deviceId)
+    ) {
+      return { status: "rejected", reason: "stale sequence" };
+    }
+
+    let result;
+    try {
+      result = await execute(command);
+    } catch (err) {
+      // A failed execution is NOT recorded as applied — the command may be
+      // retried (with the same commandId) and will run again. Surfacing the
+      // error lets the caller decide; idempotency only protects SUCCESSES.
+      return { status: "rejected", reason: `execute failed: ${err.message}` };
+    }
+
+    const applyIndex = this._order.length;
+    this._applied.set(commandId, {
+      applyIndex,
+      result,
+      deviceId,
+      ts: this._now(),
+    });
+    this._order.push(commandId);
+    if (deviceId != null && Number.isFinite(command.seq)) {
+      this._perDeviceSeq.set(deviceId, command.seq);
+    }
+    return { status: "applied", result, applyIndex };
+  }
+
+  /**
+   * The ordered tail of applied commands after `cursor` (an applyIndex), so a
+   * reconnecting endpoint can replay missed state in the one agreed order.
+   * @returns {Array<{applyIndex, commandId, result, deviceId}>}
+   */
+  appliedSince(cursor = -1) {
+    const out = [];
+    for (let i = cursor + 1; i < this._order.length; i++) {
+      const commandId = this._order[i];
+      const rec = this._applied.get(commandId);
+      out.push({
+        applyIndex: i,
+        commandId,
+        result: rec.result,
+        deviceId: rec.deviceId,
+      });
+    }
+    return out;
+  }
+
+  /** Highest assigned applyIndex (−1 when nothing applied). */
+  cursor() {
+    return this._order.length - 1;
+  }
+
+  appliedCount() {
+    return this._order.length;
+  }
+
+  snapshot() {
+    return {
+      order: [...this._order],
+      applied: Array.from(this._applied.entries()),
+      revoked: Array.from(this._revoked),
+      perDeviceSeq: Array.from(this._perDeviceSeq.entries()),
+    };
+  }
+
+  static restore(snap, { now = () => Date.now() } = {}) {
+    const l = new RemoteCommandLedger({ now });
+    l._order = [...(snap?.order || [])];
+    l._applied = new Map(snap?.applied || []);
+    l._revoked = new Set(snap?.revoked || []);
+    l._perDeviceSeq = new Map(snap?.perDeviceSeq || []);
+    return l;
+  }
+}