arisa 3.0.9 → 3.0.11

package/README.md

@@ -1,6 +1,6 @@
 # Arisa
 
-Arisa is a personal Telegram assistant powered by Pi Agent.
+Arisa is a personal Telegram assistant powered by [Pi Agent](https://pi.dev).
 
 ## Origin
 
@@ -64,13 +64,6 @@ That isolation is part of the architecture:
 - each tool can have its own dependencies
 - one tool can be changed or replaced without tightly coupling the rest of the system
 
-Each tool must support:
-
-```bash
-node index.js --help
-node index.js run --request-file <json>
-```
-
 ### Configuration model
 - all runtime state lives under `~/.arisa/`
 - Telegram runtime config is stored in `~/.arisa/state/config.json`
@@ -108,6 +101,17 @@ arisa install <source>   # install a Pi package into Arisa's runtime
 arisa remove <source>    # remove a Pi package from Arisa's runtime
 ```
 
+## Experimental features
+
+### Pi Agent packages
+
+Arisa can install **Pi Agent packages** from the public registry into your user runtime (`~/.arisa/`), using the same package manager as Pi Agent. Browse and discover packages at [pi.dev/packages](https://pi.dev/packages).
+
+- `arisa install <source>` installs a package (by registry name or other source supported by Pi).
+- `arisa remove <source>` removes a previously installed package.
+
+Treat this as **experimental**: the registry, package formats, and install behavior follow Pi Agent and may change. Not every listed package is tailored to Arisa’s Telegram transport and artifact-based tools; prefer packages you understand and verify after install.
+
 ## Bootstrap flow
 
 On first run, Arisa will:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "3.0.9",
+  "version": "3.0.11",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",
@@ -27,6 +27,7 @@
     "zeroclaw",
     "jarvis",
     "AGENTS.md",
+    "pi.dev",
     "clasen"
   ],
   "author": "",

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

@@ -123,7 +123,7 @@ export class AgentManager {
       defineTool({
         name: "run_tool",
         label: "Run tool",
-        description: "Run a CLI tool using text input or an artifactId. If config is missing, ask the user naturally and then use set_tool_config.",
+        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.",
         parameters: Type.Object({
           name: Type.String(),
           artifactId: Type.Optional(Type.String()),

package/src/core/tools/tool-registry.js

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { getToolConfigPath, getToolTmpDir, toolsDir as userToolsRoot } from "../../runtime/paths.js";
 import { loadToolConfig, parseConfigModule, writeToolConfig } from "./tool-config.js";
+import { normalizeToolResult } from "./tool-result.js";
 
 const bundledToolsRoot = fileURLToPath(new URL("../../../tools", import.meta.url));
 const toolRoots = [
@@ -117,15 +118,16 @@ export class ToolRegistry {
     await unlink(requestFile).catch(() => {});
     try {
       const parsed = JSON.parse(result.stdout || result.stderr);
-      this.logger?.log("tools", `${name} -> ${parsed.ok === false ? "error" : "ok"}`);
-      return parsed;
+      const normalized = normalizeToolResult(name, parsed);
+      this.logger?.log("tools", `${name} -> ${normalized.ok === false ? normalized.status || "error" : "ok"}`);
+      return normalized;
     } catch {
-      return {
+      return normalizeToolResult(name, {
         ok: false,
         error: `Invalid tool response for ${name}`,
         stdout: result.stdout,
         stderr: result.stderr
-      };
+      });
     }
   }
 }

package/src/core/tools/tool-result.js

@@ -0,0 +1,71 @@
+export function toolOk(output = {}, extra = {}) {
+  return { ok: true, output, ...extra };
+}
+
+export function toolError(error, extra = {}) {
+  return {
+    ok: false,
+    status: extra.status || "failed",
+    error,
+    ...extra
+  };
+}
+
+export function toolNeedsConfig({ tool, missingConfig = [], configPath, message } = {}) {
+  return {
+    ok: false,
+    status: "needs_config",
+    error: message || `Missing tool configuration${tool ? ` for ${tool}` : ""}.`,
+    missingConfig,
+    configPath,
+    resolution: {
+      type: "user_config_required",
+      tool,
+      missingConfig,
+      configPath
+    }
+  };
+}
+
+export function normalizeToolResult(name, result = {}) {
+  if (!result || typeof result !== "object") {
+    return toolError(`Invalid tool response for ${name}`);
+  }
+
+  if (result.ok === false && result.missingConfig?.length) {
+    return {
+      ...toolNeedsConfig({
+        tool: name,
+        missingConfig: result.missingConfig,
+        configPath: result.configPath,
+        message: result.error
+      }),
+      ...result,
+      status: result.status || "needs_config",
+      resolution: result.resolution || {
+        type: "user_config_required",
+        tool: name,
+        missingConfig: result.missingConfig,
+        configPath: result.configPath
+      }
+    };
+  }
+
+  if (result.ok === false) {
+    return {
+      ...toolError(result.error || `Tool failed: ${name}`),
+      ...result,
+      status: result.status || "failed"
+    };
+  }
+
+  if (result.ok === true) {
+    return {
+      ...toolOk(result.output || {}),
+      ...result,
+      status: result.status || "ok"
+    };
+  }
+
+  return toolError(`Invalid tool response for ${name}`, { rawResult: result });
+}

package/src/runtime/paths.js

@@ -10,7 +10,6 @@ export const serviceLogFile = path.join(stateDir, "arisa.log");
 export const artifactsDir = path.join(arisaHomeDir, "artifacts");
 export const artifactsIndexFile = path.join(stateDir, "artifacts.json");
 export const toolsDir = path.join(arisaHomeDir, "tools");
-export const tmpDir = path.join(arisaHomeDir, "tmp");
 
 export function getToolDir(toolName) {
   return path.join(toolsDir, toolName);
@@ -36,6 +35,5 @@ export async function ensureArisaHome() {
   await mkdir(stateDir, { recursive: true });
   await mkdir(artifactsDir, { recursive: true });
   await mkdir(toolsDir, { recursive: true });
-  await mkdir(tmpDir, { recursive: true });
 }
 

package/src/transport/telegram/bot.js

@@ -1,7 +1,8 @@
 import { Bot, InputFile } from "grammy";
+import path from "node:path";
 import { authorizeChat } from "./auth.js";
 import { captureIncomingArtifact } from "./media.js";
-import { renderTelegramHtml, splitTelegramText } from "./text-format.js";
+import { renderTelegramHtml } from "./text-format.js";
 
 function quotedMessageSummary(message) {
   if (!message) return [];
@@ -31,13 +32,14 @@ function quotedMessageSummary(message) {
   return parts;
 }
 
-function buildPrompt({ ctx, artifact, transcript }) {
+function buildPrompt({ ctx, artifact, transcript, toolResult }) {
   const parts = [
     `New Telegram message.`,
     `chatId: ${ctx.chat.id}`,
     `userId: ${ctx.from.id}`,
     `username: ${ctx.from.username || "(no username)"}`,
-    `messageId: ${ctx.msg.message_id}`
+    `messageId: ${ctx.msg.message_id}`,
+    `preferredTelegramLanguageCode: ${ctx.from?.language_code || "unknown"}`
   ];
 
   if (ctx.message?.text) parts.push(`text: ${ctx.message.text}`);
@@ -51,6 +53,10 @@ function buildPrompt({ ctx, artifact, transcript }) {
     parts.push(`transcriptText: ${transcript.text}`);
     parts.push(`Important: the incoming audio has already been transcribed. Use the transcript as the user message content. Do not answer with a raw transcription unless the user explicitly asked for one.`);
   }
+  if (artifact?.kind === "audio" && !transcript && toolResult) {
+    parts.push(`audioNormalizationResult: ${JSON.stringify(toolResult)}`);
+    parts.push(`Important: pre-reasoning audio normalization could not be completed, so you do not have a transcript for this voice/audio message.`);
+  }
 
   parts.push(`If you need a 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.`);
@@ -74,7 +80,7 @@ async function maybeTranscribeIncomingAudio({ artifact, toolRegistry, artifactSt
   }
 
   if (!result.output?.text) {
-    return { transcript: null, toolResult: { ok: false, error: "Transcription returned no text." } };
+    return { transcript: null, toolResult: { ok: false, status: "failed", error: "Transcription returned no text." } };
   }
 
   const transcript = await artifactStore.createText({
@@ -138,19 +144,32 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
     const { transcript, toolResult } = await maybeTranscribeIncomingAudio({ artifact, toolRegistry, artifactStore });
     if (transcript) logger?.log("telegram", `audio transcribed to artifact ${transcript.id}`);
     if (artifact?.kind === "audio" && !transcript) {
-      if (toolResult?.missingConfig?.includes("OPENAI_API_KEY")) {
-        throw new Error("I need the OpenAI API key for ~/.arisa/tools/openai-transcribe/config.js before I can transcribe incoming audio.");
-      }
-      throw new Error(toolResult?.error || "Audio transcription failed.");
+      logger?.log("telegram", `audio normalization unavailable for chat ${ctx.chat.id}: ${toolResult?.error || toolResult?.missingConfig?.join(", ") || "unknown error"}`);
     }
-    return buildPrompt({ ctx, artifact, transcript });
+    return buildPrompt({ ctx, artifact, transcript, toolResult });
   }
 
-  async function sendTextReply(send, chatId, text) {
-    logger?.log("telegram", `sending text reply for chat ${chatId}`);
-    for (const chunk of splitTelegramText(text)) {
-      await send(renderTelegramHtml(chunk), { parse_mode: "HTML" });
+  async function sendTextReply({ sendText, sendDocument, chatId, text }) {
+    const maxInlineReplyLength = 3500;
+
+    if (text.length > maxInlineReplyLength) {
+      logger?.log("telegram", `sending long reply as markdown attachment for chat ${chatId}`);
+      const artifact = await artifactStore.createGeneratedFile({
+        fileName: `reply-${Date.now()}.md`,
+        content: text,
+        kind: "document",
+        mimeType: "text/markdown",
+        source: { type: "assistant", chatId },
+        metadata: { delivery: "telegram-document" }
+      });
+      await sendDocument(new InputFile(artifact.path, path.basename(artifact.path)), {
+        caption: "Response attached as Markdown."
+      });
+      return;
     }
+
+    logger?.log("telegram", `sending text reply for chat ${chatId}`);
+    await sendText(renderTelegramHtml(text), { parse_mode: "HTML" });
   }
 
   async function processPrompt(ctx, prompt) {
@@ -167,7 +186,12 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
       const { session } = await agentManager.getSessionContext(ctx.chat.id, telegram);
       const text = await collectText(session, prompt);
       if (text) {
-        await sendTextReply((message, extra) => ctx.reply(message, extra), ctx.chat.id, text);
+        await sendTextReply({
+          sendText: (message, extra) => ctx.reply(message, extra),
+          sendDocument: (file, extra) => ctx.replyWithDocument(file, extra),
+          chatId: ctx.chat.id,
+          text
+        });
       }
     });
   }
@@ -226,7 +250,7 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
       const chatState = getChatState(ctx.chat.id);
       chatState.processing = false;
       const message = error instanceof Error ? error.message : String(error);
-      await ctx.reply(`Error: ${message}`);
+      await ctx.reply(message);
     }
   });
 
@@ -260,7 +284,12 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
           ].filter(Boolean).join("\n");
           const text = await collectText(session, welcomePrompt);
           if (text) {
-            await sendTextReply((message, extra) => bot.api.sendMessage(chatId, message, extra), chatId, text);
+            await sendTextReply({
+              sendText: (message, extra) => bot.api.sendMessage(chatId, message, extra),
+              sendDocument: (file, extra) => bot.api.sendDocument(chatId, file, extra),
+              chatId,
+              text
+            });
           }
         } catch (error) {
           logger?.log("telegram", `startup message failed for chat ${chatId}: ${error instanceof Error ? error.message : String(error)}`);

package/tools/openai-transcribe/index.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { readFile, stat } from "node:fs/promises";
 import defaults from "./config.js";
 import { loadToolConfig } from "../../src/core/tools/tool-config.js";
+import { toolError, toolNeedsConfig, toolOk } from "../../src/core/tools/tool-result.js";
 import { getToolConfigPath } from "../../src/runtime/paths.js";
 
 const toolName = "openai-transcribe";
@@ -13,14 +14,18 @@ function printHelp() {
 
 async function run(requestFile) {
   if (!config.OPENAI_API_KEY) {
-    console.log(JSON.stringify({ ok: false, missingConfig: ["OPENAI_API_KEY"], configPath: getToolConfigPath(toolName) }));
+    console.log(JSON.stringify(toolNeedsConfig({
+      tool: toolName,
+      missingConfig: ["OPENAI_API_KEY"],
+      configPath: getToolConfigPath(toolName)
+    })));
     return;
   }
 
   const request = JSON.parse(await readFile(requestFile, "utf8"));
   const artifact = request.artifact;
   if (!artifact?.path) {
-    console.log(JSON.stringify({ ok: false, error: "artifact.path is required" }));
+    console.log(JSON.stringify(toolError("artifact.path is required")));
     return;
   }
 
@@ -38,11 +43,11 @@ async function run(requestFile) {
 
   const payload = await response.json();
   if (!response.ok) {
-    console.log(JSON.stringify({ ok: false, error: payload.error?.message || "OpenAI transcription failed" }));
+    console.log(JSON.stringify(toolError(payload.error?.message || "OpenAI transcription failed")));
     return;
   }
 
-  console.log(JSON.stringify({ ok: true, output: { text: payload.text || "" } }));
+  console.log(JSON.stringify(toolOk({ text: payload.text || "" })));
 }
 
 const args = process.argv.slice(2);

package/tools/openai-tts/index.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import defaults from "./config.js";
 import { loadToolConfig } from "../../src/core/tools/tool-config.js";
+import { toolError, toolNeedsConfig, toolOk } from "../../src/core/tools/tool-result.js";
 import { getToolConfigPath, getToolOutDir } from "../../src/runtime/paths.js";
 
 const toolName = "openai-tts";
@@ -13,14 +14,18 @@ function printHelp() {
 
 async function run(requestFile) {
   if (!config.OPENAI_API_KEY) {
-    console.log(JSON.stringify({ ok: false, missingConfig: ["OPENAI_API_KEY"], configPath: getToolConfigPath(toolName) }));
+    console.log(JSON.stringify(toolNeedsConfig({
+      tool: toolName,
+      missingConfig: ["OPENAI_API_KEY"],
+      configPath: getToolConfigPath(toolName)
+    })));
     return;
   }
 
   const request = JSON.parse(await readFile(requestFile, "utf8"));
   const inputText = request.text || request.artifact?.text;
   if (!inputText) {
-    console.log(JSON.stringify({ ok: false, error: "text or artifact.text is required" }));
+    console.log(JSON.stringify(toolError("text or artifact.text is required")));
     return;
   }
 
@@ -40,7 +45,7 @@ async function run(requestFile) {
 
   if (!response.ok) {
     const payload = await response.text();
-    console.log(JSON.stringify({ ok: false, error: payload }));
+    console.log(JSON.stringify(toolError(payload)));
     return;
   }
 
@@ -49,16 +54,13 @@ async function run(requestFile) {
   const filePath = path.join(outDir, `speech-${Date.now()}.ogg`);
   const buffer = Buffer.from(await response.arrayBuffer());
   await writeFile(filePath, buffer);
-  console.log(JSON.stringify({
-    ok: true,
-    output: {
-      filePath,
-      fileName: path.basename(filePath),
-      mimeType: "audio/ogg",
-      kind: "audio",
-      delivery: { method: "voice" }
-    }
-  }));
+  console.log(JSON.stringify(toolOk({
+    filePath,
+    fileName: path.basename(filePath),
+    mimeType: "audio/ogg",
+    kind: "audio",
+    delivery: { method: "voice" }
+  })));
 }
 
 const args = process.argv.slice(2);

package/tools/web-browser/index.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { toolError, toolOk } from "../../src/core/tools/tool-result.js";
 
 function printHelp() {
   console.log(`web-browser\n\nUsage:\n  node index.js --help\n  node index.js run --request-file <json>\n\nExpected input:\n  {\n    "text": "weather toronto" | "https://example.com",\n    "artifact": { "text": "weather toronto" },\n    "args": {\n      "mode": "search" | "open",\n      "url": "https://example.com",\n      "maxResults": "5"\n    }\n  }\n\nBehavior:\n  - If the input looks like a URL, open the page.\n  - Otherwise, perform a web search.\n  - When possible, opening pages uses r.jina.ai with a direct fetch fallback.\n`);
@@ -121,7 +122,7 @@ async function run(requestFile) {
   const maxResults = Number.parseInt(request.args?.maxResults || "5", 10);
 
   if (!rawInput.trim()) {
-    console.log(JSON.stringify({ ok: false, error: "text, artifact.text, or args.url is required" }));
+    console.log(JSON.stringify(toolError("text, artifact.text, or args.url is required")));
     return;
   }
 
@@ -129,9 +130,9 @@ async function run(requestFile) {
     const outputText = mode === "open"
       ? await openWebPage(rawInput)
       : await searchWeb(rawInput, Number.isFinite(maxResults) ? maxResults : 5);
-    console.log(JSON.stringify({ ok: true, output: { text: outputText } }));
+    console.log(JSON.stringify(toolOk({ text: outputText })));
   } catch (error) {
-    console.log(JSON.stringify({ ok: false, error: error.message || String(error) }));
+    console.log(JSON.stringify(toolError(error.message || String(error))));
   }
 }