gsd-pi 2.46.0-dev.f45e6dc → 2.46.1-dev.79664f2

package/src/resources/extensions/claude-code-cli/stream-adapter.ts

@@ -0,0 +1,355 @@
+/**
+ * Stream adapter: bridges the Claude Agent SDK into GSD's streamSimple contract.
+ *
+ * The SDK runs the full agentic loop (multi-turn, tool execution, compaction)
+ * in one call. This adapter translates the SDK's streaming output into
+ * AssistantMessageEvents for TUI rendering, then strips tool-call blocks from
+ * the final AssistantMessage so GSD's agent loop doesn't try to dispatch them.
+ */
+
+import type {
+	AssistantMessage,
+	AssistantMessageEvent,
+	AssistantMessageEventStream,
+	Context,
+	Model,
+	SimpleStreamOptions,
+} from "@gsd/pi-ai";
+import { EventStream } from "@gsd/pi-ai";
+import { execSync } from "node:child_process";
+import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
+import type {
+	SDKAssistantMessage,
+	SDKMessage,
+	SDKPartialAssistantMessage,
+	SDKResultMessage,
+	SDKSystemMessage,
+	SDKStatusMessage,
+	SDKUserMessage,
+} from "./sdk-types.js";
+
+// ---------------------------------------------------------------------------
+// Stream factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct an AssistantMessageEventStream using EventStream directly.
+ * (The class itself is only re-exported as a type from the @gsd/pi-ai barrel.)
+ */
+function createAssistantStream(): AssistantMessageEventStream {
+	return new EventStream<AssistantMessageEvent, AssistantMessage>(
+		(event) => event.type === "done" || event.type === "error",
+		(event) => {
+			if (event.type === "done") return event.message;
+			if (event.type === "error") return event.error;
+			throw new Error("Unexpected event type for final result");
+		},
+	) as AssistantMessageEventStream;
+}
+
+// ---------------------------------------------------------------------------
+// Claude binary resolution
+// ---------------------------------------------------------------------------
+
+let cachedClaudePath: string | null = null;
+
+/**
+ * Resolve the path to the system-installed `claude` binary.
+ * The SDK defaults to a bundled cli.js which doesn't exist when
+ * installed as a library — we need to point it at the real CLI.
+ */
+function getClaudePath(): string {
+	if (cachedClaudePath) return cachedClaudePath;
+	try {
+		cachedClaudePath = execSync("which claude", { timeout: 5_000, stdio: "pipe" })
+			.toString()
+			.trim();
+	} catch {
+		cachedClaudePath = "claude"; // fall back to PATH resolution
+	}
+	return cachedClaudePath;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the last user prompt text from GSD's context messages.
+ * The SDK manages its own conversation history — we only send
+ * the latest user message as the prompt.
+ */
+function extractLastUserPrompt(context: Context): string {
+	for (let i = context.messages.length - 1; i >= 0; i--) {
+		const msg = context.messages[i];
+		if (msg.role === "user") {
+			if (typeof msg.content === "string") return msg.content;
+			if (Array.isArray(msg.content)) {
+				const textParts = msg.content
+					.filter((part: any) => part.type === "text")
+					.map((part: any) => part.text);
+				if (textParts.length > 0) return textParts.join("\n");
+			}
+		}
+	}
+	return "";
+}
+
+// ---------------------------------------------------------------------------
+// Error helper
+// ---------------------------------------------------------------------------
+
+function makeErrorMessage(model: string, errorMsg: string): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [{ type: "text", text: `Claude Code error: ${errorMsg}` }],
+		api: "anthropic-messages",
+		provider: "claude-code",
+		model,
+		usage: { ...ZERO_USAGE },
+		stopReason: "error",
+		errorMessage: errorMsg,
+		timestamp: Date.now(),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// streamSimple implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * GSD streamSimple function that delegates to the Claude Agent SDK.
+ *
+ * Emits AssistantMessageEvent deltas for real-time TUI rendering
+ * (thinking, text, tool calls). The final AssistantMessage has tool-call
+ * blocks stripped so the agent loop ends the turn without local dispatch.
+ */
+export function streamViaClaudeCode(
+	model: Model<any>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	const stream = createAssistantStream();
+
+	void pumpSdkMessages(model, context, options, stream);
+
+	return stream;
+}
+
+async function pumpSdkMessages(
+	model: Model<any>,
+	context: Context,
+	options: SimpleStreamOptions | undefined,
+	stream: AssistantMessageEventStream,
+): Promise<void> {
+	const modelId = model.id;
+	let builder: PartialMessageBuilder | null = null;
+	/** Track the last text content seen across all assistant turns for the final message. */
+	let lastTextContent = "";
+	let lastThinkingContent = "";
+
+	try {
+		// Dynamic import — the SDK is an optional dependency.
+		const sdkModule = "@anthropic-ai/claude-agent-sdk";
+		const sdk = (await import(/* webpackIgnore: true */ sdkModule)) as {
+			query: (args: {
+				prompt: string | AsyncIterable<unknown>;
+				options?: Record<string, unknown>;
+			}) => AsyncIterable<SDKMessage>;
+		};
+
+		// Bridge GSD's AbortSignal to SDK's AbortController
+		const controller = new AbortController();
+		if (options?.signal) {
+			options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+		}
+
+		const prompt = extractLastUserPrompt(context);
+
+		const queryResult = sdk.query({
+			prompt,
+			options: {
+				pathToClaudeCodeExecutable: getClaudePath(),
+				model: modelId,
+				includePartialMessages: true,
+				persistSession: false,
+				abortController: controller,
+				cwd: process.cwd(),
+				permissionMode: "bypassPermissions",
+				allowDangerouslySkipPermissions: true,
+				settingSources: ["project"],
+				systemPrompt: { type: "preset", preset: "claude_code" },
+				betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
+			},
+		});
+
+		// Emit start with an empty partial
+		const initialPartial: AssistantMessage = {
+			role: "assistant",
+			content: [],
+			api: "anthropic-messages",
+			provider: "claude-code",
+			model: modelId,
+			usage: { ...ZERO_USAGE },
+			stopReason: "stop",
+			timestamp: Date.now(),
+		};
+		stream.push({ type: "start", partial: initialPartial });
+
+		for await (const msg of queryResult as AsyncIterable<SDKMessage>) {
+			if (options?.signal?.aborted) break;
+
+			switch (msg.type) {
+				// -- Init --
+				case "system": {
+					// Nothing to emit — the stream is already started.
+					break;
+				}
+
+				// -- Streaming partial messages --
+				case "stream_event": {
+					const partial = msg as SDKPartialAssistantMessage;
+					if (partial.parent_tool_use_id !== null) break; // skip subagent
+
+					const event = partial.event;
+
+					// New assistant turn starts with message_start
+					if (event.type === "message_start") {
+						builder = new PartialMessageBuilder(
+							(event as any).message?.model ?? modelId,
+						);
+						break;
+					}
+
+					if (!builder) break;
+
+					const assistantEvent = builder.handleEvent(event);
+					if (assistantEvent) {
+						stream.push(assistantEvent);
+					}
+					break;
+				}
+
+				// -- Complete assistant message (non-streaming fallback) --
+				case "assistant": {
+					const sdkAssistant = msg as SDKAssistantMessage;
+					if (sdkAssistant.parent_tool_use_id !== null) break;
+
+					// Capture text content from complete messages
+					for (const block of sdkAssistant.message.content) {
+						if (block.type === "text") {
+							lastTextContent = block.text;
+						} else if (block.type === "thinking") {
+							lastThinkingContent = block.thinking;
+						}
+					}
+					break;
+				}
+
+				// -- User message (synthetic tool result — signals turn boundary) --
+				case "user": {
+					const userMsg = msg as SDKUserMessage;
+					if (userMsg.parent_tool_use_id !== null) break;
+
+					// Capture accumulated text from the builder before resetting
+					if (builder) {
+						for (const block of builder.message.content) {
+							if (block.type === "text" && block.text) {
+								lastTextContent = block.text;
+							} else if (block.type === "thinking" && block.thinking) {
+								lastThinkingContent = block.thinking;
+							}
+						}
+					}
+					builder = null;
+					break;
+				}
+
+				// -- Result (terminal) --
+				case "result": {
+					const result = msg as SDKResultMessage;
+
+					// Build final message with text/thinking only (strip tool calls)
+					const finalContent: AssistantMessage["content"] = [];
+
+					// Use builder's accumulated content if available, falling back to captured text
+					if (builder) {
+						for (const block of builder.message.content) {
+							if (block.type === "text" && block.text) {
+								lastTextContent = block.text;
+							} else if (block.type === "thinking" && block.thinking) {
+								lastThinkingContent = block.thinking;
+							}
+						}
+					}
+
+					if (lastThinkingContent) {
+						finalContent.push({ type: "thinking", thinking: lastThinkingContent });
+					}
+					if (lastTextContent) {
+						finalContent.push({ type: "text", text: lastTextContent });
+					}
+
+					// Fallback: use the SDK's result text if we have no content
+					if (finalContent.length === 0 && result.subtype === "success" && result.result) {
+						finalContent.push({ type: "text", text: result.result });
+					}
+
+					const finalMessage: AssistantMessage = {
+						role: "assistant",
+						content: finalContent,
+						api: "anthropic-messages",
+						provider: "claude-code",
+						model: modelId,
+						usage: mapUsage(result.usage, result.total_cost_usd),
+						stopReason: result.is_error ? "error" : "stop",
+						timestamp: Date.now(),
+					};
+
+					if (result.is_error) {
+						const errText =
+							"errors" in result
+								? (result as any).errors?.join("; ")
+								: result.subtype;
+						finalMessage.errorMessage = errText;
+						stream.push({ type: "error", reason: "error", error: finalMessage });
+					} else {
+						stream.push({ type: "done", reason: "stop", message: finalMessage });
+					}
+					return;
+				}
+
+				default:
+					break;
+			}
+		}
+
+		// Generator exhausted without a result message (unexpected)
+		const fallbackContent: AssistantMessage["content"] = [];
+		if (lastTextContent) {
+			fallbackContent.push({ type: "text", text: lastTextContent });
+		}
+		if (fallbackContent.length === 0) {
+			fallbackContent.push({ type: "text", text: "(Claude Code session ended without a response)" });
+		}
+
+		const fallback: AssistantMessage = {
+			role: "assistant",
+			content: fallbackContent,
+			api: "anthropic-messages",
+			provider: "claude-code",
+			model: modelId,
+			usage: { ...ZERO_USAGE },
+			stopReason: "stop",
+			timestamp: Date.now(),
+		};
+		stream.push({ type: "done", reason: "stop", message: fallback });
+	} catch (err) {
+		const errorMsg = err instanceof Error ? err.message : String(err);
+		stream.push({
+			type: "error",
+			reason: "error",
+			error: makeErrorMessage(modelId, errorMsg),
+		});
+	}
+}

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -32,6 +32,6 @@ Then:
 11. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
 12. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
 
-**You MUST do ALL THREE before finishing: (1) write `{{sliceSummaryPath}}`, (2) write `{{sliceUatPath}}`, (3) call `gsd_complete_slice`. The unit will not be marked complete if any of these are missing.**
+**You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
 
 When done, say: "Slice {{sliceId}} complete."

package/src/resources/extensions/gsd/prompts/guided-plan-milestone.md

@@ -10,10 +10,10 @@ Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.gsd/DECISIONS.md`
 ## Planning Doctrine
 
 - **Risk-first means proof-first.** The earliest slices should prove the hardest thing works by shipping the real feature through the uncertain path. If auth is the risk, the first slice ships a real login page with real session handling that a user can actually use — not a CLI command that returns "authenticated: true". Proof is the shipped feature working. There is no separate "proof" artifact. Do not plan spikes, proof-of-concept slices, or validation-only slices — the proof is the real feature, built through the risky path.
-- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means you could show a stakeholder and they'd see real product progress — not a developer showing a terminal command. If the only way to demonstrate the slice is through a test runner or a curl command, the slice is missing its UI/UX surface. Add it. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
+- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means the intended user can exercise the capability through its real interface — for a web app that's the UI, for a CLI tool that's the terminal, for an API that's a consuming client or curl. The test is: can someone *use* it, not just *assert* it passes. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
 - **Brownfield bias.** When planning against an existing codebase, ground slices in existing modules, conventions, and seams. Prefer extending real patterns over inventing new ones.
 - **Each slice should establish something downstream slices can depend on.** Think about what stable surface this slice creates for later work — an API, a data shape, a proven integration path.
-- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it.
+- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it. Exception: if the infrastructure *is* the product surface (a new protocol, extension API, or provider interface), the slice is vertical by definition — the downstream consumer is the demo.
 - **Verification-first.** When planning slices, know what "done" looks like before detailing implementation. Each slice's demo line should describe concrete, verifiable evidence — not vague "it works" claims.
 - **Plan for integrated reality, not just local proof.** Distinguish contract proof from live integration proof. If the milestone involves multiple runtime boundaries, one slice must explicitly prove the assembled system through the real entrypoint or runtime path.
 - **Truthful demo lines only.** If a slice is proven by fixtures or tests only, say so. Do not phrase harness-level proof as if the user can already perform the live end-to-end behavior unless that has actually been exercised.

package/src/resources/extensions/gsd/prompts/plan-milestone.md

@@ -64,10 +64,10 @@ Then:
 Apply these when decomposing and ordering slices:
 
 - **Risk-first means proof-first.** The earliest slices should prove the hardest thing works by shipping the real feature through the uncertain path. If auth is the risk, the first slice ships a real login page with real session handling that a user can actually use — not a CLI command that returns "authenticated: true". Proof is the shipped feature working. There is no separate "proof" artifact. Do not plan spikes, proof-of-concept slices, or validation-only slices — the proof is the real feature, built through the risky path.
-- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means you could show a stakeholder and they'd see real product progress — not a developer showing a terminal command. If the only way to demonstrate the slice is through a test runner or a curl command, the slice is missing its UI/UX surface. Add it. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
+- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means the intended user can exercise the capability through its real interface — for a web app that's the UI, for a CLI tool that's the terminal, for an API that's a consuming client or curl. The test is: can someone *use* it, not just *assert* it passes. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
 - **Brownfield bias.** When planning against an existing codebase, ground slices in existing modules, conventions, and seams. Prefer extending real patterns over inventing new ones.
 - **Each slice should establish something downstream slices can depend on.** Think about what stable surface this slice creates for later work — an API, a data shape, a proven integration path.
-- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it.
+- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it. Exception: if the infrastructure *is* the product surface (a new protocol, extension API, or provider interface), the slice is vertical by definition — the downstream consumer is the demo.
 - **Verification-first.** When planning slices, know what "done" looks like before detailing implementation. Each slice's demo line should describe concrete, verifiable evidence — not vague "it works" claims.
 - **Plan for integrated reality, not just local proof.** Distinguish contract proof from live integration proof. If the milestone involves multiple runtime boundaries, one slice must explicitly prove the assembled system through the real entrypoint or runtime path.
 - **Truthful demo lines only.** If a slice is proven by fixtures or tests only, say so. Do not phrase harness-level proof as if the user can already perform the live end-to-end behavior unless that has actually been exercised.

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -77,6 +77,6 @@ Then:
 
 The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. All work stays in your working directory: `{{workingDirectory}}`.
 
-**You MUST write the file `{{outputPath}}` before finishing.**
+**You MUST call `gsd_plan_slice` to persist the planning state before finishing.**
 
 When done, say: "Slice {{sliceId}} planned."

package/src/resources/extensions/gsd/prompts/research-milestone.md

@@ -28,7 +28,7 @@ Then research the codebase and relevant technologies. Narrate key findings and s
 5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit.
 6. Use the **Research** output template from the inlined context above — include only sections that have real content
 7. If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
-8. Write `{{outputPath}}`
+8. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `artifact_type: "RESEARCH"`, and the full research markdown as `content` — the tool computes the file path and persists to both DB and disk.
 
 ## Strategic Questions to Answer
 
@@ -42,6 +42,6 @@ Then research the codebase and relevant technologies. Narrate key findings and s
 
 **Research is advisory, not auto-binding.** Surface candidate requirements clearly instead of silently expanding scope.
 
-**You MUST write the file `{{outputPath}}` before finishing.**
+**You MUST call `gsd_summary_save` with the research content before finishing.**
 
 When done, say: "Milestone {{milestoneId}} researched."

package/src/resources/extensions/gsd/prompts/run-uat.md

@@ -55,7 +55,7 @@ After running all checks, compute the **overall verdict**:
 - `FAIL` — one or more checks failed
 - `PARTIAL` — some checks passed, but one or more checks were skipped, inconclusive, or still require human judgment
 
-Write `{{uatResultPath}}` with:
+Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "ASSESSMENT"`, and the full UAT result markdown as `content` — the tool computes the file path and persists to both DB and disk. The content should follow this format:
 
 ```markdown
 ---
@@ -84,6 +84,6 @@ date: <ISO 8601 timestamp>
 
 ---
 
-**You MUST write `{{uatResultPath}}` before finishing.**
+**You MUST call `gsd_summary_save` with the UAT result content before finishing.**
 
 When done, say: "UAT {{sliceId}} complete."

package/src/resources/extensions/gsd/tests/plan-slice-prompt.test.ts

@@ -61,6 +61,18 @@ test("plan-slice prompt: DB-backed tool names survive template substitution", ()
   assert.ok(result.includes("canonical write path"), "canonical write path language should survive substitution");
 });
 
+test("plan-slice prompt: footer references gsd_plan_slice tool, not direct write", () => {
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
+  assert.ok(
+    result.includes("MUST call `gsd_plan_slice`"),
+    "footer should instruct calling gsd_plan_slice tool",
+  );
+  assert.ok(
+    !result.includes("MUST write the file"),
+    "footer should not instruct direct file write",
+  );
+});
+
 test("domain-work prompts use skillActivation placeholder", () => {
   const prompts = [
     "research-milestone",
@@ -174,6 +186,34 @@ test("research-milestone prompt substitutes skillActivation", () => {
   assert.ok(!result.includes("{{skillActivation}}"));
 });
 
+test("research-milestone prompt references gsd_summary_save, not direct write", () => {
+  const result = loadPrompt("research-milestone", {
+    workingDirectory: "/tmp/test-project",
+    milestoneId: "M001",
+    milestoneTitle: "Test Milestone",
+    milestonePath: ".gsd/milestones/M001",
+    contextPath: ".gsd/milestones/M001/M001-CONTEXT.md",
+    outputPath: "/tmp/test-project/.gsd/milestones/M001/M001-RESEARCH.md",
+    inlinedContext: "Context",
+    skillDiscoveryMode: "manual",
+    skillDiscoveryInstructions: " Discover skills manually.",
+    skillActivation: "Load research skills first.",
+  });
+
+  assert.ok(
+    result.includes("gsd_summary_save"),
+    "research-milestone should reference gsd_summary_save tool",
+  );
+  assert.ok(
+    result.includes('artifact_type: "RESEARCH"'),
+    "research-milestone should specify RESEARCH artifact type",
+  );
+  assert.ok(
+    !result.includes("MUST write the file"),
+    "research-milestone should not instruct direct file write",
+  );
+});
+
 test("research-slice prompt substitutes skillActivation", () => {
   const result = loadPrompt("research-slice", {
     workingDirectory: "/tmp/test-project",

package/src/resources/extensions/gsd/tests/run-uat.test.ts

@@ -228,6 +228,31 @@ test('(k) run-uat prompt template', () => {
   );
 });
 
+test('(k2) run-uat prompt references gsd_summary_save, not direct write', () => {
+  const promptResult = loadPromptFromWorktree('run-uat', {
+    workingDirectory: '/tmp/test-project',
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    uatPath: '.gsd/milestones/M001/slices/S01/S01-UAT.md',
+    uatResultPath: '.gsd/milestones/M001/slices/S01/S01-UAT-RESULT.md',
+    uatType: 'artifact-driven',
+    inlinedContext: '<!-- no context -->',
+  });
+
+  assert.ok(
+    promptResult.includes('gsd_summary_save'),
+    'run-uat prompt should reference gsd_summary_save tool',
+  );
+  assert.ok(
+    promptResult.includes('artifact_type: "ASSESSMENT"'),
+    'run-uat prompt should specify ASSESSMENT artifact type',
+  );
+  assert.ok(
+    !promptResult.includes('MUST write'),
+    'run-uat prompt should not instruct direct file write in footer',
+  );
+});
+
 test('(l) dispatch preconditions via resolveSliceFile', () => {
     const base = createFixtureBase();
     const uatContent = makeUatContent('artifact-driven');

package/src/resources/extensions/gsd/workflow-events.ts

@@ -40,7 +40,7 @@ export function appendEvent(
   event: Omit<WorkflowEvent, "hash" | "session_id"> & { actor_name?: string; trigger_reason?: string },
 ): void {
   const hash = createHash("sha256")
-    .update(JSON.stringify({ cmd: event.cmd, params: event.params, ts: event.ts }))
+    .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
     .digest("hex")
     .slice(0, 16);