@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/context/dist/wiki/tools/wiki-search.tool.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { BaseTool, type ToolContext, type ToolOutput } from '../../tools/index.js';
+import type { WikiSearchLaneSummary, WikiSearchMatchReason } from '../types.js';
+declare const WikiSearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+type WikiSearchInput = z.infer<typeof WikiSearchInputSchema>;
+interface WikiSearchResult {
+    blockKey: string;
+    path: string;
+    summary: string;
+    score: number;
+    matchReasons?: WikiSearchMatchReason[];
+    lanes?: WikiSearchLaneSummary[];
+}
+interface WikiSearchStructured {
+    results: WikiSearchResult[];
+    totalFound: number;
+}
+export interface WikiSearchAdapterPort {
+    search(input: {
+        userId: string;
+        query: string;
+        limit: number;
+    }): Promise<{
+        results: Array<{
+            key: string;
+            path: string;
+            summary: string;
+            score: number;
+            matchReasons?: WikiSearchMatchReason[];
+            lanes?: WikiSearchLaneSummary[];
+        }>;
+        totalFound: number;
+    }>;
+}
+export declare class WikiSearchTool extends BaseTool<typeof WikiSearchInputSchema> {
+    private readonly searchAdapter;
+    readonly name = "wiki_search";
+    constructor(searchAdapter: WikiSearchAdapterPort);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        query: z.ZodString;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>;
+    call(input: WikiSearchInput, context: ToolContext): Promise<ToolOutput<WikiSearchStructured>>;
+}
+export {};

package/node_modules/@ktx/context/dist/wiki/tools/wiki-search.tool.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { BaseTool } from '../../tools/index.js';
+const WikiSearchInputSchema = z.object({
+    query: z.string().describe('Natural language search query to find relevant knowledge blocks.'),
+    limit: z.number().optional().default(10).describe('Maximum number of results to return (default 10).'),
+});
+export class WikiSearchTool extends BaseTool {
+    searchAdapter;
+    name = 'wiki_search';
+    constructor(searchAdapter) {
+        super();
+        this.searchAdapter = searchAdapter;
+    }
+    get description() {
+        return ('Search knowledge blocks by hybrid lexical, semantic, and token matching. ' +
+            'Use this when you need to find knowledge on a topic not visible in the discovery index. ' +
+            'Returns ranked summaries — use wiki_read to load the full content of specific results.');
+    }
+    get inputSchema() {
+        return WikiSearchInputSchema;
+    }
+    async call(input, context) {
+        const response = await this.searchAdapter.search({
+            userId: context.userId,
+            query: input.query,
+            limit: input.limit,
+        });
+        if (response.results.length === 0) {
+            return {
+                markdown: `No knowledge blocks found matching "${input.query}".`,
+                structured: { results: [], totalFound: 0 },
+            };
+        }
+        const lines = response.results.map((r, i) => `${i + 1}. **${r.key}**: ${r.summary}`);
+        const structured = {
+            results: response.results.map((r) => ({
+                blockKey: r.key,
+                path: r.path,
+                summary: r.summary,
+                score: r.score,
+                matchReasons: r.matchReasons,
+                lanes: r.lanes,
+            })),
+            totalFound: response.totalFound,
+        };
+        return {
+            markdown: `Found ${response.results.length} knowledge block(s):\n\n${lines.join('\n')}`,
+            structured,
+        };
+    }
+}

package/node_modules/@ktx/context/dist/wiki/tools/wiki-search.tool.test.d.ts

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

package/node_modules/@ktx/context/dist/wiki/tools/wiki-search.tool.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from 'vitest';
+import { WikiSearchTool } from './wiki-search.tool.js';
+describe('WikiSearchTool', () => {
+    it('searches through the injected wiki adapter port', async () => {
+        const search = vi.fn(async () => ({
+            results: [
+                {
+                    key: 'metrics/revenue',
+                    path: 'knowledge/global/metrics/revenue.md',
+                    scope: 'GLOBAL',
+                    summary: 'Revenue metric definition',
+                    score: 0.02459016393442623,
+                    matchReasons: ['lexical', 'token'],
+                },
+            ],
+            totalFound: 1,
+        }));
+        const tool = new WikiSearchTool({ search });
+        const result = await tool.call({ query: 'paid order', limit: 5 }, { sourceId: 'test', messageId: 'message-1', userId: 'agent' });
+        expect(search).toHaveBeenCalledWith({ userId: 'agent', query: 'paid order', limit: 5 });
+        expect(result.structured).toEqual({
+            results: [
+                {
+                    blockKey: 'metrics/revenue',
+                    path: 'knowledge/global/metrics/revenue.md',
+                    summary: 'Revenue metric definition',
+                    score: 0.02459016393442623,
+                    matchReasons: ['lexical', 'token'],
+                },
+            ],
+            totalFound: 1,
+        });
+        expect(result.markdown).toContain('**metrics/revenue**');
+    });
+});

package/node_modules/@ktx/context/dist/wiki/tools/wiki-write.tool.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import type { KnowledgeIndexPort } from '../ports.js';
+import type { KnowledgeEventPort } from '../ports.js';
+import { KnowledgeWikiService } from '../index.js';
+import { BaseTool, type ToolContext, type ToolOutput } from '../../tools/index.js';
+declare const wikiWriteInputSchema: z.ZodObject<{
+    key: z.ZodString;
+    summary: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+    replacements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        oldText: z.ZodString;
+        newText: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sl_refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    source: z.ZodOptional<z.ZodString>;
+    intent: z.ZodOptional<z.ZodString>;
+    tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    representative_sql: z.ZodOptional<z.ZodString>;
+    usage: z.ZodOptional<z.ZodObject<{
+        executions: z.ZodNumber;
+        distinct_users: z.ZodNumber;
+        first_seen: z.ZodString;
+        last_seen: z.ZodString;
+        p50_runtime_ms: z.ZodNullable<z.ZodNumber>;
+        p95_runtime_ms: z.ZodNullable<z.ZodNumber>;
+        error_rate: z.ZodNumber;
+        rows_produced: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    fingerprints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type WikiWriteInput = z.infer<typeof wikiWriteInputSchema>;
+interface WikiWriteStructured {
+    success: boolean;
+    key: string;
+    action?: 'created' | 'updated';
+}
+export declare class WikiWriteTool extends BaseTool<typeof wikiWriteInputSchema> {
+    private readonly wikiService;
+    private readonly pagesRepository;
+    private readonly knowledgeRepository;
+    readonly name = "wiki_write";
+    constructor(wikiService: KnowledgeWikiService, pagesRepository: KnowledgeIndexPort, knowledgeRepository: KnowledgeEventPort);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        key: z.ZodString;
+        summary: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+        replacements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            oldText: z.ZodString;
+            newText: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sl_refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        source: z.ZodOptional<z.ZodString>;
+        intent: z.ZodOptional<z.ZodString>;
+        tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        representative_sql: z.ZodOptional<z.ZodString>;
+        usage: z.ZodOptional<z.ZodObject<{
+            executions: z.ZodNumber;
+            distinct_users: z.ZodNumber;
+            first_seen: z.ZodString;
+            last_seen: z.ZodString;
+            p50_runtime_ms: z.ZodNullable<z.ZodNumber>;
+            p95_runtime_ms: z.ZodNullable<z.ZodNumber>;
+            error_rate: z.ZodNumber;
+            rows_produced: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        fingerprints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    call(input: WikiWriteInput, context: ToolContext): Promise<ToolOutput<WikiWriteStructured>>;
+}
+export {};

package/node_modules/@ktx/context/dist/wiki/tools/wiki-write.tool.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { applySqlEdits } from '../../tools/sql-edit-replacer.js';
+import { BaseTool } from '../../tools/index.js';
+const MAX_USER_BLOCKS = 100;
+const SYSTEM_AUTHOR = 'System User';
+const SYSTEM_EMAIL = 'system@example.com';
+const historicSqlUsageFrontmatterSchema = z.object({
+    executions: z.number().int().nonnegative(),
+    distinct_users: z.number().int().nonnegative(),
+    first_seen: z.string().min(1),
+    last_seen: z.string().min(1),
+    p50_runtime_ms: z.number().nonnegative().nullable(),
+    p95_runtime_ms: z.number().nonnegative().nullable(),
+    error_rate: z.number().min(0).max(1),
+    rows_produced: z.number().int().nonnegative().optional(),
+});
+const wikiWriteInputSchema = z.object({
+    key: z.string().max(120),
+    summary: z.string().max(200),
+    content: z.string().max(4000).optional(),
+    replacements: z
+        .array(z.object({ oldText: z.string(), newText: z.string(), reason: z.string().optional() }))
+        .optional(),
+    tags: z.array(z.string()).optional(),
+    refs: z.array(z.string()).optional(),
+    sl_refs: z.array(z.string()).optional(),
+    source: z.string().optional(),
+    intent: z.string().optional(),
+    tables: z.array(z.string()).optional(),
+    representative_sql: z.string().optional(),
+    usage: historicSqlUsageFrontmatterSchema.optional(),
+    fingerprints: z.array(z.string()).optional(),
+});
+export class WikiWriteTool extends BaseTool {
+    wikiService;
+    pagesRepository;
+    knowledgeRepository;
+    name = 'wiki_write';
+    constructor(wikiService, pagesRepository, knowledgeRepository) {
+        super();
+        this.wikiService = wikiService;
+        this.pagesRepository = pagesRepository;
+        this.knowledgeRepository = knowledgeRepository;
+    }
+    get description() {
+        return `<purpose>
+Create or update a knowledge page. Provide content for create/rewrite, or replacements for targeted edits.
+tags/refs/sl_refs use REPLACE semantics: omit to keep existing on update, [] to clear, [values] to set.
+</purpose>`;
+    }
+    get inputSchema() {
+        return wikiWriteInputSchema;
+    }
+    async call(input, context) {
+        const wikiService = context.session?.wikiService ?? this.wikiService;
+        const writesGlobal = !!context.session;
+        const skipIndex = context.session?.isWorktreeScoped === true;
+        if (!input.content && (!input.replacements || input.replacements.length === 0)) {
+            return {
+                markdown: 'Error: provide either content (for create/rewrite) or replacements (for edits).',
+                structured: { success: false, key: input.key },
+            };
+        }
+        const scope = writesGlobal ? 'GLOBAL' : 'USER';
+        const scopeId = scope === 'USER' ? context.userId : null;
+        const existing = await wikiService.readPage(scope, scopeId, input.key);
+        if (!existing && !input.content) {
+            return {
+                markdown: `Page "${input.key}" does not exist. Provide content to create it.`,
+                structured: { success: false, key: input.key },
+            };
+        }
+        if (scope === 'USER' && !existing) {
+            const count = await this.pagesRepository.getUserPageCount(context.userId);
+            if (count >= MAX_USER_BLOCKS) {
+                return {
+                    markdown: `Cannot create "${input.key}": user has reached the limit of ${MAX_USER_BLOCKS} pages.`,
+                    structured: { success: false, key: input.key },
+                };
+            }
+        }
+        const existingFm = existing?.frontmatter;
+        const resolvedTags = input.tags === undefined ? existingFm?.tags : input.tags;
+        const resolvedRefs = input.refs === undefined ? existingFm?.refs : input.refs;
+        const resolvedSlRefs = input.sl_refs === undefined ? existingFm?.sl_refs : input.sl_refs;
+        let finalContent;
+        const finalFm = {
+            summary: input.summary,
+            usage_mode: existingFm?.usage_mode ?? 'auto',
+            sort_order: existingFm?.sort_order ?? 0,
+            tags: resolvedTags,
+            refs: resolvedRefs,
+            sl_refs: resolvedSlRefs,
+            source: input.source === undefined ? existingFm?.source : input.source,
+            intent: input.intent === undefined ? existingFm?.intent : input.intent,
+            tables: input.tables === undefined ? existingFm?.tables : input.tables,
+            representative_sql: input.representative_sql === undefined ? existingFm?.representative_sql : input.representative_sql,
+            usage: input.usage === undefined ? existingFm?.usage : input.usage,
+            fingerprints: input.fingerprints === undefined ? existingFm?.fingerprints : input.fingerprints,
+        };
+        if (input.content) {
+            finalContent = input.content;
+        }
+        else {
+            const editResult = applySqlEdits(existing?.content ?? '', input.replacements ?? []);
+            if (!editResult.success) {
+                return {
+                    markdown: `Edit errors: ${editResult.errors.join('; ')}`,
+                    structured: { success: false, key: input.key },
+                };
+            }
+            finalContent = editResult.sql;
+        }
+        await wikiService.writePage(scope, scopeId, input.key, finalFm, finalContent, SYSTEM_AUTHOR, SYSTEM_EMAIL);
+        if (!skipIndex) {
+            await wikiService.syncSinglePage(scope, scopeId, input.key, finalFm, finalContent);
+        }
+        await this.knowledgeRepository.createEvent({
+            blockId: null,
+            eventType: existing ? 'BLOCK_UPDATED' : 'BLOCK_CREATED',
+            actorId: context.userId,
+            chatId: null,
+            messageId: null,
+            payload: {
+                pageKey: input.key,
+                previousContent: existing ? existing.content.slice(0, 500) : null,
+            },
+        });
+        const action = existing ? 'updated' : 'created';
+        if (context.session) {
+            context.session.actions.push({ target: 'wiki', type: action, key: input.key, detail: input.summary });
+        }
+        return {
+            markdown: `Page "${input.key}" ${action}.`,
+            structured: { success: true, key: input.key, action },
+        };
+    }
+}

package/node_modules/@ktx/context/dist/wiki/tools/wiki-write.tool.test.d.ts

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

package/node_modules/@ktx/context/dist/wiki/tools/wiki-write.tool.test.js

@@ -0,0 +1,147 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTouchedSlSources } from '../../tools/index.js';
+import { WikiWriteTool } from './wiki-write.tool.js';
+function makeTool(overrides = {}) {
+    const wikiService = {
+        readPage: vi.fn().mockResolvedValue(null),
+        writePage: vi.fn().mockResolvedValue(undefined),
+        syncSinglePage: vi.fn().mockResolvedValue(undefined),
+        ...overrides.wikiService,
+    };
+    const pagesRepository = {
+        findPageByKey: vi.fn().mockResolvedValue(null),
+        getUserPageCount: vi.fn().mockResolvedValue(0),
+        ...overrides.pagesRepository,
+    };
+    const knowledgeRepository = {
+        createEvent: vi.fn().mockResolvedValue(undefined),
+        ...overrides.knowledgeRepository,
+    };
+    const tool = new WikiWriteTool(wikiService, pagesRepository, knowledgeRepository);
+    return { tool, wikiService, pagesRepository, knowledgeRepository };
+}
+describe('WikiWriteTool', () => {
+    const baseContext = { sourceId: 's', messageId: 'm', userId: 'u' };
+    it('creates a new page and indexes it when no session is present', async () => {
+        const { tool, wikiService } = makeTool();
+        const result = await tool.call({ key: 'leads-source', summary: 'Lead source definitions', content: '# Leads' }, baseContext);
+        expect(wikiService.writePage).toHaveBeenCalledTimes(1);
+        expect(wikiService.syncSinglePage).toHaveBeenCalledTimes(1);
+        expect(result.markdown).toMatch(/created/i);
+    });
+    it('skips syncSinglePage when session is worktree-scoped', async () => {
+        const { tool, wikiService } = makeTool();
+        const session = {
+            connectionId: 'conn-1',
+            isWorktreeScoped: true,
+            preHead: null,
+            touchedSlSources: createTouchedSlSources(),
+            actions: [],
+            semanticLayerService: {},
+            wikiService: wikiService,
+            configService: {},
+            gitService: {},
+        };
+        const context = { ...baseContext, session };
+        await tool.call({ key: 'k', summary: 's', content: '# x' }, context);
+        expect(wikiService.writePage).toHaveBeenCalledTimes(1);
+        expect(wikiService.syncSinglePage).not.toHaveBeenCalled();
+        expect(session.actions).toContainEqual(expect.objectContaining({ target: 'wiki', type: 'created', key: 'k' }));
+    });
+    it('requires either content or replacements', async () => {
+        const { tool } = makeTool();
+        const result = await tool.call({ key: 'k', summary: 's' }, baseContext);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toMatch(/content.*or.*replacements/i);
+    });
+    it('writes historic-SQL frontmatter fields', async () => {
+        const { tool, wikiService } = makeTool();
+        await tool.call({
+            key: 'queries/monthly-paid-orders',
+            summary: 'Monthly paid orders',
+            tags: ['historic-sql', 'query-pattern'],
+            sl_refs: ['analytics.orders'],
+            source: 'historic-sql',
+            intent: 'Monthly paid order count',
+            tables: ['analytics.orders'],
+            representative_sql: "SELECT count(*) FROM analytics.orders WHERE status = 'paid'",
+            usage: {
+                executions: 42,
+                distinct_users: 3,
+                first_seen: '2026-02-01',
+                last_seen: '2026-05-04',
+                p50_runtime_ms: 100,
+                p95_runtime_ms: 200,
+                error_rate: 0,
+                rows_produced: 42,
+            },
+            fingerprints: ['fp_paid_orders'],
+            content: '## Monthly paid order count',
+        }, baseContext);
+        expect(wikiService.writePage.mock.calls[0][3]).toEqual({
+            summary: 'Monthly paid orders',
+            usage_mode: 'auto',
+            sort_order: 0,
+            tags: ['historic-sql', 'query-pattern'],
+            refs: undefined,
+            sl_refs: ['analytics.orders'],
+            source: 'historic-sql',
+            intent: 'Monthly paid order count',
+            tables: ['analytics.orders'],
+            representative_sql: "SELECT count(*) FROM analytics.orders WHERE status = 'paid'",
+            usage: {
+                executions: 42,
+                distinct_users: 3,
+                first_seen: '2026-02-01',
+                last_seen: '2026-05-04',
+                p50_runtime_ms: 100,
+                p95_runtime_ms: 200,
+                error_rate: 0,
+                rows_produced: 42,
+            },
+            fingerprints: ['fp_paid_orders'],
+        });
+    });
+    it('preserves historic-SQL frontmatter fields when update omits them', async () => {
+        const existingFrontmatter = {
+            summary: 'Monthly paid orders',
+            usage_mode: 'auto',
+            sort_order: 0,
+            tags: ['historic-sql'],
+            sl_refs: ['analytics.orders'],
+            source: 'historic-sql',
+            intent: 'Monthly paid order count',
+            tables: ['analytics.orders'],
+            representative_sql: "SELECT count(*) FROM analytics.orders WHERE status = 'paid'",
+            usage: {
+                executions: 42,
+                distinct_users: 3,
+                first_seen: '2026-02-01',
+                last_seen: '2026-05-04',
+                p50_runtime_ms: 100,
+                p95_runtime_ms: 200,
+                error_rate: 0,
+                rows_produced: 42,
+            },
+            fingerprints: ['fp_paid_orders'],
+        };
+        const { tool, wikiService } = makeTool({
+            wikiService: {
+                readPage: vi.fn().mockResolvedValue({
+                    pageKey: 'queries/monthly-paid-orders',
+                    frontmatter: existingFrontmatter,
+                    content: 'old body',
+                }),
+            },
+        });
+        await tool.call({
+            key: 'queries/monthly-paid-orders',
+            summary: 'Monthly paid orders updated',
+            content: '## Monthly paid order count updated',
+        }, baseContext);
+        expect(wikiService.writePage.mock.calls[0][3]).toEqual({
+            ...existingFrontmatter,
+            summary: 'Monthly paid orders updated',
+        });
+    });
+});

package/node_modules/@ktx/context/dist/wiki/types.d.ts

@@ -0,0 +1,48 @@
+export type WikiScope = 'GLOBAL' | 'USER';
+export interface HistoricSqlWikiUsageFrontmatter {
+    executions: number;
+    distinct_users: number;
+    first_seen: string;
+    last_seen: string;
+    p50_runtime_ms: number | null;
+    p95_runtime_ms: number | null;
+    error_rate: number;
+    rows_produced?: number;
+}
+export interface WikiFrontmatter {
+    summary: string;
+    tags?: string[];
+    refs?: string[];
+    sl_refs?: string[];
+    usage_mode: 'always' | 'auto' | 'never';
+    sort_order?: number;
+    source?: string;
+    intent?: string;
+    tables?: string[];
+    representative_sql?: string;
+    usage?: HistoricSqlWikiUsageFrontmatter;
+    fingerprints?: string[];
+}
+export interface WikiPage {
+    pageKey: string;
+    frontmatter: WikiFrontmatter;
+    content: string;
+}
+export interface WikiPageWithScope extends WikiPage {
+    scope: WikiScope;
+}
+export type WikiSearchMatchReason = 'lexical' | 'semantic' | 'token' | (string & {});
+export interface WikiSearchLaneSummary {
+    lane: string;
+    status: 'available' | 'skipped' | 'failed';
+    requestedCandidatePoolLimit: number;
+    effectiveCandidatePoolLimit: number;
+    returnedCandidateCount: number;
+    weight: number;
+    reason?: string;
+}
+export interface WikiSearchMetadata {
+    score: number;
+    matchReasons: WikiSearchMatchReason[];
+    lanes?: WikiSearchLaneSummary[];
+}

package/node_modules/@ktx/context/dist/wiki/types.js

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