@alecsibilia/luca 14.0.0-alpha.17 → 14.0.0-alpha.18

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.18
+
+No changes in this release.
+
 ## 14.0.0-alpha.17
 
 No changes in this release.

package/board/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luca/board",
-    "version": "14.0.0-alpha.17",
+    "version": "14.0.0-alpha.18",
     "private": true,
     "type": "module"
 }

package/board/server/board-vocabulary-engine.ts

@@ -0,0 +1,140 @@
+/**
+ * The board's vocabulary for what the engine does while it builds: worktrees
+ * and installs, the checks, joins and rebases, stuck tickets, the PR, the
+ * decision model, agent messages, and plan limits and usage.
+ */
+import { z } from 'zod'
+
+import { JevJobSchema, TestRunSchema } from './board-vocabulary-shapes'
+
+export const ENGINE_VOCABULARY = {
+    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([]),
+    }),
+    /**
+     * After a rebase, a test the joined tickets made wrong went back to the
+     * ticket's test-writer (#489). `round` counts these per ticket.
+     */
+    tests_sent_back: z.looseObject({
+        round: z.number().int().min(1).catch(1),
+        bad_test: z
+            .looseObject({
+                file: z.string().catch(''),
+                name: z.string().catch(''),
+            })
+            .catch({ file: '', name: '' }),
+        joined: z.array(z.looseObject({ ticket: z.number().int() })).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,
+     * or `pull_request_failed`, its PR didn't open (#508).
+     */
+    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([]),
+    }),
+    // The decision model (Clef; Jev in older journals) in shadow mode:
+    // counted, never acted on.
+    jev_asked: JevJobSchema,
+    jev_answered: JevJobSchema,
+    jev_failed: JevJobSchema,
+    /**
+     * The decision model is off for the rest of the run (#534): no
+     * credentials, or Cloudflare turned them down. The board reads only the
+     * plain-words `detail`.
+     */
+    decision_model_off: z.looseObject({ detail: z.string().catch('') }),
+    // 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({}),
+    }),
+} as const

package/board/server/board-vocabulary-review.ts

@@ -0,0 +1,98 @@
+/**
+ * The board's vocabulary for the owner's replies and stuck work, the final
+ * review, memory, and the scheduler's steps.
+ */
+import { z } from 'zod'
+
+import { FindingCountsSchema } from './board-vocabulary-shapes'
+
+export const REVIEW_VOCABULARY = {
+    /** 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() }),
+} as const

package/board/server/board-vocabulary-run.ts

@@ -0,0 +1,123 @@
+/**
+ * The board's vocabulary for the run and its tickets: how a run starts,
+ * resumes, and passes intake, the snapshots of the spec and its tickets, the
+ * baseline, and what each agent does and how its turn ends.
+ */
+import { z } from 'zod'
+
+import {
+    AgentSessionSchema,
+    FindingListSchema,
+    FindingResponseListSchema,
+    LeftOutListSchema,
+    RulingListSchema,
+    SpecIssueSchema,
+    TestRunSchema,
+    WorktreeSchema,
+} from './board-vocabulary-shapes'
+
+export const RUN_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() }),
+    /**
+     * A resume took the repo's new build fields (#516); the board reads
+     * only which fields changed.
+     */
+    config_reloaded: z.looseObject({
+        changes: z.array(z.looseObject({ field: z.string() })),
+    }),
+    /** A resume kept the run's config, as the repo's couldn't be used. */
+    config_reload_refused: z.looseObject({ reason: z.string() }),
+    intake_read: z.looseObject({ spec: SpecIssueSchema }),
+    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), and `left_out` names the tickets left for a person (#499).
+     */
+    nothing_to_do: z.looseObject({
+        already_done: z.array(z.number().int()).catch([]).default([]),
+        left_out: LeftOutListSchema,
+    }),
+    spec_snapshot: z.looseObject({
+        spec: SpecIssueSchema,
+        ticket_order: z.array(z.number()).catch([]),
+        /** The tickets left out for a person (#499); older journals have none. */
+        left_out: LeftOutListSchema,
+    }),
+    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),
+    }),
+} as const

package/board/server/board-vocabulary-shapes.ts

@@ -0,0 +1,132 @@
+/**
+ * The pieces the board's kind schemas are built from: findings and rulings,
+ * test runs, worktrees, the tickets left out for a person, the spec issue, an
+ * agent's session with its tokens and rate-limit readings, and the decision
+ * model's jobs. Loose on purpose, like the kinds: extra fields are fine.
+ */
+import { z } from 'zod'
+
+export 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),
+})
+
+export 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. */
+export 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`, `wont_fix`, or
+ * `other_role` (the other writer role gets it, #616).
+ */
+export const FindingResponseListSchema = z
+    .array(
+        z.looseObject({
+            finding_id: z.string(),
+            response: z.enum(['fixed', 'wont_fix', 'other_role']),
+            reason: z.string().catch(''),
+        })
+    )
+    .catch([])
+
+export const TestRunSchema = z.looseObject({
+    cases: z.array(z.looseObject({ status: z.string() })),
+})
+
+export const WorktreeSchema = z.looseObject({ branch: z.string() })
+
+/**
+ * The open tickets intake left out for a person (#499): `for_a_person`, or
+ * `waits_on_person` with the tickets for a person it `waits_on`, and the
+ * blockers it waits `through`. Missing in older journals.
+ */
+export const LeftOutListSchema = z
+    .array(
+        z.looseObject({
+            number: z.number().int(),
+            title: z.string().catch(''),
+            reason: z.enum(['for_a_person', 'waits_on_person']),
+            waits_on: z.array(z.number().int()).catch([]).default([]),
+            through: z.array(z.number().int()).catch([]).default([]),
+        })
+    )
+    .catch([])
+    .default([])
+
+export type LeftOutList = z.infer<typeof LeftOutListSchema>
+
+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. */
+export 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([]),
+})
+
+export const JevJobSchema = z.looseObject({ job: z.string() })
+
+/**
+ * The spec issue as intake read it. `author` (the spec's owner, whose
+ * replies alone count) and `url` feed the reply buttons (#503); older
+ * journals may lack them.
+ */
+export const SpecIssueSchema = z.looseObject({
+    number: z.number(),
+    title: z.string(),
+    author: z.string().optional().catch(undefined),
+    url: z.string().optional().catch(undefined),
+})