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

package/engine/core/decide-ticket.ts

@@ -0,0 +1,267 @@
+/**
+ * One ticket's next step once it has its worktree: a failed turn, its
+ * install and prepare, its shared baseline, then its tests, code, review
+ * and join.
+ */
+
+import {
+    isRefactorTicket,
+    stuck,
+    type BuildAction,
+    type StepArgs,
+} from './build-action'
+import { launch } from './build-launch'
+import { codeStep, testStep } from './decide-red-green'
+import { joinStep, rejoinStep } from './decide-rejoin'
+import { reviewStep } from './decide-ticket-review'
+import { failedTryMessage } from './fix-loop-text'
+import { MAX_ENGINE_FAILURES, MAX_FIX_ROUNDS } from './loop-caps'
+import { setupChangeDetail } from './stuck-text'
+
+import { endedText } from '../gates/gate-schemas'
+import type {
+    ReplayedInstall,
+    ReplayedWorktree,
+    TicketProgress,
+} from '../journal/replay'
+
+/** Why an install failed, for the stuck detail, or `null` if it passed. */
+export const installFailure = ({
+    install,
+    where,
+}: {
+    install: ReplayedInstall
+    where: string
+}): string | null => {
+    const { check } = install
+    if (check === null || check.ok) return null
+    return `\`${check.command}\` failed in ${where} (${endedText(check)}). Agents never run the install, so fix the manifest or lockfile on the base branch and retry.\n${check.output}`
+}
+
+/**
+ * The next step after a failed agent turn. An engine failure starts a fresh
+ * agent of the same role without using up a try, until
+ * `MAX_ENGINE_FAILURES` in a row. Any other failure uses up one of the
+ * role's tries on the ticket; with tries left, a test-writer or implementer
+ * gets a follow-up in the session that failed (a fresh launch with the same
+ * message if it has none, such as after a crash), and a reviewer a fresh
+ * launch. The last try's failure is stuck.
+ */
+const failedTurnStep = ({
+    snapshot,
+    ticket,
+    progress,
+    run_notes,
+    failed,
+}: StepArgs & {
+    failed: NonNullable<TicketProgress['agent_failure']>
+}): BuildAction => {
+    const { role, error, failure, session_id } = failed
+    if (failure === 'engine') {
+        if (progress.engine_failures >= MAX_ENGINE_FAILURES) {
+            return stuck({
+                ticket: ticket.number,
+                reason: 'agent_failed',
+                detail: `The engine failed to run the ${role} ${progress.engine_failures} times in a row: ${error}`,
+            })
+        }
+        return launch({ role, snapshot, ticket, progress, run_notes })
+    }
+    const tries = progress.failed_tries[role] ?? 0
+    if (tries >= MAX_FIX_ROUNDS) {
+        return stuck({
+            ticket: ticket.number,
+            reason: 'agent_failed',
+            detail: `The ${role} failed ${tries} tries; the last one: ${error}`,
+        })
+    }
+    if (role === 'ticket-reviewer') {
+        return launch({ role, snapshot, ticket, progress, run_notes })
+    }
+    const message = failedTryMessage({ failure, error })
+    if (session_id === null) {
+        return launch({
+            role,
+            snapshot,
+            ticket,
+            progress,
+            run_notes,
+            follow_up: message,
+        })
+    }
+    return {
+        type: 'follow_up_agent',
+        ticket: ticket.number,
+        role,
+        session_id,
+        message,
+    }
+}
+
+type SharedBaselineArgs = {
+    number: number
+    /** The run's tickets, in order. */
+    numbers: number[]
+    progress: (number: number) => TicketProgress
+    /** Whether a ticket is neither pushed, skipped, nor stuck. */
+    can_move: (number: number) => boolean
+}
+
+/**
+ * The ticket that runs the baseline tests a ticket with no baseline shares:
+ * the first ticket still able to move whose worktree starts from the same
+ * run-branch commit and has no baseline yet. `null` with no worktree.
+ */
+export const baselineRunner = ({
+    number,
+    numbers,
+    progress,
+    can_move,
+}: SharedBaselineArgs): number | null => {
+    const base_sha = progress(number).worktree?.base_sha
+    if (base_sha === undefined) return null
+    return (
+        numbers.find(
+            (other) =>
+                can_move(other) &&
+                progress(other).baseline === null &&
+                progress(other).worktree?.base_sha === base_sha
+        ) ?? null
+    )
+}
+
+/**
+ * How a ticket with no baseline gets one. Tickets whose worktrees start from
+ * the same run-branch commit share one baseline test run: a ticket reuses a
+ * baseline taken at its commit, or else the first such ticket still able to
+ * move runs the tests (`baselineRunner`) and the rest wait for it. `null`:
+ * it waits.
+ */
+export const sharedBaselineStep = (
+    args: SharedBaselineArgs
+): BuildAction | null => {
+    const { number, numbers, progress } = args
+    const base_sha = progress(number).worktree?.base_sha
+    if (base_sha === undefined) return null
+    const lender = numbers.find(
+        (other) =>
+            other !== number &&
+            progress(other).baseline !== null &&
+            progress(other).baseline_sha === base_sha
+    )
+    if (lender !== undefined) {
+        return {
+            type: 'reuse_baseline_tests',
+            ticket: number,
+            from_ticket: lender,
+            base_sha,
+        }
+    }
+    return baselineRunner(args) === number
+        ? { type: 'run_baseline_tests', ticket: number }
+        : null
+}
+
+/**
+ * The next step for one ticket that has its worktree, or `null` when it has
+ * nothing to do now: it pushed, or its review approved and it waits its turn
+ * to join.
+ */
+export const nextTicketStep = ({
+    snapshot,
+    ticket,
+    progress,
+    run_notes,
+    run_branch,
+    joiner,
+    setup_files,
+    baseline_step,
+    base_branch,
+}: StepArgs & {
+    run_branch: ReplayedWorktree
+    /** The branch the run started from. */
+    base_branch: string
+    /** Whether the ticket is first in the join queue. */
+    joiner: boolean
+    /** The config's test setup files. */
+    setup_files: string[]
+    /** How it gets its baseline, if it has none (`sharedBaselineStep`). */
+    baseline_step: BuildAction | null
+}): BuildAction | null => {
+    const number = ticket.number
+    if (progress.agent_failure !== null) {
+        return failedTurnStep({
+            snapshot,
+            ticket,
+            progress,
+            run_notes,
+            failed: progress.agent_failure,
+        })
+    }
+    if (progress.setup_change !== null) {
+        return stuck({
+            ticket: number,
+            reason: 'setup_change_needed',
+            detail: setupChangeDetail({
+                ...progress.setup_change,
+                setup_files,
+            }),
+        })
+    }
+    if (progress.install === null) {
+        return {
+            type: 'install_dependencies',
+            target: 'ticket',
+            ticket: number,
+        }
+    }
+    const ticketFailure = installFailure({
+        install: progress.install,
+        where: `the worktree of #${number}`,
+    })
+    if (ticketFailure !== null) {
+        return stuck({
+            ticket: number,
+            reason: 'install_failed',
+            detail: ticketFailure,
+        })
+    }
+    const { prepare } = progress
+    if (prepare !== null && !prepare.ok) {
+        return stuck({
+            ticket: number,
+            reason: 'prepare_failed',
+            detail: `\`${prepare.command}\` failed in the worktree of #${number} (${endedText(prepare)}) before any agent worked on it. Agents never run the prepare command, so fix what it needs (a missing tool, say) and retry.\n${prepare.output}`,
+        })
+    }
+    if (progress.baseline === null) return baseline_step
+    if (progress.commits.green === null) {
+        const rejoin = rejoinStep({
+            snapshot,
+            ticket,
+            progress,
+            run_notes,
+        })
+        if (rejoin !== null) return rejoin
+        const tests = isRefactorTicket({ ticket })
+            ? null
+            : testStep({
+                  snapshot,
+                  ticket,
+                  progress,
+                  run_notes,
+                  base_branch,
+              })
+        if (tests !== null) return tests
+        const code = codeStep({ snapshot, ticket, progress, run_notes })
+        if (code !== null) return code
+    }
+    const review = reviewStep({
+        snapshot,
+        ticket,
+        progress,
+        run_notes,
+    })
+    if (review !== null) return review
+    return joiner ? joinStep({ ticket, progress, run_branch }) : null
+}

package/engine/core/decide-waits.ts

@@ -0,0 +1,47 @@
+/**
+ * The waits between steps to journal (#559): a ticket the engine holds on
+ * purpose, for another ticket's shared baseline tests, the join queue, or
+ * the start queue, gets one `ticket_waiting` when its wait starts. Pure.
+ */
+import type { TicketWait } from './decide-build-tickets'
+
+import type { JournalRecord } from '../journal/journal-record'
+
+/**
+ * Whether `wait` is journaled already: its ticket's `ticket_waiting` since
+ * its last `step_started` waits for the same thing on the same ticket.
+ */
+const journaled = ({
+    wait,
+    records,
+}: {
+    wait: TicketWait
+    records: JournalRecord[]
+}): boolean => {
+    const latest = records.findLast(
+        (record) =>
+            record.ticket === wait.ticket &&
+            (record.kind === 'step_started' || record.kind === 'ticket_waiting')
+    )
+    return (
+        latest?.kind === 'ticket_waiting' &&
+        latest.content.for === wait.for &&
+        latest.content.on_ticket === wait.on_ticket
+    )
+}
+
+/**
+ * The build decision's waits (`decideBuildPlan`) that started since the
+ * journal last said so, in ticket order.
+ *
+ * @example
+ * startedWaits({ waits, records: journal.read() })
+ * // [{ ticket: 12, for: 'baseline', on_ticket: 11 }]
+ */
+export const startedWaits = ({
+    waits,
+    records,
+}: {
+    waits: TicketWait[]
+    records: JournalRecord[]
+}): TicketWait[] => waits.filter((wait) => !journaled({ wait, records }))

package/engine/core/decide.ts

@@ -1,10 +1,17 @@
-import { decideBuild, type BuildAction } from './decide-build'
+import { decideBuildPlan, type BuildAction } from './decide-build'
+import type { TicketWait } from './decide-build-tickets'
 import { decideCrashes, type CrashAction } from './decide-crashes'
 import { decideMemory, type MemoryAction } from './decide-memory'
 import { decidePlan, type PlanAction } from './decide-plan'
+import {
+    decideRepoWait,
+    type RepoWaitAction,
+    type RepoWaitRun,
+} from './decide-repo-wait'
 import { decideRunBudget, type RunBudgetAction } from './decide-run-budget'
 import { decideUsage, type UsageAction } from './decide-usage'
 import { decideUsageLine, type UsageLineAction } from './decide-usage-line'
+import { startedWaits } from './decide-waits'
 
 import { checkIntake } from '../intake/intake-checks'
 import type { IntakeProblem, IntakeSnapshot } from '../intake/intake-schemas'
@@ -16,6 +23,8 @@ import type { UsageLines } from '../limits/usage-line'
 export type EngineAction =
     /** The journal cannot be a run (for example it has no `run_started`). */
     | { type: 'invalid_journal'; reason: string }
+    /** Wait for earlier runs on the same repo, before intake (#615). */
+    | RepoWaitAction
     /** Read the spec, its sub-tickets, and outside blockers from the tracker. */
     | { type: 'read_intake'; spec_number: number }
     /** Tell each bad ticket what is missing, then end the run. */
@@ -50,8 +59,10 @@ export type EngineAction =
  * It never reads the tracker, the disk, or the clock.
  *
  * Crashes come first: a run-level step cut off by a crash `MAX_CRASHES`
- * times in a row stops the run for good (`decide-crashes.ts`). Then the
- * plan: a limit wait or a billing stop is the only action,
+ * times in a row stops the run for good (`decide-crashes.ts`). Before
+ * intake, a run with `earlier_runs` going on its repo waits for them
+ * (`decide-repo-wait.ts`). After intake, the
+ * plan:a limit wait or a billing stop is the only action,
  * for the whole run, however many tickets are in flight (the scheduler lets
  * them settle first, then every cut-off step is taken again after the
  * wait). Then the run budget: a run whose tokens reached it is stuck, and
@@ -66,17 +77,44 @@ export type EngineAction =
  * const actions = decideSteps({ records: journal.read() })
  * // [{ type: 'launch_agent', ticket: 11, ... }, { type: 'run_red_check', ticket: 12, ... }]
  */
-export const decideSteps = ({
-    records,
-    usage_lines,
-    shared_readings,
-}: {
+export const decideSteps = (args: DecideInput): EngineAction[] =>
+    decideNext(args).actions
+
+/** What `decideSteps` and `decideNext` decide from. */
+type DecideInput = {
     records: JournalRecord[]
     /** The `luca-board` usage lines. Left out, there is no usage line. */
     usage_lines?: UsageLines
     /** The newest raw readings every run shared, each with its `arrived_at`. */
     shared_readings?: unknown[]
-}): EngineAction[] => {
+    /**
+     * The earlier runs going on the run's repo (`earlierRuns`), read before
+     * intake. Left out, there is no repo wait to start.
+     */
+    earlier_runs?: RepoWaitRun[]
+}
+
+/** The decision with no ticket waiting between steps. */
+const alone = (actions: EngineAction[]) => ({ actions, waits: [] })
+
+/**
+ * `decideSteps`'s actions, and beside them the waits between steps to
+ * journal now (#559): each ticket the same build decision held on purpose,
+ * for another ticket's shared baseline tests, the join queue or the start
+ * queue, whose wait the journal doesn't say yet. None when the build
+ * doesn't run: a crash stop, a repo wait, intake, a plan limit, the run
+ * budget, or a pause at the usage line.
+ *
+ * @example
+ * decideNext({ records: journal.read() })
+ * // { actions: [{ type: 'run_baseline_tests', ticket: 11 }], waits: [{ ticket: 12, for: 'baseline', on_ticket: 11 }] }
+ */
+export const decideNext = ({
+    records,
+    usage_lines,
+    shared_readings,
+    earlier_runs,
+}: DecideInput): { actions: EngineAction[]; waits: TicketWait[] } => {
     const state = replayRun({ records })
     const { phase, spec_number } = state
     const crash = phase === 'new' ? null : decideCrashes({ state })
@@ -86,10 +124,15 @@ export const decideSteps = ({
             crash.type === 'done' && phase === 'intake_passed'
                 ? decideUsage({ records, state, ending: true })
                 : null
-        return [usage ?? crash]
+        return alone([usage ?? crash])
     }
+    const repoWait =
+        spec_number === null
+            ? null
+            : decideRepoWait({ state, records, spec_number, earlier_runs })
+    if (repoWait !== null) return alone(repoWait)
     if (phase !== 'intake_passed' || spec_number === null) {
-        return [decideIntake({ state })]
+        return alone([decideIntake({ state })])
     }
     const plan = decidePlan({ state, spec_number })
     if (plan !== null) {
@@ -98,16 +141,12 @@ export const decideSteps = ({
             plan.type === 'done'
                 ? decideUsage({ records, state, ending: true })
                 : null
-        return [usage ?? plan]
+        return alone([usage ?? plan])
     }
     const budget = decideRunBudget({ state, records, spec_number })
-    if (budget !== null) return budget
-    const build = decideMemory({
-        state,
-        records,
-        spec_number,
-        build: decideBuild({ state, spec_number }),
-    })
+    if (budget !== null) return alone(budget)
+    const { steps, waits } = decideBuildPlan({ state, spec_number })
+    const build = decideMemory({ state, records, spec_number, build: steps })
     const pause = decideUsageLine({
         state,
         records,
@@ -116,14 +155,18 @@ export const decideSteps = ({
         usage_lines,
         shared_readings: shared_readings ?? [],
     })
-    if (pause !== null) return [pause]
+    if (pause !== null) return alone([pause])
+    const started = startedWaits({ waits, records })
     // A run whose every ticket was already done ends with nothing to do.
     const ending =
         build.length === 1 &&
         (build[0]?.type === 'done' || build[0]?.type === 'finish_nothing_to_do')
     const usage = decideUsage({ records, state, ending })
-    if (usage === null) return build
-    return ending ? [usage] : [usage, ...build]
+    if (usage === null) return { actions: build, waits: started }
+    return {
+        actions: ending ? [usage] : [usage, ...build],
+        waits: started,
+    }
 }
 
 /**
@@ -138,12 +181,19 @@ export const decide = ({
     records,
     usage_lines,
     shared_readings,
+    earlier_runs,
 }: {
     records: JournalRecord[]
     usage_lines?: UsageLines
     shared_readings?: unknown[]
+    earlier_runs?: RepoWaitRun[]
 }): EngineAction => {
-    const [first] = decideSteps({ records, usage_lines, shared_readings })
+    const [first] = decideSteps({
+        records,
+        usage_lines,
+        shared_readings,
+        earlier_runs,
+    })
     return (
         first ?? {
             type: 'invalid_journal',
@@ -196,6 +246,7 @@ const decideIntake = ({ state }: { state: RunState }): EngineAction => {
                     type: 'finish_nothing_to_do',
                     closed_tickets: result.closed_tickets,
                     already_done: [],
+                    left_out: result.left_out,
                 }
             }
             // A snapshot cut short by a crash is taken again in full; replay

package/engine/core/engine-chores.ts

@@ -0,0 +1,163 @@
+/**
+ * The owner chores the engine does for a writer after its turn (#618): the
+ * file modes it asked for, and the repo's generators it named. Agents can
+ * do neither themselves.
+ */
+import { chmod, lstat, realpath } from 'node:fs/promises'
+import { isAbsolute, join, relative, sep } from 'node:path'
+
+import type { BuildContext } from './build-context'
+
+import type { FileMode, RoleResult } from '../agents/role-results'
+import { testTimeoutOf } from '../config/engine-config'
+import { shellCheck } from '../gates/gate-runner'
+import { endedText, type GateCheck } from '../gates/gate-schemas'
+import { TEST_TIMEOUT_HINT } from '../gates/test-runner'
+import type { GuardArgs } from '../guards/guard-roles'
+import { mayWrite } from '../guards/write-rules'
+
+/** The chores a result asks for, or `null` for a role that asks none. */
+const choresOf = ({
+    result,
+}: {
+    result: RoleResult
+}): { file_modes: FileMode[]; run_generators: string[] } | null =>
+    result.role === 'test-writer' || result.role === 'implementer'
+        ? result.result
+        : null
+
+/**
+ * Sets one file's mode, or says why not: a path the role may not write, no
+ * regular file there, or a real path (through a symlinked folder) that
+ * leaves the worktree or that the role may not write (#624).
+ */
+const applyMode = async ({
+    cwd,
+    mode,
+    guard,
+    context,
+}: {
+    cwd: string
+    mode: FileMode
+    guard: GuardArgs
+    context: BuildContext
+}): Promise<string | null> => {
+    const { path, executable } = mode
+    if (!mayWrite({ ...guard, path, config: context.config })) {
+        return `file_modes: ${path} is a path your role may not write, so its mode was not changed.`
+    }
+    const full = join(cwd, path)
+    const found = await lstat(full).catch(() => null)
+    const real = await realpath(full).catch(() => null)
+    if (found === null || !found.isFile() || real === null) {
+        return `file_modes: ${path} is not a file in the worktree, so no mode was set.`
+    }
+    // A symlinked folder on the way must not lead the mode elsewhere.
+    const inside = relative(await realpath(cwd), real)
+    if (
+        inside === '..' ||
+        inside.startsWith(`..${sep}`) ||
+        isAbsolute(inside)
+    ) {
+        return `file_modes: ${path} is really ${real}, outside the worktree, so its mode was not changed.`
+    }
+    if (!mayWrite({ ...guard, path: inside, config: context.config })) {
+        return `file_modes: ${path} is really ${inside}, a path your role may not write, so its mode was not changed.`
+    }
+    const mode_bits = executable ? found.mode | 0o111 : found.mode & ~0o111
+    await chmod(real, mode_bits & 0o7777)
+    return null
+}
+
+/** Runs one named generator, as a `generate` check, or says it has none. */
+const runGenerator = async ({
+    cwd,
+    name,
+    context,
+}: {
+    cwd: string
+    name: string
+    context: BuildContext
+}): Promise<{ check: GateCheck | null; problem: string | null }> => {
+    const generators = context.config.generators ?? {}
+    // Own names only: `constructor` and friends are inherited, not named.
+    const command = Object.hasOwn(generators, name)
+        ? generators[name]
+        : undefined
+    if (command === undefined) {
+        const known = Object.keys(generators).map((other) => `"${other}"`)
+        return {
+            check: null,
+            problem: `run_generators: "${name}" is not a generator this repo names (${known.length === 0 ? 'it names none' : `it names ${known.join(', ')}`}).`,
+        }
+    }
+    const check = await shellCheck({
+        name: 'generate',
+        command,
+        cwd,
+        timeout_ms: testTimeoutOf({ config: context.config }),
+        timeout_hint: TEST_TIMEOUT_HINT,
+    })
+    return {
+        check,
+        problem: check.ok
+            ? null
+            : `run_generators: the generator "${name}" (\`${command}\`) failed (${endedText(check)}):\n${check.output}`,
+    }
+}
+
+/**
+ * Does the chores a writer's result asks for, in its worktree: each file
+ * mode, on a path the role may write (others are refused and left as they
+ * are), then each named generator, in order, as a `generate` check with the
+ * test time limit. What they change is committed with the rest of the
+ * turn's work. Journals `chores_done` when the result asked for any.
+ *
+ * @returns The problems, for the role's fix loop: a refused path, an
+ *   unknown generator, or a failed one. Empty when every chore was done.
+ *
+ * @example
+ * const problems = await doChores({ context, cwd, result, guard })
+ */
+export const doChores = async ({
+    context,
+    cwd,
+    ticket,
+    result,
+    guard,
+}: {
+    context: BuildContext
+    cwd: string
+    /** `null` in the final review. */
+    ticket: number | null
+    result: RoleResult
+    guard: GuardArgs
+}): Promise<string[]> => {
+    const chores = choresOf({ result })
+    if (
+        chores === null ||
+        (chores.file_modes.length === 0 && chores.run_generators.length === 0)
+    ) {
+        return []
+    }
+    const problems: string[] = []
+    const file_modes: FileMode[] = []
+    for (const mode of chores.file_modes) {
+        const problem = await applyMode({ cwd, mode, guard, context })
+        if (problem === null) file_modes.push(mode)
+        else problems.push(problem)
+    }
+    const checks: GateCheck[] = []
+    for (const name of chores.run_generators) {
+        const ran = await runGenerator({ cwd, name, context })
+        if (ran.check !== null) checks.push(ran.check)
+        if (ran.problem !== null) problems.push(ran.problem)
+    }
+    context.journal.append({
+        kind: 'chores_done',
+        ticket,
+        role: result.role,
+        content: { role: result.role, file_modes, checks, problems },
+    })
+    return problems
+}