@timmeck/brain-core 2.36.23 → 2.36.25

package/dist/tool-learning/__tests__/tool-learning.test.js

@@ -0,0 +1,187 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import Database from 'better-sqlite3';
+vi.mock('../../utils/logger.js', () => ({
+    getLogger: () => ({
+        info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn(),
+    }),
+}));
+import { ToolTracker, runToolTrackerMigration } from '../tool-tracker.js';
+import { ToolPatternAnalyzer } from '../tool-patterns.js';
+function createDb() {
+    return new Database(':memory:');
+}
+describe('ToolTracker', () => {
+    let db;
+    beforeEach(() => {
+        db = createDb();
+    });
+    afterEach(() => {
+        db.close();
+    });
+    it('records usage and retrieves it', () => {
+        const tracker = new ToolTracker(db, { brainName: 'test' });
+        tracker.recordUsage('mcp.search', 'searching docs', 150, 'success');
+        const stats = tracker.getToolStats('mcp.search');
+        expect(stats).toEqual(expect.objectContaining({
+            tool: 'mcp.search',
+            totalUses: 1,
+            successRate: 1,
+        }));
+    });
+    it('returns stats for a single tool', () => {
+        const tracker = new ToolTracker(db, { brainName: 'test' });
+        tracker.recordUsage('mcp.search', 'ctx', 100, 'success');
+        tracker.recordUsage('mcp.search', 'ctx', 200, 'failure');
+        const stats = tracker.getToolStats('mcp.search');
+        expect(stats).toEqual(expect.objectContaining({
+            tool: 'mcp.search',
+            totalUses: 2,
+            successRate: 0.5,
+            avgDuration: 150,
+        }));
+    });
+    it('returns stats for all tools', () => {
+        const tracker = new ToolTracker(db, { brainName: 'test' });
+        tracker.recordUsage('tool-a', 'ctx', 100, 'success');
+        tracker.recordUsage('tool-b', 'ctx', 200, 'success');
+        tracker.recordUsage('tool-a', 'ctx', 300, 'success');
+        const stats = tracker.getToolStats();
+        expect(Array.isArray(stats)).toBe(true);
+        expect(stats.length).toBe(2);
+        // tool-a should be first (more uses)
+        expect(stats[0].tool).toBe('tool-a');
+    });
+    it('recommends tools sorted by success rate * frequency', () => {
+        const tracker = new ToolTracker(db, { brainName: 'test' });
+        // tool-a: 3 successes in 'debug' context
+        tracker.recordUsage('tool-a', 'debug error', 100, 'success');
+        tracker.recordUsage('tool-a', 'debug crash', 100, 'success');
+        tracker.recordUsage('tool-a', 'debug log', 100, 'success');
+        // tool-b: 1 success in 'debug' context
+        tracker.recordUsage('tool-b', 'debug issue', 200, 'success');
+        // tool-c: no 'debug' context
+        tracker.recordUsage('tool-c', 'build project', 50, 'success');
+        const recs = tracker.recommend('debug');
+        expect(recs.length).toBeGreaterThanOrEqual(2);
+        expect(recs[0].tool).toBe('tool-a');
+        // tool-c should not appear (no debug context)
+        expect(recs.find(r => r.tool === 'tool-c')).toBeUndefined();
+    });
+    it('records usage with different outcomes', () => {
+        const tracker = new ToolTracker(db, { brainName: 'test' });
+        tracker.recordUsage('tool-x', 'ctx', 100, 'success');
+        tracker.recordUsage('tool-x', 'ctx', 100, 'failure');
+        tracker.recordUsage('tool-x', 'ctx', 100, 'partial');
+        const stats = tracker.getToolStats('tool-x');
+        expect(stats).toEqual(expect.objectContaining({
+            totalUses: 3,
+        }));
+        // 1 success out of 3 = 0.333...
+        expect(stats.successRate).toBeCloseTo(1 / 3, 5);
+    });
+    it('returns empty stats for unknown tool', () => {
+        const tracker = new ToolTracker(db, { brainName: 'test' });
+        const stats = tracker.getToolStats('nonexistent');
+        expect(stats).toEqual(expect.objectContaining({
+            tool: 'nonexistent',
+            totalUses: 0,
+            successRate: 0,
+        }));
+    });
+    it('getStatus returns correct counts', () => {
+        const tracker = new ToolTracker(db, { brainName: 'test' });
+        tracker.recordUsage('tool-a', null, null, 'success');
+        tracker.recordUsage('tool-b', null, null, 'failure');
+        tracker.recordUsage('tool-a', null, null, 'success');
+        const status = tracker.getStatus();
+        expect(status.totalTracked).toBe(3);
+        expect(status.uniqueTools).toBe(2);
+        // 2 successes out of 3
+        expect(status.avgSuccessRate).toBeCloseTo(2 / 3, 5);
+    });
+    it('migration is idempotent', () => {
+        const tracker1 = new ToolTracker(db, { brainName: 'test' });
+        tracker1.recordUsage('tool-a', 'ctx', 100, 'success');
+        // Run migration again — should not throw or lose data
+        runToolTrackerMigration(db);
+        const tracker2 = new ToolTracker(db, { brainName: 'test' });
+        const stats = tracker2.getToolStats('tool-a');
+        expect(stats).toEqual(expect.objectContaining({ totalUses: 1 }));
+    });
+    it('getStatus returns zeros when empty', () => {
+        const tracker = new ToolTracker(db, { brainName: 'test' });
+        const status = tracker.getStatus();
+        expect(status.totalTracked).toBe(0);
+        expect(status.uniqueTools).toBe(0);
+        expect(status.avgSuccessRate).toBe(0);
+    });
+});
+describe('ToolPatternAnalyzer', () => {
+    let db;
+    beforeEach(() => {
+        db = createDb();
+        // ToolTracker migration creates the table
+        runToolTrackerMigration(db);
+    });
+    afterEach(() => {
+        db.close();
+    });
+    function insertUsage(tool, createdAt) {
+        db.prepare(`
+      INSERT INTO tool_usage (tool_name, context, outcome, created_at)
+      VALUES (?, 'test', 'success', ?)
+    `).run(tool, createdAt);
+    }
+    it('builds transitions correctly', () => {
+        insertUsage('search', '2026-03-06 10:00:00');
+        insertUsage('read', '2026-03-06 10:01:00');
+        insertUsage('edit', '2026-03-06 10:02:00');
+        insertUsage('search', '2026-03-06 10:03:00');
+        insertUsage('read', '2026-03-06 10:04:00');
+        const analyzer = new ToolPatternAnalyzer(db);
+        const transitions = analyzer.getTransitions();
+        expect(transitions.get('search')?.get('read')).toBe(2);
+        expect(transitions.get('read')?.get('edit')).toBe(1);
+        expect(transitions.get('edit')?.get('search')).toBe(1);
+    });
+    it('predicts next tool based on transitions', () => {
+        insertUsage('search', '2026-03-06 10:00:00');
+        insertUsage('read', '2026-03-06 10:01:00');
+        insertUsage('search', '2026-03-06 10:02:00');
+        insertUsage('read', '2026-03-06 10:03:00');
+        insertUsage('search', '2026-03-06 10:04:00');
+        insertUsage('edit', '2026-03-06 10:05:00');
+        const analyzer = new ToolPatternAnalyzer(db);
+        const predictions = analyzer.predictNext('search');
+        expect(predictions.length).toBeGreaterThanOrEqual(1);
+        // 'read' follows 'search' 2 out of 3 times
+        expect(predictions[0].tool).toBe('read');
+        expect(predictions[0].probability).toBeCloseTo(2 / 3, 5);
+    });
+    it('finds frequent pairs within 5-minute windows', () => {
+        // All within 5 minutes of each other
+        insertUsage('search', '2026-03-06 10:00:00');
+        insertUsage('read', '2026-03-06 10:01:00');
+        insertUsage('search', '2026-03-06 10:02:00');
+        insertUsage('read', '2026-03-06 10:03:00');
+        const analyzer = new ToolPatternAnalyzer(db);
+        const pairs = analyzer.getFrequentPairs();
+        expect(pairs.length).toBeGreaterThanOrEqual(1);
+        const searchRead = pairs.find(p => (p.toolA === 'read' && p.toolB === 'search') ||
+            (p.toolA === 'search' && p.toolB === 'read'));
+        expect(searchRead).toBeDefined();
+        expect(searchRead.count).toBeGreaterThanOrEqual(2);
+    });
+    it('returns empty predictions for unknown tool', () => {
+        const analyzer = new ToolPatternAnalyzer(db);
+        const predictions = analyzer.predictNext('nonexistent');
+        expect(predictions).toEqual([]);
+    });
+    it('returns empty sequences when not enough data', () => {
+        insertUsage('search', '2026-03-06 10:00:00');
+        const analyzer = new ToolPatternAnalyzer(db);
+        const sequences = analyzer.getSequences(3);
+        expect(sequences).toEqual([]);
+    });
+});
+//# sourceMappingURL=tool-learning.test.js.map

package/dist/tool-learning/__tests__/tool-learning.test.js.map

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

package/dist/tool-learning/index.d.ts

@@ -0,0 +1,4 @@
+export { ToolTracker, runToolTrackerMigration } from './tool-tracker.js';
+export { ToolPatternAnalyzer } from './tool-patterns.js';
+export type { ToolOutcome, ToolUsageRecord, ToolStats, ToolRecommendation, ToolTrackerStatus, ToolTrackerConfig, } from './tool-tracker.js';
+export type { ToolSequence, ToolPrediction, ToolPair, ToolTransition, } from './tool-patterns.js';

package/dist/tool-learning/index.js

@@ -0,0 +1,3 @@
+export { ToolTracker, runToolTrackerMigration } from './tool-tracker.js';
+export { ToolPatternAnalyzer } from './tool-patterns.js';
+//# sourceMappingURL=index.js.map

package/dist/tool-learning/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tool-learning/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/tool-learning/tool-patterns.d.ts

@@ -0,0 +1,47 @@
+import type Database from 'better-sqlite3';
+export interface ToolSequence {
+    sequence: string[];
+    count: number;
+}
+export interface ToolPrediction {
+    tool: string;
+    probability: number;
+}
+export interface ToolPair {
+    toolA: string;
+    toolB: string;
+    count: number;
+}
+/** A single from→to transition with its count. */
+export interface ToolTransition {
+    from: string;
+    to: string;
+    count: number;
+}
+export declare class ToolPatternAnalyzer {
+    private db;
+    private log;
+    private stmtAllUsage;
+    private stmtWindowUsage;
+    constructor(db: Database.Database);
+    /**
+     * Find common tool sequences (N-grams) of the given window size.
+     * Returns sequences sorted by frequency descending.
+     */
+    getSequences(windowSize?: number): ToolSequence[];
+    /**
+     * Build a Markov transition matrix: which tool follows which.
+     * Returns Map<toolA, Map<toolB, count>>.
+     */
+    getTransitions(): Map<string, Map<string, number>>;
+    /**
+     * Predict the top 3 most likely next tools given the current tool,
+     * based on transition probabilities from the Markov chain.
+     */
+    predictNext(currentTool: string): ToolPrediction[];
+    /**
+     * Find tool pairs that frequently occur together within 5-minute windows.
+     * Returns pairs sorted by co-occurrence count descending.
+     */
+    getFrequentPairs(): ToolPair[];
+}

package/dist/tool-learning/tool-patterns.js

@@ -0,0 +1,125 @@
+// ── Tool Pattern Analyzer — Sequence & Transition Analysis ───
+//
+// Analyzes tool usage sequences to find patterns, build Markov
+// transition matrices, and predict likely next tools.
+import { getLogger } from '../utils/logger.js';
+// ── Engine ──────────────────────────────────────────────
+export class ToolPatternAnalyzer {
+    db;
+    log = getLogger();
+    // Prepared statements
+    stmtAllUsage;
+    stmtWindowUsage;
+    constructor(db) {
+        this.db = db;
+        // These statements query the tool_usage table created by ToolTracker
+        this.stmtAllUsage = db.prepare(`
+      SELECT tool_name, created_at FROM tool_usage ORDER BY created_at ASC
+    `);
+        this.stmtWindowUsage = db.prepare(`
+      SELECT tool_name, created_at FROM tool_usage ORDER BY created_at ASC
+    `);
+        this.log.info('[tool-patterns] Analyzer initialized');
+    }
+    /**
+     * Find common tool sequences (N-grams) of the given window size.
+     * Returns sequences sorted by frequency descending.
+     */
+    getSequences(windowSize = 3) {
+        const rows = this.stmtAllUsage.all();
+        if (rows.length < windowSize)
+            return [];
+        const seqMap = new Map();
+        for (let i = 0; i <= rows.length - windowSize; i++) {
+            const seq = rows.slice(i, i + windowSize).map(r => r.tool_name);
+            const key = seq.join(' → ');
+            seqMap.set(key, (seqMap.get(key) ?? 0) + 1);
+        }
+        const sequences = [];
+        for (const [key, count] of seqMap.entries()) {
+            if (count >= 2) {
+                sequences.push({ sequence: key.split(' → '), count });
+            }
+        }
+        sequences.sort((a, b) => b.count - a.count);
+        return sequences;
+    }
+    /**
+     * Build a Markov transition matrix: which tool follows which.
+     * Returns Map<toolA, Map<toolB, count>>.
+     */
+    getTransitions() {
+        const rows = this.stmtAllUsage.all();
+        const transitions = new Map();
+        for (let i = 0; i < rows.length - 1; i++) {
+            const from = rows[i].tool_name;
+            const to = rows[i + 1].tool_name;
+            if (!transitions.has(from)) {
+                transitions.set(from, new Map());
+            }
+            const inner = transitions.get(from);
+            inner.set(to, (inner.get(to) ?? 0) + 1);
+        }
+        return transitions;
+    }
+    /**
+     * Predict the top 3 most likely next tools given the current tool,
+     * based on transition probabilities from the Markov chain.
+     */
+    predictNext(currentTool) {
+        const transitions = this.getTransitions();
+        const fromMap = transitions.get(currentTool);
+        if (!fromMap || fromMap.size === 0)
+            return [];
+        // Calculate total transitions from this tool
+        let total = 0;
+        for (const count of fromMap.values()) {
+            total += count;
+        }
+        const predictions = [];
+        for (const [tool, count] of fromMap.entries()) {
+            predictions.push({
+                tool,
+                probability: count / total,
+            });
+        }
+        predictions.sort((a, b) => b.probability - a.probability);
+        return predictions.slice(0, 3);
+    }
+    /**
+     * Find tool pairs that frequently occur together within 5-minute windows.
+     * Returns pairs sorted by co-occurrence count descending.
+     */
+    getFrequentPairs() {
+        const rows = this.stmtWindowUsage.all();
+        if (rows.length < 2)
+            return [];
+        const pairMap = new Map();
+        const WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+        for (let i = 0; i < rows.length; i++) {
+            const timeI = new Date(rows[i].created_at).getTime();
+            for (let j = i + 1; j < rows.length; j++) {
+                const timeJ = new Date(rows[j].created_at).getTime();
+                if (timeJ - timeI > WINDOW_MS)
+                    break;
+                const toolA = rows[i].tool_name;
+                const toolB = rows[j].tool_name;
+                if (toolA === toolB)
+                    continue;
+                // Normalize pair key (alphabetical order) so A-B and B-A count together
+                const key = toolA < toolB ? `${toolA}|${toolB}` : `${toolB}|${toolA}`;
+                pairMap.set(key, (pairMap.get(key) ?? 0) + 1);
+            }
+        }
+        const pairs = [];
+        for (const [key, count] of pairMap.entries()) {
+            if (count >= 2) {
+                const [toolA, toolB] = key.split('|');
+                pairs.push({ toolA, toolB, count });
+            }
+        }
+        pairs.sort((a, b) => b.count - a.count);
+        return pairs;
+    }
+}
+//# sourceMappingURL=tool-patterns.js.map

package/dist/tool-learning/tool-patterns.js.map

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

package/dist/tool-learning/tool-tracker.d.ts

@@ -0,0 +1,58 @@
+import type Database from 'better-sqlite3';
+import type { ThoughtStream } from '../consciousness/thought-stream.js';
+export type ToolOutcome = 'success' | 'failure' | 'partial';
+export interface ToolUsageRecord {
+    id?: number;
+    tool_name: string;
+    context: string | null;
+    duration_ms: number | null;
+    outcome: ToolOutcome;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+export interface ToolStats {
+    tool: string;
+    totalUses: number;
+    successRate: number;
+    avgDuration: number;
+    lastUsed: string;
+}
+export interface ToolRecommendation {
+    tool: string;
+    score: number;
+    successRate: number;
+    frequency: number;
+}
+export interface ToolTrackerStatus {
+    totalTracked: number;
+    uniqueTools: number;
+    avgSuccessRate: number;
+}
+export interface ToolTrackerConfig {
+    brainName: string;
+}
+export declare function runToolTrackerMigration(db: Database.Database): void;
+export declare class ToolTracker {
+    private db;
+    private config;
+    private ts;
+    private log;
+    private stmtInsert;
+    private stmtStatsSingle;
+    private stmtStatsAll;
+    private stmtRecommend;
+    private stmtTotalTracked;
+    private stmtUniqueTools;
+    private stmtAvgSuccessRate;
+    constructor(db: Database.Database, config: ToolTrackerConfig);
+    /** Set the ThoughtStream for consciousness integration. */
+    setThoughtStream(stream: ThoughtStream): void;
+    /** Record a tool usage event. */
+    recordUsage(tool: string, context: string | null, duration: number | null, outcome?: ToolOutcome, metadata?: Record<string, unknown>): void;
+    /** Get statistics for a specific tool, or all tools if none specified. */
+    getToolStats(tool?: string): ToolStats | ToolStats[];
+    /** Recommend top-5 tools for a given context based on success rate * frequency. */
+    recommend(context: string): ToolRecommendation[];
+    /** Get tracker status summary. */
+    getStatus(): ToolTrackerStatus;
+}

package/dist/tool-learning/tool-tracker.js

@@ -0,0 +1,135 @@
+// ── Tool Tracker — Usage Recording & Recommendation ──────────
+//
+// Tracks tool usage with context, duration, and outcome.
+// Provides statistics and context-based recommendations.
+import { getLogger } from '../utils/logger.js';
+// ── Migration ───────────────────────────────────────────
+export function runToolTrackerMigration(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS tool_usage (
+      id INTEGER PRIMARY KEY,
+      tool_name TEXT NOT NULL,
+      context TEXT,
+      duration_ms INTEGER,
+      outcome TEXT DEFAULT 'success' CHECK(outcome IN ('success','failure','partial')),
+      metadata TEXT,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_tool_usage_tool_name ON tool_usage(tool_name);
+  `);
+}
+// ── Engine ──────────────────────────────────────────────
+export class ToolTracker {
+    db;
+    config;
+    ts = null;
+    log = getLogger();
+    // Prepared statements
+    stmtInsert;
+    stmtStatsSingle;
+    stmtStatsAll;
+    stmtRecommend;
+    stmtTotalTracked;
+    stmtUniqueTools;
+    stmtAvgSuccessRate;
+    constructor(db, config) {
+        this.db = db;
+        this.config = config;
+        runToolTrackerMigration(db);
+        // Prepare all statements
+        this.stmtInsert = db.prepare(`
+      INSERT INTO tool_usage (tool_name, context, duration_ms, outcome, metadata)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        this.stmtStatsSingle = db.prepare(`
+      SELECT
+        tool_name AS tool,
+        COUNT(*) AS totalUses,
+        CAST(SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) AS successRate,
+        COALESCE(AVG(duration_ms), 0) AS avgDuration,
+        MAX(created_at) AS lastUsed
+      FROM tool_usage
+      WHERE tool_name = ?
+      GROUP BY tool_name
+    `);
+        this.stmtStatsAll = db.prepare(`
+      SELECT
+        tool_name AS tool,
+        COUNT(*) AS totalUses,
+        CAST(SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) AS successRate,
+        COALESCE(AVG(duration_ms), 0) AS avgDuration,
+        MAX(created_at) AS lastUsed
+      FROM tool_usage
+      GROUP BY tool_name
+      ORDER BY totalUses DESC
+    `);
+        this.stmtRecommend = db.prepare(`
+      SELECT
+        tool_name AS tool,
+        COUNT(*) AS frequency,
+        CAST(SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) AS successRate
+      FROM tool_usage
+      WHERE context LIKE ?
+      GROUP BY tool_name
+      ORDER BY (CAST(SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) AS REAL) / COUNT(*)) * COUNT(*) DESC
+      LIMIT 5
+    `);
+        this.stmtTotalTracked = db.prepare(`
+      SELECT COUNT(*) AS total FROM tool_usage
+    `);
+        this.stmtUniqueTools = db.prepare(`
+      SELECT COUNT(DISTINCT tool_name) AS unique_tools FROM tool_usage
+    `);
+        this.stmtAvgSuccessRate = db.prepare(`
+      SELECT COALESCE(
+        CAST(SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) AS REAL) / NULLIF(COUNT(*), 0),
+        0
+      ) AS avgRate
+      FROM tool_usage
+    `);
+        this.log.info(`[tool-tracker] Initialized for ${config.brainName}`);
+    }
+    /** Set the ThoughtStream for consciousness integration. */
+    setThoughtStream(stream) {
+        this.ts = stream;
+    }
+    /** Record a tool usage event. */
+    recordUsage(tool, context, duration, outcome = 'success', metadata) {
+        this.stmtInsert.run(tool, context, duration, outcome, metadata ? JSON.stringify(metadata) : null);
+        this.ts?.emit('tool-tracker', 'analyzing', `Recorded ${tool} usage: ${outcome}${duration ? ` (${duration}ms)` : ''}`, 'routine');
+    }
+    /** Get statistics for a specific tool, or all tools if none specified. */
+    getToolStats(tool) {
+        if (tool) {
+            const row = this.stmtStatsSingle.get(tool);
+            if (!row) {
+                return { tool, totalUses: 0, successRate: 0, avgDuration: 0, lastUsed: '' };
+            }
+            return row;
+        }
+        return this.stmtStatsAll.all();
+    }
+    /** Recommend top-5 tools for a given context based on success rate * frequency. */
+    recommend(context) {
+        const pattern = `%${context}%`;
+        const rows = this.stmtRecommend.all(pattern);
+        return rows.map(r => ({
+            tool: r.tool,
+            score: r.successRate * r.frequency,
+            successRate: r.successRate,
+            frequency: r.frequency,
+        }));
+    }
+    /** Get tracker status summary. */
+    getStatus() {
+        const total = this.stmtTotalTracked.get().total;
+        const unique = this.stmtUniqueTools.get().unique_tools;
+        const avgRate = this.stmtAvgSuccessRate.get().avgRate;
+        return {
+            totalTracked: total,
+            uniqueTools: unique,
+            avgSuccessRate: avgRate,
+        };
+    }
+}
+//# sourceMappingURL=tool-tracker.js.map

package/dist/tool-learning/tool-tracker.js.map

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

package/dist/user-model/__tests__/user-model.test.d.ts

@@ -0,0 +1 @@
+export {};