gsd-pi 2.81.0 → 2.82.0-dev.20138ae42

package/dist/resources/extensions/subagent/launch.js

@@ -0,0 +1,77 @@
+// GSD-2 + Subagent launch contract and child process safety helpers.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { SessionManager } from "@gsd/pi-coding-agent";
+export const SUBAGENT_CHILD_ENV_VAR = "GSD_SUBAGENT_CHILD";
+export const SUBAGENT_CHILD_ENV_VALUE = "1";
+export function isSubagentChildProcess(env = process.env) {
+    return env[SUBAGENT_CHILD_ENV_VAR] === SUBAGENT_CHILD_ENV_VALUE;
+}
+export function buildSubagentProcessEnv(env = process.env) {
+    return {
+        ...env,
+        [SUBAGENT_CHILD_ENV_VAR]: SUBAGENT_CHILD_ENV_VALUE,
+    };
+}
+export function buildShellEnvAssignments(env = process.env) {
+    const value = env[SUBAGENT_CHILD_ENV_VAR];
+    return value ? [`${SUBAGENT_CHILD_ENV_VAR}=${JSON.stringify(value)}`] : [];
+}
+export function buildSubagentProcessArgs(agent, task, tmpPromptPath, modelOverride, session = { mode: "fresh" }) {
+    const args = ["--mode", "json", "-p"];
+    if (session.mode === "fork") {
+        args.push("--session", session.sessionFile);
+        if (session.sessionDir)
+            args.push("--session-dir", session.sessionDir);
+    }
+    else {
+        args.push("--no-session");
+    }
+    const effectiveModel = modelOverride ?? agent.model;
+    if (effectiveModel)
+        args.push("--model", effectiveModel);
+    if (agent.tools && agent.tools.length > 0)
+        args.push("--tools", agent.tools.join(","));
+    if (tmpPromptPath)
+        args.push("--append-system-prompt", tmpPromptPath);
+    args.push(`Task: ${task}`);
+    return args;
+}
+export function resolveSubagentSessionArgs(contextMode = "fresh", parentSessionManager) {
+    if (contextMode === "fresh")
+        return { mode: "fresh" };
+    if (!parentSessionManager) {
+        throw new Error("Forked subagent context requires a parent session manager.");
+    }
+    const parentSessionFile = parentSessionManager.getSessionFile();
+    if (!parentSessionFile) {
+        throw new Error("Forked subagent context requires a persisted parent session file; current session is in-memory.");
+    }
+    if (!fs.existsSync(parentSessionFile)) {
+        throw new Error(`Forked subagent context could not read parent session file: ${parentSessionFile}`);
+    }
+    const leafId = parentSessionManager.getLeafId();
+    if (!leafId) {
+        throw new Error("Forked subagent context requires a parent session leaf to branch from.");
+    }
+    const sessionDir = parentSessionManager.getSessionDir?.();
+    const parentSession = SessionManager.open(parentSessionFile, sessionDir);
+    const childSessionFile = parentSession.createBranchedSession(leafId);
+    if (!childSessionFile) {
+        throw new Error("Forked subagent context could not create a branched child session.");
+    }
+    return {
+        mode: "fork",
+        sessionFile: childSessionFile,
+        ...(sessionDir ? { sessionDir: path.resolve(sessionDir) } : {}),
+    };
+}
+export function createSubagentLaunchPlan(input) {
+    const session = input.session ?? resolveSubagentSessionArgs(input.contextMode ?? "fresh", input.parentSessionManager);
+    return {
+        args: buildSubagentProcessArgs(input.agent, input.task, input.tmpPromptPath, input.modelOverride, session),
+        env: buildSubagentProcessEnv(),
+        cwd: input.cwd ?? input.defaultCwd,
+        session,
+    };
+}

package/dist/resources/extensions/subagent/run-store.js

@@ -0,0 +1,148 @@
+// GSD-2 + Durable subagent run status, tracking names, and result artifact store.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomInt } from "node:crypto";
+import { getAgentDir } from "@gsd/pi-coding-agent";
+export function defaultSubagentRunStoreDir() {
+    return path.join(getAgentDir(), "subagent-runs");
+}
+const TRACKING_ADJECTIVES = [
+    "amber",
+    "bright",
+    "calm",
+    "clear",
+    "crisp",
+    "daring",
+    "keen",
+    "lucky",
+    "quiet",
+    "steady",
+    "swift",
+    "vivid",
+];
+const TRACKING_NOUNS = [
+    "anchor",
+    "atlas",
+    "beacon",
+    "canvas",
+    "compass",
+    "forge",
+    "harbor",
+    "lantern",
+    "ledger",
+    "mesa",
+    "quartz",
+    "ridge",
+    "signal",
+    "summit",
+    "vector",
+    "vista",
+];
+export function createSubagentTrackingName(existingNames = new Set()) {
+    const maxCombinations = TRACKING_ADJECTIVES.length * TRACKING_NOUNS.length;
+    for (let attempt = 0; attempt < maxCombinations * 2; attempt++) {
+        const adjective = TRACKING_ADJECTIVES[randomInt(TRACKING_ADJECTIVES.length)];
+        const noun = TRACKING_NOUNS[randomInt(TRACKING_NOUNS.length)];
+        const name = `${adjective}-${noun}`;
+        if (!existingNames.has(name))
+            return name;
+    }
+    let suffix = existingNames.size + 1;
+    while (existingNames.has(`agent-${suffix}`))
+        suffix++;
+    return `agent-${suffix}`;
+}
+export class SubagentRunStore {
+    baseDir;
+    constructor(baseDir = defaultSubagentRunStoreDir()) {
+        this.baseDir = baseDir;
+    }
+    getBaseDir() {
+        return this.baseDir;
+    }
+    create(record) {
+        this.write(record);
+        return record;
+    }
+    get(runId) {
+        const filePath = this.pathFor(runId);
+        if (!fs.existsSync(filePath))
+            return null;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+            if (!parsed ||
+                typeof parsed !== "object" ||
+                typeof parsed.runId !== "string" ||
+                typeof parsed.updatedAt !== "string" ||
+                !Array.isArray(parsed.children)) {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    update(runId, updater) {
+        const current = this.get(runId);
+        if (!current)
+            throw new Error(`Subagent run not found: ${runId}`);
+        const next = updater({
+            ...current,
+            children: current.children.map((child) => ({ ...child })),
+        });
+        next.updatedAt = new Date().toISOString();
+        this.write(next);
+        return next;
+    }
+    list() {
+        if (!fs.existsSync(this.baseDir))
+            return [];
+        return fs.readdirSync(this.baseDir)
+            .filter((name) => name.endsWith(".json"))
+            .map((name) => this.get(path.basename(name, ".json")))
+            .filter((record) => record !== null)
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    pathFor(runId) {
+        const safeRunId = runId.replace(/[^a-zA-Z0-9._-]/g, "_");
+        return path.join(this.baseDir, `${safeRunId}.json`);
+    }
+    write(record) {
+        fs.mkdirSync(this.baseDir, { recursive: true });
+        const filePath = this.pathFor(record.runId);
+        const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+        fs.writeFileSync(tmpPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+        fs.renameSync(tmpPath, filePath);
+    }
+}
+export function createInitialRunRecord(input) {
+    const now = input.now ?? new Date().toISOString();
+    return {
+        schemaVersion: 1,
+        runId: input.runId,
+        mode: input.mode,
+        contextMode: input.contextMode,
+        status: "running",
+        cwd: input.cwd,
+        startedAt: now,
+        updatedAt: now,
+        children: input.children.map((child, index) => ({
+            index,
+            agent: child.agent,
+            trackingName: child.trackingName,
+            task: child.task,
+            cwd: child.cwd,
+            status: "queued",
+        })),
+    };
+}
+export function deriveRunStatus(children) {
+    if (children.some((child) => child.status === "interrupted"))
+        return "interrupted";
+    if (children.some((child) => child.status === "failed"))
+        return "failed";
+    if (children.length > 0 && children.every((child) => child.status === "succeeded"))
+        return "succeeded";
+    return "running";
+}

package/dist/resources/extensions/visual-brief/artifact-policy.js

@@ -0,0 +1,29 @@
+// GSD-2 + Visual Brief artifact policy
+import { join } from "node:path";
+import { getAgentDir } from "@gsd/pi-coding-agent";
+export function getVisualBriefOutputDir(agentDir = getAgentDir()) {
+    return join(agentDir, "diagrams");
+}
+export function createVisualBriefArtifactPolicy(outputDir) {
+    return {
+        outputDir,
+        filenameStyle: "Use a descriptive kebab-case filename ending in .html.",
+        fileShape: "Produce one self-contained responsive HTML file with embedded CSS and minimal JavaScript.",
+        openers: [
+            "macOS: open",
+            "Linux: xdg-open",
+            "Windows: cmd /c start",
+        ],
+        failureBehavior: "If opening fails, report the absolute file path.",
+    };
+}
+export function formatArtifactPolicy(policy) {
+    return [
+        `- Create the output directory if it does not exist: ${policy.outputDir}`,
+        `- ${policy.filenameStyle}`,
+        `- ${policy.fileShape}`,
+        "- Open the result in a browser when the local platform has an opener available.",
+        ...policy.openers.map((opener) => `  - ${opener}`),
+        `- ${policy.failureBehavior}`,
+    ].join("\n");
+}

package/dist/resources/extensions/visual-brief/extension-manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "visual-brief",
+  "name": "Visual Brief",
+  "version": "1.0.0",
+  "description": "Prompt contracts backing /gsd brief visual HTML briefs",
+  "tier": "bundled",
+  "requires": { "platform": ">=2.29.0" }
+}

package/dist/resources/extensions/visual-brief/index.js

@@ -0,0 +1,5 @@
+// GSD-2 + Visual Brief bundled extension marker
+export default function visualBrief(_pi) {
+    // Visual Brief is invoked through /gsd brief. This module keeps the bundled
+    // extension discoverable without adding a second top-level slash command.
+}

package/dist/resources/extensions/visual-brief/page-contract.js

@@ -0,0 +1,124 @@
+// GSD-2 + Visual Brief page contract
+export const VISUAL_BRIEF_PAGE_RULES = [
+    "Use Mermaid for topology-heavy diagrams when it improves readability.",
+    "Use semantic HTML tables for comparisons, audits, matrices, status reports, and dense lists.",
+    "Use CSS grid/card layouts when text-heavy module details matter more than edge routing.",
+    "For 15+ entities, use a small overview diagram plus detailed cards instead of one crowded diagram.",
+    "Include accessible headings, readable contrast, responsive tables, and no horizontal body overflow.",
+    "Include source references for factual claims, file relationships, commands, and inferred behavior.",
+    "Keep the design distinctive and appropriate to the content; avoid generic purple/blue gradient styling.",
+    "CDN libraries are acceptable for Mermaid or charts, but the page must still show useful written context if a CDN fails.",
+    "Do not include provider-specific claims, branding, or assumptions.",
+];
+export function getVisualBriefModeProfile(mode, slides) {
+    if (slides || mode === "slides") {
+        return {
+            goal: "Turn the subject into a concise, visually paced deck that someone can present or skim quickly.",
+            evidenceSteps: [
+                "Identify the intended audience and the main decision or understanding the deck should support.",
+                "Read the relevant files, diffs, docs, or command output before making factual claims.",
+                "Extract the smallest set of concepts, risks, and examples needed for a clear narrative.",
+            ],
+            sections: [
+                "Title slide with the subject and one-line takeaway",
+                "Problem or context slide",
+                "System or concept diagram slide",
+                "Key evidence slide",
+                "Risks, tradeoffs, or unknowns slide",
+                "Recommended next steps slide",
+            ],
+        };
+    }
+    switch (mode) {
+        case "plan":
+            return {
+                goal: "Create a visual implementation plan that is detailed enough to guide coding without pretending uncertain facts are verified.",
+                evidenceSteps: [
+                    "Read the relevant exports, immediate callers, tests, docs, and shared utilities.",
+                    "Identify the likely file changes, existing conventions, edge cases, and test requirements.",
+                    "Mark any assumption that cannot be verified from the repository.",
+                ],
+                sections: [
+                    "Feature summary and scope boundaries",
+                    "Before/after workflow comparison",
+                    "Architecture or state-flow diagram",
+                    "Files to change with precise responsibilities",
+                    "API, command, or data-shape changes",
+                    "Edge cases and failure behavior",
+                    "Test plan with success and failure paths",
+                    "Open questions and assumptions",
+                ],
+            };
+        case "diff":
+            return {
+                goal: "Review the current changes visually so risk, intent, and affected areas are easy to scan.",
+                evidenceSteps: [
+                    "Inspect git status plus staged and unstaged diffs.",
+                    "Read changed files where needed to understand behavior, not just line changes.",
+                    "Separate confirmed findings from questions or residual risk.",
+                ],
+                sections: [
+                    "Change map by file and subsystem",
+                    "Intent summary inferred from the diff",
+                    "Risk heatmap",
+                    "Behavior changes and compatibility notes",
+                    "Test coverage matrix",
+                    "Actionable findings and open questions",
+                ],
+            };
+        case "recap":
+            return {
+                goal: "Create a context-switching snapshot that helps someone regain the project mental model quickly.",
+                evidenceSteps: [
+                    "Read the current project docs, recent git status, relevant plans, and high-signal source files.",
+                    "Identify active work, stable architecture, uncertain areas, and likely next actions.",
+                    "Prefer concrete file references and verified facts over broad summaries.",
+                ],
+                sections: [
+                    "Current project state",
+                    "Architecture map",
+                    "Active work and changed files",
+                    "Important decisions and constraints",
+                    "Risks or unresolved questions",
+                    "Recommended next actions",
+                ],
+            };
+        case "table":
+            return {
+                goal: "Turn dense structured information into an accessible visual table that is easier to compare than terminal output.",
+                evidenceSteps: [
+                    "Identify the row and column meanings before choosing table structure.",
+                    "Verify each cell from source material, command output, or code when possible.",
+                    "Use status labels and short notes so the table remains scannable.",
+                ],
+                sections: [
+                    "Short summary of what is being compared",
+                    "Primary responsive table with sticky header",
+                    "Legend for statuses or scoring",
+                    "Notable patterns, outliers, and caveats",
+                    "Source references",
+                ],
+            };
+        case "diagram":
+            return {
+                goal: "Explain the subject visually with a diagram plus enough context to make the diagram trustworthy.",
+                evidenceSteps: [
+                    "Read relevant files, docs, or command output before drawing relationships.",
+                    "Choose the right diagram type: flowchart, sequence, state, ER/schema, C4-style, timeline, or dashboard.",
+                    "Keep complex diagrams readable by splitting overview and details.",
+                ],
+                sections: [
+                    "One-line takeaway",
+                    "Primary diagram with readable labels",
+                    "Component or step details",
+                    "Data/control flow notes",
+                    "Assumptions, limitations, and source references",
+                ],
+            };
+        default:
+            throw new Error(`Unknown visual brief mode: ${mode}`);
+    }
+}
+export function formatPageRules(rules = VISUAL_BRIEF_PAGE_RULES) {
+    return rules.map((rule) => `   - ${rule}`).join("\n");
+}

package/dist/resources/extensions/visual-brief/prompts.js

@@ -0,0 +1,140 @@
+// GSD-2 + Visual Brief prompt construction
+import { createVisualBriefArtifactPolicy, formatArtifactPolicy, } from "./artifact-policy.js";
+import { formatPageRules, getVisualBriefModeProfile, } from "./page-contract.js";
+import { renderHtmlShellTemplate } from "../shared/html-shell.js";
+export const VISUAL_BRIEF_MODES = [
+    {
+        mode: "diagram",
+        aliases: ["diagram", "flow", "architecture", "arch", "web-diagram"],
+        description: "Generate a visual system, architecture, flow, state, or data diagram",
+    },
+    {
+        mode: "plan",
+        aliases: ["plan", "visual-plan", "implementation-plan"],
+        description: "Generate a visual implementation plan with risks, files, edge cases, and tests",
+    },
+    {
+        mode: "diff",
+        aliases: ["diff", "review", "diff-review", "changes"],
+        description: "Generate a visual review of staged and unstaged changes",
+        defaultSubject: "the current staged and unstaged repository changes",
+    },
+    {
+        mode: "recap",
+        aliases: ["recap", "project-recap", "summary"],
+        description: "Generate a visual project recap for context switching",
+        defaultSubject: "the current project",
+    },
+    {
+        mode: "table",
+        aliases: ["table", "comparison", "matrix", "audit"],
+        description: "Render a dense comparison, audit, or status report as a readable HTML table",
+    },
+    {
+        mode: "slides",
+        aliases: ["slides", "deck", "slide-deck"],
+        description: "Generate a visual slide deck",
+    },
+];
+export const VISUAL_BRIEF_USAGE = "Usage: /gsd brief <diagram|plan|diff|recap|table|slides> [topic] [--slides]";
+const VISUAL_BRIEF_KIND = {
+    diff: "Diff Brief",
+    recap: "Project Recap",
+    plan: "Implementation Plan",
+    diagram: "Diagram",
+    table: "Comparison",
+    slides: "Slide Deck",
+};
+export function parseVisualBriefArgs(args) {
+    const rawArgs = args.trim();
+    if (!rawArgs)
+        return null;
+    const tokens = rawArgs.split(/\s+/).filter(Boolean);
+    const slidesFlag = tokens.includes("--slides");
+    const contentTokens = tokens.filter((token) => token !== "--slides");
+    if (contentTokens.length === 0)
+        return null;
+    const firstToken = normalizeToken(contentTokens[0] ?? "");
+    const modeInfo = findMode(firstToken);
+    const mode = modeInfo?.mode ?? "diagram";
+    const subjectTokens = modeInfo ? contentTokens.slice(1) : contentTokens;
+    const subject = subjectTokens.join(" ").trim() || modeInfo?.defaultSubject;
+    if (!subject)
+        return null;
+    return {
+        mode,
+        subject,
+        slides: slidesFlag || mode === "slides",
+        rawArgs,
+    };
+}
+export function buildVisualBriefPrompt(request, options) {
+    const profile = getVisualBriefModeProfile(request.mode, request.slides);
+    const artifactPolicy = createVisualBriefArtifactPolicy(options.outputDir);
+    const outputFormat = request.slides ? "slide deck" : "scrollable explanation page";
+    const version = options.version?.trim() || undefined;
+    const shell = renderHtmlShellTemplate({
+        title: request.subject,
+        documentTitle: `GSD ${VISUAL_BRIEF_KIND[request.mode]} - ${request.subject}`,
+        subtitle: "Visual brief",
+        kind: VISUAL_BRIEF_KIND[request.mode],
+        version,
+        mainPlaceholder: "{{MAIN_HTML}}",
+        footerNote: request.subject,
+    });
+    return `Create a visual brief as a single HTML file.
+
+## Request
+
+- Mode: ${request.mode}
+- Subject: ${request.subject}
+- Output format: ${outputFormat}
+- Output directory: ${options.outputDir}
+
+## Goal
+
+${profile.goal}
+
+## Required workflow
+
+1. Gather evidence before writing the page.
+${profile.evidenceSteps.map((step) => `   - ${step}`).join("\n")}
+2. Build the visual structure from the evidence.
+${formatPageRules()}
+3. Write the HTML file.
+${formatArtifactPolicy(artifactPolicy).split("\n").map((line) => `   ${line}`).join("\n")}
+
+## Required HTML shell
+
+Use this scaffold verbatim. Replace {{MAIN_HTML}} with the authored <main> contents and {{GENERATED_AT}} with the current ISO timestamp. Do not add new <style> blocks or replace the header, footer, CSS, or script. The <h1> is the subject only; the kind chip is the only visual carrier of artifact type.
+
+\`\`\`html
+${shell}
+\`\`\`
+
+Author only section-level content for {{MAIN_HTML}}. Use the shell utility classes where they fit: .kv-grid, .tbl, .card-row, .card, .callout-info, .callout-warn, .callout-ok, .dot-active, .dot-complete, .dot-pending.
+
+## Page sections
+
+${profile.sections.map((section) => `- ${section}`).join("\n")}
+
+## Final response
+
+Keep the chat response short: state the output file path, whether the browser opened, and any uncertainty discovered during evidence gathering.`;
+}
+export function getVisualBriefCompletions(prefix) {
+    const firstPart = prefix.trim().split(/\s+/)[0] ?? "";
+    return VISUAL_BRIEF_MODES
+        .filter((mode) => mode.mode.startsWith(firstPart) || mode.aliases.some((alias) => alias.startsWith(firstPart)))
+        .map((mode) => ({
+        value: mode.mode,
+        label: mode.mode,
+        description: mode.description,
+    }));
+}
+function findMode(token) {
+    return VISUAL_BRIEF_MODES.find((mode) => mode.aliases.includes(token));
+}
+function normalizeToken(token) {
+    return token.trim().toLowerCase();
+}