@builder.io/ai-utils 0.56.0 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/codegen.d.ts

@@ -742,6 +742,7 @@ export interface SpawnBranchToolInput {
     model?: "auto" | "opus" | "sonnet" | "haiku";
     attachment_urls?: string[];
     git_base_branch?: string;
+    auto_archive_on_idle?: boolean;
 }
 export interface CreateProjectToolInput {
     repo_url: string;
@@ -768,6 +769,12 @@ export interface PRReviewComment {
     file_path: string;
     line: number;
     start_line?: number;
+    /**
+     * Diff side. RIGHT (default) = NEW file (added/context). LEFT = OLD file
+     * (removed/context). Use LEFT only when commenting on deleted code with
+     * no semantically related new-side anchor.
+     */
+    side?: "LEFT" | "RIGHT";
     title: string;
     body: string;
     severity: ReviewSeverity;
@@ -862,6 +869,11 @@ export interface CodeGenToolMap {
     EscalateToPlanner: EscalateToPlanner;
     PullPrototype: PullPrototypeToolInput;
     ConnectMCP: ConnectMCPToolInput;
+    EnsurePR: EnsurePRToolInput;
+}
+export interface EnsurePRToolInput {
+    project_id: string;
+    branch_name: string;
 }
 export interface EscalateToPlanner {
     /** What's blocking execution */
@@ -949,7 +961,7 @@ export declare const DEFAULT_QUEUE_BEHAVIOR: QueueBehavior;
 /** True for any schedule that aborts the in-flight run on enqueue. */
 export declare function isInterruptSchedule(schedule: QueueSchedule): boolean;
 export declare function normalizeQueueMode(mode: QueueMode | undefined): QueueBehavior;
-export declare const BASE_CODEGEN_POSITIONS: readonly ["fusion", "editor-ai", "repo-indexing", "cli", "create-app-firebase", "create-app-lovable", "builder-code-panel", "setup-project", "code-review-orchestrator", "project-configuration", "org-agent", "browser-testing", "projects-scheduler-memory-extraction", "builder-code", "unknown", "dsi-mcp"];
+export declare const BASE_CODEGEN_POSITIONS: readonly ["fusion", "editor-ai", "repo-indexing", "cli", "create-app-firebase", "create-app-lovable", "builder-code-panel", "setup-project", "code-review-orchestrator", "project-configuration", "org-agent", "org-worker", "browser-testing", "projects-scheduler-memory-extraction", "builder-code", "unknown", "dsi-mcp"];
 export type BaseCodeGenPosition = (typeof BASE_CODEGEN_POSITIONS)[number];
 export type CodeGenPosition = BaseCodeGenPosition | `${BaseCodeGenPosition}-agent`;
 export interface RepoIndexingConfig {
@@ -995,7 +1007,7 @@ export interface CodeGenInputOptions {
     redactUserMessages?: boolean;
     redactLLMMessages?: boolean;
     environmentVariables?: EnvironmentVariable[];
-    dirtyEnvironmentVariables?: boolean;
+    skipCommandSecurity?: boolean;
     builderContent?: BuilderContent;
     framework?: CodeGenFramework;
     styleLibrary?: CodeGenStyleLibrary;

package/src/codegen.js

@@ -38,6 +38,7 @@ export const BASE_CODEGEN_POSITIONS = [
     "code-review-orchestrator",
     "project-configuration",
     "org-agent",
+    "org-worker",
     "browser-testing",
     "projects-scheduler-memory-extraction",
     "builder-code",

package/src/diff-hunks.d.ts

@@ -0,0 +1,47 @@
+import type { PRReviewComment } from "./codegen.js";
+export interface NewSideLine {
+    line: number;
+    content: string;
+}
+export interface HunkRange {
+    oldStart: number;
+    oldEnd: number;
+    newStart: number;
+    newEnd: number;
+    /**
+     * RIGHT-side commentable lines: added (`+`) and context lines, indexed by
+     * the new-file line number.
+     */
+    newSideLines: NewSideLine[];
+    /**
+     * LEFT-side commentable lines: removed (`-`) and context lines, indexed by
+     * the old-file line number.
+     */
+    oldSideLines: NewSideLine[];
+}
+export type FileHunkInfo = {
+    kind: "binary";
+} | {
+    kind: "deleted";
+    oldLineCount: number;
+} | {
+    kind: "renamed-only";
+} | {
+    kind: "new";
+    lineCount: number;
+} | {
+    kind: "modified";
+    hunks: HunkRange[];
+};
+export interface InvalidComment {
+    comment: PRReviewComment;
+    reason: string;
+    validRanges?: string;
+    /** Concrete commentable lines (with content) on the relevant side. */
+    validLines?: NewSideLine[];
+}
+export declare function parseDiffHunks(diff: string): Map<string, FileHunkInfo>;
+export declare function validateCommentPositions(comments: PRReviewComment[], hunks: Map<string, FileHunkInfo>): {
+    valid: PRReviewComment[];
+    invalid: InvalidComment[];
+};

package/src/diff-hunks.js

@@ -0,0 +1,269 @@
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+export function parseDiffHunks(diff) {
+    const map = new Map();
+    if (!diff)
+        return map;
+    const lines = diff.split("\n");
+    let path = null;
+    let info = null;
+    let currentHunk = null;
+    let nextNew = 0;
+    let nextOld = 0;
+    const flush = () => {
+        if (path && info)
+            map.set(path, info);
+    };
+    for (const line of lines) {
+        if (line.startsWith("diff --git ")) {
+            flush();
+            const match = line.match(/ b\/(.+)$/);
+            path = match ? match[1] : null;
+            info = { kind: "modified", hunks: [] };
+            currentHunk = null;
+            continue;
+        }
+        if (line.startsWith("new file mode")) {
+            info = { kind: "new", lineCount: 0 };
+            currentHunk = null;
+            continue;
+        }
+        if (line.startsWith("deleted file mode")) {
+            info = { kind: "deleted", oldLineCount: 0 };
+            currentHunk = null;
+            continue;
+        }
+        if (line.startsWith("Binary files ")) {
+            info = { kind: "binary" };
+            currentHunk = null;
+            continue;
+        }
+        if (line.startsWith("similarity index ") &&
+            (info === null || info === void 0 ? void 0 : info.kind) === "modified" &&
+            info.hunks.length === 0) {
+            info = { kind: "renamed-only" };
+            continue;
+        }
+        if (line.startsWith("@@")) {
+            const m = line.match(HUNK_HEADER);
+            if (!m)
+                continue;
+            const oldStart = Number(m[1]);
+            const oldCount = m[2] !== undefined ? Number(m[2]) : 1;
+            const newStart = Number(m[3]);
+            const newCount = m[4] !== undefined ? Number(m[4]) : 1;
+            if ((info === null || info === void 0 ? void 0 : info.kind) === "new") {
+                const end = newStart + newCount - 1;
+                if (end > info.lineCount)
+                    info.lineCount = end;
+                currentHunk = null;
+                continue;
+            }
+            if ((info === null || info === void 0 ? void 0 : info.kind) === "deleted") {
+                const end = oldStart + oldCount - 1;
+                if (end > info.oldLineCount)
+                    info.oldLineCount = end;
+                currentHunk = null;
+                continue;
+            }
+            // A renamed-only file with hunks is actually a rename + edit.
+            if ((info === null || info === void 0 ? void 0 : info.kind) === "renamed-only") {
+                info = { kind: "modified", hunks: [] };
+            }
+            if ((info === null || info === void 0 ? void 0 : info.kind) === "modified") {
+                // Don't coerce zero-count sides into a 1-line range — a hunk like
+                // `@@ -10,3 +11,0 @@` has zero new-side lines and must not accept a
+                // RIGHT comment at line 11. Using count directly makes the range
+                // empty (newEnd < newStart) when count is 0.
+                currentHunk = {
+                    oldStart,
+                    oldEnd: oldStart + oldCount - 1,
+                    newStart,
+                    newEnd: newStart + newCount - 1,
+                    newSideLines: [],
+                    oldSideLines: [],
+                };
+                info.hunks.push(currentHunk);
+                nextNew = newStart;
+                nextOld = oldStart;
+            }
+            continue;
+        }
+        // Inside a hunk: capture per-line content for both sides.
+        if (currentHunk && (info === null || info === void 0 ? void 0 : info.kind) === "modified") {
+            if (line.startsWith("+")) {
+                currentHunk.newSideLines.push({
+                    line: nextNew,
+                    content: line.slice(1),
+                });
+                nextNew++;
+            }
+            else if (line.startsWith("-")) {
+                currentHunk.oldSideLines.push({
+                    line: nextOld,
+                    content: line.slice(1),
+                });
+                nextOld++;
+            }
+            else if (line.startsWith("\\")) {
+                // "" marker — skip.
+            }
+            else {
+                // Context line — present on both sides at separate numbers.
+                const content = line.startsWith(" ") ? line.slice(1) : line;
+                currentHunk.newSideLines.push({ line: nextNew, content });
+                currentHunk.oldSideLines.push({ line: nextOld, content });
+                nextNew++;
+                nextOld++;
+            }
+        }
+    }
+    flush();
+    return map;
+}
+export function validateCommentPositions(comments, hunks) {
+    var _a;
+    const valid = [];
+    const invalid = [];
+    for (const comment of comments) {
+        const info = hunks.get(comment.file_path);
+        const side = (_a = comment.side) !== null && _a !== void 0 ? _a : "RIGHT";
+        if (!info) {
+            const files = [...hunks.keys()];
+            const sample = files.slice(0, 10).join(", ");
+            const suffix = files.length > 10 ? `, … (+${files.length - 10} more)` : "";
+            invalid.push({
+                comment,
+                reason: `file is not in the PR diff. Files in diff: ${sample}${suffix}`,
+            });
+            continue;
+        }
+        if (info.kind === "binary" || info.kind === "renamed-only") {
+            invalid.push({
+                comment,
+                reason: `file is ${info.kind}; no inline comments possible`,
+            });
+            continue;
+        }
+        // GitHub requires start_line < line for multi-line comments. Reject only
+        // start_line > line — start_line === line is harmless (utils.ts:1114 drops
+        // the redundant start_line and GitHub accepts it as a single-line comment).
+        if (comment.start_line !== undefined && comment.start_line > comment.line) {
+            invalid.push({
+                comment,
+                reason: `start_line ${comment.start_line} must be less than line ${comment.line} for multi-line comments`,
+            });
+            continue;
+        }
+        // RIGHT-side validation
+        if (side === "RIGHT") {
+            if (info.kind === "deleted") {
+                invalid.push({
+                    comment,
+                    reason: "file is deleted; use side: 'LEFT' to comment on the old version",
+                });
+                continue;
+            }
+            if (info.kind === "new") {
+                if (comment.line < 1 || comment.line > info.lineCount) {
+                    invalid.push({
+                        comment,
+                        reason: `line ${comment.line} outside new file (lines 1–${info.lineCount})`,
+                    });
+                    continue;
+                }
+                if (comment.start_line !== undefined &&
+                    (comment.start_line < 1 || comment.start_line > info.lineCount)) {
+                    invalid.push({
+                        comment,
+                        reason: `start_line ${comment.start_line} outside new file (lines 1–${info.lineCount})`,
+                    });
+                    continue;
+                }
+                valid.push(comment);
+                continue;
+            }
+            // modified, RIGHT
+            const hunk = info.hunks.find((h) => comment.line >= h.newStart && comment.line <= h.newEnd);
+            if (!hunk) {
+                invalid.push({
+                    comment,
+                    reason: `line ${comment.line} is not inside any hunk on the new side`,
+                    // Skip hunks with empty new side (e.g. `+11,0`) — `newEnd < newStart`
+                    // would render as nonsense like "11–10".
+                    validRanges: info.hunks
+                        .filter((h) => h.newEnd >= h.newStart)
+                        .map((h) => `${h.newStart}–${h.newEnd}`)
+                        .join(", "),
+                    validLines: info.hunks.flatMap((h) => h.newSideLines),
+                });
+                continue;
+            }
+            if (comment.start_line !== undefined &&
+                (comment.start_line < hunk.newStart || comment.start_line > hunk.newEnd)) {
+                invalid.push({
+                    comment,
+                    reason: `multi-line range ${comment.start_line}-${comment.line} crosses hunk boundary`,
+                    validRanges: `${hunk.newStart}–${hunk.newEnd}`,
+                    validLines: hunk.newSideLines,
+                });
+                continue;
+            }
+            valid.push(comment);
+            continue;
+        }
+        // LEFT-side validation
+        if (info.kind === "new") {
+            invalid.push({
+                comment,
+                reason: "file is newly added; LEFT side does not exist (use side: 'RIGHT')",
+            });
+            continue;
+        }
+        if (info.kind === "deleted") {
+            if (comment.line < 1 || comment.line > info.oldLineCount) {
+                invalid.push({
+                    comment,
+                    reason: `line ${comment.line} outside deleted file (lines 1–${info.oldLineCount})`,
+                });
+                continue;
+            }
+            if (comment.start_line !== undefined &&
+                (comment.start_line < 1 || comment.start_line > info.oldLineCount)) {
+                invalid.push({
+                    comment,
+                    reason: `start_line ${comment.start_line} outside deleted file (lines 1–${info.oldLineCount})`,
+                });
+                continue;
+            }
+            valid.push(comment);
+            continue;
+        }
+        // modified, LEFT
+        const hunk = info.hunks.find((h) => comment.line >= h.oldStart && comment.line <= h.oldEnd);
+        if (!hunk) {
+            invalid.push({
+                comment,
+                reason: `line ${comment.line} (LEFT) is not inside any hunk on the old side`,
+                // Skip hunks with empty old side (e.g. `-10,0`) — would render as "11–10".
+                validRanges: info.hunks
+                    .filter((h) => h.oldEnd >= h.oldStart)
+                    .map((h) => `${h.oldStart}–${h.oldEnd}`)
+                    .join(", "),
+                validLines: info.hunks.flatMap((h) => h.oldSideLines),
+            });
+            continue;
+        }
+        if (comment.start_line !== undefined &&
+            (comment.start_line < hunk.oldStart || comment.start_line > hunk.oldEnd)) {
+            invalid.push({
+                comment,
+                reason: `multi-line range ${comment.start_line}-${comment.line} crosses hunk boundary on LEFT side`,
+                validRanges: `${hunk.oldStart}–${hunk.oldEnd}`,
+                validLines: hunk.oldSideLines,
+            });
+            continue;
+        }
+        valid.push(comment);
+    }
+    return { valid, invalid };
+}

package/src/diff-hunks.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/diff-hunks.spec.js

@@ -0,0 +1,558 @@
+import { describe, it, expect } from "vitest";
+import { parseDiffHunks, validateCommentPositions } from "./diff-hunks.js";
+function comment(partial) {
+    return {
+        title: "x",
+        body: "y",
+        severity: "medium",
+        ...partial,
+    };
+}
+describe("parseDiffHunks", () => {
+    it("returns empty map for empty diff", () => {
+        expect(parseDiffHunks("").size).toBe(0);
+    });
+    it("parses a new file", () => {
+        const diff = [
+            "diff --git a/foo.ts b/foo.ts",
+            "new file mode 100644",
+            "index 0000000..1234567",
+            "--- /dev/null",
+            "+++ b/foo.ts",
+            "@@ -0,0 +1,42 @@",
+            "+line1",
+            "+line2",
+        ].join("\n");
+        const map = parseDiffHunks(diff);
+        expect(map.get("foo.ts")).toEqual({ kind: "new", lineCount: 42 });
+    });
+    it("parses a modified file with multiple hunks", () => {
+        const diff = [
+            "diff --git a/bar.ts b/bar.ts",
+            "index aaa..bbb 100644",
+            "--- a/bar.ts",
+            "+++ b/bar.ts",
+            "@@ -212,38 +212,90 @@ class Foo {",
+            " context line",
+            "+added",
+            "@@ -1024,7 +1093,7 @@ method() {",
+            " ctx",
+        ].join("\n");
+        const info = parseDiffHunks(diff).get("bar.ts");
+        expect(info === null || info === void 0 ? void 0 : info.kind).toBe("modified");
+        if ((info === null || info === void 0 ? void 0 : info.kind) !== "modified")
+            throw new Error("unreachable");
+        expect(info.hunks).toMatchObject([
+            { oldStart: 212, oldEnd: 249, newStart: 212, newEnd: 301 },
+            { oldStart: 1024, oldEnd: 1030, newStart: 1093, newEnd: 1099 },
+        ]);
+    });
+    it("treats omitted ,count as 1 in hunk header", () => {
+        const diff = [
+            "diff --git a/baz.ts b/baz.ts",
+            "--- a/baz.ts",
+            "+++ b/baz.ts",
+            "@@ -3 +5 @@",
+            " line",
+        ].join("\n");
+        const info = parseDiffHunks(diff).get("baz.ts");
+        expect(info === null || info === void 0 ? void 0 : info.kind).toBe("modified");
+        if ((info === null || info === void 0 ? void 0 : info.kind) !== "modified")
+            throw new Error("unreachable");
+        expect(info.hunks).toMatchObject([
+            { oldStart: 3, oldEnd: 3, newStart: 5, newEnd: 5 },
+        ]);
+    });
+    it("marks binary files", () => {
+        const diff = [
+            "diff --git a/img.png b/img.png",
+            "index aaa..bbb",
+            "Binary files a/img.png and b/img.png differ",
+        ].join("\n");
+        expect(parseDiffHunks(diff).get("img.png")).toEqual({ kind: "binary" });
+    });
+    it("marks deleted files", () => {
+        const diff = [
+            "diff --git a/old.ts b/old.ts",
+            "deleted file mode 100644",
+            "--- a/old.ts",
+            "+++ /dev/null",
+            "@@ -1,5 +0,0 @@",
+            "-removed",
+        ].join("\n");
+        expect(parseDiffHunks(diff).get("old.ts")).toEqual({
+            kind: "deleted",
+            oldLineCount: 5,
+        });
+    });
+    it("marks pure renames as renamed-only when there are no hunks", () => {
+        const diff = [
+            "diff --git a/from.ts b/to.ts",
+            "similarity index 100%",
+            "rename from from.ts",
+            "rename to to.ts",
+        ].join("\n");
+        expect(parseDiffHunks(diff).get("to.ts")).toEqual({ kind: "renamed-only" });
+    });
+    it("promotes rename + edits to modified when hunks appear", () => {
+        const diff = [
+            "diff --git a/from.ts b/to.ts",
+            "similarity index 90%",
+            "rename from from.ts",
+            "rename to to.ts",
+            "@@ -10,3 +10,4 @@",
+            "+added",
+        ].join("\n");
+        const info = parseDiffHunks(diff).get("to.ts");
+        expect(info === null || info === void 0 ? void 0 : info.kind).toBe("modified");
+        if ((info === null || info === void 0 ? void 0 : info.kind) !== "modified")
+            throw new Error("unreachable");
+        expect(info.hunks).toMatchObject([
+            { oldStart: 10, oldEnd: 12, newStart: 10, newEnd: 13 },
+        ]);
+    });
+    it("handles a multi-file diff", () => {
+        var _a;
+        const diff = [
+            "diff --git a/a.ts b/a.ts",
+            "new file mode 100644",
+            "@@ -0,0 +1,10 @@",
+            "+x",
+            "diff --git a/b.ts b/b.ts",
+            "--- a/b.ts",
+            "+++ b/b.ts",
+            "@@ -1,2 +1,3 @@",
+            "+y",
+        ].join("\n");
+        const map = parseDiffHunks(diff);
+        expect(map.size).toBe(2);
+        expect(map.get("a.ts")).toEqual({ kind: "new", lineCount: 10 });
+        expect((_a = map.get("b.ts")) === null || _a === void 0 ? void 0 : _a.kind).toBe("modified");
+    });
+});
+describe("validateCommentPositions", () => {
+    it("accepts in-range lines on a new file", () => {
+        const hunks = parseDiffHunks("diff --git a/new.ts b/new.ts\nnew file mode 100644\n@@ -0,0 +1,412 @@\n+x");
+        const { valid, invalid } = validateCommentPositions([
+            comment({ file_path: "new.ts", line: 1 }),
+            comment({ file_path: "new.ts", line: 412 }),
+        ], hunks);
+        expect(valid).toHaveLength(2);
+        expect(invalid).toHaveLength(0);
+    });
+    it("rejects out-of-range lines on a new file", () => {
+        const hunks = parseDiffHunks("diff --git a/new.ts b/new.ts\nnew file mode 100644\n@@ -0,0 +1,412 @@\n+x");
+        const { invalid } = validateCommentPositions([comment({ file_path: "new.ts", line: 413 })], hunks);
+        expect(invalid).toHaveLength(1);
+        expect(invalid[0].reason).toContain("outside new file (lines 1–412)");
+    });
+    it("rejects start_line outside new file range", () => {
+        const hunks = parseDiffHunks("diff --git a/new.ts b/new.ts\nnew file mode 100644\n@@ -0,0 +1,10 @@\n+x");
+        const { invalid } = validateCommentPositions([comment({ file_path: "new.ts", line: 5, start_line: 11 })], hunks);
+        expect(invalid).toHaveLength(1);
+        expect(invalid[0].reason).toContain("start_line");
+    });
+    it("rejects line outside any hunk on a modified file", () => {
+        const hunks = parseDiffHunks([
+            "diff --git a/m.ts b/m.ts",
+            "--- a/m.ts",
+            "+++ b/m.ts",
+            "@@ -212,38 +212,90 @@",
+            " ctx",
+            "@@ -1024,7 +1093,7 @@",
+            " ctx",
+        ].join("\n"));
+        const { invalid } = validateCommentPositions([comment({ file_path: "m.ts", line: 970 })], hunks);
+        expect(invalid).toHaveLength(1);
+        expect(invalid[0].reason).toContain("not inside any hunk");
+        expect(invalid[0].validRanges).toBe("212–301, 1093–1099");
+    });
+    it("returns concrete valid line content (not just ranges) so the LLM can pick a meaningful anchor", () => {
+        var _a;
+        // Mirrors the PR #255 case: a deletion-heavy hunk where the new-side has
+        // only punctuation. Content lets the LLM see "367: return {" and either
+        // pick a better line or drop to summary.
+        const hunks = parseDiffHunks([
+            "diff --git a/config.model.ts b/config.model.ts",
+            "--- a/config.model.ts",
+            "+++ b/config.model.ts",
+            "@@ -364,22 +362,6 @@",
+            "         self.aiApiEnv === 'production'",
+            "       );",
+            "     },",
+            "-    get fusionModeWithDefault(): string {",
+            "-      return 'quality-v3';",
+            "-    },",
+            "   }))",
+            "   .actions(self => {",
+            "     return {",
+        ].join("\n"));
+        const { invalid } = validateCommentPositions([comment({ file_path: "config.model.ts", line: 95 })], hunks);
+        expect(invalid).toHaveLength(1);
+        expect(invalid[0].validLines).toBeDefined();
+        const lines = invalid[0].validLines;
+        // Six new-side commentable lines (3 context before, 3 context after the deletion)
+        expect(lines.map((l) => l.line)).toEqual([362, 363, 364, 365, 366, 367]);
+        // The brace-line at 367 — exactly the wrong-anchor PR #255 hit
+        expect((_a = lines.find((l) => l.line === 367)) === null || _a === void 0 ? void 0 : _a.content).toContain("return {");
+    });
+    it("accepts a multi-line comment within one hunk", () => {
+        const hunks = parseDiffHunks([
+            "diff --git a/m.ts b/m.ts",
+            "--- a/m.ts",
+            "+++ b/m.ts",
+            "@@ -371,15 +327,80 @@",
+            " ctx",
+        ].join("\n"));
+        const { valid, invalid } = validateCommentPositions([comment({ file_path: "m.ts", line: 395, start_line: 330 })], hunks);
+        expect(valid).toHaveLength(1);
+        expect(invalid).toHaveLength(0);
+    });
+    it("rejects a multi-line comment that crosses hunk boundary", () => {
+        const hunks = parseDiffHunks([
+            "diff --git a/m.ts b/m.ts",
+            "--- a/m.ts",
+            "+++ b/m.ts",
+            "@@ -212,38 +212,90 @@",
+            " ctx",
+            "@@ -371,15 +327,80 @@",
+            " ctx",
+        ].join("\n"));
+        const { invalid } = validateCommentPositions([comment({ file_path: "m.ts", line: 395, start_line: 300 })], hunks);
+        expect(invalid).toHaveLength(1);
+        expect(invalid[0].reason).toContain("crosses hunk boundary");
+    });
+    it("rejects RIGHT comments on binary, deleted, and renamed-only files", () => {
+        const hunks = parseDiffHunks([
+            "diff --git a/img.png b/img.png",
+            "Binary files a/img.png and b/img.png differ",
+            "diff --git a/old.ts b/old.ts",
+            "deleted file mode 100644",
+            "@@ -1,1 +0,0 @@",
+            "-x",
+            "diff --git a/from.ts b/to.ts",
+            "similarity index 100%",
+            "rename from from.ts",
+            "rename to to.ts",
+        ].join("\n"));
+        const cs = [
+            comment({ file_path: "img.png", line: 1 }),
+            comment({ file_path: "old.ts", line: 1 }),
+            comment({ file_path: "to.ts", line: 1 }),
+        ];
+        const { invalid, valid } = validateCommentPositions(cs, hunks);
+        expect(valid).toHaveLength(0);
+        expect(invalid[0].reason).toContain("binary");
+        // Deleted file with RIGHT comment is told to switch to LEFT (file is gone)
+        expect(invalid[1].reason).toContain("deleted");
+        expect(invalid[1].reason).toContain("LEFT");
+        expect(invalid[2].reason).toContain("renamed-only");
+    });
+    it("rejects comments on files not present in the diff and lists the diff's files", () => {
+        const hunks = parseDiffHunks("diff --git a/exists.ts b/exists.ts\n--- a/exists.ts\n+++ b/exists.ts\n@@ -1,1 +1,1 @@\n x");
+        const { invalid } = validateCommentPositions([comment({ file_path: "missing.ts", line: 1 })], hunks);
+        expect(invalid).toHaveLength(1);
+        expect(invalid[0].reason).toContain("file is not in the PR diff");
+        expect(invalid[0].reason).toContain("exists.ts");
+    });
+    it("rejects everything when the diff is empty", () => {
+        const hunks = parseDiffHunks("");
+        const { invalid } = validateCommentPositions([comment({ file_path: "anything.ts", line: 1 })], hunks);
+        expect(invalid).toHaveLength(1);
+    });
+    // ──────────────────────────────────────────────────────────────────
+    // PR #517 replay: this is the decisive end-to-end signal.
+    // The comment array below is what the LLM submitted on the failing run.
+    // The fixture diff mirrors the real PR's hunk headers for the touched files.
+    // After this fix lands, validateCommentPositions must surface a precise,
+    // per-file error so the LLM corrects in one round-trip.
+    // ──────────────────────────────────────────────────────────────────
+    describe("PR #517 replay", () => {
+        const diff = [
+            // record.tsx — modified, hunks include +327,80 covering 327..406
+            "diff --git a/record.tsx b/record.tsx",
+            "--- a/record.tsx",
+            "+++ b/record.tsx",
+            "@@ -53,6 +53,13 @@",
+            " ctx",
+            "@@ -85,9 +92,9 @@",
+            " ctx",
+            "@@ -237,7 +244,7 @@",
+            " ctx",
+            "@@ -251,70 +258,17 @@",
+            " ctx",
+            "@@ -339,8 +293,10 @@",
+            " ctx",
+            "@@ -371,15 +327,80 @@",
+            " ctx",
+            "@@ -962,7 +983,12 @@",
+            " ctx",
+            // camera-visualizer.tsx — new file, 412 lines
+            "diff --git a/camera-visualizer.tsx b/camera-visualizer.tsx",
+            "new file mode 100644",
+            "@@ -0,0 +1,412 @@",
+            "+x",
+            // [...page].head.ts — modified, small file
+            "diff --git a/head.ts b/head.ts",
+            "--- a/head.ts",
+            "+++ b/head.ts",
+            "@@ -1,4 +1,5 @@",
+            " ctx",
+            "@@ -10,8 +11,17 @@",
+            " ctx",
+            // recorder-engine.ts — modified
+            "diff --git a/recorder-engine.ts b/recorder-engine.ts",
+            "--- a/recorder-engine.ts",
+            "+++ b/recorder-engine.ts",
+            "@@ -212,38 +212,90 @@",
+            " ctx",
+            "@@ -284,6 +336,21 @@",
+            " ctx",
+            "@@ -822,10 +889,12 @@",
+            " ctx",
+            "@@ -1024,7 +1093,7 @@",
+            " ctx",
+            // microphone-visualizer.tsx — new file, 496 lines
+            "diff --git a/microphone-visualizer.tsx b/microphone-visualizer.tsx",
+            "new file mode 100644",
+            "@@ -0,0 +1,496 @@",
+            "+x",
+        ].join("\n");
+        it("flags recorder-engine.ts:970 with the four valid hunk ranges", () => {
+            const hunks = parseDiffHunks(diff);
+            const { invalid } = validateCommentPositions([comment({ file_path: "recorder-engine.ts", line: 970 })], hunks);
+            expect(invalid).toHaveLength(1);
+            expect(invalid[0].validRanges).toBe("212–301, 336–356, 889–900, 1093–1099");
+        });
+        it("flags microphone-visualizer.tsx:1464 (file-offset confusion) with new-file bound", () => {
+            const hunks = parseDiffHunks(diff);
+            const { invalid } = validateCommentPositions([comment({ file_path: "microphone-visualizer.tsx", line: 1464 })], hunks);
+            expect(invalid).toHaveLength(1);
+            expect(invalid[0].reason).toContain("lines 1–496");
+        });
+        it("accepts record.tsx:330-395 (it really was valid; the batch died on others)", () => {
+            const hunks = parseDiffHunks(diff);
+            const { valid, invalid } = validateCommentPositions([comment({ file_path: "record.tsx", line: 395, start_line: 330 })], hunks);
+            expect(invalid).toHaveLength(0);
+            expect(valid).toHaveLength(1);
+        });
+        it("accepts camera-visualizer.tsx:205 (in-range new file)", () => {
+            const hunks = parseDiffHunks(diff);
+            const { valid } = validateCommentPositions([comment({ file_path: "camera-visualizer.tsx", line: 205 })], hunks);
+            expect(valid).toHaveLength(1);
+        });
+    });
+    // ──────────────────────────────────────────────────────────────────
+    // LEFT-side support — added in the LEFT/RIGHT plan. Validates the
+    // PR #255 case: comment on the deleted `fusionModeWithDefault` getter
+    // by passing { line: 367, side: "LEFT" }, which lands directly on the
+    // deletion (where cursor[bot] puts it).
+    // ──────────────────────────────────────────────────────────────────
+    describe("LEFT-side validation", () => {
+        it("accepts a LEFT comment on a removed line in a modified file", () => {
+            const hunks = parseDiffHunks([
+                "diff --git a/m.ts b/m.ts",
+                "--- a/m.ts",
+                "+++ b/m.ts",
+                "@@ -10,5 +10,2 @@",
+                " ctx-a",
+                "-removed-1",
+                "-removed-2",
+                "-removed-3",
+                " ctx-b",
+            ].join("\n"));
+            const { valid, invalid } = validateCommentPositions([comment({ file_path: "m.ts", line: 12, side: "LEFT" })], hunks);
+            expect(invalid).toHaveLength(0);
+            expect(valid).toHaveLength(1);
+        });
+        it("rejects a LEFT comment outside any hunk's old-side range, returning oldSideLines", () => {
+            var _a;
+            const hunks = parseDiffHunks([
+                "diff --git a/m.ts b/m.ts",
+                "--- a/m.ts",
+                "+++ b/m.ts",
+                "@@ -10,3 +10,3 @@",
+                " ctx",
+                "-removed",
+                " ctx",
+                "@@ -100,3 +100,3 @@",
+                " ctx",
+                "-removed-2",
+                " ctx",
+            ].join("\n"));
+            const { invalid } = validateCommentPositions([comment({ file_path: "m.ts", line: 50, side: "LEFT" })], hunks);
+            expect(invalid).toHaveLength(1);
+            expect(invalid[0].reason).toContain("LEFT");
+            expect(invalid[0].validRanges).toBe("10–12, 100–102");
+            expect(invalid[0].validLines).toBeDefined();
+            expect((_a = invalid[0].validLines.find((l) => l.line === 11)) === null || _a === void 0 ? void 0 : _a.content).toBe("removed");
+        });
+        it("rejects LEFT on a newly added file (no old side exists)", () => {
+            const hunks = parseDiffHunks([
+                "diff --git a/n.ts b/n.ts",
+                "new file mode 100644",
+                "@@ -0,0 +1,5 @@",
+                "+x",
+            ].join("\n"));
+            const { invalid } = validateCommentPositions([comment({ file_path: "n.ts", line: 1, side: "LEFT" })], hunks);
+            expect(invalid).toHaveLength(1);
+            expect(invalid[0].reason).toContain("RIGHT");
+        });
+        it("accepts LEFT in [1, oldLineCount] of a fully deleted file", () => {
+            const hunks = parseDiffHunks([
+                "diff --git a/old.ts b/old.ts",
+                "deleted file mode 100644",
+                "@@ -1,5 +0,0 @@",
+                "-a",
+                "-b",
+                "-c",
+                "-d",
+                "-e",
+            ].join("\n"));
+            const { valid: validIn } = validateCommentPositions([comment({ file_path: "old.ts", line: 3, side: "LEFT" })], hunks);
+            expect(validIn).toHaveLength(1);
+            const { invalid: outOfRange } = validateCommentPositions([comment({ file_path: "old.ts", line: 6, side: "LEFT" })], hunks);
+            expect(outOfRange).toHaveLength(1);
+            expect(outOfRange[0].reason).toContain("lines 1–5");
+        });
+        it("rejects start_line > line but accepts start_line === line (normalized to single-line)", () => {
+            const hunks = parseDiffHunks([
+                "diff --git a/m.ts b/m.ts",
+                "--- a/m.ts",
+                "+++ b/m.ts",
+                "@@ -10,5 +10,5 @@",
+                " ctx",
+                "+a",
+                "+b",
+                "+c",
+                " ctx",
+            ].join("\n"));
+            // start_line === line: formattedComments drops the redundant start_line
+            // and GitHub accepts it as a single-line comment. Pre-flight must not block.
+            const equal = validateCommentPositions([comment({ file_path: "m.ts", line: 12, start_line: 12 })], hunks);
+            expect(equal.invalid).toHaveLength(0);
+            expect(equal.valid).toHaveLength(1);
+            // start_line > line: real error, GitHub would reject. Pre-flight catches.
+            const inverted = validateCommentPositions([comment({ file_path: "m.ts", line: 11, start_line: 13 })], hunks);
+            expect(inverted.invalid).toHaveLength(1);
+            expect(inverted.invalid[0].reason).toContain("must be less than line");
+        });
+        it("validRanges omits empty-side hunks (e.g. +N,0) instead of rendering inverted '11–10'", () => {
+            const hunks = parseDiffHunks([
+                "diff --git a/m.ts b/m.ts",
+                "--- a/m.ts",
+                "+++ b/m.ts",
+                // Real (non-empty) hunk on the new side.
+                "@@ -1,3 +1,3 @@",
+                " ctx",
+                "+a",
+                " ctx",
+                // Empty new side — newCount = 0. validRanges must skip this.
+                "@@ -10,3 +11,0 @@",
+                "-a",
+                "-b",
+                "-c",
+            ].join("\n"));
+            // Submit RIGHT comment at line 50 (not in any hunk) — gets validRanges back.
+            const { invalid } = validateCommentPositions([comment({ file_path: "m.ts", line: 50 })], hunks);
+            expect(invalid).toHaveLength(1);
+            // Must NOT contain the inverted "11–10" range.
+            expect(invalid[0].validRanges).not.toContain("11–10");
+            // The valid new-side range from hunk #1 must still appear.
+            expect(invalid[0].validRanges).toContain("1–3");
+        });
+        it("rejects RIGHT comment in a zero-count-new-side hunk", () => {
+            // @@ -10,3 +11,0 @@ — 3 lines removed, 0 added on new side.
+            // Pre-fix: range was synthesized as 11–11 (Math.max(0,1)); now empty.
+            const hunks = parseDiffHunks([
+                "diff --git a/m.ts b/m.ts",
+                "--- a/m.ts",
+                "+++ b/m.ts",
+                "@@ -10,3 +11,0 @@",
+                "-a",
+                "-b",
+                "-c",
+            ].join("\n"));
+            const { invalid } = validateCommentPositions([comment({ file_path: "m.ts", line: 11 })], hunks);
+            expect(invalid).toHaveLength(1);
+            expect(invalid[0].reason).toContain("not inside any hunk");
+        });
+        it("accepts LEFT in a zero-count-new-side hunk (the removals are still LEFT-commentable)", () => {
+            const hunks = parseDiffHunks([
+                "diff --git a/m.ts b/m.ts",
+                "--- a/m.ts",
+                "+++ b/m.ts",
+                "@@ -10,3 +11,0 @@",
+                "-a",
+                "-b",
+                "-c",
+            ].join("\n"));
+            const { valid } = validateCommentPositions([comment({ file_path: "m.ts", line: 11, side: "LEFT" })], hunks);
+            expect(valid).toHaveLength(1);
+        });
+        it("rejects multi-line LEFT that crosses old-side hunk boundary", () => {
+            const hunks = parseDiffHunks([
+                "diff --git a/m.ts b/m.ts",
+                "--- a/m.ts",
+                "+++ b/m.ts",
+                "@@ -10,3 +10,3 @@",
+                " ctx",
+                "-r",
+                " ctx",
+                "@@ -100,3 +100,3 @@",
+                " ctx",
+                "-r2",
+                " ctx",
+            ].join("\n"));
+            const { invalid } = validateCommentPositions([
+                comment({
+                    file_path: "m.ts",
+                    line: 101,
+                    start_line: 11,
+                    side: "LEFT",
+                }),
+            ], hunks);
+            expect(invalid).toHaveLength(1);
+            expect(invalid[0].reason).toContain("crosses hunk boundary on LEFT");
+        });
+        // PR #255 replay: the decisive end-to-end signal.
+        // Removed `fusionModeWithDefault` getter at OLD line 367 — landing comment
+        // there is exactly what cursor[bot] does (and what we couldn't do before).
+        it("PR #255 replay: LEFT comment lands on the deleted getter", () => {
+            const hunks = parseDiffHunks([
+                "diff --git a/config.model.ts b/config.model.ts",
+                "--- a/config.model.ts",
+                "+++ b/config.model.ts",
+                "@@ -364,22 +362,6 @@",
+                "         self.aiApiEnv === 'production'",
+                "       );",
+                "     },",
+                "-    get fusionModeWithDefault(): string {",
+                "-      if (self.fusionCodegenMode) {",
+                "-        return self.fusionCodegenMode;",
+                "-      }",
+                "-      return 'quality-v3';",
+                "-    },",
+                "   }))",
+                "   .actions(self => {",
+                "     return {",
+            ].join("\n"));
+            const { valid, invalid } = validateCommentPositions([
+                comment({
+                    file_path: "config.model.ts",
+                    line: 367,
+                    side: "LEFT",
+                    title: "Removed getter",
+                }),
+            ], hunks);
+            expect(invalid).toHaveLength(0);
+            expect(valid).toHaveLength(1);
+            // Sanity-check: the parser actually captured the getter line at OLD 367.
+            const info = hunks.get("config.model.ts");
+            if ((info === null || info === void 0 ? void 0 : info.kind) !== "modified")
+                throw new Error("unreachable");
+            const lineAt367 = info.hunks[0].oldSideLines.find((l) => l.line === 367);
+            expect(lineAt367 === null || lineAt367 === void 0 ? void 0 : lineAt367.content).toContain("fusionModeWithDefault");
+        });
+    });
+});

package/src/events.d.ts

@@ -767,6 +767,16 @@ export declare const VideoRecordingCompletedV1: {
     eventName: "video.recording.completed";
     version: "1";
 };
+export type TimelineRecordingReadyV1 = FusionEventVariant<"timeline.recording.ready", {
+    recordingId: string;
+    explicitOnly?: boolean;
+}, {
+    recordingId: string;
+}, 1>;
+export declare const TimelineRecordingReadyV1: {
+    eventName: "timeline.recording.ready";
+    version: "1";
+};
 export interface SendMessageToOrgAgentInput {
     agentBranchName?: string;
     agentProjectId?: string;
@@ -860,7 +870,7 @@ export declare const ClientDevtoolsToolResultV1: {
     eventName: "client.devtools.tool.result";
     version: "1";
 };
-export type FusionEvent = ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | ClientDevtoolsToolCallRequestV1 | ClientDevtoolsToolCallV1 | ClientDevtoolsToolResultV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | GitPrMergedV1 | GitPrCreatedV1 | GitPrClosedV1 | ForceSetupAgentV1 | ClawMessageSentV1 | CodegenCompletionV1 | CodegenUserPromptV1 | GitWebhooksRegisterV1 | FusionProjectSettingsUpdatedV1 | VideoRecordingCompletedV1 | FusionBranchCreatedV1 | FusionContainerStartedV1 | FusionContainerFailedV1 | FusionBranchFailedV1 | BotMentionExternalPrV1 | ReviewSubmittedV1 | PrReviewRequestedV1;
+export type FusionEvent = ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | ClientDevtoolsToolCallRequestV1 | ClientDevtoolsToolCallV1 | ClientDevtoolsToolResultV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | GitPrMergedV1 | GitPrCreatedV1 | GitPrClosedV1 | ForceSetupAgentV1 | ClawMessageSentV1 | CodegenCompletionV1 | CodegenUserPromptV1 | GitWebhooksRegisterV1 | FusionProjectSettingsUpdatedV1 | VideoRecordingCompletedV1 | TimelineRecordingReadyV1 | FusionBranchCreatedV1 | FusionContainerStartedV1 | FusionContainerFailedV1 | FusionBranchFailedV1 | BotMentionExternalPrV1 | ReviewSubmittedV1 | PrReviewRequestedV1;
 export interface ModelPermissionRequiredEvent {
     type: "assistant.model.permission.required";
     data: {

package/src/events.js

@@ -78,6 +78,10 @@ export const VideoRecordingCompletedV1 = {
     eventName: "video.recording.completed",
     version: "1",
 };
+export const TimelineRecordingReadyV1 = {
+    eventName: "timeline.recording.ready",
+    version: "1",
+};
 export const PrReviewRequestedV1 = {
     eventName: "pr.review.requested",
     version: "1",

package/src/index.d.ts

@@ -4,6 +4,7 @@ export * from "./messages.js";
 export * from "./settings.js";
 export * from "./mapping.js";
 export * from "./codegen.js";
+export * from "./diff-hunks.js";
 export * from "./projects.js";
 export * from "./repo-indexing.js";
 export * from "./organization.js";

package/src/index.js

@@ -4,6 +4,7 @@ export * from "./messages.js";
 export * from "./settings.js";
 export * from "./mapping.js";
 export * from "./codegen.js";
+export * from "./diff-hunks.js";
 export * from "./projects.js";
 export * from "./repo-indexing.js";
 export * from "./organization.js";

package/src/projects.d.ts

@@ -385,6 +385,8 @@ export interface PartialBranchData {
      * record is fully created.
      */
     sessionId?: string;
+    /** When true, the branch will be automatically archived the first time it goes idle. */
+    autoArchiveOnIdle?: boolean;
 }
 export type EntityState = "active" | "deleted" | "archived";
 /**
@@ -491,6 +493,12 @@ export interface BranchSharedData {
     needsCleanup?: boolean;
     /** Reason provided when archiving the branch (optional, max 500 chars) */
     archiveReason?: string;
+    /** MIGRATION: accepts both string and number during migration period */
+    archivedAt?: InMigrationDateNullable;
+    /** User ID or "system" that archived the branch */
+    archivedBy?: string;
+    /** When true, the branch will be automatically archived the first time it goes idle. */
+    autoArchiveOnIdle?: boolean;
     /** @deprecated Use `state` field instead. Kept for backwards compatibility. */
     deleted?: boolean;
     /** MIGRATION: accepts both string and number during migration period */
@@ -870,6 +878,11 @@ export interface CreateBranchOptions {
         branchName: string;
         url: string;
     }) => Promise<void> | void;
+    /**
+     * When true, the branch will be automatically archived the first time it goes idle.
+     * Useful for cleanup branches that should be disposed after completing their task.
+     */
+    autoArchiveOnIdle?: boolean;
     /**
      * INTERNAL ONLY. Pre-generated sessionId used by trusted callers
      * (e.g. setup-agent spawner) to bootstrap a ProposedConfig doc keyed by