flashlite 0.0.0-stage → 0.1.0

package/dist/commandpolicy.js

@@ -0,0 +1,544 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+// A best-effort recognizer, NOT a shell interpreter or a safety proof. Unlike
+// guarded auto, unfamiliar/opaque syntax is allowed. Only recognizable massive,
+// irreversible operations need an extra one-command confirmation in absolute.
+function riskSegments(command) {
+    const segments = [[]];
+    let text = '', expansion = false, started = false;
+    let quote = '';
+    const word = () => {
+        if (started)
+            segments.at(-1).push({ text, expansion });
+        text = '';
+        expansion = false;
+        started = false;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (char === '\\' && quote !== "'") {
+            started = true;
+            if (i + 1 < command.length)
+                text += command[++i];
+        }
+        else if (quote) {
+            if (char === quote)
+                quote = '';
+            else {
+                text += char;
+                if (quote === '"' && char === '$')
+                    expansion = true;
+            }
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+        }
+        else if (char === '>') {
+            word();
+            const operator = command[i + 1] === '>' ? '>>' : '>';
+            if (operator === '>>')
+                i++;
+            segments.at(-1).push({ text: operator, expansion: false, redirect: true });
+        }
+        else if (';|&\n()'.includes(char)) {
+            word();
+            if (segments.at(-1).length)
+                segments.push([]);
+        }
+        else if (/\s/.test(char))
+            word();
+        else {
+            started = true;
+            text += char;
+            if ('$~*?['.includes(char))
+                expansion = true;
+        }
+    }
+    word();
+    return segments;
+}
+const HUGE_DELETE_RISK = 'Mass irreversible deletion of a filesystem root, home, or system/volume tree.';
+const HUGE_DISK_RISK = 'Disk/volume erasure, formatting, or raw disk overwrite can irreversibly destroy widespread data.';
+const rawDisk = (value) => /^\/dev\/(?:r?disk\d+(?:s\d+)*|sd[a-z]\d*|nvme\d+n\d+(?:p\d+)?|mmcblk\d+(?:p\d+)?)$/.test(value);
+function broadDeleteTarget(word, cwd) {
+    let target = word.text;
+    if (word.expansion) {
+        target = target.replace(/^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/, os.homedir());
+        // Whole-tree globs, not a selective filename pattern or one home subdirectory.
+        if (['*', '.*', '**'].includes(target))
+            target = '.';
+        else
+            target = target.replace(/\/(?:\*|\.\*|\*\*)(?:\/\*)?$/, '/') || '/';
+    }
+    if (/[$*?[\]{}]/.test(target))
+        return false;
+    const resolved = path.resolve(cwd, target);
+    return new Set(['/', os.homedir(), '/Users', '/System', '/Library', '/Volumes', '/Applications', '/usr', '/bin', '/sbin', '/etc', '/private', '/private/etc', '/private/var', '/var']).has(resolved) ||
+        /^\/(?:Users|Volumes)\/[^/]+$/.test(resolved);
+}
+/** Narrow exceptional confirmation in absolute mode. No allowlist and no
+ * rejection just because a command is destructive, elevated, unknown or opaque.
+ * Does not inspect script files, aliases, remote code or arbitrary expansions.
+ */
+export function absoluteCommandRisk(command, cwd, depth = 0) {
+    if (depth > 4)
+        return;
+    for (const segment of riskSegments(command)) {
+        let words = segment;
+        while (words.length && ['if', 'elif', 'then', 'else', 'while', 'until', 'do', '!'].includes(words[0].text))
+            words = words.slice(1);
+        // Common literal wrappers do not make a recognizable catastrophe invisible.
+        while (words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0].text) ||
+            ['sudo', 'command', 'exec', 'env', 'nohup'].includes(path.basename(words[0].text)))) {
+            words = words.slice(1);
+            while (words[0]?.text.startsWith('-'))
+                words = words.slice(1);
+        }
+        if (!words.length)
+            continue;
+        const executable = path.basename(words[0].text);
+        const args = words.slice(1);
+        if (['sh', 'zsh', 'bash'].includes(executable)) {
+            const index = args.findIndex(word => /^-[a-z]*c[a-z]*$/.test(word.text));
+            if (index >= 0 && args[index + 1]) {
+                const risk = absoluteCommandRisk(args[index + 1].text, cwd, depth + 1);
+                if (risk)
+                    return risk;
+            }
+        }
+        if (executable === 'rm') {
+            let recursive = false, options = true;
+            const targets = [];
+            for (const arg of args) {
+                if (options && arg.text === '--') {
+                    options = false;
+                    continue;
+                }
+                if (options && arg.text.startsWith('-')) {
+                    recursive ||= arg.text === '--recursive' || /^-[^-]*[rR]/.test(arg.text);
+                }
+                else
+                    targets.push(arg);
+            }
+            if (recursive && targets.some(word => broadDeleteTarget(word, cwd)))
+                return HUGE_DELETE_RISK;
+        }
+        if (executable === 'diskutil' && (/^(?:eraseDisk|eraseVolume|partitionDisk|secureErase|zeroDisk|randomDisk)$/i.test(args[0]?.text ?? '') ||
+            (args[0]?.text.toLowerCase() === 'apfs' && /^(?:deleteContainer|deleteVolume)$/i.test(args[1]?.text ?? ''))))
+            return HUGE_DISK_RISK;
+        if (/^(?:mkfs(?:\..+)?|newfs(?:_.+)?)$/.test(executable) && args.some(word => rawDisk(word.text)))
+            return HUGE_DISK_RISK;
+        if (executable === 'dd' && args.some(word => word.text.startsWith('of=') && rawDisk(word.text.slice(3))))
+            return HUGE_DISK_RISK;
+        // Raw-device shell redirection, including `> /dev/diskN` and `>/dev/diskN`.
+        if (segment.some((word, i) => word.redirect && rawDisk(segment[i + 1]?.text ?? '')))
+            return HUGE_DISK_RISK;
+    }
+}
+// ---------------------------------------------------------------------------
+// Guarded auto classifier.
+//
+// Guarded auto is trust-by-default: it runs arbitrary terminal commands without a
+// per-call prompt. Exactly five categories still ask (or are refused when obviously
+// catastrophic), and no amount of wrapping, pipelines, or env assignments can hide
+// them: network access, installs/package managers, privilege escalation, paths
+// outside the project, and destructive Git / disk operations. Syntax this parser
+// cannot confidently reduce to literal words (substitutions, here-docs, globs,
+// eval/source, subshells, background) fails closed and asks.
+// ---------------------------------------------------------------------------
+const ALLOW = { auto: true, reason: 'Allowed by guarded auto; commands are not sandboxed and this is not a safety guarantee.' };
+const NETWORK_TOOLS = new Set([
+    'curl', 'wget', 'nc', 'netcat', 'ncat', 'telnet', 'ftp', 'lftp', 'sftp', 'ssh', 'scp',
+    'rsync', 'rclone', 'socat', 'dig', 'nslookup', 'host', 'ping', 'ping6', 'traceroute',
+    'mtr', 'whois', 'ssh-copy-id', 'openssl',
+]);
+// `git` subcommands that reach the network (or rewrite remote history).
+const GIT_NETWORK = new Set(['fetch', 'pull', 'push', 'clone', 'remote', 'submodule', 'ls-remote', 'send-pack', 'receive-pack']);
+// `git` subcommands that can destroy local work; the specific dangerous flags decide.
+const GIT_DESTRUCTIVE = new Set(['reset', 'clean', 'branch']);
+const GIT_VALUE_FLAGS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env']);
+// Package managers that install/upgrade by their very invocation.
+const PACKAGE_MANAGERS = new Set([
+    'brew', 'port', 'pip', 'pip3', 'pipx', 'apt', 'apt-get', 'apt-cache', 'dpkg', 'yum',
+    'dnf', 'zypper', 'pacman', 'snap', 'flatpak', 'nix', 'nix-env', 'mas', 'composer',
+    'conda', 'mamba', 'rustup', 'npx',
+]);
+// Runners whose subcommand decides whether they install or merely build/test.
+const NPM_LIKE = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+const NPM_INSTALL = new Set(['install', 'i', 'ci', 'add', 'remove', 'rm', 'uninstall', 'update', 'upgrade', 'link', 'publish', 'exec', 'dlx', 'create', 'init', 'pack', 'audit', 'fund', 'outdated', 'dedupe', 'prune', 'rebuild']);
+const SUBCOMMAND_INSTALL = {
+    cargo: new Set(['install', 'add', 'update', 'publish', 'yank', 'login', 'logout', 'owner']),
+    go: new Set(['get', 'install']),
+    gem: new Set(['install', 'uninstall', 'update', 'pristine', 'build']),
+    poetry: new Set(['add', 'install', 'update', 'lock', 'remove', 'sync']),
+    pipenv: new Set(['install', 'update', 'uninstall', 'sync', 'lock']),
+    bundle: new Set(['install', 'add', 'update', 'remove', 'lock']),
+};
+const SUDO_TOOLS = new Set(['sudo', 'doas', 'su', 'sudoedit', 'pkexec', 'run0']);
+const OPAQUE_COMMANDS = new Set(['eval', 'source', '.', 'xargs']);
+const SHELLS = new Set(['sh', 'zsh', 'bash', 'ash', 'dash', 'ksh']);
+// Literal wrappers whose prefix is stripped so a category cannot hide behind them.
+const WRAPPERS = new Set(['env', 'command', 'exec', 'nohup', 'nice', 'ionice', 'setsid', 'time', 'timeout', 'stdbuf', 'caffeinate']);
+const WRAPPER_VALUE_FLAGS = {
+    nice: new Set(['-n']),
+    ionice: new Set(['-c', '-n', '-p']),
+    stdbuf: new Set(['-i', '-o', '-e']),
+    timeout: new Set(['-s', '-k']),
+};
+/** Split a command into segments of literal-ish words. Returns an `opaque` reason
+ *  for shell syntax that cannot be reduced to inspectable words (it must ask). */
+function parseWords(command) {
+    const segments = [[]];
+    let text = '', dynamic = false, started = false, quote = '';
+    const word = () => {
+        if (started)
+            segments.at(-1).push({ text, dynamic, redirect: false });
+        text = '';
+        dynamic = false;
+        started = false;
+    };
+    const split = () => {
+        word();
+        if (!segments.at(-1).length)
+            return false;
+        segments.push([]);
+        return true;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (quote === "'") {
+            started = true;
+            if (char === "'")
+                quote = '';
+            else
+                text += char;
+            continue;
+        }
+        if (quote === '"') {
+            started = true;
+            if (char === '"') {
+                quote = '';
+                continue;
+            }
+            if (char === '\\') {
+                const next = command[++i];
+                if (next === undefined)
+                    return { segments, opaque: 'a trailing escape' };
+                text += '"\\$`'.includes(next) ? next : '\\' + next;
+                continue;
+            }
+            if (char === '$' || char === '`') {
+                dynamic = true;
+                text += char;
+                continue;
+            }
+            text += char;
+            continue;
+        }
+        if (char === '\\') {
+            started = true;
+            const next = command[++i];
+            if (next === undefined)
+                return { segments, opaque: 'a trailing escape' };
+            text += next;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (char === '`')
+            return { segments, opaque: 'command substitution' };
+        if (char === '$' && command[i + 1] === '(')
+            return { segments, opaque: 'command substitution' };
+        if (char === '$') {
+            started = true;
+            dynamic = true;
+            text += char;
+            continue;
+        }
+        if (char === '<' && command[i + 1] === '<')
+            return { segments, opaque: 'a here-document' };
+        if (char === '(' || char === ')' || char === '{' || char === '}')
+            return { segments, opaque: 'a subshell or group' };
+        if (char === ';' || char === '\n' || char === '|') {
+            if (!split() && segments.length === 1)
+                return { segments, opaque: 'a leading operator' };
+            continue;
+        }
+        if (char === '&') {
+            if (command[i + 1] === '&') {
+                if (!split() && segments.length === 1)
+                    return { segments, opaque: 'a leading operator' };
+                i++;
+                continue;
+            }
+            return { segments, opaque: 'background or file-descriptor syntax' };
+        }
+        if (char === '>') {
+            word();
+            let op = '>';
+            while (command[i + 1] === '>') {
+                op += '>';
+                i++;
+            }
+            if (op.length > 2)
+                return { segments, opaque: 'file-descriptor syntax' };
+            segments.at(-1).push({ text: op, dynamic: false, redirect: true });
+            continue;
+        }
+        if (char === '<') {
+            word();
+            segments.at(-1).push({ text: '<', dynamic: false, redirect: true });
+            continue;
+        }
+        if (char === '#' && !started)
+            break; // comment through end of the segment
+        if (/\s/.test(char)) {
+            word();
+            continue;
+        }
+        started = true;
+        text += char;
+        if ('*?['.includes(char))
+            dynamic = true;
+    }
+    word();
+    if (segments.length > 1 && segments.at(-1).length === 0) {
+        return { segments: segments.slice(0, -1), opaque: 'a trailing operator' };
+    }
+    return { segments: segments.filter((segment) => segment.length) };
+}
+/** Strip env assignments and literal wrappers, leaving the command actually run. */
+function effectiveWords(words) {
+    let i = 0;
+    for (;;) {
+        const current = words[i];
+        if (!current)
+            return [];
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(current.text)) {
+            i++;
+            continue;
+        }
+        const base = path.basename(current.text);
+        if (!WRAPPERS.has(base))
+            return words.slice(i);
+        i++;
+        if (base === 'timeout') {
+            while (words[i]?.text.startsWith('-'))
+                i++;
+            if (words[i] && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i].text))
+                i++; // the duration
+            continue;
+        }
+        const valueFlags = WRAPPER_VALUE_FLAGS[base];
+        while (words[i]?.text.startsWith('-'))
+            i += valueFlags?.has(words[i].text) ? 2 : 1;
+    }
+}
+/** First non-flag operand, skipping the value of known value-taking flags. */
+function firstOperand(args, valueFlags = new Set()) {
+    for (let i = 0; i < args.length; i++) {
+        const text = args[i].text;
+        if (text.startsWith('-')) {
+            if (valueFlags.has(text))
+                i++;
+            continue;
+        }
+        return text;
+    }
+}
+const CONFIG_DIR_UNDER_HOME = path.join('.config', 'flashlite');
+/** Read-only exception: the CLI's own `~/.config/flashlite` tree. */
+function configSubtree(value) {
+    if (!value.startsWith('~/'))
+        return false;
+    const expected = path.join(os.homedir(), CONFIG_DIR_UNDER_HOME);
+    const target = path.resolve(os.homedir(), value.slice(2));
+    const relative = path.relative(expected, target);
+    return relative === '' || (relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative));
+}
+/** A relative path is fine only while its deepest existing ancestor stays inside. */
+async function resolvesInsideProject(value, root) {
+    const resolved = path.resolve(root, value);
+    const relative = path.relative(root, resolved);
+    if (relative === '' || relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative))
+        return false;
+    let ancestor = resolved;
+    for (;;) {
+        try {
+            const real = await fs.realpath(ancestor);
+            const realRelative = path.relative(root, real);
+            return realRelative === '' || (realRelative !== '..' && !realRelative.startsWith('..' + path.sep) && !path.isAbsolute(realRelative));
+        }
+        catch {
+            const parent = path.dirname(ancestor);
+            if (parent === ancestor)
+                return false;
+            ancestor = parent;
+        }
+    }
+}
+function hasDotDot(value) {
+    return value.split('/').includes('..');
+}
+/** Check one path-like token. Returns a fixed reason when it leaves the project. */
+async function outsideReason(value, root, redirectTarget) {
+    if (!value)
+        return undefined;
+    if (value.startsWith('/')) {
+        if (redirectTarget && ['/dev/null', '/dev/stdout', '/dev/stderr'].includes(value))
+            return undefined;
+        return 'A path outside the project requires explicit approval in guarded auto.';
+    }
+    if (value.startsWith('~')) {
+        if (configSubtree(value))
+            return undefined;
+        return 'A path outside the project requires explicit approval in guarded auto.';
+    }
+    if (hasDotDot(value))
+        return 'A path outside the project requires explicit approval in guarded auto.';
+    if (!value.includes('/'))
+        return undefined;
+    return await resolvesInsideProject(value, root) ? undefined :
+        'A path outside the project requires explicit approval in guarded auto.';
+}
+const ASK_NETWORK = 'Network access (downloads, uploads, or remote sessions) requires explicit approval in guarded auto.';
+const ASK_INSTALL = 'Package installation or management requires explicit approval in guarded auto.';
+const ASK_SUDO = 'Privilege escalation (sudo/su) requires explicit approval in guarded auto.';
+const ASK_GIT = 'A destructive Git operation requires explicit approval in guarded auto.';
+const ASK_OPAQUE = 'The command uses shell syntax that cannot be classified safely; explicit approval is required.';
+function installReason(executable, args) {
+    if (PACKAGE_MANAGERS.has(executable))
+        return ASK_INSTALL;
+    if (NPM_LIKE.has(executable))
+        return args.some((arg) => NPM_INSTALL.has(arg.text)) ? ASK_INSTALL : undefined;
+    const subcommands = SUBCOMMAND_INSTALL[executable];
+    if (subcommands) {
+        const sub = firstOperand(args);
+        return sub && subcommands.has(sub) ? ASK_INSTALL : undefined;
+    }
+    return undefined;
+}
+function destructiveGitReason(args) {
+    const sub = firstOperand(args, GIT_VALUE_FLAGS);
+    if (!sub || !GIT_DESTRUCTIVE.has(sub))
+        return undefined;
+    const flags = args.map((arg) => arg.text);
+    if (sub === 'reset' && flags.some((flag) => flag === '--hard' || flag === '--merge' || flag === '--keep'))
+        return ASK_GIT;
+    if (sub === 'clean' && flags.some((flag) => /^-[a-zA-Z]*f/.test(flag)))
+        return ASK_GIT;
+    if (sub === 'branch' && flags.some((flag) => /^-[a-zA-Z]*D/.test(flag)))
+        return ASK_GIT;
+    return undefined;
+}
+/** Classify one parsed segment; returns the reason it must ask, if any. */
+async function classifySegment(segment, root) {
+    const words = effectiveWords(segment);
+    if (!words.length)
+        return undefined;
+    const command = words[0];
+    const executable = path.basename(command.text);
+    if (command.dynamic)
+        return ASK_OPAQUE;
+    if (OPAQUE_COMMANDS.has(executable))
+        return ASK_OPAQUE;
+    if (SUDO_TOOLS.has(executable))
+        return ASK_SUDO;
+    if (NETWORK_TOOLS.has(executable))
+        return ASK_NETWORK;
+    if (executable === 'git') {
+        const sub = firstOperand(words.slice(1), GIT_VALUE_FLAGS);
+        if (sub && GIT_NETWORK.has(sub))
+            return ASK_NETWORK;
+        const destructive = destructiveGitReason(words.slice(1));
+        if (destructive)
+            return destructive;
+    }
+    const install = installReason(executable, words.slice(1));
+    if (install)
+        return install;
+    const outside = await outsideReason(command.text, root, false);
+    if (outside)
+        return outside;
+    // Argument and redirect-target paths, plus expansions that cannot be resolved.
+    for (let i = 1; i < words.length; i++) {
+        const word = words[i];
+        if (word.redirect) {
+            const target = words[i + 1];
+            if (!target)
+                return ASK_OPAQUE;
+            const targetOutside = await outsideReason(target.text, root, true);
+            if (targetOutside)
+                return targetOutside;
+            i++;
+            continue;
+        }
+        if (word.text.startsWith('-') && word.text !== '-')
+            continue;
+        if (word.dynamic)
+            return ASK_OPAQUE;
+        const pathOutside = await outsideReason(word.text, root, false);
+        if (pathOutside)
+            return pathOutside;
+    }
+    return undefined;
+}
+/** Classify a full command string, following literal `sh -c '…'` bodies so a
+ *  wrapped category cannot hide behind a shell sub-invocation. */
+async function classifyCommand(command, root, depth = 0) {
+    if (depth > 3)
+        return undefined;
+    const parsed = parseWords(command);
+    if (parsed.opaque)
+        return `Guarded auto cannot inspect ${parsed.opaque}; explicit approval is required.`;
+    for (const segment of parsed.segments) {
+        const words = effectiveWords(segment);
+        if (!words.length)
+            continue;
+        const executable = path.basename(words[0].text);
+        if (SHELLS.has(executable)) {
+            const args = words.slice(1);
+            const index = args.findIndex((word) => /^-[a-z]*c[a-z]*$/.test(word.text));
+            if (index >= 0 && args[index + 1]) {
+                const nested = await classifyCommand(args[index + 1].text, root, depth + 1);
+                if (nested)
+                    return nested;
+                continue; // the body is clean; the shell invocation itself adds no path risk
+            }
+        }
+        const ask = await classifySegment(segment, root);
+        if (ask)
+            return ask;
+    }
+    return undefined;
+}
+/** Guarded-auto decision: allow by default, ask for the five risk categories, and
+ *  refuse obviously catastrophic deletion/disk commands outright. Rechecked at
+ *  execution time; nothing is cached. Never a sandbox or an executable verifier. */
+export async function commandPolicy(command, cwd) {
+    try {
+        if (typeof command !== 'string' || typeof cwd !== 'string' || !command.trim()) {
+            return { auto: false, reason: ASK_OPAQUE };
+        }
+        const root = await fs.realpath(cwd);
+        if (!(await fs.stat(root)).isDirectory() || command.length > 65536) {
+            return { auto: false, reason: ASK_OPAQUE };
+        }
+        // Obviously catastrophic deletion/disk commands are refused outright, not offered.
+        const catastrophic = absoluteCommandRisk(command, root);
+        if (catastrophic)
+            return { auto: false, reason: `Guarded auto refuses obviously catastrophic operations: ${catastrophic}`, deny: true };
+        const ask = await classifyCommand(command, root);
+        if (ask)
+            return { auto: false, reason: ask };
+        return { ...ALLOW };
+    }
+    catch {
+        return { auto: false, reason: ASK_OPAQUE };
+    }
+}

package/dist/commands.js

@@ -0,0 +1,29 @@
+// One catalog for the command palette; no command text is sent to the agent.
+export const COMMANDS = [
+    { id: '/model', description: 'Choose a model' },
+    { id: '/compact', description: 'Summarize older conversation context' },
+    { id: '/settings', description: 'Update API key, memory and default preferences' },
+    { id: '/sessions', description: 'Browse and resume saved conversations' },
+    { id: '/effort', description: 'Choose reasoning effort' },
+    { id: '/mode', description: 'Permissions: ask, files, guarded auto, or unguarded auto' },
+    { id: '/undo', description: 'Revert the previous turn’s file changes' },
+    { id: '/clear', description: 'Start a fresh conversation' },
+    { id: '/exit', description: 'Exit flashlite' },
+    { id: '/help', description: 'Shortcuts, permissions, and recovery' },
+    { id: '/agents', description: 'Spawn, inspect or stop subagents' },
+];
+// Custom slash commands (discovered from the user/project) are merged in at runtime.
+let paletteCommands = [];
+/** Register additional palette commands (custom slash commands); idempotent. */
+export function registerPaletteCommands(entries) {
+    paletteCommands = entries;
+}
+export function matchingCommands(text) {
+    if (!text.startsWith('/') || /\s/.test(text))
+        return [];
+    const combined = [...COMMANDS, ...paletteCommands];
+    const matches = combined.filter((command) => command.id.startsWith(text.toLowerCase()));
+    // /mode is also a prefix of /model: a fully typed command must win.
+    const exact = matches.find((command) => command.id === text.toLowerCase());
+    return exact ? [exact, ...matches.filter((command) => command !== exact)] : matches;
+}

package/dist/compaction.js

@@ -0,0 +1,66 @@
+export const MAX_COMPACTION_SUMMARY_CHARS = 12_000;
+const RETAIN_RECENT_EXCHANGES = 2;
+/** Locate only complete assistant exchanges; an orphan/pending/duplicate tool blocks compaction. */
+function completeExchanges(history) {
+    const exchanges = [];
+    for (let i = 0; i < history.length; i++) {
+        const message = history[i];
+        if (message.role === 'tool')
+            return null;
+        const calls = message.toolCalls ?? [];
+        if (calls.length && message.role !== 'assistant')
+            return null;
+        if (message.role !== 'assistant')
+            continue;
+        const start = i;
+        const pending = new Set();
+        for (const call of calls) {
+            if (!call.id.trim() || pending.has(call.id))
+                return null;
+            pending.add(call.id);
+        }
+        for (let result = 0; result < calls.length; result++) {
+            const next = history[++i];
+            if (next?.role !== 'tool' || !next.toolCallId || !pending.delete(next.toolCallId))
+                return null;
+        }
+        exchanges.push(start);
+    }
+    return exchanges;
+}
+/**
+ * Summarize complete older work, retaining current instructions and the latest two
+ * exchanges verbatim (including signed thinking). keepFrom identifies the active
+ * task's user message; zero is valid for a long first task. No tool pair is split.
+ */
+export function compactionParts(history, keepFrom) {
+    const exchanges = completeExchanges(history);
+    if (!exchanges)
+        return null;
+    const userTurns = history.flatMap((message, index) => message.role === 'user' ? [index] : []);
+    const boundary = keepFrom ?? userTurns.at(-1);
+    if (boundary === undefined || !Number.isInteger(boundary) || boundary < 0 || boundary >= history.length || history[boundary].role !== 'user')
+        return null;
+    const active = exchanges.filter((index) => index > boundary);
+    // Explicit active-task selection can compact within the task; manual compaction
+    // retains the whole latest user turn when an older turn is available.
+    if ((keepFrom !== undefined || boundary === 0) && active.length > RETAIN_RECENT_EXCHANGES) {
+        const cut = active[active.length - RETAIN_RECENT_EXCHANGES];
+        const instructions = history.slice(boundary, cut).filter((message) => message.role === 'user');
+        return { prefix: history.slice(0, cut), tail: [...instructions, ...history.slice(cut)] };
+    }
+    if (boundary === 0)
+        return null;
+    return { prefix: history.slice(0, boundary), tail: history.slice(boundary) };
+}
+export function compactedHistory(summary, tail, includeTail = true) {
+    if (!includeTail)
+        return [{ role: 'user', content: `Earlier conversation summary (context only):\n${summary}` }];
+    if (!tail.length || tail[0].role !== 'user')
+        throw new Error('compaction tail must begin at a user turn');
+    const first = tail[0];
+    return [{ ...first, content: `Earlier conversation summary (context only):\n${summary}\n\nLatest user message:\n${first.content}` }, ...tail.slice(1)];
+}
+export function validCompactionSummary(value) {
+    return typeof value === 'string' && value.trim().length > 0 && value.length <= MAX_COMPACTION_SUMMARY_CHARS;
+}