arisa 4.3.5 → 5.1.2

package/AGENTS.md

@@ -3,12 +3,13 @@
 ## Core boundaries
 Arisa core owns transport, sessions, artifacts, and tool orchestration:
 - Telegram transport handles inbound and outbound messaging.
-- Pi Agent keeps one session per authorized chat.
+- Pi Agent keeps one session per authorized chat and is the only active harness.
 - Incoming messages and files (text, voice, photo, document) and generated files become artifacts.
 - The tool registry handles tool discovery, help lookup, config writes, and execution.
 - Tools are isolated packages with their own manifest, entrypoint, and config defaults.
 - No tools ship with the core; installed tools live under `~/.arisa/tools/<toolName>`.
 - The Arisa install directory (your working directory) contains only the core. Never create or install tools inside it.
+- Restart requests use `system_shell` to run `arisa restart`; do not install or create a restart tool.
 
 New capabilities belong in tools by default. Solve requests by creating or editing a tool under `~/.arisa/tools/<toolName>`. Modifying core is the last resort: do it only after confirming the capability cannot be delivered through the tool architecture, explaining why the core change is unavoidable, and receiving explicit user approval.
 
@@ -48,9 +49,10 @@ Each tool declares in `tool.manifest.json`:
 - `skillHints`: optional skills to apply when using or editing the tool
 
 ## Text encoding
-All textual content generated or sent by Arisa or its tools must use UTF-8. This includes text files, assistant-created attachments, tool exports, email bodies, messages, HTTP responses, and API payloads.
+All textual content generated or sent by Arisa or its tools must use UTF-8.
 
-- Text files must start with a UTF-8 byte-order mark (BOM).
+- User-facing text documents and exports in `.txt`, `.md`, or `.csv` format must start with a UTF-8 byte-order mark (BOM).
+- Source code, repository documentation, configuration, manifests, and structured data must use UTF-8 without BOM.
 - Protocol payloads must declare UTF-8 through the protocol's standard mechanism and encode their bytes as UTF-8. For example, email and HTTP text content must use a `Content-Type` with `charset=UTF-8`.
 
 ## Tool-to-Arisa IPC
@@ -74,37 +76,37 @@ const result = await arisa.tools.run({
 }, { timeoutMs: 120_000 });
 ```
 
-The IPC channel is a local socket under `~/.arisa/state`. Every request must include `toolName`; chat-scoped capabilities also require `chatId`. Exposed capabilities are explicit: tools (`run`), artifacts (`createText`, `listRecent`, `get`), tasks (`add`, `list`, `cancel`), agent events (`enqueueEvent`), and runtime paths (`getChatToolStateDir`, `getToolStateDir`, `getChatToolTmpDir`, `getToolTmpDir`, `getChatArtifactsDir`). Do not expose raw `agentManager`, `taskStore`, `artifactStore`, or `toolRegistry` access.
+The IPC channel is a local socket under `~/.arisa/state`. Every request must include `toolName`; chat-scoped capabilities also require `chatId`. Exposed capabilities are explicit: tools (`list`, `help`, `skills`, `setConfig`, `run`), artifacts (`createText`, `listRecent`, `get`, `deliver`), tasks (`add`, `list`, `cancel`, `cancelAll`), agent events (`enqueueEvent`), and runtime paths (`getChatToolStateDir`, `getToolStateDir`, `getChatToolTmpDir`, `getToolTmpDir`, `getChatArtifactsDir`). Do not expose raw `agentManager`, `taskStore`, `artifactStore`, or `toolRegistry` access.
 
 ## Conceptual pipe model
 There are two different moments where pipes can happen:
 
 1. **Pre-reasoning normalization pipes**
-   - These happen before Pi Agent reasons.
-   - Their job is to convert raw inbound media into a form Pi Agent can reason about well.
+   - These happen before the active agent runtime reasons.
+   - Their job is to convert raw inbound media into a form the agent can reason about well.
    - Example: incoming Telegram audio must be transcribed first.
-   - In that case, the transcript becomes the effective user message content for Pi Agent.
-   - Pi Agent should reason over the transcript, not treat the raw audio as the primary message.
+   - In that case, the transcript becomes the effective user message content for the agent.
+   - The agent should reason over the transcript, not treat the raw audio as the primary message.
 
 2. **Reasoned action pipes**
-   - These happen after Pi Agent starts reasoning.
-   - Pi Agent may decide to chain tools to achieve a user goal.
+   - These happen after the agent starts reasoning.
+   - The agent may decide to chain tools to achieve a user goal.
    - Example: text -> TTS audio, or future multi-step workflows.
 
-Not every pipe should be decided by Pi Agent at runtime. Some pipes are part of the transport/input normalization layer and must happen before reasoning.
+Not every pipe should be decided by the agent at runtime. Some pipes are part of the transport/input normalization layer and must happen before reasoning.
 
 ## Telegram inbound pipeline
-- text -> send directly to Pi Agent
-- voice -> transcribe first -> send transcript to Pi Agent
+- text -> send directly to the active agent runtime
+- voice -> transcribe first -> send transcript to the active agent runtime
 - image/document/other media -> keep as artifacts, and add normalization pipes when needed
 
-If inbound media was normalized before reasoning, Pi Agent should use the normalized result as the actual message content.
-For example, if a voice note was transcribed, Pi Agent should answer the meaning of the transcript, not simply return the raw transcript unless the user explicitly asked for transcription.
+If inbound media was normalized before reasoning, the agent should use the normalized result as the actual message content.
+For example, if a voice note was transcribed, the agent should answer the meaning of the transcript, not simply return the raw transcript unless the user explicitly asked for transcription.
 
 ## Telegram outbound replies
 - Short textual replies are sent inline as a normal Telegram message.
 - When a textual reply is too large to read comfortably inline, it is delivered as a generated Markdown artifact instead of a long inline message. The transport handles this automatically in `sendTextReply`: replies over the inline length limit become a `reply-<timestamp>.md` artifact sent as a document.
-- This is a transport-layer concern. Pi Agent should write the full answer it wants to deliver and not pre-split or truncate it to fit the chat; the transport decides between inline text and a Markdown attachment.
+- This is a transport-layer concern. The agent should write the full answer it wants to deliver and not pre-split or truncate it to fit the chat; the transport decides between inline text and a Markdown attachment.
 
 ## How to inspect CLI tools
 Before using a tool, inspect its help:
@@ -152,11 +154,11 @@ Example manual pipe:
 Delivery is generic: any `run_tool` output that produces a file becomes an artifact, and `send_artifact(artifactId)` delivers it to the chat. The delivery method and filename are derived from the artifact (its `delivery` hint, `kind`, and stored name); internal local paths are never exposed. No caption is sent by default: the filename already appears on the attachment, so it is never duplicated into the caption text (which would let Telegram autolink a filename like `example.md` as a URL). A caption is shown only when an explicit one is passed. Tools declare their delivery intent by returning `delivery: { method }` in their output; they do not deliver to the transport themselves. As a shortcut, `run_tool` accepts `deliver: true` to generate and deliver in a single step; use it only when the user should receive the file now, not for intermediate pipe steps.
 
 ## Async event queue flow
-Beyond time-based scheduling, tools can drive an event queue that wakes the agent only when there is something to evaluate. Everything goes through the `asyncTask` (single) or `asyncTasks` (array) field the pipeline already supports; no new Pi tools are needed. The 1s poller drains tasks by `kind`:
+Beyond time-based scheduling, tools can drive an event queue that wakes the agent only when there is something to evaluate. Everything goes through the `asyncTask` (single) or `asyncTasks` (array) field the pipeline already supports; no new native agent tools are needed. The 1s poller drains tasks by `kind`:
 
-- `agent_task`: a scheduled prompt. The poller delivers it as a prompt for Pi to fulfill (time-based work).
+- `agent_task`: a scheduled prompt. The poller delivers it as a prompt for the active runtime to fulfill (time-based work).
 - `poll_tool`: a recurring checker the poller **runs directly as a tool** (no agent turn spent). The poller materializes its output with the same logic as `run_tool`, so any `agent_event` the checker emits is enqueued for the next tick. Its `recurrence` reschedules the next poll.
-- `agent_event`: an incoming event. The poller delivers it as a prompt so Pi evaluates it and decides the next action (it may stay silent).
+- `agent_event`: an incoming event. The poller delivers it as a prompt so the active runtime evaluates it and decides the next action (it may stay silent).
 
 Tasks without a `runAt` fire immediately, so `agent_event` and the first `poll_tool` run on the next tick.
 

package/README.md

@@ -1,16 +1,16 @@
 # Arisa
 
-[Arisa](https://arisa.sh) is a personal assistant you talk to through Telegram, powered by [Pi Agent](https://pi.dev).
+[Arisa](https://arisa.sh) is a personal assistant you talk to through Telegram, powered by Pi Agent and isolated CLI tools.
 
 ## Origin
 
-The initial inspiration was OpenClaw, which has interesting ideas but carries a lot of weight (about **85 MB**, **55 dependencies**) compared to Arisa (**37 kB**, **3 dependencies**): when it generates tools they end up disorganized, and the overall framework feels overloaded.
+The initial inspiration was OpenClaw, which has interesting ideas but carries a lot of weight compared with Arisa's focused core: when it generates tools they end up disorganized, and the overall framework feels overloaded.
 
 The real heart of OpenClaw is Pi Agent: a [minimal terminal coding harness](https://www.youtube.com/watch?v=Dli5slNaJu0) that lets an AI agent reason and act with very little infrastructure. That part is genuinely good.
 
 Telegram bots, on the other hand, work extremely well as a human interface. Simple, reliable, always in your pocket.
 
-So Arisa keeps exactly those two things (Pi Agent & Telegram) and nothing more. No pre-loaded opinions about what the agent should do or which tools it should have. The idea is that the agent builds itself around the user, not the other way around.
+Arisa keeps Telegram as its interface and Pi Agent as its single reasoning harness.
 
 It is designed around a simple idea:
 
@@ -40,7 +40,7 @@ This distinction is important. Some transformations belong to the transport/inpu
 
 ## Zero tools, assembled on demand
 
-A fresh install ships with **zero tools**. The core is only Telegram transport, the Pi Agent reasoning loop, the artifact store, and the tool registry. Out of the box Arisa cannot transcribe audio, browse the web, or speak; it gains each capability only once a tool that provides it is installed.
+A fresh install ships with **zero Arisa modular tools**. The core is Telegram transport, the Pi Agent reasoning loop, the artifact store, and the tool registry. Out of the box Arisa cannot transcribe audio, browse the web, or speak; it gains each capability only once a tool that provides it is installed.
 
 Arisa assembles its own toolset from real use:
 
@@ -58,6 +58,9 @@ The result is a toolset shaped by how you actually use the assistant, not by def
 - text messages go directly to Pi Agent
 - audio/voice messages are transcribed first when a transcription tool is installed, then passed to Pi Agent as text; otherwise the agent is told transcription failed and can offer to install one
 - media is stored as artifacts
+- while a chat is busy, concurrent text steers Pi's active run by default
+- set `telegram.busyMessageMode` to `"queue"` to keep concurrent text messages in order; override one chat with `telegram.chatMeta[chatId].busyMessageMode`
+- media and normalized audio stay queued, and failed steering falls back to the ordered queue
 
 ### Tool model
 No tools ship with the core. All installed tools live under `~/.arisa/tools/<tool-name>`, whether they come from the [official catalog](https://github.com/clasen/Arisa/tree/main/tools), from another source the user chooses, or are created by the agent itself.
@@ -86,7 +89,6 @@ All runtime state lives under `~/.arisa/`, split between global state and per-ch
 
 Global:
 - runtime config is stored in `~/.arisa/state/config.json`
-- Pi OAuth credentials are stored in `~/.arisa/state/pi-auth.json`
 - the scheduled-task queue is stored in `~/.arisa/state/tasks.json`
 - installed tools live under `~/.arisa/tools/<tool>/`, each with a default `config.js` template
 - global tool runtime state (daemons, caches, temp) lives under `~/.arisa/state/tools/<tool>/`
@@ -94,7 +96,7 @@ Global:
 Per chat (`~/.arisa/chats/<chatId>/`):
 - artifact files are stored under `artifacts/`
 - the artifact index is stored in `state/artifacts.json`
-- the Pi session lives under `state/pi-sessions/`
+- Pi sessions live under `state/pi-sessions/<revision>/`
 - chat-scoped tool config overrides live in `config/tools/<tool>/config.js`
 - chat-scoped daemon infrastructure lives in `state/tools/<tool>/daemon/`; persistent tool data stays beside it
 - ephemeral scratch lives under `tmp/`
@@ -105,6 +107,22 @@ Pi authentication can use either:
 - an API key entered during bootstrap
 - or Pi's existing OAuth login when supported, such as `openai-codex`
 
+Automatic context compaction uses Pi's native implementation and can be tuned in `~/.arisa/state/config.json`:
+
+```json
+{
+  "pi": {
+    "compaction": {
+      "enabled": true,
+      "reserveTokens": 120000,
+      "keepRecentTokens": 20000
+    }
+  }
+}
+```
+
+Pi compacts when the context exceeds the model's context window minus `reserveTokens`. The default keeps a large reserve so compaction occurs before Arisa Doctor's context warning on the default model. Set a smaller reserve when using models with substantially smaller context windows. Arisa does not add Telegram commands or compaction notifications.
+
 ## Install globally
 
 ```bash
@@ -123,15 +141,18 @@ Command modes:
 arisa                    # foreground, blocking
 arisa start              # start in background
 arisa stop               # stop background service
+arisa restart            # restart background service, or start it if stopped
 arisa status             # show background service status
 arisa flush              # remove ~/.arisa
 arisa --silent           # run without verbose logs
 ```
 
+Authorized Telegram chats can run the same safe service lifecycle with `/restart`.
+
 Runtime model override (current process only):
 
 ```bash
-arisa --pi.model lmstudio/google/gemma-4-26b-a4b
+arisa --pi.model openai-codex/gpt-5.6
 ```
 
 Notes:
@@ -201,7 +222,7 @@ No "I can't do that" when the thing is realistically buildable.
 
 ## Notes
 
-- `AGENTS.md` defines the project-level behavioral rules for Pi Agent
+- `AGENTS.md` defines the project-level behavioral rules for the active agent runtime
 - `src/transport/telegram/bot.js` builds the per-message runtime prompt
 - tool help is part of the architecture and should be consulted before use when details are unclear
 
@@ -210,7 +231,7 @@ No "I can't do that" when the thing is realistically buildable.
 This is currently a functional V1. The core provides:
 
 - Telegram transport
-- Pi Agent integration
+- Pi Agent session and model integration
 - artifact-based message handling
 - the isolated CLI tool registry (starts empty)
 - pre-reasoning and post-reasoning pipes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "4.3.5",
+  "version": "5.1.2",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",
@@ -28,6 +28,9 @@
   ],
   "author": "Martin Clasen",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.8.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/clasen/Arisa.git"
@@ -39,7 +42,8 @@
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.80.6",
     "@sinclair/typebox": "^0.34.41",
-    "grammy": "^1.42.0"
+    "grammy": "^1.42.0",
+    "typebox": "1.1.38"
   },
   "scripts": {
     "start": "node src/index.js",

package/pnpm-workspace.yaml

@@ -8,6 +8,7 @@ minimumReleaseAgeExclude:
   - '@earendil-works/pi-tui@0.80.6'
 
 overrides:
+  'node-fetch@2.7.0>whatwg-url': '13.0.0'
   '@protobufjs/utf8@<=1.1.0': '>=1.1.1'
   basic-ftp@<=5.2.1: '>=5.2.2'
   basic-ftp@<=5.2.2: '>=5.3.0'