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

package/engine/agents/launch-session.ts

@@ -0,0 +1,227 @@
+/**
+ * How the Claude launcher starts one agent session: checks the model, builds
+ * the role's locked-down options (guard hook, sandbox, clean environment),
+ * starts the SDK session, checks the account BEFORE the prompt is sent, then
+ * runs the first turn on the pool's open session.
+ */
+import { randomUUID } from 'node:crypto'
+import { realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+
+import type {
+    EffortLevel,
+    Options,
+    SDKUserMessage,
+} from '@anthropic-ai/claude-agent-sdk'
+
+import {
+    AgentSessionSchema,
+    type AgentLauncher,
+    type AgentSession,
+    type AgentTurn,
+} from './agent-launcher'
+import {
+    AccountSchema,
+    accountProblem,
+    errorText,
+    stop,
+    type Outcome,
+} from './claude-messages'
+import { agentEnv, agentOptions, checkLaunchModel } from './claude-options'
+import { createInputChannel } from './input-channel'
+import { commonGitDir, realClaudePath } from './launch-paths'
+import { createDeliveryHook, createLucaServer } from './message-tool'
+import {
+    nextOutcome,
+    pumpMessages,
+    type AgentQuerySession,
+    type OpenSession,
+} from './open-session'
+import type { SessionPool } from './session-pool'
+import { createTurnProgress } from './turn-progress'
+
+import { createGuardHook } from '../guards/guard-hook'
+import { guardRoleOf } from '../guards/role-rules'
+
+/** Starts an SDK session: the SDK's `query`, or a fake in tests. */
+export type AgentQuery = (params: {
+    prompt: AsyncIterable<SDKUserMessage>
+    options: Options
+}) => AgentQuerySession
+
+/**
+ * Makes the launcher's `launch`: it starts an SDK session with `start_query`
+ * and runs the session's first turn through the pool.
+ *
+ * @example
+ * const launch = createLaunch({ effort, start_query, claude_path, turn_timeout_ms, pool })
+ */
+export const createLaunch = ({
+    effort: useEffort,
+    start_query: startQuery,
+    claude_path,
+    turn_timeout_ms: timeoutMs,
+    pool,
+}: {
+    effort: EffortLevel
+    start_query: AgentQuery
+    claude_path: string | undefined
+    turn_timeout_ms: number
+    pool: Pick<SessionPool, 'close' | 'runTurn'>
+}): AgentLauncher['launch'] => {
+    const { close, runTurn } = pool
+
+    const launch: AgentLauncher['launch'] = async ({
+        role,
+        ticket,
+        prompt,
+        cwd,
+        may_edit_tests,
+        config,
+        messaging,
+        model,
+        on_progress,
+    }) => {
+        const refused = checkLaunchModel({ model })
+        if (refused !== null) return stop(refused)
+        const started = Date.now()
+        const fallback_id = `claude-launch-${randomUUID()}`
+
+        let claudePath: string
+        try {
+            claudePath = claude_path ?? realClaudePath()
+        } catch (error) {
+            return stop(errorText(error))
+        }
+        let worktree: string
+        let gitDir: string
+        try {
+            worktree = realpathSync(cwd)
+            gitDir = await commonGitDir({ cwd: worktree })
+        } catch (error) {
+            return { ok: false, failure: 'engine', error: errorText(error) }
+        }
+
+        const summary: AgentSession = AgentSessionSchema.parse({})
+        const stderr: string[] = []
+        const helpers = new Set<string>()
+        const progress = createTurnProgress({
+            worktree,
+            readings: () => open.summary.rate_limit_events,
+        })
+        progress.start(on_progress)
+        const options = agentOptions({
+            role,
+            may_edit_tests,
+            cwd: worktree,
+            model,
+            effort: useEffort,
+            claude_path: claudePath,
+            config,
+            common_git_dir: gitDir,
+            home: realpathSync(homedir()),
+            env: agentEnv({ source: process.env }),
+            guard_hook: createGuardHook({
+                role: guardRoleOf({ role }),
+                may_edit_tests,
+                worktree,
+                config,
+                // The summary is swapped each turn, so this reads it late.
+                on_deny: (denial) => open.summary.guard_denials.push(denial),
+                helpers,
+                on_helper: () => {
+                    open.summary.helpers_started += 1
+                },
+                on_allow: progress.opened,
+            }),
+            // Kept in the session's options, so its follow-ups have them too.
+            luca_server:
+                messaging === null ? null : createLucaServer({ messaging }),
+            delivery_hook:
+                messaging === null ? null : createDeliveryHook({ messaging }),
+            stderr: (data) => {
+                stderr.push(data)
+                if (stderr.length > 50) stderr.shift()
+            },
+        })
+
+        const input = createInputChannel()
+        let running: AgentQuerySession
+        try {
+            running = startQuery({ prompt: input.iterable, options })
+        } catch (error) {
+            return {
+                ok: false,
+                failure: 'engine',
+                error: `The SDK did not start: ${errorText(error)}`,
+                session: { ...summary, duration_ms: Date.now() - started },
+            }
+        }
+        const open: OpenSession = {
+            role,
+            ticket,
+            cwd,
+            may_edit_tests,
+            running,
+            input,
+            summary,
+            helpers,
+            progress,
+            model_totals: {},
+            waiter: null,
+            ended: null,
+            pump: Promise.resolve(),
+            idle_timer: undefined,
+            stderr,
+        }
+        open.pump = pumpMessages({ open, on_end: () => void close(open) })
+
+        const ended = async (outcome: Outcome): Promise<AgentTurn> => {
+            await close(open)
+            return {
+                ...outcome,
+                session_id: open.summary.session_id ?? fallback_id,
+                session: { ...open.summary, duration_ms: Date.now() - started },
+            }
+        }
+
+        let timer: ReturnType<typeof setTimeout> | undefined
+        const timedOut = new Promise<'timeout'>((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), timeoutMs)
+        })
+        const account = await Promise.race([
+            running.accountInfo().then(
+                (info) => ({ info }),
+                (error: unknown) => ({ error })
+            ),
+            nextOutcome(open).then((outcome) => ({ outcome })),
+            timedOut,
+        ])
+        clearTimeout(timer)
+        open.waiter = null
+        if (account === 'timeout') {
+            return ended({
+                ok: false,
+                failure: 'engine',
+                error: 'accountInfo() did not answer in time.',
+            })
+        }
+        if ('outcome' in account) return ended(account.outcome)
+        if ('error' in account) {
+            return ended({
+                ok: false,
+                failure: 'engine',
+                error: `accountInfo() failed: ${errorText(account.error)}`,
+            })
+        }
+        const accountParsed = AccountSchema.safeParse(account.info)
+        summary.subscription_type = accountParsed.success
+            ? (accountParsed.data.subscriptionType ?? null)
+            : null
+        const problem = accountProblem(account.info)
+        if (problem !== null) return ended(stop(`credential check: ${problem}`))
+        return runTurn({ open, message: prompt, started, fallback_id })
+    }
+
+    return launch
+}

package/engine/agents/learner-instructions.ts

@@ -0,0 +1,31 @@
+/**
+ * The learner's instructions (#370): its task, and its own rules in place of
+ * the shell and the rules for every agent.
+ */
+
+export const LEARNER = `# Your role: learner
+
+You run once, at the end of a run, even a stuck or stopped one. Your prompt is a digest of the run's journal: failures, fix loops, failed tries, review findings, stuck points, assumptions, run notes, and the memories other agents were shown. You propose lessons for FUTURE runs, which the engine saves to memory.
+
+- Propose only durable lessons: something a later run, maybe on another spec, would do better for knowing. Not a story of this run, not facts only this spec needs, and nothing a linter or the gates already enforce.
+- Pick each one's type:
+  - "pattern": a way of building that worked and is worth repeating.
+  - "pitfall": a trap that cost a fix loop, a failed try, or a stuck ticket, and how to avoid it.
+  - "procedure": steps that reliably get something done.
+  - "decision": a choice made for THIS project that later runs on it must follow.
+  Any other type is refused.
+- Mark each one's scope by asking "would this memory be useful in a completely different repo?":
+  - "repo": no, it only helps on this repo (its code, docs, or setup). It is saved to this project's memory.
+  - "anywhere": yes, it helps on any repo. It is saved to the shared memory.
+  A decision is always saved to this project's memory. A missing or other scope is refused.
+- Keep each memory atomic: one lesson each, a short "concept" name in kebab-case (such as bun-junit-reporter-flags), the lesson in "content" (a few plain sentences), and a one-line "summary".
+- At most 10. Fewer, better ones beat many. An empty list is a fine answer when the run taught nothing new.
+- In "helped", list the ids of the shown memories that actually helped this run (the digest lists them with their ids). Leave out the ones that didn't matter or were wrong.
+- You may read the repo (Read, Grep, Glob) to check a lesson. You have no shell, and you write nothing.
+
+Your result (structured output): memories (each with type, scope, concept, content, summary) and helped (memory ids).`
+
+export const LEARNER_RULES = `## Rules for the learner
+- Plain code (the engine) drives this run and saves what you propose. Only the engine talks to memory; you have no memory tools.
+- Never create, edit, or delete a file. The network is off.
+- Finish by giving your structured result. A turn without one counts as failed.`

package/engine/agents/open-session.ts

@@ -0,0 +1,210 @@
+/**
+ * One agent session the Claude launcher keeps open between turns, and how it
+ * is read: each SDK message goes into the session's summary, and an outcome
+ * (a result, a stop, a plan cut-off, an engine failure) goes to the turn
+ * waiting for it.
+ */
+import type { AgentSession, ModelTokens } from './agent-launcher'
+import {
+    AssistantSchema,
+    errorText,
+    InitSchema,
+    initProblem,
+    planCut,
+    RateLimitSchema,
+    ResultSchema,
+    modelTotalsOf,
+    stop,
+    toolResultIds,
+    turnTokens,
+    type Outcome,
+} from './claude-messages'
+import type { createInputChannel } from './input-channel'
+import type { AgentRole } from './role-results'
+import type { TurnProgressKeeper } from './turn-progress'
+
+import { planSignal } from '../limits/plan-signals'
+
+/**
+ * One running SDK session, as the launcher uses it. The SDK's own `Query`
+ * fits this; tests hand in a fake. Messages are read as `unknown` and parsed
+ * with the launcher's own schemas.
+ */
+export type AgentQuerySession = AsyncIterable<unknown> & {
+    accountInfo: () => Promise<unknown>
+    interrupt: () => Promise<unknown>
+    close: () => void
+}
+
+/**
+ * One agent session the launcher keeps open between turns, so a follow-up
+ * reaches the same agent. Its guard hook, sandbox, and options are the ones
+ * it was launched with.
+ */
+export type OpenSession = {
+    role: AgentRole
+    ticket: number
+    cwd: string
+    may_edit_tests: boolean
+    running: AgentQuerySession
+    input: ReturnType<typeof createInputChannel>
+    /** What the launcher has seen of the session; per-turn fields reset each turn. */
+    summary: AgentSession
+    /**
+     * The helpers running now, by the tool call that started each: the guard
+     * hook adds one, and its result (or the turn's end) takes it out.
+     */
+    helpers: Set<string>
+    /** The turn's live progress (#628), told to the turn's `on_progress`. */
+    progress: TurnProgressKeeper
+    /** The SDK's running tokens per model, as of the session's last result. */
+    model_totals: Record<string, ModelTokens>
+    /** Resolves the turn waiting for the session's next outcome. */
+    waiter: ((outcome: Outcome) => void) | null
+    /** A stop or an engine failure: the session is over, with this outcome. */
+    ended: Outcome | null
+    /** Reads the session's messages until it ends. */
+    pump: Promise<void>
+    idle_timer: ReturnType<typeof setTimeout> | undefined
+    stderr: string[]
+}
+
+/** The session's next outcome: a result, a stop, or its end. */
+export const nextOutcome = (open: OpenSession): Promise<Outcome> =>
+    open.ended !== null
+        ? Promise.resolve(open.ended)
+        : new Promise<Outcome>((resolve) => {
+              open.waiter = resolve
+          })
+
+export const deliver = ({
+    open,
+    outcome,
+}: {
+    open: OpenSession
+    outcome: Outcome
+}): void => {
+    if (!outcome.ok && outcome.failure !== 'agent') open.ended = outcome
+    const waiter = open.waiter
+    open.waiter = null
+    waiter?.(outcome)
+}
+
+export const stderrTail = (open: OpenSession): string =>
+    open.stderr.length === 0 ? '' : `\n${open.stderr.join('').slice(-2000)}`
+
+/** Reads one message into the session's summary; an outcome ends the turn. */
+export const watch = ({
+    open,
+    raw,
+}: {
+    open: OpenSession
+    raw: unknown
+}): Outcome | null => {
+    const { summary } = open
+    const init = InitSchema.safeParse(raw)
+    if (init.success) {
+        summary.session_id = init.data.session_id
+        summary.model = init.data.model
+        summary.claude_code_version = init.data.claude_code_version
+        summary.api_key_source = init.data.apiKeySource
+        const problem = initProblem(init.data)
+        return problem === null ? null : stop(problem)
+    }
+    const rateLimit = RateLimitSchema.safeParse(raw)
+    if (rateLimit.success) {
+        const info = rateLimit.data.rate_limit_info
+        summary.rate_limit_events.push({
+            ...info,
+            arrived_at: new Date().toISOString(),
+        })
+        const signal = planSignal({ info })
+        switch (signal.kind) {
+            case 'ok':
+                return null
+            case 'billing':
+                return planCut(signal.reason)
+            case 'limit':
+                return planCut(
+                    `rate_limit_event status=rejected (${signal.rate_limit_type ?? 'unknown'})`
+                )
+        }
+    }
+    const assistant = AssistantSchema.safeParse(raw)
+    if (assistant.success) {
+        if (assistant.data.error !== 'billing_error') return null
+        summary.billing_error = true
+        return planCut('assistant error billing_error')
+    }
+    for (const id of toolResultIds(raw)) open.helpers.delete(id)
+    const result = ResultSchema.safeParse(raw)
+    if (!result.success) return null
+    open.helpers.clear()
+    const done = result.data
+    summary.num_turns = done.num_turns
+    summary.usage = done.usage
+    const totals = modelTotalsOf(done.modelUsage)
+    summary.model_usage = turnTokens({
+        totals,
+        before: open.model_totals,
+    })
+    open.model_totals = { ...open.model_totals, ...totals }
+    summary.total_cost_usd = done.total_cost_usd
+    summary.permission_denials = done.permission_denials.map(
+        ({ tool_name, tool_use_id }) => ({ tool_name, tool_use_id })
+    )
+    if (done.subtype === 'success' && !done.is_error) {
+        return { ok: true, structured_output: done.structured_output }
+    }
+    const detail = done.errors.length > 0 ? done.errors.join('; ') : done.result
+    return {
+        ok: false,
+        failure: 'agent',
+        error: `The agent's turn ended with ${done.subtype}: ${detail}`,
+        ...(done.subtype === 'error_max_turns' ? { out_of_turns: true } : {}),
+    }
+}
+
+/**
+ * Reads a session's messages until it ends, handing each outcome to the turn
+ * waiting for it, then calls `on_end`.
+ */
+export const pumpMessages = async ({
+    open,
+    on_end,
+}: {
+    open: OpenSession
+    on_end: () => void
+}): Promise<void> => {
+    try {
+        for await (const raw of open.running) {
+            const outcome = watch({ open, raw })
+            open.progress.heard(raw)
+            if (outcome === null) continue
+            deliver({ open, outcome })
+            if (open.ended !== null) break
+        }
+        if (open.ended !== null) {
+            on_end()
+            return
+        }
+        deliver({
+            open,
+            outcome: {
+                ok: false,
+                failure: 'engine',
+                error: `The agent session ended with no result.${stderrTail(open)}`,
+            },
+        })
+    } catch (error) {
+        deliver({
+            open,
+            outcome: {
+                ok: false,
+                failure: 'engine',
+                error: `The agent session failed: ${errorText(error)}${stderrTail(open)}`,
+            },
+        })
+    }
+    on_end()
+}

package/engine/agents/prompt-sections.ts

@@ -0,0 +1,95 @@
+/**
+ * The sections the decision step adds to an agent's prompt: the notes earlier
+ * agents left, the prepare command, the feature map, and the changesets. Each
+ * is plain text.
+ */
+import type { AgentRole } from './role-results'
+
+import { isFeatureMapFolder } from '../config/engine-config'
+
+/** 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')
+
+/**
+ * The section a test-writer gets when the repo has a feature map (#583): the
+ * one file besides test files it may edit. It comes after the task's "Edit
+ * test files only", so it reads as that line's exception. A folder map
+ * (#597) is its `*.md` pages, and a new test file goes on its area's page.
+ *
+ * @param path - The map's path, as `featureMapPath` gives it.
+ *
+ * @example
+ * featureMapSection({ path: 'docs/feature-map.md' })
+ * // '## The feature map\n\nBesides test files, you may edit the feature map, `docs/feature-map.md`. ...'
+ */
+export const featureMapSection = ({ path }: { path: string }): string =>
+    [
+        '## The feature map',
+        isFeatureMapFolder({ path })
+            ? `Besides test files, you may edit the feature map's pages, the \`*.md\` files under \`${path}/\`. ` +
+              'Read the pages first: they list each feature and the test files that prove it. ' +
+              "Put new tests in a feature's existing test files when you can; " +
+              "a new test file must be listed under its feature on its area's page (add a page for a new area)."
+            : `Besides test files, you may edit the feature map, \`${path}\`. ` +
+              'Read it first: it lists each feature and the test files that prove it. ' +
+              "Put new tests in a feature's existing test files when you can; " +
+              'a new test file must be listed under its feature in the map.',
+    ].join('\n\n')
+
+/**
+ * The section a test-writer or implementer (a ticket's or the final
+ * review's fixers) gets in a repo with changesets: the engine writes the
+ * run's one changeset, so an agent's own is extra.
+ */
+export const CHANGESETS_SECTION = [
+    '## The engine writes the changeset',
+    "Don't write changesets, even if the repo's rules ask for one: the engine writes the run's one changeset when it opens the PR. " +
+        'A new file you add in `.changeset/` is removed before the commit. ' +
+        'A finding that only asks for a changeset is answered by this: answer it "wont_fix" and say the engine adds it.',
+].join('\n\n')
+
+/**
+ * The section every reviewer (the ticket-reviewer and each lens) gets in a
+ * repo with changesets, so a rule like "every PR needs a changeset" raises
+ * no finding.
+ */
+export const CHANGESETS_LENS_SECTION = [
+    '## The engine writes the changeset',
+    "The engine adds the run's one changeset when it opens the PR, so a rule that asks for a changeset is met. " +
+        'Raise no finding that only asks for a changeset.',
+].join('\n\n')