@maci0/dsh-caveman 0.16.2

package/lib/index.js

@@ -0,0 +1,616 @@
+/**
+ * dsh-caveman: Caveman terse-talk mode, as a DeepSeek Harness plugin.
+ *
+ * Four capabilities, all mounted through public Cordis extension points:
+ *
+ * - the bundled skills (`caveman`, `cavecrew`, `-commit`, `-review`,
+ *   `-compress`, `-stats`, `-help`, plus six work patterns) become one
+ *   `ctx.skills` provider;
+ * - while a level other than `off` is active, the mode-filtered ruleset is
+ *   contributed to the system prompt on every assembly;
+ * - the level is switchable from the model (`caveman` tool) and the human
+ *   (`/caveman` command);
+ * - the `caveman` settings namespace makes the level persistent and pairs with
+ *   this package's browser half, which renders the card in the Web client's
+ *   Plugins page, on the caveman row's Configure control.
+ *
+ * Skill content is adapted from the reference implementation
+ * (https://github.com/JuliusBrussee/caveman, MIT, © JuliusBrussee). Only the
+ * skill (talking-style) half is ported: the proxy, CLI verbs, and Cloud
+ * engine need an external runtime the harness has no extension point for.
+ *
+ * @module dsh-caveman
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import z from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { buildModeInstructions, isDeactivationCommand, normalizeCommandMode, normalizeMode, resolveDefaultMode, RUNTIME_MODES, } from './modes.js';
+import { createSkillProvider } from './skills.js';
+import { compressFile } from './compress-pipeline.js';
+import { MAX_FILE_SIZE } from './compress-files.js';
+import { parseFrontmatter } from './frontmatter.js';
+/** Plugin name as it appears in the loader. */
+export const name = 'caveman';
+/**
+ * Route the browser half reads for the level in use and its source. The card
+ * and the chip cannot see the env, the upstream config file, or a
+ * session-local level, so they ask the host instead of the settings document.
+ */
+export const LEVEL_ROUTE = '/caveman/level';
+/**
+ * Every accepted level as a schema union, shared by the persisted settings and
+ * the plugin row so the accepted set is declared once.
+ */
+const ModeSchema = z.union([...RUNTIME_MODES]);
+/** The levels a one-shot `once` call accepts: every level but `off`. */
+const ONCE_MODES = RUNTIME_MODES.filter((mode) => mode !== 'off');
+/**
+ * Row schema: the accepted levels and the size cap live here.
+ *
+ * Both fields are volatile, the only kind the settings document accepts: a
+ * change commits into the running config without remounting the plugin. Each is
+ * read at the moment it is used (the level at every prompt assembly, the size
+ * cap at every compress call), so an edit from the Plugins card takes effect on
+ * the next use rather than on a restart.
+ *
+ * `defaultMode` carries no default, so absence keeps flowing to
+ * `resolveDefaultMode`. A schema default would fill the field before `apply`,
+ * which would silently outrank `CAVEMAN_DEFAULT_MODE` and
+ * `~/.config/caveman/config.json`.
+ */
+export const Config = z.object({
+    defaultMode: ModeSchema.volatile(),
+    maxFileSize: z.number().min(1).default(MAX_FILE_SIZE).volatile(),
+});
+/** Upstream config file, read the way upstream reads it. */
+const UPSTREAM_CONFIG_PATH = join(homedir(), '.config', 'caveman', 'config.json');
+/**
+ * Read the upstream config file's `defaultMode`, ignoring everything that
+ * would make startup fail: a missing file, an unreadable file, invalid JSON,
+ * or a non-object document all mean "no file default".
+ * @param path - config file path; the upstream location unless tests override it.
+ * @returns the parsed document, or `undefined` when there is nothing usable.
+ */
+export function readUpstreamConfigFile(path = UPSTREAM_CONFIG_PATH) {
+    let source;
+    try {
+        if (!existsSync(path))
+            return undefined;
+        source = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    return parsed;
+}
+/**
+ * Mount the plugin.
+ * @param ctx - the host context.
+ * @param config - the schema-resolved row configuration.
+ */
+export function apply(ctx, config) {
+    // Reject configuration that would silently do the wrong thing. The loader
+    // already validated the row; this keeps a caller that bypasses it from
+    // mounting a bad level.
+    const configured = config.defaultMode.get();
+    if (configured !== undefined && normalizeMode(configured) === undefined) {
+        throw new Error(`[caveman] defaultMode must be one of ${RUNTIME_MODES.join(', ')}; got ${JSON.stringify(configured)}`);
+    }
+    /**
+     * The size cap as it stands for this call. Reading it per compress keeps a
+     * card edit live; the check runs on every read because the settings document
+     * only validates the schema's bounds, not the value a later writer left.
+     */
+    const maxFileSize = () => {
+        const value = config.maxFileSize.get();
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new Error(`[caveman] maxFileSize must be a positive number of bytes; got ${JSON.stringify(value)}`);
+        }
+        return value;
+    };
+    // Fail at load on a row that is already unusable, rather than on first use.
+    maxFileSize();
+    // `<package>/skills`, resolved from this module's own location.
+    const skillsDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+    // The env and the upstream file are read once, at mount; the row is read at
+    // every use, so clearing it falls back to them rather than to its old value.
+    const envLevel = { CAVEMAN_DEFAULT_MODE: process.env['CAVEMAN_DEFAULT_MODE'] };
+    const configFile = readUpstreamConfigFile();
+    // Parsed once, at load: the ruleset is filtered per assembly, so the
+    // frontmatter must not have to be re-read for every request. A missing body
+    // means a broken install: fail while loading rather than injecting a silently
+    // truncated ruleset.
+    const skillBody = parseFrontmatter(readFileSync(join(skillsDir, 'caveman', 'SKILL.md'), 'utf8')).body.trimStart();
+    const warn = (message) => {
+        console.warn(`[caveman] ${message}`);
+    };
+    /** Session-local level, used when the profile write cannot hold the level. */
+    let override;
+    let modeGeneration = 0;
+    /**
+     * The level in use and its source. The row is live: a committed settings
+     * change updates the volatile reference in place.
+     */
+    const activeLevel = () => override !== undefined
+        ? { mode: override, source: 'session' }
+        : resolveDefaultMode({ configured: config.defaultMode.get(), env: envLevel, configFile });
+    const activeMode = () => activeLevel().mode;
+    /**
+     * Persist a level through the settings document; false when it cannot hold it.
+     * @param next - the level to write.
+     * @param signal - cancels the write when the calling tool was cancelled.
+     */
+    const persist = async (next, signal) => {
+        const settings = ctx.get('settings');
+        const entryId = ctx.fiber?.entry?.options?.id;
+        if (settings === undefined || typeof entryId !== 'string' || normalizeMode(next) === undefined)
+            return false;
+        signal?.throwIfAborted();
+        let persisted;
+        try {
+            await settings.update(entryId, { defaultMode: next });
+            persisted = true;
+        }
+        catch (error) {
+            warn(`could not persist level "${next}": ${error instanceof Error ? error.message : String(error)}`);
+            persisted = false;
+        }
+        // Outside the try: an abort is not a persistence failure to be swallowed.
+        signal?.throwIfAborted();
+        return persisted;
+    };
+    const setMode = async (next, signal) => {
+        signal?.throwIfAborted();
+        const started = ++modeGeneration;
+        const previous = activeMode();
+        const persisted = await persist(next, signal);
+        // A refused older request cannot restore a level the human already ended.
+        if (started === modeGeneration)
+            override = persisted ? undefined : next;
+        const mode = activeMode();
+        return { previous, mode, changed: mode !== previous };
+    };
+    /**
+     * Turn the level off because the human's own message was a deactivation
+     * command.
+     *
+     * The override is set before the settings write is awaited: the durable
+     * `user/message` event arrives before the turn's prompt is assembled, and
+     * awaiting the document would let that same turn assemble with the ruleset
+     * still injected: the one turn the user just asked to end. A committed
+     * document then becomes the source of truth again, so the card and the
+     * prompt cannot disagree.
+     */
+    const deactivateFromMessage = () => {
+        if (activeMode() === 'off')
+            return;
+        const started = ++modeGeneration;
+        override = 'off';
+        void persist('off').then((persisted) => {
+            if (persisted && started === modeGeneration)
+                override = undefined;
+        });
+    };
+    ctx.on('loader/volatile-update', () => {
+        modeGeneration += 1;
+        override = undefined;
+    });
+    ctx.inject(['systemPrompt'], (scope) => {
+        scope.systemPrompt.section({
+            name: 'caveman',
+            order: 700, // after the persona prefix, before tool guidance
+            // Evaluated at each assembly, so a level change lands on the next request.
+            // `off` returns empty text, which assembly drops.
+            text: () => buildModeInstructions({ mode: activeMode(), skillBody }),
+        });
+    });
+    ctx.inject(['skills'], (scope) => {
+        scope.skills.registerProvider(() => createSkillProvider({ skillsDir, onWarn: warn }));
+    });
+    ctx.inject(['tools'], (scope) => {
+        scope.tools.register(createModeTool(activeMode, setMode, (exec) => readSessionUsage(scope, exec)));
+        scope.tools.register(createCompressTool(maxFileSize));
+    });
+    ctx.inject(['commands'], (scope) => {
+        scope.commands.register({
+            name: 'caveman',
+            description: '🪨 Set the caveman level (lite, full, ultra, wenyan-*, off) or report the current one.',
+            input: { hint: 'lite | full | ultra | wenyan-lite | wenyan-full | wenyan-ultra | off' },
+            handler: async (invocation) => handleModeCommand(invocation, activeMode, setMode),
+        });
+        scope.commands.register({
+            name: 'caveman-compress',
+            description: '🗜 Compress a memory file with local rules (backup kept).',
+            input: { hint: '<filepath>' },
+            handler: async (invocation) => handleCompressCommand(invocation, maxFileSize()),
+        });
+    });
+    ctx.inject(['webServer', 'connection'], (scope) => {
+        scope.effect(() => scope.webServer.register({
+            kind: 'exact',
+            path: LEVEL_ROUTE,
+            handler: (req, res) => {
+                const rejection = scope.connection.requestRejection(req);
+                if (rejection !== undefined) {
+                    res.statusCode = rejection;
+                    res.end();
+                    return;
+                }
+                if (req.method !== undefined && req.method !== 'GET') {
+                    res.statusCode = 405;
+                    res.setHeader('allow', 'GET');
+                    res.end();
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.setHeader('cache-control', 'no-store');
+                res.end(JSON.stringify(activeLevel()));
+            },
+        }), `caveman: GET ${LEVEL_ROUTE}`);
+    });
+    // "stop caveman" / "normal mode" typed as an ordinary message, given the
+    // same effect as `/caveman off`. The command path is unaffected: this only
+    // claims messages that are exactly the command and come from the human.
+    ctx.on('session/event', (_session, event) => {
+        if (event.type !== 'user/message')
+            return;
+        const text = userMessageText(event.data);
+        if (text === undefined || !isDeactivationCommand(text))
+            return;
+        deactivateFromMessage();
+    });
+}
+/**
+ * Read the plain text of a genuine user message.
+ *
+ * Injected context (skill bodies, file references, replayed history) rides the
+ * same event stream, so a message only counts when the harness marks it as the
+ * user's own; an injected instruction that happened to read "normal mode" must
+ * never toggle the level.
+ * @param data - the `user/message` event payload.
+ * @returns the concatenated text blocks, or `undefined` when this is not the
+ * human's own text.
+ */
+function userMessageText(data) {
+    if (data === null || typeof data !== 'object')
+        return undefined;
+    const message = data;
+    if (message.source?.kind !== 'user')
+        return undefined;
+    if (!Array.isArray(message.content))
+        return undefined;
+    const text = message.content
+        .map((block) => (block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
+        .join('\n');
+    return text.trim() === '' ? undefined : text;
+}
+/**
+ * Read this session's cumulative provider-reported usage through the
+ * token-meter `tokenUsage` projection, when the host mounts it.
+ *
+ * Counts only what the provider reported: never a saving, a percentage, or
+ * a cost. `undefined` when the service, the session, or the unit is absent.
+ * @param scope - the tools-callback scope, which may carry `sessionProjections`.
+ * @param exec - the tool execution, carrying the calling agent's session.
+ * @returns the usage totals, or `undefined`.
+ */
+function readSessionUsage(scope, exec) {
+    // Read through the accessor: `sessionProjections` is an optional seam, and a
+    // Cordis context throws on a property access for a service it does not
+    // provide, which would turn "no usage available" into a failed tool call.
+    const projections = scope.get('sessionProjections');
+    const session = exec?.agent?.session;
+    if (projections === undefined || session === undefined)
+        return undefined;
+    let state;
+    try {
+        state = projections.stateOf(session, 'tokenUsage');
+    }
+    catch {
+        return undefined;
+    }
+    const totals = state?.totals;
+    if (totals === undefined)
+        return undefined;
+    // The unit's own bucket names, mapped to this plugin's labels.
+    return {
+        input: totals.uncachedInputTokens ?? 0,
+        output: totals.outputTokens ?? 0,
+        cacheRead: totals.cacheReadTokens ?? 0,
+        cacheWrite: totals.cacheWriteTokens ?? 0,
+    };
+}
+/**
+ * Build the model-facing level tool.
+ * @param getMode - reads the active level.
+ * @param setMode - applies and persists a level.
+ * @param getUsage - reads this session's provider-reported usage, when available.
+ * @returns the registered tool definition.
+ */
+function createModeTool(getMode, setMode, getUsage) {
+    return defineTool({
+        name: 'caveman',
+        // The `enum` below already names every level, and the injected ruleset
+        // explains what each one does; repeating both here only costs tokens.
+        description: 'Set or report the caveman level, which governs how terse replies are. '
+            + 'The level persists in the user settings document. '
+            + 'Call with no arguments to report the current level. '
+            + 'A per-call `mode` applies to this call only and is not persisted.',
+        parameters: {
+            mode: {
+                type: 'string',
+                enum: [...RUNTIME_MODES],
+                description: 'Level to activate and persist. Omit to report the current level.',
+            },
+            once: {
+                type: 'string',
+                enum: [...ONCE_MODES],
+                description: 'Level for this call only. Not persisted; `mode` wins when both are given.',
+            },
+            usage: {
+                type: 'boolean',
+                description: 'Include this session’s provider-reported token totals (input, output, cache read/write). Never a saving.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    mode: { type: 'string', enum: [...RUNTIME_MODES], required: true },
+                    previous: { type: 'string', enum: [...RUNTIME_MODES], required: true },
+                    changed: { type: 'boolean', required: true },
+                    active: { type: 'boolean', required: true },
+                    once: { type: 'string', enum: [...ONCE_MODES] },
+                    usage: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            input: { type: 'number', required: true },
+                            output: { type: 'number', required: true },
+                            cacheRead: { type: 'number', required: true },
+                            cacheWrite: { type: 'number', required: true },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModeResult(value) }],
+        },
+        async execute(args, exec) {
+            // A cancelled call must not start, and must not persist a level it can
+            // no longer report.
+            exec?.signal?.throwIfAborted();
+            const once = args.once;
+            const previous = getMode();
+            if (args.mode === undefined) {
+                return {
+                    mode: once ?? previous,
+                    previous,
+                    changed: false,
+                    active: (once ?? previous) !== 'off',
+                    ...(once !== undefined ? { once } : {}),
+                    ...usageField(args, exec, getUsage),
+                };
+            }
+            const applied = await setMode(args.mode, exec?.signal);
+            return {
+                mode: applied.mode,
+                previous: applied.previous,
+                changed: applied.changed,
+                active: applied.mode !== 'off',
+                ...(once !== undefined ? { once } : {}),
+                ...usageField(args, exec, getUsage),
+            };
+        },
+    });
+}
+/**
+ * Read the optional `usage` flag's field: the session totals when asked and
+ * available, otherwise nothing. Savings are never inferred: the log has no
+ * unbuilt baseline to subtract.
+ */
+function usageField(args, exec, getUsage) {
+    if (getUsage === undefined)
+        return {};
+    if (args === null || typeof args !== 'object')
+        return {};
+    if (args['usage'] !== true)
+        return {};
+    const usage = getUsage(exec);
+    return usage === undefined ? {} : { usage };
+}
+/**
+ * Build the model-facing compress tool. Local deterministic rules only:
+ * no model call, no bytes leave the machine.
+ * @param maxFileSize - reads the configured size cap in bytes, so a card edit
+ * applies to the next call.
+ * @returns the registered tool definition.
+ */
+function createCompressTool(maxFileSize) {
+    return defineTool({
+        name: 'caveman-compress',
+        description: 'Compress a natural-language file (memory file, todo list) with local '
+            + 'caveman rules. Code, URLs, paths, and headings are preserved; the '
+            + 'original is backed up out-of-tree.',
+        parameters: {
+            filepath: {
+                type: 'string',
+                required: true,
+                description: 'Path of the file to compress; a relative path resolves against the session working directory.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ok: { type: 'boolean', required: true },
+                    reason: { type: 'string' },
+                    backupPath: { type: 'string' },
+                    originalChars: { type: 'number' },
+                    compressedChars: { type: 'number' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderCompressResult(value) }],
+        },
+        async execute(args, exec) {
+            exec?.signal?.throwIfAborted();
+            // The schema owns the type; an empty path is the one shape it cannot see.
+            if (args.filepath.trim() === '') {
+                throw new Error('caveman-compress needs a filepath string.');
+            }
+            const target = sessionPath(args.filepath, exec?.agent);
+            const cwd = exec?.agent?.session?.header?.cwd;
+            // The model may be steered by file content it read, so it writes only inside
+            // the session workspace, as the harness's own write tool does by default.
+            // The human /caveman-compress names its own file and is not confined.
+            if (cwd !== undefined && !insideWorkspace(target, cwd)) {
+                return { ok: false, reason: `${args.filepath} is outside the session workspace ${cwd}.` };
+            }
+            const outcome = compressFile(target, maxFileSize());
+            // The write is atomic but not free; a cancelled call must not claim it.
+            exec?.signal?.throwIfAborted();
+            return outcome;
+        },
+    });
+}
+/**
+ * Whether `target` (symlinks resolved) lies inside the `root` directory. A
+ * target that does not exist is judged by its resolved path; `compressFile`
+ * then reports it missing.
+ * @param target - absolute path the tool would rewrite.
+ * @param root - the session workspace.
+ * @returns true when the real target is the root or below it.
+ */
+function insideWorkspace(target, root) {
+    const real = (path) => (existsSync(path) ? realpathSync(path) : resolve(path));
+    const rel = relative(real(root), real(target));
+    return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/**
+ * Resolve a file path the way the harness's own file tools do: a relative path
+ * means the calling agent's session workspace, not the server's launch
+ * directory. Without a session cwd the path is left for `compressFile` to
+ * resolve against the process cwd.
+ * @param filepath - the path as the model or the human wrote it.
+ * @param agent - the calling agent, when the host supplied one.
+ * @returns the path `compressFile` should open.
+ */
+function sessionPath(filepath, agent) {
+    const cwd = agent?.session?.header?.cwd;
+    return cwd === undefined ? filepath : resolve(cwd, filepath);
+}
+/**
+ * Phrase one successful compression. Shared by the model-facing tool and the
+ * human command, which report the same three numbers.
+ * @param originalChars - body length before compression.
+ * @param compressedChars - body length after compression.
+ * @param backupPath - out-of-tree backup file path.
+ * @returns the sentence both surfaces report.
+ */
+function compressSentence(originalChars, compressedChars, backupPath) {
+    return `Compressed ${originalChars} to ${compressedChars} chars. Original backed up at ${backupPath}.`;
+}
+/**
+ * Render the canonical compress value for the model.
+ * @param value - the canonical value returned by `execute`.
+ * @returns model-facing prose.
+ */
+function renderCompressResult(value) {
+    const record = (value ?? {});
+    if (record['ok'] !== true) {
+        return typeof record['reason'] === 'string' ? record['reason'] : 'compression failed';
+    }
+    return compressSentence(typeof record['originalChars'] === 'number' ? record['originalChars'] : 0, typeof record['compressedChars'] === 'number' ? record['compressedChars'] : 0, typeof record['backupPath'] === 'string' ? record['backupPath'] : 'unknown');
+}
+/**
+ * Phrase one level outcome. Shared by the model-facing tool and the human
+ * command, which report the same three transitions.
+ * @param mode - the level now active.
+ * @param previous - the level before the call.
+ * @param changed - whether the call moved the level.
+ * @returns the sentence both surfaces start from.
+ */
+function modeSentence(mode, previous, changed) {
+    if (!changed)
+        return `Caveman level: ${mode}.`;
+    return mode === 'off'
+        ? `Caveman off (was ${previous}). Normal behavior.`
+        : `Caveman level: ${mode} (was ${previous}).`;
+}
+/**
+ * Render the canonical tool value for the model.
+ * @param value - the canonical value returned by `execute`.
+ * @returns model-facing prose.
+ */
+function renderModeResult(value) {
+    const record = (value ?? {});
+    const mode = typeof record['mode'] === 'string' ? record['mode'] : 'unknown';
+    const previous = typeof record['previous'] === 'string' ? record['previous'] : mode;
+    const changed = record['changed'] === true;
+    const active = record['active'] === true;
+    const once = typeof record['once'] === 'string' ? record['once'] : undefined;
+    const usage = record['usage'];
+    const core = (!changed && !active)
+        ? 'Caveman is off. Normal behavior.'
+        : active
+            ? `${modeSentence(mode, previous, changed)} The ruleset is injected into every request.`
+            : modeSentence(mode, previous, changed);
+    const onceLine = once !== undefined ? ` Reply to this call in ${once}; the persisted level is unchanged.` : '';
+    if (usage === undefined)
+        return `${core}${onceLine}`;
+    const line = (name) => typeof usage[name] === 'number' ? usage[name] : 0;
+    return `${core}${onceLine} Session usage so far: input ${line('input')}, output ${line('output')}, cache read ${line('cacheRead')}, cache write ${line('cacheWrite')}. Savings unknown without a measured comparison.`;
+}
+/**
+ * Handle the human `/caveman [level]` command.
+ * @param invocation - the command invocation.
+ * @param getMode - reads the active level.
+ * @param setMode - applies and persists a level.
+ * @returns the direct-UI result.
+ */
+async function handleModeCommand(invocation, getMode, setMode) {
+    const input = invocation.rawInput.trim().toLowerCase();
+    if (input === '')
+        return { kind: 'success', text: modeSentence(getMode(), getMode(), false) };
+    const requested = isDeactivationCommand(input) ? 'off' : normalizeCommandMode(input);
+    if (requested === undefined) {
+        return {
+            kind: 'error',
+            text: `Unknown caveman level "${invocation.rawInput.trim()}". Use one of: ${RUNTIME_MODES.join(', ')}.`,
+        };
+    }
+    const { previous, mode, changed } = await setMode(requested);
+    return { kind: 'success', text: modeSentence(mode, previous, changed) };
+}
+/**
+ * Handle the human `/caveman-compress <filepath>` command.
+ * @param invocation - the command invocation.
+ * @returns the direct-UI result.
+ */
+async function handleCompressCommand(invocation, maxFileSize) {
+    const filepath = invocation.rawInput.trim();
+    if (filepath === '') {
+        return { kind: 'error', text: 'Usage: /caveman-compress <filepath>' };
+    }
+    const outcome = compressFile(sessionPath(filepath, invocation.agent), maxFileSize);
+    if (!outcome.ok)
+        return { kind: 'error', text: outcome.reason };
+    return {
+        kind: 'success',
+        text: compressSentence(outcome.originalChars, outcome.compressedChars, outcome.backupPath),
+    };
+}