@aexol/spectral 0.9.10 → 0.9.13

package/dist/memory/testing/random-model.js

@@ -0,0 +1,237 @@
+/**
+ * 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 { fauxAssistantMessage, fauxText, fauxThinking, fauxToolCall, registerFauxProvider, } from "../../sdk/ai/providers/faux.js";
+import { SeededRandom } from "./seeded-random.js";
+import { generateRandomText, generateObservationContent, generateReflectionContent, generateTimestamp, } from "./random-text.js";
+/**
+ * Pick `count` random IDs from `availableIds`. If fewer available than count,
+ * returns all available.
+ */
+function pickRandomIds(rng, availableIds, count) {
+    if (availableIds.length === 0)
+        return [];
+    const pool = [...availableIds];
+    rng.shuffle(pool);
+    return pool.slice(0, Math.min(count, pool.length));
+}
+/**
+ * Extract observation IDs from the context messages.
+ * Looks for source entry IDs in user messages or observation lists.
+ */
+function extractObservationIds(context) {
+    const ids = new Set();
+    for (const msg of context.messages) {
+        const text = typeof msg.content === "string"
+            ? msg.content
+            : Array.isArray(msg.content)
+                ? msg.content
+                    .filter((b) => b.type === "text")
+                    .map((b) => b.text)
+                    .join("\n")
+                : "";
+        // Match 12-char hex IDs from observation lists or source entry labels
+        const matches = text.matchAll(/\b([a-f0-9]{12})\b/g);
+        for (const m of matches)
+            ids.add(m[1]);
+    }
+    return Array.from(ids);
+}
+/**
+ * Extract available source entry IDs from the user prompt.
+ */
+function extractSourceEntryIds(context) {
+    const ids = new Set();
+    for (const msg of context.messages) {
+        if (msg.role !== "user")
+            continue;
+        const text = typeof msg.content === "string"
+            ? msg.content
+            : Array.isArray(msg.content)
+                ? msg.content.filter((b) => b.type === "text").map((b) => b.text).join("\n")
+                : "";
+        // Match "[Source entry id: <id>]" — the id can contain any chars except brackets
+        const matches = text.matchAll(/\[?Source entry id:\s*([^\]]+)\]?/gi);
+        for (const m of matches) {
+            const id = m[1].trim();
+            if (id)
+                ids.add(id);
+        }
+    }
+    return Array.from(ids);
+}
+function hasToolNamed(context, name) {
+    return context.tools?.some((t) => t.name === name) ?? false;
+}
+// ── Response factories per tool set ───────────────────────────────────────────
+/**
+ * Generate observer-like responses: one or more `record_observations` tool calls
+ * followed by a short confirmation text.
+ */
+function createObserverResponse(ctx, _options, state, model, factoryState) {
+    const { rng, config } = factoryState;
+    const sourceIds = extractSourceEntryIds(ctx);
+    const batches = rng.nextInt(config.observationBatches.min, config.observationBatches.max);
+    // If we have no source IDs, generate some synthetic ones
+    if (sourceIds.length === 0) {
+        for (let i = 0; i < 10; i++)
+            sourceIds.push(rng.hexId(12));
+    }
+    const content = [];
+    for (let b = 0; b < batches; b++) {
+        const obsCount = rng.nextInt(config.observationsPerBatch.min, config.observationsPerBatch.max);
+        const observations = Array.from({ length: obsCount }, () => ({
+            timestamp: generateTimestamp(rng),
+            content: generateObservationContent(rng),
+            relevance: rng.pick(["low", "medium", "high", "critical"]),
+            sourceEntryIds: pickRandomIds(rng, sourceIds, rng.nextInt(1, Math.min(3, sourceIds.length))),
+        }));
+        content.push(fauxToolCall("record_observations", { observations: observations.length > 0 ? observations : [] }, { id: rng.hexId(8) }));
+    }
+    // Final confirmation text
+    content.push(fauxText(generateRandomText(rng, { targetChars: Math.min(config.textTargetChars, 200), includeCode: false, includeMarkdown: false })));
+    return fauxAssistantMessage(content, { stopReason: "stop" });
+}
+/**
+ * Generate reflector-like responses: one or more `record_reflections` tool calls
+ * followed by a short confirmation.
+ */
+function createReflectorResponse(ctx, _options, state, model, factoryState) {
+    const { rng, config } = factoryState;
+    const observationIds = extractObservationIds(ctx);
+    const batches = rng.nextInt(config.reflectionBatches.min, config.reflectionBatches.max);
+    if (observationIds.length === 0) {
+        for (let i = 0; i < 10; i++)
+            observationIds.push(rng.hexId(12));
+    }
+    const content = [];
+    for (let b = 0; b < batches; b++) {
+        const refCount = rng.nextInt(config.reflectionsPerBatch.min, config.reflectionsPerBatch.max);
+        const reflections = Array.from({ length: refCount }, () => ({
+            content: generateReflectionContent(rng),
+            supportingObservationIds: pickRandomIds(rng, observationIds, rng.nextInt(1, Math.min(3, observationIds.length))),
+        }));
+        content.push(fauxToolCall("record_reflections", { reflections: reflections.length > 0 ? reflections : [] }, { id: rng.hexId(8) }));
+    }
+    content.push(fauxText("Reflection pass complete. All stable patterns crystallized."));
+    return fauxAssistantMessage(content, { stopReason: "stop" });
+}
+/**
+ * Generate pruner-like responses: one or more `drop_observations` tool calls
+ * followed by a short confirmation.
+ */
+function createPrunerResponse(ctx, _options, state, model, factoryState) {
+    const { rng, config } = factoryState;
+    const observationIds = extractObservationIds(ctx);
+    const calls = rng.nextInt(config.prunerDropCalls.min, config.prunerDropCalls.max);
+    if (observationIds.length === 0) {
+        for (let i = 0; i < 10; i++)
+            observationIds.push(rng.hexId(12));
+    }
+    const content = [];
+    // Only make drop calls if we have enough IDs
+    if (observationIds.length > 3) {
+        const remaining = [...observationIds];
+        for (let c = 0; c < calls && remaining.length > 0; c++) {
+            const dropCount = Math.min(rng.nextInt(config.prunerIdsPerCall.min, config.prunerIdsPerCall.max), remaining.length);
+            const dropIds = pickRandomIds(rng, remaining, dropCount);
+            // Remove dropped IDs from remaining pool
+            for (const id of dropIds) {
+                const idx = remaining.indexOf(id);
+                if (idx >= 0)
+                    remaining.splice(idx, 1);
+            }
+            content.push(fauxToolCall("drop_observations", { ids: dropIds, reason: "Redundant or low-relevance observation" }, { id: rng.hexId(8) }));
+        }
+    }
+    content.push(fauxText("Pruning complete. Kept observations are within budget."));
+    return fauxAssistantMessage(content, { stopReason: "stop" });
+}
+/**
+ * Generate a generic assistant response (no tool calls).
+ */
+function createGenericResponse(ctx, _options, state, model, factoryState) {
+    const { rng, config } = factoryState;
+    const text = generateRandomText(rng, { targetChars: config.textTargetChars });
+    // Occasionally add thinking blocks
+    if (rng.chance(0.3)) {
+        const thinkingText = generateRandomText(rng, { targetChars: Math.min(config.textTargetChars / 2, 300), includeCode: false, includeMarkdown: false });
+        return fauxAssistantMessage([fauxThinking(thinkingText), fauxText(text)], { stopReason: "stop" });
+    }
+    return fauxAssistantMessage(text, { stopReason: "stop" });
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+const DEFAULT_CONFIG = {
+    seed: 42,
+    textTargetChars: 500,
+    observationBatches: { min: 2, max: 4 },
+    observationsPerBatch: { min: 2, max: 5 },
+    reflectionBatches: { min: 1, max: 3 },
+    reflectionsPerBatch: { min: 1, max: 3 },
+    prunerDropCalls: { min: 1, max: 3 },
+    prunerIdsPerCall: { min: 1, max: 5 },
+    tokensPerSecond: 0,
+};
+/**
+ * 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 function createRandomModel(config = {}) {
+    const merged = { ...DEFAULT_CONFIG, ...config };
+    const rng = new SeededRandom(merged.seed);
+    const factoryState = { rng, callCount: 0, config: merged };
+    const responseFactory = (ctx, opts, state, model) => {
+        factoryState.callCount = state.callCount;
+        // Detect tool set from context
+        const isObserver = hasToolNamed(ctx, "record_observations") && !hasToolNamed(ctx, "record_reflections") && !hasToolNamed(ctx, "drop_observations");
+        const isReflector = hasToolNamed(ctx, "record_reflections");
+        const isPruner = hasToolNamed(ctx, "drop_observations");
+        if (isPruner) {
+            return createPrunerResponse(ctx, opts, state, model, factoryState);
+        }
+        if (isReflector) {
+            return createReflectorResponse(ctx, opts, state, model, factoryState);
+        }
+        if (isObserver) {
+            return createObserverResponse(ctx, opts, state, model, factoryState);
+        }
+        return createGenericResponse(ctx, opts, state, model, factoryState);
+    };
+    const provider = registerFauxProvider({
+        api: "random-test",
+        provider: "random-test",
+        models: [
+            {
+                id: "random-test-1",
+                name: "Random Test Model",
+                reasoning: false,
+                input: ["text"],
+                contextWindow: 128000,
+                maxTokens: 16384,
+            },
+        ],
+        tokensPerSecond: merged.tokensPerSecond,
+    });
+    provider.setResponses([responseFactory]);
+    return { provider, config: merged, rng };
+}

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

@@ -0,0 +1,27 @@
+import { SeededRandom } from "./seeded-random.js";
+export interface RandomTextOptions {
+    /** Approximate target in characters (4 chars ≈ 1 token). Default: 1000. */
+    targetChars?: number;
+    /** Include code blocks. Default: true. */
+    includeCode?: boolean;
+    /** Include markdown formatting. Default: true. */
+    includeMarkdown?: boolean;
+}
+/**
+ * Generate realistic-looking coding conversation text of approximately
+ * `targetChars` length using a seeded PRNG.
+ */
+export declare function generateRandomText(rng: SeededRandom, options?: RandomTextOptions): string;
+/**
+ * Generate a short observation-like sentence (single line, plain prose).
+ */
+export declare function generateObservationContent(rng: SeededRandom): string;
+/**
+ * Generate a short reflection-like sentence (single line, plain prose, no markdown).
+ */
+export declare function generateReflectionContent(rng: SeededRandom): string;
+/**
+ * Generate a random timestamp in "YYYY-MM-DD HH:MM" format within the last 30 days.
+ */
+export declare function generateTimestamp(rng: SeededRandom): string;
+//# sourceMappingURL=random-text.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"random-text.d.ts","sourceRoot":"","sources":["../../../src/memory/testing/random-text.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiKlD,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kDAAkD;IAClD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAsC7F;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAWpE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CASnE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAU3D"}

package/dist/memory/testing/random-text.js

@@ -0,0 +1,216 @@
+// ── Vocabulary pools ──────────────────────────────────────────────────────────
+const ADJECTIVES = [
+    "scalable", "robust", "efficient", "optimized", "modular", "reactive",
+    "asynchronous", "declarative", "immutable", "lazy", "composable", "resilient",
+    "distributed", "event-driven", "type-safe", "concurrent", "atomic", "idempotent",
+    "deterministic", "pluggable", "extensible", "portable", "minimal", "pragmatic",
+];
+const VERBS = [
+    "implement", "refactor", "optimize", "extract", "introduce", "migrate",
+    "configure", "integrate", "expose", "consume", "validate", "serialize",
+    "normalize", "delegate", "compose", "resolve", "intercept", "propagate",
+    "coalesce", "deduplicate", "authorize", "authenticate", "transform", "stream",
+];
+const NOUNS = [
+    "handler", "middleware", "resolver", "provider", "adapter", "factory",
+    "registry", "pipeline", "orchestrator", "dispatcher", "serializer", "validator",
+    "cache layer", "event bus", "message queue", "connection pool", "rate limiter",
+    "circuit breaker", "feature flag", "policy engine", "auth gateway", "data mapper",
+    "task scheduler", "log aggregator",
+];
+const FILE_NAMES = [
+    "auth-service.ts", "database-client.ts", "api-gateway.ts", "event-handler.ts",
+    "cache-manager.ts", "config-loader.ts", "schema-validator.ts", "rate-limiter.ts",
+    "task-queue.ts", "websocket-manager.ts", "session-store.ts", "token-refresher.ts",
+    "metrics-collector.ts", "feature-flags.ts", "logging-middleware.ts",
+    "error-boundary.tsx", "use-auth.ts", "data-table.tsx", "form-validator.ts",
+    "app-router.ts", "query-builder.ts", "connection-pool.ts", "migration-runner.ts",
+];
+const FILE_PATHS = [
+    "src/services", "src/middleware", "src/handlers", "src/utils",
+    "packages/core/src", "packages/shared/src", "lib/infrastructure",
+    "app/api", "app/components", "app/hooks", "src/integrations",
+    "src/database/migrations", "src/queue", "src/cache",
+];
+const TECH_TERMS = [
+    "TypeScript", "GraphQL", "Prisma", "PostgreSQL", "Redis",
+    "Next.js", "React", "Node.js", "Deno", "WebSocket",
+    "REST", "gRPC", "Protobuf", "JWT", "OAuth2",
+    "Kubernetes", "Docker", "Terraform", "Prometheus", "Grafana",
+    "Kafka", "RabbitMQ", "S3", "CDN", "Edge Functions",
+];
+const ERROR_MESSAGES = [
+    "Cannot read properties of undefined",
+    "Connection refused",
+    "Request timeout after 30s",
+    "Unauthorized: invalid token",
+    "Rate limit exceeded",
+    "Database deadlock detected",
+    "Circuit breaker open",
+    "Cache miss on hot key",
+    "Schema validation failed",
+    "Out of memory",
+];
+const PUNCTUATION = [".", ".", ".", "!", "?"];
+// ── Code snippet generation ───────────────────────────────────────────────────
+function generateFunction(rng) {
+    const name = rng.pick(["handle", "process", "transform", "resolve", "validate", "execute", "create", "update", "delete", "fetch"])
+        + rng.pick(NOUNS).replace(/ /g, "").replace(/-/g, "");
+    const paramCount = rng.nextInt(1, 3);
+    const params = rng.pickN(["input", "context", "options", "config", "payload", "request", "id", "key"], paramCount)
+        .map((p, i) => `${p}: ${rng.pick(["string", "number", "Record<string, unknown>", "Promise<void>"])}`)
+        .join(", ");
+    const returnType = rng.chance(0.6) ? `: ${rng.pick(["Promise<void>", "string", "boolean", "Result", "void"])}` : "";
+    const bodyLines = rng.nextInt(2, 5);
+    const body = Array.from({ length: bodyLines }, () => {
+        const pattern = rng.nextInt(0, 3);
+        if (pattern === 0)
+            return `  const ${rng.pick(["result", "data", "entry", "value", "key"])} = await ${rng.pick(["fetch", "read", "query", "resolve", "validate"])}(${rng.pick(["input", "config", "options", "context"])});`;
+        if (pattern === 1)
+            return `  if (!${rng.pick(["result", "data", "input", "config"])}) throw new Error("${rng.pick(ERROR_MESSAGES)}");`;
+        return `  return ${rng.pick(["result", "data", "{ ...input, processed: true }", "undefined", "null"])};`;
+    }).join("\n");
+    return `async function ${name}(${params})${returnType} {\n${body}\n}`;
+}
+function generateInterface(rng) {
+    const name = "I" + rng.pick(["Config", "Options", "Context", "Result", "Payload", "State", "Props"]);
+    const fieldCount = rng.nextInt(2, 5);
+    const fields = Array.from({ length: fieldCount }, () => {
+        const fieldName = rng.pick(["id", "name", "type", "value", "config", "options", "enabled", "timeout", "url", "key"]);
+        const fieldType = rng.pick(["string", "number", "boolean", "Record<string, unknown>", "string[]", "Partial<Config>"]);
+        const optional = rng.chance(0.4) ? "?" : "";
+        return `  ${fieldName}${optional}: ${fieldType};`;
+    }).join("\n");
+    return `interface ${name} {\n${fields}\n}`;
+}
+function generateImportBlock(rng) {
+    const count = rng.nextInt(1, 4);
+    return Array.from({ length: count }, () => {
+        const module = rng.pick(FILE_PATHS) + "/" + rng.pick(FILE_NAMES).replace(".ts", "");
+        const imports = rng.pickN(["parse", "validate", "createClient", "configure", "resolve", "serialize", "normalize", "buildContext"], rng.nextInt(1, 3));
+        return `import { ${imports.join(", ")} } from "${module}";`;
+    }).join("\n");
+}
+// ── Prose generation ──────────────────────────────────────────────────────────
+function generateSentence(rng) {
+    const templates = [
+        () => `We should ${rng.pick(VERBS)} the ${rng.pick(NOUNS)} to make it more ${rng.pick(ADJECTIVES)}.`,
+        () => `The ${rng.pick(NOUNS)} currently ${rng.pick(["lacks", "needs", "requires", "would benefit from"])} a ${rng.pick(ADJECTIVES)} ${rng.pick(["approach", "design", "implementation", "refactor", "strategy"])}.`,
+        () => `After reviewing the ${rng.pick(FILE_NAMES)}, I think we need to ${rng.pick(VERBS)} ${rng.pick(["the", "our", "this", "the core"])} ${rng.pick(NOUNS)}.`,
+        () => `${rng.pick(TECH_TERMS)} integration with the ${rng.pick(NOUNS)} ${rng.pick(["is", "seems", "looks", "appears"])} ${rng.pick(["straightforward", "tricky", "promising", "problematic", "well-designed"])}.`,
+        () => `Consider using ${rng.pick(TECH_TERMS)} for ${rng.pick(["caching", "messaging", "logging", "monitoring", "authentication", "scheduling"])} instead of the current ${rng.pick(["approach", "solution", "implementation", "pattern"])}.`,
+        () => `The ${rng.pick(["performance", "reliability", "maintainability", "testability"])} of ${rng.pick(FILE_NAMES)} could be improved by ${rng.pick(["adding", "removing", "refactoring", "extracting", "caching"])} the ${rng.pick(NOUNS)}.`,
+        () => `One concern is ${rng.pick(["error handling", "state management", "type safety", "concurrency", "data consistency"])} in the ${rng.pick(NOUNS)} when ${rng.pick(["dealing with", "handling", "processing", "transforming"])} ${rng.pick(["large payloads", "edge cases", "concurrent requests", "nested data", "streaming responses"])}.`,
+    ];
+    return rng.pick(templates)();
+}
+function generateParagraph(rng, sentenceCount = 0) {
+    const count = sentenceCount || rng.nextInt(2, 5);
+    return Array.from({ length: count }, () => generateSentence(rng)).join(" ");
+}
+function generateMarkdownSection(rng) {
+    const headingLevel = rng.nextInt(1, 3);
+    const headingText = rng.pick([
+        "Architecture Overview",
+        "Implementation Details",
+        "Error Handling",
+        "Performance Considerations",
+        "Testing Strategy",
+        "Migration Plan",
+        "Configuration",
+        "API Design",
+        "Security Model",
+        "Data Flow",
+    ]);
+    const heading = "#".repeat(headingLevel) + " " + headingText;
+    const paragraphs = rng.nextInt(1, 3);
+    const body = Array.from({ length: paragraphs }, () => generateParagraph(rng)).join("\n\n");
+    const includeCode = rng.chance(0.7);
+    const codeBlock = includeCode
+        ? "\n\n```typescript\n" + (rng.chance(0.5) ? generateFunction(rng) : generateInterface(rng)) + "\n```"
+        : "";
+    const includeList = rng.chance(0.4);
+    const listBlock = includeList
+        ? "\n\n" + Array.from({ length: rng.nextInt(2, 4) }, () => `- ${generateSentence(rng)}`).join("\n")
+        : "";
+    return heading + "\n\n" + body + codeBlock + listBlock;
+}
+/**
+ * Generate realistic-looking coding conversation text of approximately
+ * `targetChars` length using a seeded PRNG.
+ */
+export function generateRandomText(rng, options = {}) {
+    const targetChars = options.targetChars ?? 1000;
+    const includeMarkdown = options.includeMarkdown ?? true;
+    const includeCode = options.includeCode ?? true;
+    const parts = [];
+    // Start with imports if code is included
+    if (includeCode && rng.chance(0.6)) {
+        parts.push(generateImportBlock(rng));
+    }
+    // Generate content until we hit the target
+    let charCount = parts.join("\n\n").length;
+    let iterations = 0;
+    const maxIterations = 500;
+    while (charCount < targetChars && iterations < maxIterations) {
+        iterations++;
+        if (includeMarkdown && rng.chance(0.4)) {
+            parts.push(generateMarkdownSection(rng));
+        }
+        else if (includeCode && rng.chance(0.5)) {
+            parts.push("```typescript\n" + (rng.chance(0.5) ? generateFunction(rng) : generateInterface(rng)) + "\n```");
+        }
+        else {
+            parts.push(generateParagraph(rng, rng.nextInt(1, 4)));
+        }
+        charCount = parts.join("\n\n").length;
+    }
+    // Trim if we overshot
+    let result = parts.join("\n\n");
+    if (result.length > targetChars * 1.2) {
+        result = result.slice(0, targetChars);
+    }
+    return result;
+}
+/**
+ * Generate a short observation-like sentence (single line, plain prose).
+ */
+export function generateObservationContent(rng) {
+    const templates = [
+        () => `The ${rng.pick(NOUNS)} was ${rng.pick(VERBS)}ed using a ${rng.pick(ADJECTIVES)} approach with ${rng.pick(TECH_TERMS)}.`,
+        () => `User requested ${rng.pick(VERBS)}ing the ${rng.pick(NOUNS)} to support ${rng.pick(TECH_TERMS)} integration.`,
+        () => `Assistant identified ${rng.pick(["a bug", "a performance issue", "a type error", "a race condition", "a memory leak"])} in ${rng.pick(FILE_NAMES)}.`,
+        () => `Codebase uses ${rng.pick(TECH_TERMS)} for ${rng.pick(["caching", "state management", "data fetching", "authentication", "logging"])}.`,
+        () => `Configuration for ${rng.pick(NOUNS)} is stored in ${rng.pick([".env", "config.ts", "settings.json", "deno.json", "tsconfig.json"])}.`,
+        () => `Test suite for ${rng.pick(FILE_NAMES)} covers ${rng.pick(["unit", "integration", "e2e", "snapshot", "performance"])} scenarios.`,
+        () => `Migration from ${rng.pick(TECH_TERMS)} to ${rng.pick(TECH_TERMS)} ${rng.pick(["is in progress", "was completed", "is planned", "was discussed"])}.`,
+    ];
+    return rng.pick(templates)();
+}
+/**
+ * Generate a short reflection-like sentence (single line, plain prose, no markdown).
+ */
+export function generateReflectionContent(rng) {
+    const templates = [
+        () => `The project uses a ${rng.pick(ADJECTIVES)} ${rng.pick(NOUNS)} pattern with ${rng.pick(TECH_TERMS)} for ${rng.pick(["caching", "messaging", "scheduling", "validation", "serialization"])}.`,
+        () => `${rng.pick(TECH_TERMS)} is the ${rng.pick(["primary", "secondary", "recommended", "preferred"])} ${rng.pick(["database", "cache", "queue", "storage", "runtime"])} for this ${rng.pick(["project", "service", "module", "pipeline"])}.`,
+        () => `All ${rng.pick(["API routes", "database queries", "file operations", "network calls", "user inputs"])} must be ${rng.pick(["validated", "authorized", "sanitized", "logged", "metered"])} before ${rng.pick(["processing", "execution", "storage", "propagation", "transmission"])}.`,
+        () => `The ${rng.pick(["frontend", "backend", "CLI", "SDK", "worker"])} communicates with the ${rng.pick(["API", "database", "cache", "queue", "file system"])} via ${rng.pick(["REST", "GraphQL", "gRPC", "WebSocket", "direct connection"])}.`,
+        () => `Error handling follows a ${rng.pick(["centralized", "distributed", "layered", "domain-specific", "functional"])} pattern using ${rng.pick(["custom error classes", "result types", "error boundaries", "middleware", "try-catch blocks"])}.`,
+    ];
+    return rng.pick(templates)();
+}
+/**
+ * Generate a random timestamp in "YYYY-MM-DD HH:MM" format within the last 30 days.
+ */
+export function generateTimestamp(rng) {
+    const now = Date.now();
+    const offset = rng.nextInt(0, 30 * 24 * 60 * 60 * 1000);
+    const date = new Date(now - offset);
+    const yyyy = date.getFullYear();
+    const mm = String(date.getMonth() + 1).padStart(2, "0");
+    const dd = String(date.getDate()).padStart(2, "0");
+    const hh = String(date.getHours()).padStart(2, "0");
+    const min = String(date.getMinutes()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd} ${hh}:${min}`;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Seeded pseudo-random number generator using the mulberry32 algorithm.
+ * Produces deterministic sequences for reproducible test runs.
+ */
+export declare class SeededRandom {
+    private state;
+    constructor(seed: number);
+    /** Returns a float in [0, 1). */
+    next(): number;
+    /** Returns an integer in [min, max] inclusive. */
+    nextInt(min: number, max: number): number;
+    /** Pick a random element from an array. */
+    pick<T>(items: readonly T[]): T;
+    /** Pick `count` random elements from an array (with replacement). */
+    pickN<T>(items: readonly T[], count: number): T[];
+    /** Shuffle array in place (Fisher-Yates). */
+    shuffle<T>(items: T[]): T[];
+    /** Returns true with probability p (0-1). */
+    chance(p: number): boolean;
+    /**
+     * Generate a hex id of the given length.
+     * By default produces 12-char ids matching the MEMORY_ID_PATTERN.
+     */
+    hexId(length?: number): string;
+}
+//# sourceMappingURL=seeded-random.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seeded-random.d.ts","sourceRoot":"","sources":["../../../src/memory/testing/seeded-random.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,KAAK,CAAS;gBAEV,IAAI,EAAE,MAAM;IAIxB,iCAAiC;IACjC,IAAI,IAAI,MAAM;IAQd,kDAAkD;IAClD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAIzC,2CAA2C;IAC3C,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC;IAI/B,qEAAqE;IACrE,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE;IAQjD,6CAA6C;IAC7C,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE;IAQ3B,6CAA6C;IAC7C,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;IAI1B;;;OAGG;IACH,KAAK,CAAC,MAAM,SAAK,GAAG,MAAM;CAO1B"}

package/dist/memory/testing/seeded-random.js

@@ -0,0 +1,57 @@
+/**
+ * Seeded pseudo-random number generator using the mulberry32 algorithm.
+ * Produces deterministic sequences for reproducible test runs.
+ */
+export class SeededRandom {
+    state;
+    constructor(seed) {
+        this.state = seed | 0;
+    }
+    /** Returns a float in [0, 1). */
+    next() {
+        this.state |= 0;
+        this.state = (this.state + 0x6d2b79f5) | 0;
+        let t = Math.imul(this.state ^ (this.state >>> 15), 1 | this.state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    }
+    /** Returns an integer in [min, max] inclusive. */
+    nextInt(min, max) {
+        return Math.floor(this.next() * (max - min + 1)) + min;
+    }
+    /** Pick a random element from an array. */
+    pick(items) {
+        return items[this.nextInt(0, items.length - 1)];
+    }
+    /** Pick `count` random elements from an array (with replacement). */
+    pickN(items, count) {
+        const result = [];
+        for (let i = 0; i < count; i++) {
+            result.push(this.pick(items));
+        }
+        return result;
+    }
+    /** Shuffle array in place (Fisher-Yates). */
+    shuffle(items) {
+        for (let i = items.length - 1; i > 0; i--) {
+            const j = this.nextInt(0, i);
+            [items[i], items[j]] = [items[j], items[i]];
+        }
+        return items;
+    }
+    /** Returns true with probability p (0-1). */
+    chance(p) {
+        return this.next() < p;
+    }
+    /**
+     * Generate a hex id of the given length.
+     * By default produces 12-char ids matching the MEMORY_ID_PATTERN.
+     */
+    hexId(length = 12) {
+        let result = "";
+        for (let i = 0; i < length; i++) {
+            result += "0123456789abcdef"[this.nextInt(0, 15)];
+        }
+        return result;
+    }
+}

package/dist/relay/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAgCzD,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACX,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO/C;;;GAGG;AACH,UAAU,UAAU;IAClB,KAAK,EACD,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,uBAAuB,GACvB,gBAAgB,GAChB,aAAa,GACb,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,4BAA4B,GAC5B,iBAAiB,GACjB,6BAA6B,GAC7B,cAAc,GACd,wBAAwB,GACxB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,oBAAoB,GACpB,iBAAiB,GACjB,cAAc,GACd,cAAc,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,UAAU,GAAG,IAAI,CAuHnB;AAMD;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,6FAA6F;IAC7F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAiD5B;AAwSD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,2DAA2D;IAC3D,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;;OASG;IACH,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,yEAAyE;IACzE,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAClD;AA8BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,IAAI,EAAE,iBAAiB,GACtB,IAAI,CAqIN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,iBAAiB,GACtB,IAAI,CAsDN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE;IAAE,OAAO,EAAE,oBAAoB,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,GACxF,IAAI,CAEN;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,oBAAoB,EAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GACnC,IAAI,CASN;AAMD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACjC,sDAAsD;IACtD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAClD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAQN"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/relay/dispatcher.js

@@ -623,6 +623,7 @@ export function handleClientMessage(frame, deps) {
                 forkCompactPending: attachResult.forkCompactPending || undefined,
                 contextWindowUsed: attachResult.contextWindowUsed,
                 contextWindowMax: attachResult.contextWindowMax,
+                compacting: attachResult.compacting || undefined,
             },
         });
         // Surface bridge-start failures as `error` events; otherwise the
@@ -697,6 +698,7 @@ export function handleSubscribe(frame, deps) {
             forkCompactPending: attachResult.forkCompactPending || undefined,
             contextWindowUsed: attachResult.contextWindowUsed,
             contextWindowMax: attachResult.contextWindowMax,
+            compacting: attachResult.compacting || undefined,
         },
     });
     if (isNewSubscriber) {

package/dist/sdk/agent-core/harness/types.d.ts

@@ -413,6 +413,8 @@ export interface SessionBeforeCompactEvent {
     branchEntries: SessionTreeEntry[];
     customInstructions?: string;
     signal: AbortSignal;
+    /** Emit live compaction progress to the host UI while custom hooks run. */
+    emitProgress?: (delta: string, content?: string) => void;
 }
 export interface SessionCompactEvent {
     type: "session_compact";