@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/api/server.ts

@@ -11,7 +11,7 @@ import { createServer, IncomingMessage, ServerResponse } from 'node:http';
 import { timingSafeEqual } from 'node:crypto';
 import type { ContentBlock } from '@animalabs/membrane';
 import type { AgentFramework } from '../framework.js';
-import { ResumeBlockedError } from '../framework.js';
+import { QuiesceBlockedError, ResumeBlockedError } from '../framework.js';
 import { isReleaseModel } from '../provider-waits.js';
 import type { TraceEvent, ProcessEvent } from '../types/index.js';
 import type {
@@ -78,7 +78,20 @@ export class ApiServer {
   private wss: WebSocketServer | null = null;
   private httpServer: ReturnType<typeof createServer> | null = null;
   private clients: Set<WebSocket> = new Set();
-  private currentBranch = 'main';
+  /** The store's branch as last read: what the API reports once the store has closed. */
+  private lastKnownBranch = 'main';
+
+  /**
+   * The store's current branch, read from the store while it's open. A cached
+   * name would go stale behind any move the API server didn't make itself (a
+   * rollback, a host's switch), and behind a switch whose move comes after
+   * its call returns, as one does once running maintenance has finished.
+   */
+  private get currentBranch(): string {
+    const store = this.framework.getStore();
+    if (!store.isClosed()) this.lastKnownBranch = store.currentBranch().name;
+    return this.lastKnownBranch;
+  }
 
   /** Map from client to their subscription IDs */
   private clientSubscriptions: Map<WebSocket, Set<string>> = new Map();
@@ -497,7 +510,11 @@ export class ApiServer {
     }
 
     const contextManager = agent.getContextManager();
-    const { messages } = await contextManager.compile();
+    // A dry run: listed, never sent, so it persists no fold resolutions and
+    // queues none of the compression its fold plan calls for (see
+    // Agent.compileWithInjections for what a dry run still leaves, and for
+    // context-manager#160's thinking binding).
+    const { messages } = await contextManager.compile(undefined, undefined, { dryRun: true });
 
     const limit = params?.limit ?? 50;
     const offset = params?.offset ?? 0;
@@ -568,32 +585,28 @@ export class ApiServer {
       throw new Error('name is required');
     }
 
-    const store = this.framework.getStore();
-    const previousBranch = this.currentBranch;
-
-    store.switchBranch(params.name);
-    this.currentBranch = params.name;
-
-    // Reversible Discord awareness markers are part of the branch projection.
-    // The switch is acknowledged once it has landed: delivery of the marks it
-    // adds and removes starts behind the MCPL data-plane gate, which holds
-    // channel traffic that arrives after it until they are attempted, or
-    // deferred while their server is disconnected, and a failure is an ops
-    // alert rather than a failed switch. (It used to await the awareness
-    // sync, which after a large rollback took the drain's whole length.)
-    this.framework.startDiscordAwarenessDelivery('branch switch');
-
-    // Materialize config files from the new branch
-    const ws = this.framework.getModule('workspace');
-    if (ws && 'materializeMount' in ws) {
-      await (ws as any).materializeMount('_config');
+    const from = this.currentBranch;
+
+    // The framework switches the store, starts the delivery of its Discord
+    // awareness marks behind the data-plane gate, and re-materializes the
+    // config mount. It refuses during a live turn or once stop() has begun,
+    // and stop() waits for one already running. It moves the store once any
+    // maintenance already running has finished, so the move can come after
+    // this call returns. The event names this switch's own move, from the
+    // branch read here to the one it was asked for: another switch can move
+    // the store again before this one continues.
+    let switched = false;
+    try {
+      await this.framework.switchBranch(params.name);
+      switched = true;
+    } finally {
+      // A later step can fail after the store has moved: clients still hear
+      // where it went. A refusal moved nothing, so there's nothing to tell.
+      if (switched || (this.currentBranch === params.name && params.name !== from)) {
+        this.broadcast('branch:switched', { from, to: params.name });
+      }
     }
 
-    this.broadcast('branch:switched', {
-      from: previousBranch,
-      to: params.name,
-    });
-
     return { switched: true };
   }
 
@@ -634,7 +647,6 @@ export class ApiServer {
     const result = this.framework.undoLastTurn(params.agentName);
 
     if (result.undone) {
-      this.currentBranch = result.toBranch!;
       // Marks follow behind the data-plane gate; the undo doesn't wait for Discord.
       this.framework.startDiscordAwarenessDelivery('undo', params.agentName);
       this.broadcast('branch:switched', {
@@ -655,7 +667,6 @@ export class ApiServer {
     const result = this.framework.redo(params.agentName);
 
     if (result.redone) {
-      this.currentBranch = result.toBranch!;
       // Marks follow behind the data-plane gate; the redo doesn't wait for Discord.
       this.framework.startDiscordAwarenessDelivery('redo', params.agentName);
       this.broadcast('branch:switched', {
@@ -705,10 +716,21 @@ export class ApiServer {
     }
 
     const contextManager = agent.getContextManager();
+    // A dry run: shown, never sent, so it persists no fold resolutions and
+    // queues none of the compression its fold plan calls for, at a
+    // hypothetical budget least of all (see Agent.compileWithInjections for
+    // what a dry run still leaves). Under the autobiographical strategy, a
+    // budget the context can't fit still throws: a dry run skips only
+    // context-manager's post-pick check, and an adaptive fold plan that
+    // doesn't fit then overruns at the middle's emission. Windowed
+    // passthrough's newest message alone is the one window that comes back
+    // larger than the budget.
     const { messages } = await contextManager.compile(
       params.maxTokens
         ? { maxTokens: params.maxTokens, reserveForResponse: 4096 }
-        : undefined
+        : undefined,
+      undefined,
+      { dryRun: true },
     );
 
     return { context: messages };
@@ -1051,6 +1073,9 @@ export class ApiServer {
               verdicts: error.verdicts,
               hostMode: this.framework.getHostModeStatus(),
             });
+          } else if (error instanceof QuiesceBlockedError) {
+            // A refusal, as resume()'s is: the host's mode is as it was.
+            respond(409, { error: error.message, hostMode: this.framework.getHostModeStatus() });
           } else {
             respond(500, { error: error instanceof Error ? error.message : String(error) });
           }

package/src/api/types.ts

@@ -147,7 +147,15 @@ export interface BranchDeleteParams {
 export interface AgentContextParams {
   /** Agent name */
   agentName: string;
-  /** Maximum tokens to include (optional) */
+  /** A hypothetical budget to compile the context at (optional). Without it
+   *  the context compiles at context-manager's default budget (100,000, with
+   *  4,000 reserved for the response), not the agent's own window. The
+   *  compile is a dry run. Under the autobiographical strategy, a budget the
+   *  context can't fit still fails the command, with context-manager's
+   *  refusal, which names the tokens and the limit. Passthrough keeps the
+   *  newest messages that fit (none, if the newest alone is larger), and
+   *  windowed passthrough returns the newest message alone, larger than the
+   *  budget. */
   maxTokens?: number;
 }
 
@@ -202,7 +210,7 @@ export interface InferenceSearchParams {
   offset?: number;
   /** Regex pattern to match against log content */
   pattern?: string;
-  /** Only show failed inferences */
+  /** Only show inferences that didn't succeed: failed or stopped */
   errorsOnly?: boolean;
 }
 

package/src/branch-names.ts

@@ -0,0 +1,19 @@
+/**
+ * A name for a new branch: `base` when `taken(base)` is false, else the first
+ * of `base-2`, `base-3`, … that isn't taken.
+ *
+ * Default operator branch names carry the time in milliseconds
+ * (`suppress/<agent>/<ts>`, `rollback/<agent>/<ts>`, …), so a second change of
+ * one kind made right after the first, in the same millisecond, would
+ * otherwise get the first one's name and be refused. Callers pass what counts
+ * as taken, at least every branch the store holds: the store knows every
+ * branch, whatever made it, where a counter kept in the process would know
+ * only the names it gave out.
+ */
+export function firstFreeBranchName(base: string, taken: (name: string) => boolean): string {
+  if (!taken(base)) return base;
+  for (let n = 2; ; n++) {
+    const name = `${base}-${n}`;
+    if (!taken(name)) return name;
+  }
+}

package/src/closest-names.ts

@@ -0,0 +1,94 @@
+/**
+ * The names someone most likely meant, when the one they gave matches none:
+ * for a refusal's "did you mean", such as a tool name an agent got wrong.
+ *
+ * Case is ignored. A candidate that the name matches as a whole `--` segment
+ * ("ls" for "workspace--ls"), then one that starts with it or that it starts
+ * with, then one that contains it or that it contains, ranks ahead of one
+ * that is only a few edits away, however many edits those matches take. The
+ * prefix and substring matches need three characters on the shorter side,
+ * since a letter or two is in nearly every name. A candidate that matches in
+ * none of those ways counts only within the edits noiseLimit allows, and past
+ * that it's noise. So a name that is part of no candidate, holds none and is
+ * close to none gets nothing back, and a name in a crowded namespace doesn't
+ * get its neighbours (`workspace--write` for `workspace--read`).
+ */
+export function closestNames(name: string, candidates: readonly string[], max = 2): string[] {
+  const wanted = name.toLowerCase();
+  const ranked: { candidate: string; tier: number; distance: number }[] = [];
+  for (const candidate of new Set(candidates)) {
+    const other = candidate.toLowerCase();
+    const shorter = Math.min(wanted.length, other.length);
+    const tier = other === wanted ? 0
+      : wanted && other.split('--').includes(wanted) ? 1
+      : shorter >= 3 && (other.startsWith(wanted) || wanted.startsWith(other)) ? 2
+      : shorter >= 3 && (other.includes(wanted) || wanted.includes(other)) ? 3
+      : 4;
+    // In tiers 0 to 3 one name holds the other, so the length difference is
+    // already their distance, and a long name skips the edit table.
+    const limit = tier === 4 ? noiseLimit(wanted, other) : Infinity;
+    const distance = tier === 4 ? editDistance(wanted, other, limit) : Math.abs(wanted.length - other.length);
+    if (distance > limit) continue;
+    ranked.push({ candidate, tier, distance });
+  }
+  // A stable sort: candidates that tie keep the order they were given in.
+  ranked.sort((a, b) => a.tier - b.tier || a.distance - b.distance);
+  return ranked.slice(0, Math.max(0, max)).map((entry) => entry.candidate);
+}
+
+/**
+ * Whether `name` looks like a slip for `candidate`, ignoring case: the same;
+ * a few edits apart, where a transposition counts as one edit; or, at three
+ * characters or more, a part of it, which is a shortened attempt at it
+ * (`mode` for `deliveryMode`, `interval` for `refillIntervalMs`). A part
+ * counts only that way round: a name that holds the candidate, and is more
+ * edits from it than a slip allows, is another name, usually an extra that
+ * explains it (`channel_note` beside `channel`, where `channels` is a slip).
+ * Beyond these, two names are different names rather than one mistyped.
+ */
+export function isNearMiss(name: string, candidate: string): boolean {
+  const a = name.toLowerCase(), b = candidate.toLowerCase();
+  if (a.length >= 3 && b.includes(a)) return true;
+  const limit = noiseLimit(a, b);
+  return editDistance(a, b, limit) <= limit;
+}
+
+/**
+ * The most edits that still read as a slip: a quarter of what follows the
+ * prefix the two names share, and at least one. A shared prefix is mostly a
+ * namespace (`workspace--`, `mcpl--discord--`) and says nothing about the
+ * rest, so `workspace--read` and `workspace--write` are four edits apart in
+ * a four-letter tool name, not in a fifteen-letter one.
+ */
+function noiseLimit(a: string, b: string): number {
+  let shared = 0;
+  while (shared < a.length && shared < b.length && a[shared] === b[shared]) shared++;
+  return Math.max(1, Math.floor((Math.max(a.length, b.length) - shared) / 4));
+}
+
+/**
+ * Edits between two strings: insertions, deletions, substitutions and
+ * swaps of neighbours (optimal string alignment). Past `limit` the exact
+ * count doesn't matter, so it answers `limit + 1` as soon as it is sure.
+ */
+function editDistance(a: string, b: string, limit: number): number {
+  if (Math.abs(a.length - b.length) > limit) return limit + 1;
+  let before: number[] = [];
+  let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    let best = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let value = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) value = Math.min(value, before[j - 2] + 1);
+      current.push(value);
+      best = Math.min(best, value);
+    }
+    // No row's smallest entry is below the one before it, so none later can come back under the limit.
+    if (best > limit) return limit + 1;
+    before = previous;
+    previous = current;
+  }
+  return previous[b.length];
+}