@compilr-dev/agents 0.0.1

package/dist/anchors/builtin.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Built-in default safety anchors
+ *
+ * These anchors provide sensible safety defaults that can be disabled
+ * by setting includeDefaults: false in AnchorManagerOptions.
+ */
+import type { Anchor } from './types.js';
+/**
+ * Default safety anchors shipped with the library
+ */
+export declare const DEFAULT_SAFETY_ANCHORS: Anchor[];
+/**
+ * Get a copy of the default safety anchors
+ * Clones the anchors to prevent mutation
+ */
+export declare function getDefaultAnchors(): Anchor[];
+/**
+ * Check if an anchor is a built-in default
+ */
+export declare function isBuiltinAnchor(anchor: Anchor): boolean;
+/**
+ * Get built-in anchor IDs
+ */
+export declare function getBuiltinAnchorIds(): string[];

package/dist/anchors/builtin.js

@@ -0,0 +1,61 @@
+/**
+ * Built-in default safety anchors
+ *
+ * These anchors provide sensible safety defaults that can be disabled
+ * by setting includeDefaults: false in AnchorManagerOptions.
+ */
+/**
+ * Default safety anchors shipped with the library
+ */
+export const DEFAULT_SAFETY_ANCHORS = [
+    {
+        id: 'builtin-git-safety',
+        content: 'Before destructive git operations (reset --hard, checkout --, restore, clean), ' +
+            'verify current state with git status and git diff. Consider stashing changes first.',
+        priority: 'safety',
+        scope: 'persistent',
+        createdAt: new Date(0), // Epoch - always oldest
+        tags: ['builtin', 'git', 'safety'],
+    },
+    {
+        id: 'builtin-file-safety',
+        content: 'Before deleting files or directories, confirm the path is correct and consider ' +
+            'if content should be backed up. Never delete root, home, or project root directories.',
+        priority: 'safety',
+        scope: 'persistent',
+        createdAt: new Date(0),
+        tags: ['builtin', 'filesystem', 'safety'],
+    },
+    {
+        id: 'builtin-database-safety',
+        content: 'Before DROP TABLE, TRUNCATE, or DELETE without WHERE, confirm the operation is ' +
+            'intentional and consider backing up the data first. Never run on production without explicit confirmation.',
+        priority: 'safety',
+        scope: 'persistent',
+        createdAt: new Date(0),
+        tags: ['builtin', 'database', 'safety'],
+    },
+];
+/**
+ * Get a copy of the default safety anchors
+ * Clones the anchors to prevent mutation
+ */
+export function getDefaultAnchors() {
+    return DEFAULT_SAFETY_ANCHORS.map((anchor) => ({
+        ...anchor,
+        createdAt: new Date(anchor.createdAt),
+        tags: anchor.tags ? [...anchor.tags] : undefined,
+    }));
+}
+/**
+ * Check if an anchor is a built-in default
+ */
+export function isBuiltinAnchor(anchor) {
+    return anchor.id.startsWith('builtin-');
+}
+/**
+ * Get built-in anchor IDs
+ */
+export function getBuiltinAnchorIds() {
+    return DEFAULT_SAFETY_ANCHORS.map((a) => a.id);
+}

package/dist/anchors/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Anchors module - Critical information that survives context compaction
+ */
+export { AnchorManager } from './manager.js';
+export { getDefaultAnchors, isBuiltinAnchor, getBuiltinAnchorIds, DEFAULT_SAFETY_ANCHORS, } from './builtin.js';
+export type { Anchor, AnchorInput, AnchorPriority, AnchorScope, AnchorQueryOptions, AnchorClearOptions, AnchorManagerOptions, AnchorEventType, AnchorEvent, AnchorEventHandler, SerializedAnchor, } from './types.js';

package/dist/anchors/index.js

@@ -0,0 +1,5 @@
+/**
+ * Anchors module - Critical information that survives context compaction
+ */
+export { AnchorManager } from './manager.js';
+export { getDefaultAnchors, isBuiltinAnchor, getBuiltinAnchorIds, DEFAULT_SAFETY_ANCHORS, } from './builtin.js';

package/dist/anchors/manager.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AnchorManager - Manages anchors (critical information that survives context compaction)
+ */
+import type { Anchor, AnchorInput, AnchorQueryOptions, AnchorClearOptions, AnchorManagerOptions, AnchorEventHandler } from './types.js';
+/**
+ * AnchorManager - Manages critical information that survives context compaction
+ *
+ * @example
+ * ```typescript
+ * const manager = new AnchorManager({
+ *   maxAnchors: 20,
+ *   maxTokens: 2000,
+ *   persistPath: '~/.myapp/anchors.json',
+ * });
+ *
+ * // Add a session anchor
+ * manager.add({
+ *   content: 'This session we implemented: edit tool, grep tool',
+ *   priority: 'critical',
+ *   scope: 'session',
+ * });
+ *
+ * // Get formatted anchors for injection into LLM messages
+ * const formatted = manager.format();
+ * ```
+ */
+export declare class AnchorManager {
+    private readonly anchors;
+    private readonly options;
+    private eventHandler?;
+    constructor(options?: AnchorManagerOptions);
+    /**
+     * Set the event handler for anchor events
+     */
+    onEvent(handler: AnchorEventHandler): void;
+    /**
+     * Emit an event
+     */
+    private emit;
+    /**
+     * Add a new anchor
+     *
+     * @param input - Anchor input (id and createdAt auto-generated if not provided)
+     * @returns The created anchor
+     */
+    add(input: AnchorInput): Anchor;
+    /**
+     * Get an anchor by ID
+     */
+    get(id: string): Anchor | undefined;
+    /**
+     * Get all anchors, optionally filtered
+     */
+    getAll(options?: AnchorQueryOptions): Anchor[];
+    /**
+     * Check if an anchor exists
+     */
+    has(id: string): boolean;
+    /**
+     * Remove an anchor by ID
+     *
+     * @returns true if anchor was removed, false if not found
+     */
+    remove(id: string): boolean;
+    /**
+     * Clear anchors based on criteria
+     */
+    clear(options?: AnchorClearOptions): number;
+    /**
+     * Get the current number of anchors
+     */
+    get size(): number;
+    /**
+     * Get total tokens used by all anchors
+     */
+    getTotalTokens(): number;
+    /**
+     * Get token budget utilization (0-1)
+     */
+    getUtilization(): number;
+    /**
+     * Format anchors for injection into LLM messages
+     *
+     * Groups anchors by priority and formats them for the system message.
+     */
+    format(): string;
+    /**
+     * Check if an anchor is expired
+     */
+    private isExpired;
+    /**
+     * Clean up expired temporary anchors
+     */
+    private cleanupExpired;
+    /**
+     * Make room for new content by removing low-priority anchors
+     */
+    private makeRoom;
+    /**
+     * Remove the oldest low-priority anchor to make room
+     */
+    private removeOldestLowPriority;
+    /**
+     * Load persistent anchors from disk
+     */
+    private loadPersistent;
+    /**
+     * Save persistent anchors to disk
+     */
+    private savePersistent;
+    /**
+     * Expand ~ in paths
+     */
+    private expandPath;
+}

package/dist/anchors/manager.js

@@ -0,0 +1,412 @@
+/**
+ * AnchorManager - Manages anchors (critical information that survives context compaction)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { generateId } from '../utils/index.js';
+import { getDefaultAnchors, isBuiltinAnchor } from './builtin.js';
+/**
+ * Default options for AnchorManager
+ */
+const DEFAULT_OPTIONS = {
+    maxAnchors: 20,
+    maxTokens: 2000,
+    includeDefaults: true,
+};
+/**
+ * Default token estimator (rough estimate: ~4 chars per token)
+ */
+function defaultEstimateTokens(content) {
+    return Math.ceil(content.length / 4);
+}
+/**
+ * AnchorManager - Manages critical information that survives context compaction
+ *
+ * @example
+ * ```typescript
+ * const manager = new AnchorManager({
+ *   maxAnchors: 20,
+ *   maxTokens: 2000,
+ *   persistPath: '~/.myapp/anchors.json',
+ * });
+ *
+ * // Add a session anchor
+ * manager.add({
+ *   content: 'This session we implemented: edit tool, grep tool',
+ *   priority: 'critical',
+ *   scope: 'session',
+ * });
+ *
+ * // Get formatted anchors for injection into LLM messages
+ * const formatted = manager.format();
+ * ```
+ */
+export class AnchorManager {
+    anchors = new Map();
+    options;
+    eventHandler;
+    constructor(options = {}) {
+        this.options = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+            estimateTokens: options.estimateTokens ?? defaultEstimateTokens,
+        };
+        // Load persistent anchors from disk
+        if (this.options.persistPath) {
+            this.loadPersistent();
+        }
+        // Add built-in default anchors
+        if (this.options.includeDefaults) {
+            for (const anchor of getDefaultAnchors()) {
+                this.anchors.set(anchor.id, anchor);
+            }
+        }
+    }
+    /**
+     * Set the event handler for anchor events
+     */
+    onEvent(handler) {
+        this.eventHandler = handler;
+    }
+    /**
+     * Emit an event
+     */
+    emit(type, anchor, message) {
+        this.eventHandler?.({ type, anchor, message });
+    }
+    /**
+     * Add a new anchor
+     *
+     * @param input - Anchor input (id and createdAt auto-generated if not provided)
+     * @returns The created anchor
+     */
+    add(input) {
+        // Clean up expired anchors first
+        this.cleanupExpired();
+        // Check budget before adding
+        const newTokens = this.options.estimateTokens(input.content);
+        const currentTokens = this.getTotalTokens();
+        if (currentTokens + newTokens > this.options.maxTokens) {
+            // Try to make room by removing low-priority anchors
+            this.makeRoom(newTokens);
+        }
+        // Check anchor count limit
+        if (this.anchors.size >= this.options.maxAnchors) {
+            this.removeOldestLowPriority();
+        }
+        // Create the anchor
+        const anchor = {
+            id: input.id ?? `anchor_${generateId()}`,
+            content: input.content,
+            priority: input.priority,
+            scope: input.scope,
+            createdAt: new Date(),
+            expiresAt: input.expiresAt,
+            tags: input.tags,
+            metadata: input.metadata,
+        };
+        // Store the anchor
+        this.anchors.set(anchor.id, anchor);
+        this.emit('anchor:added', anchor);
+        // Persist if it's a persistent anchor
+        if (anchor.scope === 'persistent' && this.options.persistPath) {
+            this.savePersistent();
+        }
+        return anchor;
+    }
+    /**
+     * Get an anchor by ID
+     */
+    get(id) {
+        const anchor = this.anchors.get(id);
+        if (anchor && this.isExpired(anchor)) {
+            this.remove(id);
+            return undefined;
+        }
+        return anchor;
+    }
+    /**
+     * Get all anchors, optionally filtered
+     */
+    getAll(options) {
+        this.cleanupExpired();
+        let anchors = Array.from(this.anchors.values());
+        // Filter by priority
+        if (options?.priority) {
+            anchors = anchors.filter((a) => a.priority === options.priority);
+        }
+        // Filter by scope
+        if (options?.scope) {
+            anchors = anchors.filter((a) => a.scope === options.scope);
+        }
+        // Filter by tags (must have ALL specified tags)
+        const tagsFilter = options?.tags;
+        if (tagsFilter && tagsFilter.length > 0) {
+            anchors = anchors.filter((a) => {
+                const anchorTags = a.tags;
+                if (!anchorTags)
+                    return false;
+                return tagsFilter.every((tag) => anchorTags.includes(tag));
+            });
+        }
+        // Filter out expired unless requested
+        if (!options?.includeExpired) {
+            anchors = anchors.filter((a) => !this.isExpired(a));
+        }
+        return anchors;
+    }
+    /**
+     * Check if an anchor exists
+     */
+    has(id) {
+        return this.get(id) !== undefined;
+    }
+    /**
+     * Remove an anchor by ID
+     *
+     * @returns true if anchor was removed, false if not found
+     */
+    remove(id) {
+        const anchor = this.anchors.get(id);
+        if (!anchor)
+            return false;
+        this.anchors.delete(id);
+        this.emit('anchor:removed', anchor);
+        // Update persistence if it was a persistent anchor
+        if (anchor.scope === 'persistent' && this.options.persistPath) {
+            this.savePersistent();
+        }
+        return true;
+    }
+    /**
+     * Clear anchors based on criteria
+     */
+    clear(options) {
+        let removed = 0;
+        const toRemove = [];
+        for (const [id, anchor] of this.anchors) {
+            // Skip built-in anchors unless explicitly clearing by scope
+            if (isBuiltinAnchor(anchor) && !options?.scope) {
+                continue;
+            }
+            // Filter by scope
+            if (options?.scope && anchor.scope !== options.scope) {
+                continue;
+            }
+            // Filter by tags
+            if (options?.tags && options.tags.length > 0) {
+                const anchorTags = anchor.tags;
+                if (!anchorTags || !options.tags.every((tag) => anchorTags.includes(tag))) {
+                    continue;
+                }
+            }
+            // Filter by expired
+            if (options?.expiredOnly && !this.isExpired(anchor)) {
+                continue;
+            }
+            toRemove.push(id);
+        }
+        for (const id of toRemove) {
+            this.remove(id);
+            removed++;
+        }
+        return removed;
+    }
+    /**
+     * Get the current number of anchors
+     */
+    get size() {
+        return this.anchors.size;
+    }
+    /**
+     * Get total tokens used by all anchors
+     */
+    getTotalTokens() {
+        let total = 0;
+        for (const anchor of this.anchors.values()) {
+            if (!this.isExpired(anchor)) {
+                total += this.options.estimateTokens(anchor.content);
+            }
+        }
+        return total;
+    }
+    /**
+     * Get token budget utilization (0-1)
+     */
+    getUtilization() {
+        return this.getTotalTokens() / this.options.maxTokens;
+    }
+    /**
+     * Format anchors for injection into LLM messages
+     *
+     * Groups anchors by priority and formats them for the system message.
+     */
+    format() {
+        const anchors = this.getAll();
+        if (anchors.length === 0)
+            return '';
+        // Group by priority
+        const critical = anchors.filter((a) => a.priority === 'critical');
+        const safety = anchors.filter((a) => a.priority === 'safety');
+        const info = anchors.filter((a) => a.priority === 'info');
+        const parts = [];
+        if (critical.length > 0) {
+            parts.push('### CRITICAL (Must Remember)');
+            for (const a of critical) {
+                parts.push(`- ${a.content}`);
+            }
+        }
+        if (safety.length > 0) {
+            if (parts.length > 0)
+                parts.push('');
+            parts.push('### SAFETY (Check Before Acting)');
+            for (const a of safety) {
+                parts.push(`- ${a.content}`);
+            }
+        }
+        if (info.length > 0) {
+            if (parts.length > 0)
+                parts.push('');
+            parts.push('### INFO');
+            for (const a of info) {
+                parts.push(`- ${a.content}`);
+            }
+        }
+        return parts.join('\n');
+    }
+    /**
+     * Check if an anchor is expired
+     */
+    isExpired(anchor) {
+        if (anchor.scope !== 'temporary' || !anchor.expiresAt) {
+            return false;
+        }
+        return new Date() > anchor.expiresAt;
+    }
+    /**
+     * Clean up expired temporary anchors
+     */
+    cleanupExpired() {
+        const toRemove = [];
+        for (const [id, anchor] of this.anchors) {
+            if (this.isExpired(anchor)) {
+                toRemove.push(id);
+            }
+        }
+        for (const id of toRemove) {
+            const anchor = this.anchors.get(id);
+            this.anchors.delete(id);
+            this.emit('anchor:expired', anchor);
+        }
+    }
+    /**
+     * Make room for new content by removing low-priority anchors
+     */
+    makeRoom(neededTokens) {
+        // Sort by priority (info first, then safety, then critical)
+        // Within same priority, oldest first
+        const priorityOrder = { info: 0, safety: 1, critical: 2 };
+        const sortedAnchors = this.getAll()
+            .filter((a) => !isBuiltinAnchor(a)) // Don't remove built-ins
+            .sort((a, b) => {
+            const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority];
+            if (priorityDiff !== 0)
+                return priorityDiff;
+            return a.createdAt.getTime() - b.createdAt.getTime();
+        });
+        let freedTokens = 0;
+        for (const anchor of sortedAnchors) {
+            if (freedTokens >= neededTokens)
+                break;
+            const tokens = this.options.estimateTokens(anchor.content);
+            this.remove(anchor.id);
+            freedTokens += tokens;
+            this.emit('anchor:budget_exceeded', anchor, `Removed to make room for new anchor`);
+        }
+    }
+    /**
+     * Remove the oldest low-priority anchor to make room
+     */
+    removeOldestLowPriority() {
+        const priorityOrder = { info: 0, safety: 1, critical: 2 };
+        const sortedAnchors = this.getAll()
+            .filter((a) => !isBuiltinAnchor(a))
+            .sort((a, b) => {
+            const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority];
+            if (priorityDiff !== 0)
+                return priorityDiff;
+            return a.createdAt.getTime() - b.createdAt.getTime();
+        });
+        if (sortedAnchors.length > 0) {
+            this.remove(sortedAnchors[0].id);
+        }
+    }
+    /**
+     * Load persistent anchors from disk
+     */
+    loadPersistent() {
+        if (!this.options.persistPath)
+            return;
+        try {
+            const expandedPath = this.expandPath(this.options.persistPath);
+            if (!fs.existsSync(expandedPath))
+                return;
+            const data = fs.readFileSync(expandedPath, 'utf-8');
+            const serialized = JSON.parse(data);
+            for (const s of serialized) {
+                const anchor = {
+                    ...s,
+                    createdAt: new Date(s.createdAt),
+                    expiresAt: s.expiresAt ? new Date(s.expiresAt) : undefined,
+                };
+                this.anchors.set(anchor.id, anchor);
+            }
+            this.emit('anchor:loaded', undefined, `Loaded ${String(serialized.length)} persistent anchors`);
+        }
+        catch {
+            // Ignore errors loading - start fresh
+        }
+    }
+    /**
+     * Save persistent anchors to disk
+     */
+    savePersistent() {
+        if (!this.options.persistPath)
+            return;
+        try {
+            const expandedPath = this.expandPath(this.options.persistPath);
+            // Ensure directory exists
+            const dir = path.dirname(expandedPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // Get only persistent anchors (excluding built-ins)
+            const persistent = this.getAll({ scope: 'persistent' }).filter((a) => !isBuiltinAnchor(a));
+            const serialized = persistent.map((a) => ({
+                id: a.id,
+                content: a.content,
+                priority: a.priority,
+                scope: a.scope,
+                createdAt: a.createdAt.toISOString(),
+                expiresAt: a.expiresAt?.toISOString(),
+                tags: a.tags,
+                metadata: a.metadata,
+            }));
+            fs.writeFileSync(expandedPath, JSON.stringify(serialized, null, 2));
+            this.emit('anchor:persisted', undefined, `Saved ${String(serialized.length)} persistent anchors`);
+        }
+        catch {
+            // Ignore errors saving
+        }
+    }
+    /**
+     * Expand ~ in paths
+     */
+    expandPath(p) {
+        if (p.startsWith('~/')) {
+            const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+            return path.join(home, p.slice(2));
+        }
+        return p;
+    }
+}