arisa 3.0.6 → 3.0.9

package/AGENTS.md

@@ -1,11 +1,11 @@
 # Arisa AGENTS
 
 ## Architecture
-- `src/transport/telegram/*`: Telegram inbound and outbound transport.
-- `src/core/agent/*`: Pi Agent sessions, one per authorized chat.
-- `src/core/artifacts/*`: every incoming or generated message/file becomes an artifact.
-- `src/core/tools/*`: CLI tool registry, help lookup, config writes, execution.
-- `tools/*`: isolated tools. Each tool has `package.json`, `config.js`, `tool.manifest.json`, and `index.js`.
+- Telegram transport handles inbound and outbound messaging.
+- Pi Agent keeps one session per authorized chat.
+- Every incoming or generated message or file becomes an artifact.
+- A tool registry handles tool discovery, help lookup, config writes, and execution.
+- Tools are isolated and each one has its own manifest, entrypoint, and config defaults.
 
 ## Main rule: everything is piped through artifacts
 A pipe transforms one input artifact into one output artifact.
@@ -70,45 +70,39 @@ Example manual pipe:
 ## Missing config flow
 If `run_tool` returns `missingConfig`, the agent should:
 1. ask the user naturally in Telegram for the missing value
-2. write the value into `~/.arisa/tools/<tool>/config.js` with `set_tool_config`
+2. write the value with `set_tool_config`
 3. retry the tool
 
 Do not assume a rigid question/answer protocol. Continue the conversation naturally and infer the config value from the user reply when possible.
 
-## Long-running work
-If a task is likely to take noticeable time — for example creating a new tool, editing multiple files, or doing multi-step work — the agent should first acknowledge the request briefly and naturally, then continue the work.
-
-The acknowledgment should:
-- be short and clear
-- tell the user the work is starting
-- mention when the task may take a while
+## Tool creation
+Reason in terms of capabilities, not tool names.
 
-Examples:
-- "Understood. I'll build that tool now. This may take a couple of minutes."
-- "Got it. I'll inspect the project and make the change now."
+When the user asks for something new:
+1. check whether an existing registered tool can already satisfy the task
+2. also check whether the task can be satisfied indirectly through an existing capability
+3. only propose creating a new tool when the needed capability is truly missing
 
-## Tool creation
-Do not assume specific future tools such as YouTube support exist.
-If the user asks for a capability that is not currently available, first check whether an existing registered tool can satisfy the task.
-If no existing tool can do it, the default attitude should be to propose creating a new CLI tool under `tools/<tool-name>` following the project conventions.
-All newly created tools must document their help text, usage instructions, manifests, and user-facing operational strings in English.
-Do not stop at "I cannot do that" when the task is realistically implementable through a new tool.
-Prefer responses like:
+Do not stop at "I cannot do that" when the task is realistically implementable through the tool architecture.
+The default attitude is:
 - identify that no current tool satisfies the request
 - state that the missing capability can be added
-- propose or start creating the tool needed to fulfill the request
-
-For example, if the user asks for live weather and no weather tool exists, the correct attitude is to propose building a weather tool for the bot rather than only saying real-time access is unavailable.
+- propose or start creating the needed tool
 
-When creating or editing tools, follow the shared path helpers in `src/runtime/paths.js` and `src/core/tools/tool-config.js`:
-- config in `~/.arisa/tools/<tool>/config.js`
-- temp/runtime files in `~/.arisa/tmp/tools/<tool>/`
-- durable generated files should become artifacts in `~/.arisa/artifacts/`
+When creating or editing tools:
+- use the shared path helpers and the runtime paths provided in the prompt instead of assuming fixed locations
+- consult the local skill for that workflow when building new tools
+- keep all help text, usage instructions, manifests, and user-facing operational strings in English
+- follow the One Thing Rule: each function or method should do one thing well; if it mixes low-level operations with high-level policy, split it into smaller focused units
 
-Consult the local skill for that workflow when building new tools.
+## Dependency installation
+Arisa installs tool dependencies itself.
+- Prefer `pnpm install`.
+- Fall back to `npm install`.
+- Do not ask the user to do it manually.
 
 ## Safety
-- Do not install or run arbitrary tools outside registered `tools/*` manifests in V1.
+- Do not install or run arbitrary tools outside registered tool manifests in V1.
 - Prefer tool manifests and CLI help over assumptions.
-- Keep tool configs inside `~/.arisa/tools/<tool>/config.js`.
+- Keep tool config and runtime data inside the user runtime area.
 - Be proactive about extending capabilities, but do it through the project's tool architecture, not through ad hoc one-off behavior.

package/README.md

@@ -4,7 +4,7 @@ Arisa is a personal Telegram assistant powered by Pi Agent.
 
 ## Origin
 
-The initial inspiration was [OpenClaw](https://github.com/openclaw/openclaw). OpenClaw has interesting ideas but carries too much weight: when it generates tools they end up disorganized, and the overall framework feels overloaded for personal use.
+The initial inspiration was [OpenClaw](https://github.com/openclaw/openclaw). OpenClaw has interesting ideas but carries a lot of weight (about **185 MB**) compared to Arisa (**76.7 kB**): 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.
 
@@ -46,7 +46,9 @@ This distinction is important. Some transformations belong to the transport/inpu
 - media is stored as artifacts
 
 ### Tool model
-Each tool lives in its own folder under `tools/<tool-name>` and contains:
+Bundled tools live under `<arisa-install-dir>/tools/<tool-name>` and user-created tools live under `~/.arisa/tools/<tool-name>`.
+
+Each tool folder contains:
 
 - `package.json`
 - `config.js`
@@ -57,7 +59,8 @@ Each tool is isolated from the root project and from other tools.
 That isolation is part of the architecture:
 
 - each tool has its own folder
-- each tool has a local `config.js` only for defaults/template values
+- bundled tools have a local `config.js` for defaults/template values
+- user-created tools can live entirely inside `~/.arisa/tools/<tool>/`
 - each tool can have its own dependencies
 - one tool can be changed or replaced without tightly coupling the rest of the system
 
@@ -74,8 +77,8 @@ node index.js run --request-file <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`
-- bundled tools and generated tools should both use the same source layout under `tools/<tool>/`
-- tool runtime temp files and generated outputs live in `~/.arisa/tmp/tools/<tool>/`
+- 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
@@ -96,11 +99,13 @@ arisa
 Command modes:
 
 ```bash
-arisa            # foreground, blocking
-arisa start      # start in background
-arisa stop       # stop background service
-arisa status     # show background service status
-arisa flush      # remove ~/.arisa
+arisa                    # foreground, blocking
+arisa start              # start in background
+arisa stop               # stop background service
+arisa status             # show background service status
+arisa flush              # remove ~/.arisa
+arisa install <source>   # install a Pi package into Arisa's runtime
+arisa remove <source>    # remove a Pi package from Arisa's runtime
 ```
 
 ## Bootstrap flow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "3.0.6",
+  "version": "3.0.9",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",

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

@@ -1,10 +1,11 @@
 import path from "node:path";
-import { mkdir, unlink } from "node:fs/promises";
+import { unlink } from "node:fs/promises";
 import { createAgentSession, SessionManager, defineTool } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { createPiRuntime, hasProviderAuth } from "./pi-runtime.js";
 import { loadProjectInstructions } from "./project-instructions.js";
-import { getChatDir, piAgentDir as agentDir } from "../../runtime/paths.js";
+import { arisaInstallDir, buildAgentRuntimeContext } from "./runtime-context.js";
+import { arisaHomeDir } from "../../runtime/paths.js";
 
 export class AgentManager {
   constructor({ config, artifactStore, toolRegistry, logger }) {
@@ -49,7 +50,6 @@ export class AgentManager {
       return this.sessions.get(chatId);
     }
 
-    await mkdir(agentDir, { recursive: true });
     const { authStorage, modelRegistry } = createPiRuntime({
       provider: this.config.pi.provider,
       apiKey: this.config.pi.apiKey
@@ -60,24 +60,23 @@ export class AgentManager {
       throw new Error(`No auth found for ${this.config.pi.provider}. Re-run bootstrap and complete login for this provider before Telegram starts.`);
     }
 
-    const cwd = getChatDir(chatId);
-    await mkdir(cwd, { recursive: true });
-
     this.logger?.log("agent", `creating session for chat ${chatId}`);
     const customTools = this.createTools(telegram);
     const { session } = await createAgentSession({
-      cwd,
-      agentDir,
+      cwd: arisaInstallDir,
+      agentDir: arisaHomeDir,
       authStorage,
       modelRegistry,
       model,
       customTools,
-      sessionManager: SessionManager.continueRecent(cwd)
+      sessionManager: SessionManager.inMemory()
     });
 
     const instructions = await loadProjectInstructions();
+    const runtimeContext = buildAgentRuntimeContext();
     this.logger?.log("agent", `injecting project instructions for chat ${chatId}`);
-    await session.prompt(`${instructions}\n\nAcknowledge with exactly: OK`);
+    this.logger?.log("agent", `runtime context for chat ${chatId}:\n${runtimeContext}`);
+    await session.prompt(`${instructions}\n\n${runtimeContext}\n\nAcknowledge with exactly: OK`);
 
     const ctx = { session };
     this.sessions.set(chatId, ctx);

package/src/core/agent/runtime-context.js

@@ -0,0 +1,16 @@
+import { fileURLToPath } from "node:url";
+import { arisaHomeDir, artifactsDir, stateDir, toolsDir } from "../../runtime/paths.js";
+
+export const arisaInstallDir = fileURLToPath(new URL("../../..", import.meta.url));
+export const bundledToolsDir = fileURLToPath(new URL("../../../tools", import.meta.url));
+
+export function buildAgentRuntimeContext() {
+  return [
+    `arisaHomeDir: ${arisaHomeDir}`,
+    `arisaInstallDir: ${arisaInstallDir}`,
+    `bundledToolsDir: ${bundledToolsDir}`,
+    `userToolsDir: ${toolsDir}`,
+    `artifactsDir: ${artifactsDir}`,
+    `stateDir: ${stateDir}`
+  ].join("\n");
+}

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

@@ -1,10 +1,15 @@
 import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { getToolConfigPath, getToolTmpDir } from "../../runtime/paths.js";
+import { fileURLToPath } from "node:url";
+import { getToolConfigPath, getToolTmpDir, toolsDir as userToolsRoot } from "../../runtime/paths.js";
 import { loadToolConfig, parseConfigModule, writeToolConfig } from "./tool-config.js";
 
-const toolsRoot = path.resolve("tools");
+const bundledToolsRoot = fileURLToPath(new URL("../../../tools", import.meta.url));
+const toolRoots = [
+  { root: userToolsRoot, kind: "user" },
+  { root: bundledToolsRoot, kind: "bundled" }
+];
 
 function runProcess(command, args, options = {}) {
   return new Promise((resolve) => {
@@ -26,35 +31,39 @@ export class ToolRegistry {
   async load() {
     this.tools.clear();
 
-    let entries = [];
-    try {
-      entries = await readdir(toolsRoot, { withFileTypes: true });
-    } catch {
-      this.logger?.log("tools", `tools directory not found: ${toolsRoot}`);
-      return;
-    }
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const toolDir = path.join(toolsRoot, entry.name);
-      const manifestPath = path.join(toolDir, "tool.manifest.json");
-      const configPath = path.join(toolDir, "config.js");
+    for (const { root, kind } of toolRoots) {
+      let entries = [];
       try {
-        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
-        const configSource = await readFile(configPath, "utf8");
-        const defaults = parseConfigModule(configSource);
-        const config = await loadToolConfig(manifest.name, defaults);
-        this.tools.set(manifest.name, {
-          ...manifest,
-          dir: toolDir,
-          entry: path.join(toolDir, manifest.entry || "index.js"),
-          localConfigPath: configPath,
-          configPath: getToolConfigPath(manifest.name),
-          defaults,
-          config
-        });
+        entries = await readdir(root, { withFileTypes: true });
       } catch {
-        // ignore invalid tool dirs in v1
+        this.logger?.log("tools", `${kind} tools directory not found: ${root}`);
+        continue;
+      }
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const toolDir = path.join(root, entry.name);
+        const manifestPath = path.join(toolDir, "tool.manifest.json");
+        const configPath = path.join(toolDir, "config.js");
+        try {
+          const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+          if (this.tools.has(manifest.name)) continue;
+          const configSource = await readFile(configPath, "utf8");
+          const defaults = parseConfigModule(configSource);
+          const config = await loadToolConfig(manifest.name, defaults);
+          this.tools.set(manifest.name, {
+            ...manifest,
+            dir: toolDir,
+            entry: path.join(toolDir, manifest.entry || "index.js"),
+            localConfigPath: configPath,
+            configPath: getToolConfigPath(manifest.name),
+            defaults,
+            config,
+            sourceKind: kind
+          });
+        } catch {
+          // ignore invalid tool dirs in v1
+        }
       }
     }
 

package/src/index.js

@@ -5,6 +5,7 @@ import { createApp } from "./runtime/create-app.js";
 import { createLogger } from "./runtime/logger.js";
 import { getServiceStatus, registerServiceProcess, startService, stopService } from "./runtime/service-manager.js";
 import { flushArisaHome } from "./runtime/flush.js";
+import { installPiPackage, removePiPackage } from "./runtime/pi-package-manager.js";
 
 const args = process.argv.slice(2);
 const command = args.find((arg) => !arg.startsWith("--")) || "run";
@@ -83,6 +84,28 @@ async function main() {
     return;
   }
 
+  if (command === "install") {
+    const source = args.filter((arg) => !arg.startsWith("--")).slice(1)[0];
+    if (!source) {
+      console.log("Usage: arisa install <pi-package-source>");
+      return;
+    }
+    const result = await installPiPackage(source);
+    process.exitCode = result.ok ? 0 : result.code;
+    return;
+  }
+
+  if (command === "remove") {
+    const source = args.filter((arg) => !arg.startsWith("--")).slice(1)[0];
+    if (!source) {
+      console.log("Usage: arisa remove <pi-package-source>");
+      return;
+    }
+    const result = await removePiPackage(source);
+    process.exitCode = result.ok ? 0 : result.code;
+    return;
+  }
+
   await runForeground();
 }
 

package/src/runtime/paths.js

@@ -9,15 +9,9 @@ export const servicePidFile = path.join(stateDir, "arisa.pid");
 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 piAgentDir = path.join(stateDir, "pi-agent");
-export const chatsDir = path.join(stateDir, "chats");
 export const toolsDir = path.join(arisaHomeDir, "tools");
 export const tmpDir = path.join(arisaHomeDir, "tmp");
 
-export function getChatDir(chatId) {
-  return path.join(chatsDir, String(chatId));
-}
-
 export function getToolDir(toolName) {
   return path.join(toolsDir, toolName);
 }
@@ -27,7 +21,7 @@ export function getToolConfigPath(toolName) {
 }
 
 export function getToolRuntimeDir(toolName) {
-  return path.join(tmpDir, "tools", toolName);
+  return getToolDir(toolName);
 }
 
 export function getToolOutDir(toolName) {
@@ -41,8 +35,6 @@ export function getToolTmpDir(toolName) {
 export async function ensureArisaHome() {
   await mkdir(stateDir, { recursive: true });
   await mkdir(artifactsDir, { recursive: true });
-  await mkdir(piAgentDir, { recursive: true });
-  await mkdir(chatsDir, { recursive: true });
   await mkdir(toolsDir, { recursive: true });
   await mkdir(tmpDir, { recursive: true });
 }

package/src/runtime/pi-package-manager.js

@@ -0,0 +1,49 @@
+import { DefaultPackageManager, SettingsManager } from "@mariozechner/pi-coding-agent";
+import { arisaHomeDir } from "./paths.js";
+
+function createPackageManager() {
+  const settingsManager = SettingsManager.create(arisaHomeDir, arisaHomeDir);
+  const packageManager = new DefaultPackageManager({
+    cwd: arisaHomeDir,
+    agentDir: arisaHomeDir,
+    settingsManager
+  });
+
+  packageManager.setProgressCallback((event) => {
+    if (event.type === "start") {
+      process.stdout.write(`${event.message}\n`);
+    }
+  });
+
+  return packageManager;
+}
+
+export async function installPiPackage(source) {
+  const packageManager = createPackageManager();
+
+  try {
+    await packageManager.installAndPersist(source, { local: false });
+    console.log(`Installed ${source}`);
+    return { ok: true, code: 0 };
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return { ok: false, code: 1 };
+  }
+}
+
+export async function removePiPackage(source) {
+  const packageManager = createPackageManager();
+
+  try {
+    const removed = await packageManager.removeAndPersist(source, { local: false });
+    if (!removed) {
+      console.error(`No matching package found for ${source}`);
+      return { ok: false, code: 1 };
+    }
+    console.log(`Removed ${source}`);
+    return { ok: true, code: 0 };
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return { ok: false, code: 1 };
+  }
+}