@animalabs/agent-framework 0.8.0 → 0.9.0

package/src/mcpl/channel-registry.ts

@@ -34,6 +34,8 @@ import type {
 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 { CapabilityGrant } from './capability-grant.js';
 
 // ============================================================================
 // Typing indicator interval (Discord typing lasts ~10s, so 7s keeps it alive)
@@ -253,7 +255,8 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
       'End your turn WITHOUT sending anything to any channel or surface. Use when you have ' +
       'read the messages but deliberately choose not to reply right now — ambient chatter, ' +
       'nothing to add, or you are waiting. Any plain text you wrote this turn stays private ' +
-      'and is NOT posted. To reply instead, just write plain text (no tool call).',
+      'and is NOT posted. To reply instead, just write plain text (no tool call). ' +
+      'To end this turn but come back on your own shortly, set wake_in_seconds.',
     inputSchema: {
       type: 'object' as const,
       properties: {
@@ -261,6 +264,13 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
           type: 'string',
           description: 'Optional private note on why you are not replying (not sent anywhere).',
         },
+        wake_in_seconds: {
+          type: 'number',
+          description:
+            'Optional self-wake: if nothing else wakes you first, you wake again after this ' +
+            'many seconds (1 = go again almost immediately; clamped to 1–3600). Any other ' +
+            'wake before then cancels it. Omit to stay idle until the next external wake.',
+        },
       },
       required: [],
     },
@@ -458,8 +468,19 @@ export class ChannelRegistry {
     responder?: Responder,
   ): Promise<void> {
     const registeredIds: string[] = [];
+    // §14.5: per-descriptor authorization with ITEMIZED results — one entry
+    // per submitted descriptor. Strict 0.5 servers treat a result without
+    // `results` (or a descriptor missing from it) as rejected, so the shape
+    // is interop-critical, not decorative. Rejection here is per-descriptor
+    // validation; the method-level channels.register gate already ran at the
+    // connection (§14.1).
+    const results: ChannelsRegisterResult['results'] = [];
 
     for (const channel of params.channels) {
+      if (!channel || typeof channel.id !== 'string' || channel.id.length === 0) {
+        results.push({ id: String(channel?.id ?? ''), accepted: false, reason: 'invalid descriptor: missing id' });
+        continue;
+      }
       const key = `${serverId}:${channel.id}`;
       this.channels.set(key, {
         serverId,
@@ -467,11 +488,12 @@ export class ChannelRegistry {
         open: false,
       });
       registeredIds.push(channel.id);
+      results.push({ id: channel.id, accepted: true });
     }
 
     // Respond before reconciliation — the server blocks on this response and
     // can't process channels/open until it arrives.
-    const result: ChannelsRegisterResult = { registered: registeredIds };
+    const result: ChannelsRegisterResult = { registered: registeredIds, results };
     responder?.respond(result);
 
     // One-time migration from the retired recipe policy, then reconcile the
@@ -496,39 +518,69 @@ export class ChannelRegistry {
   async handleChanged(
     serverId: string,
     params: ChannelsChangedParams,
+    responder?: Responder,
   ): Promise<void> {
-    // Process removed channels
+    // §14.5: dual-mode. Request form answers ITEMIZED per-descriptor
+    // results for added channels; Notification form filters itemwise with a
+    // diagnostic. Either way, added descriptors are validated exactly like
+    // channels/register — a changed-set cannot smuggle in what register
+    // would have rejected (PR #79 review blocker 5).
+    const addedResults: Array<{ id: string; accepted: boolean; reason?: string }> = [];
+    // Process removed channels — itemized truthfully: removal of a channel
+    // we never had is reported, not silently accepted.
     if (params.removed) {
       for (const channelId of params.removed) {
         const key = `${serverId}:${channelId}`;
-        this.channels.delete(key);
+        const existed = this.channels.delete(key);
         this.stopTyping(channelId);
+        addedResults.push({ id: channelId, accepted: existed, reason: existed ? undefined : 'not registered' });
       }
     }
 
-    // Process updated channels (replace descriptor, preserve open state)
+    // Process updated channels — validated itemwise exactly like added
+    // (§14.5: a changed-set cannot smuggle in what register would reject),
+    // and every submitted descriptor gets a verdict: a strict server reads
+    // absence from `results` as rejection.
     if (params.updated) {
       for (const channel of params.updated) {
+        if (!channel || typeof channel.id !== 'string' || channel.id.length === 0) {
+          addedResults.push({ id: String(channel?.id ?? ''), accepted: false, reason: 'invalid descriptor: missing id' });
+          this.emitTraceFn({ type: 'mcpl:channel-descriptor-rejected', serverId, reason: 'missing id (update)' });
+          continue;
+        }
         const key = `${serverId}:${channel.id}`;
         const existing = this.channels.get(key);
-        if (existing) {
-          existing.descriptor = channel;
+        if (!existing) {
+          addedResults.push({ id: channel.id, accepted: false, reason: 'not registered — update rejected (§14.5)' });
+          this.emitTraceFn({ type: 'mcpl:channel-descriptor-rejected', serverId, channelId: channel.id, reason: 'update for unregistered channel' });
+          continue;
         }
+        existing.descriptor = channel;
+        addedResults.push({ id: channel.id, accepted: true });
       }
     }
 
-    // Process added channels (register + reconcile durable desired state)
+    // Process added channels (validate per-descriptor, register, reconcile)
+    const accepted: typeof params.added = [];
     if (params.added) {
       for (const channel of params.added) {
+        if (!channel || typeof channel.id !== 'string' || channel.id.length === 0) {
+          addedResults.push({ id: String(channel?.id ?? ''), accepted: false, reason: 'invalid descriptor: missing id' });
+          this.emitTraceFn({ type: 'mcpl:channel-descriptor-rejected', serverId, reason: 'missing id' });
+          continue;
+        }
         const key = `${serverId}:${channel.id}`;
         this.channels.set(key, {
           serverId,
           descriptor: channel,
           open: false,
         });
+        addedResults.push({ id: channel.id, accepted: true });
+        accepted.push(channel);
       }
-      await this.reconcileChannels(serverId, params.added);
+      if (accepted.length > 0) await this.reconcileChannels(serverId, accepted);
     }
+    responder?.respond({ results: addedResults });
 
     this.emitTraceFn({
       type: 'mcpl:channels-changed',
@@ -553,13 +605,11 @@ export class ChannelRegistry {
     const results: ChannelIncomingMessageResult[] = [];
 
     for (const message of params.messages) {
-      // Convert MCPL content blocks to membrane ContentBlocks
-      const convertedContent: ContentBlock[] = message.content.map(convertBlock);
-
-      // Track default publish channel (most recent incoming)
-      this.defaultPublishChannel = message.channelId;
-      this.defaultPublishMessageId = message.messageId;
-      this.defaultPublishThreadId = message.threadId;
+      // §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
+      // inline base64) is allocation and parsing work done for a message
+      // that must be rejected (Sol, PR #79 re-review blocker 2).
 
       // Lazy-register the channel if we've never seen it. A channel can deliver
       // an incoming message before its channels/register (boot enumeration) or
@@ -572,31 +622,44 @@ export class ChannelRegistry {
       // is reachable. The inbound message carries enough to make it publishable,
       // so register it here; a later authoritative channels/register or
       // channels/changed will overwrite this descriptor with the richer one.
+      // §14.5: channels/incoming is validated against the ACTUALLY
+      // REGISTERED channel. An unknown claimed channelId is rejected
+      // per-message with an itemized result — never minted by its first
+      // message (PR #79 review blocker 5: lazy-registration let a server
+      // self-attest a channel identity without ever passing
+      // channels/register authorization). A server whose channel genuinely
+      // exists registers it first; discord's DM case goes through
+      // ensureChannelRegistered on push/event, which creates a CLOSED
+      // routable entry rather than an open self-attested one.
       const incomingKey = `${serverId}:${message.channelId}`;
       if (!this.channels.has(incomingKey)) {
-        const channelLabel =
-          typeof message.metadata?.channelName === 'string' && message.metadata.channelName
-            ? (message.metadata.channelName as string)
-            : message.channelId;
-        this.channels.set(incomingKey, {
-          serverId,
-          descriptor: {
-            id: message.channelId,
-            type: serverId,
-            label: channelLabel,
-            direction: 'bidirectional',
-            address: message.threadId ? { threadId: message.threadId } : undefined,
-            metadata: { lazyRegistered: true },
-          },
-          open: true,
-        });
         this.emitTraceFn({
-          type: 'mcpl:channel-lazy-registered',
+          type: 'mcpl:channel-incoming-rejected',
           serverId,
           channelId: message.channelId,
-          label: channelLabel,
+          reason: 'unknown channel — not registered (§14.5)',
         });
-      } else {
+        results.push({
+          messageId: message.messageId,
+          accepted: false,
+          reason: `unknown channel "${message.channelId}" — register it first (§14.5)`,
+        });
+        continue;
+      }
+
+      // ACCEPTED from here down: semantic processing only for admitted
+      // messages. §16.3 core-tag closure, then content conversion.
+      if (message.tags) message.tags = expandCoreTags(message.tags);
+      const convertedContent: ContentBlock[] = message.content.map(convertBlock);
+
+      // Track default publish channel (most recent ACCEPTED incoming) —
+      // 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 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
@@ -923,7 +986,7 @@ export class ChannelRegistry {
         return this.handleToolThink(input as { content?: string });
 
       case 'skip_reply':
-        return this.handleToolSkipReply(input as { reason?: string });
+        return this.handleToolSkipReply(input as { reason?: string; wake_in_seconds?: number });
 
       default:
         return { success: false, error: `Unknown channel tool: ${toolName}`, isError: true };
@@ -1181,6 +1244,19 @@ export class ChannelRegistry {
     const server = this.serverRegistry.getServer(serverId);
     if (!server) return;
 
+    // §14.1: channels/open + channels/close require channels.lifecycle.
+    // Skipping reconciliation for an ungranted server is the enforcement —
+    // its channels simply stay in whatever state the server chose, and the
+    // host never directs lifecycle it was not granted authority over.
+    if (!CapabilityGrant.of(server).has('channels.lifecycle')) {
+      this.emitTraceFn({
+        type: 'mcpl:channel-reconcile-skipped',
+        serverId,
+        reason: 'channels.lifecycle not in effective grant (§14.1)',
+      });
+      return;
+    }
+
     // Channels the subscription policy freshly admitted in THIS pass —
     // announced to the agent as one batched notice after the loop, so a
     // first boot on a new policy doesn't produce one notice per channel.
@@ -1255,6 +1331,10 @@ export class ChannelRegistry {
    * (typing timer lifecycle is still managed for when the callback is wired).
    */
   private sendTypingNotification(serverId: string, channelId: string): void {
+    // §14.1: channels/typing requires channels.typing in the grant. Silent
+    // skip — a typing indicator is cosmetic and per-7s, so a diagnostic per
+    // tick would be noise.
+    if (!CapabilityGrant.of(this.serverRegistry.getServer(serverId)).has('channels.typing')) return;
     if (this.sendTypingFn) {
       this.sendTypingFn(serverId, channelId, this.typingMetadata.get(channelId));
     }
@@ -1266,6 +1346,13 @@ export class ChannelRegistry {
   // Private: Channel Lookup
   // ==========================================================================
 
+  /** Descriptors registered by one server — the §14.3 channels/list answer. */
+  descriptorsForServer(serverId: string): ChannelDescriptor[] {
+    return [...this.channels.values()]
+      .filter((e) => e.serverId === serverId)
+      .map((e) => e.descriptor);
+  }
+
   /** Server id owning a registered channel (by descriptor id), or null. */
   getChannelServerId(channelId: string): string | null {
     return this.findChannelEntry(channelId)?.serverId ?? null;
@@ -1370,6 +1457,11 @@ export class ChannelRegistry {
     if (!server) {
       throw new Error(`Server not found: ${entry.serverId}`);
     }
+    if (!CapabilityGrant.of(server).has('channels.lifecycle')) {
+      // Desired state is already recorded — intent sticks; reconciliation
+      // will retry if the grant later widens (§6.7 expansion-on-receipt).
+      throw new Error(`channels.lifecycle not in "${entry.serverId}"'s effective grant (§14.1)`);
+    }
     const result: ChannelsOpenResult = await server.sendChannelsOpen({
       channelId: entry.descriptor.id,
       type: entry.descriptor.type,
@@ -1714,6 +1806,13 @@ export class ChannelRegistry {
     }
 
     try {
+      if (!CapabilityGrant.of(server).has('channels.lifecycle')) {
+        return {
+          success: false,
+          error: `channels.lifecycle not in "${entry.serverId}"'s effective grant (§14.1)`,
+          isError: true,
+        };
+      }
       await server.sendChannelsClose({ channelId: input.channelId });
       entry.open = false;
       return {
@@ -1759,6 +1858,8 @@ export class ChannelRegistry {
       const server = this.serverRegistry.getServer(entry.serverId);
       if (!server) {
         acknowledgmentError = `Server not found: ${entry.serverId}`;
+      } else if (!CapabilityGrant.of(server).has('channels.acknowledge')) {
+        acknowledgmentError = `channels.acknowledge not in "${entry.serverId}"'s effective grant (§14.1)`;
       } else {
         try {
           const result = await server.sendChannelsAcknowledge({
@@ -1827,7 +1928,14 @@ export class ChannelRegistry {
    * tool, so any trailing prose this turn is NOT posted. Replaces the old
    * overloaded use of `think` for staying silent.
    */
-  private handleToolSkipReply(input: { reason?: string }): ToolResult {
+  private handleToolSkipReply(input: { reason?: string; wake_in_seconds?: number }): ToolResult {
+    // The self-wake itself is armed by the framework (which owns the
+    // EventGate) BEFORE this dispatch; when the gate is absent the framework
+    // strips the field so this confirmation stays truthful.
+    const wakeSecs = Number(input.wake_in_seconds);
+    const selfWake = Number.isFinite(wakeSecs) && wakeSecs > 0
+      ? Math.max(1, Math.min(3600, Math.floor(wakeSecs)))
+      : undefined;
     return {
       success: true,
       // The note says "ended the turn" — make it TRUE. Without endTurn the
@@ -1841,7 +1949,9 @@ export class ChannelRegistry {
       // on Fable: ~60% of skip_reply result bytes were verbatim input echo).
       data: {
         skipped: true,
-        note: 'Turn ended; nothing sent.',
+        note: selfWake !== undefined
+          ? `Turn ended; nothing sent. Self-wake in ~${selfWake}s unless something wakes you first.`
+          : 'Turn ended; nothing sent.',
       },
     };
   }
@@ -1907,7 +2017,12 @@ export class ChannelRegistry {
     const matches = [...this.channels.values()].filter((e) => e.descriptor.id === channelId);
     if (matches.length !== 1) return null;
     const server = this.serverRegistry.getServer(matches[0]!.serverId);
-    if (!server?.capabilities?.channels?.streaming) return null;
+    // §5.4: the GRANT gates streaming, not the raw advertisement. The old
+    // `capabilities?.channels?.streaming` check was doubly wrong: undefined
+    // for the boolean `channels: true` shape (masking discord-mcpl's latent
+    // double-post, AUDIT-001), and pre-policy it would have sent before the
+    // server was told anything was granted.
+    if (!CapabilityGrant.of(server).has('channels.streaming')) return null;
     return server;
   }
 
@@ -1999,6 +2114,12 @@ export class ChannelRegistry {
     if (!server) {
       return fail(channelId, `server "${entry.serverId}" not found`);
     }
+    // §14.1: channels/publish requires channels.publish in the grant. The
+    // host not sending is the enforcement — a send to an ungranted server
+    // would have it act on authority it was never told it has.
+    if (!CapabilityGrant.of(server).has('channels.publish')) {
+      return fail(channelId, `channels.publish not in "${entry.serverId}"'s effective grant (§14.1)`);
+    }
 
     const publishParams: ChannelsPublishParams = {
       conversationId,
@@ -2075,6 +2196,13 @@ export class ChannelRegistry {
     }
 
     try {
+      if (!CapabilityGrant.of(server).has('channels.publish')) {
+        return {
+          success: false,
+          error: `channels.publish not in "${server.id}"'s effective grant (§14.1)`,
+          isError: true,
+        };
+      }
       const publishParams: ChannelsPublishParams = {
         conversationId: '', // Framework will fill this when wired
         channelId,

package/src/mcpl/checkpoint-manager.ts

@@ -355,17 +355,37 @@ export class CheckpointManager {
   }
 
   /**
-   * Get the first stateful feature set for a given server.
-   * Returns null if no stateful feature sets are registered.
+   * Resolve a server-managed stateful feature set for a server.
+   *
+   * An explicit feature set is returned only when it is registered and
+   * server-managed. Without one, the fallback is safe only when exactly one
+   * server-managed stateful set exists. Returns null for no match or ambiguity.
    */
-  getStatefulFeatureSet(serverId: string): string | null {
+  getStatefulFeatureSet(serverId: string, featureSet?: string): string | null {
     const prefix = `${serverId}:`;
-    for (const [key] of this.trees) {
-      if (key.startsWith(prefix)) {
-        return key.slice(prefix.length);
-      }
+
+    if (featureSet !== undefined) {
+      const tree = this.trees.get(this.key(serverId, featureSet));
+      return tree && !tree.hostState ? featureSet : null;
     }
-    return null;
+
+    let match: string | null = null;
+    for (const [key, tree] of this.trees) {
+      if (!key.startsWith(prefix) || tree.hostState) continue;
+      if (match !== null) return null;
+      match = key.slice(prefix.length);
+    }
+    return match;
+  }
+
+  /** Whether an untagged tool cannot safely select a server-managed set. */
+  hasAmbiguousServerManagedFeatureSets(serverId: string): boolean {
+    const prefix = `${serverId}:`;
+    let count = 0;
+    for (const [key, tree] of this.trees) {
+      if (key.startsWith(prefix) && !tree.hostState && ++count > 1) return true;
+    }
+    return false;
   }
 
   /**

package/src/mcpl/errors.ts

@@ -14,6 +14,13 @@ import type { JsonRpcError } from './types.js';
 /** Message used a disabled feature set. */
 export const FEATURE_SET_NOT_ENABLED = -32001;
 
+/**
+ * Method requires a capability the host has masked for this server
+ * (McplServerConfig.enabledCapabilities/disabledCapabilities). Host-side
+ * extension code, pending a spec assignment.
+ */
+export const CAPABILITY_DISABLED = -32002;
+
 /** Message used an undeclared feature set. */
 export const UNKNOWN_FEATURE_SET = -32003;
 

package/src/mcpl/feature-set-manager.ts

@@ -18,6 +18,7 @@ import {
   FEATURE_SET_NOT_ENABLED,
   UNKNOWN_FEATURE_SET,
 } from './errors.js';
+import { isKnownCapabilityPath } from './capability-grant.js';
 
 // ============================================================================
 // Error Class
@@ -143,7 +144,16 @@ export class FeatureSetManager {
   initializeServer(
     serverId: string,
     capabilities: McplCapabilities,
-    config?: { enabledFeatureSets?: string[]; disabledFeatureSets?: string[] }
+    config?: { enabledFeatureSets?: string[]; disabledFeatureSets?: string[] },
+    /**
+     * The effective capability grant (§5.4). When provided, §6.4's
+     * FAIL-CLOSED derivation runs: a feature set whose `uses` is absent,
+     * empty, or contains an unrecognized value is disabled with reason
+     * `invalid_uses`; one whose `uses` names an ungranted capability is
+     * disabled with the missing paths recorded. Derivation overrides config
+     * enablement — config can narrow the derivable set, never widen past it.
+     */
+    grant?: import('./capability-grant.js').CapabilityGrant,
   ): FeatureSetsUpdateParams {
     // Cross-package compat: agent-framework's McplCapabilities types
     // featureSets as Record<string, FeatureSetDeclaration>, but mcpl-core-ts
@@ -165,11 +175,16 @@ export class FeatureSetManager {
       enabled: new Set<string>(),
     };
 
-    // Resolve which feature sets to enable
-    const enablePatterns = config?.enabledFeatureSets ?? [];
+    // §5.3 as pinned (mcpl e869744): ABSENT enabledFeatureSets constrains
+    // nothing — every declared set is a candidate and §6.4 derivation
+    // governs. PRESENT is an allowlist ([] = deny-all selection). The old
+    // reading (unmentioned defaults disabled) reversed the pin (PR #79
+    // review blocker 7). FLEET BEHAVIOR CHANGE: configs that omitted
+    // enabledFeatureSets now enable every derivable declared set.
     const disablePatterns = config?.disabledFeatureSets ?? [];
-
-    const toEnable = resolvePatterns(enablePatterns, declared);
+    const toEnable = config?.enabledFeatureSets === undefined
+      ? Object.keys(declared)
+      : resolvePatterns(config.enabledFeatureSets, declared);
     const toDisable = resolvePatterns(disablePatterns, declared);
 
     // Enable matching sets
@@ -182,6 +197,36 @@ export class FeatureSetManager {
       state.enabled.delete(name);
     }
 
+    // §6.4 fail-closed derivation against the grant. Runs AFTER config
+    // resolution so it can only remove: nothing a declaration or a config
+    // says can supply a capability the grant lacks.
+    if (grant) {
+      for (const [name, decl] of Object.entries(declared)) {
+        const uses = (decl as { uses?: unknown }).uses;
+        if (!Array.isArray(uses) || uses.length === 0) {
+          if (state.enabled.delete(name) || true) {
+            console.error(`[mcpl] ${serverId}/${name} disabled: invalid_uses (§6.4 — uses absent or empty)`);
+          }
+          continue;
+        }
+        const unknown = uses.filter((u) => typeof u !== 'string' || !isKnownCapabilityPath(u));
+        if (unknown.length > 0) {
+          state.enabled.delete(name);
+          console.error(
+            `[mcpl] ${serverId}/${name} disabled: invalid_uses (§6.4 — unrecognized: ${unknown.join(', ')})`,
+          );
+          continue;
+        }
+        const missing = (uses as string[]).filter((u) => !grant.has(u));
+        if (missing.length > 0) {
+          state.enabled.delete(name);
+          console.error(
+            `[mcpl] ${serverId}/${name} disabled: missing capabilities ${missing.join(', ')} (§6.4)`,
+          );
+        }
+      }
+    }
+
     this.servers.set(serverId, state);
 
     // Build the update params to send to the server