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

package/engine/core/run-start.ts

@@ -0,0 +1,148 @@
+/**
+ * A run's first records: `run_started`, and on a resume `engine_resumed`
+ * and what came of taking the repo's config again.
+ */
+import values from 'lodash/values'
+
+import { configChanges } from '../config/config-reload'
+import type {
+    EngineConfig,
+    LoadEngineConfigResult,
+} from '../config/engine-config'
+import { lucaVersion } from '../config/luca-version'
+import { configProblems } from '../intake/intake-checks'
+import type { Journal } from '../journal/journal'
+import type { JournalRecord } from '../journal/journal-record'
+import { replayRun } from '../journal/replay'
+
+/**
+ * Starts a run by writing its first record. The spec and config it names are
+ * what every later step of the run works from; the Luca version it names is
+ * the one the run started on. A run started `alongside` journals right away
+ * that it skips the repo wait (`repo_wait_skipped`, #615).
+ */
+export const startRun = ({
+    journal,
+    spec_number,
+    config,
+    base_branch,
+    memory,
+    repo,
+    alongside,
+    luca_version = lucaVersion(),
+}: {
+    journal: Journal
+    spec_number: number
+    config: EngineConfig
+    /** The branch the run branch starts from. Defaults to `main`. */
+    base_branch?: string
+    /**
+     * Turns memory on (#370), with the project's vault (`null` searches only
+     * `default`). Leave it out for a run without memory.
+     */
+    memory?: { project_vault: string | null }
+    /** The repo the run is on, so a resume can find it. Defaults to `null`. */
+    repo?: string | null
+    /** Never wait for another run on the repo (`luca-run --alongside`). */
+    alongside?: boolean
+    /** Luca's version. Defaults to the engine's own. */
+    luca_version?: string
+}): JournalRecord => {
+    const started = journal.append({
+        kind: 'run_started',
+        ticket: null,
+        role: null,
+        content: {
+            spec_number,
+            config,
+            base_branch,
+            memory: memory ?? null,
+            repo,
+            luca_version,
+        },
+    })
+    if (alongside === true) {
+        journal.append({
+            kind: 'repo_wait_skipped',
+            ticket: null,
+            role: null,
+            content: {},
+        })
+    }
+    return started
+}
+
+/**
+ * Records that the engine started again on a run's journal, on Luca's
+ * version `luca_version`, before its first step.
+ */
+export const recordResume = ({
+    journal,
+    luca_version = lucaVersion(),
+}: {
+    journal: Journal
+    /** Luca's version. Defaults to the engine's own. */
+    luca_version?: string
+}): JournalRecord =>
+    journal.append({
+        kind: 'engine_resumed',
+        ticket: null,
+        role: null,
+        content: { luca_version },
+    })
+
+/**
+ * On a resume, takes the repo's config again (#516), just read as
+ * `loaded`, and journals what came of it, right after `recordResume`:
+ *
+ * - a `config_reloaded` with the build fields (`RELOADED_FIELDS`) that
+ *   changed, old to new, which replay puts on the run's config;
+ * - nothing, when none changed (frozen fields never count, see
+ *   `FROZEN_FIELDS`);
+ * - a `config_reload_refused` with the reason, when the file is missing,
+ *   not JSON, not a valid config, or one intake would refuse
+ *   (`configProblems`, on the run's tickets). The run keeps its config.
+ *
+ * Never throws for a bad file: the run always goes on. Returns the record
+ * it appended, or `null`. A journal with no config yet (not a run) gets
+ * nothing; the decision step says what is wrong with it.
+ *
+ * @example
+ * recordResume({ journal })
+ * const reload = recordConfigReload({ journal, loaded: await loadEngineConfig({ repo_root }) })
+ */
+export const recordConfigReload = ({
+    journal,
+    loaded,
+}: {
+    journal: Journal
+    loaded: LoadEngineConfigResult
+}): JournalRecord | null => {
+    const state = replayRun({ records: journal.read() })
+    if (state.config === null) return null
+    const refuse = (reason: string): JournalRecord =>
+        journal.append({
+            kind: 'config_reload_refused',
+            ticket: null,
+            role: null,
+            content: { reason },
+        })
+    if (!loaded.ok) return refuse(loaded.error)
+    const problems = configProblems({
+        config: loaded.config,
+        tickets: values(state.snapshot?.tickets ?? {}),
+    })
+    if (problems.length > 0) return refuse(problems.join('\n'))
+    const changes = configChanges({
+        current: state.config,
+        next: loaded.config,
+    })
+    return changes.length === 0
+        ? null
+        : journal.append({
+              kind: 'config_reloaded',
+              ticket: null,
+              role: null,
+              content: { changes },
+          })
+}

package/engine/core/run-stuck-text.ts

@@ -0,0 +1,86 @@
+/**
+ * The comments on the spec issue when the whole run is stuck: on its run
+ * budget, or on a pull request that didn't open.
+ */
+
+/** A token count with thousands separators, such as `50,000`. */
+const tokensText = (tokens: number): string =>
+    String(tokens).replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+
+/**
+ * Why the run is stuck on its budget, in one line.
+ *
+ * @example
+ * runBudgetDetail({ tokens: 50_100, budget: 50_000 })
+ * // 'The run used 50,100 tokens of its run budget of 50,000.'
+ */
+export const runBudgetDetail = ({
+    tokens,
+    budget,
+}: {
+    tokens: number
+    budget: number
+}): string =>
+    `The run used ${tokensText(tokens)} tokens of its run budget of ${tokensText(budget)}.`
+
+/**
+ * The comment on the spec issue when the whole run is stuck on its run
+ * budget: why, how big one budget is, and the replies `retry` and `stop`
+ * (never `skip` or `ship`).
+ *
+ * @example
+ * runStuckComment({ detail, budget: 9_000_000 })
+ * // '**The run is stuck: it used up its run budget**\n\nWhy: ...'
+ */
+export const runStuckComment = ({
+    detail,
+    budget,
+}: {
+    detail: string
+    /** One full run budget. */
+    budget: number
+}): string =>
+    [
+        '**The run is stuck: it used up its run budget**',
+        [
+            `Why: ${detail}`,
+            `One run budget is ${tokensText(budget)} tokens (input, output, and cache writes; cache reads don't count). A repo changes it with \`run_budget_tokens\` in \`.luca/config.json\`.`,
+            'Nothing new starts until you reply. Other stuck work waits for its reply until the run carries on.',
+        ].join('\n'),
+        [
+            'Reply with one word on this issue:',
+            `- \`retry\`: add half a run budget (${tokensText(Math.floor(budget / 2))} tokens) and carry on where it stopped. \`retry +500k\` or \`retry +3M\` adds the amount you name instead.`,
+            '- `stop`: end the run without a PR. The branch is kept.',
+            '',
+            'Only the spec owner counts.',
+        ].join('\n'),
+    ].join('\n\n')
+
+/**
+ * The comment on the spec issue when the run is stuck because its pull
+ * request didn't open (#508): `gh`'s error, where the PR's full text is
+ * saved, and the replies `retry` and `stop`.
+ *
+ * @example
+ * pullRequestStuckComment({ detail: 'gh pr create failed (exit code 1): ...' })
+ * // "**The run is stuck: its pull request didn't open**\n\nWhy: ..."
+ */
+export const pullRequestStuckComment = ({
+    detail,
+}: {
+    detail: string
+}): string =>
+    [
+        "**The run is stuck: its pull request didn't open**",
+        [
+            `Why: ${detail}`,
+            `The run branch is pushed, and the PR's full text is saved in the run folder as \`pull-request.md\`.`,
+        ].join('\n'),
+        [
+            'Reply with one word on this issue:',
+            '- `retry`: try to open the PR again. A PR already open from the run branch, such as one you opened by hand, is reused, never opened twice.',
+            '- `stop`: end the run without a PR. The branch is kept.',
+            '',
+            'Only the spec owner counts.',
+        ].join('\n'),
+    ].join('\n\n')

package/engine/core/schedule-rules.ts

@@ -0,0 +1,193 @@
+/**
+ * What the scheduler knows of an action: its key, its step's name, its
+ * ticket and role, and which actions wait, run slow, or use the run branch.
+ */
+import has from 'lodash/has'
+import partition from 'lodash/partition'
+
+import type { EngineAction } from './decide'
+import { isFinalReviewAction } from './decide-final-review'
+
+import type { JournalRecord } from '../journal/journal-record'
+import { crashesAfter, type CrashCounts } from '../journal/step-records'
+
+/**
+ * The ticket an action works on, or `null` for a run-level action. The
+ * plan's actions are the whole run's, whichever ticket hit the limit; a
+ * ticket's usage record is that ticket's. Reading and taking replies is
+ * the run's too (see `keyOf`).
+ */
+export const ticketOf = (action: EngineAction): number | null => {
+    switch (action.type) {
+        case 'start_limit_wait':
+        case 'wait_for_limit':
+        case 'stop_for_billing':
+        case 'wait_for_reply':
+        case 'take_reply':
+        case 'ignore_reply':
+            return null
+        case 'record_usage':
+            return action.usage.ticket
+        default:
+            return 'ticket' in action && typeof action.ticket === 'number'
+                ? action.ticket
+                : null
+    }
+}
+
+/**
+ * Replies are read and taken beside the other steps, one at a time, under
+ * their own key: waiting for a reply never holds a ticket up.
+ */
+const REPLY_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
+    'wait_for_reply',
+    'take_reply',
+    'ignore_reply',
+])
+
+/**
+ * The scheduler's key for an action: at most one action per key runs at a
+ * time. Reading and taking replies has its own (`replies`). Each lens has
+ * its own (`lens:<lens>`), so the five lenses review at once; the final review's other steps share `final`; a ticket's steps its
+ * number; and the run's own steps `run`, which only ever run alone.
+ */
+export const keyOf = (action: EngineAction): string => {
+    if (REPLY_ACTIONS.has(action.type)) return 'replies'
+    // A search waits under the key of the step it comes before: its
+    // ticket's, the final review's, or (the run's start) the run's.
+    if (action.type === 'recall_memories') {
+        if (action.ticket !== null) return String(action.ticket)
+        return action.point === 'run_start' ? 'run' : 'final'
+    }
+    if (action.type === 'launch_lens') return `lens:${action.lens}`
+    if (isFinalReviewAction(action)) return 'final'
+    const ticket = ticketOf(action)
+    return ticket === null ? 'run' : String(ticket)
+}
+
+/** Actions that are an agent's turn: their step names the role. */
+const AGENT_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
+    'launch_agent',
+    'follow_up_agent',
+    'launch_lens',
+    'launch_final_fixer',
+    'follow_up_final_fixer',
+])
+
+/** The agent role of an agent's turn (the learner's is `learner`), else `null`. */
+export const agentRoleOf = (action: EngineAction): string | null => {
+    if (action.type === 'launch_learner') return 'learner'
+    return AGENT_ACTIONS.has(action.type) &&
+        'role' in action &&
+        action.role !== null
+        ? action.role
+        : null
+}
+
+/**
+ * A step's name in the journal: its action type, plus `:<role>` for an
+ * agent's turn, such as `follow_up_agent:implementer`.
+ *
+ * @example
+ * stepOf({ type: 'run_gates', ticket: 11, target: 'ticket' }) // 'run_gates'
+ */
+export const stepOf = (action: EngineAction): string => {
+    const role = agentRoleOf(action)
+    return role === null ? action.type : `${action.type}:${role}`
+}
+
+/**
+ * Waits get no step records: a crash during one is no step's fault, and a
+ * restarted engine just waits again (a limit wait until the same time).
+ */
+export const WAIT_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
+    'wait_for_reply',
+    'wait_for_limit',
+    'wait_for_usage_line',
+    'wait_for_repo',
+])
+
+/**
+ * Steps that can run for minutes: installs, test runs, and agents' turns.
+ * The board hears of them as they start, so a run never looks frozen.
+ */
+export const SLOW_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
+    ...AGENT_ACTIONS,
+    'launch_learner',
+    'install_dependencies',
+    'run_baseline_tests',
+    'run_red_check',
+    'check_already_done',
+    'run_gates',
+    'run_final_gates',
+    'run_final_slow_tests',
+])
+
+/**
+ * Actions that read or move the run branch. At most one runs at a time, so
+ * joins, their gates, pushes, and new worktrees see one run branch. The
+ * final review's fixers, gates, slow tests (#563), commit, and push work in
+ * the run branch's worktree; its lenses only read it. Nothing writes there
+ * while a lens runs, though: its after-turn guard judges that worktree, so
+ * the slow tests wait for round 1's lenses (see `decideFinalReview`).
+ */
+export const usesRunBranch = (action: EngineAction): boolean => {
+    switch (action.type) {
+        case 'create_ticket_worktree':
+        case 'join_run_branch':
+        case 'push_run_branch':
+        case 'rebase_ticket':
+        case 'start_final_review':
+        case 'launch_final_fixer':
+        case 'follow_up_final_fixer':
+        case 'run_final_gates':
+        case 'run_final_slow_tests':
+        case 'commit_final_fix':
+        case 'push_final_fixes':
+        case 'write_changeset':
+        case 'ship_final_review':
+        case 'undo_join':
+        case 'retry_ticket':
+            return true
+        case 'run_gates':
+        case 'install_dependencies':
+            return action.target === 'run_branch'
+        // It puts back a run branch a join crashes cut off too often left.
+        case 'mark_stuck':
+            return action.reason === 'crashed'
+        default:
+            return false
+    }
+}
+
+/** The crash counts per key, from the journal's records. */
+export const crashesIn = (records: JournalRecord[]): CrashCounts =>
+    records.reduce<CrashCounts>(
+        (crashes, record) => crashesAfter({ crashes, record }),
+        {}
+    )
+
+/**
+ * The actions on keys a crash cut a step off first, in their order, then
+ * the rest: a step a crash cut off (or the stop for it) starts before any
+ * other, so a half-done change to the run branch, such as a join, is put
+ * right before another step reads the run branch.
+ */
+export const redosFirst = ({
+    actions,
+    crashes,
+}: {
+    actions: EngineAction[]
+    crashes: CrashCounts
+}): EngineAction[] => {
+    const [redos, rest] = partition(actions, (action) =>
+        has(crashes, keyOf(action))
+    )
+    return [...redos, ...rest]
+}
+
+/** The session a follow-up goes to, if the action is one. */
+export const followUpSessionOf = (action: EngineAction): string[] =>
+    action.type === 'follow_up_agent' || action.type === 'follow_up_final_fixer'
+        ? [action.session_id]
+        : []

package/engine/core/stuck-detail-text.ts

@@ -0,0 +1,89 @@
+/**
+ * The stuck details for a ticket that needs a change only the owner may make, or
+ * whose test was sent back as bad.
+ */
+import upperFirst from 'lodash/upperFirst'
+
+import type { AgentRole, BadTest, BadTestSource } from '../agents/role-results'
+import { clipOutput } from '../shell/run-command'
+
+/**
+ * The detail of a ticket or the final review stuck on a change only the
+ * owner may make (#617): the file, why, and what to do. It says "test setup
+ * file" only when the file is one of the config's.
+ */
+export const setupChangeDetail = ({
+    role,
+    file,
+    reason,
+    setup_files,
+}: {
+    role: AgentRole
+    file: string
+    reason: string
+    /** The config's test setup files. */
+    setup_files: string[]
+}): string =>
+    `The ${role} needs a change only you may make, to \`${file || 'unnamed'}\`: ${reason || 'no reason given'}\n` +
+    `${setup_files.includes(file) ? 'It is a test setup file, which agents may never change.' : 'No agent may make it.'} Make the change yourself in the worktree, then reply retry.`
+
+/**
+ * A test sent back as bad, for a stuck detail: its file and name, then the
+ * reason (the implementer's, or the engine's finding that it checks nothing,
+ * #581), clipped like other outputs (#490). "no reason given" only when
+ * there is none.
+ *
+ * @example
+ * badTestDetail({ bad_test: { file: 'src/sum.test.ts', name: 'sum > adds', reason: 'Wrong sum.' } })
+ * // 'src/sum.test.ts > sum > adds: Wrong sum.'
+ */
+export const badTestDetail = ({
+    bad_test,
+}: {
+    bad_test: BadTest | null
+}): string => {
+    const reason =
+        bad_test === null || bad_test.reason.trim() === ''
+            ? 'no reason given'
+            : clipOutput({ text: bad_test.reason })
+    const where =
+        bad_test === null
+            ? ''
+            : [bad_test.file, bad_test.name].filter(Boolean).join(' > ')
+    return where === '' ? reason : `${where}: ${reason}`
+}
+
+/** What each source did when it sent a test back as bad (#581). */
+const BOUNCE_CLAUSES: Record<BadTestSource, string> = {
+    implementer: 'the implementer sent a test back as bad',
+    engine: 'the engine found a mapped test that checks nothing',
+}
+
+/**
+ * The start of a stuck detail for a test sent back as bad a second time
+ * (#581): who sent the first back, and who the second. A test can be sent
+ * back by the implementer, or by the engine when a mapped test passes with no
+ * `expect()`; the two share one cap, so the second may have another source
+ * than the first.
+ *
+ * @example
+ * badTestTwiceText({ earlier: 'engine', latest: 'implementer' })
+ * // 'The engine found a mapped test that checks nothing, and then, after a
+ * // fresh test-writer, the implementer sent a test back as bad'
+ */
+export const badTestTwiceText = ({
+    earlier,
+    latest,
+}: {
+    earlier: BadTestSource
+    latest: BadTestSource
+}): string => {
+    if (earlier === latest) {
+        return latest === 'engine'
+            ? 'A mapped test still checks nothing after a fresh test-writer'
+            : 'The implementer sent a test back as bad a second time'
+    }
+    return upperFirst(
+        `${BOUNCE_CLAUSES[earlier]}, and then, after a fresh test-writer, ${BOUNCE_CLAUSES[latest]}`
+    )
+}

package/engine/core/stuck-format.ts

@@ -0,0 +1,22 @@
+/**
+ * Formatting the stuck comments share: a clipped code fence for error text,
+ * and counted words.
+ */
+import max from 'lodash/max'
+
+/** Longest error text a comment or prompt quotes. */
+const DETAIL_MAX = 3000
+
+/** A code fence longer than any run of backticks in `text`. */
+export const fenced = (text: string): string => {
+    const longest = max((text.match(/`+/g) ?? []).map(({ length }) => length))
+    const fence = '`'.repeat(Math.max(3, (longest ?? 0) + 1))
+    const clipped =
+        text.length > DETAIL_MAX
+            ? `${text.slice(0, DETAIL_MAX)}\n... (clipped)`
+            : text
+    return `${fence}\n${clipped}\n${fence}`
+}
+
+export const plural = (count: number, word: string): string =>
+    `${count} ${word}${count === 1 ? '' : 's'}`