@nanhara/hara 0.132.4 → 0.133.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.133.0 — 2026-07-22 — field-feedback closure: documents, web, recall, and setup
+
+- A new approval-gated `python` tool sends Python 3 source directly over stdin, so one-shot APIs such as
+  `python-docx` no longer require Hara to create and later execute a durable `.py` helper. Source size,
+  active-run cancellation, process-tree timeout, output redaction, workspace sandboxing, and protected-file
+  preflight remain enforced; the tool reports a focused prerequisite error when Python 3 is unavailable.
+- Existing user artifacts now keep their original path as the canonical output by default. Hara must not
+  invent “完整版”, “简版”, “new”, or similar copies unless the user explicitly requests a separate version.
+  Any temporary binary output used for atomic replacement must be removed on both success and failure.
+- Regression coverage executes Python through stdin, proves no `.py` file is left behind, verifies protected
+  files cannot be reached through the new input path, and pins the in-place/no-suffix/no-helper policy in the
+  agent system prompt. Upgrade with `npm i -g @nanhara/hara@0.133.0`.
+- The transitive `fast-uri` parser is pinned to 3.1.4, closing CVE-2026-16221/GHSA-v2hh-gcrm-f6hx's
+  backslash-authority host-confusion gap before URL policy and network consumers can disagree on a host.
+- `--proxy <url>` and `--lang <tag>` make the existing scoped web proxy and same-language behavior visible
+  at launch. Proxy credentials remain config/environment-only so they never enter the process list. A user
+  who explicitly refers to an older chat (for example “继续上次的任务”) now triggers bounded, audience-safe
+  `session_search` before the model turn; ordinary prompts and explicit opt-outs do not scan transcripts.
+- `web_fetch` identifies SPA shells and can retry with `render:true`. The render path requires computer-use
+  approval, launches an installed Chrome/Chromium/Edge with a fresh temporary profile, and forces every page,
+  redirect, and subresource request through a capped loopback proxy that re-applies public-IP/SSRF checks.
+  Browser cancellation, complete-DOM output, process-tree cleanup, and missing-browser failures are bounded.
+- Package installs can explicitly switch sources with `--registry npmmirror`, global `packageRegistry`, or
+  `bash.registry`. Registry values are injected as environment rather than shell text and reject credentials.
+  Hara does not silently replay an install against a public mirror, because private scopes and supply-chain
+  trust must be preserved; timeout guidance now points to the explicit public-dependency recovery.
+- A truly empty directory (including only `.DS_Store`/`.gitkeep`) no longer asks to generate `AGENTS.md`.
+  The Intel `--cwd` regression now disables update checks and uses a load-tolerant 30-second process ceiling;
+  product behavior remains checked by status/output rather than runner scheduling speed.
+- The TUI composer now keeps one stable Ink input subscription across renders. Rapid follow-up keys (including
+  Up/Down history navigation on slower terminals) can no longer land between paint and listener resubscription
+  and disappear; the handler still observes the latest draft through React 19 Effect Events.
+
 ## 0.132.4 — 2026-07-22 — release-class Intel readiness handshakes
 
 - Non-Git `@path` completion now skips the bounded Git inventory subprocess when no repository marker

package/README.md

@@ -130,6 +130,8 @@ hara config set model    ...
 **Proxy for web tools in mainland/restricted networks** — only `web_fetch` and `web_search` use it:
 ```bash
 export HTTPS_PROXY=http://127.0.0.1:7890
+# or for one Hara launch (do not put credentials in command-line arguments):
+hara --proxy http://127.0.0.1:7890
 # or persist the same endpoint privately:
 hara config set proxy http://127.0.0.1:7890
 ```
@@ -138,6 +140,24 @@ organization enrollment, and chat gateways are not silently redirected. Even thr
 pins each DNS-approved public IP and rechecks redirects; authenticated proxy URLs are masked by
 `hara config get`.
 
+When `web_fetch` receives only a JavaScript SPA shell, it tells the agent to retry with `render:true`.
+That path asks for computer-use approval, uses an installed Chrome/Chromium/Edge with a fresh temporary
+profile, and routes every browser request back through the same private-IP/redirect guard. Set
+`HARA_BROWSER_PATH` only when the browser executable is installed in a non-standard location.
+
+**Package registry for slow/restricted npm networks** — switching is explicit, so Hara never sends a
+private scope to a public mirror without your decision:
+```bash
+hara --registry npmmirror             # this launch
+hara config set packageRegistry npmmirror  # persist globally
+```
+The `bash` tool also accepts `registry:"npmmirror"` for one npm/pnpm/yarn/bun install. Use `npmjs`,
+`npmmirror`, or a credential-free HTTP(S) registry URL; keep private-registry authentication in the package
+manager's normal credential store. `HARA_PACKAGE_REGISTRY` is the environment equivalent.
+
+Replies follow the latest user message's language by default. Use `hara --lang zh-CN` (or `en`) to pin one
+launch, and `hara --lang auto` to restore per-message matching.
+
 **Vision** — hara **auto-detects** whether your main model can see images. A vision model (Claude, gpt-4o,
 qwen-vl, glm-4v…) gets pasted images **inline**. For a **text-only** model (DeepSeek, coding models), set a
 describer — the "eyes" — and hara OCRs/describes each pasted image into text first:
@@ -402,7 +422,8 @@ agent.
 ### What it can do
 
 A streaming agentic loop with built-in tools — `read_file`, `write_file`, **`edit_file`** /
-**`apply_patch`** (surgical edits — single file, or **atomic multi-file** changes), `bash`, and
+**`apply_patch`** (surgical edits — single file, or **atomic multi-file** changes), direct-stdin
+**`python`** (one-shot APIs without helper scripts), `bash`, and
 read-only **`grep`** / **`glob`** / **`ls`** / **`web_fetch`** — behind a human-in-the-loop confirmation gate on the
 dangerous ones unless `-y`. Read-only tools run in parallel within a turn, and edits print a
 **colored diff** of what changed. Shell output streams live; press **Esc** to interrupt a running

package/dist/agent/loop.js

@@ -63,9 +63,16 @@ export function needsConfirm(kind, mode) {
         return kind === "exec";
     return true; // suggest: confirm edits and exec
 }
+export function replyLanguageInstruction(env = process.env) {
+    const requested = String(env.HARA_REPLY_LANGUAGE ?? "").trim();
+    if (/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8}){0,3}$/u.test(requested)) {
+        return `Reply in ${requested} unless the user explicitly asks for another language;`;
+    }
+    return "Reply in the same language as the user's latest message unless they explicitly ask for another language;";
+}
 const HARA_SYSTEM = () => `You are hara, a coding agent running in the user's terminal.
-Be concise and direct. Reply in the same language as the user's latest message unless they explicitly
-ask for another language; keep code, commands, paths, and technical identifiers unchanged. Use the
+Be concise and direct. ${replyLanguageInstruction()} keep code, commands, paths, and technical identifiers
+unchanged. Use the
 provided tools to read files, edit/write files, and run shell
 commands. Prefer small, verifiable steps; edit existing files with edit_file rather than rewriting
 them whole. Batch INDEPENDENT tool calls in a single response — especially reads (read_file / grep /
@@ -76,6 +83,12 @@ grep/glob; don't read whole large files when a targeted search answers the quest
 grep to locate then read_file just that region with offset/limit — not the whole file. After a successful
 edit_file/write_file do NOT re-read the file to verify — the tool already applied and diffed the change;
 re-reading a big file after every edit is the slowest habit an agent can have.
+When editing an existing user artifact, including a DOCX, keep its original path as the canonical output
+and replace it in place by default. Do not invent suffix copies such as "完整版", "简版", or "new" unless
+the user explicitly asks to save a separate version. For one-shot Python library work such as python-docx,
+call the python tool with source directly; never write a durable helper .py file and then run it. If an
+atomic binary save needs a temporary output, remove it in finally/on failure and leave only the requested
+document when the task completes.
 When an attempt FAILS, never repeat it unchanged — read the error, form a hypothesis about the cause, and
 change something (arguments / approach / tool) before trying again. After two failed variants of the same
 approach, stop: re-plan from what you learned, or ask the user, stating concisely what you tried and what

package/dist/config.js

@@ -76,7 +76,7 @@ export function providerCatalog() {
         ...(PROVIDER_DEFAULTS[id].baseURL ? { defaultBaseURL: PROVIDER_DEFAULTS[id].baseURL } : {}),
     }));
 }
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "runTimeoutMs", "maxAgentRounds", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "proxy", "fallbackModel", "fallbackProvider", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "runTimeoutMs", "maxAgentRounds", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "proxy", "packageRegistry", "fallbackModel", "fallbackProvider", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
 export const REASONING_EFFORTS = ["off", "low", "medium", "high", "max"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
@@ -493,6 +493,8 @@ export function loadConfig(opts = {}) {
     const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
     const updateCheck = !(process.env.HARA_UPDATE_CHECK === "0" || merged.updateCheck === false || merged.updateCheck === "false"); // default ON
     const proxy = typeof merged.proxy === "string" && merged.proxy.trim() ? merged.proxy.trim() : undefined;
+    const packageRegistry = nonBlankEnv(process.env.HARA_PACKAGE_REGISTRY)
+        ?? (typeof merged.packageRegistry === "string" && merged.packageRegistry.trim() ? merged.packageRegistry.trim() : undefined);
     const fallbackModel = nonBlankEnv(process.env.HARA_FALLBACK_MODEL) ?? merged.fallbackModel;
     const requestedFallbackProvider = nonBlankEnv(process.env.HARA_FALLBACK_PROVIDER) ?? merged.fallbackProvider;
     const fallbackProvider = isProviderId(requestedFallbackProvider) ? requestedFallbackProvider : undefined;
@@ -502,7 +504,7 @@ export function loadConfig(opts = {}) {
     const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high", "max"].includes(reasoningRaw)
         ? reasoningRaw
         : undefined;
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, runTimeoutMs, maxAgentRounds, vimMode, autoCompact, fileCheckpoints, updateCheck, proxy, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, runTimeoutMs, maxAgentRounds, vimMode, autoCompact, fileCheckpoints, updateCheck, proxy, packageRegistry, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/context/agents-md.js

@@ -1,6 +1,6 @@
 // Project-context loading (AGENTS.md) — the cross-tool standard read by Codex/Claude Code/OpenClaw.
 // Walks up from cwd to the project root, concatenates AGENTS.md files, caps total size.
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { readModelContextBytePrefixSync } from "../fs-read.js";
 import { homeWorkspaceGuidance, isHomeWorkspace } from "./workspace-scope.js";
@@ -110,6 +110,23 @@ export function hasAgentsMd(cwd) {
     const root = findProjectRoot(cwd);
     return FILENAMES.some((n) => existsSync(join(root, n)));
 }
+/** An empty directory has nothing useful for the init agent to analyze. Do not interrupt first launch with
+ * an AGENTS.md offer until the user has created a project marker or at least one visible project file. */
+export function hasProjectContent(cwd) {
+    const root = findProjectRoot(cwd);
+    try {
+        return readdirSync(root, { withFileTypes: true }).some((entry) => {
+            if (ROOT_MARKERS.includes(entry.name))
+                return true;
+            if (entry.name === ".DS_Store" || entry.name === ".gitkeep")
+                return false;
+            return !entry.name.startsWith(".");
+        });
+    }
+    catch {
+        return false;
+    }
+}
 /** Prompt hara runs against itself to analyze the repo and write AGENTS.md. */
 export const INIT_PROMPT = "Explore this repository to understand it, then write a concise AGENTS.md at the project root.\n" +
     "Use read_file, bash (e.g. `ls`, `git ls-files`, `cat`), and write_file.\n" +

package/dist/exec/jobs.js

@@ -50,7 +50,7 @@ function ensureExitCleanup() {
     process.on("exit", killAllJobs); // sync; runs on normal quit so background jobs don't orphan
 }
 /** Start a background shell job; returns its id immediately. Output is captured to a capped tail buffer. */
-export function startJob(command, cwd, mode) {
+export function startJob(command, cwd, mode, env = {}) {
     ensureExitCleanup();
     const running = [...jobs.values()].filter((job) => job.status === "running" || job.terminationPending).length;
     if (running >= MAX_RUNNING_JOBS) {
@@ -59,7 +59,7 @@ export function startJob(command, cwd, mode) {
     pruneFinishedJobs(1);
     const { cmd, args } = shellCommand(command, cwd, mode);
     const processGroup = platform() !== "win32";
-    const child = spawn(cmd, args, { cwd, env: toolSubprocessEnv(), detached: processGroup });
+    const child = spawn(cmd, args, { cwd, env: toolSubprocessEnv(process.env, env), detached: processGroup });
     const job = {
         id: "j" + ++seq,
         // The raw command may contain an inline --token/KEY=value. It is used only for spawning above; every

package/dist/index.js

@@ -56,6 +56,7 @@ import { listJobs, tailJob, killJob } from "./exec/jobs.js";
 import { readModelContextFileSync } from "./fs-read.js";
 import { MIN_NODE_VERSION, unsupportedNodeMessage } from "./runtime.js";
 import { redactKnownSecrets } from "./security/secrets.js";
+import { normalizePackageRegistry } from "./package-registry.js";
 /** Render the background-job list for /jobs (user-facing view of what the agent has running in the
  *  background — dev servers, watchers, long tasks). Mirrors codex/Claude-Code process visibility. */
 function renderBgJobs() {
@@ -71,7 +72,7 @@ function renderBgJobs() {
     return `Background jobs — /jobs tail <id> · /jobs kill <id>:\n${rows.join("\n")}`;
 }
 import { qwenDeviceLogin, loadQwenToken } from "./providers/qwen-oauth.js";
-import { loadAgentContext, hasAgentsMd, INIT_PROMPT, findProjectRoot } from "./context/agents-md.js";
+import { loadAgentContext, hasAgentsMd, hasProjectContent, INIT_PROMPT, findProjectRoot } from "./context/agents-md.js";
 import { homeWorkspaceActionError, discoverProjectWorkspaces, isUnsafeProjectWorkspace, resolveWorkspaceSwitch, suggestedProjectWorkspace, } from "./context/workspace-scope.js";
 import { getEmbedder } from "./search/embed.js";
 import { collectRepoChunksAsync, collectDirChunksAsync, buildIndex, indexPath, indexExists } from "./search/semindex.js";
@@ -96,7 +97,7 @@ import { scaffoldAssets, assetsDir, assetSearchRoots } from "./recall.js";
 import { c, out, statusLine } from "./ui.js";
 import * as bar from "./statusbar.js";
 import { nearest } from "./fuzzy.js";
-import "./tools/builtin.js"; // register read_file/write_file/bash
+import "./tools/builtin.js"; // register read_file/write_file/python/bash/job
 import "./tools/runtime.js"; // register tool_search/tool_result_read
 import "./tools/edit.js"; // register edit_file
 import "./tools/search.js"; // register grep/glob/ls
@@ -104,7 +105,7 @@ import "./tools/patch.js"; // register apply_patch
 import "./tools/web.js"; // register web_fetch
 import "./tools/agent.js"; // register agent (subagent spawn)
 import "./tools/memory.js"; // register memory_search/get/write/forget/skill_create
-import "./tools/session-search.js"; // register bounded cross-session transcript recall
+import { automaticSessionRecall } from "./tools/session-search.js"; // register + deterministic explicit-cue recall
 import "./tools/skill.js"; // register the skill loader tool
 import "./tools/codebase.js"; // register codebase_search (repo as a knowledge base)
 import "./tools/todo.js"; // register todo_write (inline task checklist)
@@ -1396,6 +1397,9 @@ program
     .option("--profile <id>", "use this identity profile for this run (personal / org id) — see `hara profile list`")
     .option("--overlay <name>", "apply a named config overlay from ~/.hara/config.json (legacy: --profile)")
     .option("--cwd <dir>", "run from this explicit project directory (alternative to cd)")
+    .option("--proxy <url>", "HTTP(S) proxy for web_fetch/web_search in this run (credentials belong in config/env)")
+    .option("--registry <url>", "package registry for installs in this run: npmjs, npmmirror, or an HTTP(S) URL")
+    .option("--lang <tag>", "reply language for this run, for example zh-CN or en (default: follow latest message)")
     .option("-c, --continue", "resume the most recent session in this directory")
     .option("--resume <id>", "resume a specific session by id")
     .option("--sandbox <mode>", "sandbox the shell: off | workspace-write | read-only");
@@ -1419,6 +1423,46 @@ program.hook("preAction", (thisCmd) => {
             process.exit(2);
         }
     }
+    const proxyFlag = thisCmd.opts().proxy;
+    if (proxyFlag) {
+        try {
+            const parsed = new URL(proxyFlag);
+            if (!(parsed.protocol === "http:" || parsed.protocol === "https:")
+                || parsed.pathname !== "/"
+                || parsed.search
+                || parsed.hash
+                || parsed.username
+                || parsed.password)
+                throw new Error("invalid or credential-bearing proxy URL");
+            process.env.HARA_WEB_PROXY = parsed.origin;
+        }
+        catch {
+            out(c.red("Cannot use --proxy: provide an HTTP(S) origin such as http://127.0.0.1:7890. Put authenticated proxy URLs in `hara config set proxy …` or HTTPS_PROXY so credentials do not enter the process list.\n"));
+            process.exit(2);
+        }
+    }
+    const languageFlag = thisCmd.opts().lang;
+    if (languageFlag) {
+        if (languageFlag === "auto")
+            delete process.env.HARA_REPLY_LANGUAGE;
+        else if (/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8}){0,3}$/u.test(languageFlag)) {
+            process.env.HARA_REPLY_LANGUAGE = languageFlag;
+        }
+        else {
+            out(c.red("Cannot use --lang: provide a language tag such as zh-CN or en, or use auto.\n"));
+            process.exit(2);
+        }
+    }
+    const registryFlag = thisCmd.opts().registry;
+    if (registryFlag) {
+        try {
+            process.env.HARA_PACKAGE_REGISTRY = normalizePackageRegistry(registryFlag);
+        }
+        catch {
+            out(c.red("Cannot use --registry: provide npmjs, npmmirror, or an HTTP(S) registry URL without credentials/query/fragment.\n"));
+            process.exit(2);
+        }
+    }
     const flag = thisCmd.opts().profile;
     if (!flag)
         return;
@@ -3173,6 +3217,17 @@ config
             process.exit(1);
         }
     }
+    if (key === "packageRegistry") {
+        try {
+            value = normalizePackageRegistry(value) ?? "";
+            if (!value)
+                throw new Error("empty registry");
+        }
+        catch {
+            out(c.red("Invalid package registry. Use npmjs, npmmirror, or an HTTP(S) URL without credentials, query parameters, or a fragment.\n"));
+            process.exit(1);
+        }
+    }
     if (key === "runTimeoutMs") {
         const parsed = parseAgentRunTimeoutMs(value);
         if (parsed === undefined || parsed < MIN_AGENT_RUN_TIMEOUT_MS || parsed > MAX_AGENT_RUN_TIMEOUT_MS) {
@@ -3667,7 +3722,13 @@ program.action(async (opts) => {
             // Inbound images (gateway): the platform downloaded the user's photo(s) and passed their paths via env.
             // Let the agent actually SEE them — attached inline for a vision-capable main model, else described via the
             // visionModel sidecar and folded into the message (text-only models can't take image blocks).
-            const userText = await expandMentionsAsync(String(opts.print), cwd) + (schemaObj ? STRUCTURED_INSTRUCTION : "");
+            const printText = String(opts.print);
+            const automaticRecall = meta
+                ? await automaticSessionRecall(printText, { cwd, sessionId: meta.id })
+                : "";
+            const userText = (automaticRecall ? `${automaticRecall}\n\n---\n\n` : "")
+                + await expandMentionsAsync(printText, cwd)
+                + (schemaObj ? STRUCTURED_INSTRUCTION : "");
             const inboundImgs = (process.env.HARA_GATEWAY_IMAGES ?? "")
                 .split("\n")
                 .map((s) => s.trim())
@@ -3910,7 +3971,7 @@ program.action(async (opts) => {
     // First-run AGENTS.md offer — classic REPL only. In TUI mode we must NOT call rl.question before ink
     // mounts: a readline question puts stdin in a state ink can't read from, leaving the input box dead
     // (the TUI shows a `/init` tip instead, below). See the `tip` in the runTui header.
-    if (!homeWorkspace && !hasAgentsMd(cwd) && !useTui) {
+    if (!homeWorkspace && !hasAgentsMd(cwd) && hasProjectContent(cwd) && !useTui) {
         const ans = (await rl.question(`${c.dim("No AGENTS.md here — analyze this project and create one?")} ${c.dim("[Y/n]")} `)).trim().toLowerCase();
         if (ans === "" || ans.startsWith("y")) {
             out(c.dim("Analyzing project…\n"));
@@ -4565,7 +4626,7 @@ program.action(async (opts) => {
         // First-run AGENTS.md offer — via a tiny ink prompt, NOT readline. A readline question before the
         // main TUI leaves stdin unreadable by ink (dead input box); ink cleans up on unmount, so the TUI
         // mounted right after gets working input. Runs before mount, like the classic path.
-        if (!homeWorkspace && !hasAgentsMd(cwd)) {
+        if (!homeWorkspace && !hasAgentsMd(cwd) && hasProjectContent(cwd)) {
             if (await askConfirm("No AGENTS.md here — analyze this project and create one?")) {
                 out(c.dim("Analyzing project…\n"));
                 try {
@@ -5183,7 +5244,9 @@ program.action(async (opts) => {
                     const planImg = await resolveImages(images, h);
                     if (planImg.skip)
                         return;
-                    const planContent = (recalledContext ? `${recalledContext}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd, { signal: h.signal }) + (planImg.extraText ?? "");
+                    const automaticRecall = await automaticSessionRecall(line, { cwd, sessionId: meta.id, signal: h.signal });
+                    const recallPrefix = [recalledContext, automaticRecall].filter(Boolean).join("\n\n");
+                    const planContent = (recallPrefix ? `${recallPrefix}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd, { signal: h.signal }) + (planImg.extraText ?? "");
                     const executionContext = beginExecution(line);
                     if (!executionContext)
                         return;
@@ -5299,7 +5362,9 @@ program.action(async (opts) => {
                 const ri = await resolveImages(images, h);
                 if (ri.skip)
                     return;
-                const userContent = (recalledContext ? `${recalledContext}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd, { signal: h.signal }) + (ri.extraText ?? "");
+                const automaticRecall = await automaticSessionRecall(line, { cwd, sessionId: meta.id, signal: h.signal });
+                const recallPrefix = [recalledContext, automaticRecall].filter(Boolean).join("\n\n");
+                const userContent = (recallPrefix ? `${recallPrefix}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd, { signal: h.signal }) + (ri.extraText ?? "");
                 recalledContext = "";
                 const executionContext = beginExecution(line);
                 if (!executionContext)
@@ -5440,7 +5505,9 @@ program.action(async (opts) => {
             continue;
         }
         line = inlineLeadingPath(line, existsSync); // leading dropped file path → @-mention so it's read in
-        const userContent = (recalledContext ? `${recalledContext}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd);
+        const automaticRecall = await automaticSessionRecall(line, { cwd, sessionId: meta.id });
+        const recallPrefix = [recalledContext, automaticRecall].filter(Boolean).join("\n\n");
+        const userContent = (recallPrefix ? `${recallPrefix}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd);
         recalledContext = "";
         const recoveredClassicSteering = consumePendingTaskSteering(task);
         if (recoveredClassicSteering) {

package/dist/package-registry.js

@@ -0,0 +1,43 @@
+/** Explicit package-registry routing for npm/pnpm/yarn/bun installs. Registry switching is user-selected:
+ * silently replaying an install against a public mirror can break private scopes and changes the software
+ * supply-chain trust boundary. */
+export function normalizePackageRegistry(value) {
+    const raw = String(value ?? "").trim();
+    if (!raw)
+        return undefined;
+    const expanded = raw === "npmjs"
+        ? "https://registry.npmjs.org/"
+        : raw === "npmmirror"
+            ? "https://registry.npmmirror.com/"
+            : raw;
+    let url;
+    try {
+        url = new URL(expanded);
+    }
+    catch {
+        throw new Error("package registry must be npmjs, npmmirror, or an absolute HTTP(S) URL");
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:")
+        || !url.hostname
+        || url.username
+        || url.password
+        || url.search
+        || url.hash) {
+        throw new Error("package registry must be an HTTP(S) URL without credentials, query parameters, or a fragment");
+    }
+    if (!url.pathname.endsWith("/"))
+        url.pathname += "/";
+    return url.href;
+}
+export function commandHasPackageRegistry(command) {
+    return /(?:^|\s)--registry(?:=|\s|$)/iu.test(command);
+}
+/** The common npm config variable is honored by npm and pnpm; explicit Yarn/Bun variables cover their
+ * modern clients too. Values are injected as environment, never interpolated into a shell command. */
+export function packageRegistryEnv(registry) {
+    return {
+        NPM_CONFIG_REGISTRY: registry,
+        YARN_NPM_REGISTRY_SERVER: registry,
+        BUN_CONFIG_REGISTRY: registry,
+    };
+}

package/dist/tools/all.js

@@ -2,7 +2,7 @@
 // imports itself; library entries (serve/server.ts, future embedders) import THIS so the registry is
 // never empty when runAgent plans a turn — an unregistered tool is silently unplannable, which shows up
 // as "the model called write_file and nothing happened".
-import "./builtin.js"; // read_file / write_file / bash / job
+import "./builtin.js"; // read_file / write_file / python / bash / job
 import "./runtime.js"; // tool_search / tool_result_read
 import "./edit.js"; // edit_file
 import "./search.js"; // grep / glob / ls

package/dist/tools/builtin.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, platform } from "node:os";
 import { resolve, isAbsolute } from "node:path";
 import { stdout as procOut } from "node:process";
 import { registerTool } from "./registry.js";
@@ -14,8 +14,16 @@ import { startJob, listJobs, tailJob, killJob } from "../exec/jobs.js";
 import { sensitiveFileError, sensitiveShellCommandReason } from "../security/sensitive-files.js";
 import { createToolOutputLineRedactor, redactToolSubprocessOutput } from "../security/subprocess-env.js";
 import { isReadOnlyCommand, splitCompound } from "../security/permissions.js";
+import { loadConfig } from "../config.js";
+import { commandHasPackageRegistry, normalizePackageRegistry, packageRegistryEnv } from "../package-registry.js";
 import { hostsInCommand, isNetworkGitOp, hostFromConnectError, isConnectFailure, markHostUnreachable, isHostUnreachable, unreachableHostsSnapshot, } from "./net-reachability.js";
 const MAX = 100_000;
+const MAX_PYTHON_SOURCE_BYTES = 500_000;
+/** Python source is delivered over stdin, so one-shot library operations never need a durable helper
+ *  script. Keep the command itself fixed: model-authored source must not be interpolated into a shell. */
+export function pythonStdinCommand(plat = platform()) {
+    return plat === "win32" ? "py -3 -" : "python3 -";
+}
 /** Package installs are network-bound and routinely exceed the ordinary foreground cap. */
 export function isPackageInstallCommand(command) {
     return /(?:^|[;&|]\s*)(?:npm\s+(?:i|install|ci)\b|pnpm\s+(?:i|install|add)\b|yarn(?:\s+(?:install|add))?(?:\s|$)|bun\s+(?:i|install|add)\b)/i.test(command.trim());
@@ -149,7 +157,9 @@ registerTool({
 });
 registerTool({
     name: "write_file",
-    description: "Create or overwrite a UTF-8 text file (creates parent directories).",
+    description: "Create or overwrite a UTF-8 text file (creates parent directories). This is text-only: do not use " +
+        "it for binary Office files or merely to save a one-shot Python helper before executing it; send " +
+        "one-shot Python source directly to the python tool instead.",
     input_schema: {
         type: "object",
         properties: {
@@ -200,6 +210,54 @@ registerTool({
         return `Wrote ${String(input.content).length} chars to ${p}` + (committed.warnings?.length ? ` Warning: ${committed.warnings.join("; ")}` : "");
     },
 });
+registerTool({
+    name: "python",
+    description: "Execute Python 3 source directly from this tool input over stdin; no .py helper file is created. " +
+        "Prefer this for one-shot library APIs such as python-docx. When editing an existing user document, " +
+        "keep the original path as the canonical output unless the user explicitly requests a copy/version. " +
+        "Use a temporary output only for atomic replacement and remove it in finally/on failure.",
+    input_schema: {
+        type: "object",
+        properties: {
+            code: { type: "string", description: "Python 3 source executed from stdin, never written to a .py file" },
+            timeout_ms: { type: "number", description: "default 300000 (5 min), bounded to 1s..1h" },
+        },
+        required: ["code"],
+    },
+    kind: "exec",
+    requiresProjectWorkspace: true,
+    async run(input, ctx) {
+        if (typeof input.code !== "string" || !input.code.trim()) {
+            return "Error: python `code` must be a non-empty string. Nothing executed.";
+        }
+        if (Buffer.byteLength(input.code, "utf8") > MAX_PYTHON_SOURCE_BYTES) {
+            return `Error: python source exceeds ${MAX_PYTHON_SOURCE_BYTES} bytes. Split the operation into smaller direct calls; do not create a helper script.`;
+        }
+        const protectedReason = sensitiveShellCommandReason(input.code, ctx.cwd);
+        if (protectedReason) {
+            return (`Blocked: Python source crosses Hara's protected secret boundary (${protectedReason}). ` +
+                "This deny is not bypassed by direct stdin execution or full-auto.");
+        }
+        const command = pythonStdinCommand();
+        try {
+            const result = await runShell(command, ctx.cwd, ctx.sandbox ?? "off", {
+                timeout: shellTimeoutMs(command, input.timeout_ms),
+                maxBuffer: 1_000_000,
+                signal: ctx.signal,
+                input: input.code,
+            });
+            const rendered = redactToolSubprocessOutput(capHeadTail([result.stdout, result.stderr].filter(Boolean).join("\n"))).trim();
+            return rendered ? `Python completed without creating a helper script.\n${rendered}` : "Python completed without creating a helper script.";
+        }
+        catch (error) {
+            const rendered = redactToolSubprocessOutput(capHeadTail([error?.stdout, error?.stderr].filter(Boolean).join("\n"))).trim();
+            if (error?.code === 127) {
+                return "Error: Python 3 is not available on PATH. Install Python 3 and the required library, then retry; no helper script was created.";
+            }
+            return `Python failed: ${error?.message ?? String(error)}.${rendered ? `\n${rendered}` : ""}`;
+        }
+    },
+});
 registerTool({
     name: "bash",
     description: "Run a shell command in the working directory; returns combined stdout/stderr.",
@@ -209,6 +267,7 @@ registerTool({
             command: { type: "string" },
             timeout_ms: { type: "number", description: "default 300000 (5 min), or 900000 (15 min) for package installs; bounded to 1s..1h" },
             background: { type: "boolean", description: "run as a background job (dev server, watcher, long task); package installs stay foreground unless explicitly requested" },
+            registry: { type: "string", description: "for package installs only: npmjs, npmmirror, or an HTTP(S) registry URL; injected as environment, never shell text" },
         },
         required: ["command"],
     },
@@ -228,6 +287,25 @@ registerTool({
         if (input.background !== undefined && typeof input.background !== "boolean") {
             return "Error: `background` must be a boolean (true or false), not a string or another truthy value.";
         }
+        const packageInstall = isPackageInstallCommand(String(input.command ?? ""));
+        if (input.registry !== undefined && typeof input.registry !== "string") {
+            return "Error: `registry` must be a string such as npmmirror or https://registry.npmjs.org/.";
+        }
+        if (input.registry !== undefined && !packageInstall) {
+            return "Error: `registry` applies only to npm/pnpm/yarn/bun install commands.";
+        }
+        if (input.registry !== undefined && commandHasPackageRegistry(String(input.command ?? ""))) {
+            return "Error: choose one package-registry control: remove either bash.registry or the command's --registry argument.";
+        }
+        let registry;
+        if (packageInstall && !commandHasPackageRegistry(String(input.command ?? ""))) {
+            try {
+                registry = normalizePackageRegistry(input.registry ?? loadConfig({ cwd: ctx.cwd }).packageRegistry);
+            }
+            catch (error) {
+                return `Error: invalid package registry: ${error?.message ?? "unsupported value"}. Nothing executed.`;
+            }
+        }
         const protectedReason = sensitiveShellCommandReason(String(input.command ?? ""), ctx.cwd);
         if (protectedReason) {
             return (`Blocked: shell command crosses Hara's protected secret boundary (${protectedReason}). ` +
@@ -238,9 +316,11 @@ registerTool({
                 "Configure ngrok authentication first, then retry. Do not rotate through other tunnel providers blindly; ask the user which authenticated provider to use.");
         }
         if (input.background) {
-            const id = startJob(input.command, ctx.cwd, ctx.sandbox ?? "off");
+            const id = startJob(input.command, ctx.cwd, ctx.sandbox ?? "off", registry ? packageRegistryEnv(registry) : {});
             const safeCommand = redactToolSubprocessOutput(String(input.command));
-            return `Started background job ${id}: \`${safeCommand}\`. Manage with the \`job\` tool — {action:"tail",id:"${id}"} for output, {action:"kill",id:"${id}"} to stop, {action:"list"} for all. Poll until it exits before running steps that depend on it.`;
+            return `Started background job ${id}: \`${safeCommand}\`.` +
+                (registry ? " Explicit package registry override applied." : "") +
+                ` Manage with the \`job\` tool — {action:"tail",id:"${id}"} for output, {action:"kill",id:"${id}"} to stop, {action:"list"} for all. Poll until it exits before running steps that depend on it.`;
         }
         // Network fault tolerance — short-circuit if this command targets a host already found unreachable this
         // session, so a repeat doesn't burn another ~75s OS connect timeout. Only pays the git-remote lookup
@@ -278,10 +358,14 @@ registerTool({
                 maxBuffer: 10 * 1024 * 1024,
                 onData: live,
                 signal: ctx.signal,
+                ...(registry ? { env: packageRegistryEnv(registry) } : {}),
             });
             flushLive();
             const combined = (stdout || "") + (stderr ? `\n[stderr]\n${stderr}` : "");
-            return capHeadTail(redactToolSubprocessOutput(combined.trim() || "(no output)"));
+            // The endpoint can be a private hostname/path. Confirmation is useful, but echoing it back into the
+            // model transcript is unnecessary and may expose organization-specific routing metadata.
+            const notice = registry ? "hara: explicit package registry override applied\n" : "";
+            return capHeadTail(redactToolSubprocessOutput(notice + (combined.trim() || "(no output)")));
         }
         catch (e) {
             flushLive();
@@ -293,6 +377,11 @@ registerTool({
                     `\n⏱ hara: the command hit its ${timeout}ms cap and was killed. Pick ONE: ` +
                         `a long build/transform → re-run with a larger timeout_ms; a server/watcher → background:true; ` +
                         `a network op (git/curl/npm) → do NOT just retry — check connectivity/proxy or skip this step and tell the user.`;
+                if (packageInstall && !registry && !commandHasPackageRegistry(String(input.command ?? ""))) {
+                    base +=
+                        " For public npm dependencies, an explicit retry may set bash.registry=\"npmmirror\" (or launch with --registry npmmirror). " +
+                            "Hara does not silently redirect installs because private scopes and registry trust must be preserved.";
+                }
             }
             // Network fault tolerance — if this was a genuine host-unreachability (connect timeout / DNS, NOT
             // auth / 404 / connection-refused), remember the host so we fast-fail future ops to it this session.

package/dist/tools/headless-web.js

@@ -0,0 +1,417 @@
+// Optional isolated headless rendering for web_fetch. The browser uses a fresh temporary profile and is
+// forced through a loopback validating proxy: every top-level/subresource destination is resolved once,
+// rejected if any answer is private/internal, and connected by the approved IP. This preserves web_fetch's
+// SSRF boundary across JavaScript redirects instead of handing Chrome an unchecked public URL.
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { createServer, request as httpRequest, } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { createConnection } from "node:net";
+import { tmpdir, platform } from "node:os";
+import { delimiter, isAbsolute, join } from "node:path";
+import { connect as tlsConnect } from "node:tls";
+import { terminateSubprocessTree, toolSubprocessEnv } from "../security/subprocess-env.js";
+const MAX_BROWSER_REQUESTS = 192;
+const MAX_BROWSER_BYTES = 64 * 1024 * 1024;
+const MAX_BROWSER_HTML_BYTES = 4 * 1024 * 1024;
+const BROWSER_TIMEOUT_MS = 25_000;
+const BROWSER_SOCKET_TIMEOUT_MS = 12_000;
+function executableCandidates(env, plat) {
+    const explicit = String(env.HARA_BROWSER_PATH ?? "").trim();
+    const fixed = plat === "darwin"
+        ? [
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        ]
+        : plat === "win32"
+            ? [
+                env.ProgramFiles && join(env.ProgramFiles, "Google/Chrome/Application/chrome.exe"),
+                env["ProgramFiles(x86)"] && join(env["ProgramFiles(x86)"], "Google/Chrome/Application/chrome.exe"),
+                env.LOCALAPPDATA && join(env.LOCALAPPDATA, "Google/Chrome/Application/chrome.exe"),
+                env.ProgramFiles && join(env.ProgramFiles, "Microsoft/Edge/Application/msedge.exe"),
+            ]
+            : [
+                "/usr/bin/google-chrome",
+                "/usr/bin/google-chrome-stable",
+                "/usr/bin/chromium",
+                "/usr/bin/chromium-browser",
+                "/usr/bin/microsoft-edge",
+            ];
+    const names = plat === "win32"
+        ? ["chrome.exe", "msedge.exe", "chromium.exe"]
+        : ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge"];
+    const onPath = String(env.PATH ?? "")
+        .split(delimiter)
+        .filter(Boolean)
+        .flatMap((dir) => names.map((name) => join(dir, name)));
+    return [explicit && isAbsolute(explicit) ? explicit : "", ...fixed, ...onPath]
+        .filter((value) => !!value);
+}
+/** Find an already-installed Chromium-family browser. Hara never downloads or mutates a browser install. */
+export function findHeadlessBrowser(env = process.env, plat = platform()) {
+    return executableCandidates(env, plat).find((path) => {
+        try {
+            return existsSync(path);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function safeHeaders(headers) {
+    const result = {};
+    const dropped = new Set([
+        "connection", "proxy-authorization", "proxy-authenticate", "proxy-connection", "keep-alive",
+        "te", "trailer", "transfer-encoding", "upgrade",
+    ]);
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined || dropped.has(name.toLowerCase()))
+            continue;
+        result[name] = value;
+    }
+    return result;
+}
+function proxyAuth(proxy) {
+    if (!proxy.username && !proxy.password)
+        return undefined;
+    return `Basic ${Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`).toString("base64")}`;
+}
+function pinnedAuthority(route, port) {
+    return `${route.family === 6 ? `[${route.address}]` : route.address}:${port}`;
+}
+function parseConnectTarget(authority) {
+    if (!authority || /[\s/@?#]/u.test(authority))
+        throw new Error("invalid CONNECT target");
+    const target = new URL(`https://${authority}`);
+    if (!target.hostname || target.username || target.password || target.pathname !== "/")
+        throw new Error("invalid CONNECT target");
+    return target;
+}
+function requestThroughUpstream(proxyUri, target, route, req, res, countBytes) {
+    const proxy = new URL(proxyUri);
+    if (proxy.protocol !== "http:" && proxy.protocol !== "https:")
+        throw new Error("unsupported upstream proxy");
+    const pinned = new URL(target.href);
+    pinned.hostname = route.family === 6 ? `[${route.address}]` : route.address;
+    pinned.username = "";
+    pinned.password = "";
+    const headers = { ...safeHeaders(req.headers), host: target.host };
+    const auth = proxyAuth(proxy);
+    if (auth)
+        headers["proxy-authorization"] = auth;
+    const options = {
+        protocol: proxy.protocol,
+        hostname: proxy.hostname,
+        port: proxy.port || undefined,
+        method: req.method,
+        path: pinned.href,
+        headers,
+        ...(proxy.protocol === "https:" ? { servername: proxy.hostname } : {}),
+    };
+    const upstream = (proxy.protocol === "https:" ? httpsRequest : httpRequest)(options, (remote) => {
+        res.writeHead(remote.statusCode ?? 502, remote.headers);
+        remote.once("error", () => { if (!res.destroyed)
+            res.end(); });
+        remote.on("data", (chunk) => {
+            if (!countBytes(chunk.length))
+                remote.destroy();
+        });
+        remote.pipe(res);
+    });
+    upstream.setTimeout(BROWSER_SOCKET_TIMEOUT_MS, () => upstream.destroy(new Error("render proxy timeout")));
+    res.once("close", () => upstream.destroy());
+    upstream.once("error", () => {
+        if (!res.headersSent)
+            res.writeHead(502);
+        res.end("render proxy request failed");
+    });
+    req.pipe(upstream);
+}
+function requestDirect(target, route, req, res, countBytes) {
+    const upstream = httpRequest({
+        protocol: "http:",
+        hostname: route.address,
+        family: route.family,
+        port: target.port || 80,
+        method: req.method,
+        path: `${target.pathname}${target.search}`,
+        headers: { ...safeHeaders(req.headers), host: target.host },
+    }, (remote) => {
+        res.writeHead(remote.statusCode ?? 502, remote.headers);
+        remote.once("error", () => { if (!res.destroyed)
+            res.end(); });
+        remote.on("data", (chunk) => {
+            if (!countBytes(chunk.length))
+                remote.destroy();
+        });
+        remote.pipe(res);
+    });
+    upstream.setTimeout(BROWSER_SOCKET_TIMEOUT_MS, () => upstream.destroy(new Error("render destination timeout")));
+    res.once("close", () => upstream.destroy());
+    upstream.once("error", () => {
+        if (!res.headersSent)
+            res.writeHead(502);
+        res.end("render proxy request failed");
+    });
+    req.pipe(upstream);
+}
+async function upstreamTunnel(proxyUri, authority, onSocket) {
+    const proxy = new URL(proxyUri);
+    if (proxy.protocol !== "http:" && proxy.protocol !== "https:")
+        throw new Error("unsupported upstream proxy");
+    const port = Number(proxy.port || (proxy.protocol === "https:" ? 443 : 80));
+    const socket = proxy.protocol === "https:"
+        ? tlsConnect({ host: proxy.hostname, port, servername: proxy.hostname })
+        : createConnection({ host: proxy.hostname, port });
+    onSocket(socket);
+    socket.setTimeout(BROWSER_SOCKET_TIMEOUT_MS, () => socket.destroy(new Error("upstream proxy timeout")));
+    await once(socket, proxy.protocol === "https:" ? "secureConnect" : "connect");
+    const auth = proxyAuth(proxy);
+    socket.write(`CONNECT ${authority} HTTP/1.1\r\nHost: ${authority}\r\n` +
+        (auth ? `Proxy-Authorization: ${auth}\r\n` : "") +
+        "Connection: keep-alive\r\n\r\n");
+    return await new Promise((resolve, reject) => {
+        let buffered = Buffer.alloc(0);
+        const fail = () => reject(new Error("upstream proxy tunnel failed"));
+        const onData = (chunk) => {
+            buffered = Buffer.concat([buffered, chunk]);
+            if (buffered.length > 16 * 1024)
+                return fail();
+            const boundary = buffered.indexOf("\r\n\r\n");
+            if (boundary < 0)
+                return;
+            socket.off("data", onData);
+            socket.off("error", fail);
+            const status = Number(/^HTTP\/\d(?:\.\d)?\s+(\d{3})/iu.exec(buffered.subarray(0, boundary).toString("latin1"))?.[1] ?? 0);
+            if (status < 200 || status >= 300)
+                return fail();
+            socket.setTimeout(BROWSER_TIMEOUT_MS, () => socket.destroy());
+            resolve({ socket, leftover: buffered.subarray(boundary + 4) });
+        };
+        socket.on("data", onData);
+        socket.once("error", fail);
+    }).catch((error) => {
+        socket.destroy();
+        throw error;
+    });
+}
+async function startValidatingProxy(resolveRoute) {
+    const sockets = new Set();
+    let requestCount = 0;
+    let byteCount = 0;
+    let closed = false;
+    const countRequest = () => !closed && ++requestCount <= MAX_BROWSER_REQUESTS;
+    const countBytes = (amount) => !closed && (byteCount += amount) <= MAX_BROWSER_BYTES;
+    const server = createServer(async (req, res) => {
+        if (!countRequest()) {
+            res.writeHead(429);
+            return void res.end("render request budget exceeded");
+        }
+        try {
+            const target = new URL(String(req.url));
+            if (target.protocol !== "http:" || target.username || target.password)
+                throw new Error("invalid proxied URL");
+            const route = await resolveRoute(target);
+            if (route.proxyUri)
+                requestThroughUpstream(route.proxyUri, target, route, req, res, countBytes);
+            else
+                requestDirect(target, route, req, res, countBytes);
+        }
+        catch {
+            res.writeHead(502);
+            res.end("render destination blocked");
+        }
+    });
+    server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+    });
+    server.on("clientError", (_error, socket) => socket.destroy());
+    server.on("connect", async (req, client, head) => {
+        client.on("error", () => { });
+        if (!countRequest()) {
+            client.end("HTTP/1.1 429 Too Many Requests\r\nConnection: close\r\n\r\n");
+            return;
+        }
+        try {
+            const target = parseConnectTarget(String(req.url));
+            const port = Number(target.port || 443);
+            const route = await resolveRoute(target);
+            const authority = pinnedAuthority(route, port);
+            let tunnel;
+            if (route.proxyUri) {
+                tunnel = await upstreamTunnel(route.proxyUri, authority, (socket) => {
+                    sockets.add(socket);
+                    socket.once("close", () => sockets.delete(socket));
+                });
+            }
+            else {
+                const socket = createConnection({ host: route.address, port, family: route.family });
+                sockets.add(socket);
+                socket.once("close", () => sockets.delete(socket));
+                socket.setTimeout(BROWSER_SOCKET_TIMEOUT_MS, () => socket.destroy(new Error("render destination timeout")));
+                await once(socket, "connect");
+                socket.setTimeout(BROWSER_TIMEOUT_MS, () => socket.destroy());
+                tunnel = { socket, leftover: Buffer.alloc(0) };
+            }
+            const remote = tunnel.socket;
+            client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (tunnel.leftover.length)
+                client.write(tunnel.leftover);
+            if (head.length)
+                remote.write(head);
+            // Browsers routinely cancel speculative/subresource tunnels. A pipe destination can then raise EPIPE;
+            // pair the two endpoints explicitly so cancellation is ordinary cleanup, never a Hara process crash.
+            client.on("error", () => remote.destroy());
+            remote.on("error", () => client.destroy());
+            client.once("close", () => remote.destroy());
+            remote.once("close", () => client.destroy());
+            remote.on("data", (chunk) => {
+                if (!countBytes(chunk.length)) {
+                    remote.destroy();
+                    client.destroy();
+                }
+            });
+            client.on("data", (chunk) => {
+                if (!countBytes(chunk.length)) {
+                    remote.destroy();
+                    client.destroy();
+                }
+            });
+            client.pipe(remote);
+            remote.pipe(client);
+        }
+        catch {
+            client.end("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n");
+        }
+    });
+    server.listen(0, "127.0.0.1");
+    await once(server, "listening");
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("could not bind render proxy");
+    return {
+        url: `http://127.0.0.1:${address.port}`,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            for (const socket of sockets)
+                socket.destroy();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+/** Render one page in an isolated profile. This is deliberately optional: callers classify it as computer
+ * use so ordinary read-only web_fetch never starts a JS engine without a user-approved render:true call. */
+export async function renderHeadlessHtml(url, resolveRoute, parentSignal, env = process.env) {
+    const browser = findHeadlessBrowser(env);
+    if (!browser)
+        return { error: "browser-unavailable" };
+    if (parentSignal?.aborted)
+        return { error: "failed" };
+    const profile = mkdtempSync(join(tmpdir(), "hara-headless-web-"));
+    let proxy;
+    let child;
+    let timer;
+    let cancelTree;
+    try {
+        // Keep proxy startup inside the cleanup boundary: a bind/listen failure must not strand the fresh
+        // browser profile created above.
+        proxy = await startValidatingProxy(resolveRoute);
+        const args = [
+            "--headless=new",
+            "--disable-background-networking",
+            "--disable-component-update",
+            "--disable-default-apps",
+            "--disable-extensions",
+            "--disable-sync",
+            "--disable-translate",
+            "--disable-quic",
+            "--disable-dev-shm-usage",
+            "--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
+            "--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1, EXCLUDE ::1",
+            "--metrics-recording-only",
+            "--mute-audio",
+            "--no-default-browser-check",
+            "--no-first-run",
+            "--password-store=basic",
+            "--use-mock-keychain",
+            `--user-data-dir=${profile}`,
+            `--disk-cache-dir=${join(profile, "cache")}`,
+            `--proxy-server=${proxy.url}`,
+            "--proxy-bypass-list=<-loopback>",
+            "--virtual-time-budget=8000",
+            "--dump-dom",
+            url.href,
+        ];
+        const processGroup = platform() !== "win32";
+        child = spawn(browser, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: processGroup,
+            env: toolSubprocessEnv(env, {
+                HARA_BROWSER_PATH: undefined,
+                HARA_WEB_PROXY: undefined,
+                HTTPS_PROXY: undefined,
+                HTTP_PROXY: undefined,
+                https_proxy: undefined,
+                http_proxy: undefined,
+            }),
+        });
+        const result = await new Promise((resolve) => {
+            const chunks = [];
+            let size = 0;
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                parentSignal?.removeEventListener("abort", abort);
+                resolve(value);
+            };
+            const stop = (value) => {
+                if (child && !cancelTree)
+                    cancelTree = terminateSubprocessTree(child, { processGroup, force: true });
+                finish(value);
+            };
+            const abort = () => stop({ error: "failed" });
+            parentSignal?.addEventListener("abort", abort, { once: true });
+            timer = setTimeout(() => stop({ error: "timed-out" }), BROWSER_TIMEOUT_MS);
+            child.stdout.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > MAX_BROWSER_HTML_BYTES)
+                    return stop({ error: "output-too-large" });
+                chunks.push(chunk);
+                // Chrome can keep utility processes/pipes alive briefly after --dump-dom has emitted the complete
+                // document (especially with a validating proxy). The serialized closing tag is the result boundary;
+                // return it immediately and terminate the isolated process tree instead of false-timing-out.
+                const tail = Buffer.concat(chunks.slice(-3)).toString("utf8").slice(-256);
+                if (/<\/html>\s*$/iu.test(tail)) {
+                    if (child && !cancelTree)
+                        cancelTree = terminateSubprocessTree(child, { processGroup, force: true });
+                    finish({ html: Buffer.concat(chunks).toString("utf8") });
+                }
+            });
+            // Browser diagnostics can contain machine-specific paths. Drain but never return them to the model.
+            child.stderr.resume();
+            child.once("error", () => finish({ error: "failed" }));
+            child.once("close", (code) => {
+                if (code !== 0 || !chunks.length)
+                    return finish({ error: "failed" });
+                finish({ html: Buffer.concat(chunks).toString("utf8") });
+            });
+        });
+        return result;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        cancelTree?.();
+        await proxy?.close().catch(() => { });
+        rmSync(profile, { recursive: true, force: true });
+    }
+}

package/dist/tools/session-search.js

@@ -12,6 +12,18 @@ const MAX_AUTO_PROJECT_CANDIDATES = 80;
 const MAX_AUTO_PROJECT_CHARS = 8_000_000;
 const MAX_MESSAGE_SCAN_CHARS = 120_000;
 const MAX_EXCERPT_CHARS = 700;
+const HISTORICAL_REFERENCE = [
+    /(?:之前|以前|上次|前一(?:次|个)|此前|我们前面)(?:的|聊过|讨论过|说过|做过|处理过|提过|那个|那次|任务|问题|方案|对话|会话|项目|内容)?/u,
+    /(?:继续|接着)(?:之前|以前|上次|前一(?:次|个)|此前)(?:的|那个|那次)?/u,
+    /(?:还记得|记不记得|你记得)(?:之前|以前|上次|我们)?/u,
+    /\b(?:previous|prior|earlier|last)\s+(?:chat|session|conversation|time|task|issue|discussion|project)\b/iu,
+    /\b(?:continue|pick up)\s+(?:from|where)\b/iu,
+    /\b(?:do you remember|we (?:discussed|talked about|worked on)|you said before)\b/iu,
+];
+const HISTORICAL_REFERENCE_NEGATION = [
+    /(?:不要|不用|无需|别)(?:查|找|看|搜索|读取|回忆).{0,8}(?:之前|以前|上次|历史|旧会话)/u,
+    /\b(?:do not|don't|dont|no need to)\s+(?:search|read|look at|recall).{0,32}(?:previous|prior|earlier|history|old (?:chat|session))/iu,
+];
 function normalized(value) {
     return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/g, " ").trim();
 }
@@ -23,6 +35,28 @@ export function sessionSearchTerms(query) {
     const terms = lexicalSearchTerms(query);
     return terms.length <= 32 ? terms : [...terms.slice(0, 16), ...terms.slice(-16)];
 }
+/** Only search raw transcripts when the user explicitly points at older work. This makes ordinary turns
+ * deterministic and cheap while fixing the common "continue the task from our previous chat" case without
+ * relying on the model to notice and call session_search itself. Explicit opt-outs always win. */
+export function sessionRecallQuery(messageValue) {
+    const message = String(messageValue ?? "").replace(/\s+/g, " ").trim();
+    if (!message || HISTORICAL_REFERENCE_NEGATION.some((pattern) => pattern.test(message)))
+        return null;
+    if (!HISTORICAL_REFERENCE.some((pattern) => pattern.test(message)))
+        return null;
+    return message.slice(0, 512);
+}
+/** Return an injectable, clearly untrusted recall block, or an empty string when no explicit cue/match
+ * exists. Audience/project enforcement remains centralized in searchSessionHistory. */
+export async function automaticSessionRecall(message, ctx) {
+    const query = sessionRecallQuery(message);
+    if (!query)
+        return "";
+    const result = await searchSessionHistory(query, "auto", 3, ctx);
+    if (result === "(no session matches)" || result.startsWith("Error:") || result.startsWith("Blocked:"))
+        return "";
+    return `Automatic prior-session recall (triggered by the user's explicit historical reference):\n${result}`;
+}
 function visibleMessages(history) {
     const out = [];
     for (const message of history) {

package/dist/tools/web.js

@@ -10,6 +10,7 @@ import { request as httpsRequest } from "node:https";
 import { ProxyAgent, fetch as undiciFetch, request as undiciRequest } from "undici";
 import { wrapUntrusted } from "../security/external-content.js";
 import { loadConfig } from "../config.js";
+import { renderHeadlessHtml } from "./headless-web.js";
 const MAX = 60_000;
 const SEARCH_ATTEMPT_MS = 8_000;
 const SEARCH_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/124.0 Safari/537.36";
@@ -699,22 +700,31 @@ registerTool({
 });
 registerTool({
     name: "web_fetch",
-    description: "Fetch an http(s) URL and return its text content (HTML is reduced to readable text). Read-only. " +
-        "Use for docs, references, or pages the user mentions. Not sandboxed.",
+    description: "Fetch an http(s) URL and return its text content (HTML is reduced to readable text). Ordinary fetches are read-only. " +
+        "For an SPA shell, retry with render=true to use an installed Chromium-family browser in a fresh isolated profile; " +
+        "rendering executes page JavaScript and therefore requires the computer-use approval boundary. Not sandboxed.",
     input_schema: {
         type: "object",
         properties: {
             url: { type: "string", description: "http:// or https:// URL" },
             max_chars: { type: "number", description: "cap on returned text (default 60000)" },
+            render: { type: "boolean", description: "render JavaScript in an isolated headless browser (approval required; use for SPA shells)" },
         },
         required: ["url"],
     },
     kind: "read",
-    concurrencySafe: true,
+    classify(input) {
+        return input?.render
+            ? { effect: "computer", concurrencySafe: false }
+            : { effect: "read", concurrencySafe: true };
+    },
     visibility: "deferred",
     async run(input, ctx) {
         if (ctx.signal?.aborted)
             throw interrupted("web fetch");
+        if (input.render !== undefined && typeof input.render !== "boolean") {
+            return "Error: web_fetch `render` must be true or false.";
+        }
         let url;
         try {
             url = new URL(input.url);
@@ -776,8 +786,35 @@ registerTool({
             if (text.length > cap)
                 text = text.slice(0, cap) + `\n…[truncated ${text.length - cap} chars]`;
             if (/html/i.test(ct) && looksLikeJsRenderedShell(raw, text)) {
+                if (input.render === true) {
+                    const rendered = await renderHeadlessHtml(current, async (target) => {
+                        const approved = await resolvePublicHost(target.hostname);
+                        const proxy = webProxy(target, ctx.cwd);
+                        return { ...approved, ...(proxy ? { proxyUri: proxy.uri } : {}) };
+                    }, signal);
+                    if (ctx.signal?.aborted)
+                        throw interrupted("web fetch");
+                    if (rendered.html) {
+                        let renderedText = htmlToText(rendered.html);
+                        if (renderedText.length > cap) {
+                            renderedText = renderedText.slice(0, cap) + `\n…[truncated ${renderedText.length - cap} chars]`;
+                        }
+                        if (renderedText && !looksLikeJsRenderedShell(rendered.html, renderedText)) {
+                            return `# ${current.href} (rendered in isolated headless browser)\n\n${wrapUntrusted(renderedText, current.href)}`;
+                        }
+                    }
+                    const reason = rendered.error === "browser-unavailable"
+                        ? "No installed Chromium-family browser was found. Install Chrome/Chromium/Edge or set HARA_BROWSER_PATH to its executable."
+                        : rendered.error === "timed-out"
+                            ? "The isolated browser did not finish within 25 seconds."
+                            : rendered.error === "output-too-large"
+                                ? "The rendered DOM exceeded the 4 MiB safety ceiling."
+                                : "The isolated browser finished without usable rendered text.";
+                    return `# ${current.href} (HTTP ${res.status})\n\n${wrapUntrusted(`${text || "(empty shell)"}\n\nHeadless render unavailable: ${reason}`, current.href)}`;
+                }
                 const hint = "This page appears to be JavaScript-rendered; web_fetch received only the SPA shell and does not execute page scripts. " +
-                    "Use an available browser/web skill for the rendered page, or the site's authenticated API/connector (for example the Feishu Docs API).";
+                    "Retry web_fetch with render=true (it uses a fresh isolated browser and requires approval), use an available browser/web skill, " +
+                    "or use the site's authenticated API/connector (for example the Feishu Docs API).";
                 return `# ${current.href} (HTTP ${res.status})\n\n${wrapUntrusted(`${text || "(empty shell)"}\n\n${hint}`, current.href)}`;
             }
             return `# ${current.href} (HTTP ${res.status})\n\n${wrapUntrusted(text || "(empty body)", current.href)}`;

package/dist/tui/InputBox.js

@@ -14,7 +14,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 //      of leaning on ink's soft-wrap of a single <Text>, which mis-aligns wrapped rows against the
 //      "› " prompt gutter and reflows unpredictably as you type.
 import { Box, Text, useInput, useStdout } from "ink";
-import { memo, useMemo, useRef, useState } from "react";
+import { memo, useEffectEvent, useMemo, useRef, useState } from "react";
 import { fileCandidates } from "../context/mentions.js";
 import { imagePathFromPaste } from "../images.js";
 import { vimNormal } from "./vim.js";
@@ -476,7 +476,11 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
         setSel(0);
         setDismissed(false);
     };
-    useInput((input, key) => {
+    // Ink's useInput effect depends on the callback identity. An inline callback therefore tears down and
+    // re-adds the stdin listener after every rendered keystroke; on a loaded/remote terminal, the next key can
+    // arrive after paint but before the passive effect re-subscribes and be lost. Effect Events keep one stable
+    // subscription while reading the latest render state, and are invoked by Ink's effect-owned listener.
+    const handleInput = useEffectEvent((input, key) => {
         if (popupOpen && (key.upArrow || key.downArrow)) {
             const n = candidates.length;
             setSel((s) => (key.downArrow ? (s + 1) % n : (s - 1 + n) % n));
@@ -641,7 +645,8 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
             }
             set(value.slice(0, cursor) + input + value.slice(cursor), cursor + input.length);
         }
-    }, { isActive });
+    });
+    useInput(handleInput, { isActive });
     const gutter = vim && mode === "normal" ? "◆ " : "› ";
     const gutterColor = vim ? (mode === "normal" ? "yellow" : "green") : "cyan";
     // The box borders (1 each side) + paddingX (1 each side) subtract 4 cells; InputLine's deterministic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.132.4",
+  "version": "0.133.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "runtime-bootstrap.cjs"
@@ -81,6 +81,6 @@
     },
     "@hono/node-server": "2.0.11",
     "hono": "4.12.31",
-    "fast-uri": "3.1.3"
+    "fast-uri": "3.1.4"
   }
 }