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

package/engine/core/pull-request-text.ts

@@ -3,10 +3,16 @@ import flatMap from 'lodash/flatMap'
 import uniq from 'lodash/uniq'
 
 import { alreadyDoneNote } from './already-done'
-import { shippedFindingsSection } from './final-review-text'
+import { evidenceSection } from './evidence-text'
+import {
+    freshFindingsSection,
+    shippedFindingsSection,
+} from './final-review-text'
+import { leftOutSections } from './left-out'
 import { newMemoriesSection } from './memory-text'
 import { reasonLine } from './stuck-text'
 
+import type { AgentRole, MergeDanger } from '../agents/role-results'
 import {
     EMPTY_FINAL_REVIEW,
     type FinalReviewState,
@@ -24,15 +30,95 @@ const SEVERITY_TEXT = {
 const fileText = (file: string | null): string =>
     file === null ? '' : ` (${file})`
 
+/**
+ * The longest Summary picture the PR body shows (#513); a longer one is
+ * clipped, so a runaway picture can't blow the body's budget.
+ */
+export const MAX_SUMMARY_PICTURE = 3_000
+
+const FENCE = '```'
+
+/**
+ * The Summary section (#513): the integration lens's picture, clipped to
+ * `MAX_SUMMARY_PICTURE` (a fence the clip leaves open is closed), or a
+ * note that there is none.
+ */
+const summarySection = (picture: string | null): string => {
+    if (picture === null) {
+        return '## Summary\n\nNot available: the final review gave no picture.'
+    }
+    if (picture.length <= MAX_SUMMARY_PICTURE) return `## Summary\n\n${picture}`
+    const clipped = picture.slice(0, MAX_SUMMARY_PICTURE)
+    const open = clipped.split(FENCE).length % 2 === 0
+    return `## Summary\n\n${clipped}${open ? `\n${FENCE}` : ''}\n\n… (clipped: the picture is over ${MAX_SUMMARY_PICTURE.toLocaleString('en-US')} characters)`
+}
+
+const DOOR_TEXT = { one_way: 'one-way', two_way: 'two-way' } as const
+
+/** The Merge danger section (#513), or a note that there is none. */
+const mergeDangerSection = (danger: MergeDanger | null): string =>
+    danger === null
+        ? '## Merge danger\n\nNot available: the final review gave no merge danger.'
+        : `## Merge danger\n\n- **Door:** ${DOOR_TEXT[danger.door]}: ${danger.door_reason}\n- **Blast radius:** ${danger.blast_radius}: ${danger.blast_radius_reason}`
+
+/** One line per role that ran out of turns, under `where`. */
+const outOfTurnsLines = ({
+    where,
+    counts,
+}: {
+    where: string
+    counts: Partial<Record<AgentRole, number>>
+}): string[] =>
+    Object.entries(counts).map(
+        ([role, times]) =>
+            `- ${where}: ${role}, ${times} ${times === 1 ? 'time' : 'times'}`
+    )
+
+/**
+ * The Out of turns section (#543): each ticket's roles whose agents ran out
+ * of turns, and how often, then the final review's. Empty with none.
+ */
+const outOfTurnsSection = ({
+    ticket_order,
+    tickets,
+    review,
+}: {
+    ticket_order: number[]
+    tickets: Record<number, TicketProgress>
+    review: FinalReviewState
+}): string => {
+    const lines = [
+        ...flatMap(ticket_order, (number) =>
+            outOfTurnsLines({
+                where: `#${number}`,
+                counts: tickets[number]?.out_of_turns ?? {},
+            })
+        ),
+        ...outOfTurnsLines({
+            where: 'the final review',
+            counts: review.out_of_turns,
+        }),
+    ]
+    return lines.length === 0
+        ? ''
+        : `## Out of turns\n\nThese agents ran out of turns: a sign the ticket may have been too big for one go.\n\n${lines.join('\n')}`
+}
+
 /**
  * The run's pull request title and body, from the snapshot, each ticket's
  * progress, and the final review: which tickets it closes (an already-done
- * one with the commits that did its work, #484), the tickets left
+ * one with the commits that did its work, #484), the tickets left for a
+ * person and the ones waiting on them (#499), the tickets left
  * out (skipped, and why), the assumptions agents made (from every round of
- * every agent on each ticket, and in the final review), the reviews' nits,
+ * every agent on each ticket, and in the final review), the tickets whose
+ * agents ran out of turns (#543), the reviews' nits,
  * the findings declined through "won't fix", and the memories the learner
  * added or updated (#370). A final review shipped
- * while stuck puts its open findings at the very top.
+ * while stuck puts its open findings at the very top. Right after the
+ * "Built by" line come the Summary picture and the Merge Danger (from the
+ * final review's integration lens, or "Not available" without them) and
+ * the Evidence that each ticket's new tests failed first and pass now
+ * (#513), then the tickets.
  *
  * @example
  * const { title, body } = pullRequestText({ snapshot, tickets, final_review })
@@ -127,23 +213,36 @@ export const pullRequestText = ({
             })
         ),
     ]
+    const stillOpen = review.fix?.findings ?? []
     const shipped =
         review.shipped && review.stuck !== null
             ? shippedFindingsSection({
-                  findings: review.fix?.findings ?? [],
+                  findings: stillOpen,
                   stuck: review.stuck,
+                  edits: review.shipped_edits,
               })
-            : ''
+            : review.fresh_started && stillOpen.length > 0
+              ? freshFindingsSection({ findings: stillOpen })
+              : ''
     const body = [
         shipped,
         `Built by the Luca engine from spec #${spec.number}.`,
+        summarySection(review.summary_picture),
+        mergeDangerSection(review.merge_danger),
+        evidenceSection({ snapshot, tickets }),
         `## Tickets\n\n${closes.join('\n')}`,
+        ...leftOutSections({ left_out: snapshot.left_out }),
         skipped.length === 0
             ? ''
             : `## Skipped tickets\n\nLeft out of this run. They stay open for a later run.\n\n${skipped.join('\n')}`,
         assumptions.length + finalAssumptions.length === 0
             ? ''
             : `## Assumptions\n\nCalls agents made by themselves. Please check them.\n\n${[...assumptions, ...finalAssumptions].join('\n')}`,
+        outOfTurnsSection({
+            ticket_order: snapshot.ticket_order,
+            tickets,
+            review,
+        }),
         nits.length === 0
             ? ''
             : `## Nits\n\nSmall things the ticket reviews and the final review noted but did not send back.\n\n${nits.join('\n')}`,
@@ -158,6 +257,156 @@ export const pullRequestText = ({
     }
 }
 
+/**
+ * What the engine keeps the PR body, and each of its PR comments, under
+ * (#508): a margin below GitHub's limit of 65,536 characters.
+ */
+export const PULL_REQUEST_BUDGET = 60_000
+
+/** The file in the run folder the PR's full text is saved to first (#508). */
+export const PULL_REQUEST_FILE = 'pull-request.md'
+
+/**
+ * The body's long parts, which move into PR comments when the body is over
+ * its budget. The rest (open findings, the Summary and Merge danger, the
+ * tickets it closes, and the ones left out) always stays in the body.
+ */
+const MOVABLE_HEADINGS = [
+    '## Evidence',
+    '## Assumptions',
+    '## Out of turns',
+    '## Nits',
+    '## Declined findings',
+    '## New memories',
+]
+
+const CLIPPED = `\n\n… (clipped: the full text is in the run folder's \`${PULL_REQUEST_FILE}\`)`
+
+/** Room kept in each comment for its heading and the engine's marker. */
+const COMMENT_ROOM = 200
+
+/** `text`, clipped to stay under `limit` characters. */
+const clip = ({ text, limit }: { text: string; limit: number }): string =>
+    text.length < limit
+        ? text
+        : `${text.slice(0, limit - CLIPPED.length - 1)}${CLIPPED}`
+
+const isMovable = (section: string): boolean =>
+    MOVABLE_HEADINGS.some(
+        (heading) => section === heading || section.startsWith(`${heading}\n`)
+    )
+
+/**
+ * A section cut into pieces under `limit`, between its list items; each
+ * piece after the first repeats its heading. An item over the limit alone
+ * is clipped.
+ */
+const sectionPieces = ({
+    section,
+    limit,
+}: {
+    section: string
+    limit: number
+}): string[] => {
+    if (section.length < limit) return [section]
+    const heading = section.split('\n', 1)[0] ?? ''
+    const pieces: string[] = []
+    let current = ''
+    for (const item of section.split(/\n(?=- )/)) {
+        const joined = current === '' ? item : `${current}\n${item}`
+        if (joined.length < limit) {
+            current = joined
+            continue
+        }
+        if (current !== '') pieces.push(current)
+        current = clip({ text: `${heading} (continued)\n\n${item}`, limit })
+    }
+    return current === '' ? pieces : [...pieces, current]
+}
+
+/** Pieces packed into as few texts under `limit` as they fit in. */
+const packed = ({
+    pieces,
+    limit,
+}: {
+    pieces: string[]
+    limit: number
+}): string[] =>
+    pieces.reduce<string[]>((texts, piece) => {
+        const last = texts.at(-1)
+        if (last !== undefined && `${last}\n\n${piece}`.length < limit) {
+            return [...texts.slice(0, -1), `${last}\n\n${piece}`]
+        }
+        return [...texts, piece]
+    }, [])
+
+/**
+ * The PR body as sent to GitHub, and the PR comments posted after it, from
+ * its full text (#508). A body under `budget` goes as it is. A longer one
+ * keeps its essentials (open findings, the Summary and Merge danger, the
+ * tickets it closes, and the tickets left out), and its long parts (the
+ * Evidence, assumptions, out of turns, nits, declined findings, new
+ * memories) as long as
+ * they fit beside every essential (#513); the rest moves into PR
+ * comments, each under the budget, cut between list items, and the body
+ * says so. Whatever is still too long is clipped, pointing at the full
+ * text in the run folder.
+ *
+ * @example
+ * fitPullRequestBody({ body: full })
+ * // { body: '...## More in the PR comments\n\n...', comments: ['## Assumptions\n\n...'] }
+ */
+export const fitPullRequestBody = ({
+    body,
+    budget = PULL_REQUEST_BUDGET,
+}: {
+    body: string
+    budget?: number
+}): { body: string; comments: string[] } => {
+    if (body.length < budget) return { body, comments: [] }
+    const note = (moved: string[]) =>
+        `## More in the PR comments\n\nThis PR's text is too long for its body, so its ${moved.map((section) => section.split('\n', 1)[0]?.replace('## ', '').toLowerCase()).join(', ')} are in the PR comments below. The full text is in the run folder's \`${PULL_REQUEST_FILE}\`.`
+    const sections = body.split(/\n\n(?=## )/)
+    // Essentials after a long part still need their room (#513).
+    const essentials = sections.filter((section) => !isMovable(section))
+    const kept: string[] = []
+    const kept_long: string[] = []
+    const moved: string[] = []
+    for (const section of sections) {
+        if (!isMovable(section)) {
+            kept.push(section)
+            continue
+        }
+        const fits =
+            moved.length === 0 &&
+            [...essentials, ...kept_long, section, note([section])].join('\n\n')
+                .length < budget
+        if (fits) {
+            kept.push(section)
+            kept_long.push(section)
+        } else moved.push(section)
+    }
+    const comments = packed({
+        pieces: moved.flatMap((section) =>
+            sectionPieces({ section, limit: budget - COMMENT_ROOM })
+        ),
+        limit: budget - COMMENT_ROOM,
+    })
+    return {
+        body: clip({
+            text: [...kept, ...(moved.length === 0 ? [] : [note(moved)])].join(
+                '\n\n'
+            ),
+            limit: budget,
+        }),
+        comments: comments.map((text, index) =>
+            comments.length === 1
+                ? text
+                : `**More of this PR's notes (${index + 1} of ${comments.length})**\n\n${text}`
+        ),
+    }
+}
+
 /** One open ticket of the spec, as the tracker lists it. */
 type OpenTicket = { number: number; title: string }
 

package/engine/core/repo-wait-text.ts

@@ -0,0 +1,81 @@
+/**
+ * The texts of the repo wait (#615): the spec issue's comment when the run
+ * starts waiting for earlier runs on its repo, and when it is stuck on them.
+ */
+import type { RepoWaitRun } from './decide-repo-wait'
+
+/** The runs, as a list of lines. */
+const runLines = (runs: RepoWaitRun[]): string =>
+    runs
+        .map(
+            ({ run_id, spec }) =>
+                `- run \`${run_id}\`${spec === null ? ' (a demo)' : ` (spec #${spec})`}`
+        )
+        .join('\n')
+
+/**
+ * The comment on the spec issue when the run waits for earlier runs on its
+ * repo: which ones, and that it goes on by itself.
+ *
+ * @example
+ * repoWaitComment({ runs: [{ run_id: 'run-a', spec: 7 }] })
+ * // '**The run waits for another run on this repo**\n\n- run `run-a` (spec #7)\n\n...'
+ */
+export const repoWaitComment = ({ runs }: { runs: RepoWaitRun[] }): string =>
+    [
+        '**The run waits for another run on this repo**',
+        runLines(runs),
+        'Two runs on one repo slow each other down, so this one starts once none of these is going. It checks every minute and goes on by itself. After 24 hours it stops and asks you. To run two at once on purpose, start a run with `luca-run --alongside`.',
+    ].join('\n\n')
+
+/**
+ * Why the run is stuck on its repo wait, in one line, naming the `ps`
+ * failure when the wait couldn't check whether those runs are going (#624).
+ *
+ * @example
+ * repoBusyDetail({ runs: [{ run_id: 'run-a', spec: 7 }], ps_error: null })
+ * // 'The run waited 24 hours for an earlier run on this repo: run-a (spec #7).'
+ */
+export const repoBusyDetail = ({
+    runs,
+    ps_error = null,
+}: {
+    runs: RepoWaitRun[]
+    ps_error?: string | null
+}): string => {
+    const named = runs
+        .map(
+            ({ run_id, spec }) =>
+                `${run_id}${spec === null ? ' (a demo)' : ` (spec #${spec})`}`
+        )
+        .join(', ')
+    const ps =
+        ps_error === null
+            ? ''
+            : ` Luca couldn't list the processes (${ps_error}), so it couldn't tell whether those runs are still going.`
+    return `The run waited 24 hours for an earlier run on this repo: ${named}.${ps}`
+}
+
+/**
+ * The comment on the spec issue when the run is stuck after 24 hours of
+ * its repo wait (`repo_busy`): why, and the replies `retry` and `stop`.
+ *
+ * @example
+ * repoBusyStuckComment({ detail })
+ * // '**The run is stuck: another run on this repo is still going**\n\nWhy: ...'
+ */
+export const repoBusyStuckComment = ({ detail }: { detail: string }): string =>
+    [
+        '**The run is stuck: another run on this repo is still going**',
+        [
+            `Why: ${detail}`,
+            'Nothing has started yet: no ticket was read and no worktree made.',
+        ].join('\n'),
+        [
+            'Reply with one word on this issue:',
+            '- `retry`: wait up to 24 hours more, then go on once no earlier run on the repo is going.',
+            '- `stop`: end the run. Start it again later, or with `luca-run --alongside` to run both at once.',
+            '',
+            'Only the spec owner counts.',
+        ].join('\n'),
+    ].join('\n\n')

package/engine/core/review-text.ts

@@ -6,6 +6,7 @@ import type {
     ReplayedGates,
     ReviewFix,
     TicketProgress,
+    WriterRole,
 } from '../journal/replay'
 import { clipOutput } from '../shell/run-command'
 
@@ -59,6 +60,7 @@ export const responseText = ({
 }): string => {
     const answer = responses.find(({ finding_id }) => finding_id === finding.id)
     if (answer === undefined) return '  Fixer: no answer.'
+    // An `other_role` the other role never answered stands as "won't fix".
     return answer.response === 'fixed'
         ? `  Fixer: fixed. ${answer.reason}`.trimEnd()
         : `  Fixer: WON'T FIX. Reason: ${answer.reason || 'none given'}`
@@ -161,10 +163,62 @@ export const reviewSections = ({
 
 /** How a review fixer answers each finding it got. */
 export const FIX_RULES =
-    'For EACH finding, answer in "finding_responses": "fixed", or "wont_fix" with your reason if the finding is wrong. ' +
+    'For EACH finding, answer in "finding_responses": "fixed", or "wont_fix" with your reason if the finding is wrong, ' +
+    'or "other_role" with your reason if the other writer role must fix it, or must fix it too ' +
+    '(a code fix that needs a test, or a test that needs a non-test helper the test-writer may not write). ' +
+    'Fix your part first; the engine then sends an "other_role" finding to a fresh agent of the other role, before the gates. ' +
     'A fresh reviewer rules on every "won\'t fix", so give a reason that stands on its own. ' +
     'The engine runs the gates again and then a fresh reviewer checks your changes.'
 
+/** How the other role answers the findings handed to it (#616). */
+const HANDOFF_RULES =
+    'For EACH finding, answer in "finding_responses": "fixed", or "wont_fix" with your reason. ' +
+    'Your answer is final: another "other_role" counts as "wont_fix", and a fresh reviewer rules on it. ' +
+    'The engine runs the gates again and then a fresh reviewer checks the changes.'
+
+const OTHER_WRITER: Record<WriterRole, WriterRole> = {
+    'test-writer': 'implementer',
+    implementer: 'test-writer',
+}
+
+/**
+ * The findings the other writer role answered `other_role`, handed to
+ * `role` (#616), each with that fixer's reason, and how to answer them.
+ * `heading` names the fix round.
+ *
+ * @example
+ * const section = handoffSection({ fix, role: 'test-writer', heading: 'Review fix round 1' })
+ */
+export const handoffSection = ({
+    fix,
+    role,
+    heading,
+}: {
+    fix: Pick<ReviewFix, 'findings' | 'responses' | 'handed_off'>
+    role: WriterRole
+    heading: string
+}): string => {
+    const ids = fix.handed_off[role] ?? []
+    const other = OTHER_WRITER[role]
+    const findings = fix.findings
+        .filter(({ id }) => ids.includes(id))
+        .map((finding) => {
+            const answer = fix.responses.find(
+                ({ finding_id, response }) =>
+                    finding_id === finding.id && response === 'other_role'
+            )
+            return `${findingLine(finding)}\n  The ${other} passed it on: ${answer?.reason || 'no reason given'}`
+        })
+        .join('\n')
+    return [
+        `## ${heading}: findings the ${other} passed to you`,
+        `The ${other} answered these findings "other_role": they need the ${role}'s work, instead of or as well as its own. ` +
+            `Its own fixes are in the worktree, uncommitted. Do your part for these findings only. Keep to your role's rules.`,
+        findings,
+        HANDOFF_RULES,
+    ].join('\n\n')
+}
+
 /**
  * The findings a review fixer gets: the test findings for a fresh
  * test-writer, or the code findings for the implementer.

package/engine/core/run-crash-recovery-helpers.ts

@@ -0,0 +1,16 @@
+import type { JournalRecord } from '../journal/journal-record'
+
+/**
+ * Helper shared by the crash-recovery end-to-end tests
+ * (`run-crash-recovery.e2e.test.ts` and
+ * `run-crash-recovery-git.e2e.test.ts`).
+ */
+
+export const ofKind = <Kind extends JournalRecord['kind']>(
+    records: JournalRecord[],
+    kind: Kind
+): Extract<JournalRecord, { kind: Kind }>[] =>
+    records.filter(
+        (record): record is Extract<JournalRecord, { kind: Kind }> =>
+            record.kind === kind
+    )

package/engine/core/run-session-close-helpers.ts

@@ -0,0 +1,96 @@
+import { expect } from 'bun:test'
+
+import {
+    createScriptedLauncher,
+    type ScriptedLauncher,
+    type ScriptedTurn,
+} from '../agents/scripted-launcher'
+import type { JournalRecord } from '../journal/journal-record'
+import {
+    CLEAN_LENS_TURNS,
+    EMPTY_LEARNER_TURN,
+    IMPLEMENTER_RESULT,
+    SUM_TEST,
+} from '../testing/practice-repo'
+
+/**
+ * Helpers shared by the end-to-end tests for closing finished agents'
+ * sessions (`run-session-close.e2e.test.ts`,
+ * `run-session-close-ticket-ends.e2e.test.ts`, and
+ * `run-session-close-interruptions.e2e.test.ts`).
+ */
+
+/**
+ * A scripted launcher with these turns, then a clean final review of spec
+ * #10 and an empty learner to fall back on.
+ */
+export const scriptedWith = (turns: ScriptedTurn[]): ScriptedLauncher =>
+    createScriptedLauncher({
+        turns: [...turns, ...CLEAN_LENS_TURNS(10), EMPTY_LEARNER_TURN(10)],
+    })
+
+type SessionOf = { role: string | null; session_id: string }
+
+export const byId = (a: SessionOf, b: SessionOf) =>
+    a.session_id.localeCompare(b.session_id)
+
+/** Every session a scripted launcher started, with its agent's role. */
+export const launchedBy = (launcher: ScriptedLauncher): SessionOf[] =>
+    launcher
+        .launches()
+        .filter(({ kind }) => kind === 'launch')
+        .map(({ role, session_id }) => ({ role, session_id }))
+
+/** Every session close the journal records, with its agent's role. */
+export const closedIn = (records: JournalRecord[]): SessionOf[] =>
+    records
+        .flatMap((record) =>
+            record.kind === 'agent_session_closed'
+                ? [{ role: record.role, session_id: record.content.session_id }]
+                : []
+        )
+        .toSorted(byId)
+
+/** The journal's close of `session_id`, if any. */
+export const closeOf = (records: JournalRecord[], session_id: string) =>
+    records.find(
+        (record) =>
+            record.kind === 'agent_session_closed' &&
+            record.content.session_id === session_id
+    )
+
+/**
+ * No session the launcher started is still open, and the journal records
+ * each one's close exactly once.
+ */
+export const expectEveryoneClosed = ({
+    launcher,
+    records,
+}: {
+    launcher: ScriptedLauncher
+    records: JournalRecord[]
+}) => {
+    expect(launcher.openSessions()).toEqual([])
+    expect(closedIn(records)).toEqual(launchedBy(launcher).toSorted(byId))
+}
+
+/** A ticket's launches and follow-ups, in order. */
+export const callsOf = (launcher: ScriptedLauncher, ticket: number) =>
+    launcher.launches().filter((call) => call.ticket === ticket)
+
+/** A sum test that defines sum itself, so it passes before any code exists. */
+export const PASSING_SUM_TEST = SUM_TEST.replace(
+    "import { sum } from './sum'",
+    'const sum = ({ numbers }: { numbers: number[] }) =>\n    numbers.reduce((a, b) => a + b, 0)'
+)
+
+/** An implementer of `ticket` whose code fails the tests. */
+export const wrongImplementer = (ticket: number): ScriptedTurn => ({
+    role: 'implementer',
+    ticket,
+    files: {
+        'src/sum.ts': 'export const sum = (): number => 42\n',
+        'src/index.ts': "export { sum } from './sum'\n",
+    },
+    result: IMPLEMENTER_RESULT,
+})