@animalabs/agent-framework 0.7.4 → 0.9.0

package/dist/src/mcpl/channel-registry.js

@@ -12,6 +12,8 @@
  * - Expose synthesized tools: channel_list, channel_open, channel_close, channel_publish
  * - Build channel context for beforeInference params
  */
+import { expandCoreTags } from './tags.js';
+import { CapabilityGrant } from './capability-grant.js';
 // ============================================================================
 // Typing indicator interval (Discord typing lasts ~10s, so 7s keeps it alive)
 // ============================================================================
@@ -166,7 +168,8 @@ const CHANNEL_TOOL_DEFINITIONS = [
         description: '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',
             properties: {
@@ -174,14 +177,21 @@ const CHANNEL_TOOL_DEFINITIONS = [
                     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: [],
         },
     },
 ];
-// ============================================================================
-// ChannelRegistry
-// ============================================================================
+/** The machine decision sources a module-origin channel_close may record.
+ *  Closed on purpose: honest provenance means a small, auditable vocabulary,
+ *  not arbitrary self-description. */
+export const MACHINE_CLOSE_SOURCES = new Set(['subscription-gc', 'housekeeping']);
 export class ChannelRegistry {
     serverRegistry;
     featureSetManager;
@@ -245,7 +255,18 @@ export class ChannelRegistry {
      */
     async handleRegister(serverId, params, responder) {
         const registeredIds = [];
+        // §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 = [];
         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,
@@ -253,10 +274,11 @@ 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 = { registered: registeredIds };
+        const result = { registered: registeredIds, results };
         responder?.respond(result);
         // One-time migration from the retired recipe policy, then reconcile the
         // server to Chronicle-backed desired state.
@@ -275,37 +297,67 @@ export class ChannelRegistry {
      * Processes added (register + reconcile), removed (delete + stop typing),
      * and updated (replace descriptor) channels.
      */
-    async handleChanged(serverId, params) {
-        // Process removed channels
+    async handleChanged(serverId, params, responder) {
+        // §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 = [];
+        // 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 = [];
         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',
             serverId,
@@ -323,12 +375,11 @@ export class ChannelRegistry {
     handleIncoming(serverId, params, responder) {
         const results = [];
         for (const message of params.messages) {
-            // Convert MCPL content blocks to membrane ContentBlocks
-            const convertedContent = 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
             // channels/changed (post-boot create / View-permission grant) round-trip
@@ -340,31 +391,43 @@ 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
-                    : 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)',
                 });
+                results.push({
+                    messageId: message.messageId,
+                    accepted: false,
+                    reason: `unknown channel "${message.channelId}" — register it first (§14.5)`,
+                });
+                continue;
             }
-            else {
+            // 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 = 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
@@ -604,15 +667,24 @@ export class ChannelRegistry {
     }
     /**
      * Handle a call to one of the synthesized channel tools.
+     *
+     * `origin` is TRUSTED DISPATCH CONTEXT, supplied by the framework's own
+     * routing (dispatchChannelToolCall and the public executeToolCall for
+     * model-origin calls, the framework's private ModuleRegistry closure for
+     * module ctx.callTool) — never derived from tool input. Machine
+     * provenance on channel_close is honored only for module origin; a
+     * model-origin call carrying the same fields is recorded as the agent
+     * decision it actually is. Absent origin is treated as agent-origin (the
+     * untrusted-safe default).
      */
-    async handleChannelToolCall(toolName, input) {
+    async handleChannelToolCall(toolName, input, origin) {
         switch (toolName) {
             case 'channel_list':
                 return this.handleToolList();
             case 'channel_open':
                 return this.handleToolOpen(input);
             case 'channel_close':
-                return this.handleToolClose(input);
+                return this.handleToolClose(input, origin);
             case 'channel_decline':
                 return this.handleToolDecline(input);
             case 'channel_publish':
@@ -838,6 +910,18 @@ 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.
@@ -913,6 +997,11 @@ export class ChannelRegistry {
      * (typing timer lifecycle is still managed for when the callback is wired).
      */
     sendTypingNotification(serverId, channelId) {
+        // §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));
         }
@@ -922,6 +1011,12 @@ export class ChannelRegistry {
     // ==========================================================================
     // Private: Channel Lookup
     // ==========================================================================
+    /** Descriptors registered by one server — the §14.3 channels/list answer. */
+    descriptorsForServer(serverId) {
+        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) {
         return this.findChannelEntry(channelId)?.serverId ?? null;
@@ -1001,6 +1096,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 = await server.sendChannelsOpen({
             channelId: entry.descriptor.id,
             type: entry.descriptor.type,
@@ -1221,7 +1321,7 @@ export class ChannelRegistry {
             };
         }
     }
-    async handleToolClose(input) {
+    async handleToolClose(input, origin) {
         const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId);
         const entry = resolved.entry;
         if (!entry) {
@@ -1238,7 +1338,43 @@ export class ChannelRegistry {
                 data: { channelId: input.channelId, status: 'already closed' },
             };
         }
-        this.setDesiredState(entry.serverId, input.channelId, 'closed', 'agent-tool');
+        // Provenance comes from trusted dispatch, not from self-description:
+        // only module-origin calls may record a machine source, and only from
+        // the closed vocabulary. Agent-origin (or origin-less — the safe
+        // default for any legacy caller) records 'agent-tool' and has its
+        // machine fields ignored entirely.
+        const isModuleOrigin = origin?.kind === 'module';
+        let closeSource = 'agent-tool';
+        if (isModuleOrigin && input.source !== undefined) {
+            if (!MACHINE_CLOSE_SOURCES.has(input.source)) {
+                return {
+                    success: false,
+                    isError: true,
+                    error: `Unknown machine close source '${input.source}'. Machine closes must use one of: ` +
+                        `${[...MACHINE_CLOSE_SOURCES].join(', ')}.`,
+                };
+            }
+            closeSource = input.source;
+        }
+        // Housekeeping must not override stated intent (issue #5: GC closes wore
+        // the agent's badge and reset explicitly-opened doors). A machine-sourced
+        // close of a channel whose current desired state is an agent/operator
+        // 'open' is refused — structurally, so the caller can stand down rather
+        // than retry — unless it certifies an explicit idle lease.
+        if (isModuleOrigin && closeSource !== 'agent-tool' && !input.overrideExplicitOpen) {
+            const current = this.desiredStates.get(this.lifecycleKey(entry.serverId, input.channelId));
+            if (current?.state === 'open' && current.source === 'agent-tool') {
+                return {
+                    success: false,
+                    isError: false,
+                    error: `Channel ${input.channelId} was explicitly opened (source: agent-tool); ` +
+                        `a '${closeSource}' close does not override stated intent. Machine closes ` +
+                        `of explicit opens require an explicit idle lease (overrideExplicitOpen).`,
+                    data: { refusal: 'explicit-open', channelId: input.channelId },
+                };
+            }
+        }
+        this.setDesiredState(entry.serverId, input.channelId, 'closed', closeSource);
         this.stopTyping(input.channelId);
         const server = this.serverRegistry.getServer(entry.serverId);
         if (!server) {
@@ -1249,6 +1385,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 {
@@ -1288,6 +1431,9 @@ export class ChannelRegistry {
             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({
@@ -1354,6 +1500,13 @@ export class ChannelRegistry {
      * overloaded use of `think` for staying silent.
      */
     handleToolSkipReply(input) {
+        // 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
@@ -1367,7 +1520,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.',
             },
         };
     }
@@ -1424,7 +1579,12 @@ export class ChannelRegistry {
         if (matches.length !== 1)
             return null;
         const server = this.serverRegistry.getServer(matches[0].serverId);
-        if (!server?.capabilities?.channels?.streaming)
+        // §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;
     }
@@ -1508,6 +1668,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 = {
             conversationId,
             channelId,
@@ -1575,6 +1741,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 = {
                 conversationId: '', // Framework will fill this when wired
                 channelId,