@animalabs/agent-framework 0.33.0 → 0.34.0

package/src/gate/event-gate.ts

@@ -22,6 +22,9 @@ import { canonical, duplicateName, lastRecipePath, noChanges, reconcileLine, rec
 import { closestNames, isNearMiss } from '../closest-names.js';
 import { MAX_TIMER_MS } from '../deadline-timer.js';
 import { safeSlice } from '../safe-slice.js';
+import { failureWords } from '../failure-text.js';
+import { JudgeFailure } from './reply-judge.js';
+import { isSystemNotice } from '../mcpl/tags.js';
 
 import type { ToolDefinition } from '../types/events.js';
 import type { TraceEventInput } from '../types/trace.js';
@@ -45,6 +48,7 @@ import type {
   JudgeVerdict,
   UpcomingWake,
 } from './types.js';
+import { appendAll } from '../append-all.js';
 
 // Re-export types consumers need
 export type {
@@ -132,7 +136,9 @@ interface PendingEvent {
    *  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. */
+   *  one — a debounced wake's counterparty is the author of the event
+   *  wakeProvenance picks; when it picks none and gives no
+   *  `batchChannels`, the author of the batch's newest notice that has one. */
   authorId?: string;
   /** MCPL server id the event came from — the namespace for the counterparty
    *  (`<serverId>:user:<id>`), same as the direct channel-incoming path. */
@@ -141,6 +147,7 @@ interface PendingEvent {
    *  newer ambient chatter when a batched wake picks its provenance — the same
    *  rule the framework applies to the turn's speech locus. */
   addressed: boolean;
+  systemNotice?: true;
   /** The REGISTERED (composite) channel id the event arrived on, resolved by
    *  the host at enqueue time. Differs from `channelId` for push events,
    *  whose `channelId` is the adapter's raw id (a bare Discord snowflake for a
@@ -179,7 +186,13 @@ export interface WakeProvenance {
    *  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). */
+   *  channel id's first segment only when the event carried no server id).
+   *  A `chat:system` notice, unless it's a coalesced render's latest
+   *  occurrence (GateEventInfo.folds), is never chosen for a batch's route,
+   *  channel or `addressed` flag. In a batch in which no other event names a
+   *  channel or an author, and which has no `batchChannels`, the chosen
+   *  event is its newest notice that has an author, of which the wake names
+   *  only the author and its time (`at`). */
   counterparty?: string;
   /** True when the chosen event was `chat:addressed`. */
   addressed?: boolean;
@@ -196,6 +209,19 @@ export interface WakeProvenance {
    *  event named its server: channel ids are unique only within one
    *  server's connection (MCPL §14.2). */
   routeServerId?: string;
+  /** The channels a batch came from, each its registered id and server, in
+   *  the order they first appear, when no event of it addressed the agent:
+   *  those the host resolved, one or more. A channel some events gave with
+   *  its server and others without is listed once each way, since only the
+   *  host can tell they're one. A `chat:system` notice counts
+   *  neither as addressing the agent nor as a channel, except as a
+   *  coalesced render's latest occurrence, which the gate takes as a
+   *  message (GateEventInfo.folds). The wake has no route, and the turn's
+   *  no-locus notice names them, one given without its server only if its id
+   *  still names one registered channel when the wake is admitted, unless the
+   *  turn's own wake named a channel that resolves to none, or the turn is an
+   *  ephemeral run's, which writes none. */
+  batchChannels?: Array<{ channelId: string; serverId?: string }>;
   /** Timestamp (ms) of the chosen event, so a consumer coalescing several
    *  requests can order by event recency, not by flush order. */
   at?: number;
@@ -296,15 +322,25 @@ function isMetadataTruthy(value: unknown): boolean {
 }
 
 /**
- * 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.
+ * Provenance of a batched wake: the newest ADDRESSED event that names a
+ * channel or an author wins (mention / reply / DM outranks newer ambient
+ * chatter — the framework's own locus rule); else the newest event that
+ * names either. An addressed event's resolved route counts as its channel;
+ * an ambient one's doesn't. Channel, author and addressed all come from
+ * that one event, so they can never disagree. A `chat:system` notice is
+ * never chosen for the batch's route, channel or addressed flag, even one
+ * addressed by its place (a pin in a DM), since a notice never decides where
+ * the agent's speech goes; a coalesced render whose latest occurrence is a
+ * notice isn't taken as one (GateEventInfo.folds). A batch with no such event
+ * carries only its `batchChannels` when it has them; else its chosen event is
+ * its newest notice that has an author, of which it takes only the author
+ * and time.
  */
 export function wakeProvenance(events: PendingEvent[]): WakeProvenance | undefined {
+  const said = events.filter((e) => !e.systemNotice);
   let newest: PendingEvent | undefined;
   let newestAddressed: PendingEvent | undefined;
-  for (const e of events) {
+  for (const e of said) {
     // A resolved route counts as naming a channel only for an ADDRESSED
     // event: a push whose origin declares only `mcplChannelId` (no raw
     // channel id, no author) is still a routable addressed message, and
@@ -317,22 +353,42 @@ export function wakeProvenance(events: PendingEvent[]): WakeProvenance | undefin
     if (e.addressed && (!newestAddressed || e.timestamp >= newestAddressed.timestamp)) newestAddressed = e;
   }
   const pick = newestAddressed ?? newest;
-  if (!pick) return undefined;
+  const channels = said.some((e) => e.addressed) ? [] : batchRoutes(said);
+  if (!pick && channels.length === 0) {
+    const notice = events.reduce<PendingEvent | undefined>(
+      (n, e) => (e.systemNotice && e.authorId && (!n || e.timestamp >= n.timestamp) ? e : n), undefined);
+    return notice ? { counterparty: counterpartyOf(notice), at: notice.timestamp } : 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';
+  const channelId = pick?.channelId && pick.eventType !== 'mcpl:push-event' ? pick.channelId : undefined;
   return {
     ...(channelId ? { channelId } : {}),
-    ...(pick.authorId ? { counterparty: `${ns}:user:${pick.authorId}` } : {}),
-    ...(pick.addressed ? { addressed: true } : {}),
-    ...(pick.addressed && pick.routeChannelId
+    ...(pick?.authorId ? { counterparty: counterpartyOf(pick) } : {}),
+    ...(pick?.addressed ? { addressed: true } : {}),
+    ...(pick?.addressed && pick.routeChannelId
       ? { routeChannelId: pick.routeChannelId, ...(pick.serverId ? { routeServerId: pick.serverId } : {}) }
       : {}),
-    at: pick.timestamp,
+    ...(channels.length > 0 ? { batchChannels: channels } : {}),
+    ...(pick ? { at: pick.timestamp } : {}),
   };
 }
 
+function counterpartyOf(e: PendingEvent): string {
+  const ns = e.serverId || (e.channelId ? e.channelId.split(':')[0] : '') || 'channel';
+  return `${ns}:user:${e.authorId}`;
+}
+
+function batchRoutes(events: PendingEvent[]): Array<{ channelId: string; serverId?: string }> {
+  const routes: Array<{ channelId: string; serverId?: string }> = [];
+  for (const e of events) {
+    if (!e.routeChannelId) continue;
+    if (routes.some((r) => r.channelId === e.routeChannelId && r.serverId === e.serverId)) continue;
+    routes.push({ channelId: e.routeChannelId, ...(e.serverId ? { serverId: e.serverId } : {}) });
+  }
+  return routes;
+}
+
 /** A `[Gate: …]` line's reference to messages already in the window: how
  *  many, in which channel, and how long ago the oldest arrived, as of `now`. */
 function referenceLine(count: number, channel: string, oldest: number, now: number): string {
@@ -1689,7 +1745,7 @@ function readConfig(
       };
     }
   }
-  for (const rule of rules) sentences.push(...readingSentences(rule.reading, rule.outcome));
+  for (const rule of rules) appendAll(sentences, readingSentences(rule.reading, rule.outcome));
   // A list with no rules, or none the gate reads, where no sentence above said it has none.
   if (notUsed !== undefined && !sentences.some((said) => said.includes(notUsed))) {
     sentences.push(`${File} has no rules${rules.length > 0 ? ' but ones the gate leaves out' : ''}, so ${notUsedWhy}.`);
@@ -2126,9 +2182,15 @@ export function formatShadowWarning(w: ShadowWarning): string {
     + `A scope on ${later} naming the event types it's for clears this note.`;
 }
 
+function judgeFailureWords(err: unknown): string {
+  if (err instanceof JudgeFailure) return err.message;
+  return err instanceof Error ? failureWords(err, 'the call failed') : 'the call failed';
+}
+
 /** The text of a thrown value, for a log line. It never throws itself, whatever was thrown. */
 function errorText(err: unknown): string {
   try {
+    if (err instanceof JudgeFailure && err.detail !== undefined) return `${err.message} (${err.detail})`;
     return err instanceof Error ? err.message : String(err);
   } catch {
     return 'a value that could not be printed';
@@ -4023,6 +4085,7 @@ export class EventGate {
       authorId: this.extractAuthorId(info.metadata) ?? undefined,
       serverId: info.serverId || undefined,
       addressed: Array.isArray(info.tags) && info.tags.includes('chat:addressed'),
+      ...(isSystemNotice(info.tags) && !info.folds ? { systemNotice: true as const } : {}),
       routeChannelId: this.routeChannelFor(info),
       ...(typeof info.metadata?.messageId === 'string' ? { messageId: info.metadata.messageId } : {}),
       ...(typeof info.metadata?.eventId === 'string' ? { eventId: info.metadata.eventId } : {}),
@@ -4226,12 +4289,13 @@ export class EventGate {
 
     // Provenance of the batched wake (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. When that
-    // event addressed the agent and its registered channel is known,
-    // `routeChannelId` names the turn's speech locus too — the reply goes
-    // back to whoever addressed the agent, not to whichever channel last saw
-    // any traffic. Ambient-only batches set no locus. A batch whose line the
-    // gate left to the turn's start carries it too (`line`), one object
+    // author, `chat:system` notices aside; channel + author + addressed from
+    // that ONE event. When that event addressed the agent and its registered
+    // channel is known, `routeChannelId` names the turn's speech locus too —
+    // the reply goes back to whoever addressed the agent, not to whichever
+    // channel last saw any traffic. Ambient-only batches set no locus, and
+    // name the channels they came from (`batchChannels`). A batch whose line
+    // the gate left to the turn's start carries it too (`line`), one object
     // shared by every agent woken with these messages, so it is written once.
     const chosen = wakeProvenance(events);
     const provenance = line ? { ...chosen, line } : chosen;
@@ -4268,7 +4332,7 @@ export class EventGate {
     if (this.disposed) return;
     const deciding = this.judging.get(policyName);
     if (deciding) {
-      deciding.queued.push(...events);
+      appendAll(deciding.queued, events);
       this.capJudgeEvents(deciding.queued);
       return;
     }
@@ -4287,8 +4351,8 @@ export class EventGate {
     this.judging.set(policyName, state);
     const timedOut = new Promise<never>((_, reject) => {
       state.timer = setTimeout(() => {
+        reject(new JudgeFailure(`the judge took more than ${this.judgeTimeoutMs} ms`));
         abort.abort();
-        reject(new Error(`the judge took more than ${this.judgeTimeoutMs} ms`));
       }, this.judgeTimeoutMs);
       // Never keep the process alive on the judge's account.
       state.timer.unref?.();
@@ -4321,7 +4385,7 @@ export class EventGate {
   private holdForJudge(policyName: string, events: PendingEvent[], judge: JudgeConfig): void {
     const held = this.judgeHeld.get(policyName);
     if (held) {
-      held.events.push(...events);
+      appendAll(held.events, events);
       held.judge = judge;
       this.capJudgeEvents(held.events);
     } else {
@@ -4447,7 +4511,7 @@ export class EventGate {
     }
     const outcome: 'reply' | 'wait' | 'error' = failed ? 'error' : verdict.reply ? 'reply' : 'wait';
     const reason = failed
-      ? (err !== undefined ? errorText(err) : 'the judge gave no verdict')
+      ? (err !== undefined ? judgeFailureWords(err) : 'the judge gave no verdict')
       : typeof verdict.reason === 'string' ? verdict.reason : '';
     const record = this.judgeRecords.get(policyName) ?? { verdicts: { reply: 0, wait: 0, error: 0 } };
     record.verdicts[outcome]++;
@@ -4469,7 +4533,7 @@ export class EventGate {
     const wake = outcome === 'reply' || (outcome === 'error' && this.judgeOnError === 'wake');
     if (failed) {
       console.error(
-        `[gate] Rule ${quotedValue(policyName)}: the reply judge failed (${reason}), so its batch of ${state.events.length} `
+        `[gate] Rule ${quotedValue(policyName)}: the reply judge failed (${err !== undefined ? errorText(err) : reason}), so its batch of ${state.events.length} `
         + `${state.events.length === 1 ? 'event' : 'events'} ${wake ? 'wakes the agent' : "doesn't wake the agent"} (judge onError "${this.judgeOnError}")`,
       );
     }

package/src/gate/reply-judge.ts

@@ -29,6 +29,15 @@ import { NativeFormatter } from '@animalabs/membrane';
 import type { ContentBlock, DetailedUsage, Membrane, NormalizedMessage, NormalizedRequest, NormalizedResponse } from '@animalabs/membrane';
 import type { JudgeEventSummary, JudgeFn, JudgeRequest, JudgeVerdict, ReplyJudgeOptions, UpcomingWake } from './types.js';
 
+export class JudgeFailure extends Error {
+  readonly detail?: string;
+  constructor(message: string, detail?: string) {
+    super(message);
+    this.name = 'JudgeFailure';
+    if (detail !== undefined) this.detail = detail;
+  }
+}
+
 /** The judge's model when the host names none. */
 export const DEFAULT_JUDGE_MODEL = 'claude-haiku-5-5';
 /** The judge's input budget when the host names none: under Haiku 5.5's 100K price line, with margin. */
@@ -334,9 +343,9 @@ export class ReplyJudge {
   /** Build the judge's request for one batch: the system prompt, the document in chunks, the question. */
   async buildRequest(request: JudgeRequest, now = Date.now()): Promise<{ request: NormalizedRequest; agentName: string; chars: number }> {
     const agentName = this.chooseAgent(request.agentNames);
-    if (!agentName) throw new Error('no agent to judge for');
+    if (!agentName) throw new JudgeFailure('no agent to judge for');
     const preview = await this.preview(agentName);
-    if (request.signal.aborted) throw new Error('the judge was stopped before its request');
+    if (request.signal.aborted) throw new JudgeFailure('the judge was stopped before its request');
 
     let extra: UpcomingWake[] = [];
     try {
@@ -499,7 +508,7 @@ export class ReplyJudge {
     const verdict = parseVerdict(text);
     if (!verdict) {
       const stop = response.stopReason;
-      throw new Error(`the judge's answer held no verdict (stop: ${stop}${text ? `, text: ${JSON.stringify(cut(text, 120))}` : ''})`);
+      throw new JudgeFailure("the judge's answer held no verdict", `stop: ${stop}${text ? `, text: ${JSON.stringify(cut(text, 120))}` : ''}`);
     }
     return {
       ...verdict,

package/src/gate/suppression-review.ts

@@ -388,7 +388,7 @@ export class SuppressionReview {
     // A rule the reviewer couldn't answer about last time is reviewed from
     // where its unreviewed events begin.
     const fromOf = (name: string): number => Math.min(this.retryFrom.get(name) ?? fromMs, fromMs);
-    const earliest = Math.min(fromMs, ...this.retryFrom.values());
+    const earliest = [...this.retryFrom.values()].reduce((min, from) => Math.min(min, from), fromMs);
     const byRule = new Map<string, SuppressedEventRecord[]>();
     for (const record of this.deps.records(agentName, earliest, toMs)) {
       if (Date.parse(record.at) < fromOf(record.rule)) continue;
@@ -410,7 +410,7 @@ export class SuppressionReview {
       rules.push(await this.judge(agentName, { name, description, ...(rule ?? {}) }, sample, records.length, { fromMs: fromOf(name), toMs }, base));
     }
     const summary: SuppressionReviewSummary = {
-      fromMs: rules.length > 0 ? Math.min(...rules.map((r) => fromOf(r.rule))) : fromMs, toMs, rules,
+      fromMs: rules.length > 0 ? rules.reduce((min, r) => Math.min(min, fromOf(r.rule)), Infinity) : fromMs, toMs, rules,
       total: rules.reduce((n, r) => n + r.suppressed, 0),
       flagged: rules.reduce((n, r) => n + r.flagged.length, 0),
     };

package/src/gate/types.ts

@@ -521,6 +521,13 @@ export interface GateEventInfo {
    * that lands where no view hides suppressed rows.
    */
   suppressionAsked?: boolean;
+  /**
+   * A coalesced render, which folds its batch's every occurrence while its
+   * `tags` are the latest's (MCPL RFC-006): never taken as a `chat:system`
+   * notice, as the render's own wake isn't, so a message it folds keeps
+   * its channel when a notice came last.
+   */
+  folds?: true;
 }
 
 /** An MCPL event whose content the framework stored at arrival, as a

package/src/heartbeat/heartbeat.ts

@@ -603,7 +603,7 @@ export class Heartbeat {
     this.cancelReminders?.();
     this.cancelReminders = null;
     if (!this.started || this.state.reminders.length === 0) return;
-    const due = Math.min(...this.state.reminders.map(dueAt));
+    const due = this.state.reminders.reduce((min, rem) => Math.min(min, dueAt(rem)), Infinity);
     this.cancelReminders = callAt(Math.max(due, this.notBefore), this.now, () => {
       this.cancelReminders = null;
       this.fireDueReminders();

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './types/index.js';
 
 // Core classes
 export { AgentFramework, AgentStoppedError, BudgetPreflightError, DefaultErrorPolicy, ProviderWaitNotSleptError, QuiesceBlockedError, ResumeBlockedError } from './framework.js';
+export { isReasoningLoss } from './reasoning-loss.js';
 export type { RuntimeSettingsPreview, HostModeStatus, DeriveAgentOptions } from './framework.js';
 export { Agent } from './agent.js';
 export { FLAT_MINIMUM_MS, type InferenceBoundsOptions } from './inference-bounds.js';

package/src/inference-bounds.ts

@@ -72,11 +72,9 @@ export function wholeCallMs(bounds: InferenceBounds, maxTokens: number | undefin
   return setupMs(bounds.progressBounds) + allowanceMs(bounds.progressBounds, maxTokens);
 }
 
-// membrane 0.8.0 marks a deadline it reports as run out with this registered
-// symbol (on a sent request, or the Anthropic SDK's timeout, which covers its
-// connect timeout too) and exports no reader or marker for it. The one reader:
-// the deadline class here and the transient-failure check of an exhausted
-// turn's re-arm both use it.
+// membrane 0.8.0 and 0.9.0 mark a deadline they report as run out with this
+// registered symbol (on a sent request, or the Anthropic SDK's timeout, which
+// covers its connect timeout too) and export no reader or marker for it.
 const DEADLINE_EXPIRY = Symbol.for('membrane.deadlineExpiry');
 
 export function isDeadlineExpiry(error: unknown): boolean {
@@ -85,7 +83,7 @@ export function isDeadlineExpiry(error: unknown): boolean {
 
 /**
  * Names the host setting for the bound a stream cut hit, read from the opening
- * of membrane 0.8.0's message for it (its progress-bounds.ts and
+ * of membrane 0.8.0's and 0.9.0's message for it (their progress-bounds.ts and
  * providers/utils.ts), so the reason an operator and the agent see names the
  * host's setting for that bound, as the README's table maps them. A message it
  * doesn't know is left as it is.
@@ -99,6 +97,8 @@ export function withHostSetting(message: string): string {
   return setting === undefined ? message : `${message} (the host's setting for this bound: \`inferenceBounds.${setting}\`)`;
 }
 
+const CUTS = new WeakSet<object>();
+
 export function deadlineCut(message: string | undefined): MembraneError {
   const error = new MembraneError({
     type: 'timeout',
@@ -107,5 +107,10 @@ export function deadlineCut(message: string | undefined): MembraneError {
     rawError: undefined,
   });
   Object.defineProperty(error, DEADLINE_EXPIRY, { value: true });
+  CUTS.add(error);
   return error;
 }
+
+export function isDeadlineCut(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && CUTS.has(error);
+}