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

package/engine/core/execute-final-review.ts

@@ -15,6 +15,7 @@ import {
 } from './execute-build'
 import { closeSessions, openSessionsIn } from './session-close'
 
+import { roleEffort } from '../agents/role-effort'
 import { hasSlowTests } from '../config/engine-config'
 import type { EngineCommit } from '../git/git-adapter'
 import { LOCKED_PICK } from '../jev/model-pick'
@@ -137,6 +138,7 @@ export const executeFinalReviewAction = async ({
         case 'launch_lens': {
             const { lens, role, prompt } = action
             const round = state.final_review.round
+            const effort = roleEffort({ role, config })
             journal.append({
                 kind: 'lens_started',
                 ticket: null,
@@ -152,6 +154,7 @@ export const executeFinalReviewAction = async ({
                     prompt,
                     follow_up_of: null,
                     ...LOCKED_PICK,
+                    effort,
                 },
             })
             const result = await runTurn({
@@ -171,6 +174,7 @@ export const executeFinalReviewAction = async ({
                         // Lenses are reviewers: no agent messages.
                         messaging: null,
                         model: LOCKED_PICK.model,
+                        effort,
                     }),
             })
             if (result === null || !('verdict' in result.result)) return
@@ -206,7 +210,9 @@ export const executeFinalReviewAction = async ({
             return
         case 'launch_final_fixer': {
             const { role, prompt, may_edit_tests } = action
-            // The last fixes before the PR are never routed: always Opus.
+            // The last fixes before the PR are never routed: always Opus,
+            // and at the reviewers' effort, so the last code is the cleanest.
+            const effort = roleEffort({ role, config, final_fix: true })
             journal.append({
                 kind: 'agent_started',
                 ticket: null,
@@ -216,6 +222,7 @@ export const executeFinalReviewAction = async ({
                     prompt,
                     follow_up_of: null,
                     ...LOCKED_PICK,
+                    effort,
                 },
             })
             await runTurn({
@@ -235,13 +242,14 @@ export const executeFinalReviewAction = async ({
                         // Every ticket is over, so nobody is left to talk to.
                         messaging: null,
                         model: LOCKED_PICK.model,
+                        effort,
                     }),
             })
             return
         }
         case 'follow_up_final_fixer': {
             const { role, session_id, message } = action
-            const { model, model_reason } = followUpModel({
+            const { model, model_reason, effort } = followUpModel({
                 records: journal.read(),
                 session_id,
             })
@@ -255,6 +263,7 @@ export const executeFinalReviewAction = async ({
                     follow_up_of: session_id,
                     model,
                     model_reason,
+                    effort,
                 },
             })
             await runTurn({

package/engine/core/execute-memory.ts

@@ -1,6 +1,7 @@
 import type { MemoryAction, MemorySaveStep } from './decide-memory'
 import { buildContext, need, runTurn, type BuildDeps } from './execute-build'
 
+import { roleEffort } from '../agents/role-effort'
 import { launchPick } from '../jev/model-pick'
 import type { Journal } from '../journal/journal'
 import type { JournalRecord } from '../journal/journal-record'
@@ -416,6 +417,10 @@ export const executeMemoryAction = async ({
                 role: 'learner',
                 step,
             })
+            const effort = roleEffort({
+                role: 'learner',
+                config: built.config,
+            })
             journal.append({
                 kind: 'agent_started',
                 ticket: null,
@@ -426,6 +431,7 @@ export const executeMemoryAction = async ({
                     follow_up_of: null,
                     model,
                     model_reason,
+                    effort,
                 },
             })
             await runTurn({
@@ -445,6 +451,7 @@ export const executeMemoryAction = async ({
                         // The learner writes nothing and talks to nobody.
                         messaging: null,
                         model,
+                        effort,
                     }),
             })
             return

package/engine/core/final-failure-cap.ts

@@ -1,6 +1,7 @@
 /**
  * The cap on a final review role's failed tries (`failureCap`): the stuck step
- * once a failed turn used up the role's tries, or its engine failures in a row.
+ * once a failed turn used up the role's tries in a row, or its engine
+ * failures in a row. A finished turn of the role gives its tries back.
  */
 import { stuck, type FinalReviewAction } from './final-review-action'
 import { MAX_ENGINE_FAILURES, MAX_FIX_ROUNDS } from './loop-caps'
@@ -8,8 +9,11 @@ import { MAX_ENGINE_FAILURES, MAX_FIX_ROUNDS } from './loop-caps'
 import type { FinalReviewState, ReplayedAgentFailure } from '../journal/replay'
 
 /**
- * The stuck step when a failed turn used up its role's tries (or engine
- * failures in a row), else `null`: the role gets another go.
+ * The stuck step when a failed turn used up its role's tries in a row (or
+ * engine failures in a row), else `null`: the role gets another go.
+ *
+ * @example
+ * failureCap({ review, failed }) // null while the role has tries left
  */
 export const failureCap = ({
     review,
@@ -32,7 +36,7 @@ export const failureCap = ({
     return tries >= MAX_FIX_ROUNDS
         ? stuck({
               reason: 'agent_failed',
-              detail: `The ${role} failed ${tries} tries in the final review; the last one: ${error}`,
+              detail: `The ${role} failed ${tries} tries in a row in the final review; the last one: ${error}`,
           })
         : null
 }

package/engine/core/final-review-text.ts

@@ -190,13 +190,27 @@ const findingsSection = ({
         FIX_RULES,
     ].join('\n\n')
 
+/** The round's failed slow tests, beside the implementer's code findings (#563). */
+const slowTestsSection = ({
+    slow_tests,
+}: {
+    slow_tests: ReplayedGates
+}): string =>
+    [
+        '## The slow tests failed too',
+        'Once every lens finished, the engine ran the slow tests on the run branch, and these failed. Fix the code so they pass too: the gates run them again after you answer.',
+        failedChecks({ gates: slow_tests }),
+    ].join('\n\n')
+
 /**
  * The prompt a fresh final review fixer starts with: its task, the spec,
  * every ticket, and its findings (the test findings for the test-writer,
  * the code findings for the implementer, or the findings the other fixer
- * answered `other_role`, #616). An implementer launched only to
- * fix failed gates (the round had only test findings) gets the gates'
- * output instead. The engine journals it word for word.
+ * answered `other_role`, #616). The implementer that starts a round whose
+ * slow tests failed (#563) gets their output beside its code findings. An
+ * implementer launched only to fix failed gates (the round had only test
+ * findings) gets the gates' output instead. The engine journals it word
+ * for word.
  *
  * @example
  * const prompt = finalFixerPrompt({ role: 'implementer', snapshot, fix, gates: null })
@@ -206,6 +220,7 @@ export const finalFixerPrompt = ({
     snapshot,
     fix,
     gates,
+    slow_tests,
     run_notes,
     sections,
 }: {
@@ -214,6 +229,8 @@ export const finalFixerPrompt = ({
     fix: FinalReviewFix
     /** Failed gates to fix, for an implementer with no findings left. */
     gates: ReplayedGates | null
+    /** The round's failed slow tests, for the implementer that starts it. */
+    slow_tests?: ReplayedGates | null
     /** Notes earlier agents in the run left, oldest first. */
     run_notes?: PromptRunNote[]
     /** More sections after the task, such as a follow-up's message. */
@@ -239,6 +256,7 @@ export const finalFixerPrompt = ({
         FIXER_TASKS[role],
         ...workSections({ snapshot }),
         task,
+        ...(slow_tests?.ok === false ? [slowTestsSection({ slow_tests })] : []),
         ...(sections ?? []),
         ...runNotesSection({ run_notes: run_notes ?? [] }),
     ].join('\n\n')

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

@@ -15,6 +15,7 @@ import { reasonLine } from './stuck-text'
 import type { AgentRole, MergeDanger } from '../agents/role-results'
 import {
     EMPTY_FINAL_REVIEW,
+    finalPullRequestFindings,
     type FinalReviewState,
     type ReplayedSnapshot,
     type TicketProgress,
@@ -114,7 +115,9 @@ const outOfTurnsSection = ({
  * 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. Right after the
+ * while stuck puts its open findings at the very top; a round it never
+ * settled counts the findings, nits, and rulings of the lenses that
+ * finished it (see `finalPullRequestFindings`). 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
@@ -137,6 +140,8 @@ export const pullRequestText = ({
     memory_saves?: MemorySave[]
 }): { title: string; body: string } => {
     const review = final_review ?? EMPTY_FINAL_REVIEW
+    // A round a stuck lens never settled keeps its finished lenses' findings.
+    const findings = finalPullRequestFindings({ review })
     const { spec } = snapshot
     const title = (number: number) => snapshot.tickets[number]?.title ?? ''
     const isSkipped = (number: number) =>
@@ -175,7 +180,7 @@ export const pullRequestText = ({
                     `- #${number} ${id}${fileText(file)}: ${title}`
             )
         ),
-        ...review.nits.map(
+        ...findings.nits.map(
             ({ lens, id, title, file }) =>
                 `- final review, ${lens} lens: ${id}${fileText(file)}: ${title}`
         ),
@@ -206,23 +211,22 @@ export const pullRequestText = ({
                 declinedLine({ where: `#${number} `, ...entry })
             )
         ),
-        ...review.declined.map((entry) =>
+        ...findings.declined.map((entry) =>
             declinedLine({
                 where: `final review, ${entry.lens} lens: `,
                 ...entry,
             })
         ),
     ]
-    const stillOpen = review.fix?.findings ?? []
     const shipped =
         review.shipped && review.stuck !== null
             ? shippedFindingsSection({
-                  findings: stillOpen,
+                  findings: findings.open,
                   stuck: review.stuck,
                   edits: review.shipped_edits,
               })
-            : review.fresh_started && stillOpen.length > 0
-              ? freshFindingsSection({ findings: stillOpen })
+            : review.fresh_started && findings.open.length > 0
+              ? freshFindingsSection({ findings: findings.open })
               : ''
     const body = [
         shipped,

package/engine/core/stuck-format.ts

@@ -18,5 +18,17 @@ export const fenced = (text: string): string => {
     return `${fence}\n${clipped}\n${fence}`
 }
 
-export const plural = (count: number, word: string): string =>
-    `${count} ${word}${count === 1 ? '' : 's'}`
+/**
+ * `count` and `word`, with `s` past one; a word ending in a consonant and
+ * `y` ends in `ies` instead.
+ *
+ * @example
+ * plural(2, 'fix round') // '2 fix rounds'
+ * plural(3, 'failed try') // '3 failed tries'
+ */
+export const plural = (count: number, word: string): string => {
+    if (count === 1) return `${count} ${word}`
+    return /[^aeiou]y$/.test(word)
+        ? `${count} ${word.slice(0, -1)}ies`
+        : `${count} ${word}s`
+}

package/engine/guards/helper-rules.ts

@@ -6,6 +6,8 @@ import { z } from 'zod'
 
 import { ALLOW, deny, READ_TOOLS, type ToolDecision } from './guard-roles'
 
+import type { EffortLevel } from '../config/engine-config'
+
 /** The SDK tool that starts a helper. */
 export const HELPER_TOOL = 'Agent'
 
@@ -15,6 +17,9 @@ export const HELPER_TYPE = 'searcher'
 /** Helpers always run on the newest Haiku, by its short name. */
 export const HELPER_MODEL = 'haiku'
 
+/** Helpers always run at low effort (#659): a search needs little thought. */
+export const HELPER_EFFORT: EffortLevel = 'low'
+
 /** The only tools a helper has: it reads and searches, nothing else. */
 export const HELPER_TOOLS = READ_TOOLS
 
@@ -26,6 +31,7 @@ export const SEARCHER = {
     description:
         'A read-only helper that searches the repo: finds files, symbols and callers, and reports what it found. It cannot edit files or run commands.',
     model: HELPER_MODEL,
+    effort: HELPER_EFFORT,
     tools: [...HELPER_TOOLS],
     prompt: 'You are a read-only searcher. You may only read and search files in the current worktree with Read, Grep and Glob. Never try to change a file or run a command. Answer with what you found: file paths, line numbers and short excerpts, as briefly as the question allows.',
 }

package/engine/index.ts

@@ -15,7 +15,6 @@ export {
     type AgentQuerySession,
 } from './agents/claude-launcher'
 export {
-    AGENT_EFFORT,
     agentEnv,
     agentOptions,
     BANNED_ENV,
@@ -32,6 +31,7 @@ export {
     LUCA_SERVER,
     sendMessageDescription,
 } from './agents/message-tool'
+export { REVIEW_EFFORT, ROLE_EFFORT, roleEffort } from './agents/role-effort'
 export { roleInstructions } from './agents/role-instructions'
 export {
     rolePrompt,

package/engine/jev/jev-jobs.ts

@@ -10,8 +10,13 @@ import {
 } from './jev-schemas'
 import { offeredModels, type RoutedRole } from './model-pick'
 
+import { ROLE_EFFORT, roleEffort } from '../agents/role-effort'
 import type { Finding } from '../agents/role-results'
-import { DEFAULT_MODEL, modelsOf } from '../config/engine-config'
+import {
+    DEFAULT_MODEL,
+    modelsOf,
+    type EffortLevel,
+} from '../config/engine-config'
 import type { EngineAction } from '../core/decide'
 import type { TicketSnapshot } from '../intake/intake-schemas'
 import type { JournalRecord } from '../journal/journal-record'
@@ -210,6 +215,51 @@ const agentModelAsk = ({
     }
 }
 
+/** The efforts an `agent_effort` ask offers, lowest first. */
+const OFFERED_EFFORTS: readonly EffortLevel[] = ['medium', 'high', 'xhigh']
+
+/**
+ * Which effort a fresh test-writer or implementer on a ticket should use
+ * (#661), with the same facts as its `agent_model` ask. Shadow mode only:
+ * the agent always runs at its role's effort.
+ */
+const agentEffortAsk = ({
+    state,
+    ticket,
+    role,
+    attempt,
+}: {
+    state: RunState
+    ticket: number
+    role: RoutedRole
+    attempt: number
+}): JevAsk => ({
+    job: 'agent_effort',
+    ticket,
+    role,
+    request: {
+        state: {
+            ...ticketState({ state, ticket }),
+            role,
+            try: String(attempt),
+        },
+        questions: {
+            effort: choice({
+                instructions:
+                    'Which effort should this agent use? Pick the lowest that will get it right.',
+                options: OFFERED_EFFORTS,
+            }),
+        },
+    },
+    fixed: {
+        effort:
+            state.config === null
+                ? ROLE_EFFORT[role]
+                : roleEffort({ role, config: state.config }),
+    },
+    acted: false,
+})
+
 const agentSkillsAsk = ({
     state,
     ticket,
@@ -250,8 +300,9 @@ const isRoutedTicketRole = (role: string): role is RoutedRole =>
 
 /**
  * The asks to make before the engine carries out `action`: ticket order
- * before a ticket starts, skills before each agent, and the model before
- * each fresh test-writer, implementer, and learner.
+ * before a ticket starts, skills before each agent, the model before each
+ * fresh test-writer, implementer, and learner, and the effort before each
+ * fresh test-writer and implementer.
  */
 export const jevAsksBefore = ({
     action,
@@ -265,16 +316,12 @@ export const jevAsksBefore = ({
             return createTicketWorktreeAsks({ state, ticket: action.ticket })
         case 'launch_agent': {
             const { ticket, role } = action
-            const failed = state.tickets[ticket]?.failed_tries[role] ?? 0
+            const attempt = (state.tickets[ticket]?.failed_tries[role] ?? 0) + 1
             return [
                 ...(isRoutedTicketRole(role)
                     ? [
-                          agentModelAsk({
-                              state,
-                              ticket,
-                              role,
-                              attempt: failed + 1,
-                          }),
+                          agentModelAsk({ state, ticket, role, attempt }),
+                          agentEffortAsk({ state, ticket, role, attempt }),
                       ]
                     : []),
                 agentSkillsAsk({ state, ticket, role }),

package/engine/jev/jev-schemas.ts

@@ -100,11 +100,13 @@ export type JevAnswer = z.infer<typeof JevAnswerSchema>
 /**
  * The jobs the engine asks Jev about. `ticket_model` (one model per ticket)
  * is no longer asked; `agent_model` (one per agent) replaced it in #602. It
- * stays so old journals read.
+ * stays so old journals read. `agent_effort` is only ever asked in shadow
+ * mode (#661).
  */
 export const JevJobSchema = z.enum([
     'ticket_model',
     'agent_model',
+    'agent_effort',
     'agent_skills',
     'ticket_order',
     'failure_kind',

package/engine/journal/agent-entries.ts

@@ -8,6 +8,7 @@ import {
     FileModeSchema,
     RoleResultSchema,
 } from '../agents/role-results'
+import { EffortLevelSchema } from '../config/engine-config'
 import { GateCheckSchema } from '../gates/gate-schemas'
 import { ModelReasonSchema } from '../jev/model-pick'
 
@@ -23,7 +24,9 @@ import { ModelReasonSchema } from '../jev/model-pick'
  * follow-up's is its session's); `null` in journals from before #600. The
  * exact version is in the turn's `agent_session`. `model_reason` is why it
  * launched on that model (#603; a follow-up's is its session's); `null` in
- * journals from before it.
+ * journals from before it. `effort` is the effort it ran at (#659; a
+ * follow-up's is its session's); `null` in journals from before it, when
+ * every agent ran at `high`.
  */
 export const AgentStartedEntrySchema = z.object({
     ...ENTRY_FIELDS,
@@ -34,6 +37,7 @@ export const AgentStartedEntrySchema = z.object({
         follow_up_of: z.string().nullable().default(null),
         model: z.string().nullable().default(null),
         model_reason: ModelReasonSchema.nullable().default(null),
+        effort: EffortLevelSchema.nullable().default(null),
     }),
 })
 

package/engine/journal/final-review-replay.ts

@@ -143,7 +143,10 @@ export const finalReviewAfter = ({
             return finalResultChange({
                 review: {
                     ...review,
+                    // A finished turn gives the role its tries back: the
+                    // cap is on failed tries in a row.
                     agent_failures: omit(review.agent_failures, role),
+                    failed_tries: omit(review.failed_tries, role),
                     engine_failures: omit(review.engine_failures, role),
                     sessions: sessionsAfter({
                         sessions: review.sessions,

package/engine/journal/final-review-round.ts

@@ -13,7 +13,11 @@ import {
     handoffRole,
     type FinishedContent,
 } from './agent-turn-replay'
-import type { FinalFinding, FinalReviewState } from './final-review-state'
+import type {
+    FinalDeclined,
+    FinalFinding,
+    FinalReviewState,
+} from './final-review-state'
 import { setupChangeOf } from './ticket-result-replay'
 
 import {
@@ -112,6 +116,21 @@ const lensResultOf = ({
     }
 }
 
+/**
+ * The blocking findings of each due lens that finished this round, with
+ * its lens.
+ */
+const roundBlocking = ({
+    review,
+}: {
+    review: FinalReviewState
+}): FinalFinding[] =>
+    review.lenses_due.flatMap((lens) =>
+        (review.results[lens]?.findings ?? [])
+            .filter(isBlocking)
+            .map((entry) => ({ ...entry, lens }))
+    )
+
 /**
  * Every due lens finished this round, and its slow tests ran if they were
  * due (#563): the round can settle.
@@ -161,9 +180,7 @@ export const settleRound = ({
             result.findings.filter((entry) => !isBlocking(entry))
         )
     )
-    const blocking = due.flatMap(({ lens, result }) =>
-        tagged(lens, result.findings.filter(isBlocking))
-    )
+    const blocking = roundBlocking({ review })
     const settled: FinalReviewState = {
         ...review,
         declined: [...review.declined, ...declined],
@@ -199,6 +216,51 @@ export const settleRound = ({
     }
 }
 
+/** The final review's findings as its PR lists them. */
+export type PullRequestFindings = {
+    /** The blocking findings still open. */
+    open: FinalFinding[]
+    nits: FinalFinding[]
+    declined: FinalDeclined[]
+}
+
+/**
+ * The final review's findings as its PR lists them: the blocking ones still
+ * open, the nits, and the "won't fix" answers a lens let go. A round that
+ * never settled (a lens failed on every try, or a step crashed, and the
+ * owner replied `ship`) is settled over the lenses that finished it, as
+ * `settleRound` would: their blocking findings, nits, and rulings count,
+ * and a finding one of them cleared is no longer open. The open fix round's
+ * findings stay open only for the lenses that never finished. A settled
+ * round's findings are as they stand.
+ *
+ * @example
+ * finalPullRequestFindings({ review }).open
+ * // [{ id: 'simplification-F1', lens: 'simplification', severity: 'should_fix', ... }]
+ */
+export const finalPullRequestFindings = ({
+    review,
+}: {
+    review: FinalReviewState
+}): PullRequestFindings => {
+    const earlier = review.fix?.findings ?? []
+    const finished = review.lenses_due.filter(
+        (lens) => review.results[lens] !== undefined
+    )
+    if (roundDone({ review }) || finished.length === 0) {
+        return { open: earlier, nits: review.nits, declined: review.declined }
+    }
+    const settled = settleRound({ review: { ...review, lenses_due: finished } })
+    return {
+        open: [
+            ...earlier.filter(({ lens }) => !finished.includes(lens)),
+            ...(settled.fix?.findings ?? []),
+        ],
+        nits: settled.nits,
+        declined: settled.declined,
+    }
+}
+
 /**
  * Where a finished agent's result goes in the final review: a lens's
  * result this round (settling the round once every due lens finished), or

package/engine/journal/final-review-state.ts

@@ -72,7 +72,10 @@ export type FinalReviewState = {
     sessions: Partial<Record<AgentRole, string>>
     /** Each role's failed turn, if no agent of that role finished after it. */
     agent_failures: Partial<Record<AgentRole, ReplayedAgentFailure>>
-    /** Failed tries (agent, result, guard) per role, over the whole final review. */
+    /**
+     * Failed tries (agent, result, guard) per role, in a row: a finished
+     * turn of the role starts its count again.
+     */
     failed_tries: Partial<Record<AgentRole, number>>
     /** Engine failures in a row, per role. */
     engine_failures: Partial<Record<AgentRole, number>>

package/engine/journal/replay.ts

@@ -71,7 +71,7 @@ export { EMPTY_FINAL_REVIEW } from './final-review-state'
 export type { PlanState } from './plan-replay'
 export type { LearnerState, MemoryState } from './memory-replay'
 export { EMPTY_MEMORY } from './memory-replay'
-export { namespacedId } from './final-review-round'
+export { finalPullRequestFindings, namespacedId } from './final-review-round'
 export { isFinalKey } from './final-review-replay'
 export { handoffRole } from './agent-turn-replay'