@tianmucreations/jeeves 0.2.0 → 0.3.0

package/dist/providers/ollama.js

@@ -1,5 +1,6 @@
 import { streamText, stepCountIs } from 'ai';
 import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { prepareStepFor } from './step-control.js';
 const OLLAMA_BASE_URL = 'http://localhost:11434/v1';
 const MAX_TOOL_STEPS = 25;
 // Ollama exposes an OpenAI-compatible endpoint, so the OpenRouter client speaks to it directly.
@@ -12,12 +13,26 @@ export function createOllamaProvider() {
     return {
         id: 'ollama',
         name: 'Ollama',
-        async stream({ modelId, messages, tools, onToken, onReasoning, onToolCall }) {
+        async stream({ modelId, messages, tools, instructions, onToken, onReasoning, onToolCall, beforeStep, abortSignal }) {
             const result = streamText({
+                instructions,
+                // A stalled request must never wedge the app in the working state forever -
+                // but a long, healthy job must not be cut off either. So the limits are on
+                // silence, not on the whole job: 90 seconds between pieces of a reply (verified
+                // to abort a real stream), 2 minutes for the first piece once the reply has
+                // started, and 10 minutes for any single step, which also covers a request that
+                // never starts answering. (A plain number here limits the entire multi-step
+                // job; a 3-minute one killed healthy jobs mid-way in testing.)
+                timeout: { firstChunkMs: 120_000, chunkMs: 90_000, stepMs: 600_000 },
                 model: client.chat(modelId),
                 messages,
                 tools,
                 stopWhen: stepCountIs(MAX_TOOL_STEPS),
+                prepareStep: prepareStepFor(beforeStep, (id) => client.chat(id)),
+                abortSignal,
+                // The library prints every failure to the screen by default, over Jeeves's
+                // window; the failure still arrives below and is explained in plain English.
+                onError: () => { },
             });
             let streamedError = null;
             for await (const part of result.stream) {
@@ -34,10 +49,12 @@ export function createOllamaProvider() {
                     streamedError = part.error;
                 }
             }
-            const text = await result.text;
-            if (!text && streamedError !== null) {
+            // The real stream error (a rejected key, a missing model) must win over the
+            // SDK's generic no-output error, which would otherwise mask the cause.
+            if (streamedError !== null) {
                 throw streamedError instanceof Error ? streamedError : new Error(String(streamedError));
             }
+            const text = await result.text;
             const finalStep = await result.finalStep;
             const responseMessages = await result.responseMessages;
             const usage = await result.usage;
@@ -89,7 +106,7 @@ export function mapOllamaTags(body) {
 export async function listLocalOllamaModels() {
     const response = await fetch('http://localhost:11434/api/tags', { signal: AbortSignal.timeout(1500) });
     if (!response.ok)
-        throw new Error('local Ollama did not respond');
+        throw new Error('Ollama on this computer did not respond');
     return mapOllamaTags(await response.json());
 }
 export async function isOllamaOnline() {

package/dist/providers/openrouter.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { streamText, stepCountIs } from 'ai';
 import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { prepareStepFor, stepCost } from './step-control.js';
 // Assumption: the spec's "maxSteps" is called stopWhen/stepCountIs in AI SDK 7 (the installed version); same cap of 25.
 const MAX_TOOL_STEPS = 25;
 // Sticky routing: one id per conversation, sent with every request. OpenRouter uses
@@ -37,6 +38,22 @@ export async function fetchCreditInfo(apiKey) {
         return null;
     }
 }
+// The key's all-time spend in dollars, from GET /api/v1/key (field "usage",
+// confirmed against a live response). Used to work out today's spend in local time.
+export async function fetchKeyUsage(apiKey) {
+    try {
+        const response = await fetch('https://openrouter.ai/api/v1/key', {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return typeof body.data?.usage === 'number' ? body.data.usage : null;
+    }
+    catch {
+        return null;
+    }
+}
 function headerNumber(headers, name) {
     const raw = headers?.[name];
     if (raw === undefined)
@@ -49,12 +66,27 @@ export function createOpenRouterProvider(apiKey) {
     return {
         id: 'openrouter',
         name: 'OpenRouter',
-        async stream({ modelId, messages, tools, onToken, onReasoning, onToolCall }) {
+        async stream({ modelId, messages, tools, instructions, onToken, onReasoning, onToolCall, beforeStep, abortSignal }) {
             const result = streamText({
-                model: openrouter.chat(modelId),
+                instructions,
+                // A stalled request must never wedge the app in the working state forever -
+                // but a long, healthy job must not be cut off either. So the limits are on
+                // silence, not on the whole job: 90 seconds between pieces of a reply (verified
+                // to abort a real stream), 2 minutes for the first piece once the reply has
+                // started, and 10 minutes for any single step, which also covers a request that
+                // never starts answering. (A plain number here limits the entire multi-step
+                // job; a 3-minute one killed healthy jobs mid-way in testing.)
+                timeout: { firstChunkMs: 120_000, chunkMs: 90_000, stepMs: 600_000 },
+                // Usage accounting makes OpenRouter report each step's exact cost.
+                model: openrouter.chat(modelId, { usage: { include: true } }),
                 messages,
                 tools,
                 stopWhen: stepCountIs(MAX_TOOL_STEPS),
+                prepareStep: prepareStepFor(beforeStep, (id) => openrouter.chat(id, { usage: { include: true } })),
+                abortSignal,
+                // The library prints every failure to the screen by default, over Jeeves's
+                // window; the failure still arrives below and is explained in plain English.
+                onError: () => { },
                 providerOptions: {
                     openrouter: {
                         session_id: stickySessionId,
@@ -76,10 +108,12 @@ export function createOpenRouterProvider(apiKey) {
                     streamedError = part.error;
                 }
             }
-            const text = await result.text;
-            if (!text && streamedError !== null) {
+            // The real stream error (a rejected key, a missing model) must win over the
+            // SDK's generic no-output error, which would otherwise mask the cause.
+            if (streamedError !== null) {
                 throw streamedError instanceof Error ? streamedError : new Error(String(streamedError));
             }
+            const text = await result.text;
             const finalStep = await result.finalStep;
             const reasoning = finalStep.reasoningText ?? '';
             const responseMessages = await result.responseMessages;
@@ -103,6 +137,7 @@ export function createOpenRouterProvider(apiKey) {
                 },
                 cost: 0,
                 rateLimit,
+                stepCosts: (await result.steps).map(stepCost),
             };
         },
     };

package/dist/providers/step-control.js

@@ -0,0 +1,28 @@
+// Failed tool actions in one step. A person saying no to a permission is not a failure.
+export function countToolFailures(content) {
+    // Nor is an action held until research is done (research-gate.ts).
+    return content.filter((part) => part.type === 'tool-error' && !String(part.error).includes('Permission denied by the user') && !String(part.error).includes('Held for research:')).length;
+}
+// OpenRouter's own cost figure for one step, from its usage accounting.
+export function stepCost(step) {
+    const cost = step.providerMetadata?.openrouter?.usage?.cost;
+    return typeof cost === 'number' ? cost : 0;
+}
+// costOf: what a finished step cost - OpenRouter's own figure unless the service
+// works it out from a price list (the direct connections).
+export function prepareStepFor(beforeStep, modelFor, costOf = stepCost) {
+    if (!beforeStep)
+        return undefined;
+    return async ({ stepNumber, steps, messages }) => {
+        const control = await beforeStep({
+            stepNumber,
+            stepFailures: steps.map((step) => countToolFailures(step.content)),
+            stepCosts: steps.map(costOf),
+            messages,
+        });
+        return {
+            ...(control.modelId ? { model: modelFor(control.modelId) } : {}),
+            ...(control.messages ? { messages: control.messages } : {}),
+        };
+    };
+}

package/dist/providers/zai.js

@@ -1,9 +1,12 @@
 import { streamText, stepCountIs } from 'ai';
-import { createAnthropic } from '@ai-sdk/anthropic';
-// Z.ai's coding endpoint speaks the Anthropic Messages protocol, so the official
-// Anthropic adapter talks to it directly. The base URL must include /v1 because
-// the appends /messages to it.
-const ZAI_BASE_URL = 'https://api.z.ai/api/anthropic/v1';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { prepareStepFor } from './step-control.js';
+// The GLM Coding Plan endpoint: OpenAI Chat Completions protocol at
+// https://api.z.ai/api/coding/paas/v4 - NOT the standard /api/paas/v4, which is
+// the pay-per-token API. The OpenRouter client speaks the OpenAI protocol, so it
+// talks to the coding endpoint directly (the same trick the Ollama adapter uses
+// for its OpenAI-compatible endpoint).
+export const ZAI_CODING_BASE_URL = 'https://api.z.ai/api/coding/paas/v4';
 const MAX_TOOL_STEPS = 25;
 // The GLM Coding Plan is flat-rate, so prices are meaningless per token; the picker
 // shows "included" instead of a dollar figure (spec: no misleading numbers).
@@ -50,19 +53,34 @@ export const ZAI_MODELS = [
     },
 ];
 export function createZaiProvider(apiKey) {
-    const client = createAnthropic({
+    const client = createOpenRouter({
         apiKey,
-        baseURL: ZAI_BASE_URL,
+        baseURL: ZAI_CODING_BASE_URL,
+        compatibility: 'compatible',
     });
     return {
         id: 'zai',
         name: 'Z.ai',
-        async stream({ modelId, messages, tools, onToken, onReasoning, onToolCall }) {
+        async stream({ modelId, messages, tools, instructions, onToken, onReasoning, onToolCall, beforeStep, abortSignal }) {
             const result = streamText({
-                model: client(modelId),
+                instructions,
+                // A stalled request must never wedge the app in the working state forever -
+                // but a long, healthy job must not be cut off either. So the limits are on
+                // silence, not on the whole job: 90 seconds between pieces of a reply (verified
+                // to abort a real stream), 2 minutes for the first piece once the reply has
+                // started, and 10 minutes for any single step, which also covers a request that
+                // never starts answering. (A plain number here limits the entire multi-step
+                // job; a 3-minute one killed healthy jobs mid-way in testing.)
+                timeout: { firstChunkMs: 120_000, chunkMs: 90_000, stepMs: 600_000 },
+                model: client.chat(modelId),
                 messages,
                 tools,
                 stopWhen: stepCountIs(MAX_TOOL_STEPS),
+                prepareStep: prepareStepFor(beforeStep, (id) => client.chat(id)),
+                abortSignal,
+                // The library prints every failure to the screen by default, over Jeeves's
+                // window; the failure still arrives below and is explained in plain English.
+                onError: () => { },
             });
             let streamedError = null;
             for await (const part of result.stream) {
@@ -79,10 +97,12 @@ export function createZaiProvider(apiKey) {
                     streamedError = part.error;
                 }
             }
-            const text = await result.text;
-            if (!text && streamedError !== null) {
+            // The real stream error (a rejected key, a missing model) must win over the
+            // SDK's generic no-output error, which would otherwise mask the cause.
+            if (streamedError !== null) {
                 throw streamedError instanceof Error ? streamedError : new Error(String(streamedError));
             }
+            const text = await result.text;
             const finalStep = await result.finalStep;
             const responseMessages = await result.responseMessages;
             const usage = await result.usage;

package/dist/state/session.js

@@ -1,8 +1,11 @@
 import { useSyncExternalStore } from 'react';
+import { AUTO_MODEL_ID } from '../agent/auto-ids.js';
 // Assumption: z-ai/glm-5.3's context length; the Phase 6 model registry replaces this constant.
 export const DEFAULT_CONTEXT_TOKENS = 1_310_720;
 class SessionStore {
-    model = 'z-ai/glm-5.3';
+    // Auto until the person chooses otherwise (decided 18 Sept): someone who
+    // leaves the model list without picking still gets the recommended experience.
+    model = AUTO_MODEL_ID;
     providerId = 'openrouter';
     providerName = 'OpenRouter';
     status = 'idle';
@@ -14,7 +17,8 @@ class SessionStore {
     wizardActive = false;
     helpOpen = false;
     exitRequested = false;
-    launchStage = 'project';
+    launchStage = 'address';
+    addressOpen = false;
     wizardFromLaunch = false;
     recentProjects = [];
     models = [];
@@ -25,21 +29,36 @@ class SessionStore {
     tokensOut = 0;
     tokensCached = 0;
     cost = 0;
-    footerExpanded = null;
-    hiddenMetrics = [];
     creditUsed = null;
     creditRemaining = null;
     creditLimit = null;
     creditIsAccount = false;
-    spend = 0;
+    // Spent today on the OpenRouter key (local calendar day); null until first read.
+    todaySpend = null;
+    // When a flat-rate plan (Z.ai) has used up its allowance: the reset time it gave
+    // (HH:MM, or '' if none was given); null while the plan has allowance.
+    planResetAt = null;
+    // In Auto mode, the model actually working right now (worker or expert).
+    activeModel = null;
+    // True while quiet housekeeping (a summary) is running - shown in the info bar.
+    tidying = false;
+    // A short note for the info bar while something quick runs, like 'backing up…'.
+    busyNote = null;
+    // Something the model must be told with the next message (for example, that /undo ran).
+    pendingContextNote = null;
+    // The daily spending limit in dollars, and any extra allowance granted today.
+    dailyLimit = 3;
+    dailyExtra = 0;
     rateLimit = null;
     transcript = [];
     history = [];
     lastReasoning = '';
     // Lines the transcript view is scrolled up from the bottom; 0 means "follow the newest".
     transcriptScrollUp = 0;
+    // The furthest the transcript can scroll up (contentHeight - viewportHeight),
+    // reported by the Transcript from its live measurements.
+    transcriptScrollMax = Number.POSITIVE_INFINITY;
     turnEvents = [];
-    creditBaselineUsed = null;
     nextId = 1;
     version = 0;
     reasoningEntryId = null;
@@ -196,6 +215,29 @@ class SessionStore {
         this.launchStage = 'ready';
         this.emit();
     }
+    // The address question runs before the project picker on first launch only;
+    // index.tsx skips straight to the picker when an address is already saved.
+    skipAddressStage() {
+        if (this.launchStage === 'address') {
+            this.launchStage = 'project';
+            this.emit();
+        }
+    }
+    addressDone() {
+        this.addressOpen = false;
+        if (this.launchStage === 'address') {
+            this.launchStage = 'project';
+            this.emit();
+        }
+    }
+    openAddress() {
+        if (this.status === 'working' || this.approvalPending) {
+            this.addNotice('The address change happens between tasks.');
+            return;
+        }
+        this.addressOpen = true;
+        this.emit();
+    }
     setRecentProjects(projects) {
         this.recentProjects = projects.slice(0, 10);
         this.emit();
@@ -219,16 +261,25 @@ class SessionStore {
     }
     // Internal scrolling for the alternate-screen era: the terminal's own scrollback is
     // unavailable there, so the transcript region scrolls itself. Positive deltas go up
-    // (older); the count is clamped to zero so the view can never sink past the newest.
+    // (older); the count is clamped between zero (the newest) and the measured maximum
+    // (the oldest), so overshooting the top never leaves wheel or arrow presses to
+    // unwind before the view moves again.
     scrollTranscript(delta) {
         if (delta === 0)
             return;
-        const next = Math.max(0, this.transcriptScrollUp + delta);
+        const next = Math.min(this.transcriptScrollMax, Math.max(0, this.transcriptScrollUp + delta));
         if (next === this.transcriptScrollUp)
             return;
         this.transcriptScrollUp = next;
         this.emit();
     }
+    setTranscriptScrollMax(max) {
+        this.transcriptScrollMax = Math.max(0, max);
+        if (this.transcriptScrollUp > this.transcriptScrollMax) {
+            this.transcriptScrollUp = this.transcriptScrollMax;
+            this.emit();
+        }
+    }
     followTranscript() {
         if (this.transcriptScrollUp === 0)
             return;
@@ -262,41 +313,44 @@ class SessionStore {
         const cutoff = Date.now() - 60_000;
         return this.turnEvents.filter((event) => event.t >= cutoff).reduce((sum, event) => sum + event.tokens, 0);
     }
-    setHiddenMetrics(metrics) {
-        this.hiddenMetrics = metrics;
+    setCredit(used, limit, remaining, accountWide) {
+        this.creditUsed = used;
+        this.creditLimit = limit;
+        this.creditRemaining = remaining;
+        this.creditIsAccount = accountWide;
         this.emit();
     }
-    // Tab is an optional zoom-in: it expands one metric into a wide bar, cycling
-    // through them and wrapping back to the always-visible compact view.
-    tabFooter() {
-        const all = ['session', 'context', 'cache', 'today', 'credit', 'speed'];
-        const visible = all.filter((metric) => !this.hiddenMetrics.includes(metric));
-        if (visible.length === 0) {
-            this.footerExpanded = null;
-            this.emit();
+    setTodaySpend(amount) {
+        this.todaySpend = amount;
+        this.emit();
+    }
+    setActiveModel(model) {
+        if (this.activeModel === model)
             return;
-        }
-        if (this.footerExpanded === null) {
-            this.footerExpanded = visible[0];
-        }
-        else {
-            const index = visible.indexOf(this.footerExpanded);
-            this.footerExpanded = visible[index + 1] ?? null;
-        }
+        this.activeModel = model;
         this.emit();
     }
-    escapeFooter() {
-        this.footerExpanded = null;
+    setBusyNote(note) {
+        if (this.busyNote === note)
+            return;
+        this.busyNote = note;
         this.emit();
     }
-    setCredit(used, limit, remaining, accountWide) {
-        if (this.creditBaselineUsed === null)
-            this.creditBaselineUsed = used;
-        this.spend = Math.max(0, used - this.creditBaselineUsed);
-        this.creditUsed = used;
-        this.creditLimit = limit;
-        this.creditRemaining = remaining;
-        this.creditIsAccount = accountWide;
+    setTidying(value) {
+        if (this.tidying === value)
+            return;
+        this.tidying = value;
+        this.emit();
+    }
+    setDailyLimit(limit, extra = this.dailyExtra) {
+        this.dailyLimit = limit;
+        this.dailyExtra = extra;
+        this.emit();
+    }
+    setPlanResetAt(value) {
+        if (this.planResetAt === value)
+            return;
+        this.planResetAt = value;
         this.emit();
     }
     setRateLimit(info) {

package/dist/state/today-spend.js

@@ -0,0 +1,26 @@
+// "today" in the info bar is the user's own calendar day, not OpenRouter's. OpenRouter
+// reports usage_daily for the current UTC day (openrouter.ai/docs, GET /api/v1/key),
+// which for someone at UTC+7 would reset at 7am. Instead the key's all-time usage is
+// read after each turn and today's spend is measured from a baseline for the local
+// date. The zone is never stored: the date comes from the computer's clock each time,
+// so it follows the user when they travel.
+export function localDate(now) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+// When a new day starts, the last reading from yesterday becomes today's baseline,
+// so anything spent after that reading counts towards today - it may over-count a
+// little, never under-count. A reading older than yesterday is too stale to use.
+export function nextSpendReading(prev, usage, now) {
+    const today = localDate(now);
+    if (!prev || usage < prev.last)
+        return { date: today, baseline: usage, last: usage };
+    if (prev.date === today)
+        return { ...prev, last: usage };
+    const yesterday = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1);
+    const baseline = prev.date === localDate(yesterday) ? prev.last : usage;
+    return { date: today, baseline, last: usage };
+}
+export function spentToday(reading) {
+    return Math.max(0, reading.last - reading.baseline);
+}

package/dist/tools/index.js

@@ -1,10 +1,15 @@
 import { tool } from 'ai';
 import { session } from '../state/session.js';
-import { requestApproval } from '../agent/permissions.js';
+import { requestApproval, isReadOnlyBashCommand } from '../agent/permissions.js';
 import { readFileSchema, runReadFile } from './readFile.js';
 import { writeFileSchema, runWriteFile } from './writeFile.js';
 import { listDirSchema, runListDir } from './listDir.js';
 import { runBashSchema, runRunBash } from './runBash.js';
+import { webSearchSchema, runWebSearch, readWebPageSchema, runReadWebPage } from './web/research.js';
+import { ensureCheckpoint, isOutsideProject, commandMayReachOutside } from '../checkpoints/index.js';
+import { resolveFromCwd } from '../platform/paths.js';
+import { holdForWrite, holdForCommand, recordCommandResult, recordNote, noteResearchSchema, HELD_PREFIX, commandEditsFiles, } from '../agent/research-gate.js';
+import { holdUntilReproduced } from '../agent/review.js';
 // Assumption: every tool result is capped to keep huge outputs from flooding the conversation.
 const MAX_RESULT_CHARS = 150_000;
 function truncate(text) {
@@ -20,16 +25,38 @@ function describeError(error) {
 export function plainToolFailure(error) {
     const raw = describeError(error);
     const text = raw.toLowerCase();
+    // Codes and meanings per the Node.js docs' "Common system errors" list.
     if (text.includes('enoent'))
-        return 'file or folder not found';
+        return "couldn't find that file or folder";
     if (text.includes('eacces') || text.includes('eperm'))
-        return 'permission denied';
-    if (text.includes('timed out') || text.includes('etimedout') || text.includes('stopped after'))
+        return "the computer wouldn't allow it";
+    if (text.includes('eisdir'))
+        return 'that is a folder, not a file';
+    if (text.includes('enotdir'))
+        return 'part of that location is not a folder';
+    if (text.includes('eexist'))
+        return 'something with that name already exists';
+    if (text.includes('enotempty'))
+        return 'that folder is not empty';
+    if (text.includes('no space left'))
+        return 'the disk is full';
+    if (text.includes('timed out') || text.includes('etimedout') || text.includes('stopped after') || text.includes("didn't finish"))
         return 'took too long';
     if (text.includes('binary file'))
         return 'not a text file';
-    const firstLine = raw.split('\n')[0].trim();
-    return firstLine.length > 0 ? firstLine : 'failed';
+    if (text.includes('web search needs an openrouter key'))
+        return 'needs an OpenRouter key (type /keys)';
+    if (text.includes('web search is not available'))
+        return 'web search is not available right now';
+    if (text.includes("couldn't open"))
+        return "that website wouldn't open";
+    if (text.includes('not a valid web address') || text.includes('only web pages'))
+        return 'not a web address';
+    if (text.includes('needs an interactive terminal'))
+        return 'that program needs typing in a window of its own';
+    // Anything unrecognised stays off screen; the model receives the full message
+    // and explains it in plain English.
+    return 'something unexpected went wrong';
 }
 function clip(text, max) {
     return text.length > max ? text.slice(0, max - 1) + '…' : text;
@@ -42,8 +69,21 @@ function defineTool(config) {
             // The SDK validates before execute; parsing again keeps this layer strictly typed.
             const input = config.schema.parse(rawInput);
             const summary = config.summarize(input);
-            const lineId = session.addToolLine(config.name, summary, config.permission ? 'awaiting' : 'running');
-            if (config.permission) {
+            const held = (await config.hold?.(input)) ?? null;
+            if (held) {
+                const heldLine = session.addToolLine(config.name, summary, 'running');
+                session.updateToolLine(heldLine, {
+                    state: 'held',
+                    label: held.includes('reproduce the reported problem') ? 'waits until the problem is reproduced' : 'waits until the research is done',
+                });
+                throw new Error(held);
+            }
+            const needsPermission = typeof config.permission === 'function' ? config.permission(input) : config.permission;
+            const warning = config.warning?.(input) ?? null;
+            if (warning)
+                session.addNotice(warning);
+            const lineId = session.addToolLine(config.name, summary, needsPermission ? 'awaiting' : 'running');
+            if (needsPermission) {
                 const approved = await requestApproval();
                 if (!approved) {
                     session.updateToolLine(lineId, { state: 'declined' });
@@ -51,6 +91,16 @@ function defineTool(config) {
                 }
                 session.updateToolLine(lineId, { state: 'running' });
             }
+            if (config.changesFiles?.(input)) {
+                const backup = await ensureCheckpoint();
+                if (!backup.ok) {
+                    session.addNotice("I couldn't back up the project folder first, so this change couldn't be undone. Go ahead anyway? (y/n)");
+                    if (!(await requestApproval())) {
+                        session.updateToolLine(lineId, { state: 'declined' });
+                        throw new Error(`Not done: the folder could not be backed up first (${backup.problem}), and the person chose not to go ahead.`);
+                    }
+                }
+            }
             try {
                 const result = truncate(await config.run(input));
                 session.updateToolLine(lineId, { state: 'done', label: config.label(input, result) });
@@ -72,6 +122,7 @@ export const TOOLS = {
         summarize: (input) => input.path,
         label: (input) => `Read ${input.path}`,
         run: runReadFile,
+        hold: (input) => holdUntilReproduced('readFile', input.path, false),
     }),
     listDir: defineTool({
         name: 'listDir',
@@ -81,6 +132,7 @@ export const TOOLS = {
         summarize: (input) => input.path,
         label: (input, result) => `Listed ${input.path} (${result.split('\n').length} items)`,
         run: runListDir,
+        hold: (input) => holdUntilReproduced('listDir', input.path, false),
     }),
     writeFile: defineTool({
         name: 'writeFile',
@@ -90,17 +142,73 @@ export const TOOLS = {
         summarize: (input) => `${input.path} (${input.content.length} characters)`,
         label: () => 'Wrote 1 file',
         run: runWriteFile,
+        hold: async (input) => holdUntilReproduced('writeFile', input.path, true) ?? (await holdForWrite(input.path, resolveFromCwd(input.path), process.cwd())),
+        changesFiles: () => true,
+        warning: (input) => isOutsideProject(input.path)
+            ? `Heads up: ${input.path} is outside your project folder, so /undo can't reverse this change.`
+            : null,
+    }),
+    webSearch: defineTool({
+        name: 'webSearch',
+        description: 'Search the web. Returns titles, addresses and short snippets - a list of where to look, not checked facts.',
+        schema: webSearchSchema,
+        permission: false,
+        summarize: (input) => clip(input.query, 60),
+        label: (input) => `Searched ${clip(input.query, 60)}`,
+        run: runWebSearch,
+    }),
+    readWebPage: defineTool({
+        name: 'readWebPage',
+        description: 'Open a web page and find one fact on it. Returns the answer with the exact quote from the page, or says it is not stated there.',
+        schema: readWebPageSchema,
+        permission: false,
+        summarize: (input) => clip(input.url, 60),
+        label: (input) => `Read ${clip(input.url.replace(/^https?:\/\//, ''), 60)}`,
+        run: runReadWebPage,
     }),
     runBash: defineTool({
         name: 'runBash',
         description: 'Run a shell command and return its output.',
         schema: runBashSchema,
-        permission: true,
+        // Read-only commands never ask (the allowlist lives in permissions.ts);
+        // everything else - writes, deletes, installs, network - still prompts.
+        permission: (input) => !isReadOnlyBashCommand(input.command),
         summarize: (input) => clip(input.command, 60),
         label: (input) => `Ran ${clip(input.command, 60)}`,
-        run: runRunBash,
+        run: async (input) => {
+            const output = await runRunBash(input);
+            // Looking around (a search that finds nothing exits 1) is not a problem to research.
+            if (isReadOnlyBashCommand(input.command))
+                return output;
+            const exit = output.match(/^exit code: (\d+|unknown)$/m)?.[1];
+            const note = recordCommandResult(input.command, exit === undefined || exit === 'unknown' ? null : Number(exit), output);
+            return note ? output + note : output;
+        },
+        hold: (input) => holdUntilReproduced('runBash', input.command, commandEditsFiles(input.command)) ??
+            (isReadOnlyBashCommand(input.command) ? null : holdForCommand(input.command)),
+        changesFiles: (input) => !isReadOnlyBashCommand(input.command),
+        warning: (input) => !isReadOnlyBashCommand(input.command) && commandMayReachOutside(input.command)
+            ? "Heads up: this command may change things outside your project folder, which /undo can't reverse."
+            : null,
     }),
 };
+// Research before building or patching: the note that releases a hold. Shown to the
+// person in full, because code can make research happen but not make it good.
+TOOLS.noteResearch = defineTool({
+    name: 'noteResearch',
+    description: 'Record your research before building something new (kind "build") or after the same failure twice (kind "problem"). List only pages you opened with readWebPage in this conversation.',
+    schema: noteResearchSchema,
+    permission: false,
+    summarize: (input) => clip(input.subject, 60),
+    label: (_input, result) => (result.startsWith('Recorded') ? 'Research noted' : 'Research note not accepted yet'),
+    run: async (input) => {
+        const outcome = recordNote(input);
+        if (outcome.shown)
+            session.addNotice(outcome.shown);
+        return outcome.reply;
+    },
+});
+export { HELD_PREFIX };
 export function getTools() {
     return TOOLS;
 }