exempclaw 0.4.0

package/dist/ingest/ingest.js

@@ -0,0 +1,258 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, extname } from "node:path";
+import { z } from "zod";
+import { simpleParser } from "mailparser";
+import { addUsage, emptyUsage } from "../core/usage.js";
+/**
+ * The onboarding pass: read a departed employee's exported artifacts (mail
+ * exports, docs, notes, tickets — anything text), distill them into durable
+ * role memories, and seed the agent's MemoryStore. Run once per agent with
+ * `exempclaw ingest <agent.json> <dir>`.
+ */
+const TEXT_EXTENSIONS = new Set([
+    ".txt",
+    ".md",
+    ".markdown",
+    ".eml",
+    ".mbox",
+    ".json",
+    ".csv",
+    ".tsv",
+    ".log",
+    ".html",
+    ".htm",
+    ".xml",
+    ".yaml",
+    ".yml",
+]);
+const DistilledSchema = z.object({
+    memories: z.array(z.object({
+        text: z.string().describe("One durable, self-contained fact."),
+        tags: z.array(z.string()).default([]),
+    })),
+});
+export async function ingestArchive(opts) {
+    const maxFileBytes = opts.maxFileBytes ?? 512 * 1024;
+    const chunkChars = opts.chunkChars ?? 24_000;
+    const maxChunks = opts.maxChunks ?? 60;
+    const progress = opts.onProgress ?? (() => undefined);
+    const { files, skipped } = await collectFiles(opts.dir, maxFileBytes);
+    if (files.length === 0) {
+        progress({ phase: "scanned", files: 0, skipped: skipped.length });
+        return { files: 0, chunks: 0, memoriesAdded: 0, skippedFiles: skipped, usage: emptyUsage() };
+    }
+    progress({ phase: "scanned", files: files.length, skipped: skipped.length });
+    let chunks = chunkFiles(files, chunkChars);
+    if (chunks.length > maxChunks) {
+        opts.log.warn("archive larger than chunk budget; ingesting the first chunks only", {
+            chunks: chunks.length,
+            maxChunks,
+        });
+        chunks = chunks.slice(0, maxChunks);
+    }
+    let usage = emptyUsage();
+    let memoriesAdded = 0;
+    const distilledTexts = [];
+    for (const [index, chunk] of chunks.entries()) {
+        if (opts.signal?.aborted)
+            break;
+        progress({ phase: "chunk", index: index + 1, total: chunks.length, files: chunk.files });
+        const { value, usage: turnUsage } = await opts.claude.extract({
+            model: opts.model,
+            schema: DistilledSchema,
+            system: distillationSystemPrompt(opts.persona),
+            prompt: chunk.text,
+            effort: "medium",
+            signal: opts.signal,
+        });
+        usage = addUsage(usage, turnUsage);
+        for (const memory of value.memories) {
+            await opts.memory.addMemory({
+                text: memory.text,
+                source: "onboarding",
+                tags: [...new Set(memory.tags.map((t) => t.toLowerCase()))],
+            });
+            distilledTexts.push(memory.text);
+            memoriesAdded++;
+        }
+    }
+    let briefing;
+    if ((opts.briefing ?? true) && distilledTexts.length > 0 && !opts.signal?.aborted) {
+        progress({ phase: "briefing" });
+        const summary = await opts.claude.summarize(distilledTexts.join("\n- "), {
+            model: opts.model,
+            instruction: briefingInstruction(opts.persona),
+            signal: opts.signal,
+        });
+        await opts.memory.addMemory({ text: summary, source: "onboarding", tags: ["briefing"] });
+        memoriesAdded++;
+        briefing = summary;
+    }
+    return { files: files.length, chunks: chunks.length, memoriesAdded, skippedFiles: skipped, briefing, usage };
+}
+function distillationSystemPrompt(persona) {
+    return [
+        `You are preparing role context for ${persona.name}, who is taking over as ${persona.role}` +
+            (persona.succeeds ? ` from ${persona.succeeds}.` : "."),
+        "You will be given raw work artifacts (emails, docs, notes, tickets). Extract durable, forward-useful facts:",
+        "- people: who they are, their role, and how they relate to this role",
+        "- in-flight work, open commitments, and deadlines (with dates when stated)",
+        "- recurring processes, conventions, and where things live",
+        "- key decisions and their rationale",
+        "Each memory must be one self-contained sentence or two, understandable without the source document.",
+        "Skip pleasantries, duplicates, trivia, and anything stale. NEVER extract passwords, API keys, tokens, or other secrets — omit them entirely.",
+        "Tag each memory with short lowercase topics (e.g. a person's name, a project, \"process\", \"deadline\").",
+        "If a document contains nothing durable, return an empty list.",
+    ].join("\n");
+}
+function briefingInstruction(persona) {
+    return (`Write a role briefing for ${persona.name}, the incoming ${persona.role}` +
+        (persona.succeeds ? ` succeeding ${persona.succeeds}` : "") +
+        ". From the distilled notes below, produce a compact briefing covering: top priorities right now, " +
+        "key people and what they need, in-flight commitments with dates, and how this role usually operates. " +
+        "Dense prose, no fluff.");
+}
+/** Recursively collects readable text files, skipping junk and oversized files. */
+export async function collectFiles(dir, maxFileBytes) {
+    const files = [];
+    const skipped = [];
+    async function walk(current) {
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const rel = relative(dir, full);
+            if (!TEXT_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+                skipped.push(rel);
+                continue;
+            }
+            const info = await stat(full);
+            if (info.size > maxFileBytes) {
+                skipped.push(`${rel} (too large)`);
+                continue;
+            }
+            const raw = await readFile(full, "utf8");
+            const text = await normalizeText(raw, extname(entry.name).toLowerCase());
+            if (text.trim().length === 0) {
+                skipped.push(`${rel} (empty)`);
+                continue;
+            }
+            files.push({ path: rel, text });
+        }
+    }
+    await walk(dir);
+    return { files, skipped };
+}
+async function normalizeText(raw, ext) {
+    let text = raw;
+    if (ext === ".html" || ext === ".htm") {
+        text = text
+            .replace(/<style[\s\S]*?<\/style>/gi, "")
+            .replace(/<script[\s\S]*?<\/script>/gi, "")
+            .replace(/<[^>]+>/g, " ");
+    }
+    else if (ext === ".eml") {
+        text = await parseEmlForIngest(raw);
+    }
+    else if (ext === ".mbox") {
+        text = await parseMboxForIngest(raw);
+    }
+    return text.replace(/\r\n/g, "\n").replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n");
+}
+/** Parses one RFC-822 message into clean header + body text for distillation. */
+async function parseEmlForIngest(raw) {
+    try {
+        const mail = await simpleParser(raw);
+        return renderMailForIngest(mail);
+    }
+    catch {
+        return raw; // fall back to the raw source rather than dropping the file
+    }
+}
+/**
+ * Splits a classic mbox (messages separated by "From " lines) and parses each
+ * message. Caps the number of messages so a giant archive can't explode a
+ * single file into unbounded text.
+ */
+async function parseMboxForIngest(raw, maxMessages = 200) {
+    const parts = raw.split(/^From .*$/m).filter((p) => p.trim().length > 0);
+    if (parts.length === 0)
+        return raw;
+    const rendered = [];
+    for (const part of parts.slice(0, maxMessages)) {
+        try {
+            const mail = await simpleParser(part.trim());
+            rendered.push(renderMailForIngest(mail));
+        }
+        catch {
+            // skip unparseable fragments
+        }
+    }
+    if (parts.length > maxMessages) {
+        rendered.push(`[…${parts.length - maxMessages} more messages truncated…]`);
+    }
+    return rendered.join("\n\n----\n\n");
+}
+function renderMailForIngest(mail) {
+    const to = Array.isArray(mail.to) ? mail.to.map((t) => t.text).join(", ") : mail.to?.text;
+    const body = (mail.text ?? "").trim();
+    return [
+        `From: ${mail.from?.text ?? "?"}`,
+        to ? `To: ${to}` : "",
+        mail.date ? `Date: ${mail.date.toISOString()}` : "",
+        `Subject: ${mail.subject ?? "(no subject)"}`,
+        "",
+        body,
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/** Greedily packs files into chunks; oversized files split on paragraphs. */
+export function chunkFiles(files, chunkChars) {
+    const chunks = [];
+    let buffer = "";
+    let bufferFiles = [];
+    const flush = () => {
+        if (buffer.trim())
+            chunks.push({ text: buffer, files: bufferFiles });
+        buffer = "";
+        bufferFiles = [];
+    };
+    for (const file of files) {
+        const pieces = file.text.length > chunkChars ? splitText(file.text, chunkChars) : [file.text];
+        for (const [i, piece] of pieces.entries()) {
+            const label = pieces.length > 1 ? `${file.path} (part ${i + 1}/${pieces.length})` : file.path;
+            const section = `===== FILE: ${label} =====\n${piece}\n`;
+            if (buffer.length > 0 && buffer.length + section.length > chunkChars)
+                flush();
+            buffer += section;
+            if (!bufferFiles.includes(file.path))
+                bufferFiles.push(file.path);
+        }
+    }
+    flush();
+    return chunks;
+}
+function splitText(text, max) {
+    const parts = [];
+    let remaining = text;
+    while (remaining.length > max) {
+        // Prefer a paragraph boundary in the back half of the window.
+        let cut = remaining.lastIndexOf("\n\n", max);
+        if (cut < max / 2)
+            cut = max;
+        parts.push(remaining.slice(0, cut));
+        remaining = remaining.slice(cut);
+    }
+    if (remaining.trim())
+        parts.push(remaining);
+    return parts;
+}
+//# sourceMappingURL=ingest.js.map

package/dist/ingest/ingest.js.map

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

package/dist/llm/claude.d.ts

@@ -0,0 +1,97 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { z } from "zod";
+import type { Logger } from "../core/logger.js";
+import { ExempclawError } from "../core/errors.js";
+/**
+ * Thin wrapper over the Anthropic SDK. Centralizes model defaults, adaptive
+ * thinking, prompt caching, streaming, and refusal handling so the agent
+ * runtime never touches the SDK directly. Claude is the ONLY provider
+ * Exempclaw uses — there is no abstraction layer for other LLMs by design.
+ */
+export type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
+export interface ClaudeTurnParams {
+    model?: string;
+    /**
+     * System prompt blocks. Place `cache_control` on the last *stable* block
+     * (see persona.buildSystemBlocks) so the tools+persona prefix is cached.
+     */
+    system: Anthropic.TextBlockParam[];
+    messages: Anthropic.MessageParam[];
+    tools?: Anthropic.ToolUnion[];
+    /** Caps a single response. Default 64000 (streamed). */
+    maxTokens?: number;
+    /** Controls reasoning depth + token spend. Defaults to "high". */
+    effort?: EffortLevel;
+    /** Cooperative cancellation — aborts the in-flight HTTP request. */
+    signal?: AbortSignal;
+    /** Receives text deltas as they stream, for live terminal output. */
+    onText?: (delta: string) => void;
+    /**
+     * Adds a cache breakpoint on the last message so the whole conversation
+     * prefix is reusable next turn. On by default for the agent loop.
+     */
+    cacheConversation?: boolean;
+}
+export declare class RefusalError extends ExempclawError {
+    readonly category: string | null;
+    constructor(category: string | null, explanation?: string | null);
+}
+/**
+ * The surface the agent runtime depends on. ClaudeClient implements it; tests
+ * substitute a scripted double.
+ */
+export interface ClaudeLike {
+    turn(params: ClaudeTurnParams): Promise<Anthropic.Message>;
+    summarize(text: string, opts?: {
+        model?: string;
+        instruction?: string;
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+export declare class ClaudeClient implements ClaudeLike {
+    private readonly defaultModel;
+    private readonly log;
+    private readonly client;
+    constructor(apiKey: string, defaultModel: string, log: Logger);
+    /**
+     * Runs a single assistant turn (streamed). Returns the full Message so the
+     * caller can inspect stop_reason, tool_use blocks, and usage. Throws
+     * RefusalError if the safety classifiers decline (possible on Fable 5).
+     */
+    turn(params: ClaudeTurnParams): Promise<Anthropic.Message>;
+    /**
+     * One-shot structured extraction: constrains the response to `schema` via
+     * structured outputs, parses, and validates. Used by the ingestion pipeline.
+     */
+    extract<T>(opts: {
+        prompt: string;
+        schema: z.ZodType<T>;
+        system?: string;
+        model?: string;
+        effort?: EffortLevel;
+        maxTokens?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        value: T;
+        usage: Anthropic.Usage;
+    }>;
+    /** Cheap one-shot summarization, used for history compaction. */
+    summarize(text: string, opts?: {
+        model?: string;
+        instruction?: string;
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /** Verifies the API key + model are usable. Used by `exempclaw doctor`. */
+    ping(model?: string): Promise<{
+        id: string;
+        displayName: string;
+    }>;
+}
+/**
+ * Returns a copy of `messages` with a cache breakpoint on the final content
+ * block, so the entire conversation prefix is served from cache next turn.
+ * The caller's array is not mutated.
+ */
+export declare function withConversationBreakpoint(messages: Anthropic.MessageParam[]): Anthropic.MessageParam[];
+/** Parses model-produced JSON, tolerating markdown code fences. */
+export declare function parseJsonLenient(text: string): unknown;

package/dist/llm/claude.js

@@ -0,0 +1,163 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { z } from "zod";
+import { ExempclawError } from "../core/errors.js";
+export class RefusalError extends ExempclawError {
+    category;
+    constructor(category, explanation) {
+        super(`Claude declined the request${category ? ` (${category})` : ""}${explanation ? `: ${explanation}` : ""}`);
+        this.category = category;
+    }
+}
+export class ClaudeClient {
+    defaultModel;
+    log;
+    client;
+    constructor(apiKey, defaultModel, log) {
+        this.defaultModel = defaultModel;
+        this.log = log;
+        this.client = new Anthropic({ apiKey, maxRetries: 4 });
+    }
+    /**
+     * Runs a single assistant turn (streamed). Returns the full Message so the
+     * caller can inspect stop_reason, tool_use blocks, and usage. Throws
+     * RefusalError if the safety classifiers decline (possible on Fable 5).
+     */
+    async turn(params) {
+        const model = params.model || this.defaultModel;
+        const request = {
+            model,
+            max_tokens: params.maxTokens ?? 64000,
+            system: params.system,
+            messages: params.cacheConversation ? withConversationBreakpoint(params.messages) : params.messages,
+            thinking: { type: "adaptive" },
+            output_config: { effort: params.effort ?? "high" },
+            ...(params.tools && params.tools.length > 0 ? { tools: params.tools } : {}),
+        };
+        const stream = this.client.messages.stream(request, { signal: params.signal });
+        if (params.onText)
+            stream.on("text", params.onText);
+        const message = await stream.finalMessage();
+        if (message.stop_reason === "refusal") {
+            throw new RefusalError(message.stop_details?.category ?? null, message.stop_details?.explanation);
+        }
+        this.log.debug("claude turn complete", {
+            model,
+            stop_reason: message.stop_reason ?? "unknown",
+            input_tokens: message.usage.input_tokens,
+            output_tokens: message.usage.output_tokens,
+            cache_read: message.usage.cache_read_input_tokens ?? 0,
+        });
+        return message;
+    }
+    /**
+     * One-shot structured extraction: constrains the response to `schema` via
+     * structured outputs, parses, and validates. Used by the ingestion pipeline.
+     */
+    async extract(opts) {
+        const model = opts.model || this.defaultModel;
+        const jsonSchema = z.toJSONSchema(opts.schema, { target: "draft-7" });
+        const stream = this.client.messages.stream({
+            model,
+            max_tokens: opts.maxTokens ?? 16000,
+            ...(opts.system ? { system: opts.system } : {}),
+            messages: [{ role: "user", content: opts.prompt }],
+            thinking: { type: "adaptive" },
+            output_config: {
+                effort: opts.effort ?? "medium",
+                format: { type: "json_schema", schema: jsonSchema },
+            },
+        }, { signal: opts.signal });
+        const message = await stream.finalMessage();
+        if (message.stop_reason === "refusal") {
+            throw new RefusalError(message.stop_details?.category ?? null, message.stop_details?.explanation);
+        }
+        const text = message.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text)
+            .join("");
+        const parsed = opts.schema.safeParse(parseJsonLenient(text));
+        if (!parsed.success) {
+            throw new ExempclawError(`structured extraction did not match schema: ${parsed.error.message}`, {
+                retryable: true,
+            });
+        }
+        return { value: parsed.data, usage: message.usage };
+    }
+    /** Cheap one-shot summarization, used for history compaction. */
+    async summarize(text, opts = {}) {
+        const instruction = opts.instruction ??
+            "Summarize this agent conversation transcript for the agent's own future reference. Preserve: open commitments and deadlines, key facts and decisions, people and their roles, unresolved threads, and anything the agent promised to do. Omit pleasantries and tool mechanics. Write it as dense factual notes.";
+        const message = await this.turn({
+            model: opts.model,
+            system: [{ type: "text", text: "You produce dense, factual summaries. No preamble." }],
+            messages: [{ role: "user", content: `${instruction}\n\n<transcript>\n${text}\n</transcript>` }],
+            effort: "low",
+            maxTokens: 4000,
+            signal: opts.signal,
+        });
+        return message.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text)
+            .join("\n")
+            .trim();
+    }
+    /** Verifies the API key + model are usable. Used by `exempclaw doctor`. */
+    async ping(model) {
+        const info = await this.client.models.retrieve(model || this.defaultModel);
+        return { id: info.id, displayName: info.display_name };
+    }
+}
+/**
+ * Returns a copy of `messages` with a cache breakpoint on the final content
+ * block, so the entire conversation prefix is served from cache next turn.
+ * The caller's array is not mutated.
+ */
+export function withConversationBreakpoint(messages) {
+    if (messages.length === 0)
+        return messages;
+    const out = messages.slice();
+    const last = out[out.length - 1];
+    const cacheControl = { type: "ephemeral" };
+    if (typeof last.content === "string") {
+        out[out.length - 1] = {
+            ...last,
+            content: [{ type: "text", text: last.content, cache_control: cacheControl }],
+        };
+        return out;
+    }
+    const blocks = last.content.slice();
+    const lastBlock = blocks[blocks.length - 1];
+    if (!lastBlock)
+        return messages;
+    // Only block types that accept cache_control; skip exotic blocks rather than error.
+    if (lastBlock.type === "text" ||
+        lastBlock.type === "tool_result" ||
+        lastBlock.type === "tool_use" ||
+        lastBlock.type === "image" ||
+        lastBlock.type === "document") {
+        blocks[blocks.length - 1] = { ...lastBlock, cache_control: cacheControl };
+        out[out.length - 1] = { ...last, content: blocks };
+        return out;
+    }
+    return messages;
+}
+/** Parses model-produced JSON, tolerating markdown code fences. */
+export function parseJsonLenient(text) {
+    const trimmed = text.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+        if (fenced?.[1]) {
+            try {
+                return JSON.parse(fenced[1].trim());
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=claude.js.map

package/dist/llm/claude.js.map

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

package/dist/memory/compaction.d.ts

@@ -0,0 +1,22 @@
+import type Anthropic from "@anthropic-ai/sdk";
+/**
+ * Client-side history compaction. When a conversation outgrows the context
+ * budget, the older portion is summarized into a single exchange and the
+ * recent turns are kept verbatim. The cut point is chosen so tool_use /
+ * tool_result pairs are never split.
+ */
+export interface CompactionOptions {
+    /** Roughly how many trailing messages to keep verbatim. Default 8. */
+    keepRecent?: number;
+    /** Produces the summary text for the compacted transcript. */
+    summarize: (transcript: string) => Promise<string>;
+}
+export declare function compactHistory(messages: Anthropic.MessageParam[], opts: CompactionOptions): Promise<Anthropic.MessageParam[]>;
+/**
+ * Finds the earliest valid boundary at or after (length - keepRecent): the
+ * boundary message must be a user turn that is not a tool_result follow-up,
+ * so the kept tail never references a tool_use that was summarized away.
+ */
+export declare function findCutIndex(messages: Anthropic.MessageParam[], keepRecent: number): number | null;
+/** Renders messages into a plain-text transcript for the summarizer. */
+export declare function renderTranscript(messages: Anthropic.MessageParam[]): string;

package/dist/memory/compaction.js

@@ -0,0 +1,79 @@
+export async function compactHistory(messages, opts) {
+    const keepRecent = opts.keepRecent ?? 8;
+    const cut = findCutIndex(messages, keepRecent);
+    if (cut === null || cut <= 1)
+        return messages;
+    const transcript = renderTranscript(messages.slice(0, cut));
+    const summary = await opts.summarize(transcript);
+    return [
+        {
+            role: "user",
+            content: [
+                {
+                    type: "text",
+                    text: `<conversation_summary>\n${summary}\n</conversation_summary>\nEarlier turns of this conversation were compacted into the summary above. Continue from it as if you lived through those turns.`,
+                },
+            ],
+        },
+        { role: "assistant", content: "Understood — I have the summary of the earlier conversation and will continue from it." },
+        ...messages.slice(cut),
+    ];
+}
+/**
+ * Finds the earliest valid boundary at or after (length - keepRecent): the
+ * boundary message must be a user turn that is not a tool_result follow-up,
+ * so the kept tail never references a tool_use that was summarized away.
+ */
+export function findCutIndex(messages, keepRecent) {
+    const target = messages.length - keepRecent;
+    if (target <= 1)
+        return null;
+    for (let i = target; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role !== "user")
+            continue;
+        if (typeof msg.content === "string")
+            return i;
+        const hasToolResult = msg.content.some((b) => b.type === "tool_result");
+        if (!hasToolResult)
+            return i;
+    }
+    return null;
+}
+/** Renders messages into a plain-text transcript for the summarizer. */
+export function renderTranscript(messages) {
+    const lines = [];
+    for (const msg of messages) {
+        if (typeof msg.content === "string") {
+            lines.push(`${msg.role.toUpperCase()}: ${msg.content}`);
+            continue;
+        }
+        for (const block of msg.content) {
+            switch (block.type) {
+                case "text":
+                    lines.push(`${msg.role.toUpperCase()}: ${block.text}`);
+                    break;
+                case "tool_use":
+                    lines.push(`${msg.role.toUpperCase()} called ${block.name}(${truncate(JSON.stringify(block.input), 400)})`);
+                    break;
+                case "tool_result": {
+                    const content = typeof block.content === "string"
+                        ? block.content
+                        : (block.content ?? [])
+                            .map((c) => (c.type === "text" ? c.text : `[${c.type}]`))
+                            .join(" ");
+                    lines.push(`TOOL RESULT${block.is_error ? " (error)" : ""}: ${truncate(content, 600)}`);
+                    break;
+                }
+                default:
+                    // thinking blocks and other internals are deliberately omitted
+                    break;
+            }
+        }
+    }
+    return lines.join("\n");
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+//# sourceMappingURL=compaction.js.map

package/dist/memory/compaction.js.map

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