skimpyclaw 0.3.9 → 0.3.14

package/dist/providers/context-manager.d.ts

@@ -1,22 +1,53 @@
 import type { ContextManagementConfig } from './types.js';
+import type { Config } from '../types.js';
 export type { ContextManagementConfig };
+/** Result of a compaction attempt, including metadata about what happened. */
+export interface CompactionResult<T> {
+    messages: T[];
+    /** Whether any compaction was performed */
+    compacted: boolean;
+    /** 'llm' if LLM summarized, 'truncation' if mechanically truncated, undefined if no compaction */
+    method?: 'llm' | 'truncation';
+    /** The summary text (only when method === 'llm') */
+    summary?: string;
+    /** Estimated tokens before compaction */
+    tokensBefore?: number;
+    /** Estimated tokens after compaction */
+    tokensAfter?: number;
+}
 /** Rough token estimate: 1 token ≈ 4 chars of JSON. */
 export declare function estimateTokens(data: any[]): number;
+/**
+ * Serialize Anthropic-format messages into a human-readable conversation transcript
+ * suitable for LLM summarization.
+ */
+declare function serializeAnthropicMessages(messages: any[]): string;
+/**
+ * Serialize OpenAI-format messages into a human-readable transcript.
+ */
+declare function serializeOpenAIMessages(messages: any[]): string;
+/**
+ * Serialize Codex-format input items into a human-readable transcript.
+ */
+declare function serializeCodexMessages(items: any[]): string;
 /**
  * Compact Anthropic-format apiMessages when over threshold.
- * Truncates content of old tool_result blocks; leaves last KEEP_TAIL messages intact.
+ * Uses LLM summarization for old messages; falls back to truncation on failure.
  * Does NOT mutate the input array — returns a new array.
  */
-export declare function compactAnthropicMessages(messages: any[], config?: ContextManagementConfig, iteration?: number): any[];
+export declare function compactAnthropicMessages(messages: any[], config?: ContextManagementConfig, iteration?: number, fullConfig?: Config): Promise<CompactionResult<any>>;
 /**
  * Compact OpenAI-format apiMessages when over threshold.
- * Truncates content of old `role: 'tool'` messages; leaves last KEEP_TAIL messages intact.
+ * Uses LLM summarization for old messages; falls back to truncation on failure.
  * Does NOT mutate the input array — returns a new array.
  */
-export declare function compactOpenAIMessages(messages: any[], config?: ContextManagementConfig, iteration?: number): any[];
+export declare function compactOpenAIMessages(messages: any[], config?: ContextManagementConfig, iteration?: number, fullConfig?: Config): Promise<CompactionResult<any>>;
 /**
  * Compact Codex-format input items when over threshold.
- * Truncates output of old function_call_output items; leaves last KEEP_TAIL items intact.
+ * Uses LLM summarization for old items; falls back to truncation on failure.
  * Does NOT mutate the input array — returns a new array.
  */
-export declare function compactCodexMessages(input: any[], config?: ContextManagementConfig, iteration?: number): any[];
+export declare function compactCodexMessages(input: any[], config?: ContextManagementConfig, iteration?: number, fullConfig?: Config): Promise<CompactionResult<any>>;
+export { serializeAnthropicMessages, serializeOpenAIMessages, serializeCodexMessages };
+/** Reset compaction markers (for testing). */
+export declare function resetCompactionState(): void;

package/dist/providers/context-manager.js

@@ -1,33 +1,183 @@
 // Context manager for agentic tool loops.
-// When accumulated messages exceed the token threshold, compacts old tool results
-// to keep context size bounded without breaking message structure.
+// When accumulated messages exceed the token threshold, uses an LLM to summarize
+// old messages into a concise summary, preserving semantic meaning.
+//
+// Falls back to mechanical truncation if the LLM call fails.
 //
 // Key constraint: tool_use/tool_result pairs (Anthropic) and
 // function_call/function_call_output pairs (Codex) must stay structurally intact.
-// We truncate the CONTENT of old results — never remove blocks entirely.
 const DEFAULT_MAX_CONTEXT_TOKENS = 200_000;
 const KEEP_TAIL = 8; // always keep last N messages/items untouched
-const RESULT_MAX_CHARS = 500; // compact old results to this length
+const RESULT_MAX_CHARS = 500; // fallback truncation length
+const SUMMARY_MAX_TOKENS = 2048; // max tokens for summary response
+// Preferred compaction models in priority order (cheap & fast).
+// Can be overridden via contextManagement.compactionModel in config.
+const COMPACTION_MODEL_CANDIDATES = [
+    'anthropic/claude-haiku-3-5',
+    'openai/gpt-4o-mini',
+    'groq/llama-3.1-8b-instant',
+];
 /** Rough token estimate: 1 token ≈ 4 chars of JSON. */
 export function estimateTokens(data) {
     return Math.ceil(JSON.stringify(data).length / 4);
 }
+// --- LLM Summarization ---
+const COMPACTION_SYSTEM_PROMPT = `You are a conversation summarizer for an AI coding assistant. Your job is to produce a concise summary of a conversation between a user and an assistant that used tools (file reads, bash commands, file writes, etc.).
+
+Rules:
+- Preserve ALL important context: file paths, variable names, error messages, decisions made, code changes
+- Summarize tool results (e.g. "Read package.json — found dependencies X, Y, Z") rather than reproducing full output
+- Keep the summary structured with bullet points or short paragraphs
+- Note any unresolved issues or ongoing tasks
+- Be concise but don't lose critical information that the assistant needs to continue working
+- Output ONLY the summary, no preamble`;
 /**
- * Compact Anthropic-format apiMessages when over threshold.
- * Truncates content of old tool_result blocks; leaves last KEEP_TAIL messages intact.
- * Does NOT mutate the input array — returns a new array.
+ * Serialize Anthropic-format messages into a human-readable conversation transcript
+ * suitable for LLM summarization.
  */
-export function compactAnthropicMessages(messages, config, iteration = 0) {
-    if (config?.enabled === false)
-        return messages;
-    const maxTokens = config?.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
-    const estimated = estimateTokens(messages);
-    if (estimated <= maxTokens)
-        return messages;
-    console.log(`[context-manager] Compacting at iteration ${iteration} (~${Math.round(estimated / 1000)}k tokens > ${Math.round(maxTokens / 1000)}k threshold)`);
-    const tail = messages.slice(-KEEP_TAIL);
-    const head = messages.slice(0, -KEEP_TAIL);
-    const compacted = head.map(msg => {
+function serializeAnthropicMessages(messages) {
+    const lines = [];
+    for (const msg of messages) {
+        const role = msg.role === 'assistant' ? 'Assistant' : 'User';
+        if (typeof msg.content === 'string') {
+            lines.push(`[${role}]: ${msg.content}`);
+            continue;
+        }
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type === 'text') {
+                lines.push(`[${role}]: ${block.text}`);
+            }
+            else if (block.type === 'tool_use') {
+                const inputStr = typeof block.input === 'string'
+                    ? block.input
+                    : JSON.stringify(block.input);
+                const truncatedInput = inputStr.length > 500 ? inputStr.slice(0, 500) + '...' : inputStr;
+                lines.push(`[Assistant Tool Call: ${block.name}]: ${truncatedInput}`);
+            }
+            else if (block.type === 'tool_result') {
+                const raw = typeof block.content === 'string'
+                    ? block.content
+                    : JSON.stringify(block.content);
+                const truncatedResult = raw.length > 1000 ? raw.slice(0, 1000) + '...' : raw;
+                lines.push(`[Tool Result]: ${truncatedResult}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Serialize OpenAI-format messages into a human-readable transcript.
+ */
+function serializeOpenAIMessages(messages) {
+    const lines = [];
+    for (const msg of messages) {
+        if (msg.role === 'tool') {
+            const raw = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+            const truncated = raw.length > 1000 ? raw.slice(0, 1000) + '...' : raw;
+            lines.push(`[Tool Result (${msg.tool_call_id})]: ${truncated}`);
+        }
+        else if (msg.role === 'assistant') {
+            if (msg.content) {
+                lines.push(`[Assistant]: ${msg.content}`);
+            }
+            if (msg.tool_calls) {
+                for (const tc of msg.tool_calls) {
+                    const args = tc.function?.arguments || '';
+                    const truncatedArgs = args.length > 500 ? args.slice(0, 500) + '...' : args;
+                    lines.push(`[Assistant Tool Call: ${tc.function?.name}]: ${truncatedArgs}`);
+                }
+            }
+        }
+        else {
+            const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+            lines.push(`[${msg.role === 'user' ? 'User' : msg.role}]: ${content}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Serialize Codex-format input items into a human-readable transcript.
+ */
+function serializeCodexMessages(items) {
+    const lines = [];
+    for (const item of items) {
+        if (item.type === 'message') {
+            const role = item.role === 'assistant' ? 'Assistant' : 'User';
+            const content = typeof item.content === 'string'
+                ? item.content
+                : Array.isArray(item.content)
+                    ? item.content.map((c) => c.text || JSON.stringify(c)).join(' ')
+                    : JSON.stringify(item.content);
+            lines.push(`[${role}]: ${content}`);
+        }
+        else if (item.type === 'function_call') {
+            const args = item.arguments || '';
+            const truncated = args.length > 500 ? args.slice(0, 500) + '...' : args;
+            lines.push(`[Assistant Tool Call: ${item.name}]: ${truncated}`);
+        }
+        else if (item.type === 'function_call_output') {
+            const raw = item.output || '';
+            const truncated = raw.length > 1000 ? raw.slice(0, 1000) + '...' : raw;
+            lines.push(`[Tool Result]: ${truncated}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Pick the best available compaction model from candidates.
+ * Checks which providers are initialized and returns the first match.
+ */
+async function pickCompactionModel(config) {
+    const { isAnthropicAvailable } = await import('./anthropic.js');
+    const { isOpenAIAvailable } = await import('./openai.js');
+    for (const candidate of COMPACTION_MODEL_CANDIDATES) {
+        const provider = candidate.split('/')[0];
+        if (provider === 'anthropic' && isAnthropicAvailable())
+            return candidate;
+        if (isOpenAIAvailable(provider))
+            return candidate;
+    }
+    // Last resort: return the first candidate and let chat() fail → fallback to truncation
+    return COMPACTION_MODEL_CANDIDATES[0];
+}
+/**
+ * Call the LLM to summarize a conversation transcript.
+ * Returns the summary text, or null if the call fails.
+ */
+async function llmSummarize(transcript, config, compactionModel) {
+    try {
+        // Dynamically import to avoid circular dependency
+        const { chat } = await import('./index.js');
+        const model = compactionModel || await pickCompactionModel(config);
+        const messages = [
+            { role: 'system', content: COMPACTION_SYSTEM_PROMPT },
+            {
+                role: 'user',
+                content: `Summarize the following conversation between an AI coding assistant and a user. This summary will replace the old messages in the context window so the assistant can continue working.\n\n---\n${transcript}\n---`,
+            },
+        ];
+        console.log(`[context-manager] Requesting LLM summary via ${model}`);
+        const summary = await chat(messages, {
+            model,
+            maxTokens: SUMMARY_MAX_TOKENS,
+        }, config);
+        if (!summary || summary.trim().length === 0) {
+            console.warn('[context-manager] LLM returned empty summary, falling back to truncation');
+            return null;
+        }
+        console.log(`[context-manager] LLM summary: ${summary.length} chars`);
+        return summary.trim();
+    }
+    catch (err) {
+        console.warn(`[context-manager] LLM summarization failed, falling back to truncation: ${err instanceof Error ? err.message : err}`);
+        return null;
+    }
+}
+// --- Fallback truncation (original mechanical approach) ---
+function truncateAnthropicHead(head) {
+    return head.map(msg => {
         if (!Array.isArray(msg.content))
             return msg;
         let changed = false;
@@ -44,57 +194,163 @@ export function compactAnthropicMessages(messages, config, iteration = 0) {
         });
         return changed ? { ...msg, content: newContent } : msg;
     });
-    return [...compacted, ...tail];
+}
+function truncateOpenAIHead(head) {
+    return head.map(msg => {
+        if (msg.role !== 'tool')
+            return msg;
+        if (typeof msg.content !== 'string')
+            return msg;
+        if (msg.content.length <= RESULT_MAX_CHARS)
+            return msg;
+        return { ...msg, content: msg.content.slice(0, RESULT_MAX_CHARS) + ' [truncated]' };
+    });
+}
+function truncateCodexHead(head) {
+    return head.map(item => {
+        if (item.type !== 'function_call_output')
+            return item;
+        if (typeof item.output !== 'string')
+            return item;
+        if (item.output.length <= RESULT_MAX_CHARS)
+            return item;
+        return { ...item, output: item.output.slice(0, RESULT_MAX_CHARS) + ' [truncated]' };
+    });
+}
+// --- Track whether we already compacted for a given conversation ---
+// Key: a hash of the tail messages to avoid re-summarizing the same head repeatedly.
+// This is a WeakMap so we don't leak memory across conversations.
+const compactedMarker = new WeakSet();
+/**
+ * Compact Anthropic-format apiMessages when over threshold.
+ * Uses LLM summarization for old messages; falls back to truncation on failure.
+ * Does NOT mutate the input array — returns a new array.
+ */
+export async function compactAnthropicMessages(messages, config, iteration = 0, fullConfig) {
+    if (config?.enabled === false)
+        return { messages, compacted: false };
+    const maxTokens = config?.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
+    const estimated = estimateTokens(messages);
+    if (estimated <= maxTokens)
+        return { messages, compacted: false };
+    // If we already compacted this array (it has a summary message), use truncation fallback
+    // to progressively shrink rather than re-summarizing repeatedly.
+    if (compactedMarker.has(messages)) {
+        console.log(`[context-manager] Already compacted, using truncation fallback (iteration ${iteration})`);
+        const tail = messages.slice(-KEEP_TAIL);
+        const head = messages.slice(0, -KEEP_TAIL);
+        const result = [...truncateAnthropicHead(head), ...tail];
+        return { messages: result, compacted: true, method: 'truncation', tokensBefore: estimated, tokensAfter: estimateTokens(result) };
+    }
+    console.log(`[context-manager] Compacting at iteration ${iteration} (~${Math.round(estimated / 1000)}k tokens > ${Math.round(maxTokens / 1000)}k threshold)`);
+    const tail = messages.slice(-KEEP_TAIL);
+    const head = messages.slice(0, -KEEP_TAIL);
+    // Attempt LLM summarization
+    if (fullConfig) {
+        const transcript = serializeAnthropicMessages(head);
+        const summary = await llmSummarize(transcript, fullConfig, config?.compactionModel);
+        if (summary) {
+            const summaryMessage = {
+                role: 'user',
+                content: [{ type: 'text', text: `[Conversation Summary]\n${summary}` }],
+            };
+            const result = [summaryMessage, ...tail];
+            compactedMarker.add(result);
+            const tokensAfter = estimateTokens(result);
+            return { messages: result, compacted: true, method: 'llm', summary, tokensBefore: estimated, tokensAfter };
+        }
+    }
+    // Fallback: mechanical truncation
+    const result = [...truncateAnthropicHead(head), ...tail];
+    return { messages: result, compacted: true, method: 'truncation', tokensBefore: estimated, tokensAfter: estimateTokens(result) };
 }
 /**
  * Compact OpenAI-format apiMessages when over threshold.
- * Truncates content of old `role: 'tool'` messages; leaves last KEEP_TAIL messages intact.
+ * Uses LLM summarization for old messages; falls back to truncation on failure.
  * Does NOT mutate the input array — returns a new array.
  */
-export function compactOpenAIMessages(messages, config, iteration = 0) {
+export async function compactOpenAIMessages(messages, config, iteration = 0, fullConfig) {
     if (config?.enabled === false)
-        return messages;
+        return { messages, compacted: false };
     const maxTokens = config?.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
     const estimated = estimateTokens(messages);
     if (estimated <= maxTokens)
-        return messages;
+        return { messages, compacted: false };
+    if (compactedMarker.has(messages)) {
+        console.log(`[context-manager] Already compacted, using truncation fallback (iteration ${iteration})`);
+        const tail = messages.slice(-KEEP_TAIL);
+        const head = messages.slice(0, -KEEP_TAIL);
+        const result = [...truncateOpenAIHead(head), ...tail];
+        return { messages: result, compacted: true, method: 'truncation', tokensBefore: estimated, tokensAfter: estimateTokens(result) };
+    }
     console.log(`[context-manager] Compacting OpenAI messages at iteration ${iteration} (~${Math.round(estimated / 1000)}k tokens > ${Math.round(maxTokens / 1000)}k threshold)`);
     const tail = messages.slice(-KEEP_TAIL);
     const head = messages.slice(0, -KEEP_TAIL);
-    const compacted = head.map(msg => {
-        if (msg.role !== 'tool')
-            return msg;
-        if (typeof msg.content !== 'string')
-            return msg;
-        if (msg.content.length <= RESULT_MAX_CHARS)
-            return msg;
-        return { ...msg, content: msg.content.slice(0, RESULT_MAX_CHARS) + ' [truncated]' };
-    });
-    return [...compacted, ...tail];
+    // Attempt LLM summarization
+    if (fullConfig) {
+        const transcript = serializeOpenAIMessages(head);
+        const summary = await llmSummarize(transcript, fullConfig, config?.compactionModel);
+        if (summary) {
+            const summaryMessage = {
+                role: 'user',
+                content: `[Conversation Summary]\n${summary}`,
+            };
+            const result = [summaryMessage, ...tail];
+            compactedMarker.add(result);
+            const tokensAfter = estimateTokens(result);
+            return { messages: result, compacted: true, method: 'llm', summary, tokensBefore: estimated, tokensAfter };
+        }
+    }
+    // Fallback: mechanical truncation
+    const result = [...truncateOpenAIHead(head), ...tail];
+    return { messages: result, compacted: true, method: 'truncation', tokensBefore: estimated, tokensAfter: estimateTokens(result) };
 }
 /**
  * Compact Codex-format input items when over threshold.
- * Truncates output of old function_call_output items; leaves last KEEP_TAIL items intact.
+ * Uses LLM summarization for old items; falls back to truncation on failure.
  * Does NOT mutate the input array — returns a new array.
  */
-export function compactCodexMessages(input, config, iteration = 0) {
+export async function compactCodexMessages(input, config, iteration = 0, fullConfig) {
     if (config?.enabled === false)
-        return input;
+        return { messages: input, compacted: false };
     const maxTokens = config?.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
     const estimated = estimateTokens(input);
     if (estimated <= maxTokens)
-        return input;
+        return { messages: input, compacted: false };
+    if (compactedMarker.has(input)) {
+        console.log(`[context-manager] Already compacted, using truncation fallback (iteration ${iteration})`);
+        const tail = input.slice(-KEEP_TAIL);
+        const head = input.slice(0, -KEEP_TAIL);
+        const result = [...truncateCodexHead(head), ...tail];
+        return { messages: result, compacted: true, method: 'truncation', tokensBefore: estimated, tokensAfter: estimateTokens(result) };
+    }
     console.log(`[context-manager] Compacting Codex input at iteration ${iteration} (~${Math.round(estimated / 1000)}k tokens > ${Math.round(maxTokens / 1000)}k threshold)`);
     const tail = input.slice(-KEEP_TAIL);
     const head = input.slice(0, -KEEP_TAIL);
-    const compacted = head.map(item => {
-        if (item.type !== 'function_call_output')
-            return item;
-        if (typeof item.output !== 'string')
-            return item;
-        if (item.output.length <= RESULT_MAX_CHARS)
-            return item;
-        return { ...item, output: item.output.slice(0, RESULT_MAX_CHARS) + ' [truncated]' };
-    });
-    return [...compacted, ...tail];
+    // Attempt LLM summarization
+    if (fullConfig) {
+        const transcript = serializeCodexMessages(head);
+        const summary = await llmSummarize(transcript, fullConfig, config?.compactionModel);
+        if (summary) {
+            const summaryItem = {
+                type: 'message',
+                role: 'user',
+                content: `[Conversation Summary]\n${summary}`,
+            };
+            const result = [summaryItem, ...tail];
+            compactedMarker.add(result);
+            const tokensAfter = estimateTokens(result);
+            return { messages: result, compacted: true, method: 'llm', summary, tokensBefore: estimated, tokensAfter };
+        }
+    }
+    // Fallback: mechanical truncation
+    const result = [...truncateCodexHead(head), ...tail];
+    return { messages: result, compacted: true, method: 'truncation', tokensBefore: estimated, tokensAfter: estimateTokens(result) };
+}
+// --- Exported helpers for testing ---
+export { serializeAnthropicMessages, serializeOpenAIMessages, serializeCodexMessages };
+/** Reset compaction markers (for testing). */
+export function resetCompactionState() {
+    // WeakSet doesn't support clearing, so we replace it
+    // This is a no-op in production; tests should create fresh arrays
 }

package/dist/providers/openai.js

@@ -153,7 +153,13 @@ export async function chatWithToolsOpenAI(params, provider) {
             };
         }
         // Compact old tool results if context is growing large
-        const messagesForApi = compactOpenAIMessages(apiMessages, toolConfig.contextManagement, i + 1);
+        const compactionResult = await compactOpenAIMessages(apiMessages, toolConfig.contextManagement, i + 1, config);
+        const messagesForApi = compactionResult.messages;
+        if (compactionResult.compacted) {
+            const method = compactionResult.method === 'llm' ? 'LLM summary' : 'truncation';
+            const detail = `~${Math.round((compactionResult.tokensBefore || 0) / 1000)}k → ~${Math.round((compactionResult.tokensAfter || 0) / 1000)}k tokens`;
+            toolLog.push(`[context compacted via ${method}: ${detail}]`);
+        }
         console.log(`[agent:openai-tools] Iteration ${i + 1}/${maxIterations} (provider: ${provider}, model: ${modelId})`);
         const genObs = await startGenerationObservation(`${provider}:${modelId}`, {
             input: { messages: apiMessages },
@@ -252,7 +258,7 @@ export async function chatWithToolsOpenAI(params, provider) {
         // Execute each tool call
         for (const toolCall of message.tool_calls) {
             const fnName = toolCall.function.name;
-            if (fnName.startsWith('$') && fnName !== '$web_search') {
+            if (fnName.startsWith('$')) {
                 const unsupported = `Provider-native tool "${fnName}" is not supported in this runtime.`;
                 console.warn(`[agent:openai-tools] ${unsupported}`);
                 apiMessages.push({

package/dist/providers/utils.d.ts

@@ -54,8 +54,12 @@ export declare function getProvider(model: string): string;
  * Strip provider prefix from model name.
  */
 export declare function stripProvider(model: string, openaiClients?: Map<string, unknown>, responsesApiProviders?: Set<string>): string;
-/** Truncate tool result to maxBytes. Appends truncation notice. */
-export declare function truncateToolResult(result: string, maxBytes?: number): string;
+/**
+ * Mask large tool outputs by writing to scratch files.
+ * Returns the original result if small enough, or a summary + file path if large.
+ * Falls back to simple truncation if file write fails.
+ */
+export declare function truncateToolResult(result: string, _maxBytes?: number): string;
 /**
  * Build thinking config based on thinking level.
  */

package/dist/providers/utils.js

@@ -1,4 +1,7 @@
 // Provider Utilities
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
 // Anti-hallucination instructions injected between the Claude Code identity
 // block and the actual system prompt. Prevents the model from roleplaying
 // Claude Code's full behavior (XML tool calls, fabricated output, etc.)
@@ -104,7 +107,7 @@ function migrateDeprecatedModelSpec(modelSpec) {
     if (/^claude[-.]3[-.]5[-.]sonnet(?:[-_.].*)?$/i.test(bare)) {
         migratedBare = 'claude-sonnet-4-6';
     }
-    else if (/^claude[-.]3[-.]5[-.]haiku(?:[-_.].*)?$/i.test(bare)) {
+    else if (/^claude[-.]3[-.]5[-.]haiku(?:[-_.].*)?$/i.test(bare) || bare === 'claude-haiku') {
         migratedBare = 'claude-haiku-4-5';
     }
     else if (/^claude[-.]opus[-.]4(?:[-_.].*)?$/i.test(bare)) {
@@ -178,10 +181,39 @@ export function stripProvider(model, openaiClients, responsesApiProviders) {
     return model;
 }
 /** Truncate tool result to maxBytes. Appends truncation notice. */
-export function truncateToolResult(result, maxBytes = 10_240) {
-    if (result.length <= maxBytes)
+/**
+ * Observation masking threshold. Tool outputs above this size are written to
+ * a scratch file and replaced with a compact summary + file path.
+ * Outputs below this are returned inline (no file I/O overhead).
+ */
+const MASK_THRESHOLD = 8_000; // ~2000 tokens
+/**
+ * Mask large tool outputs by writing to scratch files.
+ * Returns the original result if small enough, or a summary + file path if large.
+ * Falls back to simple truncation if file write fails.
+ */
+export function truncateToolResult(result, _maxBytes = 10_240) {
+    if (result.length <= MASK_THRESHOLD)
         return result;
-    return result.slice(0, maxBytes) + `\n\n[Truncated: ${result.length} chars total]`;
+    try {
+        const scratchDir = join(homedir(), '.skimpyclaw', 'scratch');
+        if (!existsSync(scratchDir))
+            mkdirSync(scratchDir, { recursive: true });
+        const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const filePath = join(scratchDir, `${id}.txt`);
+        writeFileSync(filePath, result);
+        // Build a compact summary: first 500 chars + last 500 chars
+        const head = result.slice(0, 500);
+        const tail = result.slice(-500);
+        const summary = head + (result.length > 1000 ? '\n...\n' + tail : '');
+        console.log(`[context-manager] Masked ${result.length} chars → ${filePath}`);
+        return `${summary}\n\n[Full output (${result.length} chars) saved to ${filePath} — use Read tool to access]`;
+    }
+    catch (err) {
+        // Fallback: simple truncation
+        console.warn(`[context-manager] Masking failed: ${err instanceof Error ? err.message : err}`);
+        return result.slice(0, MASK_THRESHOLD) + `\n\n[Truncated: ${result.length} chars total]`;
+    }
 }
 /**
  * Build thinking config based on thinking level.

package/dist/sandbox/manager.js

@@ -38,6 +38,16 @@ export async function ensureContainer(sessionId, config, allowedPaths) {
     const uid = process.getuid?.() ?? 501;
     const gid = process.getgid?.() ?? 20;
     const merged = { ...SANDBOX_DEFAULTS, ...config };
+    // Expand ${VAR} references in env values from process.env
+    let resolvedEnv;
+    if (config.env) {
+        resolvedEnv = {};
+        for (const [key, val] of Object.entries(config.env)) {
+            resolvedEnv[key] = val.replace(/\$\{(\w+)\}/g, (_match, name) => {
+                return process.env[name] ?? '';
+            });
+        }
+    }
     const opts = {
         image: merged.image,
         cpus: merged.cpus,
@@ -48,6 +58,7 @@ export async function ensureContainer(sessionId, config, allowedPaths) {
             container: m.container,
             readOnly: m.readOnly,
         })),
+        env: resolvedEnv,
         user: `${uid}:${gid}`,
     };
     await createContainer(name, opts);

package/dist/sandbox/mount-security.js

@@ -83,7 +83,11 @@ export function validateMountPaths(allowedPaths) {
  * Returns the original path if no mount matches (will likely fail inside container).
  */
 export function translatePath(hostPath, mounts) {
-    const candidates = getPathCandidates(hostPath);
+    // Expand ~ to home directory (~ is a shell feature, not handled by resolve())
+    const expanded = hostPath.startsWith('~/')
+        ? homedir() + hostPath.slice(1)
+        : hostPath;
+    const candidates = getPathCandidates(expanded);
     // Sort by host path length descending so we match the most specific mount first
     const sorted = [...mounts].sort((a, b) => b.host.length - a.host.length);
     for (const candidate of candidates) {

package/dist/sandbox/runtime.d.ts

@@ -8,6 +8,7 @@ export interface ContainerOpts {
         container: string;
         readOnly?: boolean;
     }>;
+    env?: Record<string, string>;
     user?: string;
 }
 export interface ExecOpts {

package/dist/sandbox/runtime.js

@@ -114,6 +114,11 @@ export async function createContainer(name, opts) {
             args.push('--mount', mountArg);
         }
     }
+    if (opts.env) {
+        for (const [key, val] of Object.entries(opts.env)) {
+            args.push('-e', `${key}=${val}`);
+        }
+    }
     args.push(opts.image, 'sleep', 'infinity');
     const result = await runCommand(runtime, args);
     if (result.exitCode !== 0) {

package/dist/sandbox-utils.d.ts

@@ -0,0 +1,6 @@
+export type SandboxRuntime = 'container' | 'docker';
+export declare function detectSandboxRuntime(preferred?: SandboxRuntime | string | null): SandboxRuntime | null;
+export declare function isSandboxRuntimeRunning(runtime: SandboxRuntime): boolean;
+export declare function sandboxNetworkExists(runtime: SandboxRuntime, network: string): boolean;
+export declare function defaultSandboxNetwork(runtime: SandboxRuntime): string;
+export declare function sandboxImageExists(runtime: SandboxRuntime, image: string): boolean;