@alecsibilia/luca 14.0.0-alpha.11 → 14.0.0-alpha.12

package/CHANGELOG.md

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

package/board/client/board-panel.tsx

@@ -1327,7 +1327,7 @@ export const BoardPanel = ({
             ) : null}
             {state.jev.asked > 0 ? (
                 <Text style={styles.small}>
-                    Jev, in shadow mode: {state.jev.asked} asked,{' '}
+                    Decision model, in shadow mode: {state.jev.asked} asked,{' '}
                     {state.jev.answered} answered, {state.jev.failed} without an
                     answer. The engine doesn't act on them.
                 </Text>

package/board/package.json

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

package/board/server/board-vocabulary.ts

@@ -304,10 +304,17 @@ export const BOARD_VOCABULARY = {
     worktrees_removed: z.looseObject({
         paths: z.array(z.string()).catch([]),
     }),
-    // Jev in shadow mode: counted, never acted on.
+    // 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(),
@@ -490,6 +497,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' }),

package/board/server/luca-version.ts

@@ -1,2 +1,2 @@
 /** The Luca version of this board, stamped when the package was packed. */
-export const LUCA_VERSION: string = "14.0.0-alpha.11"
+export const LUCA_VERSION: string = "14.0.0-alpha.12"

package/board/server/make-rows.ts

@@ -227,8 +227,8 @@ const nothingToDoText = ({
 
 /**
  * What a record means in one line, or `null` for records that are noise in
- * a chat (snapshots, session summaries, a clean leftover scan, Jev in shadow
- * mode, ...).
+ * a chat (snapshots, session summaries, a clean leftover scan, the decision
+ * model's asks in shadow mode, ...).
  */
 export const describeRecord = ({
     before,
@@ -257,6 +257,11 @@ export const describeRecord = ({
                 text: `Config reloaded: ${record.content.changes.map(({ field }) => field).join(', ')} changed.`,
                 tone: 'info',
             })
+        case 'decision_model_off':
+            return event({
+                text: `Decision model off: ${record.content.detail}`,
+                tone: 'info',
+            })
         case 'config_reload_refused':
             return event({
                 text: `Config not reloaded, so the run keeps its own: ${record.content.reason.split('\n')[0] ?? ''}`,

package/board/server/reduce-board.ts

@@ -114,6 +114,7 @@ const QUIET_KINDS = new Set([
     'jev_asked',
     'jev_answered',
     'jev_failed',
+    'decision_model_off',
     'agent_message',
     'agent_message_delivered',
     'shared_git_changed',
@@ -1298,6 +1299,9 @@ const applyKind = ({
                 ...state,
                 jev: { ...state.jev, failed: state.jev.failed + 1 },
             }
+        // The decision model turning off is only a chat line (#534).
+        case 'decision_model_off':
+            return state
         case 'agent_message': {
             const refused = record.content.status === 'refused'
             return {

package/board/shared/board-state.ts

@@ -482,8 +482,9 @@ export const RunInfoSchema = z.object({
 export type RunInfo = z.infer<typeof RunInfoSchema>
 
 /**
- * Jev in shadow mode: how often the engine asked it and what came back. The
- * engine never acts on the answers, so the board only counts them.
+ * The decision model (Clef; Jev in older journals) in shadow mode: how often
+ * the engine asked it and what came back. The engine never acts on the
+ * answers, so the board only counts them.
  */
 export const JevCountsSchema = z.object({
     asked: z.number().int().min(0),

package/engine/cli/computer-checks.ts

@@ -26,14 +26,20 @@ import { claudeSkillsDir, skillDrift } from './luca-skills'
 import { isRight, rightEntry, userMuninnEntry } from './muninn-entry'
 
 import { LUCA_PACKAGE } from '../config/luca-version'
+import {
+    loadDecisionModelCredentials,
+    missingKeyLines,
+    type Env,
+} from '../jev/decision-model-credentials'
+import { DEFAULT_DECISION_MODEL } from '../jev/jev-schemas'
 import { READY_LABEL } from '../tracker/tracker'
 
 /**
  * `luca doctor`'s checks of this computer, read-only: Bun, the `luca`
  * copies on the PATH, Claude Code, the `gh` login, Paseo and its plugins,
  * the board, MuninnDB and Claude Code's `muninn` entry, the planning
- * skills, and Luca's own skills. `luca init` and `luca upgrade` end with them too. The token is
- * never shown.
+ * skills, Luca's own skills, and the decision model's credentials. `luca
+ * init` and `luca upgrade` end with them too. No token is ever shown.
  */
 
 /** The oldest tool versions Luca works with. */
@@ -367,12 +373,32 @@ const checkLucaSkills = async ({
     )
 }
 
+/**
+ * The decision model's Cloudflare credentials (#534), from Luca's own env
+ * file and the process env. With none it is off: a warning, not a problem,
+ * since runs go on without it. Never shows the token.
+ */
+const checkDecisionModel = async ({
+    env,
+    home,
+}: {
+    env: Env
+    home: string
+}) => {
+    const credentials = await loadDecisionModelCredentials({ env, home })
+    if (credentials.ok) return ok(`Clef set up (${DEFAULT_DECISION_MODEL})`)
+    return warning({
+        detail: `Decision model off: no credentials (${credentials.missing.join(' and ')} not set in ${credentials.file}).`,
+        fix: `Add these lines to ${credentials.file}: ${missingKeyLines(credentials).join(', ')} (a Workers AI token from the Cloudflare dashboard), or leave the decision model off.`,
+    })
+}
+
 /**
  * Runs the computer checks, in order, read-only. Never throws: a check that
  * fails becomes a problem.
  *
  * @example
- * const checks = await computerChecks({ home, luca_version, board_dir, skills_dir, engine_path, bun_path, computer, muninn, muninn_health, claude, paseo })
+ * const checks = await computerChecks({ home, luca_version, board_dir, skills_dir, engine_path, bun_path, computer, muninn, muninn_health, claude, paseo, env: process.env })
  */
 export const computerChecks = async ({
     home,
@@ -386,6 +412,7 @@ export const computerChecks = async ({
     muninn_health,
     claude,
     paseo,
+    env,
 }: {
     home: string
     /** The installed Luca's version. */
@@ -400,6 +427,11 @@ export const computerChecks = async ({
     muninn_health: MuninnHealth
     claude: ClaudeMcp
     paseo: Paseo
+    /**
+     * The process env, for the decision model's keys and `XDG_CONFIG_HOME`.
+     * Left out, none: only Luca's env file in `home` counts.
+     */
+    env?: Env
 }): Promise<DoctorCheck[]> => {
     // With Paseo down, its plugins and the board aren't asked about.
     let paseo_up = true
@@ -446,6 +478,10 @@ export const computerChecks = async ({
                 'luca_skills',
                 () => checkLucaSkills({ home, skills_dir, luca_version }),
             ],
+            [
+                'decision_model',
+                () => checkDecisionModel({ env: env ?? {}, home }),
+            ],
         ],
     })
 }

package/engine/cli/doctor-command.ts

@@ -65,6 +65,7 @@ export const doctorCommand = async ({
                           memory,
                       },
             tmp_dir: '/tmp',
+            env: process.env,
             log: (line) => {
                 console.log(line)
             },

package/engine/cli/doctor.ts

@@ -25,6 +25,7 @@ import {
 } from './v13-leftovers'
 
 import type { V13Manifest } from '../doctor/v13-manifest'
+import type { Env } from '../jev/decision-model-credentials'
 import type { MemoryClient } from '../memory/memory-client'
 import { runCommand } from '../shell/run-command'
 
@@ -32,7 +33,8 @@ import { runCommand } from '../shell/run-command'
  * `luca doctor [--fix]`: checks this computer, the repo when run inside
  * one, and what old Luca v13 left behind, and prints each check as OK, or
  * the problem and its exact fix. It exits 1 when any check is a problem;
- * warnings (memory off, planning-skill drift) don't fail it. When it finds
+ * warnings (memory off, the decision model off, planning-skill drift)
+ * don't fail it. When it finds
  * v13 leftovers, it links the migration guide.
  *
  * `--fix` fixes what's safe, without asking: it cleans up v13's leftovers
@@ -270,6 +272,7 @@ export const runDoctor = async ({
     repo,
     tmp_dir,
     v13_manifest,
+    env,
     log,
 }: LucaInstall & {
     home: string
@@ -285,6 +288,8 @@ export const runDoctor = async ({
     tmp_dir: string
     /** The v13 fingerprint list; defaults to the committed one. */
     v13_manifest?: V13Manifest
+    /** The process env, for the decision model's check. Left out, none. */
+    env?: Env
     log: (line: string) => void
 }): Promise<DoctorEnd> => {
     const check = async (): Promise<DoctorCheck[]> => [
@@ -300,6 +305,7 @@ export const runDoctor = async ({
             muninn_health,
             claude,
             paseo,
+            env,
         })),
         ...(repo === null
             ? []

package/engine/cli/init-command.ts

@@ -160,6 +160,7 @@ export const initCommand = async ({
             ask: askInTerminal,
             computer: computerOf({ home }),
             ...(await lucaInstall()),
+            env: process.env,
             log: (line) => {
                 console.log(line)
             },

package/engine/cli/init.ts

@@ -23,6 +23,8 @@ import { installLucaSkills } from './luca-skills'
 import { ensureMuninnEntry, hideToken } from './muninn-entry'
 import { runSetup } from './setup'
 
+import type { Env } from '../jev/decision-model-credentials'
+
 /**
  * `luca init`: sets up this computer for Luca, once, and is safe to run
  * again. It has three parts, each run even when an earlier one failed, and
@@ -297,6 +299,7 @@ export const runInit = async ({
     skills_dir,
     engine_path,
     bun_path,
+    env,
     log,
 }: LucaInstall & {
     home: string
@@ -312,6 +315,8 @@ export const runInit = async ({
     skills: SkillsTool
     ask: Ask
     computer: Computer
+    /** The process env, for the decision model's check. Left out, none. */
+    env?: Env
     log: (line: string) => void
 }): Promise<InitEnd> => {
     const memory = await setUpMemory({
@@ -356,6 +361,7 @@ export const runInit = async ({
         muninn_health,
         claude,
         paseo,
+        env,
     })
     for (const line of formatChecks({ checks: doctor })) log(line)
     const setup =

package/engine/cli/luca-run.ts

@@ -7,9 +7,13 @@
  *       --run-id <id> --board-plugin luca-board      (token in $LUCA_BOARD_TOKEN)
  *
  * A real run builds with real Claude agents (`createClaudeLauncher`: Claude
- * Opus 5.5, every guard on, paid by your Claude plan) and asks Jev in shadow
- * mode (`createTypeSafeJev`, which reads `TYPESAFE_API_KEY`; with no key each
- * ask is journaled as `missing_key` and the run goes on). Memory (#370) is
+ * Opus 5.5, every guard on, paid by your Claude plan) and asks the decision
+ * model, Cloudflare's Clef, in shadow mode (#534). Its credentials,
+ * `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`, come from Luca's own
+ * env file, `~/.config/luca/.env` (or `$XDG_CONFIG_HOME/luca/.env`), with
+ * the process env winning key by key; never from the repo's `.env`. With
+ * none, the decision model is off for the run: one line and one
+ * `decision_model_off` record, and no asks. Memory (#370) is
  * MuninnDB over MCP, found through `LUCA_MUNINN_URL` and `LUCA_MUNINN_TOKEN`
  * or Claude Code's `mcpServers.muninn` in `~/.claude.json`; with neither,
  * the run goes on without memory.
@@ -39,7 +43,7 @@ import {
 import { createClaudeLauncher } from '../agents/claude-launcher'
 import { createBoardSync, type BoardSync } from '../board/board-sync'
 import { createPaseoBoardLink } from '../board/paseo-board-link'
-import { createTypeSafeJev } from '../jev/jev-client'
+import { loadDecisionModelCredentials } from '../jev/decision-model-credentials'
 import { defaultRunsDir } from '../journal/journal'
 import {
     defaultSharedReadingsPath,
@@ -76,6 +80,14 @@ const memoryOf = async (): Promise<MemoryDeps | undefined> => {
     return { client: createMuninnMcpClient({ settings: found.settings }) }
 }
 
+/** The decision model's setup: its credentials from Luca's own env file. */
+const decisionModelSetup = async () => ({
+    credentials: await loadDecisionModelCredentials({
+        env: process.env,
+        home: homedir(),
+    }),
+})
+
 /**
  * The usage line (#434): the `luca-board` plugin's lines, and the readings
  * every run shares, both in Luca's state folder.
@@ -119,7 +131,7 @@ const run = async ({
             tracker: async ({ repo }) =>
                 createGitHubTracker({ repo: await githubRepoOf({ repo }) }),
             launcher: createClaudeLauncher({}),
-            jev: { client: createTypeSafeJev() },
+            decision_model: await decisionModelSetup(),
             memory: await memoryOf(),
             usage: usageLine(),
             board,
@@ -137,7 +149,7 @@ const run = async ({
         runs_dir: defaultRunsDir(),
         tracker,
         launcher: createClaudeLauncher({}),
-        jev: { client: createTypeSafeJev() },
+        decision_model: await decisionModelSetup(),
         memory: await memoryOf(),
         usage: usageLine(),
         board,

package/engine/cli/run-modes.ts

@@ -9,7 +9,7 @@ import { z } from 'zod'
 import type { AgentLauncher } from '../agents/agent-launcher'
 import { createScriptedLauncher } from '../agents/scripted-launcher'
 import type { BoardSync } from '../board/board-sync'
-import { loadEngineConfig } from '../config/engine-config'
+import { decisionModelOf, loadEngineConfig } from '../config/engine-config'
 import { lucaVersion } from '../config/luca-version'
 import { decide, type EngineAction } from '../core/decide'
 import {
@@ -21,10 +21,16 @@ import {
 } from '../core/execute'
 import { nothingToDoText } from '../core/left-out'
 import { createGitAdapter } from '../git/git-adapter'
-import { createTypeSafeJev } from '../jev/jev-client'
+import { createClefClient, type DecisionModelFetch } from '../jev/clef-client'
+import {
+    noCredentialsText,
+    type DecisionModelCredentials,
+} from '../jev/decision-model-credentials'
+import { DEFAULT_DECISION_MODEL } from '../jev/jev-schemas'
 import type { JevShadow } from '../jev/jev-shadow'
 import { createJournal, runJournalPath, type Journal } from '../journal/journal'
 import type { JournalRecord } from '../journal/journal-record'
+import { replayRun } from '../journal/replay'
 import type { UsageLineDeps } from '../limits/usage-line'
 import type { MemoryDeps } from '../memory/memory-client'
 import {
@@ -242,11 +248,67 @@ export const configReloadText = ({
     }
 }
 
+/**
+ * What a real run needs to ask the decision model (#534): its Cloudflare
+ * credentials (`loadDecisionModelCredentials`), and for tests a fake
+ * `fetch` and a shorter timeout. The model comes from the run's config.
+ */
+export type DecisionModelSetup = {
+    credentials: DecisionModelCredentials
+    /** Defaults to the global `fetch`. */
+    fetch?: DecisionModelFetch
+    /** Defaults to `DEFAULT_JEV_TIMEOUT_MS`. */
+    timeout_ms?: number
+}
+
+/**
+ * The decision model for this run, from `setup` and the model in the run's
+ * own config (its `run_started`, so a resume keeps it). With no credentials
+ * it is off for the run: one `decision_model_off { reason: 'no_credentials' }`
+ * record and one line naming Luca's env file and the keys to add, and no
+ * shadow, so nothing is ever asked. Never logs the token.
+ */
+const openDecisionModel = ({
+    setup,
+    journal,
+    log,
+}: {
+    setup: DecisionModelSetup | undefined
+    journal: Journal
+    log: (line: string) => void
+}): JevShadow | undefined => {
+    if (setup === undefined) return undefined
+    const { config } = replayRun({ records: journal.read() })
+    const model =
+        config === null ? DEFAULT_DECISION_MODEL : decisionModelOf({ config })
+    const { credentials } = setup
+    if (!credentials.ok) {
+        const detail = noCredentialsText(credentials)
+        journal.append({
+            kind: 'decision_model_off',
+            ticket: null,
+            role: null,
+            content: { model, reason: 'no_credentials', detail },
+        })
+        log(`[luca-run] decision model off: ${detail}`)
+        return undefined
+    }
+    log(`[luca-run] decision model: Clef (${model}), in shadow mode`)
+    return {
+        client: createClefClient({ credentials, model, fetch: setup.fetch }),
+        timeout_ms: setup.timeout_ms,
+        log: (line) => {
+            log(`[luca-run] ${line}`)
+        },
+    }
+}
+
 /**
  * A real run of `spec_number` on `repo`: loads the repo's engine config,
  * opens (or resumes) the run's journal at `<runs_dir>/<run_id>`, and runs the
- * engine with the board kept in step, the agents from `launcher`, and Jev
- * in shadow mode if given. With `memory`, a new run turns memory on (#370),
+ * engine with the board kept in step, the agents from `launcher`, and the
+ * decision model in shadow mode if given (`decision_model`; with no
+ * credentials it is off for the run, see `openDecisionModel`). With `memory`, a new run turns memory on (#370),
  * with the engine config's `muninn.vault` as the project vault (none:
  * `default` only); a resumed run keeps what its journal says. A new run
  * stops on a bad config; a resume takes the config's build fields again
@@ -258,7 +320,8 @@ export const configReloadText = ({
  * const end = await runSpec({
  *     spec_number: 374, repo: '/code/app', run_id, base_branch: null,
  *     runs_dir: defaultRunsDir(), tracker: createGitHubTracker({ repo: 'acme/app' }),
- *     launcher: createClaudeLauncher({}), jev: { client: createTypeSafeJev() },
+ *     launcher: createClaudeLauncher({}),
+ *     decision_model: { credentials: await loadDecisionModelCredentials({ env: process.env, home: homedir() }) },
  *     board, log: console.log,
  * })
  */
@@ -270,7 +333,7 @@ export const runSpec = async ({
     runs_dir,
     tracker,
     launcher,
-    jev,
+    decision_model,
     memory,
     usage,
     board,
@@ -285,8 +348,8 @@ export const runSpec = async ({
     runs_dir: string
     tracker: Tracker
     launcher: RunLauncher
-    /** Jev in shadow mode. Leave it out to run without Jev. */
-    jev?: JevShadow
+    /** The decision model's setup (#534). Leave it out to run without one. */
+    decision_model?: DecisionModelSetup
     /** MuninnDB (#370). Leave it out to run without memory. */
     memory?: MemoryDeps
     /** The usage line (#434). Leave it out to run without one. */
@@ -331,6 +394,7 @@ export const runSpec = async ({
         const reload = recordConfigReload({ journal, loaded })
         if (reload !== null) log(`[luca-run] ${configReloadText({ reload })}`)
     }
+    const jev = openDecisionModel({ setup: decision_model, journal, log })
     return driveRun({
         journal,
         run_id,
@@ -550,7 +614,7 @@ export const resumeRun = async ({
     repo,
     tracker,
     launcher,
-    jev,
+    decision_model,
     memory,
     usage,
     board,
@@ -563,8 +627,8 @@ export const resumeRun = async ({
     repo: string | null
     tracker: ({ repo }: { repo: string }) => Tracker | Promise<Tracker>
     launcher: RunLauncher
-    /** Jev in shadow mode. Leave it out to run without Jev. */
-    jev?: JevShadow
+    /** The decision model's setup (#534). Leave it out to go on without one. */
+    decision_model?: DecisionModelSetup
     /**
      * MuninnDB (#370), used when the run's `run_started` turned memory on.
      * Leave it out to go on without memory.
@@ -603,7 +667,7 @@ export const resumeRun = async ({
         runs_dir,
         tracker: made,
         launcher,
-        jev,
+        decision_model,
         memory,
         usage,
         board,
@@ -635,19 +699,12 @@ const slowLauncher = ({
     closeSession: (args) => launcher.closeSession(args),
 })
 
-/**
- * The demo's Jev: the real client with no key, so every ask is journaled as
- * `jev_failed` (`missing_key`) and nothing is sent, as in a real run without
- * `TYPESAFE_API_KEY`.
- */
-const OFFLINE_JEV: JevShadow = { client: createTypeSafeJev({ api_key: '' }) }
-
 /**
  * A practice run, safe to try the board with: a throwaway repo with a local
  * bare origin in a temp folder, the practice spec with two tickets (#12
  * blocked by #11) in an in-memory tracker, and scripted agents that take
- * `turn_delay_ms` per turn. No GitHub, no models, no network: Jev is asked in
- * shadow mode with no key, and memory (#370) is a fake MuninnDB seeded with
+ * `turn_delay_ms` per turn. No GitHub, no models, no network: the decision
+ * model is off (its credentials are never read), and memory (#370) is a fake MuninnDB seeded with
  * a few memories, so the board shows searches, the learner, and a save
  * with nothing leaving the machine. The temp folder (which also holds the run's
  * journal) is removed at the end.
@@ -681,6 +738,7 @@ export const runDemo = async ({
         log(`[luca-run] repo: ${repo}`)
         log(`[luca-run] origin: ${origin}`)
         log(`[luca-run] journal: ${journal.file}`)
+        log('[luca-run] decision model off: the demo never asks it.')
         const loaded = await loadEngineConfig({ repo_root: repo })
         if (!loaded.ok) throw new Error(loaded.error)
         const tracker = demoTracker()
@@ -714,7 +772,6 @@ export const runDemo = async ({
                     tracker,
                     git: createGitAdapter({ repo_root: repo }),
                     launcher,
-                    jev: OFFLINE_JEV,
                     memory,
                     board: board ?? undefined,
                 }),

package/engine/cli/upgrade-command.ts

@@ -261,6 +261,7 @@ const computerChecksOf =
             muninn_health: muninnHealth,
             claude: claudeOf({ home }),
             paseo,
+            env: process.env,
         })
 
 /** Runs `luca upgrade` with the flags after `upgrade`; returns the exit code. */

package/engine/config/config-reload.ts

@@ -43,6 +43,8 @@ export const RELOADED_FIELDS = [
  * - `muninn`: the run's memory vault is fixed at start (`run_started.memory`).
  * - `run_budget_tokens`: the budget the run's tokens are counted against,
  *   and the board's, from `run_started`; a raise is a `retry` reply.
+ * - `decision_model`: the model shadow mode asks (#534), so a run's asks
+ *   are all of one model and can be scored together.
  */
 export const FROZEN_FIELDS = [
     'checks',
@@ -51,6 +53,7 @@ export const FROZEN_FIELDS = [
     'rule_files',
     'muninn',
     'run_budget_tokens',
+    'decision_model',
 ] as const
 
 const positiveInt = z.number().int().positive().nullable()

package/engine/config/engine-config.ts

@@ -2,6 +2,12 @@ import { join } from 'node:path'
 
 import { z } from 'zod'
 
+import {
+    DEFAULT_DECISION_MODEL,
+    DecisionModelIdSchema,
+    type DecisionModelId,
+} from '../jev/jev-schemas'
+
 /**
  * The engine config file, relative to the root of the repo a run works on.
  * `muninn.vault` sits at the same path old Luca used, because memory tooling
@@ -33,9 +39,19 @@ export const MuninnConfigSchema = z.object({
     vault: z.string().min(1),
 })
 
+/**
+ * The config's `decision_model` block (#534): the Clef model shadow mode
+ * asks, `@cf/cloudflare/clef` (the accurate one, the default) or
+ * `@cf/cloudflare/clef-flash` (the fast one).
+ */
+export const DecisionModelConfigSchema = z.object({
+    model: DecisionModelIdSchema.default(DEFAULT_DECISION_MODEL),
+})
+
 /**
  * The per-repo engine config: the gate commands, where tests live, the rule
- * files for the rules lens, the project's memory vault, and the run budget.
+ * files for the rules lens, the project's memory vault, the decision model,
+ * and the run budget.
  *
  * Unknown keys, such as old Luca's, are dropped when the file is read.
  *
@@ -74,6 +90,8 @@ export const EngineConfigSchema = z.object({
     test_setup_files: z.array(z.string()).default([]),
     rule_files: z.array(z.string()).default([]),
     muninn: MuninnConfigSchema.optional(),
+    /** The decision model shadow mode asks; left out, Clef. */
+    decision_model: DecisionModelConfigSchema.optional(),
     /**
      * The repo's run budget in tokens; left out, the engine's default
      * (`DEFAULT_RUN_BUDGET_TOKENS`).
@@ -124,6 +142,21 @@ export const prepareConcurrencyOf = ({
     config: EngineConfig
 }): number => config.prepare_concurrency ?? DEFAULT_PREPARE_CONCURRENCY
 
+/**
+ * The decision model a run asks: the config's `decision_model.model`, else
+ * Clef (`DEFAULT_DECISION_MODEL`).
+ *
+ * @example
+ * decisionModelOf({ config: { ...config, decision_model: { model: '@cf/cloudflare/clef-flash' } } })
+ * // '@cf/cloudflare/clef-flash'
+ */
+export const decisionModelOf = ({
+    config,
+}: {
+    config: EngineConfig
+}): DecisionModelId =>
+    config.decision_model?.model ?? DecisionModelConfigSchema.parse({}).model
+
 /** One test command the engine runs, and how it reads the results. */
 export type TestCommand = { run: string; results: TestResults }