@animalabs/agent-framework 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",

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';
@@ -11030,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
@@ -11557,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