@compilr-dev/agents 0.3.16 → 0.3.18

package/LICENSE

@@ -0,0 +1,108 @@
+Functional Source License, Version 1.1, MIT Future License
+
+Abbreviation: FSL-1.1-MIT
+
+Notice
+
+Copyright 2026 Carmelo Scozzola
+
+Terms and Conditions
+
+Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,7 +13,7 @@
 > Lightweight multi-LLM agent library for building CLI AI assistants
 
 [![npm version](https://img.shields.io/npm/v/@compilr-dev/agents.svg)](https://www.npmjs.com/package/@compilr-dev/agents)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](https://fsl.software/)
 
 > [!WARNING]
 > This package is in beta. APIs may change between minor versions.
@@ -1314,7 +1314,7 @@ const agent = new Agent({ provider, tracing });
 
 ## License
 
-MIT - See [LICENSE](LICENSE) for details.
+[FSL-1.1-MIT](https://fsl.software/) - See [LICENSE](LICENSE) for details. Converts to MIT after 2 years per version.
 
 ---
 

package/dist/agent.d.ts

@@ -15,6 +15,7 @@ import type { DelegationConfig } from './context/delegation-types.js';
 import { PermissionManager } from './permissions/manager.js';
 import { ContextManager } from './context/manager.js';
 import { FileAccessTracker } from './context/file-tracker.js';
+import type { ObservationMaskConfig } from './context/observation-masker.js';
 import { AnchorManager } from './anchors/manager.js';
 import { GuardrailManager } from './guardrails/manager.js';
 import { type RetryConfig } from './utils/index.js';
@@ -278,6 +279,17 @@ export interface AgentConfig {
      * Requires contextManager to be set. Default: true when contextManager is provided.
      */
     autoContextManagement?: boolean;
+    /**
+     * Observation masking configuration. Masks old tool results in history to reduce tokens.
+     * Enabled by default when contextManager is provided. Set to `false` to disable.
+     */
+    observationMask?: Partial<ObservationMaskConfig> | false;
+    /**
+     * Use compact text format for tool results in LLM messages.
+     * Strips JSON wrappers and metadata, reducing token usage.
+     * Enabled by default when contextManager is provided. Set to `false` to disable.
+     */
+    compactToolResults?: boolean;
     /**
      * Event handler for monitoring agent execution
      */
@@ -878,6 +890,14 @@ export declare class Agent {
      * File restoration options for post-compaction content injection
      */
     private readonly fileRestorationConfig?;
+    /**
+     * Observation masker for reducing token usage by masking old tool results
+     */
+    private readonly observationMasker?;
+    /**
+     * Whether to use compact text format for tool results in LLM messages
+     */
+    private readonly compactToolResults;
     constructor(config: AgentConfig);
     /**
      * Create an agent with project memory loaded from files.
@@ -1280,6 +1300,14 @@ export declare class Agent {
      * Get context statistics
      */
     getContextStats(): ContextStats | undefined;
+    /**
+     * Get observation masking statistics (tokens saved, observations masked).
+     */
+    getObservationMaskStats(): {
+        maskedCount: number;
+        tokensSaved: number;
+        activeStamps: number;
+    } | undefined;
     /**
      * Get current verbosity level based on context pressure
      */

package/dist/agent.js

@@ -10,6 +10,8 @@ import { ContextManager } from './context/manager.js';
 import { FileAccessTracker } from './context/file-tracker.js';
 import { createFileTrackingHook } from './context/file-tracking-hook.js';
 import { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './context/tool-result-delegator.js';
+import { ObservationMasker } from './context/observation-masker.js';
+import { compactToolResult } from './context/result-compactor.js';
 import { createRecallResultTool } from './tools/builtin/recall-result.js';
 import { AnchorManager } from './anchors/manager.js';
 import { GuardrailManager } from './guardrails/manager.js';
@@ -97,6 +99,14 @@ export class Agent {
      * File restoration options for post-compaction content injection
      */
     fileRestorationConfig;
+    /**
+     * Observation masker for reducing token usage by masking old tool results
+     */
+    observationMasker;
+    /**
+     * Whether to use compact text format for tool results in LLM messages
+     */
+    compactToolResults;
     constructor(config) {
         this.provider = config.provider;
         this.systemPrompt = config.systemPrompt ?? '';
@@ -112,6 +122,12 @@ export class Agent {
         this.contextManager = config.contextManager;
         this.autoContextManagement =
             config.autoContextManagement ?? config.contextManager !== undefined;
+        // Observation masking: enabled by default when contextManager is provided, unless explicitly false
+        if (config.observationMask !== false && this.contextManager) {
+            this.observationMasker = new ObservationMasker(config.observationMask === undefined ? undefined : config.observationMask);
+        }
+        // Compact tool results: enabled by default when contextManager is provided
+        this.compactToolResults = config.compactToolResults ?? this.contextManager !== undefined;
         this.onEvent = config.onEvent;
         this.onIterationLimitReached = config.onIterationLimitReached;
         // State management
@@ -752,6 +768,7 @@ export class Agent {
     clearHistory() {
         this.conversationHistory = [];
         this.contextManager?.reset();
+        this.observationMasker?.reset();
         return this;
     }
     /**
@@ -807,6 +824,12 @@ export class Agent {
     getContextStats() {
         return this.contextManager?.getStats(this.conversationHistory.length);
     }
+    /**
+     * Get observation masking statistics (tokens saved, observations masked).
+     */
+    getObservationMaskStats() {
+        return this.observationMasker?.getStats();
+    }
     /**
      * Get current verbosity level based on context pressure
      */
@@ -1915,7 +1938,9 @@ export class Agent {
                                             type: 'tool_result',
                                             toolUseId: toolUse.id,
                                             content: result.success
-                                                ? JSON.stringify(result.result)
+                                                ? this.compactToolResults
+                                                    ? compactToolResult(toolUse.name, result.result, toolUse.input)
+                                                    : JSON.stringify(result.result)
                                                 : `Error: ${result.error ?? 'Unknown error'}`,
                                             isError: !result.success,
                                         },
@@ -1998,7 +2023,9 @@ export class Agent {
                     emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
                     // Build tool result content
                     let toolResultContent = result.success
-                        ? JSON.stringify(result.result)
+                        ? this.compactToolResults
+                            ? compactToolResult(toolUse.name, result.result, toolUse.input)
+                            : JSON.stringify(result.result)
                         : `Error: ${result.error ?? 'Unknown error'}`;
                     // Context management (only for sequential - parallel handles this after)
                     if (!inParallelGroup && this.contextManager && this.autoContextManagement) {
@@ -2071,6 +2098,11 @@ export class Agent {
                             iterationToolCalls.push(toolCallEntry);
                             messages.push(toolResultMsg);
                             newMessages.push(toolResultMsg);
+                            // Stamp for observation masking
+                            if (this.observationMasker) {
+                                const block = toolResultMsg.content[0];
+                                this.observationMasker.stamp(toolUse.id, toolUse.name, toolUse.input, block.content.length, this.contextManager?.getTurnCount() ?? 0);
+                            }
                         }
                     }
                     else {
@@ -2105,6 +2137,11 @@ export class Agent {
                             iterationToolCalls.push(toolCallEntry);
                             messages.push(toolResultMsg);
                             newMessages.push(toolResultMsg);
+                            // Stamp for observation masking
+                            if (this.observationMasker) {
+                                const block = toolResultMsg.content[0];
+                                this.observationMasker.stamp(toolUse.id, toolUse.name, toolUse.input, block.content.length, this.contextManager?.getTurnCount() ?? 0);
+                            }
                             if (skipped) {
                                 continue;
                             }
@@ -2223,6 +2260,10 @@ export class Agent {
             // Context management: increment turn count and update token count
             if (this.contextManager) {
                 this.contextManager.incrementTurn();
+                // Observation masking: mask old tool results in-place before token update
+                if (this.observationMasker) {
+                    this.observationMasker.maskHistory(messages, this.contextManager.getTurnCount());
+                }
                 await this.contextManager.updateTokenCount(messages);
             }
             // Update internal state tracking

package/dist/context/index.d.ts

@@ -20,3 +20,6 @@ export { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './tool-result-del
 export type { ToolResultDelegatorOptions } from './tool-result-delegator.js';
 export { DEFAULT_DELEGATION_CONFIG } from './delegation-types.js';
 export type { DelegationConfig, StoredResult, DelegationEvent } from './delegation-types.js';
+export { compactToolResult } from './result-compactor.js';
+export { ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, } from './observation-masker.js';
+export type { ObservationMaskConfig, MaskResult, ObservationMaskStats, } from './observation-masker.js';

package/dist/context/index.js

@@ -15,3 +15,7 @@ export { createFileTrackingHook, TRACKED_TOOLS } from './file-tracking-hook.js';
 export { DelegatedResultStore } from './delegated-result-store.js';
 export { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './tool-result-delegator.js';
 export { DEFAULT_DELEGATION_CONFIG } from './delegation-types.js';
+// Compact Tool Result Formatting (Phase 2 Token Optimization)
+export { compactToolResult } from './result-compactor.js';
+// Observation Masking (Phase 1 Token Optimization)
+export { ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, } from './observation-masker.js';

package/dist/context/observation-masker.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Observation Masker — Phase 1 of Advanced Token Optimization
+ *
+ * Masks old tool results (observations) in conversation history to reduce token usage.
+ * Based on JetBrains Research (Dec 2025): observation masking outperforms LLM summarization,
+ * achieving 52% cost reduction with +2.6% higher solve rates.
+ *
+ * Strategy: In-place masking of conversationHistory after N turns.
+ * The agent can re-read from the environment if needed (files, git, etc.).
+ */
+import type { Message } from '../providers/types.js';
+export interface ObservationMaskConfig {
+    /** Turns after which tool results are masked (default: 6) */
+    maskAfterTurns: number;
+    /** Minimum content length (chars) to mask — skip tiny results (default: 400 ≈ 100 tokens) */
+    minCharsToMask: number;
+    /** Tool names to NEVER mask (e.g., recall tools, state queries) */
+    neverMask: string[];
+    /** Tool names to mask after just 1 turn (large reads, bash output) */
+    alwaysMaskEarly: string[];
+}
+export declare const DEFAULT_MASK_CONFIG: ObservationMaskConfig;
+interface TurnStamp {
+    turn: number;
+    toolName: string;
+    /** Short summary of input for mask text (e.g., file path, command) */
+    inputSummary: string;
+    /** Original content length in chars */
+    contentLength: number;
+}
+export interface MaskResult {
+    maskedCount: number;
+    tokensSaved: number;
+}
+export interface ObservationMaskStats {
+    /** Total observations masked this session */
+    maskedCount: number;
+    /** Estimated tokens saved this session */
+    tokensSaved: number;
+    /** Active stamps (pending masking) */
+    activeStamps: number;
+}
+export declare class ObservationMasker {
+    private readonly stamps;
+    private readonly config;
+    private stats;
+    constructor(config?: Partial<ObservationMaskConfig>);
+    /**
+     * Register a tool result with its turn number and input context.
+     * Called immediately after a tool result is added to the messages array.
+     */
+    stamp(toolUseId: string, toolName: string, input: Record<string, unknown>, contentLength: number, turn: number): void;
+    /**
+     * Mask old tool results in-place in the messages array.
+     * Modifies ToolResultBlock.content directly.
+     */
+    maskHistory(messages: Message[], currentTurn: number): MaskResult;
+    getStats(): ObservationMaskStats;
+    /**
+     * Reset all state (stamps and stats). Used when clearing history.
+     */
+    reset(): void;
+    /**
+     * Get current configuration (for testing/inspection).
+     */
+    getConfig(): ObservationMaskConfig;
+}
+/**
+ * Extract a short summary from tool input for the mask text.
+ */
+export declare function extractInputSummary(toolName: string, input: Record<string, unknown>): string;
+/**
+ * Build the compact mask text that replaces the original content.
+ */
+export declare function buildMaskText(stamp: TurnStamp): string;
+/**
+ * Check if a tool result content string is already masked.
+ */
+export declare function isMasked(content: string): boolean;
+export {};

package/dist/context/observation-masker.js

@@ -0,0 +1,192 @@
+/**
+ * Observation Masker — Phase 1 of Advanced Token Optimization
+ *
+ * Masks old tool results (observations) in conversation history to reduce token usage.
+ * Based on JetBrains Research (Dec 2025): observation masking outperforms LLM summarization,
+ * achieving 52% cost reduction with +2.6% higher solve rates.
+ *
+ * Strategy: In-place masking of conversationHistory after N turns.
+ * The agent can re-read from the environment if needed (files, git, etc.).
+ */
+export const DEFAULT_MASK_CONFIG = {
+    maskAfterTurns: 6,
+    minCharsToMask: 400,
+    neverMask: ['recall_full_result', 'recall_work'],
+    alwaysMaskEarly: ['read_file', 'bash', 'bash_output', 'grep', 'glob'],
+};
+// ============================================================
+// ObservationMasker
+// ============================================================
+export class ObservationMasker {
+    stamps = new Map();
+    config;
+    stats = { maskedCount: 0, tokensSaved: 0 };
+    constructor(config) {
+        this.config = { ...DEFAULT_MASK_CONFIG, ...config };
+    }
+    // ----------------------------------------------------------
+    // Stamping — called when tool results are added to history
+    // ----------------------------------------------------------
+    /**
+     * Register a tool result with its turn number and input context.
+     * Called immediately after a tool result is added to the messages array.
+     */
+    stamp(toolUseId, toolName, input, contentLength, turn) {
+        this.stamps.set(toolUseId, {
+            turn,
+            toolName,
+            inputSummary: extractInputSummary(toolName, input),
+            contentLength,
+        });
+    }
+    // ----------------------------------------------------------
+    // Masking — called after incrementTurn()
+    // ----------------------------------------------------------
+    /**
+     * Mask old tool results in-place in the messages array.
+     * Modifies ToolResultBlock.content directly.
+     */
+    maskHistory(messages, currentTurn) {
+        let tokensSaved = 0;
+        let maskedCount = 0;
+        for (const msg of messages) {
+            if (msg.role !== 'user' || typeof msg.content === 'string')
+                continue;
+            for (const block of msg.content) {
+                if (block.type !== 'tool_result')
+                    continue;
+                if (isMasked(block.content))
+                    continue;
+                const stamp = this.stamps.get(block.toolUseId);
+                if (!stamp)
+                    continue;
+                if (this.config.neverMask.includes(stamp.toolName))
+                    continue;
+                const age = currentTurn - stamp.turn;
+                const threshold = this.config.alwaysMaskEarly.includes(stamp.toolName)
+                    ? 1
+                    : this.config.maskAfterTurns;
+                if (age < threshold)
+                    continue;
+                if (stamp.contentLength < this.config.minCharsToMask)
+                    continue;
+                // Build mask and calculate savings
+                const maskText = buildMaskText(stamp);
+                const savedChars = stamp.contentLength - maskText.length;
+                const savedTokens = Math.max(0, Math.ceil(savedChars / 4));
+                // Mask in-place
+                block.content = maskText;
+                tokensSaved += savedTokens;
+                maskedCount++;
+                // Clean up stamp
+                this.stamps.delete(block.toolUseId);
+            }
+        }
+        this.stats.maskedCount += maskedCount;
+        this.stats.tokensSaved += tokensSaved;
+        return { maskedCount, tokensSaved };
+    }
+    // ----------------------------------------------------------
+    // Stats
+    // ----------------------------------------------------------
+    getStats() {
+        return {
+            ...this.stats,
+            activeStamps: this.stamps.size,
+        };
+    }
+    /**
+     * Reset all state (stamps and stats). Used when clearing history.
+     */
+    reset() {
+        this.stamps.clear();
+        this.stats = { maskedCount: 0, tokensSaved: 0 };
+    }
+    /**
+     * Get current configuration (for testing/inspection).
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+// ============================================================
+// Pure functions (exported for testing)
+// ============================================================
+/**
+ * Extract a short summary from tool input for the mask text.
+ */
+export function extractInputSummary(toolName, input) {
+    // File operations — use path
+    if (toolName === 'read_file' || toolName === 'edit' || toolName === 'write_file') {
+        const path = input.path ?? input.file_path;
+        if (typeof path === 'string')
+            return path;
+    }
+    // Shell commands — use command (truncated)
+    if (toolName === 'bash' || toolName === 'bash_output') {
+        const cmd = input.command;
+        if (typeof cmd === 'string') {
+            return cmd.length > 40 ? cmd.slice(0, 40) + '...' : cmd;
+        }
+    }
+    // Search — use pattern
+    if (toolName === 'grep') {
+        const pattern = input.pattern;
+        if (typeof pattern === 'string')
+            return `"${pattern}"`;
+    }
+    // Glob — use pattern
+    if (toolName === 'glob') {
+        const pattern = input.pattern;
+        if (typeof pattern === 'string')
+            return pattern;
+    }
+    // Git tools — use subcommand or operation
+    if (toolName.startsWith('git_')) {
+        return toolName.slice(4); // "git_diff" → "diff"
+    }
+    // Web fetch — use URL
+    if (toolName === 'web_fetch') {
+        const url = input.url;
+        if (typeof url === 'string') {
+            return url.length > 60 ? url.slice(0, 60) + '...' : url;
+        }
+    }
+    // Default — just the tool name
+    return toolName;
+}
+/**
+ * Build the compact mask text that replaces the original content.
+ */
+export function buildMaskText(stamp) {
+    const { toolName, inputSummary, turn, contentLength } = stamp;
+    const lines = String(Math.ceil(contentLength / 80));
+    const t = String(turn);
+    if (toolName === 'read_file') {
+        return `[file:${inputSummary} ~${lines}L read@turn:${t}]`;
+    }
+    if (toolName === 'bash' || toolName === 'bash_output') {
+        return `[cmd:${inputSummary} ~${lines}L@turn:${t}]`;
+    }
+    if (toolName === 'grep') {
+        return `[search:${inputSummary}@turn:${t}]`;
+    }
+    if (toolName === 'glob') {
+        return `[glob:${inputSummary}@turn:${t}]`;
+    }
+    if (toolName.startsWith('git_')) {
+        return `[git:${inputSummary}@turn:${t}]`;
+    }
+    if (toolName === 'edit' || toolName === 'write_file') {
+        return `[write:${inputSummary}@turn:${t}]`;
+    }
+    // Generic
+    const tokens = String(Math.ceil(contentLength / 4));
+    return `[tool:${toolName} ${tokens}tok@turn:${t}]`;
+}
+/**
+ * Check if a tool result content string is already masked.
+ */
+export function isMasked(content) {
+    return content.startsWith('[') && content.endsWith(']') && content.includes('@turn:');
+}

package/dist/context/result-compactor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compact Tool Result Formatting — Phase 2 of Advanced Token Optimization
+ *
+ * Replaces JSON.stringify for tool results in the LLM messages array.
+ * Per-tool formatters strip JSON overhead (escaped newlines, metadata fields)
+ * and produce a text format the LLM can parse just as well.
+ *
+ * Only affects what the LLM reads in its message history.
+ * CLI formatters, events, and hooks still receive the raw ToolExecutionResult.
+ */
+/**
+ * Format a tool result as compact text for LLM context.
+ * Falls back to JSON.stringify for unknown tools or non-object results.
+ */
+export declare function compactToolResult(toolName: string, result: unknown, input?: Record<string, unknown>): string;