clauderipple 0.8.10 → 0.9.1

package/dist/mod/hooks/session.ts

@@ -0,0 +1,62 @@
+import type { SessionContextUsage, SessionRateLimit } from 'claude-code'
+import type { CacheMemo, Hot } from '../types'
+
+export function hottest(rateLimits: readonly SessionRateLimit[]): Hot | null {
+  const eligible = rateLimits.filter(limit => ['five_hour', 'seven_day'].includes(limit.kind) && limit.percentUsed >= 80)
+  const limit = eligible.reduce<SessionRateLimit | undefined>((hot, next) => !hot || next.percentUsed > hot.percentUsed ? next : hot, undefined)
+  return limit ? { kind: limit.kind, percent: limit.percentUsed, ...(limit.resetsAt ? { resetsAt: limit.resetsAt } : {}) } : null
+}
+
+/**
+ * The reset is read in the person's own clock: `offsetMinutes` is `Date#getTimezoneOffset` (minutes
+ * behind UTC), passed in so tests do not depend on the machine's zone.
+ */
+export function limitLabel(hot: Hot, now: number, offsetMinutes = new Date(now).getTimezoneOffset()): string {
+  const label = `${hot.kind === 'five_hour' ? '5h' : 'weekly'} ${Math.round(hot.percent)}%`
+  const reset = hot.resetsAt ? Date.parse(hot.resetsAt) : NaN
+  if (!Number.isFinite(reset)) return label
+  const date = new Date(reset - offsetMinutes * 60000)
+  const time = `${String(date.getUTCHours()).padStart(2, '0')}:${String(date.getUTCMinutes()).padStart(2, '0')}`
+  const day = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'][date.getUTCDay()]
+  return `${label} · resets ${reset - now < 20 * 3600000 ? time : `${day} ${time}`}`
+}
+
+export function saveUntil(hot: Hot | null, now: number): number {
+  const reset = hot?.resetsAt ? Date.parse(hot.resetsAt) : NaN
+  return Number.isFinite(reset) && reset > now ? reset : now + 5 * 3600000
+}
+
+/** The context percent when it is at or past `swampAt`, else null. */
+export function swamped(context: SessionContextUsage | null, swampAt: number): number | null {
+  if (!context || context.tokens === undefined) return null
+  const percent = context.percent ?? (context.window > 0 ? context.tokens / context.window * 100 : undefined)
+  return percent !== undefined && percent >= swampAt ? percent : null
+}
+
+export function coldAlert(memo: CacheMemo | null, contextTokens: number, now: number, hidden: boolean): boolean {
+  return !hidden && memo !== null && memo.expiresAt <= now && contextTokens >= 150000
+}
+
+export function hotAlert(hot: Hot | null, hidden: number | null): boolean {
+  return hot !== null && hot.percent >= 80 && (hidden === null || hot.percent >= hidden + 10)
+}
+
+/**
+ * The heavy-context band shows once per crossing: seen (or put off) at `hidden` percent, it waits
+ * until the context grows SWAMP_STEP points more. A hidden value over 100 is a token count kept by
+ * an older mod and is ignored.
+ */
+export const SWAMP_STEP = 15
+export function swampAlert(percent: number | null, hidden: number | null): boolean {
+  return percent !== null && (hidden === null || hidden > 100 || percent >= hidden + SWAMP_STEP)
+}
+
+/** Rendering consumes eligibility, keeping dismissal and idle decisions outside drawing code. */
+export function bandPriority(state: {
+  panel?: 'settings' | 'compact' | 'handoff' | 'setup' | null
+  judgeDown?: boolean; hot?: boolean; result?: boolean; cold?: boolean; swamp?: boolean
+}): 'settings' | 'compact' | 'handoff' | 'setup' | 'judgeDown' | 'hot' | 'result' | 'cold' | 'swamp' | 'dashboard' {
+  if (state.panel) return state.panel
+  for (const band of ['judgeDown', 'hot', 'result', 'cold', 'swamp'] as const) if (state[band]) return band
+  return 'dashboard'
+}

package/dist/mod/hooks/settings.js

@@ -0,0 +1,342 @@
+/** Bump whenever a writer's normalization can lose another format's fields. */
+export const MOD_SETTINGS_SCHEMA_VERSION = 1;
+export const DOMAINS = ['general', 'design', 'frontend', 'backend', 'infra', 'data', 'test', 'docs', 'research'];
+export const LEVELS = ['light', 'standard', 'deep'];
+export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+/** The worker ladder, bottom to top (docs/specs/2026-10-11-worker-ladder.md). */
+export const RUNGS = ['light', 'standard', 'hard', 'plan'];
+/** The rung each judged level lands on before kind and confidence move it. */
+export const LEVEL_RUNG = { light: 'light', standard: 'standard', deep: 'hard' };
+/** A rung's effort when nothing else says one: a stored rung without one, a migrated pin. */
+export const RUNG_EFFORT = { light: 'low', standard: 'medium', hard: 'high', plan: 'high' };
+const claude = (model, effort) => ({ target: { agent: 'general-purpose', model }, effort });
+export const DEFAULTS = {
+    effortAuto: true, judge: 'haiku', judgeModel: 'deepseek-v4.1-flash', jevSource: 'typesafe',
+    bias: 0, floor: 'low', ceiling: 'max', agentAuto: 'auto',
+    rules: {
+        // The spec's "Claude + GPT" example; a rung whose worker is missing moves up and says so.
+        // Only the general rule: the four workers replaced the per-field rules (2026-10-12).
+        general: { mode: 'ladder', rungs: {
+                light: [{ target: { agent: 'deepseek-v4-1-flash' }, effort: 'max' }], standard: [{ target: { agent: 'gpt-6-1-sol' }, effort: 'medium' }],
+                hard: [{ target: { agent: 'gpt-6-astra' }, effort: 'high' }], plan: [claude('opus', 'high')],
+            } },
+    },
+    allow: [], modes: [],
+    providers: {},
+    fallback: { agent: 'general-purpose', model: 'sonnet' },
+    keepWarm: false, keepWarmHours: 2, keepWarmMinTokens: 30000,
+    compactWith: 'haiku', handoffSkill: '', handoffAfter: 'continue', handoffButton: 'advised',
+    swampAt: 50, swampAlert: false, layout: 'dashboard', appearance: 'auto', language: 'auto', hide: ['reason'], extras: [], setupDone: false,
+};
+/** Band chips that show only when switched on in Look. */
+export const EXTRAS = ['context', 'limits'];
+/**
+ * Claude's own models as workers: the built-in general-purpose agent run on the model, `model` its
+ * current id. The key is what the allow-list stores.
+ */
+export const CLAUDE_WORKERS = [
+    { name: 'general-purpose:haiku', model: 'claude-haiku-5-5', provider: 'anthropic', target: { agent: 'general-purpose', model: 'haiku' } },
+    { name: 'general-purpose:sonnet', model: 'claude-sonnet-5-5', provider: 'anthropic', target: { agent: 'general-purpose', model: 'sonnet' } },
+    { name: 'general-purpose:opus', model: 'claude-opus-5-5', provider: 'anthropic', target: { agent: 'general-purpose', model: 'opus' } },
+    { name: 'general-purpose:fable', model: 'claude-fable-5-1', provider: 'anthropic', target: { agent: 'general-purpose', model: 'fable' } },
+];
+/** The allow-list key of a target: the agent's name, or `general-purpose:<model>` for Claude's own. */
+export function candidateKey(target) {
+    return target.model ? target.agent + ':' + target.model : target.agent;
+}
+function object(raw) {
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+}
+function names(raw) {
+    return Array.isArray(raw) ? [...new Set(raw.filter((v) => typeof v === 'string' && !!v.trim()).map(v => v.trim()))] : [];
+}
+function target(raw, fallback) {
+    const value = object(raw);
+    const agent = typeof value.agent === 'string' && value.agent.trim() ? value.agent.trim() : fallback?.agent;
+    const model = typeof value.model === 'string' && value.model.trim() ? value.model.trim() : fallback?.model;
+    return agent ? { agent, ...(model ? { model } : {}) } : undefined;
+}
+function calibration(value) {
+    const out = {};
+    if ([-2, -1, 0, 1, 2].includes(Number(value.effortOffset)) && typeof value.effortOffset === 'number')
+        out.effortOffset = value.effortOffset;
+    for (const field of ['floor', 'ceiling'])
+        if (EFFORTS.includes(value[field]))
+            out[field] = value[field];
+    return out;
+}
+function copy(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function sameTarget(a, b) {
+    return !!a && !!b && a.agent === b.agent && a.model === b.model;
+}
+/** An effort moved by calibration steps, then held between floor and ceiling (the floor wins). */
+function calibrated(effort, cal) {
+    const min = EFFORTS.indexOf(cal.floor ?? 'low');
+    const max = Math.max(min, EFFORTS.indexOf(cal.ceiling ?? 'max'));
+    const shifted = Math.max(0, Math.min(4, EFFORTS.indexOf(effort) + (cal.effortOffset ?? 0)));
+    return EFFORTS[Math.max(min, Math.min(max, shifted))];
+}
+/** One effort step up, max staying max. */
+export function effortUp(effort) {
+    return EFFORTS[Math.min(4, EFFORTS.indexOf(effort) + 1)];
+}
+function step(raw, rung) {
+    const v = object(raw);
+    const chosen = target(v.target);
+    if (!chosen)
+        return undefined;
+    // A rung's backup model is dropped on load: the four workers have none (the next one up stands in).
+    return { target: chosen, effort: EFFORTS.includes(v.effort) ? v.effort : RUNG_EFFORT[rung] };
+}
+/** The effort a migrated rung starts at: the default ladder's when it runs the same model there. */
+function migratedEffort(rung, chosen) {
+    const own = DEFAULTS.rules.general.rungs[rung]?.[0];
+    return own && sameTarget(own.target, chosen) ? own.effort : RUNG_EFFORT[rung];
+}
+/**
+ * A pin stored before 2026-10-11 as a ladder: light/standard/deep become Light/Standard/Hard, a
+ * missing level takes the nearest one above (as the pin climbed) or else below, each rung's effort
+ * is its default calibrated as the pin was, and Plan is Hard's model one effort higher.
+ */
+export function ladderFromPin(targets, cal) {
+    const known = LEVELS.filter(level => targets[level]);
+    if (!known.length)
+        return copy(DEFAULTS.rules.general);
+    const rungs = {};
+    LEVELS.forEach((level, at) => {
+        const above = LEVELS.slice(at).find(l => targets[l]);
+        const chosen = targets[above ?? [...LEVELS.slice(0, at)].reverse().find(l => targets[l])];
+        const rung = LEVEL_RUNG[level];
+        rungs[rung] = { target: { ...chosen }, effort: calibrated(migratedEffort(rung, chosen), cal) };
+    });
+    rungs.plan = { target: { ...rungs.hard.target }, effort: effortUp(rungs.hard.effort) };
+    return { mode: 'ladder', rungs: ladderRungs(rungs) };
+}
+/** Single steps from older saves become one-item lists; malformed items are dropped in place. */
+function ladderRungs(raw) {
+    const source = object(raw);
+    const rungs = {};
+    for (const rung of RUNGS) {
+        const items = Array.isArray(source[rung]) ? source[rung] : [source[rung]];
+        const parsed = items.flatMap(item => { const value = step(item, rung); return value ? [value] : []; });
+        if (parsed.length)
+            rungs[rung] = parsed;
+    }
+    return rungs;
+}
+/**
+ * The one rule left, the general ladder (the four workers). A ladder keeps its rungs; a pin from
+ * before the ladder becomes one; Auto (experimental, removed 2026-10-12) becomes a ladder with no
+ * rungs set, which the router fills from the ticked models (`fillLadder`). Field rules are gone.
+ */
+function generalRule(raw) {
+    const v = object(raw);
+    if (v.mode === 'ladder')
+        return { mode: 'ladder', rungs: ladderRungs(v.rungs) };
+    if (v.mode === 'auto')
+        return { mode: 'ladder', rungs: {} };
+    if (v.mode === 'pin') {
+        const source = object(v.targets);
+        const targets = {};
+        for (const level of LEVELS) {
+            const parsed = target(source[level]);
+            if (parsed)
+                targets[level] = parsed;
+        }
+        return ladderFromPin(targets, calibration(v));
+    }
+    return copy(DEFAULTS.rules.general);
+}
+/**
+ * Auto's allow-list names worker agents. Settings saved before 2026-10-10 named providers there;
+ * with the worker list known, a provider name becomes that provider's workers (names it does not
+ * know are kept: a worker may be missing only for now).
+ */
+export function migrateAllow(allow, workers) {
+    const agents = new Set(workers.map(w => w.name));
+    return [...new Set(allow.flatMap(entry => agents.has(entry) || !workers.some(w => w.provider === entry) ? [entry] : workers.filter(w => w.provider === entry).map(w => w.name)))];
+}
+/** The workers switched on by an allow-list; empty means every worker. */
+export function allowedWorkers(allow, workers) {
+    if (!allow.length)
+        return workers.map(w => w.name);
+    const on = new Set(migrateAllow(allow, workers));
+    return workers.filter(w => on.has(w.name)).map(w => w.name);
+}
+/** Switches one worker; every worker on again is stored as [], and the last one cannot go off. */
+export function toggleAllow(allow, name, workers) {
+    const on = allowedWorkers(allow, workers);
+    const next = on.includes(name) ? on.filter(n => n !== name) : workers.filter(w => w.name === name || on.includes(w.name)).map(w => w.name);
+    if (!next.length)
+        return [...allow];
+    return next.length === workers.length ? [] : next;
+}
+/**
+ * Whether a stored model is ticked: its key (an agent name, or `general-purpose:<model>`) or, for
+ * settings from before 2026-10-10, its provider is listed; an empty list ticks every model.
+ */
+export function isAllowed(key, provider, allow) {
+    return !allow.length || allow.includes(key) || allow.includes(provider);
+}
+/** The design ladder every save stored until 2026-10-12: Claude, Sonnet then Opus. */
+const RETIRED_DESIGN = JSON.stringify([claude('sonnet', 'medium'), claude('sonnet', 'high'), claude('opus', 'high'), claude('opus', 'high')].map(s => [s.target.agent, s.target.model, s.effort]));
+/**
+ * Whether stored settings still carry what the four workers replaced: Auto (experimental), or a
+ * field rule that is not the design ladder every save used to store. The dashboard says so once.
+ */
+export function hadRetiredRouting(raw) {
+    const rules = object(object(raw).rules);
+    if (object(rules.general).mode === 'auto')
+        return true;
+    return DOMAINS.some(domain => {
+        if (domain === 'general')
+            return false;
+        const stored = object(rules[domain]);
+        if (stored.mode === undefined || stored.mode === 'inherit')
+            return false;
+        if (domain !== 'design' || stored.mode !== 'ladder')
+            return true;
+        const rungs = ladderRungs(stored.rungs);
+        return JSON.stringify(RUNGS.map(rung => { const s = rungs[rung]?.[0]; return s ? [s.target.agent, s.target.model, s.effort] : null; })) !== RETIRED_DESIGN;
+    });
+}
+/** How long a mode's name may be: it shows in the band. */
+export const MODE_NAME_MAX = 40;
+/** How many modes are kept. */
+export const MODES_MAX = 20;
+/** How long a mode's reset provider name may be. */
+const PROVIDER_NAME_MAX = 64;
+/**
+ * A mode's end: a time, one provider's next quota reset, or none. Until 2026-10-12 `'reset'` meant
+ * any used provider's; it becomes the first that could have offered it, ChatGPT then Claude. Settings
+ * do not carry a worker's provider, and ChatGPT is the only worker provider with a known reset, so
+ * any worker that is not Claude's own stands for ChatGPT.
+ */
+function modeUntil(raw, rungs) {
+    if (typeof raw === 'number')
+        return Number.isFinite(raw) && raw > 0 ? raw : 'none';
+    if (raw === 'reset')
+        return { reset: Object.values(rungs).some(steps => steps?.some(step => step.target.agent !== 'general-purpose')) ? 'chatgpt' : 'anthropic' };
+    const reset = object(raw).reset;
+    return typeof reset === 'string' && reset.trim() ? { reset: reset.trim().slice(0, PROVIDER_NAME_MAX) } : 'none';
+}
+/**
+ * Saved worker sets. Old prefer/avoid modes copy the base ladder on load, dropping their policy.
+ * Every entry owns its lists: later base edits cannot mutate a saved mode.
+ */
+export function normalizeModes(raw, base = DEFAULTS.rules.general.rungs) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const v = object(entry);
+        const id = typeof v.id === 'string' ? v.id.trim().slice(0, 64) : '';
+        const name = typeof v.name === 'string' ? v.name.trim().slice(0, MODE_NAME_MAX) : '';
+        if (!id || !name || out.some(m => m.id === id))
+            continue;
+        const rungs = ladderRungs(v.rungs === undefined ? base : v.rungs);
+        out.push({ id, name, rungs, delegation: v.delegation === 'eager' ? 'eager' : 'normal', until: modeUntil(v.until, rungs) });
+        if (out.length === MODES_MAX)
+            break;
+    }
+    return out;
+}
+/** The general pin every install had before the ladder: what stored `tiers` filled in. */
+const LEGACY_GENERAL = { light: { agent: 'deepseek-v4-1-flash' }, standard: { agent: 'gpt-6-1-sol' }, deep: { agent: 'gpt-6-astra' } };
+/**
+ * Persisted settings may be old; migrate tiers and pins once and never alias nested default data.
+ * Only the general ladder survives: Auto becomes a ladder with no rungs set (its candidates become
+ * the ticked models); field rules and Auto's own fields (preference, autoFloors, autoTieBand) are
+ * dropped. With `workers`, provider names in an allow-list become those providers' workers.
+ */
+export function normalizeSettings(raw, workers) {
+    const value = object(raw);
+    const stored = object(value.rules);
+    const rules = { general: generalRule(stored.general) };
+    const old = object(value.tiers);
+    if (!Object.hasOwn(stored, 'general') && Object.keys(old).length) {
+        const targets = copy(LEGACY_GENERAL);
+        for (const level of LEVELS) {
+            const parsed = target(old[level]);
+            if (parsed)
+                targets[level] = parsed;
+        }
+        rules.general = ladderFromPin(targets, {});
+    }
+    const ticked = names(Array.isArray(value.allow) ? value.allow : object(stored.general).mode === 'auto' ? object(stored.general).allow : []);
+    const result = { ...DEFAULTS, rules, allow: workers?.length ? migrateAllow(ticked, workers) : ticked, providers: {}, hide: [...DEFAULTS.hide], extras: [...DEFAULTS.extras], fallback: { ...DEFAULTS.fallback } };
+    for (const [name, enabled] of Object.entries(object(value.providers)))
+        if (typeof enabled === 'boolean')
+            result.providers[name] = enabled;
+    for (const key of ['effortAuto', 'keepWarm', 'setupDone', 'swampAlert'])
+        if (typeof value[key] === 'boolean')
+            result[key] = value[key];
+    if (Array.isArray(value.extras))
+        result.extras = [...new Set(value.extras.filter((part) => typeof part === 'string' && EXTRAS.includes(part)))];
+    const choices = {
+        judge: ['haiku', 'jev', 'model'], jevSource: ['typesafe', 'zen'], bias: [-2, -1, 0, 1, 2], floor: EFFORTS,
+        ceiling: EFFORTS, agentAuto: ['off', 'auto', 'all'], keepWarmHours: [1, 2, 4, 8], compactWith: ['haiku', 'session'],
+        handoffAfter: ['continue', 'confirm', 'copy'], handoffButton: ['advised', 'always'], layout: ['dashboard', 'minimal'],
+        appearance: ['auto', 'dark', 'light'], language: ['auto', 'ko', 'en', 'zh', 'ja', 'es', 'pt'],
+    };
+    for (const key of Object.keys(choices))
+        if (choices[key].includes(value[key]))
+            Object.assign(result, { [key]: value[key] });
+    if (typeof value.judgeModel === 'string' && value.judgeModel.trim())
+        result.judgeModel = value.judgeModel.trim();
+    if (typeof value.handoffSkill === 'string')
+        result.handoffSkill = value.handoffSkill.trim().replace(/^\//, '');
+    if (typeof value.keepWarmMinTokens === 'number' && Number.isFinite(value.keepWarmMinTokens) && value.keepWarmMinTokens >= 0)
+        result.keepWarmMinTokens = value.keepWarmMinTokens;
+    if (typeof value.swampAt === 'number' && Number.isFinite(value.swampAt) && value.swampAt >= 0 && value.swampAt <= 100)
+        result.swampAt = value.swampAt;
+    if (Array.isArray(value.hide))
+        result.hide = [...new Set(value.hide.filter((part) => typeof part === 'string' && ['timer', 'reason', 'route', 'limits'].includes(part)))];
+    result.fallback = target(value.fallback, DEFAULTS.fallback);
+    result.modes = normalizeModes(value.modes, rules.general.rungs);
+    // An active mode must be one of the modes; its start time stays only with it.
+    if (typeof value.activeMode === 'string' && result.modes.some(m => m.id === value.activeMode)) {
+        result.activeMode = value.activeMode;
+        if (typeof value.activeSince === 'number' && Number.isFinite(value.activeSince) && value.activeSince > 0)
+            result.activeSince = value.activeSince;
+    }
+    return result;
+}
+/** Preserve unrelated remote edits, including sibling domains and provider switches. */
+export function settingsChanges(before, after) {
+    function diff(a, b, path) {
+        if (JSON.stringify(a) === JSON.stringify(b))
+            return [];
+        if (b === undefined)
+            return [{ path, remove: true }];
+        if (a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+            const left = object(a), right = object(b);
+            // Changing a discriminated rule replaces it, rather than retaining the old mode's fields.
+            if (left.mode === right.mode)
+                return [...new Set([...Object.keys(left), ...Object.keys(right)])].flatMap(key => diff(left[key], right[key], [...path, key]));
+        }
+        return [{ path, value: b }];
+    }
+    return diff(before, after, []);
+}
+export function applySettingsChanges(base, changes) {
+    const result = object(normalizeSettings(base));
+    for (const change of changes) {
+        let parent = result;
+        for (const key of change.path.slice(0, -1)) {
+            const child = object(parent[key]);
+            parent[key] = child;
+            parent = child;
+        }
+        const key = change.path.at(-1);
+        if (key === undefined)
+            continue;
+        if (change.remove)
+            delete parent[key];
+        else
+            parent[key] = change.value;
+    }
+    return normalizeSettings(result);
+}