clauderipple 0.9.1 → 0.9.3

package/dist/mod/tests/register.test.tsx

@@ -918,6 +918,42 @@ test('keep-warm forks near expiry, refreshes the memo and stops once on a null f
   expect(stats.text).toContain('Warm: 1 pings')
 })
 
+test('a cache-reading ping keeps the card, a real reply and /clear drop it, and the demo draws it', async ($, on) => {
+  const b = boundaries(on, { keepWarm: true })
+  http(on)
+  judgeStub(on)
+  stepStub(on)
+  on('model.fork', () => ({ value: { isAnswered: true, text: 'ok', usage: USAGE } }))
+  await start($)
+  await step($)
+  await complete($)
+  await b.clock.advance(3375000)
+  // The ping read 40000 cache tokens: the card tells it, with the memo's minutes left.
+  const ui = await band($)
+  expect(await ui.find({ type: 'Text', text: /held 40k tokens in cache/ })).toBeDefined()
+  await ui.unmount()
+  // A prompt counts as having seen the card; the next is a real reply, which clears the count.
+  await submit($)
+  await step($)
+  await complete($)
+  const after = await band($)
+  expect(await after.find({ type: 'Text', text: /held 40k tokens in cache/ })).toBeUndefined()
+  await after.unmount()
+  await b.clock.advance(3375000)
+  await b.clock.settle()
+  const again = await band($)
+  expect(await again.find({ type: 'Text', text: /held 40k tokens in cache/ })).toBeDefined()
+  await again.unmount()
+  await $.classic.SessionStart({ source: 'clear' })
+  const cleared = await band($)
+  expect(await cleared.find({ type: 'Text', text: /held 40k tokens in cache/ })).toBeUndefined()
+  await cleared.unmount()
+  // The demo shows the card with sample values, whatever the state.
+  await command($, 'kept')
+  const demo = await band($)
+  expect(await demo.find({ type: 'Text', text: /held 312k tokens in cache/ })).toBeDefined()
+})
+
 test('fork turn.step is not effort-steered, busy or main-request cost', async ($, on) => {
   const b = boundaries(on, { keepWarm: true })
   http(on)
@@ -941,6 +977,23 @@ test('fork turn.step is not effort-steered, busy or main-request cost', async ($
   expect(stats.text).toContain('Warm: 1 pings')
 })
 
+test('the flame turns keep-warm off for this chat only; Settings stay as they are', async ($, on) => {
+  const b = boundaries(on, { keepWarm: true })
+  http(on)
+  judgeStub(on, '{"effort":"high","why":"scope"}')
+  stepStub(on)
+  let forks = 0
+  on('model.fork', async () => { forks++; return { value: { isAnswered: true, text: 'ok', usage: USAGE } } })
+  await start($)
+  await submit($)
+  await step($)
+  await complete($)
+  await $.command.run({ command: 'ripple', origin: { kind: 'composer' }, presentation: { isFullscreen: true, columns: 140 }, args: 'warm' })
+  await b.clock.advance(3375000)
+  expect(forks).toBe(0)
+  expect(b.router().settings.keepWarm).toBe(true)
+})
+
 test('Haiku compaction returns replacement messages and forwards the keep note', async ($, on) => {
   boundaries(on)
   http(on)
@@ -1131,6 +1184,16 @@ for (const surface of ['terminal', 'desktop'] as const) test('quick controls sav
   await ui.unmount()
 })
 
+test('ripple-bar says where the line is when the layout is minimal', async ($, on) => {
+  const b = boundaries(on, { layout: 'minimal' })
+  http(on)
+  await start($)
+  const run = () => $.command.run({ command: 'ripple-bar', origin: { kind: 'composer' }, presentation: { isFullscreen: true, columns: 140 }, args: '' })
+  expect((await run()).text).toContain('hidden')
+  expect(b.saved.get('bandHidden')).toBe(true)
+  expect((await run()).text).toContain('Minimal')
+})
+
 for (const surface of ['terminal', 'desktop'] as const) test('quick settings select a saved mode, never edit rungs, on ' + surface, async ($, on) => {
   const b = boundaries(on, { modes: BURN })
   http(on)

package/dist/mod/tests/ui.test.tsx

@@ -265,6 +265,7 @@ test('a ko frame resolves temporary Korean text in labels and hover cards', asyn
 
 const ALERTS: AlertView[] = [
   { kind: 'cold', tokens: 182_000, idleMinutes: 74 },
+  { kind: 'kept', pings: 2, tokens: 312_000, minutesLeft: 47 },
   { kind: 'swamp', percent: 63, tokens: 126_000 },
   { kind: 'hot', limitKind: 'five_hour', percent: 86, resetsAt: '2026-10-10T15:40:00', save: false },
   { kind: 'judgeDown', judge: 'jev', reason: 'key rejected (401)' },
@@ -297,14 +298,17 @@ test('alert choices reach their callbacks', async ($, on) => {
     setHandoffKind: fn('kind'), setHandoffAfter: fn('after'), go: fn('go'), copy: fn('copy'), openNew: fn('open-new'),
   }
   drawPane(on, 'cold', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[0]!, actions))
-  drawPane(on, 'hot', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[2]!, actions))
+  drawPane(on, 'kept', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[1]!, actions))
+  drawPane(on, 'hot', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[3]!, actions))
   drawPane(on, 'note', (el, surface) => renderAlert(el, frameOf(surface), { kind: 'compactNote', draft: '' }, actions))
-  drawPane(on, 'choice', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[10]!, actions))
+  drawPane(on, 'choice', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[11]!, actions))
   for (const surface of SURFACES) {
     const cold = await mount($, 'cold', surface)
     await cold.press({ key: 'compact' })
     await cold.press({ key: 'handoff' })
     await cold.press({ key: 'dismiss' })
+    const kept = await mount($, 'kept', surface)
+    await kept.press({ key: 'dismiss' })
     const hot = await mount($, 'hot', surface)
     await hot.press({ key: 'save' })
     const note = await mount($, 'note', surface)
@@ -314,7 +318,7 @@ test('alert choices reach their callbacks', async ($, on) => {
     await choice.press({ key: 'after-copy' })
     await choice.press({ key: 'go' })
   }
-  const once = ['compact', 'handoff', 'dismiss', 'save', 'compact:["keep the API decision"]', 'kind:["full"]', 'after:["copy"]', 'go']
+  const once = ['compact', 'handoff', 'dismiss', 'dismiss', 'save', 'compact:["keep the API decision"]', 'kind:["full"]', 'after:["copy"]', 'go']
   expect(calls).toEqual([...once, ...once])
 })
 
@@ -354,9 +358,9 @@ test('each alert shows 리플이 with the face of its state, its gauge in 5% ste
     expect(mascots(await terminal.drawn()).length).toBe(0)
     await terminal.unmount()
   }
-  // handoffDone and compacted share the pleased face, compactNote and handoffChoice the asking
-  // one; every other state has its own.
-  expect(new Set(sources).size).toBe(ALERTS.length - 2)
+  // handoffDone, compacted and kept share the pleased face, compactNote and handoffChoice the
+  // asking one; every other state has its own.
+  expect(new Set(sources).size).toBe(ALERTS.length - 3)
   const source = async (id: string) => {
     const ui = await mount($, id, 'desktop')
     const s = String(mascots(await ui.drawn())[0]?.props?.source)

package/dist/mod/types/index.d.ts

@@ -149,6 +149,12 @@ export type Settings = {
    * picks, only among these.
    */
   allow: string[]
+  /**
+   * The allow-list keys of every worker that existed when `allow` was last written (what
+   * `candidateKey` returns). A key absent from this non-empty list counts as ticked on; empty means
+   * either every worker is ticked (`allow` empty) or all writers predate the field (#56).
+   */
+  allowKnown: string[]
   /** The user's operating modes; none is built in. */
   modes: Mode[]
   /** The mode that is on, by id; absent when none is. */
@@ -301,12 +307,15 @@ declare module 'claude-code' {
       agents: AgentRec[]
       cache: CacheMemo | null
       warm: WarmState
+      /** Keep-warm for this chat alone, set by the band's flame; null follows Settings. */
+      warmHere: boolean | null
       context: { percent: number; tokens: number; window: number } | null
       hot: Hot | null
       hotHidden: number | null
       saveUntil: number | null
       swampHidden: number | null
       coldHidden: boolean
+      kept: { pings: number; tokens: number } | null
       judgeDown: string | null
       advice: string | null
       handoff: { stage: HandoffStage; kind: HandoffKind; text?: string } | null
@@ -345,7 +354,7 @@ declare module 'claude-code' {
       judgeRuns: JudgeRun[]
       judgeDownNetwork: boolean
       limit: Hot | null
-      demo: 'cold' | 'swamp' | 'hot' | 'down' | null
+      demo: 'cold' | 'swamp' | 'hot' | 'down' | 'kept' | null
     }
   }
 }

package/dist/router/src/admin.js

@@ -23,7 +23,7 @@ import path from "node:path";
 import http from "node:http";
 import { execFile, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { adminPort, homeDir, searchProviderFor, validate } from "./config.js";
+import { adminPort, headerValueProblem, homeDir, searchProviderFor, validate } from "./config.js";
 export { adminPort } from "./config.js";
 import { generatedAgents } from "./agents.js";
 import { isJudgeOnlyModel } from "./model-policy.js";
@@ -33,6 +33,7 @@ import { normalizeSettings } from "../../mod/hooks/settings.js";
 import { chatPickerModels } from "./picker.js";
 import { PRESETS } from "./presets.js";
 import { resolveCompatibleCaps } from "./compat.js";
+import { redactErrorText } from "./redact.js";
 import { CHATGPT_FALLBACK_MODELS } from "./providers/chatgpt/catalog.js";
 import { measureModel, refusedByPlan } from "./capabilities.js";
 import { catalogEntry } from "./catalog.js";
@@ -53,6 +54,9 @@ import { exhaustedForMs, IMAGE_ASPECTS, IMAGE_BACKGROUNDS, IMAGE_FORMATS } from
 import { ANTIGRAVITY_WARNING, staticAntigravityModels } from "./providers/google/antigravity.js";
 import { readGoogleAccounts, removeGoogleAccount, summarize as summarizeGoogleAccount, updateGoogleAccount } from "./providers/google/accounts.js";
 import { GoogleOAuthSession } from "./providers/google/login.js";
+import { GROK_AUTH_HINT, grokAuthPath, grokHome, readGrokToken, sharedGrokAuth } from "./providers/grok/auth.js";
+import { GROK_DEFAULT_URL, GROK_EFFORT_LEVELS, GROK_FALLBACK_MODELS, grokModelsFromListing } from "./providers/grok/catalog.js";
+import { GROK_WARNING, grokHeaders } from "./providers/grok/index.js";
 const MAX_BODY = 1024 * 1024;
 /** `/api/image` carries reference images inline, so it gets more room than a config save. */
 const MAX_IMAGE_BODY = 32 * 1024 * 1024;
@@ -96,7 +100,8 @@ async function claudeAccountUsage(deps) {
     }
     return rows;
 }
-const ANTHROPIC_EFFORT_LEVELS = ["low", "medium", "high", "max"];
+// The CLI's `--effort` takes the same five; Opus, Sonnet and Haiku 5.5 answered `xhigh` (requests.jsonl, 2026-10-14, #56).
+const ANTHROPIC_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 const CHATGPT_DEFAULT_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 let chatgptLogin = { running: false };
 /** The Claude subscription sign-in in progress (or the last one), for GET /api/claude-oauth. */
@@ -157,6 +162,12 @@ export function effortLevels(cfg) {
             providers[name] = { default: ANTHROPIC_EFFORT_LEVELS };
             continue;
         }
+        if (provider.type === "grok") {
+            // The proxy's listing gives each model its ladder (the probe saves it); a model it has not
+            // described gets the common one, which is also what the adapter sends it.
+            providers[name] = { default: [...GROK_EFFORT_LEVELS], ...(Object.keys(modelLevels).length ? { models: modelLevels } : {}) };
+            continue;
+        }
         const preset = provider.preset ? PRESETS.find((entry) => entry.id === provider.preset) : undefined;
         providers[name] = {
             default: resolveCompatibleCaps(preset ? { effortLevels: preset.effortLevels, thinking: preset.thinking, ...(preset.serverTools ? { serverTools: true } : {}) } : undefined, provider.caps).effortLevels,
@@ -282,6 +293,14 @@ export function chatgptSignedIn(mode) {
     const borrowed = fs.existsSync(path.join(os.homedir(), ".codex", "auth.json"));
     return mode === "own" ? own : mode === "borrow-codex" ? borrowed : own || borrowed;
 }
+/**
+ * Whether the Grok CLI's session is there and not yet expired. A session near its end still counts:
+ * the router asks the CLI to refresh it before the next turn.
+ */
+export function grokSignedIn(p) {
+    const token = readGrokToken(grokAuthPath(p.home ?? grokHome()));
+    return token !== null && (token.expiresAt === 0 || token.expiresAt > Date.now());
+}
 /**
  * An Antigravity provider is only as usable as its accounts: none signed in, or every one waiting on
  * Google's verification page, answers nothing however reachable the host is.
@@ -393,8 +412,8 @@ async function withFilledLadder(deps, scores, settings) {
         return settings;
     try {
         const choices = ladderChoices(await modOptions(deps, scores));
-        const { rungs } = fillLadder(general.rungs, settings.allow, choices);
-        const modes = settings.modes.map(mode => ({ ...mode, rungs: fillLadder(mode.rungs, settings.allow, choices).rungs }));
+        const { rungs } = fillLadder(general.rungs, settings.allow, choices, settings.allowKnown);
+        const modes = settings.modes.map(mode => ({ ...mode, rungs: fillLadder(mode.rungs, settings.allow, choices, settings.allowKnown).rungs }));
         return { ...settings, rules: { general: { mode: "ladder", rungs } }, modes };
     }
     catch (error) {
@@ -409,7 +428,7 @@ async function buildStatus(deps, opts = {}) {
     // Keyed in the order the config lists them. Assigning inside the Promise.all callbacks ordered
     // them by whichever TCP check answered first, so the Health list reshuffled on every poll.
     const checked = await Promise.all(Object.entries(cfg.providers).map(async ([name, p]) => {
-        const url = p.type === "anthropic" ? "https://api.anthropic.com" : p.type === "chatgpt" ? (p.url ?? "https://chatgpt.com/backend-api") : p.type === "google" ? (p.url ?? "https://generativelanguage.googleapis.com") : p.url;
+        const url = p.type === "anthropic" ? "https://api.anthropic.com" : p.type === "chatgpt" ? (p.url ?? "https://chatgpt.com/backend-api") : p.type === "google" ? (p.url ?? "https://generativelanguage.googleapis.com") : p.type === "grok" ? (p.url ?? GROK_DEFAULT_URL) : p.url;
         let reachable = false;
         try {
             const u = new URL(url);
@@ -444,6 +463,7 @@ async function buildStatus(deps, opts = {}) {
                 // Reaching the host says nothing about being able to use it: a chatgpt provider with no
                 // credentials is not "connected", and calling it that sends the user off believing it works.
                 ...(p.type === "chatgpt" ? { needsLogin: !chatgptSignedIn(p.auth) } : {}),
+                ...(p.type === "grok" ? { needsLogin: !grokSignedIn(p) } : {}),
                 ...(p.type === "google" && p.auth === "antigravity" ? googleHealth(deps.google?.().accounts?.()[name] ?? []) : {}),
                 ...(p.type === "anthropic"
                     ? {
@@ -843,6 +863,53 @@ async function probeGoogleAntigravity(deps) {
     const models = named ? await deps.google?.().models?.(named).catch(() => null) ?? null : null;
     return { ok: true, auth: "ok", models: models ?? staticAntigravityModels() };
 }
+/**
+ * `{type:"grok"}`: whether the Grok CLI's session is usable, and the models its chat proxy lists.
+ * The session goes through the same `GrokAuth` the adapter uses — one near its end is refreshed
+ * through the CLI here too — and the listing is asked with the headers live traffic sends, since a
+ * test that presents another auth set certifies a path nobody uses (§5).
+ */
+async function probeGrok(body, log, probeFetch = fetchWithTimeout) {
+    const text = (value) => typeof value === "string" && value ? value : undefined;
+    const home = text(body.home) ?? grokHome();
+    const cli = text(body.cli);
+    const clientVersion = text(body.clientVersion);
+    const fallback = (result) => ({ ...result, models: GROK_FALLBACK_MODELS, modelsSource: "fallback", warning: GROK_WARNING });
+    const versionProblem = clientVersion ? headerValueProblem(clientVersion) : null;
+    if (versionProblem)
+        return fallback({ ok: false, auth: "unknown", error: `clientVersion cannot be sent as a header: ${versionProblem}` });
+    // The adapter's own instance for this session, so a probe joins a refresh a turn started (and the
+    // reverse) instead of spawning a second CLI.
+    const auth = sharedGrokAuth({ home, ...(cli ? { cli } : {}), log });
+    let token;
+    try {
+        token = await auth.token();
+    }
+    catch (error) {
+        return fallback({ ok: false, auth: "missing", error: errorText(error) });
+    }
+    const base = (text(body.url) ?? GROK_DEFAULT_URL).replace(/\/+$/, "");
+    const { "x-grok-model-override": _route, ...headers } = grokHeaders(token.key, "", await auth.clientVersion(clientVersion));
+    let response;
+    try {
+        response = await probeFetch(`${base}/models`, { headers });
+    }
+    catch (error) {
+        // fetch quotes a header value it refuses, which here is the session token.
+        return fallback({ ok: false, auth: "unreachable", error: redactErrorText(errorText(error), [token.key]) });
+    }
+    if (response.status === 401 || response.status === 403) {
+        return fallback({ ok: false, auth: "bad-key", error: `the proxy refused the Grok session (HTTP ${response.status}): ${GROK_AUTH_HINT}` });
+    }
+    if (!response.ok) {
+        const detail = redactErrorText(await response.text().catch(() => ""), [token.key]);
+        return fallback({ ok: false, auth: "unknown", error: `HTTP ${response.status}${detail ? `: ${detail.slice(0, 300)}` : ""}` });
+    }
+    const models = grokModelsFromListing(await response.json().catch(() => null));
+    return models.length
+        ? { ok: true, auth: "ok", models, modelsSource: "catalog", warning: GROK_WARNING }
+        : fallback({ ok: true, auth: "ok" });
+}
 function chatCompletionsUrl(base) {
     return `${base.replace(/\/+$/, "")}/chat/completions`;
 }
@@ -1532,6 +1599,10 @@ export function startAdmin(deps) {
                     });
                     return;
                 }
+                if (probe.type === "grok") {
+                    sendJson(res, 200, await probeGrok(probe, deps.log, deps.probeFetch));
+                    return;
+                }
                 if (probe.type === "google") {
                     if (probe.auth === "antigravity") {
                         sendJson(res, 200, await probeGoogleAntigravity(deps));

package/dist/router/src/agents.js

@@ -15,6 +15,7 @@ import path from "node:path";
 import { adminPort, homeDir } from "./config.js";
 import { declaredBy } from "./routing.js";
 import { isJudgeOnlyModel } from "./model-policy.js";
+import { GROK_EFFORT_LEVELS } from "./providers/grok/catalog.js";
 import { shortName } from "../../cli/src/hooks/agent-title.js";
 /** Where Claude Code's Agent tool reads its worker definitions. */
 export function defaultAgentDir() {
@@ -145,6 +146,9 @@ export function agentNameFor(modelId) {
     return modelId.replace(/[^a-z0-9-]/g, "-");
 }
 function capsEffortLevels(provider) {
+    // A grok provider has no caps: its adapter sends the common ladder to a model the listing left out.
+    if (provider.type === "grok")
+        return [...GROK_EFFORT_LEVELS];
     return provider.caps?.effortLevels;
 }
 /**

package/dist/router/src/config.js

@@ -153,6 +153,9 @@ export function headerValueProblem(value) {
         // A newline would split the header; a stray one usually means a copied line rather than a key.
         if (code === 0x0a || code === 0x0d)
             return `there is a line break at character ${i + 1} — paste the key on its own, without the line around it`;
+        // fetch refuses a NUL too, so a value that passes here would only fail when sent.
+        if (code === 0x00)
+            return `there is a NUL character at character ${i + 1} — paste the key on its own`;
     }
     return null;
 }
@@ -429,6 +432,27 @@ export function validate(c) {
                 errors.push(`provider ${name}: ${MODELS_SHAPE}`);
             }
         }
+        else if (p.type === "grok") {
+            for (const field of ["home", "cli", "clientVersion"]) {
+                if (p[field] !== undefined && (typeof p[field] !== "string" || !p[field]))
+                    errors.push(`provider ${name}: ${field} must be a non-empty string`);
+            }
+            // Sent as `x-grok-client-version`, so it has to survive being a header value.
+            const versionProblem = typeof p.clientVersion === "string" && p.clientVersion ? headerValueProblem(p.clientVersion) : null;
+            if (versionProblem)
+                errors.push(`provider ${name}: clientVersion cannot be sent as a header: ${versionProblem}`);
+            if (p.url !== undefined && !/^https?:\/\//.test(p.url))
+                errors.push(`provider ${name}: url must start with http:// or https://`);
+            if (p.models !== undefined) {
+                if (!validModels(p.models))
+                    errors.push(`provider ${name}: ${MODELS_SHAPE}`);
+                // `providerFor` turns a model with its own wire, url or auth header into an openai-compatible
+                // provider, which would go out without the session headers this one exists to add.
+                else if (p.models.some((m) => m.wire !== undefined || m.url !== undefined || m.authHeader !== undefined)) {
+                    errors.push(`provider ${name}: a grok model cannot set wire, url or authHeader`);
+                }
+            }
+        }
         else {
             errors.push(`provider ${name}: unknown type "${p.type}"`);
         }

package/dist/router/src/ingress/server.js

@@ -332,8 +332,8 @@ export class OpenAiIngress {
             // is an OpenAI wire, which the refusal below would otherwise turn away on the provider's type
             // alone. One subscription is one provider, so the model decides.
             const provider = providerFor(configured, route.model);
-            if (provider.type === "chatgpt" || provider.type === "openai-compatible" || provider.type === "google") {
-                const label = provider.type === "chatgpt" ? "ChatGPT" : provider.type === "google" ? "Google" : "OpenAI-compatible";
+            if (provider.type === "chatgpt" || provider.type === "openai-compatible" || provider.type === "google" || provider.type === "grok") {
+                const label = provider.type === "chatgpt" ? "ChatGPT" : provider.type === "google" ? "Google" : provider.type === "grok" ? "Grok" : "OpenAI-compatible";
                 const bytes = sendJson(res, 400, openAiError(`${label} provider is not available through OpenAI ingress`, "invalid_request_error", "unsupported_provider"));
                 finish(400, bytes, { note: `model ${requested} -> ${provider.type} provider unsupported` });
                 return;