@tianmucreations/jeeves 0.2.1 → 0.3.1

package/LICENSE

@@ -1,21 +1,41 @@
-MIT License
+Jeeves Licence
+Copyright (c) 2026 Tianmu Creations. All rights reserved.
 
-Copyright (c) 2026 tianmucreations
+This licence applies to Jeeves version 0.3.1 and every later version. Versions
+0.3.0 and earlier were released under the MIT licence, which still applies to
+those versions.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+1. YOU MAY
+   - Install Jeeves and use it free of charge, for personal use and for work,
+     on as many of your own computers as you like.
+   - Read the source code on GitHub.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+2. YOU MAY NOT, without written permission from Tianmu Creations
+   - copy Jeeves, or any part of its source code, except as needed to install
+     and run it;
+   - change, adapt, translate, or build other software from Jeeves or its
+     source code;
+   - merge Jeeves, or any part of it, into other software;
+   - publish, share, distribute, host, or make Jeeves available to others,
+     changed or unchanged, except by pointing them to the official copies on
+     npm (npmjs.com/package/@tianmucreations/jeeves) and GitHub;
+   - sublicense, rent, lease, lend, or sell Jeeves or access to it; or
+   - remove or change this licence or any copyright notice.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+3. OTHER PEOPLE'S WORK
+   Jeeves uses add-ons made by others, which are installed alongside it and keep
+   their own licences. Its built-in list of AI models and prices comes from
+   models.dev (MIT licence).
+
+4. NO WARRANTY
+   Jeeves is provided "as is", without any warranty of any kind. Jeeves asks
+   before changing your computer and keeps backups for /undo, but you are
+   responsible for what you approve and for the costs of the AI services you
+   connect it to. To the fullest extent the law allows, Tianmu Creations is not
+   liable for any loss or damage arising from using Jeeves.
+
+5. ENDING
+   This licence ends automatically if you break it. When it ends you must stop
+   using Jeeves and delete your copies.
+
+Questions or permission requests: https://tianmucreations.com

package/README.md

@@ -1,32 +1,96 @@
 # Jeeves
 
-A plain-English terminal assistant: describe what you need in ordinary words and it reads files, writes files, lists folders, and runs commands for you - asking permission before anything that changes your computer.
+**Your personal assistant in the terminal — built for non-coders and coders alike. Say what you need in plain English; Jeeves does the work, carefully, and tells you what it cost.**
 
-## Platforms
+Jeeves reads and writes your files, tidies folders, builds web pages, fixes programs and checks facts on the web — all from one calm window, in ordinary language. He asks before changing anything, can put things back with `/undo`, and keeps an eye on your costs. No commands to learn, no settings to fiddle with — and if you do code, every model and every detail is there when you want it.
+
+```
+npm install -g @tianmucreations/jeeves
+jeeves
+```
+
+Needs [Node.js](https://nodejs.org) 22.12 or newer, and a key from an AI service — one [OpenRouter](https://openrouter.ai/settings/keys) key is all it takes.
+
+---
+
+## What you can ask him
+
+- "Write a polite letter to my landlord about the broken boiler and save it as letter.txt."
+- "Tidy my Downloads folder: pictures in one place, documents in another, spreadsheets in a third."
+- "Make a one-page website for my bakery with our opening hours and prices."
+- "From hours.csv, make an invoice for my client Brightside, with a total at the bottom."
+- "Our phone number changed — update it everywhere on the website, however it's written."
+- "What's the latest version of Node.js?" — he looks it up and tells you where he found it.
+
+## Why people choose Jeeves
+
+**Built for people who don't code.** Every screen is a list you move through with the arrow keys and Enter. Open a recent project or create a new one from a list — no typing folder locations, no jargon, no hidden shortcuts. Errors come in plain English ("OpenAI didn't accept the key — type /keys to check or replace it"), never as codes.
+
+**A butler, not a chatbot.** Jeeves is polite, unflappable and discreet, in the tradition of P.G. Wodehouse — and he calls you whatever you like (he asks on first launch; `/address` changes it). He answers questions directly, gets on with jobs when asked, and says plainly when something is done.
+
+**Auto: the right model, without thinking about it.** Choose Auto and Jeeves works with a fast, inexpensive model, calls in an expert model when a job gets hard, and has the expert double-check finished programs and documents before telling you they're done. The expert must show a concrete example of any problem, and Jeeves must see the problem for himself before changing anything, so good work is never "fixed" into bad work. If the job still proves difficult, he asks before using the strongest (and dearest) model.
+
+**He doesn't guess.** Facts about the outside world are looked up on the web, read from the most official page, and given with their source. Before building something new, he checks what already exists and shows you a short research note: use an existing tool, adapt one (licence permitting), or build new — and why. If the same problem happens twice, he researches the cause instead of patching blindly.
 
-Designed and built for **macOS, Windows, and Linux** from a single codebase.
+**Safe to say yes to.** Anything that changes your computer asks first — or answer **a** once to always allow changes inside that project folder (`/ask` turns asking back on). Before any change in your project folder he quietly takes a backup, so `/undo` puts the folder back — changed and deleted files return, new ones disappear. Changes outside the folder always ask, with a warning, because they can't be undone.
 
-- macOS is fully verified.
-- Windows and Linux will be verified on those machines after the MVP, with any fixes applied to this same codebase - no platform forks.
+**Type while he works.** Your message box grows as you type, and anything you send while Jeeves is busy waits its turn and goes as soon as he finishes. Your own messages sit on a soft grey band, so they're easy to find when you scroll back.
 
-## Quick start (local development)
+**Honest about costs.** A daily spending limit (you choose it; $3 to start) stops and asks before going over, and a long job checks in every 50 cents. Nothing is spent without you seeing it — and it can cost nothing at all: OpenRouter's free models, or models running on your own computer with Ollama.
 
-1. Install Node.js 20 or later.
-2. `npm install`
-3. `npm run dev`
+**Your keys stay private.** Keys are kept in your computer's own secure keychain, never in a plain file.
 
-On first launch you are asked for an OpenRouter API key, which is stored securely in your operating system's credential store (macOS Keychain, Windows Credential Vault, Linux Secret Service) - never in a plain file.
+**See from across the room whether he's finished.** A traffic light in the top right of the window pulses green while Jeeves is working, turns amber when he needs your OK, and shows red when he's done and waiting for you. The same status appears in the Terminal tab's title, so you can see it from another app — and on a Mac a notification tells you when a long job has finished.
 
-## Keyboard
+**An information bar that only speaks when it matters.** Along the bottom: the model at work (in Auto, which one is working right now), what today has cost against your limit, and — with OpenRouter — what's left on your account. Warnings — credit running low, the limit reached — appear only when something needs you.
+
+**Every step visible, never noisy.** Each action is one tidy line that updates in place — "✓ Read letter.txt", "✓ Wrote 1 file" — and research notes are shown in full. The model's thinking stays out of the way unless you ask for it (`Ctrl+R`).
+
+## For people who do code
+
+- **Any model, your choice.** Turn Auto off and pick from 400+ models through OpenRouter, with search, favourites, prices, memory sizes and a free-models list.
+- **Direct connections** with your own key: Anthropic, OpenAI, Google, xAI (Grok), Mistral and Groq — each company's live model list, with costs worked out from its price list. Plus **any OpenAI-compatible service** (paste its address and key), **Ollama** for models on your own machine, and **Z.ai's GLM Coding Plan** at a flat monthly price.
+- **Prompt caching** where it matters: sticky routing on OpenRouter, and cache markers on Anthropic, so long conversations cost a fraction of the fresh price.
+- **Runs your real tools** — tests, builds, git — and reads the results before claiming a job is done.
+- **Tested on every change** on macOS, Windows and Linux.
+
+## Where Auto is available
+
+| Service | Auto | Everyday model + expert |
+|---|---|---|
+| OpenRouter | Yes | DeepSeek V4 Flash + Claude Sonnet 5 |
+| OpenAI (your key) | Yes | GPT-5.6 Luna + GPT-5.6 Terra |
+| Google (your key) | Yes | Gemini 3.8 Flash + Gemini 3.5 Flash |
+| Anthropic, xAI, Groq, Mistral, Z.ai, Ollama, others | Not yet | Pick any model yourself |
+
+Auto is offered only where a pairing has been measured doing everyday and difficult jobs well — Jeeves's name is on every result. Everywhere else, the model list says so in one line.
+
+## Everyday commands
+
+| Type | What it does |
+|---|---|
+| `/model` | Choose a service and a model (or Auto), and set your daily limit |
+| `/keys` | Add, replace or remove keys |
+| `/undo` | Put the project folder back to before your last request |
+| `/ask` | Ask before every change in this project folder again (after choosing "always allow") |
+| `/clear` | Start a fresh conversation |
+| `/address` | Change how Jeeves addresses you |
+| `/verbose` | Show the technical details as well |
+| `/help` | See everything in plain English |
+| `/exit` | Leave, with your terminal exactly as it was |
+
+Arrow keys and the trackpad scroll the conversation; `Page Up` / `Page Down` jump a screen; `End` returns to the newest. `Ctrl+R` shows the model's reasoning for the last answer.
+
+## Platforms
 
-Everything is visible on screen: arrow keys move, Enter selects, Esc goes back. `Tab` zooms a footer metric. `Ctrl+R` reveals the model's last reasoning. Slash commands: `/model`, `/keys`, `/verbose`.
+- **macOS** — fully tried and used every day.
+- **Windows and Linux** — every change is built and tested on both automatically; hands-on use on those machines is coming.
 
-Jeeves takes over the whole terminal window (the same way vim does). The shell's own scrollback is unavailable while it runs, so the up and down arrows scroll the conversation instead - `Page Up` / `Page Down` jump a whole screen. When you quit, the terminal returns exactly as it was.
+## Coming
 
-## Providers
+- Hands-on checks on Windows and Linux.
+- Auto for more services, as each is proven.
 
-- **OpenRouter (default).** One key unlocks 400+ models from every major provider. Get a key at [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys). Repeat conversation context is cached (sticky routing), so long conversations cost a fraction of the fresh-token price.
-- **Z.ai — GLM Coding Plan.** A flat-rate option for heavy daily use: from $18/month, no per-token billing. Z.ai's endpoint speaks the Anthropic protocol and Jeeves connects to it directly. To use it: subscribe at [z.ai](https://z.ai) if you want the plan, copy your Z.ai API key, then in Jeeves type `/keys`, choose Z.ai, and paste the key. Pick Z.ai in `/model` and choose a GLM model (for example GLM-5.3). Subscribing is optional - Jeeves works fine with OpenRouter alone; this is simply a money-saving option for daily drivers.
-- **Ollama.** Local models, no key needed. Start the Ollama app first.
+## Licence
 
-API keys are stored in your operating system's credential store - never in a plain file.
+Free to use, for personal use and for work. All rights reserved — see [LICENSE](LICENSE): you may not copy, change, share or sell Jeeves. Versions up to 0.3.0 were released under the MIT licence. Made by [Tianmu Creations](https://tianmucreations.com). More about Jeeves at [tianmucreations.com/jeeves](https://tianmucreations.com/jeeves/).

package/bin/jeeves

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import '../dist/index.js';
+// Jeeves's add-ons need Node.js 22.12 or newer (execa, ink and the AI SDK need 22;
+// commander needs 22.12). An older Node.js gets a plain message instead of a crash.
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 12)) {
+  console.error(`Jeeves needs Node.js 22.12 or newer, and this computer has ${process.versions.node}. Download the current version from nodejs.org, install it, then open Jeeves again.`);
+  process.exit(1);
+}
+await import('../dist/index.js');

package/dist/agent/auto-ids.js

@@ -0,0 +1,66 @@
+// The Auto mode model ids, in a module with no imports so the model catalogue can
+// use them without a dependency loop.
+export const AUTO_MODEL_ID = 'jeeves/auto';
+// Models retire and names change (the worker's name ends in a date), so each role
+// has a short list of replacements, used in order - the first one still in the
+// catalogue with tool support wins. Every id was checked live on 17 Sept 2026.
+// The first choices were measured in the model comparison; the replacements after
+// them were chosen as the nearest measured or same-family alternatives:
+// - worker: DeepSeek V4 Flash (dated name), then its undated name, then GLM 5.3
+//   Flash (15 of 15 on the bench on 17 Sept, including 2 of 2 on the calculator job,
+//   at a similar low price), then GLM 5.3 (6 of 6 on the hardest jobs, but about 15
+//   times the price - the last resort);
+// - expert: Claude Sonnet 5 (6 of 6; its reviews fixed the hard failures), then
+//   GLM 5.3 (6 of 6 alone), then Claude Opus 5;
+// - strongest model for the last rung: Claude Opus 5.
+// JEEVES_WORKER_MODEL lets the bench try another worker, as JEEVES_EXPERT_MODEL does the expert.
+export const WORKER_MODELS = [
+    ...(process.env.JEEVES_WORKER_MODEL ? [process.env.JEEVES_WORKER_MODEL] : []),
+    'deepseek/deepseek-v4-flash-0731',
+    'deepseek/deepseek-v4-flash',
+    'z-ai/glm-5.3-flash',
+    'z-ai/glm-5.3',
+];
+export const EXPERT_MODELS = [
+    ...(process.env.JEEVES_EXPERT_MODEL ? [process.env.JEEVES_EXPERT_MODEL] : []),
+    'anthropic/claude-sonnet-5',
+    'z-ai/glm-5.3',
+    'anthropic/claude-opus-5',
+];
+export const TOP_MODELS = ['anthropic/claude-opus-5'];
+export const AUTO_PROFILES = {
+    openrouter: { workers: WORKER_MODELS, experts: EXPERT_MODELS, top: TOP_MODELS },
+    // OpenAI with the person's own key. Chosen 18 Sept from public results (GPT-5.6 Luna
+    // scores near the top models at a tenth of the price), then measured through
+    // OpenRouter: Luna working with Terra as expert passed 6 of 6 of the telling jobs
+    // (letter, website, calculator, share tracker) at about 4 cents a job. Replacements:
+    // GPT-5.4 mini (OpenAI's small model for tool work) and GPT-5.5 - not measured.
+    openai: { workers: ['gpt-5.6-luna', 'gpt-5.4-mini'], experts: ['gpt-5.6-terra', 'gpt-5.5'], top: ['gpt-5.6-sol'] },
+    // Google with the person's own key (chosen 18 Sept). Measured through
+    // OpenRouter: Gemini 3.8 Flash working with 3.5 Flash as expert passed 4 of 5 of the
+    // telling jobs (the failure was a web-search fault since fixed), at 10-14 cents a job -
+    // about three times OpenAI's. Replacements (not measured): the Flash "latest" alias and
+    // 3.5 Flash; the strongest: 3.1 Pro.
+    google: { workers: ['gemini-3.8-flash', 'gemini-flash-latest', 'gemini-3.5-flash'], experts: ['gemini-3.5-flash', 'gemini-3.1-pro-preview'], top: ['gemini-3.1-pro-preview'] },
+};
+export function autoProfile(providerId) {
+    return AUTO_PROFILES[providerId] ?? null;
+}
+// First choices, for places that need a name before the catalogue has loaded.
+export const AUTO_WORKER_MODEL = WORKER_MODELS[0];
+export const AUTO_EXPERT_MODEL = EXPERT_MODELS[0];
+export const AUTO_TOP_MODEL = TOP_MODELS[0];
+// The first model in the list that is still in the catalogue and can use tools.
+// Before the catalogue has loaded (or when it could not be loaded) the first choice
+// is used, and a retired model then surfaces as a plain "not available" message.
+export function firstAvailable(candidates, catalogue) {
+    if (catalogue.length === 0)
+        return candidates[0] ?? null;
+    for (const id of candidates) {
+        const model = catalogue.find((entry) => entry.id === id);
+        const params = model?.supportedParameters ?? [];
+        if (model && (params.includes('tools') || params.includes('tool_choice')))
+            return id;
+    }
+    return null;
+}

package/dist/agent/auto.js

@@ -0,0 +1,178 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { session } from '../state/session.js';
+import { expertChat } from './expert-chat.js';
+import { seenModels } from '../providers/catalogue.js';
+// Auto mode: a cheap worker with an expert on call - the pattern Claude Code
+// publishes as its "advisor" (code.claude.com/docs/en/advisor): the main model does
+// the routine work and consults a stronger model at decision points (before
+// committing to an approach, when an error keeps recurring, before declaring a task
+// done), which costs less than running the stronger model throughout. No guessing
+// whether a message is "chat" or "work": the cheap model is always first.
+import { AUTO_MODEL_ID, AUTO_WORKER_MODEL, AUTO_PROFILES, autoProfile, firstAvailable } from './auto-ids.js';
+export { AUTO_MODEL_ID, AUTO_WORKER_MODEL };
+// Auto runs on OpenRouter and on the services with a profile in auto-ids.ts (OpenAI).
+export function hasAuto(providerId) {
+    return autoProfile(providerId) !== null;
+}
+// The model list Auto chooses from: OpenRouter's catalogue, or the models a company's
+// key can use (loaded when the company is chosen, and at startup).
+export function autoCatalogue(providerId = session.providerId) {
+    return providerId === 'openrouter' ? session.models : seenModels(providerId);
+}
+// A service without Auto falls back to OpenRouter's choices (used by web research).
+function profileFor(providerId) {
+    const profile = autoProfile(providerId);
+    return profile ? { profile, catalogue: autoCatalogue(providerId) } : { profile: AUTO_PROFILES.openrouter, catalogue: session.models };
+}
+// The models Auto uses right now, allowing for retired models (see auto-ids.ts).
+export function workerModel(providerId = session.providerId) {
+    const { profile, catalogue } = profileFor(providerId);
+    return firstAvailable(profile.workers, catalogue) ?? profile.workers[0] ?? AUTO_WORKER_MODEL;
+}
+export function expertModel(providerId = session.providerId) {
+    const { profile, catalogue } = profileFor(providerId);
+    return firstAvailable(profile.experts, catalogue);
+}
+export function topModel(providerId = session.providerId) {
+    const { profile, catalogue } = profileFor(providerId);
+    return firstAvailable(profile.top, catalogue);
+}
+// Where Auto is offered, by name, for the note in lists without it.
+export const AUTO_SERVICE_NAMES = { openrouter: 'OpenRouter', openai: 'OpenAI', google: 'Google' };
+// Jeeves only offers Auto where a pairing was proven to do good work (the project's
+// core principle: Jeeves's name carries the blame - docs/SPECIFICATION.md). Elsewhere, one plain line says so.
+export function noAutoNote(providerId, label) {
+    if (hasAuto(providerId))
+        return null;
+    const names = Object.keys(AUTO_PROFILES).map((id) => AUTO_SERVICE_NAMES[id] ?? id);
+    const list = names.length > 1 ? `${names.slice(0, -1).join(', ')} or ${names[names.length - 1]}` : names[0];
+    return `Auto isn't available with ${label} yet - choose ${list} for Auto.`;
+}
+// The Auto row in a company's model list, when it has Auto and its worker is available.
+export function autoRowFor(providerId, models) {
+    const profile = autoProfile(providerId);
+    if (!profile || providerId === 'openrouter')
+        return null;
+    const workerId = firstAvailable(profile.workers, models);
+    const worker = models.find((model) => model.id === workerId);
+    return worker ? { ...worker, id: AUTO_MODEL_ID, name: 'Auto', priceLabel: 'cheap, expert when needed' } : null;
+}
+export function isAuto(modelId) {
+    return modelId === AUTO_MODEL_ID;
+}
+// The real model id behind the selection: in Auto mode, the worker.
+export function workingModelId(modelId) {
+    return isAuto(modelId) ? workerModel() : modelId;
+}
+// If the cheap model's tool actions keep failing, the expert takes over for the
+// rest of that job: two failures within the last three steps. A person saying no
+// to a permission is not a failure.
+export function shouldTakeOver(stepFailures) {
+    return stepFailures.slice(-3).reduce((sum, failures) => sum + failures, 0) >= 2;
+}
+export { countToolFailures } from '../providers/step-control.js';
+export const EXPERT_INSTRUCTIONS = `You are the expert adviser to an assistant doing a job on a computer for someone with no technical background. You see the conversation so far, including every tool action and its result, then the assistant's question.
+Reply with specific, practical guidance: the approach to take, what to check, and any mistake you can see. Name exact files, commands, or facts where you can. Keep it under 200 words.
+Never guess: if the conversation does not show something, say it needs checking.
+If the assistant is clearly out of its depth, begin your reply with the words TAKE OVER.`;
+export const AUTO_NOTE = `
+
+Your Expert
+
+You can consult a stronger expert with askExpert. It sees this whole conversation. Consult it:
+- before starting a job that changes more than one file, or needs a plan;
+- when the same error has happened twice;
+- before telling {{ADDRESS}} that a job with several steps is finished - say what you did and how you checked it.
+Do not consult it for conversation, simple questions, or one small change. It costs far more than your own work, so ask one clear question.`;
+// A readable copy of the conversation for the expert. Long tool results are
+// shortened - the expert needs the shape of what happened, not every byte.
+export function conversationForExpert(messages, maxChars = 80_000, perResult = 2_000) {
+    const lines = [];
+    for (const message of messages) {
+        if (typeof message.content === 'string') {
+            lines.push(`${message.role.toUpperCase()}: ${message.content}`);
+            continue;
+        }
+        for (const part of message.content) {
+            if (part.type === 'text')
+                lines.push(`${message.role.toUpperCase()}: ${String(part.text)}`);
+            else if (part.type === 'tool-call')
+                lines.push(`ACTION ${String(part.toolName)}: ${JSON.stringify(part.input)}`);
+            else if (part.type === 'tool-result') {
+                const output = part.output;
+                const value = typeof output?.value === 'string' ? output.value : JSON.stringify(output?.value ?? '');
+                lines.push(`RESULT ${String(part.toolName)}: ${value.length > perResult ? value.slice(0, perResult) + ' …[shortened]' : value}`);
+            }
+        }
+    }
+    const text = lines.join('\n');
+    return text.length > maxChars ? '…[earlier conversation shortened]\n' + text.slice(-maxChars) : text;
+}
+// On in Auto mode (decided 18 Sept): Auto must be excellent without anyone
+// having to think about models. Targeted to programs and documents (review.ts), it
+// rescued 2 of 3 letters and cost 0.2-2.5 cents per checked job. JEEVES_REVIEW=0 turns
+// it off for testing.
+export const REVIEW_FINISHED_JOBS = process.env.JEEVES_REVIEW !== '0';
+export function newAutoTurnState() {
+    return { expertTookOver: false, takeoverStep: -1, askedAboutTop: false, onTopModel: false };
+}
+// How many times the expert's price the strongest model costs, from the catalogue
+// (input prices); null when either is missing.
+export function topModelPriceRatio(models, expertId = expertModel(), topId = topModel()) {
+    const expert = models.find((model) => model.id === expertId);
+    const top = models.find((model) => model.id === topId);
+    if (!expert || !top || expert.promptPrice <= 0)
+        return null;
+    return top.promptPrice / expert.promptPrice;
+}
+export function topModelQuestion(address, ratio, name = topModelName()) {
+    const cost = ratio ? ` It costs about ${Number(ratio.toFixed(1))}× as much as the expert.` : '';
+    return `This is proving difficult, ${address}. Shall I try the strongest model (${name}) for this job?${cost} (y/n)`;
+}
+// The strongest model's everyday name ("Claude Opus 5"), from the catalogue.
+export function topModelName(providerId = session.providerId) {
+    const id = topModel(providerId);
+    const found = autoCatalogue(providerId).find((model) => model.id === id);
+    if (found)
+        return found.name.replace(/^[A-Za-z][A-Za-z0-9 .-]*: /, '');
+    return id ? readableModelName(id) : 'the strongest model';
+}
+// "anthropic/claude-opus-5" -> "Claude Opus 5", "gpt-5.6-sol" -> "GPT 5.6 Sol", for
+// when the catalogue has not loaded.
+export function readableModelName(id) {
+    return (id.split('/').pop() ?? id)
+        .split('-')
+        .map((word) => (word === 'gpt' ? 'GPT' : word.charAt(0).toUpperCase() + word.slice(1)))
+        .join(' ');
+}
+export function createAskExpertTool(state) {
+    return tool({
+        description: 'Consult a stronger expert model about the job in hand. It sees the whole conversation. Use at decision points only (see the rules).',
+        inputSchema: z.object({ question: z.string().min(1).describe('One clear question for the expert') }),
+        execute: async ({ question }, { messages }) => {
+            const expert = expertModel();
+            if (!expert)
+                return 'No expert model is available right now. Carry on carefully, and tell the person the work could not be double-checked.';
+            const lineId = session.addToolLine('askExpert', question.slice(0, 60), 'running');
+            session.setActiveModel(expert);
+            try {
+                const reply = await expertChat(expert, [
+                    { role: 'system', content: EXPERT_INSTRUCTIONS },
+                    { role: 'user', content: `Conversation so far:\n${conversationForExpert(messages)}\n\nThe assistant asks: ${question}` },
+                ], 1500);
+                if (reply.trimStart().toUpperCase().startsWith('TAKE OVER'))
+                    state.expertTookOver = true;
+                session.updateToolLine(lineId, { state: 'done', label: 'Checked with the expert' });
+                return reply || 'The expert had no advice to add.';
+            }
+            catch (error) {
+                session.updateToolLine(lineId, { state: 'failed', label: 'the expert was not available' });
+                return `The expert could not be reached (${error instanceof Error ? error.message : String(error)}). Carry on carefully.`;
+            }
+            finally {
+                session.setActiveModel(state.expertTookOver ? expert : workerModel());
+            }
+        },
+    });
+}

package/dist/agent/context.js

@@ -1,35 +1,77 @@
 import { session } from '../state/session.js';
 import { getActiveProvider } from '../providers/index.js';
+import { getSystemPrompt } from './systemPrompt.js';
+import { DEFAULT_CONTEXT_TOKENS } from '../state/session.js';
+import { ZAI_MODELS } from '../providers/zai.js';
+import { findSeenModel } from '../providers/catalogue.js';
+import { SUMMARY_TRIGGER_TOKENS, SUMMARY_INSTRUCTIONS } from './housekeeping.js';
+import { workerModel, workingModelId } from './auto.js';
+import { reportStepCost } from './spending.js';
+// The model's identity and rulebook. AI SDK 7 rejects role:'system' messages in the
+// messages array ("Use the instructions option instead"), so the prompt travels as
+// streamText's instructions option via the provider layer (see loop.ts).
+export { getSystemPrompt };
 // Builds the message list for one turn; automatic summarisation of older turns (spec 3.3)
 // is deferred until long-conversation handling lands.
 export function buildTurnMessages(history, userText) {
     const userMessage = { role: 'user', content: userText };
     return [...history, userMessage];
 }
-// Condenses the whole conversation into a single summary message so a newly
-// selected model can continue without re-reading every turn.
+// How much the current model can hold in mind, from the model lists (OpenRouter's
+// catalogue, Z.ai's own list, or a direct connection's); the long-standing default when it isn't listed.
+export function contextLimitFor(modelId, models) {
+    const found = models.find((model) => model.id === modelId) ??
+        ZAI_MODELS.find((model) => model.id === modelId) ??
+        findSeenModel(session.providerId, modelId);
+    return found && found.contextLength > 0 ? found.contextLength : DEFAULT_CONTEXT_TOKENS;
+}
+// The conversation is summarised automatically once it fills this share of the
+// model's memory, so the user never has to watch a memory gauge. Matches the
+// amber threshold the old info bar used for "getting full".
+export const AUTO_SUMMARISE_AT = 0.7;
+// Whichever comes first: Anthropic's default compaction point (100,000 tokens), or
+// 70% of the model's memory for models with a small one.
+export function shouldAutoSummarise(conversationTokens, limit) {
+    return conversationTokens >= Math.min(SUMMARY_TRIGGER_TOKENS, AUTO_SUMMARISE_AT * limit);
+}
+// A failed summary is never announced - the user could do nothing about it. It is
+// retried quietly, but only after a few messages, so a service that keeps failing
+// is not asked (and billed) for a summary on every single message.
+export const SUMMARY_RETRY_AFTER = 3;
+let messagesUntilRetry = 0;
+export function summaryDue(conversationTokens, limit) {
+    if (messagesUntilRetry > 0) {
+        messagesUntilRetry -= 1;
+        return false;
+    }
+    return shouldAutoSummarise(conversationTokens, limit);
+}
+// Condenses the whole conversation into a single summary message so a model can
+// continue without re-reading every turn: on a model switch, or automatically when
+// the conversation grows long.
 export async function summariseHistory() {
     if (session.history.length === 0)
         return;
     session.setStatus('working');
+    session.setTidying(true);
     try {
         const provider = getActiveProvider();
-        const messages = [
-            ...session.history,
-            {
-                role: 'user',
-                content: 'Summarise this conversation so far as compact context a model can continue from. Reply with only the summary.',
-            },
-        ];
+        const messages = [...session.history, { role: 'user', content: SUMMARY_INSTRUCTIONS }];
+        // On OpenRouter the summary is written by the cheap worker model whatever model
+        // is selected - summarising needs care, not the most expensive model.
         const result = await provider.stream({
-            modelId: session.model,
+            modelId: session.providerId === 'openrouter' ? workerModel() : workingModelId(session.model),
             messages,
             tools: {},
+            instructions: getSystemPrompt(),
             onToken: () => { },
             onReasoning: () => { },
             onToolCall: () => { },
         });
+        for (const cost of result.stepCosts ?? [])
+            reportStepCost(cost);
         const summary = result.text.trim();
+        // Silent either way: the user can do nothing about it (a failure retries later).
         if (summary) {
             session.setHistory([
                 {
@@ -37,14 +79,14 @@ export async function summariseHistory() {
                     content: `A summary of the conversation so far:\n\n${summary}\n\nContinue helping from this point.`,
                 },
             ]);
-            session.addNotice('Conversation summarised for the new model.');
         }
         else {
-            session.addNotice('Could not summarise - kept the conversation as-is.');
+            messagesUntilRetry = SUMMARY_RETRY_AFTER;
         }
     }
     catch {
-        session.addNotice('Could not summarise - kept the conversation as-is.');
+        messagesUntilRetry = SUMMARY_RETRY_AFTER;
     }
+    session.setTidying(false);
     session.setStatus('idle');
 }