chainlesschain 0.162.188 → 0.162.193

package/src/harness/session-list-index.js

@@ -0,0 +1,254 @@
+/**
+ * Rebuildable metadata index for append-only JSONL sessions.
+ *
+ * Each transcript owns a tiny `<id>.meta.json` snapshot. A global reverse-read
+ * activity journal points at the newest snapshots, so `session list --limit N`
+ * reads O(N recent sessions) instead of every transcript body. The transcript
+ * remains the content authority; both index layers may be deleted and rebuilt.
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { iterateFileLinesReverseSync } from "../lib/file-lines.js";
+import { ensurePrivateFile } from "../lib/secure-fs.js";
+
+export const SESSION_INDEX_SCHEMA = 2;
+export const SESSION_INDEX_FILE = ".sessions-index-v2.ndjson";
+
+// Used only by an opted-in child in the independent session-scale crash gate.
+// Keeping the injection immediately around the production sidecar/journal
+// boundary makes that gate deterministic without replacing either write.
+export const _sessionScaleFaultHooks = Object.seal({
+  afterMetaSnapshot: null,
+});
+
+function runSessionScaleFaultHook(name, payload) {
+  if (process.env.CC_SESSION_SCALE_FAULT_INJECTION !== "1") return;
+  const hook = _sessionScaleFaultHooks[name];
+  if (typeof hook === "function") hook(payload);
+}
+
+export function sessionMetaPath(dir, sessionId) {
+  return join(dir, `${sessionId}.meta.json`);
+}
+
+export function sessionIndexPath(dir) {
+  return join(dir, SESSION_INDEX_FILE);
+}
+
+export function emptySessionMeta(sessionId) {
+  return {
+    schema: SESSION_INDEX_SCHEMA,
+    id: sessionId,
+    title: "Untitled",
+    provider: "",
+    model: "",
+    message_count: 0,
+    event_count: 0,
+    created_at_ms: 0,
+    updated_at_ms: 0,
+    last_hash: null,
+    deleted: false,
+  };
+}
+
+export function readSessionMeta(dir, sessionId) {
+  const filePath = sessionMetaPath(dir, sessionId);
+  if (!existsSync(filePath)) return null;
+  try {
+    const value = JSON.parse(readFileSync(filePath, "utf8"));
+    return value?.schema === SESSION_INDEX_SCHEMA && value?.id === sessionId
+      ? value
+      : null;
+  } catch {
+    // A sidecar interrupted mid-write is discarded and streamed from the
+    // authoritative transcript on the next list/search operation.
+    return null;
+  }
+}
+
+export function applyEventToSessionMeta(meta, event, lastHash) {
+  const next = { ...(meta || emptySessionMeta("")) };
+  next.schema = SESSION_INDEX_SCHEMA;
+  next.deleted = false;
+  next.event_count = Math.max(0, Number(next.event_count) || 0) + 1;
+  const timestamp = Number(event?.timestamp);
+  if (Number.isFinite(timestamp)) {
+    if (!next.created_at_ms) next.created_at_ms = timestamp;
+    next.updated_at_ms = Math.max(next.updated_at_ms || 0, timestamp);
+  }
+  if (event?.type === "session_start") {
+    next.title = event.data?.title || next.title || "Untitled";
+    next.provider = event.data?.provider || "";
+    next.model = event.data?.model || "";
+  } else if (event?.type === "session_rename" && event.data?.title) {
+    next.title = String(event.data.title);
+  } else if (
+    event?.type === "user_message" ||
+    event?.type === "assistant_message"
+  ) {
+    next.message_count = Math.max(0, Number(next.message_count) || 0) + 1;
+  } else if (
+    event?.type === "ws_turn" &&
+    event.data?.schemaVersion === 1 &&
+    event.data?.outcome === "completed" &&
+    event.data?.user?.role === "user" &&
+    event.data?.assistant?.role === "assistant"
+  ) {
+    next.message_count = Math.max(0, Number(next.message_count) || 0) + 2;
+  }
+  next.last_hash = typeof lastHash === "string" ? lastHash : null;
+  return next;
+}
+
+function writeMetaSnapshot(dir, meta) {
+  const filePath = sessionMetaPath(dir, meta.id);
+  // The owning transcript lock serializes this derived snapshot. It need not
+  // use a second temp+rename protocol: interruption can only corrupt a cache,
+  // which readSessionMeta rejects and rebuildSessionMeta regenerates.
+  writeFileSync(filePath, `${JSON.stringify(meta)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  ensurePrivateFile(filePath);
+}
+
+function appendActivity(dir, meta) {
+  const filePath = sessionIndexPath(dir);
+  // One compact line is emitted through one O_APPEND write. The journal is a
+  // disposable ordering hint (the per-session sidecar and transcript remain
+  // authoritative). Prefixing the record with a newline isolates any
+  // crash-partial physical tail before publishing the next valid snapshot;
+  // reverse readers already skip the resulting empty lines. Avoiding a second
+  // global directory lock keeps concurrent transcript appends from serializing
+  // on derived metadata.
+  appendFileSync(filePath, `\n${JSON.stringify(meta)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  ensurePrivateFile(filePath);
+}
+
+/** Called while the owning transcript lock is held. */
+export function recordSessionEvent(dir, sessionId, event, lastHash) {
+  const current =
+    readSessionMeta(dir, sessionId) || emptySessionMeta(sessionId);
+  current.id = sessionId;
+  const next = applyEventToSessionMeta(current, event, lastHash);
+  writeMetaSnapshot(dir, next);
+  runSessionScaleFaultHook("afterMetaSnapshot", {
+    dir,
+    sessionId,
+    event,
+    meta: next,
+  });
+  appendActivity(dir, next);
+  return next;
+}
+
+export function replaceSessionMeta(dir, meta) {
+  const normalized = { ...emptySessionMeta(meta.id), ...meta };
+  writeMetaSnapshot(dir, normalized);
+  appendActivity(dir, normalized);
+  return normalized;
+}
+
+/** Re-emit an existing snapshot only to the global activity order. */
+export function recordSessionActivity(dir, meta) {
+  const normalized = { ...emptySessionMeta(meta.id), ...meta };
+  appendActivity(dir, normalized);
+  return normalized;
+}
+
+export function recordSessionDeleted(dir, sessionId, timestamp = Date.now()) {
+  const current =
+    readSessionMeta(dir, sessionId) || emptySessionMeta(sessionId);
+  const tombstone = {
+    ...current,
+    updated_at_ms: timestamp,
+    deleted: true,
+  };
+  writeMetaSnapshot(dir, tombstone);
+  appendActivity(dir, tombstone);
+  return tombstone;
+}
+
+/** Newest journal snapshot for one session, or null if none survived. */
+export function readLatestSessionActivity(dir, sessionId) {
+  const filePath = sessionIndexPath(dir);
+  if (!existsSync(filePath) || typeof sessionId !== "string") return null;
+  for (const { line } of iterateFileLinesReverseSync(filePath)) {
+    try {
+      const meta = JSON.parse(line);
+      if (meta?.schema === SESSION_INDEX_SCHEMA && meta.id === sessionId) {
+        return meta;
+      }
+    } catch {
+      // A crash-partial tail is not an activity snapshot.
+    }
+  }
+  return null;
+}
+
+function iso(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) return "";
+  try {
+    return new Date(number).toISOString();
+  } catch {
+    return "";
+  }
+}
+
+export function publicSessionMeta(meta) {
+  return {
+    id: meta.id,
+    title: meta.title || "Untitled",
+    provider: meta.provider || "",
+    model: meta.model || "",
+    message_count: Math.max(0, Number(meta.message_count) || 0),
+    created_at: iso(meta.created_at_ms),
+    updated_at: iso(meta.updated_at_ms),
+  };
+}
+
+/**
+ * Read the activity journal newest-first and return the first record seen for
+ * each session. This is the latest snapshot because every metadata mutation
+ * appends after its sidecar commit.
+ */
+export function listIndexedSessions(
+  dir,
+  { limit = 20, hasSession = () => true } = {},
+) {
+  const filePath = sessionIndexPath(dir);
+  if (!existsSync(filePath)) return [];
+  const wanted = Math.max(0, Number(limit) || 0);
+  const seen = new Set();
+  const result = [];
+  for (const { line } of iterateFileLinesReverseSync(filePath)) {
+    let meta;
+    try {
+      meta = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (
+      meta?.schema !== SESSION_INDEX_SCHEMA ||
+      typeof meta.id !== "string" ||
+      seen.has(meta.id)
+    ) {
+      continue;
+    }
+    seen.add(meta.id);
+    if (meta.deleted || !hasSession(meta.id)) continue;
+    result.push(publicSessionMeta(meta));
+    if (wanted > 0 && result.length >= wanted) break;
+  }
+  return result;
+}

package/src/harness/structured-handoff.js

@@ -0,0 +1,410 @@
+/**
+ * Canonical, bounded handoff shared by compaction, checkpoint summaries, and
+ * parent-to-child agent context. The field order is part of the wire format.
+ */
+
+import { projectCanonicalResumeMessages } from "../lib/session-message-provenance.js";
+
+export const STRUCTURED_HANDOFF_FIELDS = Object.freeze([
+  "objective",
+  "constraints",
+  "keyDecisions",
+  "changedFiles",
+  "tests",
+  "unresolvedSideEffects",
+  "checkpoints",
+  "blockers",
+  "nextSteps",
+]);
+
+const ARRAY_FIELDS = STRUCTURED_HANDOFF_FIELDS.slice(1);
+const DEFAULT_MAX_CONTENT_CHARS = 32_000;
+const DEFAULT_MAX_ITEMS_PER_FIELD = 12;
+const DEFAULT_MAX_ITEM_CHARS = 1_000;
+const DEFAULT_MAX_FALLBACK_SOURCE_CHARS = 24_000;
+
+export class StructuredHandoffValidationError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "StructuredHandoffValidationError";
+    this.code = code;
+  }
+}
+
+function boundedInteger(value, fallback, minimum, maximum) {
+  const number = Math.floor(Number(value));
+  if (!Number.isFinite(number) || number <= 0) return fallback;
+  return Math.min(Math.max(number, minimum), maximum);
+}
+
+function normalizeText(value) {
+  return String(value ?? "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/[ \t]+/g, " ")
+    .replace(/ *\n */g, "\n")
+    .trim();
+}
+
+function truncateText(value, maxChars) {
+  const text = normalizeText(value);
+  if (text.length <= maxChars) return text;
+  if (maxChars <= 1) return text.slice(0, maxChars);
+  return `${text.slice(0, maxChars - 1).trimEnd()}…`;
+}
+
+function contentText(message) {
+  if (typeof message?.content === "string") return message.content;
+  if (message?.content == null) return "";
+  try {
+    return JSON.stringify(message.content);
+  } catch {
+    return String(message.content);
+  }
+}
+
+function validationError(code, message) {
+  throw new StructuredHandoffValidationError(code, message);
+}
+
+function validateHandoffObject(value, maxContentChars) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    validationError("invalid_shape", "structured handoff must be an object");
+  }
+
+  const keys = Object.keys(value);
+  if (
+    keys.length !== STRUCTURED_HANDOFF_FIELDS.length ||
+    keys.some((key, index) => key !== STRUCTURED_HANDOFF_FIELDS[index])
+  ) {
+    validationError(
+      "invalid_fields",
+      "structured handoff fields are missing, extra, or out of order",
+    );
+  }
+  if (typeof value.objective !== "string") {
+    validationError("invalid_objective", "objective must be a string");
+  }
+
+  const normalized = { objective: normalizeText(value.objective) };
+  for (const field of ARRAY_FIELDS) {
+    if (!Array.isArray(value[field])) {
+      validationError(`invalid_${field}`, `${field} must be an array`);
+    }
+    normalized[field] = value[field].map((item) => {
+      if (typeof item !== "string") {
+        validationError(`invalid_${field}`, `${field} must contain strings`);
+      }
+      return normalizeText(item);
+    });
+  }
+
+  if (JSON.stringify(normalized).length > maxContentChars) {
+    validationError(
+      "content_too_large",
+      `structured handoff exceeds ${maxContentChars} characters`,
+    );
+  }
+  return normalized;
+}
+
+/** Parse one strict JSON object. Markdown fences and surrounding prose fail. */
+export function parseStructuredHandoff(raw, options = {}) {
+  const maxContentChars = boundedInteger(
+    options.maxContentChars,
+    DEFAULT_MAX_CONTENT_CHARS,
+    512,
+    1_000_000,
+  );
+  let value = raw;
+  if (typeof raw === "string") {
+    const text = raw.trim();
+    if (!text) validationError("invalid_json", "structured handoff is empty");
+    if (text.length > maxContentChars) {
+      validationError(
+        "content_too_large",
+        `structured handoff exceeds ${maxContentChars} characters`,
+      );
+    }
+    try {
+      value = JSON.parse(text);
+    } catch {
+      validationError("invalid_json", "structured handoff is not strict JSON");
+    }
+  } else if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    validationError(
+      "invalid_type",
+      "structured handoff must be JSON text or an object",
+    );
+  }
+  return validateHandoffObject(value, maxContentChars);
+}
+
+/** Format with stable field order so persisted summaries are reproducible. */
+export function formatStructuredHandoff(value) {
+  return JSON.stringify(
+    validateHandoffObject(value, DEFAULT_MAX_CONTENT_CHARS),
+    null,
+    2,
+  );
+}
+
+function selectBoundedSources(messages, maxChars) {
+  // A structured handoff can later become durable system context. Never let a
+  // merely verified (or wire-tag-forged) system message gain that authority by
+  // being quoted into a new handoff. Only the runtime WeakMap capability is
+  // admitted; ordinary user/assistant/tool conversation remains eligible.
+  const canonicalSources = projectCanonicalResumeMessages(messages);
+  const entries = canonicalSources
+    .map((message, index) => ({
+      index,
+      role: typeof message?.role === "string" ? message.role : "unknown",
+      text: normalizeText(contentText(message)),
+    }))
+    .filter((entry) => entry.text);
+  const firstUser = entries.find((entry) => entry.role === "user");
+  const selected = new Map();
+  let remaining = maxChars;
+
+  if (firstUser) {
+    const allowance = Math.min(
+      firstUser.text.length,
+      Math.max(1, Math.floor(maxChars / 3)),
+    );
+    selected.set(firstUser.index, {
+      ...firstUser,
+      text: firstUser.text.slice(0, allowance),
+    });
+    remaining -= allowance;
+  }
+
+  for (let index = entries.length - 1; index >= 0 && remaining > 0; index--) {
+    const entry = entries[index];
+    if (selected.has(entry.index)) continue;
+    const allowance = Math.min(entry.text.length, remaining);
+    if (allowance <= 0) break;
+    selected.set(entry.index, {
+      ...entry,
+      text: entry.text.slice(0, allowance),
+    });
+    remaining -= allowance;
+  }
+  return [...selected.values()].sort((left, right) => left.index - right.index);
+}
+
+function fragments(text) {
+  return text
+    .split(/\n+|(?<=[.!?。！？])\s+/u)
+    .map((part) => normalizeText(part).replace(/^(?:[-*+]\s+|\d+[.)]\s+)/, ""))
+    .filter(Boolean);
+}
+
+function stripLabel(value, labels) {
+  return normalizeText(value).replace(
+    new RegExp(`^(?:${labels})\\s*(?::|：|-)?\\s*`, "iu"),
+    "",
+  );
+}
+
+function uniqueBounded(values, maxItems, maxItemChars) {
+  const seen = new Set();
+  const result = [];
+  for (const value of values) {
+    const item = truncateText(value, maxItemChars);
+    const key = item.toLocaleLowerCase();
+    if (!item || seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+    if (result.length >= maxItems) break;
+  }
+  return result;
+}
+
+function pathsFrom(text) {
+  const matches = text.match(
+    /(?:[A-Za-z]:[\\/]|\.{0,2}[\\/])?(?:[A-Za-z0-9_@.-]+[\\/])+(?:[A-Za-z0-9_@.-]+)/g,
+  );
+  return (matches || [])
+    .map((value) => value.replace(/[),;:.]+$/g, ""))
+    .filter((value) => value && !value.includes("://"));
+}
+
+function emptyHandoff(objective = "") {
+  return {
+    objective,
+    constraints: [],
+    keyDecisions: [],
+    changedFiles: [],
+    tests: [],
+    unresolvedSideEffects: [],
+    checkpoints: [],
+    blockers: [],
+    nextSteps: [],
+  };
+}
+
+function serializedLength(value) {
+  return JSON.stringify(value, null, 2).length;
+}
+
+function fitToContentLimit(handoff, maxContentChars) {
+  const value = structuredClone(handoff);
+  while (serializedLength(value) > maxContentChars) {
+    const strings = [
+      { field: "objective", index: null, value: value.objective },
+      ...ARRAY_FIELDS.flatMap((field) =>
+        value[field].map((item, index) => ({ field, index, value: item })),
+      ),
+    ].sort((left, right) => right.value.length - left.value.length);
+    const longest = strings[0];
+    if (!longest) break;
+    if (longest.value.length > 80) {
+      const excess = serializedLength(value) - maxContentChars;
+      const nextLength = Math.max(80, longest.value.length - excess - 1);
+      const next = truncateText(longest.value, nextLength);
+      if (longest.index == null) value.objective = next;
+      else value[longest.field][longest.index] = next;
+      continue;
+    }
+    const removable = [...ARRAY_FIELDS]
+      .reverse()
+      .find((field) => value[field].length > 0);
+    if (removable) {
+      value[removable].pop();
+      continue;
+    }
+    value.objective = truncateText(
+      value.objective,
+      Math.max(0, value.objective.length - 1),
+    );
+  }
+  return value;
+}
+
+/**
+ * Deterministic fallback that retains labelled facts and exact file paths.
+ * The first user objective and the most recent history receive source-budget
+ * priority, preventing a large middle tool result from crowding out either.
+ */
+export function buildExtractiveHandoff(messages, options = {}) {
+  const maxContentChars = boundedInteger(
+    options.maxContentChars,
+    DEFAULT_MAX_CONTENT_CHARS,
+    512,
+    1_000_000,
+  );
+  const maxItemsPerField = boundedInteger(
+    options.maxItemsPerField,
+    DEFAULT_MAX_ITEMS_PER_FIELD,
+    1,
+    256,
+  );
+  const maxItemChars = boundedInteger(
+    options.maxItemChars,
+    DEFAULT_MAX_ITEM_CHARS,
+    32,
+    16_000,
+  );
+  const maxFallbackSourceChars = boundedInteger(
+    options.maxFallbackSourceChars,
+    DEFAULT_MAX_FALLBACK_SOURCE_CHARS,
+    512,
+    1_000_000,
+  );
+  const sources = selectBoundedSources(messages, maxFallbackSourceChars);
+  const firstUser = sources.find((entry) => entry.role === "user");
+  const candidates = emptyHandoff(
+    truncateText(firstUser?.text || "", maxItemChars),
+  );
+
+  for (const source of sources) {
+    for (const fragment of fragments(source.text)) {
+      candidates.changedFiles.push(...pathsFrom(fragment));
+      if (
+        /^(?:constraint|constraints|requirement|requirements|must|must not|do not|don't|only|约束|必须|不要|只能|仅限)\b/iu.test(
+          fragment,
+        ) ||
+        /\bwithout\s+(?:widening|changing|removing|losing)\b/iu.test(fragment)
+      ) {
+        candidates.constraints.push(
+          stripLabel(
+            fragment,
+            "constraint(?:s)?|requirement(?:s)?|must(?: not)?|do not|don't|only|约束|必须|不要|只能|仅限",
+          ),
+        );
+      }
+      if (
+        /^(?:key decision|decision|decided|approach|we will|选择|决定|方案)\b/iu.test(
+          fragment,
+        )
+      ) {
+        candidates.keyDecisions.push(
+          stripLabel(
+            fragment,
+            "key decision|decision|decided|approach|we will|选择|决定|方案",
+          ),
+        );
+      }
+      if (
+        /\b(?:test|tests|vitest|jest|pytest|playwright|lint|typecheck|build)\b/iu.test(
+          fragment,
+        ) &&
+        /\b(?:passed|failed|run|ran|green|verified|success|succeeded|通过|失败|运行|验证)\b/iu.test(
+          fragment,
+        )
+      ) {
+        candidates.tests.push(stripLabel(fragment, "test(?:s)?|测试|验证"));
+      }
+      if (
+        /\b(?:unresolved (?:external )?side effects?|external action|not (?:yet )?(?:published|deployed|merged|sent)|pending (?:publish|deploy|merge)|未发布|未部署|未合并|外部副作用)\b/iu.test(
+          fragment,
+        )
+      ) {
+        candidates.unresolvedSideEffects.push(
+          stripLabel(
+            fragment,
+            "unresolved (?:external )?side effects?|external action|外部副作用",
+          ),
+        );
+      }
+      if (
+        /\b(?:checkpoint|commit\s+[0-9a-f]{7,40}|implemented|completed|done|verified|checkpoint|检查点|已完成|已实现)\b/iu.test(
+          fragment,
+        )
+      ) {
+        candidates.checkpoints.push(
+          stripLabel(fragment, "checkpoint|status|检查点|状态"),
+        );
+      }
+      if (
+        /\b(?:blocker|blocked|blocking|cannot|can't|missing|required external|阻塞|受阻|缺失)\b/iu.test(
+          fragment,
+        )
+      ) {
+        candidates.blockers.push(
+          stripLabel(fragment, "blocker(?:s)?|blocked|阻塞"),
+        );
+      }
+      if (
+        /^(?:next steps?|next|todo|remaining|then|下一步|待办|后续)\b/iu.test(
+          fragment,
+        )
+      ) {
+        candidates.nextSteps.push(
+          stripLabel(
+            fragment,
+            "next steps?|next|todo|remaining|then|下一步|待办|后续",
+          ),
+        );
+      }
+    }
+  }
+
+  for (const field of ARRAY_FIELDS) {
+    candidates[field] = uniqueBounded(
+      candidates[field],
+      maxItemsPerField,
+      maxItemChars,
+    );
+  }
+  return fitToContentLimit(candidates, maxContentChars);
+}