@animalabs/agent-framework 0.22.1 → 0.22.2

package/src/recovery/offline-branch.ts

@@ -1,5 +1,6 @@
 import { JsStore } from '@animalabs/chronicle';
-import { ContextManager } from '@animalabs/context-manager';
+import { ContextManager, continuesBody, type BodyShard } from '@animalabs/context-manager';
+import { removeStoredInterval } from '../stored-removal.js';
 import {
   DEFAULT_DISCORD_AWARENESS_EMOJI,
   DiscordAwarenessOutbox,
@@ -202,11 +203,12 @@ export async function createOfflineRecoveryBranch(
     const createdBranch = contextManager.branchAt(target.id, targetBranch);
     try {
       await contextManager.switchBranch(createdBranch);
-      // Work from newest to oldest so earlier redactions never perturb the
-      // live positions used by later range endpoints.
+      // Each interval is removed by its messages' ids, so the order doesn't
+      // change the result. removeStoredInterval takes a single message outside
+      // any body through removeMessage, and a shard or a longer interval as a
+      // range, which refuses one that splits a body.
       for (const interval of [...suppression.intervals].reverse()) {
-        if (interval.fromId === interval.toId) contextManager.removeMessage(interval.fromId);
-        else contextManager.removeMessages(interval.fromId, interval.toId);
+        removeStoredInterval(contextManager, interval.fromId, interval.toId);
       }
       if (batch) outbox.activate(batch.id);
     } catch (error) {
@@ -238,9 +240,7 @@ interface SuppressionInterval {
 
 interface MessageLocation {
   first: number;
-  last: number;
   firstId: StoredWindowMessage['id'];
-  lastId: StoredWindowMessage['id'];
   /** Usually one run; multiple runs tolerate duplicate external metadata. */
   runs: SuppressionInterval[];
 }
@@ -299,14 +299,15 @@ function validateAnchorBoundary(
   total: number,
   target: StoredWindowMessage,
 ): void {
-  const groupId = (target as StoredWindowMessage & { bodyGroupId?: string }).bodyGroupId;
-  if (!groupId || targetIndex + 1 >= total) return;
+  if (targetIndex + 1 >= total) return;
   const next = contextManager.getMessageWindow(targetIndex + 1, 1, {
     resolveBlobs: false,
-  }).messages[0] as (StoredWindowMessage & { bodyGroupId?: string }) | undefined;
-  if (next?.bodyGroupId === groupId) {
+  }).messages[0];
+  // A body continues only into a later shard of the same ingestion: a
+  // reposted document shares its group id but starts a body of its own.
+  if (continuesBody(target as BodyShard, next as BodyShard | undefined)) {
     throw new Error(
-      `Recovery anchor ${String(target.id)} splits body group ${groupId}; choose its final shard.`,
+      `Recovery anchor ${String(target.id)} splits body group ${(target as BodyShard).bodyGroupId}; choose its final shard.`,
     );
   }
 }
@@ -321,7 +322,9 @@ function validateRemovalIntegrity(
     index >= interval.start && index <= interval.end);
   const toolUses = new Map<string, boolean>();
   const toolResults = new Map<string, boolean>();
-  const groupMembership = new Map<string, boolean>();
+  // The message before, in store order: a selection splits a body when a
+  // message continuing the one before it lands on the other side.
+  let previous: { message: BodyShard; removed: boolean } | null = null;
 
   for (let offset = 0; offset < total; offset += RECOVERY_SCAN_WINDOW) {
     const messages = contextManager.getMessageWindow(
@@ -332,16 +335,14 @@ function validateRemovalIntegrity(
     for (let i = 0; i < messages.length; i++) {
       const index = offset + i;
       const isRemoved = removed(index);
-      const message = messages[i] as StoredWindowMessage & { bodyGroupId?: string };
-      if (message.bodyGroupId) {
-        const prior = groupMembership.get(message.bodyGroupId);
-        if (prior !== undefined && prior !== isRemoved) {
-          throw new Error(
-            `Recovery selection splits body group ${message.bodyGroupId}; adjust the anchor or suppression boundary.`,
-          );
-        }
-        groupMembership.set(message.bodyGroupId, isRemoved);
+      const message = messages[i];
+      const shard = message as BodyShard;
+      if (previous && previous.removed !== isRemoved && continuesBody(previous.message, shard)) {
+        throw new Error(
+          `Recovery selection splits body group ${shard.bodyGroupId}; adjust the anchor or suppression boundary.`,
+        );
       }
+      previous = { message: shard, removed: isRemoved };
       for (const rawBlock of message.content) {
         const block = rawBlock as { type?: unknown; id?: unknown; toolUseId?: unknown };
         if (block.type === 'tool_use' && typeof block.id === 'string') {
@@ -402,9 +403,7 @@ function buildSuppressionPlan(
         };
         locations.set(externalId, {
           first: index,
-          last: index,
           firstId: messages[i].id,
-          lastId: messages[i].id,
           runs: [run],
         });
       } else {
@@ -420,8 +419,6 @@ function buildSuppressionPlan(
             toId: messages[i].id,
           });
         }
-        location.last = index;
-        location.lastId = messages[i].id;
       }
     }
   }
@@ -444,12 +441,19 @@ function buildSuppressionPlan(
     const to = locations.get(range.toMessageId)!;
     const earlier = from.first <= to.first ? from : to;
     const later = from.first <= to.first ? to : from;
+    // What's between the two messages, after the earlier one began and
+    // before the later one began: from the earlier one's first stored copy
+    // through the later one's first. Each end is every copy of it besides,
+    // as a single suppression is, so a copy stored outside that span (a
+    // write cut short and retried later) is taken on its own, and nothing
+    // else stored after the later one began is taken.
     intervals.push({
       start: earlier.first,
-      end: later.last,
+      end: later.first,
       fromId: earlier.firstId,
-      toId: later.lastId,
+      toId: later.firstId,
     });
+    for (const end of [from, to]) intervals.push(...end.runs.map((run) => ({ ...run })));
   }
 
   intervals.sort((a, b) => a.start - b.start || a.end - b.end);

package/src/stored-removal.ts

@@ -0,0 +1,126 @@
+import { bodyBoundsIn, type BodyShard, type ContextManager, type MessageId } from '@animalabs/context-manager';
+
+type StoredLike = BodyShard & { id: MessageId };
+type Removals = Pick<ContextManager, 'removeMessage' | 'removeMessages'>;
+
+/** Minimal read surface the live-surgery helpers need from a ContextManager. */
+export interface SurgeryReadableCm {
+  getMessageCount(): number;
+  getMessageWindow(
+    offset: number,
+    limit: number,
+    opts?: { resolveBlobs?: boolean; alignToBodyGroups?: boolean },
+  ): { messages: Array<{ id: unknown; bodyGroupId?: string }>; startIndex: number };
+}
+
+const SURGERY_SCAN_WINDOW = 500;
+
+/**
+ * Slot index of `messageId` on the active branch, or -1. Scans from the tail
+ * in blob-free windows: operator targets are almost always recent, and a
+ * full `getAllMessages()` re-inflates every attachment on the branch.
+ */
+export function locateMessageIndex(cm: SurgeryReadableCm, messageId: string): number {
+  const hit = locateMessageIndices(cm, new Set([messageId])).get(messageId);
+  return hit ? hit.index : -1;
+}
+
+/** Tail-first scan resolving many ids at once; stops as soon as all are found. */
+export function locateMessageIndices(
+  cm: SurgeryReadableCm,
+  ids: Set<string>,
+): Map<string, { index: number; bodyGroupId?: string }> {
+  const found = new Map<string, { index: number; bodyGroupId?: string }>();
+  const total = cm.getMessageCount();
+  for (let end = total; end > 0 && found.size < ids.size; end -= SURGERY_SCAN_WINDOW) {
+    const start = Math.max(0, end - SURGERY_SCAN_WINDOW);
+    const { messages, startIndex } = cm.getMessageWindow(start, end - start, { resolveBlobs: false });
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const id = String(messages[i].id);
+      if (ids.has(id) && !found.has(id)) {
+        found.set(id, {
+          index: startIndex + i,
+          ...(messages[i].bodyGroupId ? { bodyGroupId: messages[i].bodyGroupId } : {}),
+        });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Inclusive slot range of the body-group run containing `index` (the slot
+ * itself when it is not sharded). Delegates to the store's own
+ * `alignToBodyGroups` edge walk — one contiguity assumption, not two.
+ */
+export function bodyGroupRun(
+  cm: SurgeryReadableCm,
+  index: number,
+): { from: number; to: number; fromId: string; toId: string; group: boolean } {
+  const win = cm.getMessageWindow(index, 1, { alignToBodyGroups: true, resolveBlobs: false });
+  const from = win.startIndex;
+  const to = win.startIndex + win.messages.length - 1;
+  return {
+    from,
+    to,
+    fromId: String(win.messages[0].id),
+    toId: String(win.messages[win.messages.length - 1].id),
+    group: win.messages[0].bodyGroupId !== undefined,
+  };
+}
+
+/**
+ * Remove the stored messages `first`..`last` (inclusive, in store order).
+ *
+ * A single message outside any body goes through `removeMessage`.
+ * context-manager's `removeMessage` refuses any message that carries a body
+ * group id, a one-shard body's included, so a shard, and any longer interval,
+ * goes through `removeMessages`, which refuses an interval that splits a
+ * body.
+ */
+export function removeStoredMessages(cm: Removals, first: StoredLike, last: StoredLike): void {
+  if (first.id === last.id && !first.bodyGroupId) {
+    cm.removeMessage(first.id);
+    return;
+  }
+  cm.removeMessages(first.id, last.id);
+}
+
+/**
+ * Remove one stored message by its id, with the rest of its body when it's
+ * in one: a module or a coalescer removes a message it added by the id
+ * `addMessage` returned, which for a long message stored in shards is its
+ * first shard's.
+ */
+export function removeStoredMessage(cm: ContextManager, id: MessageId): void {
+  const message = cm.getMessage(id) as StoredLike | null;
+  if (!message?.bodyGroupId) {
+    cm.removeMessage(id);
+    return;
+  }
+  // Found in blob-free windows: a full read of the branch would inflate every
+  // attachment on it, once for each message a sweep removes.
+  const index = locateMessageIndex(cm, String(id));
+  if (index < 0) {
+    cm.removeMessage(id);
+    return;
+  }
+  const run = bodyGroupRun(cm, index);
+  cm.removeMessages(run.fromId as MessageId, run.toId as MessageId);
+}
+
+/** removeStoredMessages for an interval known by its ids. */
+export function removeStoredInterval(cm: ContextManager, fromId: MessageId, toId: MessageId): void {
+  const first = cm.getMessage(fromId) as StoredLike | null;
+  removeStoredMessages(cm, first ?? { id: fromId }, { id: toId });
+}
+
+/**
+ * The first and last positions (inclusive) of the body that holds
+ * `messages[index]`, read the way context-manager 0.14.0 reads bodies
+ * (`continuesBody`, pairwise in store order). A message outside any body is a
+ * body of its own.
+ */
+export function bodyRangeIn(messages: readonly unknown[], index: number): { from: number; to: number } {
+  return bodyBoundsIn(messages as readonly (BodyShard | null | undefined)[], index);
+}

package/src/types/agent.ts

@@ -53,11 +53,14 @@ export interface AgentConfig {
   /**
    * The model's PHYSICAL context window (provider hard cap, e.g. 200000).
    * When set, the framework projects each continuation round's real size
-   * (cache-inclusive input of the prior round + the blocks about to be
-   * appended + reserve for response) and restarts the stream through a fresh
-   * compile instead of dispatching a request the provider will 400
-   * (issue #92: a legal compile can walk past the physical window mid-turn).
-   * Unset → no projection; only the maxStreamTokens restart applies.
+   * (cache-inclusive input of the latest call that reported its prompt +
+   * that call's output + what the stream has grown by since, if later calls
+   * reported none + the blocks about to be appended + reserve for response)
+   * and restarts the stream through a fresh compile instead of dispatching a
+   * request the provider will 400 (issue #92: a legal compile can walk past
+   * the physical window mid-turn). The projection runs once a call on the
+   * stream has reported its prompt. Unset → no projection; only the
+   * maxStreamTokens restart applies.
    */
   physicalWindowTokens?: number;
 
@@ -223,7 +226,20 @@ export interface AgentRuntimeSettingsPatch {
 }
 
 export interface AgentRuntimeSettingsSnapshot {
+  /**
+   * The budget the agent is set to: while a lower one converges, its target,
+   * and while a persisted one the agent couldn't apply is kept, that one.
+   */
   contextBudgetTokens: number;
+  /**
+   * The budget compiles plan at now: the live budget, or the default when the
+   * recipe sets none (the context manager's own default is the same). It
+   * equals `contextBudgetTokens` except while a lower budget converges, when
+   * it is still the budget the descent started from (context-manager #162),
+   * and while a budget the agent couldn't apply is kept, when it is the
+   * budget the agent runs at instead.
+   */
+  effectiveContextBudgetTokens: number;
   tailTokens?: number;
   transitionPaceTokens?: number;
   sameRoundThinkTextPolicy: SameRoundThinkTextPolicy;
@@ -233,7 +249,27 @@ export interface AgentRuntimeSettingsSnapshot {
 }
 
 /** Persisted values differ from recipe defaults; omitted keys inherit config. */
-export type AgentRuntimeSettingsOverrides = AgentRuntimeSettingsPatch;
+export type AgentRuntimeSettingsOverrides = AgentRuntimeSettingsPatch & {
+  /**
+   * The record's own `contextBudgetTokens`, written when a compile at the
+   * agent's live budget fits at it, with nothing about the budget changed
+   * while it ran (a paced descent's settle included): the store fit that
+   * budget. A compile the context manager refuses at it as over budget
+   * withdraws it, unless a compile at it that started later has already
+   * ended.
+   * When it equals `contextBudgetTokens`, a restore applies that budget at
+   * once, rather than pacing a descent again from the recipe's budget
+   * (context-manager #162), if a preview at boot says it still fits; if not,
+   * a budget below the recipe's restores paced, and if a compile at one that
+   * the boot applied at once is refused, the agent restores it paced then.
+   * Since the store fit it when the field was written, the planner can fold
+   * to it at once even if its carried frontier was lost. Any other value is
+   * stale (the budget changed since, or an earlier release carried the field
+   * forward), and a budget below the recipe's restores paced, as it does
+   * without the field. Never part of a patch.
+   */
+  contextBudgetReachedTokens?: number;
+};
 
 /**
  * Result of running inference.

package/src/types/framework.ts

@@ -302,6 +302,10 @@ export interface ContextMaintenanceAgentRun {
   pendingAfter?: string;
   progressBefore?: Record<string, unknown>;
   progressAfter?: Record<string, unknown>;
+  /**
+   * The agent's failure in this pass: a tick that threw, or its readiness
+   * that couldn't be read, before the ticks or after them.
+   */
   error?: string;
 }
 
@@ -323,6 +327,12 @@ export interface ContextMaintenanceSnapshot {
     agentName: string;
     ready: boolean;
     pending?: string;
+    /**
+     * Why the agent's readiness can't be read: the context manager refuses
+     * while its strategy's initialization is pending or has failed, and a
+     * strategy can refuse on its own. `ready` is false then.
+     */
+    error?: string;
     progress?: Record<string, unknown>;
   }>;
 }

package/src/types/module.ts

@@ -321,10 +321,14 @@ export interface ModuleContext {
    *
    * Modules use this to react to agent lifecycle without polling — e.g. an
    * adapter that wants to show a "typing" indicator can bracket it between
-   * `inference:started` and the terminal events (`inference:turn_ended`,
-   * `inference:aborted`, `inference:failed`, `inference:exhausted`), all of
-   * which carry `agentName`. The terminal events fire once per turn, after any
-   * tool-call cycles, so a single start/stop bracket spans the whole turn.
+   * `inference:started` and the terminal events: `inference:completed` (the
+   * normal end), `inference:turn_ended` (a tool result ended the turn),
+   * `inference:aborted`, `inference:failed` and `inference:exhausted`, all of
+   * which carry `agentName`. A turn's tool-call cycles stay inside its
+   * stream, so one bracket spans them. A context-budget restart emits
+   * `inference:started` again with no terminal event for the stream it
+   * replaced, and a failing turn can emit `inference:failed` and then
+   * `inference:exhausted`, so a bracket should allow a repeated start or end.
    *
    * Returns an unsubscribe function. Call it in the module's `stop()` to avoid
    * leaking listeners across teardown/recreate (e.g. session switch).

package/src/types/trace.ts

@@ -41,11 +41,14 @@ export type TraceEvent =
       type: 'inference:started';
       agentName: string;
       /**
-       * The turn-frozen outbound locus (see turnLocusPins) — the channel this
-       * turn's plain prose will be routed to. Omitted for turns with no locus
-       * (heartbeats with no default channel). Observability only, like every
-       * trace field; lets external taps (e.g. a TTS relay) tag the whole
-       * activation with its channel without re-deriving routing.
+       * The turn's locus as this stream starts (locus and hybrid mode): where
+       * its unprefixed plain prose is published, unless a hybrid `>>>`
+       * destination takes it, or a re-pin or a `channel_open` moves the locus
+       * later in the turn. Omitted for a turn with no locus: explicit and
+       * disabled mode, a silent turn, and a heartbeat with no default
+       * channel. Observability only, like every trace field; lets external
+       * taps (e.g. a TTS relay) tag the whole activation with its channel
+       * without re-deriving routing.
        */
       channelId?: string;
       /** True for a control-plane wake that must not surface typing/prose. */
@@ -60,7 +63,15 @@ export type TraceEvent =
   | (TraceEventBase & {
       type: 'inference:aborted';
       agentName: string;
+      /** How long this start of the turn ran; after a context-budget restart, from the restart. */
       durationMs: number;
+      /**
+       * Why the turn ended unfinished: the reason an operator gave
+       * `abortInference`, `'quiesce_abandoned'` for a turn an operator quiesce
+       * abandoned, or, for a turn dropped before it sent anything (its agent
+       * replaced or removed, or the framework stopping or restarted), a
+       * sentence saying which.
+       */
       reason?: string;
     })
   | (TraceEventBase & {
@@ -104,7 +115,9 @@ export type TraceEvent =
       blockType: 'text' | 'thinking' | 'tool_call' | 'tool_result';
       /** 0-indexed block position in the current assistant turn. */
       blockIndex: number;
-      /** Turn-frozen outbound locus for this turn (see inference:started). */
+      /** The channel this stream shows typing in: the turn's locus as the
+       *  stream started (see inference:started), or in explicit mode the
+       *  channel the start's wake came from. */
       channelId?: string;
     })
   | (TraceEventBase & {
@@ -119,7 +132,9 @@ export type TraceEvent =
       phase: 'block_start' | 'block_complete';
       blockType: 'text' | 'thinking' | 'tool_call' | 'tool_result';
       blockIndex: number;
-      /** Turn-frozen outbound locus for this turn (see inference:started). */
+      /** The channel this stream shows typing in: the turn's locus as the
+       *  stream started (see inference:started), or in explicit mode the
+       *  channel the start's wake came from. */
       channelId?: string;
     })
   | (TraceEventBase & {
@@ -236,22 +251,47 @@ export type TraceEvent =
       messageId: string;
       source: string;
     })
-  /** A push/event refused at the MCPL boundary (today: visibly-empty content). */
+  /** A push/event refused at the MCPL boundary: visibly-empty content
+   *  (`empty-content`, answered -32602, with no `field` or `detail`), or a
+   *  coalesced occurrence the host refused. A refused occurrence's reason
+   *  follows the code the producer was answered with: `coalesce-invalid` when
+   *  the occurrence was the producer's to fix (-32602 malformed; -32017 or
+   *  -32023 for a channel not permitted or not registered), `coalesce-failed`
+   *  when the host itself failed (-32000, -32603). Its trace carries the
+   *  error's message in `detail`, and the failing `field` when the error
+   *  names one, and `channelId` when the push is refused for its channel
+   *  (-32017, -32023), so each refusal names its channel even while repeats
+   *  of its line are held back. An `eventId` that is missing or isn't a
+   *  string is traced as `''`. A push refused for its feature set, or as a
+   *  duplicate, gets a `[push-event-rejected]` line and no trace. */
   | (TraceEventBase & {
       type: 'mcpl:push-event-rejected';
       serverId: string;
       eventId: string;
       featureSet: string;
       reason: string;
-    })
-  /** A channels/incoming message refused at the MCPL boundary: unregistered
-   *  channel (§14.5), or visibly-empty content (then `messageId` is set). */
+      field?: string;
+      channelId?: string;
+      detail?: string;
+    })
+  /** A channels/incoming message refused at the MCPL boundary: an
+   *  unregistered channel (`unknown-channel`, §14.5), visibly-empty content
+   *  (`empty-content`), or a coalesced item the host refused
+   *  (`coalesce-invalid` / `coalesce-failed`, with `detail`, and `field` when
+   *  the error names one, as for a push). A coalesced item refused with
+   *  -32602 (malformed) is answered `coalesce_invalid`, and one refused
+   *  otherwise (-32000, or an internal error) with the error's own message.
+   *  `messageId` is set whenever the message carries one. An uncoalesced
+   *  message without a channelId or messageId is answered `invalid
+   *  channel/message identity`, with no line and no trace. */
   | (TraceEventBase & {
       type: 'mcpl:channel-incoming-rejected';
       serverId: string;
       channelId: string;
       messageId?: string;
       reason: string;
+      field?: string;
+      detail?: string;
     })
   /** MCPL content with nothing model-visible reached the store/wake site
    *  (module-emitted or coalescer-delivered) and was dropped: no row, no wake. */
@@ -441,6 +481,12 @@ export type TraceEvent =
       type: 'mcpl:server-connect-failed';
       serverId: string;
       error: string;
+      /** The last of the server's stderr, when its handshake failed by its
+       *  transport closing, a transport error or its timeout and it had
+       *  written any: the server's own text, which `error` never carries. A
+       *  transport that failed its handshake was never wired, so its lines
+       *  never reached `mcpl:server-stderr`. */
+      stderrTail?: string;
       /** Ordinal of the failed attempt: 0 is the initial connect, N is the Nth background retry. */
       attempt: number;
       /** True when a background reconnect loop will keep retrying. */
@@ -468,6 +514,11 @@ export type TraceEvent =
       code: number | null;
       /** Signal that terminated the child, if any. */
       signal: string | null;
+      /** Why the transport closed, in its own words, such as `child process
+       *  exited, and its pipe failed with write EPIPE` or `closed by host`;
+       *  null when it gave none, or when its reason is a WebSocket server's
+       *  own close text, which stays off the trace. */
+      reason: string | null;
       /** True when a background reconnect loop will revive the connection. */
       willReconnect: boolean;
     })