gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/dist/resources/extensions/gsd/exec-history.js

@@ -0,0 +1,120 @@
+// GSD Exec History — read-side helpers for the exec sandbox.
+//
+// Pure I/O: scans `.gsd/exec/*.meta.json` under a base directory and
+// returns lightweight records. Used by the gsd_exec_search tool and
+// any future compaction-snapshot enrichment.
+import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+function listMetaFiles(baseDir) {
+    const dir = resolve(baseDir, ".gsd", "exec");
+    try {
+        return readdirSync(dir)
+            .filter((name) => name.endsWith(".meta.json"))
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+function safeReadMeta(path) {
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.id !== "string" || typeof parsed.runtime !== "string")
+            return null;
+        return {
+            id: parsed.id,
+            runtime: parsed.runtime,
+            purpose: typeof parsed.purpose === "string" ? parsed.purpose : null,
+            started_at: typeof parsed.started_at === "string" ? parsed.started_at : "",
+            finished_at: typeof parsed.finished_at === "string" ? parsed.finished_at : "",
+            duration_ms: typeof parsed.duration_ms === "number" ? parsed.duration_ms : 0,
+            exit_code: typeof parsed.exit_code === "number" ? parsed.exit_code : null,
+            signal: typeof parsed.signal === "string" ? parsed.signal : null,
+            timed_out: parsed.timed_out === true,
+            stdout_bytes: typeof parsed.stdout_bytes === "number" ? parsed.stdout_bytes : 0,
+            stderr_bytes: typeof parsed.stderr_bytes === "number" ? parsed.stderr_bytes : 0,
+            stdout_truncated: parsed.stdout_truncated === true,
+            stderr_truncated: parsed.stderr_truncated === true,
+            stdout_path: path.replace(/\.meta\.json$/, ".stdout"),
+            stderr_path: path.replace(/\.meta\.json$/, ".stderr"),
+            meta_path: path,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function listExecHistory(baseDir) {
+    const metas = listMetaFiles(baseDir)
+        .map((path) => {
+        let mtime = 0;
+        try {
+            mtime = statSync(path).mtimeMs;
+        }
+        catch {
+            /* ignore */
+        }
+        const entry = safeReadMeta(path);
+        return entry ? { entry, mtime } : null;
+    })
+        .filter((value) => value !== null);
+    metas.sort((a, b) => b.mtime - a.mtime);
+    return metas.map((m) => m.entry);
+}
+function matchesFilters(entry, opts) {
+    if (opts.runtime && entry.runtime !== opts.runtime)
+        return false;
+    if (opts.failing_only) {
+        const failed = entry.timed_out || (entry.exit_code !== 0 && entry.exit_code !== null);
+        if (!failed)
+            return false;
+    }
+    const query = (opts.query ?? "").trim().toLowerCase();
+    if (!query)
+        return true;
+    const haystack = `${entry.id} ${entry.purpose ?? ""}`.toLowerCase();
+    return haystack.includes(query);
+}
+function readDigestPreview(entry, maxChars) {
+    if (!entry.stdout_path || maxChars <= 0)
+        return undefined;
+    try {
+        const size = statSync(entry.stdout_path).size;
+        if (size === 0)
+            return undefined;
+        const readBytes = Math.min(size, maxChars * 4); // 4 bytes/char upper bound for UTF-8
+        const buf = Buffer.allocUnsafe(readBytes);
+        const fd = openSync(entry.stdout_path, "r");
+        try {
+            const bytesRead = readSync(fd, buf, 0, readBytes, Math.max(0, size - readBytes));
+            const text = buf.subarray(0, bytesRead).toString("utf-8");
+            const trimmed = text.trimEnd();
+            return trimmed.length <= maxChars ? trimmed : trimmed.slice(trimmed.length - maxChars);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+export function searchExecHistory(baseDir, opts = {}) {
+    const limit = clampLimit(opts.limit, 20, 200);
+    const entries = listExecHistory(baseDir);
+    const filtered = entries.filter((entry) => matchesFilters(entry, opts));
+    return filtered.slice(0, limit).map((entry) => ({
+        entry,
+        digest_preview: readDigestPreview(entry, 300),
+    }));
+}
+function clampLimit(value, fallback, max) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    if (value < 1)
+        return 1;
+    if (value > max)
+        return max;
+    return Math.floor(value);
+}

package/dist/resources/extensions/gsd/exec-sandbox.js

@@ -0,0 +1,258 @@
+// GSD Exec Sandbox — tool-output sandboxing for sub-sessions.
+//
+// Runs a script in a subprocess and persists stdout/stderr to
+// `.gsd/exec/<id>.{stdout,stderr,meta.json}`. Only a short digest is
+// returned to the calling agent's context, keeping large outputs
+// (e.g. Playwright snapshots, issue dumps) out of the window.
+//
+// Inspired by mksglu/context-mode (Elastic License 2.0). Independent
+// implementation — no upstream code incorporated.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+const ALWAYS_FORWARD_ENV = ["PATH", "HOME"];
+export const EXEC_DEFAULTS = {
+    clampTimeoutMs: 600_000,
+    defaultTimeoutMs: 30_000,
+    stdoutCapBytes: 1_048_576,
+    stderrCapBytes: 262_144,
+    digestChars: 300,
+    envAllowlist: [
+        "LANG",
+        "LC_ALL",
+        "TERM",
+        "TZ",
+        "SHELL",
+        "USER",
+        "LOGNAME",
+        "TMPDIR",
+        "NODE_OPTIONS",
+        "PYTHONPATH",
+        "PYTHONIOENCODING",
+    ],
+};
+function buildChildEnv(opts) {
+    const source = opts.env ?? process.env;
+    const out = {};
+    const allowed = new Set([...ALWAYS_FORWARD_ENV, ...opts.env_allowlist]);
+    for (const key of allowed) {
+        const value = source[key];
+        if (typeof value === "string")
+            out[key] = value;
+    }
+    return out;
+}
+function clampTimeout(request, opts) {
+    const requested = typeof request.timeout_ms === "number" && Number.isFinite(request.timeout_ms)
+        ? Math.floor(request.timeout_ms)
+        : opts.default_timeout_ms;
+    if (requested < 1)
+        return 1;
+    if (requested > opts.clamp_timeout_ms)
+        return opts.clamp_timeout_ms;
+    return requested;
+}
+function resolveCommand(runtime) {
+    switch (runtime) {
+        case "bash":
+            return { cmd: "bash", args: ["-c"] };
+        case "node":
+            return { cmd: process.execPath, args: ["-e"] };
+        case "python":
+            return { cmd: "python3", args: ["-c"] };
+    }
+}
+function tail(buf, chars) {
+    if (chars <= 0)
+        return "";
+    const text = buf.toString("utf-8");
+    return text.length <= chars ? text : text.slice(text.length - chars);
+}
+/**
+ * Run a script in a subprocess, capture stdout/stderr to files under
+ * `.gsd/exec/<id>.{stdout,stderr,meta.json}`, and return an `ExecSandboxResult`
+ * containing the digest plus metadata.
+ *
+ * Errors from spawn failures resolve (not reject) with `exit_code=null`.
+ * The function is pure with respect to its inputs — no global state beyond
+ * filesystem writes under `baseDir`.
+ */
+export function runExecSandbox(request, opts) {
+    return new Promise((resolveP) => {
+        const id = (opts.generateId ?? defaultGenerateId)();
+        const now = (opts.now ?? (() => new Date()))();
+        const execDir = resolve(opts.baseDir, ".gsd", "exec");
+        if (!existsSync(execDir))
+            mkdirSync(execDir, { recursive: true });
+        const stdoutPath = resolve(execDir, `${id}.stdout`);
+        const stderrPath = resolve(execDir, `${id}.stderr`);
+        const metaPath = resolve(execDir, `${id}.meta.json`);
+        const timeoutMs = clampTimeout(request, opts);
+        const { cmd, args } = resolveCommand(request.runtime);
+        const env = buildChildEnv(opts);
+        const useProcessGroup = process.platform !== "win32";
+        const started = Date.now();
+        let child;
+        try {
+            child = spawn(cmd, [...args, request.script], {
+                cwd: opts.baseDir,
+                env,
+                stdio: ["ignore", "pipe", "pipe"],
+                ...(useProcessGroup ? { detached: true } : {}),
+            });
+        }
+        catch (err) {
+            const duration = Date.now() - started;
+            const message = err instanceof Error ? err.message : String(err);
+            writeFileSync(stdoutPath, "");
+            writeFileSync(stderrPath, `spawn error: ${message}\n`);
+            const result = {
+                id,
+                runtime: request.runtime,
+                exit_code: null,
+                signal: null,
+                timed_out: false,
+                duration_ms: duration,
+                stdout_bytes: 0,
+                stderr_bytes: Buffer.byteLength(`spawn error: ${message}\n`),
+                stdout_truncated: false,
+                stderr_truncated: false,
+                stdout_path: stdoutPath,
+                stderr_path: stderrPath,
+                meta_path: metaPath,
+                digest: `[spawn error: ${message}]`,
+            };
+            writeMeta(metaPath, result, request, now);
+            resolveP(result);
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        child.stdout?.on("data", (chunk) => {
+            const remaining = opts.stdout_cap_bytes - stdoutBytes;
+            if (remaining <= 0) {
+                stdoutTruncated = true;
+                return;
+            }
+            if (chunk.length <= remaining) {
+                stdoutChunks.push(chunk);
+                stdoutBytes += chunk.length;
+            }
+            else {
+                stdoutChunks.push(chunk.subarray(0, remaining));
+                stdoutBytes += remaining;
+                stdoutTruncated = true;
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            const remaining = opts.stderr_cap_bytes - stderrBytes;
+            if (remaining <= 0) {
+                stderrTruncated = true;
+                return;
+            }
+            if (chunk.length <= remaining) {
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+            }
+            else {
+                stderrChunks.push(chunk.subarray(0, remaining));
+                stderrBytes += remaining;
+                stderrTruncated = true;
+            }
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (useProcessGroup && child.pid != null) {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch {
+                    child.kill("SIGKILL");
+                }
+            }
+            else {
+                child.kill("SIGKILL");
+            }
+        }, timeoutMs);
+        timer.unref?.();
+        const finalize = (exitCode, signal) => {
+            clearTimeout(timer);
+            const duration = Date.now() - started;
+            const stdoutBuf = Buffer.concat(stdoutChunks);
+            const stderrBuf = Buffer.concat(stderrChunks);
+            const stdoutSuffix = stdoutTruncated ? "\n[truncated: stdout cap reached]\n" : "";
+            const stderrSuffix = stderrTruncated ? "\n[truncated: stderr cap reached]\n" : "";
+            writeFileSync(stdoutPath, Buffer.concat([stdoutBuf, Buffer.from(stdoutSuffix, "utf-8")]));
+            writeFileSync(stderrPath, Buffer.concat([stderrBuf, Buffer.from(stderrSuffix, "utf-8")]));
+            const digestBody = tail(stdoutBuf, opts.digest_chars);
+            const digest = digestBody.length > 0
+                ? digestBody
+                : timedOut
+                    ? "[no stdout — timed out]"
+                    : stderrBuf.length > 0
+                        ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
+                        : "[no output]";
+            const result = {
+                id,
+                runtime: request.runtime,
+                exit_code: exitCode,
+                signal,
+                timed_out: timedOut,
+                duration_ms: duration,
+                stdout_bytes: stdoutBytes,
+                stderr_bytes: stderrBytes,
+                stdout_truncated: stdoutTruncated,
+                stderr_truncated: stderrTruncated,
+                stdout_path: stdoutPath,
+                stderr_path: stderrPath,
+                meta_path: metaPath,
+                digest,
+            };
+            writeMeta(metaPath, result, request, now);
+            resolveP(result);
+        };
+        child.on("error", (err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            const line = `child error: ${message}\n`;
+            const remaining = opts.stderr_cap_bytes - stderrBytes;
+            if (remaining > 0) {
+                const chunk = Buffer.from(line, "utf-8").subarray(0, remaining);
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+                if (chunk.length < Buffer.byteLength(line, "utf-8"))
+                    stderrTruncated = true;
+            }
+        });
+        child.on("close", (code, signal) => finalize(code, signal));
+    });
+}
+function defaultGenerateId() {
+    return randomUUID();
+}
+function writeMeta(path, result, request, now) {
+    const meta = {
+        id: result.id,
+        runtime: result.runtime,
+        purpose: request.purpose ?? null,
+        script_chars: request.script.length,
+        started_at: now.toISOString(),
+        finished_at: new Date(now.getTime() + result.duration_ms).toISOString(),
+        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,
+    };
+    writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`);
+}

package/dist/resources/extensions/gsd/file-lock.js

@@ -1,11 +1,19 @@
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+// The file-lock module is loaded in both CJS builds and ESM sources. Under ESM
+// the bare `require` identifier is not defined, so we always go through
+// createRequire. We try the current module's resolution context first and fall
+// back to the installed gsd-pi package if we are running from a consumer
+// project that does not hoist proper-lockfile.
+const localRequire = createRequire(import.meta.url);
 function _require(name) {
     try {
-        return require(name);
+        return localRequire(name);
     }
     catch {
         try {
-            const gsdPiRequire = require("module").createRequire(require("path").join(process.cwd(), "node_modules", "gsd-pi", "index.js"));
+            const gsdPiRequire = createRequire(join(process.cwd(), "node_modules", "gsd-pi", "index.js"));
             return gsdPiRequire(name);
         }
         catch {
@@ -13,14 +21,44 @@ function _require(name) {
         }
     }
 }
-export function withFileLockSync(filePath, fn) {
+const DEFAULT_RETRIES = 5;
+const DEFAULT_STALE_MS = 10000;
+const SYNC_RETRY_DELAY_MS = 50;
+// Block the thread for `ms` milliseconds without spinning the CPU.
+// Used by the sync lock retry loop, since proper-lockfile's lockSync does not
+// accept a `retries` option (only the async `lock` does).
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function acquireLockSyncWithRetry(lockfile, filePath, retries, stale) {
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return lockfile.lockSync(filePath, { stale });
+        }
+        catch (err) {
+            lastErr = err;
+            if (err?.code !== "ELOCKED")
+                throw err;
+            if (attempt < retries)
+                sleepSync(SYNC_RETRY_DELAY_MS);
+        }
+    }
+    throw lastErr;
+}
+export function withFileLockSync(filePath, fn, opts = {}) {
     const lockfile = _require("proper-lockfile");
     if (!lockfile)
         return fn();
     if (!existsSync(filePath))
         return fn();
+    const retries = opts.retries ?? DEFAULT_RETRIES;
+    const stale = opts.stale ?? DEFAULT_STALE_MS;
+    const onLocked = opts.onLocked ?? "fail";
     try {
-        const release = lockfile.lockSync(filePath, { retries: 5, stale: 10000 });
+        const release = acquireLockSyncWithRetry(lockfile, filePath, retries, stale);
         try {
             return fn();
         }
@@ -29,21 +67,23 @@ export function withFileLockSync(filePath, fn) {
         }
     }
     catch (err) {
-        if (err.code === "ELOCKED") {
-            // Could not get lock after retries, let's fallback to un-locked instead of crashing the whole state machine
+        if (err?.code === "ELOCKED" && onLocked === "skip") {
             return fn();
         }
         throw err;
     }
 }
-export async function withFileLock(filePath, fn) {
+export async function withFileLock(filePath, fn, opts = {}) {
     const lockfile = _require("proper-lockfile");
     if (!lockfile)
         return await fn();
     if (!existsSync(filePath))
         return await fn();
+    const retries = opts.retries ?? DEFAULT_RETRIES;
+    const stale = opts.stale ?? DEFAULT_STALE_MS;
+    const onLocked = opts.onLocked ?? "fail";
     try {
-        const release = await lockfile.lock(filePath, { retries: 5, stale: 10000 });
+        const release = await lockfile.lock(filePath, { retries, stale });
         try {
             return await fn();
         }
@@ -52,7 +92,7 @@ export async function withFileLock(filePath, fn) {
         }
     }
     catch (err) {
-        if (err.code === "ELOCKED") {
+        if (err?.code === "ELOCKED" && onLocked === "skip") {
             return await fn();
         }
         throw err;

package/dist/resources/extensions/gsd/git-service.js

@@ -84,6 +84,7 @@ export class MergeConflictError extends GSDError {
  */
 export const RUNTIME_EXCLUSION_PATHS = [
     ".gsd/activity/",
+    ".gsd/audit/",
     ".gsd/forensics/",
     ".gsd/runtime/",
     ".gsd/worktrees/",

package/dist/resources/extensions/gsd/gitignore.js

@@ -24,6 +24,7 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  */
 const GSD_RUNTIME_PATTERNS = [
     ".gsd/activity/",
+    ".gsd/audit/",
     ".gsd/forensics/",
     ".gsd/runtime/",
     ".gsd/worktrees/",
@@ -45,6 +46,7 @@ const BASELINE_PATTERNS = [
     // ── GSD state directory (symlink to external storage) ──
     ".gsd",
     ".gsd-id",
+    ".mcp.json",
     ".bg-shell/",
     // ── OS junk ──
     ".DS_Store",