gsd-pi 2.76.0 → 2.77.0-dev.538325aea

package/packages/mcp-server/src/server.ts

@@ -15,6 +15,7 @@ import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { z } from 'zod';
 import type { SessionManager } from './session-manager.js';
+import { isRemoteConfigured, tryRemoteQuestions } from './remote-questions.js';
 import { readProgress } from './readers/state.js';
 import { readRoadmap } from './readers/roadmap.js';
 import { readHistory } from './readers/metrics.js';
@@ -34,6 +35,34 @@ const MCP_PKG = '@modelcontextprotocol/sdk';
 const SERVER_NAME = 'gsd';
 const SERVER_VERSION = '2.53.0';
 
+/** User-interaction timeout — generous but bounded so elicitation can't hang indefinitely (#4586). */
+const ELICIT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Race a promise against a timeout. Rejects with a typed error on timeout so
+ * callers can return a specific MCP error response rather than hanging.
+ *
+ * @param timeoutMs - override for testing; defaults to ELICIT_TIMEOUT_MS
+ */
+export async function withElicitTimeout<T>(
+  promise: Promise<T>,
+  label: string,
+  timeoutMs = ELICIT_TIMEOUT_MS,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`${label} timed out after ${timeoutMs / 60000} minutes — no user response received`)),
+      timeoutMs,
+    );
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Tool result helpers
 // ---------------------------------------------------------------------------
@@ -458,17 +487,40 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
 
   // -----------------------------------------------------------------------
   // gsd_cancel — cancel a running session
+  //
+  // Supports two lookup strategies:
+  //   1. sessionId  — the ID returned from gsd_execute (primary)
+  //   2. projectDir — absolute path to the project directory (fallback)
+  //
+  // The projectDir fallback handles interactive sessions (started via
+  // `/gsd auto` in the terminal) and post-restart MCP sessions that were
+  // never registered with a sessionId in this server instance.
   // -----------------------------------------------------------------------
   server.tool(
     'gsd_cancel',
-    'Cancel a running GSD session. Aborts the current operation and stops the process.',
+    'Cancel a running GSD session. Aborts the current operation and stops the process. Provide sessionId (from gsd_execute) or projectDir as a fallback for interactive/restarted sessions.',
     {
-      sessionId: z.string().describe('Session ID returned from gsd_execute'),
+      sessionId: z.string().optional().describe('Session ID returned from gsd_execute'),
+      projectDir: z.string().optional().describe('Absolute path to the project directory (fallback when sessionId is unavailable)'),
     },
     async (args: Record<string, unknown>) => {
-      const { sessionId } = args as { sessionId: string };
+      const { sessionId, projectDir } = args as { sessionId?: string; projectDir?: string };
       try {
-        await sessionManager.cancelSession(sessionId);
+        if (!sessionId && !projectDir) {
+          return errorContent('Either sessionId or projectDir must be provided');
+        }
+        if (sessionId) {
+          try {
+            await sessionManager.cancelSession(sessionId);
+          } catch (err) {
+            if (!projectDir || !(err instanceof Error) || !err.message.includes('Session not found')) {
+              throw err;
+            }
+            await sessionManager.cancelSessionByDir(projectDir);
+          }
+        } else if (projectDir) {
+          await sessionManager.cancelSessionByDir(projectDir);
+        }
         return jsonContent({ cancelled: true });
       } catch (err) {
         return errorContent(err instanceof Error ? err.message : String(err));
@@ -545,18 +597,39 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
         allowMultiple: z.boolean().optional().describe('If true, the user can select multiple options. No "None of the above" option is added.'),
       })).describe('Questions to show the user. Prefer 1 and do not exceed 3.'),
     },
-    async (args: Record<string, unknown>) => {
+    async (args: Record<string, unknown>, extra?: McpToolExtra) => {
       const { questions } = args as unknown as AskUserQuestionsParams;
       try {
         const validationError = validateAskUserQuestionsPayload(questions);
         if (validationError) return errorContent(validationError);
 
-        const elicitation = await server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions));
-        if (elicitation.action !== 'accept' || !elicitation.content) {
-          return textContent('ask_user_questions was cancelled before receiving a response');
-        }
+        // Prefer MCP elicitation when the client supports it (desktop/test stdio).
+        // If elicitation is unavailable (e.g. Claude Code headless), fall back
+        // to remote questions when configured.
+        const remoteConfigured = isRemoteConfigured();
+        try {
+          const elicitation = await withElicitTimeout(
+            server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions)),
+            'ask_user_questions',
+          );
+          if (elicitation.action !== 'accept' || !elicitation.content) {
+            return textContent('ask_user_questions was cancelled before receiving a response');
+          }
 
-        return textContent(formatAskUserQuestionsElicitResult(questions, elicitation));
+          return textContent(formatAskUserQuestionsElicitResult(questions, elicitation));
+        } catch (elicitationError) {
+          if (!remoteConfigured) throw elicitationError;
+          const remoteResult = await tryRemoteQuestions(questions, extra?.signal);
+          if (remoteResult) {
+            const details = remoteResult.details as Record<string, unknown> | undefined;
+            if (details?.['timed_out'] || details?.['error']) {
+              // Surface timeout/error as plain text so the LLM knows to retry
+              return textContent(remoteResult.content[0]?.text ?? 'Remote questions timed out or failed');
+            }
+            return textContent(remoteResult.content[0]?.text ?? '');
+          }
+          throw elicitationError;
+        }
       } catch (err) {
         return errorContent(err instanceof Error ? err.message : String(err));
       }
@@ -627,14 +700,17 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
         }
 
         // (3) Elicit input from the MCP client
-        const elicitation = await server.server.elicitInput({
-          message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`,
-          requestedSchema: {
-            type: 'object',
-            properties,
-            required,
-          },
-        });
+        const elicitation = await withElicitTimeout(
+          server.server.elicitInput({
+            message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`,
+            requestedSchema: {
+              type: 'object',
+              properties,
+              required,
+            },
+          }),
+          'secure_env_collect',
+        );
 
         if (elicitation.action !== 'accept' || !elicitation.content) {
           return textContent('secure_env_collect was cancelled by user.');

package/packages/mcp-server/src/session-manager.ts

@@ -7,7 +7,8 @@
  */
 
 import { execSync } from 'node:child_process';
-import { resolve } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
 import { RpcClient } from '@gsd-build/rpc-client';
 import type { SdkAgentEvent, RpcInitResult, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/rpc-client';
 import type {
@@ -188,7 +189,48 @@ export class SessionManager {
   async cancelSession(sessionId: string): Promise<void> {
     const session = this.getSession(sessionId);
     if (!session) throw new Error(`Session not found: ${sessionId}`);
+    await this._cancelSessionObject(session);
+  }
+
+  /**
+   * Cancel a session looked up by project directory.
+   *
+   * This is the fallback path for interactive sessions (started via `/gsd auto`
+   * in the terminal) and sessions from a restarted MCP server that have no
+   * registered sessionId. The sessions map is keyed by projectDir, so this
+   * lookup always succeeds for any tracked session regardless of sessionId.
+   */
+  async cancelSessionByDir(projectDir: string): Promise<void> {
+    const session = this.getSessionByDir(projectDir);
+    if (session) {
+      await this._cancelSessionObject(session);
+      return;
+    }
+    const stopped = await this.stopDetachedAutoProcess(projectDir);
+    if (!stopped) {
+      throw new Error(`Session not found for projectDir: ${projectDir}`);
+    }
+  }
+
+  private async stopDetachedAutoProcess(projectDir: string): Promise<boolean> {
+    const lockPath = join(projectDir, '.gsd', 'auto.lock');
+    if (!existsSync(lockPath)) return false;
+    try {
+      const lockData = JSON.parse(readFileSync(lockPath, 'utf-8')) as { pid?: number };
+      const pid = lockData.pid;
+      if (typeof pid !== 'number') return false;
+      try { process.kill(pid, 0); } catch { return false; }
+      process.kill(pid, 'SIGTERM');
+      return true;
+    } catch {
+      return false;
+    }
+  }
 
+  /**
+   * Internal: perform abort + stop + mark cancelled on a resolved session object.
+   */
+  private async _cancelSessionObject(session: ManagedSession): Promise<void> {
     try {
       await session.client.abort();
     } catch { /* may already be stopped */ }

package/packages/mcp-server/src/workflow-tools.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
@@ -288,6 +288,136 @@ describe("workflow MCP tools", () => {
     }
   });
 
+  it("#4477 gsd_task_complete forwards every schema field to the executor (regression for destructure-rebuild bug class)", async () => {
+    // Locks in the class-fix from PR #4477 review: handleTaskComplete previously
+    // destructured args into a hand-listed set of fields and rebuilt the call
+    // payload, which silently dropped ADR-011's `escalation` field (and any
+    // future schema field added without updating the rebuild). The fix passes
+    // `args` through directly, matching the spread pattern of sibling
+    // handlers. This test verifies the contract by injecting a mock executor
+    // module that captures the args, calling gsd_task_complete with an
+    // `escalation` payload, and asserting the field reached the executor.
+    const base = makeTmpBase();
+    const capturePath = join(base, "captured-args.json");
+    const mockModulePath = join(base, "mock-executors.mjs");
+    const prevModule = process.env.GSD_WORKFLOW_EXECUTORS_MODULE;
+    const prevCapture = process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH;
+    try {
+      // Mock module: implements the WorkflowToolExecutors shape.
+      // executeTaskComplete writes its received args to disk for assertion.
+      // Other executors are no-op stubs to satisfy isWorkflowToolExecutors.
+      const mockSource = `
+import { writeFileSync } from "node:fs";
+
+const noop = async () => ({ content: [{ type: "text", text: "noop" }] });
+
+export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = ["SUMMARY", "UAT", "CONTEXT", "PLAN"];
+export const executeMilestoneStatus = noop;
+export const executePlanMilestone = noop;
+export const executePlanSlice = noop;
+export const executeReplanSlice = noop;
+export const executeSliceComplete = noop;
+export const executeCompleteMilestone = noop;
+export const executeValidateMilestone = noop;
+export const executeReassessRoadmap = noop;
+export const executeSaveGateResult = noop;
+export const executeSummarySave = noop;
+
+export const executeTaskComplete = async (params, projectDir) => {
+  const capturePath = process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH;
+  if (capturePath) {
+    writeFileSync(capturePath, JSON.stringify({ params, projectDir }, null, 2));
+  }
+  return {
+    content: [{ type: "text", text: "mock task complete" }],
+    details: { taskId: params.taskId },
+  };
+};
+`;
+      writeFileSync(mockModulePath, mockSource, "utf-8");
+      process.env.GSD_WORKFLOW_EXECUTORS_MODULE = mockModulePath;
+      process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH = capturePath;
+
+      // Fresh import bypasses the cached workflowToolExecutorsPromise so the
+      // mock module is actually loaded for this test.
+      const { registerWorkflowTools: freshRegisterWorkflowTools } = await import(
+        `./workflow-tools.ts?escalation-test=${randomUUID()}`
+      );
+      const server = makeMockServer();
+      freshRegisterWorkflowTools(server as any);
+      const taskTool = server.tools.find((t) => t.name === "gsd_task_complete");
+      assert.ok(taskTool, "task tool should be registered");
+
+      // Mirrors the ADR-011 escalation schema: question + 2-4 options
+      // (each with id/label/tradeoffs) + recommendation + rationale +
+      // continueWithDefault flag.
+      const escalationPayload = {
+        question: "Should the auth flow use OAuth or PAT?",
+        options: [
+          { id: "A", label: "OAuth", tradeoffs: "Best UX; requires more setup." },
+          { id: "B", label: "PAT", tradeoffs: "Simpler; weaker rotation story." },
+        ],
+        recommendation: "A",
+        recommendationRationale: "Initial requirement implied multi-user; OAuth fits better.",
+        continueWithDefault: true,
+      };
+
+      await taskTool!.handler({
+        projectDir: base,
+        taskId: "T01",
+        sliceId: "S01",
+        milestoneId: "M001",
+        oneLiner: "Completed task with escalation",
+        narrative: "Did the work but flagged an ambiguity",
+        verification: "npm test",
+        escalation: escalationPayload,
+        verificationEvidence: [
+          { command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1234 },
+        ],
+      });
+
+      assert.ok(existsSync(capturePath), "mock executor should have written captured args to disk");
+      const captured = JSON.parse(readFileSync(capturePath, "utf-8"));
+
+      // The handler resolves projectDir via realpathSync (security/symlink check),
+      // so on macOS where /var symlinks to /private/var, the captured path will
+      // be the realpath form. Normalize both sides.
+      assert.equal(captured.projectDir, realpathSync(base), "projectDir should be passed as second arg");
+      assert.deepEqual(
+        captured.params.escalation,
+        escalationPayload,
+        "escalation payload must reach the executor verbatim — regression guard for the destructure-rebuild bug class (#4477 review)",
+      );
+      // Spot-check a couple of other fields to ensure the spread pattern
+      // doesn't accidentally exclude the rest while including escalation.
+      assert.equal(captured.params.taskId, "T01", "taskId must be forwarded");
+      assert.equal(captured.params.milestoneId, "M001", "milestoneId must be forwarded");
+      assert.deepEqual(
+        captured.params.verificationEvidence,
+        [{ command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1234 }],
+        "verificationEvidence must be forwarded (existing field)",
+      );
+      // Ensure no projectDir leak into params (it should be the second arg only).
+      assert.equal(
+        captured.params.projectDir,
+        undefined,
+        "projectDir must NOT appear in params — it's stripped via the spread destructure",
+      );
+    } finally {
+      if (prevModule === undefined) {
+        delete process.env.GSD_WORKFLOW_EXECUTORS_MODULE;
+      } else {
+        process.env.GSD_WORKFLOW_EXECUTORS_MODULE = prevModule;
+      }
+      if (prevCapture === undefined) {
+        delete process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH;
+      } else {
+        process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH = prevCapture;
+      }
+      cleanup(base);
+    }
+  });
+
   it("gsd_complete_task alias delegates to gsd_task_complete behavior", async () => {
     const base = makeTmpBase();
     try {
@@ -1237,6 +1367,21 @@ describe("workflow MCP tools", () => {
         findings: "No new attack surface was introduced.",
       });
       assert.match((gateResult as any).content[0].text as string, /Gate Q3 result saved/);
+      // #4472: executor `details` must be adapted to MCP `structuredContent`
+      // so it survives the protocol transport intact. Asserting property
+      // *absence* rather than `=== undefined` so a future regression that
+      // explicitly sets `details: undefined` (rather than removing it) still
+      // fails this contract test.
+      assert.equal(
+        Object.prototype.hasOwnProperty.call(gateResult, "details"),
+        false,
+        "executor `details` field must be stripped from MCP tool result",
+      );
+      assert.deepEqual(
+        (gateResult as any).structuredContent,
+        { operation: "save_gate_result", gateId: "Q3", verdict: "pass" },
+        "executor details must be forwarded on the MCP `structuredContent` channel",
+      );
       const gateRows = _getAdapter()!.prepare(
         "SELECT status, verdict, rationale FROM quality_gates WHERE milestone_id = ? AND slice_id = ? AND gate_id = ?",
       ).all("M006", "S06", "Q3") as Array<Record<string, unknown>>;