@burtson-labs/agent-core 1.6.13

package/dist/security/secretPatterns.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * Secret-leak protection. Tool output (file reads, command
+ * stdout, search results) routinely surfaces API keys, OAuth tokens,
+ * and private keys when the user asks the agent to inspect dotfiles,
+ * environment variables, or anything else that touches credentials.
+ * Without redaction, those tokens land in:
+ *
+ * 1. The model's context window → the model may echo them in its
+ * next response, embed them in a tool call, or hallucinate
+ * surrounding prose that quotes them verbatim
+ * 2. The user's terminal → secrets sit in the scrollback,
+ * visible to over-shoulder readers and any screen-sharing flow
+ * 3. The session log on disk → ~/.bandit/sessions/*.jsonl
+ * persists raw secrets indefinitely, becoming a target if
+ * that file is ever shared (bug reports, etc.)
+ *
+ * The redactor is the single source of truth for "what looks like a
+ * secret." Patterns target high-confidence formats (known prefixes,
+ * stable lengths) — we deliberately do NOT redact generic
+ * high-entropy strings because false positives are corrosive (the
+ * agent loses the ability to reason about real data that happens to
+ * look secret-shaped).
+ *
+ * Each pattern has a `kind` label so the redaction replaces the match
+ * with a typed token like `<REDACTED:github-pat>` — preserves enough
+ * structure for the model (and the user) to understand what kind of
+ * thing was hidden without leaking the value.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_SECRET_PATTERNS = void 0;
+exports.redactSecrets = redactSecrets;
+exports.redactSecretsString = redactSecretsString;
+/**
+ * Built-in secret patterns. Each entry is a high-confidence format with
+ * either a recognized prefix or a strict length/charset constraint.
+ *
+ * Order matters: longer / more-specific patterns must match BEFORE
+ * shorter / more-generic ones, otherwise a fine-grained PAT would be
+ * partially matched by the classic-PAT pattern. We rely on the regex
+ * engine matching in source order via the array iteration below.
+ */
+exports.BUILTIN_SECRET_PATTERNS = [
+    // ─── GitHub ───────────────────────────────────────────────────────
+    // Fine-grained PATs are LONG (82 char body) — listed first so the
+    // classic-PAT pattern doesn't truncate them.
+    {
+        kind: 'github-pat-fine-grained',
+        label: 'GitHub fine-grained PAT',
+        re: /\bgithub_pat_[A-Za-z0-9_]{82}\b/g
+    },
+    {
+        kind: 'github-pat',
+        label: 'GitHub classic PAT',
+        re: /\bghp_[A-Za-z0-9]{36,251}\b/g
+    },
+    {
+        kind: 'github-oauth',
+        label: 'GitHub OAuth token',
+        re: /\bgho_[A-Za-z0-9]{36,251}\b/g
+    },
+    {
+        kind: 'github-server-token',
+        label: 'GitHub server-to-server token',
+        re: /\bghs_[A-Za-z0-9]{36,251}\b/g
+    },
+    {
+        kind: 'github-user-token',
+        label: 'GitHub user-to-server token',
+        re: /\bghu_[A-Za-z0-9]{36,251}\b/g
+    },
+    // ─── Slack ────────────────────────────────────────────────────────
+    {
+        kind: 'slack-bot-token',
+        label: 'Slack bot token',
+        re: /\bxoxb-[A-Za-z0-9-]+\b/g
+    },
+    {
+        kind: 'slack-user-token',
+        label: 'Slack user token',
+        re: /\bxoxp-[A-Za-z0-9-]+\b/g
+    },
+    {
+        kind: 'slack-app-token',
+        label: 'Slack app token',
+        re: /\bxoxa-[A-Za-z0-9-]+\b/g
+    },
+    // ─── GitLab ───────────────────────────────────────────────────────
+    {
+        kind: 'gitlab-pat',
+        label: 'GitLab personal access token',
+        re: /\bglpat-[A-Za-z0-9_-]{20,}\b/g
+    },
+    // ─── AWS ──────────────────────────────────────────────────────────
+    {
+        kind: 'aws-access-key',
+        label: 'AWS access key',
+        re: /\b(?:AKIA|ASIA|AROA|AGPA|AIPA)[0-9A-Z]{16}\b/g
+    },
+    // ─── Anthropic / OpenAI / Bandit ──────────────────────────────────
+    {
+        kind: 'anthropic-key',
+        label: 'Anthropic API key',
+        re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g
+    },
+    {
+        kind: 'openai-key',
+        label: 'OpenAI API key',
+        re: /\bsk-(?!ant-)[A-Za-z0-9_-]{20,}\b/g
+    },
+    {
+        kind: 'bandit-api-key',
+        label: 'Bandit / Burtson Labs API key',
+        re: /\bbai_[A-Za-z0-9]{20,}\b/g
+    },
+    // ─── Google ───────────────────────────────────────────────────────
+    // Google API keys start with "AIza" + 35 chars (39 total).
+    {
+        kind: 'google-api-key',
+        label: 'Google API key',
+        re: /\bAIza[A-Za-z0-9_-]{35}\b/g
+    },
+    // OAuth refresh tokens are "1//" + base64-like body.
+    {
+        kind: 'google-oauth-refresh',
+        label: 'Google OAuth refresh token',
+        re: /\b1\/\/[A-Za-z0-9_-]{43,}\b/g
+    },
+    // ─── Stripe ───────────────────────────────────────────────────────
+    {
+        kind: 'stripe-secret-key',
+        label: 'Stripe secret key',
+        re: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{24,}\b/g
+    },
+    // ─── JWTs (generic, three base64-url segments) ────────────────────
+    // Any token shaped `eyJ<header>.<payload>.<signature>` — covers JWTs
+    // from any issuer. Catches our own AuthApi tokens, Auth0, Google ID
+    // tokens, etc. Long enough that the entropy filter doesn't hurt.
+    {
+        kind: 'jwt',
+        label: 'JWT token',
+        re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g
+    },
+    // ─── Private keys (PEM blocks) ────────────────────────────────────
+    // PEM-armored RSA / ECDSA / OpenSSH / generic private keys. The
+    // multi-line matcher captures the entire BEGIN...END block.
+    {
+        kind: 'private-key',
+        label: 'PEM private key',
+        re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP |ENCRYPTED )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA |PGP |ENCRYPTED )?PRIVATE KEY-----/g
+    },
+    // ─── HTTP Authorization headers ───────────────────────────────────
+    // Catches "Authorization: Bearer <token>" / Token / Basic shapes that
+    // leak through curl outputs, request logs, fetch() debugging, etc.
+    // Preserves the header name + scheme so the model can still reason
+    // about WHAT auth was attempted, just not the token value.
+    //
+    // Caps the token character class at non-quote / non-whitespace /
+    // non-angle-bracket so this pattern can't re-match an already-redacted
+    // placeholder like "<REDACTED:jwt>".
+    {
+        kind: 'authorization-bearer',
+        label: 'HTTP Authorization header token',
+        // Backreferences \1 and \3 balance quotes around the key name and
+        // the value so both `Authorization: Bearer foo` and the JSON form
+        // `"Authorization": "Bearer foo"` match without grabbing stray quotes.
+        re: /(["']?)Authorization\1(\s*[:=]\s*)(["']?)(Bearer|Token|Basic)\s+([^\s"'<>]{16,})\3/gi
+    },
+    // ─── JSON / JS-style camelCase secret fields ──────────────────────
+    // The env-secret pattern below only catches SHOUTY_CASE names. JSON
+    // config files use camelCase ("apiKey", "accessToken", "clientSecret"),
+    // so the env pattern misses them entirely. ~/.bandit/config.json
+    // ({"bandit": {"apiKey": "..."}}) was leaking because of exactly this
+    // gap (2026-05-26).
+    //
+    // Matches: any quoted-or-bare camelCase identifier that ends in
+    // Key|Token|Secret|Password|Credentials, OR standalone "password" /
+    // "passwd" / "secret". Value must be a quoted string of 8+ chars.
+    // The value char class excludes <, > so it can't re-match a prior
+    // pattern's placeholder.
+    //
+    // Preserves: opening key quote, key name, closing key quote,
+    // separator (`: ` or `=`), opening value quote, closing value quote.
+    // Replaces: only the value's content.
+    {
+        kind: 'json-camelcase-secret',
+        label: 'camelCase config secret value',
+        re: /(["']?)([a-z][a-zA-Z0-9]*(?:Key|Token|Secret|Password|Credentials?)|password|passwd|secret)\1(\s*[:=]\s*)(["'])([^"'\s<>]{8,})\4/g
+    },
+    // ─── Generic env-style secret lines ───────────────────────────────
+    // Last-resort pattern: capture `*_TOKEN=<value>`, `*_KEY=<value>`,
+    // `*_SECRET=<value>`, `*_PASSWORD=<value>` style env lines where
+    // the value is non-empty and has at least 8 characters. Replaces
+    // only the value, not the variable name (preserves readability).
+    //
+    // The variable name is either a prefix + underscore + keyword
+    // (`STRIPE_SECRET_KEY`, `GITHUB_TOKEN`) OR just the keyword on its
+    // own (`PASSWORD=`, `TOKEN=`, `API_KEY=`). The optional non-capturing
+    // group `(?:[A-Z][A-Z0-9_]*_)?` handles both cases — the trailing
+    // underscore forces a real prefix boundary so `DEBUG=...` (which has
+    // no keyword suffix) never matches.
+    //
+    // Quoted values supported via the back-referenced quote group.
+    {
+        kind: 'env-secret',
+        label: 'env-style secret value',
+        re: /\b((?:[A-Z][A-Z0-9_]*_)?(?:TOKEN|KEY|SECRET|PASSWORD|PASSWD|PWD|CREDENTIALS?|API|AUTH))\s*[:=]\s*(['"]?)([^\s'"]{8,})\2/g
+    }
+];
+/**
+ * Apply all built-in patterns to a string. Replaces each match with
+ * `<REDACTED:{kind}>`. The replacement is intentionally short so the
+ * model can still reason about the surrounding text without burning
+ * context on long placeholder tokens.
+ *
+ * The `env-secret` pattern is special: it preserves the variable name
+ * and only redacts the value. So `GITHUB_TOKEN=ghp_abc...` becomes
+ * `GITHUB_TOKEN=<REDACTED:env-secret>` — the model can still see WHAT
+ * variable was set without seeing its value. For all other patterns
+ * the whole match is replaced.
+ */
+function redactSecrets(text, patterns = exports.BUILTIN_SECRET_PATTERNS) {
+    if (!text || text.length === 0) {
+        return { text, redactionCount: 0, kinds: [] };
+    }
+    let working = text;
+    let redactionCount = 0;
+    const kinds = [];
+    const recordKind = (kind) => {
+        if (!kinds.includes(kind))
+            kinds.push(kind);
+    };
+    for (const pattern of patterns) {
+        // Reset lastIndex so the global regex starts at 0 every call.
+        pattern.re.lastIndex = 0;
+        let mutated = false;
+        if (pattern.kind === 'env-secret') {
+            // Preserve `VAR=` prefix, redact only the value.
+            working = working.replace(pattern.re, (_match, varName) => {
+                redactionCount++;
+                recordKind(pattern.kind);
+                mutated = true;
+                return `${varName}=<REDACTED:${pattern.kind}>`;
+            });
+        }
+        else if (pattern.kind === 'json-camelcase-secret') {
+            // Preserve quoted key + separator + value quotes; redact only the
+            // inner value. Groups: (1) keyQuote, (2) keyName, (3) separator,
+            // (4) valueQuote, (5) value.
+            working = working.replace(pattern.re, (_match, kq, keyName, sep, vq) => {
+                redactionCount++;
+                recordKind(pattern.kind);
+                mutated = true;
+                return `${kq}${keyName}${kq}${sep}${vq}<REDACTED:${pattern.kind}>${vq}`;
+            });
+        }
+        else if (pattern.kind === 'authorization-bearer') {
+            // Preserve quoted header name + separator + value quotes; redact
+            // only the token. Groups: (1) keyQuote, (2) separator, (3) valueQuote,
+            // (4) scheme, (5) token.
+            working = working.replace(pattern.re, (_match, kq, sep, vq, scheme) => {
+                redactionCount++;
+                recordKind(pattern.kind);
+                mutated = true;
+                return `${kq}Authorization${kq}${sep}${vq}${scheme} <REDACTED:${pattern.kind}>${vq}`;
+            });
+        }
+        else {
+            working = working.replace(pattern.re, () => {
+                redactionCount++;
+                recordKind(pattern.kind);
+                mutated = true;
+                return `<REDACTED:${pattern.kind}>`;
+            });
+        }
+        // Defensive: regex with `g` flag carries state across calls. Reset
+        // again to guarantee no leftover lastIndex affects later callers.
+        if (mutated)
+            pattern.re.lastIndex = 0;
+    }
+    return { text: working, redactionCount, kinds };
+}
+/**
+ * Convenience helper used by callers that don't need the metadata —
+ * just want the masked string. Equivalent to redactSecrets(text).text.
+ */
+function redactSecretsString(text) {
+    return redactSecrets(text).text;
+}
+//# sourceMappingURL=secretPatterns.js.map

package/dist/security/secretPatterns.js.map

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

package/dist/tools/ask-user-tool.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `ask_user` — pose one or more clarifying questions to the user and wait
+ * for their answer before continuing.
+ *
+ * Host-agnostic: the tool only formats the question payload and the answer
+ * summary. The actual interactive prompt is rendered by the host via
+ * `ToolExecutionContext.requestUserInput` (the CLI's ink form, the
+ * extension's webview card). When a host doesn't provide that callback the
+ * tool degrades to telling the model to ask in plain text, so it's always
+ * safe to register — though hosts typically only register the owning skill
+ * when they actually have an interactive surface (see interaction-skill).
+ */
+import type { AgentTool, UserInputQuestion } from './tool-types';
+/** Parse the model-supplied `questions` JSON into validated question specs.
+ *  Tolerant: accepts a single object (not wrapped in an array), string
+ *  options, and `question`/`text`/`prompt` aliases. Assigns stable ids. */
+export declare function parseAskUserQuestions(rawJson: string): UserInputQuestion[];
+export declare const askUserTool: AgentTool;
+//# sourceMappingURL=ask-user-tool.d.ts.map

package/dist/tools/ask-user-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user-tool.d.ts","sourceRoot":"","sources":["../../src/tools/ask-user-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAyBjE;;2EAE2E;AAC3E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE,CA4B1E;AAED,eAAO,MAAM,WAAW,EAAE,SAmFzB,CAAC"}

package/dist/tools/ask-user-tool.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * `ask_user` — pose one or more clarifying questions to the user and wait
+ * for their answer before continuing.
+ *
+ * Host-agnostic: the tool only formats the question payload and the answer
+ * summary. The actual interactive prompt is rendered by the host via
+ * `ToolExecutionContext.requestUserInput` (the CLI's ink form, the
+ * extension's webview card). When a host doesn't provide that callback the
+ * tool degrades to telling the model to ask in plain text, so it's always
+ * safe to register — though hosts typically only register the owning skill
+ * when they actually have an interactive surface (see interaction-skill).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askUserTool = void 0;
+exports.parseAskUserQuestions = parseAskUserQuestions;
+const QUESTIONS_EXAMPLE = '[{"question":"Which database should we use?","header":"Database","options":' +
+    '[{"label":"Postgres","description":"Relational, strong consistency"},' +
+    '{"label":"MongoDB","description":"Flexible document store"}],"allowFreeform":true}]';
+function coerceOption(raw) {
+    if (typeof raw === 'string')
+        return raw.trim() ? { label: raw.trim() } : null;
+    if (raw && typeof raw === 'object') {
+        const o = raw;
+        const label = typeof o.label === 'string' ? o.label
+            : typeof o.value === 'string' ? o.value
+                : typeof o.text === 'string' ? o.text : '';
+        if (!label.trim())
+            return null;
+        return {
+            label: label.trim(),
+            description: typeof o.description === 'string' ? o.description : undefined
+        };
+    }
+    return null;
+}
+/** Parse the model-supplied `questions` JSON into validated question specs.
+ *  Tolerant: accepts a single object (not wrapped in an array), string
+ *  options, and `question`/`text`/`prompt` aliases. Assigns stable ids. */
+function parseAskUserQuestions(rawJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawJson);
+    }
+    catch {
+        return [];
+    }
+    const list = Array.isArray(parsed) ? parsed : [parsed];
+    const questions = [];
+    list.forEach((raw, i) => {
+        if (!raw || typeof raw !== 'object')
+            return;
+        const r = raw;
+        const text = typeof r.question === 'string' ? r.question
+            : typeof r.text === 'string' ? r.text
+                : typeof r.prompt === 'string' ? r.prompt : '';
+        if (!text.trim())
+            return;
+        const options = (Array.isArray(r.options) ? r.options : [])
+            .map(coerceOption)
+            .filter((o) => o !== null);
+        questions.push({
+            id: typeof r.id === 'string' && r.id.trim() ? r.id.trim() : `q${i + 1}`,
+            question: text.trim(),
+            header: typeof r.header === 'string' && r.header.trim() ? r.header.trim() : undefined,
+            options: options.length > 0 ? options : undefined,
+            allowFreeform: r.allowFreeform === false ? false : true
+        });
+    });
+    return questions;
+}
+exports.askUserTool = {
+    name: 'ask_user',
+    description: 'Ask the user one or more clarifying questions and WAIT for their answer before continuing. ' +
+        'ALWAYS use this tool when you need a decision or direction from the user — do NOT ask in your prose ' +
+        'response and end the turn. A prose question is passive (the user must start a new turn); this renders ' +
+        'an interactive prompt they answer in one click. ' +
+        'Use only when you are genuinely blocked on a decision that is the user\'s to make and cannot be ' +
+        'resolved from the request, the code, or sensible defaults — not for routine choices you can make ' +
+        'yourself. Provide 1–4 questions, each with 2–4 suggested options (the user can also type their own ' +
+        'answer). When one option is the clear best choice, make it the FIRST option and append ' +
+        '" (Recommended)" to its label — it is pre-selected, so the user can accept it with one click. ' +
+        'The tool result contains the user\'s answers; act on them directly without re-asking.',
+    parameters: [
+        {
+            name: 'questions',
+            description: 'A JSON array of question objects. Each object: { "question": "the question text", ' +
+                '"header": "short tab label", "options": [{ "label": "...", "description": "optional context" }], ' +
+                '"allowFreeform": true }. Example: ' + QUESTIONS_EXAMPLE,
+            required: true,
+            schema: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        question: { type: 'string', description: 'The question to ask the user.' },
+                        header: { type: 'string', description: 'A short (≤12 char) label for the question tab.' },
+                        options: {
+                            type: 'array',
+                            description: 'Suggested answers (2–4). If one is the clear best choice, list it first and append " (Recommended)" to its label.',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    label: { type: 'string', description: 'The option text.' },
+                                    description: { type: 'string', description: 'Optional one-line explanation of the option.' }
+                                },
+                                required: ['label']
+                            }
+                        },
+                        allowFreeform: { type: 'boolean', description: 'Allow a typed custom answer (default true).' }
+                    },
+                    required: ['question']
+                }
+            }
+        }
+    ],
+    async execute(params, ctx) {
+        if (!ctx.requestUserInput) {
+            return {
+                output: 'Interactive questions are not available in this environment. Ask your question(s) in plain ' +
+                    'text in your normal response and wait for the user to reply.',
+                isError: false
+            };
+        }
+        const questions = parseAskUserQuestions(params.questions ?? '');
+        if (questions.length === 0) {
+            return {
+                output: 'ask_user failed: the `questions` parameter must be a JSON array of {question, options} ' +
+                    'objects. Example: ' + QUESTIONS_EXAMPLE,
+                isError: true
+            };
+        }
+        const res = await ctx.requestUserInput({ questions });
+        if (res.cancelled) {
+            return {
+                output: 'The user dismissed the question(s) without answering. Do not immediately re-ask — proceed ' +
+                    'with your best judgment, or briefly explain what you need and let the user respond when ready.',
+                isError: false
+            };
+        }
+        const lines = questions.map((q) => {
+            const a = res.answers[q.id];
+            return `Q: ${q.question}\nA: ${a !== undefined && a !== '' ? a : '(no answer)'}`;
+        });
+        return { output: 'The user answered:\n\n' + lines.join('\n\n'), isError: false };
+    }
+};
+//# sourceMappingURL=ask-user-tool.js.map

package/dist/tools/ask-user-tool.js.map

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

package/dist/tools/compactMessages.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Message-history compaction for the tool-use loop.
+ *
+ * Why this exists:
+ *   The loop appends every tool result as a `user` message carrying
+ *   the raw output (read_file content, search_code hits, command
+ *   stdout). After ~6 iterations on a medium-sized codebase the
+ *   cumulative tool output is ~12-18k tokens — enough to push past
+ *   the Ollama num_ctx ceiling on small/medium models, which causes
+ *   silent front-truncation of the system prompt (the exact failure
+ *   mode that made `bandit-core:12b-it-qat` appear to "refuse" C#
+ *   edits until num_ctx was properly configured).
+ *
+ * Strategy (deterministic, no extra LLM calls):
+ *   1. Count tokens with a cheap char/4 heuristic.
+ *   2. If the total fits a configurable budget, return as-is.
+ *   3. Otherwise, walk the message list from oldest to newest and
+ *      replace the *body* of earlier tool-result messages with a
+ *      one-line placeholder ("[read_file api/foo.cs — 412 lines, see
+ *      earlier]"). We always keep the system prompt, the initial user
+ *      prompt, the last N tool results in full, and any assistant
+ *      message that contains a tool call (the model needs to see its
+ *      own prior reasoning).
+ *
+ * The compacted messages retain the same `role` / `content` shape so
+ * the loop doesn't need to change — it just passes them through chat.
+ */
+import type { ToolLoopMessage } from './tool-types';
+export interface CompactionOptions {
+    /** Target token budget. Defaults to 12000 (safe for 16k num_ctx). */
+    tokenBudget?: number;
+    /** Always keep the last N tool-result messages in full. Default 2. */
+    keepRecentToolResults?: number;
+    /** Character-to-token ratio for heuristic counting. Default 4. */
+    charsPerToken?: number;
+}
+export interface CompactionReport {
+    compacted: ToolLoopMessage[];
+    /** Pre-compaction estimated token count. */
+    beforeTokens: number;
+    /** Post-compaction estimated token count. */
+    afterTokens: number;
+    /** How many messages were collapsed to placeholders. */
+    messagesCompacted: number;
+}
+/**
+ * Main entry point. Returns compacted messages plus a report of what
+ * changed. Callers can log the report so agents/CLIs can surface
+ * "compacted history — N msgs, saved X tokens" as a status line.
+ */
+export declare function compactToolMessages(messages: ToolLoopMessage[], options?: CompactionOptions): CompactionReport;
+//# sourceMappingURL=compactMessages.d.ts.map

package/dist/tools/compactMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactMessages.d.ts","sourceRoot":"","sources":["../../src/tools/compactMessages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAyCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,EAAE,EAC3B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CA0FlB"}