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

package/board/server/describe-record.ts

@@ -0,0 +1,403 @@
+import type { BoardRecord } from './board-vocabulary'
+import {
+    COMMITTED,
+    event,
+    finalFinishedText,
+    finalStartedText,
+    finishedText,
+    ignoredText,
+    learnerFinishedText,
+    lowerFirst,
+    messageText,
+    nothingToDoText,
+    on,
+    recalledText,
+    savedText,
+    SHIPPED_TEXT,
+    startedText,
+} from './record-texts'
+import {
+    failureText,
+    finalReasonText,
+    LEARNER,
+    reasonText,
+    RETRY_REFUSED_TEXT,
+    rebasedText,
+    runReasonText,
+    roleWords,
+    shortSha,
+    testsSentBackText,
+} from './reduce-board'
+
+import type { Tone } from '../shared/board-rows'
+import {
+    LOOP_CAP,
+    stoppedText,
+    windowWords,
+    type BoardState,
+    type FindingCounts,
+} from '../shared/board-state'
+
+const findingsText = ({ findings }: { findings: FindingCounts }): string => {
+    const parts = [
+        findings.blocker > 0 ? `${findings.blocker} blocker` : null,
+        findings.should_fix > 0 ? `${findings.should_fix} should-fix` : null,
+        findings.nit > 0 ? `${findings.nit} nit` : null,
+    ].filter((part) => part !== null)
+    return parts.length > 0 ? parts.join(', ') : 'no findings'
+}
+
+/**
+ * What a record means in one line, or `null` for records that are noise in
+ * a chat (snapshots, session summaries, a clean leftover scan, the decision
+ * model's asks in shadow mode, ...).
+ */
+export const describeRecord = ({
+    before,
+    after,
+    record,
+}: {
+    before: BoardState
+    after: BoardState
+    record: BoardRecord
+}): { text: string; tone: Tone } | null => {
+    const at = on({ ticket: record.ticket })
+    switch (record.kind) {
+        case 'run_started':
+            return event({
+                text: `The run started on spec #${record.content.spec_number}.`,
+                tone: 'info',
+            })
+        // Only a resume on a different Luca version is worth a row.
+        case 'engine_resumed':
+            return after.run.version_note !== null &&
+                after.run.version_note !== before.run.version_note
+                ? event({ text: after.run.version_note, tone: 'warning' })
+                : null
+        case 'config_reloaded':
+            return event({
+                text: `Config reloaded: ${record.content.changes.map(({ field }) => field).join(', ')} changed.`,
+                tone: 'info',
+            })
+        case 'decision_model_off':
+            return event({
+                text: `Decision model off: ${record.content.detail}`,
+                tone: 'info',
+            })
+        case 'config_reload_refused':
+            return event({
+                text: `Config not reloaded, so the run keeps its own: ${record.content.reason.split('\n')[0] ?? ''}`,
+                tone: 'warning',
+            })
+        case 'intake_refused':
+            return event({
+                text: `Intake refused the run. ${after.run.refusal.join('; ')}`,
+                tone: 'danger',
+            })
+        case 'nothing_to_do':
+            return event({
+                text: nothingToDoText({ content: record.content }),
+                tone: 'info',
+            })
+        case 'spec_snapshot': {
+            const { spec, ticket_order, left_out } = record.content
+            const people =
+                left_out.length === 0
+                    ? ''
+                    : ` ${left_out.length} left for a person: ${left_out.map(({ number }) => `#${number}`).join(', ')}.`
+            return event({
+                text: `Intake passed: spec #${spec.number}, ${ticket_order.length} tickets.${people}`,
+                tone: 'success',
+            })
+        }
+        case 'run_branch_created':
+            return event({
+                text: `The run branch ${record.content.branch} is ready.`,
+                tone: 'info',
+            })
+        case 'ticket_worktree_created':
+            return event({ text: `${at}started.`, tone: 'info' })
+        case 'usage_line_wait_started': {
+            const { line, percent, resets_at } = record.content
+            const window = windowWords({ window: record.content.window })
+            return event({
+                text: `Paused at the ${window} usage line: the account's ${window} window is at ${percent}% (line ${line}%). The run carries on when it resets at ${resets_at}, or once the line is raised.`,
+                tone: 'warning',
+            })
+        }
+        case 'usage_line_wait_ended':
+            return event({
+                text: 'The run carries on from the usage line.',
+                tone: 'info',
+            })
+        case 'dependencies_installed': {
+            const { check } = record.content
+            if (check === null || check.ok) return null
+            const where =
+                record.ticket === null
+                    ? "The run branch's install"
+                    : `${at}the install`
+            return event({
+                text: `${where} failed: \`${check.command}\`.`,
+                tone: 'danger',
+            })
+        }
+        case 'agent_started':
+            if (record.content.role === LEARNER) {
+                return event({
+                    text: "The learner reads the run's journal for lessons to keep.",
+                    tone: 'info',
+                })
+            }
+            return record.ticket === null
+                ? finalStartedText({ record })
+                : startedText({ before, after, record })
+        case 'agent_finished':
+            if (record.content.role === LEARNER) {
+                return learnerFinishedText({ record })
+            }
+            return record.ticket === null
+                ? finalFinishedText({ record })
+                : finishedText({ before, record })
+        case 'agent_failed': {
+            const { role, error, failure } = record.content
+            const who =
+                role === LEARNER
+                    ? 'The learner'
+                    : record.ticket === null
+                      ? `Final review: the ${roleWords({ role })}`
+                      : `${at}the ${role}`
+            return event({
+                text: `${who} ${failureText({ failure })}: ${error.split('\n')[0] ?? ''}`,
+                tone: failure === 'engine' ? 'warning' : 'danger',
+            })
+        }
+        case 'run_stopped': {
+            const text = stoppedText(record.content)
+            return event({
+                text: `${at}${text.charAt(0).toLowerCase()}${text.slice(1)}`,
+                tone: 'danger',
+            })
+        }
+        case 'worktree_reset':
+            return event({
+                text: `${at}starting over from the tests after a bad test.`,
+                tone: 'warning',
+            })
+        case 'red_check': {
+            const failing = after.tickets.find(
+                (ticket) => ticket.number === record.ticket
+            )?.tests?.failing
+            return record.content.ok
+                ? event({
+                      text: `${at}red check passed${failing ? ` (${failing} new tests fail)` : ''}.`,
+                      tone: 'success',
+                  })
+                : event({
+                      text: `${at}red check failed: ${record.content.problems[0] ?? 'no detail'}`,
+                      tone: 'danger',
+                  })
+        }
+        case 'leftover_scan':
+            return record.content.hits.length === 0
+                ? null
+                : event({
+                      text: `${record.ticket === null ? 'Final review: ' : at}the leftover scan found ${record.content.hits.map((hit) => hit.path).join(', ')}.`,
+                      tone: 'warning',
+                  })
+        case 'commit_made':
+            return record.ticket === null
+                ? event({
+                      text: 'Final review: the fixes committed on the run branch.',
+                      tone: 'info',
+                  })
+                : event({
+                      text: `${at}${COMMITTED[record.content.stage] ?? 'tests'} committed.`,
+                      tone: 'info',
+                  })
+        case 'gates_run': {
+            const failed = record.content.checks
+                .filter((check) => !check.ok)
+                .map((check) => check.name)
+            // The final review's slow tests, after round 1's lenses (#563).
+            if (record.content.target === 'final_slow') {
+                return record.content.ok
+                    ? event({
+                          text: 'Final review: slow tests passed.',
+                          tone: 'success',
+                      })
+                    : event({
+                          text: `Final review: slow tests failed: ${failed.join(', ') || 'no detail'}.`,
+                          tone: 'danger',
+                      })
+            }
+            const where =
+                record.ticket === null
+                    ? ' on the fixes'
+                    : record.content.target === 'run_branch'
+                      ? ' after joining'
+                      : ''
+            const who = record.ticket === null ? 'Final review: ' : at
+            return record.content.ok
+                ? event({
+                      text: `${who}checks passed${where}.`,
+                      tone: 'success',
+                  })
+                : event({
+                      text: `${who}checks failed${where}: ${failed.join(', ') || 'no detail'}.`,
+                      tone: 'danger',
+                  })
+        }
+        case 'ticket_joined':
+            return record.content.ok
+                ? event({
+                      text: `${at}joined the run branch.`,
+                      tone: 'success',
+                  })
+                : event({
+                      text: `${at}couldn't join the run branch: ${record.content.error ?? 'no detail'}`,
+                      tone: 'danger',
+                  })
+        case 'ticket_rebased':
+            return event({
+                text: `${at}${lowerFirst({ text: rebasedText({ content: record.content }) })}.`,
+                tone: 'warning',
+            })
+        case 'tests_sent_back':
+            return event({
+                text: `${at}${lowerFirst({ text: testsSentBackText({ content: record.content }) })}.`,
+                tone: 'warning',
+            })
+        case 'ticket_stuck':
+            return event({
+                text: `${at}stuck. ${reasonText({ reason: record.content.reason })}`,
+                tone: 'danger',
+            })
+        case 'run_stuck':
+            return event({
+                text: `The run is stuck. ${runReasonText({ reason: record.content.reason })}`,
+                tone: 'danger',
+            })
+        case 'pull_request_opened':
+            return event({
+                text: `Pull request #${record.content.number} opened: ${record.content.url}`,
+                tone: 'success',
+            })
+        case 'reply_received': {
+            const ticket = record.content.ticket ?? record.ticket
+            return event({
+                text: `You replied \`${record.content.word}${ticket === null ? '' : ` #${ticket}`}\`.`,
+                tone: 'info',
+            })
+        }
+        case 'ticket_already_done':
+            return event({
+                text: `${at}already done on the base branch, by ${record.content.shas.map((sha) => shortSha({ sha })).join(', ')}. Nothing to build.`,
+                tone: 'success',
+            })
+        case 'ticket_closed':
+            return event({
+                text: `${at}closed, since its work was already done.`,
+                tone: 'info',
+            })
+        case 'ticket_skipped': {
+            const { because } = record.content
+            return event({
+                text:
+                    because === null
+                        ? `${at}skipped. It stays open for a later run.`
+                        : `${at}skipped, since it waits on #${because}, which was skipped. It stays open for a later run.`,
+                tone: 'info',
+            })
+        }
+        case 'ticket_retried':
+            switch (record.content.mode) {
+                case 'resume':
+                    return null
+                case 'restart':
+                    return event({
+                        text: `${at}starts over from the edited ticket.`,
+                        tone: 'info',
+                    })
+                case 'refused':
+                    return event({
+                        text: `${at}the retry was refused: ${lowerFirst({ text: RETRY_REFUSED_TEXT })} ${record.content.problems.join(' ')}`.trimEnd(),
+                        tone: 'warning',
+                    })
+            }
+            break
+        case 'reply_ignored':
+            return event({
+                text: `Your reply was sent back: ${ignoredText({ reason: record.content.reason, before })}. The answer is on the spec issue.`,
+                tone: 'warning',
+            })
+        case 'final_review_started':
+            return event({
+                text: `The final review started (round ${after.final_review.round}).`,
+                tone: 'info',
+            })
+        case 'lens_finished':
+            return event({
+                text: `Final review, ${record.content.lens} lens: ${findingsText({ findings: record.content.findings })}.`,
+                tone:
+                    record.content.findings.blocker +
+                        record.content.findings.should_fix >
+                    0
+                        ? 'warning'
+                        : 'success',
+            })
+        case 'final_review_fixing':
+            return event({
+                text: `Final review: fix round ${record.content.round}/${LOOP_CAP}.`,
+                tone: 'warning',
+            })
+        case 'final_review_stuck':
+            return event({
+                text: `The final review is stuck. ${finalReasonText({ reason: record.content.reason })}`,
+                tone: 'danger',
+            })
+        case 'final_review_passed':
+            return event({ text: 'The final review passed.', tone: 'success' })
+        case 'agent_message':
+            return messageText({ record })
+        case 'final_review_shipped':
+            return event({ text: SHIPPED_TEXT, tone: 'info' })
+        case 'memory_recalled':
+            return recalledText({ record })
+        case 'memories_saved':
+            return savedText({ record })
+        case 'learning_skipped':
+            return event({
+                text: `The learner was skipped: ${record.content.reason.split('\n')[0] ?? ''} The run ends without new memories.`,
+                tone: 'warning',
+            })
+        case 'memories_reported':
+            return event({
+                text: `The ${record.content.count} new ${record.content.count === 1 ? 'memory went' : 'memories went'} on the spec issue, since there is no PR.`,
+                tone: 'info',
+            })
+        // The repo wait shows as a banner on the panel (#632).
+        case 'repo_wait_started':
+        case 'repo_wait_ended':
+        case 'intake_read':
+        case 'ticket_snapshot':
+        case 'baseline_tests':
+        case 'baseline_reused':
+        case 'run_branch_pushed':
+        case 'worktrees_removed':
+        case 'agent_session':
+        case 'jev_asked':
+        case 'jev_answered':
+        case 'jev_failed':
+        case 'agent_message_delivered':
+        case 'shared_git_changed':
+        case 'limit_wait_started':
+        case 'limit_wait_ended':
+        case 'usage_recorded':
+        case 'lens_started':
+        case 'step_started':
+        case 'step_ended':
+        case 'ticket_waiting':
+            return null
+    }
+}

package/board/server/engine-launch.ts

@@ -10,25 +10,42 @@ import type { EngineSettings } from '../shared/engine-settings'
  * `import.meta.url` is undefined and the cwd is `/`.
  */
 
-/** What a run builds: one spec, or the engine's safe practice run. */
+/** What a new run builds: one spec, or the engine's safe practice run. */
 export type RunTarget = { kind: 'spec'; spec: number } | { kind: 'demo' }
 
+/** What `/luca-run` asks for: a new run, or to resume a run the board started. */
+export type RunRequest = RunTarget | { kind: 'resume'; run_id: string }
+
 /**
- * Reads what followed `/luca-run`: `123`, `#123`, or `demo`.
+ * Reads what followed `/luca-run`: `123`, `#123`, `demo`, or
+ * `resume <run id>`.
  *
  * @example
  * parseRunArgs({ args: '#12' }) // { ok: true, target: { kind: 'spec', spec: 12 } }
+ * parseRunArgs({ args: 'resume luca-20260928-124805-69hp' }) // { ok: true, target: { kind: 'resume', run_id: 'luca-20260928-124805-69hp' } }
  * parseRunArgs({ args: 'soon' }).ok // false
  */
 export const parseRunArgs = ({
     args,
 }: {
     args: string
-}): { ok: true; target: RunTarget } | { ok: false; message: string } => {
+}): { ok: true; target: RunRequest } | { ok: false; message: string } => {
     const text = args.trim()
     if (text.toLowerCase() === 'demo') {
         return { ok: true, target: { kind: 'demo' } }
     }
+    const words = text.split(/\s+/)
+    if (words[0]?.toLowerCase() === 'resume') {
+        const run_id = words[1]
+        return run_id !== undefined &&
+            words.length === 2 &&
+            !run_id.startsWith('-')
+            ? { ok: true, target: { kind: 'resume', run_id } }
+            : {
+                  ok: false,
+                  message: `Which run? Give its id, as the board shows it. Usage: ${RUN_USAGE}`,
+              }
+    }
     const match = /^#?(\d+)$/.exec(text)
     const spec = match?.[1] ? Number(match[1]) : 0
     if (spec > 0 && Number.isSafeInteger(spec)) {

package/board/server/engine-restart-helpers.ts

@@ -0,0 +1,105 @@
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+    createHarness,
+    type Harness,
+    type UnfinishedRun,
+} from './testing/board-harness'
+import { runStarted } from './testing/journal-fixtures'
+
+import { ROW_KIND } from '../shared/board-rows'
+
+/**
+ * Helpers shared by the engine restart tests (`engine-restart.test.ts` and
+ * the `engine-restart-*.test.ts` files beside it).
+ *
+ * The boards and folders a test makes are in `harnesses` and `dirs`; each
+ * test file cleans them up after every test.
+ */
+
+export const harnesses: Harness[] = []
+export const dirs: string[] = []
+
+/** A plugin on a registry kept in `registry_dir`, so it can be restarted. */
+export const plugin = async ({
+    registry_dir,
+    ...options
+}: {
+    registry_dir: string
+} & Omit<Parameters<typeof createHarness>[0] & object, 'registry_dir'>) => {
+    const harness = await createHarness({ registry_dir, ...options })
+    harnesses.push(harness)
+    return harness
+}
+
+export const registryDir = async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'luca-board-restart-'))
+    dirs.push(dir)
+    return dir
+}
+
+/** Runs started by a first plugin, whose engines sent `run_started`. */
+export const startRuns = async ({
+    registry_dir,
+    runs,
+}: {
+    registry_dir: string
+    runs: { args: string; cwd?: string }[]
+}) => {
+    const first = await plugin({ registry_dir })
+    const started = []
+    for (const { args, cwd } of runs) {
+        const run = await first.start({ args, cwd })
+        await first.send({
+            run_id: run.run_id,
+            token: run.token,
+            entries: [runStarted({ spec: 10 })],
+        })
+        started.push(run)
+    }
+    return started
+}
+
+export const listed = ({
+    run_id,
+    restart = true,
+    reason = 'resumable',
+    message = null,
+}: Partial<UnfinishedRun> & { run_id: string }): UnfinishedRun => ({
+    run_id,
+    restart,
+    reason,
+    message,
+})
+
+export const registryEntry = async ({
+    registry_dir,
+    run_id,
+}: {
+    registry_dir: string
+    run_id: string
+}) => {
+    const file = JSON.parse(
+        await Bun.file(join(registry_dir, 'runs.json')).text()
+    ) as { runs: { run_id: string; restarts: number; ended: unknown }[] }
+    return file.runs.find((entry) => entry.run_id === run_id)
+}
+
+export const runOf = async ({
+    harness,
+    run_id,
+}: {
+    harness: Harness
+    run_id: string
+}) => {
+    const { selected } = await harness.read({ run_id })
+    if (!selected) throw new Error(`no run ${run_id}`)
+    return selected.run
+}
+
+export const eventTexts = ({ harness }: { harness: Harness }) =>
+    harness.rows.flatMap(({ row }) =>
+        row.kind === ROW_KIND.event ? [row.data.text] : []
+    )

package/board/server/engine-watch.ts

@@ -131,6 +131,18 @@ export type StopWhy =
     | { kind: 'check_failed'; error: string }
     | { kind: 'spawn_failed'; error: string }
 
+/**
+ * How the owner resumes run `run_id` with the board attached: the
+ * `/luca-run resume` slash command (see `resumeRow`). A bare
+ * `luca-run --resume` would run without the board's token, so the board
+ * would show it read-only.
+ *
+ * @example
+ * resumeHint({ run_id: 'r1' }) // 'type /luca-run resume r1 in a Paseo chat'
+ */
+export const resumeHint = ({ run_id }: { run_id: string }): string =>
+    `type /luca-run resume ${run_id} in a Paseo chat`
+
 /**
  * What the board says when a run's engine is gone and the plugin won't
  * restart it. The panel and header show it as "The engine stopped: <text>".
@@ -147,22 +159,22 @@ export const engineStoppedText = ({
     run_id: string
     log_path: string
 }): string => {
-    const resume = `luca-run --resume ${run_id}`
+    const resume = resumeHint({ run_id })
     switch (why.kind) {
         case 'demo':
             return `its process is gone, and a demo can't be picked up again. Start a new one with /luca-run demo. Its log is ${log_path}.`
         case 'not_listed':
             return `its process is gone, and its journal has nothing to pick up again (it never wrote one, or the run already ended). Read its log: ${log_path}.`
         case 'launcher_stopped':
-            return `The run stopped: ${why.reason}. It isn't restarted automatically, because it would stop the same way. Fix that, then run ${resume}. Its log is ${log_path}.`
+            return `The run stopped: ${why.reason}. It isn't restarted automatically, because it would stop the same way. Fix that, then ${resume}. Its log is ${log_path}.`
         case 'billing_stopped':
             return `The run stopped for billing: ${why.reason}. It will not go on; start a new run once per-token billing is off.`
         case 'restarts_used_up':
-            return `it stopped again after ${MAX_AUTO_RESTARTS} automatic restarts, so Paseo stopped restarting it. Read its log: ${log_path}. To try once more, run ${resume}.`
+            return `it stopped again after ${MAX_AUTO_RESTARTS} automatic restarts, so Paseo stopped restarting it. Read its log: ${log_path}. To try once more, ${resume}.`
         case 'check_failed':
-            return `its process is gone, and Paseo couldn't check whether the run can go on (${why.error}). To go on from its journal, run ${resume}. Its log is ${log_path}.`
+            return `its process is gone, and Paseo couldn't check whether the run can go on (${why.error}). To go on from its journal, ${resume}. Its log is ${log_path}.`
         case 'spawn_failed':
-            return `its process is gone, and Paseo couldn't restart the engine: ${why.error}. To go on from its journal, run ${resume}. Its log is ${log_path}.`
+            return `its process is gone, and Paseo couldn't restart the engine: ${why.error}. To go on from its journal, ${resume}. Its log is ${log_path}.`
     }
 }
 
@@ -195,3 +207,31 @@ export const restartRow = ({
         tone: 'warning',
     },
 })
+
+/** The words of the chat row for a run resumed with `/luca-run resume`. */
+export const RESUMED_TEXT =
+    'The run was resumed from its journal with /luca-run resume.'
+
+/**
+ * The chat row for a run resumed with `/luca-run resume`; its id is unique
+ * per run and time, so each resume gets its own row.
+ *
+ * @example
+ * resumeRow({ run_id, time: new Date().toISOString() })
+ */
+export const resumeRow = ({
+    run_id,
+    time,
+}: {
+    run_id: string
+    time: string
+}): BoardRow => ({
+    id: `${run_id}-resumed-${time}`,
+    kind: ROW_KIND.event,
+    data: {
+        time,
+        ticket: null,
+        text: RESUMED_TEXT,
+        tone: 'info',
+    },
+})