@animalabs/agent-framework 0.13.0 → 0.15.0

package/dist/src/tool-image-ledger.d.ts

@@ -0,0 +1,175 @@
+/**
+ * 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.
+ */
+export interface RetainedToolImage {
+    /** Stable per-ledger handle (`img_<nonce>_<seq>`), minted once per (toolCallId, blockIndex). */
+    ref: string;
+    toolCallId: string;
+    toolName: string;
+    /** Position of the image block inside the tool result's content array. */
+    blockIndex: number;
+    mediaType: string;
+    byteSize: number;
+    sha256: string;
+    retainedAt: number;
+}
+/** A retained image whose bytes are still held. */
+export interface RetainedToolImageWithData extends RetainedToolImage {
+    /** Base64 payload, exactly as the tool returned it. */
+    data: string;
+}
+export type ToolImageLookup = {
+    status: 'retained';
+    image: RetainedToolImageWithData;
+}
+/** The ref was issued by this ledger but its bytes were evicted (bounded budget). */
+ | {
+    status: 'evicted';
+    image: RetainedToolImage;
+}
+/** Never issued by this ledger — a typo, or a ref minted before a restart. */
+ | {
+    status: 'unknown';
+};
+export interface ToolImageLedgerOptions {
+    /** Total base64 chars held across retained images (≈ bytes × 4/3). */
+    maxChars?: number;
+    /** Maximum number of images whose bytes are held. */
+    maxEntries?: number;
+}
+/** 96 MB of base64 ≈ 72 MB of image bytes — a few dozen world snapshots. */
+export declare const DEFAULT_TOOL_IMAGE_LEDGER_MAX_CHARS: number;
+export declare const DEFAULT_TOOL_IMAGE_LEDGER_MAX_ENTRIES = 64;
+export declare class ToolImageLedger {
+    /** Namespace for every ref this ledger mints; a fresh ledger (new process,
+     *  agent re-registration) never shares one with its predecessors. */
+    readonly nonce: string;
+    private nextSeq;
+    /** Insertion-ordered (oldest first) — eviction pops from the front. */
+    private readonly retained;
+    /** Provenance for every ref ever issued, bytes or not (bounded separately). */
+    private readonly issued;
+    private readonly refByKey;
+    private heldChars;
+    private readonly maxChars;
+    private readonly maxEntries;
+    constructor(options?: ToolImageLedgerOptions);
+    /**
+     * 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: {
+        toolCallId: string;
+        toolName: string;
+        blockIndex: number;
+        data: string;
+        mediaType: string;
+    }): RetainedToolImage;
+    lookup(ref: string): ToolImageLookup;
+    /** Ref already minted for this block, if any (no retention side effect). */
+    refFor(toolCallId: string, blockIndex: number): string | undefined;
+    /** Count of images whose bytes are currently held. */
+    get size(): number;
+    private evictOverBudget;
+    /** 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. */
+    private trimProvenance;
+}
+/** Grammar of a ref this module mints: `img_<ledger nonce>_<sequence>`. */
+export declare const TOOL_IMAGE_REF_RE: RegExp;
+export declare 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 declare function normalizeMediaType(mediaType: string): string;
+/** History placeholder for a retained tool image: `[image: image/png, ~691KB, ref img_7]`. */
+export declare function formatToolImagePlaceholder(mediaType: string, sizeLabel: string, ref: string | null): string;
+export type ParsedImagePlaceholder = 
+/** An inline tool image the serializer replaced with a placeholder. */
+{
+    kind: 'inline';
+    mediaType: string;
+    sizeLabel: string;
+    /** null for placeholders written before retention existed (unsaveable). */
+    ref: string | null;
+    /** Character offset in the scanned text — for ordering within a block. */
+    offset: number;
+    /** The placeholder exactly as it appears in the text. */
+    text: string;
+}
+/** An RFC-005 reference stub whose testimony says image — bytes live
+ *  behind fetch_reference, never in this ledger. Occupies a slot so the
+ *  index cannot slide past it. */
+ | {
+    kind: 'reference';
+    refId: string;
+    /** Mime sniffed from the stub text; null when the stub names none. */
+    mediaType: string | null;
+    offset: number;
+    /** The stub line exactly as it appears in the text. */
+    text: string;
+};
+/**
+ * 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 declare function parseImagePlaceholders(text: string): ParsedImagePlaceholder[];
+/**
+ * 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 declare function splitPreservingImageSlots(text: string, cap: number): {
+    head: string;
+    tail: string[];
+};
+/** Text to append after a truncation notice so the preserved slots stay
+ *  parseable (each reference stub on its own line). Empty when none. */
+export declare function formatPreservedImageSlots(tail: string[]): string;
+export declare function sha256Hex(bytes: Buffer): string;
+//# sourceMappingURL=tool-image-ledger.d.ts.map

package/dist/src/tool-image-ledger.d.ts.map

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

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/types/agent.d.ts

@@ -309,5 +309,15 @@ export interface InferenceRequest {
      * so a household ledger can say who woke whom; carries no content.
      */
     counterparty?: string;
+    /**
+     * Where the wake came from, for telemetry ONLY — never a speech locus.
+     * Set by the EventGate for batched wakes (composite channel id of the
+     * chosen event when the event carried one; push-event raw ids are not
+     * used). Routing keeps reading `channelId`, which only the direct channel
+     * paths set from normalized ids — a gate wake leaves it unset, as before.
+     */
+    wakeChannelId?: string;
+    /** Timestamp of the event the wake provenance was taken from (ms). */
+    wakeAt?: number;
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/src/types/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/types/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEpE,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC5D,MAAM,MAAM,8BAA8B,GACtC,kBAAkB,GAClB,QAAQ,GACR,uBAAuB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IAEb,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IAEd,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IAErB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAE3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,CAAC;IAEhC;;;;OAIG;IACH,cAAc,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,CAAC;IAElC,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;0EACsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;4DACwD;IACxD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;+CAC2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,EAAE;QACT,OAAO,EAAE,OAAO,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,yEAAyE;QACzE,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;QAC9B;;;;WAIG;QACH,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;KACpC,CAAC;IACF;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE;QAChB;;;;;;;;;;;;;;;;;;;;;;;WAuBG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,2EAA2E;QAC3E,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,kEAAkE;QAClE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB;;;;WAIG;QACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,CAAC;IAEF;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;IAE5D;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IACpD;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wBAAwB,EAAE,wBAAwB,CAAC;IACnD,8BAA8B,EAAE,8BAA8B,CAAC;IAC/D,UAAU,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;IAChD,gBAAgB,CAAC,EAAE,2BAA2B,GAAG,kCAAkC,CAAC;CACrF;AAED,iFAAiF;AACjF,MAAM,MAAM,6BAA6B,GAAG,yBAAyB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,uDAAuD;IACvD,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,uCAAuC;IACvC,GAAG,CAAC,EAAE;QACJ,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,kBAAkB;IAClB,KAAK,CAAC,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAAC,eAAe,EAAE,eAAe,CAAA;CAAE,GAC5F;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;IAAC,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,cAAc,CAAA;CAAE,GACnI;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,UAAU,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,UAAU,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/types/agent.ts"],"names":[],"mappings":"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"}

package/dist/src/types/trace.d.ts

@@ -293,6 +293,10 @@ export type TraceEvent = (TraceEventBase & {
     toolUseId: string;
     isError: boolean;
     durationMs: number;
+    /** The pair was queued behind a turn that replaced the puppet's
+     *  reservation (provider-admission re-entry) instead of stored
+     *  directly; it lands at that turn's end flush. */
+    deferred?: boolean;
 }) | (TraceEventBase & {
     type: 'mcpl:server-connect-failed';
     serverId: string;