@animalabs/agent-framework 0.12.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/mcpl/channel-registry.ts

@@ -45,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;
@@ -438,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[]>();
@@ -1146,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);
       }
@@ -1181,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
@@ -1297,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;
@@ -1710,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 {
@@ -1808,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/modules/workspace/index.ts

@@ -369,9 +369,13 @@ function validateJpeg(bytes: Buffer, mountPrefixedPath: string): void {
     offset += 1;
 
     if (marker === JPEG_EOI) {
-      if (!sawSof || !sawSos || offset !== bytes.length) {
+      if (!sawSof || !sawSos) {
         invalidImage('JPEG', mountPrefixedPath);
       }
+      // Bytes after EOI are tolerated: hardware encoders (e.g. Raspberry Pi
+      // camera stills) pad each frame to a 4-byte boundary with NULs after
+      // the EOI marker, and every mainstream decoder stops at EOI. The image
+      // proper (SOI..EOI) has been fully validated by this point.
       return;
     }
     if (marker === JPEG_TEM || (marker >= 0xd0 && marker <= 0xd7)) {

package/src/tool-wrapper-prose-guard.ts

@@ -0,0 +1,38 @@
+import type { ContentBlock } from '@animalabs/membrane';
+
+/**
+ * Recognize ONLY a whole-response textual invocation wrapper for a tool that
+ * was registered on this exact inference. This is containment, not parsing:
+ * callers must never execute the returned tool name or wrapper body.
+ */
+export function detectKnownToolWrapperProse(
+  content: ContentBlock[],
+  knownToolNames: ReadonlySet<string>,
+): string | null {
+  if (knownToolNames.size === 0) return null;
+
+  // Signed thinking may precede visible prose. Any other non-text block makes
+  // this a mixed response, not an exact textual wrapper.
+  const text: string[] = [];
+  for (const block of content) {
+    if (block.type === 'text') text.push(block.text);
+    else if (block.type !== 'thinking' && block.type !== 'redacted_thinking') return null;
+  }
+  const body = text.join('\n').trim();
+  if (!body) return null;
+
+  const tagName = '[A-Za-z_][A-Za-z0-9_.:-]*';
+  let match = body.match(new RegExp(`^<(${tagName})\\s*/>$`));
+  if (match && knownToolNames.has(match[1]!)) return match[1]!;
+
+  match = body.match(new RegExp(`^<(${tagName})\\s*>([\\s\\S]*?)<\\/\\1\\s*>$`));
+  if (match && knownToolNames.has(match[1]!)) return match[1]!;
+
+  // Legacy XML formatter shape used by older Claude harnesses.
+  match = body.match(/^<invoke\s*>\s*<tool\s+name=(['"])([^'"]+)\1(?:\s+[^>]*)?\s*\/>\s*<\/invoke\s*>$/);
+  if (match && knownToolNames.has(match[2]!)) return match[2]!;
+  match = body.match(/^<invoke\s*>\s*<tool\s+name=(['"])([^'"]+)\1(?:\s+[^>]*)?\s*>([\s\S]*?)<\/tool\s*>\s*<\/invoke\s*>$/);
+  if (match && knownToolNames.has(match[2]!)) return match[2]!;
+
+  return null;
+}