@explyt/ai-agent 0.3.2 → 0.4.0-dogfood.2

package/README.md

@@ -17,8 +17,8 @@ explyt update                # install the newer latest, then restart open sessi
 For a one-off pinned run:
 
 ```bash
-npx -y "@explyt/ai-agent@0.3.2"          # start the terminal UI
-npx -y "@explyt/ai-agent@0.3.2" login    # store a provider credential, once
+npx -y "@explyt/ai-agent@0.4.0"          # start the terminal UI
+npx -y "@explyt/ai-agent@0.4.0" login    # store a provider credential, once
 ```
 
 The agent runs with exactly the extensions this build ships with and ignores any
@@ -28,4 +28,4 @@ you get.
 IDE (ACP) integration is not part of this package: it is provided by the Explyt
 managed backend, which the Neo plugin downloads and manages.
 
-Run `npx -y @explyt/ai-agent@0.3.2 --help` for the available options.
+Run `npx -y @explyt/ai-agent@0.4.0 --help` for the available options.

package/THIRD-PARTY-NOTICES.md

@@ -89,7 +89,7 @@ License or other written license agreements with the Company.
   the unmodified `pi-mcp-adapter` entrypoint (`index.ts`) together with the package's
   small runtime helper files, so that Node can load it outside the engine's TypeScript
   loader. The compilation also inlines the package's own runtime dependencies except
-  `recheck`, `@napi-rs/keyring`, `open` and `@modelcontextprotocol/ext-apps`, which npm
+  `recheck`, `@napi-rs/keyring`, `open` and `quickjs-wasi`, which npm
   installs beside it; each inlined package is listed with its copyright notice in the
   generated "Packages compiled into this package's own files" section at the end of this file.
 - The public npm package contains `dist/vendor/pi-tui.js` and `dist/vendor/pi-mcp-adapter-types.js`:
@@ -102,23 +102,19 @@ License or other written license agreements with the Company.
 - The public npm package contains `dist/vendor/pi-web-access.js`, an unobfuscated
   compilation of the unmodified `pi-web-access` entrypoint (`dist/index.js`) carrying the
   package's name, version and licence in a banner, so that its imports of the engine and
-  `typebox` resolve to the product's files under `dist/vendor/`; and small generated files
-  under `dist/vendor/pi-web-access-deps/` that import the package's own installed copy of
-  `@modelcontextprotocol/sdk`. The package's own files are not altered.
-- In the managed backend archive only, `pi-mcp-adapter` is redistributed with one
-  textual modification made at build time: in its `index.ts`, the slash-command alias
-  registered as `pi-mcp` (a second name for the package's `mcp` status command) is
-  renamed to `explyt-mcp`. The command's behavior, the primary `mcp` name, the package's
-  event names and diagnostics are unchanged. The modification is applied by
-  `scripts/build-release.mjs` (`scripts/bundled-command-rename.mjs`) and is documented
-  here as required by the MIT License; the original copyright and license notice above
-  apply to the modified package unchanged. The public npm package does not carry the
-  adapter and therefore carries no modification of it.
+  `typebox` resolve to the product's files under `dist/vendor/`. The package's own files
+  are not altered.
+- In the managed backend archive only, `pi-mcp-adapter` is redistributed as installed
+  from npm; the public npm package does not carry the adapter's files. Any textual
+  modification made at build time is listed below, applied by `scripts/build-release.mjs`
+  (`scripts/mcp-keyring-service.mjs`) and documented here as required by the MIT
+  License; the original copyright and license notice above apply to a modified package
+  unchanged.
 - The public npm package contains `dist/vendor/pi-coding-agent.js`, a generated file that
   re-exports the engine's own bundled entry point by name; it contains no engine code.
 - The formerly bundled `pi-subagents` package was removed by spec 008; references to it in
   older release history are historical and do not describe the current artifact.
-- Seven units of `@earendil-works/pi-coding-agent` 0.84.4 are **copied** (from the TypeScript in
+- Seven units of `@earendil-works/pi-coding-agent` 1.1.0 are **copied** (from the TypeScript in
   the shipped sourcemaps' `sourcesContent`) into `extensions/bash/engine/` under spec 006
   (RQ-37) — `killProcessTree` into `packages/shared/src/process/`, where spec 008's children
   share it; the whitespace-normalized originals sit next to each copy as `*.upstream.txt`, and every
@@ -133,7 +129,7 @@ License or other written license agreements with the Company.
     replaced by `join(getAgentDir(), "bin")`.
   - `sanitizeBinaryOutput` — `src/utils/shell.ts` → `sanitize-binary-output.ts`; unmodified.
   - `OutputAccumulator` — `src/core/tools/output-accumulator.ts` → `output-accumulator.ts`;
-    modified: the `os.tmpdir()` spill file is removed.
+    modified: the spill file (and `readFullOutput`, which only reads it back) is removed.
   - `resolveSpawnContext` — `src/core/tools/bash.ts` → `spawn-context.ts`; modified: produces only the
     `PI_*` session variables (`sessionEnvFrom`); the env merge, `spawnHook` and `exposeSessionEnvironment` are gone.
   - `formatOutput` — `src/core/tools/bash.ts` (closure inside `execute`) → `format-preview.ts`; modified:
@@ -650,19 +646,20 @@ Generated at build time. It records the license metadata declared by the npm pac
 this package depends on at runtime; none is bundled into the tarball, npm installs them beside it.
 Consult each package for its complete license text.
 
-- @modelcontextprotocol/ext-apps@1.7.5: license metadata = MIT (installed by npm beside this package)
+- @modelcontextprotocol/sdk@1.32.1: license metadata = MIT (installed by npm beside this package)
 - @mozilla/readability@0.6.0: license metadata = Apache-2.0 (installed by npm beside this package)
-- @napi-rs/keyring@1.3.0: license metadata = MIT (installed by npm beside this package)
+- @napi-rs/keyring@2.1.1: license metadata = MIT (installed by npm beside this package)
 - defuddle@0.19.3: license metadata = MIT (installed by npm beside this package)
 - linkedom@0.16.11: license metadata = ISC (installed by npm beside this package)
 - minimatch@10.2.6: license metadata = BlueOak-1.0.0 (installed by npm beside this package)
 - model-probe@0.6.0: license metadata = MIT (installed by npm beside this package)
 - open@10.2.0: license metadata = MIT (installed by npm beside this package)
 - p-limit@6.2.0: license metadata = MIT (installed by npm beside this package)
-- pi-mcp-adapter@2.31.0: license metadata = MIT (installed by npm beside this package)
-- pi-web-access@0.31.0: license metadata = MIT (installed by npm beside this package)
+- pi-mcp-adapter@5.2.0: license metadata = MIT (installed by npm beside this package)
+- pi-web-access@0.39.0: license metadata = MIT (installed by npm beside this package)
 - promise.try@2.0.2: license metadata = MIT (installed by npm beside this package)
-- recheck@4.5.0: license metadata = MIT (installed by npm beside this package)
+- quickjs-wasi@3.6.2: license metadata = MIT (installed by npm beside this package)
+- recheck@4.6.0-beta.3: license metadata = MIT (installed by npm beside this package)
 - semver@7.8.5: license metadata = ISC (installed by npm beside this package)
 - turndown@7.2.4: license metadata = MIT (installed by npm beside this package)
 - unbash@5.0.0: license metadata = ISC (installed by npm beside this package)
@@ -670,9 +667,9 @@ Consult each package for its complete license text.
 - unpdf@1.8.1: license metadata = MIT (installed by npm beside this package)
 - yaml@2.9.0: license metadata = ISC (installed by npm beside this package)
 - yauzl@3.4.0: license metadata = MIT (installed by npm beside this package)
-- typebox@1.3.24: license metadata = MIT (compiled into dist/vendor/typebox)
+- typebox@1.3.27: license metadata = MIT (compiled into dist/vendor/typebox)
 - model-probe@0.6.0: license metadata = MIT (compiled into dist/vendor/model-probe)
-- pi-web-access@0.31.0: license metadata = MIT (compiled into dist/vendor/pi-web-access.js)
+- pi-web-access@0.39.0: license metadata = MIT (compiled into dist/vendor/pi-web-access.js)
 
 ## Packages compiled into this package's own files
 
@@ -680,13 +677,17 @@ Generated at build time from the packages each compiled, unobfuscated file inlin
 directories do not ship, so their copyright notices are reproduced here; the full text of
 each licence named is under "Full License Texts" above.
 
-- @earendil-works/pi-tui@0.84.4, MIT, compiled into dist/vendor/pi-tui.js
+- @earendil-works/pi-tui@1.1.0, MIT, compiled into dist/vendor/pi-tui.js
   - Copyright (c) 2025 Mario Zechner
-  - notice recorded from https://github.com/earendil-works/pi/blob/v0.84.4/LICENSE (the package ships none)
-- @modelcontextprotocol/client@2.0.0, MIT, compiled into dist/mcp-adapter.js
+  - notice recorded from https://github.com/earendil-works/pi/blob/v1.1.0/LICENSE (the package ships none)
+- @modelcontextprotocol/client@2.3.1, Apache-2.0, compiled into dist/mcp-adapter.js
   - Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
-- @modelcontextprotocol/core@2.0.0, MIT, compiled into dist/mcp-adapter.js
+- @modelcontextprotocol/core@2.3.1, Apache-2.0, compiled into dist/mcp-adapter.js
   - Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
+- @modelcontextprotocol/ext-tasks@0.1.0, Apache-2.0, compiled into dist/mcp-adapter.js
+  - Copyright 2025 The Model Context Protocol Authors
+- @typesafe-ai/sdk@0.6.0, MIT, compiled into dist/mcp-adapter.js
+  - Copyright (c) 2026 TypeSafe
 - ajv-formats@3.0.1, MIT, compiled into dist/mcp-adapter.js
   - Copyright (c) 2020 Evgeny Poberezkin
 - ajv@8.20.0, MIT, compiled into dist/mcp-adapter.js
@@ -716,7 +717,7 @@ each licence named is under "Full License Texts" above.
   - Copyright (c) 2018 Filip Skokan
 - json-schema-traverse@1.0.0, MIT, compiled into dist/mcp-adapter.js
   - Copyright (c) 2017 Evgeny Poberezkin
-- marked@18.0.5, MIT, compiled into dist/vendor/pi-tui.js
+- marked@18.0.11, MIT, compiled into dist/vendor/pi-tui.js
   - Copyright (c) 2018+, MarkedJS (https://github.com/markedjs/)
   - Copyright (c) 2011-2018, Christopher Jeffrey (https://github.com/chjj/)
   - Copyright © 2004, John Gruber
@@ -727,7 +728,7 @@ each licence named is under "Full License Texts" above.
   - Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
 - pend@1.2.0, MIT, compiled into dist/vendor/yauzl.js
   - Copyright (c) 2014 Andrew Kelley
-- pi-mcp-adapter@2.31.0, MIT, compiled into dist/mcp-adapter.js, dist/vendor/pi-mcp-adapter-types.js
+- pi-mcp-adapter@5.2.0, MIT, compiled into dist/mcp-adapter.js, dist/vendor/pi-mcp-adapter-types.js
   - Copyright (c) 2026 Nico Bailon
 - pkce-challenge@5.0.1, MIT, compiled into dist/mcp-adapter.js
   - Copyright (c) 2019
@@ -737,15 +738,17 @@ each licence named is under "Full License Texts" above.
   - Copyright (c) Kevin Mårtensson <kevinmartensson@gmail.com> (github.com/kevva)
 - shebang-regex@3.0.0, MIT, compiled into dist/mcp-adapter.js
   - Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
-- smol-toml@1.9.0, BSD-3-Clause, compiled into dist/mcp-adapter.js
+- smol-toml@1.9.1, BSD-3-Clause, compiled into dist/mcp-adapter.js
   - Copyright (c) Squirrel Chat et al., All rights reserved.
 - strip-json-comments@5.0.3, MIT, compiled into dist/mcp-adapter.js
   - Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+- undici@6.29.0, MIT, compiled into dist/mcp-adapter.js
+  - Copyright (c) Matteo Collina and Undici contributors
 - which@2.0.2, ISC, compiled into dist/mcp-adapter.js
   - Copyright (c) Isaac Z. Schlueter and Contributors
 - yaml@2.9.0, ISC, compiled into dist/vendor/yaml.js
   - Copyright Eemeli Aro <eemeli@gmail.com>
 - yauzl@3.4.0, MIT, compiled into dist/vendor/yauzl.js
   - Copyright (c) 2014 Josh Wolfe
-- zod@4.6.5, MIT, compiled into dist/vendor/zod.js
+- zod@4.6.6, MIT, compiled into dist/vendor/zod.js
   - Copyright (c) 2025 Colin McDonnell

package/agent-docs/README.md

@@ -15,6 +15,8 @@ it. Read the whole file before editing anything it describes.
 | `agents.md` | helper agents and model profiles: where the files live, every field, which model a helper runs on, disabling one |
 | `mcp.md` | MCP servers: the two `mcp.json` files, the entry shape, disabling a server or a tool |
 | `web-search.md` | web search and page fetch: `web-search.json`, where requests go, keys, switching search off, failures |
+| `local-models.md` | models on the user's own machine: the llama.cpp router and `/llama`, other OpenAI-compatible servers |
+| `cache-warming.md` | prompt cache warming: what it costs and saves, which models it works with, `cacheWarming` and how to turn it on |
 | `plugins.md` | Marketplace plugins (dogfood builds only; a stable build has neither this file nor `explyt plugin`): the project manifest, the `explyt plugin` command, plugin values |
 | `telegram.md` | the Telegram remote for terminal sessions (dogfood builds only; a stable build has neither this file nor `/telegram`): setup and pairing, `/telegram` and its subcommands, notifications, its files, what leaves the machine |
 
@@ -58,7 +60,8 @@ dogfood builds only: if `telegram.md` is absent here, this build does not have t
 
 The agent updates itself: the terminal UI checks its channel at most once a day and installs a newer
 version in the background, used from the next start. `explyt update` updates at once, and
-`PI_OFFLINE=1` turns the check off. The update channel and the automatic update switch
+`EXPLYT_OFFLINE=1` turns the check off, together with the engine's own background requests;
+`updates.md` lists what it stops and what still goes out. The update channel and the automatic update switch
 (`updateChannel`, `autoUpdate`) are not `.explyt/` settings: they live in the engine's own
 `settings.json` and are changed with `explyt config`. `updates.md` has the details.
 

package/agent-docs/cache-warming.md

@@ -0,0 +1,62 @@
+# Prompt cache warming
+
+Some model providers cache the beginning of a request — the system prompt, the tools, the
+conversation so far — for a few minutes. A later request that starts the same way reads that part
+from the cache at a fraction of the price. When the cache expires, the next request pays the full
+price for all of it again.
+
+**Cache warming** keeps that cache alive: shortly before it expires, the agent re-sends the last
+request with a one-token answer limit, so the next real request still finds the cache. It is
+**off by default**. Turn it on only when the user asks for it or agrees to it after you explain the
+trade-off below.
+
+## What it costs and what it saves
+
+Every refresh is a **real, billed request** that the user did not make: it is paid at the cache-read
+price for the whole prompt plus one output token. It saves money only when a real request follows
+before the cache would have expired anyway; a refresh that nobody needed is pure cost.
+
+The agent decides each refresh on its own and refreshes only when the expected saving is at least
+$0.05. Refreshes stop one hour after the last real request of a run (30 minutes after it between
+runs), when the conversation changes, or when the mode is switched off. Each real request starts that
+clock again, so a run that keeps sending requests keeps being warmed. Their cost counts toward the
+session's usage; they do not enter the conversation.
+
+It pays off with a large context on an expensive model and long pauses inside a run — a long build,
+long tests, a slow tool — that would otherwise outlive the cache.
+
+## Which models it works with
+
+Only models whose cache lifetime the agent knows. In the built-in model catalogue these are the
+**Anthropic** models (Claude), with a 5-minute cache, or 1 hour when the environment the agent starts
+with sets `EXPLYT_CACHE_RETENTION=long` (`long` is the only value; any other is ignored, and so is the
+engine's own `PI_CACHE_RETENTION` set by hand). For every other provider in the catalogue — OpenAI, Google, Bedrock,
+OpenRouter and the rest — no lifetime is known, so warming does nothing there even when it is on.
+The Explyt AI Agent account models and custom providers are not warmed either: they declare no
+cache lifetime and no price, so a refresh could never be shown to save anything. A Claude model that thinks with a fixed thinking budget (not adaptive
+thinking) is never warmed either, because its cache cannot be refreshed safely.
+
+## Modes
+
+| Value | Meaning |
+|---|---|
+| `"off"` | never refresh (the product default) |
+| `"streaming"` | refresh while the agent is working on a request; stop when it finishes |
+| `"idle"` | also keep refreshing for up to 30 minutes after the last real request, in case the user writes again soon |
+
+`"idle"` costs the most: most refreshes between requests are not followed by a request in time.
+
+## Turning it on or off
+
+The setting is `cacheWarming` in the engine's own settings file, `<root>/agent/settings.json`
+(`updates.md` says where `<root>` is) — **not** `.explyt/settings.json`, and there is no project
+value. Change it with the command, which keeps every other key of that file:
+
+```
+explyt config set cacheWarming streaming
+explyt config set cacheWarming off
+explyt config get cacheWarming
+```
+
+A change applies to sessions started afterwards. `/session` in the terminal shows the current warming
+decision of the session.

package/agent-docs/local-models.md

@@ -0,0 +1,34 @@
+# Local models
+
+There are two ways to run the agent on a model served from the user's own machine or network.
+
+## A llama.cpp router: `/llama`
+
+The agent supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server, which finds
+the GGUF models in a directory and loads or unloads them on demand.
+
+1. Start the router without `--model` (a model on the command line starts single-model mode instead):
+
+   ```bash
+   llama-server --models-dir ~/models --no-models-autoload --jinja --host 127.0.0.1 --port 8080 -ngl 999 -c 32768
+   ```
+
+2. In the terminal, run `/login llama.cpp` and enter the router URL (default `http://127.0.0.1:8080`)
+   and an API key if the router was started with `--api-key`. The environment variables
+   `LLAMA_BASE_URL` and `LLAMA_API_KEY` configure the same without `/login`.
+3. Run `/llama` to load a model (or download one from Hugging Face), then pick it with `/model`.
+
+`/llama` lists the router's models: select an unloaded one to load it, a loaded one to unload it, or
+**Download model…** to search Hugging Face. Loaded and sleeping models appear in `/model`; with
+`--no-models-autoload` a model has to be loaded through `/llama` first. Nothing here deletes model
+files. `/llama` is a terminal command; in an IDE, load the model in the terminal (or start the router
+with autoload) and choose it in the IDE's model list.
+
+When something does not work, check the router first: `curl http://127.0.0.1:8080/health` and
+`curl http://127.0.0.1:8080/models`. No models in `/llama` means the `--models-dir` or its layout is
+wrong; a load that fails or runs out of memory needs a smaller `-c` or another model unloaded.
+
+## Any OpenAI-compatible server: `/custom-provider`
+
+Ollama, LM Studio, vLLM or any other server with an OpenAI-compatible API is added with
+`/custom-provider`, which asks for the address and finds the server's models.

package/agent-docs/mcp.md

@@ -53,6 +53,17 @@ HTTP server uses `url` with optional `headers`.
 | `headers` | object of strings | headers sent with each request |
 | `disabled` | boolean | `true` keeps the definition but does not start the server |
 | `excludeTools` | array of strings | tools of this server the model must not see |
+| `auth` | `{ "provider": "<id>" }` | send the credential stored with `/login` for that model provider as a Bearer token; **not in a project file** |
+
+`auth` with a `provider` is honoured in `~/.explyt/mcp.json` and in the IDE's own session
+request. A project file or a plugin chooses its own server URL, so the product refuses such a
+server there: it is not started, and `/mcp` shows why on its row.
+
+That refusal covers only the credentials of the model providers. It is **not** a boundary for other
+secrets: a project file can still put an environment variable into `headers`, `url` or `env`
+(`${VAR}`), and that value goes to whatever server the file names. Treat a project's `mcp.json` like
+the project's code: do not add a server that sends a secret to a URL you have not checked, and do not
+put a secret the project should not see into the environment the agent starts with.
 
 An entry whose field has the wrong type is skipped with a warning, and the rest of the file still
 loads. A file that is not valid JSON, or whose top level is not an object, contributes no servers

package/agent-docs/plugins.md

@@ -0,0 +1,62 @@
+# Marketplace plugins
+
+## Project activation
+
+Plugins are enabled per project in `.explyt/plugins.json`. Commit the exact plugin version and each MCP server's zero-based `runModes` index; do not put credentials or filesystem paths in this file. An entry without a `version` is reported and ignored, and `enable`, `disable` and `config set-run-mode` drop it when they rewrite the file.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "plugins": {
+    "security-pack": {
+      "version": "1.3.1",
+      "runModes": { "Github MCP": 1 }
+    }
+  }
+}
+```
+
+## Plugin commands
+
+Plugins are managed from a shell in the project directory with `explyt plugin <operation>`. Without a global install, run `npx -y @explyt/ai-agent@<version> plugin <operation>` with the same version as the running agent (`explyt --version`, or the version it was started with). The current directory is the project. The command prints results on stdout and errors on stderr, and exits `0` on success, `1` when an operation fails, and `2` on an argument or usage error: an unknown operation or flag, a missing or extra argument, or an invalid plugin ID, version or run-mode index. Each error names its typed kind, such as `PluginVersionNotInstalled`.
+
+The operations are `install`, `uninstall`, `update`, `enable`, `disable`, `list`, `details`, `verify`, `config set`, and `config set-run-mode`; `explyt plugin help` lists their arguments, shows both values-file shapes and an `enable` example. Plugin activation requires an installed exact version. When enabling a plugin is not a no-op, provide an explicit run-mode choice for every declared MCP server, one `--run-mode <server-name> <index>` each, for example `explyt plugin enable security-pack@1.3.1 --run-mode "Github MCP" 1 --run-mode Local 0`; an existing selection for the same exact version in the current project may be reused. `verify` takes no argument and reports every issue of the plugins the current project enables: a missing or damaged version, an incompatible `minPluginVersion`, and a required value that is not set. The issues are its result: it prints them on stdout and exits `0`, and fails only when the project manifest cannot be read or is invalid.
+
+Before writing a values file or choosing run modes, run `explyt plugin details <plugin-id>@<version> --project` for the installed version. It lists each declared variable with its type, whether it is required, its default and choices, and whether a global or project value is stored (never the value itself), and each MCP server with its run-mode variants by index and the index this project selects. Without a version, or for a version that is not installed, `details` lists no declarations.
+
+No command changes a running session. Changes take effect in a new session, or in a running terminal session after `/reload`. A command run through a tool cannot reload the session it was run from.
+
+## Values and credentials
+
+Credentials and other plugin values stay in the local plugin store, not in the project manifest. Values are first supplied at install time with a JSON object mapping each declared variable ID to a string; a required value that is neither supplied, already stored, nor defaulted fails the install:
+
+```text
+explyt plugin install <plugin-id>[@<version>] --values-file <values-file>
+```
+
+```json
+{ "github_pat": "ghp_...", "mode": "http" }
+```
+
+Later changes go through `config set`:
+
+```text
+explyt plugin config set <plugin-id>@<version> <values-file>
+explyt plugin config set <plugin-id>@<version> --project <values-file>
+```
+
+The first command patches global values; the second patches values for the current project. A project value overrides the global value for that project. The values file for `config set` contains a `values` object and may contain an `unset` array; omitted keys are preserved, and an ID may not be in both:
+
+```json
+{ "values": { "mode": "mcp" }, "unset": ["api_key"] }
+```
+
+A `secret`, `path` or free-form `string` value may be an `${env:NAME}` or `${env:NAME:-fallback}` reference instead of the value itself, which keeps a secret out of the store; it is read from the agent's environment when a session starts.
+
+To remove an installed version, use `explyt plugin uninstall <plugin-id>[@<version>]`. Removing the last installed version also removes that plugin's stored values and per-version `${PLUGIN_DATA}` directories. To change one MCP server's selection for an enabled version, use:
+
+```text
+explyt plugin config set-run-mode <plugin-id>@<version> <server-name> <index>
+```

package/agent-docs/telegram.md

@@ -0,0 +1,171 @@
+# Telegram remote for terminal sessions
+
+The Telegram remote lets the user follow and continue a **terminal** (`explyt`) session from the
+phone: write to the agent, stop it, answer its permission dialogs and questions, and get notified
+when it finishes or fails. It works only in the terminal UI; IDE sessions and subagents do not
+load it. Nothing happens until the user runs `/telegram setup`.
+
+The remote is **not configured in `.explyt/`**. There is no `settings.json` key for it: the user
+sets it up with terminal commands, and its files live in the agent's own directory (below). Do not
+write a token or a Telegram setting into any `settings.json`; nothing reads it there.
+
+## Setting it up
+
+1. The user creates a bot of their own with `@BotFather` in Telegram (`/newbot`) and copies its
+   token. The product has no shared bot and no server of its own: the terminal talks to Telegram
+   directly.
+2. The user turns on **Threaded Mode** for the bot: open @BotFather's mini app (the Open button in
+   the BotFather chat) → the bot → Bot Settings → Threaded Mode. The classic `/mybots` menu does not
+   have this setting. Setup refuses a bot with Threaded Mode off, because a session the user opens
+   gets a topic of its own (topics exist only on demand; see below).
+3. In the terminal: `/telegram setup`. It asks for the token in a masked prompt.
+4. Setup shows a single-use link `https://t.me/<bot>?start=<code>` and a QR code. The user opens it
+   on the phone within 5 minutes and presses Start. The Telegram account that does this becomes the
+   only one that can control the agent. A wrong, expired or used code gets no reply in Telegram;
+   the terminal says to open the newest link from `/telegram setup`. A link from an earlier setup
+   or an earlier terminal run is no longer valid. The link and QR code leave the terminal once the
+   code is used, after 5 minutes, or when the setup is cancelled.
+
+Setup stops and stores nothing when the token is rejected, when Threaded Mode is off, or when the bot
+already has a **webhook** set — that means another program uses the bot, and setup shows the
+webhook URL instead of deleting it. The user should then make a separate bot for the terminal.
+
+Running `/telegram setup` again pairs anew; the old pairing stays until the new one succeeds.
+
+## Terminal commands
+
+The remote has one terminal command, `/telegram`, with subcommands (the terminal completes them):
+
+| Command | Effect |
+|---|---|
+| `/telegram` or `/telegram status` | show the pairing, notifications, presence and connection |
+| `/telegram setup` | set up or re-pair the remote (above) |
+| `/telegram away` | mark the user away, for every terminal session of this user |
+| `/telegram back` | clear the away mark and show what happened remotely while away |
+| `/telegram notify always\|auto\|off` | set the notifications (below) |
+| `/telegram unpair` | disconnect: delete the token and all remote state |
+
+There is no `/away`, `/back` or `/mode` command of the remote; `/mode` in the terminal belongs to
+the permission modes.
+
+The footer shows `telegram: online`, `away` (you are marked away), `off` (notifications off), `offline`, `token revoked`, `conflict` (another
+program polls the same bot) or `not paired`. `online` and `offline` are the view of the terminal that
+polls Telegram, the same in every terminal; `offline` also means no terminal polls. `not paired` shows in every terminal session until
+the first setup, so the remote is discoverable; while not paired the extension makes no network
+call. The away mark lasts until `/telegram back`; typing in the terminal does not clear it.
+
+## Notifications
+
+| Notifications | Permission cards and questions | "Done" and final-error notices | Reply to a run started from Telegram | Progress and `typing…` |
+|---|---|---|---|---|
+| `auto` (default), not away | sent silently, only if the session has a topic | sent silently, only if the session has a topic | sent silently | for every run of a session that has a topic |
+| `auto`, after `/telegram away` | sent with sound (the topic is created if needed) | sent with sound | sent with sound | for every run, silently |
+| `always` | sent with sound (the topic is created if needed) | sent with sound | sent with sound | for every run, silently |
+| `off` | not sent | not sent | not sent | never |
+
+`auto` rings the phone only while you are marked away. While you are at the computer (`auto`, no `/telegram away`), a session you did not open from
+`/sessions` stays out of Telegram entirely. A session that has a topic is watched: every run of
+it, also one you start in the terminal, shows its progress (with `⏹ Stop`) and its answer in the
+topic, silently; the phone rings only after `/telegram away` or with `always`.
+
+A run counts as started from Telegram when a message from the phone reached it (also a steer into
+a running turn); its final answer, or its final error, comes back to the topic.
+
+When a card is sent (see the table), a permission dialog or a question is open in the terminal
+**and** in Telegram at once; the first answer, from either side, wins and closes the other. The Telegram card
+shows what the terminal question shows, in the same order: the effect sentences (or the
+`IRREVERSIBLE:` heading of a once-only action), the command, the shell prefix line when one is
+set, and the folder. It offers exactly the terminal's options: `Allow once`, `Allow for this
+session`, `Reject` — or `Reject`, `Allow once` for a once-only action. `Allow for this session`
+pressed in Telegram records the same session grant as in the terminal. A subagent's permission
+question arrives the same way, as a card in its parent session's topic that names the subagent.
+With `off` the bot still accepts commands and messages.
+
+## In Telegram
+
+The bot works only in its private chat with the paired user; messages from anyone else, forwarded
+or edited messages, and groups are ignored (the bot leaves a group it is added to).
+
+A terminal session has a topic only on demand: you open it from `/sessions`, or it is created
+when the session needs you while you are away (or with `always`) — a permission card, a
+question, or the answer of a run. Opening a terminal creates nothing. When the session ends (the
+terminal closes, `/new`, `/resume` or `/fork`; not `/reload`), its topic is deleted with its
+messages, so the chat lists only sessions that run. After `/new`, `/resume` or `/fork` the delete
+waits a few seconds, so `/resume` back to the same session keeps its topic. If a terminal is killed,
+or Telegram is unreachable when it closes, the delete is not lost: the next running terminal does
+it (the pending deletes live in `state.json`). A card that waited while the session had no topic
+appears once you open the session from `/sessions` or run `/telegram away`. A topic is named `<project> · <session title>`
+(`new session` until the session has a title) and is renamed only when the title changes, because
+Telegram posts a visible "renamed the thread" line for each rename. Agent text is shown with its
+Markdown formatting (code, bold, links). Nothing is pinned.
+
+`/sessions` is a picker of the running sessions, with their state (🟢 running, ⏳ waiting for you,
+💤 idle):
+
+- `☐ <project · title · state>` — a session without a topic; a tap selects it (`☑`).
+- `📂 Open selected (N)` — creates the topics of the selected sessions; each gets a
+  `📍 This session: …` note, so it shows as unread in the chat's topic list. The button answers
+  `Opening N topic(s)…` at once; a session that could not be opened is reported in a message
+  under the list.
+- `💬 <project · title> · open` — a session that has a topic; a tap posts the note there again.
+
+Only one list is active: a new `/sessions` deletes the previous list and the previous `/sessions`
+message (one older than 48 hours is marked `⌛ This list is old` instead).
+
+While a run goes (when the table above shows progress), the bot posts one progress message when
+the run starts and shows `typing…`; cards and replies sent during the run come after it. The
+message shows the elapsed time (it moves every few seconds) and the step number, which is the
+number of tool calls so far. It lists the run's last five tool calls: `▶` while a call runs, `✓`
+once that call ended; calls the agent runs in parallel show `▶` together, and a subagent shows its
+task. It also shows `retry n/m` while the provider is retried, `⏳ Waiting for you` while a card
+waits, and a `⏹ Stop` button that stops that run. When the run ends, the message folds into one
+line (`✓ Done in … · N steps`, `✖ Stopped after …` or `❌ Failed after …`), also after a rate limit
+or a short outage, and the answer arrives as a new message with `Diff` and `History` buttons.
+Turning notifications `off` during a run stops its progress message where it is.
+
+- Plain text in a session topic goes to the agent. While the agent works, it steers the current
+  run, as typing in the terminal does; `/later <text>` queues it for after the run instead.
+- A message older than 10 minutes (for example, sent while the laptop slept) is not run on its
+  own: the bot asks `Run now` or `Discard`.
+- The bot's command menu holds the chat-wide commands: `/sessions`, `/notify always|auto|off`,
+  `/help`, `/unpair`. `/notify off` and `/unpair` from the phone ask for confirmation. Telegram
+  cannot give a topic its own menu, so the session commands are not in the menu; type them in a
+  session topic (`/help` lists them): `/stop`, `/later <text>`, `/history` (recent turns, `Full`
+  sends the whole history as a file), `/diff` (files changed in the session by `edit` and `write`,
+  with a `.diff` file; changes made through `bash` are not counted). The `⏹ Stop` button on the
+  progress message and the `Diff`/`History` buttons on an answer do the same. `/start` is sent by
+  the pairing link's Start button; you never type it.
+- Messages from Telegram appear in the terminal transcript as user messages. The bot posts no
+  "received" reply: `typing…` and the progress message show that the session took the message;
+  only a message the session could not take gets a reply.
+
+A topic you created yourself, or one whose session ended but could not be deleted, answers that
+no session uses it or that the session is closed. The remote works only while a terminal session is running: when the machine sleeps or the
+terminal is closed, nothing answers. With several terminals open, one of them polls Telegram and
+routes messages to the others; if a session is open in two terminals, only the first has the
+remote.
+
+## Where its files are
+
+All of them are in the agent's own directory, under `telegram/`, with mode `0600` (directory
+`0700`):
+
+```text
+<agent dir>/telegram/credentials.json   bot token, bot id and username, paired user id
+<agent dir>/telegram/state.json         mode, away mark, topics of running sessions, topics owed a delete, update offset, the active /sessions list
+<agent dir>/telegram/leader.json        which terminal process polls Telegram
+<agent dir>/telegram/sessions/          running sessions and how to reach them
+<agent dir>/telegram/handled/           update ids already handled, to drop repeats
+```
+
+`<agent dir>` is `$XDG_DATA_HOME/explyt-ai-agent/agent` (default `~/.local/share/explyt-ai-agent/agent`),
+or `PI_CODING_AGENT_DIR` when it is set. Do not edit these files; `/telegram unpair` removes them.
+
+## What leaves the machine
+
+Telegram receives the agent's final answers (cut to 1000 characters), the progress of a run (tool
+names and a short argument of each), permission cards with the command, questions, and — on request —
+history and diffs. Bot chats are **not end-to-end encrypted** and stay on Telegram's servers. A
+user who must not send project code there should keep notifications `off` or not set the remote up. The
+token is never written to logs; anyone who has it can read what the bot receives, so it belongs
+only in the credentials file.

package/agent-docs/updates.md

@@ -33,12 +33,38 @@ conflict, and the installer offers to remove it.
 Updates are automatic: the terminal UI checks its channel at most once a day and installs a newer
 version in the background. The new version is used from the next start; the terminal UI then says so,
 and `explyt --continue` resumes the session on it. A running session keeps its version until it exits.
-`explyt update` updates at once. `PI_OFFLINE=1` turns every check off.
+`explyt update` updates at once.
+
+## Offline mode
+
+`EXPLYT_OFFLINE=1` (also `true` or `yes`) in the environment the agent starts with turns off these
+requests the agent makes on its own:
+
+- the update check and the background install described above;
+- the engine's own checks at startup and the refresh of the model catalogue — including the model
+  list of the Explyt AI Agent account: after a login, or when the account adds a model, the list stays
+  as it was stored last (on a fresh login, only the free model) until the agent runs without the
+  variable.
+
+Only this variable does it. The engine's own `PI_OFFLINE`, set by hand, keeps the engine offline but
+no longer stops the agent's update check and background install; use `EXPLYT_OFFLINE` instead.
+
+It is not a switch for all network access. These still go out with it set:
+
+- requests the user's work needs: the model provider, web search and page fetch, MCP servers and
+  their sign-in;
+- the product's usage telemetry, which this variable does not control;
+- the Telegram remote, when it is set up: it keeps polling Telegram while it runs;
+- the MCP servers' own background refresh of their tool lists, while those servers are configured.
+
+Set the variable where the agent is started — the shell profile for the terminal, the IDE's
+environment for the IDE — and restart it.
 
 ## The two update settings
 
 They live in the engine's settings file, `<root>/agent/settings.json`, **not** in `.explyt/`. Change them
-with `explyt config`, which keeps every other key of that file:
+with `explyt config`, which keeps every other key of that file (it also sets `cacheWarming`,
+described in `cache-warming.md`):
 
 | Key | Values | Default | Meaning |
 |---|---|---|---|

package/agent-docs/web-search.md

@@ -36,6 +36,7 @@ Every time the product starts, it adds these keys to the file when they are abse
 {
   "provider": ["exa", "duckduckgo"],
   "workflow": "none",
+  "toolActivation": "eager",
   "autoOpenBrowser": false,
   "fetch": { "allowedModes": ["readable", "raw"] },
   "githubClone": { "clonePath": "<os temp dir>/explyt-github-repos" },
@@ -55,6 +56,9 @@ Every time the product starts, it adds these keys to the file when they are abse
 - `provider` is not added when the file already has `provider`, `searchProvider` or `searchRouting`.
 - `workflow` is ignored: every search runs without the browser-based curator and without a
   generated summary, whatever the file says.
+- `toolActivation: "eager"` gives you the four web tools from the first message. Do not change it:
+  with `"auto"` or `"dynamic"` the tools are hidden behind an extra activation step
+  (`web_enable`) that the product does not support.
 - The page-answer mode of `fetch_content` (`answer`) is not available; the tool offers `readable`
   and `raw` only.
 

package/dist/cli/brand-profile.js

@@ -38,11 +38,12 @@ const PROFILE = freeze({
     "repository": "explyt/explyt-ai-agent-distribution"
   },
   "telemetryEndpoint": "https://plugin.explyt.ai/telemetry",
-  "mcpAlias": "explyt-mcp",
   "loginCommand": "explyt login",
   "githubCloneDir": "explyt-github-repos",
   "agentDirEnv": "EXPLYT_CODING_AGENT_DIR",
   "updateCheckEnv": "EXPLYT_UPDATE_CHECK",
+  "offlineEnv": "EXPLYT_OFFLINE",
+  "cacheRetentionEnv": "EXPLYT_CACHE_RETENTION",
   "oauth": {
     "keyringService": "pi-mcp-adapter.oauth",
     "redirectUri": "http://127.0.0.1:34517/callback",