arisa 4.1.6 → 4.1.10

package/AGENTS.md

@@ -121,7 +121,9 @@ To run a pipe, the agent should:
 Example manual pipe:
 1. `run_tool(openai-transcribe, artifact audio)`
 2. take the returned text `artifactId`
-3. `run_tool(openai-tts, artifact text)` or `send_media_reply(text)`
+3. `run_tool(openai-tts, artifact text)` to generate audio, then `send_artifact(artifactId)` to deliver it (or `run_tool(openai-tts, artifact text, deliver: true)` to generate and send in one step)
+
+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 caption are derived from the artifact (its `delivery` hint, `kind`, and stored name); internal local paths are never exposed. 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`:
@@ -195,6 +197,8 @@ Tools may declare skills in `tool.manifest.json`:
 
 The tool registry resolves these from the installed skills directory and injects them into the tool request as `skills`. `list_tools` exposes the hints and `tool_help` shows their resolution status. Skills are guidance for the agent/tool; they are not separate runtime dependencies.
 
+If a tool executes deterministic logic over skill content, bundle the required skill assets inside the tool package and treat injected `skills` only as an optional override. A catalog tool must still work when the hinted skill is not installed on the target Arisa instance.
+
 ## Safety
 - Prefer tool manifests and CLI help over assumptions.
 - Keep config and runtime data inside the user runtime area through the path helpers above.

package/README.md

@@ -1,6 +1,6 @@
 # Arisa
 
-[Arisa](https://arisa.sh) is a personal Telegram assistant powered by [Pi Agent](https://pi.dev).
+[Arisa](https://arisa.sh) is a personal assistant you talk to through Telegram, powered by [Pi Agent](https://pi.dev).
 
 ## Origin
 
@@ -56,7 +56,7 @@ The result is a toolset shaped by how you actually use the assistant, not by def
 
 ### Telegram input
 - 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 Arisa offers to install one
+- 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
 
 ### Tool model
@@ -82,17 +82,24 @@ That isolation is part of the architecture:
 - one tool can be changed or replaced without tightly coupling the rest of the system
 
 ### Configuration model
-- all runtime state lives under `~/.arisa/`
-- Telegram runtime config is stored in `~/.arisa/state/config.json`
-- artifact index is stored in `~/.arisa/state/artifacts.json`
-- incoming Telegram attachments are stored directly in `~/.arisa/artifacts/`
-- tool-specific secrets/config live in `~/.arisa/tools/<tool>/config.js`
-- user-created tools also live under `~/.arisa/tools/<tool>/`
-- tool runtime temp files and generated outputs live under `~/.arisa/tools/<tool>/` (for example `tmp/` and `out/`)
-- durable files should end up in `~/.arisa/artifacts/`
-- Pi authentication can use either:
-  - an API key entered during bootstrap
-  - or Pi's existing OAuth login when supported, such as `openai-codex`
+All runtime state lives under `~/.arisa/`, split between global state and per-chat state.
+
+Global:
+- runtime config is stored in `~/.arisa/state/config.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>/`
+
+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/`
+- chat-scoped tool config overrides live in `config/tools/<tool>/config.js`
+- ephemeral scratch lives under `tmp/`
+
+Pi authentication can use either:
+- an API key entered during bootstrap
+- or Pi's existing OAuth login when supported, such as `openai-codex`
 
 ## Install globally
 
@@ -129,54 +136,15 @@ Notes:
 
 ## Bootstrap flow
 
-On first run, Arisa will:
-
-1. ask for a Telegram bot token
-2. validate the token and ask whether to continue bootstrap from Telegram (default: yes)
-3. when Telegram setup is selected, show a `https://t.me/<bot>?start=<setup-token>` link
-4. authorize that Telegram chat and continue setup there: Pi provider, model, and Pi auth
-5. ask from Telegram whether Arisa should keep running in background
-6. validate that Pi Agent works
-7. only then start listening to Telegram
-
-Choosing `n` at the Telegram setup prompt keeps the previous CLI-only bootstrap flow.
-
-Arisa does not run a persistent HTTP health server or Telegram webhook; Telegram uses long polling.
-
-Telegram bot tokens can be created with:
-
-- https://t.me/BotFather
-
-## Using Pi authentication
+On first run, Arisa walks you through three steps:
 
-For providers with internal Pi login support, such as Codex, leaving the API key empty during bootstrap will start the internal login flow automatically if no existing auth is found.
+1. Give it a Telegram bot token (create one with [@BotFather](https://t.me/BotFather)) and Arisa validates it.
+2. Continue setup in Telegram (the default): open the link to authorize your chat, then pick the Pi provider, model, and auth, and whether to keep running in the background.
+3. Once Pi is working, Arisa starts listening.
 
-For example, selecting:
+## ChatGPT subscription is enough to run Arisa
 
-- `openai-codex/gpt-5.5`
-
-allows Arisa to authenticate through Pi's Codex OAuth flow instead of requiring a normal OpenAI API key.
-
-## Running model
-
-Arisa keeps one Pi session per authorized Telegram chat.
-
-If a message arrives while Pi Agent is still processing another one:
-
-- the current message keeps running
-- the new message is appended to a queued buffer
-- additional incoming messages are concatenated to that same buffer
-- once the current processing finishes, the buffered messages are sent together as the next prompt
-
-Conceptually:
-
-```txt
-message 1 is processing
-message 2 arrives -> queued
-message 3 arrives -> appended to queued
-message 1 finishes
-queued batch is processed next
-```
+Allows Arisa to authenticate through Pi's Codex OAuth flow instead of requiring a normal OpenAI API key. This means a regular ChatGPT subscription is enough to run Arisa on GPT-5.5, which is powerful and a genuine pleasure to use.
 
 ## Project structure
 
@@ -186,10 +154,16 @@ src/
   transport/    Telegram integration
   core/         agent, tools, artifacts, config
 ~/.arisa/
-  state/
-  artifacts/
-  tools/        installed tools (catalog, user-chosen, or agent-created)
-  tmp/
+  state/              global config, task queue, IPC socket
+    config.json
+    tasks.json
+    tools/<tool>/     global tool state (daemons, caches, tmp)
+  tools/<tool>/       installed tools (catalog, user-chosen, or agent-created)
+  chats/<chatId>/
+    artifacts/        per-chat artifact files
+    state/            artifact index + Pi session
+    config/tools/     chat-scoped tool config overrides
+    tmp/              ephemeral scratch
 ```
 
 The official tool catalog lives in the repository under [`tools/`](https://github.com/clasen/Arisa/tree/main/tools) and is not part of the npm package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "4.1.6",
+  "version": "4.1.10",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",
@@ -35,7 +35,7 @@
   "bugs": {
     "url": "https://github.com/clasen/Arisa/issues"
   },
-  "homepage": "https://github.com/clasen/Arisa#readme",
+  "homepage": "https://arisa.sh",
   "dependencies": {
     "@earendil-works/pi-coding-agent": "^0.79.9",
     "@sinclair/typebox": "^0.34.41",

package/src/core/agent/agent-manager.js

@@ -19,7 +19,7 @@ const arisaToolNames = [
   "list_scheduled_tasks",
   "cancel_scheduled_task",
   "cancel_all_scheduled_tasks",
-  "send_media_reply"
+  "send_artifact"
 ];
 
 function isLocalBaseUrl(value) {
@@ -55,30 +55,31 @@ async function promptAndThrowOnAssistantError(session, prompt) {
   }
 }
 
-function mimeMatches(pattern, mimeType = "") {
-  if (!pattern || !mimeType) return false;
-  if (pattern === mimeType) return true;
-  if (pattern.endsWith("/*")) return mimeType.startsWith(`${pattern.slice(0, -2)}/`);
-  return false;
+function inferDeliveryMethod(artifact) {
+  if (artifact.kind === "audio" || (artifact.mimeType || "").startsWith("audio/")) return "audio";
+  return "document";
 }
 
-function toolSupportsTextInput(tool) {
-  return (tool.input || []).some((input) => mimeMatches(input, "text/plain"));
+function containsAbsolutePath(value) {
+  if (typeof value !== "string") return false;
+  return /(^|\s)(\/[^\s]|[A-Za-z]:[\\/])/.test(value);
 }
 
-function toolProducesAudio(tool) {
-  return (tool.output || []).some((output) => mimeMatches(output, "audio/ogg") || mimeMatches(output, "audio/*"));
+function resolveMediaCaption({ caption, output, method }) {
+  if (caption && !containsAbsolutePath(caption)) return caption;
+  if (method === "document" && output?.fileName) return output.fileName;
+  if (output?.text && !containsAbsolutePath(output.text)) return output.text;
+  if (output?.fileName) return output.fileName;
+  return undefined;
 }
 
-function looksLikeTextToSpeechTool(tool) {
-  return /tts|text.?to.?speech|speech.?audio|speech/i.test(`${tool.name} ${tool.description || ""}`);
-}
-
-function selectMediaReplyTool(toolRegistry) {
-  const tools = toolRegistry.list()
-    .filter(toolSupportsTextInput)
-    .filter(toolProducesAudio);
-  return tools.find(looksLikeTextToSpeechTool) || tools[0] || null;
+async function deliverArtifactToChat({ artifact, telegram, caption, method, logger }) {
+  const resolvedMethod = method || artifact.metadata?.delivery?.method || inferDeliveryMethod(artifact);
+  const fileName = path.basename(artifact.path);
+  const resolvedCaption = resolveMediaCaption({ caption, output: { fileName }, method: resolvedMethod });
+  logger?.log("agent", `deliver artifact ${artifact.id} as ${resolvedMethod}`);
+  await telegram.sendMedia(artifact.path, { method: resolvedMethod, caption: resolvedCaption, filename: fileName });
+  return { method: resolvedMethod, fileName, artifactId: artifact.id };
 }
 
 async function assertDirectory(dir, label) {
@@ -238,7 +239,7 @@ export class AgentManager {
         kind: result.output.kind || "file",
         mimeType: result.output.mimeType || "application/octet-stream",
         source: { type: "tool", toolName: name },
-        metadata: { tool: name }
+        metadata: { tool: name, delivery: result.output.delivery }
       });
       result.output.artifactId = generated.id;
       await unlink(result.output.filePath).catch(() => {});
@@ -337,12 +338,13 @@ export class AgentManager {
       defineTool({
         name: "run_tool",
         label: "Run tool",
-        description: "Run a CLI tool using text input or an artifactId. Inspect the returned status/resolution fields. If a tool reports missing config, ask the user naturally, use set_tool_config, and retry.",
+        description: "Run a CLI tool using text input or an artifactId. Inspect the returned status/resolution fields. If a tool reports missing config, ask the user naturally, use set_tool_config, and retry. Set `deliver: true` to also send the generated file to the chat in one step (only when you want the user to receive it now, not for intermediate pipe steps).",
         parameters: Type.Object({
           name: Type.String(),
           artifactId: Type.Optional(Type.String()),
           text: Type.Optional(Type.String()),
-          args: Type.Optional(Type.Record(Type.String(), Type.String()))
+          args: Type.Optional(Type.Record(Type.String(), Type.String())),
+          deliver: Type.Optional(Type.Boolean())
         }),
         execute: async (_id, params) => {
           let artifact = null;
@@ -362,6 +364,13 @@ export class AgentManager {
             chatId
           });
 
+          if (params.deliver && result.output?.artifactId) {
+            const generated = await chatArtifactStore.get(result.output.artifactId);
+            if (generated?.path) {
+              result.sent = await deliverArtifactToChat({ artifact: generated, telegram, logger: this.logger });
+            }
+          }
+
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             details: result
@@ -417,12 +426,12 @@ export class AgentManager {
         }
       }),
       defineTool({
-        name: "send_media_reply",
-        label: "Send media reply",
-        description: "Run a CLI tool that generates a file and send it to the current Telegram chat using the tool's delivery hint or an explicit method.",
+        name: "send_artifact",
+        label: "Send artifact",
+        description: "Deliver an existing chat artifact to the current Telegram chat. Pass the `artifactId` returned by run_tool or from an inbound file. The delivery method, caption, and filename are derived from the artifact (its delivery hint, kind, and stored name); internal local paths are never exposed. Set `caption` for a visible label, or `method` to override the delivery method. The artifact is not deleted.",
         parameters: Type.Object({
-          text: Type.String(),
-          toolName: Type.Optional(Type.String()),
+          artifactId: Type.String(),
+          caption: Type.Optional(Type.String()),
           method: Type.Optional(Type.Union([
             Type.Literal("voice"),
             Type.Literal("audio"),
@@ -430,36 +439,25 @@ export class AgentManager {
           ]))
         }),
         execute: async (_id, params) => {
-          await this.toolRegistry.load();
-          const selectedTool = params.toolName
-            ? this.toolRegistry.get(params.toolName)
-            : selectMediaReplyTool(this.toolRegistry);
-          if (!selectedTool) {
-            const result = {
-              ok: false,
-              status: "failed",
-              error: params.toolName
-                ? `Tool not found: ${params.toolName}`
-                : "No registered text-to-speech tool can generate an audio reply."
-            };
+          const artifact = await chatArtifactStore.get(params.artifactId);
+          if (!artifact) {
+            const result = { ok: false, status: "failed", error: `Artifact not found: ${params.artifactId}` };
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
           }
-          const toolName = selectedTool.name;
-          this.logger?.log("agent", `send_media_reply via ${toolName}`);
-          const result = await this.toolRegistry.run({
-            name: toolName,
-            request: { text: params.text, args: {} },
-            chatId
-          });
-          if (!result.ok || !result.output?.filePath) {
+          if (!artifact.path) {
+            const result = { ok: false, status: "failed", error: `Artifact ${params.artifactId} has no file to deliver.` };
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
           }
-          const method = params.method || result.output?.delivery?.method || "audio";
-          await telegram.sendMedia(result.output.filePath, { method, caption: params.text });
-          await unlink(result.output.filePath).catch(() => {});
+          const sent = await deliverArtifactToChat({
+            artifact,
+            telegram,
+            caption: params.caption,
+            method: params.method,
+            logger: this.logger
+          });
           return {
-            content: [{ type: "text", text: `Media sent to Telegram as ${method}.` }],
-            details: { ...result, sent: { method } }
+            content: [{ type: "text", text: `Media sent to Telegram as ${sent.method}.` }],
+            details: { ok: true, sent }
           };
         }
       })

package/src/transport/telegram/bot.js

@@ -77,7 +77,7 @@ function buildPrompt({ ctx, artifact, transcript, toolResult }) {
   parts.push(`Use read/write/edit for file work in the active workspace, bash for bash-compatible commands, and system_shell for native system commands such as PowerShell on Windows.`);
   parts.push(`If you need an Arisa modular CLI tool, use list_tools/tool_help/run_tool.`);
   parts.push(`If a tool config is missing, ask the user naturally and then use set_tool_config.`);
-  parts.push(`If the user wants a generated media reply, use send_media_reply.`);
+  parts.push(`To deliver a file to the chat: run_tool with deliver:true to generate and send in one step, or send_artifact with an existing artifactId (e.g. an inbound file).`);
   return parts.join("\n");
 }
 
@@ -426,9 +426,9 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
 
   function createTelegramSessionBridge(chatId) {
     return {
-      sendMedia: async (filePath, { method = "audio", caption } = {}) => {
+      sendMedia: async (filePath, { method = "audio", caption, filename } = {}) => {
         logger?.log("telegram", `sending ${method} reply for chat ${chatId}`);
-        const input = new InputFile(filePath);
+        const input = new InputFile(filePath, filename || undefined);
         if (method === "voice") return bot.api.sendVoice(chatId, input, { caption });
         if (method === "document") return bot.api.sendDocument(chatId, input, { caption });
         return bot.api.sendAudio(chatId, input, { caption });