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

package/engine/core/agent-turn.ts

@@ -0,0 +1,395 @@
+/**
+ * One agent turn (`runTurn`): the worktree guard around it, and how it
+ * ended, journaled. Also the `launch_agent` and `follow_up_agent` steps,
+ * which start a turn.
+ */
+import { need, ticketWorktree, type BuildContext } from './build-context'
+import { mayEditTests, type BuildAction } from './decide-build'
+import { doChores } from './engine-chores'
+import { closeSessions } from './session-close'
+
+import type { AgentTurn } from '../agents/agent-launcher'
+import {
+    parseRoleResult,
+    type AgentRole,
+    type RoleResult,
+} from '../agents/role-results'
+import { DEFAULT_MODEL } from '../config/engine-config'
+import { describeViolations } from '../guards/after-turn-check'
+import { guardRoleOf } from '../guards/role-rules'
+import { enforceAfterTurn, snapshotWorktree } from '../guards/worktree-state'
+import { launchPick, type ModelReason } from '../jev/model-pick'
+import type { AgentFailure, JournalRecord } from '../journal/journal-record'
+import type { ReplayedWorktree } from '../journal/replay'
+import { sessionSignal } from '../limits/plan-signals'
+import { createAgentMessaging } from '../messages/agent-messaging'
+
+const failTurn = ({
+    context,
+    ticket,
+    role,
+    error,
+    failure,
+    session_id,
+    session_gone,
+    out_of_turns,
+}: {
+    context: BuildContext
+    ticket: number | null
+    role: AgentRole
+    error: string
+    failure: AgentFailure
+    session_id: string | null
+    session_gone: boolean
+    out_of_turns: boolean
+}) => {
+    context.journal.append({
+        kind: 'agent_failed',
+        ticket,
+        role,
+        content: {
+            role,
+            error,
+            failure,
+            session_id,
+            ...(session_gone ? { session_gone } : {}),
+            ...(out_of_turns ? { out_of_turns } : {}),
+        },
+    })
+}
+
+/**
+ * Runs one agent turn, a launch or a follow-up, and journals how it ended.
+ * Before the turn the engine snapshots the worktree; after it, the
+ * after-turn check undoes and reports anything the role may not change, for
+ * every launcher alike; what others changed in the shared `.git` meanwhile
+ * is journaled as `shared_git_changed`. Then the result is judged by its
+ * structured output. Each failed turn is journaled once as `agent_failed`
+ * with how it failed; the decision step picks what happens next. A writer's
+ * result then gets its chores done (`doChores`, #618); one the engine could
+ * not do fails the turn as a `chore` failure. A launcher stop journals
+ * `run_stopped` and ends the run. A turn the plan cut off (a rejected limit,
+ * overage, a billing error) journals only its session. Both close the
+ * turn's session first, since no follow-up can reach it.
+ *
+ * @param worktree - Where the agent works: its ticket's worktree, or the run
+ *   branch's for the final review.
+ * @param ticket - The ticket its records name, `null` for the final review.
+ * @returns The role's result when the agent finished, else `null`.
+ */
+export const runTurn = async ({
+    context,
+    worktree,
+    ticket,
+    role,
+    may_edit_tests,
+    start,
+}: {
+    context: BuildContext
+    worktree: ReplayedWorktree
+    ticket: number | null
+    role: AgentRole
+    may_edit_tests: boolean
+    start: (cwd: string) => Promise<AgentTurn>
+}): Promise<RoleResult | null> => {
+    const { path, branch } = worktree
+    const before = await snapshotWorktree({
+        cwd: path,
+        branch,
+        config: context.config,
+    })
+    const turn = await start(path)
+    if (turn.session !== undefined) {
+        context.journal.append({
+            kind: 'agent_session',
+            ticket,
+            role,
+            content: { role, session: turn.session },
+        })
+    }
+    const guard_role = guardRoleOf({ role })
+    const { violations, outside } = await enforceAfterTurn({
+        cwd: path,
+        branch,
+        role: guard_role,
+        may_edit_tests,
+        config: context.config,
+        before,
+        leave_out: context.state.prepare_made,
+    })
+    // Others' changes to the shared .git: noted, never blamed or undone.
+    if (outside.length > 0) {
+        context.journal.append({
+            kind: 'shared_git_changed',
+            ticket,
+            role,
+            content: { role, changes: outside },
+        })
+    }
+    // The plan cut the turn off. Its session, journaled above, holds why,
+    // and the decision step reads it from there: a limit wait or a billing
+    // stop. The turn uses up no try, and its step is taken again. With no
+    // sign in the session, the engine can't tell which, so it stops.
+    const unexplained =
+        !turn.ok &&
+        turn.failure === 'plan' &&
+        (turn.session === undefined ||
+            sessionSignal({ session: turn.session }).kind === 'ok')
+    // Either way no follow-up reaches the session: close it now.
+    const cut = !turn.ok && (turn.failure === 'plan' || turn.failure === 'stop')
+    if (cut && turn.session_id !== undefined) {
+        await closeSessions({
+            journal: context.journal,
+            launcher: context.launcher,
+            sessions: [{ session_id: turn.session_id, ticket, role }],
+        })
+    }
+    if (!turn.ok && turn.failure === 'plan' && !unexplained) return null
+    if (!turn.ok && (turn.failure === 'stop' || unexplained)) {
+        context.journal.append({
+            kind: 'run_stopped',
+            ticket,
+            role,
+            content: { reason: turn.error, role, billing: false },
+        })
+        throw new Error(`Run stopped: ${turn.error}`)
+    }
+    const session_id = turn.session_id ?? null
+    const fail = ({
+        failure,
+        error,
+        session_gone = false,
+        out_of_turns = false,
+    }: {
+        failure: AgentFailure
+        error: string
+        session_gone?: boolean
+        out_of_turns?: boolean
+    }) => {
+        failTurn({
+            context,
+            ticket,
+            role,
+            error,
+            failure,
+            session_id,
+            session_gone,
+            out_of_turns,
+        })
+        return null
+    }
+    if (violations.length > 0) {
+        return fail({
+            failure: 'guard',
+            error: describeViolations({ role: guard_role, violations }),
+        })
+    }
+    if (!turn.ok) {
+        return fail({
+            failure: turn.failure === 'engine' ? 'engine' : 'agent',
+            error: turn.error,
+            session_gone: turn.session_gone === true,
+            out_of_turns: turn.out_of_turns === true,
+        })
+    }
+    if (
+        turn.structured_output === undefined ||
+        turn.structured_output === null
+    ) {
+        return fail({
+            failure: 'result',
+            error: `The ${role} finished with no structured output.`,
+        })
+    }
+    const checked = parseRoleResult({ role, output: turn.structured_output })
+    if (!checked.ok) return fail({ failure: 'result', error: checked.error })
+    // The chores the writer asked for (#618), before any check or commit.
+    const problems = await doChores({
+        context,
+        cwd: path,
+        ticket,
+        result: checked.value,
+        guard: { role: guard_role, may_edit_tests },
+    })
+    if (problems.length > 0) {
+        return fail({
+            failure: 'chore',
+            error: problems.map((line) => `- ${line}`).join('\n'),
+        })
+    }
+    context.journal.append({
+        kind: 'agent_finished',
+        ticket,
+        role,
+        content: { ...checked.value, session_id },
+    })
+    return checked.value
+}
+
+/** The session a record names, if any. */
+const sessionOf = (record: JournalRecord): string | null => {
+    switch (record.kind) {
+        case 'agent_session':
+            return record.content.session.session_id
+        case 'agent_finished':
+        case 'agent_failed':
+            return record.content.session_id
+        default:
+            return null
+    }
+}
+
+/** The model a session launched on, and why (`null` before #603). */
+export type SessionModel = { model: string; model_reason: ModelReason | null }
+
+/**
+ * The model a session launched on, and why, from the journal: the
+ * `agent_started` of the launch the session's first record came after (same
+ * ticket and role), or of an earlier follow-up to it. `null` if the journal
+ * names none, as in journals from before #600; every agent ran Opus then.
+ *
+ * @example
+ * sessionModel({ records: journal.read(), session_id }) // { model: 'opus', model_reason: 'locked' }
+ */
+export const sessionModel = ({
+    records,
+    session_id,
+}: {
+    records: JournalRecord[]
+    session_id: string
+}): SessionModel | null => {
+    const followed = records.findLast(
+        (record) =>
+            record.kind === 'agent_started' &&
+            record.content.follow_up_of === session_id &&
+            record.content.model !== null
+    )
+    const first = records.findIndex(
+        (record) => sessionOf(record) === session_id
+    )
+    const { ticket, role } = records[first] ?? {}
+    const started =
+        followed ??
+        (first === -1
+            ? undefined
+            : records
+                  .slice(0, first)
+                  .findLast(
+                      (record) =>
+                          record.kind === 'agent_started' &&
+                          record.ticket === ticket &&
+                          record.role === role &&
+                          record.content.follow_up_of === null
+                  ))
+    if (started?.kind !== 'agent_started') return null
+    const { model, model_reason } = started.content
+    return model === null ? null : { model, model_reason }
+}
+
+/** A follow-up's model: its session's, else Opus, as before #600. */
+export const followUpModel = ({
+    records,
+    session_id,
+}: {
+    records: JournalRecord[]
+    session_id: string
+}): SessionModel =>
+    sessionModel({ records, session_id }) ?? {
+        model: DEFAULT_MODEL,
+        model_reason: null,
+    }
+
+export const launchAgent = async ({
+    context,
+    action,
+}: {
+    context: BuildContext
+    action: Extract<BuildAction, { type: 'launch_agent' }>
+}) => {
+    const { ticket, role, prompt, may_edit_tests } = action
+    // The decision model's answer, journaled just before this step, picks
+    // a routed role's model; a reviewer is locked on Opus. A redo keeps
+    // the model its first try journaled.
+    const { model, model_reason } = launchPick({
+        records: context.journal.read(),
+        state: context.state,
+        config: context.config,
+        ticket,
+        role,
+        step: context.step,
+    })
+    context.journal.append({
+        kind: 'agent_started',
+        ticket,
+        role,
+        content: { role, prompt, follow_up_of: null, model, model_reason },
+    })
+    await runTurn({
+        context,
+        worktree: ticketWorktree({ state: context.state, ticket }),
+        ticket,
+        role,
+        may_edit_tests,
+        start: (cwd) =>
+            context.launcher.launch({
+                role,
+                ticket,
+                prompt,
+                cwd,
+                may_edit_tests,
+                config: context.config,
+                messaging: createAgentMessaging({
+                    journal: context.journal,
+                    ticket,
+                    role,
+                }),
+                model,
+            }),
+    })
+}
+
+export const followUpAgent = async ({
+    context,
+    action,
+}: {
+    context: BuildContext
+    action: Extract<BuildAction, { type: 'follow_up_agent' }>
+}) => {
+    const { ticket, role, session_id, message } = action
+    const snapshot = need({
+        value: context.state.snapshot?.tickets[ticket],
+        what: `snapshot of #${ticket}`,
+    })
+    const { model, model_reason } = followUpModel({
+        records: context.journal.read(),
+        session_id,
+    })
+    context.journal.append({
+        kind: 'agent_started',
+        ticket,
+        role,
+        content: {
+            role,
+            prompt: message,
+            follow_up_of: session_id,
+            model,
+            model_reason,
+        },
+    })
+    await runTurn({
+        context,
+        worktree: ticketWorktree({ state: context.state, ticket }),
+        ticket,
+        role,
+        may_edit_tests: mayEditTests({ role, ticket: snapshot }),
+        start: (cwd) =>
+            context.launcher.followUp({
+                session_id,
+                role,
+                ticket,
+                message,
+                cwd,
+                config: context.config,
+            }),
+    })
+}

package/engine/core/already-done.ts

@@ -3,7 +3,7 @@ import type {
     DoneCommit,
     TestWriterResult,
 } from '../agents/role-results'
-import type { TicketSnapshot } from '../intake/intake-schemas'
+import type { LeftOutTicket, TicketSnapshot } from '../intake/intake-schemas'
 
 /**
  * A ticket whose work is already on the base branch (#484): its
@@ -30,13 +30,56 @@ export type AlreadyDoneAction =
     /**
      * End the run with nothing to do: at intake (`already_done` is empty),
      * or once every ticket's work was already done and those are closed.
+     * At intake, `left_out` names the open tickets left for a person (#499).
      */
     | {
           type: 'finish_nothing_to_do'
           closed_tickets: number[]
           already_done: number[]
+          left_out?: LeftOutTicket[]
       }
 
+/**
+ * Check a test-writer's `already_done` evidence (#495) in the ticket's
+ * worktree before the ticket counts as done: each commit in `done_by` is on
+ * `base_sha` (the commit the worktree started from), every criterion names
+ * a test, and each named test exists and passes there. The engine journals
+ * the check as `already_done_checked`.
+ */
+export type CheckAlreadyDoneAction = {
+    type: 'check_already_done'
+    ticket: number
+    base_sha: string
+    criteria_ids: string[]
+    done_by: DoneCommit[]
+    criteria: CriterionTests[]
+}
+
+/**
+ * The step that checks a test-writer's `already_done` evidence (#495), on
+ * the commit the ticket's worktree started from.
+ *
+ * @example
+ * checkAlreadyDoneStep({ ticket, base_sha: 'b0', result })
+ * // { type: 'check_already_done', ticket: 11, base_sha: 'b0', criteria_ids: ['AC1'], done_by, criteria }
+ */
+export const checkAlreadyDoneStep = ({
+    ticket,
+    base_sha,
+    result,
+}: {
+    ticket: TicketSnapshot
+    base_sha: string
+    result: TestWriterResult
+}): CheckAlreadyDoneAction => ({
+    type: 'check_already_done',
+    ticket: ticket.number,
+    base_sha,
+    criteria_ids: ticket.criteria.map(({ id }) => id),
+    done_by: result.done_by,
+    criteria: result.criteria,
+})
+
 /** How many characters of a sha the engine shows. */
 const SHORT_SHA = 7
 

package/engine/core/build-action.ts

@@ -0,0 +1,214 @@
+/**
+ * The build step's actions (`BuildAction`), and what every ticket step
+ * shares: its arguments, a stuck action, and whether a ticket is a refactor.
+ */
+
+import type { AlreadyDoneAction, CheckAlreadyDoneAction } from './already-done'
+import type { FinalReviewAction } from './decide-final-review'
+import type { StuckAction } from './decide-stuck'
+
+import type { AgentRole, BadTest, CriterionTests } from '../agents/role-results'
+import type { TicketSnapshot } from '../intake/intake-schemas'
+import type {
+    ChangesetBump,
+    CommitStage,
+    GateTarget,
+    RejoinCause,
+    StuckReason,
+} from '../journal/journal-record'
+import type {
+    ReplayedRunNote,
+    ReplayedSnapshot,
+    TicketProgress,
+} from '../journal/replay'
+import { REFACTOR_LABEL } from '../tracker/tracker'
+
+/** The next build step for a run whose intake passed. */
+export type BuildAction =
+    /** Make the run branch, in its own worktree, from the base branch. */
+    | { type: 'create_run_branch'; spec_number: number; base_branch: string }
+    /** Make the ticket's worktree on a new branch from the run branch. */
+    | { type: 'create_ticket_worktree'; ticket: number; run_branch: string }
+    /**
+     * Install the dependencies from the lockfile, without changing it, in a
+     * new ticket worktree or the run branch's checkout (`ticket` is `null`),
+     * before any agent or gate runs there.
+     */
+    | {
+          type: 'install_dependencies'
+          target: GateTarget
+          ticket: number | null
+      }
+    /** Run the tests before any agent works, to know the old tests. */
+    | { type: 'run_baseline_tests'; ticket: number }
+    /**
+     * Take `from_ticket`'s baseline instead of running the tests again: both
+     * worktrees start from the same run-branch commit, `base_sha`.
+     */
+    | {
+          type: 'reuse_baseline_tests'
+          ticket: number
+          from_ticket: number
+          base_sha: string
+      }
+    /**
+     * Start a fresh agent session in the ticket's worktree with this prompt.
+     * `may_edit_tests` is true for the test-writer and for a refactor
+     * ticket's implementer; the launcher's guards enforce it.
+     */
+    | {
+          type: 'launch_agent'
+          ticket: number
+          role: AgentRole
+          prompt: string
+          may_edit_tests: boolean
+      }
+    /**
+     * Send a follow-up message, such as a failed check's output, to the agent
+     * session that is still open, in a fix loop.
+     */
+    | {
+          type: 'follow_up_agent'
+          ticket: number
+          role: AgentRole
+          session_id: string
+          message: string
+      }
+    /**
+     * Throw away every uncommitted change in the ticket's worktree, so a
+     * fresh test-writer starts clean after a bad test. With a `bad_test`, the
+     * engine itself found the test checks nothing (#581); without one, the
+     * implementer sent it back.
+     */
+    | { type: 'reset_ticket_worktree'; ticket: number; bad_test?: BadTest }
+    /**
+     * Prove every criterion has a test, new tests fail, old tests pass. A
+     * lone rerun (`exclusive`, #544) runs its tests alone.
+     */
+    | {
+          type: 'run_red_check'
+          ticket: number
+          criteria_ids: string[]
+          mapping: CriterionTests[]
+          exclusive?: true
+      }
+    /** Scan for leftovers, then commit everything in the worktree. */
+    | {
+          type: 'commit_ticket'
+          ticket: number
+          stage: CommitStage
+          message: string
+      }
+    /**
+     * Run the engine config's gates in the ticket worktree or on the run
+     * branch. A lone rerun (`exclusive`, #544) runs its tests alone.
+     */
+    | {
+          type: 'run_gates'
+          ticket: number
+          target: GateTarget
+          exclusive?: true
+      }
+    /** Replay the approved ticket's commits onto the run branch. */
+    | { type: 'join_run_branch'; ticket: number }
+    /**
+     * Put a joined ticket's whole change back on top of the run branch, as
+     * uncommitted changes in its worktree, after a clash or failed gates
+     * after joining. With `undo_first_sha`, first undo the join on the run
+     * branch, back to before that commit.
+     */
+    | {
+          type: 'rebase_ticket'
+          ticket: number
+          cause: RejoinCause
+          undo_first_sha: string | null
+      }
+    /**
+     * After a rebase, send the test the implementer called bad back to the
+     * ticket's test-writer to update (#489), keeping the implementer's code.
+     * The engine looks up what joined the run branch between `from_sha` and
+     * `base_sha` and journals it all as `tests_sent_back`.
+     */
+    | {
+          type: 'send_tests_back'
+          ticket: number
+          round: number
+          bad_test: BadTest
+          from_sha: string
+          base_sha: string
+      }
+    /** Remove these git worktrees at the end of the run; branches stay. */
+    | { type: 'remove_worktrees'; paths: string[] }
+    /** No ticket can move, and not every ticket has joined. */
+    | { type: 'invalid_journal'; reason: string }
+    /** Push the run branch to `origin`. */
+    | { type: 'push_run_branch'; ticket: number; branch: string }
+    /** The engine can't safely pick this ticket's next step by itself. */
+    | {
+          type: 'mark_stuck'
+          ticket: number
+          reason: StuckReason
+          detail: string
+      }
+    /**
+     * In a repo with changesets, commit the run's one changeset to the run
+     * branch and push it, before the PR (#461).
+     */
+    | {
+          type: 'write_changeset'
+          branch: string
+          bump: ChangesetBump
+          summary: string
+          message: string
+      }
+    /** Open the run's one pull request from the run branch. */
+    | {
+          type: 'open_pull_request'
+          head: string
+          base: string
+          title: string
+          body: string
+      }
+    /** Every ticket joined (or was skipped) and the PR is open. */
+    | {
+          type: 'done'
+          outcome: 'pr_opened'
+          pull_request: { number: number; url: string }
+      }
+    /** The final review of the whole run branch (`decide-final-review.ts`). */
+    | FinalReviewAction
+    /** The owner replied `stop`: the run ends without a PR; its branch stays. */
+    | { type: 'done'; outcome: 'stopped_by_user' }
+    /** Every ticket was skipped, so there is nothing to open a PR for. */
+    | { type: 'done'; outcome: 'all_skipped' }
+    /** Telling the owner about stuck work, and acting on their replies. */
+    | StuckAction
+    /** A ticket whose work was already on the base branch (#484). */
+    | AlreadyDoneAction
+    /** Check a test-writer's evidence that the work is already done (#495). */
+    | CheckAlreadyDoneAction
+
+/** Whether a ticket is a refactor ticket: it skips the test-writer and red check. */
+export const isRefactorTicket = ({
+    ticket,
+}: {
+    ticket: TicketSnapshot
+}): boolean => ticket.labels.includes(REFACTOR_LABEL)
+
+export type StepArgs = {
+    snapshot: ReplayedSnapshot
+    ticket: TicketSnapshot
+    progress: TicketProgress
+    /** The run notes a fresh agent gets (`newestRunNotes`). */
+    run_notes: ReplayedRunNote[]
+}
+
+export const stuck = ({
+    ticket,
+    reason,
+    detail,
+}: {
+    ticket: number
+    reason: StuckReason
+    detail: string
+}): BuildAction => ({ type: 'mark_stuck', ticket, reason, detail })