@animalabs/agent-framework 0.14.0 → 0.16.0

package/src/modules/history/search-regex-worker.ts

@@ -0,0 +1,76 @@
+/**
+ * search-regex-worker — runs a caller-supplied regex against a batch of
+ * message text on a separate thread, so HistoryModule's `search` tool can
+ * forcibly terminate a catastrophically-backtracking pattern (ReDoS)
+ * instead of blocking the framework's single-threaded event loop.
+ *
+ * Why a worker and not a Promise.race/setTimeout "timeout": JS is
+ * single-threaded, so nothing on the SAME thread can interrupt a
+ * synchronous RegExp.exec() call already in flight — a timeout callback
+ * racing it can't even fire until the blocking call returns, by which point
+ * it's too late. A worker thread is real OS-level concurrency: the parent's
+ * event loop keeps running, and `worker.terminate()` actually kills the
+ * stuck thread rather than just giving up on waiting for it.
+ *
+ * Only regex-mode search routes through this worker. Plain substring search
+ * (String.prototype.indexOf) is inherently linear in input length and has
+ * no equivalent risk, so it stays in-process — the common case pays no
+ * worker-spawn overhead.
+ *
+ * One-shot: the whole job (already-flattened text, already syntax-validated
+ * pattern/flags, match limit) arrives via `workerData` at construction; this
+ * script runs it to completion and posts exactly one message, then the
+ * parent always terminates the worker (whether it finished normally or had
+ * to be killed for running long) — no persistent pool, so a wedged worker
+ * from one bad pattern can never contaminate a later call.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+
+export interface SearchWorkerJob {
+  /** Flattened candidate text, aligned by index with the parent's candidate array. */
+  texts: string[];
+  pattern: string;
+  flags: string;
+  /** Stop scanning once this many matches are found. */
+  limit: number;
+}
+
+export interface SearchWorkerMatch {
+  /** Index into `texts` / the parent's candidate array. */
+  candidateIndex: number;
+  matchIndex: number;
+  matchLength: number;
+}
+
+export type SearchWorkerMessage =
+  | { type: 'done'; matches: SearchWorkerMatch[]; scanned: number }
+  | { type: 'error'; error: string };
+
+const { texts, pattern, flags, limit } = workerData as SearchWorkerJob;
+
+try {
+  // Re-construct (not re-validate for safety — RegExp syntax is what it is;
+  // the parent already rejected an uncompilable pattern before ever getting
+  // here) the matcher on this thread. Compilation succeeding doesn't bound
+  // MATCHING time — that's exactly the risk this worker exists to contain.
+  const matcher = new RegExp(pattern, flags);
+  const matches: SearchWorkerMatch[] = [];
+  let scanned = 0;
+  for (let i = 0; i < texts.length; i++) {
+    // Check the limit BEFORE doing any work for this candidate — not after
+    // pushing a match — so limit:0 (a valid clampCount value: it's >= 0)
+    // correctly yields zero matches instead of one. Checking post-push would
+    // always let through the match that first reaches the limit.
+    if (matches.length >= limit) break;
+    scanned++;
+    const m = matcher.exec(texts[i] ?? '');
+    if (m) {
+      matches.push({ candidateIndex: i, matchIndex: m.index, matchLength: m[0].length });
+    }
+  }
+  const done: SearchWorkerMessage = { type: 'done', matches, scanned };
+  parentPort?.postMessage(done);
+} catch (e) {
+  const errMsg: SearchWorkerMessage = { type: 'error', error: e instanceof Error ? e.message : String(e) };
+  parentPort?.postMessage(errMsg);
+}

package/src/modules/index.ts

@@ -8,6 +8,8 @@ export type { ApiEvent } from './api/index.js';
 export { HealthModule } from './health/index.js';
 export type { HealthModuleConfig } from './health/index.js';
 
+export { HistoryModule } from './history/index.js';
+
 export { WorkspaceModule, WorkspaceReadError } from './workspace/index.js';
 export type { WorkspaceReadErrorCode, WorkspaceReadStage, WorkspaceDiskReadResult, ReadFileFromDiskOptions } from './workspace/index.js';
 export type {

package/src/modules/workspace/index.ts

@@ -932,13 +932,19 @@ export class WorkspaceModule implements Module {
     return [
       {
         name: 'read',
-        description: 'Read a file from the workspace. Returns content with line numbers. Reads at most 2000 lines per call by default — use offset/limit to page through larger files.',
+        description: 'Read a file from the workspace. Returns content with line numbers. '
+          + 'Reads at most 2000 lines per call by default — use offset/limit to page through larger files. '
+          + 'For long lines or spill files, use offsetChars/limitChars instead: returns raw text without '
+          + 'line numbers, with nextOffsetChars (null at EOF). Keep limitChars when continuing. '
+          + 'Character offsets count UTF-16 code units; do not mix character and line parameters.',
         inputSchema: {
           type: 'object' as const,
           properties: {
             path: { type: 'string', description: 'File path (mount-prefixed, e.g., "project/src/main.ts")' },
             offset: { type: 'number', description: 'Starting line number (1-indexed)' },
             limit: { type: 'number', description: 'Maximum number of lines to return (default 2000)' },
+            offsetChars: { type: 'integer', description: 'Character paging: zero-based UTF-16 offset (default 0); use nextOffsetChars to continue' },
+            limitChars: { type: 'integer', description: 'Character paging: code units to return (default 2000), plus at most one to keep a surrogate pair intact. Use the limit suggested by a spill notice.' },
           },
           required: ['path'],
         },
@@ -1741,6 +1747,19 @@ export class WorkspaceModule implements Module {
   // ==========================================================================
 
   private async handleRead(input: ReadInput): Promise<ToolResult> {
+    const characterPaging = input.offsetChars !== undefined || input.limitChars !== undefined;
+    const offsetChars = input.offsetChars ?? 0;
+    const limitChars = input.limitChars ?? 2000;
+    if (characterPaging) {
+      if (input.offset !== undefined || input.limit !== undefined) {
+        return { success: false, isError: true, error: 'Use either offset/limit (lines) or offsetChars/limitChars (characters), not both.' };
+      }
+      if (!Number.isSafeInteger(offsetChars) || offsetChars < 0
+          || !Number.isSafeInteger(limitChars) || limitChars < 1
+          || input.offsetChars === null || input.limitChars === null) {
+        return { success: false, isError: true, error: 'offsetChars must be a non-negative safe integer and limitChars a positive safe integer.' };
+      }
+    }
     const { mount, relativePath } = this.parsePath(input.path);
     const store = this.getStore();
 
@@ -1757,6 +1776,28 @@ export class WorkspaceModule implements Module {
     }
 
     const content = blob.toString('utf-8');
+    if (characterPaging) {
+      const start = Math.min(offsetChars, content.length);
+      const splitsPair = (at: number): boolean =>
+        at > 0 && at < content.length
+        && content.charCodeAt(at - 1) >= 0xd800 && content.charCodeAt(at - 1) <= 0xdbff
+        && content.charCodeAt(at) >= 0xdc00 && content.charCodeAt(at) <= 0xdfff;
+      if (splitsPair(start)) {
+        return { success: false, isError: true, error: 'offsetChars splits a surrogate pair; use nextOffsetChars from the previous page.' };
+      }
+      let end = start + Math.min(limitChars, content.length - start);
+      if (splitsPair(end)) end++;
+      return {
+        success: true,
+        data: {
+          path: input.path,
+          totalChars: content.length,
+          offsetChars: start,
+          nextOffsetChars: end < content.length ? end : null,
+          content: content.slice(start, end),
+        },
+      };
+    }
     const lines = content.split('\n');
 
     // Apply offset/limit. An unlimited read of a large file would inject the

package/src/modules/workspace/types.ts

@@ -133,6 +133,11 @@ export interface ReadInput {
   offset?: number;
   /** Number of lines to read (optional) */
   limit?: number;
+  /** Zero-based UTF-16 offset; selects character paging. Cannot mix with line offset/limit. */
+  offsetChars?: number;
+  /** Character page size in UTF-16 code units (default 2000); selects character paging.
+   * May include one extra code unit to keep a surrogate pair intact. */
+  limitChars?: number;
 }
 
 export interface ReadImageInput {

package/src/operator-log.ts

@@ -0,0 +1,132 @@
+/**
+ * Operator action log — a durable, append-only JSONL record of every
+ * operator-initiated mutation of a live resident: branch rollbacks, message
+ * suppressions, undo/redo/hide, unstick/nudge, runtime-settings changes,
+ * host quiesce/resume. One file per store, next to the chronicle
+ * (`<storePath>/operator-actions.jsonl`), so it travels with backups and
+ * survives host restarts the way `repair-receipts.jsonl` and
+ * `watchdog-wedge.jsonl` do.
+ *
+ * The chronicle record log is the authoritative history of *what* changed;
+ * this file records *who asked for it, from where, and why* — the part the
+ * store cannot know. Writes are best-effort (a logging failure never fails
+ * the action) and synchronous (`write(2)`, not `fsync`): an entry survives a
+ * process crash once the call returns, not a power loss. Mutations record
+ * after they complete, so a crash between the chronicle switch and the
+ * append loses the who/why for that one action — the branch itself remains
+ * the evidence. The file is created 0600: it carries requester identity and
+ * free-text operator notes.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** Who asked. `via` names the surface ('webui', 'host-command', 'api',
+ *  'cli', …); `name`/`id` are whatever identity that surface has. */
+export interface OperatorRequester {
+  via: string;
+  name?: string;
+  id?: string;
+}
+
+export interface OperatorLogEntry {
+  /** ISO-8601 wall-clock time of the record. */
+  at: string;
+  /** Action kind, e.g. 'rollback', 'suppress', 'undo', 'hide', 'quiesce'. */
+  kind: string;
+  /** Agent the action targeted (absent for host-wide actions). */
+  agent?: string;
+  requester?: OperatorRequester;
+  /** Free-text reason supplied by the operator. */
+  note?: string;
+  /** Inputs as the caller supplied them (ids, counts, patches). */
+  params?: Record<string, unknown>;
+  /** Outcome details (branches, removed ids, refs) when the action succeeded. */
+  result?: Record<string, unknown>;
+  /** Error message when the action was refused or failed. */
+  error?: string;
+}
+
+export type OperatorLogInput = Omit<OperatorLogEntry, 'at'> & { at?: string };
+
+export class OperatorLog {
+  private warned = false;
+
+  constructor(readonly path: string | undefined) {}
+
+  get enabled(): boolean {
+    return this.path !== undefined;
+  }
+
+  /** Append one record. Never throws. Returns the stamped entry. */
+  append(input: OperatorLogInput): OperatorLogEntry {
+    const entry: OperatorLogEntry = { ...input, at: input.at ?? new Date().toISOString() };
+    if (!this.path) return entry;
+    try {
+      const dir = dirname(this.path);
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      appendFileSync(this.path, JSON.stringify(entry) + '\n', { mode: 0o600 });
+    } catch (error) {
+      if (!this.warned) {
+        this.warned = true;
+        console.error(
+          `[operator-log] failed to write ${this.path}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+    return entry;
+  }
+
+  /**
+   * Read the newest `limit` entries (oldest first within the slice). Reads
+   * the whole file — the log is small (one line per operator action).
+   * Malformed lines are skipped rather than failing the read.
+   */
+  readTail(limit = 100): OperatorLogEntry[] {
+    if (!this.path || !existsSync(this.path)) return [];
+    let raw: string;
+    try {
+      raw = readFileSync(this.path, 'utf8');
+    } catch {
+      return [];
+    }
+    const lines = raw.split('\n').filter((l) => l.length > 0);
+    const slice = lines.slice(Math.max(0, lines.length - Math.max(0, limit)));
+    const out: OperatorLogEntry[] = [];
+    for (const line of slice) {
+      try {
+        const parsed = JSON.parse(line) as OperatorLogEntry;
+        if (parsed && typeof parsed === 'object' && typeof parsed.kind === 'string') out.push(parsed);
+      } catch {
+        // skip torn/corrupt line
+      }
+    }
+    return out;
+  }
+}
+
+export function defaultOperatorLogPath(storePath: string): string {
+  return join(storePath, 'operator-actions.jsonl');
+}
+
+/** Ids lists in log records are capped so one wide `hide`/`suppress` cannot
+ *  write a multi-KB line; the full count is always recorded alongside. */
+export const OPERATOR_LOG_ID_CAP = 50;
+export function capIds(ids: string[]): { ids: string[]; count: number; truncated?: true } {
+  return ids.length > OPERATOR_LOG_ID_CAP
+    ? { ids: ids.slice(0, OPERATOR_LOG_ID_CAP), count: ids.length, truncated: true }
+    : { ids, count: ids.length };
+}
+
+/** Thrown by live surgery methods when a request cannot be honored. `code`
+ *  lets surfaces distinguish "agent busy — quiesce first" from bad input. */
+export class OperatorActionError extends Error {
+  constructor(
+    readonly code: 'unknown-agent' | 'agent-busy' | 'unknown-message' | 'invalid' | 'failed',
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = 'OperatorActionError';
+  }
+}

package/src/recovery/discord-awareness-outbox.ts

@@ -158,6 +158,25 @@ export class DiscordAwarenessOutbox {
     this.write(document);
   }
 
+  /**
+   * Retire a batch that was prepared but whose operation did not complete
+   * (fork failed, a removal threw and the source branch was restored). A
+   * prepared batch is armed: it re-fires at boot or on branch switch through
+   * `activatePreparedForBranch` / `preparedSuppressionsForBranch`, and an
+   * un-completable suppression there aborts framework start. Only prepared
+   * batches can be discarded — an active batch owns delivered markers and
+   * must be reconciled, not dropped. Returns false when nothing was removed.
+   */
+  discard(batchId: string): boolean {
+    const document = this.read();
+    const index = document.batches.findIndex((candidate) => candidate.id === batchId);
+    if (index < 0) return false;
+    if (document.batches[index].status !== 'prepared') return false;
+    document.batches.splice(index, 1);
+    this.write(document);
+    return true;
+  }
+
   /**
    * Reconcile every retained ledger entry against the active branch. A marker
    * is desired when any active batch for the same ref+emoji has a target branch

package/src/types/framework.ts

@@ -95,9 +95,36 @@ export interface FrameworkConfig {
    */
   discordAwarenessOutboxPath?: string;
 
+  /**
+   * Branch-INDEPENDENT record of the host's quiesce state (issue #122).
+   * Defaults to `<storePath>/recovery/host-mode.json`. Lives outside the
+   * chronicle because a historical rollback (branchAt + switchBranch) would
+   * otherwise move the active branch to a version of `framework/state`
+   * predating the marker, and a restart would boot SERVING mid-surgery. Set
+   * explicitly when providing an app-owned `store` without `storePath`;
+   * without either, the branch-local slot is used with a one-time warning.
+   */
+  hostModePath?: string;
+
+  /**
+   * Branch-independent durable queue of context writes deferred while
+   * quiesced. Defaults to `<storePath>/recovery/deferred-writes.json`; same
+   * rationale and fallback as `hostModePath`.
+   */
+  deferredWritesPath?: string;
+
   /** Emoji used for branch-awareness markers (default: 💤). */
   discordAwarenessEmoji?: string;
 
+  /**
+   * Durable JSONL record of operator-initiated mutations (rollback, suppress,
+   * undo/hide, settings, quiesce). Defaults to
+   * `<storePath>/operator-actions.jsonl`; set explicitly when providing an
+   * app-owned `store` without `storePath`. `false` disables the file (actions
+   * still emit `operator:action` traces).
+   */
+  operatorLogPath?: string | false;
+
   /**
    * Mandatory deadline for each Discord awareness marker tools/call. This is
    * independent of MCPL requestTimeoutMs and cannot be disabled with 0.

package/src/types/trace.ts

@@ -266,6 +266,20 @@ export type TraceEvent =
       toBranch: string;
     })
 
+  // Operator-initiated mutation (rollback/suppress/undo/hide/settings/quiesce…).
+  // Mirrors the durable operator-actions.jsonl record so live UIs see the
+  // same entry the file keeps.
+  | (TraceEventBase & {
+      type: 'operator:action';
+      agentName?: string;
+      kind: string;
+      requester?: { via: string; name?: string; id?: string };
+      note?: string;
+      params?: Record<string, unknown>;
+      result?: Record<string, unknown>;
+      error?: string;
+    })
+
   // MCPL subprocess stderr (one trace per line, for receipts when things break)
   | (TraceEventBase & {
       type: 'mcpl:server-stderr';
@@ -351,6 +365,10 @@ export type TraceEvent =
       toolUseId: string;
       isError: boolean;
       durationMs: number;
+      /** The pair was queued behind a turn that replaced the puppet's
+       *  reservation (provider-admission re-entry) instead of stored
+       *  directly; it lands at that turn's end flush. */
+      deferred?: boolean;
     })
 
   // MCPL server connection lifecycle (spawn / handshake / reconnect health).
@@ -422,6 +440,34 @@ export type TraceEvent =
       message: string;
       /** Kind-specific structured payload (mirrors the failures.log record). */
       data?: Record<string, unknown>;
+    })
+
+  // Host quiesce/maintenance mode (issue #122)
+  | (TraceEventBase & {
+      type: 'host:quiesce';
+      reason?: string;
+      /** Whether all turns settled within the drain window. */
+      drained: boolean;
+      /** Turns still alive at return (0 unless the drain timed out). */
+      activeTurns: number;
+      /** Wakes still parked on provider admission at return (see HostModeStatus). */
+      parkedAdmissions?: number;
+      /** True when undrained turns were force-cancelled (abandon). */
+      abandoned?: boolean;
+      /** Agents whose turn abandon could not cancel (token held, no stream). */
+      unabandonable?: string[];
+    })
+  | (TraceEventBase & {
+      type: 'host:resume';
+      /** True when a failing feasibility verdict was overridden. */
+      forced?: boolean;
+      /** Gated inference requests released back to the scheduler. */
+      releasedRequests: number;
+    })
+  | (TraceEventBase & {
+      type: 'host:quiesced_boot';
+      reason?: string;
+      since?: number;
     });
 
 /**