@kaelio/ktx 0.0.0 → 0.1.0-rc.1

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

@@ -0,0 +1,85 @@
+import { z, type ZodType } from 'zod';
+import { type KtxLogger } from '../core/index.js';
+import type { KtxRuntimeToolDescriptor } from '../llm/runtime-port.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;
+    toRuntimeTool(context: ToolContext): KtxRuntimeToolDescriptor;
+    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,94 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { noopLogger } from '../core/index.js';
+import { normalizeKtxRuntimeToolOutput } from '../llm/runtime-tools.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 the LLM; tool callers still receive the structured output.
+            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) }] };
+            },
+        });
+    }
+    toRuntimeTool(context) {
+        const toolName = this.name;
+        return {
+            name: toolName,
+            description: this.description,
+            inputSchema: this.inputSchema,
+            execute: async (params) => {
+                const callContext = { ...context };
+                if (!callContext.userId) {
+                    throw new Error('Authentication required: userId must be provided in ToolContext');
+                }
+                const parsedInput = this.parseInput(params);
+                return normalizeKtxRuntimeToolOutput(await this.call(parsedInput, callContext));
+            },
+        };
+    }
+    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 {};

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

@@ -0,0 +1,140 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { buildContextCandidateEmbeddingText } from '../ingest/context-candidates/index.js';
+import { BaseTool } from './base-tool.js';
+import { chunkIdSchema } from './context-evidence-ids.js';
+import { ingestMetadataRequired, resolveIngestMetadata } from './context-ingest-metadata.js';
+const scoreSchema = z.number().int().min(0).max(3);
+const contextCandidateWriteInputSchema = z.object({
+    candidateKey: z.string().min(1).max(160),
+    topic: z.string().min(1).max(200),
+    assertion: z.string().min(1).max(500),
+    rationale: z.string().min(1).max(1000),
+    evidenceChunkIds: z.array(chunkIdSchema).min(1),
+    suggestedPageKey: z.string().min(1).max(120).optional(),
+    actionHint: z.enum(['create', 'update', 'merge', 'conflict', 'skip']),
+    durabilityScore: scoreSchema,
+    authorityScore: scoreSchema,
+    reuseScore: scoreSchema,
+    noveltyScore: scoreSchema,
+    riskScore: scoreSchema,
+});
+export class ContextCandidateWriteTool extends BaseTool {
+    store;
+    embeddingService;
+    name = 'context_candidate_write';
+    constructor(store, embeddingService) {
+        super();
+        this.store = store;
+        this.embeddingService = embeddingService;
+    }
+    get description() {
+        return 'Write a durable knowledge candidate from indexed context evidence. Use this during ingest candidate extraction instead of wiki_write.';
+    }
+    get inputSchema() {
+        return contextCandidateWriteInputSchema;
+    }
+    async call(input, context) {
+        const ingest = resolveIngestMetadata(context);
+        if (!ingest) {
+            return ingestMetadataRequired();
+        }
+        const connectionId = context.connectionId ?? context.session?.connectionId;
+        if (!connectionId) {
+            return {
+                markdown: 'Error: no connectionId is available for candidate write.',
+                structured: {
+                    success: false,
+                    error: 'CONNECTION_REQUIRED',
+                    message: 'Run this inside an ingest session with a connectionId.',
+                },
+            };
+        }
+        if (input.evidenceChunkIds.length === 0) {
+            return {
+                markdown: 'Error: candidates require at least one evidence chunk.',
+                structured: { success: false, error: 'EVIDENCE_REQUIRED', message: 'Provide one or more evidenceChunkIds.' },
+            };
+        }
+        const chunks = await this.store.readChunksByIds(input.evidenceChunkIds, connectionId, ingest.sourceKey, ingest.runId);
+        if (chunks.length !== input.evidenceChunkIds.length) {
+            const found = new Set(chunks.map((chunk) => chunk.chunkId));
+            const missing = input.evidenceChunkIds.filter((id) => !found.has(id));
+            return {
+                markdown: `Error: evidence chunks not found or not visible: ${missing.join(', ')}`,
+                structured: {
+                    success: false,
+                    error: 'EVIDENCE_NOT_FOUND',
+                    message: `Missing evidence chunk ids: ${missing.join(', ')}`,
+                },
+            };
+        }
+        const promotionScore = input.durabilityScore + input.authorityScore + input.reuseScore + input.noveltyScore - input.riskScore;
+        const status = input.actionHint === 'conflict' ? 'conflict' : input.actionHint === 'skip' ? 'rejected' : 'pending';
+        const evidenceRefs = chunks.map((chunk) => ({
+            chunkId: chunk.chunkId,
+            stableCitationKey: chunk.stableCitationKey,
+            syncId: chunk.syncId,
+            rawPath: chunk.rawPath,
+            title: chunk.title,
+            path: chunk.path,
+            url: chunk.url,
+            lastEditedAt: chunk.lastEditedAt?.toISOString() ?? null,
+            snippetHash: createHash('sha256').update(chunk.content).digest('hex'),
+            citation: chunk.citation,
+        }));
+        const embedding = await this.computeCandidateEmbedding(input);
+        try {
+            const candidate = await this.store.insertCandidate({
+                runId: ingest.runId,
+                connectionId,
+                sourceKey: ingest.sourceKey,
+                candidateKey: input.candidateKey,
+                topic: input.topic,
+                assertion: input.assertion,
+                rationale: input.rationale,
+                evidenceChunkIds: input.evidenceChunkIds,
+                evidenceRefs,
+                suggestedPageKey: input.suggestedPageKey ?? null,
+                actionHint: input.actionHint,
+                durabilityScore: input.durabilityScore,
+                authorityScore: input.authorityScore,
+                reuseScore: input.reuseScore,
+                noveltyScore: input.noveltyScore,
+                riskScore: input.riskScore,
+                promotionScore,
+                status,
+                rejectionReason: input.actionHint === 'skip' ? 'Extractor marked this candidate as skip.' : null,
+                embedding,
+            });
+            return {
+                markdown: `Candidate "${candidate.candidate_key}" saved with promotion score ${candidate.promotion_score}.`,
+                structured: {
+                    success: true,
+                    candidateKey: candidate.candidate_key,
+                    promotionScore: candidate.promotion_score,
+                    status: candidate.status,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                markdown: `Error: candidate "${input.candidateKey}" could not be saved.`,
+                structured: {
+                    success: false,
+                    error: 'CANDIDATE_WRITE_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+    }
+    async computeCandidateEmbedding(input) {
+        try {
+            return await this.embeddingService.computeEmbedding(buildContextCandidateEmbeddingText(input));
+        }
+        catch (error) {
+            this.logger.warn(`Candidate embedding generation failed for topic "${input.topic}": ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+}

package/node_modules/@ktx/context/dist/tools/context-evidence-ids.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export declare const chunkIdSchema: z.ZodString;
+export declare const documentIdSchema: z.ZodString;

package/node_modules/@ktx/context/dist/tools/context-evidence-ids.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+const UUID_BODY = '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}';
+const CHUNK_ID_PATTERN = new RegExp(`^ctxchunk-${UUID_BODY}$`);
+const DOCUMENT_ID_PATTERN = new RegExp(`^ctxdoc-${UUID_BODY}$`);
+export const chunkIdSchema = z
+    .string()
+    .regex(CHUNK_ID_PATTERN, 'Use a chunkId returned by context_evidence_search (format: "ctxchunk-<uuid>").')
+    .describe('A chunkId from context_evidence_search results, e.g. "ctxchunk-<uuid>".');
+export const documentIdSchema = z
+    .string()
+    .regex(DOCUMENT_ID_PATTERN, 'Use a documentId returned by context_evidence_search or context_evidence_neighbors (format: "ctxdoc-<uuid>").')
+    .describe('A documentId from context_evidence_search or context_evidence_neighbors results, e.g. "ctxdoc-<uuid>".');

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

@@ -0,0 +1,48 @@
+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 contextEvidenceNeighborsInputSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    relation: z.ZodEnum<{
+        parent: "parent";
+        children: "children";
+        linked: "linked";
+        backlinked: "backlinked";
+        same_path: "same_path";
+    }>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type ContextEvidenceNeighborsInput = z.infer<typeof contextEvidenceNeighborsInputSchema>;
+interface ContextEvidenceNeighborsStructured {
+    success: true;
+    results: Array<{
+        documentId: string;
+        externalId: string;
+        title: string;
+        path: string;
+        relation: string;
+        url: string | null;
+        lastEditedAt: string | null;
+    }>;
+    totalFound: number;
+}
+export declare class ContextEvidenceNeighborsTool extends BaseTool<typeof contextEvidenceNeighborsInputSchema> {
+    private readonly store;
+    readonly name = "context_evidence_neighbors";
+    constructor(store: ContextEvidenceToolStorePort);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        documentId: z.ZodString;
+        relation: z.ZodEnum<{
+            parent: "parent";
+            children: "children";
+            linked: "linked";
+            backlinked: "backlinked";
+            same_path: "same_path";
+        }>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    call(input: ContextEvidenceNeighborsInput, context: ToolContext): Promise<ToolOutput<ContextEvidenceNeighborsStructured | ToolFailure>>;
+}
+export {};

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

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { BaseTool } from './base-tool.js';
+import { documentIdSchema } from './context-evidence-ids.js';
+import { ingestMetadataRequired, resolveIngestMetadata } from './context-ingest-metadata.js';
+const contextEvidenceNeighborsInputSchema = z.object({
+    documentId: documentIdSchema,
+    relation: z.enum(['parent', 'children', 'linked', 'backlinked', 'same_path']),
+    limit: z.number().int().min(1).max(25).default(10),
+});
+export class ContextEvidenceNeighborsTool extends BaseTool {
+    store;
+    name = 'context_evidence_neighbors';
+    constructor(store) {
+        super();
+        this.store = store;
+    }
+    get description() {
+        return 'Find parent, child, linked, backlinked, or same-folder evidence documents for the current ingest source.';
+    }
+    get inputSchema() {
+        return contextEvidenceNeighborsInputSchema;
+    }
+    async call(input, context) {
+        const ingest = resolveIngestMetadata(context);
+        if (!ingest) {
+            return ingestMetadataRequired();
+        }
+        const connectionId = context.connectionId ?? context.session?.connectionId;
+        if (!connectionId) {
+            return {
+                markdown: 'Error: no connectionId is available for context evidence neighbors.',
+                structured: {
+                    success: false,
+                    error: 'CONNECTION_REQUIRED',
+                    message: 'Run this inside an ingest session with a connectionId.',
+                },
+            };
+        }
+        const results = await this.store.findNeighborDocuments({
+            connectionId,
+            sourceKey: ingest.sourceKey,
+            documentId: input.documentId,
+            relation: input.relation,
+            limit: input.limit,
+            currentRunId: ingest.runId,
+        });
+        if (results.length === 0) {
+            return {
+                markdown: `No ${input.relation} evidence documents found.`,
+                structured: { success: true, results: [], totalFound: 0 },
+            };
+        }
+        return {
+            markdown: [
+                `Found ${results.length} ${input.relation} evidence document(s):`,
+                '',
+                ...results.map((result, index) => `${index + 1}. **${result.title}** (${result.path}) documentId=${result.documentId}`),
+            ].join('\n'),
+            structured: {
+                success: true,
+                totalFound: results.length,
+                results: results.map((result) => ({
+                    ...result,
+                    lastEditedAt: result.lastEditedAt?.toISOString() ?? null,
+                })),
+            },
+        };
+    }
+}

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

@@ -0,0 +1,37 @@
+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 contextEvidenceReadInputSchema: z.ZodObject<{
+    chunkId: z.ZodOptional<z.ZodString>;
+    documentId: z.ZodOptional<z.ZodString>;
+    externalId: z.ZodOptional<z.ZodString>;
+    includeNeighborChunks: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type ContextEvidenceReadInput = z.infer<typeof contextEvidenceReadInputSchema>;
+interface ContextEvidenceReadStructured {
+    success: true;
+    found: boolean;
+    documentId?: string;
+    chunkId?: string;
+    externalId?: string;
+    title?: string;
+    path?: string;
+    url?: string | null;
+    content?: string;
+    citation?: unknown;
+}
+export declare class ContextEvidenceReadTool extends BaseTool<typeof contextEvidenceReadInputSchema> {
+    private readonly store;
+    readonly name = "context_evidence_read";
+    constructor(store: ContextEvidenceToolStorePort);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        chunkId: z.ZodOptional<z.ZodString>;
+        documentId: z.ZodOptional<z.ZodString>;
+        externalId: z.ZodOptional<z.ZodString>;
+        includeNeighborChunks: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    call(input: ContextEvidenceReadInput, context: ToolContext): Promise<ToolOutput<ContextEvidenceReadStructured | ToolFailure>>;
+}
+export {};