@aexol/spectral 0.9.12 → 0.9.13

package/dist/memory/hooks/compaction-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../../../src/memory/hooks/compaction-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AAsBtF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AA6B7C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA2VhF"}
+{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../../../src/memory/hooks/compaction-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA+C,MAAM,iCAAiC,CAAC;AAsBjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAmE7C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA8XhF"}

package/dist/memory/hooks/compaction-hook.js

@@ -20,6 +20,43 @@ function formatReflectorStats(stats) {
 function formatPrunerStats(result) {
     return `pruner dropped ${plural(result.droppedIds.length, "observation")} in ${plural(result.passes.length, "pass", "passes")}, stop: ${result.stopReason}`;
 }
+function emitProgressLine(emitProgress, line) {
+    emitProgress?.(`${line}\n`);
+}
+function compactToolDetails(details) {
+    if (!details || typeof details !== "object")
+        return "";
+    const r = details;
+    const parts = [];
+    for (const key of ["added", "accepted", "dropped", "duplicates", "rejected", "remaining", "total"]) {
+        const value = r[key];
+        if (typeof value === "number")
+            parts.push(`${key}=${value}`);
+        if (Array.isArray(value))
+            parts.push(`${key}=${value.length}`);
+    }
+    return parts.length ? ` (${parts.join(", ")})` : "";
+}
+function emitAgentLoopProgress(emitProgress, phase, event) {
+    if (!emitProgress || !event || typeof event !== "object")
+        return;
+    const e = event;
+    if (e.type === "message_update") {
+        const assistantMessageEvent = e.assistantMessageEvent;
+        if (assistantMessageEvent?.type === "text_delta" && typeof assistantMessageEvent.delta === "string") {
+            emitProgress(assistantMessageEvent.delta);
+        }
+        return;
+    }
+    if (e.type === "tool_execution_start" && typeof e.toolName === "string") {
+        emitProgressLine(emitProgress, `\n[${phase}] ${e.toolName} started`);
+        return;
+    }
+    if (e.type === "tool_execution_end" && typeof e.toolName === "string") {
+        const result = e.result && typeof e.result === "object" ? e.result : undefined;
+        emitProgressLine(emitProgress, `[${phase}] ${e.toolName} complete${compactToolDetails(result?.details ?? result)}`);
+    }
+}
 export function registerCompactionHook(ext, runtime) {
     ext.on("session_before_compact", async (event, ctx) => {
         if (runtime.compactHookInFlight) {
@@ -34,6 +71,8 @@ export function registerCompactionHook(ext, runtime) {
             return await withDebugLogContext({ enabled: runtime.config.debugLog === true, cwd: ctx.cwd, runId }, async () => {
                 const { preparation, branchEntries, signal } = event;
                 const { firstKeptEntryId, tokensBefore } = preparation;
+                const emitProgress = event.emitProgress;
+                emitProgressLine(emitProgress, `Observational memory compaction started on ~${tokensBefore.toLocaleString()} tokens.`);
                 // Capture ctx properties synchronously — after multiple awaits below,
                 // the extension ctx may become stale (e.g. after session replacement/reload).
                 const hasUI = ctx.hasUI;
@@ -47,6 +86,7 @@ export function registerCompactionHook(ext, runtime) {
                     turnLimits,
                     legacyCompactionMaxToolCalls: runtime.config.compactionMaxToolCalls,
                 });
+                emitProgressLine(emitProgress, "Resolving memory model…");
                 const resolved = await runtime.resolveModel(ctx);
                 if (!resolved.ok) {
                     debugLog("compaction.model_unavailable", { reason: resolved.reason });
@@ -56,8 +96,10 @@ export function registerCompactionHook(ext, runtime) {
                     return { cancel: true };
                 }
                 runtime.resolveFailureNotified = false;
+                emitProgressLine(emitProgress, "Memory model ready.");
                 let entries = branchEntries;
                 if (runtime.observerPromise) {
+                    emitProgressLine(emitProgress, "Waiting for in-flight observer…");
                     try {
                         await runtime.observerPromise;
                     }
@@ -72,6 +114,7 @@ export function registerCompactionHook(ext, runtime) {
                     pendingObservations: memoryState.pendingObs.length,
                     reflections: memoryState.reflections.length,
                 });
+                emitProgressLine(emitProgress, `Loaded memory state: ${memoryState.committedObs.length} committed observations, ${memoryState.pendingObs.length} pending observations, ${memoryState.reflections.length} reflections.`);
                 let gapObservationData = null;
                 const gap = gapRawEntries(entries, firstKeptEntryId);
                 if (gap.length > 0) {
@@ -103,6 +146,7 @@ export function registerCompactionHook(ext, runtime) {
                             chunk: gapChunk,
                             allowedSourceEntryIds: sourceEntryIds,
                             signal,
+                            onEvent: (agentEvent) => emitAgentLoopProgress(emitProgress, "observer", agentEvent),
                             maxTurns: turnLimits.observerMaxTurnsPerRun,
                         });
                         const gapPromise = gapCall.then(() => undefined, () => undefined);
@@ -125,6 +169,7 @@ export function registerCompactionHook(ext, runtime) {
                                     records,
                                 });
                                 ext.appendEntry(OBSERVATION_CUSTOM_TYPE, gapObservationData);
+                                emitProgressLine(emitProgress, `Sync catch-up recorded ${records.length} observation${records.length === 1 ? "" : "s"} (~${observationTokens.toLocaleString()} tokens).`);
                                 if (hasUI && ui)
                                     ui.notify(`Observational memory: sync catch-up recorded ${records.length} observation${records.length === 1 ? "" : "s"} (~${observationTokens.toLocaleString()} tokens)`, "info");
                             }
@@ -152,13 +197,15 @@ export function registerCompactionHook(ext, runtime) {
                 const deltaObservationData = collectObservationsByCoverage(entries, priorFirstKeptEntryId, firstKeptEntryId);
                 if (gapObservationData)
                     deltaObservationData.push(gapObservationData);
+                const deltaObservationRecords = deltaObservationData.reduce((sum, data) => sum + data.records.length, 0);
                 debugLog("compaction.delta", {
                     priorFirstKeptEntryId,
                     firstKeptEntryId,
                     deltaObservationEntries: deltaObservationData.length,
-                    deltaObservationRecords: deltaObservationData.reduce((sum, data) => sum + data.records.length, 0),
+                    deltaObservationRecords,
                     gapObservationRecords: gapObservationData?.records.length ?? 0,
                 });
+                emitProgressLine(emitProgress, `Compaction delta contains ${deltaObservationRecords} observation${deltaObservationRecords === 1 ? "" : "s"}.`);
                 if (deltaObservationData.length === 0) {
                     // No new observations since last compaction. If we have existing memory,
                     // carry it forward in a no-op compaction so it survives spectral's compaction.
@@ -175,6 +222,7 @@ export function registerCompactionHook(ext, runtime) {
                         return { cancel: true };
                     }
                     // Carry forward existing memory without running reflector/pruner
+                    emitProgressLine(emitProgress, "No new observations; carrying forward existing memory.");
                     const workingReflections = migrateLegacyReflections(memoryState.reflections);
                     debugLog("compaction.no_delta_carry_forward", {
                         observations: memoryState.committedObs.length,
@@ -206,6 +254,7 @@ export function registerCompactionHook(ext, runtime) {
                     ...deltaObservationData.flatMap((d) => d.records),
                 ];
                 const observationTokens = observationPoolTokens(workingObservations);
+                emitProgressLine(emitProgress, `Working set: ${workingObservations.length} observations, ${workingReflections.length} reflections, ~${observationTokens.toLocaleString()} observation tokens.`);
                 debugLog("compaction.reflect_prune.gate", {
                     observationTokens,
                     reflectionThresholdTokens: runtime.config.reflectionThresholdTokens,
@@ -224,8 +273,16 @@ export function registerCompactionHook(ext, runtime) {
                         });
                         if (hasUI)
                             ui?.notify("Observational memory: running reflector + pruner...", "info");
+                        emitProgressLine(emitProgress, "Running reflector + pruner…");
                         const coverageBefore = coverageTagCounts(workingReflections, workingObservations);
-                        const reflectorResult = await runReflector({ model: resolved.model, apiKey: resolved.apiKey, headers: resolved.headers, signal, maxTurns: turnLimits.reflectorMaxTurnsPerPass }, workingReflections, workingObservations);
+                        const reflectorResult = await runReflector({
+                            model: resolved.model,
+                            apiKey: resolved.apiKey,
+                            headers: resolved.headers,
+                            signal,
+                            onEvent: (agentEvent) => emitAgentLoopProgress(emitProgress, "reflector", agentEvent),
+                            maxTurns: turnLimits.reflectorMaxTurnsPerPass,
+                        }, workingReflections, workingObservations, (pass, maxPasses) => emitProgressLine(emitProgress, `Reflector pass ${pass}/${maxPasses} started.`));
                         finalReflections = reflectorResult.reflections;
                         const coverageAfter = coverageTagCounts(finalReflections, workingObservations);
                         debugLog("compaction.reflector.result", {
@@ -235,7 +292,14 @@ export function registerCompactionHook(ext, runtime) {
                             beforeReflections: workingReflections.length,
                             afterReflections: finalReflections.length,
                         });
-                        const prunerResult = await runPruner({ model: resolved.model, apiKey: resolved.apiKey, headers: resolved.headers, signal, maxTurns: turnLimits.prunerMaxTurnsPerPass }, finalReflections, workingObservations, runtime.config.reflectionThresholdTokens);
+                        const prunerResult = await runPruner({
+                            model: resolved.model,
+                            apiKey: resolved.apiKey,
+                            headers: resolved.headers,
+                            signal,
+                            onEvent: (agentEvent) => emitAgentLoopProgress(emitProgress, "pruner", agentEvent),
+                            maxTurns: turnLimits.prunerMaxTurnsPerPass,
+                        }, finalReflections, workingObservations, runtime.config.reflectionThresholdTokens, (pass, maxPasses) => emitProgressLine(emitProgress, `Pruner pass ${pass}/${maxPasses} started.`));
                         finalObservations = prunerResult.observations;
                         debugLog("compaction.pruner.result", {
                             stopReason: prunerResult.stopReason,
@@ -259,6 +323,7 @@ export function registerCompactionHook(ext, runtime) {
                             ui?.notify(`Observational memory: reflect/prune failed: ${msg}`, "warning");
                     }
                 }
+                emitProgressLine(emitProgress, `Rendering final memory summary from ${finalObservations.length} observations and ${finalReflections.length} reflections…`);
                 const summary = renderSummary(finalReflections, finalObservations);
                 if (finalObservations.length === 0) {
                     throw new Error("invariant violated: finalObservations empty after delta guard");
@@ -275,6 +340,7 @@ export function registerCompactionHook(ext, runtime) {
                     firstKeptEntryId,
                     tokensBefore,
                 });
+                emitProgressLine(emitProgress, `Compaction assembled — ${finalObservations.length} observation${finalObservations.length === 1 ? "" : "s"}, ${finalReflections.length} reflection${finalReflections.length === 1 ? "" : "s"}.`);
                 if (hasUI)
                     ui?.notify(`Observational memory: compaction assembled — ${finalObservations.length} observation${finalObservations.length === 1 ? "" : "s"}, ${finalReflections.length} reflection${finalReflections.length === 1 ? "" : "s"}`, "info");
                 // Promote reflections as project observations (cross-session durable memory).

package/dist/memory/observer.d.ts

@@ -1,4 +1,4 @@
-import { agentLoop } from "../sdk/agent-core/index.js";
+import { agentLoop, type AgentEvent } from "../sdk/agent-core/index.js";
 import type { Model } from "../sdk/ai/index.js";
 import type { ObservationRecord } from "./types.js";
 interface RunObserverArgs {
@@ -11,6 +11,7 @@ interface RunObserverArgs {
     allowedSourceEntryIds: string[];
     signal?: AbortSignal;
     agentLoop?: typeof agentLoop;
+    onEvent?: (event: AgentEvent) => void;
     maxTurns?: number;
 }
 export declare const OBSERVATION_TIMESTAMP_PATTERN = "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}$";

package/dist/memory/observer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../src/memory/observer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAA2D,MAAM,4BAA4B,CAAC;AAChH,OAAO,KAAK,EAAW,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAOzD,OAAO,KAAK,EAAE,iBAAiB,EAAa,MAAM,YAAY,CAAC;AAE/D,UAAU,eAAe;IACxB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AASD,eAAO,MAAM,6BAA6B,mDAAmD,CAAC;AAkC9F,wBAAgB,uBAAuB,CACtC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC7C,qBAAqB,EAAE,SAAS,MAAM,EAAE,GACtC,MAAM,EAAE,GAAG,SAAS,CAYtB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,EAAE,GAAG,SAAS,CAAC,CA+GjG;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAEhF"}
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../src/memory/observer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAqB,KAAK,UAAU,EAAwC,MAAM,4BAA4B,CAAC;AACjI,OAAO,KAAK,EAAW,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAOzD,OAAO,KAAK,EAAE,iBAAiB,EAAa,MAAM,YAAY,CAAC;AAE/D,UAAU,eAAe;IACxB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AASD,eAAO,MAAM,6BAA6B,mDAAmD,CAAC;AAkC9F,wBAAgB,uBAAuB,CACtC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC7C,qBAAqB,EAAE,SAAS,MAAM,EAAE,GACtC,MAAM,EAAE,GAAG,SAAS,CAYtB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,EAAE,GAAG,SAAS,CAAC,CAgHjG;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAEhF"}

package/dist/memory/observer.js

@@ -144,8 +144,9 @@ ${conversation}`;
     };
     const loop = args.agentLoop ?? agentLoop;
     const stream = loop(prompts, context, config, signal);
-    for await (const _event of stream) {
+    for await (const event of stream) {
         // Drain events; the tool's execute already collects records.
+        args.onEvent?.(event);
     }
     await stream.result();
     if (accumulated.size === 0)

package/dist/memory/testing/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Testing utilities for the observational memory pipeline.
+ *
+ * Provides deterministic, seeded random message generation and a faux LLM model
+ * that produces structured tool-call responses for observer, reflector, and pruner,
+ * enabling end-to-end pipeline testing without real API costs.
+ */
+export { SeededRandom } from "./seeded-random.js";
+export { generateRandomText, generateObservationContent, generateReflectionContent, generateTimestamp, type RandomTextOptions, } from "./random-text.js";
+export { createRandomModel, type RandomModelConfig, type RandomModelRegistration, } from "./random-model.js";
+export { generateRandomMessages, populateSession, createInMemoryInjector, type PopulateSessionOptions, type PopulateResult, } from "./populate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACN,kBAAkB,EAClB,0BAA0B,EAC1B,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,iBAAiB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,GACnB,MAAM,eAAe,CAAC"}

package/dist/memory/testing/index.js

@@ -0,0 +1,11 @@
+/**
+ * Testing utilities for the observational memory pipeline.
+ *
+ * Provides deterministic, seeded random message generation and a faux LLM model
+ * that produces structured tool-call responses for observer, reflector, and pruner,
+ * enabling end-to-end pipeline testing without real API costs.
+ */
+export { SeededRandom } from "./seeded-random.js";
+export { generateRandomText, generateObservationContent, generateReflectionContent, generateTimestamp, } from "./random-text.js";
+export { createRandomModel, } from "./random-model.js";
+export { generateRandomMessages, populateSession, createInMemoryInjector, } from "./populate.js";

package/dist/memory/testing/populate.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Session population utilities for testing compaction, reflection, and observation.
+ *
+ * Populates sessions with deterministic random messages to reach target token
+ * counts, enabling efficient stress testing of the full memory pipeline.
+ */
+import type { Message } from "../../sdk/ai/types.js";
+export interface PopulateSessionOptions {
+    /** Seed for reproducible sequences. Default: 42. */
+    seed?: number;
+    /**
+     * Target total tokens in the session.
+     * Messages are generated until this approximate token count is reached.
+     * Token estimation: 4 chars ≈ 1 token.
+     * Default: 20000.
+     */
+    targetTokens?: number;
+    /**
+     * Average tokens per user message. Default: 200.
+     */
+    avgUserTokens?: number;
+    /**
+     * Average tokens per assistant message. Default: 400.
+     */
+    avgAssistantTokens?: number;
+    /**
+     * Ratio of user:assistant messages. Higher = more user messages per assistant.
+     * Default: 0.8 (80% user, 20% assistant).
+     */
+    userMessageRatio?: number;
+    /**
+     * Include tool result messages between assistant turns. Default: false.
+     */
+    includeToolResults?: boolean;
+    /**
+     * Callback for each generated message. Useful for progress reporting.
+     */
+    onMessage?: (index: number, totalEstimated: number, role: string, charCount: number) => void;
+}
+export interface PopulateResult {
+    /** Total messages generated. */
+    messageCount: number;
+    /** Estimated total tokens (chars / 4). */
+    estimatedTokens: number;
+    /** Total characters generated. */
+    totalChars: number;
+    /** Breakdown by role. */
+    breakdown: {
+        user: number;
+        assistant: number;
+        toolResult: number;
+    };
+}
+interface SessionInjector {
+    appendMessage(message: Message): void | Promise<void>;
+}
+/**
+ * Generate an array of random messages totaling approximately `targetTokens` tokens.
+ *
+ * Does NOT require a session — returns the message array for injection into
+ * any session or storage system.
+ *
+ * Token estimation: Math.ceil(text.length / 4).
+ */
+export declare function generateRandomMessages(options?: PopulateSessionOptions): {
+    messages: Message[];
+    result: PopulateResult;
+};
+/**
+ * Populate a session-like object with random messages.
+ *
+ * The injector must implement `appendMessage(message)`.
+ * This works with any session manager that exposes message-append capability.
+ *
+ * @example
+ * ```typescript
+ * const injector = {
+ *   appendMessage(msg: Message) { sessionManager.appendMessage(msg); }
+ * };
+ * const result = await populateSession(injector, { targetTokens: 20000, seed: 42 });
+ * console.log(`Populated ${result.messageCount} messages, ~${result.estimatedTokens} tokens`);
+ * ```
+ */
+export declare function populateSession(injector: SessionInjector, options?: PopulateSessionOptions): Promise<PopulateResult>;
+/**
+ * Create an in-memory message array injector. Useful for testing without a real session.
+ */
+export declare function createInMemoryInjector(): {
+    messages: Message[];
+    injector: SessionInjector;
+};
+export {};
+//# sourceMappingURL=populate.d.ts.map

package/dist/memory/testing/populate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"populate.d.ts","sourceRoot":"","sources":["../../../src/memory/testing/populate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAW,OAAO,EAA4C,MAAM,uBAAuB,CAAC;AAMxG,MAAM,WAAW,sBAAsB;IACtC,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7F;AAED,MAAM,WAAW,cAAc;IAC9B,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAcD,UAAU,eAAe;IACxB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AA0CD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,GAAG;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CA8C5H;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACpC,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,sBAA2B,GAClC,OAAO,CAAC,cAAc,CAAC,CAMzB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,CAU3F"}

package/dist/memory/testing/populate.js

@@ -0,0 +1,177 @@
+/**
+ * Session population utilities for testing compaction, reflection, and observation.
+ *
+ * Populates sessions with deterministic random messages to reach target token
+ * counts, enabling efficient stress testing of the full memory pipeline.
+ */
+import { fauxAssistantMessage } from "../../sdk/ai/providers/faux.js";
+import { SeededRandom } from "./seeded-random.js";
+import { generateRandomText, generateObservationContent } from "./random-text.js";
+// ── Internal helpers ──────────────────────────────────────────────────────────
+const DEFAULT_POPULATE_OPTIONS = {
+    seed: 42,
+    targetTokens: 20000,
+    avgUserTokens: 200,
+    avgAssistantTokens: 400,
+    userMessageRatio: 0.8,
+    includeToolResults: false,
+    onMessage: () => { },
+};
+/**
+ * Generate a single random user message.
+ */
+function generateUserMessage(rng, targetChars) {
+    const text = generateRandomText(rng, { targetChars });
+    return {
+        role: "user",
+        content: [{ type: "text", text }],
+        timestamp: Date.now() - rng.nextInt(0, 7 * 24 * 60 * 60 * 1000),
+    };
+}
+/**
+ * Generate a single random assistant message.
+ */
+function generateAssistantMessage(rng, targetChars) {
+    const text = generateRandomText(rng, { targetChars });
+    return fauxAssistantMessage(text, {
+        stopReason: rng.chance(0.9) ? "stop" : "length",
+        timestamp: Date.now() - rng.nextInt(0, 7 * 24 * 60 * 60 * 1000),
+    });
+}
+/**
+ * Generate a single random tool result message.
+ */
+function generateToolResultMessage(rng) {
+    const text = generateObservationContent(rng);
+    return {
+        role: "toolResult",
+        toolCallId: `tool_${rng.hexId(8)}`,
+        toolName: rng.pick(["read", "bash", "grep", "write", "execute"]),
+        content: [{ type: "text", text }],
+        isError: rng.chance(0.1),
+        timestamp: Date.now() - rng.nextInt(0, 7 * 24 * 60 * 60 * 1000),
+    };
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Generate an array of random messages totaling approximately `targetTokens` tokens.
+ *
+ * Does NOT require a session — returns the message array for injection into
+ * any session or storage system.
+ *
+ * Token estimation: Math.ceil(text.length / 4).
+ */
+export function generateRandomMessages(options = {}) {
+    const opts = { ...DEFAULT_POPULATE_OPTIONS, ...options };
+    const rng = new SeededRandom(opts.seed);
+    const targetChars = opts.targetTokens * 4;
+    const messages = [];
+    let totalChars = 0;
+    const breakdown = { user: 0, assistant: 0, toolResult: 0 };
+    let index = 0;
+    while (totalChars < targetChars) {
+        const remainingChars = targetChars - totalChars;
+        const isUser = rng.next() < opts.userMessageRatio;
+        let message;
+        if (isUser) {
+            const chars = Math.min(opts.avgUserTokens * 4, remainingChars);
+            const variedChars = Math.max(20, chars + rng.nextInt(-Math.floor(chars * 0.3), Math.floor(chars * 0.3)));
+            message = generateUserMessage(rng, variedChars);
+            breakdown.user++;
+        }
+        else if (opts.includeToolResults && rng.chance(0.15)) {
+            message = generateToolResultMessage(rng);
+            breakdown.toolResult++;
+        }
+        else {
+            const chars = Math.min(opts.avgAssistantTokens * 4, remainingChars);
+            const variedChars = Math.max(20, chars + rng.nextInt(-Math.floor(chars * 0.3), Math.floor(chars * 0.3)));
+            message = generateAssistantMessage(rng, variedChars);
+            breakdown.assistant++;
+        }
+        const messageChars = estimateMessageChars(message);
+        totalChars += messageChars;
+        messages.push(message);
+        index++;
+        opts.onMessage(index, Math.ceil(totalChars / 4), message.role, messageChars);
+    }
+    return {
+        messages,
+        result: {
+            messageCount: messages.length,
+            estimatedTokens: Math.ceil(totalChars / 4),
+            totalChars,
+            breakdown,
+        },
+    };
+}
+/**
+ * Populate a session-like object with random messages.
+ *
+ * The injector must implement `appendMessage(message)`.
+ * This works with any session manager that exposes message-append capability.
+ *
+ * @example
+ * ```typescript
+ * const injector = {
+ *   appendMessage(msg: Message) { sessionManager.appendMessage(msg); }
+ * };
+ * const result = await populateSession(injector, { targetTokens: 20000, seed: 42 });
+ * console.log(`Populated ${result.messageCount} messages, ~${result.estimatedTokens} tokens`);
+ * ```
+ */
+export async function populateSession(injector, options = {}) {
+    const { messages, result } = generateRandomMessages(options);
+    for (const message of messages) {
+        await injector.appendMessage(message);
+    }
+    return result;
+}
+/**
+ * Create an in-memory message array injector. Useful for testing without a real session.
+ */
+export function createInMemoryInjector() {
+    const messages = [];
+    return {
+        messages,
+        injector: {
+            appendMessage(message) {
+                messages.push(message);
+            },
+        },
+    };
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function estimateMessageChars(message) {
+    if (message.role === "user" || message.role === "toolResult") {
+        const content = message.content;
+        if (typeof content === "string")
+            return content.length;
+        if (Array.isArray(content)) {
+            return content.reduce((sum, block) => {
+                if (block.type === "text" && "text" in block) {
+                    return sum + block.text.length;
+                }
+                return sum;
+            }, 0);
+        }
+        return 0;
+    }
+    if (message.role === "assistant") {
+        const content = message.content;
+        if (typeof content === "string")
+            return content.length;
+        if (Array.isArray(content)) {
+            return content.reduce((sum, block) => {
+                if (block.type === "text" && block.text)
+                    return sum + block.text.length;
+                if (block.type === "thinking" && block.thinking)
+                    return sum + block.thinking.length;
+                if (block.type === "toolCall" && block.arguments)
+                    return sum + JSON.stringify(block.arguments).length;
+                return sum;
+            }, 0);
+        }
+    }
+    return 0;
+}

package/dist/memory/testing/random-model.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Random testing model built on the faux provider.
+ *
+ * Generates deterministic, structured LLM-like responses that exercise the
+ * full observational memory pipeline (observer → reflector → pruner → compaction)
+ * without real LLM API calls.
+ *
+ * The model inspects the tool definitions in the context to decide what kind
+ * of response to generate:
+ *  - `record_observations` → generates observation batches with source entry IDs
+ *  - `record_reflections` → generates reflection proposals with supporting IDs
+ *  - `drop_observations`   → generates drop-lists with observation IDs
+ *  - No tool / unknown     → generates plain text
+ */
+import { type FauxProviderRegistration } from "../../sdk/ai/providers/faux.js";
+import { SeededRandom } from "./seeded-random.js";
+export interface RandomModelConfig {
+    /** Seed for reproducible sequences. Default: 42. */
+    seed?: number;
+    /** Target character count per assistant text response. Default: 500. */
+    textTargetChars?: number;
+    /** Number of observation batches per observer run. Default: 2-4 (random). */
+    observationBatches?: {
+        min: number;
+        max: number;
+    };
+    /** Observations per batch. Default: 2-5 (random). */
+    observationsPerBatch?: {
+        min: number;
+        max: number;
+    };
+    /** Number of reflection batches per reflector pass. Default: 1-3. */
+    reflectionBatches?: {
+        min: number;
+        max: number;
+    };
+    /** Reflections per batch. Default: 1-3. */
+    reflectionsPerBatch?: {
+        min: number;
+        max: number;
+    };
+    /** Number of drop calls per pruner pass. Default: 1-3. */
+    prunerDropCalls?: {
+        min: number;
+        max: number;
+    };
+    /** IDs to drop per call. Default: 1-5. */
+    prunerIdsPerCall?: {
+        min: number;
+        max: number;
+    };
+    /** Tokens per second for streaming simulation. Default: 0 (instant). */
+    tokensPerSecond?: number;
+}
+export interface RandomModelRegistration {
+    provider: FauxProviderRegistration;
+    config: Required<RandomModelConfig>;
+    /** The seeded RNG for direct use by tests. */
+    rng: SeededRandom;
+}
+/**
+ * Register a deterministic random model as a faux provider.
+ *
+ * The model automatically detects which tools are in the context and generates
+ * appropriate structured responses for the observer, reflector, and pruner.
+ *
+ * @example
+ * ```typescript
+ * const testModel = createRandomModel({ seed: 123 });
+ * // Use testModel.provider.getModel() in agentLoop calls
+ * // After testing: testModel.provider.unregister()
+ * ```
+ */
+export declare function createRandomModel(config?: RandomModelConfig): RandomModelRegistration;
+//# sourceMappingURL=random-model.d.ts.map

package/dist/memory/testing/random-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-model.d.ts","sourceRoot":"","sources":["../../../src/memory/testing/random-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAON,KAAK,wBAAwB,EAC7B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUlD,MAAM,WAAW,iBAAiB;IACjC,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,qDAAqD;IACrD,oBAAoB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,qEAAqE;IACrE,iBAAiB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,2CAA2C;IAC3C,mBAAmB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,0DAA0D;IAC1D,eAAe,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AA4MD,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,wBAAwB,CAAC;IACnC,MAAM,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACpC,8CAA8C;IAC9C,GAAG,EAAE,YAAY,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,iBAAsB,GAAG,uBAAuB,CA6CzF"}