@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/context/dist/sql-analysis/http-sql-analysis-port.js

@@ -0,0 +1,125 @@
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+function normalizedBaseUrl(baseUrl) {
+    return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+}
+function parseJsonObject(raw, path) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`sql analysis HTTP ${path} returned non-object JSON`);
+    }
+    return parsed;
+}
+function postJson(baseUrl) {
+    return async (path, payload) => new Promise((resolve, reject) => {
+        const target = new URL(path.replace(/^\//, ''), normalizedBaseUrl(baseUrl));
+        const body = JSON.stringify(payload);
+        const client = target.protocol === 'https:' ? httpsRequest : httpRequest;
+        const request = client(target, {
+            method: 'POST',
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/json',
+                'content-length': Buffer.byteLength(body),
+            },
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => chunks.push(chunk));
+            response.on('end', () => {
+                const text = Buffer.concat(chunks).toString('utf8');
+                const statusCode = response.statusCode ?? 0;
+                if (statusCode < 200 || statusCode >= 300) {
+                    reject(new Error(`sql analysis HTTP ${path} failed with ${statusCode}: ${text}`));
+                    return;
+                }
+                try {
+                    resolve(parseJsonObject(text, path));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        request.on('error', reject);
+        request.end(body);
+    });
+}
+function requiredString(raw, field) {
+    const value = raw[field];
+    if (typeof value !== 'string') {
+        throw new Error(`sql analysis response is missing string field ${field}`);
+    }
+    return value;
+}
+function optionalString(raw, field) {
+    const value = raw[field];
+    if (value === null || value === undefined || typeof value === 'string') {
+        return value;
+    }
+    throw new Error(`sql analysis response has invalid optional string field ${field}`);
+}
+function requiredStringArray(raw, field) {
+    const value = raw[field];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(`sql analysis response is missing string[] field ${field}`);
+    }
+    return value;
+}
+function isLiteralSlotType(value) {
+    return (value === 'string' ||
+        value === 'number' ||
+        value === 'timestamp' ||
+        value === 'date' ||
+        value === 'boolean' ||
+        value === 'null' ||
+        value === 'unknown');
+}
+function literalSlots(raw) {
+    const value = raw.literal_slots;
+    if (!Array.isArray(value)) {
+        throw new Error('sql analysis response is missing literal_slots array');
+    }
+    return value.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            throw new Error('sql analysis response contains invalid literal slot');
+        }
+        const slot = item;
+        if (typeof slot.position !== 'number') {
+            throw new Error('sql analysis response literal slot is missing numeric position');
+        }
+        if (!isLiteralSlotType(slot.type)) {
+            throw new Error('sql analysis response literal slot is missing valid type');
+        }
+        if (typeof slot.example_value !== 'string') {
+            throw new Error('sql analysis response literal slot is missing example_value');
+        }
+        return {
+            position: slot.position,
+            type: slot.type,
+            exampleValue: slot.example_value,
+        };
+    });
+}
+function mapResult(raw) {
+    const error = optionalString(raw, 'error');
+    return {
+        fingerprint: requiredString(raw, 'fingerprint'),
+        normalizedSql: requiredString(raw, 'normalized_sql'),
+        tablesTouched: requiredStringArray(raw, 'tables_touched'),
+        literalSlots: literalSlots(raw),
+        ...(error !== undefined ? { error } : {}),
+    };
+}
+export function createHttpSqlAnalysisPort(options) {
+    const requestJson = options.requestJson ?? postJson(options.baseUrl);
+    return {
+        async analyzeForFingerprint(sql, dialect) {
+            const raw = await requestJson('/api/sql/analyze-for-fingerprint', {
+                sql,
+                dialect,
+            });
+            return mapResult(raw);
+        },
+    };
+}

package/node_modules/@ktx/context/dist/sql-analysis/http-sql-analysis-port.test.d.ts

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

package/node_modules/@ktx/context/dist/sql-analysis/http-sql-analysis-port.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createHttpSqlAnalysisPort } from './http-sql-analysis-port.js';
+describe('createHttpSqlAnalysisPort', () => {
+    it('calls the python-service fingerprint endpoint and maps snake_case response fields', async () => {
+        const requestJson = vi.fn(async () => ({
+            fingerprint: 'fingerprint-template',
+            normalized_sql: 'SELECT * FROM analytics.orders WHERE status = ?',
+            tables_touched: ['analytics.orders'],
+            literal_slots: [{ position: 1, type: 'string', example_value: 'paid' }],
+        }));
+        const port = createHttpSqlAnalysisPort({ baseUrl: 'http://python.test', requestJson });
+        await expect(port.analyzeForFingerprint("SELECT * FROM analytics.orders WHERE status = 'paid'", 'postgres')).resolves.toEqual({
+            fingerprint: 'fingerprint-template',
+            normalizedSql: 'SELECT * FROM analytics.orders WHERE status = ?',
+            tablesTouched: ['analytics.orders'],
+            literalSlots: [{ position: 1, type: 'string', exampleValue: 'paid' }],
+        });
+        expect(requestJson).toHaveBeenCalledWith('/api/sql/analyze-for-fingerprint', {
+            sql: "SELECT * FROM analytics.orders WHERE status = 'paid'",
+            dialect: 'postgres',
+        });
+    });
+    it('preserves python-service parse errors in the mapped result', async () => {
+        const requestJson = vi.fn(async () => ({
+            fingerprint: '',
+            normalized_sql: '',
+            tables_touched: [],
+            literal_slots: [],
+            error: 'Invalid expression / Unexpected token',
+        }));
+        const port = createHttpSqlAnalysisPort({ baseUrl: 'http://python.test', requestJson });
+        await expect(port.analyzeForFingerprint('SELECT * FROM WHERE', 'postgres')).resolves.toEqual({
+            fingerprint: '',
+            normalizedSql: '',
+            tablesTouched: [],
+            literalSlots: [],
+            error: 'Invalid expression / Unexpected token',
+        });
+    });
+    it('rejects malformed daemon responses instead of inventing defaults', async () => {
+        const requestJson = vi.fn(async () => ({
+            fingerprint: 'abc',
+            normalized_sql: 'SELECT ?',
+            tables_touched: 'orders',
+            literal_slots: [],
+        }));
+        const port = createHttpSqlAnalysisPort({ baseUrl: 'http://python.test', requestJson });
+        await expect(port.analyzeForFingerprint('SELECT 1', 'postgres')).rejects.toThrow('sql analysis response is missing string[] field tables_touched');
+    });
+});

package/node_modules/@ktx/context/dist/sql-analysis/index.d.ts

@@ -0,0 +1,3 @@
+export { createHttpSqlAnalysisPort } from './http-sql-analysis-port.js';
+export type { HttpSqlAnalysisPortOptions, KtxSqlAnalysisHttpJsonRunner } from './http-sql-analysis-port.js';
+export type { SqlAnalysisDialect, SqlAnalysisFingerprintResult, SqlAnalysisLiteralSlot, SqlAnalysisLiteralSlotType, SqlAnalysisPort, } from './ports.js';

package/node_modules/@ktx/context/dist/sql-analysis/index.js

@@ -0,0 +1 @@
+export { createHttpSqlAnalysisPort } from './http-sql-analysis-port.js';

package/node_modules/@ktx/context/dist/sql-analysis/ports.d.ts

@@ -0,0 +1,17 @@
+export type SqlAnalysisDialect = 'bigquery' | 'snowflake' | 'postgres' | 'redshift' | 'mysql' | 'sqlite' | 'tsql' | 'clickhouse' | (string & {});
+export type SqlAnalysisLiteralSlotType = 'string' | 'number' | 'timestamp' | 'date' | 'boolean' | 'null' | 'unknown';
+export interface SqlAnalysisLiteralSlot {
+    position: number;
+    type: SqlAnalysisLiteralSlotType;
+    exampleValue: string;
+}
+export interface SqlAnalysisFingerprintResult {
+    fingerprint: string;
+    normalizedSql: string;
+    tablesTouched: string[];
+    literalSlots: SqlAnalysisLiteralSlot[];
+    error?: string | null;
+}
+export interface SqlAnalysisPort {
+    analyzeForFingerprint(sql: string, dialect: SqlAnalysisDialect): Promise<SqlAnalysisFingerprintResult>;
+}

package/node_modules/@ktx/context/dist/sql-analysis/ports.js

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

package/node_modules/@ktx/context/dist/test/make-local-git-repo.d.ts

@@ -0,0 +1,10 @@
+import type { SimpleGit } from 'simple-git';
+export interface LocalGitRepo {
+    repoDir: string;
+    repoUrl: string;
+    git: SimpleGit;
+    commit: (message: string) => Promise<string>;
+    writeFile: (relPath: string, content: string) => Promise<void>;
+    deleteFile: (relPath: string) => Promise<void>;
+}
+export declare function makeLocalGitRepo(fixtureDir: string, destRoot: string): Promise<LocalGitRepo>;

package/node_modules/@ktx/context/dist/test/make-local-git-repo.js

@@ -0,0 +1,34 @@
+import { cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createSimpleGit } from '../ingest/git-env.js';
+export async function makeLocalGitRepo(fixtureDir, destRoot) {
+    const repoDir = join(destRoot, 'repo');
+    await mkdir(repoDir, { recursive: true });
+    await cp(fixtureDir, repoDir, { recursive: true });
+    const git = createSimpleGit(repoDir);
+    await git.init();
+    await git.raw(['checkout', '-B', 'main']);
+    await git.addConfig('user.email', 'test@ktx.local');
+    await git.addConfig('user.name', 'KTX Test');
+    await git.add('.');
+    await git.commit('initial');
+    const commit = async (message) => {
+        await git.add('.');
+        await git.commit(message);
+        return (await git.log({ maxCount: 1 })).latest?.hash ?? '';
+    };
+    return {
+        repoDir,
+        repoUrl: `file://${repoDir}`,
+        git,
+        commit,
+        writeFile: async (relPath, content) => {
+            const dest = join(repoDir, relPath);
+            await mkdir(join(dest, '..'), { recursive: true });
+            await writeFile(dest, content, 'utf-8');
+        },
+        deleteFile: async (relPath) => {
+            await rm(join(repoDir, relPath), { force: true });
+        },
+    };
+}

package/node_modules/@ktx/context/dist/tools/authors.d.ts

@@ -0,0 +1,8 @@
+export interface GitAuthor {
+    name: string;
+    email: string;
+}
+export interface GitAuthorResolverPort {
+    resolve(userId: string | null | undefined): Promise<GitAuthor>;
+}
+export declare const SYSTEM_GIT_AUTHOR: GitAuthor;

package/node_modules/@ktx/context/dist/tools/authors.js

@@ -0,0 +1,4 @@
+export const SYSTEM_GIT_AUTHOR = {
+    name: 'System User',
+    email: 'system@example.com',
+};

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

@@ -0,0 +1,83 @@
+import { z, type ZodType } from 'zod';
+import { type KtxLogger } from '../core/index.js';
+import type { IngestToolMetadata, ToolSession } from './tool-session.js';
+export interface ToolOutput<T = unknown> {
+    markdown: string;
+    structured: T;
+}
+export interface ToolTimingTrackerPort {
+    recordToolExecutionStart(messageId: string, toolName: string, toolCallId: string): void;
+    recordToolExecutionEnd(messageId: string, toolName: string, toolCallId: string, state: string): void;
+}
+export interface ToolProgressRelayPort {
+    emit(event: unknown): void;
+}
+type ChatSource = 'RESEARCH' | 'DASHBOARD' | 'WIDGET_CONFIG' | 'EVALUATION' | 'METRIC_WORKSHOP' | 'INPUT_CONFIG' | 'SCHEDULED_RESEARCH' | 'DASHBOARD_GENERATION';
+export interface ToolContext {
+    sourceId: string;
+    messageId: string;
+    userId: string;
+    userRoles?: string[];
+    authToken?: string;
+    currentUserMessage?: string;
+    toolCallId?: string;
+    toolCallHistory?: string[];
+    timingTracker?: ToolTimingTrackerPort;
+    source?: ChatSource;
+    dashboardId?: string;
+    methodologyEntries?: MethodologyEntry[];
+    progressRelay?: ToolProgressRelayPort;
+    connectionId?: string;
+    ingest?: IngestToolMetadata;
+    /**
+     * Per-session state (ingest WU, memory-agent post-turn). When present, SL/wiki
+     * tools use session-scoped services and emit touched-set entries instead of
+     * writing to shared indexes immediately. Non-session callers leave this unset.
+     */
+    session?: ToolSession;
+    currentDefinition?: {
+        sql: string;
+        measures: unknown[];
+        dimensions: unknown[];
+        parameters: unknown[];
+        segments: unknown[];
+        name?: string;
+        description?: string;
+    };
+}
+export interface MethodologyEntry {
+    key: string;
+    toolName: string;
+    label: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+}
+/**
+ * SECURITY: All tools require authentication. userId must always be provided in ToolContext.
+ */
+export declare abstract class BaseTool<TInput extends ZodType = ZodType> {
+    protected readonly logger: KtxLogger;
+    abstract readonly name: string;
+    constructor(logger?: KtxLogger);
+    abstract get description(): string;
+    abstract get inputSchema(): TInput;
+    abstract call(input: z.infer<TInput>, context: ToolContext): Promise<any>;
+    getParametersSchema(): {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+    toAnthropicFormat(): {
+        name: string;
+        description: string;
+        input_schema: {
+            type: 'object';
+            properties: Record<string, any>;
+            required?: string[];
+        };
+    };
+    toAiSdkTool(context: ToolContext): any;
+    parseInput(input: Record<string, any>): z.infer<TInput>;
+    protected getCurrentUserQuery(context: ToolContext): string | null;
+}
+export {};

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

@@ -0,0 +1,77 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { noopLogger } from '../core/index.js';
+/**
+ * SECURITY: All tools require authentication. userId must always be provided in ToolContext.
+ */
+export class BaseTool {
+    logger;
+    constructor(logger = noopLogger) {
+        this.logger = logger;
+    }
+    getParametersSchema() {
+        const jsonSchema = z.toJSONSchema(this.inputSchema, {
+            target: 'draft-7',
+        });
+        return jsonSchema;
+    }
+    toAnthropicFormat() {
+        return {
+            name: this.name,
+            description: this.description,
+            input_schema: this.getParametersSchema(),
+        };
+    }
+    toAiSdkTool(context) {
+        const toolName = this.name;
+        const logger = this.logger;
+        return tool({
+            description: this.description,
+            inputSchema: this.inputSchema,
+            execute: async (params, { toolCallId }) => {
+                // Create context copy with current toolCallId (safe for parallel execution)
+                const callContext = { ...context, toolCallId };
+                // Record tool execution start (input generation has already been tracked via onChunk)
+                if (callContext.timingTracker && toolCallId) {
+                    callContext.timingTracker.recordToolExecutionStart(callContext.messageId, toolName, toolCallId);
+                }
+                let state = 'completed';
+                try {
+                    if (!callContext.userId) {
+                        throw new Error('Authentication required: userId must be provided in ToolContext');
+                    }
+                    const parsedInput = this.parseInput(params);
+                    const result = await this.call(parsedInput, callContext);
+                    return result;
+                }
+                catch (error) {
+                    state = 'error';
+                    this.logger.error(`Tool ${this.name} execution failed: ${error instanceof Error ? error.message : String(error)}`);
+                    throw error;
+                }
+                finally {
+                    // Record tool execution end
+                    if (callContext.timingTracker && toolCallId) {
+                        callContext.timingTracker.recordToolExecutionEnd(callContext.messageId, toolName, toolCallId, state);
+                    }
+                }
+            },
+            // Send only markdown to LLM - frontend still receives full { markdown, structured } via stream
+            toModelOutput: ({ output }) => {
+                if (output && typeof output === 'object' && 'markdown' in output) {
+                    return { type: 'content', value: [{ type: 'text', text: output.markdown }] };
+                }
+                if (typeof output !== 'string') {
+                    logger.warn(`Tool ${toolName} returned unexpected output type: ${typeof output}. Coercing to string.`);
+                }
+                return { type: 'content', value: [{ type: 'text', text: String(output) }] };
+            },
+        });
+    }
+    parseInput(input) {
+        return this.inputSchema.parse(input);
+    }
+    getCurrentUserQuery(context) {
+        return context.currentUserMessage ?? null;
+    }
+}

package/node_modules/@ktx/context/dist/tools/context-candidate-mark.tool.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { BaseTool, type ToolContext, type ToolOutput } from './base-tool.js';
+import type { ContextEvidenceToolStorePort } from './context-evidence-tool-store.js';
+import { type ToolFailure } from './context-ingest-metadata.js';
+declare const contextCandidateMarkInputSchema: z.ZodObject<{
+    candidateKey: z.ZodString;
+    status: z.ZodEnum<{
+        conflict: "conflict";
+        rejected: "rejected";
+        merged: "merged";
+        pending: "pending";
+        promoted: "promoted";
+    }>;
+    rejectionReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type ContextCandidateMarkInput = z.infer<typeof contextCandidateMarkInputSchema>;
+interface ContextCandidateMarkStructured {
+    success: boolean;
+    error?: string;
+    candidateKey?: string;
+    status?: string;
+}
+export declare class ContextCandidateMarkTool extends BaseTool<typeof contextCandidateMarkInputSchema> {
+    private readonly store;
+    readonly name = "context_candidate_mark";
+    constructor(store: ContextEvidenceToolStorePort);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        candidateKey: z.ZodString;
+        status: z.ZodEnum<{
+            conflict: "conflict";
+            rejected: "rejected";
+            merged: "merged";
+            pending: "pending";
+            promoted: "promoted";
+        }>;
+        rejectionReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    call(input: ContextCandidateMarkInput, context: ToolContext): Promise<ToolOutput<ContextCandidateMarkStructured | ToolFailure>>;
+}
+export {};

package/node_modules/@ktx/context/dist/tools/context-candidate-mark.tool.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { BaseTool } from './base-tool.js';
+import { ingestMetadataRequired, resolveIngestMetadata } from './context-ingest-metadata.js';
+const contextCandidateMarkInputSchema = z.object({
+    candidateKey: z.string().min(1),
+    status: z.enum(['pending', 'promoted', 'merged', 'rejected', 'conflict']),
+    rejectionReason: z.string().max(500).nullable().default(null),
+});
+export class ContextCandidateMarkTool extends BaseTool {
+    store;
+    name = 'context_candidate_mark';
+    constructor(store) {
+        super();
+        this.store = store;
+    }
+    get description() {
+        return 'Mark a context knowledge candidate after curator reconciliation promotes, merges, rejects, or keeps it as a conflict.';
+    }
+    get inputSchema() {
+        return contextCandidateMarkInputSchema;
+    }
+    async call(input, context) {
+        const ingest = resolveIngestMetadata(context);
+        if (!ingest) {
+            return ingestMetadataRequired();
+        }
+        const updated = await this.store.updateCandidateStatus({
+            runId: ingest.runId,
+            candidateKey: input.candidateKey,
+            status: input.status,
+            rejectionReason: input.rejectionReason,
+        });
+        if (!updated) {
+            return {
+                markdown: `No candidate found with key "${input.candidateKey}".`,
+                structured: { success: false, error: 'CANDIDATE_NOT_FOUND', candidateKey: input.candidateKey },
+            };
+        }
+        return {
+            markdown: `Candidate "${updated.candidate_key}" marked ${updated.status}.`,
+            structured: { success: true, candidateKey: updated.candidate_key, status: updated.status },
+        };
+    }
+}

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

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import type { KtxEmbeddingPort } from '../core/index.js';
+import { BaseTool, type ToolContext, type ToolOutput } from './base-tool.js';
+import type { ContextEvidenceToolStorePort } from './context-evidence-tool-store.js';
+import { type ToolFailure } from './context-ingest-metadata.js';
+declare const contextCandidateWriteInputSchema: z.ZodObject<{
+    candidateKey: z.ZodString;
+    topic: z.ZodString;
+    assertion: z.ZodString;
+    rationale: z.ZodString;
+    evidenceChunkIds: z.ZodArray<z.ZodString>;
+    suggestedPageKey: z.ZodOptional<z.ZodString>;
+    actionHint: z.ZodEnum<{
+        merge: "merge";
+        conflict: "conflict";
+        skip: "skip";
+        create: "create";
+        update: "update";
+    }>;
+    durabilityScore: z.ZodNumber;
+    authorityScore: z.ZodNumber;
+    reuseScore: z.ZodNumber;
+    noveltyScore: z.ZodNumber;
+    riskScore: z.ZodNumber;
+}, z.core.$strip>;
+type ContextCandidateWriteInput = z.infer<typeof contextCandidateWriteInputSchema>;
+interface ContextCandidateWriteStructured {
+    success: boolean;
+    error?: string;
+    message?: string;
+    candidateKey?: string;
+    promotionScore?: number;
+    status?: string;
+}
+export declare class ContextCandidateWriteTool extends BaseTool<typeof contextCandidateWriteInputSchema> {
+    private readonly store;
+    private readonly embeddingService;
+    readonly name = "context_candidate_write";
+    constructor(store: ContextEvidenceToolStorePort, embeddingService: Pick<KtxEmbeddingPort, 'computeEmbedding'>);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        candidateKey: z.ZodString;
+        topic: z.ZodString;
+        assertion: z.ZodString;
+        rationale: z.ZodString;
+        evidenceChunkIds: z.ZodArray<z.ZodString>;
+        suggestedPageKey: z.ZodOptional<z.ZodString>;
+        actionHint: z.ZodEnum<{
+            merge: "merge";
+            conflict: "conflict";
+            skip: "skip";
+            create: "create";
+            update: "update";
+        }>;
+        durabilityScore: z.ZodNumber;
+        authorityScore: z.ZodNumber;
+        reuseScore: z.ZodNumber;
+        noveltyScore: z.ZodNumber;
+        riskScore: z.ZodNumber;
+    }, z.core.$strip>;
+    call(input: ContextCandidateWriteInput, context: ToolContext): Promise<ToolOutput<ContextCandidateWriteStructured | ToolFailure>>;
+    private computeCandidateEmbedding;
+}
+export {};