@kenkaiiii/ggcoder 4.14.2 → 4.15.0

package/dist/core/hashline.js

@@ -0,0 +1,76 @@
+/**
+ * Hash-anchored line addressing — the pure, UI-free core shared by the hashline
+ * benchmark and the opt-in anchor guard in the read/edit tools.
+ *
+ * Every line gets a short content+position hash. Anchors are UNIQUE by
+ * construction (the line's index is folded into the hash, so blank/repeated
+ * lines never collide), which is what lets an edit either resolve to exactly one
+ * location or be rejected — never silently corrupt a file that drifted since the
+ * model last read it.
+ */
+import { createHash } from "node:crypto";
+/**
+ * 4-hex-char anchor for a line. Position is folded into the hash so anchors are
+ * UNIQUE by construction (blank lines and repeated lines no longer collide).
+ * Resolution stays O(1) via a lookup map. `index` is the 0-based line index.
+ */
+export function lineHash(line, index) {
+    return createHash("sha1").update(`${index}:${line.trim()}`).digest("hex").slice(0, 4);
+}
+/** File rendered with `anchor│line` prefixes for the model to read. */
+export function renderWithAnchors(file) {
+    return file
+        .split("\n")
+        .map((l, i) => `${lineHash(l, i)}│${l}`)
+        .join("\n");
+}
+export function anchorFile(file) {
+    const lines = file.split("\n");
+    const counts = new Map();
+    lines.forEach((l, i) => {
+        const h = lineHash(l, i);
+        const arr = counts.get(h) ?? [];
+        arr.push(i);
+        counts.set(h, arr);
+    });
+    const anchorToIndex = new Map();
+    const ambiguous = new Set();
+    for (const [h, idxs] of counts) {
+        // Position-folded anchors are unique unless sha1 itself collides in 16 bits.
+        if (idxs.length === 1)
+            anchorToIndex.set(h, idxs[0]);
+        else
+            ambiguous.add(h);
+    }
+    return { rendered: renderWithAnchors(file), anchorToIndex, ambiguous, lines };
+}
+/**
+ * True when the line at `index` (0-based) still hashes to `hash`. Out-of-range
+ * indices return false. This is the staleness gate the edit tool uses.
+ */
+export function verifyAnchor(lines, index, hash) {
+    if (index < 0 || index >= lines.length)
+        return false;
+    return lineHash(lines[index], index) === hash;
+}
+/**
+ * Resolve an anchor against the current file lines (0-based). Rejects the edit
+ * if either endpoint is out of range, the range is reversed, or either hash no
+ * longer matches — the corruption-avoidance property.
+ */
+export function resolveAnchoredEdit(lines, anchor) {
+    const startIndex = anchor.start_line - 1;
+    const endIndex = anchor.end_line - 1;
+    if (startIndex < 0 || endIndex < 0 || startIndex >= lines.length || endIndex >= lines.length) {
+        return { ok: false, reason: "out_of_range" };
+    }
+    if (startIndex > endIndex) {
+        return { ok: false, reason: "reversed" };
+    }
+    if (!verifyAnchor(lines, startIndex, anchor.start_hash) ||
+        !verifyAnchor(lines, endIndex, anchor.end_hash)) {
+        return { ok: false, reason: "hash_mismatch" };
+    }
+    return { ok: true, startIndex, endIndex };
+}
+//# sourceMappingURL=hashline.js.map

package/dist/core/hashline.js.map

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

package/dist/core/semantic-search-benchmark.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Semantic AST-chunk retrieval vs whole-file reads — real-API measurement of
+ * whether Feature #3 is worth building.
+ *
+ * The claim (cocoindex-code / oh-my-pi): replacing "grep then read whole files"
+ * with "retrieve only the relevant AST chunks" cuts ~70% of the tokens an agent
+ * spends locating code, with no loss of answer quality. We test that directly on
+ * OUR OWN repo against a live model.
+ *
+ * For a set of natural-language questions about real files in this repo, we build
+ * three context strategies and ask the model the same question with each:
+ *
+ *   BASELINE (whole-file): deliver the FULL text of the top files a lexical
+ *   grep would surface — this is what the agent reads today (read + grep).
+ *
+ *   SEMANTIC (AST chunks): parse every file into top-level declarations
+ *   (functions / classes / interfaces / consts), rank chunks with a real BM25
+ *   retriever, and deliver only the top-k chunks. No embedding model needed; a
+ *   learned embedding retriever would land between BM25 and ORACLE.
+ *
+ *   ORACLE (upper bound): deliver only the hand-labelled answer chunk(s) — the
+ *   best case any retriever could achieve.
+ *
+ * We measure, per question and strategy: INPUT tokens delivered (the headline
+ * cost) and whether the model's answer was correct (deterministic keyword grade).
+ * The verdict: does SEMANTIC reach BASELINE-level correctness at a fraction of
+ * the input tokens?
+ *
+ * Usage:
+ *   npx tsx src/core/semantic-search-benchmark.ts
+ *
+ * Env overrides:
+ *   GG_SS_PROVIDER / GG_SS_MODEL   (default openai / gpt-5.5)
+ *   GG_SS_TOPK                     (chunks/files delivered, default 3)
+ */
+export declare function grade(answer: string, mustInclude: string[]): boolean;
+//# sourceMappingURL=semantic-search-benchmark.d.ts.map

package/dist/core/semantic-search-benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-search-benchmark.d.ts","sourceRoot":"","sources":["../../src/core/semantic-search-benchmark.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAwHH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAGpE"}

package/dist/core/semantic-search-benchmark.js

@@ -0,0 +1,211 @@
+/**
+ * Semantic AST-chunk retrieval vs whole-file reads — real-API measurement of
+ * whether Feature #3 is worth building.
+ *
+ * The claim (cocoindex-code / oh-my-pi): replacing "grep then read whole files"
+ * with "retrieve only the relevant AST chunks" cuts ~70% of the tokens an agent
+ * spends locating code, with no loss of answer quality. We test that directly on
+ * OUR OWN repo against a live model.
+ *
+ * For a set of natural-language questions about real files in this repo, we build
+ * three context strategies and ask the model the same question with each:
+ *
+ *   BASELINE (whole-file): deliver the FULL text of the top files a lexical
+ *   grep would surface — this is what the agent reads today (read + grep).
+ *
+ *   SEMANTIC (AST chunks): parse every file into top-level declarations
+ *   (functions / classes / interfaces / consts), rank chunks with a real BM25
+ *   retriever, and deliver only the top-k chunks. No embedding model needed; a
+ *   learned embedding retriever would land between BM25 and ORACLE.
+ *
+ *   ORACLE (upper bound): deliver only the hand-labelled answer chunk(s) — the
+ *   best case any retriever could achieve.
+ *
+ * We measure, per question and strategy: INPUT tokens delivered (the headline
+ * cost) and whether the model's answer was correct (deterministic keyword grade).
+ * The verdict: does SEMANTIC reach BASELINE-level correctness at a fraction of
+ * the input tokens?
+ *
+ * Usage:
+ *   npx tsx src/core/semantic-search-benchmark.ts
+ *
+ * Env overrides:
+ *   GG_SS_PROVIDER / GG_SS_MODEL   (default openai / gpt-5.5)
+ *   GG_SS_TOPK                     (chunks/files delivered, default 3)
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { stream } from "@kenkaiiii/gg-ai";
+import { AuthStorage } from "./auth-storage.js";
+import { chunkFile, bm25Rank, rankFiles } from "./code-retrieval.js";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.resolve(HERE, ".."); // packages/ggcoder/src
+const QUESTIONS = [
+    {
+        q: "Which method resolves provider credentials and auto-refreshes expired OAuth tokens, and what happens if it is not logged in?",
+        files: ["core/auth-storage.ts", "core/loop-breaker.ts", "tools/edit-diff.ts"],
+        oracle: { file: "core/auth-storage.ts", symbol: "resolveCredentials" },
+        mustInclude: ["resolvecredentials", "refresh"],
+    },
+    {
+        q: "What function performs fuzzy text matching for the edit tool, and how does it tolerate indentation drift?",
+        files: ["tools/edit-diff.ts", "core/auth-storage.ts", "core/checkpoint-store.ts"],
+        oracle: { file: "tools/edit-diff.ts", symbol: "fuzzyFindText" },
+        mustInclude: ["fuzzyfindtext", "indent"],
+    },
+    {
+        q: "What restore modes does the checkpoint / rewind system support?",
+        files: ["core/checkpoint-store.ts", "core/loop-breaker.ts", "tools/edit-diff.ts"],
+        oracle: { file: "core/checkpoint-store.ts", symbol: "RestoreMode" },
+        mustInclude: ["code", "conversation", "both"],
+    },
+];
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function ask(provider, model, c, context, question) {
+    const messages = [
+        {
+            role: "system",
+            content: "You answer questions about a codebase using ONLY the provided context. " +
+                "Be specific: name the exact functions/types involved. If the context is insufficient, say so. " +
+                "Answer in 1-3 sentences.",
+        },
+        { role: "user", content: `CONTEXT:\n${context}\n\nQUESTION: ${question}` },
+    ];
+    let lastErr;
+    for (let attempt = 0; attempt < 4; attempt++) {
+        try {
+            let text = "";
+            const result = stream({
+                provider: provider,
+                model,
+                messages,
+                maxTokens: 512,
+                apiKey: c.apiKey,
+                baseUrl: c.baseUrl,
+                accountId: c.accountId,
+            });
+            for await (const event of result) {
+                if (event.type === "text_delta")
+                    text += event.text;
+            }
+            const response = await result.response;
+            const content = response.message.content;
+            const finalText = typeof content === "string"
+                ? content
+                : content
+                    .filter((p) => p.type === "text")
+                    .map((p) => p.text ?? "")
+                    .join("");
+            return {
+                text: finalText || text,
+                inputTokens: response.usage.inputTokens,
+                outputTokens: response.usage.outputTokens,
+            };
+        }
+        catch (err) {
+            lastErr = err;
+            await sleep(2000 * (attempt + 1));
+        }
+    }
+    throw lastErr;
+}
+export function grade(answer, mustInclude) {
+    const a = answer.toLowerCase();
+    return mustInclude.every((t) => a.includes(t));
+}
+async function main() {
+    const provider = process.env.GG_SS_PROVIDER ?? "openai";
+    const model = process.env.GG_SS_MODEL ?? "gpt-5.5";
+    const topK = Math.max(1, parseInt(process.env.GG_SS_TOPK ?? "3", 10));
+    const auth = new AuthStorage();
+    await auth.load();
+    const cr = await auth.resolveCredentials(provider);
+    const creds = { apiKey: cr.accessToken, baseUrl: cr.baseUrl, accountId: cr.accountId };
+    console.log(`\n🔎 Semantic-search benchmark — ${provider}/${model} (top-${topK})\n`);
+    const rows = [];
+    for (const q of QUESTIONS) {
+        // Load the real corpus files; skip the question if any are missing/moved.
+        const files = new Map();
+        let missing = false;
+        for (const rel of q.files) {
+            const abs = path.join(SRC, rel);
+            if (!fs.existsSync(abs)) {
+                console.log(`   ⚠ skipping question — missing ${rel}`);
+                missing = true;
+                break;
+            }
+            files.set(rel, fs.readFileSync(abs, "utf-8"));
+        }
+        if (missing)
+            continue;
+        // BASELINE context: full text of the top-k files a grep would surface.
+        const baseFiles = rankFiles(q.q, files, topK);
+        const baseContext = baseFiles.map((f) => `// FILE: ${f}\n${files.get(f)}`).join("\n\n");
+        // SEMANTIC context: top-k AST chunks across all corpus files.
+        const allChunks = [...files].flatMap(([rel, src]) => chunkFile(rel, src));
+        const semChunks = bm25Rank(q.q, allChunks, topK);
+        const semContext = semChunks.map((c) => `// ${c.file} → ${c.symbol}\n${c.text}`).join("\n\n");
+        // ORACLE context: just the labelled answer chunk.
+        const oracleChunk = allChunks.find((c) => c.file === q.oracle.file && c.symbol === q.oracle.symbol);
+        const oracleContext = oracleChunk
+            ? `// ${oracleChunk.file} → ${oracleChunk.symbol}\n${oracleChunk.text}`
+            : semContext;
+        process.stdout.write(`▶ ${q.q.slice(0, 64)}…\n`);
+        await sleep(1200);
+        const base = await ask(provider, model, creds, baseContext, q.q);
+        await sleep(1200);
+        const sem = await ask(provider, model, creds, semContext, q.q);
+        await sleep(1200);
+        const oracle = await ask(provider, model, creds, oracleContext, q.q);
+        const row = {
+            q: q.q.slice(0, 40),
+            baseInTok: base.inputTokens,
+            baseOk: grade(base.text, q.mustInclude),
+            semInTok: sem.inputTokens,
+            semOk: grade(sem.text, q.mustInclude),
+            oracleInTok: oracle.inputTokens,
+            oracleOk: grade(oracle.text, q.mustInclude),
+        };
+        rows.push(row);
+        process.stdout.write(`   baseline ${row.baseInTok} in tok ${row.baseOk ? "OK" : "FAIL"} | ` +
+            `semantic ${row.semInTok} in tok ${row.semOk ? "OK" : "FAIL"} | ` +
+            `oracle ${row.oracleInTok} in tok ${row.oracleOk ? "OK" : "FAIL"}\n\n`);
+    }
+    if (rows.length === 0) {
+        console.log("No questions ran (corpus files not found).");
+        return;
+    }
+    // ── Report ──
+    console.log("══════════════════════ RESULTS ══════════════════════\n");
+    console.log("Question                                 | base in-tok | sem in-tok | oracle | ok b/s/o");
+    for (const r of rows) {
+        console.log(`${r.q.padEnd(40)} | ${String(r.baseInTok).padStart(11)} | ${String(r.semInTok).padStart(10)} | ` +
+            `${String(r.oracleInTok).padStart(6)} | ${r.baseOk ? "1" : "0"}/${r.semOk ? "1" : "0"}/${r.oracleOk ? "1" : "0"}`);
+    }
+    const sum = (f) => rows.reduce((s, r) => s + f(r), 0);
+    const baseIn = sum((r) => r.baseInTok);
+    const semIn = sum((r) => r.semInTok);
+    const oracleIn = sum((r) => r.oracleInTok);
+    console.log(`\nInput tokens to answer: baseline ${baseIn} | semantic ${semIn} ` +
+        `(${(((baseIn - semIn) / baseIn) * 100).toFixed(0)}% fewer) | oracle ${oracleIn} ` +
+        `(${(((baseIn - oracleIn) / baseIn) * 100).toFixed(0)}% fewer)`);
+    console.log(`Correctness: baseline ${rows.filter((r) => r.baseOk).length}/${rows.length} | ` +
+        `semantic ${rows.filter((r) => r.semOk).length}/${rows.length} | ` +
+        `oracle ${rows.filter((r) => r.oracleOk).length}/${rows.length}`);
+    console.log(`\nVerdict: worth building if SEMANTIC keeps correctness ≈ baseline while cutting input tokens. ` +
+        `cocoindex claims ~70% fewer; ORACLE shows the ceiling a better (embedding) retriever could reach.\n`);
+}
+// Run when executed directly (not when imported by tests).
+const isDirectRun = process.argv[1]?.endsWith("semantic-search-benchmark.ts") ||
+    process.argv[1]?.endsWith("semantic-search-benchmark.js") ||
+    process.argv[1]?.endsWith("semantic-search-benchmark");
+if (isDirectRun) {
+    main().catch((err) => {
+        console.error("Benchmark failed:", err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=semantic-search-benchmark.js.map

package/dist/core/semantic-search-benchmark.js.map

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

package/dist/core/semantic-search-benchmark.test.d.ts

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

package/dist/core/semantic-search-benchmark.test.d.ts.map

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

package/dist/core/semantic-search-benchmark.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import { chunkFile, tokenize, bm25Rank, rankFiles } from "./code-retrieval.js";
+import { grade } from "./semantic-search-benchmark.js";
+/**
+ * Deterministic tests for the retrieval half of the semantic-search benchmark.
+ * The token-saving claim is only meaningful if AST chunking, tokenization, BM25
+ * ranking, and the answer grader are correct. We test parsing across every node
+ * kind, full-body capture, camelCase splitting, ranking relevance, the top-k
+ * cap, and the grader's all-tokens-required strictness.
+ */
+const SAMPLE = `
+import { x } from "y";
+
+export interface Session { id: string; userId: string; }
+
+export type Mode = "code" | "conversation" | "both";
+
+export enum Color { Red, Green }
+
+const DEFAULT_TTL = 3000;
+
+/** Sign a session token with HMAC-SHA256. */
+export function signSessionToken(s: Session, secret: string): string {
+  return s.id + secret + "SIGNED_MARKER";
+}
+
+export class LruCache {
+  evictLeastRecentlyUsed(): void {}
+}
+`;
+describe("chunkFile (AST chunking)", () => {
+    const chunks = chunkFile("sample.ts", SAMPLE);
+    const symbols = chunks.map((c) => c.symbol);
+    it("1. extracts a top-level function declaration by name", () => {
+        expect(symbols).toContain("signSessionToken");
+    });
+    it("2. extracts class and interface declarations", () => {
+        expect(symbols).toContain("LruCache");
+        expect(symbols).toContain("Session");
+    });
+    it("3. extracts type alias, enum, and top-level const", () => {
+        expect(symbols).toContain("Mode");
+        expect(symbols).toContain("Color");
+        expect(symbols).toContain("DEFAULT_TTL");
+    });
+    it("4. captures the FULL body text of a chunk (not just the signature)", () => {
+        const fn = chunks.find((c) => c.symbol === "signSessionToken");
+        expect(fn.text).toContain("SIGNED_MARKER");
+        expect(fn.file).toBe("sample.ts");
+    });
+    it("5. ignores import statements (no spurious chunk)", () => {
+        expect(symbols).not.toContain("x");
+        expect(chunks.length).toBe(6); // Session, Mode, Color, DEFAULT_TTL, signSessionToken, LruCache
+    });
+});
+describe("tokenize", () => {
+    it("6. splits camelCase identifiers into separate terms", () => {
+        const toks = tokenize("resolveCredentials");
+        expect(toks).toContain("resolve");
+        expect(toks).toContain("credentials");
+    });
+    it("7. lowercases and splits on non-word boundaries (snake/punctuation)", () => {
+        const toks = tokenize("DEFAULT_TTL = signSessionToken()");
+        expect(toks).toEqual(expect.arrayContaining(["default", "ttl", "sign", "session", "token"]));
+        expect(toks.every((t) => t === t.toLowerCase())).toBe(true);
+    });
+});
+describe("bm25Rank + rankFiles (retrieval)", () => {
+    const chunks = chunkFile("sample.ts", SAMPLE);
+    it("8. ranks the chunk matching the query's terms first", () => {
+        const top = bm25Rank("how are session tokens signed", chunks, 1);
+        expect(top[0].symbol).toBe("signSessionToken");
+    });
+    it("9. never returns more than top-k chunks", () => {
+        expect(bm25Rank("session", chunks, 2).length).toBeLessThanOrEqual(2);
+        expect(bm25Rank("session", chunks, 100).length).toBe(chunks.length);
+    });
+    it("10. rankFiles surfaces the relevant file and grade requires ALL tokens", () => {
+        const files = new Map([
+            ["auth.ts", SAMPLE],
+            ["unrelated.ts", "export const pi = 3.14; // geometry helpers only"],
+        ]);
+        expect(rankFiles("sign a session token", files, 1)[0]).toBe("auth.ts");
+        // grade is strict: every required token must be present (case-insensitive).
+        expect(grade("It uses signSessionToken with refresh logic", ["signsessiontoken", "refresh"])).toBe(true);
+        expect(grade("It uses signSessionToken", ["signsessiontoken", "refresh"])).toBe(false);
+    });
+});
+//# sourceMappingURL=semantic-search-benchmark.test.js.map

package/dist/core/semantic-search-benchmark.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-search-benchmark.test.js","sourceRoot":"","sources":["../../src/core/semantic-search-benchmark.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAEvD;;;;;;GAMG;AAEH,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;CAmBd,CAAC;AAEF,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,MAAM,MAAM,GAAG,SAAS,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAE5C,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QACtC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACnC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oEAAoE,EAAE,GAAG,EAAE;QAC5E,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,kBAAkB,CAAE,CAAC;QAChE,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;QAC3C,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,gEAAgE;IACjG,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,IAAI,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qEAAqE,EAAE,GAAG,EAAE;QAC7E,MAAM,IAAI,GAAG,QAAQ,CAAC,kCAAkC,CAAC,CAAC;QAC1D,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAC7F,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAChD,MAAM,MAAM,GAAG,SAAS,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAE9C,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,GAAG,GAAG,QAAQ,CAAC,+BAA+B,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;QACrE,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAiB;YACpC,CAAC,SAAS,EAAE,MAAM,CAAC;YACnB,CAAC,cAAc,EAAE,kDAAkD,CAAC;SACrE,CAAC,CAAC;QACH,MAAM,CAAC,SAAS,CAAC,sBAAsB,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAEvE,4EAA4E;QAC5E,MAAM,CACJ,KAAK,CAAC,6CAA6C,EAAE,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC,CACtF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/core/steering.d.ts

@@ -0,0 +1,25 @@
+import type { TextContent, ImageContent, VideoContent } from "@kenkaiiii/gg-ai";
+type ContentPart = TextContent | ImageContent | VideoContent;
+type UserContent = string | ContentPart[];
+/**
+ * Framing prepended to a mid-run steering message (a prompt the user submitted
+ * while the agent was already working).
+ *
+ * Without this wrapper the queued text arrives as a bare top-level user turn,
+ * identical to a brand-new request — so models treat it as the authoritative
+ * instruction and silently abandon the original task. The wrapper names the
+ * relationship (a second, concurrent instruction) and the one rule that kills
+ * the failure mode: don't drop either side. The model already knows how to
+ * merge two live instructions once it knows both are in force.
+ */
+export declare const STEERING_PREFIX: string;
+/** Wrap a plain-text steering message with the framing prefix. */
+export declare function wrapSteeringText(text: string): string;
+/**
+ * Wrap a steering `UserContent` (string or multimodal parts) with the framing
+ * prefix. Media blocks pass through untouched; the prefix is prepended to the
+ * leading text so attachments still ride the same native-block path.
+ */
+export declare function wrapSteeringContent(content: UserContent): UserContent;
+export {};
+//# sourceMappingURL=steering.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"steering.d.ts","sourceRoot":"","sources":["../../src/core/steering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhF,KAAK,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;AAC7D,KAAK,WAAW,GAAG,MAAM,GAAG,WAAW,EAAE,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,QAGd,CAAC;AAEf,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAGrE"}

package/dist/core/steering.js

@@ -0,0 +1,29 @@
+/**
+ * Framing prepended to a mid-run steering message (a prompt the user submitted
+ * while the agent was already working).
+ *
+ * Without this wrapper the queued text arrives as a bare top-level user turn,
+ * identical to a brand-new request — so models treat it as the authoritative
+ * instruction and silently abandon the original task. The wrapper names the
+ * relationship (a second, concurrent instruction) and the one rule that kills
+ * the failure mode: don't drop either side. The model already knows how to
+ * merge two live instructions once it knows both are in force.
+ */
+export const STEERING_PREFIX = "[The user added this while you were working — fold it into the current " +
+    "task, adjusting or extending as needed. Don't drop your original work or " +
+    "this.]\n\n";
+/** Wrap a plain-text steering message with the framing prefix. */
+export function wrapSteeringText(text) {
+    return STEERING_PREFIX + text;
+}
+/**
+ * Wrap a steering `UserContent` (string or multimodal parts) with the framing
+ * prefix. Media blocks pass through untouched; the prefix is prepended to the
+ * leading text so attachments still ride the same native-block path.
+ */
+export function wrapSteeringContent(content) {
+    if (typeof content === "string")
+        return wrapSteeringText(content);
+    return [{ type: "text", text: STEERING_PREFIX }, ...content];
+}
+//# sourceMappingURL=steering.js.map

package/dist/core/steering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steering.js","sourceRoot":"","sources":["../../src/core/steering.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,yEAAyE;IACzE,2EAA2E;IAC3E,YAAY,CAAC;AAEf,kEAAkE;AAClE,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,eAAe,GAAG,IAAI,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAoB;IACtD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAClE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAiB,EAAE,GAAG,OAAO,CAAC,CAAC;AAC9E,CAAC"}

package/dist/tools/edit.d.ts

@@ -11,6 +11,12 @@ declare const EditParams: z.ZodObject<{
         old_text: z.ZodString;
         new_text: z.ZodString;
         replace_all: z.ZodOptional<z.ZodBoolean>;
+        anchor: z.ZodOptional<z.ZodObject<{
+            start_line: z.ZodNumber;
+            start_hash: z.ZodString;
+            end_line: z.ZodNumber;
+            end_hash: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>>>;
     atomic: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;

package/dist/tools/edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/tools/edit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAYrD,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG/E,KAAK,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnE,uGAAuG;AACvG,KAAK,mBAAmB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAuClF,QAAA,MAAM,UAAU;;;;;;;;iBAgBd,CAAC;AAsDH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,WAAW,EACvB,GAAG,GAAE,cAAgC,EACrC,0BAA0B,CAAC,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,gBAAgB,EACpE,aAAa,CAAC,EAAE,gBAAgB,EAChC,iBAAiB,CAAC,EAAE,gBAAgB,EACpC,cAAc,CAAC,EAAE,mBAAmB,GACnC,SAAS,CAAC,OAAO,UAAU,CAAC,CAgP9B"}
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/tools/edit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAYrD,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAI/E,KAAK,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnE,uGAAuG;AACvG,KAAK,mBAAmB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAqDlF,QAAA,MAAM,UAAU;;;;;;;;;;;;;;iBAgBd,CAAC;AAuDH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,WAAW,EACvB,GAAG,GAAE,cAAgC,EACrC,0BAA0B,CAAC,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,gBAAgB,EACpE,aAAa,CAAC,EAAE,gBAAgB,EAChC,iBAAiB,CAAC,EAAE,gBAAgB,EACpC,cAAc,CAAC,EAAE,mBAAmB,GACnC,SAAS,CAAC,OAAO,UAAU,CAAC,CAsQ9B"}

package/dist/tools/edit.js

@@ -4,6 +4,7 @@ import { resolvePath, rejectSymlink } from "./path-utils.js";
 import { fuzzyFindText, countOccurrences, generateDiff, findClosestSnippet, findOccurrenceLines, stripBlankEdges, applyDotdotdots, applyMissingLeadingWhitespace, } from "./edit-diff.js";
 import { localOperations } from "./operations.js";
 import { assertFresh, recordWrite } from "./read-tracker.js";
+import { resolveAnchoredEdit } from "../core/hashline.js";
 import { isPlanModeActive, planModeRestriction } from "../core/runtime-mode.js";
 function isMutationCallback(value) {
     return typeof value === "function";
@@ -13,6 +14,14 @@ function isPlanModeRef(value) {
         value !== null &&
         typeof value.current === "boolean");
 }
+const EditAnchorSchema = z.object({
+    start_line: z.number().int().min(1).describe("1-based line number of the first edited line"),
+    start_hash: z
+        .string()
+        .describe("Content anchor of the first line (from a read with anchors:true)"),
+    end_line: z.number().int().min(1).describe("1-based line number of the last edited line"),
+    end_hash: z.string().describe("Content anchor of the last line"),
+});
 const EditItem = z.object({
     old_text: z.string().describe("The exact text to find and replace"),
     new_text: z.string().describe("The replacement text"),
@@ -21,6 +30,9 @@ const EditItem = z.object({
         .optional()
         .describe("Replace every occurrence of old_text instead of requiring a unique match. " +
         "Use for renames or repeated tokens. Defaults to false."),
+    anchor: EditAnchorSchema.optional().describe("Optional staleness guard. When set (using line+hash anchors from a read with anchors:true), " +
+        "the edit is rejected if the file changed since you read it. old_text/new_text still drive the " +
+        "actual replacement."),
 });
 // Some models (Opus 4.6, GLM-5.1) occasionally send `edits` as a JSON string
 // instead of a real array, which trips Zod and makes the model fall back to
@@ -91,7 +103,9 @@ export function createEditTool(cwd, readFiles, ops = localOperations, planModeRe
             "Each old_text should identify one location — include surrounding context; set replace_all: true only for deliberate global replacements/renames. " +
             "The matcher tolerates safe whitespace/quote/dash drift, but do not paraphrase. For long blocks, a line containing only `...` in BOTH old_text and new_text elides a middle preserved verbatim. " +
             "Partial-apply by default: failed edits are listed for retry, successful ones are still written — " +
-            "re-issue ONLY the listed failures, not the whole batch. Returns a unified diff.",
+            "re-issue ONLY the listed failures, not the whole batch. " +
+            "Optionally pin an edit with `anchor` (line+hash from a read with anchors:true) to reject it if the file changed since you read it. " +
+            "Returns a unified diff.",
         parameters: EditParams,
         executionMode: "sequential",
         async execute({ file_path, edits, atomic = false }) {
@@ -105,10 +119,25 @@ export function createEditTool(cwd, readFiles, ops = localOperations, planModeRe
             const hasCRLF = original.includes("\r\n");
             const originalNormalized = hasCRLF ? original.replace(/\r\n/g, "\n") : original;
             let working = originalNormalized;
+            // Anchors pin lines in the file AS READ, so they always verify against the
+            // original (pre-edit) line array — earlier edits in the batch don't shift
+            // what an anchor refers to.
+            const originalLines = originalNormalized.split("\n");
             const fileName = path.basename(resolved);
             const outcomes = new Array(edits.length);
             for (let i = 0; i < edits.length; i++) {
-                const { old_text, new_text, replace_all } = edits[i];
+                const { old_text, new_text, replace_all, anchor } = edits[i];
+                // Optional staleness guard (opt-in). Runs BEFORE the fuzzy match ladder:
+                // if the model supplied an anchor and the file drifted since it read it,
+                // reject this edit instead of risking a misplaced fuzzy match. The fuzzy
+                // path below is byte-identical to today when `anchor` is absent.
+                if (anchor) {
+                    const res = resolveAnchoredEdit(originalLines, anchor);
+                    if (!res.ok) {
+                        outcomes[i] = { ok: false, failure: { reason: "stale_anchor" } };
+                        continue;
+                    }
+                }
                 const normalizedOld = hasCRLF ? old_text.replace(/\r\n/g, "\n") : old_text;
                 const normalizedNew = hasCRLF ? new_text.replace(/\r\n/g, "\n") : new_text;
                 const replaceAll = replace_all ?? false;
@@ -197,6 +226,9 @@ export function createEditTool(cwd, readFiles, ops = localOperations, planModeRe
             // and the snippet is its only guidance — keep it.
             const willPersistSuccesses = successCount > 0 && !atomic;
             const formatFailureMessage = (f) => {
+                if (f.reason === "stale_anchor") {
+                    return `the file changed since you read it (anchor mismatch) — re-read \`${file_path}\` and retry`;
+                }
                 if (f.reason === "noop") {
                     return `old_text and new_text are identical in ${fileName} — this edit would be a no-op. Either fix new_text or drop this edit.`;
                 }