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

package/engine/cli/run-demo.ts

@@ -0,0 +1,143 @@
+/**
+ * The practice run, `luca-run --demo` (`runDemo`): a throwaway repo, scripted
+ * agents, and a fake MuninnDB, safe to try the board with.
+ */
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { errorText, driveRun, type RunEnd } from './run-end'
+
+import type { AgentLauncher } from '../agents/agent-launcher'
+import { createScriptedLauncher } from '../agents/scripted-launcher'
+import type { BoardSync } from '../board/board-sync'
+import { loadEngineConfig } from '../config/engine-config'
+import { runEngine, startRun } from '../core/execute'
+import { createGitAdapter } from '../git/git-adapter'
+import { createJournal, runJournalPath } from '../journal/journal'
+import {
+    DEMO_TURNS,
+    demoMuninn,
+    demoTracker,
+    makePracticeRepo,
+    PRACTICE_SPEC_NUMBER,
+} from '../testing/practice-run'
+import type { InMemoryPullRequest } from '../tracker/in-memory-tracker'
+
+/** How long each scripted agent turn of the demo takes, so the board is watchable. */
+export const DEMO_TURN_DELAY_MS = 1500
+
+/** Wraps a launcher so each agent turn takes at least `delay_ms`. */
+const slowLauncher = ({
+    launcher,
+    delay_ms,
+    log,
+}: {
+    launcher: AgentLauncher
+    delay_ms: number
+    log: (line: string) => void
+}): AgentLauncher => ({
+    launch: async (args) => {
+        log(`[luca-run] ${args.role} on #${args.ticket}`)
+        await Bun.sleep(delay_ms)
+        return launcher.launch(args)
+    },
+    followUp: async (args) => {
+        log(`[luca-run] ${args.role} on #${args.ticket} (follow-up)`)
+        await Bun.sleep(delay_ms)
+        return launcher.followUp(args)
+    },
+    closeSession: (args) => launcher.closeSession(args),
+})
+
+/**
+ * A practice run, safe to try the board with: a throwaway repo with a local
+ * bare origin in a temp folder, the practice spec with two tickets (#12
+ * blocked by #11) in an in-memory tracker, and scripted agents that take
+ * `turn_delay_ms` per turn. No GitHub, no models, no network: the decision
+ * model is off (its credentials are never read), and memory (#370) is a fake MuninnDB seeded with
+ * a few memories, so the board shows searches, the learner, and a save
+ * with nothing leaving the machine. The temp folder (which also holds the run's
+ * journal) is removed at the end.
+ *
+ * @returns The run's end, the PRs the in-memory tracker opened, and the
+ * (removed) temp folder.
+ *
+ * @example
+ * const { ok, pull_requests } = await runDemo({ run_id, board: null, log: console.log, turn_delay_ms: DEMO_TURN_DELAY_MS })
+ */
+export const runDemo = async ({
+    run_id,
+    board,
+    log,
+    turn_delay_ms,
+}: {
+    run_id: string
+    board: BoardSync | null
+    log: (line: string) => void
+    turn_delay_ms: number
+}): Promise<
+    RunEnd & { pull_requests: InMemoryPullRequest[]; root: string }
+> => {
+    const root = await mkdtemp(join(tmpdir(), 'luca-demo-'))
+    try {
+        const { repo, origin } = await makePracticeRepo({ root })
+        const journal = createJournal({
+            file: runJournalPath({ runs_dir: join(root, 'runs'), run_id }),
+        })
+        log(`[luca-run] demo run ${run_id} in ${root}`)
+        log(`[luca-run] repo: ${repo}`)
+        log(`[luca-run] origin: ${origin}`)
+        log(`[luca-run] journal: ${journal.file}`)
+        log('[luca-run] decision model off: the demo never asks it.')
+        const loaded = await loadEngineConfig({ repo_root: repo })
+        if (!loaded.ok) throw new Error(loaded.error)
+        const tracker = demoTracker()
+        startRun({
+            journal,
+            spec_number: PRACTICE_SPEC_NUMBER,
+            config: loaded.config,
+            base_branch: 'main',
+            memory: { project_vault: null },
+            repo,
+        })
+        const memory = { client: demoMuninn() }
+        const launcher = slowLauncher({
+            launcher: createScriptedLauncher({
+                turns: DEMO_TURNS,
+            }),
+            delay_ms: turn_delay_ms,
+            log,
+        })
+        const end = await driveRun({
+            journal,
+            // A demo's journal is in a temp folder that is removed at its end.
+            run_id: null,
+            launcher,
+            memory,
+            board,
+            log,
+            run: () =>
+                runEngine({
+                    journal,
+                    tracker,
+                    git: createGitAdapter({ repo_root: repo }),
+                    launcher,
+                    memory,
+                    board: board ?? undefined,
+                }),
+        })
+        return { ...end, pull_requests: tracker.pullRequests(), root }
+    } catch (error) {
+        const end = {
+            ok: false,
+            message: `The demo crashed: ${errorText(error)}`,
+        }
+        log(`[luca-run] stopped: ${end.message}`)
+        await board?.end(end)
+        return { ...end, pull_requests: [], root }
+    } finally {
+        await rm(root, { recursive: true, force: true })
+        log(`[luca-run] removed ${root}`)
+    }
+}

package/engine/cli/run-end.ts

@@ -0,0 +1,184 @@
+/**
+ * How a run ends for the person watching it: what a run's last action means
+ * (`RunEnd`), how to go on from its journal (`resumeCommand`), and driving the
+ * engine to its end without ever throwing (`driveRun`).
+ */
+import type { AgentLauncher } from '../agents/agent-launcher'
+import type { BoardSync } from '../board/board-sync'
+import type { EngineAction } from '../core/decide'
+import { nothingToDoText } from '../core/left-out'
+import type { Journal } from '../journal/journal'
+import type { JournalRecord } from '../journal/journal-record'
+import type { MemoryDeps } from '../memory/memory-client'
+
+/** How a `luca-run` process ended; the board gets it as `ended`. */
+export type RunEnd = { ok: boolean; message: string }
+
+/**
+ * An agent launcher a run may close at its end, such as the Claude launcher,
+ * which keeps sessions open for follow-ups.
+ */
+export type RunLauncher = AgentLauncher & { closeAll?: () => Promise<void> }
+
+/** An error's message, or any other thrown value as text. */
+export const errorText = (error: unknown): string =>
+    error instanceof Error ? error.message : String(error)
+
+/**
+ * What a run's last action means for the person watching it. A run with
+ * nothing to do says why, from its `nothing_to_do` record in `records`.
+ */
+const endOf = ({
+    action,
+    records,
+}: {
+    action: EngineAction
+    records: JournalRecord[]
+}): RunEnd => {
+    if (action.type === 'invalid_journal') {
+        return {
+            ok: false,
+            message: `The journal is not a run: ${action.reason}`,
+        }
+    }
+    if (action.type !== 'done') {
+        return {
+            ok: false,
+            message: `The engine stopped before ${action.type}.`,
+        }
+    }
+    switch (action.outcome) {
+        case 'pr_opened':
+            return {
+                ok: true,
+                message: `PR opened: ${action.pull_request.url}`,
+            }
+        case 'nothing_to_do': {
+            const end = records.findLast(
+                (record) => record.kind === 'nothing_to_do'
+            )
+            return {
+                ok: true,
+                message: nothingToDoText({
+                    content:
+                        end?.kind === 'nothing_to_do'
+                            ? end.content
+                            : {
+                                  closed_tickets: [],
+                                  already_done: [],
+                                  left_out: [],
+                              },
+                }),
+            }
+        }
+        case 'refused':
+            return {
+                ok: false,
+                message:
+                    'Intake refused the run; the spec and tickets have comments saying what is missing.',
+            }
+        case 'stopped_by_user':
+            return {
+                ok: false,
+                message:
+                    "Stopped by your `stop` reply: no PR. The run branch and the unfinished tickets' worktrees are kept.",
+            }
+        case 'all_skipped':
+            return {
+                ok: true,
+                message:
+                    'Every ticket was skipped, so there is no PR. The skipped tickets stay open.',
+            }
+        case 'stopped':
+            return {
+                ok: false,
+                message: `Run stopped for billing: ${action.reason}. It will not go on; start a new run once per-token billing is off.`,
+            }
+        case 'crashed':
+            return {
+                ok: false,
+                message: `Run stopped for good after crashes: ${action.reason} It will not go on; read the engine's log for why it crashed, then start a new run.`,
+            }
+    }
+}
+
+/**
+ * How to go on with run `run_id` from its journal: `/luca-run resume <id>`
+ * in Paseo when the board plugin started it (so the board shows it live),
+ * else `luca-run --resume <id>`. Pure.
+ *
+ * @example
+ * resumeCommand({ run_id: 'r1', board: true }) // 'type /luca-run resume r1 in a Paseo chat'
+ * resumeCommand({ run_id: 'r1', board: false }) // 'run luca-run --resume r1'
+ */
+export const resumeCommand = ({
+    run_id,
+    board,
+}: {
+    run_id: string
+    board: boolean
+}): string =>
+    board
+        ? `type /luca-run resume ${run_id} in a Paseo chat`
+        : `run luca-run --resume ${run_id}`
+
+/** `text` as a sentence, then `more`. Pure. */
+const thenSay = ({ text, more }: { text: string; more: string }): string =>
+    `${text}${/[.!?]$/.test(text) ? '' : '.'} ${more}`
+
+/**
+ * Runs the engine to its end and turns what happened into a `RunEnd`, then
+ * closes the launcher's open sessions and tells the board. A crash is caught
+ * and reported, never thrown. With `run_id`, a crash or a launcher stop says
+ * how to go on from the journal (see `resumeCommand`).
+ */
+export const driveRun = async ({
+    journal,
+    run,
+    run_id,
+    launcher,
+    memory,
+    board,
+    log,
+}: {
+    journal: Journal
+    run: () => Promise<EngineAction>
+    /** The run's id, or `null` for one that can't go on again (the demo). */
+    run_id: string | null
+    launcher: RunLauncher
+    /** Closed at the end too. */
+    memory?: MemoryDeps
+    board: BoardSync | null
+    log: (line: string) => void
+}): Promise<RunEnd> => {
+    let end: RunEnd
+    try {
+        const action = await run()
+        end = endOf({ action, records: journal.read() })
+    } catch (error) {
+        const message = errorText(error)
+        // A launcher stop is journaled as run_stopped, then thrown.
+        const stopped = message.startsWith('Run stopped:')
+        const text = stopped ? message : `The engine crashed: ${message}`
+        if (run_id === null) {
+            end = { ok: false, message: text }
+        } else {
+            const how = resumeCommand({ run_id, board: board !== null })
+            end = {
+                ok: false,
+                message: thenSay({
+                    text,
+                    more: stopped
+                        ? `Fix that, then, to go on from its journal, ${how}.`
+                        : `To go on from its journal, ${how}.`,
+                }),
+            }
+        }
+    } finally {
+        await launcher.closeAll?.()
+        await memory?.client.close().catch(() => undefined)
+    }
+    log(`[luca-run] ${end.ok ? 'finished' : 'stopped'}: ${end.message}`)
+    await board?.end({ records: journal.read(), ...end })
+    return end
+}

package/engine/cli/run-modes-helpers.ts

@@ -0,0 +1,81 @@
+import type { RunLauncher } from './run-modes'
+
+import {
+    createScriptedLauncher,
+    type ScriptedTurn,
+} from '../agents/scripted-launcher'
+import {
+    createBoardSync,
+    type BoardEnded,
+    type BoardLink,
+} from '../board/board-sync'
+import { createJournal, runJournalPath } from '../journal/journal'
+import type { JournalRecord } from '../journal/journal-record'
+
+/**
+ * What the run modes' end-to-end tests share: a stand-in for the Claude
+ * launcher, a board that keeps what it is sent, and readers of a run's journal.
+ */
+
+/**
+ * A stand-in for the Claude launcher: scripted turns, plus a `closeAll`
+ * that counts its calls.
+ */
+export const fakeClaudeLauncher = ({ turns }: { turns: ScriptedTurn[] }) => {
+    const scripted = createScriptedLauncher({ turns })
+    let closed = 0
+    const launcher: RunLauncher = {
+        launch: scripted.launch,
+        followUp: scripted.followUp,
+        closeSession: scripted.closeSession,
+        closeAll: async () => {
+            closed += 1
+        },
+    }
+    return { launcher, closed: () => closed, launches: scripted.launches }
+}
+
+/** A board that keeps everything it is sent. */
+export const recordingBoard = () => {
+    const kinds: string[] = []
+    const seqs: number[] = []
+    const endings: BoardEnded[] = []
+    const link: BoardLink = {
+        send: async ({ records, ended }) => {
+            for (const record of records) {
+                if (record.seq === seqs.length + 1) {
+                    seqs.push(record.seq)
+                    kinds.push(record.kind)
+                }
+            }
+            if (ended !== null) endings.push(ended)
+            return { ok: true, next_seq: seqs.length + 1, message: 'ok' }
+        },
+    }
+    return {
+        board: createBoardSync({ link }),
+        /** The kinds it got, without the scheduler's step records. */
+        kinds: () =>
+            kinds.filter(
+                (kind) =>
+                    kind !== 'step_started' &&
+                    kind !== 'step_ended' &&
+                    kind !== 'run_resumed'
+            ),
+        endings: () => endings,
+    }
+}
+
+/** The records of run `run_id` in `runs_dir`. */
+export const recordsOf = ({
+    runs_dir,
+    run_id,
+}: {
+    runs_dir: string
+    run_id: string
+}): JournalRecord[] =>
+    createJournal({ file: runJournalPath({ runs_dir, run_id }) }).read()
+
+/** The kinds of a run's records, oldest first. */
+export const kindsIn = (records: JournalRecord[]) =>
+    records.map(({ kind }) => kind)