@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

package/packages/mcp-server/dist/workflow-tools.js

@@ -8,7 +8,7 @@ import { homedir } from "node:os";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
-import { WORKFLOW_TOOL_NAMES as CONTRACT_WORKFLOW_TOOL_NAMES, CANONICAL_WORKFLOW_TOOL_NAMES as CONTRACT_CANONICAL_WORKFLOW_TOOL_NAMES, WORKFLOW_TOOL_ALIAS_NAMES as CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES, } from "@opengsd/contracts";
+import { WORKFLOW_TOOL_NAMES as CONTRACT_WORKFLOW_TOOL_NAMES, CANONICAL_WORKFLOW_TOOL_NAMES as CONTRACT_CANONICAL_WORKFLOW_TOOL_NAMES, WORKFLOW_TOOL_ALIAS_NAMES as CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES, SUMMARY_SAVE_CONTENT_MAX_LENGTH, } from "@opengsd/contracts";
 import { logAliasUsage } from "./alias-telemetry.js";
 async function importBridgeModule() {
     return importLocalModule("../../../src/resources/extensions/gsd/mcp-bridge.js");
@@ -500,18 +500,15 @@ function isPlainObject(value) {
 async function runSerializedWorkflowOperation(fn) {
     // The shared DB adapter and workflow log base path are process-global, so
     // workflow MCP mutations must not overlap within a single server process.
-    // A per-operation deadline prevents a single stuck call from wedging every
-    // subsequent write for the lifetime of the process.
+    // A per-operation deadline prevents a single stuck call from wedging its
+    // caller for the lifetime of the process.
     //
-    // Known limitation: on timeout we surface an error and release the queue,
-    // but Promise.race cannot cancel the underlying `fn()` — it may continue
-    // running in the background and overlap with the next admitted operation.
-    // Proper cancellation requires threading an AbortSignal through every
-    // workflow executor (`workflow-tool-executors.ts` and friends), which is
-    // a larger change. The current trade-off: risk a theoretical overlap after
-    // a 5-minute wall-clock timeout vs permanently wedging the server. The
-    // overlap window is bounded by how long the zombie `fn()` keeps running;
-    // in practice DB writes complete quickly even when the caller gave up.
+    // Promise.race cannot cancel the underlying `fn()`. On timeout, surface an
+    // error to the caller but keep the queue held until `fn()` actually settles
+    // so a retry cannot overlap with the still-running operation. True
+    // cancellation remains a larger deferred design: it requires threading an
+    // AbortSignal through every workflow executor (`workflow-tool-executors.ts`
+    // and friends).
     const prior = workflowExecutionQueue;
     let release;
     workflowExecutionQueue = new Promise((resolve) => {
@@ -519,18 +516,21 @@ async function runSerializedWorkflowOperation(fn) {
     });
     await prior;
     const timeoutMs = getWorkflowOpTimeoutMs();
+    const operationPromise = Promise.resolve().then(fn);
+    let timedOut = false;
     try {
         if (timeoutMs === 0) {
-            return await fn();
+            return await operationPromise;
         }
         let timer;
         const timeoutPromise = new Promise((_, reject) => {
             timer = setTimeout(() => {
+                timedOut = true;
                 reject(new Error(`Workflow operation exceeded ${timeoutMs}ms deadline (GSD_MCP_WORKFLOW_TIMEOUT_MS)`));
             }, timeoutMs);
         });
         try {
-            return await Promise.race([fn(), timeoutPromise]);
+            return await Promise.race([operationPromise, timeoutPromise]);
         }
         finally {
             if (timer)
@@ -538,9 +538,18 @@ async function runSerializedWorkflowOperation(fn) {
         }
     }
     finally {
-        release();
+        if (timedOut) {
+            void operationPromise.then(release, release);
+        }
+        else {
+            release();
+        }
     }
 }
+/** @internal — exported for testing only */
+export function _runSerializedWorkflowOperationForTest(fn) {
+    return runSerializedWorkflowOperation(fn);
+}
 async function runSerializedWorkflowDbOperation(projectDir, fn) {
     return runSerializedWorkflowOperation(async () => {
         const bridge = await importBridgeModule();
@@ -946,7 +955,7 @@ const planSliceParams = {
         inputs: nonEmptyStringArray("inputs"),
         expectedOutput: nonEmptyStringArray("expectedOutput"),
         observabilityImpact: optionalNonEmptyString("observabilityImpact"),
-    })).describe("Planned tasks for the slice"),
+    })).optional().describe("Optional full task replacement for the slice. Omit for incremental planning, then call gsd_plan_task once per task."),
     successCriteria: z.string().optional(),
     proofLevel: z.string().optional(),
     integrationClosure: z.string().optional(),
@@ -1125,7 +1134,9 @@ const summarySaveParams = {
     slice_id: z.string().optional().describe("Slice ID (e.g. S01)"),
     task_id: z.string().optional().describe("Task ID (e.g. T01)"),
     artifact_type: z.string().describe("Artifact type to save (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT)"),
-    content: z.string().describe("The full markdown content of the artifact"),
+    content: z.string()
+        .max(SUMMARY_SAVE_CONTENT_MAX_LENGTH, `content must be at most ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters per save`)
+        .describe(`The full markdown content of the artifact. Maximum ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters per save.`),
 };
 const ROOT_SUMMARY_ARTIFACT_TYPES = new Set([
     "PROJECT",
@@ -1143,6 +1154,7 @@ const summarySaveSchema = z.object(summarySaveParams).superRefine((value, ctx) =
         });
     }
 });
+export const _summarySaveSchemaForTest = summarySaveSchema;
 const decisionSaveParams = {
     projectDir: projectDirParam,
     scope: z.string().describe("Scope of the decision (e.g. architecture, library, observability)"),
@@ -1390,9 +1402,9 @@ const resumeSchema = z.object(resumeParams);
 function wrapServerWithErrorHandler(realServer) {
     return {
         tool(name, description, params, handler) {
-            return realServer.tool(name, description, params, async (args) => {
+            return realServer.tool(name, description, params, async (args, extra) => {
                 try {
-                    return await handler(args);
+                    return await handler(args, extra);
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
@@ -1734,22 +1746,24 @@ export function registerWorkflowTools(realServer, options = {}) {
         }
         return { content: [{ type: "text", text: JSON.stringify(entries, null, 2) }] };
     });
-    server.tool("gsd_uat_exec", "Run one UAT-scoped bash/node/python check with milestone/slice/check metadata. Evidence persists under .gsd/exec with kind=uat_exec.", uatExecParams, async (args) => {
+    server.tool("gsd_uat_exec", "Run one UAT-scoped bash/node/python check with milestone/slice/check metadata. Evidence persists under .gsd/exec with kind=uat_exec.", uatExecParams, async (args, extra) => {
         const { projectDir, ...params } = parseWorkflowArgs(uatExecSchema, args);
         await enforceWorkflowWriteGate("gsd_uat_exec", projectDir);
         const { executeUatExec } = await importLocalModule("../../../src/resources/extensions/gsd/tools/exec-tool.js");
         return adaptExecutorResult(await runSerializedWorkflowOperation(async () => executeUatExec(params, {
             baseDir: projectDir,
             preferences: await loadProjectPreferences(projectDir),
+            signal: extra?.signal,
         })));
     });
-    server.tool("gsd_exec", "Run a short bash/node/python script in the project directory. Capped stdout/stderr and metadata persist under .gsd/exec; only a digest returns to MCP.", execParams, async (args) => {
+    server.tool("gsd_exec", "Run a short bash/node/python script in the project directory. Capped stdout/stderr and metadata persist under .gsd/exec; only a digest returns to MCP.", execParams, async (args, extra) => {
         const { projectDir, ...params } = parseWorkflowArgs(execSchema, args);
         await enforceWorkflowWriteGate("gsd_exec", projectDir);
         const { executeGsdExec } = await importLocalModule("../../../src/resources/extensions/gsd/tools/exec-tool.js");
         return adaptExecutorResult(await runSerializedWorkflowOperation(async () => executeGsdExec(params, {
             baseDir: projectDir,
             preferences: await loadProjectPreferences(projectDir),
+            signal: extra?.signal,
         })));
     });
     server.tool("gsd_exec_search", "Search prior gsd_exec runs from .gsd/exec/*.meta.json without re-running them.", execSearchParams, async (args) => {