@animalabs/agent-framework 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.17.0",
+  "version": "0.19.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

@@ -5,7 +5,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeF
 import { JsStore } from '@animalabs/chronicle';
 import type { Membrane, ContentBlock, NormalizedRequest, YieldingStream, ToolResult as MembraneToolResult, ToolResultContentBlock } from '@animalabs/membrane';
 import { MembraneError } from '@animalabs/membrane';
-import { ContextManager, PassthroughStrategy, WindowedPassthroughStrategy } from '@animalabs/context-manager';
+import { ContextManager, PassthroughStrategy, WindowedPassthroughStrategy, OverBudgetError, UncoveredDropError } from '@animalabs/context-manager';
 import type { CacheWireReceipt } from './kv-unified-wire.js';
 import { SUBCONSCIOUS_TOOLS, SUBCONSCIOUS_TOOL_NAMES, type SubconsciousConfig } from './tune-out/tools.js';
 import { TuneOutCoordinator, TUNE_OUT_DEFAULTS } from './tune-out/coordinator.js';
@@ -98,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).
@@ -8478,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.
@@ -8741,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.
@@ -8889,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.
@@ -9554,6 +9565,7 @@ export class AgentFramework {
               ),
             };
             previousUsage = cumulativeUsage;
+            outputTokensSinceStamp += perCallUsage.outputTokens;
             const strat = (agent as unknown as {
               getContextManager?: () => { getStrategy?: () => unknown };
             }).getContextManager?.()?.getStrategy?.() as
@@ -11018,11 +11030,11 @@ export class AgentFramework {
       return;
     }
 
-    // Route synthesized 'think' (private reasoning) and 'skip_reply' (deliberate
-    // stay-silent) tools — handled by the channel registry like the other
+    // Route synthesized 'think' (private reasoning), 'journal' (private
+    // long-form notes) and 'skip_reply' (deliberate stay-silent) tools — handled by the channel registry like the other
     // synthesized channel tools, but they aren't `channel_`-prefixed so they
     // need an explicit route here.
-    if ((enrichedCall.name === 'think' || enrichedCall.name === 'skip_reply') && this.channelRegistry) {
+    if ((enrichedCall.name === 'think' || enrichedCall.name === 'journal' || enrichedCall.name === 'skip_reply') && this.channelRegistry) {
       // skip_reply(wake_in_seconds): arm a gate self-wake so "not replying
       // NOW" can also mean "back in a moment" — ends the turn, then wakes
       // the agent after N seconds unless something else wakes it first
@@ -11545,24 +11557,27 @@ export class AgentFramework {
    * quarantine, OverBudget drain kick) gate on `errorType`, so classification
    * drift between sites would silently disable a safety net.
    *
-   * context-manager's OverBudgetError is recognized by `err.name`: CM does not
-   * export the class from its package root, so a cross-package `instanceof` is
-   * unavailable — but `name` is set in its constructor and survives the package
-   * boundary. Deliberately NOT a message match: the message wording belongs to
-   * CM and can be reworded without warning.
+   * context-manager's refusal errors are matched by a real `instanceof` since
+   * CM exports them from its package root (context-manager#41 / #71; floor
+   * `^0.7.0`, ours is higher). The `err.name` comparison stays as a FALLBACK
+   * only: a deployment that ends up with two CM copies (a peer package
+   * pinning a different version) constructs errors from a different class
+   * object, and `name` — set in the constructor — survives that boundary.
+   * Deliberately NOT a message match: the message wording belongs to CM and
+   * can be reworded without warning.
    */
   private classifyInferenceError(err: Error): { retryable?: boolean; errorType?: string } {
     if (err instanceof MembraneError) {
       return { retryable: err.retryable, errorType: err.type };
     }
-    if (err.name === 'OverBudgetError') {
+    if (err instanceof OverBudgetError || err.name === 'OverBudgetError') {
       return { errorType: 'over_budget' };
     }
     // context-manager's fatal coverage invariant (fix/coverage-invariant-fatal,
     // 2026-07-26): a compile REFUSES rather than shipping a context with
     // silently-dropped messages. Recovery is identical to over_budget — kick
     // the compression drain so summaries cover the un-represented span.
-    if (err.name === 'UncoveredDropError') {
+    if (err instanceof UncoveredDropError || err.name === 'UncoveredDropError') {
       return { errorType: 'context_refusal' };
     }
     return {};

package/src/mcpl/channel-registry.ts

@@ -401,6 +401,22 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
       required: [],
     },
   },
+  {
+    name: 'journal',
+    description:
+      'Write an entry in your private journal. The entry stays in your own context and ' +
+      'memory and is NOT sent to any channel, surface or person. Use it for anything longer ' +
+      'than a line that you want to keep for yourself — reflections, what you decided and ' +
+      'why, notes for later. It does not end your turn and does not affect where ordinary ' +
+      'text is routed; to end the turn without replying, call skip_reply afterwards.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        content: { type: 'string', description: 'The journal entry (private; not sent anywhere).' },
+      },
+      required: ['content'],
+    },
+  },
   {
     name: 'skip_reply',
     description:
@@ -414,7 +430,9 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
       properties: {
         reason: {
           type: 'string',
-          description: 'Optional private note on why you are not replying (not sent anywhere).',
+          description:
+            'Optional ONE short line on why you are not replying (private; not sent anywhere). ' +
+            'Keep it under ~100 characters — put anything longer in journal() first.',
         },
         wake_in_seconds: {
           type: 'number',
@@ -773,7 +791,8 @@ export class ChannelRegistry {
       }
     }
 
-    // Process added channels (validate per-descriptor, register, reconcile)
+    // Process added channels (validate per-descriptor, register; reconcile
+    // after responding, below)
     const accepted: typeof params.added = [];
     if (params.added) {
       for (const channel of params.added) {
@@ -792,10 +811,18 @@ export class ChannelRegistry {
         addedResults.push({ id: channel.id, accepted: true });
         accepted.push(channel);
       }
-      if (accepted.length > 0) await this.reconcileChannels(serverId, accepted);
     }
+
+    // Respond before reconciliation, as handleRegister does. A server that
+    // announces from inside a request it is serving (a tool that refreshes
+    // or subscribes) cannot read the channels/open or channels/close that
+    // reconciling sends until this response arrives; reconciling first
+    // deadlocks both sides until one times out (#160). The verdicts are
+    // settled above, so nothing in the response depends on reconciling.
     responder?.respond({ results: addedResults });
 
+    if (accepted.length > 0) await this.reconcileChannels(serverId, accepted);
+
     this.emitTraceFn({
       type: 'mcpl:channels-changed',
       serverId,
@@ -1218,6 +1245,9 @@ export class ChannelRegistry {
       case 'think':
         return this.handleToolThink(input as { content?: string });
 
+      case 'journal':
+        return this.handleToolJournal(input as { content?: string });
+
       case 'skip_reply':
         return this.handleToolSkipReply(input as { reason?: string; wake_in_seconds?: number });
 
@@ -2670,6 +2700,28 @@ export class ChannelRegistry {
     };
   }
 
+  /**
+   * Handle the synthesized `journal` tool — a private place for long-form
+   * notes. Sends nothing, does not end the turn, does not touch prose routing.
+   *
+   * Why it exists (sill, 2026-09-19): residents were keeping 2–3KB diaries in
+   * `skip_reply.reason`. Long prose in a private-REASONING tool argument
+   * (`skip_reply.reason`, `think.content`) makes replayed history read as a
+   * reasoning trace, and every memory-compression request over it is refused
+   * `reasoning_extraction` regardless of content; the same prose in a
+   * note-taking tool passes (canary record: context-manager
+   * `tool-prose-hoist.ts`, whose fallback rung rewrites old history into calls
+   * to THIS tool — so the result wording below is mirrored there as
+   * DEFAULT_TOOL_PROSE_RESULT; keep the two in step).
+   */
+  private handleToolJournal(_input: { content?: string }): ToolResult {
+    return {
+      success: true,
+      // No echo: the entry is already in the tool_use block.
+      data: { recorded: true, note: 'Journal entry recorded (private — not sent anywhere).' },
+    };
+  }
+
   /**
    * Handle the synthesized `skip_reply` tool — the deliberate "stay silent"
    * signal. A no-op as far as any surface is concerned (sends nothing); its

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;
+  });
+}