@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/node_modules/@ktx/context/dist/llm/embedding-port.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from 'vitest';
+import { KtxIngestEmbeddingPortAdapter, KtxScanEmbeddingPortAdapter } from './embedding-port.js';
+describe('KTX embedding port adapters', () => {
+    it('adapts @ktx/llm embeddings to ingest embedding port shape', async () => {
+        const provider = {
+            dimensions: 3,
+            maxBatchSize: 2,
+            embed: vi.fn(async () => [1, 2, 3]),
+            [['embed', 'Many'].join('')]: vi.fn(async () => [
+                [1, 2, 3],
+                [4, 5, 6],
+            ]),
+        };
+        const adapter = new KtxIngestEmbeddingPortAdapter(provider);
+        await expect(adapter.computeEmbedding('alpha')).resolves.toEqual([1, 2, 3]);
+        await expect(adapter.computeEmbeddingsBulk(['alpha', 'beta'])).resolves.toEqual([
+            [1, 2, 3],
+            [4, 5, 6],
+        ]);
+        expect(adapter.maxBatchSize).toBe(2);
+    });
+    it('adapts @ktx/llm embeddings to scan embedding port shape', async () => {
+        const provider = {
+            dimensions: 3,
+            maxBatchSize: 2,
+            embed: vi.fn(),
+            [['embed', 'Many'].join('')]: vi.fn(async () => [[1, 2, 3]]),
+        };
+        const adapter = new KtxScanEmbeddingPortAdapter(provider);
+        await expect(adapter.embedBatch(['alpha'])).resolves.toEqual([[1, 2, 3]]);
+        expect(adapter.dimensions).toBe(3);
+        expect(adapter.maxBatchSize).toBe(2);
+    });
+});

package/node_modules/@ktx/context/dist/llm/generation.d.ts

@@ -0,0 +1,8 @@
+import type { z } from 'zod';
+import type { KtxGenerateObjectInput, KtxGenerateTextInput, KtxLlmRuntimePort } from './runtime-port.js';
+export declare function generateKtxText(input: KtxGenerateTextInput & {
+    runtime: KtxLlmRuntimePort;
+}): Promise<string>;
+export declare function generateKtxObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema> & {
+    runtime: KtxLlmRuntimePort;
+}): Promise<TOutput>;

package/node_modules/@ktx/context/dist/llm/generation.js

@@ -0,0 +1,6 @@
+export async function generateKtxText(input) {
+    return input.runtime.generateText(input);
+}
+export async function generateKtxObject(input) {
+    return input.runtime.generateObject(input);
+}

package/node_modules/@ktx/context/dist/llm/index.d.ts

@@ -0,0 +1,13 @@
+export { KtxIngestEmbeddingPortAdapter, KtxScanEmbeddingPortAdapter } from './embedding-port.js';
+export { AiSdkKtxLlmRuntime } from './ai-sdk-runtime.js';
+export type { AgentTelemetryPort, AiSdkKtxLlmRuntimeDeps } from './ai-sdk-runtime.js';
+export { createKtxClaudeCodeEnv, CLAUDE_CODE_PROVIDER_ENV_DENYLIST } from './claude-code-env.js';
+export { resolveClaudeCodeModel } from './claude-code-models.js';
+export { ClaudeCodeKtxLlmRuntime, mapClaudeCodeStopReason, runClaudeCodeAuthProbe } from './claude-code-runtime.js';
+export { generateKtxObject, generateKtxText } from './generation.js';
+export type { AgentRunnerPort, KtxGenerateObjectInput, KtxGenerateTextInput, KtxLlmRuntimePort, KtxRuntimeToolDescriptor, KtxRuntimeToolOutput, KtxRuntimeToolSet, RunLoopParams, RunLoopResult, RunLoopStepInfo, RunLoopStopReason, } from './runtime-port.js';
+export { RuntimeAgentRunner } from './runtime-port.js';
+export { createAiSdkToolSet, createClaudeSdkTools, createRuntimeToolDescriptorFromAiTool, createRuntimeToolSetFromAiSdkTools, normalizeKtxRuntimeToolOutput, } from './runtime-tools.js';
+export type { KtxLlmDebugProviderOptionsEntry, KtxLlmDebugRequest, KtxLlmDebugRequestRecorder, SummarizeKtxLlmDebugRequestInput, } from './debug-request-recorder.js';
+export { createJsonlKtxLlmDebugRequestRecorder, summarizeKtxLlmDebugRequest, } from './debug-request-recorder.js';
+export { MANAGED_SENTENCE_TRANSFORMERS_BASE_URL, MANAGED_SENTENCE_TRANSFORMERS_BASE_URL_ENV, createLocalKtxEmbeddingProviderFromConfig, createLocalKtxLlmProviderFromConfig, createLocalKtxLlmRuntimeFromConfig, resolveLocalKtxEmbeddingConfig, resolveLocalKtxLlmConfig, } from './local-config.js';

package/node_modules/@ktx/context/dist/llm/index.js

@@ -0,0 +1,10 @@
+export { KtxIngestEmbeddingPortAdapter, KtxScanEmbeddingPortAdapter } from './embedding-port.js';
+export { AiSdkKtxLlmRuntime } from './ai-sdk-runtime.js';
+export { createKtxClaudeCodeEnv, CLAUDE_CODE_PROVIDER_ENV_DENYLIST } from './claude-code-env.js';
+export { resolveClaudeCodeModel } from './claude-code-models.js';
+export { ClaudeCodeKtxLlmRuntime, mapClaudeCodeStopReason, runClaudeCodeAuthProbe } from './claude-code-runtime.js';
+export { generateKtxObject, generateKtxText } from './generation.js';
+export { RuntimeAgentRunner } from './runtime-port.js';
+export { createAiSdkToolSet, createClaudeSdkTools, createRuntimeToolDescriptorFromAiTool, createRuntimeToolSetFromAiSdkTools, normalizeKtxRuntimeToolOutput, } from './runtime-tools.js';
+export { createJsonlKtxLlmDebugRequestRecorder, summarizeKtxLlmDebugRequest, } from './debug-request-recorder.js';
+export { MANAGED_SENTENCE_TRANSFORMERS_BASE_URL, MANAGED_SENTENCE_TRANSFORMERS_BASE_URL_ENV, createLocalKtxEmbeddingProviderFromConfig, createLocalKtxLlmProviderFromConfig, createLocalKtxLlmRuntimeFromConfig, resolveLocalKtxEmbeddingConfig, resolveLocalKtxLlmConfig, } from './local-config.js';

package/node_modules/@ktx/context/dist/llm/local-config.d.ts

@@ -0,0 +1,22 @@
+import { createKtxEmbeddingProvider, createKtxLlmProvider, type KtxEmbeddingConfig, type KtxEmbeddingProvider, type KtxLlmConfig, type KtxLlmProvider } from '@ktx/llm';
+import type { KtxProjectEmbeddingConfig, KtxProjectLlmConfig } from '../project/config.js';
+import { ClaudeCodeKtxLlmRuntime } from './claude-code-runtime.js';
+import type { KtxLlmRuntimePort } from './runtime-port.js';
+interface LocalConfigDeps {
+    env?: NodeJS.ProcessEnv;
+    projectDir?: string;
+    createKtxLlmProvider?: typeof createKtxLlmProvider;
+    createKtxEmbeddingProvider?: typeof createKtxEmbeddingProvider;
+    createClaudeCodeRuntime?: (deps: ConstructorParameters<typeof ClaudeCodeKtxLlmRuntime>[0]) => KtxLlmRuntimePort;
+    createAiSdkRuntime?: (deps: {
+        llmProvider: KtxLlmProvider;
+    }) => KtxLlmRuntimePort;
+}
+export declare const MANAGED_SENTENCE_TRANSFORMERS_BASE_URL = "managed:local-embeddings";
+export declare const MANAGED_SENTENCE_TRANSFORMERS_BASE_URL_ENV = "KTX_MANAGED_SENTENCE_TRANSFORMERS_BASE_URL";
+export declare function resolveLocalKtxLlmConfig(config: KtxProjectLlmConfig, env: NodeJS.ProcessEnv): KtxLlmConfig | null;
+export declare function createLocalKtxLlmProviderFromConfig(config: KtxProjectLlmConfig, deps?: LocalConfigDeps): KtxLlmProvider | null;
+export declare function createLocalKtxLlmRuntimeFromConfig(config: KtxProjectLlmConfig, deps?: LocalConfigDeps): KtxLlmRuntimePort | null;
+export declare function resolveLocalKtxEmbeddingConfig(config: KtxProjectEmbeddingConfig, env: NodeJS.ProcessEnv): KtxEmbeddingConfig | null;
+export declare function createLocalKtxEmbeddingProviderFromConfig(config: KtxProjectEmbeddingConfig, deps?: LocalConfigDeps): KtxEmbeddingProvider | null;
+export {};

package/node_modules/@ktx/context/dist/llm/local-config.js

@@ -0,0 +1,145 @@
+import { createKtxEmbeddingProvider, createKtxLlmProvider, } from '@ktx/llm';
+import { resolveKtxConfigReference } from '../core/config-reference.js';
+import { AiSdkKtxLlmRuntime } from './ai-sdk-runtime.js';
+import { ClaudeCodeKtxLlmRuntime } from './claude-code-runtime.js';
+export const MANAGED_SENTENCE_TRANSFORMERS_BASE_URL = 'managed:local-embeddings';
+export const MANAGED_SENTENCE_TRANSFORMERS_BASE_URL_ENV = 'KTX_MANAGED_SENTENCE_TRANSFORMERS_BASE_URL';
+function resolveOptional(value, env) {
+    return resolveKtxConfigReference(value, env) || undefined;
+}
+function resolveRequired(value, env, message) {
+    const resolved = resolveOptional(value, env);
+    if (!resolved) {
+        throw new Error(message);
+    }
+    return resolved;
+}
+function resolveModelSlots(models, env) {
+    const resolved = {};
+    for (const [role, value] of Object.entries(models)) {
+        if (value) {
+            resolved[role] = resolveRequired(value, env, `llm.models.${role} is required`);
+        }
+    }
+    if (!resolved.default) {
+        throw new Error('llm.models.default is required when llm.provider.backend is not none');
+    }
+    return resolved;
+}
+function resolvedProviderConfig(config, env) {
+    if (!config) {
+        return undefined;
+    }
+    const apiKey = resolveOptional(config.api_key, env);
+    const baseURL = resolveOptional(config.base_url, env);
+    if (!apiKey && !baseURL) {
+        return undefined;
+    }
+    return {
+        ...(apiKey ? { apiKey } : {}),
+        ...(baseURL ? { baseURL } : {}),
+    };
+}
+function resolvedVertexConfig(config, env) {
+    if (!config) {
+        return undefined;
+    }
+    const project = resolveOptional(config.project, env);
+    const location = resolveRequired(config.location, env, 'llm.provider.vertex.location is required');
+    return {
+        ...(project ? { project } : {}),
+        location,
+    };
+}
+export function resolveLocalKtxLlmConfig(config, env) {
+    if (config.provider.backend === 'none') {
+        return null;
+    }
+    const modelSlots = resolveModelSlots(config.models, env);
+    const vertex = config.provider.backend === 'vertex' ? resolvedVertexConfig(config.provider.vertex, env) : undefined;
+    const anthropic = resolvedProviderConfig(config.provider.anthropic, env);
+    const gateway = resolvedProviderConfig(config.provider.gateway, env);
+    return {
+        backend: config.provider.backend,
+        ...(vertex ? { vertex } : {}),
+        ...(anthropic ? { anthropic } : {}),
+        ...(gateway ? { gateway } : {}),
+        modelSlots,
+        promptCaching: config.promptCaching,
+    };
+}
+export function createLocalKtxLlmProviderFromConfig(config, deps = {}) {
+    const resolved = resolveLocalKtxLlmConfig(config, deps.env ?? process.env);
+    if (!resolved || resolved.backend === 'claude-code') {
+        return null;
+    }
+    return (deps.createKtxLlmProvider ?? createKtxLlmProvider)(resolved);
+}
+export function createLocalKtxLlmRuntimeFromConfig(config, deps = {}) {
+    const resolved = resolveLocalKtxLlmConfig(config, deps.env ?? process.env);
+    if (!resolved) {
+        return null;
+    }
+    if (resolved.backend === 'claude-code') {
+        const projectDir = deps.projectDir;
+        if (!projectDir) {
+            throw new Error('projectDir is required when creating the claude-code LLM runtime');
+        }
+        return (deps.createClaudeCodeRuntime ?? ((runtimeDeps) => new ClaudeCodeKtxLlmRuntime(runtimeDeps)))({
+            projectDir,
+            modelSlots: resolved.modelSlots,
+            env: deps.env,
+        });
+    }
+    const llmProvider = (deps.createKtxLlmProvider ?? createKtxLlmProvider)(resolved);
+    return (deps.createAiSdkRuntime ?? ((runtimeDeps) => new AiSdkKtxLlmRuntime(runtimeDeps)))({ llmProvider });
+}
+function resolveSentenceTransformersBaseUrl(value, env) {
+    if (!value) {
+        return undefined;
+    }
+    if (value === MANAGED_SENTENCE_TRANSFORMERS_BASE_URL) {
+        return resolveOptional(`env:${MANAGED_SENTENCE_TRANSFORMERS_BASE_URL_ENV}`, env);
+    }
+    return value;
+}
+export function resolveLocalKtxEmbeddingConfig(config, env) {
+    if (config.backend === 'none') {
+        return null;
+    }
+    if (config.backend === 'sentence-transformers') {
+        const baseURL = resolveSentenceTransformersBaseUrl(config.sentenceTransformers?.base_url, env);
+        if (!baseURL) {
+            return null;
+        }
+        return {
+            backend: config.backend,
+            model: config.model ?? 'all-MiniLM-L6-v2',
+            dimensions: config.dimensions,
+            sentenceTransformers: {
+                baseURL,
+                pathPrefix: config.sentenceTransformers?.pathPrefix,
+            },
+            batchSize: config.batchSize,
+        };
+    }
+    return {
+        backend: config.backend,
+        model: config.model ?? 'deterministic',
+        dimensions: config.dimensions,
+        ...(resolvedProviderConfig(config.openai, env) ? { openai: resolvedProviderConfig(config.openai, env) } : {}),
+        ...(config.sentenceTransformers
+            ? {
+                sentenceTransformers: {
+                    baseURL: config.sentenceTransformers.base_url,
+                    pathPrefix: config.sentenceTransformers.pathPrefix,
+                },
+            }
+            : {}),
+        batchSize: config.batchSize,
+    };
+}
+export function createLocalKtxEmbeddingProviderFromConfig(config, deps = {}) {
+    const resolved = resolveLocalKtxEmbeddingConfig(config, deps.env ?? process.env);
+    return resolved ? (deps.createKtxEmbeddingProvider ?? createKtxEmbeddingProvider)(resolved) : null;
+}

package/node_modules/@ktx/context/dist/llm/local-config.test.d.ts

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

package/node_modules/@ktx/context/dist/llm/local-config.test.js

@@ -0,0 +1,165 @@
+import { describe, expect, it, vi } from 'vitest';
+import { buildDefaultKtxProjectConfig, } from '../project/config.js';
+import { MANAGED_SENTENCE_TRANSFORMERS_BASE_URL, MANAGED_SENTENCE_TRANSFORMERS_BASE_URL_ENV, createLocalKtxEmbeddingProviderFromConfig, createLocalKtxLlmProviderFromConfig, resolveLocalKtxEmbeddingConfig, resolveLocalKtxLlmConfig, } from './local-config.js';
+describe('local KTX LLM config', () => {
+    it('resolves env and file references into a KtxLlmConfig', () => {
+        const config = {
+            provider: {
+                backend: 'gateway',
+                gateway: { api_key: 'env:AI_GATEWAY_API_KEY', base_url: 'https://gateway.example/v1' }, // pragma: allowlist secret
+            },
+            models: { default: 'env:KTX_MODEL', triage: 'anthropic/claude-haiku-4-5' },
+            promptCaching: { enabled: false },
+        };
+        expect(resolveLocalKtxLlmConfig(config, {
+            AI_GATEWAY_API_KEY: 'gateway-key', // pragma: allowlist secret
+            KTX_MODEL: 'anthropic/claude-sonnet-4-6',
+        })).toEqual({
+            backend: 'gateway',
+            gateway: { apiKey: 'gateway-key', baseURL: 'https://gateway.example/v1' }, // pragma: allowlist secret
+            modelSlots: { default: 'anthropic/claude-sonnet-4-6', triage: 'anthropic/claude-haiku-4-5' },
+            promptCaching: { enabled: false },
+        });
+    });
+    it('resolves Vertex AI env references into a KtxLlmConfig', () => {
+        const config = {
+            provider: {
+                backend: 'vertex',
+                vertex: { project: 'env:GOOGLE_VERTEX_PROJECT', location: 'env:GOOGLE_VERTEX_LOCATION' },
+            },
+            models: { default: 'env:KTX_MODEL' },
+            promptCaching: { enabled: true, vertexFallbackTo5m: true },
+        };
+        expect(resolveLocalKtxLlmConfig(config, {
+            GOOGLE_VERTEX_PROJECT: 'local-gcp-project',
+            GOOGLE_VERTEX_LOCATION: 'us-east5',
+            KTX_MODEL: 'claude-sonnet-4-6',
+        })).toEqual({
+            backend: 'vertex',
+            vertex: { project: 'local-gcp-project', location: 'us-east5' },
+            modelSlots: { default: 'claude-sonnet-4-6' },
+            promptCaching: { enabled: true, vertexFallbackTo5m: true },
+        });
+    });
+    it('ignores inactive Vertex AI references for non-Vertex backends', () => {
+        const config = {
+            provider: {
+                backend: 'anthropic',
+                anthropic: { api_key: 'env:ANTHROPIC_API_KEY' }, // pragma: allowlist secret
+                vertex: { location: 'env:MISSING_VERTEX_LOCATION' },
+            },
+            models: { default: 'claude-sonnet-4-6' },
+        };
+        expect(resolveLocalKtxLlmConfig(config, {
+            ANTHROPIC_API_KEY: 'sk-ant-test', // pragma: allowlist secret
+        })).toEqual({
+            backend: 'anthropic',
+            anthropic: { apiKey: 'sk-ant-test' }, // pragma: allowlist secret
+            modelSlots: { default: 'claude-sonnet-4-6' },
+            promptCaching: undefined,
+        });
+    });
+    it('returns null when the local LLM backend is disabled', () => {
+        expect(createLocalKtxLlmProviderFromConfig({
+            provider: { backend: 'none' },
+            models: {},
+        })).toBeNull();
+    });
+    it('constructs providers through @ktx/llm', () => {
+        const createKtxLlmProvider = vi.fn(() => ({ getModel: vi.fn() }));
+        const result = createLocalKtxLlmProviderFromConfig({
+            provider: {
+                backend: 'anthropic',
+                anthropic: { api_key: 'env:ANTHROPIC_API_KEY' }, // pragma: allowlist secret
+            },
+            models: { default: 'claude-sonnet-4-6' },
+        }, { env: { ANTHROPIC_API_KEY: 'sk-ant-test' }, createKtxLlmProvider });
+        expect(result).not.toBeNull();
+        expect(createKtxLlmProvider).toHaveBeenCalledWith({
+            backend: 'anthropic',
+            anthropic: { apiKey: 'sk-ant-test' }, // pragma: allowlist secret
+            modelSlots: { default: 'claude-sonnet-4-6' },
+            promptCaching: undefined,
+        });
+    });
+    it('inherits enabled prompt caching from @ktx/llm when local config omits promptCaching', () => {
+        const provider = createLocalKtxLlmProviderFromConfig({
+            provider: {
+                backend: 'gateway',
+                gateway: { base_url: 'https://gateway.example/v1' },
+            },
+            models: { default: 'anthropic/claude-sonnet-4-6' },
+        });
+        expect(provider?.promptCachingConfig()).toMatchObject({
+            enabled: true,
+            systemTtl: '1h',
+            toolsTtl: '1h',
+            historyTtl: '5m',
+            vertexFallbackTo5m: false,
+        });
+    });
+});
+describe('local KTX embedding config', () => {
+    it('resolves sentence-transformers config', () => {
+        const config = {
+            backend: 'sentence-transformers',
+            model: 'all-MiniLM-L6-v2',
+            dimensions: 384,
+            sentenceTransformers: { base_url: 'http://localhost:18081', pathPrefix: '' },
+            batchSize: 16,
+        };
+        expect(resolveLocalKtxEmbeddingConfig(config, {})).toEqual({
+            backend: 'sentence-transformers',
+            model: 'all-MiniLM-L6-v2',
+            dimensions: 384,
+            sentenceTransformers: { baseURL: 'http://localhost:18081', pathPrefix: '' },
+            batchSize: 16,
+        });
+    });
+    it('resolves managed sentence-transformers config from the CLI-provided daemon URL', () => {
+        const config = {
+            backend: 'sentence-transformers',
+            model: 'all-MiniLM-L6-v2',
+            dimensions: 384,
+            sentenceTransformers: {
+                base_url: MANAGED_SENTENCE_TRANSFORMERS_BASE_URL,
+                pathPrefix: '',
+            },
+            batchSize: 32,
+        };
+        expect(resolveLocalKtxEmbeddingConfig(config, {
+            [MANAGED_SENTENCE_TRANSFORMERS_BASE_URL_ENV]: 'http://127.0.0.1:61234',
+        })).toEqual({
+            backend: 'sentence-transformers',
+            model: 'all-MiniLM-L6-v2',
+            dimensions: 384,
+            sentenceTransformers: { baseURL: 'http://127.0.0.1:61234', pathPrefix: '' },
+            batchSize: 32,
+        });
+    });
+    it('returns null for managed sentence-transformers when no daemon URL is available', () => {
+        const config = {
+            backend: 'sentence-transformers',
+            model: 'all-MiniLM-L6-v2',
+            dimensions: 384,
+            sentenceTransformers: {
+                base_url: MANAGED_SENTENCE_TRANSFORMERS_BASE_URL,
+                pathPrefix: '',
+            },
+        };
+        expect(resolveLocalKtxEmbeddingConfig(config, {})).toBeNull();
+    });
+    it('constructs deterministic embeddings from the default project config', () => {
+        const createKtxEmbeddingProvider = vi.fn(() => ({}));
+        const provider = createLocalKtxEmbeddingProviderFromConfig(buildDefaultKtxProjectConfig().ingest.embeddings, { createKtxEmbeddingProvider });
+        expect(provider).not.toBeNull();
+        expect(createKtxEmbeddingProvider).toHaveBeenCalledWith(expect.objectContaining({
+            backend: 'deterministic',
+            model: 'deterministic',
+            dimensions: 8,
+        }));
+    });
+    it('returns null when embeddings are disabled', () => {
+        expect(createLocalKtxEmbeddingProviderFromConfig({ backend: 'none', dimensions: 8 })).toBeNull();
+    });
+});

package/node_modules/@ktx/context/dist/llm/runtime-local-config.test.d.ts

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

package/node_modules/@ktx/context/dist/llm/runtime-local-config.test.js

@@ -0,0 +1,17 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createLocalKtxLlmProviderFromConfig, createLocalKtxLlmRuntimeFromConfig } from './local-config.js';
+describe('local KTX LLM runtime config', () => {
+    it('creates a Claude Code runtime for claude-code backend without creating an AI SDK provider', () => {
+        const runtime = createLocalKtxLlmRuntimeFromConfig({
+            provider: { backend: 'claude-code' },
+            models: { default: 'sonnet', triage: 'haiku' },
+        }, { env: {}, projectDir: '/tmp/project', createClaudeCodeRuntime: vi.fn((deps) => ({ deps })) });
+        expect(runtime).toMatchObject({ deps: expect.objectContaining({ projectDir: '/tmp/project' }) });
+    });
+    it('returns null from the AI SDK provider factory for claude-code backend', () => {
+        expect(createLocalKtxLlmProviderFromConfig({
+            provider: { backend: 'claude-code' },
+            models: { default: 'sonnet' },
+        })).toBeNull();
+    });
+});

package/node_modules/@ktx/context/dist/llm/runtime-port.d.ts

@@ -0,0 +1,59 @@
+import type { KtxModelRole } from '@ktx/llm';
+import type { z } from 'zod';
+export interface KtxRuntimeToolOutput<TOutput = unknown> {
+    markdown: string;
+    structured?: TOutput;
+}
+export interface KtxRuntimeToolDescriptor<TInput = unknown, TOutput = unknown> {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<z.ZodRawShape>;
+    execute(input: TInput): Promise<KtxRuntimeToolOutput<TOutput>>;
+}
+export type KtxRuntimeToolSet = Record<string, KtxRuntimeToolDescriptor>;
+export type RunLoopStopReason = 'budget' | 'natural' | 'error';
+export interface RunLoopStepInfo {
+    stepIndex: number;
+    stepBudget: number;
+}
+export interface RunLoopParams {
+    modelRole: KtxModelRole;
+    systemPrompt: string;
+    userPrompt: string;
+    toolSet: KtxRuntimeToolSet;
+    stepBudget: number;
+    telemetryTags: Record<string, string>;
+    onStepFinish?: (info: RunLoopStepInfo) => void | Promise<void>;
+}
+export interface RunLoopResult {
+    stopReason: RunLoopStopReason;
+    error?: Error;
+}
+export interface KtxGenerateTextInput {
+    role: KtxModelRole;
+    prompt: string;
+    system?: string;
+    tools?: KtxRuntimeToolSet;
+    temperature?: number;
+}
+export interface KtxGenerateObjectInput<TOutput, TSchema extends z.ZodType<TOutput>> {
+    role: KtxModelRole;
+    prompt: string;
+    system?: string;
+    tools?: KtxRuntimeToolSet;
+    temperature?: number;
+    schema: TSchema;
+}
+export interface KtxLlmRuntimePort {
+    generateText(input: KtxGenerateTextInput): Promise<string>;
+    generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;
+    runAgentLoop(params: RunLoopParams): Promise<RunLoopResult>;
+}
+export interface AgentRunnerPort {
+    runLoop(params: RunLoopParams): Promise<RunLoopResult>;
+}
+export declare class RuntimeAgentRunner implements AgentRunnerPort {
+    private readonly runtime;
+    constructor(runtime: KtxLlmRuntimePort);
+    runLoop(params: RunLoopParams): Promise<RunLoopResult>;
+}

package/node_modules/@ktx/context/dist/llm/runtime-port.js

@@ -0,0 +1,9 @@
+export class RuntimeAgentRunner {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    runLoop(params) {
+        return this.runtime.runAgentLoop(params);
+    }
+}

package/node_modules/@ktx/context/dist/llm/runtime-tools.d.ts

@@ -0,0 +1,10 @@
+import { type Tool, type ToolSet } from 'ai';
+import { type SdkMcpToolDefinition } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import type { KtxRuntimeToolDescriptor, KtxRuntimeToolOutput, KtxRuntimeToolSet } from './runtime-port.js';
+export declare function normalizeKtxRuntimeToolOutput(value: unknown): KtxRuntimeToolOutput;
+export declare function createAiSdkToolSet(tools?: KtxRuntimeToolSet): ToolSet;
+export declare function createClaudeSdkTools(tools?: KtxRuntimeToolSet): Array<SdkMcpToolDefinition<z.ZodRawShape>>;
+export declare function mcpToolIds(tools?: KtxRuntimeToolSet): string[];
+export declare function createRuntimeToolDescriptorFromAiTool(name: string, aiSdkTool: Tool): KtxRuntimeToolDescriptor;
+export declare function createRuntimeToolSetFromAiSdkTools(tools?: ToolSet): KtxRuntimeToolSet;

package/node_modules/@ktx/context/dist/llm/runtime-tools.js

@@ -0,0 +1,68 @@
+import { tool as aiTool } from 'ai';
+import { tool as claudeTool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+function isRuntimeOutput(value) {
+    return Boolean(value &&
+        typeof value === 'object' &&
+        'markdown' in value &&
+        typeof value.markdown === 'string');
+}
+export function normalizeKtxRuntimeToolOutput(value) {
+    if (isRuntimeOutput(value)) {
+        return 'structured' in value ? { markdown: value.markdown, structured: value.structured } : { markdown: value.markdown };
+    }
+    if (typeof value === 'string') {
+        return { markdown: value };
+    }
+    return {
+        markdown: `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``,
+        structured: value,
+    };
+}
+function assertObjectSchema(name, schema) {
+    if (!(schema instanceof z.ZodObject)) {
+        throw new Error(`KTX runtime tool "${name}" must use z.object input schema for claude-code`);
+    }
+}
+export function createAiSdkToolSet(tools = {}) {
+    return Object.fromEntries(Object.entries(tools).map(([name, descriptor]) => [
+        name,
+        aiTool({
+            description: descriptor.description,
+            inputSchema: descriptor.inputSchema,
+            execute: async (input) => descriptor.execute(input),
+            toModelOutput: ({ output }) => {
+                const normalized = normalizeKtxRuntimeToolOutput(output);
+                return { type: 'text', value: normalized.markdown };
+            },
+        }),
+    ]));
+}
+export function createClaudeSdkTools(tools = {}) {
+    return Object.values(tools).map((descriptor) => {
+        assertObjectSchema(descriptor.name, descriptor.inputSchema);
+        return claudeTool(descriptor.name, descriptor.description, descriptor.inputSchema.shape, async (input) => {
+            const normalized = normalizeKtxRuntimeToolOutput(await descriptor.execute(input));
+            return { content: [{ type: 'text', text: normalized.markdown }] };
+        });
+    });
+}
+export function mcpToolIds(tools = {}) {
+    return Object.keys(tools).map((name) => `mcp__ktx__${name}`);
+}
+export function createRuntimeToolDescriptorFromAiTool(name, aiSdkTool) {
+    return {
+        name,
+        description: aiSdkTool.description ?? '',
+        inputSchema: aiSdkTool.inputSchema,
+        execute: async (input) => {
+            if (typeof aiSdkTool.execute !== 'function') {
+                throw new Error(`KTX runtime tool "${name}" has no execute function`);
+            }
+            return normalizeKtxRuntimeToolOutput(await aiSdkTool.execute(input, { toolCallId: `runtime-${name}` }));
+        },
+    };
+}
+export function createRuntimeToolSetFromAiSdkTools(tools = {}) {
+    return Object.fromEntries(Object.entries(tools).map(([name, aiSdkTool]) => [name, createRuntimeToolDescriptorFromAiTool(name, aiSdkTool)]));
+}

package/node_modules/@ktx/context/dist/llm/runtime-tools.test.d.ts

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

package/node_modules/@ktx/context/dist/llm/runtime-tools.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { createAiSdkToolSet, createClaudeSdkTools, normalizeKtxRuntimeToolOutput } from './runtime-tools.js';
+describe('runtime tool descriptors', () => {
+    const descriptor = {
+        name: 'read_thing',
+        description: 'Read one thing.',
+        inputSchema: z.object({ id: z.string() }),
+        execute: vi.fn(async (input) => ({
+            markdown: `Read ${input.id}`,
+            structured: { ok: true },
+        })),
+    };
+    it('normalizes string and object tool outputs into markdown plus optional structured payload', () => {
+        expect(normalizeKtxRuntimeToolOutput('plain text')).toEqual({ markdown: 'plain text' });
+        expect(normalizeKtxRuntimeToolOutput({ markdown: 'shown', structured: { id: 1 } })).toEqual({
+            markdown: 'shown',
+            structured: { id: 1 },
+        });
+        expect(normalizeKtxRuntimeToolOutput({ name: 'skill', content: 'body' })).toEqual({
+            markdown: '```json\n{\n  "name": "skill",\n  "content": "body"\n}\n```',
+            structured: { name: 'skill', content: 'body' },
+        });
+    });
+    it('builds AI SDK tools that expose markdown to the model', async () => {
+        const tools = createAiSdkToolSet({ read_thing: descriptor });
+        const output = await tools.read_thing.execute?.({ id: 'a' }, { toolCallId: 'call-1', messages: [] });
+        const modelOutput = tools.read_thing.toModelOutput?.({ output });
+        expect(modelOutput).toEqual({ type: 'text', value: 'Read a' });
+    });
+    it('builds Claude SDK tools that return text content only', async () => {
+        const tools = createClaudeSdkTools({ read_thing: descriptor });
+        const result = await tools[0].handler({ id: 'b' }, {});
+        expect(result).toEqual({ content: [{ type: 'text', text: 'Read b' }] });
+    });
+});

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

@@ -0,0 +1,9 @@
+import type { KtxMcpContextPorts, KtxMcpServerLike, KtxMcpToolResult, KtxMcpUserContext } from './types.js';
+export interface RegisterKtxContextToolsDeps {
+    server: KtxMcpServerLike;
+    ports: KtxMcpContextPorts;
+    userContext: KtxMcpUserContext;
+}
+export declare function jsonToolResult<T extends object>(structuredContent: T): KtxMcpToolResult<T>;
+export declare function jsonErrorToolResult(text: string): KtxMcpToolResult<Record<string, never>>;
+export declare function registerKtxContextTools(deps: RegisterKtxContextToolsDeps): void;