@fabric-harness/sdk 1.12.2 → 1.14.0

package/dist/session.js

@@ -8,15 +8,69 @@ import { defaultLoopRuntime } from './loop.js';
 import { defaultModelProvider, generateWithRuntime } from './model.js';
 import { clampCommandTimeout, evaluateCommandPolicy, evaluateToolCallPolicy } from './policy.js';
 import { buildResultRetryPrompt, validateResult } from './result.js';
-import { evaluateContextBudget, isContextOverflowError } from './context-budget.js';
+import { estimateSessionEntryTokens, evaluateContextBudget, isContextOverflowError } from './context-budget.js';
 import { policiedSandboxEnv } from './policied-sandbox.js';
 import { createSandboxEnv, createScopedSandboxEnv } from './sandbox.js';
+import { createFabricFs } from './filesystem.js';
 import { registerSandbox, serializeSandboxRef, unregisterSandbox } from './sandbox-ref.js';
 import path from 'node:path';
 import { defaultSessionStore } from './store.js';
-import { createBuiltinTools, createCommandTools, shellQuote } from './tools.js';
+import { createActivateSkillTool, createBuiltinTools, createCommandTools, shellQuote } from './tools.js';
+import { formatPackagedSkillResourceList, readPackagedSkillFile } from './skills.js';
 import { MAX_TASK_DEPTH } from './types.js';
 let nextTaskId = 0;
+const CROCKFORD_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const AFFINITY_KEY_REGEX = /^aff_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+function encodeBase32(buf, length) {
+    let result = '';
+    let bitIndex = 0; // 0 = MSB of buf[0]
+    for (let i = 0; i < length; i++) {
+        let value = 0;
+        for (let j = 0; j < 5; j++) {
+            const byteIndex = Math.floor(bitIndex / 8);
+            const bitInByte = 7 - (bitIndex % 8);
+            const byte = buf[byteIndex] ?? 0;
+            const bit = (byte >> bitInByte) & 1;
+            value = (value << 1) | bit;
+            bitIndex++;
+        }
+        result += CROCKFORD_ALPHABET[value];
+    }
+    return result;
+}
+/**
+ * Generate a deterministic `aff_\u003cULID\u003e` affinity key from an
+ * `(agentId, sessionId)` pair. The same pair always produces the same key,
+ * which is stable across restarts. Different pairs produce different keys
+ * with overwhelming probability.
+ */
+export function generateAffinityKey(agentId, sessionId) {
+    const hash = createHash('sha256').update(agentId).update('\0').update(sessionId).digest();
+    // Build a 128-bit buffer from the hash, clearing the top 5 bits of the
+    // first byte so the first Crockford base32 char is in [0-7].
+    const combined = Buffer.alloc(16);
+    combined[0] = (hash[0] ?? 0) & 0x07;
+    combined.set(hash.slice(1, 16), 1);
+    return `aff_${encodeBase32(combined, 26)}`;
+}
+export function isValidAffinityKey(key) {
+    return AFFINITY_KEY_REGEX.test(key);
+}
+const COMPACTION_SUMMARIZATION_SYSTEM_PROMPT = 'Summarize durable agent session history for future context. Preserve user goals, decisions, tool/command effects, files touched, errors, policy/approval events, and pending work. Do not include secrets.';
+const TURN_PREFIX_SUMMARIZATION_PROMPT = `This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.
+
+Summarize the prefix to provide context for the retained suffix:
+
+## Original Request
+[What did the user ask for in this turn?]
+
+## Early Progress
+- [Key decisions and work done in the prefix]
+
+## Context for Suffix
+- [Information needed to understand the retained recent work]
+
+Be concise. Focus on what's needed to understand the kept suffix.`;
 export class StubFabricSession {
     id;
     agent;
@@ -25,6 +79,7 @@ export class StubFabricSession {
         create: (options) => this.createCheckpoint(options),
         restore: (options) => this.restoreCheckpoint(options),
     };
+    fs;
     approval = {
         request: (input) => this.requestCustomApproval(input),
     };
@@ -47,12 +102,14 @@ export class StubFabricSession {
     /** Set when this session has registered its sandbox in the in-process ref registry. */
     ownedSandboxRefId;
     costBudget;
+    skillCache = new Map();
     constructor(agent, id, options = {}) {
         this.agent = agent;
         this.id = id;
         this.options = options;
         this.store = options.store ?? defaultSessionStore;
         this.sandbox = this.createSandbox();
+        this.fs = createFabricFs(this.sandbox);
         this.costBudget = new CostBudgetTracker(options.costLimit);
     }
     getDurableRuntime() {
@@ -92,7 +149,8 @@ export class StubFabricSession {
             const sandbox = createScopedSandboxEnv(await this.sandbox, options.cwd);
             const tools = this.resolveTools(sandbox, options.tools, options.commands);
             await this.recordEntry('user_prompt', { text, ...(role ? { role: role.name } : {}) });
-            let messages = buildModelMessagesFromHistory(await this.history(), role);
+            const sessionData = await this.history();
+            let messages = buildModelMessagesFromHistory(sessionData, role);
             if (!messages.some((message) => message.role === 'user' && message.content === text))
                 messages.push({ role: 'user', content: text });
             messages = await this.autoCompactIfNeeded(messages, role, options);
@@ -102,14 +160,19 @@ export class StubFabricSession {
                 await this.emit('prompt_end', { text, result: results });
                 return validateResult(results, options.result, options.resultExtraction);
             }
+            // Use tool-based result extraction when a validator is provided and the caller
+            // has not explicitly opted into delimiter-based extraction.
+            const useResultTools = options.result !== undefined && options.resultExtraction === undefined;
             const runtime = options.loopRuntime ?? this.options.loopRuntime ?? defaultLoopRuntime;
             const runRuntime = () => runtime.runPrompt({
                 sessionId: this.id,
+                ...(sessionData.affinityKey !== undefined ? { affinityKey: sessionData.affinityKey } : {}),
                 text,
                 messages,
                 tools,
                 sandbox,
                 ...(typeof (options.model ?? this.options.model ?? this.agent.model) === 'string' ? { model: (options.model ?? this.options.model ?? this.agent.model) } : {}),
+                ...((options.thinkingLevel ?? this.options.thinkingLevel ?? this.agent.thinkingLevel) !== undefined ? { thinkingLevel: options.thinkingLevel ?? this.options.thinkingLevel ?? this.agent.thinkingLevel } : {}),
                 ...((options.modelProvider ?? this.options.modelProvider) !== undefined ? { modelProvider: options.modelProvider ?? this.options.modelProvider } : {}),
                 ...(options.maxIterations !== undefined ? { maxIterations: options.maxIterations } : {}),
                 ...(options.modelTimeoutMs !== undefined ? { modelTimeoutMs: options.modelTimeoutMs } : {}),
@@ -122,7 +185,10 @@ export class StubFabricSession {
                     costBudget: this.costBudget,
                     requestCostLimitApproval: (ctx) => this.requestCostLimitApproval(ctx, options.approvalTimeoutMs ?? this.options.approvalTimeoutMs, options.onApproval),
                 } : {}),
-                executeToolCalls: (calls, policy, approvalTimeoutMs) => this.executeToolCalls(calls, tools, sandbox, policy, approvalTimeoutMs, options.onApproval),
+                ...(useResultTools ? { resultValidator: options.result } : {}),
+                agentId: this.agent.id,
+                ...(this.options.tenantId !== undefined ? { tenantId: this.options.tenantId } : {}),
+                executeToolCalls: (calls, policy, approvalTimeoutMs, attribution) => this.executeToolCalls(calls, tools, sandbox, policy, approvalTimeoutMs, options.onApproval, attribution),
                 recordEntry: (type, data) => this.recordEntry(type, data),
                 emit: (type, data) => this.emit(type, data),
             });
@@ -144,6 +210,10 @@ export class StubFabricSession {
                 messages = buildModelMessagesFromHistory(await this.history(), role);
                 result = await runRuntime();
             }
+            // If the loop produced a validated result via finish/give_up tools, return it directly.
+            if (result.validatedResult !== undefined) {
+                return result.validatedResult;
+            }
             const resultRetries = options.resultRetries ?? (options.result ? 1 : 0);
             for (let attempt = 0; attempt <= resultRetries; attempt += 1) {
                 try {
@@ -215,7 +285,8 @@ export class StubFabricSession {
         if (!skill)
             throw new FabricError({ code: 'SKILL_NOT_FOUND', message: `Skill not found: ${name}`, details: { skill: name } });
         const argsText = options.args ? `\n\nArguments:\n${JSON.stringify(options.args, null, 2)}` : '';
-        const result = await this.prompt(`${skill.content ?? ''}${argsText}`, options);
+        const packagedText = skill.packaged ? formatPackagedSkillResourceList(skill.packaged) : '';
+        const result = await this.prompt(`${skill.content ?? ''}${argsText}${packagedText}`, options);
         await this.recordEntry('skill_end', { skill: name });
         await this.emit('skill_end', { skill: name });
         return result;
@@ -377,10 +448,22 @@ export class StubFabricSession {
         const timeout = clampCommandTimeout(options.timeout, policy);
         if (timeout !== undefined)
             execOptions.timeout = timeout;
-        await this.recordEntry('shell_command', { command });
         await this.emit('command_start', { command });
         const result = await sandbox.exec(command, execOptions);
-        await this.recordEntry('shell_result', { command, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, ...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}) });
+        const redactedCommand = redactEnvValues(command, options.env);
+        const toolCallId = `shell-${Date.now()}`;
+        await this.recordEntry('user_prompt', { text: `Run shell command: ${redactedCommand}` });
+        await this.recordEntry('tool_call', { tool: 'bash', input: { command: redactedCommand }, toolCallId, synthetic: true });
+        await this.recordEntry('tool_result', {
+            tool: 'bash',
+            output: {
+                stdout: redactEnvValues(result.stdout, options.env),
+                stderr: redactEnvValues(result.stderr, options.env),
+                exitCode: result.exitCode,
+            },
+            toolCallId,
+            synthetic: true,
+        });
         await this.emit('command_end', { command, exitCode: result.exitCode, ...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}) });
         return result;
     }
@@ -436,6 +519,9 @@ export class StubFabricSession {
     async history() {
         return this.ensureData();
     }
+    async createSignalEntry(data) {
+        return this.recordEntry('signal', data);
+    }
     async sandboxRef(options) {
         const sandbox = await this.sandbox;
         const ref = registerSandbox(sandbox, { ownerSessionId: this.id });
@@ -518,13 +604,39 @@ export class StubFabricSession {
     async compact(options = {}) {
         const history = await this.history();
         const entries = history.entries ?? [];
-        const keepRecentEntries = options.keepRecentEntries ?? 20;
-        const compactedEntries = Math.max(0, entries.length - keepRecentEntries);
-        const firstKeptEntry = compactedEntries > 0 ? entries[compactedEntries] : undefined;
-        const compacted = compactedEntries > 0 ? entries.slice(0, compactedEntries) : [];
-        const fileRefs = collectFileReferences(compacted);
-        const baseSummary = options.summary ?? (options.generateSummary ? await this.generateCompactionSummary(compacted) : summarizeEntries(compacted));
+        const settings = this.options.compaction;
+        const explicitKeepRecentEntries = options.keepRecentEntries ?? settings?.keepRecentEntries;
+        const explicitKeepRecentTokens = options.keepRecentTokens ?? settings?.keepRecentTokens;
+        let compacted = [];
+        let firstKeptEntry;
+        let prep;
+        if (explicitKeepRecentEntries !== undefined) {
+            // Backward-compatible count-based cut.
+            const compactedCount = Math.max(0, entries.length - explicitKeepRecentEntries);
+            firstKeptEntry = compactedCount > 0 ? entries[compactedCount] : undefined;
+            compacted = compactedCount > 0 ? entries.slice(0, compactedCount) : [];
+        }
+        else {
+            const effectiveKeepTokens = explicitKeepRecentTokens ?? 8_000;
+            prep = prepareCompaction(entries, effectiveKeepTokens);
+            if (prep && prep.firstKeptIndex > 0) {
+                compacted = [...prep.messagesToSummarize, ...prep.turnPrefixMessages];
+                firstKeptEntry = entries[prep.firstKeptIndex];
+            }
+        }
+        const fileRefs = prep ? prep.fileRefs : collectFileReferences(compacted);
+        const summaryInput = prep ?? {
+            firstKeptIndex: firstKeptEntry ? entries.indexOf(firstKeptEntry) : 0,
+            messagesToSummarize: compacted,
+            turnPrefixMessages: [],
+            isSplitTurn: false,
+            fileRefs,
+        };
+        const baseSummary = options.summary ?? (options.generateSummary
+            ? await this.generateCompactionSummary(summaryInput)
+            : summarizeEntries(compacted));
         const summary = appendFileReferenceTags(baseSummary, fileRefs);
+        const compactedEntries = compacted.length;
         const entry = await this.recordEntry('compaction', {
             summary,
             compactedEntries,
@@ -546,6 +658,7 @@ export class StubFabricSession {
             summary,
             compactedEntries,
             ...(firstKeptEntry ? { firstKeptEntryId: firstKeptEntry.id } : {}),
+            details: { readFiles: fileRefs.readFiles, modifiedFiles: fileRefs.modifiedFiles },
         };
     }
     async autoCompactIfNeeded(messages, role, options) {
@@ -556,37 +669,69 @@ export class StubFabricSession {
             return messages;
         const compactAtTokens = options.compactAtTokens ?? settings?.compactAtTokens;
         const reserveTokens = options.reserveTokens ?? settings?.reserveTokens;
-        const keepRecentEntries = options.compactionKeepRecentEntries ?? settings?.keepRecentEntries ?? 20;
+        const keepRecentEntries = options.compactionKeepRecentEntries ?? settings?.keepRecentEntries;
+        const contextWindowTokens = options.contextWindowTokens ?? this.resolveModelContextWindow(options);
         const budget = evaluateContextBudget(messages, {
-            ...(options.contextWindowTokens !== undefined ? { contextWindowTokens: options.contextWindowTokens } : {}),
+            ...(contextWindowTokens !== undefined ? { contextWindowTokens } : {}),
             ...(compactAtTokens !== undefined ? { compactAtTokens } : {}),
             ...(reserveTokens !== undefined ? { reserveTokens } : {}),
+            ...(settings?.keepRecentTokens !== undefined ? { keepRecentTokens: settings.keepRecentTokens } : {}),
         });
         if (!budget.shouldCompact)
             return messages;
         const messagesBefore = messages.length;
         const tokensBefore = budget.estimatedTokens;
-        await this.compact({ keepRecentEntries, generateSummary: true, reason: 'threshold', tokensBefore, messagesBefore });
+        const compactOpts = { generateSummary: true, reason: 'threshold', tokensBefore, messagesBefore };
+        if (keepRecentEntries !== undefined) {
+            compactOpts.keepRecentEntries = keepRecentEntries;
+        }
+        else {
+            compactOpts.keepRecentTokens = settings?.keepRecentTokens ?? budget.keepRecentTokens ?? 8_000;
+        }
+        await this.compact(compactOpts);
         const compacted = buildModelMessagesFromHistory(await this.history(), role);
         return compacted;
     }
-    async generateCompactionSummary(entries) {
+    resolveModelContextWindow(options) {
+        const provider = options.modelProvider ?? this.options.modelProvider;
+        if (!provider)
+            return undefined;
+        const model = typeof (options.model ?? this.options.model ?? this.agent.model) === 'string'
+            ? (options.model ?? this.options.model ?? this.agent.model)
+            : undefined;
+        return this.readProviderModelMetadata(provider, model)?.contextWindowTokens;
+    }
+    readProviderModelMetadata(provider, model) {
+        try {
+            return provider.getModelMetadata?.(model);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async generateCompactionSummary(prep) {
+        if (prep.isSplitTurn && prep.turnPrefixMessages.length > 0) {
+            const [historyResult, prefixResult] = await Promise.all([
+                this.summarizeEntrySet(prep.messagesToSummarize),
+                this.summarizeEntrySet(prep.turnPrefixMessages, TURN_PREFIX_SUMMARIZATION_PROMPT),
+            ]);
+            return `${historyResult}\n\n---\n\n**Turn Context (split turn):**\n\n${prefixResult}`;
+        }
+        return this.summarizeEntrySet(prep.messagesToSummarize);
+    }
+    async summarizeEntrySet(entries, prefixPrompt) {
         if (entries.length === 0)
             return summarizeEntries(entries);
         const deterministic = summarizeEntries(entries);
         const provider = this.options.modelProvider ?? defaultModelProvider;
         try {
+            const serialized = JSON.stringify(entries.map((entry) => ({ type: entry.type, timestamp: entry.timestamp, data: entry.data ?? {} })).slice(0, 200));
+            const userContent = prefixPrompt ? `${serialized}\n\n${prefixPrompt}` : serialized;
             const response = await generateWithRuntime(provider, {
                 ...(this.agent.model !== undefined ? { model: this.agent.model } : {}),
                 messages: [
-                    {
-                        role: 'system',
-                        content: 'Summarize durable agent session history for future context. Preserve user goals, decisions, tool/command effects, files touched, errors, policy/approval events, and pending work. Do not include secrets.',
-                    },
-                    {
-                        role: 'user',
-                        content: JSON.stringify(entries.map((entry) => ({ type: entry.type, timestamp: entry.timestamp, data: entry.data ?? {} })).slice(0, 200)),
-                    },
+                    { role: 'system', content: COMPACTION_SUMMARIZATION_SYSTEM_PROMPT },
+                    { role: 'user', content: userContent },
                 ],
             }, { retries: 1, retryDelayMs: 250 });
             return response.message?.content?.trim() || deterministic;
@@ -688,7 +833,7 @@ export class StubFabricSession {
         const scoped = createScopedSandboxEnv(env, this.options.cwd);
         return wrapWithPolicy(scoped, this.options.policy, this.options.bypassPolicyEnforcement);
     }
-    async executeToolCalls(calls, tools, sandbox, callPolicy, approvalTimeoutMs, approvalHandler) {
+    async executeToolCalls(calls, tools, sandbox, callPolicy, approvalTimeoutMs, approvalHandler, attribution) {
         const results = [];
         const policy = callPolicy ?? this.options.policy;
         for (const call of calls) {
@@ -760,13 +905,13 @@ export class StubFabricSession {
                     continue;
                 }
             }
-            await this.recordEntry('tool_call', { tool: call.tool, input: call.input, ...(tool?.metadata?.effect ? { effect: tool.metadata.effect } : {}), ...(call.id ? { toolCallId: call.id } : {}) });
-            await this.emit('tool_start', { tool: call.tool });
+            await this.recordEntry('tool_call', { tool: call.tool, input: call.input, ...(tool?.metadata?.effect ? { effect: tool.metadata.effect } : {}), ...(call.id ? { toolCallId: call.id } : {}), ...(attribution ? { attribution: attribution } : {}) });
+            await this.emit('tool_start', { tool: call.tool, ...(attribution ? { attribution: attribution } : {}) });
             if (!tool?.execute) {
                 const error = `Tool is not available: ${call.tool}`;
                 results.push({ tool: call.tool, input: call.input, error, ...(call.id ? { id: call.id } : {}) });
                 await this.recordEntry('error', { tool: call.tool, error, approvalRequired: false });
-                await this.emit('tool_end', { tool: call.tool, error });
+                await this.emit('tool_end', { tool: call.tool, error, ...(attribution ? { attribution: attribution } : {}) });
                 continue;
             }
             try {
@@ -775,14 +920,14 @@ export class StubFabricSession {
                 const output = await tool.execute(input, { sandbox });
                 const durationMs = Date.now() - startedAt;
                 results.push({ tool: call.tool, input, output, ...(call.id ? { id: call.id } : {}) });
-                await this.recordEntry('tool_result', { tool: call.tool, output: output, durationMs, ...(call.id ? { toolCallId: call.id } : {}) });
-                await this.emit('tool_end', { tool: call.tool, durationMs });
+                await this.recordEntry('tool_result', { tool: call.tool, output: output, durationMs, ...(call.id ? { toolCallId: call.id } : {}), ...(attribution ? { attribution: attribution } : {}) });
+                await this.emit('tool_end', { tool: call.tool, durationMs, ...(attribution ? { attribution: attribution } : {}) });
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 results.push({ tool: call.tool, input: call.input, error: message, ...(call.id ? { id: call.id } : {}) });
                 await this.recordEntry('error', { tool: call.tool, error: message });
-                await this.emit('tool_end', { tool: call.tool, error: message });
+                await this.emit('tool_end', { tool: call.tool, error: message, ...(attribution ? { attribution: attribution } : {}) });
             }
         }
         return results;
@@ -908,7 +1053,7 @@ export class StubFabricSession {
     resolveTools(sandbox, promptTools = [], promptCommands = []) {
         const tools = new Map();
         const commandToolOptions = this.options.resolveSecret ? { resolveSecret: this.options.resolveSecret } : {};
-        for (const tool of createBuiltinTools(sandbox))
+        for (const tool of createBuiltinTools(sandbox, this.options.packagedSkills))
             tools.set(tool.name, tool);
         for (const tool of createCommandTools(this.options.commands ?? [], commandToolOptions))
             tools.set(tool.name, tool);
@@ -918,8 +1063,40 @@ export class StubFabricSession {
             tools.set(tool.name, tool);
         for (const tool of promptTools)
             tools.set(tool.name, tool);
+        const skills = this.options.skills ?? [];
+        if (skills.length > 0) {
+            const skillNames = skills.map((skill) => skill.name);
+            const activateSkillTool = createActivateSkillTool(skillNames, (name) => this.activateSkillForTool(name));
+            tools.set(activateSkillTool.name, activateSkillTool);
+        }
         return tools;
     }
+    async activateSkillForTool(name) {
+        const cached = this.skillCache.get(name);
+        if (cached !== undefined)
+            return cached;
+        const skill = this.resolveSkill(name);
+        if (!skill)
+            return `Error: Skill "${name}" not found.`;
+        let content = skill.content;
+        if (content === undefined && skill.path) {
+            try {
+                const sandbox = await this.sandbox;
+                content = await sandbox.readFile(skill.path);
+            }
+            catch {
+                return `Error: Skill "${name}" found but could not read content from path "${skill.path}".`;
+            }
+        }
+        if (content === undefined) {
+            return `Error: Skill "${name}" found but has no content or readable path.`;
+        }
+        if (skill.packaged) {
+            content += formatPackagedSkillResourceList(skill.packaged);
+        }
+        this.skillCache.set(name, content);
+        return content;
+    }
     resolveSkill(name) {
         const normalized = normalizeSkillReference(name);
         return this.options.skills?.find((skill) => {
@@ -965,10 +1142,22 @@ export class StubFabricSession {
                     retryable: false,
                 });
             }
+            if (!existing.affinityKey) {
+                existing.affinityKey = generateAffinityKey(this.agent.id, this.id);
+                await this.store.save(existing);
+            }
             return existing;
         }
         const now = new Date().toISOString();
-        const data = { id: this.id, agentId: this.agent.id, createdAt: now, updatedAt: now, events: [], entries: [] };
+        const data = {
+            id: this.id,
+            agentId: this.agent.id,
+            createdAt: now,
+            updatedAt: now,
+            events: [],
+            entries: [],
+            affinityKey: generateAffinityKey(this.agent.id, this.id),
+        };
         if (this.options.metadata !== undefined)
             data.metadata = this.options.metadata;
         if (this.options.tenantId !== undefined)
@@ -1048,6 +1237,20 @@ function isJsonValue(value) {
         return false;
     return Object.values(value).every(isJsonValue);
 }
+function redactEnvValues(text, env) {
+    if (!env)
+        return text;
+    let result = text;
+    for (const [key, value] of Object.entries(env)) {
+        if (key.length > 0) {
+            result = result.replaceAll(key, '[REDACTED]');
+        }
+        if (value.length > 0) {
+            result = result.replaceAll(value, '[REDACTED]');
+        }
+    }
+    return result;
+}
 function summarizeEntries(entries) {
     if (entries.length === 0)
         return 'No entries to compact.';
@@ -1087,6 +1290,77 @@ function appendFileReferenceTags(summary, refs) {
         sections.push(`<modified-files>\n${refs.modifiedFiles.join('\n')}\n</modified-files>`);
     return sections.join('\n\n');
 }
+/** Valid cut points: user prompts and assistant messages. Never cut at tool_result. */
+function findValidCutPoints(entries, start, end) {
+    const cutPoints = [];
+    for (let i = start; i < end; i++) {
+        const type = entries[i]?.type;
+        if (type === 'user_prompt' || type === 'assistant_message') {
+            cutPoints.push(i);
+        }
+    }
+    return cutPoints;
+}
+function findTurnStartIndex(entries, index, start) {
+    for (let i = index; i >= start; i--) {
+        if (entries[i]?.type === 'user_prompt')
+            return i;
+    }
+    return -1;
+}
+function findCutPoint(entries, start, end, keepRecentTokens) {
+    const cutPoints = findValidCutPoints(entries, start, end);
+    if (cutPoints.length === 0) {
+        return { firstKeptIndex: start, turnStartIndex: -1, isSplitTurn: false };
+    }
+    let accumulatedTokens = 0;
+    let firstKeptIndex = start;
+    for (let i = end - 1; i >= start; i--) {
+        const entry = entries[i];
+        if (!entry)
+            continue;
+        accumulatedTokens += estimateSessionEntryTokens(entry);
+        if (accumulatedTokens >= keepRecentTokens) {
+            for (const cutPoint of cutPoints) {
+                if (cutPoint >= i) {
+                    firstKeptIndex = cutPoint;
+                    break;
+                }
+            }
+            break;
+        }
+    }
+    const isUserMessage = entries[firstKeptIndex]?.type === 'user_prompt';
+    const turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, firstKeptIndex, start);
+    return {
+        firstKeptIndex,
+        turnStartIndex,
+        isSplitTurn: !isUserMessage && turnStartIndex !== -1,
+    };
+}
+/** Pure function — no I/O. Finds the token-based cut point, extracts messages to summarize, and tracks file ops. */
+export function prepareCompaction(entries, keepRecentTokens, previousCompaction) {
+    if (entries.length === 0)
+        return undefined;
+    const boundaryStart = previousCompaction ? previousCompaction.firstKeptIndex : 0;
+    const boundaryEnd = entries.length;
+    const cutPoint = findCutPoint(entries, boundaryStart, boundaryEnd, keepRecentTokens);
+    if (cutPoint.firstKeptIndex <= boundaryStart)
+        return undefined;
+    const historyEnd = cutPoint.isSplitTurn ? cutPoint.turnStartIndex : cutPoint.firstKeptIndex;
+    const messagesToSummarize = entries.slice(boundaryStart, historyEnd);
+    const turnPrefixMessages = cutPoint.isSplitTurn
+        ? entries.slice(cutPoint.turnStartIndex, cutPoint.firstKeptIndex)
+        : [];
+    const fileRefs = collectFileReferences([...messagesToSummarize, ...turnPrefixMessages]);
+    return {
+        firstKeptIndex: cutPoint.firstKeptIndex,
+        messagesToSummarize,
+        turnPrefixMessages,
+        isSplitTurn: cutPoint.isSplitTurn,
+        fileRefs,
+    };
+}
 function isReadOnlyFileTool(tool) {
     return tool !== undefined && ['read', 'read_buffer', 'stat', 'readdir', 'exists', 'grep', 'glob'].includes(tool);
 }