gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

package/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -0,0 +1,126 @@
+// 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, } from "../exec-sandbox.js";
+import { isContextModeEnabled } from "../preferences-types.js";
+export function buildExecOptions(baseDir, cfg, extras) {
+    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, fallback, min, max) {
+    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) {
+    return isContextModeEnabled(prefs);
+}
+function disabledResult() {
+    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) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        details: { operation: "gsd_exec", error: "invalid_params", detail: message },
+        isError: true,
+    };
+}
+export async function executeGsdExec(params, deps) {
+    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) {
+    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) {
+    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/dist/resources/extensions/gsd/tools/memory-tools.js

@@ -58,7 +58,8 @@ export function executeMemoryCapture(params) {
     const confidence = clampConfidence(params.confidence);
     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." }],
@@ -82,6 +83,19 @@ function normalizeTags(value) {
         return [];
     return value.filter((t) => typeof t === "string" && t.trim().length > 0).slice(0, 10);
 }
+function normalizeStructuredFields(value) {
+    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;
+}
 function clampConfidence(value) {
     if (typeof value !== "number" || !Number.isFinite(value))
         return 0.8;
@@ -200,6 +214,16 @@ function includeSupersededMemories(rankedActive) {
                     /* leave empty */
                 }
             }
+            let structuredFields = null;
+            if (typeof row["structured_fields"] === "string" && row["structured_fields"].length > 0) {
+                try {
+                    const parsed = JSON.parse(row["structured_fields"]);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        structuredFields = parsed;
+                    }
+                }
+                catch { /* leave null */ }
+            }
             return {
                 seq: row["seq"],
                 id: row["id"],
@@ -214,6 +238,7 @@ function includeSupersededMemories(rankedActive) {
                 hit_count: row["hit_count"],
                 scope: row["scope"] ?? "project",
                 tags,
+                structured_fields: structuredFields,
             };
         });
     }

package/dist/resources/extensions/gsd/tools/resume-tool.js

@@ -0,0 +1,23 @@
+// 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 function executeResume(_params, opts) {
+    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/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -11,6 +11,7 @@
 import { join } from "node:path";
 import { transaction, insertAssessment, deleteAssessmentByScope, 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";
@@ -59,14 +60,18 @@ export async function handleValidateMilestone(params, basePath, opts) {
         return { error: `verdict must be one of: ${VALIDATION_VERDICTS.join(", ")}` };
     }
     // ── 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;
-    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/dist/resources/extensions/gsd/unit-context-composer.js

@@ -0,0 +1,147 @@
+// 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, } from "./unit-context-manifest.js";
+/**
+ * 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, resolveArtifact) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return "";
+    const blocks = [];
+    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) {
+    const manifest = resolveManifest(unitType);
+    return manifest ? manifest.maxSystemPromptChars : null;
+}
+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, opts) {
+    const manifest = 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 = {
+        ...opts,
+        base: { ...opts.base, unitType },
+    };
+    const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
+    const inlineBlocks = [];
+    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, opts) {
+    if (ids.length === 0 || !opts.computed)
+        return [];
+    const registry = opts.computed;
+    const out = [];
+    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;
+}