gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -0,0 +1,183 @@
+// GSD Exec Tool — executor for the gsd_exec MCP tool.
+//
+// Thin wrapper around exec-sandbox.ts that reads effective options from
+// the project preferences (context_mode block) and formats the result
+// for MCP return.
+
+import {
+  EXEC_DEFAULTS,
+  runExecSandbox,
+  type ExecSandboxOptions,
+  type ExecSandboxRequest,
+  type ExecSandboxResult,
+} from "../exec-sandbox.js";
+import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
+
+export interface ExecToolParams {
+  runtime: ExecSandboxRequest["runtime"];
+  script: string;
+  purpose?: string;
+  timeout_ms?: number;
+}
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+export interface ExecToolDeps {
+  baseDir: string;
+  preferences: { context_mode?: ContextModeConfig } | null;
+  /** Optional override for testing. */
+  run?: (req: ExecSandboxRequest, opts: ExecSandboxOptions) => Promise<ExecSandboxResult>;
+  now?: () => Date;
+  generateId?: () => string;
+}
+
+export function buildExecOptions(
+  baseDir: string,
+  cfg: ContextModeConfig | undefined,
+  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId">,
+): ExecSandboxOptions {
+  const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg!.exec_env_allowlist! : EXEC_DEFAULTS.envAllowlist;
+  const stdoutCap = clampNumber(
+    cfg?.exec_stdout_cap_bytes,
+    EXEC_DEFAULTS.stdoutCapBytes,
+    4_096,
+    16_777_216,
+  );
+  const defaultTimeout = clampNumber(
+    cfg?.exec_timeout_ms,
+    EXEC_DEFAULTS.defaultTimeoutMs,
+    1_000,
+    EXEC_DEFAULTS.clampTimeoutMs,
+  );
+  const digestChars = clampNumber(cfg?.exec_digest_chars, EXEC_DEFAULTS.digestChars, 0, 4_000);
+  return {
+    baseDir,
+    clamp_timeout_ms: EXEC_DEFAULTS.clampTimeoutMs,
+    default_timeout_ms: defaultTimeout,
+    stdout_cap_bytes: stdoutCap,
+    stderr_cap_bytes: EXEC_DEFAULTS.stderrCapBytes,
+    digest_chars: digestChars,
+    env_allowlist: allowlist,
+    ...extras,
+  };
+}
+
+function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  if (value < min) return min;
+  if (value > max) return max;
+  return Math.floor(value);
+}
+
+function isEnabled(prefs: ExecToolDeps["preferences"]): boolean {
+  return isContextModeEnabled(prefs);
+}
+
+function disabledResult(): ToolExecutionResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text:
+          "gsd_exec is disabled by `context_mode.enabled: false` in preferences. Remove that " +
+          "override (or set it to true) to re-enable sandboxed tool-output execution.",
+      },
+    ],
+    details: { operation: "gsd_exec", error: "context_mode_disabled" },
+    isError: true,
+  };
+}
+
+function paramError(message: string): ToolExecutionResult {
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    details: { operation: "gsd_exec", error: "invalid_params", detail: message },
+    isError: true,
+  };
+}
+
+export async function executeGsdExec(
+  params: ExecToolParams,
+  deps: ExecToolDeps,
+): Promise<ToolExecutionResult> {
+  if (!isEnabled(deps.preferences)) return disabledResult();
+
+  const runtime = params.runtime;
+  if (runtime !== "bash" && runtime !== "node" && runtime !== "python") {
+    return paramError(`invalid runtime "${String(runtime)}" — must be bash | node | python`);
+  }
+  const script = typeof params.script === "string" ? params.script : "";
+  if (script.trim().length === 0) {
+    return paramError("script is required and must be a non-empty string");
+  }
+  if (Buffer.byteLength(script, "utf8") > 200_000) {
+    return paramError("script exceeds the 200 KB length limit");
+  }
+
+  const opts = buildExecOptions(
+    deps.baseDir,
+    deps.preferences?.context_mode,
+    { now: deps.now, generateId: deps.generateId },
+  );
+  const run = deps.run ?? runExecSandbox;
+
+  try {
+    const result = await run(
+      {
+        runtime,
+        script,
+        ...(typeof params.purpose === "string" ? { purpose: params.purpose } : {}),
+        ...(typeof params.timeout_ms === "number" ? { timeout_ms: params.timeout_ms } : {}),
+      },
+      opts,
+    );
+    return formatResult(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Error: gsd_exec failed — ${message}` }],
+      details: { operation: "gsd_exec", error: message },
+      isError: true,
+    };
+  }
+}
+
+function formatResult(result: ExecSandboxResult): ToolExecutionResult {
+  const headerLines = [
+    `gsd_exec[${result.id}] runtime=${result.runtime} exit=${formatExit(result)} duration=${result.duration_ms}ms`,
+    `  stdout: ${result.stdout_bytes}B${result.stdout_truncated ? " (truncated)" : ""} → ${result.stdout_path}`,
+    `  stderr: ${result.stderr_bytes}B${result.stderr_truncated ? " (truncated)" : ""} → ${result.stderr_path}`,
+  ];
+  const summary = `${headerLines.join("\n")}\n--- digest ---\n${result.digest}`.trimEnd();
+  return {
+    content: [{ type: "text", text: summary }],
+    details: {
+      operation: "gsd_exec",
+      id: result.id,
+      runtime: result.runtime,
+      exit_code: result.exit_code,
+      signal: result.signal,
+      timed_out: result.timed_out,
+      duration_ms: result.duration_ms,
+      stdout_bytes: result.stdout_bytes,
+      stderr_bytes: result.stderr_bytes,
+      stdout_truncated: result.stdout_truncated,
+      stderr_truncated: result.stderr_truncated,
+      stdout_path: result.stdout_path,
+      stderr_path: result.stderr_path,
+      meta_path: result.meta_path,
+    },
+    isError: result.timed_out || result.signal !== null || result.exit_code !== 0,
+  };
+}
+
+function formatExit(result: ExecSandboxResult): string {
+  if (result.timed_out) return "timeout";
+  if (result.signal) return `signal:${result.signal}`;
+  if (result.exit_code === null) return "null";
+  return String(result.exit_code);
+}

package/src/resources/extensions/gsd/tools/memory-tools.ts

@@ -48,6 +48,14 @@ export interface MemoryCaptureParams {
   confidence?: number;
   tags?: string[];
   scope?: string;
+  /**
+   * ADR-013 Step 2: optional structured payload preserved verbatim on the
+   * memories row. Used when capturing decisions that need to retain
+   * gsd_save_decision-style fields (scope, decision, choice, rationale,
+   * made_by, revisable) so the eventual cutover (Step 6) is lossless.
+   * Plain pattern/gotcha/convention captures may omit this entirely.
+   */
+  structuredFields?: Record<string, unknown> | null;
 }
 
 const VALID_CATEGORIES = new Set([
@@ -87,7 +95,8 @@ export function executeMemoryCapture(params: MemoryCaptureParams): ToolExecution
   const scope = normalizeScope(params.scope);
   const tags = normalizeTags(params.tags);
 
-  const id = createMemory({ category, content, confidence, scope, tags });
+  const structuredFields = normalizeStructuredFields(params.structuredFields);
+  const id = createMemory({ category, content, confidence, scope, tags, structuredFields });
   if (!id) {
     return {
       content: [{ type: "text", text: "Error: failed to create memory." }],
@@ -113,6 +122,17 @@ function normalizeTags(value: unknown): string[] {
   return value.filter((t): t is string => typeof t === "string" && t.trim().length > 0).slice(0, 10);
 }
 
+function normalizeStructuredFields(value: unknown): Record<string, unknown> | null {
+  if (value == null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return null;
+  // Only accept plain objects (Object.prototype or null prototype). Class
+  // instances and exotic objects won't round-trip cleanly through JSON, so
+  // reject them here instead of producing a partially-serialized payload.
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== null && proto !== Object.prototype) return null;
+  return value as Record<string, unknown>;
+}
+
 function clampConfidence(value: unknown): number {
   if (typeof value !== "number" || !Number.isFinite(value)) return 0.8;
   if (value < 0.1) return 0.1;
@@ -248,6 +268,15 @@ function includeSupersededMemories(rankedActive: Memory[]): Memory[] {
           /* leave empty */
         }
       }
+      let structuredFields: Record<string, unknown> | null = null;
+      if (typeof row["structured_fields"] === "string" && (row["structured_fields"] as string).length > 0) {
+        try {
+          const parsed = JSON.parse(row["structured_fields"] as string);
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            structuredFields = parsed as Record<string, unknown>;
+          }
+        } catch { /* leave null */ }
+      }
       return {
         seq: row["seq"] as number,
         id: row["id"] as string,
@@ -262,6 +291,7 @@ function includeSupersededMemories(rankedActive: Memory[]): Memory[] {
         hit_count: row["hit_count"] as number,
         scope: (row["scope"] as string) ?? "project",
         tags,
+        structured_fields: structuredFields,
       };
     });
   } catch {

package/src/resources/extensions/gsd/tools/resume-tool.ts

@@ -0,0 +1,40 @@
+// GSD Resume Tool — returns the contents of .gsd/last-snapshot.md so
+// agents can re-orient after compaction or session resume without
+// re-deriving project memory state.
+
+import { readCompactionSnapshot } from "../compaction-snapshot.js";
+
+export interface ResumeToolParams {
+  /** Ignored — reserved for future variant (e.g. dated snapshots). */
+  _variant?: string;
+}
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+export function executeResume(
+  _params: ResumeToolParams,
+  opts: { baseDir: string },
+): ToolExecutionResult {
+  const snapshot = readCompactionSnapshot(opts.baseDir);
+  if (snapshot == null) {
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            "No snapshot found at .gsd/last-snapshot.md. The snapshot is written automatically " +
+            "on session_before_compact (enabled by default; set context_mode.enabled=false to opt out).",
+        },
+      ],
+      details: { operation: "gsd_resume", found: false },
+    };
+  }
+  return {
+    content: [{ type: "text", text: snapshot }],
+    details: { operation: "gsd_resume", found: true, bytes: Buffer.byteLength(snapshot, "utf-8") },
+  };
+}

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

@@ -18,6 +18,7 @@ import {
   getMilestoneSlices,
 } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
@@ -100,14 +101,19 @@ export async function handleValidateMilestone(
   }
 
   // ── Resolve paths and render markdown ────────────────────────────────
+  // #4761: route through the canonical-root resolver so that when a live
+  // worktree exists for this milestone, validation reads/writes the
+  // worktree's artifacts instead of stale project-root state.
   const validationMd = renderValidationMarkdown(params);
 
+  const canonicalBase = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
+
   let validationPath: string;
-  const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+  const milestoneDir = resolveMilestonePath(canonicalBase, params.milestoneId);
   if (milestoneDir) {
     validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
   } else {
-    const gsdDir = join(basePath, ".gsd");
+    const gsdDir = join(canonicalBase, ".gsd");
     const manualDir = join(gsdDir, "milestones", params.milestoneId);
     validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
   }

package/src/resources/extensions/gsd/types.ts

@@ -695,8 +695,8 @@ export interface CompleteSliceParams {
 
 export type GateId = "Q3" | "Q4" | "Q5" | "Q6" | "Q7" | "Q8" | "MV01" | "MV02" | "MV03" | "MV04";
 export type GateScope = "slice" | "task" | "milestone";
-export type GateStatus = "pending" | "complete" | "omitted";
-export type GateVerdict = "pass" | "flag" | "omitted" | "";
+export type GateStatus = "pending" | "complete";
+export type GateVerdict = "pass" | "flag" | "omitted";
 
 export interface GateRow {
   milestone_id: string;
@@ -705,7 +705,7 @@ export interface GateRow {
   scope: GateScope;
   task_id: string;
   status: GateStatus;
-  verdict: GateVerdict;
+  verdict: GateVerdict | null;
   rationale: string;
   findings: string;
   evaluated_at: string | null;

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -0,0 +1,218 @@
+// GSD-2 — UnitContextComposer (#4782 phase 2).
+//
+// Reads a unit type's manifest and orchestrates artifact inlining through
+// a caller-provided resolver. Returns a joined context block suitable for
+// substitution into the unit's prompt template.
+//
+// Design rationale:
+//   - Pure dependency on the manifest module — no circular import with
+//     `auto-prompts.ts` where the per-artifact-key resolver lives.
+//   - Caller-supplied resolver means the composer can be unit-tested with
+//     trivial mocks; production wiring in `auto-prompts.ts` dispatches to
+//     the existing `inlineFile` / `inline*FromDb` helpers.
+//   - Null-returning resolvers are skipped silently: they model the
+//     "artifact is optional / missing / not applicable to this milestone"
+//     case. The composer never errors on a missing artifact.
+//
+// Scope: phase 2 pilot shipped `composeInlinedContext` for static-key
+// inlining. Phase 3.5 (#4924) adds the v2 surface — `composeUnitContext`
+// — which also handles excerpts, computed artifacts, and prepended blocks.
+// `composeInlinedContext` stays for backward compatibility with the
+// already-migrated simple builders.
+//
+// ─── Composer boundary invariant (#4924) ─────────────────────────────────
+//
+// The composer is allowed to:
+//   - order named sections per the manifest's declared sequence
+//   - resolve registered artifacts (static / computed / excerpt / on-demand)
+//   - apply typed policies (knowledge / memory / codebase-map / preferences)
+//
+// The composer must NOT grow:
+//   - arbitrary conditionals on unit state
+//   - loops over caller-supplied data
+//   - string templating beyond section composition (join + separator)
+//
+// Logic that needs those belongs in a typed computed-artifact builder
+// owned by the unit, not in the composer. Reviews must enforce this — it
+// is the difference between an orchestrator and a runaway DSL.
+
+import {
+  resolveManifest,
+  type ArtifactKey,
+  type BaseResolverContext,
+  type ComputedArtifactId,
+  type ComputedArtifactRegistry,
+  type UnitContextManifest,
+} from "./unit-context-manifest.js";
+
+/**
+ * Async function mapping an artifact key to its inlined-content string,
+ * or `null` when the artifact does not apply to the current milestone
+ * (missing file, empty table, etc).
+ */
+export type ArtifactResolver = (key: ArtifactKey) => Promise<string | null>;
+
+/**
+ * Produce the inlined-context portion of a unit's system prompt by
+ * walking the manifest's `artifacts.inline` list in order and calling
+ * the provided resolver for each key.
+ *
+ * Returns an empty string when the unit type has no manifest registered,
+ * so callers can guard their wiring with a simple truthy check. Unknown
+ * unit types do not error — this mirrors `resolveManifest`'s contract.
+ *
+ * The separator between inlined blocks matches the in-tree convention
+ * (`\n\n---\n\n`) so composer output slots into existing prompt templates
+ * without visible diff.
+ */
+export async function composeInlinedContext(
+  unitType: string,
+  resolveArtifact: ArtifactResolver,
+): Promise<string> {
+  const manifest: UnitContextManifest | null = resolveManifest(unitType);
+  if (!manifest) return "";
+
+  const blocks: string[] = [];
+  for (const key of manifest.artifacts.inline) {
+    const body = await resolveArtifact(key);
+    if (body !== null && body.length > 0) {
+      blocks.push(body);
+    }
+  }
+  return blocks.join("\n\n---\n\n");
+}
+
+/**
+ * Convenience helper returning the manifest's declared budget so callers
+ * can telemetry a mismatch between actual prompt size and declared budget.
+ * Returns null for unknown unit types.
+ */
+export function manifestBudgetChars(unitType: string): number | null {
+  const manifest = resolveManifest(unitType);
+  return manifest ? manifest.maxSystemPromptChars : null;
+}
+
+// ─── v2 surface (#4924) ───────────────────────────────────────────────────
+
+/**
+ * Resolver for excerpt-class artifacts. Returns the compact block body
+ * (per-unit excerpt rendering — e.g. `buildSliceSummaryExcerpt` for the
+ * complete-milestone closer) or `null` to omit. Mirrors `ArtifactResolver`
+ * shape so consumers can reuse the same registry pattern.
+ */
+export type ExcerptResolver = (key: ArtifactKey) => Promise<string | null>;
+
+/**
+ * Inputs to the v2 composer entrypoint. The base context is required;
+ * each resolver/registry is optional and absent ones are treated as
+ * "manifest declares no entries of that class for this unit."
+ */
+export interface ComposeUnitContextOptions {
+  readonly base: BaseResolverContext;
+  readonly resolveArtifact?: ArtifactResolver;
+  readonly resolveExcerpt?: ExcerptResolver;
+  readonly computed?: ComputedArtifactRegistry;
+}
+
+/**
+ * Composer output. Kept structured (rather than a single joined string)
+ * because some builders need to splice the prepend block above their own
+ * preamble while keeping the main context block in its existing position.
+ *
+ * Both fields are joined with the in-tree `\n\n---\n\n` separator. Empty
+ * string means "no content for this section" — callers branch on truthy
+ * to decide whether to render any wrapper headers.
+ */
+export interface ComposedUnitContext {
+  readonly prepend: string;
+  readonly inline: string;
+}
+
+const SECTION_SEPARATOR = "\n\n---\n\n";
+
+/**
+ * Compose all manifest-declared context for a unit type using the v2
+ * surface. Walks `prepend` first (computed-only), then the `inline` list
+ * (static keys via `resolveArtifact`), then `excerpt` (via `resolveExcerpt`),
+ * then `artifacts.computed` (via the typed registry). Order within each
+ * section follows the manifest's declared sequence.
+ *
+ * Unknown unit types return empty strings for both sections — callers can
+ * fall back to existing imperative wiring without a special case.
+ *
+ * Resolver / registry omissions: if the manifest declares an entry but no
+ * resolver / registry entry is provided, the composer skips it silently.
+ * This matches the v1 contract where a null body is a no-op, and lets
+ * partial migrations land without forcing every consumer to register
+ * every artifact class up-front.
+ */
+export async function composeUnitContext(
+  unitType: string,
+  opts: ComposeUnitContextOptions,
+): Promise<ComposedUnitContext> {
+  const manifest: UnitContextManifest | null = resolveManifest(unitType);
+  if (!manifest) return { prepend: "", inline: "" };
+
+  // Single-source `unitType`: the manifest is resolved against the
+  // function arg, but computed builders read it from `base.unitType`.
+  // If those ever diverge (caller passes one type to composeUnitContext
+  // but a different one in opts.base), the composer would silently
+  // mix one unit's manifest with another unit's computed context.
+  // Normalize here so the composer dispatches a consistent identity
+  // through to every builder.
+  const normalizedOpts: ComposeUnitContextOptions = {
+    ...opts,
+    base: { ...opts.base, unitType },
+  };
+
+  const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
+  const inlineBlocks: string[] = [];
+
+  for (const key of manifest.artifacts.inline) {
+    if (!normalizedOpts.resolveArtifact) break;
+    const body = await normalizedOpts.resolveArtifact(key);
+    if (body && body.length > 0) inlineBlocks.push(body);
+  }
+  for (const key of manifest.artifacts.excerpt) {
+    if (!normalizedOpts.resolveExcerpt) break;
+    const body = await normalizedOpts.resolveExcerpt(key);
+    if (body && body.length > 0) inlineBlocks.push(body);
+  }
+  inlineBlocks.push(...await runComputed(manifest.artifacts.computed ?? [], normalizedOpts));
+
+  return {
+    prepend: prependBlocks.join(SECTION_SEPARATOR),
+    inline: inlineBlocks.join(SECTION_SEPARATOR),
+  };
+}
+
+/**
+ * Invoke the registered builder for each declared computed id, in order.
+ * Missing registry entries (manifest declares the id but caller didn't
+ * register it) are skipped silently — see composeUnitContext rationale.
+ */
+async function runComputed(
+  ids: readonly ComputedArtifactId[],
+  opts: ComposeUnitContextOptions,
+): Promise<string[]> {
+  if (ids.length === 0 || !opts.computed) return [];
+  // Type safety lives at the registration boundary (caller-supplied
+  // `computed` is typed against ComputedArtifactInputs[K] per id). Inside
+  // the composer we only dispatch — view the registry through a widened
+  // local shape so the loop compiles when the registry is empty (which
+  // it is in the v2-contract foundation PR before any computed ids are
+  // registered, making `keyof ComputedArtifactInputs` resolve to `never`).
+  type AnyEntry = {
+    build: (inputs: unknown, base: BaseResolverContext) => Promise<string | null>;
+    inputs: unknown;
+  };
+  const registry = opts.computed as Record<string, AnyEntry | undefined>;
+  const out: string[] = [];
+  for (const id of ids) {
+    const entry = registry[id];
+    if (!entry) continue;
+    const body = await entry.build(entry.inputs, opts.base);
+    if (body && body.length > 0) out.push(body);
+  }
+  return out;
+}