codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/shared/storageRunActions.js

@@ -1,14 +1,16 @@
 (function initStorageRunActions(root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory();
+    module.exports = factory(require('./selectionContext'), require('./writebackIntent'), require('./writingStyle'), require('./directoryCleanupProof'));
   } else {
-    root.CodexOverleafStorageRunActions = factory();
+    root.CodexOverleafModuleRegistry.define('StorageRunActions', ['SelectionContext', 'WritebackIntent', 'WritingStyle', 'DirectoryCleanupProof'], factory);
   }
-})(typeof globalThis !== 'undefined' ? globalThis : window, function storageRunActionsFactory() {
+})(typeof globalThis !== 'undefined' ? globalThis : window, function storageRunActionsFactory(SelectionContext, WritebackIntent, WritingStyle, DirectoryCleanupProof) {
   'use strict';
 
-  var MAX_PERSISTED_ACTION_RUNS_PER_SESSION = 2;
-  var MAX_PERSISTED_ACTION_BYTES_PER_RUN = 320 * 1024;
+  // Share a bounded budget across the retained history, rather than expiring
+  // otherwise valid recovery data after two edits. The session builder also
+  // reserves room for display metadata within the shared transport limit.
+  var MAX_PERSISTED_ACTION_BYTES_PER_SESSION = 16 * 1024 * 1024;
 
   function compactRunsForStorage(runs, options, maxRuns, compactRun) {
     if (typeof compactRun !== 'function') {
@@ -17,22 +19,100 @@
     var selectedRuns = (Array.isArray(runs) ? runs : [])
       .filter(function (run) { return run && typeof run.id === 'string'; })
       .slice(-Math.max(0, Number(maxRuns) || 0));
-    var actionRunIds = new Set();
+    var payloads = new Map();
+    var remaining = Math.min(MAX_PERSISTED_ACTION_BYTES_PER_SESSION,
+      Number.isFinite(options?.maxActionPayloadBytes) ? Math.max(0, options.maxActionPayloadBytes) : Infinity);
+    var usedBytes = 0, usedChars = 0;
+    var fits = (bytes, chars) => bytes <= remaining && (typeof options?.canRetainActionPayload !== 'function'
+      || options.canRetainActionPayload(usedBytes + bytes, usedChars + chars));
     if (options && options.preserveRunActionPayload === true) {
-      for (var index = selectedRuns.length - 1;
-        index >= 0 && actionRunIds.size < MAX_PERSISTED_ACTION_RUNS_PER_SESSION;
-        index -= 1) {
-        if (hasReloadableRunActionPayload(selectedRuns[index])) {
-          actionRunIds.add(selectedRuns[index].id);
+      for (var index = selectedRuns.length - 1; index >= 0; index -= 1) {
+        var run = selectedRuns[index];
+        if (!hasReloadableRunActionPayload(withoutDirectoryFacts(run))) continue;
+        var payload = compactRunActionPayload(run, true, { includeCaptures: false, includeDirectoryCleanup: false });
+        if (payload.recoveryRetention?.state === 'omitted') { payloads.set(run.id, payload); continue; }
+        var serialized = JSON.stringify(payload);
+        var bytes = getUtf8ByteLength(serialized);
+        if (!fits(bytes, serialized.length)) {
+          payloads.set(run.id, { ...emptyActionPayload(), recoveryRetention: omitted('session-budget', bytes) });
+          continue;
+        }
+        remaining -= bytes;
+        usedBytes += bytes; usedChars += serialized.length;
+        payloads.set(run.id, payload);
+      }
+      // Captures are optional. They must not crowd out any retained core data.
+      for (var run of selectedRuns.slice().reverse()) {
+        var payload = payloads.get(run.id);
+        if (!payload || payload.recoveryRetention?.state === 'omitted'
+          || run.undoStatus === 'applied' || ['accepted', 'rejected'].includes(run.trackedChangeStatus)) continue;
+        var captures = cloneSerializableArray(run.trackedChangeCaptures);
+        var extraText = captures.length ? JSON.stringify({ trackedChangeCaptures: captures }) : '';
+        var extraBytes = getUtf8ByteLength(extraText);
+        if (extraBytes && fits(extraBytes, extraText.length)) {
+          payload.trackedChangeCaptures = captures;
+          remaining -= extraBytes;
+          usedBytes += extraBytes; usedChars += extraText.length;
         }
       }
     }
+    // Passive directory history uses only the space left after all original
+    // recovery payloads and optional captures have been selected.
+    var directoryRemaining = Number.isFinite(options?.maxOptionalDirectoryBytes)
+      ? Math.max(0, options.maxOptionalDirectoryBytes) : Infinity;
     return selectedRuns.map(function (run) {
-      return compactRun(run, actionRunIds.has(run.id));
+      var payload = payloads.get(run.id) || compactRunActionPayload(run, false, { includeDirectoryCleanup: false });
+      if (options?.deferDirectoryCleanup !== true) payload = appendDirectoryFacts(payload, run,
+        options?.preserveRunActionPayload === true, function (bytes, chars) {
+          if (bytes > directoryRemaining || !fits(bytes, chars)) return false;
+          directoryRemaining -= bytes; remaining -= bytes;
+          usedBytes += bytes; usedChars += chars;
+          return true;
+        }, 'session-budget');
+      return compactRun(run, payloads.has(run.id) && !coreWasOmitted(payload), payload);
     });
   }
 
+  // Keep the complete display history while allocating finite recovery space
+  // across the current project. A record plus its previous merge baseline is
+  // transported together; a readable batch must also fit the response bound.
+  function compactSessionBatchActions(records, options = {}, buildSessionRecord, SharedSessionTransfer) {
+    var budget = SharedSessionTransfer.MAX_RESPONSE_BYTES - 64 * 1024;
+    if (SharedSessionTransfer.byteLength(JSON.stringify(records)) <= budget) return records;
+    var summaries = records.map(record => buildSessionRecord(record, { preserveRunActionPayload: false, deferDirectoryCleanup: true }));
+    var remaining = Math.max(0, budget - SharedSessionTransfer.byteLength(JSON.stringify(summaries)));
+    var allocated = new Map();
+    var ordered = records.slice().sort((a, b) => Number(b.id === options.activeSessionId) - Number(a.id === options.activeSessionId)
+      || (Date.parse(b.updatedAt) || 0) - (Date.parse(a.updatedAt) || 0));
+    for (var record of ordered) {
+      var summary = summaries.find(item => item.id === record.id);
+      var next = buildSessionRecord(record, { preserveRunActionPayload: true, maxActionPayloadBytes: remaining, deferDirectoryCleanup: true });
+      remaining -= Math.max(0, SharedSessionTransfer.byteLength(JSON.stringify(next)) - SharedSessionTransfer.byteLength(JSON.stringify(summary)));
+      allocated.set(record.id, next);
+    }
+    // Do not let an active session's optional directory facts evict another
+    // session's existing Undo core under the shared response bound.
+    for (var record of ordered) {
+      var core = allocated.get(record.id);
+      var sourceRuns = new Map((record.runs || []).map(run => [run.id, run]));
+      var withFacts = { ...core, runs: core.runs.map(run => {
+        var source = sourceRuns.get(run.id), next = { ...run };
+        if (source?.pendingDirectoryCleanup) next.pendingDirectoryCleanup = source.pendingDirectoryCleanup;
+        if (source?.recoveryRetention?.directoryCleanup === true) next.recoveryRetention = {
+          ...(next.recoveryRetention || { ...source.recoveryRetention, coreRetained: true }), directoryCleanup: true };
+        return next;
+      }) };
+      var enriched = buildSessionRecord(withFacts, { preserveRunActionPayload: true, maxOptionalDirectoryBytes: remaining });
+      remaining -= Math.max(0, SharedSessionTransfer.byteLength(JSON.stringify(enriched)) - SharedSessionTransfer.byteLength(JSON.stringify(core)));
+      allocated.set(record.id, enriched);
+    }
+    return records.map(record => allocated.get(record.id));
+  }
+
   function hasReloadableRunActionPayload(run) {
+    if (!run || run.forkSnapshot === true) return false;
+    if (runDirectoryCleanup(run)) return true;
+    if (run.undoStatus === 'applied' || ['accepted', 'rejected'].includes(run.trackedChangeStatus)) return false;
     var trackedStatus = run && run.trackedChangeStatus;
     var trackedLifecycle = (trackedStatus === 'pending' || trackedStatus === 'needs_review')
       && Array.isArray(run.undoTrackedChanges) && run.undoTrackedChanges.length > 0
@@ -52,29 +132,96 @@
     return trackedLifecycle || reviewingEditorUndo || legacyUndo;
   }
 
-  function compactRunActionPayload(run, keepActionPayload) {
+  function runDirectoryCleanup(run) {
+    var proof = DirectoryCleanupProof.normalize(run?.pendingDirectoryCleanup);
+    return proof && proof.runId === run.id && proof.projectId === run.runProjectId ? proof : null;
+  }
+
+  function omitted(reason, bytes = 0) {
+    return { state: 'omitted', reason, bytes };
+  }
+
+  function withoutDirectoryFacts(run) {
+    var core = { ...run };
+    delete core.pendingDirectoryCleanup;
+    if (core.recoveryRetention?.directoryCleanup === true) {
+      if (core.recoveryRetention.coreRetained === true) delete core.recoveryRetention;
+      else {
+        core.recoveryRetention = { ...core.recoveryRetention };
+        delete core.recoveryRetention.directoryCleanup;
+        delete core.recoveryRetention.coreRetained;
+      }
+    }
+    return core;
+  }
+
+  function coreWasOmitted(payload) {
+    return payload.recoveryRetention?.state === 'omitted' && payload.recoveryRetention.coreRetained !== true;
+  }
+
+  function appendDirectoryFacts(payload, run, keep, fits, reason) {
+    if (run?.forkSnapshot === true) return payload;
+    var directory = runDirectoryCleanup(run), previous = run?.recoveryRetention;
+    if (!directory && previous?.directoryCleanup !== true) return payload;
+    if (directory && keep) {
+      var extended = { ...payload, pendingDirectoryCleanup: directory };
+      var before = JSON.stringify(payload), after = JSON.stringify(extended);
+      if (fits(getUtf8ByteLength(after) - getUtf8ByteLength(before), after.length - before.length)) return extended;
+    }
+    // The existing omission marker distinguishes optional history from lost
+    // recovery authority. Never imply that a retained Undo core was discarded.
+    var retention = coreWasOmitted(payload) ? payload.recoveryRetention
+      : omitted(!keep ? 'fallback' : directory ? reason : previous.reason,
+        directory ? getUtf8ByteLength(JSON.stringify(directory)) : previous.bytes);
+    return { ...payload, recoveryRetention: { ...retention, directoryCleanup: true,
+      ...(!coreWasOmitted(payload) ? { coreRetained: true } : {}) } };
+  }
+
+  function compactRunActionPayload(run, keepActionPayload, options = {}) {
+    var payload = compactCoreActionPayload(withoutDirectoryFacts(run), keepActionPayload, options);
+    if (options.includeDirectoryCleanup === false) return payload;
+    var serialized = JSON.stringify(payload);
+    return appendDirectoryFacts(payload, run, keepActionPayload,
+      bytes => getUtf8ByteLength(serialized) + bytes <= MAX_PERSISTED_ACTION_BYTES_PER_SESSION, 'run-budget');
+  }
+
+  function compactCoreActionPayload(run, keepActionPayload, options = {}) {
     var empty = emptyActionPayload();
     if (!keepActionPayload || !hasReloadableRunActionPayload(run)) {
+      if (hasReloadableRunActionPayload(run)) empty.recoveryRetention = omitted('fallback');
+      else if (run?.recoveryRetention?.state === 'omitted' && !run.forkSnapshot
+        && run.undoStatus !== 'applied' && !['accepted', 'rejected'].includes(run.trackedChangeStatus)) {
+        empty.recoveryRetention = omitted(
+          ['run-budget', 'session-budget', 'fallback', 'invalid'].includes(run.recoveryRetention.reason)
+            ? run.recoveryRetention.reason : 'invalid', Math.max(0, Number(run.recoveryRetention.bytes) || 0));
+      }
       return empty;
     }
-    var payload = {
+    var terminal = run.undoStatus === 'applied' || ['accepted', 'rejected'].includes(run.trackedChangeStatus);
+    var payload = terminal ? emptyActionPayload() : {
       appliedOperations: cloneSerializableArray(run.appliedOperations),
       undoOperations: cloneSerializableArray(run.undoOperations),
       undoBaseFiles: cloneSerializableArray(run.undoBaseFiles),
       undoTrackedChanges: cloneSerializableArray(run.undoTrackedChanges),
       undoExpectedFiles: cloneSerializableArray(run.undoExpectedFiles)
     };
+    if (!terminal && Object.keys(payload).some(key => run[key]?.length && !payload[key].length)) {
+      return { ...empty, recoveryRetention: omitted('invalid') };
+    }
     var serialized;
     try {
       serialized = JSON.stringify(payload);
     } catch (_error) {
-      return empty;
+      return { ...empty, recoveryRetention: omitted('invalid') };
     }
-    if (getUtf8ByteLength(serialized) > MAX_PERSISTED_ACTION_BYTES_PER_RUN) return empty;
+    var bytes = getUtf8ByteLength(serialized);
+    if (bytes > MAX_PERSISTED_ACTION_BYTES_PER_SESSION) return { ...empty,
+      recoveryRetention: omitted('run-budget', bytes) };
+    if (options.includeCaptures === false || terminal) return payload;
     const captures = cloneSerializableArray(run.trackedChangeCaptures);
     if (captures.length) {
       const extended = { ...payload, trackedChangeCaptures: captures };
-      if (getUtf8ByteLength(JSON.stringify(extended)) <= MAX_PERSISTED_ACTION_BYTES_PER_RUN) return extended;
+      if (getUtf8ByteLength(JSON.stringify(extended)) <= MAX_PERSISTED_ACTION_BYTES_PER_SESSION) return extended;
     }
     return payload; // Optional capture evidence must never evict a mature Undo payload.
   }
@@ -126,6 +273,8 @@
       compact.focusFiles = snapshot.focusFiles.slice(0, 100)
         .filter(function (value) { return typeof value === 'string'; }).map(normalize);
     }
+    compact.selectionContext = SelectionContext.normalize(snapshot.selectionContext);
+    compact.writingStyle = WritingStyle.normalizeSnapshot(snapshot.writingStyle);
     return { executionSnapshot: compact };
   }
 
@@ -163,17 +312,20 @@
   function mergeSessionReviewState(incoming, existing, reviewRunIds) {
     if (!existing || incoming.id !== existing.id || incoming.projectId !== existing.projectId
       || !incoming.accountScopeId || incoming.accountScopeId !== existing.accountScopeId) return incoming;
-    var terminal = run => ['accepted', 'rejected'].includes(run?.trackedChangeStatus);
+    var terminal = run => ['accepted', 'rejected'].includes(run?.trackedChangeStatus) || run?.undoStatus === 'applied';
     var incomingRuns = new Map((incoming.runs || []).map(run => [run.id, run]));
     var existingRuns = new Map((existing.runs || []).map(run => [run.id, run]));
     var requestedIds = new Set(reviewRunIds || []);
-    var explicitReview = Array.from(requestedIds).some(id =>
-      ['accepted', 'rejected', 'needs_review'].includes(incomingRuns.get(id)?.trackedChangeStatus));
+    var explicitReview = Array.from(requestedIds).some(id => {
+      var run = incomingRuns.get(id);
+      return ['accepted', 'rejected', 'needs_review'].includes(run?.trackedChangeStatus)
+        || ['applied', 'partial'].includes(run?.undoStatus);
+    });
     var newer = (Date.parse(incoming.updatedAt) || 0) >= (Date.parse(existing.updatedAt) || 0);
     if (!newer && !explicitReview) return incoming;
     var base = newer ? incoming : existing;
-    var fields = ['trackedChangeStatus', 'undoStatus', 'undoTrackedChanges', 'undoExpectedFiles',
-      'undoOperations', 'undoBaseFiles', 'appliedOperations', 'trackedChangeCaptures', 'settlement', 'settlementFacts'];
+    var fields = ['trackedChangeStatus', 'undoStatus', 'undoOwnerProtocol', 'undoTrackedChanges', 'undoExpectedFiles',
+      'undoOperations', 'undoBaseFiles', 'appliedOperations', 'trackedChangeCaptures', 'recoveryRetention', 'settlement', 'settlementFacts'];
     var changed = false;
     var runs = (base.runs || []).map(function (run) {
       var previous = existingRuns.get(run.id), candidate = incomingRuns.get(run.id);
@@ -212,7 +364,44 @@
     return (hash >>> 0).toString(16).padStart(8, '0');
   }
 
+  // A successful durable write can omit an oversized checkpoint while the
+  // current tab still has it. Warn only the view and exact action revision
+  // that was saved; never mutate or remove its in-memory recovery material.
+  function projectRetentionUpdates({ liveState, capturedState, written, capturedScope, currentScope } = {}) {
+    if (!capturedScope?.accountScopeId || !capturedScope.projectId
+      || !Number.isSafeInteger(capturedScope.generation)
+      || ['accountScopeId', 'projectId', 'generation'].some(key => capturedScope[key] !== currentScope?.[key])) return [];
+    var fields = ['appliedOperations', 'undoOperations', 'undoBaseFiles', 'undoTrackedChanges',
+      'undoExpectedFiles', 'undoStatus', 'trackedChangeStatus', 'pendingDirectoryCleanup'];
+    var fingerprint = run => JSON.stringify(fields.map(field => run[field]));
+    var updates = [];
+    for (var record of written || []) {
+      if (record.accountScopeId !== capturedScope.accountScopeId || record.projectId !== capturedScope.projectId) continue;
+      var live = liveState?.sessions?.find(session => session.id === record.id);
+      var captured = capturedState?.sessions?.find(session => session.id === record.id);
+      for (var storedRun of record.runs || []) {
+        var run = live?.runs?.find(run => run.id === storedRun.id);
+        var original = captured?.runs?.find(run => run.id === storedRun.id);
+        if (!run || !original || run.runProjectId !== capturedScope.projectId
+          || original.runProjectId !== capturedScope.projectId || !hasReloadableRunActionPayload(run)) continue;
+        try {
+          if (fingerprint(run) !== fingerprint(original)) continue;
+          if (storedRun.recoveryRetention?.state === 'omitted') updates.push({ runId: run.id, retention: { ...storedRun.recoveryRetention } });
+          else if (fingerprint(storedRun) === fingerprint(original)) updates.push({ runId: run.id, retention: null });
+        } catch (_error) { /* Invalid data cannot establish a revision. */ }
+      }
+    }
+    return updates;
+  }
+
+  function projectRetentionWarnings(input) {
+    return projectRetentionUpdates(input).filter(update => update.retention).map(update => update.runId);
+  }
+
   return {
+    projectRetentionUpdates: projectRetentionUpdates,
+    projectRetentionWarnings: projectRetentionWarnings,
+    compactSessionBatchActions: compactSessionBatchActions,
     compactStructuredEventValue: compactStructuredEventValue,
     mergeSessionReviewState: mergeSessionReviewState,
     compactRunsForStorage: compactRunsForStorage,

package/extension/src/shared/storageValuePruning.js

@@ -0,0 +1,40 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafModuleRegistry.define('StorageValuePruning', [], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  'use strict';
+
+  function removeEmptySummaryFields(value) {
+    var result = {};
+    var keys = Object.keys(value || {});
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i];
+      var item = value[key];
+      if (item === undefined || item === '' || item === null) {
+        continue;
+      }
+      if (Array.isArray(item) && item.length === 0) {
+        continue;
+      }
+      if (item && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).length === 0) {
+        continue;
+      }
+      result[key] = item;
+    }
+    return result;
+  }
+
+  function removeEmptyFields(value) {
+    var result = {};
+    var keys = Object.keys(value);
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i];
+      if (value[key] !== undefined && value[key] !== '') {
+        result[key] = value[key];
+      }
+    }
+    return result;
+  }
+
+  return { removeEmptySummaryFields, removeEmptyFields };
+});

package/extension/src/shared/subagentActivityModel.js

@@ -0,0 +1,174 @@
+(function initSubagentActivityModel(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory(require('./agentTranscript'), require('./runActivityModel'));
+  } else root.CodexOverleafModuleRegistry.define('SubagentActivityModel', ['AgentTranscript', 'RunActivityModel'], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : window, function subagentActivityModelFactory(Transcript, Activity) {
+  'use strict';
+  const MAX_AGENTS = 16, MAX_EVENTS = 100, MAX_CHARS = 48000;
+  const STATES = new Set(['pending', 'running', 'completed', 'failed', 'cancelled', 'unknown']);
+  const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+  const string = value => typeof value === 'string' ? value : '';
+  function clean(value, sanitize = string, limit = 24000) {
+    return string(sanitize(string(value))).slice(0, limit);
+  }
+  function trim(agent) {
+    if (agent.events.length > MAX_EVENTS) { agent.events = agent.events.slice(-MAX_EVENTS); agent.clipped = true; }
+    while (agent.events.length > 1 && JSON.stringify(agent.events).length > MAX_CHARS) {
+      agent.events.shift(); agent.clipped = true;
+    }
+    return agent;
+  }
+  function normalize(agents, sanitize = string) {
+    const seen = new Set();
+    return (Array.isArray(agents) ? agents : []).slice(0, MAX_AGENTS).filter(agent => {
+      if (!agent || !['broker', 'codex'].includes(agent.source)) return false;
+      const id = agent.source === 'broker' ? agent.jobId : agent.threadId;
+      if (typeof id !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,159}$/.test(id)) return false;
+      const key = agent.source + ':' + id;
+      if (seen.has(key)) return false;
+      seen.add(key); return true;
+    }).map(agent => trim({
+      v: 1, source: agent.source, key: agent.source + ':' + (agent.source === 'broker' ? agent.jobId : agent.threadId),
+      jobId: clean(agent.jobId, sanitize, 160), threadId: clean(agent.threadId, sanitize, 160),
+      parentThreadId: clean(agent.parentThreadId, sanitize, 160),
+      title: clean(agent.title, sanitize, 160), task: clean(agent.task, sanitize, 4096),
+      model: clean(agent.model, sanitize, 160), reasoningEffort: clean(agent.reasoningEffort, sanitize, 32),
+      status: STATES.has(agent.status) ? agent.status : 'unknown',
+      startedAt: clean(agent.startedAt, sanitize, 64), updatedAt: clean(agent.updatedAt, sanitize, 64),
+      finishedAt: clean(agent.finishedAt, sanitize, 64),
+      lastSequence: Number.isSafeInteger(agent.lastSequence) ? agent.lastSequence : 0,
+      nativeEventSeq: Number.isSafeInteger(agent.nativeEventSeq) ? agent.nativeEventSeq : 0,
+      clipped: agent.clipped === true, historyUnavailable: agent.historyUnavailable === true,
+      events: (Array.isArray(agent.events) ? agent.events : []).filter(event => event && typeof event.title === 'string')
+        .slice(-MAX_EVENTS).map(event => ({
+          title: clean(event.title, sanitize), status: clean(event.status, sanitize, 32),
+          timestamp: clean(event.timestamp, sanitize, 64),
+          kind: event.kind === 'stream' ? 'stream' : 'activity',
+          streamKey: clean(event.streamKey, sanitize, 600), streamRole: event.streamRole === 'assistant' ? 'assistant' : '',
+          streamPhase: Activity.normalizePhase(event.streamPhase),
+          activity: Activity.normalize(event.activity, sanitize)
+        }))
+    }));
+  }
+  function effectiveStatus(agent, run) {
+    if (TERMINAL.has(agent.status) || agent.status === 'unknown' || run.status === 'running') return agent.status;
+    return ['cancelled', 'rejected'].includes(run.status) ? 'cancelled' : 'unknown';
+  }
+  function terminalTime(agent, run) {
+    const terminal = [agent.finishedAt, run.status === 'running' ? '' : run.finishedAt]
+      .map(value => Date.parse(value || '')).find(Number.isFinite);
+    const evidence = [agent.startedAt, agent.updatedAt, ...(agent.events || []).map(event => event.timestamp)];
+    if (run.status !== 'running') evidence.push(run.startedAt, run.updatedAt, ...(run.events || []).map(event => event.timestamp));
+    return terminal ?? Math.max(...evidence.map(value => Date.parse(value || '')).filter(Number.isFinite));
+  }
+  function elapsedMs(agent, run, now = Date.now()) {
+    const start = Date.parse(agent.startedAt || '');
+    const live = run.status === 'running' && ['pending', 'running'].includes(effectiveStatus(agent, run));
+    return Number.isFinite(start) ? Math.max(0, (live ? now : terminalTime(agent, run)) - start) : null;
+  }
+  function append(agent, input, sanitize) {
+    const event = {
+      title: clean(input.title, sanitize), status: input.status || 'running',
+      timestamp: input.timestamp || new Date().toISOString(),
+      kind: input.kind === 'stream' ? 'stream' : 'activity',
+      streamKey: input.streamKey || '', streamRole: input.streamRole || '',
+      streamPhase: Activity.normalizePhase(input.streamPhase),
+      activity: Activity.normalize(input.activity, sanitize)
+    };
+    if (!event.title) return;
+    const key = event.kind === 'stream' ? 'stream:' + event.streamKey : event.activity?.id;
+    const previous = key && agent.events.find(old => (old.kind === 'stream' ? 'stream:' + old.streamKey : old.activity?.id) === key);
+    if (previous) {
+      if (previous.status === 'completed' && event.status === 'running' && input.appendText) return;
+      const fullText = input.appendText ? previous.title + event.title : event.title;
+      if (fullText.length > 24000) agent.clipped = true;
+      const activity = previous.activity && event.activity ? { ...previous.activity, ...event.activity,
+        command: event.activity.command || previous.activity.command,
+        output: event.activity.output || previous.activity.output,
+        paths: event.activity.paths?.length ? event.activity.paths : previous.activity.paths,
+        files: event.activity.files?.length ? event.activity.files : previous.activity.files } : event.activity || previous.activity;
+      Object.assign(previous, event, { title: fullText.slice(0, 24000), activity });
+    } else agent.events.push(event);
+    trim(agent);
+  }
+  function addAnswer(agent, answer, timestamp, sanitize) {
+    if (!answer) return;
+    const last = agent.events.filter(event => event.kind === 'stream' && event.streamRole === 'assistant').at(-1);
+    const safe = clean(answer, sanitize);
+    if (last?.title.trim() === safe.trim()) { last.status = 'completed'; return; }
+    append(agent, { kind: 'stream', streamRole: 'assistant', streamPhase: 'final_answer',
+      streamKey: last?.streamPhase === 'final_answer' ? last.streamKey : 'answer:' + agent.key,
+      title: safe, status: 'completed', timestamp }, sanitize);
+  }
+  function ingest(run, raw, options = {}) {
+    const type = string(raw?.type), detail = raw?.detail || {};
+    if (type === 'codex.subagent.drained') return true;
+    if (!['codex.subagent.queued', 'codex.subagent.started', 'codex.subagent.completed',
+      'codex.subagent.failed', 'codex.subagent.rejected', 'codex.subagent.event', 'codex.subagent.observed'].includes(type)) return false;
+    const source = detail.source === 'codex' ? 'codex' : 'broker';
+    const id = source === 'broker' ? string(detail.jobId || detail.id) : string(detail.threadId);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,159}$/.test(id)) return true;
+    const sanitize = options.sanitize || string, key = source + ':' + id;
+    const agents = run.subagents || (run.subagents = []);
+    let agent = agents.find(item => item.key === key);
+    if (!agent) {
+      if (agents.length >= MAX_AGENTS) return true;
+      agent = { v: 1, source, key, jobId: source === 'broker' ? id : '', threadId: source === 'codex' ? id : '',
+        title: id, task: '', status: 'pending', events: [], nativeEventSeq: 0, lastSequence: 0 };
+      agents.push(agent);
+    }
+    const seq = Number(options.nativeEventSeq) || 0;
+    if (seq > 0 && seq <= (agent.nativeEventSeq || 0)) return true;
+    const sequence = Number(detail.sequence) || 0;
+    if (sequence > 0 && sequence <= (agent.lastSequence || 0)) return true;
+    agent.nativeEventSeq = Math.max(agent.nativeEventSeq || 0, seq);
+    agent.lastSequence = Math.max(agent.lastSequence || 0, sequence);
+    const timestamp = string(raw.timestamp) || new Date().toISOString(), at = Date.parse(string(raw.timestamp));
+    const wasTerminal = TERMINAL.has(agent.status), previousEnd = terminalTime(agent, run);
+    if (Number.isFinite(at) && at < Date.parse(agent.startedAt || '')) return true;
+    agent.updatedAt = timestamp;
+    for (const field of ['title', 'task', 'threadId', 'parentThreadId', 'model', 'reasoningEffort']) {
+      const value = detail[field] || (field === 'title' ? raw.title : '');
+      if (typeof value === 'string' && value) agent[field] = clean(value, sanitize, field === 'task' ? 4096 : 160);
+    }
+    agent.clipped ||= detail.historyClipped === true;
+    if (typeof detail.historyUnavailable === 'boolean') agent.historyUnavailable = detail.historyUnavailable;
+    let next = type.endsWith('.queued') ? 'pending' : type.endsWith('.started') ? 'running'
+      : type.endsWith('.completed') ? 'completed' : type.endsWith('.rejected') ? 'failed'
+        : type.endsWith('.failed') ? (detail.status === 'cancelled' ? 'cancelled' : 'failed') : detail.status;
+    const inner = type === 'codex.subagent.event' ? detail.event : null;
+    const method = inner?.detail?.method, params = inner?.detail?.params || {};
+    if (method === 'turn/started') next = 'running';
+    if (method === 'turn/completed' && source === 'codex') next = params.turn?.status === 'interrupted' ? 'cancelled' : params.turn?.status;
+    const reopening = wasTerminal && method === 'turn/started';
+    if (STATES.has(next) && (!wasTerminal || TERMINAL.has(next) || reopening)) agent.status = next;
+    if (reopening) { agent.startedAt = timestamp; agent.finishedAt = ''; }
+    if (agent.status === 'running' && !agent.startedAt) agent.startedAt = timestamp;
+    if (TERMINAL.has(agent.status) || run.status !== 'running') {
+      // Late snapshots describe the same stopped interval; only a new turn resets it.
+      const end = wasTerminal || run.status !== 'running' || !Number.isFinite(at) ? previousEnd : at;
+      if (Number.isFinite(end)) agent.finishedAt = new Date(end).toISOString();
+    }
+    if (inner) {
+      const boundThread = inner.detail?.threadId || params.threadId || params.thread?.id;
+      if (boundThread) agent.threadId = clean(boundThread, sanitize, 160);
+      if (params.thread?.model) agent.model = clean(params.thread.model, sanitize, 160);
+      const mapped = Transcript.mapAgentEventToActivity(inner, { locale: options.locale });
+      const activity = Activity.capture({ ...mapped, technicalDetail: mapped?.technicalDetail || inner }, sanitize);
+      if (mapped?.visible && mapped.kind !== 'technical' && (!mapped.streamRole || mapped.streamRole === 'assistant')) {
+        const itemId = params.item?.id || params.itemId || inner.detail?.itemId;
+        const turnId = params.turnId || inner.detail?.turnId || '';
+        append(agent, { ...mapped, timestamp, activity,
+          streamKey: mapped.kind === 'stream' ? turnId + ':' + (itemId || mapped.streamKey || 'assistant') : '' }, sanitize);
+      }
+    }
+    if (TERMINAL.has(agent.status)) {
+      for (const event of agent.events) if (event.kind === 'stream' && event.status === 'running') event.status = 'completed';
+      addAnswer(agent, detail.summary, timestamp, sanitize);
+      if (detail.reason) append(agent, { title: clean(detail.reason, sanitize, 1200), status: 'warning', timestamp,
+        activity: { kind: 'notice', id: key + ':failure', state: agent.status === 'failed' ? 'failed' : 'warning' } }, sanitize);
+    }
+    return true;
+  }
+  return { normalize, ingest, effectiveStatus, elapsedMs };
+});