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

package/engine/agents/role-prompts.ts

@@ -1,71 +1,24 @@
-import type { AgentRole, BadTest, Finding } from './role-results'
+import { runNotesSection, type PromptRunNote } from './prompt-sections'
+import type { AgentRole, BadTest, BadTestSource } from './role-results'
 
 import type { SpecSnapshot, TicketSnapshot } from '../intake/intake-schemas'
-import type { RejoinCause } from '../journal/journal-record'
 import { agentAddress, canMessage } from '../messages/agent-messages'
 
-/**
- * Why and how a ticket was sent back onto the run branch, for the prompts of
- * the agents that fix it there: the cause, the run branch commit it now
- * starts from, the files that clashed (tests and code), and the findings of
- * the review that approved it.
- */
-export type RejoinContext = {
-    cause: RejoinCause
-    base_sha: string
-    tests: string[]
-    code: string[]
-    earlier_findings: Finding[]
-}
-
-const fileList = (files: string[]): string =>
-    files.map((file) => `- ${file}`).join('\n')
-
-/** One line on what happened to the ticket, for every rejoin section. */
-export const rejoinOpening = ({ rejoin }: { rejoin: RejoinContext }): string =>
-    rejoin.cause === 'clash'
-        ? `Other tickets joined the run branch after this ticket started, and this ticket's change clashed with them. ` +
-          `The engine put this ticket's whole change back on top of the run branch (commit ${rejoin.base_sha}), as uncommitted changes in the worktree.`
-        : `The gates failed on the run branch after this ticket joined it. ` +
-          `The engine undid the join and put this ticket's whole change back on top of the run branch (commit ${rejoin.base_sha}), as uncommitted changes in the worktree.`
-
-/**
- * The section a fresh test-writer or implementer gets while it fixes a
- * ticket on top of the run branch: the clashed test files, or the clashed
- * code (or the failed gates). `null` for a role with nothing to fix there.
- * The reviewer's re-review is the review's own (`reviewSections`).
- *
- * @example
- * const section = rejoinSection({ role: 'test-writer', rejoin })
- */
-export const rejoinSection = ({
-    role,
-    rejoin,
-}: {
-    role: AgentRole
-    rejoin: RejoinContext
-}): string | null => {
-    if (role === 'test-writer') {
-        if (rejoin.tests.length === 0) return null
-        return [
-            '## This ticket clashed with the run branch',
-            rejoinOpening({ rejoin }),
-            `These test files have conflict markers:\n\n${fileList(rejoin.tests)}`,
-            "Resolve the markers so the tests check both what the run branch already has and this ticket's criteria. " +
-                'Change nothing else. Answer with the full criterion mapping again.',
-        ].join('\n\n')
-    }
-    if (role === 'implementer') {
-        return [
-            '## This ticket is being fixed on top of the run branch',
-            rejoinOpening({ rejoin }),
-            rejoin.code.length > 0
-                ? `These files have conflict markers:\n\n${fileList(rejoin.code)}\n\nResolve them so the code keeps both what the run branch has and what this ticket adds, and make every gate pass.`
-                : 'Make every gate pass on top of the run branch.',
-        ].join('\n\n')
-    }
-    return null
-}
+export {
+    rejoinOpening,
+    rejoinSection,
+    testUpdateSection,
+    type JoinedSince,
+    type RejoinContext,
+} from './rejoin-prompts'
+export {
+    CHANGESETS_LENS_SECTION,
+    CHANGESETS_SECTION,
+    featureMapSection,
+    prepareSection,
+    runNotesSection,
+    type PromptRunNote,
+} from './prompt-sections'
 
 /** A refactor ticket's implementer's task, in place of the usual one. */
 const REFACTOR_TASK =
@@ -73,11 +26,21 @@ const REFACTOR_TASK =
     'Make every gate pass. You may follow renames and moves into test files, but you must not change what a test checks. ' +
     'If a test is wrong, answer "bad_test" with your reason.'
 
-/** What a fresh test-writer is told when it replaces a bad test. */
-const badTestSection = ({ bad_test }: { bad_test: BadTest }): string =>
+/**
+ * What a fresh test-writer is told when it replaces a bad test: the
+ * implementer sent it back, or the engine found it passes with no
+ * `expect()`, so it checks nothing (#581).
+ */
+const badTestSection = ({
+    bad_test,
+    by,
+}: {
+    bad_test: BadTest
+    by: BadTestSource
+}): string =>
     [
         '## A test was sent back as a bad test',
-        `The implementer says this test is wrong:\n\n- File: ${bad_test.file}\n- Test: ${bad_test.name}\n- Reason: ${bad_test.reason}`,
+        `${by === 'engine' ? 'The engine found this test checks nothing' : 'The implementer says this test is wrong'}:\n\n- File: ${bad_test.file}\n- Test: ${bad_test.name}\n- Reason: ${bad_test.reason}`,
         'Fix or replace it so it checks what its criterion asks. Keep the other tests unless they are wrong too. ' +
             'Answer with the full criterion mapping again: every criterion, the kept tests included.',
     ].join('\n\n')
@@ -88,52 +51,14 @@ const REFACTOR_REVIEW_TASK =
     "No test's meaning changed, no test was weakened or dropped, and no new behavior was added. " +
     'A behavior change is a blocker.'
 
-/** A run note as a later agent's prompt lists it. */
-export type PromptRunNote = { ticket: number; role: AgentRole; note: string }
-
-/** The notes earlier agents left, oldest first; nothing when there are none. */
-export const runNotesSection = ({
-    run_notes,
-}: {
-    run_notes: PromptRunNote[]
-}): string[] =>
-    run_notes.length === 0
-        ? []
-        : [
-              '## Run notes from earlier agents in this run',
-              run_notes
-                  .map(
-                      ({ ticket, role, note }) =>
-                          `- ${note} (${role}, #${ticket})`
-                  )
-                  .join('\n'),
-          ]
-
-/**
- * The section a test-writer or implementer gets when the repo has a prepare
- * command: the engine runs it before its test runs, so tests that need its
- * outputs may fail when the agent runs them itself.
- *
- * @example
- * prepareSection({ command: 'bun run build:rom' })
- * // '## This repo has a prepare command\n\n...'
- */
-export const prepareSection = ({ command }: { command: string }): string =>
-    [
-        '## This repo has a prepare command',
-        `The engine runs \`${command}\` in the worktree before each of its test runs (the red check and the gates), so tests that need its outputs find them up to date. ` +
-            "Never run it yourself. Tests that need its outputs may fail when you run them, and still pass at the engine's checks. " +
-            "If the engine's prepare command fails after your turn, its output comes back to you like a failed check.",
-    ].join('\n\n')
-
 /** What each lens judges the whole run branch on, in one paragraph. */
 const LENS_TASK_TEXT =
     'You are one lens of the final review: a fresh, read-only reviewer of the WHOLE run branch, every ticket of the spec together. Write nothing.'
 
 const ROLE_TASKS: Record<AgentRole, string> = {
     'test-writer':
-        'Write failing tests for every acceptance criterion below. Edit test files only. ' +
-        'Map each criterion id to the tests that check it.',
+        'Write failing tests for every acceptance criterion below: the fewest that prove each one. Edit test files only. ' +
+        'Map every test you add to the criterion it checks.',
     implementer:
         'Make every gate pass. Never edit a test file. ' +
         'If a test is wrong, answer "bad_test" with your reason. ' +
@@ -172,7 +97,10 @@ export const roleTask = ({ role }: { role: AgentRole }): string =>
  * @param refactor - The ticket is a refactor ticket: the implementer gets
  *   the refactor task (no new behavior; it may follow renames into tests).
  * @param bad_test - For a fresh test-writer after a bad-test bounce: the
- *   test the implementer sent back, and why.
+ *   test the implementer sent back, or the engine found checks nothing
+ *   (#581), and why.
+ * @param bad_test_by - Who sent `bad_test` back: the implementer (the
+ *   default) or the engine.
  * @param sections - More sections for the end, such as a reviewer's diff
  *   and gate results, or a review fixer's findings.
  * @param run_notes - Notes earlier agents in the run left, oldest first,
@@ -187,6 +115,7 @@ export const rolePrompt = ({
     ticket,
     refactor,
     bad_test,
+    bad_test_by,
     sections,
     run_notes,
 }: {
@@ -195,6 +124,7 @@ export const rolePrompt = ({
     ticket: TicketSnapshot
     refactor?: boolean
     bad_test?: BadTest | null
+    bad_test_by?: BadTestSource
     sections?: string[]
     run_notes?: PromptRunNote[]
 }): string =>
@@ -216,7 +146,7 @@ export const rolePrompt = ({
         '## Acceptance criteria',
         ticket.criteria.map(({ id, text }) => `- ${id}: ${text}`).join('\n'),
         ...(role === 'test-writer' && bad_test
-            ? [badTestSection({ bad_test })]
+            ? [badTestSection({ bad_test, by: bad_test_by ?? 'implementer' })]
             : []),
         ...(sections ?? []),
         // Recalled memories (#370) are added after these by the decision step.

package/engine/agents/role-results.ts

@@ -82,12 +82,14 @@ export const CriterionTestsSchema = z.object({
 export type CriterionTests = z.infer<typeof CriterionTestsSchema>
 
 /**
- * A review fixer's answer to one finding it was sent: `fixed`, or
- * `wont_fix` with its reason (pushback the next fresh reviewer rules on).
+ * A review fixer's answer to one finding it was sent: `fixed`, `wont_fix`
+ * with its reason (pushback the next fresh reviewer rules on), or
+ * `other_role` with its reason: the other writer role must fix it, or must
+ * fix it too (#616).
  */
 export const FindingResponseSchema = z.object({
     finding_id: z.string().min(1),
-    response: z.enum(['fixed', 'wont_fix']),
+    response: z.enum(['fixed', 'wont_fix', 'other_role']),
     reason: z.string().default(''),
 })
 
@@ -118,6 +120,43 @@ const SETUP_FIELDS = {
     setup_change: SetupChangeSchema.nullable().default(null),
 }
 
+/**
+ * Why a writer says a failed red check or failed gates are not its
+ * ticket's fault (#613): a port already in use, an old test that fails at
+ * baseline too. The engine checks the claim by rerunning the check.
+ */
+export const EnvironmentSchema = z.object({
+    evidence: z.string().trim().min(1),
+})
+
+export type Environment = z.infer<typeof EnvironmentSchema>
+
+/**
+ * What a writer that blames the environment adds to its result, with the
+ * outcome `environment`.
+ */
+const ENVIRONMENT_FIELDS = {
+    environment: EnvironmentSchema.nullable().default(null),
+}
+
+/** A file mode a writer asks the engine to set (#618). */
+export const FileModeSchema = z.object({
+    /** Worktree-relative path of the file. */
+    path: z.string().min(1),
+    executable: z.boolean(),
+})
+
+export type FileMode = z.infer<typeof FileModeSchema>
+
+/**
+ * The owner chores a writer asks the engine to do after its turn (#618):
+ * file modes to set, and the repo's generators to run, by name.
+ */
+const CHORE_FIELDS = {
+    file_modes: z.array(FileModeSchema).default([]),
+    run_generators: z.array(z.string().min(1)).default([]),
+}
+
 const SHARED_FIELDS = {
     summary: z.string().default(''),
     /** Calls the agent made by itself when something was unclear. */
@@ -143,7 +182,8 @@ export type DoneCommit = z.infer<typeof DoneCommitSchema>
  * it and `criteria` the existing tests that cover each criterion; the engine
  * counts the ticket as done. `needs_setup_change` says the tests can't be
  * written without a change to a test setup file (`setup_change`), which
- * only the user may make.
+ * only the user may make. `environment` says a failed red check is not the
+ * ticket's fault (#613), with its evidence; the engine reruns the check.
  */
 export const TestWriterResultSchema = z.object({
     outcome: z.enum([
@@ -151,6 +191,7 @@ export const TestWriterResultSchema = z.object({
         'nothing_new_to_test',
         'already_done',
         'needs_setup_change',
+        'environment',
     ]),
     /**
      * For each criterion id (AC1, AC2, ...), the tests that check it: new
@@ -160,6 +201,8 @@ export const TestWriterResultSchema = z.object({
     /** With `already_done`: the base branch's commits that did the work. */
     done_by: z.array(DoneCommitSchema).default([]),
     ...SETUP_FIELDS,
+    ...ENVIRONMENT_FIELDS,
+    ...CHORE_FIELDS,
     ...SHARED_FIELDS,
     ...FIXER_FIELDS,
 })
@@ -175,15 +218,25 @@ export const BadTestSchema = z.object({
 
 export type BadTest = z.infer<typeof BadTestSchema>
 
+/**
+ * Who sent a test back as bad: the implementer, who says it is wrong, or the
+ * engine, which found a mapped test that passes with no `expect()` (#581).
+ */
+export type BadTestSource = 'implementer' | 'engine'
+
 /**
  * The implementer's result. `bad_test` sends a wrong test back;
  * `needs_setup_change` says the gates can't pass without a change to a test
- * setup file (`setup_change`), which only the user may make.
+ * setup file (`setup_change`), which only the user may make;
+ * `environment` says failed gates are not the ticket's fault (#613), with
+ * its evidence, and the engine reruns them.
  */
 export const ImplementerResultSchema = z.object({
-    outcome: z.enum(['done', 'bad_test', 'needs_setup_change']),
+    outcome: z.enum(['done', 'bad_test', 'needs_setup_change', 'environment']),
     bad_test: BadTestSchema.nullable().default(null),
     ...SETUP_FIELDS,
+    ...ENVIRONMENT_FIELDS,
+    ...CHORE_FIELDS,
     ...SHARED_FIELDS,
     ...FIXER_FIELDS,
 })
@@ -251,6 +304,37 @@ export const LensReviewResultSchema = TicketReviewResultSchema
 
 export type LensReviewResult = z.infer<typeof LensReviewResultSchema>
 
+/**
+ * How dangerous the branch is to merge (#513), as the integration lens
+ * judges it. A **one-way door** is a change a revert can't undo out in the
+ * world: a migration that drops data, a publish, sent messages, a deploy.
+ * A two-way door a revert undoes. The **blast radius** is how much breaks
+ * if the change is wrong. Each comes with a one-line reason.
+ */
+export const MergeDangerSchema = z.object({
+    door: z.enum(['one_way', 'two_way']),
+    door_reason: z.string(),
+    blast_radius: z.enum(['small', 'medium', 'large']),
+    blast_radius_reason: z.string(),
+})
+
+export type MergeDanger = z.infer<typeof MergeDangerSchema>
+
+/**
+ * The integration lens's result (#513): a lens result, plus, on its first
+ * round, the PR's Summary picture and Merge Danger. `summary_picture` is the
+ * smallest visual that makes the change clear (a call tree, a file tree, a
+ * Mermaid diagram, or a diff sketch), as markdown with its fenced block. A
+ * re-review gives null for both. Both default to null, so older journals
+ * still parse.
+ */
+export const IntegrationLensResultSchema = LensReviewResultSchema.extend({
+    summary_picture: z.string().nullable().default(null),
+    merge_danger: MergeDangerSchema.nullable().default(null),
+})
+
+export type IntegrationLensResult = z.infer<typeof IntegrationLensResultSchema>
+
 /** The most memories one learner may propose. */
 export const MAX_PROPOSED_MEMORIES = 10
 
@@ -306,7 +390,10 @@ export const RoleResultSchema = z.discriminatedUnion('role', [
     lensResult('architecture-lens'),
     lensResult('simplification-lens'),
     lensResult('security-lens'),
-    lensResult('integration-lens'),
+    z.object({
+        role: z.literal('integration-lens'),
+        result: IntegrationLensResultSchema,
+    }),
     lensResult('rules-lens'),
     z.object({ role: z.literal('learner'), result: LearnerResultSchema }),
 ])
@@ -336,6 +423,18 @@ export const parseRoleResult = ({
         }
     }
     const { result } = parsed.data
+    // "Environment" is only an answer with its evidence (#613).
+    if (
+        (parsed.data.role === 'test-writer' ||
+            parsed.data.role === 'implementer') &&
+        parsed.data.result.outcome === 'environment' &&
+        parsed.data.result.environment === null
+    ) {
+        return {
+            ok: false,
+            error: `The ${role}'s "environment" gives no evidence: say in "environment.evidence" why the failure is not this ticket's fault.`,
+        }
+    }
     // "Already done" is only an answer with its evidence (#484).
     if (parsed.data.role === 'test-writer') {
         const { outcome, done_by, criteria } = parsed.data.result

package/engine/agents/scripted-launcher.ts

@@ -50,6 +50,8 @@ export type ScriptedTurn = {
     result?: unknown
     failure?: LauncherFailure
     error?: string
+    /** With `failure`: the turn reached its role's turn limit (#543). */
+    out_of_turns?: boolean
     /** A session summary for the engine to journal. */
     session?: AgentSession
 }
@@ -64,6 +66,11 @@ export type ScriptedCall = {
     session_id: string
     /** Only on launches. */
     may_edit_tests?: boolean
+    /**
+     * The model a launch asked for; a follow-up's is its session's, `null`
+     * for a session the launcher doesn't know.
+     */
+    model: string | null
     /** What each of the turn's tool calls handed over, in order. */
     delivered: string[]
 }
@@ -100,8 +107,11 @@ export const createScriptedLauncher = ({
 }): ScriptedLauncher => {
     const remaining = [...turns]
     const calls: ScriptedCall[] = []
-    /** Each open session's messaging, kept for its follow-ups. */
-    const sessions = new Map<string, AgentMessaging | null>()
+    /** Each open session's messaging and model, kept for its follow-ups. */
+    const sessions = new Map<
+        string,
+        { messaging: AgentMessaging | null; model: string }
+    >()
 
     const toolsFor = ({
         messaging,
@@ -161,6 +171,7 @@ export const createScriptedLauncher = ({
                 failure: turn.failure,
                 session_id,
                 error: turn.error ?? `The scripted ${role} failed.`,
+                ...(turn.out_of_turns === true ? { out_of_turns: true } : {}),
                 ...session,
             }
         }
@@ -180,9 +191,10 @@ export const createScriptedLauncher = ({
             cwd,
             may_edit_tests,
             messaging,
+            model,
         }) => {
             const session_id = `scripted-${role}-${ticket}-${calls.length + 1}`
-            sessions.set(session_id, messaging)
+            sessions.set(session_id, { messaging, model })
             const call: ScriptedCall = {
                 kind: 'launch',
                 role,
@@ -190,6 +202,7 @@ export const createScriptedLauncher = ({
                 prompt,
                 session_id,
                 may_edit_tests,
+                model,
                 delivered: [],
             }
             calls.push(call)
@@ -197,25 +210,27 @@ export const createScriptedLauncher = ({
             return play({ role, ticket, cwd, session_id, tools })
         },
         followUp: async ({ session_id, role, ticket, message, cwd }) => {
+            const open = sessions.get(session_id)
             const call: ScriptedCall = {
                 kind: 'follow_up',
                 role,
                 ticket,
                 prompt: message,
                 session_id,
+                model: open?.model ?? null,
                 delivered: [],
             }
             calls.push(call)
-            const messaging = sessions.get(session_id)
-            if (messaging === undefined) {
+            if (open === undefined) {
                 return {
                     ok: false,
                     failure: 'engine',
                     session_id,
+                    session_gone: true,
                     error: `No scripted session ${session_id}.`,
                 }
             }
-            const tools = toolsFor({ messaging, call })
+            const tools = toolsFor({ messaging: open.messaging, call })
             return play({ role, ticket, cwd, session_id, tools })
         },
         closeSession: async ({ session_id }) => {

package/engine/agents/session-pool.ts

@@ -0,0 +1,124 @@
+/**
+ * The agent sessions the Claude launcher keeps open between turns: the pool
+ * of them by session id, a turn on one (`runTurn`), and closing one or all.
+ * A success or an agent failure keeps a session open for follow-ups until it
+ * sits idle too long; a stop, an engine failure, or a timeout closes it.
+ */
+import { AgentSessionSchema, type AgentTurn } from './agent-launcher'
+import type { Outcome } from './claude-messages'
+import { nextOutcome, type OpenSession } from './open-session'
+
+/**
+ * Makes the pool of open sessions. A turn gives up after `turn_timeout_ms`;
+ * a session left open closes after `idle_timeout_ms` of sitting idle.
+ *
+ * @example
+ * const pool = createSessionPool({ turn_timeout_ms: 40 * 60_000, idle_timeout_ms: 30 * 60_000 })
+ * const turn = await pool.runTurn({ open, message, started: Date.now(), fallback_id })
+ * await pool.closeAll()
+ */
+export const createSessionPool = ({
+    turn_timeout_ms: timeoutMs,
+    idle_timeout_ms: idleMs,
+}: {
+    turn_timeout_ms: number
+    idle_timeout_ms: number
+}) => {
+    const sessions = new Map<string, OpenSession>()
+
+    const close = async (open: OpenSession): Promise<void> => {
+        clearTimeout(open.idle_timer)
+        for (const [id, each] of sessions) {
+            if (each === open) sessions.delete(id)
+        }
+        open.input.close()
+        open.running.close()
+        await Promise.race([open.pump, Bun.sleep(5_000)])
+    }
+
+    /** Keeps a session open for follow-ups until it sits idle too long. */
+    const keepOpen = (open: OpenSession, session_id: string): void => {
+        sessions.set(session_id, open)
+        clearTimeout(open.idle_timer)
+        open.idle_timer = setTimeout(() => void close(open), idleMs)
+        open.idle_timer.unref?.()
+    }
+
+    /** Resets the summary's per-turn fields; the session's own stay. */
+    const startTurn = (open: OpenSession): void => {
+        clearTimeout(open.idle_timer)
+        const fresh = AgentSessionSchema.parse({})
+        open.summary = {
+            ...fresh,
+            session_id: open.summary.session_id,
+            model: open.summary.model,
+            claude_code_version: open.summary.claude_code_version,
+            api_key_source: open.summary.api_key_source,
+            subscription_type: open.summary.subscription_type,
+        }
+    }
+
+    /**
+     * Sends one message and waits for the turn's outcome. A success or an
+     * agent failure keeps the session open for follow-ups; a stop, an
+     * engine failure, or a timeout closes it.
+     */
+    const runTurn = async ({
+        open,
+        message,
+        started,
+        fallback_id,
+    }: {
+        open: OpenSession
+        message: string
+        started: number
+        /** The id to report if the session never named itself. */
+        fallback_id: string
+    }): Promise<AgentTurn> => {
+        const waiting = nextOutcome(open)
+        open.input.push({
+            type: 'user',
+            message: { role: 'user', content: message },
+            parent_tool_use_id: null,
+        })
+        let timer: ReturnType<typeof setTimeout> | undefined
+        const timedOut = new Promise<'timeout'>((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), timeoutMs)
+        })
+        const raced = await Promise.race([waiting, timedOut])
+        clearTimeout(timer)
+        const outcome: Outcome =
+            raced === 'timeout'
+                ? {
+                      ok: false,
+                      failure: 'agent',
+                      error: `No result within ${timeoutMs} ms; the agent was interrupted.`,
+                  }
+                : raced
+        if (raced === 'timeout') {
+            await open.running.interrupt().catch(() => undefined)
+        }
+        const session_id = open.summary.session_id ?? fallback_id
+        const session = {
+            ...open.summary,
+            duration_ms: Date.now() - started,
+        }
+        const keep =
+            raced !== 'timeout' &&
+            open.ended === null &&
+            open.summary.session_id !== null
+        if (keep) keepOpen(open, session_id)
+        else await close(open)
+        return { ...outcome, session_id, session }
+    }
+
+    /** Closes every session still open. */
+    const closeAll = async (): Promise<void> => {
+        await Promise.all([...new Set(sessions.values())].map(close))
+    }
+
+    return { sessions, close, startTurn, runTurn, closeAll }
+}
+
+/** The pool `createSessionPool` makes. */
+export type SessionPool = ReturnType<typeof createSessionPool>