skimpyclaw 0.3.9 → 0.3.10

package/dist/__tests__/skills.test.js

@@ -294,31 +294,58 @@ describe('formatSkillsPrompt', () => {
     it('returns empty string for no skills', () => {
         expect(formatSkillsPrompt([])).toBe('');
     });
-    it('formats single skill with header', () => {
-        const result = formatSkillsPrompt([makeSkill('greet', 'Say hello.')]);
-        expect(result).toContain('## Active Skills');
-        expect(result).toContain('### greet');
-        expect(result).toContain('Say hello.');
-    });
-    it('includes emoji in header when present', () => {
-        const result = formatSkillsPrompt([makeSkill('greet', 'Say hello.', '👋')]);
-        expect(result).toContain('### 👋 greet');
-    });
-    it('separates multiple skills with dividers', () => {
-        const result = formatSkillsPrompt([
-            makeSkill('a', 'A body'),
-            makeSkill('b', 'B body'),
-        ]);
-        expect(result).toContain('---');
-        expect(result).toContain('### a');
-        expect(result).toContain('### b');
-    });
-    it('does not skip skills based on prompt budget argument', () => {
-        const result = formatSkillsPrompt([
-            makeSkill('small', 'tiny'),
-            makeSkill('big', 'x'.repeat(50000)),
-        ], 100);
-        expect(result).toContain('### small');
-        expect(result).toContain('### big');
+    describe('dynamic loading (default)', () => {
+        it('formats skill catalog with names, descriptions, and paths', () => {
+            const result = formatSkillsPrompt([makeSkill('greet', 'Say hello.')]);
+            expect(result).toContain('## Skills');
+            expect(result).toContain('read the SKILL.md file');
+            expect(result).toContain('greet');
+            expect(result).toContain('`/fake/greet/SKILL.md`');
+        });
+        it('includes emoji in catalog', () => {
+            const result = formatSkillsPrompt([makeSkill('greet', 'Say hello.', '👋')]);
+            expect(result).toContain('👋 greet');
+        });
+        it('does not include skill body', () => {
+            const result = formatSkillsPrompt([makeSkill('greet', 'Say hello.')]);
+            expect(result).not.toContain('Say hello.');
+        });
+        it('lists multiple skills', () => {
+            const result = formatSkillsPrompt([
+                makeSkill('a', 'A body'),
+                makeSkill('b', 'B body'),
+            ]);
+            expect(result).toContain('| a |');
+            expect(result).toContain('| b |');
+        });
+    });
+    describe('inline loading (dynamicLoading=false)', () => {
+        it('formats single skill with header and body', () => {
+            const result = formatSkillsPrompt([makeSkill('greet', 'Say hello.')], undefined, false);
+            expect(result).toContain('## Active Skills');
+            expect(result).toContain('### greet');
+            expect(result).toContain('Say hello.');
+        });
+        it('includes emoji in header when present', () => {
+            const result = formatSkillsPrompt([makeSkill('greet', 'Say hello.', '👋')], undefined, false);
+            expect(result).toContain('### 👋 greet');
+        });
+        it('separates multiple skills with dividers', () => {
+            const result = formatSkillsPrompt([
+                makeSkill('a', 'A body'),
+                makeSkill('b', 'B body'),
+            ], undefined, false);
+            expect(result).toContain('---');
+            expect(result).toContain('### a');
+            expect(result).toContain('### b');
+        });
+        it('does not skip skills based on prompt budget argument', () => {
+            const result = formatSkillsPrompt([
+                makeSkill('small', 'tiny'),
+                makeSkill('big', 'x'.repeat(50000)),
+            ], 100, false);
+            expect(result).toContain('### small');
+            expect(result).toContain('### big');
+        });
     });
 });

package/dist/__tests__/token-efficiency.test.js

@@ -1,27 +1,49 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterAll } from 'vitest';
 import { truncateToolResult } from '../providers/utils.js';
+import { existsSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+const scratchDir = join(homedir(), '.skimpyclaw', 'scratch');
+// Clean up scratch files created during tests
+afterAll(() => {
+    try {
+        if (existsSync(scratchDir)) {
+            for (const f of readdirSync(scratchDir)) {
+                try {
+                    unlinkSync(join(scratchDir, f));
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    catch { /* ignore */ }
+});
 describe('token efficiency', () => {
     describe('truncateToolResult', () => {
         it('returns short results unchanged', () => {
             const result = 'short result';
             expect(truncateToolResult(result)).toBe(result);
         });
-        it('truncates at exact boundary', () => {
-            const result = 'x'.repeat(10_240);
-            expect(truncateToolResult(result)).toBe(result); // exactly at limit
+        it('returns results under mask threshold unchanged', () => {
+            const result = 'x'.repeat(7_999);
+            expect(truncateToolResult(result)).toBe(result);
         });
-        it('truncates over limit with notice', () => {
-            const result = 'x'.repeat(20_000);
-            const truncated = truncateToolResult(result);
-            expect(truncated.length).toBeLessThan(result.length);
-            expect(truncated).toContain('[Truncated: 20000 chars total]');
-            expect(truncated.startsWith('x'.repeat(10_240))).toBe(true);
+        it('masks large results to scratch file with summary', () => {
+            const result = 'START' + 'x'.repeat(10_000) + 'END';
+            const masked = truncateToolResult(result);
+            expect(masked.length).toBeLessThan(result.length);
+            expect(masked).toContain('[Full output');
+            expect(masked).toContain('saved to');
+            expect(masked).toContain('.skimpyclaw/scratch/');
+            expect(masked).toContain('use Read tool to access');
+            // Summary includes head and tail
+            expect(masked).toContain('START');
+            expect(masked).toContain('END');
         });
-        it('respects custom maxBytes', () => {
-            const result = 'abcdefghij'; // 10 chars
-            const truncated = truncateToolResult(result, 5);
-            expect(truncated).toContain('[Truncated: 10 chars total]');
-            expect(truncated.startsWith('abcde')).toBe(true);
+        it('includes char count in masked output', () => {
+            const result = 'y'.repeat(20_000);
+            const masked = truncateToolResult(result);
+            expect(masked).toContain('20000 chars');
         });
     });
     describe('retry prompt compression', () => {

package/dist/agent.js

@@ -52,7 +52,7 @@ export function buildSystemPrompt(agentId, skillsContext) {
             cronJobId: skillsContext?.cronJobId,
             tags: skillsContext?.tags,
         });
-        skillsSection = formatSkillsPrompt(contextSkills, skillsContext?.skillConfig?.maxPromptTokens);
+        skillsSection = formatSkillsPrompt(contextSkills, skillsContext?.skillConfig?.maxPromptTokens, skillsContext?.skillConfig?.dynamicLoading);
     }
     const base = [soul, identity, tools, skillsSection].filter(Boolean).join('\n\n---\n\n');
     const userContext = [user, memory].filter(Boolean).join('\n\n');

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.)
@@ -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/service.js

@@ -6,12 +6,37 @@ import { initProviders } from './agent.js';
 import { initLangfuse, shutdownLangfuse } from './langfuse.js';
 import { restoreCodeAgentTasks, setCodeAgentConfig } from './tools.js';
 import { releaseAll, cleanupOrphans, setRuntime, probeRuntime } from './sandbox/index.js';
+/** Clean up old scratch files (observation masking). Keeps files < 24h. */
+function cleanupScratch() {
+    try {
+        const { readdirSync, statSync, unlinkSync } = require('fs');
+        const { join } = require('path');
+        const { homedir } = require('os');
+        const dir = join(homedir(), '.skimpyclaw', 'scratch');
+        const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+        let count = 0;
+        for (const f of readdirSync(dir)) {
+            const p = join(dir, f);
+            try {
+                if (statSync(p).mtimeMs < cutoff) {
+                    unlinkSync(p);
+                    count++;
+                }
+            }
+            catch { /* skip */ }
+        }
+        if (count > 0)
+            console.log(`[scratch] Cleaned up ${count} old file(s)`);
+    }
+    catch { /* dir doesn't exist yet, fine */ }
+}
 export async function startRuntime(config) {
     const smokeTest = process.env.SKIMPYCLAW_SMOKE_TEST === '1';
     initLangfuse(config);
     initProviders(config);
     restoreCodeAgentTasks();
     setCodeAgentConfig(config);
+    cleanupScratch();
     // Initialize sandbox runtime if configured — auto-disable if no runtime available
     if (config.sandbox?.enabled) {
         const detected = probeRuntime(config.sandbox.runtime);

package/dist/skills-types.d.ts

@@ -62,4 +62,10 @@ export interface SkillConfig {
     entries?: Record<string, boolean>;
     /** Max approximate tokens for injected skills prompt (default: 4000) */
     maxPromptTokens?: number;
+    /**
+     * Dynamic loading: only include skill names and descriptions in the system prompt.
+     * Full skill content is loaded on-demand via the Read tool.
+     * Default: true (progressive disclosure)
+     */
+    dynamicLoading?: boolean;
 }

package/dist/skills.d.ts

@@ -27,5 +27,9 @@ export declare function getSkillsForContext(skills: LoadedSkill[], context?: {
 }): LoadedSkill[];
 /**
  * Format eligible, context-filtered skills into a markdown prompt section.
+ *
+ * When dynamicLoading is true (default), only skill names, descriptions, and
+ * file paths are included. The agent loads full content on-demand via the Read tool.
+ * When false, full skill bodies are inlined (legacy behavior).
  */
-export declare function formatSkillsPrompt(skills: LoadedSkill[], _maxTokens?: number): string;
+export declare function formatSkillsPrompt(skills: LoadedSkill[], _maxTokens?: number, dynamicLoading?: boolean): string;

package/dist/skills.js

@@ -237,12 +237,35 @@ export function getSkillsForContext(skills, context) {
 }
 /**
  * Format eligible, context-filtered skills into a markdown prompt section.
+ *
+ * When dynamicLoading is true (default), only skill names, descriptions, and
+ * file paths are included. The agent loads full content on-demand via the Read tool.
+ * When false, full skill bodies are inlined (legacy behavior).
  */
-export function formatSkillsPrompt(skills, _maxTokens) {
+export function formatSkillsPrompt(skills, _maxTokens, dynamicLoading) {
     if (skills.length === 0)
         return '';
+    // Default to dynamic loading
+    const useDynamic = dynamicLoading !== false;
+    if (useDynamic) {
+        const lines = [
+            '## Skills',
+            '',
+            'Available skills — read the SKILL.md file with the Read tool when the task matches a skill\'s description.',
+            '',
+            '| Skill | Description | Path |',
+            '|-------|-------------|------|',
+        ];
+        for (const skill of skills) {
+            const emoji = skill.frontmatter.emoji ? `${skill.frontmatter.emoji} ` : '';
+            const desc = skill.frontmatter.description || '(no description)';
+            const path = join(skill.dirPath, 'SKILL.md');
+            lines.push(`| ${emoji}${skill.name} | ${desc} | \`${path}\` |`);
+        }
+        return lines.join('\n');
+    }
+    // Legacy: inline full skill bodies
     const sections = [];
-    // Header
     const header = '## Active Skills\n';
     for (const skill of skills) {
         const emoji = skill.frontmatter.emoji ? `${skill.frontmatter.emoji} ` : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skimpyclaw",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Lightweight personal AI assistant with Telegram and Discord integration",
   "type": "module",
   "main": "dist/index.js",
@@ -16,25 +16,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "cli": "tsx src/cli.ts",
-    "start": "tsx src/index.ts",
-    "dev": "tsx watch src/index.ts",
-    "dashboard:dev": "pnpm --dir web/dashboard dev",
-    "dashboard:build": "pnpm --dir web/dashboard install --frozen-lockfile && pnpm --dir web/dashboard build",
-    "docs:dev": "pnpm --dir docs dev",
-    "docs:build": "pnpm --dir docs install --frozen-lockfile && pnpm --dir docs build",
-    "docs:preview": "pnpm --dir docs preview",
-    "setup": "tsx src/setup.ts",
-    "onboard": "tsx src/cli.ts onboard",
-    "build": "tsc && pnpm dashboard:build",
-    "release:check": "pnpm build && pnpm test",
-    "release:local": "bash ./scripts/release.sh",
-    "lint": "eslint \"src/**/*.ts\"",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "ci": "pnpm run lint && pnpm run typecheck && pnpm run test"
-  },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.52.0",
     "@grammyjs/runner": "^2.0.3",
@@ -56,11 +37,6 @@
     "openai": "^4.47.0",
     "playwright": "^1.49.0"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^20.11.0",
@@ -70,5 +46,24 @@
     "typescript": "^5.4.0",
     "typescript-eslint": "^8.54.0",
     "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "cli": "tsx src/cli.ts",
+    "start": "tsx src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "dashboard:dev": "pnpm --dir web/dashboard dev",
+    "dashboard:build": "pnpm --dir web/dashboard install --frozen-lockfile && pnpm --dir web/dashboard build",
+    "docs:dev": "pnpm --dir docs dev",
+    "docs:build": "pnpm --dir docs install --frozen-lockfile && pnpm --dir docs build",
+    "docs:preview": "pnpm --dir docs preview",
+    "setup": "tsx src/setup.ts",
+    "onboard": "tsx src/cli.ts onboard",
+    "build": "tsc && pnpm dashboard:build",
+    "release:check": "pnpm build && pnpm test",
+    "release:local": "bash ./scripts/release.sh",
+    "lint": "eslint \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "ci": "pnpm run lint && pnpm run typecheck && pnpm run test"
   }
-}
+}