pi-soly 1.11.2 → 1.12.1

package/mcp/index.ts

@@ -1,6 +1,7 @@
 // @ts-nocheck — upstream MCP code with pre-existing strict-mode issues
-import type { ExtensionAPI, ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
+import type { DirectToolSpec } from "./types.ts";
 import { Type } from "typebox";
 import { showStatus, showTools, reconnectServers, authenticateServer, logoutServer, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
 import { loadMcpConfig } from "./config.ts";
@@ -11,11 +12,30 @@ import { executeAuthComplete, executeAuthStart, executeCall, executeConnect, exe
 import { getConfigPathFromArgv, truncateAtWord } from "./utils.ts";
 import { initializeOAuth, shutdownOAuth } from "./mcp-auth-flow.ts";
 import { createMcpDirectToolCallRenderer, renderMcpProxyToolCall, renderMcpToolResult } from "./tool-result-renderer.ts";
+import { ToolCache, cacheKey as makeCacheKey } from "./tool-cache.ts";
+
+/** Default TTL for cached MCP tool results (60s). Tools that hit a stable
+ *  server benefit; volatile ones are penalized for 60s — call sites can
+ *  invalidate via cache.invalidateServer(name) on reconnect. */
+const TOOL_CACHE_TTL_MS = 60_000;
 
 export default function mcpAdapter(pi: ExtensionAPI) {
   let state: McpExtensionState | null = null;
   let initPromise: Promise<McpExtensionState> | null = null;
   let lifecycleGeneration = 0;
+  /** In-memory TTL cache for direct MCP tool results. Per-session; cleared on
+   *  shutdown and on per-server invalidation (e.g. after reconnect). The
+   *  onChange callback refreshes the footer segment so cache activity stays
+   *  visible without an explicit refresh. */
+  const toolCache = new ToolCache(TOOL_CACHE_TTL_MS, Date.now, () => {
+    // state may be null briefly during session_restart / session_shutdown —
+    // skip the refresh in that case, the next init will set it again.
+    if (state) updateStatusBar(state);
+  });
+
+  /** Registry of direct-tool specs keyed by their registered (prefixed) name,
+   *  so mcp_retry can look up a spec by name when the LLM asks for a retry. */
+  const specByPrefixedName = new Map<string, DirectToolSpec>();
 
   async function shutdownState(currentState: McpExtensionState | null, reason: string): Promise<void> {
     if (!currentState) return;
@@ -68,13 +88,14 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     || missingConfiguredDirectToolServers.length > 0;
 
   for (const spec of directSpecs) {
+    specByPrefixedName.set(spec.prefixedName, spec);
     (pi.registerTool as (tool: unknown) => unknown)({
       name: spec.prefixedName,
       label: `MCP: ${spec.originalName}`,
       description: spec.description || "(no description)",
       promptSnippet: truncateAtWord(spec.description, 100) || `MCP tool from ${spec.serverName}`,
       parameters: Type.Unsafe((spec.inputSchema || { type: "object", properties: {} }) as never),
-      execute: createDirectToolExecutor(() => state, () => initPromise, spec),
+      execute: createDirectToolExecutor(() => state, () => initPromise, spec, toolCache),
       renderCall: createMcpDirectToolCallRenderer(spec.prefixedName),
       renderResult: renderMcpToolResult,
     });
@@ -124,6 +145,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       }
 
       state = nextState;
+      nextState.toolCache = toolCache;
       updateStatusBar(nextState);
       initPromise = null;
     }).catch(err => {
@@ -143,6 +165,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     const currentState = state;
     state = null;
     initPromise = null;
+    toolCache.clear();
 
     try {
       await Promise.all([
@@ -359,4 +382,123 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       },
     });
   }
+
+  // ============================================================================
+  // LLM-callable retry / reconnect
+  //
+  // Direct tools fail with `server_unavailable`, `not_connected`, or
+  // `call_failed` when the underlying connection drops. The LLM used to need
+  // the user to run `/mcp reconnect <server>` manually; these tools let it
+  // self-recover without bothering the user.
+  // ============================================================================
+
+  /** Pull the live state out of the lazy init promise; structured error on failure. */
+  async function getStateForTool() {
+    let s = state;
+    if (!s && initPromise) {
+      try {
+        s = await initPromise;
+      } catch (error) {
+        return {
+          ok: false as const,
+          result: {
+            content: [{
+              type: "text" as const,
+              text: `MCP initialization failed: ${error instanceof Error ? error.message : String(error)}`,
+            }],
+            details: { error: "init_failed" },
+          },
+        };
+      }
+    }
+    if (!s) {
+      return {
+        ok: false as const,
+        result: {
+          content: [{ type: "text" as const, text: "MCP not initialized" }],
+          details: { error: "not_initialized" },
+        },
+      };
+    }
+    return { ok: true as const, state: s };
+  }
+
+  (pi.registerTool as (tool: unknown) => unknown)({
+    name: "mcp_reconnect",
+    label: "MCP reconnect",
+    description: "Reconnect to one or all MCP servers after a connection failure. Use this when direct tool calls return `server_unavailable`, `not_connected`, or `call_failed` errors. Without `server`, reconnects all configured servers. The tool cache for the affected server is invalidated so the next call gets a fresh result.",
+    promptSnippet: "MCP reconnect - restore a server connection after failure",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: "Server name to reconnect; omit to reconnect all configured servers" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
+      const got = await getStateForTool();
+      if (!got.ok) return got.result;
+      const targetServer = params.server;
+      if (targetServer) toolCache.invalidateServer(targetServer);
+      else toolCache.clear();
+      await reconnectServers(got.state, ctx, targetServer);
+      return {
+        content: [{
+          type: "text" as const,
+          text: targetServer
+            ? `Reconnect attempted for "${targetServer}". Check server status with /mcp status, then re-call the failed tool.`
+            : "Reconnect attempted for all configured servers. Re-call any failed tool.",
+        }],
+        details: { server: targetServer ?? null, action: "reconnect" },
+      };
+    },
+  });
+
+  (pi.registerTool as (tool: unknown) => unknown)({
+    name: "mcp_retry",
+    label: "MCP retry",
+    description: "Reconnect to an MCP server and re-execute a specific direct tool call in one shot. Use after `mcp_reconnect`, or directly when you know the original tool name and arguments. The `tool` must be a registered direct tool name (the prefixed form, e.g. 'demo_search'). The tool cache for the server is invalidated before the retry so the response is fresh.",
+    promptSnippet: "MCP retry - reconnect server and re-execute a tool call",
+    parameters: Type.Object({
+      server: Type.String({ description: "Server name to reconnect" }),
+      tool: Type.String({ description: "Direct tool name as registered (prefixedName, e.g. 'demo_search')" }),
+      args: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Original tool arguments as a JSON object; omit or pass {} if the tool takes no arguments" })),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx: ExtensionContext) {
+      const got = await getStateForTool();
+      if (!got.ok) return got.result;
+
+      const spec = specByPrefixedName.get(params.tool);
+      if (!spec) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: `Tool "${params.tool}" not found. Use the proxy tool mcp({ server: "${params.server}" }) to see available tools for this server.`,
+          }],
+          details: { error: "tool_not_found", requestedTool: params.tool },
+        };
+      }
+      if (spec.serverName !== params.server) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: `Tool "${params.tool}" belongs to server "${spec.serverName}", not "${params.server}".`,
+          }],
+          details: {
+            error: "server_mismatch",
+            requestedTool: params.tool,
+            requestedServer: params.server,
+            actualServer: spec.serverName,
+          },
+        };
+      }
+
+      toolCache.invalidateServer(params.server);
+      await reconnectServers(got.state, ctx, params.server);
+
+      const executor = createDirectToolExecutor(
+        () => got.state,
+        () => null,
+        spec,
+        toolCache,
+      );
+      return executor(toolCallId, params.args ?? {}, signal, onUpdate, ctx);
+    },
+  });
 }

package/mcp/init.ts

@@ -328,6 +328,17 @@ export function updateStatusBar(state: McpExtensionState): void {
     }
     parts.push(`${name} ${fg(color, icon)}`);
   }
+
+  // Cache stats segment — appended last so the footer stays scannable. Hidden
+  // until the cache has actually seen traffic so a fresh session stays quiet.
+  //   ⚡ 12/3   = 12 hits, 3 misses   (expirations appear inline when >0)
+  const cacheStats = state.toolCache?.stats();
+  if (cacheStats && (cacheStats.hits > 0 || cacheStats.misses > 0 || cacheStats.expirations > 0 || cacheStats.size > 0)) {
+    const exp = cacheStats.expirations > 0 ? `/${cacheStats.expirations}e` : "";
+    const cacheText = `⚡ ${cacheStats.hits}h/${cacheStats.misses}m${exp}`;
+    parts.push(fg("muted", cacheText));
+  }
+
   ui.setStatus("mcp", parts.join(" · "));
 }
 

package/mcp/lifecycle.ts

@@ -55,7 +55,7 @@ export class McpLifecycleManager {
   private async checkConnections(): Promise<void> {
     for (const [name, definition] of this.keepAliveServers) {
       const connection = this.manager.getConnection(name);
-      
+
       if (!connection || connection.status !== "connected") {
         try {
           await this.manager.connect(name, definition);
@@ -63,7 +63,14 @@ export class McpLifecycleManager {
           // Notify extension to update metadata
           this.onReconnect?.(name);
         } catch (error) {
-          console.error(`MCP: Failed to reconnect to ${name}:`, error);
+          // Silent retry: a downed MCP server would otherwise spam the
+          // terminal every 30s until the next health check succeeds. The
+          // failure stays visible via MCP_UI_DEBUG=1 if a developer needs
+          // to inspect the underlying error.
+          logger.debug(`Reconnect attempt failed for ${name}`, {
+            server: name,
+            error: error instanceof Error ? error.message : String(error),
+          });
         }
       }
     }

package/mcp/server-manager.ts

@@ -381,6 +381,34 @@ export class McpServerManager {
    * session id internally; our fix works because `close()` + `connect()`
    * creates a brand new transport + client, so the SDK starts fresh.
    */
+  /** Call the SDK client's callTool with arguments in the CORRECT positions.
+   *
+   * SDK signature is `callTool(params, resultSchema?, options?)`. We pass
+   * `undefined` for resultSchema (→ SDK default `CallToolResultSchema`) and
+   * forward only `signal` as the options. The previous inline cast treated
+   * the method as `(params, options?)` and passed our options object as the
+   * 2nd argument — landing it in the resultSchema slot. The SDK then
+   * validated every response via `safeParse({_bookkeep, signal}, result)`,
+   * and since a plain object has no `.safeParse`, every call crashed with
+   * `v3Schema.safeParse is not a function` — breaking ALL tool calls (and,
+   * via the same result-validation path in `request()`, tool listings too,
+   * so only the adapter's own meta-tools stayed visible). */
+  private async sdkCallTool(
+    client: Client,
+    params: CallToolRequest["params"],
+    options?: { signal?: AbortSignal },
+  ): Promise<CallToolResult> {
+    return (client.callTool as (
+      p: CallToolRequest["params"],
+      resultSchema: unknown,
+      o?: { signal?: AbortSignal },
+    ) => Promise<CallToolResult>)(
+      params,
+      undefined, // → SDK default CallToolResultSchema
+      options?.signal ? { signal: options.signal } : undefined,
+    );
+  }
+
   async callTool(
     name: string,
     params: CallToolRequest["params"],
@@ -398,17 +426,7 @@ export class McpServerManager {
         this.incrementInFlight(name);
       }
       try {
-        // The SDK's callTool signature changed in 1.28 to accept an optional
-        // resultSchema; we still target 1.27.1. Cast through unknown to
-        // bridge the type skew without losing type safety elsewhere.
-        const result = await (connection.client.callTool as (
-          p: CallToolRequest["params"],
-          o?: unknown,
-        ) => Promise<CallToolResult>)(
-          params as CallToolRequest["params"],
-          options,
-        );
-        return result;
+        return this.sdkCallTool(connection.client, params, options);
       } finally {
         if (bookkeeping) {
           this.decrementInFlight(name);
@@ -433,13 +451,7 @@ export class McpServerManager {
       }
       await this.connect(name, connection.definition);
       try {
-        const result = await (connection.client.callTool as (
-          p: CallToolRequest["params"],
-          o?: unknown,
-        ) => Promise<CallToolResult>)(
-          params as CallToolRequest["params"],
-          options,
-        );
+        const result = await this.sdkCallTool(connection.client, params, options);
         this.onSessionRecover?.(name, true, errMsg);
         return result;
       } catch (retryErr) {

package/mcp/state.ts

@@ -3,6 +3,7 @@ import type { ConsentManager } from "./consent-manager.ts";
 import type { McpLifecycleManager } from "./lifecycle.ts";
 import type { McpServerManager } from "./server-manager.ts";
 import type { ToolMetadata, McpConfig, UiSessionMessages, UiStreamSummary } from "./types.ts";
+import type { ToolCache } from "./tool-cache.ts";
 import type { UiResourceHandler } from "./ui-resource-handler.ts";
 import type { UiServerHandle } from "./ui-server.ts";
 
@@ -35,6 +36,12 @@ export interface McpExtensionState {
   consentManager: ConsentManager;
   uiServer: UiServerHandle | null;
   completedUiSessions: CompletedUiSession[];
+  /** In-memory TTL cache for direct tool call results. Attached by index.ts
+   *  right after initializeMcp resolves; consumed by updateStatusBar for the
+   *  footer and by showStatus for the /mcp status panel. Optional because
+   *  initializeMcp constructs the state without it; index.ts assigns before
+   *  any consumer can see the state. */
+  toolCache?: ToolCache;
   openBrowser: (url: string) => Promise<void>;
   ui?: ExtensionContext["ui"];
   sendMessage?: SendMessageFn;

package/mcp/tool-cache.ts

@@ -0,0 +1,135 @@
+// =============================================================================
+// mcp/tool-cache.ts — in-memory TTL cache for MCP tool call results
+// =============================================================================
+//
+// Lives once per MCP session, cleared on session_shutdown. Keyed by
+// `${server}:${tool}:${stableStringify(args)}`. Only successful tool results
+// are stored; errors, auth-required, init failures, UI tools, and resource
+// reads are never cached (UI tools have side effects, resources may be large
+// and the user explicitly asked for "тулзы" only).
+//
+// Stats (hits/misses/expirations) are tracked for future observability but
+// not surfaced yet — kept internal until a user-facing surface exists.
+// =============================================================================
+
+/** A single cache entry with absolute expiry timestamp. */
+type CacheEntry = {
+	value: unknown;
+	expiresAt: number;
+};
+
+/** Snapshot of cache counters — for tests and future telemetry. */
+export type CacheStats = {
+	size: number;
+	hits: number;
+	misses: number;
+	expirations: number;
+};
+
+/** In-memory TTL cache for MCP tool results. Not thread-safe (single-threaded JS). */
+export class ToolCache {
+	private readonly entries = new Map<string, CacheEntry>();
+	private hits = 0;
+	private misses = 0;
+	private expirations = 0;
+
+	constructor(
+		private readonly defaultTtlMs: number,
+		private readonly now: () => number = Date.now,
+		/** Fires after every get/set/clear/invalidateServer/delete so the
+		 *  caller can refresh the footer or telemetry. Fired before the
+		 *  function returns, never throws — UI work must not crash the cache. */
+		private readonly onChange?: () => void,
+	) {}
+
+	private notify(): void {
+		if (!this.onChange) return;
+		try { this.onChange(); } catch { /* UI refresh must never break the cache */ }
+	}
+
+	/** Return the cached value if present and not expired; otherwise undefined. */
+	get(key: string): unknown | undefined {
+		const entry = this.entries.get(key);
+		if (!entry) {
+			this.misses++;
+			this.notify();
+			return undefined;
+		}
+		if (this.now() >= entry.expiresAt) {
+			this.entries.delete(key);
+			this.expirations++;
+			this.misses++;
+			this.notify();
+			return undefined;
+		}
+		this.hits++;
+		this.notify();
+		return entry.value;
+	}
+
+	/** Store `value` under `key`, overwriting any prior entry. */
+	set(key: string, value: unknown, ttlMs?: number): void {
+		this.entries.set(key, {
+			value,
+			expiresAt: this.now() + (ttlMs ?? this.defaultTtlMs),
+		});
+		this.notify();
+	}
+
+	/** Remove a single entry; returns true if it existed. */
+	delete(key: string): boolean {
+		const existed = this.entries.delete(key);
+		if (existed) this.notify();
+		return existed;
+	}
+
+	/** Drop every cached entry. Called on session_shutdown. */
+	clear(): void {
+		const had = this.entries.size > 0;
+		this.entries.clear();
+		if (had) this.notify();
+	}
+
+	/** Drop every entry belonging to a server (e.g. after a reconnect invalidates them). */
+	invalidateServer(serverName: string): void {
+		const prefix = `${serverName}:`;
+		let removed = 0;
+		for (const key of [...this.entries.keys()]) {
+			if (key.startsWith(prefix)) {
+				this.entries.delete(key);
+				removed++;
+			}
+		}
+		if (removed > 0) this.notify();
+	}
+
+	stats(): CacheStats {
+		return {
+			size: this.entries.size,
+			hits: this.hits,
+			misses: this.misses,
+			expirations: this.expirations,
+		};
+	}
+}
+
+/**
+ * Stable JSON serialization: object keys are sorted recursively, so two
+ * structurally-equal arguments always produce the same string regardless of
+ * the original insertion order. Required for a correct cache key.
+ */
+export function stableStringify(value: unknown): string {
+	if (value === null) return "null";
+	if (typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) {
+		return "[" + value.map(stableStringify).join(",") + "]";
+	}
+	const obj = value as Record<string, unknown>;
+	const keys = Object.keys(obj).sort();
+	return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+
+/** Build a deterministic cache key for an MCP tool call. */
+export function cacheKey(serverName: string, toolName: string, args: unknown): string {
+	return `${serverName}:${toolName}:${stableStringify(args ?? {})}`;
+}

package/nudge.ts

@@ -82,7 +82,10 @@ export function classifyTaskHeuristics(prompt: string): TaskHeuristics {
 	return { nonTrivial, researchHeavy, mentions, suggestedAngles };
 }
 
-export function buildNudgeSection(heuristics: TaskHeuristics): string {
+export function buildNudgeSection(
+	heuristics: TaskHeuristics,
+	opts: { hasProject?: boolean; confirmBeforeCode?: boolean } = {},
+): string {
 	// Always-on rules (cheap to add, high signal):
 	//   - Don't dive in on non-trivial tasks without a brief check
 	//   - Prefer background subagents for research
@@ -105,18 +108,32 @@ export function buildNudgeSection(heuristics: TaskHeuristics): string {
 				.join("\n")}`
 		: "";
 
+	// When there's an active soly project and the task is non-trivial, steer the
+	// model toward the workflow lifecycle instead of ad-hoc edits.
+	const workflowPoint =
+		opts.hasProject && heuristics.nonTrivial
+			? `\n\n4. **Route project work through the soly workflow.** For phase/task work in \`.soly/\`, prefer the lifecycle over ad-hoc edits: \`soly discuss <N>\` (scope) → \`soly plan <N>\` (write tasks) → \`soly execute <N>\` (do them) → \`soly verify\` (review). Run \`soly status\` to see where you are. Skip only for a genuine one-off.`
+			: "";
+
+	// Confirm-before-coding gate: for non-trivial implementation, don't start
+	// editing files until the user has greenlit the approach.
+	const confirmBlock =
+		opts.confirmBeforeCode && heuristics.nonTrivial
+			? `\n\n   **Confirm before coding.** Don't jump straight into writing/editing code. First state your understanding and intended approach in 1–3 sentences and list anything still open, then ask via the \`ask_pro\` picker whether to proceed — one question with options like "Go — implement now", "Discuss / refine the approach", "Adjust scope first" (add an \`allowOther\` for a free-text steer). Wait for the choice before touching files. Skip only for trivial fixes, or when the user already said to proceed ("just do it", "go", "yes").`
+			: "";
+
 	return `
 
 ## soly behavioral nudge (always on)
 
 The following are user-set defaults, not project rules. They tell you how the user wants you to behave in this session.
 
-1. **Pre-action gate.** Before starting non-trivial work, take a 10-second pause and decide: do I have enough to act, or should I ask? If the prompt has ambiguity, missing scope, or a hidden assumption, surface one short clarifying question (or a small set of multi-choice options) instead of starting to code. Skip the gate for trivial fixes ("rename X", "add log line", "fix typo") and for follow-up turns in an already-clarified task.
+1. **Pre-action gate.** Before starting non-trivial work, take a 10-second pause and decide: do I have enough to act, or should I ask? If the prompt has ambiguity, missing scope, or a hidden assumption, surface one short clarifying question (or a small set of multi-choice options) instead of starting to code. Skip the gate for trivial fixes ("rename X", "add log line", "fix typo") and for follow-up turns in an already-clarified task.${confirmBlock}
    ${triggerLine}${anglesBlock}
 
 2. **Background subagents by default.** When you need to read unfamiliar code, scout a directory, gather external evidence, or run a multi-step review, prefer \`subagent(...)\` with \`async: true\` and \`context: "fresh"\` over doing it inline. Reserve your own context for the actual decision the user is paying you to make. If the work needs the parent conversation history, use \`context: "fork"\` instead. Do not silently block on long runs — launch async and continue with independent work.
 
-3. **Subagent tool ergonomics.** When delegating: give the child a concrete role, scope, success criteria, hard constraints, and expected output. Do not pass vague instructions like "implement this" or "look into that". Async is the default; foreground is the explicit opt-out.
+3. **Subagent tool ergonomics.** When delegating: give the child a concrete role, scope, success criteria, hard constraints, and expected output. Do not pass vague instructions like "implement this" or "look into that". Async is the default; foreground is the explicit opt-out.${workflowPoint}
 
 Treat (1) and (2) as defaults, not laws. The user can always override per-task ("just do it", "ask me everything", "no subagents"). When overriding, briefly acknowledge it.
 `;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-soly",
-  "version": "1.11.2",
-  "description": "Project management + workflow engine for pi-coding-agent. Plans, state, MANDATORY rules, multi-question picker — one npm install, zero config. LLM is the executor (no subagent layer).",
+  "version": "1.12.1",
+  "description": "Project management + workflow framework for pi-coding-agent. Plans, state, MANDATORY rules, self-review, multi-question picker, native footer + welcome chrome — one npm install, zero config. The LLM drives execution and delegates to a worker subagent when available.",
   "type": "module",
   "main": "index.ts",
   "scripts": {
@@ -40,14 +40,18 @@
     "intent.ts",
     "iteration.ts",
     "nudge.ts",
+    "tool-hints.ts",
     "scratchpad.ts",
     "tools.ts",
-    "agents-install.ts",
+    "util.ts",
     "ask",
+    "deck",
+    "artifact",
     "skills",
     "workflows",
     "workflows-data",
     "mcp",
+    "visual",
     "notification.ts",
     "notifications-log.ts",
     "status.ts",
@@ -76,6 +80,9 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "publishConfig": {