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

package/board/server/board-vocabulary.ts

@@ -1,387 +1,25 @@
 import { z } from 'zod'
 
+import { ENGINE_VOCABULARY } from './board-vocabulary-engine'
+import { REVIEW_VOCABULARY } from './board-vocabulary-review'
+import { RUN_VOCABULARY } from './board-vocabulary-run'
+
+export type { LeftOutList } from './board-vocabulary-shapes'
+
 /**
  * The board's vocabulary: every journal kind the board reads, and the few
  * fields it reads from each. Schemas are loose on purpose, so the engine can
  * add fields without breaking the board, and the plugin never needs the
  * engine's code. A record whose content doesn't fit is skipped and logged.
+ *
+ * The kinds are in three modules (`board-vocabulary-run.ts`,
+ * `board-vocabulary-engine.ts`, `board-vocabulary-review.ts`) and the pieces
+ * they share in `board-vocabulary-shapes.ts`.
  */
-
-const FindingCountsSchema = z.looseObject({
-    blocker: z.number().int().min(0).catch(0),
-    should_fix: z.number().int().min(0).catch(0),
-    nit: z.number().int().min(0).catch(0),
-})
-
-const FindingListSchema = z.array(
-    z.looseObject({
-        id: z.string().catch(''),
-        severity: z.enum(['blocker', 'should_fix', 'nit']),
-    })
-)
-
-/** A re-reviewer's ruling on a fixer's "won't fix" of a review finding. */
-const RulingListSchema = z
-    .array(
-        z.looseObject({
-            finding_id: z.string(),
-            ruling: z.enum(['accepted', 'rejected']),
-            reason: z.string().catch(''),
-        })
-    )
-    .catch([])
-
-/** A review fixer's answer to each finding: `fixed` or `wont_fix`. */
-const FindingResponseListSchema = z
-    .array(
-        z.looseObject({
-            finding_id: z.string(),
-            response: z.enum(['fixed', 'wont_fix']),
-            reason: z.string().catch(''),
-        })
-    )
-    .catch([])
-
-const TestRunSchema = z.looseObject({
-    cases: z.array(z.looseObject({ status: z.string() })),
-})
-
-const WorktreeSchema = z.looseObject({ branch: z.string() })
-
-const tokenCount = z.number().min(0).catch(0)
-
-/** One plan window's reading: `utilization` 0 to 1, `resetsAt` in seconds. */
-const WindowReadingSchema = z.looseObject({
-    utilization: z.number().optional().catch(undefined),
-    resetsAt: z.number().optional().catch(undefined),
-})
-
-/**
- * One `rate_limit_event`'s info, as the Claude Agent SDK sends it:
- * `utilization` is 0 to 1, `resetsAt` is in seconds since the epoch. Real
- * readings carry no top-level `utilization`; each window's is in
- * `unifiedWindows`, keyed by window name (`five_hour`, `seven_day`, ...).
- */
-const RateLimitReadingSchema = z.looseObject({
-    rateLimitType: z.string().optional().catch(undefined),
-    utilization: z.number().optional().catch(undefined),
-    resetsAt: z.number().optional().catch(undefined),
-    unifiedWindows: z
-        .record(z.string(), WindowReadingSchema.catch({}))
-        .optional()
-        .catch(undefined),
-})
-
-const TokensSchema = z
-    .looseObject({
-        input_tokens: tokenCount,
-        output_tokens: tokenCount,
-        cache_read_input_tokens: tokenCount,
-        cache_creation_input_tokens: tokenCount,
-    })
-    .catch({
-        input_tokens: 0,
-        output_tokens: 0,
-        cache_read_input_tokens: 0,
-        cache_creation_input_tokens: 0,
-    })
-
-/** The launcher's summary of an agent's session: tokens and readings. */
-const AgentSessionSchema = z.looseObject({
-    /** The main loop's tokens. */
-    usage: TokensSchema,
-    /** The turn's tokens per model, subagents included; older journals have none. */
-    model_usage: z.record(z.string(), TokensSchema).catch({}).default({}),
-    rate_limit_events: z.array(RateLimitReadingSchema).catch([]),
-})
-
-const JevJobSchema = z.looseObject({ job: z.string() })
-
 export const BOARD_VOCABULARY = {
-    run_started: z.looseObject({
-        spec_number: z.number().int(),
-        /** The engine config; the board reads only its run budget. */
-        config: z
-            .looseObject({
-                run_budget_tokens: z
-                    .number()
-                    .int()
-                    .positive()
-                    .optional()
-                    .catch(undefined),
-            })
-            .optional()
-            .catch(undefined),
-        /** Luca's version the run started on (#460); older journals have none. */
-        luca_version: z.string().nullable().catch(null),
-    }),
-    /** The engine started again on the run's journal, on Luca's `luca_version`. */
-    engine_resumed: z.looseObject({ luca_version: z.string() }),
-    intake_read: z.looseObject({
-        spec: z.looseObject({ number: z.number(), title: z.string() }),
-    }),
-    intake_refused: z.looseObject({
-        problems: z.array(
-            z.looseObject({
-                ticket: z.number().nullable(),
-                missing: z.array(z.string()),
-            })
-        ),
-    }),
-    /** The run ends with nothing to do; `already_done` is empty at intake (#484). */
-    nothing_to_do: z.looseObject({
-        already_done: z.array(z.number().int()).catch([]).default([]),
-    }),
-    spec_snapshot: z.looseObject({
-        spec: z.looseObject({ number: z.number(), title: z.string() }),
-        ticket_order: z.array(z.number()).catch([]),
-    }),
-    ticket_snapshot: z.looseObject({
-        number: z.number().int(),
-        title: z.string(),
-        labels: z.array(z.string()).catch([]),
-        blockers: z.array(z.number().int()).catch([]),
-    }),
-    run_branch_created: WorktreeSchema,
-    ticket_worktree_created: WorktreeSchema,
-    baseline_tests: TestRunSchema,
-    /** Another ticket's baseline, taken from the same run-branch commit (#404). */
-    baseline_reused: z.looseObject({ from_ticket: z.number().int() }),
-    agent_started: z.looseObject({
-        role: z.string(),
-        /** The session a fix-loop or failed-try follow-up went to. */
-        follow_up_of: z.string().nullable().catch(null),
-    }),
-    agent_finished: z.looseObject({
-        role: z.string(),
-        result: z
-            .looseObject({
-                outcome: z.string().optional(),
-                verdict: z.string().optional(),
-                findings: FindingListSchema.optional(),
-                /** The ticket-reviewer's rulings on declined findings. */
-                rulings: RulingListSchema,
-                /** A review fixer's answer to each finding it got. */
-                finding_responses: FindingResponseListSchema,
-                /** The learner's proposed memories (#370). */
-                memories: z.array(z.unknown()).catch([]).optional(),
-                /** The shown memories the learner said helped. */
-                helped: z.array(z.string()).catch([]).optional(),
-            })
-            .catch({ rulings: [], finding_responses: [] }),
-    }),
-    agent_failed: z.looseObject({
-        role: z.string(),
-        error: z.string(),
-        /** `agent`, `result`, `guard`, or `engine`. */
-        failure: z.string().catch('agent'),
-    }),
-    agent_session: z.looseObject({
-        role: z.string(),
-        session: AgentSessionSchema,
-    }),
-    run_stopped: z.looseObject({
-        reason: z.string(),
-        role: z.string().nullable().catch(null),
-        /** A billing stop: the session would bill per token. */
-        billing: z.boolean().catch(false),
-        /** A stop after the same step crashed again and again. */
-        crashed: z.boolean().catch(false),
-    }),
-    worktree_reset: z.looseObject({}),
-    /** The engine's install in a new worktree; `check` is null with no manifest. */
-    dependencies_installed: z.looseObject({
-        target: z.string(),
-        check: z
-            .looseObject({ command: z.string(), ok: z.boolean() })
-            .nullable(),
-    }),
-    red_check: z.looseObject({
-        ok: z.boolean(),
-        problems: z.array(z.string()).catch([]),
-        tests: TestRunSchema.optional(),
-    }),
-    leftover_scan: z.looseObject({
-        /** `red`, `green`, or `fix` (a review fix round). */
-        stage: z.string(),
-        hits: z.array(z.looseObject({ path: z.string() })),
-    }),
-    /** `stage` is `red`, `green`, or `fix` (a review fix round). */
-    commit_made: z.looseObject({ stage: z.string() }),
-    gates_run: z.looseObject({
-        target: z.string(),
-        ok: z.boolean(),
-        checks: z.array(z.looseObject({ name: z.string(), ok: z.boolean() })),
-    }),
-    ticket_joined: z.looseObject({
-        ok: z.boolean(),
-        error: z.string().optional(),
-    }),
-    /** A joined ticket sent back to be fixed on top of the run branch. */
-    ticket_rebased: z.looseObject({
-        /** `clash` or `join_gates`. */
-        cause: z.string(),
-        tests: z.array(z.string()).catch([]),
-        code: z.array(z.string()).catch([]),
-    }),
-    run_branch_pushed: z.looseObject({ branch: z.string() }),
-    ticket_stuck: z.looseObject({
-        reason: z.string(),
-        detail: z.string().catch(''),
-    }),
-    /** The whole run is stuck (#435): `run_budget`, it used up its budget. */
-    run_stuck: z.looseObject({
-        reason: z.string(),
-        detail: z.string().catch(''),
-    }),
-    pull_request_opened: z.looseObject({
-        number: z.number().int(),
-        url: z.string(),
-    }),
-    /** The run's worktrees, removed at its end. Nothing visible changes. */
-    worktrees_removed: z.looseObject({
-        paths: z.array(z.string()).catch([]),
-    }),
-    // Jev in shadow mode: counted, never acted on.
-    jev_asked: JevJobSchema,
-    jev_answered: JevJobSchema,
-    jev_failed: JevJobSchema,
-    // Agent messages: sent inside an agent's turn, so they move nothing.
-    agent_message: z.looseObject({
-        from: z.string(),
-        to: z.string(),
-        text: z.string(),
-        status: z.enum(['queued', 'not_delivered', 'refused']),
-        reason: z.string().nullable().catch(null),
-    }),
-    agent_message_delivered: z.looseObject({
-        ids: z.array(z.string()).catch([]),
-    }),
-    /** Another process changed the shared `.git` during an agent's turn. */
-    shared_git_changed: z.looseObject({
-        role: z.string().catch(''),
-        changes: z.array(z.string()).catch([]),
-    }),
-    limit_wait_started: z.looseObject({
-        /** When the limit resets; `null` when not known. */
-        resets_at: z.string().nullable().catch(null),
-        /** When the engine wakes; always set by the engine. */
-        until: z.string().nullable().catch(null),
-        /** The window that was hit: `five_hour`, `seven_day`, ... */
-        rate_limit_type: z.string().nullable().catch(null),
-    }),
-    limit_wait_ended: z.looseObject({}),
-    /** The run paused at a usage line. */
-    usage_line_wait_started: z.looseObject({
-        /** `seven_day` or `five_hour`. */
-        window: z.string(),
-        /** The line, in percent. */
-        line: z.number(),
-        /** How full the window was, in percent. */
-        percent: z.number(),
-        /** When the window resets. */
-        resets_at: z.string(),
-    }),
-    /** The run carries on: `reason` is `reset` or `line_raised`. */
-    usage_line_wait_ended: z.looseObject({}),
-    /** How much of the plan a ticket (scope `ticket`) or the run used. */
-    usage_recorded: z.looseObject({
-        scope: z.enum(['ticket', 'run']),
-        ticket: z.number().int().nullable().catch(null),
-        /** Percents 0 to 100 per window, before and after, and the difference. */
-        windows: z
-            .record(z.string(), z.looseObject({ used: z.number() }))
-            .catch({}),
-    }),
-
-    /** The owner's reply on the spec issue, read by the engine (#366). */
-    reply_received: z.looseObject({
-        /** `ship` is only for a stuck final review. */
-        word: z.enum(['retry', 'skip', 'stop', 'ship']),
-        ticket: z.number().int().nullable().optional(),
-    }),
-    /** A reply the engine couldn't use; it answered why on the spec issue. */
-    reply_ignored: z.looseObject({
-        /** `no_ticket_named`, `not_stuck`, `nothing_stuck`, `ship_needs_final_review`, ... */
-        reason: z.string(),
-    }),
-    /** How the engine took a `retry` for a stuck ticket. */
-    ticket_retried: z.looseObject({
-        /** `resume`, `restart` (the ticket was edited), or `refused`. */
-        mode: z.enum(['resume', 'restart', 'refused']),
-        /** Why the edited ticket isn't ready to build, for `refused`. */
-        problems: z.array(z.string()).catch([]),
-    }),
-    /** `because`: `null` when the owner skipped it, else the skipped ticket it waits on. */
-    ticket_skipped: z.looseObject({
-        because: z.number().int().nullable().catch(null),
-    }),
-    /** A ticket whose work was already on the base branch (#484), done by `shas`. */
-    ticket_already_done: z.looseObject({
-        shas: z.array(z.string()).catch([]),
-    }),
-    /** The engine closed an already-done ticket, as the run opens no PR. */
-    ticket_closed: z.looseObject({}),
-
-    // The final review (#367). Its agent, gate, scan, commit, and push
-    // records are the usual kinds with `ticket: null`.
-    final_review_started: z.looseObject({}),
-    lens_started: z.looseObject({ lens: z.string() }),
-    lens_finished: z.looseObject({
-        lens: z.string(),
-        findings: FindingCountsSchema,
-    }),
-    final_review_fixing: z.looseObject({ round: z.number().int().min(0) }),
-    final_review_stuck: z.looseObject({
-        reason: z.string(),
-        detail: z.string().catch(''),
-    }),
-    final_review_passed: z.looseObject({}),
-    /** A `ship` reply to the stuck final review: the PR opens anyway. */
-    final_review_shipped: z.looseObject({}),
-
-    // Memory (#370): counted, and its learner shown. The learner's agent
-    // records are the usual kinds with `ticket: null` and role `learner`.
-    /** A search at a recall point: each vault's outcome, and what it showed. */
-    memory_recalled: z.looseObject({
-        /** `run_start`, `ticket`, `review`, or `fix_round`. */
-        point: z.string(),
-        vaults: z
-            .array(
-                z.looseObject({
-                    vault: z.string(),
-                    ok: z.boolean(),
-                    error: z.string().nullable().catch(null),
-                })
-            )
-            .catch([]),
-        memories: z.array(z.unknown()).catch([]),
-    }),
-    /** The learner's memories saved, refused, or failed. */
-    memories_saved: z.looseObject({
-        saves: z
-            .array(
-                z.looseObject({
-                    /** `added`, `updated`, `refused`, or `failed`. */
-                    outcome: z.string(),
-                })
-            )
-            .catch([]),
-    }),
-    /** The engine gave up on the learner; the run ends without it. */
-    learning_skipped: z.looseObject({ reason: z.string().catch('') }),
-    /** With no PR, the new memories went on the spec issue. */
-    memories_reported: z.looseObject({ count: z.number().int().catch(0) }),
-
-    // The scheduler's steps (#403): what the engine is doing right now.
-    /**
-     * A step began. `key` is the scheduler's key (a ticket's number, `run`,
-     * `final`, `lens:<lens>`, ...); `step` its action type, plus `:<role>`
-     * for an agent's turn.
-     */
-    step_started: z.looseObject({ key: z.string(), step: z.string() }),
-    /** The step on `key` settled. */
-    step_ended: z.looseObject({ key: z.string(), step: z.string() }),
+    ...RUN_VOCABULARY,
+    ...ENGINE_VOCABULARY,
+    ...REVIEW_VOCABULARY,
 } as const
 
 export type BoardKind = keyof typeof BOARD_VOCABULARY
@@ -394,7 +32,11 @@ const entry = <Kind extends BoardKind>({ kind }: { kind: Kind }) =>
 
 const BoardEntrySchema = z.discriminatedUnion('kind', [
     entry({ kind: 'run_started' }),
+    entry({ kind: 'repo_wait_started' }),
+    entry({ kind: 'repo_wait_ended' }),
     entry({ kind: 'engine_resumed' }),
+    entry({ kind: 'config_reloaded' }),
+    entry({ kind: 'config_reload_refused' }),
     entry({ kind: 'intake_read' }),
     entry({ kind: 'intake_refused' }),
     entry({ kind: 'nothing_to_do' }),
@@ -417,6 +59,7 @@ const BoardEntrySchema = z.discriminatedUnion('kind', [
     entry({ kind: 'gates_run' }),
     entry({ kind: 'ticket_joined' }),
     entry({ kind: 'ticket_rebased' }),
+    entry({ kind: 'tests_sent_back' }),
     entry({ kind: 'run_branch_pushed' }),
     entry({ kind: 'ticket_stuck' }),
     entry({ kind: 'run_stuck' }),
@@ -425,6 +68,7 @@ const BoardEntrySchema = z.discriminatedUnion('kind', [
     entry({ kind: 'jev_asked' }),
     entry({ kind: 'jev_answered' }),
     entry({ kind: 'jev_failed' }),
+    entry({ kind: 'decision_model_off' }),
     entry({ kind: 'agent_message' }),
     entry({ kind: 'agent_message_delivered' }),
     entry({ kind: 'shared_git_changed' }),
@@ -452,6 +96,7 @@ const BoardEntrySchema = z.discriminatedUnion('kind', [
     entry({ kind: 'memories_reported' }),
     entry({ kind: 'step_started' }),
     entry({ kind: 'step_ended' }),
+    entry({ kind: 'ticket_waiting' }),
 ])
 
 /** A record the board understands, with its content parsed. */

package/board/server/current-step-panel-helpers.ts

@@ -0,0 +1,108 @@
+import { type Harness } from './testing/board-harness'
+import { intakeOfThree, stamp, type Entry } from './testing/journal-fixtures'
+
+import type { EngineRecord } from '../shared/board-rpc'
+
+/**
+ * Helpers shared by the current step tests (`current-step-panel.test.ts` and
+ * the `current-step-panel-*.test.ts` files beside it).
+ *
+ * The pure helpers that build and read journal records and the run header
+ * row. Each test file keeps its own `harness`, `extra`, `dirs`, and
+ * `runWith`, because the tests start boards of their own.
+ */
+
+/**
+ * `step_started` as the engine journals it: `key` is the ticket's number,
+ * or `run` for the run's own steps; `step` is the action type, plus
+ * `:<role>` for an agent's turn.
+ */
+export const stepStarted = ({
+    ticket,
+    step,
+    role = null,
+    first_seq = null,
+}: {
+    ticket: number | null
+    step: string
+    role?: string | null
+    first_seq?: number | null
+}): Entry => ({
+    kind: 'step_started',
+    ticket,
+    role,
+    content: {
+        key: ticket === null ? 'run' : String(ticket),
+        step,
+        first_seq,
+    },
+})
+
+/** `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 },
+})
+
+/** The journal: three tickets through intake, then `entries`. */
+export const journalWith = ({
+    entries,
+}: {
+    entries: Entry[]
+}): EngineRecord[] => stamp({ entries: [...intakeOfThree(), ...entries] })
+
+/** The stamped time of the record at `seq`. */
+export const timeOf = ({
+    records,
+    seq,
+}: {
+    records: EngineRecord[]
+    seq: number
+}): string => {
+    const found = records.find((record) => record.seq === seq)
+    if (!found) throw new Error(`no record ${seq}`)
+    return found.time
+}
+
+/** The seq of the last record of `kind` whose content has `step`. */
+export const lastStepSeq = ({
+    records,
+    kind,
+    step,
+    ticket,
+}: {
+    records: EngineRecord[]
+    kind: string
+    step: string
+    ticket: number | null
+}): number => {
+    const found = records.findLast(
+        (record) =>
+            record.kind === kind &&
+            record.ticket === ticket &&
+            (record.content as { step: string }).step === step
+    )
+    if (!found) throw new Error(`no ${kind} for ${step}`)
+    return found.seq
+}
+
+/** The run's header row as the chat shows it now. */
+export const headerOf = ({ board }: { board: Harness }) => {
+    const found = board
+        .latestRows()
+        .find(({ row }) => row.kind === 'luca-board-run')
+    if (!found || found.row.kind !== 'luca-board-run') {
+        throw new Error('no header row')
+    }
+    return found.row.data
+}