gsd-pi 2.76.0-dev.82e249f7b → 2.76.0-dev.fe143342a

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

@@ -0,0 +1,109 @@
+// GSD2 — Exec (context-mode) tool registration.
+//
+// Exposes the `gsd_exec` tool over MCP. Opt-in: disabled unless
+// `context_mode.enabled: true` is set in preferences.
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+import { executeGsdExec } from "../tools/exec-tool.js";
+import { executeExecSearch } from "../tools/exec-search-tool.js";
+import { executeResume } from "../tools/resume-tool.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { logWarning } from "../workflow-logger.js";
+
+export function registerExecTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "gsd_exec",
+    label: "Exec (Sandboxed)",
+    description:
+      "Run a short script (bash/node/python) in a subprocess. Full stdout/stderr persist to " +
+      ".gsd/exec/<id>.{stdout,stderr,meta.json}; only a short digest returns in context. Use " +
+      "this instead of reading many files or emitting large tool outputs — e.g. have the script " +
+      "count/grep/summarize and log the finding. Enabled by default; opt out via " +
+      "preferences.context_mode.enabled=false.",
+    promptSnippet:
+      "Run a bash/node/python script in a sandbox; full output is saved to disk and only a digest returns",
+    promptGuidelines: [
+      "Prefer gsd_exec for analyses that would otherwise read >3 files or produce large tool output.",
+      "Write scripts that log the finding (counts, matches, summaries) rather than raw dumps.",
+      "The digest is the last ~300 chars of stdout — size your log output accordingly.",
+      "Need the full output? Read the stdout_path returned in details (file on local disk).",
+    ],
+    parameters: Type.Object({
+      runtime: Type.Union(
+        [Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")],
+        { description: "Interpreter: bash (-c), node (-e), or python3 (-c)." },
+      ),
+      script: Type.String({ description: "Script body. Keep output small (log the finding, not the data)." }),
+      purpose: Type.Optional(Type.String({ description: "Short label recorded in meta.json for later review." })),
+      timeout_ms: Type.Optional(
+        Type.Number({
+          description: "Per-invocation timeout (ms). Capped at 600000. Default from preferences.",
+          minimum: 1_000,
+          maximum: 600_000,
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      let prefs: Awaited<ReturnType<typeof loadEffectiveGSDPreferences>> | null = null;
+      try {
+        prefs = loadEffectiveGSDPreferences();
+      } catch (err) {
+        logWarning("tool", `gsd_exec could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      return executeGsdExec(params as Parameters<typeof executeGsdExec>[0], {
+        baseDir: process.cwd(),
+        preferences: prefs?.preferences ?? null,
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_exec_search",
+    label: "Search gsd_exec History",
+    description:
+      "List prior gsd_exec runs (most recent first) from .gsd/exec/*.meta.json. Useful for " +
+      "rediscovering the stdout_path of an earlier run without re-executing it. Read-only.",
+    promptSnippet: "Search prior gsd_exec runs by substring, runtime, or failing-only filter",
+    promptGuidelines: [
+      "Use this before re-running an expensive analysis — the prior run's stdout file may still answer.",
+      "The preview shows the trailing ~300 chars of stdout; read stdout_path for the full transcript.",
+    ],
+    parameters: Type.Object({
+      query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
+      runtime: Type.Optional(
+        Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], {
+          description: "Restrict to one runtime.",
+        }),
+      ),
+      failing_only: Type.Optional(Type.Boolean({ description: "Only non-zero exit codes and timeouts." })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 20, cap 200)", minimum: 1, maximum: 200 })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeExecSearch(params as Parameters<typeof executeExecSearch>[0], {
+        baseDir: process.cwd(),
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_resume",
+    label: "Resume (Read Snapshot)",
+    description:
+      "Return the contents of .gsd/last-snapshot.md — a ≤2 KB digest of top memories, recent " +
+      "gsd_exec runs, and active context, written automatically on session_before_compact. Use " +
+      "this after compaction or session resume to re-orient quickly.",
+    promptSnippet: "Read the pre-compaction snapshot to re-orient after context loss",
+    promptGuidelines: [
+      "Call this right after a session resumes if you feel you've lost durable context.",
+      "The snapshot is a summary — use memory_query or gsd_exec_search for detail.",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeResume(params as Parameters<typeof executeResume>[0], {
+        baseDir: process.cwd(),
+      });
+    },
+  });
+}

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -8,6 +8,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
+import { registerExecTools } from "./exec-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
 import { registerMemoryTools } from "./memory-tools.js";
 import { registerQueryTools } from "./query-tools.js";
@@ -100,6 +101,7 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     ["journal-tools", () => registerJournalTools(pi)],
     ["query-tools", () => registerQueryTools(pi)],
     ["memory-tools", () => registerMemoryTools(pi)],
+    ["exec-tools", () => registerExecTools(pi)],
     ["shortcuts", () => registerShortcuts(pi)],
     ["hooks", () => registerHooks(pi, ecosystemHandlers)],
     ["ecosystem", () => {

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -225,6 +225,42 @@ export function registerHooks(
     }));
   });
 
+  // Context-mode snapshot: write .gsd/last-snapshot.md before compaction so
+  // agents can call gsd_resume (or Read the file) to re-orient. Opt-in via
+  // preferences.context_mode.enabled. Runs after the auto-cancel handler
+  // above — if that one returned cancel:true, pi still fires us but the
+  // compaction won't actually happen; the snapshot is still useful then,
+  // since auto may pause and resume later.
+  pi.on("session_before_compact", async () => {
+    try {
+      const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+      const { isContextModeEnabled } = await import("../preferences-types.js");
+      const prefs = loadEffectiveGSDPreferences();
+      if (!isContextModeEnabled(prefs?.preferences)) return;
+      const { writeCompactionSnapshot } = await import("../compaction-snapshot.js");
+      const { ensureDbOpen } = await import("./dynamic-tools.js");
+      await ensureDbOpen();
+      const basePath = process.cwd();
+      let activeContext: string | null = null;
+      try {
+        const state = await deriveState(basePath);
+        if (state.activeMilestone && state.activeSlice && state.activeTask) {
+          activeContext =
+            `Active: ${state.activeMilestone.id} / ${state.activeSlice.id} / ${state.activeTask.id}` +
+            (state.activeTask.title ? ` — ${state.activeTask.title}` : "");
+        }
+      } catch {
+        /* non-fatal */
+      }
+      writeCompactionSnapshot(basePath, { activeContext });
+    } catch (err) {
+      safetyLogWarning(
+        "context-mode",
+        `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  });
+
   pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
     if (isParallelActive()) {
       try {

package/src/resources/extensions/gsd/compaction-snapshot.ts

@@ -0,0 +1,165 @@
+// GSD Compaction Snapshot — writes a ≤2 KB markdown digest of durable
+// project state before the session context is compacted. On resume, an
+// agent can `gsd_resume` (or Read .gsd/last-snapshot.md) to re-orient
+// without re-deriving the same memories.
+//
+// Inspired by mksglu/context-mode. Independent implementation.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { getActiveMemoriesRanked, type Memory } from "./memory-store.js";
+import { listExecHistory, type ExecHistoryEntry } from "./exec-history.js";
+
+export const DEFAULT_SNAPSHOT_BYTES = 2048;
+export const SNAPSHOT_FILENAME = "last-snapshot.md";
+
+export interface SnapshotSources {
+  memories: Memory[];
+  execHistory: ExecHistoryEntry[];
+  generatedAt: Date;
+  /** Optional free-form context string (e.g. active unit id). */
+  activeContext?: string | null;
+}
+
+export interface BuildSnapshotOptions {
+  /** Hard cap in bytes (UTF-8). Default 2048. */
+  maxBytes?: number;
+  /** Memory count cap before truncation (default 6). */
+  maxMemories?: number;
+  /** Exec history cap (default 5). */
+  maxExec?: number;
+}
+
+/**
+ * Build a priority-tiered markdown snapshot. Pure — no I/O. Tiers:
+ *   1. Active context (if any)
+ *   2. Top memories by rank
+ *   3. Recent exec runs (failures highlighted)
+ * The result is guaranteed to be <= opts.maxBytes (truncated with an
+ * ellipsis marker if necessary).
+ */
+export function buildSnapshot(sources: SnapshotSources, opts: BuildSnapshotOptions = {}): string {
+  const maxBytes = opts.maxBytes ?? DEFAULT_SNAPSHOT_BYTES;
+  const maxMemories = opts.maxMemories ?? 6;
+  const maxExec = opts.maxExec ?? 5;
+
+  const lines: string[] = [];
+  lines.push(`# GSD context snapshot (${sources.generatedAt.toISOString()})`);
+  lines.push("");
+
+  if (sources.activeContext && sources.activeContext.trim().length > 0) {
+    lines.push("## Active context");
+    lines.push(sources.activeContext.trim());
+    lines.push("");
+  }
+
+  const memories = sources.memories.slice(0, maxMemories);
+  if (memories.length > 0) {
+    lines.push("## Top project memories");
+    for (const memory of memories) {
+      lines.push(`- [${memory.id}] (${memory.category}) ${memory.content.trim()}`);
+    }
+    lines.push("");
+  }
+
+  const exec = sources.execHistory.slice(0, maxExec);
+  if (exec.length > 0) {
+    lines.push("## Recent gsd_exec runs");
+    for (const entry of exec) {
+      const status = entry.timed_out
+        ? "timeout"
+        : entry.exit_code === null
+          ? "exit:null"
+          : `exit:${entry.exit_code}`;
+      const purpose = entry.purpose ? ` — ${entry.purpose}` : "";
+      lines.push(`- [${entry.id}] ${entry.runtime} ${status}${purpose}`);
+    }
+    lines.push("");
+  }
+
+  if (memories.length === 0 && exec.length === 0 && !sources.activeContext) {
+    lines.push("_No durable memories, active context, or exec history to surface._");
+  }
+
+  return enforceByteCap(lines.join("\n").trimEnd(), maxBytes);
+}
+
+function enforceByteCap(input: string, maxBytes: number): string {
+  if (Buffer.byteLength(input, "utf-8") <= maxBytes) return input;
+  const marker = "\n…[truncated]";
+  const markerBytes = Buffer.byteLength(marker, "utf-8");
+  const budget = Math.max(0, maxBytes - markerBytes);
+  // Walk backwards until the trimmed string fits. utf-8 is variable-width;
+  // naive char slicing is safe for ASCII but may split a multi-byte char.
+  // Guard by decoding the trimmed Buffer and relying on the replacement-char
+  // fallback in TextDecoder (implicit via toString).
+  const buf = Buffer.from(input, "utf-8").subarray(0, budget);
+  return `${buf.toString("utf-8")}${marker}`;
+}
+
+export interface WriteSnapshotOptions extends BuildSnapshotOptions {
+  activeContext?: string | null;
+  now?: () => Date;
+}
+
+export interface WriteSnapshotResult {
+  path: string;
+  bytes: number;
+  memories: number;
+  execRuns: number;
+}
+
+export function writeCompactionSnapshot(
+  baseDir: string,
+  opts: WriteSnapshotOptions = {},
+): WriteSnapshotResult {
+  const memories = safeGetMemories();
+  const execHistory = safeListExec(baseDir);
+  const content = buildSnapshot(
+    {
+      memories,
+      execHistory,
+      generatedAt: (opts.now ?? (() => new Date()))(),
+      activeContext: opts.activeContext ?? null,
+    },
+    opts,
+  );
+  const gsdDir = resolve(baseDir, ".gsd");
+  if (!existsSync(gsdDir)) mkdirSync(gsdDir, { recursive: true });
+  const path = resolve(gsdDir, SNAPSHOT_FILENAME);
+  const finalContent = `${content}\n`;
+  writeFileSync(path, finalContent, "utf-8");
+  return {
+    path,
+    bytes: Buffer.byteLength(finalContent, "utf-8"),
+    memories: memories.length,
+    execRuns: execHistory.length,
+  };
+}
+
+export function readCompactionSnapshot(baseDir: string): string | null {
+  const path = resolve(baseDir, ".gsd", SNAPSHOT_FILENAME);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function safeGetMemories(): Memory[] {
+  try {
+    return getActiveMemoriesRanked(12);
+  } catch {
+    return [];
+  }
+}
+
+function safeListExec(baseDir: string): ExecHistoryEntry[] {
+  try {
+    return listExecHistory(baseDir);
+  } catch {
+    return [];
+  }
+}

package/src/resources/extensions/gsd/error-classifier.ts

@@ -47,12 +47,19 @@ const PERMANENT_RE = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|bill
 // Include provider-specific quota-window phrasing like:
 // - "You've hit your limit"
 // - "usage limit" / "quota reached"
-const RATE_LIMIT_RE = /rate.?limit|too many requests|429|hit your limit|usage limit|quota (?:reached|hit)|limit.*resets?/i;
+// - "out of extra usage"
+const RATE_LIMIT_RE = /rate.?limit|too many requests|429|hit your limit|usage limit|out of extra usage|quota (?:reached|hit)|limit.*resets?/i;
 // OpenRouter affordability-style quota errors should be treated as transient
 // so core retry logic can lower maxTokens and continue in-session.
 const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient credits|not enough credits|fewer max_tokens/i;
-const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns|unexpected eof/i;
-const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
+// "Stream idle timeout" and "partial response received" are emitted by the SDK/harness
+// for mid-stream disconnects. Both indicate a transient network-level interruption.
+// See: https://github.com/gsd-build/gsd-2/issues/4558
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received/i;
+// Context overflow errors (context window/length exceeded) should be treated as server-class
+// transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
+// See: https://github.com/gsd-build/gsd-2/issues/4528
+const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
 const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".

package/src/resources/extensions/gsd/exec-history.ts

@@ -0,0 +1,153 @@
+// 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";
+
+export interface ExecHistoryEntry {
+  id: string;
+  runtime: "bash" | "node" | "python" | string;
+  purpose: string | null;
+  started_at: string;
+  finished_at: string;
+  duration_ms: number;
+  exit_code: number | null;
+  signal: string | null;
+  timed_out: boolean;
+  stdout_bytes: number;
+  stderr_bytes: number;
+  stdout_truncated: boolean;
+  stderr_truncated: boolean;
+  stdout_path: string;
+  stderr_path: string;
+  meta_path: string;
+}
+
+export interface ExecSearchOptions {
+  /** Case-insensitive needle matched against purpose. Empty string matches all. */
+  query?: string;
+  /** Restrict to this runtime. */
+  runtime?: ExecHistoryEntry["runtime"];
+  /** Include only entries with exit_code !== 0 || timed_out. */
+  failing_only?: boolean;
+  /** Return at most N entries, most recent first. Default 20, cap 200. */
+  limit?: number;
+}
+
+export interface ExecSearchHit {
+  entry: ExecHistoryEntry;
+  /** Tail of stdout (first 300 chars) — cheap to read, useful for disambiguation. */
+  digest_preview?: string;
+}
+
+function listMetaFiles(baseDir: string): string[] {
+  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: string): ExecHistoryEntry | null {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<ExecHistoryEntry>;
+    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: string): ExecHistoryEntry[] {
+  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 is { entry: ExecHistoryEntry; mtime: number } => value !== null);
+  metas.sort((a, b) => b.mtime - a.mtime);
+  return metas.map((m) => m.entry);
+}
+
+function matchesFilters(entry: ExecHistoryEntry, opts: ExecSearchOptions): boolean {
+  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: ExecHistoryEntry, maxChars: number): string | undefined {
+  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: string,
+  opts: ExecSearchOptions = {},
+): ExecSearchHit[] {
+  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: unknown, fallback: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  if (value < 1) return 1;
+  if (value > max) return max;
+  return Math.floor(value);
+}