clauderipple 0.8.10 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.9.0 — 2026-10-13
+
+### Added
+
+- **The ripple mod.** A band above the Code tab's prompt shows reasoning effort, context, the
+  cache timer, and which model answered each request with its cache hit. Log opens the request
+  log, ⚙ opens quick settings, and the dashboard has a mod page with every setting.
+- **Effort picked per prompt.** A small judge model (Haiku 5.5 or Jev) reads the prompt and the
+  recent turns, then sets low through max. Pick an effort yourself whenever you want; Auto comes
+  back when you switch it on.
+- **Workers picked per task.** The main chat hands work to `ripple:auto`, and the judge decides
+  how hard each task is and sends it to the matching rung: light work to DeepSeek or GLM, hard work
+  to GPT or Opus. Rungs, candidate models and named modes (prefer or avoid a model, eager
+  delegation, switch off at a quota reset) are set on the dashboard. Every pick is kept in
+  `logs/worker-picks.jsonl`.
+- **Warnings that save tokens.** Cards appear when the prompt cache has gone cold on a big chat,
+  when the context gets heavy, and when a plan window passes 80%. Each card offers compact or a
+  handoff.
+- **Handoff to a fresh session.** A handoff writes a summary and opens a new session in the same
+  folder with it in the prompt box. The current chat is left as it is.
+- **리플이**, the mascot, on the band and every card, acting out what the band is doing. Mod text
+  in six languages, following the Mac's system language.
+- **Artificial Analysis scores** for every routable model, refreshed daily, used to rank worker
+  candidates by measured cost.
+- A provider that answers 402 or says its quota is exhausted is skipped for a while.
+
+### Changed
+
+- Dashboard settings are rebuilt in the style of macOS System Settings.
+- The mod's settings live in the router, so every session follows a change at once.
+
+### Fixed
+
+- Judge-only models such as Jev no longer appear in pickers, worker lists or Codex.
+- The install script works under macOS `/bin/sh` again.
+
 ## 0.8.10 — 2026-10-10
 
 ### Added

package/README.es.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
-</p>
-
 <h1 align="center">ClaudeRipple</h1>
 
 <p align="center"><a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <b>Español</b> · <a href="README.pt-BR.md">Português (BR)</a></p>

package/README.ja.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
-</p>
-
 <h1 align="center">ClaudeRipple</h1>
 
 <p align="center"><a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <b>日本語</b> · <a href="README.es.md">Español</a> · <a href="README.pt-BR.md">Português (BR)</a></p>

package/README.ko.md

@@ -1,5 +1,9 @@
 <p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="brand/mark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="brand/mark.svg">
+    <img src="brand/mark.svg" width="120" height="120" alt="ClaudeRipple 마스코트 리플이: 속이 빈 파문 고리에 물마루가 말려 오른 모습">
+  </picture>
 </p>
 
 <h1 align="center">ClaudeRipple</h1>

package/README.md

@@ -1,5 +1,9 @@
 <p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="brand/mark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="brand/mark.svg">
+    <img src="brand/mark.svg" width="120" height="120" alt="The ClaudeRipple mascot: a hollow ripple ring with a curling wave crest">
+  </picture>
 </p>
 
 <h1 align="center">ClaudeRipple</h1>

package/README.pt-BR.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
-</p>
-
 <h1 align="center">ClaudeRipple</h1>
 
 <p align="center"><a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a> · <b>Português (BR)</b></p>

package/README.zh-CN.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
-</p>
-
 <h1 align="center">ClaudeRipple</h1>
 
 <p align="center"><a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <b>简体中文</b> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a> · <a href="README.pt-BR.md">Português (BR)</a></p>

package/dist/app/package.json

@@ -1,5 +1,5 @@
 {
   "private": true,
-  "version": "0.8.10",
+  "version": "0.9.0",
   "type": "commonjs"
 }

package/dist/cli/src/codex.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isJudgeOnlyModel } from "../../router/src/model-policy.js";
 const START = "# >>> ClaudeRipple Codex provider >>>";
 const END = "# <<< ClaudeRipple Codex provider <<<";
 const PROFILE_START = "# >>> ClaudeRipple Codex profile >>>";
@@ -76,7 +77,8 @@ export function writeCodexCatalog(models, home = codexHome()) {
     catch {
         return undefined;
     }
-    const entries = (cached.models ?? []).filter((m) => typeof m.slug === "string");
+    models = models.filter(m => !isJudgeOnlyModel(m.id));
+    const entries = (cached.models ?? []).filter((m) => typeof m.slug === "string" && !isJudgeOnlyModel(m.slug));
     const template = entries.find((m) => m.slug === "gpt-5.5" && m.model_messages) ?? entries.find((m) => m.model_messages);
     if (!template)
         return undefined;

package/dist/cli/src/settings.js

@@ -216,11 +216,14 @@ export function agentTitleHookEnabled() {
 }
 // ---- Status mod (packages/mod) ------------------------------------------------------------
 /** The `name` in packages/mod/.claude-plugin/plugin.json: how our entry is told from anyone else's. */
-export const STATUS_MOD_NAME = "clauderipple-status";
+export const STATUS_MOD_NAME = "ripple";
+/** Its name until 0.8.10: an entry an older install added is still ours to replace or remove. */
+const OLD_STATUS_MOD_NAMES = ["clauderipple-status"];
 const PLUGIN_DIRS = "CLAUDE_CODE_PLUGIN_DIRS";
 function isStatusMod(dir) {
     try {
-        return JSON.parse(fs.readFileSync(path.join(dir, ".claude-plugin", "plugin.json"), "utf8")).name === STATUS_MOD_NAME;
+        const name = JSON.parse(fs.readFileSync(path.join(dir, ".claude-plugin", "plugin.json"), "utf8")).name;
+        return name === STATUS_MOD_NAME || OLD_STATUS_MOD_NAMES.includes(name);
     }
     catch {
         return false;

package/dist/mod/.claude-plugin/plugin.json

@@ -1 +1,9 @@
-{ "name": "clauderipple-status", "version": "0.1.0", "description": "Shows where ClaudeRipple sent each request and its request log, and keeps ClaudeRipple workers on their own model and effort.", "types": "./types/index.d.ts" }
+{
+  "name": "ripple",
+  "displayName": "ClaudeRipple",
+  "version": "0.7.0",
+  "description": "Picks the reasoning effort for every prompt and the worker for every delegated task, can keep the prompt cache warm, and shows where ClaudeRipple sent each request.",
+  "author": { "name": "ClaudeRipple" },
+  "license": "GPL-3.0-only",
+  "types": "./types/index.d.ts"
+}

package/dist/mod/hooks/cache.ts

@@ -0,0 +1,60 @@
+import type { ModelForkResult } from 'claude-code'
+import type { CacheMemo, Settings, Usage, WarmState } from '../types'
+import { weighted } from './stats'
+import { t } from './i18n.ts'
+import type { Lang } from './i18n.ts'
+
+const HOUR = 3600000
+const FIVE_MINUTES = 300000
+
+export function ttlFromUsage(usage: Usage): number {
+  if ((usage.cache_creation?.ephemeral_1h_input_tokens ?? 0) > 0) return HOUR
+  if ((usage.cache_creation?.ephemeral_5m_input_tokens ?? 0) > 0) return FIVE_MINUTES
+  return HOUR
+}
+
+/** A five-minute tail must not shorten a mostly-read hour-long prefix. */
+export function nextMemo(prev: CacheMemo | null, usage: Usage, now: number): CacheMemo {
+  const total = (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0)
+  const mostlyRead = (usage.cache_read_input_tokens ?? 0) > total / 2
+  const explicit = (usage.cache_creation?.ephemeral_1h_input_tokens ?? 0) > 0 || (usage.cache_creation?.ephemeral_5m_input_tokens ?? 0) > 0
+  let ttlMs = explicit ? ttlFromUsage(usage) : prev?.ttlMs ?? HOUR
+  if (prev?.ttlMs === HOUR && mostlyRead) ttlMs = HOUR
+  if (!explicit && prev && now - prev.lastReplyAt > FIVE_MINUTES && mostlyRead) ttlMs = HOUR
+  return { ttlMs, lastReplyAt: now, expiresAt: now + ttlMs }
+}
+
+export function secondsLeft(memo: CacheMemo | null, now: number): number | null {
+  return memo ? Math.max(0, Math.ceil((memo.expiresAt - now) / 1000)) : null
+}
+
+/** Never pay to revive an expired cache or extend the last-real-reply bound with our own pings. */
+export function shouldPing(input: {
+  settings: Settings; memo: CacheMemo | null; warm: WarmState; now: number; idle: boolean
+  contextTokens: number; lastRealReplyAt: number | null
+}): { ping: true } | { ping: false; reason?: string } {
+  const { settings, memo, warm, now } = input
+  if (!settings.keepWarm) return { ping: false, reason: 'keep warm is off' }
+  if (warm.stopped) return { ping: false, reason: warm.stopped }
+  if (!input.idle) return { ping: false, reason: 'chat is busy' }
+  if (!memo || memo.expiresAt <= now) return { ping: false, reason: 'cache is not warm' }
+  if (input.lastRealReplyAt === null || now >= input.lastRealReplyAt + settings.keepWarmHours * HOUR) return { ping: false, reason: 'keep warm time bound reached' }
+  if (input.contextTokens < settings.keepWarmMinTokens) return { ping: false, reason: 'chat is too small' }
+  const lead = memo.ttlMs === FIVE_MINUTES ? 60000 : 240000
+  return memo.expiresAt - now <= lead ? { ping: true } : { ping: false }
+}
+
+/** Failed forks stop once; answered cache misses still count the real tokens they spent. */
+export function afterPing(warm: WarmState, forkResult: ModelForkResult | null, now: number, lang: Lang = 'en'): WarmState {
+  if (!forkResult?.isAnswered) return { ...warm, stopped: t(lang, 'toasts.warmNoReply') }
+  const next: WarmState = { pings: warm.pings + 1, cost: warm.cost + weighted(forkResult.usage), lastPingAt: now }
+  if (forkResult.usage.cache_read_input_tokens <= 0) next.stopped = t(lang, 'toasts.warmNoCache')
+  return next
+}
+
+export function restoreFromResume(secondsSinceLastResponse: number | undefined, likelyExpired: boolean | undefined, ttlMs: number, now: number): CacheMemo | null {
+  if (secondsSinceLastResponse === undefined || !Number.isFinite(secondsSinceLastResponse) || secondsSinceLastResponse < 0) return null
+  const lastReplyAt = now - secondsSinceLastResponse * 1000
+  const expiresAt = lastReplyAt + ttlMs
+  return { ttlMs, lastReplyAt, expiresAt: likelyExpired || expiresAt <= now ? now - 1 : expiresAt }
+}

package/dist/mod/hooks/compact.ts

@@ -0,0 +1,40 @@
+import type { SessionCompacted, SessionMessage } from 'claude-code'
+
+export const COMPACT_SYSTEM = `Create a faithful continuation record of this coding conversation. Keep the user's intent and changes of mind, decisions and constraints, relevant concepts, files and code touched, errors and their fixes, and user feedback. List user requests in order, distinguish solved from pending work, and state exactly what is happening now. Include a next step only when the conversation justifies it. Preserve useful exact paths and commands, but omit secrets, redundant logs, and obsolete detail. Do not invent verification or claim unfinished work is complete. Write in the user's language.`
+
+function clipped(text: string, limit: number): string {
+  return text.length > limit ? `${text.slice(0, limit)}\n[truncated]` : text
+}
+
+function render(messages: readonly SessionMessage[], tight: boolean): string {
+  return messages.map((message, index) => {
+    const tail = index >= messages.length - 6
+    const inputLimit = tail ? (tight ? 4000 : 20000) : 400
+    const resultLimit = tail ? (tight ? 4000 : 20000) : (tight ? 300 : 2000)
+    const parts = [`${message.role}:\n${message.text}`]
+    for (const use of message.toolUses) {
+      parts.push(`tool ${use.tool} (${use.tool_use_id}):\n${clipped(JSON.stringify(use.input), inputLimit)}`)
+      const result = use.text ?? (use.result !== undefined ? JSON.stringify(use.result) : undefined)
+      if (result !== undefined) parts.push(`result${use.isError ? ' ERROR' : ''}:\n${clipped(result, resultLimit)}`)
+    }
+    if (!message.toolUses.length) {
+      for (const result of message.toolResults ?? []) parts.push(`result ${result.tool_use_id}${result.isError ? ' ERROR' : ''}:\n${clipped(result.text, resultLimit)}`)
+    }
+    return parts.join('\n\n')
+  }).join('\n\n---\n\n')
+}
+
+/** Shrink only tool bulk; losing user intent to hit a budget is worse than engine fallback. */
+export function serializeTranscript(messages: readonly SessionMessage[], budget = 2400000): string | null {
+  if (!messages.length) return null
+  const full = render(messages, false)
+  if (full.length <= budget) return full
+  const tight = render(messages, true)
+  return tight.length <= budget ? tight : null
+}
+
+/** No handle: the engine builds this replacement from role, text and tool blocks. */
+export function compactResult(summary: string): SessionCompacted {
+  return { messages: [{ role: 'user', toolUses: [], text:
+    `Continuation record from the previous conversation:\n\n${summary.trim()}\n\nResume the pending work from this record. Do not repeat completed work or ask for information already recorded.` }] }
+}

package/dist/mod/hooks/handoff.ts

@@ -0,0 +1,43 @@
+import type { SessionMessage } from 'claude-code'
+import type { HandoffKind, Settings } from '../types'
+
+export const QUICK_PROMPT = `Prepare a concise resume note for a fresh coding chat, in the user's language, about forty lines of bullets. Use only this conversation; do not run tools. Record project, folder and branch if known, the goal, verified completed work, unfinished work and blockers, git state as last checked, decisions and failed approaches, permissions or resume details, and the highest-priority runnable next action. Mark actions requiring the user. Keep only current relevant state and point to files or specs instead of copying them. Exclude secrets, environment values and raw logs. Output only the note, without an introduction or farewell.`
+
+export const FULL_PROMPT = `Write a durable handoff for the next coding chat. First verify the working directory, git status, recent commits and whether changes are pushed; check open pull requests if gh is available. Rebuild project-root HANDOFF.md from the current facts, fewer than eighty lines, in the user's language. Include the goal, verified done and undone work, blockers, changed files, decisions and failed approaches, permissions, exact current state and a prioritized next action. Distinguish facts from unverified claims. Never expose secrets, environment values or raw logs. Finish with the saved file path and a concise status for the next chat.`
+
+export function wrapForNewChat(text: string, after: Settings['handoffAfter'], kind: HandoffKind, hasSkill: boolean): string {
+  const source = kind === 'full' && hasSkill ?
+    'First read the saved handoff files named below; if no file is named, read HANDOFF.md. The last answer alone may not contain the handoff.\n\n' : ''
+  const action = after === 'confirm' ?
+    'State the current status and proposed next action in two lines, then wait for my confirmation without starting work.' :
+    'Continue with the justified next action. If it needs my permission or input, explain what is needed and wait.'
+  return `${source}Resume context from the previous chat:\n\n${text.trim()}\n\n${action}`
+}
+
+export const ADVICE_SYSTEM = `Decide whether starting a fresh chat clearly helps this coding work. Recommend it only when completed work is followed by a different task, unrelated history is dead weight, the topic changed, or repeated failed approaches are going in circles. A long chat, high context usage, or an ordinary next step is not enough. When uncertain, do not recommend it. Output only JSON {"handoff":null} or {"handoff":"reason"}, using the user's language and at most eight words.`
+
+/** Cadence counts real eligible prompts, not tool steps, pings or judge requests. */
+export function adviceDue(count: number, percent: number): boolean {
+  return percent >= 30 && Number.isInteger(count) && count > 0 && count % 2 === 0
+}
+
+export function adviceInput(input: { messages: readonly SessionMessage[]; next: string; contextPercent: number; warm: boolean }): string {
+  const users = input.messages.filter(message => message.role === 'user' && message.text.trim())
+  const assistant = input.messages.findLast(message => message.role === 'assistant' && message.text.trim())
+  const trail = users.slice(-8, -1).map(message => message.text.replace(/\s+/g, ' ').slice(0, 160)).join('\n')
+  return [`Context: ${Math.round(input.contextPercent)}%; user messages: ${users.length}; cache: ${input.warm ? 'warm' : 'cold'}`,
+    `Initial request: ${users[0]?.text.slice(0, 500) ?? ''}`, `Earlier requests:\n${trail}`,
+    `Assistant tail: ${assistant?.text.slice(-700) ?? ''}`, `Next request: ${input.next.slice(0, 600)}`].join('\n\n')
+}
+
+export function parseAdvice(text: string): string | null {
+  const span = /\{[\s\S]*\}/.exec(text)?.[0]
+  if (!span) return null
+  try {
+    const value: unknown = JSON.parse(span)
+    if (!value || typeof value !== 'object' || !('handoff' in value)) return null
+    return typeof value.handoff === 'string' && value.handoff.trim() ? value.handoff.trim().slice(0, 70) : null
+  } catch {
+    return null
+  }
+}