@animalabs/agent-framework 0.15.0 → 0.17.0

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

@@ -70,6 +70,21 @@ export interface CodeExecutionConfig {
   maxWakesPerScript?: number;
 }
 
+/** See `FrameworkConfig.providerHold`. */
+export interface ProviderHold {
+  holdMs: number;
+  /** Operator-facing explanation, logged with the hold. */
+  reason?: string;
+}
+/** What the framework knows about the failing call. */
+export interface ProviderHoldContext {
+  /** Model of the agent whose call failed — a quota window may be model-scoped. */
+  model?: string;
+}
+export type ProviderHoldHook = (
+  error: Error, agentName: string, context: ProviderHoldContext,
+) => ProviderHold | undefined;
+
 export interface FrameworkConfig {
   /**
    * The subconscious resident (issue #77): a persistent side-agent that
@@ -95,9 +110,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.
@@ -123,6 +165,27 @@ export interface FrameworkConfig {
   /** Custom error policy */
   errorPolicy?: ErrorPolicy;
 
+  /**
+   * Host verdict on a failed inference: "this cannot succeed until later".
+   * Consulted before the error policy and before the built-in
+   * organization-acceleration classification, for a persistent agent's
+   * primary inference and for its auxiliary (compression) calls. Ephemeral
+   * runs (subagents) and conversation forks are NOT covered: they have no
+   * provider-admission gate and keep the ordinary error policy. A hold parks the agent's provider
+   * admission (primary and auxiliary) instead of retrying, and — like the
+   * built-in organization-acceleration cooldown — records no failed turn and
+   * does not feed the hard-down streak. The motivating case is a subscription
+   * credential whose quota window is spent: its 429 looks like a throttle,
+   * but retrying cannot help until the window resets.
+   *
+   * Holds are served in slices of at most 10 minutes. When a slice expires
+   * the hook is consulted again with the same error, before any inference is
+   * attempted; it extends the hold by returning another, or releases it by
+   * returning undefined. Must be synchronous and cheap; a throwing hook is
+   * treated as "no hold".
+   */
+  providerHold?: ProviderHoldHook;
+
   /** Interval for periodic store sync in milliseconds (default: 1000ms, 0 to disable) */
   syncIntervalMs?: number;
 

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';
@@ -426,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;
     });
 
 /**