@alecsibilia/luca 14.0.0-alpha.30 → 14.0.0-alpha.32

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.32
+
+No changes in this release.
+
+## 14.0.0-alpha.31
+
+No changes in this release.
+
 ## 14.0.0-alpha.30
 
 No changes in this release.

package/board/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luca/board",
-    "version": "14.0.0-alpha.30",
+    "version": "14.0.0-alpha.32",
     "private": true,
     "type": "module"
 }

package/board/server/board-vocabulary-engine.ts

@@ -75,6 +75,21 @@ export const ENGINE_VOCABULARY = {
         reason: z.string(),
         detail: z.string().catch(''),
     }),
+    /**
+     * The engine told the owner a ticket (`ticket` set), the run, or the
+     * final review is stuck (#705): its Needs-you item shows from here.
+     */
+    stuck_reported: z.looseObject({}),
+    /**
+     * The engine retried a stuck ticket, the final review, or the run by
+     * itself (#705): `item` is `ticket`, `final_review`, or `run`, and
+     * `body` its comment on the spec issue, word for word.
+     */
+    auto_retried: z.looseObject({
+        item: z.string(),
+        reason: z.string().catch(''),
+        body: z.string().catch(''),
+    }),
     pull_request_opened: z.looseObject({
         number: z.number().int(),
         url: z.string(),

package/board/server/board-vocabulary.ts

@@ -65,6 +65,8 @@ const BoardEntrySchema = z.discriminatedUnion('kind', [
     entry({ kind: 'run_branch_pushed' }),
     entry({ kind: 'ticket_stuck' }),
     entry({ kind: 'run_stuck' }),
+    entry({ kind: 'stuck_reported' }),
+    entry({ kind: 'auto_retried' }),
     entry({ kind: 'pull_request_opened' }),
     entry({ kind: 'worktrees_removed' }),
     entry({ kind: 'jev_asked' }),

package/board/server/describe-record.ts

@@ -278,6 +278,9 @@ export const describeRecord = ({
                 text: `The run is stuck. ${runReasonText({ reason: record.content.reason })}`,
                 tone: 'danger',
             })
+        // The engine's own retry (#705): its comment on the spec issue.
+        case 'auto_retried':
+            return event({ text: record.content.body, tone: 'info' })
         case 'pull_request_opened':
             return event({
                 text: `Pull request #${record.content.number} opened: ${record.content.url}`,
@@ -377,11 +380,13 @@ export const describeRecord = ({
                 tone: 'info',
             })
         // The repo wait shows as a banner on the panel (#632), the network
-        // wait as the run's status (#701).
+        // wait as the run's status (#701), and a stuck report as the stuck
+        // row it brings (#705).
         case 'repo_wait_started':
         case 'repo_wait_ended':
         case 'network_wait_started':
         case 'network_wait_ended':
+        case 'stuck_reported':
         case 'intake_read':
         case 'ticket_snapshot':
         case 'baseline_tests':

package/board/server/journal-rebuild-helpers.ts

@@ -9,6 +9,7 @@ import {
     pullRequestOpened,
     runStarted,
     stamp,
+    stuckReported,
     ticketStuck,
     ticketWorktreeCreated,
     wholeTicket,
@@ -133,11 +134,15 @@ export const finishedRun = (): Entry[] => [
     }),
 ]
 
-/** Spec 10 with ticket 13 stuck and nothing else running. */
+/**
+ * Spec 10 with ticket 13 stuck, told to the owner (so it needs you, #705),
+ * and nothing else running.
+ */
 export const stuckRun = (): Entry[] => [
     ...intakeOfThree(),
     ticketWorktreeCreated({ ticket: 13 }),
     ticketStuck({ ticket: 13, reason: 'red_check_failed', detail: 'x' }),
+    stuckReported({ ticket: 13 }),
 ]
 
 export const nothingToDoRun = (): Entry[] => [

package/board/server/luca-version.ts

@@ -1,2 +1,2 @@
 /** The Luca version of this board, stamped when the package was packed. */
-export const LUCA_VERSION: string = "14.0.0-alpha.30"
+export const LUCA_VERSION: string = "14.0.0-alpha.32"

package/board/server/reduce-board-create.ts

@@ -83,6 +83,7 @@ export const createBoardState = ({
     network_waits: [],
     run_plan_used: [],
     needs_you: [],
+    unreported: [],
     tickets: [],
     final_review: {
         state: 'waiting',

package/board/server/reduce-board-final-review.ts

@@ -7,7 +7,7 @@ import { finalReasonText } from './reduce-board-reasons'
 import { clip } from './reduce-board-text'
 import {
     DETAIL_MAX,
-    addNeedsYou,
+    addUnreported,
     resolveNeedsYou,
     updateFinal,
     withTried,
@@ -125,8 +125,9 @@ export const applyFinalReviewKind = ({
                     }),
                 }),
             })
+        // Needs you once the engine tells the owner (#705).
         case 'final_review_stuck':
-            return addNeedsYou({
+            return addUnreported({
                 state: updateFinal({
                     state,
                     update: (review) => ({ ...review, state: 'stuck' }),

package/board/server/reduce-board-needs-you.ts

@@ -1,6 +1,7 @@
 /**
- * What needs a person: a stuck ticket or run, a skipped or retried ticket,
- * and the replies that resolve them.
+ * What needs a person: a stuck ticket or run (once the engine told the
+ * owner, #705), a skipped or retried ticket, and the replies and the
+ * engine's own retries that resolve them.
  */
 import type { BoardRecord } from './board-vocabulary'
 import {
@@ -12,6 +13,8 @@ import { clip } from './reduce-board-text'
 import {
     DETAIL_MAX,
     addNeedsYou,
+    addUnreported,
+    reportNeedsYou,
     resolveNeedsYou,
     updateFinal,
     updateTicket,
@@ -126,6 +129,55 @@ const ticketRetried = ({
     }
 }
 
+/**
+ * A retry of a ticket, the run, or the final review, the owner's or the
+ * engine's own (#705): it carries on, and its item is resolved.
+ */
+const retriedTicket = ({
+    state,
+    ticket,
+}: {
+    state: BoardState
+    ticket: number
+}): BoardState =>
+    resolveNeedsYou({
+        state: updateTicket({
+            state,
+            number: ticket,
+            update: (card) => ({
+                ...card,
+                stage: 'building',
+                activity: 'retrying',
+            }),
+        }),
+        key: ticketKey({ ticket }),
+    })
+
+const retriedRun = ({
+    state,
+    top_up,
+}: {
+    state: BoardState
+    top_up: number
+}): BoardState =>
+    resolveNeedsYou({
+        state: {
+            ...state,
+            run_budget_tokens: state.run_budget_tokens + top_up,
+            run_stuck_reason: null,
+        },
+        key: RUN_KEY,
+    })
+
+const retriedFinal = ({ state }: { state: BoardState }): BoardState =>
+    resolveNeedsYou({
+        state: updateFinal({
+            state,
+            update: (review) => ({ ...review, state: 'reviewing' }),
+        }),
+        key: FINAL_KEY,
+    })
+
 const replyReceived = ({
     state,
     record,
@@ -137,45 +189,21 @@ const replyReceived = ({
     const ticket = record.content.ticket ?? record.ticket
     switch (word) {
         case 'retry':
-            if (ticket !== null) {
-                return resolveNeedsYou({
-                    state: updateTicket({
-                        state,
-                        number: ticket,
-                        update: (card) => ({
-                            ...card,
-                            stage: 'building',
-                            activity: 'retrying',
-                        }),
-                    }),
-                    key: ticketKey({ ticket }),
-                })
-            }
+            if (ticket !== null) return retriedTicket({ state, ticket })
             // A bare `retry` while the run is stuck on its budget adds its
             // top-up (one whole budget for a retry journaled with none,
             // #543); stuck for another reason, no budget. The final review
             // is left as it is.
             if (state.needs_you.some((item) => item.key === RUN_KEY)) {
-                const top_up =
-                    state.run_stuck_reason === 'run_budget'
-                        ? (record.content.top_up ?? state.run_budget_each)
-                        : 0
-                return resolveNeedsYou({
-                    state: {
-                        ...state,
-                        run_budget_tokens: state.run_budget_tokens + top_up,
-                        run_stuck_reason: null,
-                    },
-                    key: RUN_KEY,
+                return retriedRun({
+                    state,
+                    top_up:
+                        state.run_stuck_reason === 'run_budget'
+                            ? (record.content.top_up ?? state.run_budget_each)
+                            : 0,
                 })
             }
-            return resolveNeedsYou({
-                state: updateFinal({
-                    state,
-                    update: (review) => ({ ...review, state: 'reviewing' }),
-                }),
-                key: FINAL_KEY,
-            })
+            return retriedFinal({ state })
         case 'skip':
             return skipTicket({ state, ticket, because: null })
         case 'ship':
@@ -191,10 +219,39 @@ const replyReceived = ({
     }
 }
 
+/**
+ * The engine retried a stuck item by itself (#705): nothing to reply to,
+ * so its item is resolved, told or not, and it carries on as after the
+ * owner's `retry`.
+ */
+const autoRetried = ({
+    state,
+    record,
+}: {
+    state: BoardState
+    record: Extract<BoardRecord, { kind: 'auto_retried' }>
+}): BoardState => {
+    const { ticket } = record
+    switch (record.content.item) {
+        case 'ticket':
+            return ticket === null ? state : retriedTicket({ state, ticket })
+        // The engine retries the run only after `pull_request_failed`: no
+        // budget to add.
+        case 'run':
+            return retriedRun({ state, top_up: 0 })
+        case 'final_review':
+            return retriedFinal({ state })
+        default:
+            return state
+    }
+}
+
 /** The record kinds of what needs a person. */
 export const NEEDS_YOU_KINDS = [
     'ticket_stuck',
     'run_stuck',
+    'stuck_reported',
+    'auto_retried',
     'reply_received',
     'ticket_skipped',
     'ticket_retried',
@@ -229,7 +286,8 @@ export const applyNeedsYouKind = ({
                     activity: 'stuck',
                 }),
             })
-            return addNeedsYou({
+            // Needs you once the engine tells the owner (#705).
+            return addUnreported({
                 state: stuck,
                 item: {
                     key: ticketKey({ ticket }),
@@ -250,7 +308,7 @@ export const applyNeedsYouKind = ({
             })
         }
         case 'run_stuck':
-            return addNeedsYou({
+            return addUnreported({
                 state: { ...state, run_stuck_reason: record.content.reason },
                 item: {
                     key: RUN_KEY,
@@ -266,6 +324,20 @@ export const applyNeedsYouKind = ({
                     since: record.time,
                 },
             })
+        // A report with no ticket is the run's while it waits to be told,
+        // else the final review's.
+        case 'stuck_reported':
+            return reportNeedsYou({
+                state,
+                key:
+                    ticket !== null
+                        ? ticketKey({ ticket })
+                        : state.unreported.some((item) => item.key === RUN_KEY)
+                          ? RUN_KEY
+                          : FINAL_KEY,
+            })
+        case 'auto_retried':
+            return autoRetried({ state, record })
         case 'reply_received':
             return replyReceived({ state, record })
         case 'ticket_skipped':

package/board/server/reduce-board-update.ts

@@ -77,6 +77,44 @@ export const addNeedsYou = ({
     ],
 })
 
+/**
+ * A stuck item the engine hasn't told the owner of yet (#705): it waits in
+ * `unreported` until `stuck_reported` (`reportNeedsYou`).
+ */
+export const addUnreported = ({
+    state,
+    item,
+}: {
+    state: BoardState
+    item: NeedsYou
+}): BoardState => ({
+    ...state,
+    unreported: [
+        ...state.unreported.filter((entry) => entry.key !== item.key),
+        item,
+    ],
+})
+
+/** The engine told the owner: the item `key` waiting to be told needs you now. */
+export const reportNeedsYou = ({
+    state,
+    key,
+}: {
+    state: BoardState
+    key: string
+}): BoardState => {
+    const item = state.unreported.find((entry) => entry.key === key)
+    if (item === undefined) return state
+    return addNeedsYou({
+        state: {
+            ...state,
+            unreported: state.unreported.filter((entry) => entry.key !== key),
+        },
+        item,
+    })
+}
+
+/** Resolves item `key`, told or not yet told, or every item for `null`. */
 export const resolveNeedsYou = ({
     state,
     key,
@@ -89,6 +127,10 @@ export const resolveNeedsYou = ({
         key === null
             ? []
             : state.needs_you.filter((entry) => entry.key !== key),
+    unreported:
+        key === null
+            ? []
+            : state.unreported.filter((entry) => entry.key !== key),
 })
 
 /** The final review with one more "tried" line. */

package/board/shared/board-state.ts

@@ -144,6 +144,13 @@ export const BoardStateSchema = z.object({
     /** How much of the plan the whole run used, per window. */
     run_plan_used: z.array(PlanUsedSchema),
     needs_you: z.array(NeedsYouSchema),
+    /**
+     * A stuck ticket's or run's item before the engine told the owner
+     * (#705): it moves to `needs_you` on the engine's `stuck_reported`, and
+     * is dropped when the engine retries the item by itself. Defaulted, so
+     * a board state from before it still parses.
+     */
+    unreported: z.array(NeedsYouSchema).default([]),
     tickets: z.array(TicketCardSchema),
     final_review: FinalReviewSchema,
     jev: JevCountsSchema,

package/engine/cli/config-reload-text.ts

@@ -5,7 +5,9 @@
 import type { JournalRecord } from '../journal/journal-record'
 
 /** A value of a reloaded config field in a log line; `null` is "none". */
-const fieldValue = (value: string | number | string[] | null): string => {
+const fieldValue = (
+    value: string | number | boolean | string[] | null
+): string => {
     if (value === null) return 'none'
     if (Array.isArray(value)) return `[${value.join(', ')}]`
     return String(value)

package/engine/config/config-fields.ts

@@ -94,6 +94,16 @@ export const decisionModelOf = ({
 export const modelsOf = ({ config }: { config: EngineConfig }): ModelsConfig =>
     config.models ?? ModelsConfigSchema.parse({})
 
+/**
+ * Whether the engine retries a routine stuck item once by itself (#705):
+ * the config's `auto_retry`, else `true`.
+ *
+ * @example
+ * autoRetryOf({ config: { ...config, auto_retry: false } }) // false
+ */
+export const autoRetryOf = ({ config }: { config: EngineConfig }): boolean =>
+    config.auto_retry ?? true
+
 /**
  * The feature map's path (#583), in the form a worktree-relative path takes
  * everywhere else (`normalize`, no leading `./`), or `null` with no map.

package/engine/config/config-reload.ts

@@ -3,6 +3,7 @@ import omit from 'lodash/omit'
 import reduce from 'lodash/reduce'
 import { z } from 'zod'
 
+import { autoRetryOf } from './config-fields'
 import type { EngineConfig } from './engine-config'
 
 /**
@@ -28,6 +29,9 @@ import type { EngineConfig } from './engine-config'
  * - `leftover_allow`: more new markdown the leftover scan lets through
  *   (#520). Each scan reads it then, so a run stuck on a leftover can be
  *   unstuck by allowing the file and resuming.
+ * - `auto_retry`: whether the engine retries a routine stuck item once by
+ *   itself (#705). Only an item stuck after the resume is retried, so
+ *   turning it on leaves an item already told to the owner waiting.
  */
 export const RELOADED_FIELDS = [
     'prepare',
@@ -37,6 +41,7 @@ export const RELOADED_FIELDS = [
     'test_timeout_ms',
     'test_case_timeout_ms',
     'leftover_allow',
+    'auto_retry',
 ] as const
 
 /**
@@ -130,6 +135,12 @@ export const ConfigChangeSchema = z.discriminatedUnion('field', [
         from: patterns,
         to: patterns,
     }),
+    // Never left out: a config without it reads as `true`.
+    z.object({
+        field: z.literal('auto_retry'),
+        from: z.boolean(),
+        to: z.boolean(),
+    }),
 ])
 
 export type ConfigChange = z.infer<typeof ConfigChangeSchema>
@@ -186,6 +197,11 @@ export const configChanges = ({
             from: current.leftover_allow ?? null,
             to: next.leftover_allow ?? null,
         },
+        {
+            field: 'auto_retry',
+            from: autoRetryOf({ config: current }),
+            to: autoRetryOf({ config: next }),
+        },
     ]
     return all.filter(({ from, to }) => !isEqual(from, to))
 }
@@ -226,6 +242,8 @@ const applyChange = ({
             return change.to === null
                 ? omit(config, 'leftover_allow')
                 : { ...config, leftover_allow: change.to }
+        case 'auto_retry':
+            return { ...config, auto_retry: change.to }
     }
 }
 

package/engine/config/engine-config-schema.ts

@@ -344,6 +344,13 @@ export const EngineConfigSchema = z.object({
      * (`DEFAULT_RUN_BUDGET_TOKENS`).
      */
     run_budget_tokens: z.number().int().positive().optional(),
+    /**
+     * Whether the engine retries a routine stuck item once by itself
+     * (#705), with a comment on the spec issue, before it asks the owner.
+     * Left out, `true`; a config written before it may lack it, and reads
+     * as `true` too (`autoRetryOf`).
+     */
+    auto_retry: z.boolean().default(true).optional(),
 })
 
 export type EngineConfig = z.infer<typeof EngineConfigSchema>

package/engine/config/engine-config.ts

@@ -17,6 +17,7 @@ import {
 } from './engine-config-schema'
 
 export {
+    autoRetryOf,
     DEFAULT_PREPARE_CONCURRENCY,
     DEFAULT_PREPARE_TIMEOUT_MS,
     decisionModelOf,