@alecsibilia/luca 14.0.0-alpha.2 → 14.0.0-alpha.21

package/engine/git/git-join.ts

@@ -0,0 +1,139 @@
+/**
+ * The git adapter's moves between branches: list the commits between two,
+ * replay them onto the run branch, undo a replay, and move a worktree's
+ * change onto another commit.
+ */
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { GitAdapter } from './git-adapter'
+import { gitOk, gitRun, head, lines } from './git-run'
+
+/**
+ * Lines added plus lines removed in `git diff --numstat` output. A binary
+ * file (`-` for both counts) counts 0.
+ */
+const linesChanged = (numstat: string): number =>
+    lines(numstat).reduce((total, line) => {
+        const [added = '', removed = ''] = line.split('\t')
+        return total + (Number(added) || 0) + (Number(removed) || 0)
+    }, 0)
+
+export const joinOps: Pick<
+    GitAdapter,
+    'commitsBetween' | 'replay' | 'undoReplay' | 'rebaseWorktree'
+> = {
+    commitsBetween: async ({ cwd, from, to }) =>
+        lines(
+            await gitOk({
+                cwd,
+                args: ['rev-list', '--reverse', `${from}..${to}`],
+            })
+        ),
+    replay: async ({ cwd, commits }) => {
+        const before = await head({ cwd })
+        const picked = await gitRun({
+            cwd,
+            args: ['cherry-pick', ...commits],
+        })
+        if (picked.exit_code !== 0) {
+            await gitRun({ cwd, args: ['cherry-pick', '--abort'] })
+            return { ok: false, error: picked.stderr || picked.stdout }
+        }
+        return {
+            ok: true,
+            shas: lines(
+                await gitOk({
+                    cwd,
+                    args: ['rev-list', '--reverse', `${before}..HEAD`],
+                })
+            ),
+            lines_changed: linesChanged(
+                await gitOk({
+                    cwd,
+                    args: ['diff', '--numstat', '--no-renames', before, 'HEAD'],
+                })
+            ),
+        }
+    },
+    undoReplay: async ({ cwd, first_sha, only }) => {
+        const short = first_sha.slice(0, 7)
+        const parent = await gitRun({
+            cwd,
+            args: [
+                'rev-parse',
+                '--verify',
+                '--quiet',
+                `${first_sha}^{commit}^`,
+            ],
+        })
+        if (parent.exit_code !== 0) {
+            return {
+                ok: false,
+                error: `Commit ${short} is not in the repo (or has no parent), so there is no join to undo.`,
+            }
+        }
+        const before = parent.stdout.trim()
+        const tip = await head({ cwd })
+        const ancestor = await gitRun({
+            cwd,
+            args: ['merge-base', '--is-ancestor', first_sha, 'HEAD'],
+        })
+        if (ancestor.exit_code !== 0) {
+            // Already undone, such as a redo after a crash.
+            if (tip === before) return { ok: true, undone: [] }
+            return {
+                ok: false,
+                error: `Commit ${short} is not on the branch, so undoing it (a reset to its parent) would rewind the branch over other work.`,
+            }
+        }
+        const undone = lines(
+            await gitOk({
+                cwd,
+                args: ['rev-list', '--reverse', `${before}..HEAD`],
+            })
+        )
+        const others = undone.filter((sha) => !only.includes(sha))
+        if (others.length > 0) {
+            return {
+                ok: false,
+                error: `Undoing ${short} would also undo other work on top of it: ${others.map((sha) => sha.slice(0, 7)).join(', ')}.`,
+            }
+        }
+        await gitOk({ cwd, args: ['reset', '--quiet', '--hard', before] })
+        return { ok: true, undone }
+    },
+    rebaseWorktree: async ({ cwd, from, to, onto }) => {
+        const folder = await mkdtemp(join(tmpdir(), 'luca-rebase-'))
+        try {
+            const patch = join(folder, 'change.patch')
+            await gitOk({
+                cwd,
+                args: ['diff', '--binary', `--output=${patch}`, from, to],
+            })
+            await gitOk({ cwd, args: ['reset', '--quiet', '--hard', onto] })
+            if ((await Bun.file(patch).size) === 0) return { conflicts: [] }
+            const applied = await gitRun({
+                cwd,
+                args: ['apply', '--3way', patch],
+            })
+            const conflicts = lines(
+                await gitOk({
+                    cwd,
+                    args: ['diff', '--name-only', '--diff-filter=U'],
+                })
+            ).toSorted()
+            if (applied.exit_code !== 0 && conflicts.length === 0) {
+                throw new Error(
+                    `git apply --3way failed in ${cwd}:\n${applied.stderr || applied.stdout}`
+                )
+            }
+            // Everything becomes plain uncommitted changes, markers kept.
+            await gitOk({ cwd, args: ['reset', '--quiet'] })
+            return { conflicts }
+        } finally {
+            await rm(folder, { recursive: true, force: true })
+        }
+    },
+}

package/engine/git/git-read.ts

@@ -0,0 +1,123 @@
+/**
+ * The git adapter's reads: what changed in a worktree or between commits,
+ * which files exist, and where a commit is. None of them changes the repo.
+ */
+import sortBy from 'lodash/sortBy'
+import uniq from 'lodash/uniq'
+
+import type { FileChange, GitAdapter } from './git-adapter'
+import { gitOk, gitRun, head, lines } from './git-run'
+
+/** A full or short commit id, in hex. Anything else is no commit id. */
+const COMMIT_ID = /^[0-9a-f]{4,64}$/i
+
+/** Parses `git status --porcelain=v1 -z --untracked-files=all`. */
+export const parseStatus = ({ text }: { text: string }): FileChange[] => {
+    const parts = text.split('\0').filter((part) => part.length > 0)
+    const changes: FileChange[] = []
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index] ?? ''
+        const [x = ' ', y = ' '] = part
+        const path = part.slice(3)
+        if (x === 'R' || x === 'C') index += 1 // the next part is the old path
+        if (x === 'D' || y === 'D') changes.push({ path, change: 'deleted' })
+        else if (x === '?' || x === 'A' || x === 'R' || x === 'C')
+            changes.push({ path, change: 'added' })
+        else changes.push({ path, change: 'modified' })
+    }
+    return sortBy(changes, 'path')
+}
+
+export const readOps: Pick<
+    GitAdapter,
+    | 'changes'
+    | 'changedSince'
+    | 'fileAt'
+    | 'filesBetween'
+    | 'untracked'
+    | 'listFiles'
+    | 'filesMentioning'
+    | 'head'
+    | 'commitOnBase'
+> = {
+    changes: async ({ cwd }) =>
+        parseStatus({
+            text: await gitOk({
+                cwd,
+                args: [
+                    'status',
+                    '--porcelain=v1',
+                    '-z',
+                    '--untracked-files=all',
+                ],
+            }),
+        }),
+    changedSince: async ({ cwd, from }) => {
+        const tracked = lines(
+            await gitOk({ cwd, args: ['diff', '--name-only', from] })
+        )
+        const untracked = lines(
+            await gitOk({
+                cwd,
+                args: ['ls-files', '--others', '--exclude-standard'],
+            })
+        )
+        return uniq([...tracked, ...untracked]).toSorted()
+    },
+    fileAt: async ({ cwd, sha, path }) => {
+        const result = await gitRun({
+            cwd,
+            args: ['show', `${sha}:${path}`],
+        })
+        return result.exit_code === 0 ? result.stdout : null
+    },
+    filesBetween: async ({ cwd, from, to }) =>
+        lines(
+            await gitOk({ cwd, args: ['diff', '--name-only', from, to] })
+        ).toSorted(),
+    untracked: async ({ cwd }) =>
+        (
+            await gitOk({
+                cwd,
+                args: ['ls-files', '--others', '--exclude-standard', '-z'],
+            })
+        )
+            .split('\0')
+            .filter((path) => path !== ''),
+    listFiles: async ({ cwd }) =>
+        lines(
+            await gitOk({
+                cwd,
+                args: [
+                    'ls-files',
+                    '--cached',
+                    '--others',
+                    '--exclude-standard',
+                ],
+            })
+        ),
+    filesMentioning: async ({ cwd, text }) => {
+        // git grep exits 1 when nothing matches; that is an empty answer.
+        const result = await gitRun({
+            cwd,
+            args: ['grep', '-l', '-F', '-e', text, '--', '.'],
+        })
+        return result.exit_code === 0 ? lines(result.stdout) : []
+    },
+    head,
+    commitOnBase: async ({ cwd, sha, base }) => {
+        if (!COMMIT_ID.test(sha)) return 'unknown'
+        const found = await gitRun({
+            cwd,
+            args: ['rev-parse', '--verify', '--quiet', `${sha}^{commit}`],
+        })
+        if (found.exit_code !== 0) return 'unknown'
+        const args = ['merge-base', '--is-ancestor', sha, base]
+        const ancestor = await gitRun({ cwd, args })
+        if (ancestor.exit_code === 0) return 'on_base'
+        if (ancestor.exit_code === 1) return 'not_on_base'
+        throw new Error(
+            `git ${args.join(' ')} failed in ${cwd}:\n${ancestor.stderr || ancestor.stdout}`
+        )
+    },
+}

package/engine/git/git-run.ts

@@ -0,0 +1,32 @@
+/**
+ * Runs `git` in a folder: `gitRun` returns the result as it is, `gitOk`
+ * throws when git fails. Also the line splitter and `head` the other git
+ * modules share.
+ */
+import { runCommand } from '../shell/run-command'
+
+export const gitRun = ({ cwd, args }: { cwd: string; args: string[] }) =>
+    runCommand({ cmd: ['git', ...args], cwd, timeout_ms: 120_000 })
+
+export const gitOk = async ({
+    cwd,
+    args,
+}: {
+    cwd: string
+    args: string[]
+}): Promise<string> => {
+    const result = await gitRun({ cwd, args })
+    if (result.exit_code !== 0) {
+        throw new Error(
+            `git ${args.join(' ')} failed in ${cwd}:\n${result.stderr || result.stdout}`
+        )
+    }
+    return result.stdout
+}
+
+export const lines = (text: string): string[] =>
+    text.split('\n').filter((line) => line.trim() !== '')
+
+/** The commit checked out at `cwd`. */
+export const head = async ({ cwd }: { cwd: string }) =>
+    (await gitOk({ cwd, args: ['rev-parse', 'HEAD'] })).trim()

package/engine/git/git-worktrees.ts

@@ -0,0 +1,143 @@
+/**
+ * The git adapter's worktrees: fetch the base branch, make the run branch and
+ * each ticket's worktree (safe to repeat after a crash), and remove them.
+ * These are the calls that need the repo's root.
+ */
+import { existsSync, realpathSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+
+import type { GitAdapter } from './git-adapter'
+import { gitOk, gitRun, head, lines } from './git-run'
+
+export const createWorktreeOps = ({
+    repo_root,
+}: {
+    repo_root: string
+}): Pick<
+    GitAdapter,
+    'fetchBase' | 'createRunBranch' | 'createWorktree' | 'removeWorktree'
+> => {
+    /** The branch git has checked out in a worktree at `path`, if any. */
+    const worktreeBranchAt = async ({
+        path,
+    }: {
+        path: string
+    }): Promise<{ branch: string | null } | null> => {
+        if (!existsSync(path)) return null
+        const wanted = realpathSync(path)
+        const listed = await gitOk({
+            cwd: repo_root,
+            args: ['worktree', 'list', '--porcelain'],
+        })
+        for (const block of listed.split('\n\n')) {
+            const fields = lines(block)
+            const at = fields
+                .find((line) => line.startsWith('worktree '))
+                ?.slice('worktree '.length)
+            if (at === undefined || !existsSync(at)) continue
+            if (realpathSync(at) !== wanted) continue
+            const ref = fields
+                .find((line) => line.startsWith('branch '))
+                ?.slice('branch '.length)
+            return { branch: ref?.replace(/^refs\/heads\//, '') ?? null }
+        }
+        return null
+    }
+
+    const branchExists = async ({ branch }: { branch: string }) =>
+        (
+            await gitRun({
+                cwd: repo_root,
+                args: [
+                    'rev-parse',
+                    '--verify',
+                    '--quiet',
+                    `refs/heads/${branch}`,
+                ],
+            })
+        ).exit_code === 0
+
+    const addWorktree = async ({
+        branch,
+        from,
+        path,
+    }: {
+        branch: string
+        from: string
+        path: string
+    }) => {
+        const known = await worktreeBranchAt({ path })
+        if (known !== null && known.branch !== branch) {
+            throw new Error(
+                `${path} is already a worktree on ${known.branch ?? 'no branch'}, not ${branch}.`
+            )
+        }
+        if (known !== null) {
+            // Made before a crash: nothing has worked in it since, so finish
+            // a checkout the crash may have cut off, and adopt it.
+            const reset = await gitRun({
+                cwd: path,
+                args: ['reset', '--quiet', '--hard', 'HEAD'],
+            })
+            if (reset.exit_code === 0) {
+                return { base_sha: await head({ cwd: path }) }
+            }
+            await gitRun({
+                cwd: repo_root,
+                args: ['worktree', 'remove', '--force', '--force', path],
+            })
+        }
+        // A half-made folder git doesn't know (or no longer does) goes.
+        await rm(path, { recursive: true, force: true })
+        await gitOk({ cwd: repo_root, args: ['worktree', 'prune'] })
+        await gitOk({
+            cwd: repo_root,
+            args: (await branchExists({ branch }))
+                ? ['worktree', 'add', '--quiet', path, branch]
+                : [
+                      'worktree',
+                      'add',
+                      '--quiet',
+                      '--no-track',
+                      '-b',
+                      branch,
+                      path,
+                      from,
+                  ],
+        })
+        return { base_sha: await head({ cwd: path }) }
+    }
+
+    return {
+        fetchBase: async ({ base_branch }) => {
+            const fetched = await gitRun({
+                cwd: repo_root,
+                args: [
+                    'fetch',
+                    '--quiet',
+                    'origin',
+                    `+refs/heads/${base_branch}:refs/remotes/origin/${base_branch}`,
+                ],
+            })
+            return fetched.exit_code === 0
+                ? { ok: true }
+                : {
+                      ok: false,
+                      error: (fetched.stderr || fetched.stdout).trim(),
+                  }
+        },
+        createRunBranch: ({ branch, base_branch, path }) =>
+            addWorktree({ branch, from: `origin/${base_branch}`, path }),
+        createWorktree: addWorktree,
+        removeWorktree: async ({ path }) => {
+            if (existsSync(path)) {
+                // A folder that is no worktree (or not any more) is fine.
+                await gitRun({
+                    cwd: repo_root,
+                    args: ['worktree', 'remove', '--force', path],
+                })
+            }
+            await gitOk({ cwd: repo_root, args: ['worktree', 'prune'] })
+        },
+    }
+}

package/engine/git/outside-links.ts

@@ -0,0 +1,55 @@
+import { lstat, readlink, realpath } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+import uniq from 'lodash/uniq'
+
+/** Whether `target` is `root` or somewhere under it. */
+const isInside = ({ root, target }: { root: string; target: string }) => {
+    const path = relative(root, target)
+    return (
+        path === '' ||
+        (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path))
+    )
+}
+
+/**
+ * The paths among `paths` that are symlinks pointing outside the checkout
+ * at `cwd`, such as a build's link to a vendor folder in the owner's own
+ * checkout. Such a link only works on one machine, so no commit should hold
+ * it. A link's target is read, never followed; a relative target counts
+ * from the link's folder. A path that is not a link, or can't be read, is
+ * never one.
+ *
+ * @param cwd - The checkout's root.
+ * @param paths - Checkout-relative paths, as git lists them.
+ * @returns The outside-pointing links, in the order given.
+ *
+ * @example
+ * await outsideLinks({ cwd, paths: ['tools/bin', 'src/sum.ts'] })
+ * // ['tools/bin'], when tools/bin links to /home/me/vendor/bin
+ */
+export const outsideLinks = async ({
+    cwd,
+    paths,
+}: {
+    cwd: string
+    paths: string[]
+}): Promise<string[]> => {
+    // A link may name the checkout by its real path (macOS's /private/var
+    // for /var, say), so both count as inside.
+    const roots = uniq([resolve(cwd), await realpath(cwd).catch(() => cwd)])
+    const found: string[] = []
+    for (const path of paths) {
+        const full = join(cwd, path)
+        const target = await lstat(full)
+            .then(async (stat) =>
+                stat.isSymbolicLink()
+                    ? resolve(dirname(full), await readlink(full))
+                    : null
+            )
+            .catch(() => null)
+        if (target === null) continue
+        if (!roots.some((root) => isInside({ root, target }))) found.push(path)
+    }
+    return found
+}

package/engine/guards/after-turn-check.ts

@@ -22,7 +22,10 @@ export type GitState = {
     head_ref: string | null
     /** The ticket branch's commit, `null` if the branch is gone. */
     branch_ref: string | null
-    /** Other refs pointing at HEAD. The repo's refs are shared, so only these count. */
+    /**
+     * Other refs pointing at HEAD. The repo's refs are shared, so only these
+     * count, and only when HEAD is a commit made during the turn.
+     */
     refs_at_head: string[]
     /** Stash entries naming the branch. The stash is shared too. */
     stash: string[]
@@ -146,6 +149,29 @@ export const pathViolations = ({
 const added = ({ before, after }: { before: string[]; after: string[] }) =>
     after.filter((item) => !before.includes(item))
 
+/**
+ * The new refs at HEAD the agent made. The refs are shared, so a new ref
+ * counts only when HEAD is a commit made during the turn: one at a commit
+ * that already existed may be another process's, such as a helper's
+ * worktree branch.
+ *
+ * @example
+ * refsMadeInTurn({ before, after, head_is_new: false }) // []
+ */
+export const refsMadeInTurn = ({
+    before,
+    after,
+    head_is_new,
+}: {
+    before: GitState
+    after: GitState
+    /** Whether HEAD is now a commit made during the turn. */
+    head_is_new: boolean
+}): string[] =>
+    head_is_new
+        ? added({ before: before.refs_at_head, after: after.refs_at_head })
+        : []
+
 /**
  * Every git change between two snapshots. No role may change git state, so
  * each one is a violation.
@@ -153,9 +179,12 @@ const added = ({ before, after }: { before: string[]; after: string[] }) =>
 export const gitViolations = ({
     before,
     after,
+    head_is_new,
 }: {
     before: GitState
     after: GitState
+    /** Whether HEAD is now a commit made during the turn. */
+    head_is_new: boolean
 }): Violation[] => {
     const details: string[] = []
     if (before.head !== after.head) {
@@ -171,10 +200,7 @@ export const gitViolations = ({
             `the ticket branch moved from ${before.branch_ref} to ${after.branch_ref}`
         )
     }
-    const refs = added({
-        before: before.refs_at_head,
-        after: after.refs_at_head,
-    })
+    const refs = refsMadeInTurn({ before, after, head_is_new })
     if (refs.length > 0) details.push(`new refs at HEAD: ${refs.join(', ')}`)
     const stash = added({ before: before.stash, after: after.stash })
     if (stash.length > 0) details.push(`new stash entries: ${stash.join('; ')}`)

package/engine/guards/guard-hook.ts

@@ -3,6 +3,7 @@ import type {
     HookJSONOutput,
 } from '@anthropic-ai/claude-agent-sdk'
 
+import { checkHelperTool, HELPER_TOOL, MAX_HELPERS } from './helper-rules'
 import { checkToolCall, type GuardRole } from './role-rules'
 
 import type { EngineConfig } from '../config/engine-config'
@@ -13,6 +14,13 @@ import type { EngineConfig } from '../config/engine-config'
  * reason. An allowed call gets no opinion from the hook, so the SDK's own
  * permission rules still apply. Any error in the guard itself denies.
  *
+ * Helpers (#627): a call from inside a helper (one with the SDK's
+ * `agent_id`) may only read and search, whatever the agent may do. An
+ * allowed helper goes into `helpers`, by the id of the call that started it,
+ * until its result comes back (the launcher takes it out); a helper past
+ * `MAX_HELPERS` running is denied. `on_helper` is called for each one
+ * started.
+ *
  * @example
  * const hook = createGuardHook({ role: 'implementer', may_edit_tests: false, worktree, config, on_deny: (denial) => denials.push(denial) })
  * const options = { hooks: { PreToolUse: [{ hooks: [hook] }] } }
@@ -23,6 +31,9 @@ export const createGuardHook = ({
     worktree,
     config,
     on_deny,
+    helpers = new Set(),
+    on_helper,
+    on_allow,
 }: {
     role: GuardRole
     /** Whether the agent may edit test files. */
@@ -32,6 +43,16 @@ export const createGuardHook = ({
     config: EngineConfig
     /** Called for each denied call, such as to count it. */
     on_deny?: (denial: { tool_name: string; reason: string }) => void
+    /** The agent's running helpers, by the tool call that started each. */
+    helpers?: Set<string>
+    /** Called for each helper started, such as to count it. */
+    on_helper?: () => void
+    /** Called for each of the agent's own calls let through (not a helper's), such as to show it running. */
+    on_allow?: (call: {
+        tool_name: string
+        tool_input: unknown
+        tool_use_id: string
+    }) => void
 }): HookCallback => {
     const denied = (reason: string): HookJSONOutput => ({
         hookSpecificOutput: {
@@ -40,20 +61,47 @@ export const createGuardHook = ({
             permissionDecisionReason: reason,
         },
     })
-    return async (input): Promise<HookJSONOutput> => {
+    return async (input, tool_use_id): Promise<HookJSONOutput> => {
         if (input.hook_event_name !== 'PreToolUse') return {}
         try {
-            const decision = checkToolCall({
-                role,
-                may_edit_tests,
-                tool_name: input.tool_name,
-                tool_input: input.tool_input,
-                worktree,
-                config,
-            })
-            if (decision.allow) return {}
-            on_deny?.({ tool_name: input.tool_name, reason: decision.reason })
-            return denied(decision.reason)
+            const fromHelper = input.agent_id !== undefined
+            const helperTool = fromHelper
+                ? checkHelperTool({ tool_name: input.tool_name })
+                : null
+            const decision =
+                helperTool !== null && !helperTool.allow
+                    ? helperTool
+                    : checkToolCall({
+                          role,
+                          may_edit_tests,
+                          tool_name: input.tool_name,
+                          tool_input: input.tool_input,
+                          worktree,
+                          config,
+                      })
+            const full =
+                decision.allow &&
+                input.tool_name === HELPER_TOOL &&
+                helpers.size >= MAX_HELPERS
+            if (decision.allow && !full) {
+                if (input.tool_name === HELPER_TOOL) {
+                    helpers.add(tool_use_id ?? input.tool_use_id)
+                    on_helper?.()
+                }
+                if (!fromHelper) {
+                    on_allow?.({
+                        tool_name: input.tool_name,
+                        tool_input: input.tool_input,
+                        tool_use_id: tool_use_id ?? input.tool_use_id,
+                    })
+                }
+                return {}
+            }
+            const reason = decision.allow
+                ? `At most ${MAX_HELPERS} helpers run at once: wait for one to finish.`
+                : decision.reason
+            on_deny?.({ tool_name: input.tool_name, reason })
+            return denied(reason)
         } catch (error) {
             return denied(
                 `The guard could not check this call: ${String(error)}`