@animalabs/agent-framework 0.11.0 → 0.13.0

package/src/gate/event-gate.ts

@@ -515,7 +515,13 @@ export class EventGate {
 
   // Dependency-injected callbacks
   private emitTrace: (event: TraceEventLike) => void;
-  private addMessageFn: (participant: string, content: Array<{ type: 'text'; text: string }>, metadata?: Record<string, unknown>) => unknown;
+  private addMessageFn: (
+    participant: string,
+    content: Array<{ type: 'text'; text: string }>,
+    metadata?: Record<string, unknown>,
+    /** Registry agent to deliver into; absent = primary (historical). */
+    forAgent?: string,
+  ) => unknown;
   private requestInferenceFn: (agentName: string, reason: string, source: string) => void;
   private getAgentNamesFn: () => string[];
   /** Clock injection — keeps the new rate_limit / passive_sample paths
@@ -527,7 +533,12 @@ export class EventGate {
     initialConfig?: GateConfig;
     privilegedUsersPath?: string;
     emitTrace: (event: TraceEventLike) => void;
-    addMessage: (participant: string, content: Array<{ type: 'text'; text: string }>, metadata?: Record<string, unknown>) => unknown;
+    addMessage: (
+      participant: string,
+      content: Array<{ type: 'text'; text: string }>,
+      metadata?: Record<string, unknown>,
+      forAgent?: string,
+    ) => unknown;
     requestInference: (agentName: string, reason: string, source: string) => void;
     getAgentNames: () => string[];
     /** Optional clock — defaults to Date.now. Tests inject for deterministic time. */
@@ -1582,10 +1593,13 @@ export class EventGate {
       // before the inference request so it rides the wake turn (addMessage's
       // turn-alive guard defers it to that turn's start if needed).
       const nowIso = new Date(this.now()).toISOString().slice(0, 19) + 'Z';
+      // Deliver the notice into the WAKING agent's window — a self-wake
+      // armed by a non-primary agent (e.g. a subconscious cadence) must not
+      // narrate itself into the primary's context.
       this.addMessageFn('user', [{
         type: 'text',
         text: `[self-wake] your ${source} timer (${Math.round(ms / 1000)}s) elapsed — now ${nowIso}`,
-      }], { source: 'gate:self-wake' });
+      }], { source: 'gate:self-wake' }, agentName);
       this.requestInferenceFn(
         agentName,
         `self-scheduled wake (${source}, ${Math.round(ms / 1000)}s)`,
@@ -1659,6 +1673,17 @@ export class EventGate {
   }
 
   /** Load the privileged-users file (bare array or { userIds: [...] }). */
+  /**
+   * Whether an author id is on the privileged-users list (hot-reloaded).
+   * Shared by sleep bypass and tune-out wake classification (#77: wakes are
+   * "mentions, gate-privileged authors, etc.").
+   */
+  isPrivilegedUser(authorId: string | null | undefined): boolean {
+    if (!authorId) return false;
+    this.loadPrivileged();
+    return this.privilegedUserIds.has(authorId);
+  }
+
   private loadPrivileged(): void {
     if (!this.privilegedUsersPath) return;
     try {

package/src/kv-unified-wire.ts

@@ -0,0 +1,12 @@
+/** Structural copy of membrane's cache-wire receipt contract.
+ * Kept local so agent-framework remains source-compatible with the previous
+ * membrane release while the stacked membrane PR lands. */
+export interface CacheWireReceipt {
+  requestHash: string;
+  markers: Array<{ ordinal: number; prefixHash: string; estimatedOffset: number }>;
+}
+
+export interface KvUnifiedRequestHooks {
+  cacheMarkers?: 'membrane-system' | 'cm-owned';
+  onCacheWireReceipt?: (receipt: CacheWireReceipt) => void;
+}

package/src/mcpl/channel-registry.ts

@@ -14,6 +14,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
+import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
 import type { JsStore } from '@animalabs/chronicle';
 
 import type {
@@ -44,14 +45,53 @@ import { CapabilityGrant } from './capability-grant.js';
 const TYPING_INTERVAL_MS = 7_000;
 const CHANNEL_LIFECYCLE_LOG_ID = 'mcpl/channel-lifecycle';
 
-type DesiredChannelState = 'open' | 'closed';
+type DesiredChannelState = 'open' | 'closed' | 'tuned-out';
+
+/**
+ * Parameters of an active tune-out (issue #77), carried on the
+ * 'desired-state' record entering the tuned-out state and projected into
+ * `desiredStates`. A tuned-out channel stays OPEN at the transport (traffic
+ * must keep arriving for the subconscious); the divert-don't-wake behavior
+ * is applied downstream at ingestion.
+ */
+export interface TuneOutParams {
+  /** Identity of this tune-out epoch. Stamped into diverted messages
+   *  (`metadata.tuneOut = { epochId }`) for permanent main-view exclusion
+   *  and per-epoch audit; also keys durable wake counting. */
+  epochId: string;
+  /** Subconscious summary cadence, in seconds. */
+  cadenceSeconds: number;
+  /** Maximum messages dumped raw at cancel; above the cap the subconscious
+   *  curates a digest and `fetch_history` covers the rest. */
+  backlogCap: number;
+  /** Wake invocations before the tune-out auto-cancels. */
+  maxWakes: number;
+  /** Chronicle sequence when the tune-out began — window anchor + audit bound. */
+  startedAtSequence: number;
+  /** Absolute wall-clock deadline (epoch ms). When set, the tune-out
+   *  auto-cancels at this time via the standard cancel flow ("duration
+   *  elapsed") — the agent's self-binding attention budget (#77 "for a
+   *  period chosen by the agent"). Unset = until cancelled. */
+  expiresAtMs?: number;
+}
 
 interface ChannelLifecycleEvent {
-  kind: 'desired-state' | 'legacy-policy-migrated' | 'invitation-declined';
+  kind:
+    | 'desired-state'
+    | 'legacy-policy-migrated'
+    | 'invitation-declined'
+    | 'tune-out-wake';
   serverId: string;
   timestamp: string;
   channelId?: string;
   desired?: DesiredChannelState;
+  /** Present when desired === 'tuned-out'. */
+  tuneOut?: TuneOutParams;
+  /** kind 'tune-out-wake': durable running wake count for an epoch.
+   *  Lives in the lifecycle log (not gate stats) because gate runtime
+   *  state dies with the process and max-wakes must not reset on restart. */
+  epochId?: string;
+  wakeCount?: number;
   source?: string;
   messageId?: string;
   acknowledgment?: string;
@@ -124,6 +164,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: block.text };
 
     case 'image':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'image',
@@ -139,6 +189,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Image: no data]' };
 
     case 'audio':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'audio',
@@ -148,7 +208,14 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Audio: no data]' };
 
     case 'resource':
-      return { type: 'text', text: `[Resource: ${block.uri}]` };
+      // RFC-005: reference blocks become bounded stubs — never raw URIs
+      // (a signed URL is a bearer credential that looks like a location).
+      return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
+
+    default:
+      // Unknown wire block types previously fell off the exhaustive switch
+      // and propagated `undefined` into ContentBlock[]. Fail visibly.
+      return { type: 'text', text: `[unrecognized content block: ${(block as { type?: string }).type ?? 'untyped'}]` };
   }
 }
 
@@ -410,7 +477,15 @@ export class ChannelRegistry {
   /** Chronicle-projected desired lifecycle state, keyed by server + channel.
    *  Provenance is kept so reconcile can tell a pure default (nobody ever
    *  decided) from a real decision (agent-tool, invitation-declined, …). */
-  private desiredStates = new Map<string, { state: DesiredChannelState; source: string }>();
+  private desiredStates = new Map<string, {
+    state: DesiredChannelState;
+    source: string;
+    /** Present iff state === 'tuned-out'. */
+    tuneOut?: TuneOutParams;
+    /** Durable wake count for the active tune-out epoch (replayed from
+     *  'tune-out-wake' lifecycle records; see recordTuneOutWake). */
+    wakeCount?: number;
+  }>();
 
   /** One-time migration inputs from the retired recipe auto-open policy. */
   private legacyPolicies = new Map<string, 'auto' | 'manual' | string[]>();
@@ -1118,12 +1193,31 @@ export class ChannelRegistry {
       if (
         event.kind === 'desired-state' &&
         typeof event.channelId === 'string' &&
-        (event.desired === 'open' || event.desired === 'closed')
+        (event.desired === 'open' || event.desired === 'closed' ||
+          (event.desired === 'tuned-out' && event.tuneOut))
       ) {
         this.desiredStates.set(
           this.lifecycleKey(event.serverId, event.channelId),
-          { state: event.desired, source: typeof event.source === "string" ? event.source : "unknown" },
+          {
+            state: event.desired,
+            source: typeof event.source === "string" ? event.source : "unknown",
+            tuneOut: event.desired === 'tuned-out' ? event.tuneOut : undefined,
+            wakeCount: 0,
+          },
         );
+      } else if (
+        event.kind === 'tune-out-wake' &&
+        typeof event.channelId === 'string' &&
+        typeof event.wakeCount === 'number'
+      ) {
+        // Fold durable wake counts into the projection — but only while the
+        // epoch that recorded them is still the active desired state
+        // (last-record-wins semantics, same as desired-state itself).
+        const key = this.lifecycleKey(event.serverId, event.channelId);
+        const current = this.desiredStates.get(key);
+        if (current?.state === 'tuned-out' && current.tuneOut?.epochId === event.epochId) {
+          current.wakeCount = event.wakeCount;
+        }
       } else if (event.kind === 'legacy-policy-migrated') {
         this.migratedLegacyPolicies.add(event.serverId);
       }
@@ -1153,6 +1247,147 @@ export class ChannelRegistry {
     });
   }
 
+  // ==========================================================================
+  // Tune-out state (issue #77) — durable in the lifecycle log
+  // ==========================================================================
+
+  /**
+   * Enter (or re-enter with fresh params) the tuned-out state for a channel.
+   * Re-entering under a new epochId replaces the active epoch; the previous
+   * epoch's stamped messages stay excluded (stamps are permanent) and its
+   * wake count is superseded. Transport stays open (see reconcile).
+   */
+  enterTuneOut(
+    serverId: string,
+    channelId: string,
+    params: TuneOutParams,
+    source: string,
+  ): void {
+    const key = this.lifecycleKey(serverId, channelId);
+    this.desiredStates.set(key, {
+      state: 'tuned-out',
+      source,
+      tuneOut: params,
+      wakeCount: 0,
+    });
+    this.appendLifecycleEvent({
+      kind: 'desired-state',
+      serverId,
+      channelId,
+      desired: 'tuned-out',
+      tuneOut: params,
+      source,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * End the active tune-out, returning the channel to `nextState`.
+   * The caller (tune-out coordinator) owns the dump/notice flow; this is
+   * only the durable state flip. No-op returning null if the channel is
+   * not tuned out.
+   */
+  cancelTuneOut(
+    serverId: string,
+    channelId: string,
+    nextState: 'open' | 'closed',
+    source: string,
+  ): { params: TuneOutParams; wakeCount: number } | null {
+    const key = this.lifecycleKey(serverId, channelId);
+    const current = this.desiredStates.get(key);
+    if (current?.state !== 'tuned-out' || !current.tuneOut) return null;
+    const ended = { params: current.tuneOut, wakeCount: current.wakeCount ?? 0 };
+    this.desiredStates.set(key, { state: nextState, source });
+    this.appendLifecycleEvent({
+      kind: 'desired-state',
+      serverId,
+      channelId,
+      desired: nextState,
+      source,
+      timestamp: new Date().toISOString(),
+    });
+    return ended;
+  }
+
+  /**
+   * Durably record one wake invocation against the active epoch and return
+   * the updated count with the params (the coordinator compares against
+   * maxWakes and decides auto-cancel). Durable here, not in gate stats:
+   * gate runtime state dies with the process, and a restart must not grant
+   * a hammered channel a fresh wake budget.
+   */
+  recordTuneOutWake(
+    serverId: string,
+    channelId: string,
+  ): { params: TuneOutParams; wakeCount: number } | null {
+    const key = this.lifecycleKey(serverId, channelId);
+    const current = this.desiredStates.get(key);
+    if (current?.state !== 'tuned-out' || !current.tuneOut) return null;
+    current.wakeCount = (current.wakeCount ?? 0) + 1;
+    this.appendLifecycleEvent({
+      kind: 'tune-out-wake',
+      serverId,
+      channelId,
+      epochId: current.tuneOut.epochId,
+      wakeCount: current.wakeCount,
+      timestamp: new Date().toISOString(),
+    });
+    return { params: current.tuneOut, wakeCount: current.wakeCount };
+  }
+
+  /** Active tune-out params + wake count for a channel, or null. */
+  getTuneOutState(
+    serverId: string,
+    channelId: string,
+  ): { params: TuneOutParams; wakeCount: number } | null {
+    const current = this.desiredStates.get(this.lifecycleKey(serverId, channelId));
+    if (current?.state !== 'tuned-out' || !current.tuneOut) return null;
+    return { params: current.tuneOut, wakeCount: current.wakeCount ?? 0 };
+  }
+
+  /** Registered channel entries (read-only iteration for the coordinator). */
+  listChannelsRaw(): Array<{ serverId: string; descriptor: ChannelDescriptor }> {
+    return [...this.channels.values()].map((e) => ({
+      serverId: e.serverId,
+      descriptor: e.descriptor,
+    }));
+  }
+
+  /**
+   * Small chronicle snapshot-state helpers for the tune-out coordinator
+   * (dispositions slot). Registration is idempotent; absent store = null/no-op
+   * (mirrors the lifecycle log's optional-store posture).
+   */
+  readCoordinatorState(stateId: string): unknown {
+    if (!this.store) return null;
+    try {
+      this.store.registerState({ id: stateId, strategy: 'snapshot' });
+    } catch { /* already registered */ }
+    return this.store.getStateJson(stateId);
+  }
+
+  writeCoordinatorState(stateId: string, value: unknown): void {
+    if (!this.store) return;
+    try {
+      this.store.registerState({ id: stateId, strategy: 'snapshot' });
+    } catch { /* already registered */ }
+    this.store.setStateJson(stateId, value);
+  }
+
+  /**
+   * Publish into a channel on behalf of a named non-resident agent (the
+   * subconscious's speak_in_channel). Same delivery path as the
+   * channel_publish tool; the agent name rides the speech-routed trace.
+   */
+  async publishForAgent(
+    channelId: string,
+    text: string,
+    agentName: string,
+  ): Promise<{ success: boolean; data?: unknown; error?: string; isError?: boolean }> {
+    this.emitTraceFn({ type: 'mcpl:speech-routed', conversationId: agentName, channelId, text });
+    return this.handleToolPublish({ channelId, content: text });
+  }
+
   /**
    * Consume the old recipe policy exactly once. It seeds Chronicle for
    * existing deployments, but is not an ongoing admission policy: channels
@@ -1269,7 +1504,10 @@ export class ChannelRegistry {
       const key = `${serverId}:${channel.id}`;
       const desired = this.getDesiredState(serverId, channel.id);
       const entry = this.channels.get(key);
-      if (desired !== 'open') {
+      // Tuned-out sits on the OPEN side of reconcile: traffic must keep
+      // arriving (the subconscious reads it); only main's wake/visibility
+      // is diverted, downstream at ingestion.
+      if (desired !== 'open' && desired !== 'tuned-out') {
         try {
           await server.sendChannelsClose({ channelId: channel.id });
           if (entry) entry.open = false;
@@ -1682,6 +1920,22 @@ export class ChannelRegistry {
       };
     }
 
+    // A tuned-out channel is transport-open but attention-diverted; a plain
+    // open would silently discard the epoch (and its pending backlog dump).
+    // Cancelling is the tune-out coordinator's flow, reached via its own
+    // tool — refuse with the pointer rather than eat the state.
+    if (this.getDesiredState(entry.serverId, input.channelId) === 'tuned-out') {
+      return {
+        success: false,
+        isError: false,
+        error:
+          `Channel ${input.channelId} is tuned out. Cancel the tune-out ` +
+          `(tune_out with mode: 'cancel') to resume normal attention — ` +
+          `cancelling delivers the diverted backlog.`,
+        data: { refusal: 'tuned-out', channelId: input.channelId },
+      };
+    }
+
     const alreadyDesiredOpen = this.getDesiredState(entry.serverId, input.channelId) === 'open';
     if (entry.open && alreadyDesiredOpen && !input.backscroll) {
       return {
@@ -1780,7 +2034,9 @@ export class ChannelRegistry {
     // 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') {
+      // Tuned-out is stated intent too: a GC/housekeeping close would
+      // silently end the epoch and orphan its backlog.
+      if ((current?.state === 'open' || current?.state === 'tuned-out') && current.source === 'agent-tool') {
         return {
           success: false,
           isError: false,

package/src/mcpl/hook-orchestrator.ts

@@ -14,6 +14,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
+import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
 import type { ContextInjection } from '@animalabs/context-manager';
 
 import type {
@@ -65,6 +66,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: block.text };
 
     case 'image':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on context injection') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'image',
@@ -81,6 +92,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Image: missing data]' };
 
     case 'audio':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on context injection') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'audio',
@@ -91,8 +112,14 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: `[Audio: ${block.uri ?? 'missing data'}]` };
 
     case 'resource':
-      // Resources don't have a direct membrane equivalent — degrade to text
-      return { type: 'text', text: `[Resource: ${block.uri}]` };
+      // RFC-005: reference blocks become bounded stubs — never raw URIs
+      // (a signed URL is a bearer credential that looks like a location).
+      return { type: 'text', text: referenceStubOrNull(block, 'attachment on context injection') ?? '[reference]' };
+
+    default:
+      // Unknown wire block types previously fell off the exhaustive switch
+      // and propagated `undefined` into ContentBlock[]. Fail visibly.
+      return { type: 'text', text: `[unrecognized content block: ${(block as { type?: string }).type ?? 'untyped'}]` };
   }
 }
 

package/src/mcpl/push-handler.ts

@@ -8,6 +8,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
+import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
 
 import type {
   McplContentBlock,
@@ -51,12 +52,22 @@ export interface McplPushEvent {
  * Convert a single MCPL wire-format content block to a membrane ContentBlock.
  * Same logic as hook-orchestrator.ts.
  */
-function convertBlock(block: McplContentBlock): ContentBlock {
+export function convertBlock(block: McplContentBlock): ContentBlock {
   switch (block.type) {
     case 'text':
       return { type: 'text', text: block.text };
 
     case 'image':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'image',
@@ -72,6 +83,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Image: no data]' };
 
     case 'audio':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'audio',
@@ -81,7 +102,14 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Audio: no data]' };
 
     case 'resource':
-      return { type: 'text', text: `[Resource: ${block.uri}]` };
+      // RFC-005: reference blocks become bounded stubs — never raw URIs
+      // (a signed URL is a bearer credential that looks like a location).
+      return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
+
+    default:
+      // Unknown wire block types previously fell off the exhaustive switch
+      // and propagated `undefined` into ContentBlock[]. Fail visibly.
+      return { type: 'text', text: `[unrecognized content block: ${(block as { type?: string }).type ?? 'untyped'}]` };
   }
 }