@animalabs/agent-framework 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",
@@ -46,8 +46,8 @@
   "author": "Anima Research",
   "license": "MIT",
   "dependencies": {
-    "@animalabs/chronicle": "^0.3.0",
-    "@animalabs/context-manager": "^0.8.0",
+    "@animalabs/chronicle": "^0.4.0",
+    "@animalabs/context-manager": "^0.10.0",
     "@animalabs/membrane": "^0.5.78",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",

package/src/agent.ts

@@ -99,6 +99,11 @@ export class Agent {
   private _state: AgentState = { status: 'idle' };
   private _inferenceStartedAt = 0;
   private _streamId = 0;
+  /** kv-unified receipt flights opened by the CURRENT activation and not yet
+   * settled by a usage event. Held on the agent (not only in the stream's
+   * closure) so the next activation can close whatever its predecessor left
+   * open — see failOpenKvSubmissions. */
+  private kvOpenQueue: Array<{ submissionId: string; wireReceipt: CacheWireReceipt }> | null = null;
   lastStreamInputTokens = 0;
   /** Real prefix size of the last usage event: fresh + cache creation +
    *  cache read. THE window-shaped number — `lastStreamInputTokens` alone
@@ -271,6 +276,75 @@ export class Agent {
     return { ...this.runtimeSettingsOverrides };
   }
 
+  /**
+   * Read-only mirror of `updateRuntimeSettings`' budget semantics: derive what
+   * the next compile would actually plan at if `patch` were applied, WITHOUT
+   * mutating anything. This is the settings→config mapping a feasibility
+   * preview must share with the live path — previewing `patch.contextBudgetTokens`
+   * directly models the wrong compile for a paced descent (a non-immediate
+   * decrease never changes the compile budget; it only arms a prepared-window
+   * transition — see the else-branch in updateRuntimeSettings).
+   *
+   * - `path: 'immediate'` — the patch changes the compile budget (increase, or
+   *   decrease with `immediate: true`); `effectiveBudgetTokens` = patch value.
+   * - `path: 'paced'` — non-immediate decrease; `effectiveBudgetTokens` stays
+   *   at the live budget and `advisoryTargetTokens` carries the descent target.
+   * - `path: 'none'` — patch absent or budget untouched.
+   *
+   * `overrides` uses strategy-config names (`recentWindowTokens`,
+   * `kvStableReachTokens`) suitable for `previewContext`. `preparedWindowTokens`
+   * is deliberately never mapped: it is strategy instance state, not config,
+   * and cannot be simulated by a preview. A `kvStableReachTokens` override is
+   * omitted while a prepared window is in flight — the live runtime pace
+   * shadows the config value there, so the override would not be observed.
+   */
+  planRuntimeSettings(patch?: AgentRuntimeSettingsPatch): {
+    effectiveBudgetTokens: number;
+    /** The budget compiles currently plan at — the baseline the patch moves
+     *  from. Lets callers distinguish a lowering from a no-op or an increase
+     *  (an increase on an already-wedged agent never makes things worse). */
+    liveBudgetTokens: number;
+    advisoryTargetTokens?: number;
+    path: 'immediate' | 'paced' | 'none';
+    overrides: Record<string, unknown>;
+  } {
+    if (patch && Object.keys(patch).length > 0) {
+      this.validateRuntimeSettingsPatch(patch);
+    }
+    const hot = this.getHotContextSettings();
+    const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+
+    const overrides: Record<string, unknown> = {};
+    if (patch?.tailTokens !== undefined) {
+      overrides.recentWindowTokens = patch.tailTokens;
+    }
+    if (
+      patch?.transitionPaceTokens !== undefined &&
+      hot?.preparedWindowTokens === undefined
+    ) {
+      overrides.kvStableReachTokens = patch.transitionPaceTokens;
+    }
+
+    if (patch?.contextBudgetTokens === undefined) {
+      return { effectiveBudgetTokens: live, liveBudgetTokens: live, path: 'none', overrides };
+    }
+    if (patch.contextBudgetTokens >= live || patch.immediate) {
+      return {
+        effectiveBudgetTokens: patch.contextBudgetTokens,
+        liveBudgetTokens: live,
+        path: 'immediate',
+        overrides,
+      };
+    }
+    return {
+      effectiveBudgetTokens: live,
+      liveBudgetTokens: live,
+      advisoryTargetTokens: patch.contextBudgetTokens,
+      path: 'paced',
+      overrides,
+    };
+  }
+
   getEffectiveSameRoundThinkTextPolicy(): SameRoundThinkTextPolicy {
     return this.runtimeSettingsOverrides.sameRoundThinkTextPolicy
       ?? this.configuredSameRoundThinkTextPolicy
@@ -730,6 +804,19 @@ export class Agent {
       throw new Error(`Agent ${this.name} cannot start stream in state ${this._state.status}`);
     }
 
+    // A new activation supersedes every receipt flight the previous one left
+    // open. Membrane fires the kv-unified wire receipt per provider attempt,
+    // BEFORE the adapter call; only that attempt's usage event settles it.
+    // When the attempt dies without usage (transport error, idle timeout,
+    // framework cancel for a budget restart or endTurn) the flight stays open
+    // until the old driveStream's `finally` runs — and every successor path
+    // (error-policy retry, budget restart, the next wake after an abort)
+    // starts the new stream BEFORE that `finally`. The successor's first
+    // receipt then met the ledger's single-flight guard and failed the
+    // recovery itself: "kv-unified submission devops:46:…:4 is still in
+    // flight" (devops agent, 2026-09-16 07:33Z, no provider error logged).
+    this.failOpenKvSubmissions();
+
     this._streamId++;
     this._inferenceStartedAt = Date.now();
     this.lastStreamInputTokens = 0;
@@ -753,6 +840,7 @@ export class Agent {
     const kvQueue: Array<{ submissionId: string; wireReceipt: CacheWireReceipt }> = [];
     let kvCall = 0;
     if (kvEnabled) {
+      this.kvOpenQueue = kvQueue;
       const layoutHash = stableHash(request.messages);
       const kvRequest = request as NormalizedRequest & KvUnifiedRequestHooks;
       kvRequest.onCacheWireReceipt = (receipt) => {
@@ -791,6 +879,28 @@ export class Agent {
     };
   }
 
+  /** Close every kv-unified receipt flight the previous activation left
+   * unsettled. Idempotent: the framework's driveStream `finally` drains the
+   * same per-stream queue, so whichever runs first empties it and the other
+   * finds nothing. Failing an already-settled id is a no-op in the ledger. */
+  private failOpenKvSubmissions(): void {
+    const open = this.kvOpenQueue?.splice(0) ?? [];
+    this.kvOpenQueue = null;
+    if (open.length === 0) return;
+    const strategy = (this.contextManager as unknown as { getStrategy?: () => unknown })
+      .getStrategy?.() as { reportKvUnifiedFailed?: (submissionId: string) => void } | undefined;
+    for (const { submissionId } of open) {
+      console.error(
+        `[kv-unified] ${this.name}: closing receipt flight ${submissionId} left open by the previous activation`,
+      );
+      try {
+        strategy?.reportKvUnifiedFailed?.(submissionId);
+      } catch (err) {
+        console.error(`[kv-unified] ${this.name}: could not close flight ${submissionId}:`, err);
+      }
+    }
+  }
+
   /**
    * Transition to waiting_for_tools when stream yields tool calls.
    * Called by framework's driveStream.

package/src/api/server.ts

@@ -8,8 +8,10 @@
 
 import { WebSocketServer, WebSocket } from 'ws';
 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 type { TraceEvent, ProcessEvent } from '../types/index.js';
 import type {
   ApiServerConfig,
@@ -46,7 +48,9 @@ import type {
 
 export * from './types.js';
 
-const DEFAULT_CONFIG: Required<ApiServerConfig> = {
+type ResolvedApiServerConfig = Required<Omit<ApiServerConfig, 'adminToken' | 'allowedOrigins'>> & Pick<ApiServerConfig, 'adminToken' | 'allowedOrigins'>;
+
+const DEFAULT_CONFIG: ResolvedApiServerConfig = {
   port: 8765,
   host: 'localhost',
   path: '/ws',
@@ -56,11 +60,19 @@ const DEFAULT_CONFIG: Required<ApiServerConfig> = {
 /** Polling interval for subscriptions (ms) */
 const SUBSCRIPTION_POLL_INTERVAL = 50;
 
+/** Constant-time token comparison (length leak is acceptable; content isn't). */
+function timingSafeTokenEqual(presented: string, expected: string): boolean {
+  const a = Buffer.from(presented);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
 /**
  * API Server for the agent framework.
  */
 export class ApiServer {
-  private config: Required<ApiServerConfig>;
+  private config: ResolvedApiServerConfig;
   private framework: AgentFramework;
   private wss: WebSocketServer | null = null;
   private httpServer: ReturnType<typeof createServer> | null = null;
@@ -74,9 +86,37 @@ export class ApiServer {
 
   constructor(framework: AgentFramework, config: ApiServerConfig = {}) {
     this.framework = framework;
+    // An empty token would look configured while matching an empty header:
+    // the gate would pass for anyone. Refuse it at construction.
+    if (config.adminToken !== undefined && config.adminToken.length === 0) {
+      throw new Error('ApiServerConfig.adminToken must be non-empty when set (omit it to disable the gate)');
+    }
     this.config = { ...DEFAULT_CONFIG, ...config };
   }
 
+  /**
+   * WebSocket upgrade origin policy (see ApiServerConfig.allowedOrigins).
+   * Non-browser clients send no Origin and pass; a browser Origin must match
+   * this server's own host or the configured allow-list.
+   */
+  private originAllowed(origin: string | undefined, hostHeader: string | undefined): boolean {
+    if (origin === undefined || origin === '' || origin === 'null') return origin !== 'null';
+    let originHost: string;
+    try {
+      originHost = new URL(origin).host;
+    } catch {
+      return false;
+    }
+    if (hostHeader && originHost.toLowerCase() === hostHeader.toLowerCase()) return true;
+    return (this.config.allowedOrigins ?? []).some((allowed) => {
+      try {
+        return new URL(allowed).host.toLowerCase() === originHost.toLowerCase();
+      } catch {
+        return allowed.toLowerCase() === originHost.toLowerCase();
+      }
+    });
+  }
+
   /**
    * Start the API server.
    */
@@ -95,6 +135,14 @@ export class ApiServer {
     this.wss = new WebSocketServer({
       server: this.httpServer,
       path: this.config.path,
+      // Browsers skip CORS for WS handshakes, so the Origin check is the
+      // only thing standing between a visited web page and this command
+      // surface on a localhost bind (host.quiesce, undo, branch.delete…).
+      verifyClient: (info: { origin: string; req: IncomingMessage }, done: (ok: boolean, code?: number, msg?: string) => void) => {
+        const ok = this.originAllowed(info.origin, info.req.headers.host);
+        if (!ok) console.warn(`[api] rejected WebSocket upgrade from origin ${info.origin}`);
+        done(ok, 403, 'origin not allowed');
+      },
     });
 
     this.wss.on('connection', (ws) => {
@@ -357,11 +405,37 @@ export class ApiServer {
       case 'events.subscribe':
         return this.cmdEventsSubscribe(params as unknown as EventsSubscribeParams);
 
+      // Host quiesce/maintenance mode (issue #122). When an adminToken is
+      // configured, the mutating verbs require it here too — the WS surface
+      // must not be a token-free path to the same authority as the HTTP verbs.
+      case 'host.quiesce':
+        this.requireAdminToken(params);
+        return this.framework.quiesce(params as
+          { reason?: string; timeoutMs?: number; abandon?: boolean } | undefined);
+      case 'host.resume':
+        this.requireAdminToken(params);
+        return this.framework.resume(params as { force?: boolean } | undefined);
+      case 'host.status':
+        return this.framework.getHostModeStatus();
+      case 'host.maintenanceTick':
+        this.requireAdminToken(params);
+        return this.framework.maintenanceTick();
+
       default:
         throw new Error(`Unknown command: ${command}`);
     }
   }
 
+  /** WS-side admin gate for the mutating host verbs: no-op unless an
+   *  adminToken is configured, then `params.adminToken` must match. */
+  private requireAdminToken(params?: Record<string, unknown>): void {
+    if (this.config.adminToken === undefined) return;
+    const presented = params?.adminToken;
+    if (typeof presented !== 'string' || !timingSafeTokenEqual(presented, this.config.adminToken)) {
+      throw new Error('adminToken required for host verbs on this server');
+    }
+  }
+
   // ==========================================================================
   // Conversation Commands
   // ==========================================================================
@@ -861,11 +935,94 @@ export class ApiServer {
           agents: agents.map((a) => ({ name: a.name, status: a.state.status })),
           clients: this.clients.size,
           queueDepth: this.framework.getQueueDepth(),
+          quiesced: this.framework.getHostModeStatus().quiesced,
         })
       );
       return;
     }
 
+    // Host quiesce/maintenance mode (issue #122). Options ride the query
+    // string — this file has no body parser and these verbs don't warrant
+    // introducing one. Auth: opt-in shared secret (config.adminToken); the
+    // default bind is localhost and the WS surface carries the same authority,
+    // so no ambient remoteAddress check is attempted (it breaks behind
+    // proxies both ways and adds nothing on a local bind).
+    if (url.pathname === '/hostmode') {
+      // Carries the operator's free-text reason; when a token is configured,
+      // reads require it too (ACAO:* makes this cross-origin readable).
+      if (this.config.adminToken !== undefined) {
+        const presented = req.headers['x-admin-token'];
+        if (typeof presented !== 'string' || !timingSafeTokenEqual(presented, this.config.adminToken)) {
+          res.writeHead(401, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'x-admin-token required' }));
+          return;
+        }
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(this.framework.getHostModeStatus()));
+      return;
+    }
+    const hostVerb = req.method === 'POST'
+      && ['/quiesce', '/resume', '/maintenance/tick'].includes(url.pathname);
+    if (hostVerb) {
+      // CSRF guard: the x-admin-token header is REQUIRED even when no token
+      // is configured (any value then). A custom header makes the request
+      // non-simple, forcing a CORS preflight — and the OPTIONS response only
+      // allows Content-Type, so browsers refuse to send it cross-origin.
+      // Without this, ACAO:* + query-string options made POST /quiesce a
+      // simple request any web page could fire at a localhost bind.
+      const presented = req.headers['x-admin-token'];
+      const authorized = typeof presented === 'string' && (
+        this.config.adminToken === undefined || timingSafeTokenEqual(presented, this.config.adminToken)
+      );
+      if (!authorized) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          error: this.config.adminToken !== undefined
+            ? 'x-admin-token required (configured token mismatch or missing header)'
+            : 'x-admin-token header required (any value; forces CORS preflight)',
+        }));
+        return;
+      }
+      const respond = (code: number, body: unknown) => {
+        res.writeHead(code, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(body));
+      };
+      void (async () => {
+        try {
+          if (url.pathname === '/quiesce') {
+            const timeoutMs = url.searchParams.get('timeoutMs');
+            respond(200, await this.framework.quiesce({
+              ...(url.searchParams.get('reason')
+                ? { reason: url.searchParams.get('reason')! } : {}),
+              ...(timeoutMs ? { timeoutMs: Number(timeoutMs) } : {}),
+              ...(url.searchParams.get('abandon') === 'true' ? { abandon: true } : {}),
+            }));
+          } else if (url.pathname === '/resume') {
+            respond(200, await this.framework.resume(
+              url.searchParams.get('force') === 'true' ? { force: true } : undefined,
+            ));
+          } else {
+            respond(200, await this.framework.maintenanceTick());
+          }
+        } catch (error) {
+          if (error instanceof ResumeBlockedError) {
+            respond(409, {
+              error: error.message,
+              verdicts: error.verdicts,
+              hostMode: this.framework.getHostModeStatus(),
+            });
+          } else {
+            respond(500, { error: error instanceof Error ? error.message : String(error) });
+          }
+        }
+      })().catch(() => {
+        // The client went away mid-drain: respond() threw, and the fallback
+        // respond(500) threw again. Nothing left to tell anyone.
+      });
+      return;
+    }
+
     res.writeHead(404, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ error: 'Not found' }));
   }

package/src/api/types.ts

@@ -539,4 +539,19 @@ export interface ApiServerConfig {
   path?: string;
   /** Enable HTTP endpoints alongside WebSocket (default: true) */
   enableHttp?: boolean;
+  /** Opt-in shared secret for the HTTP host verbs (POST /quiesce, /resume,
+   *  /maintenance/tick). When set, those requests must carry it in the
+   *  `x-admin-token` header (401 otherwise). Unset preserves the historical
+   *  bind-address-is-the-security-model behavior — the default bind is
+   *  localhost; deployments that front the port with a proxy should set this. */
+  adminToken?: string;
+  /**
+   * Browser origins allowed to open the WebSocket. Browsers do not apply
+   * CORS to WebSocket handshakes, so without this check any web page the
+   * operator visits could drive the WS command surface on a localhost bind.
+   * Upgrades with no Origin header (non-browser clients) always pass; a
+   * browser Origin passes when it names this server's own host (the
+   * request's Host header) or appears here. Default: none beyond same-host.
+   */
+  allowedOrigins?: string[];
 }