@xandout/libra-harness 0.1.8

package/dist/extras/extensions/token-stats/extension.js

@@ -0,0 +1,99 @@
+// Metadata key for accumulated usage across LLM calls in a turn.
+const USAGE_KEY = '_tokenStats_usage';
+/**
+ * Token-stats extension — appends a stats line to the agent's final
+ * response message.
+ *
+ * Accumulates token usage across all LLM calls in a turn (via
+ * `afterLLM`), then appends a summary to `turn.response.message` in
+ * `beforeResponse`. The stats include:
+ *
+ * - Total prompt + completion tokens
+ * - Cached and reasoning tokens (if reported)
+ * - Number of LLM calls / iterations
+ * - Context window usage percentage (if `contextWindow` is configured)
+ *
+ * ## Example output (Slack italics)
+ *
+ * ```
+ * _📊 105,445 prompt + 2,324 completion · 1,503 reasoning · 3 LLM calls · 82% of 128K context_
+ * ```
+ *
+ * ## Priority
+ *
+ * Uses priority -100 (runs late, after most extensions) so it sees
+ * the final response after other extensions have potentially modified
+ * it. The `afterLLM` accumulator runs at the same priority.
+ */
+export default function createTokenStatsExtension(config) {
+    const contextWindow = config?.contextWindow;
+    const slackItalics = config?.slackItalics ?? true;
+    const label = config?.label ?? '📊';
+    return {
+        name: 'token-stats',
+        priority: -100,
+        install(agent) {
+            // ── afterLLM: accumulate usage ────────────────────────────────
+            agent.hook('afterLLM', 'token-stats', async (ctx) => {
+                const usage = ctx.modelResponse?.usage;
+                if (!usage)
+                    return;
+                const meta = ctx.turn.metadata;
+                const acc = meta[USAGE_KEY] ?? {
+                    promptTokens: 0,
+                    completionTokens: 0,
+                    cachedPromptTokens: 0,
+                    cacheWriteTokens: 0,
+                    reasoningTokens: 0,
+                    calls: 0,
+                };
+                acc.promptTokens += usage.promptTokens ?? 0;
+                acc.completionTokens += usage.completionTokens ?? 0;
+                acc.cachedPromptTokens += usage.cachedPromptTokens ?? 0;
+                acc.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
+                acc.reasoningTokens += usage.reasoningTokens ?? 0;
+                acc.calls += 1;
+                meta[USAGE_KEY] = acc;
+            });
+            // ── beforeResponse: append stats to the final message ─────────
+            agent.hook('beforeResponse', 'token-stats', async (ctx) => {
+                const response = ctx.turn.response;
+                if (!response)
+                    return;
+                const acc = ctx.turn.metadata[USAGE_KEY];
+                if (!acc || acc.calls === 0)
+                    return;
+                const parts = [
+                    `${fmt(acc.promptTokens)} prompt + ${fmt(acc.completionTokens)} completion`,
+                ];
+                if (acc.cachedPromptTokens > 0 || acc.cacheWriteTokens > 0) {
+                    const cacheParts = [];
+                    if (acc.cachedPromptTokens > 0)
+                        cacheParts.push(`${fmt(acc.cachedPromptTokens)} read`);
+                    if (acc.cacheWriteTokens > 0)
+                        cacheParts.push(`${fmt(acc.cacheWriteTokens)} written`);
+                    parts.push(`cache: ${cacheParts.join(', ')}`);
+                }
+                if (acc.reasoningTokens > 0) {
+                    parts.push(`${fmt(acc.reasoningTokens)} reasoning`);
+                }
+                parts.push(`${acc.calls} LLM call${acc.calls > 1 ? 's' : ''}`);
+                if (contextWindow) {
+                    const pct = ((acc.promptTokens / contextWindow) * 100).toFixed(0);
+                    parts.push(`${pct}% of ${fmt(contextWindow)} context`);
+                }
+                const line = parts.join(' · ');
+                const formatted = slackItalics ? `_${label} ${line}_` : `${label} ${line}`;
+                response.message = `${response.message}\n\n${formatted}`;
+            });
+        },
+    };
+}
+function fmt(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(n);
+}
+//# sourceMappingURL=extension.js.map

package/dist/extras/extensions/token-stats/extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../../../../src/extras/extensions/token-stats/extension.ts"],"names":[],"mappings":"AAyBA,iEAAiE;AACjE,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAWtC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAC/C,MAAyB;IAEzB,MAAM,aAAa,GAAG,MAAM,EAAE,aAAa,CAAC;IAC5C,MAAM,YAAY,GAAG,MAAM,EAAE,YAAY,IAAI,IAAI,CAAC;IAClD,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,IAAI,CAAC;IAEpC,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,QAAQ,EAAE,CAAC,GAAG;QACd,OAAO,CAAC,KAAK;YACX,iEAAiE;YACjE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAClD,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC;gBACvC,IAAI,CAAC,KAAK;oBAAE,OAAO;gBAEnB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAC/B,MAAM,GAAG,GAAI,IAAI,CAAC,SAAS,CAAsB,IAAI;oBACnD,YAAY,EAAE,CAAC;oBACf,gBAAgB,EAAE,CAAC;oBACnB,kBAAkB,EAAE,CAAC;oBACrB,gBAAgB,EAAE,CAAC;oBACnB,eAAe,EAAE,CAAC;oBAClB,KAAK,EAAE,CAAC;iBACT,CAAC;gBAEF,GAAG,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;gBAC5C,GAAG,CAAC,gBAAgB,IAAI,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;gBACpD,GAAG,CAAC,kBAAkB,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC,CAAC;gBACxD,GAAG,CAAC,gBAAgB,IAAI,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;gBACpD,GAAG,CAAC,eAAe,IAAI,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC;gBAClD,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;gBAEf,IAAI,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC;YACxB,CAAC,CAAC,CAAC;YAEH,iEAAiE;YACjE,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBACxD,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;gBACnC,IAAI,CAAC,QAAQ;oBAAE,OAAO;gBAEtB,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAiC,CAAC;gBACzE,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,KAAK,CAAC;oBAAE,OAAO;gBAEpC,MAAM,KAAK,GAAa;oBACtB,GAAG,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,aAAa,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,aAAa;iBAC5E,CAAC;gBAEF,IAAI,GAAG,CAAC,kBAAkB,GAAG,CAAC,IAAI,GAAG,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;oBAC3D,MAAM,UAAU,GAAa,EAAE,CAAC;oBAChC,IAAI,GAAG,CAAC,kBAAkB,GAAG,CAAC;wBAAE,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;oBACvF,IAAI,GAAG,CAAC,gBAAgB,GAAG,CAAC;wBAAE,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;oBACtF,KAAK,CAAC,IAAI,CAAC,UAAU,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAChD,CAAC;gBACD,IAAI,GAAG,CAAC,eAAe,GAAG,CAAC,EAAE,CAAC;oBAC5B,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;gBACtD,CAAC;gBAED,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,YAAY,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAE/D,IAAI,aAAa,EAAE,CAAC;oBAClB,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,YAAY,GAAG,aAAa,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;oBAClE,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,QAAQ,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;gBACzD,CAAC;gBAED,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC/B,MAAM,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,IAAI,EAAE,CAAC;gBAE3E,QAAQ,CAAC,OAAO,GAAG,GAAG,QAAQ,CAAC,OAAO,OAAO,SAAS,EAAE,CAAC;YAC3D,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,GAAG,CAAC,CAAS;IACpB,IAAI,CAAC,IAAI,SAAS;QAAE,OAAO,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAC5D,IAAI,CAAC,IAAI,KAAK;QAAE,OAAO,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACpD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/dist/extras/extensions/token-stats/extension.json

@@ -0,0 +1,7 @@
+{
+  "name": "token-stats",
+  "description": "Appends token usage and context window stats to the agent's final response message. Accumulates usage across all LLM calls in a turn.",
+  "enabled": true,
+  "priority": -100,
+  "configKeys": ["contextWindow", "slackItalics", "label"]
+}

package/dist/extras/extensions/token-stats/extension.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extension.test.d.ts.map

package/dist/extras/extensions/token-stats/extension.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.test.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/token-stats/extension.test.ts"],"names":[],"mappings":""}

package/dist/extras/extensions/token-stats/extension.test.js

@@ -0,0 +1,197 @@
+import { describe, it, expect } from 'vitest';
+import { Agent } from '../../../agent.js';
+import { createTokenStatsExtension } from './index.js';
+// ── Mock model ─────────────────────────────────────────────────────
+function mockModel(responses) {
+    let callCount = 0;
+    return {
+        async generate(req) {
+            const resp = responses[Math.min(callCount, responses.length - 1)];
+            callCount++;
+            if (typeof resp.message === 'function') {
+                return { ...resp, message: resp.message(req) };
+            }
+            return resp;
+        },
+    };
+}
+// ── Tests ──────────────────────────────────────────────────────────
+describe('token-stats extension', () => {
+    it('appends stats to the final response', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hello!' },
+                finishReason: 'stop',
+                usage: { promptTokens: 1000, completionTokens: 50 },
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000 });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).toContain('Hello!');
+        expect(result.message).toContain('📊');
+        expect(result.message).toContain('1.0K prompt + 50 completion');
+        expect(result.message).toContain('1 LLM call');
+        expect(result.message).toContain('1% of 128.0K context');
+    });
+    it('uses Slack italics by default', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+                usage: { promptTokens: 100, completionTokens: 10 },
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000 });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        // Should be wrapped in _..._ for Slack italics.
+        expect(result.message).toMatch(/_📊.*_/);
+    });
+    it('disables italics when configured', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+                usage: { promptTokens: 100, completionTokens: 10 },
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000, slackItalics: false });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).not.toMatch(/_📊.*_/);
+        expect(result.message).toContain('📊');
+    });
+    it('omits context percentage when contextWindow not set', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+                usage: { promptTokens: 100, completionTokens: 10 },
+            }]);
+        const ext = createTokenStatsExtension();
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).toContain('100 prompt + 10 completion');
+        expect(result.message).not.toContain('context');
+    });
+    it('accumulates usage across multiple LLM calls', async () => {
+        const tool = {
+            name: 'echo',
+            description: 'Echo',
+            parameters: { type: 'object', properties: {} },
+            async execute() {
+                return { toolCallId: '', content: 'echoed' };
+            },
+        };
+        const model = mockModel([
+            {
+                message: {
+                    role: 'assistant',
+                    content: '',
+                    toolCalls: [{ id: 'tc1', name: 'echo', arguments: '{}' }],
+                },
+                finishReason: 'tool_calls',
+                usage: { promptTokens: 500, completionTokens: 20 },
+            },
+            {
+                message: { role: 'assistant', content: 'Done' },
+                finishReason: 'stop',
+                usage: { promptTokens: 800, completionTokens: 30 },
+            },
+        ]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000 });
+        const agent = new Agent({ model: model, tools: [tool] });
+        agent.use(ext);
+        const result = await agent.run({ message: 'call echo' });
+        // Should show accumulated totals: 500+800=1300 prompt, 20+30=50 completion.
+        expect(result.message).toContain('1.3K prompt + 50 completion');
+        expect(result.message).toContain('2 LLM calls');
+    });
+    it('shows cache read, cache write, and reasoning tokens when present', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+                usage: {
+                    promptTokens: 10000,
+                    completionTokens: 100,
+                    cachedPromptTokens: 5000,
+                    cacheWriteTokens: 3000,
+                    reasoningTokens: 200,
+                },
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000 });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).toContain('cache:');
+        expect(result.message).toContain('5.0K read');
+        expect(result.message).toContain('3.0K written');
+        expect(result.message).toContain('200 reasoning');
+    });
+    it('shows only cache read when no cache write', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+                usage: {
+                    promptTokens: 10000,
+                    completionTokens: 100,
+                    cachedPromptTokens: 5000,
+                },
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000 });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).toContain('cache:');
+        expect(result.message).toContain('5.0K read');
+        expect(result.message).not.toContain('written');
+    });
+    it('omits cache/reasoning when not reported', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+                usage: { promptTokens: 100, completionTokens: 10 },
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000 });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).not.toContain('cached');
+        expect(result.message).not.toContain('reasoning');
+    });
+    it('does not append stats when no usage is reported', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000 });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).toBe('Hi');
+    });
+    it('supports custom label', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+                usage: { promptTokens: 100, completionTokens: 10 },
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000, label: 'Tokens:' });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).toContain('Tokens:');
+        expect(result.message).not.toContain('📊');
+    });
+    it('computes context percentage correctly', async () => {
+        const model = mockModel([{
+                message: { role: 'assistant', content: 'Hi' },
+                finishReason: 'stop',
+                usage: { promptTokens: 64000, completionTokens: 100 },
+            }]);
+        const ext = createTokenStatsExtension({ contextWindow: 128000 });
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'hi' });
+        expect(result.message).toContain('50% of 128.0K context');
+    });
+});
+//# sourceMappingURL=extension.test.js.map

package/dist/extras/extensions/token-stats/extension.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.test.js","sourceRoot":"","sources":["../../../../src/extras/extensions/token-stats/extension.test.ts"],"names":[],"mappings":"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"}

package/dist/extras/extensions/token-stats/index.d.ts

@@ -0,0 +1,3 @@
+export { default as createTokenStatsExtension } from './extension.js';
+export type { TokenStatsConfig } from './extension.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extras/extensions/token-stats/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/token-stats/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/extras/extensions/token-stats/index.js

@@ -0,0 +1,2 @@
+export { default as createTokenStatsExtension } from './extension.js';
+//# sourceMappingURL=index.js.map

package/dist/extras/extensions/token-stats/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/extras/extensions/token-stats/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/extras/extensions/tool-buffer/extension.d.ts

@@ -0,0 +1,89 @@
+import type { Extension } from '../../../extension.js';
+/**
+ * Config for the tool-buffer extension.
+ */
+export interface ToolBufferConfig {
+    /**
+     * Directory to store buffered tool outputs. Created if it doesn't exist.
+     * Default: `./tool-buffers`.
+     */
+    bufferDir?: string;
+    /**
+     * Minimum content length (characters) to trigger buffering. Tool
+     * results shorter than this are passed through unchanged. Default:
+     * `2000`.
+     */
+    threshold?: number;
+    /**
+     * Tool names to buffer (whitelist). If set, only these tools are
+     * buffered. If omitted, all tools are eligible. Default: all tools.
+     */
+    tools?: string[];
+    /**
+     * Tool names to exclude from buffering (blacklist). Takes precedence
+     * over `tools`. Default: none.
+     */
+    excludeTools?: string[];
+    /**
+     * Whether to preserve the first N characters of the original content
+     * in the pointer message, giving the LLM a preview without needing
+     * to grep. Default: `200`.
+     */
+    previewLength?: number;
+    /**
+     * Prefix for buffer file names. A random ID is appended. Default:
+     * `buffer_`.
+     */
+    filePrefix?: string;
+    /**
+     * Name of the no-buffer control tool exposed to the LLM. Default:
+     * `no_buffer`.
+     */
+    noBufferToolName?: string;
+}
+/**
+ * Tool-buffer extension — redirects large tool outputs to files.
+ *
+ * Hooks `afterTool` and checks the result content size. If it exceeds
+ * the configured threshold, the content is written to a file in
+ * `bufferDir` and the tool result is replaced with a pointer message:
+ *
+ * ```
+ * [tool-buffer] Output saved to tool-buffers/buffer_a1b2c3.txt
+ * (234 lines, 12.5 KB). Use grep to search within this file.
+ *
+ * Preview (first 200 chars):
+ * {"jobs":[{"id":"JT-001","name":"Kitchen remodel"},…
+ * ```
+ *
+ * This keeps the LLM context small when tools return large datasets
+ * (e.g. list_jobs, list_messages, search results) while preserving
+ * full access to the data via a grep tool or filesystem reads.
+ *
+ * By default, all tools are buffered. Use `excludeTools` to exempt
+ * tools whose output the LLM always needs inline (e.g. read_file,
+ * send_message, status checks). The LLM can also call `no_buffer`
+ * at runtime to bypass buffering on demand.
+ *
+ * ## LLM-controlled bypass
+ *
+ * The extension registers a `no_buffer` tool that the LLM can call to
+ * disable buffering on demand — either for the next tool call only or
+ * for the rest of the turn. This gives the LLM real-time control without
+ * any tool knowing about buffering.
+ *
+ * - `no_buffer({ scope: "next" })` — skip buffering for the next tool
+ *   call only. The flag is cleared after one tool executes.
+ * - `no_buffer({ scope: "turn" })` — skip buffering for all remaining
+ *   tool calls in this turn.
+ *
+ * The LLM typically calls `no_buffer` before a tool whose full output
+ * it needs inline (e.g. reading a file it intends to summarize).
+ *
+ * ## Priority
+ *
+ * Uses priority -50 (runs after most extensions) so it sees the final
+ * tool result after other extensions have potentially modified it.
+ */
+export default function createToolBufferExtension(config?: ToolBufferConfig): Extension;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extras/extensions/tool-buffer/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/tool-buffer/extension.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIvD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAC/C,MAAM,CAAC,EAAE,gBAAgB,GACxB,SAAS,CAyIX"}

package/dist/extras/extensions/tool-buffer/extension.js

@@ -0,0 +1,182 @@
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+// ── Turn-level flag keys (stored in turn.metadata) ──────────────────
+// These are internal to the extension and not part of the public API.
+const FLAG_NEXT = '_toolBuffer_skipNext';
+const FLAG_TURN = '_toolBuffer_skipTurn';
+/**
+ * Tool-buffer extension — redirects large tool outputs to files.
+ *
+ * Hooks `afterTool` and checks the result content size. If it exceeds
+ * the configured threshold, the content is written to a file in
+ * `bufferDir` and the tool result is replaced with a pointer message:
+ *
+ * ```
+ * [tool-buffer] Output saved to tool-buffers/buffer_a1b2c3.txt
+ * (234 lines, 12.5 KB). Use grep to search within this file.
+ *
+ * Preview (first 200 chars):
+ * {"jobs":[{"id":"JT-001","name":"Kitchen remodel"},…
+ * ```
+ *
+ * This keeps the LLM context small when tools return large datasets
+ * (e.g. list_jobs, list_messages, search results) while preserving
+ * full access to the data via a grep tool or filesystem reads.
+ *
+ * By default, all tools are buffered. Use `excludeTools` to exempt
+ * tools whose output the LLM always needs inline (e.g. read_file,
+ * send_message, status checks). The LLM can also call `no_buffer`
+ * at runtime to bypass buffering on demand.
+ *
+ * ## LLM-controlled bypass
+ *
+ * The extension registers a `no_buffer` tool that the LLM can call to
+ * disable buffering on demand — either for the next tool call only or
+ * for the rest of the turn. This gives the LLM real-time control without
+ * any tool knowing about buffering.
+ *
+ * - `no_buffer({ scope: "next" })` — skip buffering for the next tool
+ *   call only. The flag is cleared after one tool executes.
+ * - `no_buffer({ scope: "turn" })` — skip buffering for all remaining
+ *   tool calls in this turn.
+ *
+ * The LLM typically calls `no_buffer` before a tool whose full output
+ * it needs inline (e.g. reading a file it intends to summarize).
+ *
+ * ## Priority
+ *
+ * Uses priority -50 (runs after most extensions) so it sees the final
+ * tool result after other extensions have potentially modified it.
+ */
+export default function createToolBufferExtension(config) {
+    const bufferDir = config?.bufferDir ?? './tool-buffers';
+    const threshold = config?.threshold ?? 2000;
+    const whitelist = config?.tools ? new Set(config.tools) : undefined;
+    const blacklist = config?.excludeTools ? new Set(config.excludeTools) : undefined;
+    const previewLength = config?.previewLength ?? 200;
+    const filePrefix = config?.filePrefix ?? 'buffer_';
+    const noBufferToolName = config?.noBufferToolName ?? 'no_buffer';
+    // Ensure buffer directory exists at setup time.
+    if (!existsSync(bufferDir)) {
+        mkdirSync(bufferDir, { recursive: true });
+    }
+    function shouldBuffer(toolName) {
+        if (blacklist?.has(toolName))
+            return false;
+        if (whitelist && !whitelist.has(toolName))
+            return false;
+        return true;
+    }
+    function formatSize(bytes) {
+        if (bytes < 1024)
+            return `${bytes} B`;
+        if (bytes < 1024 * 1024)
+            return `${(bytes / 1024).toFixed(1)} KB`;
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+    // ── no_buffer tool ────────────────────────────────────────────────
+    const noBufferTool = {
+        name: noBufferToolName,
+        description: 'Disable tool output buffering. Call this before a tool whose full output you need inline ' +
+            '(e.g. reading a file you intend to summarize or quote). ' +
+            'scope "next" skips buffering for the next tool call only. ' +
+            'scope "turn" skips buffering for all remaining tool calls this turn.',
+        parameters: {
+            type: 'object',
+            properties: {
+                scope: {
+                    type: 'string',
+                    enum: ['next', 'turn'],
+                    description: '"next" = skip buffering for the next tool call only (default). "turn" = skip for all remaining tool calls this turn.',
+                    default: 'next',
+                },
+            },
+        },
+        async execute(args, ctx) {
+            const scope = args.scope ?? 'next';
+            if (scope === 'turn') {
+                ctx.metadata[FLAG_TURN] = true;
+            }
+            else {
+                ctx.metadata[FLAG_NEXT] = true;
+            }
+            return {
+                toolCallId: '',
+                content: `Buffering disabled for ${scope === 'turn' ? 'the rest of this turn' : 'the next tool call'}.`,
+            };
+        },
+    };
+    return {
+        name: 'tool-buffer',
+        priority: -50,
+        install(agent) {
+            // Register the no_buffer tool so the LLM can call it.
+            agent.tool(noBufferTool);
+            agent.hook('afterTool', 'tool-buffer', async (ctx) => {
+                if (!ctx.toolCall || !ctx.toolResult)
+                    return;
+                // The no_buffer tool itself is never buffered.
+                if (ctx.toolCall.name === noBufferToolName)
+                    return;
+                const toolName = ctx.toolCall.name;
+                const result = ctx.toolResult;
+                const meta = ctx.turn.metadata;
+                // Check bypass flags set by the no_buffer tool.
+                const skipTurn = meta[FLAG_TURN] === true;
+                const skipNext = meta[FLAG_NEXT] === true;
+                if (skipTurn || skipNext) {
+                    // Clear the one-shot flag (turn flag persists).
+                    if (skipNext)
+                        delete meta[FLAG_NEXT];
+                    return;
+                }
+                // Don't buffer error results — the LLM needs to see those inline.
+                if (result.isError)
+                    return;
+                // Don't buffer empty or short results.
+                const content = result.content;
+                if (!content || content.length < threshold)
+                    return;
+                // Check whitelist/blacklist.
+                if (!shouldBuffer(toolName))
+                    return;
+                // Generate a unique filename.
+                const id = randomBytes(4).toString('hex');
+                const fileName = `${filePrefix}${id}.txt`;
+                const filePath = join(bufferDir, fileName);
+                // Write the full content to the buffer file.
+                try {
+                    writeFileSync(filePath, content, 'utf-8');
+                }
+                catch (err) {
+                    // If we can't write, pass the result through unchanged.
+                    // Don't break the tool call over a buffering failure.
+                    return;
+                }
+                // Build the pointer message.
+                const lineCount = content.split('\n').length;
+                const sizeBytes = Buffer.byteLength(content, 'utf-8');
+                const preview = content.slice(0, previewLength);
+                const previewTruncated = content.length > previewLength ? '…' : '';
+                const pointer = [
+                    `[tool-buffer] Output saved to ${filePath}`,
+                    `(${lineCount} lines, ${formatSize(sizeBytes)}). Use grep to search within this file.`,
+                    '',
+                    `If you need the full output inline, call no_buffer({ scope: "next" }) and re-run this tool.`,
+                    '',
+                    `Preview (first ${previewLength} chars):`,
+                    preview + previewTruncated,
+                ].join('\n');
+                // Replace the tool result with the pointer.
+                const bufferedResult = {
+                    toolCallId: result.toolCallId,
+                    content: pointer,
+                    isError: false,
+                };
+                return { skip: true, value: bufferedResult };
+            });
+        },
+    };
+}
+//# sourceMappingURL=extension.js.map

package/dist/extras/extensions/tool-buffer/extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../../../../src/extras/extensions/tool-buffer/extension.ts"],"names":[],"mappings":"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"}

package/dist/extras/extensions/tool-buffer/extension.json

@@ -0,0 +1,7 @@
+{
+  "name": "tool-buffer",
+  "description": "Redirects large tool outputs to files and returns a pointer to the LLM. Keeps context small when tools return large datasets. Pair with a grep tool for searching buffered content.",
+  "enabled": true,
+  "priority": -50,
+  "configKeys": ["bufferDir", "threshold", "tools", "excludeTools", "previewLength", "filePrefix"]
+}

package/dist/extras/extensions/tool-buffer/extension.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extension.test.d.ts.map