@animalabs/agent-framework 0.12.0 → 0.14.0

package/src/gate/event-gate.ts

@@ -78,6 +78,37 @@ interface PendingEvent {
    *  metadata carries one — batched-wake lines render this instead of the raw
    *  composite channel id. */
   channelLabel?: string;
+  /** Author id of the event (discord snowflake etc.), when the metadata carries
+   *  one — a debounced wake names the newest such author as its counterparty. */
+  authorId?: string;
+  /** MCPL server id the event came from — the namespace for the counterparty
+   *  (`<serverId>:user:<id>`), same as the direct channel-incoming path. */
+  serverId?: string;
+  /** `chat:addressed` (mention / reply-to-bot / DM): an addressed event outranks
+   *  newer ambient chatter when a batched wake picks its provenance — the same
+   *  rule the framework applies to the turn's speech locus. */
+  addressed: boolean;
+}
+
+/**
+ * Where a gate-requested wake came from, handed to the framework alongside the
+ * reason so the turn's InferenceRequest can carry it (host telemetry stamps
+ * "who woke the agent" from it). Ids only, never content or display names.
+ */
+export interface WakeProvenance {
+  /** Composite channel id of the chosen event — telemetry only, never a
+   *  speech locus. Omitted for `mcpl:push-event` events, whose channel ids
+   *  are raw server ids (unroutable and a second spelling of the same
+   *  channel); the framework derives the composite id on the direct path. */
+  channelId?: string;
+  /** Server-namespaced author id: `<serverId>:user:<id>` (falls back to the
+   *  channel id's first segment only when the event carried no server id). */
+  counterparty?: string;
+  /** True when the chosen event was `chat:addressed`. */
+  addressed?: boolean;
+  /** Timestamp (ms) of the chosen event, so a consumer coalescing several
+   *  requests can order by event recency, not by flush order. */
+  at?: number;
 }
 
 interface DebounceState {
@@ -149,6 +180,34 @@ function isMetadataTruthy(value: unknown): boolean {
   return Boolean(value);
 }
 
+/**
+ * Provenance of a batched wake: the newest ADDRESSED channel-bearing event
+ * wins (mention / reply / DM outranks newer ambient chatter — the framework's
+ * own locus rule); else the newest channel-bearing event. Channel, author and
+ * addressed all come from that one event, so they can never disagree.
+ */
+export function wakeProvenance(events: PendingEvent[]): WakeProvenance | undefined {
+  let newest: PendingEvent | undefined;
+  let newestAddressed: PendingEvent | undefined;
+  for (const e of events) {
+    if (!e.channelId && !e.authorId) continue;
+    if (!newest || e.timestamp >= newest.timestamp) newest = e;
+    if (e.addressed && (!newestAddressed || e.timestamp >= newestAddressed.timestamp)) newestAddressed = e;
+  }
+  const pick = newestAddressed ?? newest;
+  if (!pick) return undefined;
+  // push-event channel ids are the adapter's raw ids (a Discord snowflake):
+  // not a composite channel id, so not reported as one
+  const channelId = pick.channelId && pick.eventType !== 'mcpl:push-event' ? pick.channelId : undefined;
+  const ns = pick.serverId || (pick.channelId ? pick.channelId.split(':')[0] : '') || 'channel';
+  return {
+    ...(channelId ? { channelId } : {}),
+    ...(pick.authorId ? { counterparty: `${ns}:user:${pick.authorId}` } : {}),
+    ...(pick.addressed ? { addressed: true } : {}),
+    at: pick.timestamp,
+  };
+}
+
 /** Compact, log-friendly serialization of a GateBehavior. */
 function formatBehavior(b: import('./types.js').GateBehavior): string {
   if (typeof b === 'string') return b;
@@ -515,8 +574,14 @@ 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 requestInferenceFn: (agentName: string, reason: string, source: string) => void;
+  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, provenance?: WakeProvenance) => void;
   private getAgentNamesFn: () => string[];
   /** Clock injection — keeps the new rate_limit / passive_sample paths
    *  testable without monkey-patching Date.now globally. */
@@ -527,8 +592,13 @@ 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;
-    requestInference: (agentName: string, reason: string, source: string) => void;
+    addMessage: (
+      participant: string,
+      content: Array<{ type: 'text'; text: string }>,
+      metadata?: Record<string, unknown>,
+      forAgent?: string,
+    ) => unknown;
+    requestInference: (agentName: string, reason: string, source: string, provenance?: WakeProvenance) => void;
     getAgentNames: () => string[];
     /** Optional clock — defaults to Date.now. Tests inject for deterministic time. */
     now?: () => number;
@@ -1374,6 +1444,9 @@ export class EventGate {
         typeof info.metadata?.channelName === 'string' && info.metadata.channelName
           ? (info.metadata.channelName as string)
           : undefined,
+      authorId: this.extractAuthorId(info.metadata) ?? undefined,
+      serverId: info.serverId || undefined,
+      addressed: Array.isArray(info.tags) && info.tags.includes('chat:addressed'),
     };
 
     const existing = this.debounceTimers.get(policy.name);
@@ -1461,8 +1534,14 @@ export class EventGate {
       policies: policyNames,
     });
 
+    // Provenance of the batched wake (telemetry: who/where woke the agent):
+    // the newest ADDRESSED event first, else the newest event naming a
+    // channel or an author; channel + author + addressed from that ONE
+    // event. It does not set the turn's speech locus — the framework keeps
+    // its own routing rule for that.
+    const provenance = wakeProvenance(events);
     for (const agentName of this.getAgentNamesFn()) {
-      this.requestInferenceFn(agentName, 'gate:debounce', 'gate');
+      this.requestInferenceFn(agentName, 'gate:debounce', 'gate', provenance);
     }
   }
 
@@ -1582,10 +1661,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 +1741,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/gate/index.ts

@@ -1,4 +1,4 @@
-export { EventGate } from './event-gate.js';
+export { EventGate, wakeProvenance, type WakeProvenance } from './event-gate.js';
 export type {
   GateConfig,
   GateOptions,

package/src/index.ts

@@ -76,7 +76,7 @@ export type {
 export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent } from './usage/index.js';
 
 // EventGate
-export { EventGate } from './gate/index.js';
+export { EventGate, type WakeProvenance } from './gate/index.js';
 export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior } from './gate/index.js';
 
 // MCPL channel registry (exposed for modules that need channel-level operations)

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)) {