@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/tool-contract.ts

@@ -4,11 +4,19 @@
 import {
   resolveManifest,
   type ArtifactKey,
+  type ComputedArtifactId,
   type ContextModePolicy,
   type ToolsPolicy,
+  type UnitContextManifest,
 } from "./unit-context-manifest.js";
-import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
-import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
+import {
+  getWorkflowTransportSupportError,
+  type WorkflowCapabilityOptions,
+} from "./workflow-mcp.js";
+import {
+  getRequiredWorkflowToolsForUnit,
+  getUnitToolSurfaceContract,
+} from "./unit-tool-contracts.js";
 import {
   WHOLE_FILE_OBSERVATION_MAX_BYTES,
   WHOLE_FILE_OBSERVATION_MAX_LINES,
@@ -21,6 +29,7 @@ export interface UnitToolContract {
   requiredWorkflowTools: readonly string[];
   forbiddenWorkflowTools: readonly { name: string; reason: string }[];
   promptObligations: readonly string[];
+  promptContext: UnitPromptContextContract;
   validationRules: readonly string[];
   closeoutTools: readonly string[];
   sourceObservations: UnitSourceObservationContract;
@@ -31,6 +40,22 @@ export interface UnitToolContract {
   };
 }
 
+export interface UnitPromptContextContract {
+  unitType: string;
+  contextMode: ContextModePolicy;
+  toolsPolicy: ToolsPolicy;
+  obligations: readonly string[];
+  sourceObservations: UnitSourceObservationContract;
+  artifacts: {
+    inline: readonly ArtifactKey[];
+    excerpt: readonly ArtifactKey[];
+    onDemand: readonly ArtifactKey[];
+    computed: readonly ComputedArtifactId[];
+    prepend: readonly ComputedArtifactId[];
+  };
+  maxSystemPromptChars: number;
+}
+
 export type UnitSourceObservationContract =
   | { mode: "none" }
   | {
@@ -45,6 +70,51 @@ export type ToolContractResult =
   | { ok: true; contract: UnitToolContract }
   | { ok: false; reason: "unknown-unit-type" | "missing-closeout-tool"; detail: string };
 
+export type UnitContextContractResult =
+  | { ok: true; contract: UnitPromptContextContract }
+  | { ok: false; reason: "unknown-unit-type"; detail: string };
+
+export interface UnitWorkflowDispatchReadinessInput {
+  provider?: string;
+  unitType: string;
+  projectRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  surface?: string;
+  authMode?: WorkflowCapabilityOptions["authMode"];
+  baseUrl?: string;
+  activeTools?: string[];
+}
+
+export function compileUnitContextContract(unitType: string): UnitContextContractResult {
+  const manifest = resolveManifest(unitType);
+  if (!manifest) {
+    return {
+      ok: false,
+      reason: "unknown-unit-type",
+      detail: `No Unit manifest is registered for ${unitType}`,
+    };
+  }
+  return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
+}
+
+export function getUnitWorkflowDispatchReadinessError(
+  input: UnitWorkflowDispatchReadinessInput,
+): string | null {
+  return getWorkflowTransportSupportError(
+    input.provider,
+    getRequiredWorkflowToolsForUnit(input.unitType),
+    {
+      projectRoot: input.projectRoot,
+      env: input.env,
+      surface: input.surface,
+      unitType: input.unitType,
+      authMode: input.authMode,
+      baseUrl: input.baseUrl,
+      activeTools: input.activeTools,
+    },
+  );
+}
+
 export function compileUnitToolContract(unitType: string): ToolContractResult {
   const manifest = resolveManifest(unitType);
   const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -56,7 +126,7 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
     };
   }
 
-  const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+  const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType);
   const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
     .map(([name, reason]) => ({ name, reason }));
   const closeoutTools = requiredWorkflowTools.filter((tool) =>
@@ -71,6 +141,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
     };
   }
 
+  const promptContext = buildPromptContextContract(unitType, manifest);
+
   return {
     ok: true,
     contract: {
@@ -79,10 +151,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
       toolsPolicy: manifest.tools,
       requiredWorkflowTools,
       forbiddenWorkflowTools,
-      promptObligations: [
-        `context-mode:${manifest.contextMode}`,
-        `tools-policy:${manifest.tools.mode}`,
-      ],
+      promptObligations: promptContext.obligations,
+      promptContext,
       validationRules: [
         "unit-manifest-present",
         "workflow-tool-surface-present",
@@ -90,16 +160,59 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
         ...(unitType === "execute-task" ? ["source-observation-contract-present"] : []),
       ],
       closeoutTools,
-      sourceObservations: sourceObservationContractForUnit(unitType),
+      sourceObservations: promptContext.sourceObservations,
       artifacts: {
-        inline: manifest.artifacts.inline,
-        excerpt: manifest.artifacts.excerpt,
-        onDemand: manifest.artifacts.onDemand,
+        inline: promptContext.artifacts.inline,
+        excerpt: promptContext.artifacts.excerpt,
+        onDemand: promptContext.artifacts.onDemand,
       },
     },
   };
 }
 
+function buildPromptContextContract(
+  unitType: string,
+  manifest: UnitContextManifest,
+): UnitPromptContextContract {
+  const sourceObservations = sourceObservationContractForUnit(unitType);
+  return {
+    unitType,
+    contextMode: manifest.contextMode,
+    toolsPolicy: manifest.tools,
+    obligations: promptContextObligations(manifest, sourceObservations),
+    sourceObservations,
+    artifacts: {
+      inline: manifest.artifacts.inline,
+      excerpt: manifest.artifacts.excerpt,
+      onDemand: manifest.artifacts.onDemand,
+      computed: manifest.artifacts.computed ?? [],
+      prepend: manifest.prepend ?? [],
+    },
+    maxSystemPromptChars: manifest.maxSystemPromptChars,
+  };
+}
+
+function promptContextObligations(
+  manifest: UnitContextManifest,
+  sourceObservations: UnitSourceObservationContract,
+): string[] {
+  const obligations = [
+    `context-mode:${manifest.contextMode}`,
+    `tools-policy:${manifest.tools.mode}`,
+    artifactObligation("context-inline", manifest.artifacts.inline),
+    artifactObligation("context-excerpt", manifest.artifacts.excerpt),
+    artifactObligation("context-on-demand", manifest.artifacts.onDemand),
+  ];
+  if (sourceObservations.mode !== "none") {
+    obligations.push(`source-observations:${sourceObservations.mode}`);
+  }
+  return obligations;
+}
+
+function artifactObligation(label: string, artifacts: readonly ArtifactKey[]): string {
+  return `${label}:${artifacts.length > 0 ? artifacts.join(",") : "none"}`;
+}
+
 function sourceObservationContractForUnit(unitType: string): UnitSourceObservationContract {
   if (unitType !== "execute-task") return { mode: "none" };
   return {

package/src/resources/extensions/gsd/tool-presentation-plan.ts

@@ -7,7 +7,10 @@ import {
   RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
   RUN_UAT_WORKFLOW_TOOL_NAMES,
 } from "./unit-tool-contracts.js";
+import { parseMcpToolName, toMcpToolName } from "./mcp-tool-name.js";
+import { createToolSurfaceSnapshot, type ToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 
 export {
   RUN_UAT_BROWSER_TOOL_NAMES,
@@ -33,6 +36,7 @@ export interface ToolPresentationPlan {
   blockedToolNames: Array<{ name: string; reason: string }>;
   aliases: Array<{ requested: string; canonical: string }>;
   diagnostics: string[];
+  toolSurface: ToolSurfaceSnapshot;
 }
 
 export interface RunUatResultPresentation {
@@ -62,44 +66,14 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
   "Grep",
 ] as const;
 
-const WORKFLOW_ALIAS_TO_CANONICAL: Record<string, string> = {
-  gsd_save_decision: "gsd_decision_save",
-  gsd_update_requirement: "gsd_requirement_update",
-  gsd_save_requirement: "gsd_requirement_save",
-  gsd_save_summary: "gsd_summary_save",
-  gsd_generate_milestone_id: "gsd_milestone_generate_id",
-  gsd_milestone_plan: "gsd_plan_milestone",
-  gsd_slice_plan: "gsd_plan_slice",
-  gsd_task_plan: "gsd_plan_task",
-  gsd_slice_replan: "gsd_replan_slice",
-  gsd_complete_slice: "gsd_slice_complete",
-  gsd_milestone_complete: "gsd_complete_milestone",
-  gsd_milestone_validate: "gsd_validate_milestone",
-  gsd_roadmap_reassess: "gsd_reassess_roadmap",
-  gsd_complete_task: "gsd_task_complete",
-  gsd_reopen_task: "gsd_task_reopen",
-  gsd_reopen_slice: "gsd_slice_reopen",
-  gsd_reopen_milestone: "gsd_milestone_reopen",
-};
-
-export function canonicalWorkflowToolName(toolName: string): string {
-  const mcp = parseMcpToolName(toolName);
-  const baseName = mcp?.tool ?? toolName;
-  return WORKFLOW_ALIAS_TO_CANONICAL[baseName] ?? baseName;
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing presentation importers (uat-run.ts).
+export { canonicalWorkflowToolName };
 
-export function parseMcpToolName(toolName: string): { server: string; tool: string } | null {
-  if (!toolName.startsWith("mcp__")) return null;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  if (toolSeparator < 0) return null;
-  return {
-    server: toolName.slice("mcp__".length, toolSeparator),
-    tool: toolName.slice(toolSeparator + 2),
-  };
-}
+export { parseMcpToolName } from "./mcp-tool-name.js";
 
 export function toWorkflowMcpToolName(serverName: string, toolName: string): string {
-  return `mcp__${serverName}__${canonicalWorkflowToolName(toolName)}`;
+  return toMcpToolName(serverName, canonicalWorkflowToolName(toolName));
 }
 
 function dedupe(values: readonly string[]): string[] {
@@ -212,6 +186,14 @@ export function resolveToolPresentationPlan(options: {
           : name
       )
     : allowedToolNames;
+  const toolSurface = createToolSurfaceSnapshot({
+    source: "presentation-plan",
+    phase: options.phase,
+    modelFacingToolNames: options.availableToolNames ?? requested,
+    registeredToolNames: options.availableToolNames ?? requested,
+    scopedToolNames: allowedToolNames,
+    presentedToolNames,
+  });
 
   if (options.phase === "run-uat") {
     for (const forbidden of RUN_UAT_FORBIDDEN_TOOL_NAMES) {
@@ -228,5 +210,6 @@ export function resolveToolPresentationPlan(options: {
     blockedToolNames,
     aliases,
     diagnostics: [],
+    toolSurface,
   };
 }

package/src/resources/extensions/gsd/tool-surface-readiness.ts

@@ -0,0 +1,183 @@
+// Project/App: gsd-pi
+// File Purpose: Tool Contract module's runtime face — verify the live SDK tool surface covers a Unit's required workflow tools.
+
+import { testMcpServerConnection } from "../mcp-client/manager.js";
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import {
+  recordWorkflowMcpProbe,
+  WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+} from "./workflow-mcp-readiness-cache.js";
+import { resolveWorkflowMcpProjectRoot } from "./workflow-mcp.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+
+/**
+ * Stable phrase recognized as transient by auto-tool-tracking's
+ * isToolUnavailableError and error-classifier's transient buckets,
+ * which build their matchers from this constant.
+ */
+export const TOOL_SURFACE_NOT_READY = "workflow tool surface not ready";
+
+/** MCP server statuses that will not self-heal within the session. */
+const TERMINAL_MCP_SERVER_STATUSES = new Set(["failed", "needs-auth", "disabled"]);
+
+export interface LiveToolSurfaceObservation {
+  /** Tool names the session reported at init (MCP tools appear as mcp__<server>__<tool>). */
+  tools: readonly string[];
+  /** MCP server connection statuses the session reported at init. */
+  mcpServers: readonly { name: string; status: string }[];
+}
+
+/**
+ * Verify the live tool surface observed at SDK session init covers the Unit's
+ * required workflow tools. Complements the static pre-dispatch gate
+ * (getWorkflowTransportSupportError), which only proves the MCP launch config
+ * is discoverable — the workflow server connects asynchronously after session
+ * start, so the static gate cannot see whether the tools actually registered.
+ *
+ * Returns a transient, recovery-classifiable error (kind tool-unavailable →
+ * retry) when the workflow server failed or has not yet registered a required
+ * tool, so dispatch aborts before the first model turn instead of letting the
+ * Unit improvise around "No such tool available". Returns null when no
+ * workflow server is part of this session (native tool path), when the Unit
+ * requires no workflow tools, or when the surface is ready.
+ */
+export interface WorkflowMcpToolProbeResult {
+  ok: boolean;
+  tools: readonly string[];
+}
+
+export type WorkflowMcpToolProbe = (
+  serverName: string,
+  projectRoot: string,
+) => Promise<WorkflowMcpToolProbeResult>;
+
+export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_TIMEOUT_MS = 30_000;
+export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS = 200;
+const RUN_UAT_PREFLIGHT_TIMEOUT_MS = 90_000;
+
+function resolveWorkflowMcpPreflightTimeoutMs(unitType: string | undefined): number {
+  if (unitType === "run-uat") return RUN_UAT_PREFLIGHT_TIMEOUT_MS;
+  return DEFAULT_WORKFLOW_MCP_PREFLIGHT_TIMEOUT_MS;
+}
+
+export function probeCoversRequiredWorkflowTools(
+  tools: readonly string[],
+  required: readonly string[],
+): boolean {
+  return required.every((tool) =>
+    tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+  );
+}
+
+export async function awaitWorkflowMcpToolRegistration(input: {
+  unitType: string | undefined;
+  workflowServerName: string | undefined;
+  projectRoot: string;
+  timeoutMs?: number;
+  pollMs?: number;
+  probe?: WorkflowMcpToolProbe;
+  signal?: AbortSignal;
+}): Promise<string | null> {
+  const { unitType, workflowServerName, projectRoot } = input;
+  if (!unitType || !workflowServerName) return null;
+
+  const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+  if (required.length === 0) return null;
+
+  const probe = input.probe ?? (async (serverName, root) => {
+    const result = await testMcpServerConnection(serverName, {
+      projectDir: resolveWorkflowMcpProjectRoot(root),
+      timeoutMs: WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+    });
+    return { ok: result.ok, tools: result.tools };
+  });
+
+  const deadline = Date.now() + (input.timeoutMs ?? resolveWorkflowMcpPreflightTimeoutMs(unitType));
+  const pollMs = input.pollMs ?? DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS;
+
+  while (Date.now() < deadline) {
+    throwIfAborted(input.signal);
+    const result = await probe(workflowServerName, projectRoot);
+    throwIfAborted(input.signal);
+    if (result.ok && probeCoversRequiredWorkflowTools(result.tools, required)) {
+      recordWorkflowMcpProbe(projectRoot, workflowServerName, result.tools);
+      return null;
+    }
+    await sleep(pollMs, input.signal);
+  }
+
+  return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" did not register required tools before session start: ${required.join(", ")}`;
+}
+
+function makeAbortError(): Error {
+  const error = new Error("AbortError: The operation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw makeAbortError();
+}
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  throwIfAborted(signal);
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timeout);
+      reject(makeAbortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Brief pause after a successful preflight before SDK query (race with MCP attach). */
+export const POST_PREFLIGHT_SDK_SETTLE_MS = 750;
+
+export const POST_PREFLIGHT_READINESS_RETRY_DELAYS_MS = [
+  1_000, 2_000, 3_000, 5_000, 8_000, 10_000, 15_000, 15_000, 15_000, 15_000,
+] as const;
+
+export function getToolSurfaceReadinessError(input: {
+  unitType: string | undefined;
+  workflowServerName: string | undefined;
+  observation: LiveToolSurfaceObservation;
+  projectRoot?: string | undefined;
+}): string | null {
+  const { unitType, workflowServerName, observation } = input;
+  if (!unitType || !workflowServerName) return null;
+
+  const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+  if (required.length === 0) return null;
+
+  const server = observation.mcpServers.find((entry) => entry.name === workflowServerName);
+  if (server && TERMINAL_MCP_SERVER_STATUSES.has(server.status)) {
+    const missing = required.filter(
+      (tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+    );
+    const tools = missing.length > 0 ? missing : required;
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" status is "${server.status}" (terminal) — cannot register: ${tools.join(", ")}`;
+  }
+
+  const missing = required.filter(
+    (tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+  );
+  if (missing.length === 0) {
+    return null;
+  }
+
+  if (!server) {
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is absent from the init surface (not yet connected): ${missing.join(", ")}`;
+  }
+
+  if (server.status !== "connected") {
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" status is "${server.status}" (not yet connected): ${missing.join(", ")}`;
+  }
+
+  return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is connected but has not registered: ${missing.join(", ")}`;
+}

package/src/resources/extensions/gsd/tool-surface-snapshot.ts

@@ -0,0 +1,47 @@
+// Project/App: gsd-pi
+// File Purpose: Typed snapshots for model-facing, registered, scoped, and presented tool surfaces.
+
+export type ToolSurfaceSnapshotSource =
+  | "runtime-scope"
+  | "dispatch-scope"
+  | "provider-adjustment"
+  | "presentation-plan";
+
+export interface ToolSurfaceSnapshot {
+  source: ToolSurfaceSnapshotSource;
+  unitType?: string;
+  phase?: string;
+  modelFacingToolNames: string[];
+  registeredToolNames: string[];
+  scopedToolNames: string[];
+  presentedToolNames: string[];
+  capturedAt: number;
+}
+
+export interface ToolSurfaceSnapshotInput {
+  source: ToolSurfaceSnapshotSource;
+  unitType?: string;
+  phase?: string;
+  modelFacingToolNames?: readonly string[];
+  registeredToolNames?: readonly string[];
+  scopedToolNames?: readonly string[];
+  presentedToolNames?: readonly string[];
+  capturedAt?: number;
+}
+
+function dedupeToolNames(toolNames: readonly string[] | undefined): string[] {
+  return [...new Set(toolNames ?? [])];
+}
+
+export function createToolSurfaceSnapshot(input: ToolSurfaceSnapshotInput): ToolSurfaceSnapshot {
+  return {
+    source: input.source,
+    unitType: input.unitType,
+    phase: input.phase,
+    modelFacingToolNames: dedupeToolNames(input.modelFacingToolNames),
+    registeredToolNames: dedupeToolNames(input.registeredToolNames),
+    scopedToolNames: dedupeToolNames(input.scopedToolNames),
+    presentedToolNames: dedupeToolNames(input.presentedToolNames),
+    capturedAt: input.capturedAt ?? Date.now(),
+  };
+}

package/src/resources/extensions/gsd/tools/complete-milestone.ts

@@ -26,7 +26,8 @@ import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { isClosedStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections, stripIdPrefix } from "../workflow-projections.js";
+import { stripIdPrefix } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -240,7 +241,7 @@ export async function handleCompleteMilestone(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await renderAllProjections(artifactBasePath, params.milestoneId);
+    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
   } catch (projErr) {
     logWarning("tool", `complete-milestone projection warning: ${(projErr as Error).message}`);
   }