gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

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

@@ -296,6 +296,12 @@ export const WORKFLOW_TOOL_NAMES = [
     "gsd_complete_task",
     "gsd_milestone_status",
     "gsd_journal_query",
+    // ADR-013 step 3: memory-store tools exposed to external MCP clients.
+    // gsd_memory_graph is namespaced to avoid collision with the existing
+    // gsd_graph tool (project knowledge graph from .gsd/ artifacts).
+    "gsd_capture_thought",
+    "gsd_memory_query",
+    "gsd_memory_graph",
 ];
 const DEFAULT_WORKFLOW_OP_TIMEOUT_MS = 5 * 60 * 1000;
 function getWorkflowOpTimeoutMs(env = process.env) {
@@ -307,6 +313,53 @@ function getWorkflowOpTimeoutMs(env = process.env) {
         return DEFAULT_WORKFLOW_OP_TIMEOUT_MS;
     return parsed; // 0 disables the timeout
 }
+/**
+ * Adapt an executor `ToolExecutionResult` ({ content, details?, isError? }) to
+ * the MCP `CallToolResult` shape ({ content, structuredContent?, isError? }).
+ *
+ * MCP transports (including stdio) only serialize fields declared in the
+ * protocol, so a non-standard `details` field is silently dropped over the
+ * wire. Mirroring it into `structuredContent` — the protocol's supported
+ * channel for structured tool payloads — preserves the data for clients that
+ * render from it (e.g. the save_gate_result renderer that reads gateId /
+ * verdict). See #4472.
+ *
+ * Discard policy for non-plain-object `details`: the `isPlainObject` guard
+ * accepts the canonical case (a record literal) and intentionally drops bare
+ * primitives (string, number, boolean), bare arrays, and class instances /
+ * Date objects. This is deliberate — MCP `structuredContent` is specified as
+ * a JSON object; non-object payloads can't round-trip cleanly. No current
+ * executor returns a non-object `details`, so this never fires in practice.
+ * Future executors needing to return a primitive should wrap it
+ * (`details: { value: 42 }`) rather than relying on the discard.
+ */
+function adaptExecutorResult(result) {
+    if (!result || typeof result !== "object")
+        return result;
+    const r = result;
+    if (!("details" in r))
+        return result;
+    const { details, ...rest } = r;
+    return isPlainObject(details) ? { ...rest, structuredContent: details } : rest;
+}
+/**
+ * Strict plain-object guard. True only for object literals and
+ * `Object.create(null)` — not for `Date`, `URL`, `Map`, `Set`, class instances,
+ * or arrays. Used to gate `structuredContent` forwarding so the MCP transport
+ * receives only true JSON objects (the protocol contract).
+ *
+ * Mirrored in `src/mcp-server.ts` for the agent-tool registry path's
+ * structured-content gate. Keep both copies in sync if the contract definition
+ * needs to evolve. See #4477 review.
+ */
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
 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.
@@ -375,58 +428,50 @@ async function enforceWorkflowWriteGate(toolName, projectDir, milestoneId = null
 }
 async function handleTaskComplete(projectDir, args) {
     await enforceWorkflowWriteGate("gsd_task_complete", projectDir, args.milestoneId);
-    const { taskId, sliceId, milestoneId, oneLiner, narrative, verification, deviations, knownIssues, keyFiles, keyDecisions, blockerDiscovered, verificationEvidence, } = args;
     const { executeTaskComplete } = await getWorkflowToolExecutors();
-    return runSerializedWorkflowOperation(() => executeTaskComplete({
-        taskId,
-        sliceId,
-        milestoneId,
-        oneLiner,
-        narrative,
-        verification,
-        deviations,
-        knownIssues,
-        keyFiles,
-        keyDecisions,
-        blockerDiscovered,
-        verificationEvidence,
-    }, projectDir));
+    // Pass `args` through directly rather than destructure-then-rebuild. The
+    // previous implementation re-listed each field, which silently dropped
+    // schema fields that weren't in the rebuild list (e.g., ADR-011's
+    // `escalation` payload). The destructure-then-rebuild pattern is the bug
+    // class; matching the spread shape used by sibling handlers (handleSliceComplete,
+    // handleReplanSlice) eliminates the recurrence risk by construction.
+    return adaptExecutorResult(await runSerializedWorkflowOperation(() => executeTaskComplete(args, projectDir)));
 }
 async function handleSliceComplete(projectDir, args) {
     await enforceWorkflowWriteGate("gsd_slice_complete", projectDir, args.milestoneId);
     const { executeSliceComplete } = await getWorkflowToolExecutors();
     const { projectDir: _projectDir, ...params } = args;
-    return runSerializedWorkflowOperation(() => executeSliceComplete(params, projectDir));
+    return adaptExecutorResult(await runSerializedWorkflowOperation(() => executeSliceComplete(params, projectDir)));
 }
 async function handleReplanSlice(projectDir, args) {
     await enforceWorkflowWriteGate("gsd_replan_slice", projectDir, args.milestoneId);
     const { executeReplanSlice } = await getWorkflowToolExecutors();
     const { projectDir: _projectDir, ...params } = args;
-    return runSerializedWorkflowOperation(() => executeReplanSlice(params, projectDir));
+    return adaptExecutorResult(await runSerializedWorkflowOperation(() => executeReplanSlice(params, projectDir)));
 }
 async function handleCompleteMilestone(projectDir, args) {
     await enforceWorkflowWriteGate("gsd_complete_milestone", projectDir, args.milestoneId);
     const { executeCompleteMilestone } = await getWorkflowToolExecutors();
     const { projectDir: _projectDir, ...params } = args;
-    return runSerializedWorkflowOperation(() => executeCompleteMilestone(params, projectDir));
+    return adaptExecutorResult(await runSerializedWorkflowOperation(() => executeCompleteMilestone(params, projectDir)));
 }
 async function handleValidateMilestone(projectDir, args) {
     await enforceWorkflowWriteGate("gsd_validate_milestone", projectDir, args.milestoneId);
     const { executeValidateMilestone } = await getWorkflowToolExecutors();
     const { projectDir: _projectDir, ...params } = args;
-    return runSerializedWorkflowOperation(() => executeValidateMilestone(params, projectDir));
+    return adaptExecutorResult(await runSerializedWorkflowOperation(() => executeValidateMilestone(params, projectDir)));
 }
 async function handleReassessRoadmap(projectDir, args) {
     await enforceWorkflowWriteGate("gsd_reassess_roadmap", projectDir, args.milestoneId);
     const { executeReassessRoadmap } = await getWorkflowToolExecutors();
     const { projectDir: _projectDir, ...params } = args;
-    return runSerializedWorkflowOperation(() => executeReassessRoadmap(params, projectDir));
+    return adaptExecutorResult(await runSerializedWorkflowOperation(() => executeReassessRoadmap(params, projectDir)));
 }
 async function handleSaveGateResult(projectDir, args) {
     await enforceWorkflowWriteGate("gsd_save_gate_result", projectDir, args.milestoneId);
     const { executeSaveGateResult } = await getWorkflowToolExecutors();
     const { projectDir: _projectDir, ...params } = args;
-    return runSerializedWorkflowOperation(() => executeSaveGateResult(params, projectDir));
+    return adaptExecutorResult(await runSerializedWorkflowOperation(() => executeSaveGateResult(params, projectDir)));
 }
 async function ensureMilestoneDbRow(milestoneId) {
     try {
@@ -459,6 +504,15 @@ const nonEmptyStringArray = (field) => z.array(nonEmptyString(`${field}[]`));
 // empty/whitespace fields at parse time. Without this, MCP callers pass "" for
 // the heavy planning fields, Zod accepts it, and the executor rejects one
 // field per call — forcing the agent into a retry loop to discover every gap.
+//
+// #4759 follow-up: the four heavy fields are Zod-optional because sketch
+// slices (isSketch=true) legitimately omit them, but they are REQUIRED for
+// every other slice. The conditional requirement is invisible in the JSON
+// Schema `required` array, so callers can only discover it from the
+// descriptions or by hitting the runtime superRefine below. The `.describe()`
+// calls below make that contract unmistakable in the tool schema sent to
+// agents; the superRefine enforces it at parse time.
+const HEAVY_FIELD_DESCRIBE = (field) => `${field} for this slice. REQUIRED unless isSketch=true (sketch slices defer this to refine-slice).`;
 const planMilestoneSliceSchema = z.object({
     sliceId: nonEmptyString("sliceId"),
     title: nonEmptyString("title"),
@@ -467,14 +521,14 @@ const planMilestoneSliceSchema = z.object({
     demo: nonEmptyString("demo"),
     goal: nonEmptyString("goal"),
     // ADR-011: heavy planning fields are optional for sketch slices; required for full slices.
-    successCriteria: z.string().optional(),
-    proofLevel: z.string().optional(),
-    integrationClosure: z.string().optional(),
-    observabilityImpact: z.string().optional(),
+    successCriteria: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("successCriteria")),
+    proofLevel: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("proofLevel")),
+    integrationClosure: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("integrationClosure")),
+    observabilityImpact: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("observabilityImpact")),
     // ADR-011 sketch-then-refine fields.
-    isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion"),
+    isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion. When true, successCriteria/proofLevel/integrationClosure/observabilityImpact may be omitted and sketchScope becomes required."),
     sketchScope: z.string().optional().describe("ADR-011: 2-3 sentence scope boundary, required when isSketch=true"),
-}).superRefine((slice, ctx) => {
+}).describe("Planned slice. For full slices (isSketch omitted or false): successCriteria, proofLevel, integrationClosure, and observabilityImpact are all required. For sketch slices (isSketch=true): those four fields may be omitted, but sketchScope is required.").superRefine((slice, ctx) => {
     if (slice.isSketch === true) {
         if (typeof slice.sketchScope !== "string" || slice.sketchScope.trim().length === 0) {
             ctx.addIssue({
@@ -915,14 +969,14 @@ export function registerWorkflowTools(server) {
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_plan_milestone", projectDir, params.milestoneId);
         const { executePlanMilestone } = await getWorkflowToolExecutors();
-        return runSerializedWorkflowOperation(() => executePlanMilestone(params, projectDir));
+        return adaptExecutorResult(await runSerializedWorkflowOperation(() => executePlanMilestone(params, projectDir)));
     });
     server.tool("gsd_plan_slice", "Write slice/task planning state to the GSD database and render plan artifacts from DB.", planSliceParams, async (args) => {
         const parsed = parseWorkflowArgs(planSliceSchema, args);
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_plan_slice", projectDir, params.milestoneId);
         const { executePlanSlice } = await getWorkflowToolExecutors();
-        return runSerializedWorkflowOperation(() => executePlanSlice(params, projectDir));
+        return adaptExecutorResult(await runSerializedWorkflowOperation(() => executePlanSlice(params, projectDir)));
     });
     server.tool("gsd_plan_task", "Write task planning state to the GSD database and render tasks/T##-PLAN.md from DB.", planTaskParams, async (args) => {
         const parsed = parseWorkflowArgs(planTaskSchema, args);
@@ -1031,7 +1085,7 @@ export function registerWorkflowTools(server) {
         if (!supportedArtifactTypes.includes(artifact_type)) {
             throw new Error(`artifact_type must be one of: ${supportedArtifactTypes.join(", ")}`);
         }
-        return runSerializedWorkflowOperation(() => executors.executeSummarySave({ milestone_id, slice_id, task_id, artifact_type, content }, projectDir));
+        return adaptExecutorResult(await runSerializedWorkflowOperation(() => executors.executeSummarySave({ milestone_id, slice_id, task_id, artifact_type, content }, projectDir)));
     });
     server.tool("gsd_task_complete", "Record a completed task to the GSD database and render its SUMMARY.md.", taskCompleteParams, async (args) => {
         const parsed = parseWorkflowArgs(taskCompleteSchema, args);
@@ -1049,7 +1103,7 @@ export function registerWorkflowTools(server) {
         // during pending-gate or queue-mode states.
         const { projectDir, milestoneId } = parseWorkflowArgs(milestoneStatusSchema, args);
         const { executeMilestoneStatus } = await getWorkflowToolExecutors();
-        return runSerializedWorkflowOperation(() => executeMilestoneStatus({ milestoneId }, projectDir));
+        return adaptExecutorResult(await runSerializedWorkflowOperation(() => executeMilestoneStatus({ milestoneId }, projectDir)));
     });
     server.tool("gsd_journal_query", "Query the structured event journal for auto-mode iterations.", journalQueryParams, async (args) => {
         const { projectDir, limit, ...filters } = parseWorkflowArgs(journalQuerySchema, args);
@@ -1060,5 +1114,98 @@ export function registerWorkflowTools(server) {
         }
         return { content: [{ type: "text", text: JSON.stringify(entries, null, 2) }] };
     });
+    // ─── ADR-013 step 3 — memory-store tools for external MCP clients ────────
+    //
+    // The same three tools the LLM sees in-process as `capture_thought`,
+    // `memory_query`, and `gsd_graph` (the memory variant). MCP exposes them
+    // under the gsd_* prefix and renames the memory graph to gsd_memory_graph
+    // to avoid collision with the project knowledge graph tool registered as
+    // `gsd_graph` in server.ts.
+    const MEMORY_CATEGORY = z.enum([
+        "architecture",
+        "convention",
+        "gotcha",
+        "preference",
+        "environment",
+        "pattern",
+    ]);
+    const captureThoughtSchema = z.object({
+        projectDir: z.string().optional(),
+        category: MEMORY_CATEGORY,
+        // Reject empty / whitespace-only content at the schema layer so the LLM
+        // never produces a memory row with no searchable text.
+        content: z.string().trim().min(1, "content must be a non-empty trimmed string"),
+        confidence: z.number().min(0.1).max(0.99).optional(),
+        tags: z.array(z.string()).optional(),
+        scope: z.string().optional(),
+        structuredFields: z.record(z.string(), z.unknown()).optional(),
+    });
+    const captureThoughtParams = {
+        projectDir: z.string().optional().describe("Absolute path to the project directory (defaults to MCP server cwd)"),
+        category: MEMORY_CATEGORY.describe("Memory category"),
+        content: z.string().describe("Memory text (1-3 sentences, no secrets)"),
+        confidence: z.number().min(0.1).max(0.99).optional().describe("0.1-0.99, default 0.8"),
+        tags: z.array(z.string()).optional().describe("Free-form tags"),
+        scope: z.string().optional().describe("Scope name; defaults to 'project'"),
+        structuredFields: z.record(z.string(), z.unknown()).optional().describe("ADR-013 structured payload (e.g. decision fields)"),
+    };
+    server.tool("gsd_capture_thought", "Record a durable project insight into the GSD memory store. Categories: architecture, convention, gotcha, preference, environment, pattern. Mirrors the in-process capture_thought tool for external MCP clients.", captureThoughtParams, async (args) => {
+        const { projectDir, ...params } = parseWorkflowArgs(captureThoughtSchema, args);
+        await enforceWorkflowWriteGate("gsd_capture_thought", projectDir);
+        return runSerializedWorkflowDbOperation(projectDir, async () => {
+            const { executeMemoryCapture } = await importLocalModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
+            return executeMemoryCapture(params);
+        });
+    });
+    const memoryQuerySchema = z.object({
+        projectDir: z.string().optional(),
+        // Match the documented "2+ char terms" contract in the in-process
+        // memory_query tool — reject sub-2-char queries at the schema layer.
+        query: z.string().trim().min(2, "query must be at least 2 characters"),
+        k: z.number().int().min(1).max(50).optional(),
+        category: MEMORY_CATEGORY.optional(),
+        scope: z.string().optional(),
+        tag: z.string().optional(),
+        include_superseded: z.boolean().optional(),
+        reinforce_hits: z.boolean().optional(),
+    });
+    const memoryQueryParams = {
+        projectDir: z.string().optional().describe("Absolute path to the project directory (defaults to MCP server cwd)"),
+        query: z.string().describe("Keyword query (2+ char terms)"),
+        k: z.number().int().min(1).max(50).optional().describe("Max results (default 10, max 50)"),
+        category: MEMORY_CATEGORY.optional().describe("Restrict to a single category"),
+        scope: z.string().optional().describe("Only include memories with this scope"),
+        tag: z.string().optional().describe("Only include memories tagged with this value"),
+        include_superseded: z.boolean().optional().describe("Include superseded memories (default false)"),
+        reinforce_hits: z.boolean().optional().describe("Increment hit_count on returned memories (default false)"),
+    };
+    server.tool("gsd_memory_query", "Search the GSD memory store by keyword. Returns ranked memories with id, category, content, confidence, scope, and tags. Mirrors the in-process memory_query tool for external MCP clients.", memoryQueryParams, async (args) => {
+        const { projectDir, ...params } = parseWorkflowArgs(memoryQuerySchema, args);
+        return runSerializedWorkflowDbOperation(projectDir, async () => {
+            const { executeMemoryQuery } = await importLocalModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
+            return executeMemoryQuery(params);
+        });
+    });
+    const memoryGraphSchema = z.object({
+        projectDir: z.string().optional(),
+        mode: z.enum(["build", "query"]),
+        memoryId: z.string().optional(),
+        depth: z.number().int().min(0).max(5).optional(),
+        rel: z.enum(["related_to", "depends_on", "contradicts", "elaborates", "supersedes"]).optional(),
+    }).refine((val) => val.mode !== "query" || (typeof val.memoryId === "string" && val.memoryId.trim().length > 0), { message: "memoryId is required and must be non-empty when mode=query", path: ["memoryId"] });
+    const memoryGraphParams = {
+        projectDir: z.string().optional().describe("Absolute path to the project directory (defaults to MCP server cwd)"),
+        mode: z.enum(["build", "query"]).describe("build = recompute graph (placeholder), query = inspect edges"),
+        memoryId: z.string().optional().describe("Memory ID (required when mode=query)"),
+        depth: z.number().int().min(0).max(5).optional().describe("Hops to traverse (0-5, default 1)"),
+        rel: z.enum(["related_to", "depends_on", "contradicts", "elaborates", "supersedes"]).optional().describe("Only include edges with this relation type"),
+    };
+    server.tool("gsd_memory_graph", "Inspect the relationship graph between memories. mode=query walks edges from a given memoryId. mode=build is a placeholder reserved for future graph rebuilds. Distinct from gsd_graph (project knowledge graph) — see ADR-013.", memoryGraphParams, async (args) => {
+        const { projectDir, ...params } = parseWorkflowArgs(memoryGraphSchema, args);
+        return runSerializedWorkflowDbOperation(projectDir, async () => {
+            const { executeGsdGraph } = await importLocalModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
+            return executeGsdGraph(params);
+        });
+    });
 }
 //# sourceMappingURL=workflow-tools.js.map