@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

package/dist/resources/extensions/claude-code-cli/turn-assembler.js

@@ -0,0 +1,224 @@
+// gsd-pi - Claude Code logical turn assembly
+import { PartialMessageBuilder } from "./partial-builder.js";
+/** Normalise heterogeneous SDK tool-result content (string, array, or object) into a uniform `ExternalToolResultContentBlock[]`. */
+function normalizeToolResultContent(content) {
+    if (typeof content === "string") {
+        return [{ type: "text", text: content }];
+    }
+    if (!Array.isArray(content)) {
+        if (content == null)
+            return [{ type: "text", text: "" }];
+        return [{ type: "text", text: JSON.stringify(content) }];
+    }
+    const blocks = [];
+    for (const item of content) {
+        if (typeof item === "string") {
+            blocks.push({ type: "text", text: item });
+            continue;
+        }
+        if (!item || typeof item !== "object") {
+            blocks.push({ type: "text", text: String(item) });
+            continue;
+        }
+        const block = item;
+        if (block.type === "text") {
+            blocks.push({ type: "text", text: typeof block.text === "string" ? block.text : "" });
+            continue;
+        }
+        if (block.type === "image"
+            && typeof block.data === "string"
+            && typeof block.mimeType === "string") {
+            blocks.push({ type: "image", data: block.data, mimeType: block.mimeType });
+            continue;
+        }
+        blocks.push({ type: "text", text: JSON.stringify(block) });
+    }
+    return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
+}
+/**
+ * Extract a `details` payload from an MCP tool-result block.
+ *
+ * MCP's `CallToolResult` carries structured data in `structuredContent` — the
+ * protocol's supported channel for non-text payloads. Claude Code's synthetic
+ * user message may surface that field in one of two shapes depending on SDK
+ * version: as a sibling on the `mcp_tool_result` block itself, or as a
+ * dedicated content sub-block with `type: "structuredContent"`. Snake-case
+ * (`structured_content`) is accepted defensively in case a transport hop
+ * rewrites casing. All other shapes return undefined, matching the nullable
+ * `details` contract consumed by tool result renderers.
+ */
+function extractStructuredDetailsFromBlock(block) {
+    const sibling = block.structuredContent ?? block.structured_content;
+    if (sibling && typeof sibling === "object" && !Array.isArray(sibling)) {
+        return sibling;
+    }
+    if (Array.isArray(block.content)) {
+        for (const item of block.content) {
+            if (!item || typeof item !== "object")
+                continue;
+            const sub = item;
+            if (sub.type !== "structuredContent" && sub.type !== "structured_content")
+                continue;
+            const payload = sub.structuredContent ?? sub.structured_content ?? sub.data ?? sub.value;
+            if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+                return payload;
+            }
+        }
+    }
+    // Return undefined (not {}) when no structured payload is present, matching
+    // the pre-#4477 contract where `details` was nullable. An empty-object
+    // sentinel is truthy and breaks downstream consumers that gate on
+    // `if (details)`. `undefined` matches the type of the field these results
+    // flow into (`Record<string, unknown> | undefined`).
+    return undefined;
+}
+/**
+ * True for items that are MCP `structuredContent` pseudo-blocks living inside
+ * a tool-result `content[]` array. These blocks carry the structured payload
+ * (extracted separately by `extractStructuredDetailsFromBlock`) and must NOT
+ * leak into the visible content rendered to the user — otherwise the renderer
+ * stringifies the JSON pseudo-block and shows it next to the actual tool
+ * output. See PR #4477 review (post-fix-round).
+ */
+function isStructuredContentPseudoBlock(item) {
+    if (!item || typeof item !== "object")
+        return false;
+    const type = item.type;
+    return type === "structuredContent" || type === "structured_content";
+}
+/**
+ * Strip `structuredContent` pseudo-blocks from a tool-result content array
+ * before normalization. The structured payload is extracted via the sibling
+ * `structuredContent` field (or a dedicated extractor pass on the raw block);
+ * the visible content path must not include the pseudo-block itself.
+ */
+function stripStructuredContentPseudoBlocks(content) {
+    if (!Array.isArray(content))
+        return content;
+    return content.filter((item) => !isStructuredContentPseudoBlock(item));
+}
+/** Extract tool result payloads from an SDK synthetic user message, keyed by tool-use ID. */
+export function extractToolResultsFromSdkUserMessage(message) {
+    const extracted = [];
+    const seen = new Set();
+    const rawMessage = message.message;
+    const content = Array.isArray(rawMessage?.content) ? rawMessage.content : [];
+    for (const item of content) {
+        if (!item || typeof item !== "object")
+            continue;
+        const block = item;
+        const type = typeof block.type === "string" ? block.type : "";
+        if (type !== "tool_result" && type !== "mcp_tool_result")
+            continue;
+        const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+        if (!toolUseId || seen.has(toolUseId))
+            continue;
+        seen.add(toolUseId);
+        extracted.push({
+            toolUseId,
+            result: {
+                content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(block.content)),
+                details: extractStructuredDetailsFromBlock(block),
+                isError: block.is_error === true,
+            },
+        });
+    }
+    if (extracted.length === 0) {
+        const fallback = message.tool_use_result;
+        if (fallback && typeof fallback === "object") {
+            const toolResult = fallback;
+            const toolUseId = typeof toolResult.tool_use_id === "string" ? toolResult.tool_use_id : "";
+            if (toolUseId) {
+                extracted.push({
+                    toolUseId,
+                    result: {
+                        content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(toolResult.content)),
+                        details: extractStructuredDetailsFromBlock(toolResult),
+                        isError: toolResult.is_error === true,
+                    },
+                });
+            }
+        }
+    }
+    return extracted;
+}
+/** Attach external tool results from the SDK synthetic user message to their corresponding tool-call blocks by ID. */
+export function attachExternalResultsToToolBlocks(toolBlocks, toolResultsById) {
+    for (const block of toolBlocks) {
+        if (block.type !== "toolCall" && block.type !== "serverToolUse")
+            continue;
+        const externalResult = toolResultsById.get(block.id);
+        if (!externalResult)
+            continue;
+        block.externalResult = externalResult;
+    }
+}
+/**
+ * Build the final assistant content that Agent Core consumes in
+ * `externalToolExecution` mode. This preserves tool-call blocks, attaches any
+ * SDK-produced external results by tool-call id, and then appends the final
+ * text/thinking blocks for the completed turn.
+ */
+export function buildFinalAssistantContent(params) {
+    const mergedToolBlocks = [...params.intermediateToolBlocks];
+    if (params.pendingContent) {
+        mergePendingToolCalls(mergedToolBlocks, params.pendingContent);
+    }
+    attachExternalResultsToToolBlocks(mergedToolBlocks, params.toolResultsById);
+    const finalContent = [...mergedToolBlocks];
+    if (params.pendingContent && params.pendingContent.length > 0) {
+        for (const block of params.pendingContent) {
+            if (block.type === "text" || block.type === "thinking") {
+                finalContent.push(block);
+            }
+        }
+    }
+    else {
+        if (params.lastThinkingContent) {
+            finalContent.push({ type: "thinking", thinking: params.lastThinkingContent });
+        }
+        if (params.lastTextContent) {
+            finalContent.push({ type: "text", text: params.lastTextContent });
+        }
+    }
+    if (finalContent.length === 0 && params.fallbackResultText) {
+        finalContent.push({ type: "text", text: params.fallbackResultText });
+    }
+    return finalContent;
+}
+/**
+ * Merge tool-call blocks from the active partial-message builder into the
+ * running list of intermediate tool calls, preserving order and de-duping
+ * by tool-call id. Exposed for testing the F3 fix (final-turn tool calls
+ * dropped when `result` arrives without a preceding synthetic `user`).
+ */
+export function mergePendingToolCalls(intermediate, pending) {
+    const alreadyIncluded = new Set();
+    for (const block of intermediate) {
+        if (block.type === "toolCall")
+            alreadyIncluded.add(block.id);
+    }
+    for (const block of pending) {
+        if (block.type !== "toolCall")
+            continue;
+        if (alreadyIncluded.has(block.id))
+            continue;
+        alreadyIncluded.add(block.id);
+        intermediate.push(block);
+    }
+    return intermediate;
+}
+export function handleClaudeCodePartialStreamEvent(builder, event, modelId) {
+    if (event.type === "message_start") {
+        // Claude Code can emit repeated SDK message_start events inside one
+        // logical assistant response. Keep appending until a synthetic user
+        // tool-result boundary explicitly clears the builder.
+        return {
+            builder: builder ?? new PartialMessageBuilder(event.message?.model ?? modelId),
+            assistantEvent: null,
+        };
+    }
+    if (!builder)
+        return { builder, assistantEvent: null };
+    return { builder, assistantEvent: builder.handleEvent(event) };
+}

package/dist/resources/extensions/github-sync/templates.js

@@ -7,7 +7,7 @@
  * All functions produce GitHub-flavored markdown strings ready
  * for the `gh` CLI body parameters.
  */
-import { buildPrEvidence } from "../gsd/pr-evidence.js";
+import { buildPullRequestEvidence } from "../gsd/pull-request-process.js";
 // ─── Helpers ────────────────────────────────────────────────────────────────
 /**
  * Wrap a string in a CommonMark inline-code span, escaping any embedded
@@ -85,7 +85,7 @@ export function formatSlicePRBody(data) {
         .map((task) => task.issueNumber)
         .filter((issueNumber) => typeof issueNumber === "number")
         .map((issueNumber) => `#${issueNumber}`);
-    return buildPrEvidence({
+    return buildPullRequestEvidence({
         milestoneId: data.id,
         subjectId: data.id,
         subjectKind: "slice",
@@ -172,7 +172,7 @@ export function formatSwarmLanePRBody(data) {
         `### Changed contracts\n${checkedList(data.lane.changedContracts, "No shared contracts changed").join("\n")}`,
         `### Transition risks\n${checkedList(data.transitionRisks, "No transition risks identified").join("\n")}`,
     ].filter(Boolean);
-    return buildPrEvidence({
+    return buildPullRequestEvidence({
         milestoneId: laneLabel,
         subjectId: laneLabel,
         subjectKind: "workflow",

package/dist/resources/extensions/gsd/artifact-projection.js

@@ -0,0 +1,14 @@
+// Project/App: gsd-pi
+// File Purpose: Resolves closeout artifact projection roots across project and milestone worktrees.
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+export function resolveCloseoutArtifactProjection(input) {
+    const projectRoot = resolveWorktreeProjectRoot(input.basePath, input.originalBasePath);
+    const canonicalMilestoneRoot = resolveCanonicalMilestoneRoot(projectRoot, input.milestoneId);
+    return {
+        projectRoot,
+        canonicalMilestoneRoot,
+        summaryArtifactBasePath: canonicalMilestoneRoot,
+        gateEvidenceBasePath: canonicalMilestoneRoot,
+    };
+}

package/dist/resources/extensions/gsd/auto/loop.js

@@ -3,7 +3,7 @@
 /**
  * auto/loop.ts — Main auto-mode execution loop.
  *
- * Iterates: derive → dispatch → guards → runUnit → finalize → repeat.
+ * Iterates: orchestration.advance → guards → runUnit → finalize → repeat.
  * Exits when s.active becomes false or a terminal condition is reached.
  *
  * Imports from: auto/types, auto/resolve, auto/phases
@@ -13,7 +13,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { MAX_LOOP_ITERATIONS, } from "./types.js";
 import { _clearCurrentResolve } from "./resolve.js";
-import { runPreDispatch, runDispatch, runGuards, runFinalize, STUCK_WINDOW_SIZE, } from "./phases.js";
+import { runGuards, runFinalize, STUCK_WINDOW_SIZE } from "./phases.js";
 import { debugLog } from "../debug-logger.js";
 import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
 import { ModelPolicyDispatchBlockedError } from "../auto-model-selection.js";
@@ -92,6 +92,22 @@ function resolveCompletionStopFromState(stateSnapshot) {
         },
     };
 }
+function resolveCompletionStopFromOutcome(outcome, stateSnapshot) {
+    if (outcome?.code !== "all-complete")
+        return null;
+    const completedMilestone = stateSnapshot?.lastCompletedMilestone ?? stateSnapshot?.activeMilestone;
+    return {
+        reason: outcome.displayReason,
+        options: {
+            completionWidget: {
+                milestoneId: completedMilestone?.id ?? null,
+                milestoneTitle: completedMilestone?.title ?? null,
+                allMilestonesComplete: true,
+            },
+            terminalOutcome: outcome,
+        },
+    };
+}
 // ── Stuck detection persistence (#3704) ──────────────────────────────────
 // Phase C migration: stuck-state.json deleted in favor of DB-backed
 // equivalents. recentUnits is rebuilt from unit_dispatches (Phase B
@@ -104,6 +120,7 @@ function resolveCompletionStopFromState(stateSnapshot) {
 // tolerates — same behavior as a fresh session.
 const STUCK_RECOVERY_ATTEMPTS_KEY = "stuck_recovery_attempts";
 const MAX_CONSECUTIVE_ALREADY_ACTIVE_SKIPS = 3;
+const ORCHESTRATION_MISSING_REASON = "Auto Orchestration Module is not wired; cannot dispatch built-in GSD Unit.";
 function stableStuckStateScopeId(s) {
     return normalizeRealPath(s.scope?.workspace.projectRoot ?? (s.originalBasePath || s.basePath));
 }
@@ -247,9 +264,9 @@ function closeOutCrashedUnit(s, iterData, err) {
     }
 }
 /**
- * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
- * runUnit → finalize → repeat. Exits when s.active becomes false or a
- * terminal condition is reached.
+ * Main auto-mode execution loop. Iterates: orchestration.advance → guards →
+ * runUnit → finalize → repeat. Exits when s.active becomes false or a terminal
+ * condition is reached.
  *
  * This is the linear replacement for the recursive
  * dispatchNextUnit → resolveAgentEnd → dispatchNextUnit chain.
@@ -441,10 +458,9 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             journalReporter.emit("iteration-start", { iteration });
             let iterData;
             // ── Custom engine path ──────────────────────────────────────────────
-            // When activeEngineId is a non-dev value, bypass runPreDispatch and
-            // runDispatch entirely — the custom engine drives its own state via
-            // GRAPH.yaml. Shares runGuards and runUnitPhase with the dev path.
-            // After unit execution, verifies then reconciles via the engine layer.
+            // When activeEngineId is a non-dev value, the custom engine drives its own
+            // state via GRAPH.yaml. It shares guards and Unit execution with the dev
+            // path, then verifies and reconciles via the engine layer.
             //
             // GSD_ENGINE_BYPASS=1 skips the engine layer entirely — falls through
             // to the dev path below.
@@ -520,7 +536,7 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 });
                 observedUnitType = iterData.unitType;
                 observedUnitId = iterData.unitId;
-                // ── Progress widget (mirrors dev path in runDispatch) ──
+                // ── Progress widget (mirrors the dev path) ──
                 deps.updateProgressWidget(ctx, iterData.unitType, iterData.unitId, iterData.state);
                 // ── Guards (shared with dev path) ──
                 const guardsResult = await runGuards(ic, s.currentMilestoneId ?? "workflow");
@@ -727,15 +743,23 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                         : await orchestration.advance();
                     if (orchestrationResult.kind === "blocked") {
                         s.pendingOrchestrationDispatch = null;
+                        const blockMessage = orchestrationResult.terminalOutcome?.code === "settlement-blocked"
+                            ? [
+                                orchestrationResult.terminalOutcome.displayReason,
+                                `Next: ${orchestrationResult.terminalOutcome.nextAction}`,
+                            ].join("\n")
+                            : orchestrationResult.reason;
                         if (orchestrationResult.action === "pause") {
                             await deps.pauseAuto(ctx, pi, {
-                                message: orchestrationResult.reason,
+                                message: blockMessage,
                                 category: "unknown",
+                            }, {
+                                expectedCurrentUnit: null,
                             });
                             finishTurn("paused", "manual-attention", "orchestration-blocked");
                         }
                         else {
-                            await deps.stopAuto(ctx, pi, orchestrationResult.reason);
+                            await deps.stopAuto(ctx, pi, blockMessage);
                             finishTurn("stopped", "manual-attention", "orchestration-blocked");
                         }
                         finishIncompleteIteration({
@@ -745,8 +769,19 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                         });
                         break;
                     }
+                    if (orchestrationResult.kind === "skipped") {
+                        s.pendingOrchestrationDispatch = null;
+                        emitIterationEnd({ skipped: true });
+                        completeIteration();
+                        finishTurn("skipped");
+                        continue;
+                    }
                     if (orchestrationResult.kind === "paused") {
                         s.pendingOrchestrationDispatch = null;
+                        finishIncompleteIteration({
+                            status: "paused",
+                            reason: orchestrationResult.reason,
+                        });
                         finishTurn("skipped");
                         continue;
                     }
@@ -766,7 +801,8 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     }
                     if (orchestrationResult.kind === "stopped") {
                         s.pendingOrchestrationDispatch = null;
-                        const completionStop = resolveCompletionStopFromState(orchestrationResult.stateSnapshot);
+                        let completionStop = resolveCompletionStopFromOutcome(orchestrationResult.terminalOutcome, orchestrationResult.stateSnapshot);
+                        completionStop ??= resolveCompletionStopFromState(orchestrationResult.stateSnapshot);
                         if (completionStop) {
                             await deps.stopAuto(ctx, pi, completionStop.reason, completionStop.options);
                         }
@@ -837,55 +873,37 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     });
                     observedUnitType = iterData.unitType;
                     observedUnitId = iterData.unitId;
-                }
-                else {
-                    const preDispatchResult = await runPreDispatch(ic, loopState);
-                    phaseReporter.report("pre-dispatch", preDispatchResult.action);
-                    if (preDispatchResult.action === "break") {
-                        finishTurn("stopped", "manual-attention", "pre-dispatch-break");
+                    const guardMilestoneId = iterData.mid ?? s.currentMilestoneId ?? "workflow";
+                    const guardsResult = await runGuards(ic, guardMilestoneId);
+                    phaseReporter.report("guard", guardsResult.action, {
+                        unitType: iterData.unitType,
+                        unitId: iterData.unitId,
+                    });
+                    if (guardsResult.action === "break") {
+                        finishTurn("stopped", "manual-attention", "guard-break");
                         finishIncompleteIteration({
                             status: "stopped",
-                            reason: "pre-dispatch-break",
+                            reason: "guard-break",
+                            unitType: iterData.unitType,
+                            unitId: iterData.unitId,
                             failureClass: "manual-attention",
                         });
                         break;
                     }
-                    if (preDispatchResult.action === "continue") {
-                        emitIterationEnd({ skipped: true });
-                        completeIteration();
-                        finishTurn("skipped");
-                        continue;
-                    }
-                    if (preDispatchResult.action === "retry") {
-                        finishTurn("retry", "execution", preDispatchResult.reason);
-                        continue;
-                    }
-                    const preData = preDispatchResult.data;
-                    const guardsResult = await runGuards(ic, preData.mid);
-                    phaseReporter.report("guard", guardsResult.action);
-                    if (guardsResult.action === "break") {
-                        finishTurn("stopped", "manual-attention", "guard-break");
-                        break;
-                    }
-                    const dispatchResult = await runDispatch(ic, preData, loopState);
-                    phaseReporter.report("dispatch", dispatchResult.action);
-                    if (dispatchResult.action === "break") {
-                        finishTurn("stopped", "manual-attention", "dispatch-break");
-                        break;
-                    }
-                    if (dispatchResult.action === "continue") {
-                        emitIterationEnd({ skipped: true });
-                        completeIteration();
-                        finishTurn("skipped");
-                        continue;
-                    }
-                    if (dispatchResult.action === "retry") {
-                        finishTurn("retry", "execution", dispatchResult.reason);
-                        continue;
-                    }
-                    iterData = dispatchResult.data;
-                    observedUnitType = iterData.unitType;
-                    observedUnitId = iterData.unitId;
+                }
+                else {
+                    s.pendingOrchestrationDispatch = null;
+                    await deps.pauseAuto(ctx, pi, {
+                        message: ORCHESTRATION_MISSING_REASON,
+                        category: "unknown",
+                    });
+                    finishTurn("paused", "manual-attention", "orchestration-missing");
+                    finishIncompleteIteration({
+                        status: "paused",
+                        reason: ORCHESTRATION_MISSING_REASON,
+                        failureClass: "manual-attention",
+                    });
+                    break;
                 }
             }
             else {