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

package/board/server/ticket-stages-panel-helpers.ts

@@ -0,0 +1,296 @@
+import { expect } from 'bun:test'
+
+import { createHarness, type Harness } from './testing/board-harness'
+import {
+    agentFinished,
+    agentStarted,
+    baselineTests,
+    commitMade,
+    finding,
+    gatesRun,
+    intakeOfThree,
+    leftoverScan,
+    redCheck,
+    reviewFinished,
+    runBranchPushed,
+    sessionOf,
+    ticketJoined,
+    ticketWorktreeCreated,
+    type Entry,
+} from './testing/journal-fixtures'
+
+/**
+ * Helpers shared by the ticket stage tests (`ticket-stages-panel.test.ts`
+ * and the `ticket-stages-panel-*.test.ts` files beside it).
+ *
+ * The harness is the one the running test started; `runWith` sets it, and
+ * each test file cleans it up after every test.
+ */
+
+export let harness: Harness
+export let sent = { run_id: '', token: '', next_seq: 1 }
+
+/** Starts a run and sends intake plus `entries` in one go. */
+export const runWith = async ({ entries }: { entries: Entry[] }) => {
+    harness = await createHarness()
+    const { run_id, token } = await harness.start()
+    const reply = await harness.send({
+        run_id,
+        token,
+        entries: [...intakeOfThree(), ...entries],
+    })
+    expect(reply.ok).toBe(true)
+    sent = { run_id, token, next_seq: reply.next_seq }
+}
+
+/** Sends more records to the same run, after the ones already sent. */
+export const sendMore = async ({ entries }: { entries: Entry[] }) => {
+    const reply = await harness.send({
+        run_id: sent.run_id,
+        token: sent.token,
+        entries,
+        first_seq: sent.next_seq,
+    })
+    expect(reply.ok).toBe(true)
+    sent = { ...sent, next_seq: reply.next_seq }
+}
+
+/**
+ * `step_started` as the engine journals it: `key` is the ticket's number,
+ * or `run` for a step of no ticket; `step` is the action type, plus
+ * `:<role>` for an agent's turn.
+ */
+export const stepStarted = ({
+    ticket,
+    step,
+    role = null,
+}: {
+    ticket: number | null
+    step: string
+    role?: string | null
+}): Entry => ({
+    kind: 'step_started',
+    ticket,
+    role,
+    content: {
+        key: ticket === null ? 'run' : String(ticket),
+        step,
+        first_seq: null,
+    },
+})
+
+/** `step_ended` as the engine journals it once the step settles. */
+export const stepEnded = ({
+    ticket,
+    step,
+    role = null,
+}: {
+    ticket: number | null
+    step: string
+    role?: string | null
+}): Entry => ({
+    kind: 'step_ended',
+    ticket,
+    role,
+    content: { key: ticket === null ? 'run' : String(ticket), step },
+})
+
+/** A whole step: its start, the records it wrote, and its end. */
+export const wholeStep = ({
+    ticket,
+    step,
+    role = null,
+    entries,
+}: {
+    ticket: number | null
+    step: string
+    role?: string | null
+    entries: Entry[]
+}): Entry[] => [
+    stepStarted({ ticket, step, role }),
+    ...entries,
+    stepEnded({ ticket, step, role }),
+]
+
+/** An agent's turn starting: its step, then its `agent_started`. */
+export const agentTurnStarts = ({
+    ticket,
+    role,
+    follow_up = false,
+}: {
+    ticket: number
+    role: string
+    follow_up?: boolean
+}): Entry[] => [
+    stepStarted({
+        ticket,
+        step: `${follow_up ? 'follow_up_agent' : 'launch_agent'}:${role}`,
+        role,
+    }),
+    agentStarted({
+        ticket,
+        role,
+        follow_up_of: follow_up ? sessionOf({ ticket, role }) : null,
+    }),
+]
+
+/** An agent's turn ending: its result, then its step's end. */
+export const agentTurnEnds = ({
+    ticket,
+    role,
+    follow_up = false,
+    finished,
+}: {
+    ticket: number
+    role: string
+    follow_up?: boolean
+    finished?: Entry
+}): Entry[] => [
+    finished ?? agentFinished({ ticket, role }),
+    stepEnded({
+        ticket,
+        step: `${follow_up ? 'follow_up_agent' : 'launch_agent'}:${role}`,
+        role,
+    }),
+]
+
+/** A commit of `stage`, with its leftover scan, as one step. */
+export const committed = ({
+    ticket,
+    stage,
+}: {
+    ticket: number
+    stage: 'red' | 'green' | 'fix'
+}): Entry[] =>
+    wholeStep({
+        ticket,
+        step: 'commit_ticket',
+        entries: [
+            leftoverScan({ ticket, stage }),
+            commitMade({ ticket, stage }),
+        ],
+    })
+
+/** The checks running on the ticket's worktree (or the run branch). */
+export const gatesStart = ({ ticket }: { ticket: number }): Entry =>
+    stepStarted({ ticket, step: 'run_gates' })
+
+export const gatesEnd = ({
+    ticket,
+    ok,
+    target = 'ticket',
+}: {
+    ticket: number
+    ok: boolean
+    target?: 'ticket' | 'run_branch'
+}): Entry[] => [
+    gatesRun({ ticket, ok, target }),
+    stepEnded({ ticket, step: 'run_gates' }),
+]
+
+export const blockerOnly = [finding({ id: 'R1-1', severity: 'blocker' })]
+
+/** One point in a ticket's life: the records up to it, and its stage then. */
+export type Checkpoint = { at: string; entries: Entry[]; stage: string }
+
+/**
+ * Sends each checkpoint's records in order and reads the ticket's stage
+ * after each, as `<at>: <stage>` lines, so a wrong stage names its point.
+ */
+export const stagesAlong = async ({
+    ticket,
+    checkpoints,
+}: {
+    ticket: number
+    checkpoints: Checkpoint[]
+}): Promise<string[]> => {
+    const seen: string[] = []
+    for (const { at, entries } of checkpoints) {
+        await sendMore({ entries })
+        seen.push(`${at}: ${(await harness.ticket({ number: ticket })).stage}`)
+    }
+    return seen
+}
+
+export const expectedAlong = ({
+    checkpoints,
+}: {
+    checkpoints: Checkpoint[]
+}): string[] => checkpoints.map(({ at, stage }) => `${at}: ${stage}`)
+
+export const stageOf = async ({ ticket }: { ticket: number }) =>
+    (await harness.ticket({ number: ticket })).stage
+
+/** Ticket `ticket` from its worktree to its tests committed. */
+export const testsCommitted = ({ ticket }: { ticket: number }): Entry[] => [
+    ticketWorktreeCreated({ ticket }),
+    ...wholeStep({
+        ticket,
+        step: 'run_baseline_tests',
+        entries: [baselineTests({ ticket, passed: 4 })],
+    }),
+    ...agentTurnStarts({ ticket, role: 'test-writer' }),
+    ...agentTurnEnds({ ticket, role: 'test-writer' }),
+    ...wholeStep({
+        ticket,
+        step: 'run_red_check',
+        entries: [redCheck({ ticket, ok: true, failing: 2, passing: 4 })],
+    }),
+    ...committed({ ticket, stage: 'red' }),
+]
+
+/** Ticket `ticket` up to its first ticket review asking for changes. */
+export const reviewedOnce = ({ ticket }: { ticket: number }): Entry[] => [
+    ...testsCommitted({ ticket }),
+    ...agentTurnStarts({ ticket, role: 'implementer' }),
+    ...agentTurnEnds({ ticket, role: 'implementer' }),
+    gatesStart({ ticket }),
+    ...gatesEnd({ ticket, ok: true }),
+    ...committed({ ticket, stage: 'green' }),
+    ...agentTurnStarts({ ticket, role: 'ticket-reviewer' }),
+]
+
+/** Ticket `ticket` approved by its ticket review, not yet joined. */
+export const approved = ({ ticket }: { ticket: number }): Entry[] => [
+    ...reviewedOnce({ ticket }),
+    ...agentTurnEnds({
+        ticket,
+        role: 'ticket-reviewer',
+        finished: reviewFinished({ ticket }),
+    }),
+]
+
+/** An approved ticket's join, its gates on the run branch, and the push. */
+export const joinedAndPushed = ({ ticket }: { ticket: number }): Entry[] => [
+    ...wholeStep({
+        ticket,
+        step: 'join_run_branch',
+        entries: [ticketJoined({ ticket })],
+    }),
+    gatesStart({ ticket }),
+    ...gatesEnd({ ticket, ok: true, target: 'run_branch' }),
+    ...wholeStep({
+        ticket,
+        step: 'push_run_branch',
+        entries: [runBranchPushed({ ticket })],
+    }),
+]
+
+/** The refactor ticket 11: no test-writer and no red check. */
+export const refactorDone = (): Entry[] => [
+    ticketWorktreeCreated({ ticket: 11 }),
+    ...agentTurnStarts({ ticket: 11, role: 'implementer' }),
+    ...agentTurnEnds({ ticket: 11, role: 'implementer' }),
+    gatesStart({ ticket: 11 }),
+    ...gatesEnd({ ticket: 11, ok: true }),
+    ...committed({ ticket: 11, stage: 'green' }),
+    ...agentTurnStarts({ ticket: 11, role: 'ticket-reviewer' }),
+    ...agentTurnEnds({
+        ticket: 11,
+        role: 'ticket-reviewer',
+        finished: reviewFinished({ ticket: 11 }),
+    }),
+    ...joinedAndPushed({ ticket: 11 }),
+]
+
+export const T = 13

package/board/shared/board-rows.ts

@@ -85,6 +85,15 @@ export const StuckRowSchema = z.object({
     tried: z.array(z.string()),
     replies: z.array(z.string()),
     resolution: z.string().nullable(),
+    /**
+     * The run and the stuck item, for the row's reply buttons and "Help me"
+     * (#503). Defaulted, so a row added before them still renders (without
+     * the buttons).
+     */
+    run_id: z.string().nullable().default(null),
+    key: z.string().nullable().default(null),
+    ticket: z.number().int().nullable().default(null),
+    since: z.string().nullable().default(null),
 })
 
 export type StuckRow = z.infer<typeof StuckRowSchema>

package/board/shared/board-rpc.ts

@@ -6,6 +6,7 @@ import {
     EngineEndedSchema,
     RunSummarySchema,
 } from './board-state'
+import { PostedReplySchema } from './reply-actions'
 
 /**
  * The plugin's RPCs. Payload keys are snake_case (API convention).
@@ -14,6 +15,7 @@ import {
  * - `engine.event`: the engine sends its journal records to the board.
  * - `board.read`: the side panel polls the runs of one workspace.
  * - `board.version`: `luca doctor` asks which Luca version is loaded.
+ * - `reply.post`: a reply button on stuck work posts its word on the spec.
  */
 
 /**
@@ -105,6 +107,13 @@ export const BoardReadInputSchema = z.object({
 export const BoardReadOutputSchema = z.object({
     runs: z.array(RunSummarySchema),
     selected: BoardStateSchema.nullable(),
+    /**
+     * The chat the selected run started in, for "Help me"; `null` for a run
+     * the plugin didn't start. Defaulted, so an older daemon's answer parses.
+     */
+    chat_agent_id: z.string().nullable().default(null),
+    /** The replies the board posted for the selected run (#503). */
+    posted: z.array(PostedReplySchema).default([]),
 })
 
 export const boardReadRpc = defineRpc({
@@ -129,3 +138,36 @@ export const boardVersionRpc = defineRpc({
     input: z.object({}),
     output: BoardVersionOutputSchema,
 })
+
+/**
+ * API Request: post one reply on a run's spec issue (#503). `key` is the
+ * stuck item's (`ticket-<n>`, `final`, or `run`), and `reply` one of the
+ * words the engine takes for it, such as `retry #134`.
+ */
+export const ReplyPostInputSchema = z.object({
+    run_id: z.string().min(1),
+    key: z.string().min(1),
+    reply: z.string().min(1),
+})
+
+/**
+ * API Response: `posted` (it went on the spec now), `already_posted` (the
+ * same reply was posted for this item before; nothing was posted again),
+ * `refused` (the board won't post it, and says why), or `failed` (`gh`
+ * failed). `ok` is true for the first two.
+ */
+export const ReplyPostOutputSchema = z.object({
+    ok: z.boolean(),
+    status: z.enum(['posted', 'already_posted', 'refused', 'failed']),
+    message: z.string(),
+    posted: PostedReplySchema.nullable(),
+})
+
+export const replyPostRpc = defineRpc({
+    name: 'reply.post',
+    input: ReplyPostInputSchema,
+    output: ReplyPostOutputSchema,
+})
+
+export type ReplyPostInput = z.infer<typeof ReplyPostInputSchema>
+export type ReplyPostOutput = z.infer<typeof ReplyPostOutputSchema>

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

@@ -0,0 +1,77 @@
+/**
+ * What the board only counts: the decision model's questions, agent
+ * messages, and memory with its learner.
+ */
+import { z } from 'zod'
+
+/**
+ * The decision model (Clef; Jev in older journals) in shadow mode: how often
+ * the engine asked it and what came back. The engine never acts on the
+ * answers, so the board only counts them.
+ */
+export const JevCountsSchema = z.object({
+    asked: z.number().int().min(0),
+    answered: z.number().int().min(0),
+    failed: z.number().int().min(0),
+})
+
+export type JevCounts = z.infer<typeof JevCountsSchema>
+
+/**
+ * Agent messages: `sent` counts the queued and the not delivered ones,
+ * `refused` the ones the engine turned down, and `delivered` the messages
+ * handed over, once per receiver (a message to `all` can count more than
+ * once). Messages happen inside a turn, so the board only counts them.
+ */
+export const MessageCountsSchema = z.object({
+    sent: z.number().int().min(0),
+    refused: z.number().int().min(0),
+    delivered: z.number().int().min(0),
+})
+
+export type MessageCounts = z.infer<typeof MessageCountsSchema>
+
+/**
+ * Where the learner stands at the end of a run (#370): `waiting` until it
+ * starts (a run without memory never starts it), `learning`, `learned`
+ * once it answered, or `skipped` when the engine gave up on it.
+ */
+export const LearnerStateSchema = z.enum([
+    'waiting',
+    'learning',
+    'learned',
+    'skipped',
+])
+
+export type LearnerState = z.infer<typeof LearnerStateSchema>
+
+/**
+ * Memory (#370), counted: the searches at recall points (and the vault
+ * searches among them that failed), the memories they showed agents, the
+ * learner, and what became of its memories. Memory changes no ticket, so
+ * the board only counts it.
+ */
+export const MemoryCountsSchema = z.object({
+    searches: z.number().int().min(0),
+    search_errors: z.number().int().min(0),
+    shown: z.number().int().min(0),
+    learner: LearnerStateSchema,
+    added: z.number().int().min(0),
+    updated: z.number().int().min(0),
+    refused: z.number().int().min(0),
+    failed: z.number().int().min(0),
+})
+
+export type MemoryCounts = z.infer<typeof MemoryCountsSchema>
+
+/** Memory before any of its records. */
+export const NO_MEMORY: MemoryCounts = {
+    searches: 0,
+    search_errors: 0,
+    shown: 0,
+    learner: 'waiting',
+    added: 0,
+    updated: 0,
+    refused: 0,
+    failed: 0,
+}

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

@@ -0,0 +1,99 @@
+/**
+ * The live file (#628) in the board's state: what an agent in a turn is
+ * doing now, from the engine's `live.json`, never from the journal.
+ */
+import { z } from 'zod'
+
+/**
+ * A live file written longer ago than this means the engine is hung or
+ * gone (#635). The engine rewrites it at least every 5 seconds, so a long
+ * tool call never gets near it.
+ */
+export const LIVE_STALE_MS = 60_000
+
+/**
+ * Whether a live file written at `written_at` is fresh at `now`: written
+ * at most `LIVE_STALE_MS` ago.
+ *
+ * @example
+ * liveIsFresh({ written_at: '2026-09-23T12:30:00.000Z', now: Date.parse('2026-09-23T12:31:10.000Z') }) // false
+ */
+export const liveIsFresh = ({
+    written_at,
+    now,
+}: {
+    written_at: string
+    now: number
+}): boolean => now - Date.parse(written_at) <= LIVE_STALE_MS
+
+/** The agent's latest action: a tool and a short target, with its time. */
+export const LiveActionSchema = z.object({
+    tool: z.string(),
+    target: z.string(),
+    at: z.string(),
+})
+
+/** A tool call still running, since `started_at`. */
+export const LiveOpenCallSchema = z.object({
+    tool: z.string(),
+    target: z.string(),
+    started_at: z.string(),
+})
+
+/**
+ * One of an agent's helpers (#636): a read-only Haiku session it started,
+ * with its latest action and whether it's done.
+ */
+export const LiveHelperSchema = z.object({
+    model: z.string().nullable().default(null),
+    action: LiveActionSchema.nullable().default(null),
+    done: z.boolean().default(false),
+})
+
+export type LiveHelper = z.infer<typeof LiveHelperSchema>
+
+/** One agent in a turn, as the live file has it. */
+export const LiveAgentSchema = z.object({
+    ticket: z.number().int().nullable(),
+    role: z.string(),
+    model: z.string().nullable().default(null),
+    /** The turn's tokens so far, cache reads included; the journal has none of them yet. */
+    tokens: z.number().min(0).default(0),
+    action: LiveActionSchema.nullable().default(null),
+    open_call: LiveOpenCallSchema.nullable().default(null),
+    /**
+     * The agent's activity count for each of the last 30 seconds (#631),
+     * oldest first; a file from before has none.
+     */
+    activity: z.array(z.number().min(0)).catch([]).default([]),
+    /** The agent's helpers (#636), oldest first; a file from before has none. */
+    helpers: z.array(LiveHelperSchema).catch([]).default([]),
+})
+
+export type LiveAgent = z.infer<typeof LiveAgentSchema>
+
+/** One action of the run's live feed (#634): when, who, on which model, and what. */
+export const LiveFeedEntrySchema = z.object({
+    at: z.string(),
+    ticket: z.number().int().nullable(),
+    role: z.string(),
+    model: z.string().nullable().default(null),
+    tool: z.string(),
+    target: z.string(),
+})
+
+export type LiveFeedEntry = z.infer<typeof LiveFeedEntrySchema>
+
+/**
+ * A wait inside a step (#632): a ticket's check waits for a prepare slot
+ * or a test slot, while `in_use` of the engine's `slots` are taken.
+ */
+export const LiveWaitSchema = z.object({
+    ticket: z.number().int(),
+    for: z.enum(['prepare_slot', 'test_slot']),
+    in_use: z.number().int().min(0),
+    slots: z.number().int().min(0),
+    since: z.string(),
+})
+
+export type LiveWait = z.infer<typeof LiveWaitSchema>

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

@@ -0,0 +1,59 @@
+/**
+ * The final review in the board's state: its lenses, and where the review
+ * stands.
+ */
+import { z } from 'zod'
+
+import { FindingCountsSchema } from './board-state-ticket'
+
+export const LENS_NAMES = [
+    'architecture',
+    'simplification',
+    'security',
+    'integration',
+    'rules',
+] as const
+
+export const LensNameSchema = z.enum(LENS_NAMES)
+
+export type LensName = z.infer<typeof LensNameSchema>
+
+export const LensStateSchema = z.enum([
+    'waiting',
+    'reviewing',
+    'fixing',
+    'clean',
+])
+
+export type LensState = z.infer<typeof LensStateSchema>
+
+export const LensCardSchema = z.object({
+    name: LensNameSchema,
+    state: LensStateSchema,
+    findings: FindingCountsSchema,
+})
+
+export type LensCard = z.infer<typeof LensCardSchema>
+
+export const FinalReviewStateSchema = z.enum([
+    'waiting',
+    'reviewing',
+    'fixing',
+    'stuck',
+    'passed',
+])
+
+export type FinalReviewState = z.infer<typeof FinalReviewStateSchema>
+
+export const FinalReviewSchema = z.object({
+    state: FinalReviewStateSchema,
+    /** False (drawn dimmed) until every ticket is done or skipped. */
+    active: z.boolean(),
+    round: z.number().int().min(0),
+    fix_round: z.number().int().min(0),
+    lenses: z.array(LensCardSchema),
+    /** What was tried on it so far, oldest first. */
+    tried: z.array(z.string()),
+})
+
+export type FinalReview = z.infer<typeof FinalReviewSchema>