@animalabs/agent-framework 0.18.0 → 0.20.0

package/src/index.ts

@@ -93,6 +93,19 @@ export type { McplServerConfig } from './mcpl/index.js';
 export { McplServerConnection } from './mcpl/index.js';
 export type { McplHostCapabilities } from './mcpl/index.js';
 
+// MCPL tool lifecycle (RFC-007) and tool classes (RFC-008): the types a host
+// needs to write McplServerConfig.toolLifecycle policy and class tables, and
+// the portable pattern matcher both use.
+export { TOOL_CLASSES, DEFAULT_INPUT_CLASSES, globMatch } from './mcpl/index.js';
+export type {
+  ToolClass,
+  ToolClassSource,
+  ToolLifecycleConfig,
+  ToolLifecycleNarrowing,
+  ToolLifecycleParams,
+  ToolObserveRule,
+} from './mcpl/index.js';
+
 // Per-channel conversation routing
 export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './mcpl/index.js';
 export type {

package/src/mcpl/capability-grant.ts

@@ -48,6 +48,9 @@ const VOCABULARY: CapNode = {
   modelInfo: null,
   inferenceRequest: { streaming: null },
   inferenceLifecycle: null,
+  // RFC-007: metadata observation and argument observation are separate
+  // leaves, separately granted (observation never bundles content).
+  toolLifecycle: { observe: null, inputs: null },
   contextHooks: {
     beforeInference: {
       observe: null,
@@ -217,8 +220,36 @@ export function capabilityPatternMatches(pattern: string, path: string): boolean
 // The grant
 // ============================================================================
 
-/** §13.4: denied unless explicitly enabled by host config. */
-const DENY_BY_DEFAULT: readonly string[] = ['contextHooks.beforeInference.inject.system'];
+/** §13.4: denied unless explicitly enabled by host config. RFC-007 adds both
+ *  tool-lifecycle leaves: observing other servers' tool use (and, above all,
+ *  their arguments) is an operator decision, never a default. */
+const DENY_BY_DEFAULT: readonly string[] = [
+  'contextHooks.beforeInference.inject.system',
+  'toolLifecycle.observe',
+  'toolLifecycle.inputs',
+];
+
+/**
+ * RFC-007: stating a `toolLifecycle.observe` / `.inputs` policy block in the
+ * server's config is itself the explicit grant of that path — the operator
+ * who wrote a narrowing meant to grant what it narrows.
+ */
+function configGrants(config: Pick<McplServerConfig, 'toolLifecycle'>, path: string): boolean {
+  const key = path === 'toolLifecycle.observe' ? 'observe' : path === 'toolLifecycle.inputs' ? 'inputs' : null;
+  if (!key) return false;
+  const block = (config.toolLifecycle as Record<string, unknown> | undefined)?.[key];
+  if (block === undefined) return false;
+  // Only a policy OBJECT is a grant. `observe: false` (or null, or a string)
+  // must never read as "granted with no narrowing".
+  if (!isPlainObject(block)) {
+    console.error(
+      `[mcpl] toolLifecycle.${key} is ${JSON.stringify(block)}, not a policy object — ` +
+        `not granted by this block (RFC-007 §4.1)`,
+    );
+    return false;
+  }
+  return true;
+}
 
 export class CapabilityGrant {
   /** Exact granted paths (already expanded — no patterns stored). */
@@ -286,7 +317,7 @@ export class CapabilityGrant {
  */
 export function computeGrant(
   capabilities: McplCapabilities | null,
-  config: Pick<McplServerConfig, 'enabledCapabilities'>,
+  config: Pick<McplServerConfig, 'enabledCapabilities' | 'toolLifecycle'>,
   opts?: {
     /** §5.1: `tools` is sourced from the OUTER standard MCP
      *  `capabilities.tools` — pass its presence here. The experimental
@@ -304,16 +335,33 @@ export function computeGrant(
     !!config.enabledCapabilities?.some((pat) => capabilityPatternMatches(pat, path));
 
   for (const path of advertised) {
-    if (DENY_BY_DEFAULT.includes(path) && !explicitlyEnabled(path)) {
+    if (DENY_BY_DEFAULT.includes(path) && !explicitlyEnabled(path) && !configGrants(config, path)) {
       denied.push(path);
       console.error(
-        `[mcpl] "${path}" advertised but DENIED BY DEFAULT (SPEC §13.4) — ` +
-          `grant it explicitly via enabledCapabilities if intended`,
+        `[mcpl] "${path}" advertised but DENIED BY DEFAULT (${path.startsWith('toolLifecycle.') ? 'RFC-007' : 'SPEC §13.4'}) — ` +
+          `grant it explicitly via enabledCapabilities${path.startsWith('toolLifecycle.') ? ' or a toolLifecycle policy block' : ''} if intended`,
       );
       continue;
     }
     granted.add(path);
   }
 
+  // RFC-007 §4.1/§4.3 diagnostics — loud, because each is a grant that
+  // silently delivers less than the operator probably meant.
+  if (granted.has('toolLifecycle.inputs')) {
+    if (!granted.has('toolLifecycle.observe')) {
+      console.error('[mcpl] toolLifecycle.inputs granted without toolLifecycle.observe — delivers nothing (RFC-007 §4.1)');
+    }
+    const n = config.toolLifecycle?.inputs;
+    const hasTerm = isPlainObject(n) && ((Array.isArray(n.tools) && n.tools.length > 0)
+      || n.classes === 'default' || (Array.isArray(n.classes) && n.classes.length > 0));
+    if (!hasTerm) {
+      console.error(
+        '[mcpl] toolLifecycle.inputs granted with no tools/classes narrowing — treated as narrowed to NO tools; ' +
+          'inputs is never unconditional (RFC-007 §4.3)',
+      );
+    }
+  }
+
   return new CapabilityGrant(granted, denied.sort());
 }

package/src/mcpl/channel-registry.ts

@@ -26,6 +26,7 @@ import type {
   ChannelsIncomingParams,
   ChannelsIncomingResult,
   ChannelIncomingMessageResult,
+  ChannelIncomingMessage,
   ChannelsPublishParams,
   ChannelsOpenResult,
   ChannelHistoryRequest,
@@ -36,6 +37,7 @@ import type { McplServerRegistry } from './server-registry.js';
 import type { FeatureSetManager } from './feature-set-manager.js';
 import type { ToolDefinition, ToolResult, ProcessEvent } from '../types/index.js';
 import { expandCoreTags } from './tags.js';
+import { validateCoalescedContent } from './push-coalescer.js';
 import { CapabilityGrant } from './capability-grant.js';
 
 // ============================================================================
@@ -401,6 +403,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 +432,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',
@@ -434,6 +454,17 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
 // ============================================================================
 
 interface ChannelRegistryOptions {
+  /**
+   * RFC-006: an admitted `channels/incoming` message carrying `coalesce`, with
+   * the event the ordinary path would have queued. The handler decides
+   * replace / append / withdraw and returns the per-message result. Throws a
+   * `CoalesceError` for a malformed or unauthorized occurrence.
+   */
+  handleCoalescedIncoming?: (
+    serverId: string,
+    message: ChannelIncomingMessage,
+    event: McplChannelIncomingEvent,
+  ) => Promise<ChannelIncomingMessageResult>;
   /** Chronicle store used for durable desired channel lifecycle state. */
   store?: JsStore;
   /** Callback to determine whether an incoming message should trigger inference. */
@@ -625,6 +656,7 @@ export class ChannelRegistry {
   /** One-time migration inputs from the retired recipe auto-open policy. */
   private legacyPolicies = new Map<string, 'auto' | 'manual' | string[]>();
   private migratedLegacyPolicies = new Set<string>();
+  private handleCoalescedIncoming?: ChannelRegistryOptions['handleCoalescedIncoming'];
 
   constructor(
     serverRegistry: McplServerRegistry,
@@ -640,6 +672,7 @@ export class ChannelRegistry {
       ) => void;
     },
   ) {
+    this.handleCoalescedIncoming = options?.handleCoalescedIncoming;
     this.serverRegistry = serverRegistry;
     this.featureSetManager = featureSetManager;
     this.pushEventFn = pushEventFn;
@@ -773,7 +806,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 +826,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,
@@ -811,14 +853,23 @@ export class ChannelRegistry {
    * Converts each message's content, pushes McplChannelIncomingEvent to the
    * queue, and responds with per-message results.
    */
-  handleIncoming(
+  async handleIncoming(
     serverId: string,
     params: ChannelsIncomingParams,
     responder?: Responder,
-  ): void {
+  ): Promise<void> {
     const results: ChannelIncomingMessageResult[] = [];
 
     for (const message of params.messages) {
+      if (!message || typeof message.channelId !== 'string' || !message.channelId
+        || typeof message.messageId !== 'string' || !message.messageId) {
+        results.push({
+          messageId: typeof message?.messageId === 'string' ? message.messageId : '',
+          accepted: false,
+          reason: message?.coalesce !== undefined ? 'coalesce_invalid' : 'invalid channel/message identity',
+        });
+        continue;
+      }
       // §14.5 FIRST, before ANY semantic processing: admission against the
       // actually-registered channel precedes tag expansion and content
       // conversion — decoding an unregistered sender's payload (including
@@ -863,6 +914,17 @@ export class ChannelRegistry {
 
       // ACCEPTED from here down: semantic processing only for admitted
       // messages. §16.3 core-tag closure, then content conversion.
+      const coalesced = message.coalesce !== undefined && !!this.handleCoalescedIncoming;
+      if (coalesced) {
+        // RFC-006 §13: malformed content on a coalesced item is that item's
+        // failure, not the batch's — check the shape before converting.
+        try {
+          validateCoalescedContent(message.content);
+        } catch (error) {
+          results.push({ messageId: message.messageId, accepted: false, reason: 'coalesce_invalid' });
+          continue;
+        }
+      }
       if (message.tags) message.tags = expandCoreTags(message.tags);
       const convertedContent: ContentBlock[] = message.content.map(convertBlock);
 
@@ -870,16 +932,19 @@ export class ChannelRegistry {
       // deliberately after §14.5 validation: a rejected message from an
       // unregistered channel must not retarget outbound speech (the locus is
       // exactly the authority a self-attested channel would be stealing).
-      this.defaultPublishChannel = message.channelId;
-      this.defaultPublishMessageId = message.messageId;
-      this.defaultPublishThreadId = message.threadId;
-      {
+      // A coalesced item is "accepted" only once the coalescer admits it, so
+      // for those this runs after the hook (below).
+      const markAccepted = () => {
+        this.defaultPublishChannel = message.channelId;
+        this.defaultPublishMessageId = message.messageId;
+        this.defaultPublishThreadId = message.threadId;
         // A server sending channels/incoming is authoritative evidence that
         // the transport is actually open. This repairs transient status only;
         // durable desired state still changes exclusively through lifecycle
         // operations.
         this.channels.get(incomingKey)!.open = true;
-      }
+      };
+      if (!coalesced) markAccepted();
 
       // Determine whether to trigger inference
       let triggerInference = true;
@@ -918,6 +983,26 @@ export class ChannelRegistry {
         triggerInference,
       };
 
+      if (coalesced) {
+        // RFC-006 §14.3: a coalesced message is admitted like any other and
+        // then handed, with the event the ordinary path would have queued, to
+        // the coalescer, which replaces, appends or withdraws. Malformed
+        // `coalesce` is a per-message failure; siblings are unaffected.
+        try {
+          const result = await this.handleCoalescedIncoming!(serverId, message, event);
+          if (result.accepted) markAccepted();
+          results.push(result);
+        } catch (error) {
+          const err = error as Error & { code?: number };
+          results.push({
+            messageId: message.messageId,
+            accepted: false,
+            reason: err.code === -32602 ? 'coalesce_invalid' : err.message,
+          });
+        }
+        continue;
+      }
+
       // Push to the processing queue
       // Cast through unknown because McplChannelIncomingEvent matches the
       // CustomEvent `${string}:${string}` type pattern but lacks an index signature.
@@ -1128,6 +1213,18 @@ export class ChannelRegistry {
    * Get the descriptor for a channel by its channelId (first match across
    * servers). Used by the conversation router for DM classification.
    */
+  /**
+   * RFC-006 §3.2: is `channelId` registered BY `serverId` through a server
+   * declaration (channels/register, channels/changed) or an authorized open?
+   * A placeholder minted from a push's `origin` (ensureChannelRegistered)
+   * does not count: a channel id appearing in an untrusted field is not a
+   * registration.
+   */
+  isDeclaredChannel(serverId: string, channelId: string): boolean {
+    const entry = this.channels.get(`${serverId}:${channelId}`);
+    return !!entry && !(entry.descriptor.metadata as { lazyRegistered?: boolean } | undefined)?.lazyRegistered;
+  }
+
   getDescriptor(channelId: string): ChannelDescriptor | undefined {
     return this.findChannelEntry(channelId)?.descriptor;
   }
@@ -1218,6 +1315,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 });
 
@@ -2345,6 +2445,44 @@ export class ChannelRegistry {
     return { error: `no channel matches "${trimmed}"`, ...(near.length ? { candidates: near } : {}) };
   }
 
+  /**
+   * The `>>` target to show an agent for a channel: one whitespace-free token
+   * that `resolveProseTarget()` maps back to this same channel. The prefix
+   * grammar takes the target as the first non-whitespace run, so a label with
+   * a space can't be quoted verbatim: `>>#DM: alice` parses as target `#DM:`
+   * plus body `alice …`, and `>>#fable (antra's server)` delivers
+   * `(antra's server)` as text. Tried in order: `@name` for a DM, `#label`,
+   * `#name` (label without its server suffix), the descriptor id.
+   *
+   * Undefined when there is no safe token: the channel isn't registered (on
+   * `serverId`, when given), no candidate is whitespace-free and resolves back,
+   * or the id is registered by more than one server. A resolved target names a
+   * channel by id alone, and ids are unique only within a connection, so a
+   * shared id could route the reply through the wrong server.
+   */
+  proseTargetFor(channelId: string, serverId?: string): string | undefined {
+    const sameId = [...this.channels.values()].filter((e) => e.descriptor.id === channelId);
+    const entry = serverId ? sameId.find((e) => e.serverId === serverId) : sameId[0];
+    if (!entry || sameId.length > 1) return undefined;
+    const d = entry.descriptor;
+    const label = d.label ?? '';
+    const meta = d.metadata as { channelType?: string; recipientName?: string } | undefined;
+    const isDm = meta?.channelType === 'dm' || label.toLowerCase().startsWith('dm: ') || d.id.includes(':dm:');
+    const dmName = meta?.recipientName ?? (label.toLowerCase().startsWith('dm: ') ? label.slice(4) : undefined);
+    const bare = label.replace(/^#/, '');
+    const candidates = [
+      ...(isDm && dmName ? [`@${dmName}`] : []),
+      ...(bare ? [`#${bare}`, `#${bare.replace(/\s*\([^)]*\)\s*$/, '')}`] : []),
+      d.id,
+    ];
+    for (const c of candidates) {
+      if (/\s/.test(c) || c === '#') continue;
+      const r = this.resolveProseTarget(c);
+      if ('channelId' in r && r.channelId === d.id) return c;
+    }
+    return undefined;
+  }
+
   /**
    * Open a channel because something was DELIVERED into it (explicit send
    * tool or routed speech). Sending into a closed channel is not a thing:
@@ -2670,6 +2808,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/mcpl/index.ts

@@ -118,6 +118,35 @@ export { ScopeManager, type ElevationHandler } from './scope-manager.js';
 // Hook orchestration (beforeInference/afterInference fan-out)
 export { HookOrchestrator } from './hook-orchestrator.js';
 
+export {
+  ToolLifecycleEmitter,
+  parseToolObserveParams,
+  selectFields,
+  boundInput,
+  openingFor,
+  DEFAULT_MAX_INPUT_BYTES,
+  TOOL_OBSERVE_LIMITS,
+  type ToolPhase,
+  type ToolLifecycleParams,
+  type ToolObserveRule,
+  type ToolObserveMatch,
+  type ToolLifecycleConfig,
+  type ToolLifecycleNarrowing,
+} from './tool-lifecycle.js';
+export {
+  TOOL_CLASSES,
+  TOOL_CLASS_META_KEY,
+  DEFAULT_INPUT_CLASSES,
+  BUILTIN_TOOL_CLASSES,
+  parseDeclaredClasses,
+  resolveToolClass,
+  isToolClass,
+  type ToolClass,
+  type ToolClassSource,
+  type EffectiveToolClass,
+} from './tool-classes.js';
+export { globMatch } from './tool-glob.js';
+
 // Push events (Section 9)
 export { PushHandler } from './push-handler.js';
 export type { McplPushEvent } from './push-handler.js';