@kenkaiiii/ggcoder 4.11.3 → 4.12.2

package/dist/core/shell.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cross-platform shell resolution for the bash tool + background process
+ * manager.
+ *
+ * The agent writes shell commands assuming POSIX `bash` semantics (`&&`, pipes,
+ * `ls`, `grep`, `$(...)`, single-quoting, …). On macOS/Linux that's just
+ * `bash`. On Windows there are three cases, and getting this wrong is the root
+ * of the "files not mounted / different environment" class of bugs:
+ *
+ *   1. Git Bash (Git for Windows) — a REAL POSIX bash that operates on the
+ *      native Windows filesystem. `D:\proj` is reachable as `/d/proj` AND the
+ *      spawned process honors the Windows `cwd`. This is what we want, so we
+ *      detect and prefer it.
+ *
+ *   2. WSL bash (`C:\Windows\System32\bash.exe`) — the Windows Subsystem for
+ *      Linux launcher. It runs commands inside a SEPARATE Linux distro whose
+ *      filesystem is not the project tree (`D:\proj` ≈ `/mnt/d/proj`, and a
+ *      raw `D:\proj` cwd lands you somewhere else entirely). Commands appear to
+ *      run "in a different project / sandbox". We deliberately SKIP it.
+ *
+ *   3. No bash at all — bare `spawn("bash", …)` fails with `spawn bash ENOENT`,
+ *      so every shell command the agent runs errors out. We fall back to
+ *      `cmd.exe` so commands can at least run (with different semantics, which
+ *      the agent is told about).
+ *
+ * The resolver is pure: filesystem + env + platform are injected so it can be
+ * unit-tested for every OS from any host.
+ */
+export interface ShellResolution {
+    /** Executable to spawn (never goes through a shell wrapper itself). */
+    file: string;
+    /** Args that run the given command string as one shell command. */
+    args: string[];
+    /** True when `file` is a cmd.exe fallback (non-POSIX semantics). */
+    isCmdFallback: boolean;
+}
+export interface ResolveShellOpts {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    /** Injected for testability; defaults to fs.existsSync. */
+    exists?: (p: string) => boolean;
+}
+/**
+ * Resolve the shell executable + args to run a single command string.
+ *
+ * `GG_BASH` env override always wins (point it at any POSIX bash, e.g. a custom
+ * Git Bash or msys2 install). Otherwise: non-Windows → `bash`; Windows → Git
+ * Bash if found, else `cmd.exe`.
+ */
+export declare function resolveShell(command: string, opts?: ResolveShellOpts): ShellResolution;
+//# sourceMappingURL=shell.d.ts.map

package/dist/core/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/core/shell.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACjC;AAmDD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,eAAe,CAwB1F"}

package/dist/core/shell.js

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+/**
+ * Fixed Git-Bash install locations to probe on Windows, in priority order.
+ * These cover the official Git for Windows installer (system + per-user) plus
+ * the common 32-bit path. We NEVER include `System32\bash.exe` (WSL).
+ */
+function gitBashFixedCandidates(env) {
+    const programFiles = env.ProgramFiles ?? "C:\\Program Files";
+    const programFilesX86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    const localAppData = env.LOCALAPPDATA;
+    const candidates = [
+        path.win32.join(programFiles, "Git", "bin", "bash.exe"),
+        path.win32.join(programFilesX86, "Git", "bin", "bash.exe"),
+    ];
+    if (localAppData) {
+        candidates.push(path.win32.join(localAppData, "Programs", "Git", "bin", "bash.exe"));
+    }
+    return candidates;
+}
+/**
+ * Derive Git Bash from `git.exe` on PATH: Git for Windows ships `git.exe` under
+ * `<root>\cmd` (and `<root>\bin`), with `bash.exe` at `<root>\bin\bash.exe`.
+ */
+function gitBashFromPath(env, exists) {
+    const rawPath = env.PATH ?? env.Path ?? "";
+    if (!rawPath)
+        return null;
+    // Windows PATH is always ';'-separated. (Don't use path.delimiter — it
+    // reflects the HOST OS, which breaks when this win32-only branch is exercised
+    // in cross-platform tests on a POSIX host.)
+    for (const dir of rawPath.split(";")) {
+        if (!dir)
+            continue;
+        const gitExe = path.win32.join(dir, "git.exe");
+        if (!exists(gitExe))
+            continue;
+        // <root>\cmd\git.exe or <root>\bin\git.exe → <root>\bin\bash.exe
+        const gitRoot = path.win32.dirname(path.win32.dirname(gitExe));
+        const bash = path.win32.join(gitRoot, "bin", "bash.exe");
+        if (exists(bash))
+            return bash;
+    }
+    return null;
+}
+/** Locate a usable Git Bash on Windows, or null if none is installed. */
+function findGitBash(env, exists) {
+    for (const candidate of gitBashFixedCandidates(env)) {
+        if (exists(candidate))
+            return candidate;
+    }
+    return gitBashFromPath(env, exists);
+}
+/**
+ * Resolve the shell executable + args to run a single command string.
+ *
+ * `GG_BASH` env override always wins (point it at any POSIX bash, e.g. a custom
+ * Git Bash or msys2 install). Otherwise: non-Windows → `bash`; Windows → Git
+ * Bash if found, else `cmd.exe`.
+ */
+export function resolveShell(command, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    const exists = opts.exists ?? existsSync;
+    // Explicit override (power users / tests): treat as a POSIX bash.
+    const override = env.GG_BASH?.trim();
+    if (override) {
+        return { file: override, args: ["-c", command], isCmdFallback: false };
+    }
+    if (platform !== "win32") {
+        return { file: "bash", args: ["-c", command], isCmdFallback: false };
+    }
+    const gitBash = findGitBash(env, exists);
+    if (gitBash) {
+        return { file: gitBash, args: ["-c", command], isCmdFallback: false };
+    }
+    // Last resort: cmd.exe. `/d` skips AutoRun, `/s` + `/c` runs the rest as a
+    // single command verbatim (correct quoting for an arbitrary command string).
+    const comspec = env.ComSpec ?? env.COMSPEC ?? "C:\\Windows\\System32\\cmd.exe";
+    return { file: comspec, args: ["/d", "/s", "/c", command], isCmdFallback: true };
+}
+//# sourceMappingURL=shell.js.map

package/dist/core/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/core/shell.ts"],"names":[],"mappings":"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"}

package/dist/core/shell.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shell.test.d.ts.map

package/dist/core/shell.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.test.d.ts","sourceRoot":"","sources":["../../src/core/shell.test.ts"],"names":[],"mappings":""}

package/dist/core/shell.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { resolveShell } from "./shell.js";
+describe("resolveShell", () => {
+    it("uses bash on macOS/Linux", () => {
+        for (const platform of ["darwin", "linux"]) {
+            const r = resolveShell("ls -la", { platform, env: {}, exists: () => false });
+            expect(r).toEqual({ file: "bash", args: ["-c", "ls -la"], isCmdFallback: false });
+        }
+    });
+    it("honors the GG_BASH override on any platform", () => {
+        const r = resolveShell("echo hi", {
+            platform: "win32",
+            env: { GG_BASH: "C:\\msys64\\usr\\bin\\bash.exe" },
+            // Even though Git Bash also 'exists', the override wins.
+            exists: () => true,
+        });
+        expect(r).toEqual({
+            file: "C:\\msys64\\usr\\bin\\bash.exe",
+            args: ["-c", "echo hi"],
+            isCmdFallback: false,
+        });
+    });
+    it("prefers Git Bash at the standard Program Files location on Windows", () => {
+        const gitBash = "C:\\Program Files\\Git\\bin\\bash.exe";
+        const r = resolveShell("grep -r foo .", {
+            platform: "win32",
+            env: { ProgramFiles: "C:\\Program Files" },
+            exists: (p) => p === gitBash,
+        });
+        expect(r).toEqual({ file: gitBash, args: ["-c", "grep -r foo ."], isCmdFallback: false });
+    });
+    it("finds per-user Git Bash under LOCALAPPDATA", () => {
+        const gitBash = "C:\\Users\\dev\\AppData\\Local\\Programs\\Git\\bin\\bash.exe";
+        const r = resolveShell("pwd", {
+            platform: "win32",
+            env: { LOCALAPPDATA: "C:\\Users\\dev\\AppData\\Local" },
+            exists: (p) => p === gitBash,
+        });
+        expect(r.file).toBe(gitBash);
+        expect(r.isCmdFallback).toBe(false);
+    });
+    it("derives Git Bash from git.exe on PATH (<root>\\cmd\\git.exe)", () => {
+        const gitExe = "C:\\Tools\\Git\\cmd\\git.exe";
+        const bash = "C:\\Tools\\Git\\bin\\bash.exe";
+        const r = resolveShell("node -v", {
+            platform: "win32",
+            env: { PATH: "C:\\Windows\\System32;C:\\Tools\\Git\\cmd" },
+            exists: (p) => p === gitExe || p === bash,
+        });
+        expect(r.file).toBe(bash);
+        expect(r.isCmdFallback).toBe(false);
+    });
+    it("NEVER selects WSL's System32 bash.exe (it isn't a Git Bash candidate)", () => {
+        // Only System32\bash.exe 'exists' — the resolver must ignore it and fall
+        // back to cmd.exe, because WSL runs in a separate Linux filesystem.
+        const wslBash = "C:\\Windows\\System32\\bash.exe";
+        const r = resolveShell("ls", {
+            platform: "win32",
+            env: {
+                PATH: "C:\\Windows\\System32",
+                ComSpec: "C:\\Windows\\System32\\cmd.exe",
+            },
+            exists: (p) => p === wslBash,
+        });
+        expect(r.file).not.toBe(wslBash);
+        expect(r.file).toBe("C:\\Windows\\System32\\cmd.exe");
+        expect(r.isCmdFallback).toBe(true);
+    });
+    it("falls back to ComSpec cmd.exe on Windows when no Git Bash exists", () => {
+        const r = resolveShell("dir", {
+            platform: "win32",
+            env: { ComSpec: "C:\\Windows\\System32\\cmd.exe" },
+            exists: () => false,
+        });
+        expect(r).toEqual({
+            file: "C:\\Windows\\System32\\cmd.exe",
+            args: ["/d", "/s", "/c", "dir"],
+            isCmdFallback: true,
+        });
+    });
+    it("defaults the cmd.exe path when ComSpec is unset", () => {
+        const r = resolveShell("dir", { platform: "win32", env: {}, exists: () => false });
+        expect(r.file).toBe("C:\\Windows\\System32\\cmd.exe");
+        expect(r.isCmdFallback).toBe(true);
+    });
+});
+//# sourceMappingURL=shell.test.js.map

package/dist/core/shell.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.test.js","sourceRoot":"","sources":["../../src/core/shell.test.ts"],"names":[],"mappings":"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"}

package/dist/core/speed-benchmark.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Speed benchmark harness — measures the latency impact of speedProfile
+ * optimizations (1-h cache TTL + pre-warming) against the current baseline
+ * (5-min cache TTL, no pre-warm).
+ *
+ * Uses a mock streaming provider that simulates realistic provider timing:
+ *   - Cold prefill (cache miss): proportional to uncached input tokens
+ *   - Warm prefill (cache hit): 10× faster (cache reads cost 0.1×)
+ *   - Output streaming: at a configurable token rate
+ *   - Cache TTL: configurable (5 min baseline vs 1 h optimized)
+ *
+ * No real API calls are made — the mock uses real `setTimeout` for prefill and
+ * output-token latency (so wall-clock measurements are meaningful) but a
+ * virtual clock for inter-turn delays (so multi-minute gaps are instant).
+ *
+ * Run via vitest:  npx vitest run src/core/speed-benchmark.test.ts
+ * Or as a script:  npx tsx src/core/speed-benchmark.ts
+ */
+import { StreamResult, type StreamOptions } from "@kenkaiiii/gg-ai";
+export interface MockTimingConfig {
+    /** ms per uncached input token during prefill (cold start). */
+    coldPrefillMsPerToken: number;
+    /** ms per cached input token during prefill (cache hit). 10× faster. */
+    warmPrefillMsPerToken: number;
+    /** ms per output token (determines streaming rate). ~15ms = 66 tok/s. */
+    outputMsPerToken: number;
+    /** Cache TTL in ms. 5_000 = baseline (5 min), 3_600_000 = optimized (1 h). */
+    cacheTtlMs: number;
+    /** Fixed network overhead per request (TCP + TLS + auth). */
+    networkOverheadMs: number;
+    /** Default output tokens per turn if not specified by the workload. */
+    defaultOutputTokens: number;
+}
+export declare const REALISTIC_TIMING: MockTimingConfig;
+/**
+ * A mock streaming provider that simulates LLM timing with cache semantics.
+ * Registered as provider "benchmark-mock" so the real agent loop code path
+ * is exercised end-to-end.
+ */
+export declare class MockBenchmarkProvider {
+    private cache;
+    private config;
+    /** Virtual clock — lets the benchmark simulate multi-minute gaps between
+     *  turns without actually sleeping. The cache TTL check uses this, not
+     *  Date.now(). Only prefill/output latency uses real setTimeout. */
+    private virtualNow;
+    readonly stats: {
+        cacheHits: number;
+        cacheMisses: number;
+        cacheWrites: number;
+        cacheEvictions: number;
+        totalPrefillMs: number;
+        totalOutputMs: number;
+        totalNetworkMs: number;
+        turns: number;
+    };
+    constructor(config?: Partial<MockTimingConfig>);
+    /** Update config (e.g., switch TTL for baseline vs optimized run). */
+    setConfig(config: Partial<MockTimingConfig>): void;
+    /** Advance the virtual clock (for cache TTL simulation without real sleeping). */
+    advanceClock(ms: number): void;
+    /** Clear all cache state and stats (between benchmark runs). */
+    reset(): void;
+    /** Number of entries currently in the mock cache. */
+    getCacheSize(): number;
+    /** Force a cache write (simulates pre-warming). */
+    prewarm(cacheKey: string, tokenCount: number): void;
+    stream(options: StreamOptions): StreamResult;
+    private runStream;
+    /** Compute a stable cache key from the system prompt + tool names. */
+    private computeCacheKey;
+}
+export interface WorkloadTurn {
+    /** User message content. */
+    prompt: string;
+    /** Delay before this turn (simulates user think time). Default: 0. */
+    delayMs?: number;
+    /** Override output tokens for this turn. */
+    outputTokens?: number;
+}
+export interface Workload {
+    name: string;
+    /** System prompt (simulates a realistic coding-agent system prompt). */
+    systemPrompt: string;
+    /** Tool definitions (names only for the mock). */
+    toolNames: string[];
+    turns: WorkloadTurn[];
+}
+export interface TurnMetrics {
+    turnNumber: number;
+    promptPreview: string;
+    delayBeforeTurnMs: number;
+    ttftMs: number;
+    cacheHit: boolean;
+    inputTokens: number;
+    outputTokens: number;
+    wallClockMs: number;
+}
+export interface BenchmarkResult {
+    name: string;
+    config: MockTimingConfig;
+    prewarmed: boolean;
+    turns: TurnMetrics[];
+    totalWallClockMs: number;
+    totalTtftMs: number;
+    cacheHits: number;
+    cacheMisses: number;
+    cacheHitRate: number;
+}
+/** Run a workload against the mock provider and collect per-turn metrics. */
+export declare function runBenchmark(workload: Workload, config: MockTimingConfig, options?: {
+    prewarm?: boolean;
+    name?: string;
+}): Promise<BenchmarkResult>;
+export interface ComparisonResult {
+    baseline: BenchmarkResult;
+    optimized: BenchmarkResult;
+    wallClockImprovement: number;
+    ttftImprovement: number;
+    cacheHitRateImprovement: number;
+}
+export declare function compareResults(baseline: BenchmarkResult, optimized: BenchmarkResult): ComparisonResult;
+/** Format a benchmark result as a readable table. */
+export declare function formatResultTable(result: BenchmarkResult): string;
+/** Format a side-by-side comparison. */
+export declare function formatComparison(comparison: ComparisonResult): string;
+/** A realistic multi-turn coding workload with time gaps that expose the
+ *  5-min vs 1-h TTL difference. */
+export declare function createDefaultWorkload(): Workload;
+/** Run baseline vs optimized and return the comparison. Uses scaled-down
+ *  timing (10× faster than real) so the benchmark completes in seconds. */
+export declare function runFullBenchmark(): Promise<ComparisonResult>;
+//# sourceMappingURL=speed-benchmark.d.ts.map

package/dist/core/speed-benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speed-benchmark.d.ts","sourceRoot":"","sources":["../../src/core/speed-benchmark.ts"],"names":[],"mappings":"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"}