mu-harness 0.26.0 → 0.28.0

package/esm/session/agent-session.js

@@ -22,6 +22,77 @@ export const createAgentSession = (config) => {
     let started = false;
     let running = false;
     let controller;
+    // Assemble the request from the CURRENT in-memory messages — the real system (base +
+    // prepareRequest hook injections like the env block + tool prompt blocks), the post-hook
+    // tool set, and the live message list. Reflects "what the next turn would send".
+    const assembleRequest = async () => {
+        const hasSystem = messages[0]?.role === 'system';
+        const system = hasSystem ? textOf(messages[0]) : '';
+        const prepared = await hooks.prepareRequest?.({ system, tools: decorated });
+        const callTools = prepared?.tools ?? decorated;
+        const baseSystem = prepared?.system ?? system;
+        const toolBlock = callTools.map((tool) => tool.prompt?.trim()).filter(Boolean).join('\n');
+        const effectiveSystem = [baseSystem, toolBlock].filter(Boolean).join('\n\n');
+        const body = hasSystem ? messages.slice(1) : messages;
+        const withSystem = effectiveSystem ? [systemMessage(effectiveSystem), ...body] : body;
+        const callMessages = prepared?.messages?.length ? [...withSystem, ...prepared.messages] : withSystem;
+        return { system: effectiveSystem, tools: callTools, messages: callMessages };
+    };
+    const msgText = (m) => m.content
+        .map((p) => p.type === 'text'
+        ? p.text
+        : p.type === 'tool_call'
+            ? `[call ${p.name} ${JSON.stringify(p.input)}]`
+            : p.type === 'tool_result'
+                ? p.content.map((c) => (c.type === 'text' ? c.text : '')).join('')
+                : '')
+        .join(' ')
+        .trim();
+    /** Ask the model to summarize a slice of the conversation (for compaction). */
+    const summarize = async (msgs) => {
+        const transcript = msgs.map((m) => `${m.role}: ${msgText(m)}`).filter(Boolean).join('\n');
+        if (!transcript)
+            return '';
+        let out = '';
+        try {
+            for await (const ev of provider.stream({
+                model: config.model,
+                tools: [],
+                messages: [
+                    {
+                        role: 'system',
+                        content: [{
+                                type: 'text',
+                                text: 'Summarize the conversation below for continuity. Preserve decisions, facts, file paths, code changes, and open tasks. Be concise. Output only the summary.',
+                            }],
+                    },
+                    { role: 'user', content: [{ type: 'text', text: transcript }] },
+                ],
+            })) {
+                if (ev.type === 'text')
+                    out += ev.text;
+            }
+        }
+        catch {
+            return '';
+        }
+        return out.trim();
+    };
+    /** Replace older messages with a summary, keeping the system message + the last N. */
+    const compact = async (opts) => {
+        const keep = Math.max(1, opts?.keepLastTurns ?? 6);
+        const sysCount = messages[0]?.role === 'system' ? 1 : 0;
+        if (messages.length <= sysCount + keep + 1)
+            return;
+        const middle = messages.slice(sysCount, messages.length - keep);
+        if (middle.length === 0)
+            return;
+        const summary = await summarize(middle);
+        if (!summary)
+            return;
+        const summaryMsg = { role: 'user', content: [{ type: 'text', text: `<summary>\n${summary}\n</summary>` }] };
+        messages.splice(sysCount, middle.length, summaryMsg);
+    };
     const send = async (input) => {
         if (running)
             throw new Error('AgentSession: busy (a turn is already running)');
@@ -37,21 +108,12 @@ export const createAgentSession = (config) => {
             const message = toMessage(input);
             messages.push(message);
             emitter.emit({ type: 'turn_start', input: message });
-            const hasSystem = messages[0]?.role === 'system';
-            const system = hasSystem ? textOf(messages[0]) : '';
-            const prepared = await hooks.prepareRequest?.({ system, tools: decorated });
-            const callTools = prepared?.tools ?? decorated;
-            const baseSystem = prepared?.system ?? system;
-            const toolBlock = callTools.map((tool) => tool.prompt?.trim()).filter(Boolean).join('\n');
-            const effectiveSystem = [baseSystem, toolBlock].filter(Boolean).join('\n\n');
-            const body = hasSystem ? messages.slice(1) : messages;
-            const withSystem = effectiveSystem ? [systemMessage(effectiveSystem), ...body] : body;
-            const callMessages = prepared?.messages?.length ? [...withSystem, ...prepared.messages] : withSystem;
+            const request = await assembleRequest();
             const events = run({
                 provider,
                 model: config.model,
-                tools: callTools,
-                messages: callMessages,
+                tools: [...request.tools],
+                messages: [...request.messages],
                 signal: ac.signal,
             });
             for await (const event of events) {
@@ -69,6 +131,15 @@ export const createAgentSession = (config) => {
             controller = undefined;
         }
         emitter.emit(terminal);
+        // After a successful turn, let hooks compact/persist. Failures here never break the turn.
+        if (terminal.type === 'turn_end') {
+            await Promise.resolve(hooks.afterTurn?.({
+                messages,
+                countTokens: (t) => config.provider.countTokens?.(t, config.model) ?? Promise.resolve(undefined),
+                contextWindow: () => config.provider.contextWindow?.(config.model) ?? Promise.resolve(undefined),
+                compact,
+            })).catch(() => { });
+        }
     };
     return {
         id,
@@ -76,6 +147,10 @@ export const createAgentSession = (config) => {
         get messages() {
             return messages;
         },
+        assembleRequest,
+        countTokens: (text) => config.provider.countTokens?.(text, config.model) ?? Promise.resolve(undefined),
+        contextWindow: () => config.provider.contextWindow?.(config.model) ?? Promise.resolve(undefined),
+        compact,
         send,
         abort: () => controller?.abort(),
         subscribe: emitter.subscribe,

package/esm/session/manager.js

@@ -12,6 +12,10 @@ const onFirstMessage = (session, fire) => {
         get tools() {
             return session.tools;
         },
+        assembleRequest: session.assembleRequest?.bind(session),
+        countTokens: session.countTokens?.bind(session),
+        contextWindow: session.contextWindow?.bind(session),
+        compact: session.compact?.bind(session),
         send: async (input) => {
             if (pending) {
                 pending = false;

package/esm/session/persist.js

@@ -10,6 +10,10 @@ export const persistTo = (store, session, persisted = 0) => {
         get tools() {
             return session.tools;
         },
+        assembleRequest: session.assembleRequest?.bind(session),
+        countTokens: session.countTokens?.bind(session),
+        contextWindow: session.contextWindow?.bind(session),
+        compact: session.compact?.bind(session),
         send: async (input) => {
             await session.send(input);
             const all = session.messages;

package/esm/session/types.d.ts

@@ -8,10 +8,29 @@ export type AgentSessionEvent = {
     type: 'error';
     error: unknown;
 };
+/** The request the provider sees for a turn, assembled from the live session. */
+export interface AssembledRequest {
+    /** Final system prompt: base system + prepareRequest hook injections + tool prompt blocks. */
+    system: string;
+    /** Final tool set (after prepareRequest hooks — may differ from session.tools, e.g. per-agent filtering). */
+    tools: readonly Tool[];
+    /** Final message list (system message + body + any hook-injected messages). */
+    messages: readonly Message[];
+}
 export interface AgentSession {
     readonly id: string;
     readonly messages: readonly Message[];
     readonly tools: readonly Tool[];
+    /** Assemble the request from the CURRENT in-memory session — what the next turn would send. */
+    assembleRequest?(): Promise<AssembledRequest>;
+    /** Exact token count of `text` via the model's own tokenizer, when the provider supports it. */
+    countTokens?(text: string): Promise<number | undefined>;
+    /** The active model's context window in tokens, when reportable. */
+    contextWindow?(): Promise<number | undefined>;
+    /** Summarize older messages (keeping the system + last N) to free context. */
+    compact?(opts?: {
+        keepLastTurns?: number;
+    }): Promise<void>;
     send(input: string | ContentPart[]): Promise<void>;
     abort(): void;
     subscribe(listener: (event: AgentSessionEvent) => void): () => void;

package/esm/tui/chat/ChatApp.d.ts

@@ -49,7 +49,9 @@ export interface ChatHost {
         name: string;
         description: string;
     }[];
-    runCommand?(input: string): Promise<{
+    runCommand?(input: string, ctx?: {
+        session?: AgentSession;
+    }): Promise<{
         ok: boolean;
         output?: unknown;
         error?: string;
@@ -75,6 +77,7 @@ export declare class ChatApp {
     private unsubscribeTheme;
     private unsubscribeSubAgents;
     private unsubscribeModelLoading;
+    private modelLoading;
     private readonly runUnsubs;
     private readonly activeRuns;
     private mentionAc;

package/esm/tui/chat/ChatApp.js

@@ -103,6 +103,7 @@ export class ChatApp {
     unsubscribeTheme;
     unsubscribeSubAgents;
     unsubscribeModelLoading;
+    modelLoading = false;
     runUnsubs = new Set();
     activeRuns = new Set();
     mentionAc;
@@ -431,13 +432,18 @@ export class ChatApp {
         this.queue.length = 0;
         this.pendingShell.length = 0;
         this.running = false;
-        this.status.busy = false;
         this.status.context = '';
-        this.stopSpinner();
-        this.setStatus('ready');
+        // A model switch sets this session swap in motion AND kicks off a model load;
+        // don't stomp the "loading…" spinner the load just put up.
+        if (!this.modelLoading) {
+            this.status.busy = false;
+            this.stopSpinner();
+            this.setStatus('ready');
+        }
         this.tui.requestRender(true);
     }
     onModelLoading(model, loading) {
+        this.modelLoading = loading;
         const name = model.split('/').pop() ?? model;
         if (loading) {
             this.status.busy = true;
@@ -819,7 +825,7 @@ export class ChatApp {
             name: c.name,
             description: c.description,
             run: async (args) => {
-                const res = await this.host.runCommand(`/${c.name}${args ? ` ${args}` : ''}`);
+                const res = await this.host.runCommand(`/${c.name}${args ? ` ${args}` : ''}`, { session: this.session });
                 if (res.ok) {
                     if (res.output != null)
                         this.transcript.note(String(res.output));
@@ -1085,7 +1091,14 @@ export class ChatApp {
             this.showError('Export path must stay inside the project directory.');
             return;
         }
-        const system = all.filter((message) => message.role === 'system').map(textOf).join('\n\n');
+        // Assemble the EXACT request from the live session (real system = base + hook injections
+        // + tool prompt blocks). Fall back to the stored messages if the session can't assemble.
+        const last = await this.session?.assembleRequest?.();
+        const system = last
+            ? last.system
+            : all.filter((message) => message.role === 'system').map(textOf).join('\n\n');
+        const requestTools = last?.tools ?? this.session?.tools ?? [];
+        const requestMessages = (last?.messages ?? all).filter((message) => message.role !== 'system');
         const payload = {
             exportedAt: new Date().toISOString(),
             session: {
@@ -1095,14 +1108,16 @@ export class ChatApp {
                 model: this.host.modelRef(),
             },
             request: {
+                // true = the exact payload last sent; false = reconstructed (no turn has run yet).
+                assembled: last != null,
                 system,
-                tools: (this.session?.tools ?? []).map((tool) => ({
+                tools: requestTools.map((tool) => ({
                     name: tool.name,
                     description: tool.description,
                     parameters: tool.parameters,
                     ...(tool.prompt ? { prompt: tool.prompt } : {}),
                 })),
-                messages: all.filter((message) => message.role !== 'system'),
+                messages: requestMessages,
             },
         };
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mu-harness",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Agent harness: createHarness wires mu-core into a host — XDG paths, model registry, plugins, disk-loaded agents & skills, sub-agents, sessions (JSONL + SQLite catalog), slash commands, permission/approval hooks, an optional scheduler, and a composable TUI chat app",
   "license": "MIT",
   "main": "./script/index.js",
@@ -23,8 +23,8 @@
     "@swc/wasm-typescript": "^1.15.0",
     "cli-highlight": "^2.1.11",
     "croner": "^9.0.0",
-    "mu-core": "^0.26.0",
-    "mu-tui": "^0.26.0",
+    "mu-core": "^0.28.0",
+    "mu-tui": "^0.28.0",
     "ws": "^8.18.0"
   },
   "_generatedBy": "dnt@dev",

package/script/channels/channel.js

@@ -25,6 +25,9 @@ const createChannel = (config) => {
         get messages() {
             return session?.messages ?? [];
         },
+        get session() {
+            return session;
+        },
         send: async (input) => (await ensure()).send(input),
         abort: () => session?.abort(),
         subscribe: emitter.subscribe,

package/script/channels/types.d.ts

@@ -1,5 +1,5 @@
 import type { ContentPart, Message } from 'mu-core';
-import type { AgentSessionEvent } from '../session/index.js';
+import type { AgentSession, AgentSessionEvent } from '../session/index.js';
 export type ChannelEvent = AgentSessionEvent | {
     type: 'channel_open';
     title: string;
@@ -14,6 +14,8 @@ export interface Channel {
     readonly title: string;
     readonly started: boolean;
     readonly messages: readonly Message[];
+    /** The live AgentSession, once started — exposes `lastRequest` for inspection commands. */
+    readonly session?: AgentSession;
     send(input: string | ContentPart[]): Promise<void>;
     abort(): void;
     subscribe(listener: (event: AgentSessionEvent) => void): () => void;

package/script/channels/ws/server.js

@@ -114,7 +114,7 @@ function webSocketAdapter(opts) {
                 }
                 case 'command': {
                     const sessionId = msg.sessionId ?? client.sessionId;
-                    const result = await commands.run(msg.text, { sessionId });
+                    const result = await commands.run(msg.text, { sessionId, session: manager.get(sessionId)?.session });
                     if (result.ok) {
                         if (result.output != null) {
                             push({

package/script/commands/defaults.d.ts

@@ -8,4 +8,13 @@ export declare const createSessionsCommand: (sessions: SessionManager, options?:
     cwd?: string;
 }) => Command;
 export declare const createQuitCommand: (onQuit: () => void | Promise<void>) => Command;
+/**
+ * Universal `/context` — the live session's context broken down into all categories
+ * (system / context / instructions / memory / tools / you / agent / tool-output), each
+ * counted with the model's own tokenizer, plus the context-window fill % and a colour
+ * heatmap. Works on every channel.
+ */
+export declare const createContextCommand: () => Command;
+/** Universal `/compact` — manually summarize older messages to free context now. */
+export declare const createCompactCommand: () => Command;
 export declare const createHelpCommand: (list: () => Command[]) => Command;

package/script/commands/defaults.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createHelpCommand = exports.createQuitCommand = exports.createSessionsCommand = exports.createSkillsCommand = exports.createAgentsCommand = void 0;
+exports.createHelpCommand = exports.createCompactCommand = exports.createContextCommand = exports.createQuitCommand = exports.createSessionsCommand = exports.createSkillsCommand = exports.createAgentsCommand = void 0;
 const createAgentsCommand = (agents) => ({
     name: 'agents',
     description: 'List available agents',
@@ -47,6 +47,135 @@ const createQuitCommand = (onQuit) => ({
     },
 });
 exports.createQuitCommand = createQuitCommand;
+const estTokens = (chars) => Math.max(1, Math.round(chars / 4));
+const GRID_COLS = 24;
+const GRID_ROWS = 8;
+const GRID_CELLS = GRID_COLS * GRID_ROWS;
+const BLOCK = '█';
+const FREE = '·';
+// ANSI SGR colours — mu's TUI text utils are ANSI-aware so these render in the terminal;
+// the companion strips them (plain text), keeping the labelled breakdown readable.
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const paint = (s, color) => `${color}${s}${RESET}`;
+const fillColor = (pct) => (pct >= 80 ? '\x1b[31m' : pct >= 50 ? '\x1b[33m' : '\x1b[32m');
+/** Extract a `<tag>…</tag>` block (with tags), or '' when absent. */
+function tagBlock(s, tag) {
+    const i = s.indexOf(`<${tag}>`);
+    const j = s.indexOf(`</${tag}>`);
+    return i !== -1 && j > i ? s.slice(i, j + `</${tag}>`.length) : '';
+}
+/** Split the assembled system into its segments: agent prompt / env / instructions / memory / tool-prompts. */
+function splitSystem(system) {
+    const env = tagBlock(system, 'env');
+    const instructions = tagBlock(system, 'instructions');
+    const memory = tagBlock(system, 'memory');
+    const opens = ['<env>', '<instructions>', '<memory>'].map((t) => system.indexOf(t)).filter((i) => i !== -1);
+    const closes = [
+        [env, '</env>'],
+        [instructions, '</instructions>'],
+        [memory, '</memory>'],
+    ]
+        .filter(([b]) => b)
+        .map(([, c]) => system.indexOf(c) + c.length);
+    const firstOpen = opens.length ? Math.min(...opens) : -1;
+    const lastClose = closes.length ? Math.max(...closes) : -1;
+    return {
+        agent: (firstOpen === -1 ? system : system.slice(0, firstOpen)).trim(),
+        env,
+        instructions,
+        memory,
+        toolPrompts: lastClose === -1 ? '' : system.slice(lastClose).trim(),
+    };
+}
+/**
+ * Universal `/context` — the live session's context broken down into all categories
+ * (system / context / instructions / memory / tools / you / agent / tool-output), each
+ * counted with the model's own tokenizer, plus the context-window fill % and a colour
+ * heatmap. Works on every channel.
+ */
+const createContextCommand = () => ({
+    name: 'context',
+    description: 'Show the live context: per-category tokens, window fill %, and a heatmap',
+    run: async (_args, ctx) => {
+        const last = await ctx.session?.assembleRequest?.();
+        if (!last)
+            return { ok: true, output: 'No session in memory yet — start a conversation first.' };
+        const sys = splitSystem(last.system);
+        const toolSchemas = last.tools
+            .map((t) => JSON.stringify({ name: t.name, description: t.description, parameters: t.parameters }))
+            .join('\n');
+        const body = last.messages.filter((m) => m.role !== 'system');
+        const byRole = (role) => body.filter((m) => m.role === role).map((m) => JSON.stringify(m.content)).join('\n');
+        const count = ctx.session?.countTokens;
+        const measure = async (text) => {
+            if (!text)
+                return { n: 0, exact: true };
+            if (count) {
+                const n = await count(text);
+                if (n !== undefined)
+                    return { n, exact: true };
+            }
+            return { n: estTokens(text.length), exact: false };
+        };
+        // label, text, ANSI colour — one per category, in render order.
+        const SPEC = [
+            ['system', sys.agent, '\x1b[36m'], // cyan — the agent prompt
+            ['context', sys.env, '\x1b[33m'], // yellow — the <env> block
+            ['instructions', sys.instructions, '\x1b[34m'], // blue — AGENTS.md / CLAUDE.md
+            ['memory', sys.memory, '\x1b[35m'], // magenta — MEMORY.md
+            ['tools', `${toolSchemas}\n${sys.toolPrompts}`, '\x1b[31m'], // red — schemas + tool prompts
+            ['you', byRole('user'), '\x1b[32m'], // green — your messages
+            ['agent', byRole('assistant'), '\x1b[94m'], // bright blue — assistant replies
+            ['tool-out', byRole('tool'), '\x1b[90m'], // grey — tool results
+        ];
+        const measured = await Promise.all(SPEC.map(([, text]) => measure(text)));
+        const cats = SPEC.map(([label, , color], i) => ({ label, n: measured[i].n, color })).filter((c) => c.n > 0);
+        const exact = measured.every((m) => m.exact);
+        const total = cats.reduce((s, c) => s + c.n, 0);
+        const window = (await ctx.session?.contextWindow?.()) ?? 0;
+        const mark = (n) => (exact ? `${n}` : `~${n}`);
+        const lines = [`context — tokens (${exact ? 'exact, model tokenizer' : 'estimated ≈ chars/4'}):`];
+        for (const c of cats)
+            lines.push(`  ${paint(BLOCK, c.color)} ${c.label.padEnd(13)} ${mark(c.n)}`);
+        const pctNum = window ? Math.round((total / window) * 100) : 0;
+        const pct = window ? ` / ${window} ${paint(`(${pctNum}%)`, fillColor(pctNum))}` : '';
+        lines.push(`  ${' '.repeat(15)}── ${mark(total)}${pct}`);
+        if (window > 0) {
+            const cellTokens = Math.max(1, window / GRID_CELLS);
+            const cells = [];
+            for (const c of cats) {
+                for (let i = 0; i < Math.round(c.n / cellTokens) && cells.length < GRID_CELLS; i++)
+                    cells.push(paint(BLOCK, c.color));
+            }
+            while (cells.length < GRID_CELLS)
+                cells.push(paint(FREE, DIM));
+            cells.length = GRID_CELLS;
+            lines.push('');
+            for (let r = 0; r < GRID_ROWS; r++)
+                lines.push(`  ${cells.slice(r * GRID_COLS, (r + 1) * GRID_COLS).join('')}`);
+        }
+        return { ok: true, output: lines.join('\n') };
+    },
+});
+exports.createContextCommand = createContextCommand;
+/** Universal `/compact` — manually summarize older messages to free context now. */
+const createCompactCommand = () => ({
+    name: 'compact',
+    description: 'Summarize older messages to free up context now',
+    run: async (_args, ctx) => {
+        if (!ctx.session?.compact)
+            return { ok: true, output: 'Compaction is not available on this session.' };
+        const before = ctx.session.messages?.length ?? 0;
+        await ctx.session.compact();
+        const after = ctx.session.messages?.length ?? 0;
+        return {
+            ok: true,
+            output: after < before ? `Compacted: ${before} → ${after} messages.` : 'Nothing to compact yet.',
+        };
+    },
+});
+exports.createCompactCommand = createCompactCommand;
 const createHelpCommand = (list) => ({
     name: 'help',
     description: 'Show available commands',

package/script/commands/index.d.ts

@@ -1,4 +1,4 @@
-export { createAgentsCommand, createHelpCommand, createQuitCommand, createSessionsCommand, createSkillsCommand, } from './defaults.js';
+export { createAgentsCommand, createCompactCommand, createContextCommand, createHelpCommand, createQuitCommand, createSessionsCommand, createSkillsCommand, } from './defaults.js';
 export { createCommandRegistry } from './registry.js';
 export { createSkillCommand, type SkillCommandDeps } from './skill.js';
 export type { Command, CommandContext, CommandRegistry, CommandResult } from './types.js';

package/script/commands/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSkillCommand = exports.createCommandRegistry = exports.createSkillsCommand = exports.createSessionsCommand = exports.createQuitCommand = exports.createHelpCommand = exports.createAgentsCommand = void 0;
+exports.createSkillCommand = exports.createCommandRegistry = exports.createSkillsCommand = exports.createSessionsCommand = exports.createQuitCommand = exports.createHelpCommand = exports.createContextCommand = exports.createCompactCommand = exports.createAgentsCommand = void 0;
 var defaults_js_1 = require("./defaults.js");
 Object.defineProperty(exports, "createAgentsCommand", { enumerable: true, get: function () { return defaults_js_1.createAgentsCommand; } });
+Object.defineProperty(exports, "createCompactCommand", { enumerable: true, get: function () { return defaults_js_1.createCompactCommand; } });
+Object.defineProperty(exports, "createContextCommand", { enumerable: true, get: function () { return defaults_js_1.createContextCommand; } });
 Object.defineProperty(exports, "createHelpCommand", { enumerable: true, get: function () { return defaults_js_1.createHelpCommand; } });
 Object.defineProperty(exports, "createQuitCommand", { enumerable: true, get: function () { return defaults_js_1.createQuitCommand; } });
 Object.defineProperty(exports, "createSessionsCommand", { enumerable: true, get: function () { return defaults_js_1.createSessionsCommand; } });

package/script/commands/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentSession } from '../session/index.js';
 export interface CommandResult {
     ok: boolean;
     output?: unknown;
@@ -5,6 +6,8 @@ export interface CommandResult {
 }
 export interface CommandContext {
     sessionId?: string;
+    /** The live session for this invocation — lets a command inspect what the model actually saw. */
+    session?: AgentSession;
 }
 export interface Command {
     name: string;

package/script/harness/compaction.d.ts

@@ -0,0 +1,14 @@
+import type { AgentSessionHooks } from '../hooks/index.js';
+export interface CompactionOptions {
+    /** Compact once estimated usage exceeds this fraction of the context window. Default 0.8. */
+    thresholdPct?: number;
+    /** Number of most-recent messages kept verbatim through a compaction. Default 6. */
+    keepLastTurns?: number;
+}
+/**
+ * An `afterTurn` hook that auto-compacts the conversation as it approaches the context
+ * window: when the estimated token usage crosses `thresholdPct`, older messages are
+ * summarized (keeping the system message + the last `keepLastTurns`). The gap between the
+ * threshold and the window is the reserved compaction buffer.
+ */
+export declare function createCompactionHook(opts?: CompactionOptions): AgentSessionHooks;

package/script/harness/compaction.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCompactionHook = createCompactionHook;
+/**
+ * An `afterTurn` hook that auto-compacts the conversation as it approaches the context
+ * window: when the estimated token usage crosses `thresholdPct`, older messages are
+ * summarized (keeping the system message + the last `keepLastTurns`). The gap between the
+ * threshold and the window is the reserved compaction buffer.
+ */
+function createCompactionHook(opts = {}) {
+    const thresholdPct = opts.thresholdPct ?? 0.8;
+    const keepLastTurns = opts.keepLastTurns ?? 6;
+    return {
+        afterTurn: async ({ messages, contextWindow, compact }) => {
+            const window = await contextWindow();
+            if (!window)
+                return;
+            // Cheap chars/4 estimate — avoids a tokenizer round-trip on every turn.
+            const estimate = messages.reduce((n, m) => n + JSON.stringify(m.content).length, 0) / 4;
+            if (estimate > window * thresholdPct)
+                await compact({ keepLastTurns });
+        },
+    };
+}