@sriinnu/kosha-discovery 1.1.0 → 1.5.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACN,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,uBAAuB,EACvB,2BAA2B,GAC3B,MAAM,yBAAyB,CAAC;AAgBjC,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC3G,OAAO,EACN,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,GAChB,MAAM,uBAAuB,CAAC;AAkC/B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAyC;IAC1E,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC1B,OAAO,QAAQ,CAAC;AACjB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACN,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,uBAAuB,EACvB,2BAA2B,GAC3B,MAAM,yBAAyB,CAAC;AAgBjC,OAAO,EACN,kBAAkB,EAClB,gBAAgB,GAChB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,GACnB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS9E,OAAO,EACN,kBAAkB,EAClB,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,EAC9B,qBAAqB,EACrB,qBAAqB,GACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACN,uBAAuB,EACvB,aAAa,EACb,gCAAgC,EAChC,0BAA0B,EAC1B,0BAA0B,EAC1B,mCAAmC,EACnC,2BAA2B,GAC3B,MAAM,qBAAqB,CAAC;AAa7B,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC3G,OAAO,EACN,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,GAChB,MAAM,uBAAuB,CAAC;AAkC/B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAyC;IAC1E,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC1B,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/mcp-server.d.ts

@@ -1,18 +1,223 @@
 #!/usr/bin/env node
 /**
- * kosha-discovery — MCP server (stdio transport, protocol 2024-11-05).
+ * kosha-discovery — MCP server (stdio transport).
  *
  * Exposes the local kosha registry as MCP tools so AI agents can query
  * model pricing, routing, and health without HTTP.
  *
+ * Protocol: JSON-RPC 2.0 over newline-delimited stdio. The server speaks
+ * every MCP revision in {@link MCP_PROTOCOL_VERSIONS} and echoes the
+ * client's requested revision back when it is one of them (otherwise it
+ * answers with the newest it supports, per the MCP negotiation rule).
+ *
  * Tools:
  *   kosha_query_models      — list / filter models
  *   kosha_cheapest_model    — cheapest model meeting requirements
+ *   kosha_ranked_routes     — strategy-ranked routes (cheapest / fastest / reliable / balanced)
  *   kosha_model_detail      — full detail for one model
  *   kosha_model_routes      — all provider routes for a model
  *   kosha_resolve_alias     — alias → canonical ID
  *   kosha_provider_health   — provider auth + error status
+ *   kosha_context_strategy  — context-management advice for a long conversation
+ *
+ * The JSON-RPC handler ({@link handleJsonRpc}) is exported and pure over an
+ * injected registry loader so it can be unit-tested; the stdio loop only
+ * starts when this file is the process entry point.
  * @module
  */
-export {};
+import { ModelRegistry } from "./registry.js";
+/** Package version, read from package.json so `serverInfo.version` never drifts from the release. */
+export declare const KOSHA_MCP_VERSION: string;
+/** MCP protocol revisions this server implements, newest first. */
+export declare const MCP_PROTOCOL_VERSIONS: readonly string[];
+/**
+ * Pick the protocol revision to answer an `initialize` with: the client's
+ * own when we support it, otherwise our newest (the client then decides
+ * whether to proceed).
+ */
+export declare function negotiateProtocolVersion(requested: unknown): string;
+export interface JsonRpcMessage {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export declare const TOOLS: readonly [{
+    readonly name: "kosha_query_models";
+    readonly description: "List AI models from the local kosha registry. Optionally filter by provider, mode, or capability tag. Returns id, provider, name, mode, context window, capabilities, and pricing.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly provider: {
+                readonly type: "string";
+                readonly description: "Provider ID (e.g. anthropic, openai, groq, openrouter)";
+            };
+            readonly mode: {
+                readonly type: "string";
+                readonly enum: readonly ["chat", "embedding", "image", "video", "audio", "moderation", "rerank"];
+                readonly description: "Primary model mode";
+            };
+            readonly capability: {
+                readonly type: "string";
+                readonly description: "Capability tag (e.g. vision, tool_use, code, reasoning)";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Max results to return (default 20)";
+            };
+        };
+    };
+}, {
+    readonly name: "kosha_cheapest_model";
+    readonly description: "Find the cheapest AI model that meets your requirements. Returns ranked matches with per-million token pricing. Use this before routing a request to pick the most cost-effective option.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly capability: {
+                readonly type: "string";
+                readonly description: "Required capability (e.g. tool_use, vision, code, reasoning)";
+            };
+            readonly min_context_k: {
+                readonly type: "number";
+                readonly description: "Minimum context window in thousands of tokens (e.g. 128 means 128k)";
+            };
+            readonly provider: {
+                readonly type: "string";
+                readonly description: "Pin to a specific provider";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Number of ranked results (default 5)";
+            };
+        };
+    };
+}, {
+    readonly name: "kosha_ranked_routes";
+    readonly description: "Rank chat-model routes by strategy: cheapest (price only), fastest (observed p95 latency), reliable (circuit-breaker state plus timeout / auth-error history), or balanced (weighted blend of all three). Providers whose breaker is open always sort last, so the result doubles as a failover order. Accepts the same filters as kosha_cheapest_model.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly strategy: {
+                readonly type: "string";
+                readonly enum: readonly ["cheapest", "fastest", "reliable", "balanced"];
+                readonly description: "Ranking strategy";
+            };
+            readonly capability: {
+                readonly type: "string";
+                readonly description: "Required capability tag (e.g. tool_use, vision)";
+            };
+            readonly min_context_k: {
+                readonly type: "number";
+                readonly description: "Minimum context window in thousands of tokens";
+            };
+            readonly provider: {
+                readonly type: "string";
+                readonly description: "Pin to a specific provider";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Number of ranked results (default 5)";
+            };
+        };
+        readonly required: readonly ["strategy"];
+    };
+}, {
+    readonly name: "kosha_model_detail";
+    readonly description: "Get full details for a specific model — pricing, capabilities, context window, tool dialect, structured output modes, status, and deprecation info.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly model: {
+                readonly type: "string";
+                readonly description: "Model ID or alias (e.g. sonnet, claude-sonnet-5, gpt-4o, deepseek-v3)";
+            };
+        };
+        readonly required: readonly ["model"];
+    };
+}, {
+    readonly name: "kosha_model_routes";
+    readonly description: "List all serving-layer routes for a model (direct provider, OpenRouter, Bedrock, Vertex, etc.) with pricing per route. Useful for finding the cheapest or most available path to a specific model.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly model: {
+                readonly type: "string";
+                readonly description: "Model ID or alias";
+            };
+        };
+        readonly required: readonly ["model"];
+    };
+}, {
+    readonly name: "kosha_resolve_alias";
+    readonly description: "Resolve a model alias or short name to its canonical ID and provider.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly alias: {
+                readonly type: "string";
+                readonly description: "Short name or alias (e.g. sonnet, opus, haiku, gpt-4o-mini, gemini-flash)";
+            };
+        };
+        readonly required: readonly ["alias"];
+    };
+}, {
+    readonly name: "kosha_provider_health";
+    readonly description: "Get authentication and health status for all discovered providers. Shows which providers are active, which need credentials, and any recent discovery errors.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly provider: {
+                readonly type: "string";
+                readonly description: "Filter to a specific provider ID";
+            };
+        };
+    };
+}, {
+    readonly name: "kosha_context_strategy";
+    readonly description: "Advise on context management for a long-running conversation. Given a model and current token usage, returns ranked options (continue, enable prompt cache, compact + continue, switch to long-context tier, switch model, batch offload) with rough cost-per-turn math. Useful before deciding whether to summarize, swap models, or just keep going.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly model: {
+                readonly type: "string";
+                readonly description: "Model ID or alias the caller is currently using";
+            };
+            readonly current_tokens: {
+                readonly type: "number";
+                readonly description: "Approximate token count of the conversation so far";
+            };
+            readonly expected_output_tokens: {
+                readonly type: "number";
+                readonly description: "Tokens the next reply is expected to produce (default 1024)";
+            };
+            readonly expected_remaining_turns: {
+                readonly type: "number";
+                readonly description: "How many more turns the caller plans (default 5)";
+            };
+        };
+        readonly required: readonly ["model", "current_tokens"];
+    };
+}];
+/** Dependencies the JSON-RPC handler needs; injected so tests can supply a fixture registry. */
+export interface McpDeps {
+    registry: () => Promise<ModelRegistry>;
+}
+export declare function callTool(name: string, args: Record<string, unknown>, deps?: McpDeps): Promise<unknown>;
+/**
+ * Handle one JSON-RPC request and return the response, or `null` for
+ * notifications (which carry no id and expect no reply).
+ *
+ * Tool *execution* failures come back as a successful `tools/call` result
+ * with `isError: true`, per the MCP spec, so the model can read the message
+ * and recover; only protocol-level problems (unknown method, unknown tool,
+ * malformed params) surface as JSON-RPC errors.
+ */
+export declare function handleJsonRpc(msg: JsonRpcMessage, deps?: McpDeps): Promise<JsonRpcMessage | null>;
+/** Start the newline-delimited JSON-RPC loop over stdio. */
+export declare function runStdioServer(deps?: McpDeps): void;
 //# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server.js

@@ -1,24 +1,71 @@
 #!/usr/bin/env node
 /**
- * kosha-discovery — MCP server (stdio transport, protocol 2024-11-05).
+ * kosha-discovery — MCP server (stdio transport).
  *
  * Exposes the local kosha registry as MCP tools so AI agents can query
  * model pricing, routing, and health without HTTP.
  *
+ * Protocol: JSON-RPC 2.0 over newline-delimited stdio. The server speaks
+ * every MCP revision in {@link MCP_PROTOCOL_VERSIONS} and echoes the
+ * client's requested revision back when it is one of them (otherwise it
+ * answers with the newest it supports, per the MCP negotiation rule).
+ *
  * Tools:
  *   kosha_query_models      — list / filter models
  *   kosha_cheapest_model    — cheapest model meeting requirements
+ *   kosha_ranked_routes     — strategy-ranked routes (cheapest / fastest / reliable / balanced)
  *   kosha_model_detail      — full detail for one model
  *   kosha_model_routes      — all provider routes for a model
  *   kosha_resolve_alias     — alias → canonical ID
  *   kosha_provider_health   — provider auth + error status
+ *   kosha_context_strategy  — context-management advice for a long conversation
+ *
+ * The JSON-RPC handler ({@link handleJsonRpc}) is exported and pure over an
+ * injected registry loader so it can be unit-tested; the stdio loop only
+ * starts when this file is the process entry point.
  * @module
  */
+import { createRequire } from "node:module";
+import { computeContextStrategy } from "./context-strategy.js";
+import { isMainModule } from "./entry.js";
 import { ModelRegistry } from "./registry.js";
+import { parseRouteStrategy, ROUTE_STRATEGIES } from "./registry-routing.js";
+// ---------------------------------------------------------------------------
+// Server identity + protocol negotiation
+// ---------------------------------------------------------------------------
+/** Package version, read from package.json so `serverInfo.version` never drifts from the release. */
+export const KOSHA_MCP_VERSION = (() => {
+    try {
+        const require = createRequire(import.meta.url);
+        return require("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+/** MCP protocol revisions this server implements, newest first. */
+export const MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+/**
+ * Pick the protocol revision to answer an `initialize` with: the client's
+ * own when we support it, otherwise our newest (the client then decides
+ * whether to proceed).
+ */
+export function negotiateProtocolVersion(requested) {
+    if (typeof requested === "string" && MCP_PROTOCOL_VERSIONS.includes(requested))
+        return requested;
+    return MCP_PROTOCOL_VERSIONS[0];
+}
+/** Standard JSON-RPC 2.0 error codes used by this server. */
+const JSON_RPC = {
+    PARSE_ERROR: -32700,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+};
 // ---------------------------------------------------------------------------
 // Tool definitions (MCP schema)
 // ---------------------------------------------------------------------------
-const TOOLS = [
+export const TOOLS = [
     {
         name: "kosha_query_models",
         description: "List AI models from the local kosha registry. Optionally filter by provider, mode, or capability tag. Returns id, provider, name, mode, context window, capabilities, and pricing.",
@@ -28,7 +75,7 @@ const TOOLS = [
                 provider: { type: "string", description: "Provider ID (e.g. anthropic, openai, groq, openrouter)" },
                 mode: {
                     type: "string",
-                    enum: ["chat", "embedding", "image", "audio"],
+                    enum: ["chat", "embedding", "image", "video", "audio", "moderation", "rerank"],
                     description: "Primary model mode",
                 },
                 capability: {
@@ -58,6 +105,25 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "kosha_ranked_routes",
+        description: "Rank chat-model routes by strategy: cheapest (price only), fastest (observed p95 latency), reliable (circuit-breaker state plus timeout / auth-error history), or balanced (weighted blend of all three). Providers whose breaker is open always sort last, so the result doubles as a failover order. Accepts the same filters as kosha_cheapest_model.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                strategy: {
+                    type: "string",
+                    enum: ["cheapest", "fastest", "reliable", "balanced"],
+                    description: "Ranking strategy",
+                },
+                capability: { type: "string", description: "Required capability tag (e.g. tool_use, vision)" },
+                min_context_k: { type: "number", description: "Minimum context window in thousands of tokens" },
+                provider: { type: "string", description: "Pin to a specific provider" },
+                limit: { type: "number", description: "Number of ranked results (default 5)" },
+            },
+            required: ["strategy"],
+        },
+    },
     {
         name: "kosha_model_detail",
         description: "Get full details for a specific model — pricing, capabilities, context window, tool dialect, structured output modes, status, and deprecation info.",
@@ -66,7 +132,7 @@ const TOOLS = [
             properties: {
                 model: {
                     type: "string",
-                    description: "Model ID or alias (e.g. sonnet, claude-sonnet-4-6, gpt-4o, deepseek-v3)",
+                    description: "Model ID or alias (e.g. sonnet, claude-sonnet-5, gpt-4o, deepseek-v3)",
                 },
             },
             required: ["model"],
@@ -107,25 +173,51 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "kosha_context_strategy",
+        description: "Advise on context management for a long-running conversation. Given a model and current token usage, returns ranked options (continue, enable prompt cache, compact + continue, switch to long-context tier, switch model, batch offload) with rough cost-per-turn math. Useful before deciding whether to summarize, swap models, or just keep going.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                model: { type: "string", description: "Model ID or alias the caller is currently using" },
+                current_tokens: { type: "number", description: "Approximate token count of the conversation so far" },
+                expected_output_tokens: {
+                    type: "number",
+                    description: "Tokens the next reply is expected to produce (default 1024)",
+                },
+                expected_remaining_turns: {
+                    type: "number",
+                    description: "How many more turns the caller plans (default 5)",
+                },
+            },
+            required: ["model", "current_tokens"],
+        },
+    },
 ];
-// ---------------------------------------------------------------------------
-// Registry — load in background on startup so first tool call is fast
-// ---------------------------------------------------------------------------
 let registryInstance = null;
-const registryReady = (async () => {
+let registryReady = null;
+async function loadRegistry() {
     const reg = new ModelRegistry();
     await reg.discover();
     registryInstance = reg;
     return reg;
-})();
+}
 async function getRegistry() {
-    return registryInstance ?? registryReady;
+    if (registryInstance)
+        return registryInstance;
+    registryReady ??= loadRegistry();
+    return registryReady;
+}
+/** Production dependencies: the discover-on-first-use registry. */
+const defaultDeps = { registry: getRegistry };
+/** Thrown by a tool handler for caller mistakes (unknown tool, bad argument). */
+class ToolInputError extends Error {
 }
 // ---------------------------------------------------------------------------
 // Tool handlers
 // ---------------------------------------------------------------------------
-async function callTool(name, args) {
-    const reg = await getRegistry();
+export async function callTool(name, args, deps = defaultDeps) {
+    const reg = await deps.registry();
     switch (name) {
         case "kosha_query_models": {
             const models = reg.models({
@@ -168,6 +260,43 @@ async function callTool(name, args) {
                 missingCredentials: result.missingCredentials.map((c) => c.providerId),
             };
         }
+        case "kosha_ranked_routes": {
+            const strategy = parseRouteStrategy(typeof args.strategy === "string" ? args.strategy : undefined);
+            if (!strategy) {
+                throw new ToolInputError(`unknown strategy '${String(args.strategy)}' — expected one of ${ROUTE_STRATEGIES.join(", ")}`);
+            }
+            const limit = typeof args.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : 5;
+            const minContext = typeof args.min_context_k === "number" ? args.min_context_k * 1_000 : undefined;
+            const ranked = reg.rankedRoutes({
+                mode: "chat",
+                capability: args.capability,
+                provider: args.provider,
+                // Over-fetch so a min-context filter applied after ranking
+                // still has enough candidates to fill `limit`.
+                limit: Math.max(limit * 4, 20),
+            }, strategy);
+            const filtered = minContext ? ranked.filter((r) => r.model.contextWindow >= minContext) : ranked;
+            return {
+                strategy,
+                routes: filtered.slice(0, limit).map((r) => ({
+                    id: r.model.id,
+                    provider: r.providerId,
+                    name: r.model.name,
+                    contextWindow: r.model.contextWindow,
+                    pricing: r.model.pricing ?? null,
+                    price: r.price,
+                    compositeScore: r.compositeScore,
+                    health: {
+                        available: r.health.available,
+                        breakerState: r.health.breakerState,
+                        reliabilityScore: r.health.reliabilityScore,
+                        p95LatencyMs: r.health.p95LatencyMs,
+                        samples: r.health.samples,
+                        lastErrorType: r.health.lastErrorType,
+                    },
+                })),
+            };
+        }
         case "kosha_model_detail": {
             const model = reg.model(args.model);
             if (!model)
@@ -221,73 +350,144 @@ async function callTool(name, args) {
                 lastError: errorByProvider.get(p.id) ?? null,
             }));
         }
+        case "kosha_context_strategy": {
+            const modelId = args.model;
+            if (!modelId)
+                return { error: "model is required" };
+            const currentTokens = typeof args.current_tokens === "number" ? args.current_tokens : undefined;
+            if (currentTokens === undefined || currentTokens < 0) {
+                return { error: "current_tokens must be a non-negative number" };
+            }
+            const model = reg.model(modelId);
+            if (!model)
+                return { error: `model '${modelId}' not found` };
+            const candidates = reg
+                .cheapestModels({ mode: "chat", limit: 20 })
+                .matches.map((m) => m.model);
+            return computeContextStrategy({
+                model,
+                currentTokens,
+                expectedRemainingTurns: typeof args.expected_remaining_turns === "number" ? args.expected_remaining_turns : undefined,
+                expectedOutputTokens: typeof args.expected_output_tokens === "number" ? args.expected_output_tokens : undefined,
+                candidateAlternatives: candidates,
+            });
+        }
         default:
-            throw new Error(`unknown tool: ${name}`);
+            throw new ToolInputError(`unknown tool: ${name}`);
     }
 }
 // ---------------------------------------------------------------------------
-// Stdio JSON-RPC loop
+// JSON-RPC dispatch (pure) + stdio loop (entry point only)
 // ---------------------------------------------------------------------------
-function send(msg) {
-    process.stdout.write(JSON.stringify(msg) + "\n");
+function ok(id, result) {
+    return { jsonrpc: "2.0", id: id ?? null, result };
 }
-function respond(id, result) {
-    send({ jsonrpc: "2.0", id: id ?? null, result });
+function fail(id, code, message) {
+    return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
 }
-function respondError(id, code, message) {
-    send({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
-}
-async function handleMessage(msg) {
+/**
+ * Handle one JSON-RPC request and return the response, or `null` for
+ * notifications (which carry no id and expect no reply).
+ *
+ * Tool *execution* failures come back as a successful `tools/call` result
+ * with `isError: true`, per the MCP spec, so the model can read the message
+ * and recover; only protocol-level problems (unknown method, unknown tool,
+ * malformed params) surface as JSON-RPC errors.
+ */
+export async function handleJsonRpc(msg, deps = defaultDeps) {
     const { id, method, params } = msg;
     // Notifications carry no id — no response expected.
     if (!method || method.startsWith("notifications/"))
-        return;
+        return null;
     switch (method) {
-        case "initialize":
-            respond(id, {
-                protocolVersion: "2024-11-05",
+        case "initialize": {
+            const requested = params?.protocolVersion;
+            return ok(id, {
+                protocolVersion: negotiateProtocolVersion(requested),
                 capabilities: { tools: {} },
-                serverInfo: { name: "kosha", version: "1.0.0" },
+                serverInfo: { name: "kosha", version: KOSHA_MCP_VERSION },
             });
-            return;
+        }
+        case "ping":
+            return ok(id, {});
         case "tools/list":
-            respond(id, { tools: TOOLS });
-            return;
+            return ok(id, { tools: TOOLS });
         case "tools/call": {
-            const { name, arguments: args = {} } = params;
+            const call = (params ?? {});
+            if (typeof call.name !== "string") {
+                return fail(id, JSON_RPC.INVALID_PARAMS, "tools/call requires a string `name`");
+            }
+            const args = call.arguments && typeof call.arguments === "object" && !Array.isArray(call.arguments)
+                ? call.arguments
+                : {};
             try {
-                const result = await callTool(name, args);
-                respond(id, { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });
+                const result = await callTool(call.name, args, deps);
+                return ok(id, { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                respondError(id, -32603, message);
+                if (err instanceof ToolInputError)
+                    return fail(id, JSON_RPC.INVALID_PARAMS, message);
+                return ok(id, { content: [{ type: "text", text: message }], isError: true });
             }
-            return;
         }
         default:
-            respondError(id, -32601, `method not found: ${method}`);
+            return fail(id, JSON_RPC.METHOD_NOT_FOUND, `method not found: ${method}`);
     }
 }
-let buffer = "";
-process.stdin.setEncoding("utf-8");
-process.stdin.on("data", (chunk) => {
-    buffer += chunk;
-    const lines = buffer.split("\n");
-    buffer = lines.pop() ?? "";
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        try {
-            handleMessage(JSON.parse(trimmed)).catch((err) => {
+function send(msg) {
+    process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+/** Start the newline-delimited JSON-RPC loop over stdio. */
+export function runStdioServer(deps = defaultDeps) {
+    let buffer = "";
+    /** In-flight requests, so an EOF on stdin waits for their answers before exiting. */
+    const pending = new Set();
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => {
+        buffer += chunk;
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                // Malformed JSON. Per JSON-RPC 2.0 we must still answer with a
+                // -32700 Parse error so the client doesn't block forever waiting
+                // on a response. The id is unknowable from unparseable input, so
+                // per spec we respond with id=null (we deliberately avoid scanning
+                // the raw text for an id, which would mean running a regex over
+                // uncontrolled stdin).
+                send(fail(null, JSON_RPC.PARSE_ERROR, "Parse error"));
+                continue;
+            }
+            const job = handleJsonRpc(parsed, deps)
+                .then((response) => {
+                if (response)
+                    send(response);
+            })
+                .catch((err) => {
                 process.stderr.write(`[kosha-mcp] ${err}\n`);
+            })
+                .finally(() => {
+                pending.delete(job);
             });
+            pending.add(job);
         }
-        catch {
-            // malformed JSON — ignore
-        }
-    }
-});
-process.stdin.on("end", () => process.exit(0));
+    });
+    // One-shot / piped clients half-close stdin right after writing their
+    // request; exiting immediately would drop the answer still being computed.
+    process.stdin.on("end", () => {
+        Promise.allSettled(pending).then(() => process.exit(0));
+    });
+}
+// Only attach to stdio when executed directly (`kosha-mcp` bin or
+// `node dist/mcp-server.js`); see entry.ts for why realpath matters.
+if (isMainModule(import.meta.url))
+    runStdioServer();
 //# sourceMappingURL=mcp-server.js.map