@animalabs/agent-framework 0.12.0 → 0.14.0

package/dist/src/tool-image-ledger.js

@@ -0,0 +1,257 @@
+/**
+ * Per-agent retention of tool-result images, with provenance (issue #104).
+ *
+ * History keeps a compact text placeholder for every image a tool returns —
+ * the bytes only ever ride the live wire copy of that one turn. That policy
+ * is right (megabytes of base64 in the persisted window would be sliced,
+ * compressed, and replayed forever), but it left `save_recent_image` with no
+ * way to reach an image the resident had just seen: the scanner walked past
+ * the byteless placeholder and quietly saved whichever OLDER attachment came
+ * next, under the filename the resident chose for the new one.
+ *
+ * This ledger is the missing half. At ingestion every tool-result image is
+ * retained here under a stable per-agent ref (`img_k7x3q2_7`) bound to the
+ * exact tool call and block it came from, with its digest. The ref carries a
+ * per-ledger nonce: ledgers live and die with the process, but the persisted
+ * store keeps yesterday's placeholders visible in context, so a bare sequence
+ * number would let a stale `img_7` resolve to whatever this process minted
+ * seventh. A stale ref must resolve `unknown`, never to other bytes.
+ *
+ * The history placeholder carries the ref, so the ordered inventory
+ * `save_recent_image` walks can
+ * include tool images at their true position — and when the bytes behind a
+ * ref are gone (bounded eviction, or a restart: the ledger is in-memory by
+ * design, so it never adds to blob growth), the save fails AT THAT INDEX with
+ * a specific error instead of sliding to an older image. Silent substitution
+ * of bytes from another surface is the failure this exists to end.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { safeSlice } from './safe-slice.js';
+/** 96 MB of base64 ≈ 72 MB of image bytes — a few dozen world snapshots. */
+export const DEFAULT_TOOL_IMAGE_LEDGER_MAX_CHARS = 96 * 1024 * 1024;
+export const DEFAULT_TOOL_IMAGE_LEDGER_MAX_ENTRIES = 64;
+export class ToolImageLedger {
+    /** Namespace for every ref this ledger mints; a fresh ledger (new process,
+     *  agent re-registration) never shares one with its predecessors. */
+    nonce = mintLedgerNonce();
+    nextSeq = 1;
+    /** Insertion-ordered (oldest first) — eviction pops from the front. */
+    retained = new Map();
+    /** Provenance for every ref ever issued, bytes or not (bounded separately). */
+    issued = new Map();
+    refByKey = new Map();
+    heldChars = 0;
+    maxChars;
+    maxEntries;
+    constructor(options = {}) {
+        this.maxChars = options.maxChars ?? DEFAULT_TOOL_IMAGE_LEDGER_MAX_CHARS;
+        this.maxEntries = options.maxEntries ?? DEFAULT_TOOL_IMAGE_LEDGER_MAX_ENTRIES;
+    }
+    /**
+     * Retain one image block from a tool result. Idempotent per
+     * (toolCallId, blockIndex) for as long as that block's provenance record
+     * is held (bounded — see trimProvenance): within that window the same
+     * block always yields the same ref, so a result serialized twice (or
+     * retained early in a tool batch, then serialized at commit) agrees with
+     * itself. A block re-serialized after its record aged out mints a fresh
+     * ref; the old one resolves `evicted`/`unknown`, never to other bytes.
+     */
+    retain(source) {
+        const key = `${source.toolCallId}:${source.blockIndex}`;
+        const existingRef = this.refByKey.get(key);
+        if (existingRef !== undefined) {
+            const known = this.issued.get(existingRef);
+            if (known)
+                return known;
+        }
+        const ref = `img_${this.nonce}_${this.nextSeq++}`;
+        // Digest without materializing the whole decoded image: a 96MB base64
+        // field would otherwise transiently allocate ~72MB more and the ledger
+        // would be the one asking for it. Chunked decode keeps the peak small.
+        const { byteSize, sha256 } = digestBase64(source.data);
+        const image = {
+            ref,
+            toolCallId: source.toolCallId,
+            toolName: source.toolName,
+            blockIndex: source.blockIndex,
+            // Tools send mime types unvalidated; the placeholder grammar is
+            // lowercase, so normalize here and at format time (same rule) or an
+            // `Image/PNG` would write a placeholder that never re-parses — an
+            // invisible slot, i.e. a silent index slide.
+            mediaType: normalizeMediaType(source.mediaType),
+            byteSize,
+            sha256,
+            retainedAt: Date.now(),
+            data: source.data,
+        };
+        const { data: _data, ...provenance } = image;
+        this.refByKey.set(key, ref);
+        this.issued.set(ref, provenance);
+        // A single image over the whole budget is issued (so the placeholder is
+        // honest about its provenance) but never held.
+        if (source.data.length <= this.maxChars) {
+            this.retained.set(ref, image);
+            this.heldChars += source.data.length;
+            this.evictOverBudget();
+        }
+        this.trimProvenance();
+        return provenance;
+    }
+    lookup(ref) {
+        const held = this.retained.get(ref);
+        if (held)
+            return { status: 'retained', image: held };
+        const known = this.issued.get(ref);
+        if (known)
+            return { status: 'evicted', image: known };
+        return { status: 'unknown' };
+    }
+    /** Ref already minted for this block, if any (no retention side effect). */
+    refFor(toolCallId, blockIndex) {
+        return this.refByKey.get(`${toolCallId}:${blockIndex}`);
+    }
+    /** Count of images whose bytes are currently held. */
+    get size() {
+        return this.retained.size;
+    }
+    evictOverBudget() {
+        for (const [ref, image] of this.retained) {
+            if (this.retained.size <= this.maxEntries && this.heldChars <= this.maxChars)
+                break;
+            this.retained.delete(ref);
+            this.heldChars -= image.data.length;
+        }
+    }
+    /** Provenance for evicted refs is kept for a while so the error can name
+     *  the tool call; bounded so a long-lived agent can't grow it forever. */
+    trimProvenance() {
+        const keep = Math.max(this.maxEntries * 4, 256);
+        while (this.issued.size > keep) {
+            const oldest = this.issued.keys().next().value;
+            if (oldest === undefined)
+                break;
+            const image = this.issued.get(oldest);
+            this.issued.delete(oldest);
+            if (image)
+                this.refByKey.delete(`${image.toolCallId}:${image.blockIndex}`);
+        }
+    }
+}
+/** Six random base36 chars — one per ledger lifetime, embedded in every ref. */
+function mintLedgerNonce() {
+    return randomBytes(4).readUInt32BE(0).toString(36).padStart(6, '0').slice(-6);
+}
+/** Grammar of a ref this module mints: `img_<ledger nonce>_<sequence>`. */
+export const TOOL_IMAGE_REF_RE = /^img_[0-9a-z]+_\d+$/;
+/** RFC 6838 type/subtype token characters (lowercased); no parameters. */
+const MEDIA_TYPE_ESSENCE_RE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/;
+export const FALLBACK_MEDIA_TYPE = 'application/octet-stream';
+/**
+ * The one spelling the placeholder grammar accepts: trimmed, lowercased, the
+ * `type/subtype` essence only (parameters such as `; charset=binary` are
+ * dropped), and — because `mimeType` arrives from external MCPL servers
+ * unvalidated — anything that still is not a well-formed type/subtype falls
+ * back to `application/octet-stream`. The invariant this buys: the
+ * serializer can NEVER write a placeholder that does not re-parse, so a
+ * strange mime can never produce an invisible slot (a silent index slide).
+ */
+export function normalizeMediaType(mediaType) {
+    const essence = mediaType.split(';', 1)[0].trim().toLowerCase();
+    return MEDIA_TYPE_ESSENCE_RE.test(essence) ? essence : FALLBACK_MEDIA_TYPE;
+}
+/** History placeholder for a retained tool image: `[image: image/png, ~691KB, ref img_7]`. */
+export function formatToolImagePlaceholder(mediaType, sizeLabel, ref) {
+    const mime = normalizeMediaType(mediaType);
+    return ref === null
+        ? `[image: ${mime}, ${sizeLabel}]`
+        : `[image: ${mime}, ${sizeLabel}, ref ${ref}]`;
+}
+const PLACEHOLDER_RE = /\[image: ([a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+), (~?[\d.]+(?:B|KB|MB))(?:, ref (img_[0-9a-z]+_\d+))?\]/g;
+/** `[ref_1_ab3d] cam.png — image/png, 1.2MB claimed — from tool result — …` (one line). */
+const REFERENCE_STUB_RE = /^\[(ref_[0-9a-z]+_[0-9a-z]+)\] ([^\n]*)$/gm;
+const IMAGE_MIME_RE = /\bimage\/[a-z0-9!#$&^_.+-]+/i;
+/**
+ * Every image slot in a stored tool-result string, in text order: inline
+ * placeholders and image-typed reference stubs. Text-derived and therefore
+ * untrusted — a tool result can quote someone else's placeholder verbatim —
+ * so the caller MUST cross-check a resolved ref's provenance against the
+ * tool_result block it was found in before handing out bytes.
+ */
+export function parseImagePlaceholders(text) {
+    const out = [];
+    for (const m of text.matchAll(PLACEHOLDER_RE)) {
+        out.push({ kind: 'inline', mediaType: m[1], sizeLabel: m[2], ref: m[3] ?? null, offset: m.index ?? 0, text: m[0] });
+    }
+    for (const m of text.matchAll(REFERENCE_STUB_RE)) {
+        const mime = m[2].match(IMAGE_MIME_RE);
+        out.push({ kind: 'reference', refId: m[1], mediaType: mime ? mime[0].toLowerCase() : null, offset: m.index ?? 0, text: m[0] });
+    }
+    out.sort((a, b) => a.offset - b.offset);
+    return out;
+}
+/**
+ * Cut `text` to at most `cap` chars WITHOUT losing or splitting an image
+ * slot. The stored tool_result text is the only place the inventory
+ * discovers tool images, while the live wire still delivers every image
+ * regardless of text length — so a slot dropped by truncation is an image
+ * the resident saw that the index silently slides past (the #104 failure,
+ * one representation over). Returns the head to keep and the slots that
+ * fell at or past the cut, to be re-appended verbatim after the truncation
+ * notice. A slot straddling the cut moves the cut back to its start, so the
+ * head never contains a partial slot (a partial reference-stub line would
+ * otherwise still re-parse and be counted twice).
+ */
+export function splitPreservingImageSlots(text, cap) {
+    const slots = parseImagePlaceholders(text);
+    let cutAt = cap;
+    for (const slot of slots) {
+        if (slot.offset < cutAt && slot.offset + slot.text.length > cutAt)
+            cutAt = slot.offset;
+    }
+    return {
+        head: safeSlice(text, 0, cutAt),
+        tail: slots.filter((slot) => slot.offset >= cutAt).map((slot) => slot.text),
+    };
+}
+/** Text to append after a truncation notice so the preserved slots stay
+ *  parseable (each reference stub on its own line). Empty when none. */
+export function formatPreservedImageSlots(tail) {
+    if (tail.length === 0)
+        return '';
+    return `\n[${tail.length} image slot(s) fell past the cut; kept here in order so save_recent_image still counts them:]\n`
+        + tail.join('\n');
+}
+export function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** Only the base64 alphabet, with nothing but trailing `=` padding after it. */
+function isCleanBase64(data) {
+    const m = /[^A-Za-z0-9+/]/.exec(data);
+    if (!m)
+        return true;
+    const rest = data.length - m.index;
+    return rest <= 2 && /^=+$/.test(data.slice(m.index));
+}
+/**
+ * Byte length and SHA-256 of a base64 payload, decoded in 4-char-aligned
+ * chunks so the peak allocation stays at one chunk rather than the whole
+ * image. Falls back to a whole decode when the string carries whitespace
+ * or embedded padding (chunk alignment would no longer be trustworthy) —
+ * the digest must describe exactly the bytes a later whole decode writes.
+ */
+function digestBase64(data) {
+    if (!isCleanBase64(data)) {
+        const bytes = Buffer.from(data, 'base64');
+        return { byteSize: bytes.byteLength, sha256: sha256Hex(bytes) };
+    }
+    const CHUNK = 1 << 20; // multiple of 4
+    const hash = createHash('sha256');
+    let byteSize = 0;
+    for (let i = 0; i < data.length; i += CHUNK) {
+        const bytes = Buffer.from(data.slice(i, i + CHUNK), 'base64');
+        hash.update(bytes);
+        byteSize += bytes.byteLength;
+    }
+    return { byteSize, sha256: hash.digest('hex') };
+}
+//# sourceMappingURL=tool-image-ledger.js.map

package/dist/src/tool-image-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-image-ledger.js","sourceRoot":"","sources":["../../src/tool-image-ledger.ts"],"names":[],"mappings":"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"}

package/dist/src/tool-result-history.d.ts

@@ -13,6 +13,18 @@
  * replaces image blocks with a short `[image: mimeType, ~NKB]` placeholder.
  * For anything else it falls back to JSON.
  */
+export interface HistorySerializeOptions {
+    /**
+     * Called for every image block the serializer replaces with a placeholder
+     * (issue #104). Returns the retention ref to embed in the placeholder —
+     * `[image: image/png, ~691KB, ref img_7]` — so the image keeps a saveable
+     * handle in history; null leaves the legacy ref-less form.
+     */
+    imageRef?: (blockIndex: number, image: {
+        data: string;
+        mimeType: string;
+    }) => string | null;
+}
 /**
  * House-safe default inline cap (chars) for tool results, error results, and
  * background-script wake payloads (issue #89: a resident should never eat a
@@ -31,7 +43,8 @@
  * broad greps) still spill, which is the point.
  */
 export declare const DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS = 24000;
-export declare function toolResultDataToHistoryString(data: unknown, maxChars?: number): string;
-/** Bounded copy of an arbitrary string with the standard truncation notice. */
+export declare function toolResultDataToHistoryString(data: unknown, maxChars?: number, options?: HistorySerializeOptions): string;
+/** Bounded copy of an arbitrary string with the standard truncation notice.
+ *  Image slots past the cut are re-appended, never dropped (issue #104). */
 export declare function truncateForHistory(str: string, maxChars: number): string;
 //# sourceMappingURL=tool-result-history.d.ts.map

package/dist/src/tool-result-history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-result-history.d.ts","sourceRoot":"","sources":["../../src/tool-result-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oCAAoC,QAAQ,CAAC;AAE1D,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAItF;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIxE"}
+{"version":3,"file":"tool-result-history.d.ts","sourceRoot":"","sources":["../../src/tool-result-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,GAAG,IAAI,CAAC;CAC7F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oCAAoC,QAAQ,CAAC;AAE1D,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,OAAO,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAIR;AAED;4EAC4E;AAC5E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMxE"}

package/dist/src/tool-result-history.js

@@ -13,8 +13,8 @@
  * replaces image blocks with a short `[image: mimeType, ~NKB]` placeholder.
  * For anything else it falls back to JSON.
  */
-import { safeSlice } from './safe-slice.js';
 import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './mcpl/references.js';
+import { formatPreservedImageSlots, formatToolImagePlaceholder, splitPreservingImageSlots } from './tool-image-ledger.js';
 /**
  * House-safe default inline cap (chars) for tool results, error results, and
  * background-script wake payloads (issue #89: a resident should never eat a
@@ -33,28 +33,31 @@ import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from
  * broad greps) still spill, which is the point.
  */
 export const DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS = 24000;
-export function toolResultDataToHistoryString(data, maxChars) {
-    const fromArray = tryHistoryStringFromContentArray(data);
+export function toolResultDataToHistoryString(data, maxChars, options) {
+    const fromArray = tryHistoryStringFromContentArray(data, options);
     const str = fromArray ?? JSON.stringify(data);
     return maxChars ? truncateForHistory(str, maxChars) : str;
 }
-/** Bounded copy of an arbitrary string with the standard truncation notice. */
+/** Bounded copy of an arbitrary string with the standard truncation notice.
+ *  Image slots past the cut are re-appended, never dropped (issue #104). */
 export function truncateForHistory(str, maxChars) {
     if (str.length <= maxChars)
         return str;
-    return safeSlice(str, 0, maxChars)
-        + '\n\n[truncated — original was ' + str.length + ' chars]';
+    const { head, tail } = splitPreservingImageSlots(str, maxChars);
+    return head
+        + '\n\n[truncated — original was ' + str.length + ' chars]'
+        + formatPreservedImageSlots(tail);
 }
 /**
  * If `data` is an MCP content array whose every block has a shape we
  * recognize, return a history-safe string (images → placeholders). Otherwise
  * return `null` to defer to the caller's fallback (JSON, usually).
  */
-function tryHistoryStringFromContentArray(data) {
+function tryHistoryStringFromContentArray(data, options) {
     if (!Array.isArray(data))
         return null;
     const parts = [];
-    for (const raw of data) {
+    for (const [blockIndex, raw] of data.entries()) {
         if (!raw || typeof raw !== 'object')
             return null;
         const b = raw;
@@ -69,11 +72,15 @@ function tryHistoryStringFromContentArray(data) {
         else if (b.type === 'image' && typeof b.data === 'string' && typeof b.mimeType === 'string') {
             // Decoded byte estimate from base64 length (3/4 ratio, rounded).
             const approxBytes = Math.floor(b.data.length * 3 / 4);
-            parts.push(`[image: ${b.mimeType}, ${formatSize(approxBytes)}]`);
+            const ref = options?.imageRef?.(blockIndex, { data: b.data, mimeType: b.mimeType }) ?? null;
+            parts.push(formatToolImagePlaceholder(b.mimeType, formatSize(approxBytes), ref));
         }
         else if (b.type === 'resource' || ((b.type === 'image' || b.type === 'audio') && typeof b.uri === 'string')) {
             // RFC-005 reference block: a bounded stub, never the raw block JSON
             // (which used to inline the URI — and the whole array — into history).
+            // Image-typed stubs still occupy a slot in save_recent_image's
+            // inventory (a failing one — bytes live behind fetch_reference), so
+            // the index never slides past an image the resident saw.
             const stub = referenceStubOrNull(b, 'from tool result');
             if (stub === null)
                 return null;

package/dist/src/tool-result-history.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-result-history.js","sourceRoot":"","sources":["../../src/tool-result-history.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-result-history.js","sourceRoot":"","sources":["../../src/tool-result-history.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,8 @@
+import type { ContentBlock } from '@animalabs/membrane';
+/**
+ * Recognize ONLY a whole-response textual invocation wrapper for a tool that
+ * was registered on this exact inference. This is containment, not parsing:
+ * callers must never execute the returned tool name or wrapper body.
+ */
+export declare function detectKnownToolWrapperProse(content: ContentBlock[], knownToolNames: ReadonlySet<string>): string | null;
+//# sourceMappingURL=tool-wrapper-prose-guard.d.ts.map

package/dist/src/tool-wrapper-prose-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-wrapper-prose-guard.d.ts","sourceRoot":"","sources":["../../src/tool-wrapper-prose-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC,MAAM,GAAG,IAAI,CA2Bf"}

package/dist/src/tool-wrapper-prose-guard.js

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

package/dist/src/tool-wrapper-prose-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-wrapper-prose-guard.js","sourceRoot":"","sources":["../../src/tool-wrapper-prose-guard.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAuB,EACvB,cAAmC;IAEnC,IAAI,cAAc,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3C,4EAA4E;IAC5E,uDAAuD;IACvD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;aAC5C,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB;YAAE,OAAO,IAAI,CAAC;IACxF,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,OAAO,GAAG,2BAA2B,CAAC;IAC5C,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC,CAAC;IAC5D,IAAI,KAAK,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAE,CAAC;IAE7D,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,OAAO,iCAAiC,CAAC,CAAC,CAAC;IAC/E,IAAI,KAAK,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAE,CAAC;IAE7D,6DAA6D;IAC7D,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,kFAAkF,CAAC,CAAC;IACvG,IAAI,KAAK,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAE,CAAC;IAC7D,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,qGAAqG,CAAC,CAAC;IAC1H,IAAI,KAAK,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAE,CAAC;IAE7D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/tune-out/coordinator.d.ts

@@ -0,0 +1,144 @@
+/**
+ * TuneOutCoordinator (issue #77) — the host-side machinery between a
+ * tuned-out channel and the subconscious resident.
+ *
+ * Responsibilities: classify diverted traffic (stamp everything, wake on
+ * addressed), acknowledge suppressed mentions deterministically, run the
+ * per-channel summary cadence, count wakes durably with max-wakes
+ * auto-cancel, and deliver the cancel dump.
+ *
+ * Voice doctrine ("no words in models' mouths"): everything the resident
+ * reads from the subconscious is the subconscious's verbatim text under its
+ * own participant name. Host-authored framing is system-styled and never
+ * voiced: `<tuned-out-backlog …>` wraps raw diverted messages (the
+ * <backscroll> precedent), and `[Tune-out: …]` bracket notices carry
+ * lifecycle facts (the [Gate: …] precedent).
+ */
+import type { ContentBlock } from '@animalabs/membrane';
+import type { StoredMessage } from '@animalabs/context-manager';
+import type { ChannelRegistry, TuneOutParams } from '../mcpl/channel-registry.js';
+import type { McplServerRegistry } from '../mcpl/server-registry.js';
+/** Defaults for tune_out tool params. */
+export declare const TUNE_OUT_DEFAULTS: {
+    readonly cadenceSeconds: 1800;
+    readonly backlogCap: 200;
+    readonly maxWakes: 5;
+};
+export interface TuneOutFrameworkHooks {
+    /** Deliver a message into an agent's window (per-agent seam). */
+    addMessage: (participant: string, content: ContentBlock[], metadata?: Record<string, unknown>, forAgent?: string) => string;
+    /** Queue an inference request for an agent. */
+    requestInference: (agentName: string, reason: string, source: string) => void;
+    /** The subconscious's registry/participant name. */
+    subconsciousName: () => string | null;
+    /** The primary resident's registry name. */
+    primaryName: () => string | null;
+    /** Read the primary's stored messages (shared slot, unfiltered). */
+    getStoredMessages: () => StoredMessage[];
+    /** Current chronicle head sequence (window anchor for new epochs). */
+    currentSequence: () => number;
+    /** Move the subconscious window anchor (never forward past active epochs). */
+    setSubconsciousAnchor: (sequence: number) => void;
+    /** True when a channel is bound to a conversation-fork agent. */
+    isForkBound: (channelId: string) => boolean;
+    /** Gate privileged-users list (#77: privileged authors wake, like mentions). */
+    isPrivilegedAuthor: (authorId: string | null | undefined) => boolean;
+    /** speak_in_channel master switch (recipe-side, canary-gated). */
+    allowChannelSpeech: () => boolean;
+    emitTrace: (event: {
+        type: string;
+        [key: string]: unknown;
+    }) => void;
+}
+export declare class TuneOutCoordinator {
+    private readonly channelRegistry;
+    private readonly serverRegistry;
+    private readonly hooks;
+    private cadenceTimers;
+    /** Duration-expiry timers (params.expiresAtMs); cleared on any cancel. */
+    private expiryTimers;
+    /** Channels with a wake invocation pending inside the coalescing window. */
+    private pendingWakes;
+    /** Diverted-message tallies since the last subconscious invocation, per channel key. */
+    private divertedSinceInvocation;
+    constructor(channelRegistry: ChannelRegistry, serverRegistry: McplServerRegistry, hooks: TuneOutFrameworkHooks);
+    private key;
+    /** Restart cadence + expiry timers and re-anchor after a process restart. */
+    resumeActiveEpochs(): void;
+    private armExpiry;
+    private listActive;
+    enter(serverId: string, channelId: string, opts: {
+        cadenceSeconds?: number;
+        backlogCap?: number;
+        maxWakes?: number;
+        durationSeconds?: number;
+    }, source: string): {
+        ok: true;
+        params: TuneOutParams;
+    } | {
+        ok: false;
+        error: string;
+    };
+    /**
+     * End a tune-out: durable flip, system-framed backlog dump into the
+     * resident's window (capped), lifecycle notice, one wake for the
+     * resident. `subconsciousNote` is the subconscious's own text (from its
+     * cancel_tuneout call) — delivered verbatim under its name, never
+     * synthesized here.
+     */
+    cancel(serverId: string, channelId: string, source: string, reason: string, subconsciousNote?: string): {
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    };
+    /**
+     * Consulted by the framework for every incoming channel message BEFORE
+     * storage. Null = channel not tuned out (proceed normally). Otherwise the
+     * caller stamps `metadata.tuneOut = { epochId }`, stores the message
+     * without waking the residents, and this coordinator has already handled
+     * wake bookkeeping (coalesced subconscious invocation, durable count,
+     * suppression ack, possible auto-cancel).
+     */
+    onIncoming(serverId: string, channelId: string, messageId: string, tags: string[] | undefined, authorId?: string, gatePass?: boolean): {
+        epochId: string;
+    } | null;
+    private acknowledgeSuppressed;
+    private startCadence;
+    private stopCadence;
+    private scheduleWakeInvocation;
+    /**
+     * One subconscious turn: a system-framed trigger notice (bracket style —
+     * what happened, never what to say) plus standing dispositions, then an
+     * inference request. The merged view supplies the actual traffic.
+     */
+    private invokeSubconscious;
+    private dispositionsCache;
+    private get dispositionsStateId();
+    /**
+     * The dispositions as a fixed system-position ContextInjection for the
+     * subconscious's compiles (antra: deliver changes, never let them wash
+     * away — it has no long-term memory, so they must not live in window
+     * content). Bytes change only when a disposition changes: KV-friendly.
+     */
+    getDispositionsInjection(): {
+        namespace: string;
+        position: 'system';
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    } | null;
+    private readDispositions;
+    noteDisposition(key: string, text: string): void;
+    handleSubconsciousTool(name: string, input: Record<string, unknown>): Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: string;
+        isError?: boolean;
+    }>;
+    private findByChannel;
+    /** Stop all timers (framework shutdown). */
+    stop(): void;
+}
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/src/tune-out/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/tune-out/coordinator.ts"],"names":[],"mappings":"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"}