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

package/board/shared/board-state-run.ts

@@ -0,0 +1,236 @@
+/**
+ * The run in the board's state: where it stands (status and phase), why it
+ * stopped, the run's own facts, the budget, the stuck work that needs a
+ * reply, the tickets left out for a person, and the run list's summaries.
+ */
+import { z } from 'zod'
+
+/**
+ * Why the run stopped and what to do, in words. A billing stop, or a stop
+ * after the same step crashed again and again, won't go on; any other stop
+ * picks up again when the run is started with its run id.
+ *
+ * @example
+ * stoppedText({ reason: 'overage in use', billing: true })
+ * // 'Stopped for billing: overage in use. This run will not go on; ...'
+ */
+export const stoppedText = ({
+    reason,
+    billing,
+    crashed,
+}: {
+    reason: string
+    billing: boolean
+    /** The same run-level step crashed again and again. */
+    crashed?: boolean
+}): string => {
+    if (billing) {
+        return `Stopped for billing: ${reason}. This run will not go on; start a new run once per-token billing is off.`
+    }
+    if (crashed === true) {
+        return `Stopped after crashes: ${reason} This run will not go on; read the engine's log for why it crashed, then start a new run.`
+    }
+    return `The run stopped: ${reason}. Start it again with the same run id to pick up where it stopped.`
+}
+
+/** Where a run stands, as one word for the header row and the panel. */
+export const RunStatusSchema = z.enum([
+    'starting',
+    'intake',
+    'building',
+    'final_review',
+    'limit_wait',
+    'usage_line_wait',
+    'done',
+    'refused',
+    'nothing_to_do',
+    'stuck',
+    'stopped',
+    'ended_with_error',
+])
+
+export type RunStatus = z.infer<typeof RunStatusSchema>
+
+/** The part of a run's status the journal sets directly. */
+export const RunPhaseSchema = z.enum([
+    'starting',
+    'intake',
+    'building',
+    'final_review',
+    'done',
+    'refused',
+    'nothing_to_do',
+])
+
+export type RunPhase = z.infer<typeof RunPhaseSchema>
+
+/** Stuck work waiting for a one-word reply on the spec issue. */
+export const NeedsYouSchema = z.object({
+    /** `ticket-<n>`, `final`, or `run` (the run stuck on its budget). */
+    key: z.string(),
+    ticket: z.number().int().nullable(),
+    subject: z.string(),
+    reason: z.string(),
+    detail: z.string(),
+    /** What was tried before it got stuck, oldest first. */
+    tried: z.array(z.string()),
+    /** The exact replies to post as a comment on the spec issue. */
+    replies: z.array(z.string()),
+    since: z.string(),
+})
+
+export type NeedsYou = z.infer<typeof NeedsYouSchema>
+
+/**
+ * The engine's default run budget in tokens (its
+ * `DEFAULT_RUN_BUDGET_TOKENS`, in `engine/src/limits/run-budget.ts`), for a
+ * run whose engine config sets no `run_budget_tokens`. The plugin never
+ * loads the engine's code, so the number is kept here too.
+ */
+export const DEFAULT_RUN_BUDGET_TOKENS = 9_000_000
+
+/**
+ * The engine's default `models.confidence_bar` (in
+ * `engine/src/config/engine-config-schema.ts`): the decision model is sharp at or
+ * over it, split under it. Kept here for the same reason.
+ */
+export const DEFAULT_CONFIDENCE_BAR = 0.8
+
+export const EngineEndedSchema = z.object({
+    ok: z.boolean(),
+    message: z.string(),
+})
+
+export type EngineEnded = z.infer<typeof EngineEndedSchema>
+
+/**
+ * The run stopped because going on was unsafe (wrong credentials or plan,
+ * a rejected rate limit, overage, ...). Starting it again with the same run
+ * id picks the step up again, except after a billing stop, which won't go on.
+ */
+export const RunStoppedSchema = z.object({
+    reason: z.string(),
+    role: z.string().nullable(),
+    ticket: z.number().int().nullable(),
+    /** The session would bill per token; this run won't go on. */
+    billing: z.boolean(),
+    /** The same step crashed again and again; this run won't go on. */
+    crashed: z.boolean().default(false),
+    since: z.string(),
+})
+
+export type RunStopped = z.infer<typeof RunStoppedSchema>
+
+export const RunInfoSchema = z.object({
+    run_id: z.string(),
+    /** `null` for a demo run until the engine names its spec. */
+    spec_number: z.number().int().nullable(),
+    spec_title: z.string().nullable(),
+    demo: z.boolean(),
+    branch: z.string().nullable(),
+    phase: RunPhaseSchema,
+    status: RunStatusSchema,
+    pr_url: z.string().nullable(),
+    pr_number: z.number().int().nullable(),
+    /** Why intake refused the run, one line per problem. */
+    refusal: z.array(z.string()),
+    started_at: z.string(),
+    last_time: z.string().nullable(),
+    engine_ended: EngineEndedSchema.nullable(),
+    /** Set by `run_stopped`, cleared once the engine moves on. */
+    stopped: RunStoppedSchema.nullable(),
+    log_path: z.string().nullable(),
+    /**
+     * Luca's version the run started on (#460); `null` when its journal
+     * doesn't say. Defaulted, so an older board state still parses.
+     */
+    started_on: z.string().nullable().default(null),
+    /**
+     * Set once the run resumed on a different Luca version than it started
+     * on, naming both. The run keeps going. Defaulted, so an older board
+     * state still parses.
+     */
+    version_note: z.string().nullable().default(null),
+    /**
+     * The spec's owner (its issue's author), from intake (#503): only their
+     * replies count. `null` when the journal doesn't say. Defaulted, so an
+     * older board state still parses.
+     */
+    spec_author: z.string().nullable().default(null),
+    /** The spec's repo as `owner/repo`, from its URL; `null` when not known. */
+    spec_repo: z.string().nullable().default(null),
+})
+
+export type RunInfo = z.infer<typeof RunInfoSchema>
+
+/** The run phases after which no engine is needed. */
+export const OVER_PHASES: ReadonlySet<RunPhase> = new Set<RunPhase>([
+    'done',
+    'refused',
+    'nothing_to_do',
+])
+
+/**
+ * Whether a run may still need an engine: not ended, not over. The
+ * server's engine check and the panel's "no sign of life" both go by it.
+ *
+ * @example
+ * needsEngine({ state }) // true while the run builds
+ */
+export const needsEngine = ({ state }: { state: { run: RunInfo } }): boolean =>
+    state.run.engine_ended === null && !OVER_PHASES.has(state.run.phase)
+
+/**
+ * An open ticket the run left out for a person (#499): one labeled
+ * `ready-for-human`, or one waiting on such a ticket. Not a problem, so the
+ * board lists it calmly and nobody is asked to act.
+ */
+export const PersonTicketSchema = z.object({
+    number: z.number().int(),
+    title: z.string(),
+    /** Why, in words: `for a person`, or `waits on #12, which is for a person`. */
+    why: z.string(),
+})
+
+export type PersonTicket = z.infer<typeof PersonTicketSchema>
+
+/** One run in the panel's run list. */
+export const RunSummarySchema = z.object({
+    run_id: z.string(),
+    spec_number: z.number().int().nullable(),
+    spec_title: z.string().nullable(),
+    demo: z.boolean(),
+    status: RunStatusSchema,
+    started_at: z.string(),
+    needs_you: z.number().int().min(0),
+})
+
+export type RunSummary = z.infer<typeof RunSummarySchema>
+
+/** How many of the newest runs get a tab; the older ones are folded. */
+export const RECENT_RUN_TABS = 6
+
+/**
+ * Splits runs (newest first) into the ones with a tab and the folded older
+ * ones. A picked older run keeps a tab too, after the newest ones.
+ *
+ * @example
+ * const { shown, folded } = foldRuns({ runs, selected: picked })
+ */
+export const foldRuns = ({
+    runs,
+    selected,
+}: {
+    runs: RunSummary[]
+    selected: string | null
+}): { shown: RunSummary[]; folded: RunSummary[] } => {
+    const shown = runs.slice(0, RECENT_RUN_TABS)
+    const older = runs.slice(RECENT_RUN_TABS)
+    const picked = older.find((run) => run.run_id === selected)
+    return picked
+        ? {
+              shown: [...shown, picked],
+              folded: older.filter((run) => run !== picked),
+          }
+        : { shown, folded: older }
+}

package/board/shared/board-state-ticket.ts

@@ -0,0 +1,257 @@
+/**
+ * A ticket's card in the board's state: its steps and stage, its findings,
+ * the check that is open, the step the engine is in, and the card itself.
+ */
+import { z } from 'zod'
+
+import { LiveAgentSchema, LiveWaitSchema } from './board-state-live'
+import { PlanUsedSchema } from './board-state-usage'
+
+/** The steps of a ticket, shown as dots on its card. */
+export const STEP_NAMES = [
+    'tests',
+    'red check',
+    'code',
+    'checks',
+    'review',
+] as const
+
+/** Refactor tickets skip the first two steps: no new test can fail first. */
+export const REFACTOR_SKIPS_STEPS = 2
+
+/** The step index a ticket has when every step is done. */
+export const ALL_STEPS_DONE = STEP_NAMES.length
+
+/**
+ * What a ticket is really doing (#549): `building` its first test-writer and
+ * implementer pass, `reviewing` only while a reviewer works, `testing` the red
+ * check or the checks, `fixing` any fix round, `joining` the run branch and
+ * the checks there. Every older stage is still one, so a stored board state
+ * from before still parses.
+ */
+export const TicketStageSchema = z.enum([
+    'blocked',
+    'building',
+    'reviewing',
+    'testing',
+    'fixing',
+    'joining',
+    'stuck',
+    'done',
+    'skipped',
+])
+
+export type TicketStage = z.infer<typeof TicketStageSchema>
+
+export const FindingCountsSchema = z.object({
+    blocker: z.number().int().min(0),
+    should_fix: z.number().int().min(0),
+    nit: z.number().int().min(0),
+})
+
+export type FindingCounts = z.infer<typeof FindingCountsSchema>
+
+/**
+ * A check whose failure went back to an agent: its fix loop is open. `review`
+ * is a ticket review that asked for changes: the next fixer starts a review
+ * fix round.
+ */
+export const OpenCheckSchema = z.enum(['red_check', 'gates', 'review'])
+
+export type OpenCheck = z.infer<typeof OpenCheckSchema>
+
+/**
+ * What the engine is doing right now for a ticket or the run, from its
+ * `step_started`, such as "running the baseline tests"; `since` is that
+ * record's time. Cleared by the step's `step_ended`.
+ */
+export const CurrentStepSchema = z.object({
+    text: z.string(),
+    since: z.string(),
+})
+
+export type CurrentStep = z.infer<typeof CurrentStepSchema>
+
+/** The baseline tests' step (`run_baseline_tests`) in words. */
+export const BASELINE_STEP_TEXT = 'running the baseline tests'
+
+/**
+ * What a ticket waits for between steps (#559): `baseline` another
+ * ticket's shared baseline tests, `join` the join queue, `start` the start
+ * queue, each on `on_ticket`. From the engine's `ticket_waiting`.
+ */
+export const WaitForSchema = z.enum(['baseline', 'join', 'start'])
+
+export type WaitFor = z.infer<typeof WaitForSchema>
+
+/**
+ * A ticket between steps, since `since`: from `ticket_waiting` with what it
+ * waits for, or from its last `step_ended` with `for` and `on_ticket` null
+ * (an old journal's wait, worked out from the board). Cleared by the
+ * ticket's next `step_started`.
+ */
+export const TicketWaitSchema = z.object({
+    for: WaitForSchema.nullable(),
+    on_ticket: z.number().int().nullable(),
+    since: z.string(),
+})
+
+export type TicketWait = z.infer<typeof TicketWaitSchema>
+
+/**
+ * A time span in words: seconds under a minute, then minutes and seconds,
+ * then hours and minutes.
+ *
+ * @example
+ * elapsedText({ ms: 125_000 }) // '2m 5s'
+ * elapsedText({ ms: 3_790_000 }) // '1h 3m'
+ */
+export const elapsedText = ({ ms }: { ms: number }): string => {
+    const seconds = Math.max(0, Math.floor(ms / 1000))
+    const hours = Math.floor(seconds / 3600)
+    const minutes = Math.floor((seconds % 3600) / 60)
+    if (hours > 0) return `${hours}h ${minutes}m`
+    if (minutes > 0) return `${minutes}m ${seconds % 60}s`
+    return `${seconds}s`
+}
+
+/**
+ * The current step in words, with how long it has been running.
+ *
+ * @example
+ * currentStepText({
+ *     step: { text: 'running the checks', since: '2026-09-23T12:00:00.000Z' },
+ *     now: Date.parse('2026-09-23T12:02:05.000Z'),
+ * }) // 'running the checks (2m 5s)'
+ */
+export const currentStepText = ({
+    step,
+    now,
+}: {
+    step: CurrentStep
+    now: number
+}): string =>
+    `${step.text} (${elapsedText({ ms: now - Date.parse(step.since) })})`
+
+/**
+ * The decision model's answer to an agent's `agent_model` ask: the model it
+ * picked and how sure it was, either `null` when the answer lacks it.
+ */
+export const ModelAnswerSchema = z.object({
+    role: z.string(),
+    pick: z.string().nullable(),
+    confidence: z.number().nullable(),
+})
+
+export type ModelAnswer = z.infer<typeof ModelAnswerSchema>
+
+/**
+ * The model the card's latest agent runs on (#630), from its
+ * `agent_started`, and why: its `model_reason` (`null` in older journals)
+ * and its `agent_model` answer, if any.
+ */
+export const AgentModelSchema = z.object({
+    role: z.string(),
+    name: z.string(),
+    reason: z.string().nullable(),
+    answer: ModelAnswerSchema.nullable(),
+})
+
+export type AgentModel = z.infer<typeof AgentModelSchema>
+
+export const TicketCardSchema = z.object({
+    number: z.number().int(),
+    title: z.string(),
+    refactor: z.boolean(),
+    /** Tickets of this run this one waits on. */
+    blockers: z.array(z.number().int()),
+    /** The engine has begun work on it (its worktree exists). */
+    started: z.boolean(),
+    stage: TicketStageSchema,
+    /**
+     * Index into STEP_NAMES of the current step: -1 not started, 5 when every
+     * step is done. A stuck or skipped ticket keeps the step it stopped at.
+     */
+    step: z.number().int().min(-1).max(ALL_STEPS_DONE),
+    /** One-word (or two) activity, such as "coding" or "reviewing". */
+    activity: z.string(),
+    /** The role working on it now, `null` when no agent is. */
+    role: z.string().nullable(),
+    /**
+     * The latest agent's model and why; `null` before one starts, or when
+     * its journal names no model. Defaulted, so an older board state still
+     * parses.
+     */
+    model: AgentModelSchema.nullable().default(null),
+    /**
+     * The decision model's latest `agent_model` answer, kept until its
+     * agent starts. Defaulted, so an older board state still parses.
+     */
+    model_answer: ModelAnswerSchema.nullable().default(null),
+    /**
+     * Each role's last used `agent_model` answer, by role, for its
+     * follow-ups, which ask nothing new. Defaulted, so an older board state
+     * still parses.
+     */
+    model_answers: z.record(z.string(), ModelAnswerSchema).default({}),
+    /**
+     * The engine's step on it now, `null` between steps. Defaulted, so a
+     * board state from before it still parses.
+     */
+    current_step: CurrentStepSchema.nullable().default(null),
+    /**
+     * The ticket between steps, `null` in a step or before its first.
+     * Defaulted, so a board state from before it still parses.
+     */
+    wait: TicketWaitSchema.nullable().default(null),
+    /** Fix rounds in the current fix loop; back to 0 once its check passes. */
+    fix_round: z.number().int().min(0),
+    review_round: z.number().int().min(0),
+    /** Review fix rounds so far (up to LOOP_CAP): fixes after a review. */
+    review_fix_round: z.number().int().min(0),
+    /** The check whose failure the next follow-up answers, if any. */
+    open_check: OpenCheckSchema.nullable(),
+    /** The role whose latest turn failed, until an agent finishes again. */
+    failed_turn: z.string().nullable(),
+    tests: z
+        .object({
+            failing: z.number().int().min(0),
+            total: z.number().int().min(0),
+        })
+        .nullable(),
+    /**
+     * Its own baseline's test counts, kept so a ticket that reuses this one's
+     * baseline (`baseline_reused`) gets them after `tests` has moved on.
+     * Defaulted, so a board state from before it still parses.
+     */
+    baseline_tests: z
+        .object({
+            failing: z.number().int().min(0),
+            total: z.number().int().min(0),
+        })
+        .nullable()
+        .default(null),
+    findings: FindingCountsSchema.nullable(),
+    /** Every token the ticket's agents read or wrote, cache reads included. */
+    tokens: z.number().min(0),
+    /** The same tokens by role. */
+    agent_tokens: z.record(z.string(), z.number().min(0)),
+    /** What was tried on it so far (failed checks, fix rounds), oldest first. */
+    tried: z.array(z.string()),
+    /** How much of the plan the ticket used, per window; empty until known. */
+    plan_used: z.array(PlanUsedSchema),
+    /**
+     * Its agent's entry in the run's live file (#628), `null` with none.
+     * Laid over the state on each read, never journaled. Defaulted, so a
+     * board state from before it still parses.
+     */
+    live: LiveAgentSchema.nullable().default(null),
+    /**
+     * Its check's wait for a prepare slot or a test slot (#632), from the
+     * live file the same way, `null` with none. Defaulted, so a board
+     * state from before it still parses.
+     */
+    slot_wait: LiveWaitSchema.nullable().default(null),
+})
+
+export type TicketCard = z.infer<typeof TicketCardSchema>

package/board/shared/board-state-usage.ts

@@ -0,0 +1,107 @@
+/**
+ * Plan usage in the board's state: the color level of a percent, plan
+ * windows in words and in their shown order, how much of a window something
+ * used, and the plan's latest reading.
+ */
+import { z } from 'zod'
+
+/** Plan usage is yellow from this percent. */
+export const USAGE_WARN_FROM = 60
+
+/** Plan usage is red above this percent. */
+export const USAGE_HIGH_ABOVE = 85
+
+export const UsageLevelSchema = z.enum(['ok', 'warn', 'high'])
+
+export type UsageLevel = z.infer<typeof UsageLevelSchema>
+
+/**
+ * The color level of a plan usage percent: `ok` (green) below 60, `warn`
+ * (yellow) from 60 to 85, `high` (red) above 85.
+ *
+ * @example
+ * usageLevel({ percent: 59 }) // 'ok'
+ * usageLevel({ percent: 85 }) // 'warn'
+ * usageLevel({ percent: 86 }) // 'high'
+ */
+export const usageLevel = ({ percent }: { percent: number }): UsageLevel => {
+    if (percent > USAGE_HIGH_ABOVE) return 'high'
+    if (percent >= USAGE_WARN_FROM) return 'warn'
+    return 'ok'
+}
+
+/** Plan windows in words; any other window keeps its raw name. */
+const WINDOW_WORDS: Record<string, string> = {
+    five_hour: 'five-hour',
+    seven_day: 'weekly',
+    seven_day_opus: 'weekly Opus',
+    seven_day_sonnet: 'weekly Sonnet',
+}
+
+/**
+ * A plan window's name in words.
+ *
+ * @example
+ * windowWords({ window: 'seven_day_opus' }) // 'weekly Opus'
+ * windowWords({ window: 'overage' }) // 'overage'
+ */
+export const windowWords = ({ window }: { window: string }): string =>
+    WINDOW_WORDS[window] ?? window
+
+/**
+ * The order windows are shown in: five-hour, weekly, the other weekly ones
+ * (Opus, Sonnet, ...), then the rest.
+ */
+export const windowRank = ({ window }: { window: string }): number => {
+    if (window === 'five_hour') return 0
+    if (window === 'seven_day') return 1
+    if (window.startsWith('seven_day')) return 2
+    return 3
+}
+
+/** How much of one plan window something used, as a whole percent. */
+export const PlanUsedSchema = z.object({
+    /** The window in words, such as "five-hour" or "weekly". */
+    window: z.string(),
+    percent: z.number(),
+})
+
+export type PlanUsed = z.infer<typeof PlanUsedSchema>
+
+/**
+ * The plan used, in words, windows in their shown order.
+ *
+ * @example
+ * planUsedText({ used, sign: '+' }) // 'five-hour +1%, weekly +1%'
+ * planUsedText({ used, sign: '' }) // 'five-hour 3%, weekly 1%'
+ */
+export const planUsedText = ({
+    used,
+    sign,
+}: {
+    used: PlanUsed[]
+    sign: '+' | ''
+}): string =>
+    used.map(({ window, percent }) => `${window} ${sign}${percent}%`).join(', ')
+
+/**
+ * The plan's usage, from the rate-limit readings in agents' sessions. Each
+ * window keeps its latest reading; `null` until one arrives.
+ */
+export const UsageSchema = z.object({
+    five_hour_percent: z.number().nullable(),
+    weekly_percent: z.number().nullable(),
+    five_hour_level: UsageLevelSchema.nullable(),
+    weekly_level: UsageLevelSchema.nullable(),
+    /** When the five-hour window resets. */
+    resets_at: z.string().nullable(),
+    read_at: z.string(),
+})
+
+export type Usage = z.infer<typeof UsageSchema>
+
+/**
+ * The words on the plan usage: its windows are the whole account's, every
+ * run's and chat's, never one run's.
+ */
+export const USAGE_LABEL = 'plan usage (account-wide)'