gsd-pi 2.35.0 → 2.36.0-dev.d612764

package/README.md

@@ -455,7 +455,9 @@ auto_report: true
 
 ### Agent Instructions
 
-Create an `agent-instructions.md` file in your project root to inject persistent per-project behavioral guidance into every agent session. This file is loaded automatically and provides project-specific context the LLM should always have — coding standards, architectural decisions, domain terminology, or workflow preferences.
+Place an `AGENTS.md` file in any directory to provide persistent behavioral guidance for that scope. Pi core loads `AGENTS.md` automatically (with `CLAUDE.md` as a fallback) at both user and project levels. Use these files for coding standards, architectural decisions, domain terminology, or workflow preferences.
+
+> **Note:** The legacy `agent-instructions.md` format (`~/.gsd/agent-instructions.md` and `.gsd/agent-instructions.md`) is deprecated and no longer loaded. Migrate any existing instructions to `AGENTS.md` or `CLAUDE.md`.
 
 ### Debug Mode
 

package/dist/cli.js

@@ -327,7 +327,10 @@ if (isPrintMode) {
     markStartup('createAgentSession');
     if (extensionsResult.errors.length > 0) {
         for (const err of extensionsResult.errors) {
-            process.stderr.write(`[gsd] Extension load error: ${err.error}\n`);
+            // Downgrade conflicts with built-in tools to warnings (#1347)
+            const isSuperseded = err.error.includes("supersedes");
+            const prefix = isSuperseded ? "Extension conflict" : "Extension load error";
+            process.stderr.write(`[gsd] ${prefix}: ${err.error}\n`);
         }
     }
     // Apply --model override if specified
@@ -456,7 +459,9 @@ const { session, extensionsResult } = await createAgentSession({
 markStartup('createAgentSession');
 if (extensionsResult.errors.length > 0) {
     for (const err of extensionsResult.errors) {
-        process.stderr.write(`[gsd] Extension load error: ${err.error}\n`);
+        const isSuperseded = err.error.includes("supersedes");
+        const prefix = isSuperseded ? "Extension conflict" : "Extension load error";
+        process.stderr.write(`[gsd] ${prefix}: ${err.error}\n`);
     }
 }
 // Restore scoped models from settings on startup.

package/dist/resource-loader.d.ts

@@ -9,7 +9,7 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  * - extensions/ → ~/.gsd/agent/extensions/   (overwrite when version changes)
  * - agents/     → ~/.gsd/agent/agents/        (overwrite when version changes)
  * - skills/     → ~/.gsd/agent/skills/        (overwrite when version changes)
- * - GSD-WORKFLOW.md is read directly from bundled path via GSD_WORKFLOW_PATH env var
+ * - GSD-WORKFLOW.md → ~/.gsd/agent/GSD-WORKFLOW.md (fallback for env var miss)
  *
  * Skips the copy when the managed-resources.json version matches the current
  * GSD version, avoiding ~128ms of synchronous cpSync on every startup.

package/dist/resource-loader.js

@@ -18,6 +18,9 @@ import { loadRegistry, readManifestFromEntryPath, isExtensionEnabled, ensureRegi
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const distResources = join(packageRoot, 'dist', 'resources');
 const srcResources = join(packageRoot, 'src', 'resources');
+// Use dist/resources only if it has the full expected structure.
+// A partial build (tsc without copy-resources) creates dist/resources/extensions/
+// but not agents/ or skills/, causing initResources to sync from an incomplete source.
 const resourcesDir = (existsSync(distResources) && existsSync(join(distResources, 'agents')))
     ? distResources
     : srcResources;
@@ -220,7 +223,7 @@ function copyDirRecursive(src, dest) {
  * - extensions/ → ~/.gsd/agent/extensions/   (overwrite when version changes)
  * - agents/     → ~/.gsd/agent/agents/        (overwrite when version changes)
  * - skills/     → ~/.gsd/agent/skills/        (overwrite when version changes)
- * - GSD-WORKFLOW.md is read directly from bundled path via GSD_WORKFLOW_PATH env var
+ * - GSD-WORKFLOW.md → ~/.gsd/agent/GSD-WORKFLOW.md (fallback for env var miss)
  *
  * Skips the copy when the managed-resources.json version matches the current
  * GSD version, avoiding ~128ms of synchronous cpSync on every startup.
@@ -247,6 +250,15 @@ export function initResources(agentDir) {
     syncResourceDir(bundledExtensionsDir, join(agentDir, 'extensions'));
     syncResourceDir(join(resourcesDir, 'agents'), join(agentDir, 'agents'));
     syncResourceDir(join(resourcesDir, 'skills'), join(agentDir, 'skills'));
+    // Sync GSD-WORKFLOW.md to agentDir as a fallback for when GSD_WORKFLOW_PATH
+    // env var is not set (e.g. fork/dev builds, alternative entry points).
+    const workflowSrc = join(resourcesDir, 'GSD-WORKFLOW.md');
+    if (existsSync(workflowSrc)) {
+        try {
+            copyFileSync(workflowSrc, join(agentDir, 'GSD-WORKFLOW.md'));
+        }
+        catch { /* non-fatal */ }
+    }
     // Ensure all newly copied files are owner-writable so the next run can
     // overwrite them (covers extensions, agents, and skills in one walk).
     makeTreeWritable(agentDir);

package/dist/resources/extensions/async-jobs/await-tool.js

@@ -52,14 +52,12 @@ export function createAwaitTool(getManager) {
             const running = watched.filter((j) => j.status === "running");
             if (running.length === 0) {
                 const result = formatResults(watched);
-                manager.acknowledgeDeliveries(watched.map((j) => j.id));
                 return { content: [{ type: "text", text: result }], details: undefined };
             }
             // Wait for at least one to complete
             await Promise.race(running.map((j) => j.promise));
             // Collect all completed results (more may have finished while waiting)
             const completed = watched.filter((j) => j.status !== "running");
-            manager.acknowledgeDeliveries(completed.map((j) => j.id));
             const stillRunning = watched.filter((j) => j.status === "running");
             let result = formatResults(completed);
             if (stillRunning.length > 0) {

package/dist/resources/extensions/async-jobs/job-manager.js

@@ -101,12 +101,6 @@ export class AsyncJobManager {
     getAllJobs() {
         return [...this.jobs.values()];
     }
-    /**
-     * No-op. Retained for API compatibility with await_job tool.
-     */
-    acknowledgeDeliveries(_jobIds) {
-        // Delivery is fire-once; no retries to cancel.
-    }
     /**
      * Cleanup all timers and resources.
      */

package/dist/resources/extensions/bg-shell/output-formatter.js

@@ -2,7 +2,7 @@
  * Output analysis, digest generation, highlights extraction, and output retrieval.
  */
 import { truncateHead, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, } from "@gsd/pi-coding-agent";
-import { ERROR_PATTERN_UNION, WARNING_PATTERN_UNION, READINESS_PATTERN_UNION, BUILD_COMPLETE_PATTERN_UNION, TEST_RESULT_PATTERN_UNION, URL_PATTERN, PORT_PATTERN_SOURCE, LINE_DEDUP_MAX, } from "./types.js";
+import { ERROR_PATTERN_UNION, WARNING_PATTERN_UNION, READINESS_PATTERN_UNION, BUILD_COMPLETE_PATTERN_UNION, TEST_RESULT_PATTERN_UNION, URL_PATTERN, PORT_PATTERN_SOURCE, } from "./types.js";
 import { addEvent, pushAlert } from "./process-manager.js";
 import { transitionToReady } from "./readiness-detector.js";
 import { formatUptime, formatTimeAgo } from "./utilities.js";
@@ -78,24 +78,6 @@ export function analyzeLine(bg, line, stream) {
             pushAlert(bg, "recovered — errors cleared");
         }
     }
-    // Dedup tracking — evict oldest entry when map exceeds LINE_DEDUP_MAX (LRU via Map insertion order)
-    bg.totalRawLines++;
-    const lineHash = line.trim().slice(0, 100);
-    const existing = bg.lineDedup.get(lineHash);
-    if (existing !== undefined) {
-        // Re-insert to update insertion order (move to tail = most recent)
-        bg.lineDedup.delete(lineHash);
-        bg.lineDedup.set(lineHash, existing + 1);
-    }
-    else {
-        if (bg.lineDedup.size >= LINE_DEDUP_MAX) {
-            // Evict oldest entry (Map iteration order = insertion order = LRU at head)
-            const oldest = bg.lineDedup.keys().next().value;
-            if (oldest !== undefined)
-                bg.lineDedup.delete(oldest);
-        }
-        bg.lineDedup.set(lineHash, 1);
-    }
 }
 // ── Digest Generation ──────────────────────────────────────────────────────
 export function generateDigest(bg, mutate = false) {

package/dist/resources/extensions/bg-shell/process-manager.js

@@ -135,12 +135,8 @@ export function startProcess(opts) {
         group: opts.group || null,
         lastErrorCount: 0,
         lastWarningCount: 0,
-        commandHistory: [],
-        lineDedup: new Map(),
-        totalRawLines: 0,
         stdoutLineCount: 0,
         stderrLineCount: 0,
-        envKeys: Object.keys(opts.env || {}),
         restartCount: 0,
         startConfig: {
             command,

package/dist/resources/extensions/bg-shell/types.js

@@ -5,8 +5,6 @@
 export const MAX_BUFFER_LINES = 5000;
 export const MAX_EVENTS = 200;
 export const DEAD_PROCESS_TTL = 10 * 60 * 1000;
-/** Maximum unique entries in the per-process lineDedup Map before LRU eviction. */
-export const LINE_DEDUP_MAX = 500;
 export const PORT_PROBE_TIMEOUT = 500;
 export const READY_POLL_INTERVAL = 250;
 export const DEFAULT_READY_TIMEOUT = 30000;

package/dist/resources/extensions/cmux/index.js

@@ -0,0 +1,321 @@
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const DEFAULT_SOCKET_PATH = "/tmp/cmux.sock";
+const STATUS_KEY = "gsd";
+const lastSidebarSnapshots = new Map();
+let cmuxPromptedThisSession = false;
+let cachedCliAvailability = null;
+export function detectCmuxEnvironment(env = process.env, socketExists = existsSync, cliAvailable = isCmuxCliAvailable) {
+    const socketPath = env.CMUX_SOCKET_PATH ?? DEFAULT_SOCKET_PATH;
+    const workspaceId = env.CMUX_WORKSPACE_ID?.trim() || undefined;
+    const surfaceId = env.CMUX_SURFACE_ID?.trim() || undefined;
+    const available = Boolean(workspaceId && surfaceId && socketExists(socketPath));
+    return {
+        available,
+        cliAvailable: cliAvailable(),
+        socketPath,
+        workspaceId,
+        surfaceId,
+    };
+}
+export function resolveCmuxConfig(preferences, env = process.env, socketExists = existsSync, cliAvailable = isCmuxCliAvailable) {
+    const detected = detectCmuxEnvironment(env, socketExists, cliAvailable);
+    const cmux = preferences?.cmux ?? {};
+    const enabled = detected.available && cmux.enabled === true;
+    return {
+        ...detected,
+        enabled,
+        notifications: enabled && cmux.notifications !== false,
+        sidebar: enabled && cmux.sidebar !== false,
+        splits: enabled && cmux.splits === true,
+        browser: enabled && cmux.browser === true,
+    };
+}
+export function shouldPromptToEnableCmux(preferences, env = process.env, socketExists = existsSync, cliAvailable = isCmuxCliAvailable) {
+    if (cmuxPromptedThisSession)
+        return false;
+    const detected = detectCmuxEnvironment(env, socketExists, cliAvailable);
+    if (!detected.available)
+        return false;
+    return preferences?.cmux?.enabled === undefined;
+}
+export function markCmuxPromptShown() {
+    cmuxPromptedThisSession = true;
+}
+export function resetCmuxPromptState() {
+    cmuxPromptedThisSession = false;
+}
+export function isCmuxCliAvailable() {
+    if (cachedCliAvailability !== null)
+        return cachedCliAvailability;
+    try {
+        execFileSync("cmux", ["--help"], { stdio: "ignore", timeout: 1000 });
+        cachedCliAvailability = true;
+    }
+    catch {
+        cachedCliAvailability = false;
+    }
+    return cachedCliAvailability;
+}
+export function supportsOsc777Notifications(env = process.env) {
+    const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
+    return termProgram === "ghostty" || termProgram === "wezterm" || termProgram === "iterm.app";
+}
+export function emitOsc777Notification(title, body) {
+    if (!supportsOsc777Notifications())
+        return;
+    const safeTitle = normalizeNotificationText(title).replace(/;/g, ",");
+    const safeBody = normalizeNotificationText(body).replace(/;/g, ",");
+    process.stdout.write(`\x1b]777;notify;${safeTitle};${safeBody}\x07`);
+}
+export function buildCmuxStatusLabel(state) {
+    const parts = [];
+    if (state.activeMilestone)
+        parts.push(state.activeMilestone.id);
+    if (state.activeSlice)
+        parts.push(state.activeSlice.id);
+    if (state.activeTask) {
+        const prev = parts.pop();
+        parts.push(prev ? `${prev}/${state.activeTask.id}` : state.activeTask.id);
+    }
+    if (parts.length === 0)
+        return state.phase;
+    return `${parts.join(" ")} · ${state.phase}`;
+}
+export function buildCmuxProgress(state) {
+    const progress = state.progress;
+    if (!progress)
+        return null;
+    const choose = (done, total, label) => {
+        if (total <= 0)
+            return null;
+        return { value: Math.max(0, Math.min(1, done / total)), label: `${done}/${total} ${label}` };
+    };
+    return choose(progress.tasks?.done ?? 0, progress.tasks?.total ?? 0, "tasks")
+        ?? choose(progress.slices?.done ?? 0, progress.slices?.total ?? 0, "slices")
+        ?? choose(progress.milestones.done, progress.milestones.total, "milestones");
+}
+function phaseVisuals(phase) {
+    switch (phase) {
+        case "blocked":
+            return { icon: "triangle-alert", color: "#ef4444" };
+        case "paused":
+            return { icon: "pause", color: "#f59e0b" };
+        case "complete":
+        case "completing-milestone":
+            return { icon: "check", color: "#22c55e" };
+        case "planning":
+        case "researching":
+        case "replanning-slice":
+            return { icon: "compass", color: "#3b82f6" };
+        case "validating-milestone":
+        case "verifying":
+            return { icon: "shield-check", color: "#06b6d4" };
+        default:
+            return { icon: "rocket", color: "#4ade80" };
+    }
+}
+function sidebarSnapshotKey(config) {
+    return config.workspaceId ?? "default";
+}
+export class CmuxClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    static fromPreferences(preferences) {
+        return new CmuxClient(resolveCmuxConfig(preferences));
+    }
+    getConfig() {
+        return this.config;
+    }
+    canRun() {
+        return this.config.available && this.config.cliAvailable;
+    }
+    appendWorkspace(args) {
+        return this.config.workspaceId ? [...args, "--workspace", this.config.workspaceId] : args;
+    }
+    appendSurface(args, surfaceId) {
+        return surfaceId ? [...args, "--surface", surfaceId] : args;
+    }
+    runSync(args) {
+        if (!this.canRun())
+            return null;
+        try {
+            return execFileSync("cmux", args, {
+                encoding: "utf-8",
+                timeout: 3000,
+                env: process.env,
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    async runAsync(args) {
+        if (!this.canRun())
+            return null;
+        try {
+            const result = await execFileAsync("cmux", args, {
+                encoding: "utf-8",
+                timeout: 5000,
+                env: process.env,
+            });
+            return result.stdout;
+        }
+        catch {
+            return null;
+        }
+    }
+    getCapabilities() {
+        const stdout = this.runSync(["capabilities", "--json"]);
+        return stdout ? parseJson(stdout) : null;
+    }
+    identify() {
+        const stdout = this.runSync(["identify", "--json"]);
+        return stdout ? parseJson(stdout) : null;
+    }
+    setStatus(label, phase) {
+        if (!this.config.sidebar)
+            return;
+        const visuals = phaseVisuals(phase);
+        this.runSync(this.appendWorkspace([
+            "set-status",
+            STATUS_KEY,
+            label,
+            "--icon",
+            visuals.icon,
+            "--color",
+            visuals.color,
+        ]));
+    }
+    clearStatus() {
+        if (!this.config.sidebar)
+            return;
+        this.runSync(this.appendWorkspace(["clear-status", STATUS_KEY]));
+    }
+    setProgress(progress) {
+        if (!this.config.sidebar)
+            return;
+        if (!progress) {
+            this.runSync(this.appendWorkspace(["clear-progress"]));
+            return;
+        }
+        this.runSync(this.appendWorkspace([
+            "set-progress",
+            progress.value.toFixed(3),
+            "--label",
+            progress.label,
+        ]));
+    }
+    log(message, level = "info", source = "gsd") {
+        if (!this.config.sidebar)
+            return;
+        this.runSync(this.appendWorkspace([
+            "log",
+            "--level",
+            level,
+            "--source",
+            source,
+            "--",
+            message,
+        ]));
+    }
+    notify(title, body, subtitle) {
+        if (!this.config.notifications)
+            return false;
+        const args = ["notify", "--title", title, "--body", body];
+        if (subtitle)
+            args.push("--subtitle", subtitle);
+        return this.runSync(args) !== null;
+    }
+    async listSurfaceIds() {
+        const stdout = await this.runAsync(this.appendWorkspace(["list-surfaces", "--json", "--id-format", "both"]));
+        const parsed = stdout ? parseJson(stdout) : null;
+        return extractSurfaceIds(parsed);
+    }
+    async createSplit(direction) {
+        if (!this.config.splits)
+            return null;
+        const before = new Set(await this.listSurfaceIds());
+        const args = ["new-split", direction];
+        const scopedArgs = this.appendSurface(this.appendWorkspace(args), this.config.surfaceId);
+        await this.runAsync(scopedArgs);
+        const after = await this.listSurfaceIds();
+        for (const id of after) {
+            if (!before.has(id))
+                return id;
+        }
+        return null;
+    }
+    async sendSurface(surfaceId, text) {
+        const payload = text.endsWith("\n") ? text : `${text}\n`;
+        const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);
+        return stdout !== null;
+    }
+}
+export function syncCmuxSidebar(preferences, state) {
+    const client = CmuxClient.fromPreferences(preferences);
+    const config = client.getConfig();
+    if (!config.sidebar)
+        return;
+    const label = buildCmuxStatusLabel(state);
+    const progress = buildCmuxProgress(state);
+    const snapshot = JSON.stringify({ label, progress, phase: state.phase });
+    const key = sidebarSnapshotKey(config);
+    if (lastSidebarSnapshots.get(key) === snapshot)
+        return;
+    client.setStatus(label, state.phase);
+    client.setProgress(progress);
+    lastSidebarSnapshots.set(key, snapshot);
+}
+export function clearCmuxSidebar(preferences) {
+    const config = resolveCmuxConfig(preferences);
+    if (!config.available || !config.cliAvailable)
+        return;
+    const client = new CmuxClient({ ...config, enabled: true, sidebar: true });
+    const key = sidebarSnapshotKey(config);
+    client.clearStatus();
+    client.setProgress(null);
+    lastSidebarSnapshots.delete(key);
+}
+export function logCmuxEvent(preferences, message, level = "info") {
+    CmuxClient.fromPreferences(preferences).log(message, level);
+}
+export function shellEscape(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function normalizeNotificationText(value) {
+    return value.replace(/\r?\n/g, " ").trim();
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function extractSurfaceIds(value) {
+    const found = new Set();
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (!node || typeof node !== "object")
+            return;
+        for (const [key, child] of Object.entries(node)) {
+            if (typeof child === "string"
+                && (key === "surface_id" || key === "surface" || (key === "id" && child.includes("surface")))) {
+                found.add(child);
+            }
+            visit(child);
+        }
+    };
+    visit(value);
+    return Array.from(found);
+}

package/dist/resources/extensions/context7/index.js

@@ -327,6 +327,11 @@ export default function (pi) {
             return new Text(text, 0, 0);
         },
     });
+    // ── Session cleanup ─────────────────────────────────────────────────────
+    pi.on("session_shutdown", async () => {
+        searchCache.clear();
+        docCache.clear();
+    });
     // ── Startup notification ─────────────────────────────────────────────────
     pi.on("session_start", async (_event, ctx) => {
         if (!getApiKey()) {

package/dist/resources/extensions/get-secrets-from-user.js

@@ -8,9 +8,9 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import { CURSOR_MARKER, Editor, Key, matchesKey, Text, truncateToWidth, wrapTextWithAnsi } from "@gsd/pi-tui";
+import { Editor, Key, matchesKey, Text, truncateToWidth, wrapTextWithAnsi } from "@gsd/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { makeUI } from "./shared/mod.js";
+import { makeUI, maskEditorLine } from "./shared/mod.js";
 import { parseSecretsManifest, formatSecretsManifest } from "./gsd/files.js";
 import { resolveMilestoneFile } from "./gsd/paths.js";
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -21,34 +21,6 @@ function maskPreview(value) {
         return "*".repeat(value.length);
     return `${value.slice(0, 4)}${"*".repeat(Math.max(4, value.length - 8))}${value.slice(-4)}`;
 }
-/**
- * Replace editor visible text with masked characters while preserving ANSI cursor/sequencer codes.
- */
-function maskEditorLine(line) {
-    // Keep border / metadata lines readable.
-    if (line.startsWith("─")) {
-        return line;
-    }
-    let output = "";
-    let i = 0;
-    while (i < line.length) {
-        if (line.startsWith(CURSOR_MARKER, i)) {
-            output += CURSOR_MARKER;
-            i += CURSOR_MARKER.length;
-            continue;
-        }
-        const ansiMatch = /^\x1b\[[0-9;]*m/.exec(line.slice(i));
-        if (ansiMatch) {
-            output += ansiMatch[0];
-            i += ansiMatch[0].length;
-            continue;
-        }
-        const ch = line[i];
-        output += ch === " " ? " " : "*";
-        i += 1;
-    }
-    return output;
-}
 function shellEscapeSingle(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }

package/dist/resources/extensions/google-search/index.js

@@ -326,6 +326,11 @@ export default function (pi) {
             return new Text(text, 0, 0);
         },
     });
+    // ── Session cleanup ─────────────────────────────────────────────────────
+    pi.on("session_shutdown", async () => {
+        resultCache.clear();
+        client = null;
+    });
     // ── Startup notification ─────────────────────────────────────────────────
     pi.on("session_start", async (_event, ctx) => {
         if (process.env.GEMINI_API_KEY)