arisa 4.0.16 → 4.0.18

package/AGENTS.md

@@ -31,7 +31,24 @@ Each tool declares in `tool.manifest.json`:
 - `output`: produced output types
 - `configSchema`: required config fields
 - `skillHints`: optional skills to apply when using or editing the tool
-- `web.routes`: optional HTTP routes exposed through Arisa's main server
+
+## Tool-to-Arisa IPC
+Arisa does not mount tool-provided web routes in core. If a tool needs to expose a web UI or HTTP endpoint, the tool owns that server, usually through the shared daemon runtime. The tool's server handles its own requests and uses Arisa IPC when it needs artifacts, tasks, agent events, or runtime paths.
+
+Installed tools can import the IPC client through `ARISA_PACKAGE_DIR`:
+
+```js
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const importCore = (relativePath) => import(pathToFileURL(path.join(process.env.ARISA_PACKAGE_DIR, "src", relativePath)).href);
+const { createArisaClient } = await importCore("core/tools/ipc-client.js");
+
+const arisa = createArisaClient({ toolName: "example-tool", chatId });
+await arisa.artifacts.createText({ text: "hello" });
+```
+
+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: artifacts (`createText`, `listRecent`, `get`), tasks (`add`, `list`, `cancel`), agent events (`enqueueEvent`), and runtime paths (`getChatToolStateDir`, `getToolStateDir`, `getChatToolTmpDir`, `getToolTmpDir`, `getChatArtifactsDir`). Do not add raw access to `agentManager`, `taskStore`, `artifactStore`, or `toolRegistry`.
 
 ## Conceptual pipe model
 There are two different moments where pipes can happen:
@@ -72,27 +89,6 @@ Every CLI must support (the entrypoint comes from `manifest.entry`, currently al
 - `node index.js --help`
 - `node index.js run --request-file <json>`
 
-## Tool-provided web routes
-Tools may expose small web pages or HTTP endpoints through Arisa's main HTTP server by declaring `web.routes` in `tool.manifest.json`. See `tools/README.md` and `tools/web-hello` for the full contract and minimal example.
-
-```json
-{
-  "name": "example-tool",
-  "web": {
-    "routes": [
-      {
-        "path": "/example",
-        "handler": "web/index.js",
-        "methods": ["GET"],
-        "public": false
-      }
-    ]
-  }
-}
-```
-
-Handlers run in-process and export `handleWebRequest(req, res, context)`. Routes are protected by default with `config.web.token`; use `public: true` only for intentional public GET endpoints. Keep handlers inside the installed tool directory, avoid reserved paths (`/`, `/health`, `/api*`, `/auth*`, `/telegram-*`), and persist data only through `context.paths` runtime helpers such as `getChatToolStateDir(chatId, toolName)`.
-
 ### Tools that need daemons
 A tool may need a persistent process, for example to keep a browser session alive or a local model warm. The shared daemon runtime exists for this (the `whispermix-transcribe` catalog tool uses it).
 When such a tool is built, implement it with the shared daemon runtime instead of custom ad hoc process management:
@@ -103,6 +99,7 @@ When such a tool is built, implement it with the shared daemon runtime instead o
 - keep one daemon owner per tool/session and avoid opening a second client over the same resource
 - use `beforeStart` only for tool-specific cleanup such as stale browser locks, without deleting persistent session/model data
 - keep daemon tools headless/server-safe by default when they are meant to run on VPS machines
+- if the daemon exposes an HTTP server, keep that server inside the tool; Arisa core does not discover or mount tool routes
 
 ## Manual pipe behavior
 To run a pipe, the agent should:

package/README.md

@@ -162,7 +162,7 @@ Notes:
 
 - interactive bootstrap remains unchanged when no CLI overrides are provided
 - `--bootstrap` can be combined with overrides to regenerate config non-interactively
-- Arisa's HTTP server listens on `ARISA_HTTP_PORT` (default `11970`); bootstrap OAuth pages and tool-provided web routes use this server
+- when `--pi.apiKey` is omitted and the provider supports OAuth, bootstrap can use a temporary auth relay if `PORT` is set; this relay is only for Pi login and is not a tool web route server
 - unknown `--pi.provider` or `--pi.model` values are ignored and replaced by safe defaults
 
 Telegram bot tokens can be created with:

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "arisa",
-  "version": "4.0.16",
+  "version": "4.0.18",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",
   "bin": {
     "arisa": "bin/arisa.js"
   },
-  "scripts": {
-    "start": "node src/index.js",
-    "bootstrap": "node src/index.js --bootstrap",
-    "test": "node --test"
-  },
   "keywords": [
     "telegram",
     "pi-agent",
@@ -41,10 +36,14 @@
     "url": "https://github.com/clasen/Arisa/issues"
   },
   "homepage": "https://github.com/clasen/Arisa#readme",
-  "packageManager": "pnpm@11.3.0+sha512.2c403d6594527287672b1f7056343a1f7c3634036a67ffabfcc2b3d7595d843768f8787148d1b57cf7956c90606bbd192857c363af19e96d2d0ec9ec5741d215",
   "dependencies": {
     "@earendil-works/pi-coding-agent": "^0.79.9",
     "@sinclair/typebox": "^0.34.41",
     "grammy": "^1.42.0"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "bootstrap": "node src/index.js --bootstrap",
+    "test": "node --test"
   }
-}
+}

package/src/core/tools/ipc-client.js

@@ -0,0 +1,94 @@
+import crypto from "node:crypto";
+import net from "node:net";
+import { arisaIpcSocketFile } from "../../runtime/paths.js";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+function requestIpc({ socketPath, request, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let buffer = "";
+    let settled = false;
+
+    function finish(fn, value) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      socket.end();
+      fn(value);
+    }
+
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      finish(reject, new Error("Arisa IPC request timed out"));
+    }, timeoutMs);
+    timeout.unref?.();
+
+    socket.setEncoding("utf8");
+    socket.once("connect", () => {
+      socket.write(`${JSON.stringify(request)}\n`);
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex === -1) return;
+      const line = buffer.slice(0, newlineIndex);
+      try {
+        const response = JSON.parse(line);
+        if (!response.ok) {
+          finish(reject, new Error(response.error || "Arisa IPC request failed"));
+          return;
+        }
+        finish(resolve, response.result);
+      } catch (error) {
+        finish(reject, error);
+      }
+    });
+    socket.once("error", (error) => {
+      finish(reject, error);
+    });
+    socket.once("close", () => {
+      finish(reject, new Error("Arisa IPC connection closed before response"));
+    });
+  });
+}
+
+export function createArisaClient({ toolName, chatId = null, socketPath = process.env.ARISA_IPC_SOCKET || arisaIpcSocketFile } = {}) {
+  if (typeof toolName !== "string" || !toolName.trim()) {
+    throw new Error("toolName is required");
+  }
+
+  const call = (method, params = {}) => requestIpc({
+    socketPath,
+    request: {
+      id: crypto.randomUUID(),
+      method,
+      toolName,
+      chatId,
+      params
+    }
+  });
+
+  return {
+    artifacts: {
+      createText: (params) => call("artifacts.createText", params),
+      listRecent: (params) => call("artifacts.listRecent", params),
+      get: (params) => call("artifacts.get", params)
+    },
+    tasks: {
+      add: (params) => call("tasks.add", params),
+      list: (params) => call("tasks.list", params),
+      cancel: (params) => call("tasks.cancel", params)
+    },
+    agent: {
+      enqueueEvent: (params) => call("agent.enqueueEvent", params)
+    },
+    paths: {
+      getChatToolStateDir: () => call("paths.getChatToolStateDir"),
+      getToolStateDir: () => call("paths.getToolStateDir"),
+      getChatToolTmpDir: () => call("paths.getChatToolTmpDir"),
+      getToolTmpDir: () => call("paths.getToolTmpDir"),
+      getChatArtifactsDir: () => call("paths.getChatArtifactsDir")
+    }
+  };
+}

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

@@ -1,14 +1,13 @@
 import { mkdir, readdir, readFile, rmdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { arisaPackageDir, getToolConfigPath, getToolTmpDir, getChatToolTmpDir, toolsDir as userToolsRoot } from "../../runtime/paths.js";
-import { validateToolWebRoutes } from "../../runtime/web/route-validation.js";
+import { arisaIpcSocketFile, arisaPackageDir, getToolConfigPath, getToolTmpDir, getChatToolTmpDir, toolsDir as userToolsRoot } from "../../runtime/paths.js";
 import { loadToolConfig, parseConfigModule, writeToolConfig } from "./tool-config.js";
 import { normalizeToolResult } from "./tool-result.js";
 import { SkillRegistry } from "../skills/skill-registry.js";
 
 function toolEnv() {
-  return { ...process.env, ARISA_PACKAGE_DIR: arisaPackageDir };
+  return { ...process.env, ARISA_PACKAGE_DIR: arisaPackageDir, ARISA_IPC_SOCKET: arisaIpcSocketFile };
 }
 
 function runProcess(command, args, options = {}) {
@@ -26,14 +25,11 @@ export class ToolRegistry {
   constructor({ logger } = {}) {
     this.logger = logger;
     this.tools = new Map();
-    this.webRoutes = [];
     this.skillRegistry = new SkillRegistry();
   }
 
   async load() {
     this.tools.clear();
-    this.webRoutes = [];
-    const claimedWebPaths = new Map();
 
     let entries = [];
     try {
@@ -54,7 +50,7 @@ export class ToolRegistry {
         const defaults = parseConfigModule(configSource);
         const config = await loadToolConfig(manifest.name, defaults);
         const skillHints = this.skillRegistry.normalizeHints(manifest);
-        const tool = {
+        this.tools.set(manifest.name, {
           ...manifest,
           skillHints,
           dir: toolDir,
@@ -63,13 +59,7 @@ export class ToolRegistry {
           configPath: getToolConfigPath(manifest.name),
           defaults,
           config
-        };
-        this.tools.set(manifest.name, tool);
-        const { routes, errors } = validateToolWebRoutes(manifest, toolDir, claimedWebPaths);
-        this.webRoutes.push(...routes);
-        for (const error of errors) {
-          this.logger?.log("web", `skipping route for ${manifest.name}: ${error.error}`);
-        }
+        });
       } catch {
         // ignore invalid tool dirs in v1
       }
@@ -89,13 +79,6 @@ export class ToolRegistry {
     }));
   }
 
-  listWebRoutes() {
-    return this.webRoutes.map((route) => ({
-      ...route,
-      methods: [...route.methods]
-    }));
-  }
-
   get(name) {
     return this.tools.get(name) || null;
   }

package/src/runtime/arisa-capabilities.js

@@ -0,0 +1,123 @@
+import {
+  getChatArtifactsDir,
+  getChatToolStateDir,
+  getChatToolTmpDir,
+  getToolStateDir,
+  getToolTmpDir
+} from "./paths.js";
+
+function requireToolName(toolName) {
+  if (typeof toolName !== "string" || !toolName.trim()) {
+    throw new Error("toolName is required");
+  }
+  return toolName.trim();
+}
+
+function requireChatId(chatId, method) {
+  if (chatId == null || chatId === "") {
+    throw new Error(`${method} requires chatId`);
+  }
+  return chatId;
+}
+
+function requireString(value, fieldName) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${fieldName} is required`);
+  }
+  return value;
+}
+
+function normalizeLimit(limit) {
+  const value = Number(limit);
+  if (!Number.isInteger(value) || value <= 0) return 20;
+  return Math.min(value, 100);
+}
+
+export function createArisaCapabilities({ artifactStore, taskStore } = {}) {
+  async function dispatch({ method, toolName, chatId = null, params = {} } = {}) {
+    const scopedToolName = requireToolName(toolName);
+
+    if (method === "artifacts.createText") {
+      const scopedChatId = requireChatId(chatId, method);
+      return artifactStore.forChat(scopedChatId).createText({
+        text: requireString(params.text, "text"),
+        mimeType: params.mimeType || "text/plain",
+        source: { type: "tool", toolName: scopedToolName, chatId: scopedChatId },
+        metadata: params.metadata || {}
+      });
+    }
+
+    if (method === "artifacts.listRecent") {
+      const scopedChatId = requireChatId(chatId, method);
+      return artifactStore.forChat(scopedChatId).listRecent(normalizeLimit(params.limit));
+    }
+
+    if (method === "artifacts.get") {
+      const scopedChatId = requireChatId(chatId, method);
+      return artifactStore.forChat(scopedChatId).get(requireString(params.artifactId, "artifactId"));
+    }
+
+    if (method === "tasks.add") {
+      const scopedChatId = requireChatId(chatId, method);
+      return taskStore.add(params.task || {}, {
+        payload: { chatId: scopedChatId },
+        source: { type: "tool", toolName: scopedToolName, chatId: scopedChatId }
+      });
+    }
+
+    if (method === "tasks.list") {
+      const scopedChatId = requireChatId(chatId, method);
+      return taskStore.list({
+        chatId: scopedChatId,
+        status: params.status || undefined,
+        kind: params.kind || undefined
+      });
+    }
+
+    if (method === "tasks.cancel") {
+      const scopedChatId = requireChatId(chatId, method);
+      const taskId = requireString(params.taskId, "taskId");
+      const task = await taskStore.get(taskId);
+      if (!task) return null;
+      if (String(task.payload?.chatId) !== String(scopedChatId)) {
+        throw new Error("task does not belong to chatId");
+      }
+      return taskStore.cancel(taskId);
+    }
+
+    if (method === "agent.enqueueEvent") {
+      const scopedChatId = requireChatId(chatId, method);
+      return taskStore.add({
+        kind: "agent_event",
+        payload: { prompt: requireString(params.prompt, "prompt") }
+      }, {
+        payload: { chatId: scopedChatId },
+        source: { type: "tool", toolName: scopedToolName, chatId: scopedChatId }
+      });
+    }
+
+    if (method === "paths.getChatToolStateDir") {
+      return getChatToolStateDir(requireChatId(chatId, method), scopedToolName);
+    }
+
+    if (method === "paths.getToolStateDir") {
+      return getToolStateDir(scopedToolName);
+    }
+
+    if (method === "paths.getChatToolTmpDir") {
+      return getChatToolTmpDir(requireChatId(chatId, method), scopedToolName);
+    }
+
+    if (method === "paths.getToolTmpDir") {
+      return getToolTmpDir(scopedToolName);
+    }
+
+    if (method === "paths.getChatArtifactsDir") {
+      return getChatArtifactsDir(requireChatId(chatId, method));
+    }
+
+    throw new Error(`unknown IPC method: ${method}`);
+  }
+
+  return { dispatch };
+}

package/src/runtime/create-app.js

@@ -1,4 +1,3 @@
-import crypto from "node:crypto";
 import { loadConfig, saveConfig, updateConfig } from "../core/config/config-store.js";
 import { ArtifactStore } from "../core/artifacts/artifact-store.js";
 import { ToolRegistry } from "../core/tools/tool-registry.js";
@@ -7,14 +6,8 @@ import { AgentManager } from "../core/agent/agent-manager.js";
 import { getErrorMessage, getPiAuthIssue } from "../core/agent/auth-flow.js";
 import { createTelegramBot } from "../transport/telegram/bot.js";
 import { createToolProcessSupervisor } from "./tool-process-supervisor.js";
-import { createWebRouter } from "./web/web-router.js";
-import {
-  getChatArtifactsDir,
-  getChatToolStateDir,
-  getChatToolTmpDir,
-  getToolStateDir,
-  getToolTmpDir
-} from "./paths.js";
+import { createArisaCapabilities } from "./arisa-capabilities.js";
+import { createIpcServer } from "./ipc/ipc-server.js";
 
 function normalizeString(value) {
   const text = String(value ?? "").trim();
@@ -53,29 +46,6 @@ function applyRuntimeOverrides(config, runtimeOverrides) {
   };
 }
 
-async function ensureWebToken(config, logger) {
-  if (config.web?.token) return config.web.token;
-
-  const generatedToken = crypto.randomBytes(24).toString("hex");
-  const persisted = await updateConfig((storedConfig) => {
-    storedConfig.web ||= {};
-    storedConfig.web.token ||= generatedToken;
-  });
-  config.web = { ...(config.web || {}), token: persisted.web.token };
-  logger?.log("web", "generated shared web route token");
-  return config.web.token;
-}
-
-function createToolWebPaths() {
-  return {
-    getChatArtifactsDir,
-    getChatToolStateDir,
-    getChatToolTmpDir,
-    getToolStateDir,
-    getToolTmpDir
-  };
-}
-
 export async function createApp({ logger, runtimeOverrides, webhookUrl, setHttpRequestHandler } = {}) {
   logger?.log("app", "loading config");
   const persistedConfig = await loadConfig();
@@ -92,33 +62,9 @@ export async function createApp({ logger, runtimeOverrides, webhookUrl, setHttpR
   logger?.log("app", `loaded ${toolRegistry.list().length} tools`);
 
   const agentManager = new AgentManager({ config, artifactStore, toolRegistry, taskStore, logger });
-  await ensureWebToken(config, logger);
-  const webRouter = createWebRouter({
-    getRoutes: () => toolRegistry.listWebRoutes(),
-    getToken: () => config.web?.token || "",
-    logger,
-    buildContext: ({ toolName, chatId }) => ({
-      toolName,
-      chatId,
-      logger,
-      toolRegistry,
-      artifactStore,
-      taskStore,
-      agentManager,
-      paths: createToolWebPaths()
-    })
-  });
-  webRouter.registerCoreRoute({
-    method: "GET",
-    path: "/health",
-    handler: (_req, res) => {
-      res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-      res.end("ok\n");
-    }
-  });
-  setHttpRequestHandler?.(webRouter.dispatch);
-
-  const bot = await createTelegramBot({ config, artifactStore, toolRegistry, taskStore, agentManager, saveConfig, updateConfig, logger, webhookUrl, webRouter: setHttpRequestHandler ? webRouter : null });
+  const arisaCapabilities = createArisaCapabilities({ artifactStore, taskStore });
+  const ipcServer = createIpcServer({ capabilities: arisaCapabilities, logger });
+  const bot = await createTelegramBot({ config, artifactStore, toolRegistry, taskStore, agentManager, saveConfig, updateConfig, logger, webhookUrl, setHttpRequestHandler });
 
   return {
     async start() {
@@ -135,12 +81,18 @@ export async function createApp({ logger, runtimeOverrides, webhookUrl, setHttpR
         logger?.error("app", `Pi auth validation failed; starting Telegram in auth recovery mode: ${getErrorMessage(error)}`);
         await bot.notifyPiAuthIssue?.(error);
       }
-      await toolProcessSupervisor.start();
-      logger?.log("app", "starting Telegram bot");
+      let ipcStarted = false;
+      let supervisorStarted = false;
       try {
+        await ipcServer.start();
+        ipcStarted = true;
+        await toolProcessSupervisor.start();
+        supervisorStarted = true;
+        logger?.log("app", "starting Telegram bot");
         await bot.start({ skipAgentStartupPrompts });
       } catch (error) {
-        await toolProcessSupervisor.stop();
+        if (supervisorStarted) await toolProcessSupervisor.stop();
+        if (ipcStarted) await ipcServer.stop();
         throw error;
       }
     },
@@ -148,6 +100,7 @@ export async function createApp({ logger, runtimeOverrides, webhookUrl, setHttpR
     async stop() {
       await bot.stop?.();
       await toolProcessSupervisor.stop();
+      await ipcServer.stop();
     }
   };
 }

package/src/runtime/ipc/ipc-server.js

@@ -0,0 +1,109 @@
+import net from "node:net";
+import path from "node:path";
+import { chmod, mkdir, unlink } from "node:fs/promises";
+import { arisaIpcSocketFile } from "../paths.js";
+
+function writeResponse(socket, response) {
+  socket.write(`${JSON.stringify(response)}\n`);
+}
+
+function isStaleSocketError(error) {
+  return ["ENOENT", "ECONNREFUSED"].includes(error?.code);
+}
+
+async function hasLiveSocket(socketPath) {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(socketPath);
+    client.once("connect", () => {
+      client.end();
+      resolve(true);
+    });
+    client.once("error", (error) => {
+      if (isStaleSocketError(error)) {
+        resolve(false);
+        return;
+      }
+      reject(error);
+    });
+  });
+}
+
+export function createIpcServer({ capabilities, socketPath = arisaIpcSocketFile, logger } = {}) {
+  let server = null;
+
+  async function handleLine(socket, line) {
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      writeResponse(socket, { id: null, ok: false, error: "invalid JSON request" });
+      return;
+    }
+
+    try {
+      const result = await capabilities.dispatch(request);
+      writeResponse(socket, { id: request.id ?? null, ok: true, result });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger?.log?.("ipc", `request failed: ${message}`);
+      writeResponse(socket, { id: request.id ?? null, ok: false, error: message });
+    }
+  }
+
+  async function start() {
+    if (server) return { socketPath };
+    await mkdir(path.dirname(socketPath), { recursive: true });
+
+    if (await hasLiveSocket(socketPath)) {
+      throw new Error(`Arisa IPC socket already in use: ${socketPath}`);
+    }
+    await unlink(socketPath).catch((error) => {
+      if (error?.code !== "ENOENT") throw error;
+    });
+
+    server = net.createServer((socket) => {
+      socket.setEncoding("utf8");
+      let buffer = "";
+      socket.on("data", (chunk) => {
+        buffer += chunk;
+        let newlineIndex = buffer.indexOf("\n");
+        while (newlineIndex !== -1) {
+          const line = buffer.slice(0, newlineIndex).trim();
+          buffer = buffer.slice(newlineIndex + 1);
+          if (line) handleLine(socket, line);
+          newlineIndex = buffer.indexOf("\n");
+        }
+      });
+      socket.on("error", (error) => {
+        logger?.log?.("ipc", `client socket error: ${error instanceof Error ? error.message : String(error)}`);
+      });
+    });
+
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(socketPath, resolve);
+    });
+    await chmod(socketPath, 0o600).catch(() => {});
+    logger?.log?.("ipc", `listening on ${socketPath}`);
+    return { socketPath };
+  }
+
+  async function stop() {
+    if (!server) return;
+    const closingServer = server;
+    server = null;
+    await new Promise((resolve) => closingServer.close(resolve));
+    await unlink(socketPath).catch((error) => {
+      if (error?.code !== "ENOENT") throw error;
+    });
+  }
+
+  return {
+    start,
+    stop,
+    address: () => server?.address() || null,
+    get socketPath() {
+      return socketPath;
+    }
+  };
+}

package/src/runtime/paths.js

@@ -9,6 +9,7 @@ export const stateDir = path.join(arisaHomeDir, "state");
 export const configFile = path.join(stateDir, "config.json");
 export const servicePidFile = path.join(stateDir, "arisa.pid");
 export const serviceLogFile = path.join(stateDir, "arisa.log");
+export const arisaIpcSocketFile = path.join(stateDir, "arisa.sock");
 export const tasksFile = path.join(stateDir, "tasks.json");
 export const toolsDir = path.join(arisaHomeDir, "tools");
 export const chatsDir = path.join(arisaHomeDir, "chats");