chainlesschain 0.162.180 → 0.162.181

package/src/lib/background-interaction-journal.js

@@ -0,0 +1,407 @@
+/**
+ * Durable pending/settlement journal for background human interactions.
+ *
+ * Each mutation appends a full snapshot to the session's tamper-evident JSONL
+ * transcript. The worker persists a terminal settlement before delivering it
+ * to the suspended child, so retries can be classified as the same idempotent
+ * answer or a conflicting second settlement even after a process restart.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  appendEvent as storeAppendEvent,
+  readEvents as storeReadEvents,
+} from "../harness/jsonl-session-store.js";
+import {
+  normalizeInteractionBinding,
+  sameInteractionBinding,
+} from "./interaction-binding.js";
+
+export const BACKGROUND_INTERACTION_JOURNAL_EVENT =
+  "background_interaction_journal";
+export const BACKGROUND_INTERACTION_JOURNAL_VERSION = 1;
+export const MAX_BACKGROUND_INTERACTION_RECORDS = 256;
+
+const TERMINAL_STATUSES = new Set(["resolved", "rejected", "cancelled"]);
+
+export const _deps = {
+  appendEvent: storeAppendEvent,
+  readEvents: storeReadEvents,
+};
+
+function journalError(message, code, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function cloneJson(value) {
+  if (value === undefined) return null;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function canonicalize(value) {
+  if (value === undefined) return "__undefined__";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalize(entry)).join(",")}]`;
+  }
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`)
+    .join(",")}}`;
+}
+
+function fingerprint(value) {
+  return createHash("sha256").update(canonicalize(value)).digest("hex");
+}
+
+function normalizeError(error, fallbackCode = "INTERACTION_REJECTED") {
+  if (!error) return null;
+  if (typeof error === "string") {
+    return { code: fallbackCode, message: error };
+  }
+  return {
+    code: String(error.code || fallbackCode),
+    message: String(error.message || error),
+  };
+}
+
+function normalizeSettlement(outcome = {}) {
+  const status = String(outcome.status || "");
+  if (!TERMINAL_STATUSES.has(status)) {
+    throw journalError(
+      `Invalid background interaction settlement status: ${status || "<missing>"}`,
+      "INTERACTION_SETTLEMENT_INVALID",
+    );
+  }
+  return {
+    status,
+    answer: status === "resolved" ? cloneJson(outcome.answer) : null,
+    error:
+      status === "resolved"
+        ? null
+        : normalizeError(
+            outcome.error,
+            status === "cancelled"
+              ? "INTERACTION_CANCELLED"
+              : "INTERACTION_REJECTED",
+          ),
+  };
+}
+
+export class BackgroundInteractionJournal {
+  constructor(options = {}) {
+    this.backgroundAgentId = String(options.backgroundAgentId || "");
+    if (!this.backgroundAgentId) {
+      throw journalError(
+        "backgroundAgentId is required for the interaction journal",
+        "INTERACTION_JOURNAL_INVALID",
+      );
+    }
+    this._now = options.now || Date.now;
+    this.records = [];
+  }
+
+  static fromJSON(snapshot, options = {}) {
+    if (
+      !snapshot ||
+      snapshot.version !== BACKGROUND_INTERACTION_JOURNAL_VERSION ||
+      typeof snapshot.backgroundAgentId !== "string" ||
+      !Array.isArray(snapshot.records)
+    ) {
+      throw journalError(
+        "Invalid background interaction journal snapshot",
+        "INTERACTION_JOURNAL_CORRUPT",
+      );
+    }
+    const journal = new BackgroundInteractionJournal({
+      backgroundAgentId: snapshot.backgroundAgentId,
+      now: options.now,
+    });
+    journal.records = snapshot.records.map((record) => ({
+      requestId: String(record.requestId || ""),
+      binding: normalizeInteractionBinding(record.binding),
+      payload: cloneJson(record.payload || {}),
+      payloadFingerprint: String(record.payloadFingerprint || ""),
+      status: String(record.status || "pending"),
+      createdAt: Number(record.createdAt) || 0,
+      settledAt: record.settledAt == null ? null : Number(record.settledAt),
+      settlement: record.settlement ? cloneJson(record.settlement) : null,
+      settlementFingerprint: record.settlementFingerprint
+        ? String(record.settlementFingerprint)
+        : null,
+    }));
+    return journal;
+  }
+
+  toJSON() {
+    return {
+      version: BACKGROUND_INTERACTION_JOURNAL_VERSION,
+      backgroundAgentId: this.backgroundAgentId,
+      records: cloneJson(this.records),
+    };
+  }
+
+  get(requestId) {
+    return (
+      this.records.find((record) => record.requestId === String(requestId)) ||
+      null
+    );
+  }
+
+  pending() {
+    return this.records.filter((record) => record.status === "pending");
+  }
+
+  recordPending({ requestId, binding, payload = {}, createdAt } = {}) {
+    const id = String(requestId || "");
+    const normalizedBinding = normalizeInteractionBinding(binding);
+    if (!id || normalizedBinding.sequence === null) {
+      throw journalError(
+        "A requestId and complete interaction binding are required",
+        "INTERACTION_REQUEST_INVALID",
+      );
+    }
+    const safePayload = cloneJson(payload);
+    const payloadFingerprint = fingerprint(safePayload);
+    const existing = this.get(id);
+    if (existing) {
+      if (
+        sameInteractionBinding(existing.binding, normalizedBinding) &&
+        existing.payloadFingerprint === payloadFingerprint
+      ) {
+        return { applied: false, record: cloneJson(existing) };
+      }
+      throw journalError(
+        `Interaction request ${id} was replayed with different binding or payload`,
+        "INTERACTION_REQUEST_CONFLICT",
+        { requestId: id },
+      );
+    }
+
+    const record = {
+      requestId: id,
+      binding: normalizedBinding,
+      payload: safePayload,
+      payloadFingerprint,
+      status: "pending",
+      createdAt: Number(createdAt) || this._now(),
+      settledAt: null,
+      settlement: null,
+      settlementFingerprint: null,
+    };
+    this.records.push(record);
+    this._prune();
+    return { applied: true, record: cloneJson(record) };
+  }
+
+  settle(requestId, binding, outcome = {}) {
+    const id = String(requestId || "");
+    const record = this.get(id);
+    if (!record) {
+      throw journalError(
+        `Unknown background interaction request: ${id || "<missing>"}`,
+        "INTERACTION_REQUEST_UNKNOWN",
+        { requestId: id },
+      );
+    }
+    if (!sameInteractionBinding(record.binding, binding)) {
+      throw journalError(
+        `Interaction response binding does not match request ${id}`,
+        "INTERACTION_BINDING_MISMATCH",
+        { requestId: id },
+      );
+    }
+    const settlement = normalizeSettlement(outcome);
+    const settlementFingerprint = fingerprint(settlement);
+    if (record.status !== "pending") {
+      if (record.settlementFingerprint === settlementFingerprint) {
+        return { applied: false, record: cloneJson(record) };
+      }
+      throw journalError(
+        `Interaction request ${id} is already settled`,
+        "INTERACTION_ALREADY_SETTLED",
+        { requestId: id, status: record.status },
+      );
+    }
+
+    record.status = settlement.status;
+    record.settledAt = this._now();
+    record.settlement = settlement;
+    record.settlementFingerprint = settlementFingerprint;
+    return { applied: true, record: cloneJson(record) };
+  }
+
+  rejectPending(error = {}) {
+    const rejected = [];
+    for (const record of this.pending()) {
+      const result = this.settle(record.requestId, record.binding, {
+        status: "rejected",
+        error,
+      });
+      rejected.push(result.record);
+    }
+    return rejected;
+  }
+
+  _prune() {
+    while (this.records.length > MAX_BACKGROUND_INTERACTION_RECORDS) {
+      const terminalIndex = this.records.findIndex((record) =>
+        TERMINAL_STATUSES.has(record.status),
+      );
+      if (terminalIndex === -1) {
+        throw journalError(
+          `Background interaction journal exceeded ${MAX_BACKGROUND_INTERACTION_RECORDS} pending requests`,
+          "INTERACTION_PENDING_LIMIT",
+        );
+      }
+      this.records.splice(terminalIndex, 1);
+    }
+  }
+}
+
+export class BackgroundInteractionPersistenceError extends Error {
+  constructor(operation, sessionId, cause) {
+    const detail =
+      cause?.message || String(cause || "unknown persistence error");
+    super(
+      `Background interaction journal ${operation} failed for ${sessionId}: ${detail}`,
+      { cause },
+    );
+    this.name = "BackgroundInteractionPersistenceError";
+    this.code =
+      operation === "read"
+        ? "INTERACTION_JOURNAL_READ_FAILED"
+        : "INTERACTION_JOURNAL_PERSIST_FAILED";
+    this.operation = operation;
+    this.sessionId = sessionId;
+  }
+}
+
+export function persistBackgroundInteractionJournal(
+  sessionId,
+  journal,
+  options = {},
+) {
+  const failIfUnavailable = options.failIfUnavailable !== false;
+  try {
+    if (!sessionId || !(journal instanceof BackgroundInteractionJournal)) {
+      throw new TypeError("sessionId and interaction journal are required");
+    }
+    _deps.appendEvent(
+      sessionId,
+      BACKGROUND_INTERACTION_JOURNAL_EVENT,
+      journal.toJSON(),
+    );
+    return true;
+  } catch (error) {
+    if (!failIfUnavailable) return false;
+    throw new BackgroundInteractionPersistenceError(
+      "write",
+      sessionId || "<missing-session>",
+      error,
+    );
+  }
+}
+
+export function loadBackgroundInteractionJournal(
+  sessionId,
+  backgroundAgentId,
+  options = {},
+) {
+  const failIfUnavailable = options.failIfUnavailable !== false;
+  try {
+    if (!sessionId || !backgroundAgentId) {
+      throw new TypeError("sessionId and backgroundAgentId are required");
+    }
+    const events = _deps.readEvents(sessionId) || [];
+    for (let index = events.length - 1; index >= 0; index--) {
+      const event = events[index];
+      if (
+        event?.type === BACKGROUND_INTERACTION_JOURNAL_EVENT &&
+        event.data?.backgroundAgentId === backgroundAgentId
+      ) {
+        return BackgroundInteractionJournal.fromJSON(event.data, options);
+      }
+    }
+    return new BackgroundInteractionJournal({
+      backgroundAgentId,
+      now: options.now,
+    });
+  } catch (error) {
+    if (!failIfUnavailable) {
+      return new BackgroundInteractionJournal({
+        backgroundAgentId,
+        now: options.now,
+      });
+    }
+    throw new BackgroundInteractionPersistenceError(
+      "read",
+      sessionId || "<missing-session>",
+      error,
+    );
+  }
+}
+
+/**
+ * Clone-mutate-persist transaction. The live journal is not changed when the
+ * append fails, so a caller may safely retry the same settlement.
+ */
+export function updateBackgroundInteractionJournal(
+  sessionId,
+  journal,
+  mutate,
+  options = {},
+) {
+  const draft = BackgroundInteractionJournal.fromJSON(journal.toJSON(), {
+    now: options.now || journal._now,
+  });
+  const result = mutate(draft);
+  if (!options.persistIf || options.persistIf(result) !== false) {
+    persistBackgroundInteractionJournal(sessionId, draft, options);
+  }
+  return { journal: draft, result };
+}
+
+/**
+ * Recovery entry point used when a worker is observed lost or starts again.
+ * An optional state-file fallback lets pre-journal pendingQuestion records be
+ * imported once and deterministically rejected.
+ */
+export function rejectPendingBackgroundInteractions(
+  sessionId,
+  backgroundAgentId,
+  options = {},
+) {
+  let journal = loadBackgroundInteractionJournal(
+    sessionId,
+    backgroundAgentId,
+    options,
+  );
+  const fallback = options.fallbackRequest;
+  const hasFallback =
+    fallback?.requestId &&
+    normalizeInteractionBinding(fallback.binding).sequence !== null &&
+    !journal.get(fallback.requestId);
+  if (!journal.pending().length && !hasFallback) {
+    return { journal, rejected: [], changed: false };
+  }
+  const mutation = updateBackgroundInteractionJournal(
+    sessionId,
+    journal,
+    (draft) => {
+      if (hasFallback) draft.recordPending(fallback);
+      return draft.rejectPending({
+        code: options.code || "INTERACTION_WORKER_LOST",
+        message:
+          options.message ||
+          "The background worker exited before the interaction settled",
+      });
+    },
+    options,
+  );
+  journal = mutation.journal;
+  return { journal, rejected: mutation.result, changed: true };
+}

package/src/lib/background-interaction-resolver.js

@@ -13,6 +13,16 @@
  */
 
 import { randomUUID } from "node:crypto";
+import {
+  hasCompleteInteractionBinding,
+  normalizeInteractionBinding,
+  sameInteractionBinding,
+} from "./interaction-binding.js";
+
+export {
+  normalizeInteractionBinding,
+  sameInteractionBinding,
+} from "./interaction-binding.js";
 
 export const BACKGROUND_INTERACTION_PROTOCOL_VERSION = 1;
 export const DEFAULT_BACKGROUND_INTERACTION_TIMEOUT_MS = 60_000;
@@ -30,31 +40,6 @@ function asNullableString(value) {
   return String(value);
 }
 
-function normalizeBinding(binding = {}) {
-  return {
-    backgroundAgentId: asNullableString(binding.backgroundAgentId),
-    sessionId: asNullableString(binding.sessionId),
-    turnId: asNullableString(binding.turnId),
-    toolUseId: asNullableString(binding.toolUseId),
-    sequence:
-      Number.isSafeInteger(binding.sequence) && binding.sequence > 0
-        ? binding.sequence
-        : null,
-  };
-}
-
-function sameBinding(left, right) {
-  const a = normalizeBinding(left);
-  const b = normalizeBinding(right);
-  return (
-    a.backgroundAgentId === b.backgroundAgentId &&
-    a.sessionId === b.sessionId &&
-    a.turnId === b.turnId &&
-    a.toolUseId === b.toolUseId &&
-    a.sequence === b.sequence
-  );
-}
-
 function validRequest(message) {
   return (
     message &&
@@ -65,12 +50,16 @@ function validRequest(message) {
     message.requestId.length <= 256 &&
     message.payload &&
     typeof message.payload === "object" &&
-    normalizeBinding(message.binding).sequence !== null
+    hasCompleteInteractionBinding(message.binding)
   );
 }
 
 function sendIpc(target, message, onError = () => {}) {
-  if (!target || typeof target.send !== "function" || target.connected === false)
+  if (
+    !target ||
+    typeof target.send !== "function" ||
+    target.connected === false
+  )
     return false;
   try {
     target.send(message, (error) => {
@@ -138,7 +127,8 @@ export function createBackgroundInteractionClient(options = {}) {
       return;
     }
     const entry = pending.get(message.requestId);
-    if (!entry || !sameBinding(entry.binding, message.binding)) return;
+    if (!entry || !sameInteractionBinding(entry.binding, message.binding))
+      return;
 
     if (message.status === "resolved") {
       settle(entry, entry.resolve, message.answer);
@@ -170,7 +160,7 @@ export function createBackgroundInteractionClient(options = {}) {
 
       sequence += 1;
       const requestId = `${backgroundAgentId}:${idFactory()}`;
-      const binding = normalizeBinding({
+      const binding = normalizeInteractionBinding({
         backgroundAgentId,
         sessionId: payload.sessionId ?? sessionId,
         turnId: payload.turnId ?? turnId,
@@ -301,7 +291,7 @@ export function attachInteractionRequestHandler(
       protocolVersion: BACKGROUND_INTERACTION_PROTOCOL_VERSION,
       requestId:
         typeof message?.requestId === "string" ? message.requestId : "",
-      binding: normalizeBinding(message?.binding),
+      binding: normalizeInteractionBinding(message?.binding),
       status: "rejected",
       error: { code, message: detail },
     };
@@ -315,7 +305,7 @@ export function attachInteractionRequestHandler(
       message.protocolVersion === BACKGROUND_INTERACTION_PROTOCOL_VERSION
     ) {
       const active = inflight.get(message.requestId);
-      if (active && sameBinding(active.binding, message.binding)) {
+      if (active && sameInteractionBinding(active.binding, message.binding)) {
         inflight.delete(message.requestId);
         active.controller.abort(message.reason || "cancelled");
       }
@@ -331,12 +321,11 @@ export function attachInteractionRequestHandler(
       return;
     }
 
-    const binding = normalizeBinding(message.binding);
+    const binding = normalizeInteractionBinding(message.binding);
     const expectedAgentId = asNullableString(options.backgroundAgentId);
     const expectedSessionId = asNullableString(options.sessionId);
     if (
-      (expectedAgentId &&
-        binding.backgroundAgentId !== expectedAgentId) ||
+      (expectedAgentId && binding.backgroundAgentId !== expectedAgentId) ||
       (expectedSessionId && binding.sessionId !== expectedSessionId)
     ) {
       rejectRequest(

package/src/lib/background-session-transport.js

@@ -198,7 +198,8 @@ export function startBackgroundSessionServer(opts) {
             case "interaction_response": {
               try {
                 // Support both field names: requestId (client) and intId (wire legacy)
-                const { requestId, intId, answer, result, error } = message;
+                const { requestId, intId, binding, answer, result, error } =
+                  message;
                 const resolvedId = requestId || intId;
                 if (!resolvedId) {
                   writeMessage(socket, {
@@ -208,14 +209,23 @@ export function startBackgroundSessionServer(opts) {
                   return;
                 }
                 // Single-object callback matching worker expectation: { requestId, answer, error }
-                onInteractionResponse?.({
+                const settlement = onInteractionResponse?.({
                   requestId: resolvedId,
+                  binding,
                   answer: answer ?? result,
                   error,
                 });
                 writeMessage(socket, {
                   type: "received",
                   requestId: resolvedId,
+                  accepted:
+                    typeof settlement === "object"
+                      ? settlement.accepted === true
+                      : settlement === true,
+                  duplicate:
+                    typeof settlement === "object"
+                      ? settlement.duplicate === true
+                      : false,
                 });
               } catch (err) {
                 writeMessage(socket, {

package/src/lib/capability-manifest.js

@@ -49,6 +49,14 @@ export const CAPABILITY_MANIFEST = Object.freeze({
       description:
         'tool_use / tool_result lines carry a pairing `id` ("tu-<n>")',
     }),
+    Object.freeze({
+      key: "permission_decision",
+      field: "permission_decision",
+      companionFields: Object.freeze(["permission_decision_id"]),
+      minVersion: 1,
+      description:
+        "gated tool_result lines may carry a redacted permission decision and its correlation id",
+    }),
     Object.freeze({
       key: "trace_id",
       field: "trace_id",
@@ -135,6 +143,24 @@ export function toFieldGate(m = CAPABILITY_MANIFEST) {
   return out;
 }
 
+/**
+ * Every negotiable line field → the primary gate field that controls it.
+ * Companion fields are kept under the same logical feature so negotiation can
+ * never emit a decision without its id (or an orphan id without its decision).
+ * @returns {Record<string, string>}
+ */
+export function toGateableFieldGate(m = CAPABILITY_MANIFEST) {
+  const out = {};
+  for (const f of wireFeaturesOf(m)) {
+    if (!f?.field) continue;
+    out[f.field] = f.field;
+    for (const companion of f.companionFields || []) {
+      if (companion) out[companion] = f.field;
+    }
+  }
+  return out;
+}
+
 /**
  * The server negotiation offer shape consumed by
  * capability-negotiation.js `negotiateProtocol(server, …)`.
@@ -199,7 +225,12 @@ export function capabilityDigest(m = CAPABILITY_MANIFEST) {
     protocolVersion: Number(mm.protocolVersion) || 1,
     minProtocolVersion: Number(mm.minProtocolVersion) || 1,
     wire: wireFeaturesOf(mm)
-      .map((f) => [f.key, f.field, Number(f.minVersion) || 1])
+      .map((f) => [
+        f.key,
+        f.field,
+        [...(f.companionFields || [])].sort(),
+        Number(f.minVersion) || 1,
+      ])
       .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)),
     runtime: [...(mm.runtimeFeatures || [])].sort(),
     mcp: [...(mm.mcpFeatures || [])].sort(),
@@ -224,7 +255,7 @@ export function renderBehaviorMatrix(m = CAPABILITY_MANIFEST) {
   return wireFeaturesOf(m).map((f) => ({
     feature: f.key,
     minVersion: Number(f.minVersion) || 1,
-    field: f.field,
+    field: [f.field, ...(f.companionFields || [])].join(", "),
     negotiable: true,
     description: String(f.description || ""),
   }));
@@ -280,6 +311,7 @@ export function diffCapabilities(prev, next = CAPABILITY_MANIFEST) {
     for (const f of wireFeaturesOf(m)) {
       out.set(f.key, {
         field: f.field,
+        companionFields: [...(f.companionFields || [])].sort(),
         minVersion: Number(f.minVersion) || 1,
       });
     }
@@ -294,7 +326,13 @@ export function diffCapabilities(prev, next = CAPABILITY_MANIFEST) {
   const changedWireFeatures = [];
   for (const [key, nv] of n) {
     const pv = p.get(key);
-    if (pv && (pv.field !== nv.field || pv.minVersion !== nv.minVersion)) {
+    if (
+      pv &&
+      (pv.field !== nv.field ||
+        pv.minVersion !== nv.minVersion ||
+        JSON.stringify(pv.companionFields) !==
+          JSON.stringify(nv.companionFields))
+    ) {
       changedWireFeatures.push({ feature: key, from: pv, to: nv });
     }
   }

package/src/lib/capability-negotiation.js

@@ -210,7 +210,7 @@ const FEATURE_TO_FIELD = toFieldGate();
  * baseline). Mutates `gate` in place and returns it.
  *
  * @param {{features:string[], ok:boolean}} result
- * @param {{seq?:boolean, trace_id?:boolean, tool_use_id?:boolean}} gate
+ * @param {{seq?:boolean, trace_id?:boolean, tool_use_id?:boolean, permission_decision?:boolean}} gate
  */
 export function applyNegotiationToGate(result, gate = {}) {
   if (!result || result.ok === false) return gate;