@sayknow-cli/coding-agent 0.3.16 → 0.4.1

package/src/prompts/tools/lsp.md

@@ -1,7 +1,7 @@
 Interacts with Language Server Protocol servers for code intelligence.
 
 <operations>
-- `diagnostics`: Get errors/warnings for a file, a glob of files, or the entire workspace (`file: "*"`)
+- `diagnostics`: Get errors/warnings for a concrete file or a glob of files
 - `definition`: Go to symbol definition → file path + position + 3-line source context
 - `type_definition`: Go to symbol type definition → file path + position + 3-line source context
 - `implementation`: Find concrete implementations → file path + position + 3-line source context
@@ -18,7 +18,7 @@ Interacts with Language Server Protocol servers for code intelligence.
 </operations>
 
 <parameters>
-- `file`: File path, glob pattern (e.g. `src/**/*.ts`), or `"*"` for workspace scope. Globs are expanded locally before dispatch. `"*"` routes `diagnostics`/`symbols`/`reload` to their workspace-wide form.
+- `file`: File path, glob pattern (e.g. `src/**/*.ts`), or `"*"` for workspace scope where supported. Globs are expanded locally before dispatch. `"*"` routes `symbols`/`reload` to their workspace-wide form; workspace build diagnostics are unavailable through `lsp`.
 - `line`: 1-indexed line number for position-based actions
 - `symbol`: Substring on the target line used to resolve column automatically. Append `#N` to pick the Nth occurrence on that line (1-indexed; default 1) — e.g. `foo#2` selects the second `foo`.
 - `query`: Symbol search query, code-action kind filter / selector (list/apply mode), or LSP method name when `action: request`
@@ -31,7 +31,7 @@ Interacts with Language Server Protocol servers for code intelligence.
 <caution>
 - Requires running LSP server for target language
 - Some operations require file to be saved to disk
-- Glob expansion samples up to 20 files per request; use `file: "*"` for broader coverage
+- Glob expansion samples up to 20 files per request; narrow broad patterns when they exceed that limit
 - When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `#N` occurrence selectors return an explicit error instead of silently falling back
 </caution>
 

package/src/prompts/tools/read.md

@@ -73,10 +73,7 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 `agent://<id>`, `artifact://<id>`, `rule://<name>`, and `local://<name>.md` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.
 
 <critical>
-- You MUST use `read` for every file, directory, archive, and URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN — any such bash call is a bug, regardless of how short or convenient it looks.
-- You MUST prefer `read` over a browser/puppeteer tool for URL content; only reach for a browser when `read` cannot deliver reasonable content.
-- You MUST always include `path`. NEVER call `read` with `{}`.
-- For line ranges, append the selector to `path` (`path="src/foo.ts:50-200"`, `path="src/foo.ts:50+150"`). NEVER substitute `sed -n`, `awk NR`, or `head`/`tail` pipelines.
-- Summary footer says `read <path>:raw …`? Re-issue the exact selector it names. NEVER guess what's inside `..` / `…` markers — they carry no content.
-- You MAY combine selectors with URL reads and internal URIs; both paginate the cached resolved output.
+- Always include `path`; never call `read` with `{}`.
+- For line ranges, append the selector to `path`.
+- Re-issue the selector named by a summary footer before relying on elided content.
 </critical>

package/src/prompts/tools/search-tool-bm25.md

@@ -1,8 +1,6 @@
 Search hidden tool metadata to discover and activate tools.
 
 Activate hidden tools (MCP and built-in) when you need a capability not in your active tool set.
-{{#if hasDiscoverableMCPServers}}Discoverable MCP servers in this session: {{#list discoverableMCPServerSummaries join=", "}}{{this}}{{/list}}.{{/if}}
-{{#if discoverableMCPToolCount}}Total discoverable tools available: {{discoverableMCPToolCount}}.{{/if}}
 Input:
 - `query` — required natural-language or keyword query
 - `limit` — optional maximum number of tools to return and activate (default `8`; start with 5–10 if unsure)

package/src/prompts/tools/search.md

@@ -18,8 +18,6 @@ Searches files using powerful regex matching.
 </output>
 
 <critical>
-- You MUST use the built-in `search` tool for any content search. NEVER shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
-- Bash `grep`/`rg` loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The `search` tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
-- If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the lookup through the `search` tool instead.
-- If the search is open-ended and requires multiple rounds across subsystems, delegate a bounded fact-finding task to an appropriate canonical role agent (`planner` for sequencing/context maps or `architect` for read-only architecture assessment) instead of chaining broad `search` calls yourself.
+- Search paths are an array; pass separate entries rather than comma-joined paths.
+- Use a cross-line pattern only when the match actually spans lines.
 </critical>

package/src/prompts/tools/skill-discovery.md

@@ -1,8 +1,7 @@
 Discover project and user runtime skills without loading full skill content.
 
 <instruction>
-- Searches only custom runtime skill locations: project `.skc/skills` and user `~/.skc/skills`.
-- Built-in, bundled, and internal workflow skills are intentionally excluded.
+- Searches only custom runtime skill locations: nearest project `.skc/skills`; then, under the home directory, canonical `<config>/agent/skills`, configured legacy `<config>/skills`, and historical legacy `.skc/skills`. `<config>` is the home-relative directory name from `SKC_CONFIG_DIR`, then `PI_CONFIG_DIR`, then `.skc`; even an absolute-looking configured name is joined beneath `<home>`. Duplicate names use that exact precedence. Built-in, bundled, and internal workflow skills are intentionally excluded.
 - Returns thin metadata only: name, description, source scope, path, and use conditions when present.
 - To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.
 </instruction>

package/src/prompts/tools/task.md

@@ -7,7 +7,7 @@ Launches subagents to parallelize workflows.
 {{else}}
 - Use `subagent` action `inspect` or `list` to snapshot manager state.
 {{/if}}
-- To wait or cancel, use the `subagent` tool; its await/cancel doctrine applies (never cancel just because an await timed out).
+- To wait or cancel, use the `subagent` tool; its await/cancel doctrine is authoritative.
 
 {{#if ircEnabled}}
 Subagents have no conversation history, but they can reach you and their siblings live via the `irc` tool. Front-load every fact, file path, and direction they need in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.

package/src/runtime-mcp/client.ts

@@ -35,6 +35,7 @@ import type {
 	MCPToolsListResult,
 	MCPTransport,
 } from "./types";
+import { MCPExpectedFailure } from "./types";
 
 /** MCP protocol version we support */
 const PROTOCOL_VERSION = "2025-03-26";
@@ -47,6 +48,66 @@ const CLIENT_INFO = {
 	name: "skc-coding-agent",
 	version: "1.0.0",
 };
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function decodeInitializeResult(value: unknown): MCPInitializeResult {
+	if (
+		!isRecord(value) ||
+		typeof value.protocolVersion !== "string" ||
+		!isRecord(value.capabilities) ||
+		!isRecord(value.serverInfo) ||
+		typeof value.serverInfo.name !== "string" ||
+		typeof value.serverInfo.version !== "string" ||
+		(value.instructions !== undefined && typeof value.instructions !== "string")
+	) {
+		throw new MCPExpectedFailure();
+	}
+
+	return {
+		protocolVersion: value.protocolVersion,
+		capabilities: value.capabilities as MCPServerCapabilities,
+		serverInfo: {
+			name: value.serverInfo.name,
+			version: value.serverInfo.version,
+		},
+		...(value.instructions === undefined ? {} : { instructions: value.instructions }),
+	};
+}
+
+function decodeToolsListResult(value: unknown): MCPToolsListResult {
+	if (
+		!isRecord(value) ||
+		!Array.isArray(value.tools) ||
+		(value.nextCursor !== undefined && typeof value.nextCursor !== "string")
+	) {
+		throw new MCPExpectedFailure();
+	}
+
+	const tools = value.tools.map(tool => {
+		if (
+			!isRecord(tool) ||
+			typeof tool.name !== "string" ||
+			!isRecord(tool.inputSchema) ||
+			tool.inputSchema.type !== "object" ||
+			(tool.inputSchema.properties !== undefined && !isRecord(tool.inputSchema.properties)) ||
+			(tool.inputSchema.required !== undefined &&
+				(!Array.isArray(tool.inputSchema.required) ||
+					!tool.inputSchema.required.every(item => typeof item === "string"))) ||
+			(tool.description !== undefined && typeof tool.description !== "string")
+		) {
+			throw new MCPExpectedFailure();
+		}
+		return {
+			name: tool.name,
+			inputSchema: { ...tool.inputSchema, type: "object" as const },
+			...(tool.description === undefined ? {} : { description: tool.description }),
+		};
+	});
+
+	return value.nextCursor === undefined ? { tools } : { tools, nextCursor: value.nextCursor };
+}
 
 /**
  * Default handler for standard MCP server-to-client requests.
@@ -93,22 +154,22 @@ async function initializeConnection(
 	transport: MCPTransport,
 	options?: {
 		signal?: AbortSignal;
+		/** Whether to advertise the roots/list capability (default: true). */
+		advertiseRoots?: boolean;
 		/** Called after the initialize response (which sets the session ID) but before notifications/initialized. */
 		onInitialized?: () => void | Promise<void>;
 	},
 ): Promise<MCPInitializeResult> {
 	const params: MCPInitializeParams = {
 		protocolVersion: PROTOCOL_VERSION,
-		capabilities: {
-			roots: { listChanged: false },
-		},
+		capabilities: options?.advertiseRoots === false ? {} : { roots: { listChanged: false } },
 		clientInfo: CLIENT_INFO,
 	};
 
-	const result = await transport.request<MCPInitializeResult>(
-		"initialize",
-		params as unknown as Record<string, unknown>,
-		{ signal: options?.signal },
+	const result = decodeInitializeResult(
+		await transport.request<unknown>("initialize", params as unknown as Record<string, unknown>, {
+			signal: options?.signal,
+		}),
 	);
 
 	if (options?.signal?.aborted) {
@@ -135,6 +196,8 @@ export async function connectToServer(
 	config: MCPServerConfig,
 	options?: {
 		signal?: AbortSignal;
+		/** Whether to advertise the roots/list capability (default: true). */
+		advertiseRoots?: boolean;
 		onNotification?: (method: string, params: unknown) => void;
 		onRequest?: (method: string, params: unknown) => Promise<unknown>;
 	},
@@ -150,14 +213,14 @@ export async function connectToServer(
 			transport.onNotification = options.onNotification;
 		}
 
-		// Always handle standard MCP server-to-client requests (ping, roots/list).
-		// The initialize request declares roots capability, so we must respond to
-		// roots/list — even for short-lived test connections.
+		// Always install a handler for standard MCP server-to-client requests.
+		// Callers that do not advertise roots can reject roots/list via onRequest.
 		transport.onRequest = options?.onRequest ?? defaultRequestHandler;
 
 		try {
 			const initResult = await initializeConnection(transport, {
 				signal: connectSignal,
+				advertiseRoots: options?.advertiseRoots,
 				async onInitialized() {
 					// Open the SSE stream before sending initialized, so server-to-client
 					// requests triggered by on_initialized (e.g. roots/list) are delivered.
@@ -176,24 +239,36 @@ export async function connectToServer(
 				instructions: initResult.instructions,
 			};
 		} catch (error) {
-			await transport.close();
+			try {
+				await transport.close();
+			} catch {
+				// Preserve the initialization failure when cleanup also fails.
+			}
 			throw error;
 		}
 	};
 
+	const connectionTimeoutMessage = `Connection to MCP server "${name}" timed out after ${timeoutMs}ms`;
+
 	try {
-		return await withTimeout(
-			connect(),
-			timeoutMs,
-			`Connection to MCP server "${name}" timed out after ${timeoutMs}ms`,
-			connectSignal,
-		);
+		return await withTimeout(connect(), timeoutMs, connectionTimeoutMessage, connectSignal);
 	} catch (error) {
 		// If withTimeout rejected (timeout/abort) while connect() was still pending,
 		// abort initialization and wait for transport cleanup before returning.
+		const aborted = options?.signal?.aborted === true;
 		connectAbort.abort(error);
 		if (transport) {
-			await transport.close().catch(() => {});
+			try {
+				await transport.close();
+			} catch {
+				// Preserve the primary connection failure when cleanup also fails.
+			}
+		}
+		if (error instanceof MCPExpectedFailure) {
+			throw error;
+		}
+		if (aborted || (error instanceof Error && error.message === connectionTimeoutMessage)) {
+			throw new MCPExpectedFailure(error);
 		}
 		throw error;
 	}
@@ -225,7 +300,7 @@ export async function listTools(
 			params.cursor = cursor;
 		}
 
-		const result = await connection.transport.request<MCPToolsListResult>("tools/list", params, options);
+		const result = decodeToolsListResult(await connection.transport.request<unknown>("tools/list", params, options));
 		allTools.push(...result.tools);
 		cursor = result.nextCursor;
 	} while (cursor);

package/src/runtime-mcp/config.ts

@@ -9,6 +9,7 @@ import { mcpCapability } from "../capability/mcp";
 import type { SourceMeta } from "../capability/types";
 import type { MCPServer } from "../discovery";
 import { loadCapability } from "../discovery";
+import { loadMCPJsonFile } from "../discovery/mcp-json";
 import { readDisabledServers } from "./config-writer";
 import type { MCPServerConfig } from "./types";
 
@@ -20,8 +21,10 @@ export interface LoadMCPConfigsOptions {
 	filterExa?: boolean;
 	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
 	filterBrowser?: boolean;
-	/** Only include servers eligible for startup connection, i.e. autoload !== false (default: false) */
+	/** Only include startup-eligible servers; exact-config sessions always enforce autoload !== false. */
 	autoloadOnly?: boolean;
+	/** Load only this explicit MCP config file. */
+	configPath?: string;
 }
 
 /** Result of loading MCP configs */
@@ -32,6 +35,8 @@ export interface LoadMCPConfigsResult {
 	exaApiKeys: string[];
 	/** Source metadata for each server */
 	sources: Record<string, SourceMeta>;
+	/** Whether the explicit configuration was unavailable or contained invalid entries. */
+	configurationWarning: boolean;
 }
 
 /**
@@ -97,21 +102,28 @@ function convertToLegacyConfig(server: MCPServer): MCPServerConfig {
  * @param options Load options
  */
 export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOptions): Promise<LoadMCPConfigsResult> {
+	const exactConfig = options?.configPath !== undefined;
 	const enableProjectConfig = options?.enableProjectConfig ?? true;
-	const filterExa = options?.filterExa ?? true;
-	const filterBrowser = options?.filterBrowser ?? false;
-	const autoloadOnly = options?.autoloadOnly ?? false;
-
-	// Load MCP servers via capability system
-	const result = await loadCapability<MCPServer>(mcpCapability.id, { cwd });
-
-	// Filter out project-level configs if disabled
-	const servers = enableProjectConfig
-		? result.items
-		: result.items.filter(server => server._source.level !== "project");
+	const filterExa = exactConfig ? false : (options?.filterExa ?? true);
+	const filterBrowser = exactConfig ? false : (options?.filterBrowser ?? false);
+	const autoloadOnly = exactConfig || (options?.autoloadOnly ?? false);
+
+	let servers: MCPServer[];
+	let disabledServers: Set<string>;
+	let configurationWarning = false;
+	if (exactConfig) {
+		const result = await loadMCPJsonFile(options.configPath!, "project", { quiet: true });
+		servers = result.items;
+		disabledServers = new Set(result.disabledServers);
+		configurationWarning = (result.warnings?.length ?? 0) > 0;
+	} else {
+		// Load MCP servers via capability system
+		const result = await loadCapability<MCPServer>(mcpCapability.id, { cwd });
+		// Filter out project-level configs if disabled
+		servers = enableProjectConfig ? result.items : result.items.filter(server => server._source.level !== "project");
+		disabledServers = new Set(await readDisabledServers(getMCPConfigPath("user", cwd)));
+	}
 
-	// Load user-level disabled servers list
-	const disabledServers = new Set(await readDisabledServers(getMCPConfigPath("user", cwd)));
 	// Convert to legacy format and preserve source metadata
 	let configs: Record<string, MCPServerConfig> = {};
 	let sources: Record<string, SourceMeta> = {};
@@ -142,7 +154,7 @@ export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOpt
 		sources = browserResult.sources;
 	}
 
-	return { configs, exaApiKeys, sources };
+	return { configs, exaApiKeys, sources, configurationWarning };
 }
 
 /** Pattern to match Exa MCP servers */

package/src/runtime-mcp/discoverable-tool-metadata.ts

@@ -2,24 +2,27 @@
  * Back-compat re-export layer.
  * All types and functions have moved to src/tool-discovery/tool-index.ts.
  * This file exists solely so existing imports continue to compile without changes.
+ *
+ * Upstream v0.11.x renamed `DiscoverableMCP*` → `DiscoverableTool*`; we re-export
+ * the new symbols under the legacy names so existing call sites still compile.
  */
 export type {
-	DiscoverableMCPSearchDocument,
-	DiscoverableMCPSearchIndex,
-	DiscoverableMCPSearchResult,
-	DiscoverableMCPTool,
-	DiscoverableMCPToolServerSummary,
-	DiscoverableMCPToolSummary,
+	DiscoverableToolSearchDocument as DiscoverableMCPSearchDocument,
+	DiscoverableToolSearchIndex as DiscoverableMCPSearchIndex,
+	DiscoverableToolSearchResult as DiscoverableMCPSearchResult,
+	DiscoverableTool as DiscoverableMCPTool,
+	DiscoverableToolServerSummary as DiscoverableMCPToolServerSummary,
+	DiscoverableToolSummary as DiscoverableMCPToolSummary,
 } from "../tool-discovery/tool-index";
 
 export {
-	buildDiscoverableMCPSearchIndex,
-	collectDiscoverableMCPTools,
-	formatDiscoverableMCPToolServerSummary,
-	getDiscoverableMCPTool,
+	buildDiscoverableToolSearchIndex as buildDiscoverableMCPSearchIndex,
+	collectDiscoverableTools as collectDiscoverableMCPTools,
+	formatDiscoverableToolServerSummary as formatDiscoverableMCPToolServerSummary,
+	getDiscoverableTool as getDiscoverableMCPTool,
 	isMCPBridgeTool,
 	isMCPToolName,
-	searchDiscoverableMCPTools,
-	selectDiscoverableMCPToolNamesByServer,
-	summarizeDiscoverableMCPTools,
+	searchDiscoverableTools as searchDiscoverableMCPTools,
+	selectDiscoverableToolNamesByServer as selectDiscoverableMCPToolNamesByServer,
+	summarizeDiscoverableTools as summarizeDiscoverableMCPTools,
 } from "../tool-discovery/tool-index";