@xandout/libra-harness 0.1.8

package/dist/extras/extensions/keyword-extractor/extension.test.js

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+import { Agent } from '@xandout/libra-harness';
+import { createWinkQueryAnalyzer } from './index.js';
+import { createKeywordExtractorExtension } from './index.js';
+// Mock model — returns a fixed assistant reply without touching a provider.
+function mockModel() {
+    return {
+        async generate() {
+            return {
+                message: { role: 'assistant', content: 'ok' },
+                finishReason: 'stop',
+                usage: { promptTokens: 0, completionTokens: 0 },
+            };
+        },
+    };
+}
+describe('keyword-extractor extension', () => {
+    it('extracts terms and writes sessionMeta.keywords on beforeTurn', async () => {
+        const extracted = [];
+        let capturedMeta;
+        const analyzer = createWinkQueryAnalyzer();
+        const ext = createKeywordExtractorExtension({
+            analyzer,
+            log: (entry) => extracted.push(entry),
+        });
+        const agent = new Agent({ model: mockModel() });
+        // Register the extension first so its beforeTurn hook runs before
+        // the observer (hooks run in registration order within a stage).
+        agent.use(ext);
+        agent.hook('beforeTurn', 'observer', async (ctx) => {
+            capturedMeta = ctx.turn.metadata.sessionMeta;
+        });
+        await agent.run({
+            message: 'Can you find our documentation about the MCP server architecture?',
+        });
+        expect(extracted).toHaveLength(1);
+        expect(extracted[0].message).toBe('Can you find our documentation about the MCP server architecture?');
+        expect(extracted[0].terms).toEqual([
+            'find',
+            'documentation',
+            'MCP',
+            'server',
+            'architecture',
+        ]);
+        expect(extracted[0].phrases).toContain('MCP server architecture');
+        // The enrichment bag should contain keywords under the right shape.
+        expect(capturedMeta).toBeDefined();
+        expect(capturedMeta.keywords).toEqual({
+            terms: ['find', 'documentation', 'MCP', 'server', 'architecture'],
+            phrases: expect.arrayContaining(['MCP server architecture']),
+        });
+    });
+    it('extracts empty terms for an empty message', async () => {
+        const extracted = [];
+        const ext = createKeywordExtractorExtension({
+            analyzer: createWinkQueryAnalyzer(),
+            log: (entry) => extracted.push(entry),
+        });
+        const agent = new Agent({ model: mockModel() });
+        agent.use(ext);
+        await agent.run({ message: '' });
+        expect(extracted).toHaveLength(1);
+        expect(extracted[0].terms).toEqual([]);
+        expect(extracted[0].phrases).toEqual([]);
+    });
+    it('uses the shared analyzer when none is provided', async () => {
+        const extracted = [];
+        const ext = createKeywordExtractorExtension({ log: (e) => extracted.push(e) });
+        const agent = new Agent({ model: mockModel() });
+        agent.use(ext);
+        await agent.run({ message: 'Where did we store agent memory?' });
+        expect(extracted[0].terms).toEqual(['store', 'agent', 'memory']);
+    });
+    it('merges into existing sessionMeta without overwriting other keys', async () => {
+        let capturedMeta;
+        const ext = createKeywordExtractorExtension({
+            analyzer: createWinkQueryAnalyzer(),
+            log: () => { },
+        });
+        const agent = new Agent({ model: mockModel() });
+        // A prior extension with higher priority writes its own key first.
+        const priorExt = {
+            name: 'prior',
+            priority: 100,
+            install(a) {
+                a.hook('beforeTurn', 'prior', async (ctx) => {
+                    ctx.turn.metadata.sessionMeta = { sentiment: 'positive' };
+                });
+            },
+        };
+        agent.use(priorExt);
+        // keyword-extractor (priority 50) runs second and should merge, not overwrite.
+        agent.use(ext);
+        // Observe after both have run (default priority 0 = last).
+        agent.hook('beforeTurn', 'observer', async (ctx) => {
+            capturedMeta = ctx.turn.metadata.sessionMeta;
+        });
+        await agent.run({ message: 'Find the MCP documentation' });
+        expect(capturedMeta).toBeDefined();
+        expect(capturedMeta.sentiment).toBe('positive');
+        expect(capturedMeta.keywords).toBeDefined();
+        expect(capturedMeta.keywords.terms).toContain('MCP');
+    });
+});
+//# sourceMappingURL=extension.test.js.map

package/dist/extras/extensions/keyword-extractor/extension.test.js.map

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

package/dist/extras/extensions/keyword-extractor/index.d.ts

@@ -0,0 +1,5 @@
+export { default as createKeywordExtractorExtension } from './extension.js';
+export type { KeywordExtractorConfig, KeywordExtractionEntry } from './extension.js';
+export type { SearchTerms, QueryAnalyzer } from './nlp.js';
+export { WinkQueryAnalyzer, getQueryAnalyzer, createWinkQueryAnalyzer } from './nlp.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extras/extensions/keyword-extractor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/keyword-extractor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,+BAA+B,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACrF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC"}

package/dist/extras/extensions/keyword-extractor/index.js

@@ -0,0 +1,3 @@
+export { default as createKeywordExtractorExtension } from './extension.js';
+export { WinkQueryAnalyzer, getQueryAnalyzer, createWinkQueryAnalyzer } from './nlp.js';
+//# sourceMappingURL=index.js.map

package/dist/extras/extensions/keyword-extractor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/extras/extensions/keyword-extractor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,+BAA+B,EAAE,MAAM,gBAAgB,CAAC;AAG5E,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC"}

package/dist/extras/extensions/keyword-extractor/nlp.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The result of analyzing a user message for search terms.
+ */
+export interface SearchTerms {
+    /**
+     * Ordered, de-duplicated single-word search terms extracted from the
+     * input. Conversational filler, punctuation, and stop words are
+     * removed. Capitalization is preserved for proper nouns / technical
+     * terms (e.g. `TypeScript`, `AWS`, `MCP`); other terms are lowercased.
+     */
+    terms: string[];
+    /**
+     * Multi-word phrases (n-grams of length 2–3) built from consecutive
+     * retained terms that were adjacent in the original text. Longer
+     * phrases appear first. May be empty or undefined when no multi-word
+     * phrases were found.
+     */
+    phrases?: string[];
+}
+/**
+ * Analyzes conversational text and returns search terms.
+ *
+ * Implementations must be deterministic and safe to reuse across many
+ * turns of a long-running agent process (the NLP model should be
+ * initialized once, not per call).
+ */
+export interface QueryAnalyzer {
+    analyze(input: string): SearchTerms;
+}
+/**
+ * winkNLP-backed implementation of {@link QueryAnalyzer}.
+ *
+ * The winkNLP model is initialized exactly once (lazily on first use,
+ * then reused). This is safe for a long-running agent process —
+ * `analyze()` never re-instantiates the NLP engine.
+ *
+ * Extraction steps:
+ *  1. Tokenize the input.
+ *  2. Drop punctuation and non-word tokens.
+ *  3. Drop English stop words.
+ *  4. Keep tokens whose POS is a noun, proper noun, verb, or adjective.
+ *  5. Preserve the original surface form for proper nouns (so
+ *     `TypeScript`, `AWS`, `MCP`, `Kubernetes` keep their casing);
+ *     lowercase everything else via winkNLP's `normal` form.
+ *  6. De-duplicate while preserving first-occurrence order.
+ *  7. Build 2–3 word phrases from consecutive retained tokens that were
+ *     adjacent in the original text.
+ */
+export declare class WinkQueryAnalyzer implements QueryAnalyzer {
+    private nlp;
+    /** Lazily create the winkNLP engine exactly once. */
+    private engine;
+    analyze(input: string): SearchTerms;
+}
+/**
+ * Returns a process-wide shared {@link WinkQueryAnalyzer} instance.
+ * The NLP model is initialized lazily on first use and reused for all
+ * subsequent calls.
+ */
+export declare function getQueryAnalyzer(): QueryAnalyzer;
+/**
+ * Creates a fresh, independent {@link WinkQueryAnalyzer} instance.
+ *
+ * Prefer {@link getQueryAnalyzer} unless you specifically need an
+ * isolated instance (e.g. in tests that want to control initialization).
+ */
+export declare function createWinkQueryAnalyzer(): QueryAnalyzer;
+//# sourceMappingURL=nlp.d.ts.map

package/dist/extras/extensions/keyword-extractor/nlp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nlp.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/keyword-extractor/nlp.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;CACrC;AA4BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,GAAG,CAAyC;IAEpD,qDAAqD;IACrD,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAyClC;CACF;AAqDD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,aAAa,CAEvD"}

package/dist/extras/extensions/keyword-extractor/nlp.js

@@ -0,0 +1,156 @@
+import winkNLP from 'wink-nlp';
+import model from 'wink-eng-lite-web-model';
+/**
+ * Part-of-speech tags worth retaining as search terms.
+ *
+ * Prioritizes nouns, proper nouns, and meaningful verbs/adjectives.
+ * Stop words, punctuation, pronouns, determiners, conjunctions, etc.
+ * are dropped (either via the stop-word flag or by not being in this
+ * set).
+ */
+const RETAINED_POS = new Set([
+    'NOUN',
+    'PROPN',
+    'VERB',
+    'ADJ',
+]);
+/**
+ * winkNLP-backed implementation of {@link QueryAnalyzer}.
+ *
+ * The winkNLP model is initialized exactly once (lazily on first use,
+ * then reused). This is safe for a long-running agent process —
+ * `analyze()` never re-instantiates the NLP engine.
+ *
+ * Extraction steps:
+ *  1. Tokenize the input.
+ *  2. Drop punctuation and non-word tokens.
+ *  3. Drop English stop words.
+ *  4. Keep tokens whose POS is a noun, proper noun, verb, or adjective.
+ *  5. Preserve the original surface form for proper nouns (so
+ *     `TypeScript`, `AWS`, `MCP`, `Kubernetes` keep their casing);
+ *     lowercase everything else via winkNLP's `normal` form.
+ *  6. De-duplicate while preserving first-occurrence order.
+ *  7. Build 2–3 word phrases from consecutive retained tokens that were
+ *     adjacent in the original text.
+ */
+export class WinkQueryAnalyzer {
+    nlp;
+    /** Lazily create the winkNLP engine exactly once. */
+    engine() {
+        if (!this.nlp) {
+            // `as any` because winkNLP's types declare the model shape as
+            // `unknown` internally; the runtime model object is compatible.
+            this.nlp = winkNLP(model);
+        }
+        return this.nlp;
+    }
+    analyze(input) {
+        const trimmed = input?.trim() ?? '';
+        if (trimmed === '')
+            return { terms: [], phrases: [] };
+        const nlp = this.engine();
+        const doc = nlp.readDoc(trimmed);
+        const values = doc.tokens().out();
+        const types = doc.tokens().out(nlp.its.type);
+        const pos = doc.tokens().out(nlp.its.pos);
+        const stop = doc.tokens().out(nlp.its.stopWordFlag);
+        const normal = doc.tokens().out(nlp.its.normal);
+        const retained = [];
+        const seen = new Set();
+        for (let i = 0; i < values.length; i++) {
+            // Drop punctuation and non-word tokens.
+            if (types[i] !== 'word')
+                continue;
+            // Drop stop words.
+            if (stop[i])
+                continue;
+            // Keep only meaningful POS.
+            if (!RETAINED_POS.has(pos[i]))
+                continue;
+            // Preserve casing for proper nouns (TypeScript, AWS, MCP,
+            // Kubernetes, Terraform, API, …). Lowercase everything else via
+            // the `normal` form, which also normalizes simple grammatical
+            // variants (case, contractions).
+            const term = pos[i] === 'PROPN' ? values[i] : normal[i];
+            if (term === '')
+                continue;
+            // De-duplicate while preserving first-occurrence order.
+            if (seen.has(term))
+                continue;
+            seen.add(term);
+            retained.push({ term, index: i });
+        }
+        const terms = retained.map((t) => t.term);
+        const phrases = extractPhrases(retained);
+        return { terms, phrases };
+    }
+}
+/**
+ * Build 2–3 word phrases from consecutive retained tokens that were
+ * adjacent in the original document (token indices differ by exactly 1).
+ *
+ * Longer phrases (trigrams) are emitted before shorter ones (bigrams),
+ * and all phrases are de-duplicated while preserving first-occurrence
+ * order within each size.
+ */
+function extractPhrases(retained) {
+    // Group retained tokens into runs of document-adjacent tokens.
+    const runs = [];
+    let current = [];
+    for (const tok of retained) {
+        const prev = current[current.length - 1];
+        if (prev && tok.index === prev.index + 1) {
+            current.push(tok);
+        }
+        else {
+            if (current.length >= 2)
+                runs.push(current);
+            current = [tok];
+        }
+    }
+    if (current.length >= 2)
+        runs.push(current);
+    const phrases = [];
+    const seen = new Set();
+    // Trigrams first, then bigrams.
+    for (const size of [3, 2]) {
+        for (const run of runs) {
+            for (let i = 0; i + size <= run.length; i++) {
+                const phrase = run.slice(i, i + size).map((t) => t.term).join(' ');
+                if (!seen.has(phrase)) {
+                    seen.add(phrase);
+                    phrases.push(phrase);
+                }
+            }
+        }
+    }
+    return phrases;
+}
+/**
+ * Shared singleton analyzer instance.
+ *
+ * The winkNLP model is heavy to load; reuse one instance across the
+ * whole process. Call {@link createWinkQueryAnalyzer} to get a new
+ * independent instance if needed (rare).
+ */
+let shared;
+/**
+ * Returns a process-wide shared {@link WinkQueryAnalyzer} instance.
+ * The NLP model is initialized lazily on first use and reused for all
+ * subsequent calls.
+ */
+export function getQueryAnalyzer() {
+    if (!shared)
+        shared = new WinkQueryAnalyzer();
+    return shared;
+}
+/**
+ * Creates a fresh, independent {@link WinkQueryAnalyzer} instance.
+ *
+ * Prefer {@link getQueryAnalyzer} unless you specifically need an
+ * isolated instance (e.g. in tests that want to control initialization).
+ */
+export function createWinkQueryAnalyzer() {
+    return new WinkQueryAnalyzer();
+}
+//# sourceMappingURL=nlp.js.map

package/dist/extras/extensions/keyword-extractor/nlp.js.map

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

package/dist/extras/extensions/keyword-extractor/nlp.test.d.ts

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

package/dist/extras/extensions/keyword-extractor/nlp.test.d.ts.map

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

package/dist/extras/extensions/keyword-extractor/nlp.test.js

@@ -0,0 +1,176 @@
+import { describe, it, expect } from 'vitest';
+import { createWinkQueryAnalyzer } from './index.js';
+// Use a fresh analyzer instance for the suite so initialization is
+// controlled and independent of any process-wide singleton.
+const analyzer = createWinkQueryAnalyzer();
+describe('WinkQueryAnalyzer', () => {
+    // ── Normal conversational sentence ──────────────────────────────
+    it('extracts terms from a normal conversational sentence', () => {
+        const out = analyzer.analyze("Can you find the documentation for the TypeScript library we're using to build nested knowledge graphs?");
+        expect(out.terms).toEqual([
+            'find',
+            'documentation',
+            'TypeScript',
+            'library',
+            'build',
+            'nested',
+            'knowledge',
+            'graphs',
+        ]);
+        // Trigram first, then bigrams.
+        expect(out.phrases).toEqual([
+            'build nested knowledge',
+            'nested knowledge graphs',
+            'TypeScript library',
+            'build nested',
+            'nested knowledge',
+            'knowledge graphs',
+        ]);
+    });
+    // ── Heavy conversational filler ─────────────────────────────────
+    it('drops conversational filler and keeps meaningful terms', () => {
+        const out = analyzer.analyze('Hey, could you please look through our documentation and find the thing we discussed yesterday about MCP authentication?');
+        // Filler (hey, could, you, please, through, our, and, the, we,
+        // yesterday, about) is gone. "look" is a real verb and is retained.
+        expect(out.terms).toEqual([
+            'look',
+            'documentation',
+            'find',
+            'thing',
+            'discussed',
+            'MCP',
+            'authentication',
+        ]);
+        expect(out.phrases).toEqual(['MCP authentication']);
+    });
+    // ── Technical terms ─────────────────────────────────────────────
+    it('preserves technical/proper-noun terms with their casing', () => {
+        const out = analyzer.analyze('AWS Kubernetes Terraform API MCP JavaScript');
+        expect(out.terms).toEqual([
+            'AWS',
+            'Kubernetes',
+            'Terraform',
+            'API',
+            'MCP',
+            'JavaScript',
+        ]);
+    });
+    // ── Acronyms ────────────────────────────────────────────────────
+    it('preserves acronyms as proper nouns', () => {
+        const out = analyzer.analyze('What is the MCP?');
+        expect(out.terms).toEqual(['MCP']);
+        expect(out.phrases).toEqual([]);
+    });
+    // ── Duplicate words ─────────────────────────────────────────────
+    it('removes duplicate terms (same casing)', () => {
+        const out = analyzer.analyze('MCP, MCP, MCP');
+        expect(out.terms).toEqual(['MCP']);
+    });
+    it('removes duplicate non-stopwords across a sentence', () => {
+        const out = analyzer.analyze('find the documentation, find the thing!');
+        expect(out.terms).toEqual(['find', 'documentation', 'thing']);
+    });
+    // ── Punctuation ─────────────────────────────────────────────────
+    it('strips punctuation and keeps only word tokens', () => {
+        const out = analyzer.analyze('Hello, world!!! How are you doing today?');
+        // "Hello" (INTJ) and "today" (ADV) are dropped by the POS filter;
+        // punctuation is dropped by the word-type filter.
+        expect(out.terms).toEqual(['world']);
+        expect(out.phrases).toEqual([]);
+    });
+    // ── Empty string ────────────────────────────────────────────────
+    it('returns empty terms for an empty string', () => {
+        const out = analyzer.analyze('');
+        expect(out.terms).toEqual([]);
+        expect(out.phrases).toEqual([]);
+    });
+    it('returns empty terms for whitespace-only input', () => {
+        const out = analyzer.analyze('   ');
+        expect(out.terms).toEqual([]);
+        expect(out.phrases).toEqual([]);
+    });
+    it('returns empty terms for nullish input', () => {
+        const out = analyzer.analyze(undefined);
+        expect(out.terms).toEqual([]);
+        expect(out.phrases).toEqual([]);
+    });
+    // ── Very short input ────────────────────────────────────────────
+    it('handles very short input (single filler word)', () => {
+        const out = analyzer.analyze('Hi');
+        // "Hi" is an interjection — dropped by the POS filter.
+        expect(out.terms).toEqual([]);
+    });
+    it('handles very short input (single stop-word-only phrase)', () => {
+        const out = analyzer.analyze('the and of');
+        expect(out.terms).toEqual([]);
+    });
+    // ── A question ──────────────────────────────────────────────────
+    it('extracts terms from a question about agent memory', () => {
+        const out = analyzer.analyze('Where did we decide to store agent memory?');
+        expect(out.terms).toEqual(['decide', 'store', 'agent', 'memory']);
+        expect(out.phrases).toEqual([
+            'store agent memory',
+            'store agent',
+            'agent memory',
+        ]);
+    });
+    // ── Multi-word technical concepts ───────────────────────────────
+    it('extracts multi-word technical concepts as phrases', () => {
+        const out = analyzer.analyze('Can you find our documentation about the MCP server architecture?');
+        expect(out.terms).toEqual([
+            'find',
+            'documentation',
+            'MCP',
+            'server',
+            'architecture',
+        ]);
+        expect(out.phrases).toEqual([
+            'MCP server architecture',
+            'MCP server',
+            'server architecture',
+        ]);
+    });
+    it('extracts phrases from "nested knowledge graph"', () => {
+        const out = analyzer.analyze('nested knowledge graph');
+        expect(out.terms).toEqual(['nested', 'knowledge', 'graph']);
+        expect(out.phrases).toEqual([
+            'nested knowledge graph',
+            'nested knowledge',
+            'knowledge graph',
+        ]);
+    });
+    // ── Mixed casing ────────────────────────────────────────────────
+    it('treats different surface casings of a proper noun as distinct terms', () => {
+        // winkNLP tags "typescript" (lowercase) as a proper noun too, so
+        // each surface form is preserved verbatim and not collapsed.
+        const out = analyzer.analyze('TypeScript typescript TYPESCRIPT');
+        expect(out.terms).toEqual(['TypeScript', 'typescript', 'TYPESCRIPT']);
+    });
+    // ── Determinism ─────────────────────────────────────────────────
+    it('is deterministic — same input yields same output across calls', () => {
+        const input = 'Can you find our documentation about the MCP server architecture?';
+        const a = analyzer.analyze(input);
+        const b = analyzer.analyze(input);
+        expect(b).toEqual(a);
+    });
+    it('is safe to reuse repeatedly (long-running process)', () => {
+        const analyzer2 = createWinkQueryAnalyzer();
+        const samples = [
+            'Find the MCP documentation',
+            'Where did we store agent memory?',
+            'AWS Kubernetes Terraform',
+            '',
+            'nested knowledge graph',
+        ];
+        // Run many times — should never throw and stay deterministic.
+        for (let i = 0; i < 50; i++) {
+            for (const s of samples) {
+                const out = analyzer2.analyze(s);
+                expect(Array.isArray(out.terms)).toBe(true);
+            }
+        }
+        // Final call matches a fresh call on another instance.
+        expect(analyzer2.analyze('nested knowledge graph')).toEqual(analyzer.analyze('nested knowledge graph'));
+    });
+});
+//# sourceMappingURL=nlp.test.js.map

package/dist/extras/extensions/keyword-extractor/nlp.test.js.map

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

package/dist/extras/extensions/logger/extension.d.ts

@@ -0,0 +1,52 @@
+import type { Extension } from '../../../extension.js';
+/**
+ * Log level for the logging extension.
+ *
+ * - `'info'` — turn start/finish, errors (high-level lifecycle)
+ * - `'debug'` — per-LLM-call and per-tool-call details (verbose)
+ */
+export type LogLevel = 'info' | 'debug';
+/**
+ * Config for the logging extension.
+ *
+ * Passed by the extension loader from the host's config object.
+ * Keys should be declared in extension.json's `configKeys`.
+ */
+export interface LoggingExtensionConfig {
+    /**
+     * Custom log function. Default: `console.log`.
+     * Useful for routing logs to a file, transport, or structured logger.
+     */
+    logFunction?: (...args: unknown[]) => void;
+    /**
+     * Custom error function. Default: `console.error`.
+     */
+    errorFunction?: (...args: unknown[]) => void;
+    /**
+     * Prefix for log lines. Default: `"[logging]"`.
+     */
+    logPrefix?: string;
+    /**
+     * Minimum log level to emit. Default: `'info'`.
+     *
+     * Set to `'debug'` to see per-LLM-call and per-tool-call details.
+     * If the `DEBUG` environment variable is set, defaults to `'debug'`.
+     */
+    level?: LogLevel;
+}
+/**
+ * Logging extension — logs each lifecycle stage.
+ *
+ * Observes every hook stage (beforeTurn, beforeLLM, afterLLM, beforeTool,
+ * afterTool, onError, afterTurn) without mutating anything. Accepts
+ * optional config for custom log/error functions, a prefix, and a log level.
+ *
+ * Log levels:
+ * - **info** (default): turn start/finish, errors
+ * - **debug**: per-LLM-call and per-tool-call details
+ *
+ * If the `DEBUG` environment variable is set and no explicit `level` is
+ * provided, the level defaults to `'debug'`.
+ */
+export default function createLoggingExtension(config?: LoggingExtensionConfig): Extension;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extras/extensions/logger/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/logger/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvD;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAExC;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC3C;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC7C;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAID;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,sBAAsB,CAC5C,MAAM,CAAC,EAAE,sBAAsB,GAC9B,SAAS,CAgDX"}