@animalabs/agent-framework 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
   "license": "MIT",
   "dependencies": {
     "@animalabs/chronicle": "^0.4.0",
-    "@animalabs/context-manager": "^0.10.0",
+    "@animalabs/context-manager": "^0.11.0",
     "@animalabs/membrane": "^0.5.78",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",

package/src/framework.ts

@@ -21,6 +21,7 @@ import type {
   FrameworkConfig,
   InferencePolicy,
   ErrorPolicy,
+  ProviderHoldHook,
   ErrorAction,
   FrameworkState,
   TraceEvent,
@@ -97,6 +98,7 @@ import {
 } from './code-execution/tool-definition.js';
 import { splitProseSegments } from './prose-segments.js';
 import { cumulativeDelta } from './usage-accounting.js';
+import { stampThinkingTokenEstimates } from './thinking-token-stamp.js';
 
 /** Detect a supported image media type from magic bytes (the model API
  *  rejects mislabeled media types, so trust bytes over extensions).
@@ -744,6 +746,12 @@ interface ProviderAccelerationCooldown {
   heldRequests: InferenceRequest[];
   reason: string;
   failures: number;
+  /** Set on a host-requested hold (config.providerHold): the error to
+   *  re-present to the hook when this slice expires. */
+  hostHoldError?: Error;
+  /** Armed by an auxiliary (compression) failure with no primary involved:
+   *  release reopens auxiliary admission without synthesising an inference. */
+  auxiliaryOrigin?: boolean;
 }
 interface ProviderAccelerationRecovery {
   startedAt: number;
@@ -948,6 +956,7 @@ export class AgentFramework {
   private providerAccelerationLastRecovery: Map<string, ProviderAccelerationReceipt> = new Map();
   private providerAccelerationDefaultCooldownMs = PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS;
   private providerAccelerationJitterMs = PROVIDER_ACCELERATION_JITTER_MS;
+  private providerHoldHook: ProviderHoldHook | undefined;
   private providerAdmissionClosed = false;
   /** Last time we reported stale (busy-requeued) inference requests, per agent. */
   private staleWarnAt = new Map<string, number>();
@@ -1452,6 +1461,7 @@ export class AgentFramework {
       normalizeDiscordAwarenessDeadline(config.discordAwarenessDeadlineMs),
       new OperatorLog(operatorLogPath),
     );
+    framework.providerHoldHook = config.providerHold;
 
     // If an offline recovery process crashed after switching Chronicle but
     // before committing its prepared marker batch, the active branch is the
@@ -1915,6 +1925,14 @@ export class AgentFramework {
     }
     gate.auxiliaryInFlight++;
     try { return await run(); }
+    catch (error) {
+      // Compression can be the first call to find a spent quota (idle agent,
+      // scheduled maintenance). Arm the host hold so later passes wait at the
+      // gate instead of retrying into it; this pass still fails to its caller.
+      const agent = this.agents.get(agentName);
+      if (agent && error instanceof Error) this.holdProviderAcceleration(agent, error, undefined, true);
+      throw error;
+    }
     finally {
       gate.auxiliaryInFlight = Math.max(0, gate.auxiliaryInFlight - 1);
       if (gate.auxiliaryInFlight === 0) for (const resolve of gate.idleWaiters.splice(0)) resolve();
@@ -1941,27 +1959,75 @@ export class AgentFramework {
     return a.agentName === b.agentName && a.reason === b.reason && a.source === b.source &&
       a.timestamp === b.timestamp && a.channelId === b.channelId;
   }
-  private holdProviderAcceleration(agent: Agent, error: Error, trigger?: InferenceRequest): boolean {
-    if (this.ephemeralRuns.has(agent.name) || this.conversationAgentHomes.has(agent.name) || !isOrganizationAccelerationRateLimit(error)) return false;
-    const now = Date.now(); const delayMs = this.accelerationCooldownMs(agent.name, error);
+  private consultProviderHold(error: Error, agentName: string): { holdMs: number; reason: string } | undefined {
+    if (!this.providerHoldHook) return undefined;
+    try {
+      const hold = this.providerHoldHook(error, agentName, { model: this.agents.get(agentName)?.model });
+      if (!hold || !Number.isFinite(hold.holdMs) || hold.holdMs <= 0) return undefined;
+      return { holdMs: Math.min(PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, Math.max(1_000, hold.holdMs)),
+        reason: typeof hold.reason === 'string' && hold.reason ? hold.reason : error.message };
+    } catch (err) {
+      console.error(`[provider-cooldown] providerHold hook threw for ${agentName}; treating as no hold:`, err);
+      return undefined;
+    }
+  }
+  /** A host hold whose slice expired: ask the host again before spending an
+   *  inference on it. True = extended in place (held requests stay held). */
+  private extendHostProviderHold(agentName: string, cooldown: ProviderAccelerationCooldown): boolean {
+    if (!cooldown.hostHoldError) return false;
+    const hold = this.consultProviderHold(cooldown.hostHoldError, agentName);
+    if (!hold) return false;
+    clearTimeout(cooldown.timer);
+    cooldown.until = Date.now() + hold.holdMs;
+    cooldown.timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agentName), hold.holdMs);
+    cooldown.timer.unref?.();
+    if (hold.reason !== cooldown.reason) {
+      cooldown.reason = hold.reason;
+      console.error(`[provider-cooldown] agent=${agentName} host hold extended — ${hold.reason}`);
+    }
+    return true;
+  }
+  private holdProviderAcceleration(agent: Agent, error: Error, trigger?: InferenceRequest, auxiliary = false): boolean {
+    if (this.ephemeralRuns.has(agent.name) || this.conversationAgentHomes.has(agent.name)) return false;
+    // The host knows more than the message wording does: ask it first. An
+    // auxiliary failure arms host holds only — the built-in acceleration
+    // cooldown stays a primary-path mechanism.
+    const hostHold = this.consultProviderHold(error, agent.name);
+    const acceleration = !hostHold && !auxiliary && isOrganizationAccelerationRateLimit(error);
+    if (!acceleration && !hostHold) return false;
+    const now = Date.now(); const delayMs = hostHold ? hostHold.holdMs : this.accelerationCooldownMs(agent.name, error as MembraneError);
     const existing = this.providerAccelerationCooldowns.get(agent.name);
     const held = existing?.heldRequests ?? [];
     if (trigger && !held.some((r) => this.sameInferenceRequest(r, trigger))) held.push(trigger);
     if (existing) clearTimeout(existing.timer);
     const timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agent.name), delayMs); timer.unref?.();
     this.providerAccelerationCooldowns.set(agent.name, { startedAt: existing?.startedAt ?? now,
-      until: now + delayMs, timer, heldRequests: held, reason: error.message,
-      failures: (existing?.failures ?? 0) + 1 });
+      until: now + delayMs, timer, heldRequests: held, reason: hostHold?.reason ?? error.message,
+      failures: (existing?.failures ?? 0) + 1, ...(hostHold ? { hostHoldError: error } : {}),
+      ...(auxiliary && (!existing || existing.auxiliaryOrigin) ? { auxiliaryOrigin: true } : {}) });
+    if (auxiliary && !existing) {
+      console.error(`[provider-cooldown] agent=${agent.name} host hold (${hostHold!.reason}) from an auxiliary call — ` +
+        `holding primary/auxiliary for ${delayMs}ms`);
+      return true;
+    }
     const gate = this.providerGate(agent.name); gate.primaryPending = true;
     this.providerAccelerationRecoveries.set(agent.name, { startedAt: existing?.startedAt ?? now,
       failures: (existing?.failures ?? 0) + 1, heldRequests: held.length, reason: error.message });
-    console.error(`[provider-cooldown] agent=${agent.name} organization acceleration 429 — ` +
+    console.error(`[provider-cooldown] agent=${agent.name} ` +
+      `${hostHold ? `host hold (${hostHold.reason})` : 'organization acceleration 429'} — ` +
       `holding primary/auxiliary for ${delayMs}ms; ${held.length} request(s) retained`);
     return true;
   }
   private releaseProviderAccelerationCooldown(agentName: string): void {
     const cooldown = this.providerAccelerationCooldowns.get(agentName); if (!cooldown) return;
+    if (this.extendHostProviderHold(agentName, cooldown)) return;
     clearTimeout(cooldown.timer); this.providerAccelerationCooldowns.delete(agentName);
+    if (cooldown.auxiliaryOrigin && cooldown.heldRequests.length === 0) {
+      // Nobody asked for an inference while parked: just reopen the gate.
+      console.error(`[provider-cooldown] agent=${agentName} auxiliary hold released after ${Date.now() - cooldown.startedAt}ms`);
+      this.flushAuxiliaryAdmission(agentName);
+      return;
+    }
     const recovery = this.providerAccelerationRecoveries.get(agentName);
     if (recovery) { recovery.releasedAt = Date.now(); recovery.heldRequests = cooldown.heldRequests.length; }
     const requests = cooldown.heldRequests.length > 0 ? cooldown.heldRequests : [{ agentName,
@@ -7322,7 +7388,7 @@ export class AgentFramework {
 
       const providerCooldown = this.providerAccelerationCooldowns?.get(agentName);
       if (providerCooldown) {
-        if (now < providerCooldown.until) {
+        if (now < providerCooldown.until || this.extendHostProviderHold(agentName, providerCooldown)) {
           for (const req of requests) {
             if (!providerCooldown.heldRequests.some((r) => this.sameInferenceRequest(r, req))) {
               providerCooldown.heldRequests.push(req);
@@ -8413,6 +8479,12 @@ export class AgentFramework {
       cacheCreationTokens: 0,
       cacheReadTokens: 0,
     };
+    // Output tokens billed since this turn's assistant blocks were last
+    // persisted. The residual over the round's visible blocks is the price of
+    // its hidden thinking, stamped on the signed blocks at persist time
+    // (thinking-token-stamp.ts). Accumulates across max_tokens continuations
+    // within a round; reset at each stamp.
+    let outputTokensSinceStamp = 0;
     // This turn's alive-marker, set at startAgentStream entry. Safe to read
     // from the map here: the turn-alive busy check in processInferenceRequests
     // means no successor turn can have replaced it while we compiled.
@@ -8676,6 +8748,8 @@ export class AgentFramework {
                 });
               }
             }
+            assistantBlocks = stampThinkingTokenEstimates(assistantBlocks, outputTokensSinceStamp);
+            outputTokensSinceStamp = 0;
             this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
 
             // Note: max_tokens truncation cannot produce tool-calls events here.
@@ -8824,9 +8898,11 @@ export class AgentFramework {
                 b.type === 'tool_use' || b.type === 'tool_result' ? i : last,
               -1
             );
-            const terminalContent = lastToolIdx >= 0
-              ? response.content.slice(lastToolIdx + 1)
-              : response.content;
+            const terminalContent = stampThinkingTokenEstimates(
+              lastToolIdx >= 0 ? response.content.slice(lastToolIdx + 1) : response.content,
+              outputTokensSinceStamp,
+            );
+            outputTokensSinceStamp = 0;
             // This is a whole-response boundary, not a trailing-prose
             // classifier. If the turn executed any genuine structured tool
             // call, preserve its later prose exactly as ordinary history.
@@ -9489,6 +9565,7 @@ export class AgentFramework {
               ),
             };
             previousUsage = cumulativeUsage;
+            outputTokensSinceStamp += perCallUsage.outputTokens;
             const strat = (agent as unknown as {
               getContextManager?: () => { getStrategy?: () => unknown };
             }).getContextManager?.()?.getStrategy?.() as
@@ -11349,6 +11426,8 @@ export class AgentFramework {
             auxiliaryInFlight: gate?.auxiliaryInFlight ?? 0,
             auxiliaryDeferred: gate?.deferredAuxiliary ?? 0,
             cooldownUntil: cooldown?.until ?? null,
+            cooldownReason: cooldown?.reason ?? null,
+            hostHold: cooldown?.hostHoldError !== undefined,
             heldRequests: cooldown?.heldRequests.length ?? 0,
             lastRecovery: this.providerAccelerationLastRecovery?.get(name) ?? null,
           };

package/src/thinking-token-stamp.ts

@@ -0,0 +1,95 @@
+import type { ContentBlock } from '@animalabs/membrane';
+
+/**
+ * Stamp signed thinking blocks with the tokens they will cost when replayed.
+ *
+ * On keep-all models (Opus >= 4.5, Sonnet >= 4.6, Fable/Mythos) every prior
+ * assistant thinking block is sent back and billed as INPUT at the size of
+ * the full hidden chain of thought — whatever its visible text says (empty
+ * under `display: "omitted"`, a short summary under `"summarized"`). The
+ * signature encodes that chain but its length is not a reliable measure
+ * (2.8–8.7 chars/token measured on Opus 4.8), and the stored block carries
+ * no other trace of the size. The response DOES: `usage.output_tokens` is
+ * the visible blocks plus the hidden thinking. So at creation, price each
+ * carrier block from the residual of this call's output tokens over its
+ * visible blocks, split across carriers by signature length, and stamp it
+ * as `tokenEstimate` — the field context-manager already prefers over any
+ * heuristic for thinking, redacted_thinking and image blocks.
+ *
+ * Carriers: `thinking` with a non-empty `signature`, `redacted_thinking`
+ * with `data`. Blocks that already carry a `tokenEstimate` keep it. When the
+ * residual is not positive (no thinking, or the visible estimate over-
+ * shoots) nothing is stamped and context-manager's own fallback applies.
+ *
+ * The visible-block rates mirror context-manager's estimator (prose 2.9,
+ * JSON 2.3 chars/token); their precision matters little — on agentic turns
+ * the hidden thinking is the bulk of the output, and this stamp is what makes
+ * the compiled budget honest (see context-manager `SIGNATURE_CHARS_PER_TOKEN`).
+ *
+ * Wire safety: membrane's Anthropic formatter builds thinking blocks field
+ * by field (`type`, `thinking`, `signature`), so the stamp never reaches the
+ * provider; the signature itself is copied, never edited.
+ */
+const PROSE_CHARS_PER_TOKEN = 2.9;
+const DENSE_CHARS_PER_TOKEN = 2.3;
+
+function carrierWeight(block: ContentBlock): number {
+  if (block.type === 'thinking') {
+    const sig = (block as { signature?: unknown }).signature;
+    return typeof sig === 'string' ? sig.length : 0;
+  }
+  if (block.type === 'redacted_thinking') {
+    const data = (block as { data?: unknown }).data;
+    return typeof data === 'string' ? data.length : 0;
+  }
+  return 0;
+}
+
+function visibleTokens(block: ContentBlock): number {
+  switch (block.type) {
+    case 'text':
+      return Math.ceil((block.text ?? '').length / PROSE_CHARS_PER_TOKEN);
+    case 'tool_use': {
+      let json = '';
+      try { json = JSON.stringify(block.input ?? {}); } catch { json = ''; }
+      return Math.ceil(json.length / DENSE_CHARS_PER_TOKEN) + 20;
+    }
+    case 'thinking':
+      // Unsigned thinking (text-only providers, XML mode): the text is the
+      // whole cost and is priced by context-manager as text.
+      return carrierWeight(block) > 0 ? 0 : Math.ceil((block.thinking ?? '').length / PROSE_CHARS_PER_TOKEN);
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Returns a new array; carrier blocks are shallow-copied with `tokenEstimate`
+ * set, every other block is the same object.
+ */
+export function stampThinkingTokenEstimates(blocks: ContentBlock[], outputTokens: number): ContentBlock[] {
+  if (!Array.isArray(blocks) || blocks.length === 0) return blocks;
+  if (!Number.isFinite(outputTokens) || outputTokens <= 0) return blocks;
+
+  let totalWeight = 0;
+  let visible = 0;
+  for (const block of blocks) {
+    const already = (block as { tokenEstimate?: unknown }).tokenEstimate;
+    const w = typeof already === 'number' ? 0 : carrierWeight(block);
+    if (w > 0) totalWeight += w;
+    else visible += visibleTokens(block);
+    if (typeof already === 'number') visible += already;
+  }
+  if (totalWeight <= 0) return blocks;
+  const residual = outputTokens - visible;
+  if (residual <= 0) return blocks;
+
+  return blocks.map((block) => {
+    const already = (block as { tokenEstimate?: unknown }).tokenEstimate;
+    if (typeof already === 'number') return block;
+    const w = carrierWeight(block);
+    if (w <= 0) return block;
+    const tokenEstimate = Math.max(1, Math.round((residual * w) / totalWeight));
+    return { ...block, tokenEstimate } as ContentBlock;
+  });
+}

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
@@ -150,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;