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

package/board/shared/reply-actions.ts

@@ -0,0 +1,207 @@
+import { z } from 'zod'
+
+/**
+ * The reply buttons on stuck work (#503): which one-word replies the engine
+ * takes for each kind of stuck item, the words of the confirm step, the
+ * `/luca-unstick` command for "Help me", and what each button shows. Plain
+ * values only, so the panel, the chat rows, and the server share them.
+ */
+
+/** The key of a ticket's "Needs you" item. */
+export const ticketKey = ({ ticket }: { ticket: number }): string =>
+    `ticket-${ticket}`
+
+/** The key of the final review's "Needs you" item. */
+export const FINAL_KEY = 'final'
+
+/** The key of the "Needs you" item for the whole run, stuck on its budget. */
+export const RUN_KEY = 'run'
+
+/**
+ * The replies the engine takes for one stuck item, as the owner would type
+ * them. A stuck ticket always gets its number (`retry #12`), since a bare
+ * word is only taken while one ticket is stuck. The final review takes a
+ * bare `retry`, `stop`, or `ship`; the run stuck on its budget a bare
+ * `retry` or `stop` (see the engine's README, "Replies"). An item this
+ * doesn't know gets none, so no button can post a word the engine refuses.
+ *
+ * @example
+ * allowedReplies({ key: 'ticket-12', ticket: 12 }) // ['retry #12', 'skip #12', 'stop']
+ * allowedReplies({ key: 'final', ticket: null }) // ['retry', 'stop', 'ship']
+ */
+export const allowedReplies = ({
+    key,
+    ticket,
+}: {
+    key: string
+    ticket: number | null
+}): string[] => {
+    if (ticket !== null) {
+        return key === ticketKey({ ticket })
+            ? [`retry #${ticket}`, `skip #${ticket}`, 'stop']
+            : []
+    }
+    if (key === FINAL_KEY) return ['retry', 'stop', 'ship']
+    if (key === RUN_KEY) return ['retry', 'stop']
+    return []
+}
+
+/** A reply word and the ticket it names, as the engine journals it. */
+export type ReplyParts = {
+    word: 'retry' | 'skip' | 'stop' | 'ship'
+    ticket: number | null
+}
+
+const REPLY_PATTERN = /^(retry|skip|stop|ship)(?: #(\d+))?$/
+
+/** `retry` with an amount for the run stuck on its budget (#543). */
+const AMOUNT_REPLY_PATTERN = /^retry \+\S+$/
+
+/**
+ * Splits one of `allowedReplies`, or a `retry +<amount>` the owner typed,
+ * into its word and ticket, to match it with the engine's `reply_received`.
+ * `null` for anything else.
+ *
+ * @example
+ * replyParts({ reply: 'retry #12' }) // { word: 'retry', ticket: 12 }
+ * replyParts({ reply: 'retry +3M' }) // { word: 'retry', ticket: null }
+ */
+export const replyParts = ({ reply }: { reply: string }): ReplyParts | null => {
+    if (AMOUNT_REPLY_PATTERN.test(reply)) return { word: 'retry', ticket: null }
+    const match = REPLY_PATTERN.exec(reply)
+    const word = z.enum(['retry', 'skip', 'stop', 'ship']).safeParse(match?.[1])
+    if (!match || !word.success) return null
+    return {
+        word: word.data,
+        ticket: match[2] === undefined ? null : Number(match[2]),
+    }
+}
+
+const ISSUE_URL_PATTERN =
+    /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/issues\/\d+/
+
+/**
+ * The repo of a GitHub issue URL, as `owner/repo`; `null` for any other URL.
+ *
+ * @example
+ * repoOfIssueUrl({ url: 'https://github.com/o/r/issues/10' }) // 'o/r'
+ */
+export const repoOfIssueUrl = ({ url }: { url: string }): string | null => {
+    const match = ISSUE_URL_PATTERN.exec(url)
+    return match ? `${match[1]}/${match[2]}` : null
+}
+
+/**
+ * The question before a reply is posted.
+ *
+ * @example
+ * confirmReplyText({ reply: 'retry #134', spec_number: 133 })
+ * // 'Post `retry #134` on spec #133?'
+ */
+export const confirmReplyText = ({
+    reply,
+    spec_number,
+}: {
+    reply: string
+    spec_number: number | null
+}): string =>
+    `Post \`${reply}\` on ${spec_number === null ? 'the spec issue' : `spec #${spec_number}`}?`
+
+/**
+ * The `/luca-unstick` command "Help me" puts in the chat: the run id, and
+ * the ticket for a stuck ticket (none for the final review or the budget).
+ *
+ * @example
+ * unstickCommand({ run_id: 'luca-20260928-101500-abcd', ticket: 134 })
+ * // '/luca-unstick luca-20260928-101500-abcd #134'
+ */
+export const unstickCommand = ({
+    run_id,
+    ticket,
+}: {
+    run_id: string
+    ticket: number | null
+}): string =>
+    ticket === null
+        ? `/luca-unstick ${run_id}`
+        : `/luca-unstick ${run_id} #${ticket}`
+
+/**
+ * API Response part: a reply the board posted on the spec issue, for one
+ * stuck item (its key and `since`), and whether the engine took it
+ * (`reply_received`). Kept in the plugin's memory only.
+ */
+export const PostedReplySchema = z.object({
+    key: z.string(),
+    /** The stuck item's `since`: the same ticket stuck again is a new item. */
+    since: z.string(),
+    reply: z.string(),
+    posted_at: z.string(),
+    /** The comment's URL, as `gh issue comment` printed it. */
+    comment_url: z.string().nullable(),
+    /** Set once the engine journaled `reply_received` for it. */
+    taken_at: z.string().nullable(),
+})
+
+export type PostedReply = z.infer<typeof PostedReplySchema>
+
+/** One reply button: its reply, and whether and why it can't be tapped. */
+export type ReplyButton = {
+    reply: string
+    /** `ready`, `sending` (this one is in flight), `posted`, or `locked`. */
+    state: 'ready' | 'sending' | 'posted' | 'locked'
+}
+
+/**
+ * The buttons of one stuck item. Once a reply is posted (or while one is in
+ * flight) for this item, that button shows it and the others lock, so a
+ * second tap can't post again or post a second word the engine would
+ * refuse.
+ *
+ * @example
+ * replyButtons({ item, posted: [], sending: null })
+ * // [{ reply: 'retry #12', state: 'ready' }, ...]
+ */
+export const replyButtons = ({
+    item,
+    posted,
+    sending,
+}: {
+    item: { key: string; ticket: number | null; since: string }
+    posted: PostedReply[]
+    /** The reply being posted for this item now, if any. */
+    sending: string | null
+}): ReplyButton[] => {
+    const done = postedFor({ item, posted })
+    return allowedReplies(item).map((reply) => {
+        if (done)
+            return { reply, state: done.reply === reply ? 'posted' : 'locked' }
+        if (sending !== null) {
+            return { reply, state: sending === reply ? 'sending' : 'locked' }
+        }
+        return { reply, state: 'ready' }
+    })
+}
+
+/** The reply posted for this stuck item, if any. */
+export const postedFor = ({
+    item,
+    posted,
+}: {
+    item: { key: string; since: string }
+    posted: PostedReply[]
+}): PostedReply | null =>
+    posted.find(
+        (entry) => entry.key === item.key && entry.since === item.since
+    ) ?? null
+
+/**
+ * What a posted reply says under the buttons.
+ *
+ * @example
+ * postedText({ posted }) // 'Posted `retry #12`. Waiting for the engine to read it.'
+ */
+export const postedText = ({ posted }: { posted: PostedReply }): string =>
+    posted.taken_at === null
+        ? `Posted \`${posted.reply}\`. Waiting for the engine to read it (it checks about once a minute).`
+        : `Posted \`${posted.reply}\`. The engine took it.`

package/engine/agents/agent-launcher.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 
 import type { AgentRole } from './role-results'
+import type { ProgressListener } from './turn-progress'
 
 import type { EngineConfig } from '../config/engine-config'
 
@@ -66,6 +67,11 @@ export const AgentSessionSchema = z.object({
     rate_limit_events: z.array(z.record(z.string(), z.unknown())).default([]),
     /** An assistant message came back with `error: "billing_error"`. */
     billing_error: z.boolean().default(false),
+    /**
+     * How many helpers (#627) the turn started. Their tokens are in
+     * `model_usage`. Older journals have none.
+     */
+    helpers_started: z.number().int().min(0).default(0),
 })
 
 export type AgentSession = z.infer<typeof AgentSessionSchema>
@@ -94,7 +100,10 @@ export type LauncherFailure = z.infer<typeof LauncherFailureSchema>
  * the same way; a success with no structured output is a failed try.
  * `session_id` names the session the turn ran in, so the engine can send that
  * same agent a follow-up in a fix loop. `session` is the launcher's summary
- * of the model session, for the journal.
+ * of the model session, for the journal. `session_gone` marks a follow-up
+ * that found its session closed or unknown (#521): no agent ran, and the
+ * engine hands the follow-up's message to a fresh agent. `out_of_turns`
+ * marks a turn that reached its role's turn limit (#543).
  */
 export type AgentTurn =
     | {
@@ -109,6 +118,8 @@ export type AgentTurn =
           error: string
           session_id?: string
           session?: AgentSession
+          session_gone?: boolean
+          out_of_turns?: boolean
       }
 
 /**
@@ -157,13 +168,23 @@ export type AgentLauncher = {
          * for its follow-ups.
          */
         messaging: AgentMessaging | null
+        /**
+         * The model's short name: `opus`, `sonnet` or `haiku`. The session's
+         * follow-ups run on it too.
+         */
+        model: string
+        /**
+         * Hears the turn's live progress (#628) each time it changes, before
+         * the turn ends, for the engine's live file. Left out, nothing hears it.
+         */
+        on_progress?: ProgressListener
     }) => Promise<AgentTurn>
     /**
      * Sends a follow-up message to an agent session that is still open, such
      * as a failed gate's output in a fix loop, and returns the session's new
-     * result. The agent keeps everything it knew from its earlier turns, and
-     * the guards it was launched with. A session the launcher doesn't know,
-     * or one that has closed, is an engine failure.
+     * result. The agent keeps everything it knew from its earlier turns, the
+     * guards it was launched with, and its model. A session the launcher doesn't know,
+     * or one that has closed, is an engine failure with `session_gone`.
      *
      * @example
      * const turn = await launcher.followUp({ session_id, role: 'implementer', ticket: 11, message: 'lint failed: ...', cwd, config })
@@ -175,6 +196,8 @@ export type AgentLauncher = {
         message: string
         cwd: string
         config: EngineConfig
+        /** Hears the follow-up turn's live progress, as for `launch`. */
+        on_progress?: ProgressListener
     }) => Promise<AgentTurn>
     /**
      * Closes one agent session once nothing can send it a follow-up anymore,

package/engine/agents/claude-launcher-helpers.ts

@@ -0,0 +1,233 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { $ } from 'bun'
+
+import type { Options, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
+import { afterEach, beforeEach } from 'bun:test'
+
+import type { AgentMessaging, AgentTurn } from './agent-launcher'
+import { createClaudeLauncher, type AgentQuery } from './claude-launcher'
+import { CLAUDE_MODEL } from './claude-options'
+import type { AgentRole } from './role-results'
+
+import type { EngineConfig } from '../config/engine-config'
+
+/**
+ * Helpers shared by the launcher tests (`claude-launcher.test.ts` and the
+ * `claude-launcher-*.test.ts` files beside it).
+ *
+ * The launcher seam: `createClaudeLauncher` with a fake `query` that plays
+ * back SDK-shaped messages, and a fake `claude` path. No model, no process.
+ */
+
+export const CONFIG: EngineConfig = {
+    checks: { test: 'bun test', types: 'bunx --bun tsc --noEmit' },
+    test_file_patterns: ['src/**/*.test.ts'],
+    test_setup_files: ['src/test-setup.ts'],
+    rule_files: [],
+}
+
+export const CLAUDE_PATH = '/opt/fake/bin/claude'
+
+export const MAX_ACCOUNT = {
+    email: 'me@example.com',
+    subscriptionType: 'max',
+    apiKeySource: 'none',
+    apiProvider: 'firstParty',
+}
+
+export const INIT = {
+    type: 'system',
+    subtype: 'init',
+    apiKeySource: 'none',
+    model: 'claude-opus-5-5',
+    claude_code_version: '2.1.280',
+    session_id: 'session-1',
+    cwd: '/somewhere',
+    tools: ['Read', 'Grep', 'Glob', 'Bash', 'StructuredOutput'],
+    mcp_servers: [],
+    permissionMode: 'dontAsk',
+}
+
+export const APPROVE = {
+    verdict: 'approve',
+    findings: [],
+    summary: 'Fine.',
+    assumptions: [],
+}
+
+export const result = (fields: Record<string, unknown>) => ({
+    type: 'result',
+    subtype: 'success',
+    is_error: false,
+    num_turns: 3,
+    duration_ms: 1200,
+    total_cost_usd: 0.25,
+    usage: {
+        input_tokens: 10,
+        output_tokens: 20,
+        cache_read_input_tokens: 30,
+        cache_creation_input_tokens: 40,
+    },
+    permission_denials: [],
+    session_id: 'session-1',
+    ...fields,
+})
+
+type FakeCall = {
+    options: Options
+    prompts: SDKUserMessage[]
+    account_checked_before_prompt: boolean
+    interrupted: boolean
+    closed: boolean
+}
+
+/**
+ * A fake `query`: it answers `accountInfo()` with `account`, waits for the
+ * first prompt, then plays `messages` (a function throws where it sits).
+ * With `hang`, it runs until it is closed. With `turns`, it plays one list
+ * per prompt instead, like a session in streaming-input mode, and runs until
+ * it is closed. `during` runs after each prompt arrives and before that
+ * turn's messages play, the way the agent's tool calls happen mid-turn.
+ */
+export const fakeQuery = ({
+    account,
+    messages,
+    hang,
+    turns,
+    during,
+}: {
+    account?: unknown
+    messages?: (unknown | (() => never))[]
+    hang?: boolean
+    turns?: unknown[][]
+    during?: (call: FakeCall, turn: number) => Promise<void>
+}) => {
+    const calls: FakeCall[] = []
+    const query: AgentQuery = ({ prompt, options }) => {
+        let accountChecked = false
+        const call: FakeCall = {
+            options,
+            prompts: [],
+            account_checked_before_prompt: false,
+            interrupted: false,
+            closed: false,
+        }
+        calls.push(call)
+        let wake = () => {}
+        const woken = new Promise<void>((resolve) => {
+            wake = resolve
+        })
+        let end = () => {}
+        const ended = new Promise<void>((resolve) => {
+            end = resolve
+        })
+        let notify = () => {}
+        const prompted = (count: number) =>
+            new Promise<void>((resolve) => {
+                notify = () => {
+                    if (call.prompts.length >= count || call.closed) resolve()
+                }
+                notify()
+            })
+        void (async () => {
+            for await (const message of prompt) {
+                if (call.prompts.length === 0) {
+                    call.account_checked_before_prompt = accountChecked
+                }
+                call.prompts.push(message)
+                wake()
+                notify()
+            }
+        })()
+        return {
+            [Symbol.asyncIterator]: async function* () {
+                if (turns !== undefined) {
+                    for (const [index, batch] of turns.entries()) {
+                        await prompted(index + 1)
+                        if (call.closed) return
+                        await during?.(call, index)
+                        for (const message of batch) yield message
+                    }
+                    await ended
+                    return
+                }
+                await woken
+                if (call.closed) return
+                await during?.(call, 0)
+                for (const message of messages ?? []) {
+                    if (typeof message === 'function') message()
+                    yield message
+                }
+                if (hang) await ended
+            },
+            accountInfo: async () => {
+                accountChecked = true
+                return account ?? MAX_ACCOUNT
+            },
+            interrupt: async () => {
+                call.interrupted = true
+            },
+            close: () => {
+                call.closed = true
+                wake()
+                end()
+                notify()
+            },
+        }
+    }
+    return { query, calls }
+}
+
+/** The git repo the current test runs in: a fresh one for each test. */
+export let repo = ''
+
+/** Gives each test of the file that calls it a fresh git repo in `repo`. */
+export const repoPerTest = () => {
+    beforeEach(async () => {
+        repo = await mkdtemp(join(tmpdir(), 'luca-launcher-'))
+        await $`git init -q -b main ${repo}`.quiet()
+    })
+
+    afterEach(async () => {
+        await rm(repo, { recursive: true, force: true })
+    })
+}
+
+export const launch = ({
+    query,
+    model,
+    role,
+    turn_timeout_ms,
+    messaging,
+}: {
+    query: AgentQuery
+    model?: string
+    role?: AgentRole
+    turn_timeout_ms?: number
+    messaging?: AgentMessaging
+}): Promise<AgentTurn> =>
+    createClaudeLauncher({
+        query,
+        claude_path: CLAUDE_PATH,
+        turn_timeout_ms,
+    }).launch({
+        role: role ?? 'ticket-reviewer',
+        ticket: 11,
+        prompt: 'Review ticket #11.',
+        cwd: repo,
+        may_edit_tests: role === 'test-writer',
+        config: CONFIG,
+        messaging: messaging ?? null,
+        model: model ?? CLAUDE_MODEL,
+    })
+
+export const IMPLEMENTER_DONE = {
+    outcome: 'done',
+    bad_test: null,
+    summary: 'Done.',
+    assumptions: [],
+    run_notes: [],
+}