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

package/engine/journal/reply-replay.ts

@@ -0,0 +1,144 @@
+/**
+ * The owner's replies and the engine's stuck reports in replay: a reply
+ * taken for the run, the final review, or a ticket; a report for the stuck
+ * run, the final review, or a ticket; and a ticket's `retry`.
+ */
+import omit from 'lodash/omit'
+
+import type { JournalRecord } from './journal-record'
+import { engineCommentsAfter, type RunState } from './run-state'
+import { applyTicketRecord } from './ticket-replay'
+
+import { runBudgetOf } from '../limits/run-budget'
+
+/**
+ * An owner's reply: `stop` ends the run, a bare `retry` or `ship` is the
+ * stuck run's or the final review's, and the rest go to its ticket.
+ */
+export const replyReceivedAfter = ({
+    state,
+    next,
+    record,
+}: {
+    /** The state before the record. */
+    state: RunState
+    /** The state with the record's seq and crash counts. */
+    next: RunState
+    record: Extract<JournalRecord, { kind: 'reply_received' }>
+}): RunState => {
+    const handled = {
+        ...next,
+        handled_comments: [
+            ...state.handled_comments,
+            record.content.comment_id,
+        ],
+    }
+    const { word, comment_id, ticket } = record.content
+    if (word === 'stop') return { ...handled, stop: { comment_id } }
+    // A bare `retry` while the run is stuck on its budget adds its top-up
+    // (one whole budget for a retry journaled before top-ups, #543), and
+    // the run carries on; stuck on its PR, the PR is tried again; stuck on
+    // its repo wait, it waits 24 hours more.
+    const { stuck } = state.run_budget
+    if (ticket === null && word === 'retry' && stuck !== null) {
+        const top_up =
+            stuck.reason === 'run_budget'
+                ? (record.content.top_up ??
+                  runBudgetOf({ config: state.config }))
+                : 0
+        return {
+            ...handled,
+            repo_wait:
+                stuck.reason === 'repo_busy'
+                    ? { status: 'waiting', since: record.time }
+                    : state.repo_wait,
+            run_budget: {
+                stuck: null,
+                report: null,
+                top_ups: state.run_budget.top_ups + top_up,
+            },
+        }
+    }
+    if (ticket === null && (word === 'retry' || word === 'ship')) {
+        return { ...handled, final_reply: { word, comment_id } }
+    }
+    return applyTicketRecord({ state: handled, record })
+}
+
+/** A stuck report the engine posted, for the run, the final review, or a ticket. */
+export const stuckReportedAfter = ({
+    state,
+    next,
+    record,
+}: {
+    state: RunState
+    next: RunState
+    record: Extract<JournalRecord, { kind: 'stuck_reported' }>
+}): RunState => {
+    const reported = {
+        ...next,
+        engine_comments: engineCommentsAfter({
+            state,
+            comment_id: record.content.comment_id,
+        }),
+    }
+    // A report with no ticket is the stuck run's, while it is not
+    // told yet, else the final review's.
+    const { run_budget } = state
+    if (
+        record.ticket === null &&
+        run_budget.stuck !== null &&
+        run_budget.report === null
+    ) {
+        return {
+            ...reported,
+            run_budget: {
+                ...run_budget,
+                report: { comment_id: record.content.comment_id },
+            },
+        }
+    }
+    return record.ticket === null
+        ? {
+              ...reported,
+              final_stuck_report: {
+                  comment_id: record.content.comment_id,
+              },
+          }
+        : applyTicketRecord({ state: reported, record })
+}
+
+/** A ticket's `retry`, with the run-wide parts it resets. */
+export const ticketRetriedAfter = ({
+    state,
+    next,
+    record,
+}: {
+    state: RunState
+    next: RunState
+    record: Extract<JournalRecord, { kind: 'ticket_retried' }>
+}): RunState => {
+    const { answer_id, mode } = record.content
+    const install = state.run_branch_install?.check
+    // A run branch whose install failed is installed again on a retry.
+    const run_branch_install =
+        mode === 'refused' || install === undefined || install?.ok !== false
+            ? state.run_branch_install
+            : null
+    return applyTicketRecord({
+        state: {
+            ...next,
+            // A retry gives the ticket fresh crash counts too.
+            crashes:
+                record.ticket === null
+                    ? next.crashes
+                    : omit(next.crashes, String(record.ticket)),
+            run_branch_install,
+            engine_comments: engineCommentsAfter({
+                state,
+                comment_id: answer_id,
+            }),
+        },
+        record,
+    })
+}

package/engine/journal/repo-wait-entries.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod'
+
+import { ENTRY_FIELDS } from './entry-fields'
+
+/**
+ * The journal entries of the repo wait (#615): a run started while an
+ * earlier run on the same repo is going waits for it, before intake.
+ */
+
+/**
+ * The run waits for the earlier runs on its repo that are going, named by
+ * run id and spec (`null` for a demo). The spec issue was told once.
+ */
+export const RepoWaitStartedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('repo_wait_started'),
+    content: z.object({
+        runs: z.array(
+            z.object({
+                run_id: z.string().min(1),
+                spec: z.number().int().positive().nullable(),
+            })
+        ),
+    }),
+})
+
+/** No earlier run on the repo is going anymore: the run goes on to intake. */
+export const RepoWaitEndedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('repo_wait_ended'),
+    content: z.object({}),
+})
+
+/**
+ * The repo wait couldn't check whether the earlier runs are going, since
+ * `ps` failed (#624): `error` says how. Journaled once per wait, which goes
+ * on, counting every unfinished run as going.
+ */
+export const RepoWaitPsFailedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('repo_wait_ps_failed'),
+    content: z.object({ error: z.string() }),
+})
+
+/**
+ * The run was started with `luca-run --alongside`, so it never waits for
+ * another run on its repo. Journaled right after `run_started`.
+ */
+export const RepoWaitSkippedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('repo_wait_skipped'),
+    content: z.object({}),
+})

package/engine/journal/run-entries.ts

@@ -0,0 +1,172 @@
+import { z } from 'zod'
+
+import { ENTRY_FIELDS } from './entry-fields'
+
+import { AgentRoleSchema } from '../agents/role-results'
+import { ConfigChangeSchema } from '../config/config-reload'
+import { EngineConfigSchema } from '../config/engine-config'
+
+/**
+ * The journal entries of the run's own life: its start, resumes and config
+ * reloads, a stop, and the scheduler's step records.
+ */
+
+export const RunStartedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('run_started'),
+    content: z.object({
+        spec_number: z.number().int().positive(),
+        config: EngineConfigSchema,
+        /** The branch the run branch starts from and its PR merges into. */
+        base_branch: z.string().min(1).default('main'),
+        /**
+         * Memory for this run (#370): on, with the project's vault (`null`
+         * searches only `default`), or `null` for off. Off leaves the run
+         * exactly as it was before memory.
+         */
+        memory: z
+            .object({ project_vault: z.string().min(1).nullable() })
+            .nullable()
+            .default(null),
+        /**
+         * The repo the run is on, as an absolute path, so `luca-run --resume`
+         * can find it. `null` in older journals.
+         */
+        repo: z.string().min(1).nullable().default(null),
+        /**
+         * Luca's version the run started on (#460). `null` in older
+         * journals.
+         */
+        luca_version: z.string().min(1).nullable().default(null),
+    }),
+})
+
+/**
+ * The engine started again on the run's journal (#460), on Luca's version
+ * `luca_version`, which may differ from the one in `run_started`. Journaled
+ * once per resume, before the engine's first step. Nothing reads it but
+ * the board.
+ */
+export const EngineResumedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('engine_resumed'),
+    content: z.object({ luca_version: z.string().min(1) }),
+})
+
+/**
+ * A resume read the repo's `.luca/config.json` again (#516), and the
+ * build fields it reloads (`RELOADED_FIELDS`) changed: each one, old to
+ * new. Journaled right after the resume's `engine_resumed`, only when
+ * something changed. Replay puts the new values on the run's config.
+ */
+export const ConfigReloadedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('config_reloaded'),
+    content: z.object({ changes: z.array(ConfigChangeSchema).min(1) }),
+})
+
+/**
+ * A resume could not take the repo's config (#516): it is missing, not
+ * JSON, not a valid config, or one intake would refuse. The run keeps the
+ * config it had and goes on. `reason` says what is wrong.
+ */
+export const ConfigReloadRefusedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('config_reload_refused'),
+    content: z.object({ reason: z.string().min(1) }),
+})
+
+/**
+ * The run stopped because going on was unsafe: the wrong credentials or
+ * plan, the wrong model, or a foreign MCP server. A later `runEngine` on the
+ * same journal picks the step up again.
+ *
+ * A `billing` stop (overage, or a billing error) sticks: the run never goes
+ * on, however often the engine is started again on its journal.
+ */
+export const RunStoppedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('run_stopped'),
+    content: z.object({
+        reason: z.string(),
+        role: AgentRoleSchema.nullable().default(null),
+        billing: z.boolean().default(false),
+        /**
+         * The same step was cut off by a crash `MAX_CRASHES` times in a row
+         * on a run-level key: like a billing stop, it sticks.
+         */
+        crashed: z.boolean().default(false),
+    }),
+})
+
+/**
+ * The scheduler is about to carry out one step: an action it started, other
+ * than a wait. `key` is the scheduler's key for it (a ticket's number,
+ * `final`, `lens:<lens>`, `replies`, or `run`), and `step` its action type,
+ * plus `:<role>` for an agent's turn. `first_seq` is the `step_started` seq
+ * of this step's first try when a crash cut off an earlier try of it, else
+ * `null`. `ticket` is the action's ticket, and `role` the agent's role.
+ */
+export const StepStartedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('step_started'),
+    content: z.object({
+        key: z.string().min(1),
+        step: z.string().min(1),
+        first_seq: z.number().int().min(1).nullable().default(null),
+    }),
+})
+
+/**
+ * The step under `key` settled: its own records are in the journal, so it
+ * is a checkpoint. Not written when the step threw.
+ */
+export const StepEndedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('step_ended'),
+    content: z.object({
+        key: z.string().min(1),
+        step: z.string().min(1),
+    }),
+})
+
+/**
+ * A ticket began to wait on purpose between steps (#559): `baseline` for
+ * another ticket's shared baseline tests, `join` for the join queue,
+ * `start` for the start queue, each on `on_ticket`. Journaled once when the
+ * wait starts, since `since`; the ticket's next `step_started` ends it.
+ * Only the board reads it.
+ */
+export const TicketWaitingEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('ticket_waiting'),
+    content: z.object({
+        for: z.enum(['baseline', 'join', 'start']),
+        on_ticket: z.number().int().positive().nullable(),
+        since: z.iso.datetime(),
+    }),
+})
+
+/** One step a crash cut off: its `step_started` had no `step_ended`. */
+export const InterruptedStepSchema = z.object({
+    key: z.string().min(1),
+    step: z.string().min(1),
+    ticket: z.number().int().positive().nullable(),
+    role: z.string().nullable(),
+    /** The seq of the cut-off step's `step_started`. */
+    started_seq: z.number().int().min(1),
+    /** That record's `first_seq`: the step's first try, if it was a redo. */
+    first_seq: z.number().int().min(1).nullable(),
+})
+
+export type InterruptedStep = z.infer<typeof InterruptedStepSchema>
+
+/**
+ * A restarted engine found steps a crash cut off, journaled once before its
+ * first step. Each is taken again, an agent's turn in a fresh session.
+ */
+export const RunResumedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('run_resumed'),
+    content: z.object({ interrupted: z.array(InterruptedStepSchema) }),
+})

package/engine/journal/run-state.ts

@@ -0,0 +1,264 @@
+/**
+ * The shape of a run's state as replay rebuilds it, with its run-wide parts
+ * (snapshot, comments, PR, notes, budget), its empty value, and the small
+ * run-wide updates: the snapshot's phase, run notes, and engine comments.
+ */
+import { EMPTY_FINAL_REVIEW, type FinalReviewState } from './final-review-state'
+import type { JournalRecord, RunStuckReason } from './journal-record'
+import { EMPTY_MEMORY, type MemoryState } from './memory-replay'
+import type { PlanState } from './plan-replay'
+import type { CrashCounts } from './step-records'
+import type {
+    ReplayedGates,
+    ReplayedInstall,
+    ReplayedWorktree,
+    TicketProgress,
+} from './ticket-progress'
+
+import type { AgentRole } from '../agents/role-results'
+import type { EngineConfig } from '../config/engine-config'
+import type { TestCaseRef } from '../gates/gate-schemas'
+import type {
+    IntakeProblem,
+    IntakeRead,
+    LeftOutTicket,
+    SpecSnapshot,
+    TicketSnapshot,
+} from '../intake/intake-schemas'
+
+/** Where a run stands, as far as intake goes. */
+export type RunPhase =
+    | 'new'
+    | 'started'
+    | 'intake_read'
+    | 'refused'
+    | 'nothing_to_do'
+    /** The spec snapshot is written but some ticket snapshots are not. */
+    | 'snapshotting'
+    | 'intake_passed'
+
+/** The snapshot as replayed from `spec_snapshot` and `ticket_snapshot`. */
+export type ReplayedSnapshot = {
+    spec: SpecSnapshot
+    ticket_order: number[]
+    closed_tickets: number[]
+    /** The latest snapshot of each ticket, keyed by ticket number. */
+    tickets: Record<number, TicketSnapshot>
+    /** The open tickets intake left out for a person, and why (#499). */
+    left_out: LeftOutTicket[]
+}
+
+/** A comment the engine read on the spec issue. */
+export type ReplayedComment = {
+    comment_id: number
+    author: string
+    body: string
+}
+
+/** The run's pull request, once opened. */
+export type ReplayedPullRequest = { number: number; url: string }
+
+/** One run note, with the agent that wrote it. */
+export type ReplayedRunNote = { ticket: number; role: AgentRole; note: string }
+
+/**
+ * The run budget (#435): whether the run is stuck on it (or on its PR,
+ * #508) and told, and how many tokens the owner's `retry` replies added.
+ */
+export type RunBudgetState = {
+    /** The run is stuck, until the owner's `retry`. */
+    stuck: { reason: RunStuckReason; detail: string } | null
+    /** The spec issue's comment that told the owner the run is stuck. */
+    report: { comment_id: number } | null
+    /**
+     * Tokens added by `retry` (#543): the run may use its budget plus these.
+     * A retry journaled with no top-up added one whole budget.
+     */
+    top_ups: number
+}
+
+/**
+ * The repo wait (#615), before intake: not begun (`none`), waiting for an
+ * earlier run on the repo, over, or skipped (`luca-run --alongside`).
+ */
+export type RepoWaitState = {
+    status: 'none' | 'waiting' | 'ended' | 'skipped'
+    /**
+     * When the wait began, or the owner's `retry` of a run stuck on it
+     * (`repo_busy`): its 24 hours count from here.
+     */
+    since: string | null
+}
+
+/** An old test that failed in a ticket's check, at its record's time (#544). */
+export type OldTestFailure = TestCaseRef & { ticket: number; time: string }
+
+/** A run's state, rebuilt only from its journal. There is no status file. */
+export type RunState = {
+    phase: RunPhase
+    spec_number: number | null
+    config: EngineConfig | null
+    base_branch: string | null
+    intake: IntakeRead | null
+    problems: IntakeProblem[] | null
+    snapshot: ReplayedSnapshot | null
+    run_branch: ReplayedWorktree | null
+    /** The install in the run branch's checkout, once it ran. */
+    run_branch_install: ReplayedInstall | null
+    tickets: Record<number, TicketProgress>
+    /**
+     * The repo had a changesets config when the run branch was made, so a
+     * changeset is written before the PR (#461).
+     */
+    changesets: boolean
+    /** The run's changeset, once written and pushed. */
+    changeset: { path: string | null; sha: string } | null
+    pull_request: ReplayedPullRequest | null
+    plan: PlanState
+    /**
+     * The seq of each ticket's latest usage record (a retried ticket that
+     * finishes again gets another), and whether the run's is recorded.
+     */
+    usage_recorded: { tickets: Record<number, number>; run: boolean }
+    /** The worktrees the engine removed at the end of the run. */
+    removed_worktrees: string[]
+    /**
+     * Every session journaled as closed (`agent_session_closed`), or found
+     * gone by a follow-up (#521). None is ever a follow-up target again.
+     */
+    closed_sessions: string[]
+    /**
+     * Every run note from every finished agent in the run, oldest first
+     * (journal order), word for word.
+     */
+    run_notes: ReplayedRunNote[]
+    /** The latest gates on the run branch: after a join, or a final review fix. */
+    run_branch_gates: ReplayedGates | null
+    /**
+     * Every untracked path a prepare run made in any of the run's checkouts
+     * (`prepare_made`), in journal order. Never an agent's work: the engine
+     * leaves them out of commits, the leftover scan, and role rules.
+     */
+    prepare_made: string[]
+    /**
+     * Every old test (one that passed at its ticket's baseline) that failed
+     * in a ticket's red check, gates or join gates, oldest first (#544).
+     */
+    old_test_failures: OldTestFailure[]
+    final_review: FinalReviewState
+    /** Comments read on the spec issue while waiting for replies, oldest first. */
+    comments: ReplayedComment[]
+    /** Comments already taken as a reply, or sent back. */
+    handled_comments: number[]
+    /** Comments the engine itself posted on the spec issue. */
+    engine_comments: number[]
+    /** The owner replied `stop`: nothing new starts, and the run ends without a PR. */
+    stop: { comment_id: number } | null
+    /** The spec issue's comment that told the owner the final review is stuck. */
+    final_stuck_report: { comment_id: number } | null
+    /** The owner's reply to the stuck final review, until the engine acts on it. */
+    final_reply: { word: 'retry' | 'ship'; comment_id: number } | null
+    /** The run's budget of tokens: stuck on it, and the budgets added (#435). */
+    run_budget: RunBudgetState
+    /** The wait for earlier runs on the same repo (#615). */
+    repo_wait: RepoWaitState
+    /** Memory's recalls, the learner, and the saves (#370). */
+    memory: MemoryState
+    /**
+     * Crashes in a row per scheduler key (`run_resumed`), until a step under
+     * the key ends. A ticket's `retry`, or the final review's, clears its own.
+     */
+    crashes: CrashCounts
+    /** Set once a stop for crashes is journaled. It sticks. */
+    crash_stopped: { reason: string } | null
+    last_seq: number
+}
+
+export const EMPTY_STATE: RunState = {
+    phase: 'new',
+    spec_number: null,
+    config: null,
+    base_branch: null,
+    intake: null,
+    problems: null,
+    snapshot: null,
+    run_branch: null,
+    run_branch_install: null,
+    tickets: {},
+    changesets: false,
+    changeset: null,
+    pull_request: null,
+    plan: {
+        hit: null,
+        wait: null,
+        resets_announced: [],
+        billing: null,
+        billing_stopped: null,
+        usage_wait: null,
+        waited_until: null,
+    },
+    usage_recorded: { tickets: {}, run: false },
+    removed_worktrees: [],
+    closed_sessions: [],
+    run_notes: [],
+    run_branch_gates: null,
+    prepare_made: [],
+    old_test_failures: [],
+    final_review: EMPTY_FINAL_REVIEW,
+    comments: [],
+    handled_comments: [],
+    engine_comments: [],
+    stop: null,
+    final_stuck_report: null,
+    final_reply: null,
+    run_budget: { stuck: null, report: null, top_ups: 0 },
+    repo_wait: { status: 'none', since: null },
+    memory: EMPTY_MEMORY,
+    crashes: {},
+    crash_stopped: null,
+    last_seq: 0,
+}
+
+export const snapshotPhase = ({
+    snapshot,
+}: {
+    snapshot: ReplayedSnapshot
+}): RunPhase =>
+    snapshot.ticket_order.every((number) => number in snapshot.tickets)
+        ? 'intake_passed'
+        : 'snapshotting'
+
+/** The run's notes after an agent finished: its own go at the end. */
+export const notesAfter = ({
+    state,
+    record,
+}: {
+    state: RunState
+    record: Extract<JournalRecord, { kind: 'agent_finished' }>
+}): ReplayedRunNote[] => {
+    const { ticket, content } = record
+    // Reviewers (the ticket reviewer and the lenses) leave no run notes.
+    if (ticket === null || !('run_notes' in content.result)) {
+        return state.run_notes
+    }
+    return [
+        ...state.run_notes,
+        ...content.result.run_notes.map((note) => ({
+            ticket,
+            role: content.role,
+            note,
+        })),
+    ]
+}
+
+/** The spec comments the engine posted, plus this one if it posted one. */
+export const engineCommentsAfter = ({
+    state,
+    comment_id,
+}: {
+    state: RunState
+    comment_id: number | null
+}): number[] =>
+    comment_id === null
+        ? state.engine_comments
+        : [...state.engine_comments, comment_id]