@ai-agent-forge/agent-forge 0.85.0

package/dist/core/extensions/lifecycle-delivery-queue.js

@@ -0,0 +1,164 @@
+export class LifecycleDeliveryQueueOverflowError extends Error {
+    code;
+    maxPendingEvents;
+    maxPendingBytes;
+    pendingEvents;
+    pendingBytes;
+    attemptedBytes;
+    constructor(code, maxPendingEvents, maxPendingBytes, pendingEvents, pendingBytes, attemptedBytes) {
+        super(`Lifecycle delivery queue overflow: pending events ${pendingEvents + 1} exceeds ${maxPendingEvents}` +
+            (maxPendingBytes === undefined
+                ? ""
+                : ` or pending bytes ${pendingBytes + attemptedBytes} exceeds ${maxPendingBytes}`));
+        this.name = "LifecycleDeliveryQueueOverflowError";
+        this.code = code;
+        this.maxPendingEvents = maxPendingEvents;
+        this.maxPendingBytes = maxPendingBytes;
+        this.pendingEvents = pendingEvents;
+        this.pendingBytes = pendingBytes;
+        this.attemptedBytes = attemptedBytes;
+    }
+}
+export class LifecycleDeliveryQueueClosedError extends Error {
+    code = "lifecycle_delivery_closed";
+    constructor() {
+        super("Lifecycle delivery queue is closed");
+        this.name = "LifecycleDeliveryQueueClosedError";
+    }
+}
+function assertPositiveSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`Lifecycle delivery queue ${label} must be a positive safe integer`);
+    }
+}
+/**
+ * Overflow terminates only this subscription's acceptance path. Values already
+ * accepted remain FIFO and handler failures do not alter source lifecycle
+ * facts. A closed queue rejects pending values; an overflowed queue rejects
+ * further values with the original overflow code so telemetry keeps one stable
+ * backpressure classification. Callers must attach a handler to every enqueue
+ * promise immediately: close() and overflow reject those promises.
+ */
+export function createLifecycleDeliveryQueue(options) {
+    assertPositiveSafeInteger(options.maxPendingEvents, "maxPendingEvents");
+    if (options.maxPendingBytes !== undefined)
+        assertPositiveSafeInteger(options.maxPendingBytes, "maxPendingBytes");
+    if (typeof options.overflowCode !== "string" || !options.overflowCode.trim()) {
+        throw new Error("Lifecycle delivery queue overflowCode must be non-empty");
+    }
+    const entries = [];
+    let status = "active";
+    let pendingEvents = 0;
+    let pendingBytes = 0;
+    let accepted = 0;
+    let delivered = 0;
+    let rejected = 0;
+    let processing = false;
+    let drainPromise;
+    let resolveDrain;
+    const ensureDrainPromise = () => {
+        if (drainPromise === undefined) {
+            drainPromise = new Promise((resolve) => {
+                resolveDrain = resolve;
+            });
+        }
+        return drainPromise;
+    };
+    const settleDrainIfIdle = () => {
+        if (processing || entries.length > 0)
+            return;
+        resolveDrain?.();
+        drainPromise = undefined;
+        resolveDrain = undefined;
+    };
+    const pump = async () => {
+        if (processing)
+            return;
+        processing = true;
+        try {
+            while (entries.length > 0) {
+                const entry = entries.shift();
+                if (entry === undefined)
+                    continue;
+                try {
+                    await options.deliver(entry.value);
+                    delivered += 1;
+                    entry.resolve();
+                }
+                catch (error) {
+                    rejected += 1;
+                    entry.reject(error);
+                }
+                finally {
+                    pendingEvents -= 1;
+                    pendingBytes -= entry.bytes;
+                }
+            }
+        }
+        finally {
+            processing = false;
+            settleDrainIfIdle();
+        }
+    };
+    return {
+        enqueue(value) {
+            if (status === "overflowed") {
+                rejected += 1;
+                return Promise.reject(new LifecycleDeliveryQueueOverflowError(options.overflowCode, options.maxPendingEvents, options.maxPendingBytes, pendingEvents, pendingBytes, 0));
+            }
+            if (status === "closed") {
+                rejected += 1;
+                return Promise.reject(new LifecycleDeliveryQueueClosedError());
+            }
+            const bytes = options.measureBytes(value);
+            assertPositiveSafeInteger(bytes, "measureBytes result");
+            if (pendingEvents + 1 > options.maxPendingEvents ||
+                (options.maxPendingBytes !== undefined && pendingBytes + bytes > options.maxPendingBytes)) {
+                status = "overflowed";
+                rejected += 1;
+                return Promise.reject(new LifecycleDeliveryQueueOverflowError(options.overflowCode, options.maxPendingEvents, options.maxPendingBytes, pendingEvents, pendingBytes, bytes));
+            }
+            accepted += 1;
+            pendingEvents += 1;
+            pendingBytes += bytes;
+            const result = new Promise((resolve, reject) => {
+                entries.push({ value, bytes, resolve, reject });
+            });
+            ensureDrainPromise();
+            void pump();
+            return result;
+        },
+        drain() {
+            if (!processing && entries.length === 0)
+                return Promise.resolve();
+            return ensureDrainPromise();
+        },
+        close() {
+            if (status === "closed")
+                return;
+            status = "closed";
+            const error = new LifecycleDeliveryQueueClosedError();
+            while (entries.length > 0) {
+                const entry = entries.shift();
+                if (entry === undefined)
+                    continue;
+                pendingEvents -= 1;
+                pendingBytes -= entry.bytes;
+                rejected += 1;
+                entry.reject(error);
+            }
+            settleDrainIfIdle();
+        },
+        snapshot: () => Object.freeze({
+            status,
+            maxPendingEvents: options.maxPendingEvents,
+            ...(options.maxPendingBytes === undefined ? {} : { maxPendingBytes: options.maxPendingBytes }),
+            pendingEvents,
+            pendingBytes,
+            accepted,
+            delivered,
+            rejected,
+        }),
+    };
+}
+//# sourceMappingURL=lifecycle-delivery-queue.js.map

package/dist/core/extensions/lifecycle-delivery-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-delivery-queue.js","sourceRoot":"","sources":["../../../src/core/extensions/lifecycle-delivery-queue.ts"],"names":[],"mappings":"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","sourcesContent":["/** Internal FIFO queue for an explicitly buffered lifecycle subscription. */\nexport type LifecycleDeliveryQueueStatus = \"active\" | \"overflowed\" | \"closed\";\n\nexport interface LifecycleDeliveryQueueSnapshot {\n\treadonly status: LifecycleDeliveryQueueStatus;\n\treadonly maxPendingEvents: number;\n\treadonly maxPendingBytes?: number;\n\treadonly pendingEvents: number;\n\treadonly pendingBytes: number;\n\treadonly accepted: number;\n\treadonly delivered: number;\n\treadonly rejected: number;\n}\n\nexport interface LifecycleDeliveryQueueOptions<T> {\n\treadonly maxPendingEvents: number;\n\treadonly maxPendingBytes?: number;\n\treadonly measureBytes: (value: T) => number;\n\treadonly deliver: (value: T) => void | Promise<void>;\n\treadonly overflowCode: string;\n}\n\nexport interface LifecycleDeliveryQueue<T> {\n\tenqueue(value: T): Promise<void>;\n\tdrain(): Promise<void>;\n\tclose(): void;\n\tsnapshot(): LifecycleDeliveryQueueSnapshot;\n}\n\nexport class LifecycleDeliveryQueueOverflowError extends Error {\n\treadonly code: string;\n\treadonly maxPendingEvents: number;\n\treadonly maxPendingBytes?: number;\n\treadonly pendingEvents: number;\n\treadonly pendingBytes: number;\n\treadonly attemptedBytes: number;\n\n\tconstructor(\n\t\tcode: string,\n\t\tmaxPendingEvents: number,\n\t\tmaxPendingBytes: number | undefined,\n\t\tpendingEvents: number,\n\t\tpendingBytes: number,\n\t\tattemptedBytes: number,\n\t) {\n\t\tsuper(\n\t\t\t`Lifecycle delivery queue overflow: pending events ${pendingEvents + 1} exceeds ${maxPendingEvents}` +\n\t\t\t\t(maxPendingBytes === undefined\n\t\t\t\t\t? \"\"\n\t\t\t\t\t: ` or pending bytes ${pendingBytes + attemptedBytes} exceeds ${maxPendingBytes}`),\n\t\t);\n\t\tthis.name = \"LifecycleDeliveryQueueOverflowError\";\n\t\tthis.code = code;\n\t\tthis.maxPendingEvents = maxPendingEvents;\n\t\tthis.maxPendingBytes = maxPendingBytes;\n\t\tthis.pendingEvents = pendingEvents;\n\t\tthis.pendingBytes = pendingBytes;\n\t\tthis.attemptedBytes = attemptedBytes;\n\t}\n}\n\nexport class LifecycleDeliveryQueueClosedError extends Error {\n\treadonly code = \"lifecycle_delivery_closed\";\n\n\tconstructor() {\n\t\tsuper(\"Lifecycle delivery queue is closed\");\n\t\tthis.name = \"LifecycleDeliveryQueueClosedError\";\n\t}\n}\n\ninterface QueueEntry<T> {\n\treadonly value: T;\n\treadonly bytes: number;\n\treadonly resolve: () => void;\n\treadonly reject: (error: unknown) => void;\n}\n\nfunction assertPositiveSafeInteger(value: number, label: string): void {\n\tif (!Number.isSafeInteger(value) || value < 1) {\n\t\tthrow new Error(`Lifecycle delivery queue ${label} must be a positive safe integer`);\n\t}\n}\n\n/**\n * Overflow terminates only this subscription's acceptance path. Values already\n * accepted remain FIFO and handler failures do not alter source lifecycle\n * facts. A closed queue rejects pending values; an overflowed queue rejects\n * further values with the original overflow code so telemetry keeps one stable\n * backpressure classification. Callers must attach a handler to every enqueue\n * promise immediately: close() and overflow reject those promises.\n */\nexport function createLifecycleDeliveryQueue<T>(options: LifecycleDeliveryQueueOptions<T>): LifecycleDeliveryQueue<T> {\n\tassertPositiveSafeInteger(options.maxPendingEvents, \"maxPendingEvents\");\n\tif (options.maxPendingBytes !== undefined) assertPositiveSafeInteger(options.maxPendingBytes, \"maxPendingBytes\");\n\tif (typeof options.overflowCode !== \"string\" || !options.overflowCode.trim()) {\n\t\tthrow new Error(\"Lifecycle delivery queue overflowCode must be non-empty\");\n\t}\n\n\tconst entries: QueueEntry<T>[] = [];\n\tlet status: LifecycleDeliveryQueueStatus = \"active\";\n\tlet pendingEvents = 0;\n\tlet pendingBytes = 0;\n\tlet accepted = 0;\n\tlet delivered = 0;\n\tlet rejected = 0;\n\tlet processing = false;\n\tlet drainPromise: Promise<void> | undefined;\n\tlet resolveDrain: (() => void) | undefined;\n\n\tconst ensureDrainPromise = (): Promise<void> => {\n\t\tif (drainPromise === undefined) {\n\t\t\tdrainPromise = new Promise<void>((resolve) => {\n\t\t\t\tresolveDrain = resolve;\n\t\t\t});\n\t\t}\n\t\treturn drainPromise;\n\t};\n\tconst settleDrainIfIdle = (): void => {\n\t\tif (processing || entries.length > 0) return;\n\t\tresolveDrain?.();\n\t\tdrainPromise = undefined;\n\t\tresolveDrain = undefined;\n\t};\n\tconst pump = async (): Promise<void> => {\n\t\tif (processing) return;\n\t\tprocessing = true;\n\t\ttry {\n\t\t\twhile (entries.length > 0) {\n\t\t\t\tconst entry = entries.shift();\n\t\t\t\tif (entry === undefined) continue;\n\t\t\t\ttry {\n\t\t\t\t\tawait options.deliver(entry.value);\n\t\t\t\t\tdelivered += 1;\n\t\t\t\t\tentry.resolve();\n\t\t\t\t} catch (error) {\n\t\t\t\t\trejected += 1;\n\t\t\t\t\tentry.reject(error);\n\t\t\t\t} finally {\n\t\t\t\t\tpendingEvents -= 1;\n\t\t\t\t\tpendingBytes -= entry.bytes;\n\t\t\t\t}\n\t\t\t}\n\t\t} finally {\n\t\t\tprocessing = false;\n\t\t\tsettleDrainIfIdle();\n\t\t}\n\t};\n\n\treturn {\n\t\tenqueue(value) {\n\t\t\tif (status === \"overflowed\") {\n\t\t\t\trejected += 1;\n\t\t\t\treturn Promise.reject(\n\t\t\t\t\tnew LifecycleDeliveryQueueOverflowError(\n\t\t\t\t\t\toptions.overflowCode,\n\t\t\t\t\t\toptions.maxPendingEvents,\n\t\t\t\t\t\toptions.maxPendingBytes,\n\t\t\t\t\t\tpendingEvents,\n\t\t\t\t\t\tpendingBytes,\n\t\t\t\t\t\t0,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (status === \"closed\") {\n\t\t\t\trejected += 1;\n\t\t\t\treturn Promise.reject(new LifecycleDeliveryQueueClosedError());\n\t\t\t}\n\t\t\tconst bytes = options.measureBytes(value);\n\t\t\tassertPositiveSafeInteger(bytes, \"measureBytes result\");\n\t\t\tif (\n\t\t\t\tpendingEvents + 1 > options.maxPendingEvents ||\n\t\t\t\t(options.maxPendingBytes !== undefined && pendingBytes + bytes > options.maxPendingBytes)\n\t\t\t) {\n\t\t\t\tstatus = \"overflowed\";\n\t\t\t\trejected += 1;\n\t\t\t\treturn Promise.reject(\n\t\t\t\t\tnew LifecycleDeliveryQueueOverflowError(\n\t\t\t\t\t\toptions.overflowCode,\n\t\t\t\t\t\toptions.maxPendingEvents,\n\t\t\t\t\t\toptions.maxPendingBytes,\n\t\t\t\t\t\tpendingEvents,\n\t\t\t\t\t\tpendingBytes,\n\t\t\t\t\t\tbytes,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\taccepted += 1;\n\t\t\tpendingEvents += 1;\n\t\t\tpendingBytes += bytes;\n\t\t\tconst result = new Promise<void>((resolve, reject) => {\n\t\t\t\tentries.push({ value, bytes, resolve, reject });\n\t\t\t});\n\t\t\tensureDrainPromise();\n\t\t\tvoid pump();\n\t\t\treturn result;\n\t\t},\n\t\tdrain() {\n\t\t\tif (!processing && entries.length === 0) return Promise.resolve();\n\t\t\treturn ensureDrainPromise();\n\t\t},\n\t\tclose() {\n\t\t\tif (status === \"closed\") return;\n\t\t\tstatus = \"closed\";\n\t\t\tconst error = new LifecycleDeliveryQueueClosedError();\n\t\t\twhile (entries.length > 0) {\n\t\t\t\tconst entry = entries.shift();\n\t\t\t\tif (entry === undefined) continue;\n\t\t\t\tpendingEvents -= 1;\n\t\t\t\tpendingBytes -= entry.bytes;\n\t\t\t\trejected += 1;\n\t\t\t\tentry.reject(error);\n\t\t\t}\n\t\t\tsettleDrainIfIdle();\n\t\t},\n\t\tsnapshot: () =>\n\t\t\tObject.freeze({\n\t\t\t\tstatus,\n\t\t\t\tmaxPendingEvents: options.maxPendingEvents,\n\t\t\t\t...(options.maxPendingBytes === undefined ? {} : { maxPendingBytes: options.maxPendingBytes }),\n\t\t\t\tpendingEvents,\n\t\t\t\tpendingBytes,\n\t\t\t\taccepted,\n\t\t\t\tdelivered,\n\t\t\t\trejected,\n\t\t\t}),\n\t};\n}\n"]}

package/dist/core/extensions/microcompact.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Microcompact (P1 context hygiene): before spending an LLM summarization
+ * call, elide the BULKY OLD tool results from the LLM context — a pure local
+ * history transform with zero model cost (the codex/ZCode "microcompact"
+ * layer). The session file keeps every byte (append-only marker + logical
+ * transform at context build); only the model-visible context shrinks.
+ *
+ * Contract: the marker is a `custom` session entry (`MICROCOMPACT_CUSTOM_TYPE`)
+ * whose data names the elision point. The projection registered by the
+ * bootstrap compaction policy plugin (via the PUBLIC
+ * `api.registerEntryProjection` channel) replaces eligible tool-result
+ * contents older than that point with a fixed placeholder, so reload and
+ * token estimation stay consistent with live turns. The kernel applies
+ * registered projections verbatim and knows nothing about microcompact.
+ */
+import type { AgentMessage } from "@agent-forge/agent-core";
+import { type CompactionSettings } from "../compaction/index.ts";
+import type { SessionEntry } from "../session-manager.ts";
+/** Custom entry type carrying the microcompact elision point. */
+export declare const MICROCOMPACT_CUSTOM_TYPE = "microcompact.v1";
+/** Replacement content for an elided tool result. */
+export declare const MICROCOMPACT_ELIDED_PLACEHOLDER = "[earlier tool result elided by microcompact]";
+/** Tool results shorter than this are not worth eliding (noise, not bulk). */
+export declare const DEFAULT_MIN_ELIDE_CHARS = 200;
+/**
+ * Minimum estimated token relief for a microcompact to fire: below this the
+ * churn (marker entry + context transition) cannot pay for itself and the
+ * caller falls through to full LLM compaction.
+ */
+export declare const MIN_MICROCOMPACT_FREED_TOKENS = 2048;
+/** Data carried by a {@link MICROCOMPACT_CUSTOM_TYPE} custom entry. */
+export interface MicrocompactMarkerData {
+    /** Entries strictly BEFORE this entry id (path order) are elision candidates. */
+    readonly elideBeforeEntryId: string;
+    /** Tool results whose serialized content is shorter are kept verbatim. */
+    readonly minChars: number;
+}
+export interface MicrocompactPlan {
+    readonly elideBeforeEntryId: string;
+    /** Estimated tokens freed by eliding the eligible tool results. */
+    readonly freedTokens: number;
+    readonly elidedCount: number;
+}
+/**
+ * Plan one microcompact over the branch path: protect the most recent
+ * `settings.keepRecentTokens` (estimated) as the verbatim tail, and elide the
+ * eligible old tool results before that cut. Returns undefined when there is
+ * nothing to elide or the relief cannot reach the minimum.
+ */
+export declare function planMicrocompact(pathEntries: readonly {
+    readonly id?: string;
+    readonly type: string;
+    readonly message?: AgentMessage;
+}[], settings: CompactionSettings, options?: {
+    minElideChars?: number;
+}): MicrocompactPlan | undefined;
+/** Resolve the marker data of the LAST microcompact marker in path order. */
+export declare function lastMicrocompactMarker(pathEntries: readonly {
+    readonly type: string;
+    readonly customType?: string;
+    readonly data?: unknown;
+}[]): MicrocompactMarkerData | undefined;
+/**
+ * The entry projection backing microcompact: replaces the CONTENT of eligible
+ * tool results before the marker's cut point with the fixed placeholder, and
+ * keeps everything else verbatim. Registered through the public
+ * `api.registerEntryProjection` channel — the same channel any third-party
+ * context policy uses; the kernel applies it without interpretation.
+ */
+export declare function applyMicrocompactElision(path: SessionEntry[]): SessionEntry[];
+//# sourceMappingURL=microcompact.d.ts.map

package/dist/core/extensions/microcompact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"microcompact.d.ts","sourceRoot":"","sources":["../../../src/core/extensions/microcompact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,KAAK,kBAAkB,EAAkB,MAAM,wBAAwB,CAAC;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D,qDAAqD;AACrD,eAAO,MAAM,+BAA+B,iDAAiD,CAAC;AAE9F,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD,uEAAuE;AACvE,MAAM,WAAW,sBAAsB;IACtC,iFAAiF;IACjF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAUD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,WAAW,EAAE,SAAS;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;CAAE,EAAE,EACxG,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACtC,gBAAgB,GAAG,SAAS,CAoC9B;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,GACtG,sBAAsB,GAAG,SAAS,CAapC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAe7E","sourcesContent":["/**\n * Microcompact (P1 context hygiene): before spending an LLM summarization\n * call, elide the BULKY OLD tool results from the LLM context — a pure local\n * history transform with zero model cost (the codex/ZCode \"microcompact\"\n * layer). The session file keeps every byte (append-only marker + logical\n * transform at context build); only the model-visible context shrinks.\n *\n * Contract: the marker is a `custom` session entry (`MICROCOMPACT_CUSTOM_TYPE`)\n * whose data names the elision point. The projection registered by the\n * bootstrap compaction policy plugin (via the PUBLIC\n * `api.registerEntryProjection` channel) replaces eligible tool-result\n * contents older than that point with a fixed placeholder, so reload and\n * token estimation stay consistent with live turns. The kernel applies\n * registered projections verbatim and knows nothing about microcompact.\n */\n\nimport type { AgentMessage } from \"@agent-forge/agent-core\";\nimport { contentText } from \"@agent-forge/ai\";\nimport { type CompactionSettings, estimateTokens } from \"../compaction/index.ts\";\nimport type { SessionEntry } from \"../session-manager.ts\";\n\n/** Custom entry type carrying the microcompact elision point. */\nexport const MICROCOMPACT_CUSTOM_TYPE = \"microcompact.v1\";\n\n/** Replacement content for an elided tool result. */\nexport const MICROCOMPACT_ELIDED_PLACEHOLDER = \"[earlier tool result elided by microcompact]\";\n\n/** Tool results shorter than this are not worth eliding (noise, not bulk). */\nexport const DEFAULT_MIN_ELIDE_CHARS = 200;\n\n/**\n * Minimum estimated token relief for a microcompact to fire: below this the\n * churn (marker entry + context transition) cannot pay for itself and the\n * caller falls through to full LLM compaction.\n */\nexport const MIN_MICROCOMPACT_FREED_TOKENS = 2048;\n\n/** Data carried by a {@link MICROCOMPACT_CUSTOM_TYPE} custom entry. */\nexport interface MicrocompactMarkerData {\n\t/** Entries strictly BEFORE this entry id (path order) are elision candidates. */\n\treadonly elideBeforeEntryId: string;\n\t/** Tool results whose serialized content is shorter are kept verbatim. */\n\treadonly minChars: number;\n}\n\nexport interface MicrocompactPlan {\n\treadonly elideBeforeEntryId: string;\n\t/** Estimated tokens freed by eliding the eligible tool results. */\n\treadonly freedTokens: number;\n\treadonly elidedCount: number;\n}\n\nfunction isElidableToolResult(\n\tmessage: AgentMessage,\n\tminChars: number,\n): message is Extract<AgentMessage, { role: \"toolResult\" }> {\n\tif (message.role !== \"toolResult\") return false;\n\treturn contentText(message.content, \"\").length >= minChars;\n}\n\n/**\n * Plan one microcompact over the branch path: protect the most recent\n * `settings.keepRecentTokens` (estimated) as the verbatim tail, and elide the\n * eligible old tool results before that cut. Returns undefined when there is\n * nothing to elide or the relief cannot reach the minimum.\n */\nexport function planMicrocompact(\n\tpathEntries: readonly { readonly id?: string; readonly type: string; readonly message?: AgentMessage }[],\n\tsettings: CompactionSettings,\n\toptions: { minElideChars?: number } = {},\n): MicrocompactPlan | undefined {\n\tconst minChars = options.minElideChars ?? DEFAULT_MIN_ELIDE_CHARS;\n\n\t// Protect the recent tail: walk backwards accumulating estimated tokens,\n\t// cutting before the entry that crosses the budget (same walk as\n\t// findCutPoint, but without turn-boundary subtleties — elision never\n\t// removes entries, only replaces contents, so any cut point is safe).\n\tlet accumulated = 0;\n\tlet cutIndex = 0;\n\tfor (let i = pathEntries.length - 1; i >= 0; i--) {\n\t\tconst entry = pathEntries[i];\n\t\tconst messageTokens = entry.message ? estimateTokens(entry.message) : 0;\n\t\tif (messageTokens === 0) continue;\n\t\taccumulated += messageTokens;\n\t\tif (accumulated >= settings.keepRecentTokens) {\n\t\t\tcutIndex = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\tlet freedTokens = 0;\n\tlet elidedCount = 0;\n\tfor (let i = 0; i < cutIndex; i++) {\n\t\tconst message = pathEntries[i].message;\n\t\tif (!message || !isElidableToolResult(message, minChars)) continue;\n\t\tfreedTokens +=\n\t\t\testimateTokens(message) -\n\t\t\testimateTokens({ ...message, content: [{ type: \"text\", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] });\n\t\telidedCount += 1;\n\t}\n\n\tconst elideBefore = pathEntries[cutIndex];\n\tif (elidedCount === 0 || freedTokens < MIN_MICROCOMPACT_FREED_TOKENS) return undefined;\n\tconst elideBeforeEntryId = elideBefore?.id;\n\tif (!elideBeforeEntryId) return undefined;\n\treturn { elideBeforeEntryId, freedTokens, elidedCount };\n}\n\n/** Resolve the marker data of the LAST microcompact marker in path order. */\nexport function lastMicrocompactMarker(\n\tpathEntries: readonly { readonly type: string; readonly customType?: string; readonly data?: unknown }[],\n): MicrocompactMarkerData | undefined {\n\tlet marker: MicrocompactMarkerData | undefined;\n\tfor (const entry of pathEntries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== MICROCOMPACT_CUSTOM_TYPE) continue;\n\t\tconst data = entry.data as Partial<MicrocompactMarkerData> | undefined;\n\t\tif (typeof data?.elideBeforeEntryId === \"string\") {\n\t\t\tmarker = {\n\t\t\t\telideBeforeEntryId: data.elideBeforeEntryId,\n\t\t\t\tminChars: typeof data.minChars === \"number\" && data.minChars >= 0 ? data.minChars : DEFAULT_MIN_ELIDE_CHARS,\n\t\t\t};\n\t\t}\n\t}\n\treturn marker;\n}\n\n/**\n * The entry projection backing microcompact: replaces the CONTENT of eligible\n * tool results before the marker's cut point with the fixed placeholder, and\n * keeps everything else verbatim. Registered through the public\n * `api.registerEntryProjection` channel — the same channel any third-party\n * context policy uses; the kernel applies it without interpretation.\n */\nexport function applyMicrocompactElision(path: SessionEntry[]): SessionEntry[] {\n\tconst marker = lastMicrocompactMarker(path);\n\tif (marker === undefined) return path;\n\tconst cutIndex = path.findIndex((entry) => entry.id === marker.elideBeforeEntryId);\n\tif (cutIndex <= 0) return path;\n\treturn path.map((entry, index) => {\n\t\tif (index >= cutIndex || entry.type !== \"message\") return entry;\n\t\tconst message = entry.message;\n\t\tif (message.role !== \"toolResult\") return entry;\n\t\tif (contentText(message.content, \"\").length < marker.minChars) return entry;\n\t\treturn {\n\t\t\t...entry,\n\t\t\tmessage: { ...message, content: [{ type: \"text\", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] },\n\t\t};\n\t});\n}\n"]}

package/dist/core/extensions/microcompact.js

@@ -0,0 +1,123 @@
+/**
+ * Microcompact (P1 context hygiene): before spending an LLM summarization
+ * call, elide the BULKY OLD tool results from the LLM context — a pure local
+ * history transform with zero model cost (the codex/ZCode "microcompact"
+ * layer). The session file keeps every byte (append-only marker + logical
+ * transform at context build); only the model-visible context shrinks.
+ *
+ * Contract: the marker is a `custom` session entry (`MICROCOMPACT_CUSTOM_TYPE`)
+ * whose data names the elision point. The projection registered by the
+ * bootstrap compaction policy plugin (via the PUBLIC
+ * `api.registerEntryProjection` channel) replaces eligible tool-result
+ * contents older than that point with a fixed placeholder, so reload and
+ * token estimation stay consistent with live turns. The kernel applies
+ * registered projections verbatim and knows nothing about microcompact.
+ */
+import { contentText } from "@agent-forge/ai";
+import { estimateTokens } from "../compaction/index.js";
+/** Custom entry type carrying the microcompact elision point. */
+export const MICROCOMPACT_CUSTOM_TYPE = "microcompact.v1";
+/** Replacement content for an elided tool result. */
+export const MICROCOMPACT_ELIDED_PLACEHOLDER = "[earlier tool result elided by microcompact]";
+/** Tool results shorter than this are not worth eliding (noise, not bulk). */
+export const DEFAULT_MIN_ELIDE_CHARS = 200;
+/**
+ * Minimum estimated token relief for a microcompact to fire: below this the
+ * churn (marker entry + context transition) cannot pay for itself and the
+ * caller falls through to full LLM compaction.
+ */
+export const MIN_MICROCOMPACT_FREED_TOKENS = 2048;
+function isElidableToolResult(message, minChars) {
+    if (message.role !== "toolResult")
+        return false;
+    return contentText(message.content, "").length >= minChars;
+}
+/**
+ * Plan one microcompact over the branch path: protect the most recent
+ * `settings.keepRecentTokens` (estimated) as the verbatim tail, and elide the
+ * eligible old tool results before that cut. Returns undefined when there is
+ * nothing to elide or the relief cannot reach the minimum.
+ */
+export function planMicrocompact(pathEntries, settings, options = {}) {
+    const minChars = options.minElideChars ?? DEFAULT_MIN_ELIDE_CHARS;
+    // Protect the recent tail: walk backwards accumulating estimated tokens,
+    // cutting before the entry that crosses the budget (same walk as
+    // findCutPoint, but without turn-boundary subtleties — elision never
+    // removes entries, only replaces contents, so any cut point is safe).
+    let accumulated = 0;
+    let cutIndex = 0;
+    for (let i = pathEntries.length - 1; i >= 0; i--) {
+        const entry = pathEntries[i];
+        const messageTokens = entry.message ? estimateTokens(entry.message) : 0;
+        if (messageTokens === 0)
+            continue;
+        accumulated += messageTokens;
+        if (accumulated >= settings.keepRecentTokens) {
+            cutIndex = i;
+            break;
+        }
+    }
+    let freedTokens = 0;
+    let elidedCount = 0;
+    for (let i = 0; i < cutIndex; i++) {
+        const message = pathEntries[i].message;
+        if (!message || !isElidableToolResult(message, minChars))
+            continue;
+        freedTokens +=
+            estimateTokens(message) -
+                estimateTokens({ ...message, content: [{ type: "text", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] });
+        elidedCount += 1;
+    }
+    const elideBefore = pathEntries[cutIndex];
+    if (elidedCount === 0 || freedTokens < MIN_MICROCOMPACT_FREED_TOKENS)
+        return undefined;
+    const elideBeforeEntryId = elideBefore?.id;
+    if (!elideBeforeEntryId)
+        return undefined;
+    return { elideBeforeEntryId, freedTokens, elidedCount };
+}
+/** Resolve the marker data of the LAST microcompact marker in path order. */
+export function lastMicrocompactMarker(pathEntries) {
+    let marker;
+    for (const entry of pathEntries) {
+        if (entry.type !== "custom" || entry.customType !== MICROCOMPACT_CUSTOM_TYPE)
+            continue;
+        const data = entry.data;
+        if (typeof data?.elideBeforeEntryId === "string") {
+            marker = {
+                elideBeforeEntryId: data.elideBeforeEntryId,
+                minChars: typeof data.minChars === "number" && data.minChars >= 0 ? data.minChars : DEFAULT_MIN_ELIDE_CHARS,
+            };
+        }
+    }
+    return marker;
+}
+/**
+ * The entry projection backing microcompact: replaces the CONTENT of eligible
+ * tool results before the marker's cut point with the fixed placeholder, and
+ * keeps everything else verbatim. Registered through the public
+ * `api.registerEntryProjection` channel — the same channel any third-party
+ * context policy uses; the kernel applies it without interpretation.
+ */
+export function applyMicrocompactElision(path) {
+    const marker = lastMicrocompactMarker(path);
+    if (marker === undefined)
+        return path;
+    const cutIndex = path.findIndex((entry) => entry.id === marker.elideBeforeEntryId);
+    if (cutIndex <= 0)
+        return path;
+    return path.map((entry, index) => {
+        if (index >= cutIndex || entry.type !== "message")
+            return entry;
+        const message = entry.message;
+        if (message.role !== "toolResult")
+            return entry;
+        if (contentText(message.content, "").length < marker.minChars)
+            return entry;
+        return {
+            ...entry,
+            message: { ...message, content: [{ type: "text", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] },
+        };
+    });
+}
+//# sourceMappingURL=microcompact.js.map

package/dist/core/extensions/microcompact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"microcompact.js","sourceRoot":"","sources":["../../../src/core/extensions/microcompact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAA2B,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGjF,iEAAiE;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC;AAE1D,qDAAqD;AACrD,MAAM,CAAC,MAAM,+BAA+B,GAAG,8CAA8C,CAAC;AAE9F,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAiBlD,SAAS,oBAAoB,CAC5B,OAAqB,EACrB,QAAgB,EAC2C;IAC3D,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC;AAAA,CAC3D;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC/B,WAAwG,EACxG,QAA4B,EAC5B,OAAO,GAA+B,EAAE,EACT;IAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,IAAI,uBAAuB,CAAC;IAElE,yEAAyE;IACzE,iEAAiE;IACjE,uEAAqE;IACrE,sEAAsE;IACtE,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,IAAI,aAAa,KAAK,CAAC;YAAE,SAAS;QAClC,WAAW,IAAI,aAAa,CAAC;QAC7B,IAAI,WAAW,IAAI,QAAQ,CAAC,gBAAgB,EAAE,CAAC;YAC9C,QAAQ,GAAG,CAAC,CAAC;YACb,MAAM;QACP,CAAC;IACF,CAAC;IAED,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QACvC,IAAI,CAAC,OAAO,IAAI,CAAC,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC;YAAE,SAAS;QACnE,WAAW;YACV,cAAc,CAAC,OAAO,CAAC;gBACvB,cAAc,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,+BAA+B,EAAE,CAAC,EAAE,CAAC,CAAC;QACpG,WAAW,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,WAAW,KAAK,CAAC,IAAI,WAAW,GAAG,6BAA6B;QAAE,OAAO,SAAS,CAAC;IACvF,MAAM,kBAAkB,GAAG,WAAW,EAAE,EAAE,CAAC;IAC3C,IAAI,CAAC,kBAAkB;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AAAA,CACxD;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CACrC,WAAwG,EACnE;IACrC,IAAI,MAA0C,CAAC;IAC/C,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,KAAK,wBAAwB;YAAE,SAAS;QACvF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAmD,CAAC;QACvE,IAAI,OAAO,IAAI,EAAE,kBAAkB,KAAK,QAAQ,EAAE,CAAC;YAClD,MAAM,GAAG;gBACR,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;gBAC3C,QAAQ,EAAE,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,uBAAuB;aAC3G,CAAC;QACH,CAAC;IACF,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAoB,EAAkB;IAC9E,MAAM,MAAM,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACnF,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;QACjC,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAChE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5E,OAAO;YACN,GAAG,KAAK;YACR,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,+BAA+B,EAAE,CAAC,EAAE;SAC3F,CAAC;IAAA,CACF,CAAC,CAAC;AAAA,CACH","sourcesContent":["/**\n * Microcompact (P1 context hygiene): before spending an LLM summarization\n * call, elide the BULKY OLD tool results from the LLM context — a pure local\n * history transform with zero model cost (the codex/ZCode \"microcompact\"\n * layer). The session file keeps every byte (append-only marker + logical\n * transform at context build); only the model-visible context shrinks.\n *\n * Contract: the marker is a `custom` session entry (`MICROCOMPACT_CUSTOM_TYPE`)\n * whose data names the elision point. The projection registered by the\n * bootstrap compaction policy plugin (via the PUBLIC\n * `api.registerEntryProjection` channel) replaces eligible tool-result\n * contents older than that point with a fixed placeholder, so reload and\n * token estimation stay consistent with live turns. The kernel applies\n * registered projections verbatim and knows nothing about microcompact.\n */\n\nimport type { AgentMessage } from \"@agent-forge/agent-core\";\nimport { contentText } from \"@agent-forge/ai\";\nimport { type CompactionSettings, estimateTokens } from \"../compaction/index.ts\";\nimport type { SessionEntry } from \"../session-manager.ts\";\n\n/** Custom entry type carrying the microcompact elision point. */\nexport const MICROCOMPACT_CUSTOM_TYPE = \"microcompact.v1\";\n\n/** Replacement content for an elided tool result. */\nexport const MICROCOMPACT_ELIDED_PLACEHOLDER = \"[earlier tool result elided by microcompact]\";\n\n/** Tool results shorter than this are not worth eliding (noise, not bulk). */\nexport const DEFAULT_MIN_ELIDE_CHARS = 200;\n\n/**\n * Minimum estimated token relief for a microcompact to fire: below this the\n * churn (marker entry + context transition) cannot pay for itself and the\n * caller falls through to full LLM compaction.\n */\nexport const MIN_MICROCOMPACT_FREED_TOKENS = 2048;\n\n/** Data carried by a {@link MICROCOMPACT_CUSTOM_TYPE} custom entry. */\nexport interface MicrocompactMarkerData {\n\t/** Entries strictly BEFORE this entry id (path order) are elision candidates. */\n\treadonly elideBeforeEntryId: string;\n\t/** Tool results whose serialized content is shorter are kept verbatim. */\n\treadonly minChars: number;\n}\n\nexport interface MicrocompactPlan {\n\treadonly elideBeforeEntryId: string;\n\t/** Estimated tokens freed by eliding the eligible tool results. */\n\treadonly freedTokens: number;\n\treadonly elidedCount: number;\n}\n\nfunction isElidableToolResult(\n\tmessage: AgentMessage,\n\tminChars: number,\n): message is Extract<AgentMessage, { role: \"toolResult\" }> {\n\tif (message.role !== \"toolResult\") return false;\n\treturn contentText(message.content, \"\").length >= minChars;\n}\n\n/**\n * Plan one microcompact over the branch path: protect the most recent\n * `settings.keepRecentTokens` (estimated) as the verbatim tail, and elide the\n * eligible old tool results before that cut. Returns undefined when there is\n * nothing to elide or the relief cannot reach the minimum.\n */\nexport function planMicrocompact(\n\tpathEntries: readonly { readonly id?: string; readonly type: string; readonly message?: AgentMessage }[],\n\tsettings: CompactionSettings,\n\toptions: { minElideChars?: number } = {},\n): MicrocompactPlan | undefined {\n\tconst minChars = options.minElideChars ?? DEFAULT_MIN_ELIDE_CHARS;\n\n\t// Protect the recent tail: walk backwards accumulating estimated tokens,\n\t// cutting before the entry that crosses the budget (same walk as\n\t// findCutPoint, but without turn-boundary subtleties — elision never\n\t// removes entries, only replaces contents, so any cut point is safe).\n\tlet accumulated = 0;\n\tlet cutIndex = 0;\n\tfor (let i = pathEntries.length - 1; i >= 0; i--) {\n\t\tconst entry = pathEntries[i];\n\t\tconst messageTokens = entry.message ? estimateTokens(entry.message) : 0;\n\t\tif (messageTokens === 0) continue;\n\t\taccumulated += messageTokens;\n\t\tif (accumulated >= settings.keepRecentTokens) {\n\t\t\tcutIndex = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\tlet freedTokens = 0;\n\tlet elidedCount = 0;\n\tfor (let i = 0; i < cutIndex; i++) {\n\t\tconst message = pathEntries[i].message;\n\t\tif (!message || !isElidableToolResult(message, minChars)) continue;\n\t\tfreedTokens +=\n\t\t\testimateTokens(message) -\n\t\t\testimateTokens({ ...message, content: [{ type: \"text\", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] });\n\t\telidedCount += 1;\n\t}\n\n\tconst elideBefore = pathEntries[cutIndex];\n\tif (elidedCount === 0 || freedTokens < MIN_MICROCOMPACT_FREED_TOKENS) return undefined;\n\tconst elideBeforeEntryId = elideBefore?.id;\n\tif (!elideBeforeEntryId) return undefined;\n\treturn { elideBeforeEntryId, freedTokens, elidedCount };\n}\n\n/** Resolve the marker data of the LAST microcompact marker in path order. */\nexport function lastMicrocompactMarker(\n\tpathEntries: readonly { readonly type: string; readonly customType?: string; readonly data?: unknown }[],\n): MicrocompactMarkerData | undefined {\n\tlet marker: MicrocompactMarkerData | undefined;\n\tfor (const entry of pathEntries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== MICROCOMPACT_CUSTOM_TYPE) continue;\n\t\tconst data = entry.data as Partial<MicrocompactMarkerData> | undefined;\n\t\tif (typeof data?.elideBeforeEntryId === \"string\") {\n\t\t\tmarker = {\n\t\t\t\telideBeforeEntryId: data.elideBeforeEntryId,\n\t\t\t\tminChars: typeof data.minChars === \"number\" && data.minChars >= 0 ? data.minChars : DEFAULT_MIN_ELIDE_CHARS,\n\t\t\t};\n\t\t}\n\t}\n\treturn marker;\n}\n\n/**\n * The entry projection backing microcompact: replaces the CONTENT of eligible\n * tool results before the marker's cut point with the fixed placeholder, and\n * keeps everything else verbatim. Registered through the public\n * `api.registerEntryProjection` channel — the same channel any third-party\n * context policy uses; the kernel applies it without interpretation.\n */\nexport function applyMicrocompactElision(path: SessionEntry[]): SessionEntry[] {\n\tconst marker = lastMicrocompactMarker(path);\n\tif (marker === undefined) return path;\n\tconst cutIndex = path.findIndex((entry) => entry.id === marker.elideBeforeEntryId);\n\tif (cutIndex <= 0) return path;\n\treturn path.map((entry, index) => {\n\t\tif (index >= cutIndex || entry.type !== \"message\") return entry;\n\t\tconst message = entry.message;\n\t\tif (message.role !== \"toolResult\") return entry;\n\t\tif (contentText(message.content, \"\").length < marker.minChars) return entry;\n\t\treturn {\n\t\t\t...entry,\n\t\t\tmessage: { ...message, content: [{ type: \"text\", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] },\n\t\t};\n\t});\n}\n"]}

package/dist/core/extensions/public-api.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Backward-compatibility shim: the experimental public API surface moved to
+ * `@agent-forge/plugin-sdk` (D-075 S2), which is the single authoring authority
+ * for plugin-facing contracts. This module re-exports the SDK surface so
+ * existing intra-host imports (`./public-api.ts`) and the host's public exports
+ * keep resolving unchanged.
+ */
+export type { ShouldStopAfterTurnContext } from "@agent-forge/agent-core";
+export * from "@agent-forge/plugin-sdk";
+//# sourceMappingURL=public-api.d.ts.map

package/dist/core/extensions/public-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.d.ts","sourceRoot":"","sources":["../../../src/core/extensions/public-api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAC1E,cAAc,yBAAyB,CAAC","sourcesContent":["/**\n * Backward-compatibility shim: the experimental public API surface moved to\n * `@agent-forge/plugin-sdk` (D-075 S2), which is the single authoring authority\n * for plugin-facing contracts. This module re-exports the SDK surface so\n * existing intra-host imports (`./public-api.ts`) and the host's public exports\n * keep resolving unchanged.\n */\n\n// The loop-stop context stays kernel-typed in @agent-forge/agent-core (its\n// fields reference the provider message model, which must not cross into the\n// SDK); the SDK re-declares the hook parameter as `any` for the same reason.\n// Keep exporting the typed contract from the historical host path.\nexport type { ShouldStopAfterTurnContext } from \"@agent-forge/agent-core\";\nexport * from \"@agent-forge/plugin-sdk\";\n"]}

package/dist/core/extensions/public-api.js

@@ -0,0 +1,9 @@
+/**
+ * Backward-compatibility shim: the experimental public API surface moved to
+ * `@agent-forge/plugin-sdk` (D-075 S2), which is the single authoring authority
+ * for plugin-facing contracts. This module re-exports the SDK surface so
+ * existing intra-host imports (`./public-api.ts`) and the host's public exports
+ * keep resolving unchanged.
+ */
+export * from "@agent-forge/plugin-sdk";
+//# sourceMappingURL=public-api.js.map

package/dist/core/extensions/public-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.js","sourceRoot":"","sources":["../../../src/core/extensions/public-api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,cAAc,yBAAyB,CAAC","sourcesContent":["/**\n * Backward-compatibility shim: the experimental public API surface moved to\n * `@agent-forge/plugin-sdk` (D-075 S2), which is the single authoring authority\n * for plugin-facing contracts. This module re-exports the SDK surface so\n * existing intra-host imports (`./public-api.ts`) and the host's public exports\n * keep resolving unchanged.\n */\n\n// The loop-stop context stays kernel-typed in @agent-forge/agent-core (its\n// fields reference the provider message model, which must not cross into the\n// SDK); the SDK re-declares the hook parameter as `any` for the same reason.\n// Keep exporting the typed contract from the historical host path.\nexport type { ShouldStopAfterTurnContext } from \"@agent-forge/agent-core\";\nexport * from \"@agent-forge/plugin-sdk\";\n"]}