@animalabs/context-manager 0.5.4 → 0.5.9

package/src/adaptive/picker.ts

@@ -81,11 +81,32 @@ export interface PickerChunk {
   lockedByAgent: boolean;
   bodyGroupId?: string;
   pinned: boolean;
+  /**
+   * V2 dynamic pin — fix this chunk at EXACTLY this fold level (0 = raw). Set
+   * from a `ProtectedRange.level`. Such a chunk is NOT `pinned` (the controller
+   * must be able to move it to its level), but the KV-stable controller holds it
+   * there and never folds/un-folds it. Ignored by non-kv-stable strategies.
+   */
+  pinLevel?: number;
+  /**
+   * V2 dynamic pin — this chunk may fold no deeper than this level (hard cap).
+   * Set from a `ProtectedRange.maxLevel`. Honored only by the KV-stable
+   * controller (in normal and emergency shedding). Ignored elsewhere.
+   */
+  pinMaxLevel?: number;
   /**
    * The L1 summary covering this chunk, if any. Higher levels are derived
    * by walking parentId pointers in the summary tree.
    */
   l1Id?: SummaryId;
+  /**
+   * Salience ∈ [0,1] — the coefficient on this chunk's information loss
+   * (design §13.3). Lower = folds earlier and costs less when folded:
+   * content whose payload is externalized (code on disk, tool output,
+   * images, link drops) vs conversation that exists nowhere else. Default 1.
+   * Honored by the kv-stable controller; never overrides hard protections.
+   */
+  salience?: number;
 }
 
 export interface PickerInputs {

package/src/adaptive/strategies/kv-stable.ts

@@ -30,14 +30,16 @@ import type {
 } from '../folding-strategy.js';
 import type { PickerInputs } from '../picker.js';
 import { SummaryTree } from '../summary-tree.js';
-import { planControlledFrontier } from '../kv-control.js';
+import { planControlledFrontier, type ControlPlan } from '../kv-control.js';
 
 export interface KvStableOptions {
-  /** Per-turn divergence reach — the structural perturbation cap P, in tokens.
-   *  Smaller = gentler per-turn KV churn (shallow divergence) but less efficient
-   *  compression. Exceeded only to stay under the hard wall. Default: the hard
-   *  budget (effectively unbounded within the window). */
+  /** Trust region P on per-turn perturbation, in tokens the provider would
+   *  re-read (exact kvCost — see design §13.4). Within it the solver adopts
+   *  the relevance-ideal cut; beyond it it amortizes via suffix adoption or
+   *  overrides with cause. Default: the hard budget (never binds). */
   reachTokens?: number;
+  /** Quality-gap override threshold (design §13.4). Default 0.35. */
+  qualityGapRatio?: number;
   /** Base-k summary grouping (matches the strategy's mergeThreshold). Default 6. */
   mergeThreshold?: number;
 }
@@ -49,6 +51,7 @@ export class KvStableStrategy implements FoldingStrategy {
   private readonly opts: KvStableOptions;
   private readonly fPrev: Map<ChunkId, number>;
   private target: Map<ChunkId, number> | null = null;
+  private _lastPlan: ControlPlan | null = null;
 
   constructor(inputs: PickerInputs, opts: KvStableOptions = {}) {
     this.inputs = inputs;
@@ -66,38 +69,85 @@ export class KvStableStrategy implements FoldingStrategy {
     return this.target;
   }
 
+  /** The full control plan behind the target (perturbation, override) — for
+   *  observability at the call site (`[kv-escalation]` logging). Null before
+   *  the first `selectNextFold`. */
+  lastPlan(): ControlPlan | null {
+    return this._lastPlan;
+  }
+
   private solve(budget: FoldingBudget): Map<ChunkId, number> {
     const tree = new SummaryTree(this.inputs);
 
-    // Flat zone (forced raw, never folded): head, tail, pinned. Frozen (kept at
-    // their carried resolution, never folded): locked.
+    // Flat zone (forced raw, never folded): head, tail, classic pins. Frozen
+    // (kept at their carried resolution, never folded): locked. V2 dynamic pins
+    // (`pinLevel` / `pinMaxLevel`) are honored as a fixed level or a hard fold-
+    // depth cap — see `planControlledFrontier`.
     const rawZone = new Set<ChunkId>();
     const frozen = new Set<ChunkId>();
+    const fixedLevels = new Map<ChunkId, number>();
+    const pinCaps = new Map<ChunkId, number>();
+    const fixedPins: Array<{ id: ChunkId; level: number }> = [];
     let now = 0;
     for (const c of this.inputs.chunks) {
       if (c.sequence > now) now = c.sequence;
       if (this.inputs.headChunkIds.has(c.id) || this.inputs.tailChunkIds.has(c.id) || c.pinned) {
         rawZone.add(c.id);
+      } else if (c.pinLevel !== undefined) {
+        // Pin-at-level-k: fix exactly at k (0 = raw). k=0 is equivalent to a
+        // classic raw pin, so route it through the raw zone; k>0 is resolved to
+        // its whole L_k node below (group-consistent — see the loop after).
+        if (c.pinLevel <= 0) rawZone.add(c.id);
+        else fixedPins.push({ id: c.id, level: c.pinLevel });
+      } else if (c.pinMaxLevel !== undefined) {
+        // Pin-max-level: a hard fold-depth cap. maxLevel 0 ≡ classic raw pin.
+        if (c.pinMaxLevel <= 0) rawZone.add(c.id);
+        else pinCaps.set(c.id, c.pinMaxLevel);
+        if (c.lockedByAgent) frozen.add(c.id);
       } else if (c.lockedByAgent) {
         frozen.add(c.id);
       }
     }
 
-    return planControlledFrontier(this.inputs, tree, {
+    // Group-consistency for pin-at-level-k: an L_k recall pair is atomic over
+    // its whole covered range, so "cut through the L_k node" (design §7) fixes
+    // EVERY leaf under that node at k — not just the addressed chunk. Fixing a
+    // single sub-chunk while its siblings render raw is an unrenderable (and
+    // non-converging) frontier. Clamp k to the deepest produced level for the
+    // chunk; if none exists, fall back to fixing just the chunk (the controller
+    // clamps it further). Skip leaves already forced raw (head/tail/classic pin).
+    for (const { id, level } of fixedPins) {
+      const eff = Math.min(level, tree.maxLevel(id));
+      if (eff <= 0) { rawZone.add(id); continue; }
+      const node = tree.ancestorAt(id, eff);
+      if (!node) { fixedLevels.set(id, eff); continue; }
+      for (const leaf of node.leafChunkIds) {
+        if (rawZone.has(leaf)) continue;
+        // Finest requirement wins if two pins overlap a leaf.
+        const prev = fixedLevels.get(leaf);
+        fixedLevels.set(leaf, prev === undefined ? eff : Math.min(prev, eff));
+      }
+    }
+
+    const plan = planControlledFrontier(this.inputs, tree, {
       previous: this.fPrev,
-      // Bidirectional within the slack band: fold when over the hard budget,
-      // un-fold to use headroom when under the soft target. Both reach-bounded;
-      // [targetBudget, totalBudget] is the quiet dead band.
+      // Single-path solve (design §13.4): the [targetBudget, totalBudget] band
+      // is the quiet dead band; the trust region and overrides do the rest.
       foldAtTokens: budget.totalBudget,
       expandAtTokens: budget.targetBudget,
       targetTokens: budget.targetBudget,
       windowTokens: budget.totalBudget,
       reachTokens: this.opts.reachTokens,
+      qualityGapRatio: this.opts.qualityGapRatio,
       rawZone,
       frozen,
+      fixedLevels,
+      pinCaps,
       now,
       mergeThreshold: this.opts.mergeThreshold,
-    }).resolutions;
+    });
+    this._lastPlan = plan;
+    return plan.resolutions;
   }
 
   /** Emit one op moving the live state toward the target frontier. */

package/src/context-log.ts

@@ -323,6 +323,17 @@ export class ContextLog {
   }
 
   private getInternal(index: number): ContextEntryInternal | null {
+    // Point lookup through chronicle's per-item cache — O(item size).
+    // See MessageStore.getInternal for why this must never fetch the
+    // full state per index.
+    //
+    // Feature-detect: getStateItemJson landed in chronicle 0.2.2; boxes
+    // still on <= 0.2.1 (npm copies) fall back to the full-materialization
+    // path so a routine `git pull` of this package can never crash them.
+    if (typeof (this.store as { getStateItemJson?: unknown }).getStateItemJson === 'function') {
+      const item = this.store.getStateItemJson(this.stateId, index);
+      return (item as ContextEntryInternal | null) ?? null;
+    }
     const all = this.getAllInternal();
     return all[index] ?? null;
   }

package/src/context-manager.ts

@@ -1,5 +1,5 @@
 import { JsStore } from '@animalabs/chronicle';
-import type { Membrane, NormalizedMessage, ContentBlock } from '@animalabs/membrane';
+import type { Membrane, NormalizedMessage, ContentBlock, ToolDefinition } from '@animalabs/membrane';
 import type {
   MessageId,
   Sequence,
@@ -16,13 +16,14 @@ import type {
   ContextInjection,
   CompileResult,
   ProtectedRange,
+  PinLevelOptions,
   SearchQuery,
   SearchResult,
   SummaryEntry,
 } from './types/index.js';
 import { isResettableStrategy, isPinnableStrategy, isSearchableStrategy, isRenderStatsCapable } from './types/index.js';
 import type { RenderStats } from './types/index.js';
-import { MessageStore, MessageStoreEvent } from './message-store.js';
+import { MessageStore, MessageStoreEvent, MessageStoreListener, MessageWindow, MessageWindowOptions } from './message-store.js';
 import { ContextLog } from './context-log.js';
 import { PassthroughStrategy } from './strategies/passthrough.js';
 import { splitMixedToolMessages } from './normalize-tool-messages.js';
@@ -300,6 +301,31 @@ export class ContextManager {
     return this.messageStore.getAll();
   }
 
+  /**
+   * Get the total number of messages — O(1).
+   */
+  getMessageCount(): number {
+    return this.messageStore.length();
+  }
+
+  /**
+   * Get a window of messages by slot index — O(window), not O(all).
+   * See MessageStore.getWindow for options (blob resolution, bodyGroup
+   * alignment). Intended for viewers/paginated UIs.
+   */
+  getMessageWindow(offset: number, limit: number, opts?: MessageWindowOptions): MessageWindow {
+    return this.messageStore.getWindow(offset, limit, opts);
+  }
+
+  /**
+   * Subscribe to message-store mutations (add/edit/remove/removeRange).
+   * Returns a detacher. Unlike trace events, this fires for ALL stored
+   * messages including assistant turns and tool results.
+   */
+  onMessage(listener: MessageStoreListener): () => void {
+    return this.messageStore.addListener(listener);
+  }
+
   /**
    * Query messages by filter criteria.
    * Useful for finding messages from external sources, by participant, etc.
@@ -640,19 +666,29 @@ export class ContextManager {
    *
    * Throws if the active strategy doesn't support pins.
    */
-  pinRange(firstMessageId: MessageId, lastMessageId: MessageId, opts?: { name?: string }): string {
+  pinRange(firstMessageId: MessageId, lastMessageId: MessageId, opts?: PinLevelOptions): string {
     if (!isPinnableStrategy(this.strategy)) {
       throw new Error('Active strategy does not support pins');
     }
     return this.strategy.pinRange(firstMessageId, lastMessageId, opts);
   }
 
+  /**
+   * V2 dynamic pin-at-level-k: fix a range to render at EXACTLY fold level
+   * `level` (0 = raw) — the frontier cut passes through that L_k node. Honored
+   * only by `foldingStrategy: 'kv-stable'`; other strategies fall back to
+   * treating the range as raw. Returns the new pin id.
+   */
+  pinAtLevel(firstMessageId: MessageId, lastMessageId: MessageId, level: number, opts?: { name?: string }): string {
+    return this.pinRange(firstMessageId, lastMessageId, { name: opts?.name, level });
+  }
+
   /**
    * Mark a single message as a "document" (semantically a body of
    * information to retain in full). Same effect as a single-message pin
    * with `kind: 'document'`. Returns the new pin id.
    */
-  markDocument(messageId: MessageId, opts?: { name?: string }): string {
+  markDocument(messageId: MessageId, opts?: PinLevelOptions): string {
     if (!isPinnableStrategy(this.strategy)) {
       throw new Error('Active strategy does not support documents');
     }
@@ -758,7 +794,22 @@ export class ContextManager {
     }
   }
 
+  /**
+   * Live tool definitions for the owning agent, refreshed by the host on
+   * every activation (Agent.buildActivationRequest in agent-framework).
+   * Threaded into StrategyContext so compression/summarizer LLM calls can
+   * declare the same tools as the live instance — required to avoid
+   * reasoning_extraction refusals on transcripts containing tool blocks.
+   */
+  private toolDefinitions?: ToolDefinition[];
+
+  /** Host hook: record the agent's current tool definitions (see above). */
+  setToolDefinitions(tools: ToolDefinition[] | undefined): void {
+    if (tools && tools.length > 0) this.toolDefinitions = tools;
+  }
+
   private createStrategyContext(): StrategyContext {
+    const self = this;
     return {
       messageStore: this.messageStore.createView(),
       contextLog: this.contextLog.createView(),
@@ -766,6 +817,12 @@ export class ContextManager {
       currentSequence: this.store.currentSequence(),
       store: this.store,
       namespace: this.strategyNamespace,
+      // Live getter, not a snapshot: strategies capture a ctx object once and
+      // reuse it across a long-running drain (driveSpeculativeDrain recurses
+      // with the same ctx). A snapshot taken before the session's first
+      // activation would freeze `tools` as undefined for the drain's entire
+      // lifetime — the getter always reflects the latest activation.
+      get tools() { return self.toolDefinitions; },
     };
   }
 

package/src/index.ts

@@ -2,15 +2,19 @@
 export { ContextManager } from './context-manager.js';
 export type { ContextManagerConfig } from './context-manager.js';
 
+// Phase channel (liveness-watchdog observability hook)
+export { phaseChannel, enterPhase, withPhase, withPhaseAsync } from './phase-channel.js';
+
 // Storage
 export { MessageStore } from './message-store.js';
-export type { MessageStoreEvent, MessageStoreListener } from './message-store.js';
+export type { MessageStoreEvent, MessageStoreListener, MessageWindow, MessageWindowOptions } from './message-store.js';
+export { concatBodyGroups } from './adaptive/render.js';
 export { ContextLog } from './context-log.js';
 export { BlobManager } from './blob-manager.js';
 
 // Strategies
 export { PassthroughStrategy } from './strategies/passthrough.js';
-export { AutobiographicalStrategy, type AutobiographicalProgressSnapshot } from './strategies/autobiographical.js';
+export { AutobiographicalStrategy, type AutobiographicalProgressSnapshot, type Chunk } from './strategies/autobiographical.js';
 export { KnowledgeStrategy } from './strategies/knowledge.js';
 
 // Utilities

package/src/message-store.ts

@@ -28,6 +28,39 @@ export type MessageStoreEvent =
  */
 export type MessageStoreListener = (event: MessageStoreEvent) => void;
 
+/**
+ * Options for windowed message reads.
+ */
+export interface MessageWindowOptions {
+  /**
+   * Re-inline blob media (images/documents) into content blocks, matching
+   * the behavior of get()/getAll(). Default true. Viewers that only need
+   * text/thinking/tool blocks should pass false to avoid inflating large
+   * base64 payloads.
+   */
+  resolveBlobs?: boolean;
+  /**
+   * Extend the window edges outward so that no bodyGroup (shard run of a
+   * single large message) is split across the window boundary. Default
+   * false (exact offset/limit semantics).
+   */
+  alignToBodyGroups?: boolean;
+}
+
+/**
+ * A window of messages plus enough metadata to page through the store.
+ */
+export interface MessageWindow {
+  messages: StoredMessage[];
+  /**
+   * Actual first slot index of the returned window. May be lower than the
+   * requested offset when alignToBodyGroups extended the window backward.
+   */
+  startIndex: number;
+  /** Total number of messages in the store at read time. */
+  totalCount: number;
+}
+
 /**
  * Options for token estimation.
  */
@@ -358,19 +391,72 @@ export class MessageStore {
     );
   }
 
+  /**
+   * Get a window of messages by slot index — O(window), not O(all).
+   *
+   * Backed by chronicle's `getStateSlice` (0.2.2+) with a
+   * full-materialization fallback for older chronicle copies, mirroring
+   * the feature-detect in getInternal().
+   */
+  getWindow(offset: number, limit: number, opts: MessageWindowOptions = {}): MessageWindow {
+    const totalCount = this.length();
+    let start = Math.max(0, Math.min(offset, totalCount));
+    let end = Math.min(start + Math.max(0, limit), totalCount);
+
+    if (start >= end) {
+      return { messages: [], startIndex: Math.min(start, totalCount), totalCount };
+    }
+
+    if (opts.alignToBodyGroups) {
+      // Shards of a bodyGroup are contiguous by construction (removeRange
+      // refuses to bisect a group). Walk edges outward with O(item) point
+      // lookups until the group boundary.
+      const first = this.getInternal(start);
+      if (first?.bodyGroupId !== undefined) {
+        while (start > 0) {
+          const prev = this.getInternal(start - 1);
+          if (prev?.bodyGroupId !== first.bodyGroupId) break;
+          start--;
+        }
+      }
+      const last = this.getInternal(end - 1);
+      if (last?.bodyGroupId !== undefined) {
+        while (end < totalCount) {
+          const next = this.getInternal(end);
+          if (next?.bodyGroupId !== last.bodyGroupId) break;
+          end++;
+        }
+      }
+    }
+
+    const internals = this.getSliceInternal(start, end - start);
+    const resolveBlobs = opts.resolveBlobs !== false;
+    return {
+      messages: internals.map((internal, i) =>
+        this.internalToStored(internal, internal.id, start + i, resolveBlobs)
+      ),
+      startIndex: start,
+      totalCount,
+    };
+  }
+
   /**
    * Get messages from a specific index.
+   * Negative indices count from the end, matching Array.prototype.slice.
    */
   getFrom(index: number): StoredMessage[] {
-    return this.getAll().slice(index);
+    const len = this.length();
+    const start = index < 0 ? Math.max(0, len + index) : Math.min(index, len);
+    return this.getWindow(start, len - start).messages;
   }
 
   /**
    * Get the last N messages.
    */
   getTail(count: number): StoredMessage[] {
-    const all = this.getAll();
-    return all.slice(Math.max(0, all.length - count));
+    const len = this.length();
+    const n = Math.max(0, Math.min(count, len));
+    return this.getWindow(len - n, n).messages;
   }
 
   /**
@@ -391,21 +477,62 @@ export class MessageStore {
     return tokens;
   }
 
+  /**
+   * Closed-loop calibration multiplier applied to every estimate (default 1).
+   * Owned by the strategy: it compares real `usage` totals against the
+   * compile-time estimate and feeds the EMA back here, so the store's
+   * numbers track the live model/content mix instead of a fixed heuristic.
+   */
+  private tokenCalibration = 1;
+
+  setTokenCalibration(factor: number): void {
+    if (Number.isFinite(factor) && factor > 0.25 && factor < 4) this.tokenCalibration = factor;
+  }
+
+  getTokenCalibration(): number {
+    return this.tokenCalibration;
+  }
+
+  /**
+   * Hidden-CoT price for a signed thinking block whose text was summarized/
+   * redacted away (2026-07-12): the block estimates as EMPTY client-side, but
+   * signed replay bills the FULL original chain of thought. Measured on
+   * mythos production turns: median ~608 tokens/block, mean ~590, p90 ~1210.
+   * A per-block `tokenEstimate` stamped at creation (from usage residuals)
+   * takes precedence; this constant is the fallback for unstamped history.
+   */
+  static readonly HIDDEN_THINKING_TOKENS_DEFAULT = 600;
+
   private estimateBlockTokens(block: ContentBlock): number {
+    return Math.round(this.estimateBlockTokensRaw(block) * this.tokenCalibration);
+  }
+
+  private estimateBlockTokensRaw(block: ContentBlock): number {
     switch (block.type) {
       case 'text':
         return this.tokenEstimator(block.text);
-      case 'thinking':
+      case 'thinking': {
+        // Stamped price wins; a signed-but-empty block is a HIDDEN full CoT
+        // (never "no thinking") — price it at the measured default.
+        const stamped = (block as { tokenEstimate?: number }).tokenEstimate;
+        if (typeof stamped === 'number') return stamped;
+        const hasSignature =
+          typeof (block as { signature?: string }).signature === 'string' &&
+          ((block as { signature?: string }).signature as string).length > 0;
+        if (hasSignature && (!block.thinking || block.thinking.length === 0)) {
+          return MessageStore.HIDDEN_THINKING_TOKENS_DEFAULT;
+        }
         return this.tokenEstimator(block.thinking);
+      }
       case 'tool_use':
-        return this.tokenEstimator(JSON.stringify(block.input)) + 20; // overhead for name, id
+        return jsonTokenEstimator(JSON.stringify(block.input)) + 20; // overhead for name, id
       case 'tool_result':
         if (!block.content) return 0;
         if (typeof block.content === 'string') {
-          return this.tokenEstimator(block.content);
+          return jsonTokenEstimator(block.content);
         }
         if (Array.isArray(block.content)) {
-          return block.content.reduce((sum, b) => sum + this.estimateBlockTokens(b), 0);
+          return block.content.reduce((sum, b) => sum + this.estimateBlockTokensRaw(b), 0);
         }
         return 0;
       case 'image':
@@ -429,6 +556,8 @@ export class MessageStore {
       getFrom: (index) => this.getFrom(index),
       getTail: (count) => this.getTail(count),
       length: () => this.length(),
+      setTokenCalibration: (f: number) => this.setTokenCalibration(f),
+      getTokenCalibration: () => this.getTokenCalibration(),
       estimateTokens: (msg) => this.estimateTokens(msg),
     };
   }
@@ -545,7 +674,35 @@ export class MessageStore {
     return state as StoredMessageInternal[];
   }
 
+  private getSliceInternal(offset: number, limit: number): StoredMessageInternal[] {
+    // Windowed read — O(window) JSON conversion instead of materializing
+    // the entire state slot. getStateSlice landed in chronicle 0.2.2 and
+    // returns the window as a JSON-array Buffer; feature-detect so boxes
+    // on <= 0.2.1 fall back to full materialization (same pattern as
+    // getInternal below).
+    const s = this.store as { getStateSlice?: (id: string, offset: number, limit: number) => Buffer | null };
+    if (typeof s.getStateSlice === 'function') {
+      const buf = s.getStateSlice(this.stateId, offset, limit);
+      if (!buf) return [];
+      return JSON.parse(buf.toString('utf-8')) as StoredMessageInternal[];
+    }
+    return this.getAllInternal().slice(offset, offset + limit);
+  }
+
   private getInternal(index: number): StoredMessageInternal | null {
+    // Point lookup through chronicle's per-item cache — O(item size).
+    // Never fetch the full state for a single index: with a 4.6k-message
+    // session, each full `getStateJson` materialization cost ~15ms, and
+    // per-entry get() loops turned renders into minutes (observed on
+    // Lena, 2026-07-02, /debug/context at 51–108s).
+    //
+    // Feature-detect: getStateItemJson landed in chronicle 0.2.2; boxes
+    // still on <= 0.2.1 (npm copies) fall back to the full-materialization
+    // path so a routine `git pull` of this package can never crash them.
+    if (typeof (this.store as { getStateItemJson?: unknown }).getStateItemJson === 'function') {
+      const item = this.store.getStateItemJson(this.stateId, index);
+      return (item as StoredMessageInternal | null) ?? null;
+    }
     const all = this.getAllInternal();
     return all[index] ?? null;
   }
@@ -554,6 +711,7 @@ export class MessageStore {
     internal: StoredMessageInternal,
     id: MessageId,
     _index: number,
+    resolveBlobs: boolean = true,
   ): StoredMessage {
     const stored: StoredMessage = {
       id,
@@ -570,7 +728,12 @@ export class MessageStore {
       // so /undo of a 800-message conversation forked ~400 messages back.
       sequence: internal.sequence,
       participant: internal.participant,
-      content: this.blobManager.resolveBlobs(internal.content),
+      // When resolveBlobs is false, blob_ref placeholder blocks are passed
+      // through un-inflated (StoredContentBlock ⊂ wire-safe superset of
+      // ContentBlock for viewer purposes).
+      content: resolveBlobs
+        ? this.blobManager.resolveBlobs(internal.content)
+        : (internal.content as unknown as ContentBlock[]),
       metadata: internal.metadata,
       timestamp: new Date(internal.timestamp),
       causedBy: internal.causedBy,
@@ -587,6 +750,36 @@ export class MessageStore {
 /**
  * Default token estimator: chars / 4
  */
+/**
+ * Content-class token rates (2026-07-12, measured on mythos production
+ * requests by reconciling real `usage` against per-class char counts):
+ *   - prose (Discord multiparty, markdown, emoji)  ≈ 2.9 chars/token
+ *   - JSON / tool i/o / code                        ≈ 2.3 chars/token
+ * The old flat chars/4 under-priced real windows by ~1.7-1.9x (a 183.6k
+ * "hard budget" compiled to a 344k request — straight into the refusal
+ * band). Rates are deliberately slightly conservative; the closed-loop
+ * calibration multiplier trims the residual per agent.
+ */
+const PROSE_CHARS_PER_TOKEN = 2.9;
+const DENSE_CHARS_PER_TOKEN = 2.3;
+
 function defaultTokenEstimator(text: string): number {
-  return Math.ceil(text.length / 4);
+  if (!text) return 0;
+  // Cheap density probe: JSON/code punctuation and non-ASCII share.
+  let dense = 0;
+  const n = Math.min(text.length, 2000);
+  for (let i = 0; i < n; i++) {
+    const c = text.charCodeAt(i);
+    if (c > 126) { dense++; continue; } // non-ASCII (emoji, accents, CJK)
+    const ch = text[i];
+    if (ch === '{' || ch === '}' || ch === '[' || ch === ']' || ch === '"' || ch === ':' || ch === '_' || ch === '/' || ch === '=' || ch === '`') dense++;
+  }
+  const rate = dense / n > 0.12 ? DENSE_CHARS_PER_TOKEN : PROSE_CHARS_PER_TOKEN;
+  return Math.ceil(text.length / rate);
+}
+
+/** JSON-ish payloads (tool inputs/results) always use the dense rate. */
+function jsonTokenEstimator(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / DENSE_CHARS_PER_TOKEN);
 }

package/src/phase-channel.ts

@@ -0,0 +1,57 @@
+/**
+ * Phase channel — a process-wide observability hook for labelling the
+ * synchronous operation the main thread is currently running.
+ *
+ * Long synchronous work (context assembly, compression, merge-graph walks) can
+ * wedge the single-threaded event loop. An external liveness watchdog (in the
+ * host/agent-framework) can detect the wedge but not name what was running —
+ * unless the running code labels itself here. This module is a no-op sink by
+ * default; the watchdog installs `report` on start so labels reach its wedge
+ * report. context-manager owns the channel (no upward dependency); the watchdog
+ * (which depends on context-manager) wires it.
+ */
+const stack: string[] = [];
+
+export const phaseChannel: {
+  /** Installed by the watchdog; receives the current (innermost) phase label. */
+  report: (label: string) => void;
+} = {
+  report: () => {},
+};
+
+/** Enter a named phase. Returns a disposer that restores the previous phase. */
+export function enterPhase(label: string): () => void {
+  stack.push(label);
+  phaseChannel.report(label);
+  let done = false;
+  return () => {
+    if (done) return;
+    done = true;
+    // Pop this label (tolerate out-of-order disposal defensively).
+    const idx = stack.lastIndexOf(label);
+    if (idx !== -1) stack.splice(idx, 1);
+    phaseChannel.report(stack[stack.length - 1] ?? 'idle');
+  };
+}
+
+/** Run a synchronous section under a phase label (nesting-safe). */
+export function withPhase<T>(label: string, fn: () => T): T {
+  const leave = enterPhase(label);
+  try {
+    return fn();
+  } finally {
+    leave();
+  }
+}
+
+/** Run an async section under a phase label. Note: this labels across awaits,
+ *  which is what we want — the synchronous spans inside (where a wedge would
+ *  occur) stay attributed to this phase. */
+export async function withPhaseAsync<T>(label: string, fn: () => Promise<T>): Promise<T> {
+  const leave = enterPhase(label);
+  try {
+    return await fn();
+  } finally {
+    leave();
+  }
+}