tiergear 0.1.0

package/dist/core/judges/presets.js

@@ -0,0 +1,27 @@
+// All three speak TypeSafe's /v1/systemone contract; only where and how to reach them differs.
+export const JUDGE_PRESETS = {
+    jev: { baseUrl: 'https://api.typesafe.ai', model: 'jev-latest', keyEnv: 'TYPESAFE_API_KEY', keyRequired: true, firstTurnTimeoutMs: 2000, turnTimeoutMs: 1200 },
+    // Local models vary a lot by machine, so their budgets are wider.
+    laya: { baseUrl: 'http://localhost:11435', model: 'laya', keyEnv: 'OLLAYA_API_KEY', keyRequired: false, firstTurnTimeoutMs: 3000, turnTimeoutMs: 2500 },
+    kev: { baseUrl: 'http://localhost:8009', model: 'kev-latest', keyEnv: 'KEV_API_KEY', keyRequired: false, firstTurnTimeoutMs: 3000, turnTimeoutMs: 2000 },
+};
+export function isJudgeName(value) {
+    return value === 'jev' || value === 'laya' || value === 'kev';
+}
+// Prompts travel in the request, so plain http is only for a judge on this machine.
+export function isAllowedJudgeUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === 'https:')
+        return true;
+    return parsed.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
+}
+// A preset's key belongs to the preset's address; another address gets only a key set for it.
+export function presetKeyApplies(preset, baseUrl) {
+    return baseUrl.replace(/\/+$/, '') === preset.baseUrl.replace(/\/+$/, '');
+}

package/dist/core/judges/systemone.js

@@ -0,0 +1,85 @@
+import { guarded } from '../judge.js';
+import { TIER_ORDER, isTier } from '../tiers.js';
+const TIER_CRITERIA = {
+    trivial: 'A lookup or mechanical edit: read a value, rename, format, run one known command. No reasoning needed.',
+    quick: 'A small, clear change in one place with an obvious approach.',
+    standard: 'Ordinary engineering: implement or fix something with a clear spec across a few files.',
+    deep: 'Hard work: unclear cause, design decisions, many files, or high stakes such as production, money, credentials or data loss.',
+    max: 'The hardest problems: repeated failed attempts, debugging across systems, or architecture with lasting consequences.',
+};
+export function endpoint(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, '')}/v1/systemone`;
+}
+export function buildQuestions(withStuck) {
+    const questions = {
+        tier: {
+            type: 'choice',
+            instructions: 'Which tier of model and reasoning effort does the next step of this coding-agent session need? ' +
+                'Judge the work the next step requires within the whole task, not how short the latest message is.',
+            criteria: Object.fromEntries(TIER_ORDER.map((tier) => [tier, TIER_CRITERIA[tier]])),
+        },
+    };
+    if (withStuck) {
+        questions['stuck'] = {
+            type: 'noul',
+            instructions: 'Is the agent stuck on this task?',
+            criteria: {
+                true: 'The same approach keeps failing, or the user says it still does not work.',
+                false: 'Work is progressing, or it has just started.',
+            },
+        };
+    }
+    return questions;
+}
+function readTier(answer) {
+    if (!answer || typeof answer !== 'object')
+        return null;
+    const { choice, confidence } = answer;
+    if (!isTier(choice) || typeof confidence !== 'number' || !Number.isFinite(confidence))
+        return null;
+    return { tier: choice, confidence };
+}
+function readNoul(answer) {
+    if (!answer || typeof answer !== 'object')
+        return null;
+    const { noul } = answer;
+    return typeof noul === 'number' && Number.isFinite(noul) ? noul : null;
+}
+export function parseVerdict(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error('judge returned malformed JSON');
+    }
+    const answers = parsed?.answers;
+    if (!answers || typeof answers !== 'object')
+        throw new Error('judge response is missing answers');
+    const record = answers;
+    return { tier: readTier(record['tier']), stuck: readNoul(record['stuck']) };
+}
+// An answer is a few hundred bytes; anything far larger is not one, and parsing it would only cost time.
+export const MAX_RESPONSE_CHARS = 1_000_000;
+/** Jev, Laya (Ollaya) and Kev all serve this contract; a preset only changes the address, model and key. */
+export function createSystemOneJudge(options) {
+    return {
+        name: options.name,
+        async ask({ state, withStuck, timeoutMs }) {
+            if (options.keyRequired && !options.apiKey)
+                return { ok: false, reason: `no API key for ${options.name}` };
+            const headers = { 'content-type': 'application/json' };
+            if (options.apiKey)
+                headers['authorization'] = `Bearer ${options.apiKey}`;
+            const body = JSON.stringify({ model: options.model, state, questions: buildQuestions(withStuck) });
+            return guarded(async () => {
+                const response = await options.transport(endpoint(options.baseUrl), { method: 'POST', headers, body });
+                if (!response.ok)
+                    throw new Error(`${options.name} responded ${response.status}`);
+                if (response.text.length > MAX_RESPONSE_CHARS)
+                    throw new Error('judge response too large');
+                return parseVerdict(response.text);
+            }, options.sleep, timeoutMs);
+        },
+    };
+}

package/dist/core/log.js

@@ -0,0 +1,50 @@
+import { appliedText } from './decide.js';
+export const MAX_LOG_LINES = 1000;
+export function decisionsDir(home) {
+    return `${home}/.local/state/tiergear/decisions`;
+}
+export function decisionLogPath(home, name) {
+    return `${decisionsDir(home)}/${name.replace(/[^A-Za-z0-9._-]/g, '_')}.jsonl`;
+}
+export function appendLogLine(existing, line, maxLines = MAX_LOG_LINES) {
+    const lines = existing.split('\n').filter((l) => l.length > 0);
+    lines.push(line);
+    return `${lines.slice(-maxLines).join('\n')}\n`;
+}
+export function parseLogLines(text) {
+    const entries = [];
+    for (const line of text.split('\n')) {
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.at === 'number')
+                entries.push(parsed);
+        }
+        catch {
+            // A torn write leaves a partial line; skip it.
+        }
+    }
+    return entries;
+}
+function clockTime(at) {
+    const d = new Date(at);
+    return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+}
+function judgeText(entry) {
+    if (entry.outcome !== 'ok')
+        return entry.outcome;
+    const said = entry.confidence === null ? 'n/d' : entry.confidence.toFixed(2);
+    return `${entry.proposed === undefined ? '?' : (entry.proposed ?? '-')} ${said}`;
+}
+/** One line per decision, newest first: what the judge said, what tiergear did, and what ran. */
+export function recentDecisionLines(text, limit, time = clockTime) {
+    return parseLogLines(text)
+        .slice(-limit)
+        .reverse()
+        .map((e) => {
+        const ran = e.applied ? appliedText(e.applied) : 'session';
+        const who = e.phase === 'manual' ? 'manual' : `judge ${judgeText(e)}`;
+        return `${time(e.at)}  ${who} → ${e.change} ${e.tier ?? 'unset'} (${e.reason}) · ${ran}`;
+    });
+}

package/dist/core/state.js

@@ -0,0 +1,72 @@
+// Exchanges, not raw messages: a tool call is two messages, so a busy turn would fill any message window.
+export const RECENT_EXCHANGES = 3;
+// The reply the next prompt answers gets the most room, its end most of all, where a question sits.
+export const LAST_REPLY_CHARS = 1500;
+export const LAST_REPLY_HEAD_SHARE = 0.3;
+export const OLDER_TEXT_CHARS = 400;
+// The first prompt says less about the current work the longer a session runs.
+export const TASK_CHARS = 500;
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+export function abridge(text, max, headShare = 0.6) {
+    if (text.length <= max)
+        return text;
+    const head = Math.floor(max * headShare);
+    const tail = max - head;
+    return `${text.slice(0, head)} […${text.length - max} chars omitted…] ${text.slice(text.length - tail)}`;
+}
+export function countChangedFiles(messages) {
+    const paths = new Set();
+    for (const message of messages) {
+        for (const use of message.toolUses ?? []) {
+            if (!EDIT_TOOLS.has(use.tool))
+                continue;
+            const input = use.input;
+            const path = input?.file_path ?? input?.notebook_path;
+            if (typeof path === 'string')
+                paths.add(path);
+        }
+    }
+    return paths.size;
+}
+export function firstTurnState(prompt) {
+    return { task: abridge(prompt, 4000) };
+}
+// Each prompt with the assistant's last words before the next one, and the tools it used on the way.
+export function toExchanges(messages) {
+    const exchanges = [];
+    for (const message of messages) {
+        if (message.role === 'user') {
+            if (!message.isToolResult && message.text.trim())
+                exchanges.push({ prompt: message.text, reply: '', tools: [] });
+            continue;
+        }
+        if (exchanges.length === 0)
+            exchanges.push({ prompt: '', reply: '', tools: [] });
+        const current = exchanges[exchanges.length - 1];
+        if (message.text.trim())
+            current.reply = message.text;
+        for (const use of message.toolUses ?? [])
+            if (!current.tools.includes(use.tool))
+                current.tools.push(use.tool);
+    }
+    return exchanges;
+}
+function recentMessages(messages) {
+    const exchanges = toExchanges(messages).slice(-RECENT_EXCHANGES);
+    return exchanges.flatMap((exchange, i) => {
+        const isLast = i === exchanges.length - 1;
+        const reply = isLast ? abridge(exchange.reply, LAST_REPLY_CHARS, LAST_REPLY_HEAD_SHARE) : abridge(exchange.reply, OLDER_TEXT_CHARS);
+        const prompt = exchange.prompt ? [{ role: 'user', text: abridge(exchange.prompt, OLDER_TEXT_CHARS), tools: [] }] : [];
+        return [...prompt, { role: 'assistant', text: reply, tools: exchange.tools }];
+    });
+}
+// The task and the recent exchanges travel with every question, so a terse follow-up is judged in context.
+export function nextTurnState(input) {
+    return {
+        task: abridge(input.firstPrompt, TASK_CHARS),
+        recent: recentMessages(input.messages),
+        next_prompt: abridge(input.prompt, 2000),
+        stats: { files_changed: countChangedFiles(input.messages), repeated_failures: input.repeatedFailures },
+        current: { tier: input.tier, effort: input.effort },
+    };
+}

package/dist/core/status.js

@@ -0,0 +1,65 @@
+import { claudeModelId, isTier } from './tiers.js';
+export function statusDir(home) {
+    return `${home}/.local/state/tiergear/status`;
+}
+export function statusPath(home, session) {
+    return `${statusDir(home)}/${session.replace(/[^A-Za-z0-9._-]/g, '_')}.json`;
+}
+export function parseStatus(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const r = parsed;
+    const { session, tier, model, effort, paused, reason, line, updatedAt } = r;
+    if (typeof session !== 'string' || typeof reason !== 'string' || typeof line !== 'string' || typeof updatedAt !== 'number')
+        return null;
+    if ((tier !== null && !isTier(tier)) || (model !== null && typeof model !== 'string') || typeof paused !== 'boolean')
+        return null;
+    if (effort !== null && typeof effort !== 'string' && typeof effort !== 'number')
+        return null;
+    return { session, tier, model, effort, paused, reason, line, updatedAt };
+}
+export const STATUS_FIELDS = ['tier', 'state', 'model', 'effort'];
+export function isStatusField(value) {
+    return typeof value === 'string' && STATUS_FIELDS.includes(value);
+}
+// One value for a widget of its own; empty when not known, so the widget hides.
+export function statusField(status, field) {
+    if (field === 'state')
+        return status.paused ? 'paused' : 'auto';
+    const value = status[field];
+    return value === null ? '' : String(value);
+}
+// As Claude Code names a model: claude-opus-5-5 is "Opus 5.5"; anything else keeps its own name.
+function modelName(model) {
+    const match = /^claude-([a-z]+)-(\d+)-(\d+)$/.exec(claudeModelId(model));
+    return match ? `${match[1][0].toUpperCase()}${match[1].slice(1)} ${match[2]}.${match[3]}` : model;
+}
+// Placeholders: {tier} {model} {modelName} (as Claude Code names it) {effort} {state} (auto or paused) {line} (the band's text).
+export function formatStatus(status, template) {
+    if (template !== undefined) {
+        const values = {
+            tier: status.tier ?? 'unset',
+            model: status.model ?? '-',
+            modelName: status.model === null ? '-' : modelName(status.model),
+            effort: status.effort === null ? '-' : String(status.effort),
+            state: status.paused ? 'paused' : 'auto',
+            line: status.line,
+        };
+        const known = { tier: status.tier !== null, model: status.model !== null, modelName: status.model !== null, effort: status.effort !== null, state: true, line: true };
+        const keys = [...template.matchAll(/\{(tier|modelName|model|effort|state|line)\}/g)].map((m) => m[1]);
+        // A template with nothing known in it prints nothing, so its widget hides.
+        if (keys.length > 0 && keys.every((key) => !known[key]))
+            return '';
+        return template.replace(/\{(tier|modelName|model|effort|state|line)\}/g, (_, key) => values[key]);
+    }
+    const effort = status.effort === null ? null : String(status.effort);
+    const ran = status.model ? `${status.model}/${effort ?? '-'}` : effort;
+    return [status.paused ? 'paused' : status.tier, ran].filter((part) => part !== null).join(' · ');
+}

package/dist/core/tables.js

@@ -0,0 +1,85 @@
+import { claudeAlias, isEffort, isTier } from './tiers.js';
+function column(trivial, quick, standard, deep, max) {
+    return { trivial, quick, standard, deep, max };
+}
+export const DEFAULT_TABLES = {
+    claude: {
+        // Not haiku for trivial: auto mode does not run on it, so every command waits for approval.
+        // The haiku column stays so a bypass-permissions user can restore it with one models cell.
+        models: { trivial: 'sonnet', quick: 'sonnet', standard: 'sonnet', deep: 'opus', max: 'fable' },
+        effort: {
+            haiku: column(null, null, null, null, null),
+            sonnet: column('low', 'low', 'medium', 'high', 'max'),
+            opus: column('low', 'low', 'medium', 'xhigh', 'max'),
+            fable: column('low', 'low', 'medium', 'high', 'xhigh'),
+        },
+    },
+    codex: {
+        models: { trivial: 'gpt-5.6-luna', quick: 'gpt-5.6-terra', standard: 'gpt-5.6-terra', deep: 'gpt-5.6-terra', max: 'gpt-5.6-terra' },
+        effort: {
+            'gpt-5.6-luna': column('low', 'low', 'medium', 'high', 'high'),
+            'gpt-5.6-terra': column('low', 'low', 'medium', 'xhigh', 'max'),
+        },
+    },
+};
+export function effortFor(tables, harness, model, tier) {
+    const table = tables[harness];
+    const found = table.effort[model] ?? table.effort[claudeAlias(model)] ?? table.effort[table.models[tier]];
+    return found ? found[tier] : null;
+}
+export function firstTarget(tables, harness, tier) {
+    const model = tables[harness].models[tier];
+    return { model, effort: effortFor(tables, harness, model, tier) };
+}
+// A model id ends up in a launch command a shell reads, so only id characters pass (brackets as in `opus[1m]`).
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/[\]-]*$/;
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function mergeTables(base, override) {
+    if (!isObject(override))
+        return null;
+    const result = JSON.parse(JSON.stringify(base));
+    for (const [harness, value] of Object.entries(override)) {
+        if ((harness !== 'claude' && harness !== 'codex') || !isObject(value))
+            return null;
+        const target = result[harness];
+        const { models, effort } = value;
+        if (models !== undefined) {
+            if (!isObject(models))
+                return null;
+            for (const [tier, model] of Object.entries(models)) {
+                if (!isTier(tier) || typeof model !== 'string' || !MODEL_ID.test(model))
+                    return null;
+                target.models[tier] = model;
+            }
+        }
+        if (effort !== undefined) {
+            if (!isObject(effort))
+                return null;
+            for (const [model, cells] of Object.entries(effort)) {
+                if (!isObject(cells))
+                    return null;
+                const merged = { ...(target.effort[model] ?? column(null, null, null, null, null)) };
+                for (const [tier, level] of Object.entries(cells)) {
+                    if (!isTier(tier) || (level !== null && !isEffort(level)))
+                        return null;
+                    merged[tier] = level;
+                }
+                target.effort[model] = merged;
+            }
+        }
+    }
+    return result;
+}
+export function parseTablesFile(text) {
+    try {
+        return mergeTables(DEFAULT_TABLES, JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+export function tablesPath(home) {
+    return `${home}/.config/tiergear/tables.json`;
+}

package/dist/core/tiers.js

@@ -0,0 +1,53 @@
+export const TIER_ORDER = ['trivial', 'quick', 'standard', 'deep', 'max'];
+export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+// turn.step names the request's model by id; the CLI flags take aliases.
+export const CLAUDE_MODEL_IDS = {
+    haiku: 'claude-haiku-4-5',
+    sonnet: 'claude-sonnet-5-5',
+    opus: 'claude-opus-5-5',
+    fable: 'claude-fable-5-1',
+};
+export function claudeModelId(model) {
+    return CLAUDE_MODEL_IDS[model] ?? model;
+}
+// A dated (`claude-haiku-4-5-20251001`) or suffixed (`claude-opus-5-5[1m]`) id names the same model.
+export function claudeAlias(model) {
+    for (const [alias, id] of Object.entries(CLAUDE_MODEL_IDS)) {
+        if (model === id || model.startsWith(`${id}-`) || model.startsWith(`${id}[`))
+            return alias;
+    }
+    return model;
+}
+export function isTier(value) {
+    return typeof value === 'string' && TIER_ORDER.includes(value);
+}
+export function isEffort(value) {
+    return typeof value === 'string' && EFFORTS.includes(value);
+}
+export function tierRank(tier) {
+    return TIER_ORDER.indexOf(tier);
+}
+export function stepUp(tier) {
+    return TIER_ORDER[Math.min(tierRank(tier) + 1, TIER_ORDER.length - 1)];
+}
+export function stepDown(tier) {
+    return TIER_ORDER[Math.max(tierRank(tier) - 1, 0)];
+}
+export function maxTier(a, b) {
+    return b !== null && tierRank(b) > tierRank(a) ? b : a;
+}
+export function clampTier(tier, range) {
+    if (range.min && tierRank(tier) < tierRank(range.min))
+        return range.min;
+    if (range.max && tierRank(tier) > tierRank(range.max))
+        return range.max;
+    return tier;
+}
+export function launchCommand(harness, target) {
+    // Tables admit only id characters, so quoting is needed just to keep a shell from globbing `[1m]`.
+    const model = /^[A-Za-z0-9._:/-]+$/.test(target.model) ? target.model : `'${target.model}'`;
+    if (harness === 'claude') {
+        return target.effort ? `claude --model ${model} --effort ${target.effort}` : `claude --model ${model}`;
+    }
+    return target.effort ? `codex --model ${model} -c model_reasoning_effort="${target.effort}"` : `codex --model ${model}`;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "tiergear",
+  "version": "0.1.0",
+  "description": "Let a decision model pick the model and reasoning effort for Claude Code sessions and Orca workers",
+  "type": "module",
+  "license": "MIT",
+  "author": "jang2162",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jang2162/tiergear.git"
+  },
+  "homepage": "https://github.com/jang2162/tiergear#readme",
+  "bugs": "https://github.com/jang2162/tiergear/issues",
+  "keywords": ["claude-code", "claude", "plugin", "reasoning-effort", "model-routing", "orca"],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "tiergear": "dist/cli/bin.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.hooks.json",
+    "validate:plugin": "claude plugin validate ."
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3"
+  }
+}