arisa 4.0.8 → 4.0.12

package/AGENTS.md

@@ -31,6 +31,7 @@ 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
 
 ## Conceptual pipe model
 There are two different moments where pipes can happen:
@@ -71,6 +72,27 @@ 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:

package/README.md

@@ -71,6 +71,8 @@ Each tool folder contains:
 - `tool.manifest.json`
 - `index.js`
 
+`tool.manifest.json` may also include optional `skillHints`; Arisa resolves installed skills and passes them into `run_tool` requests as `skills` guidance, not runtime dependencies.
+
 Each tool is isolated from the root project and from other tools.
 That isolation is part of the architecture:
 
@@ -160,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
-- when `--pi.apiKey` is omitted and the provider supports OAuth, Arisa starts a temporary web page on `PORT` (default `10000`) where you can complete authentication from any browser
+- Arisa's HTTP server listens on `ARISA_HTTP_PORT` (default `91107`); bootstrap OAuth pages and tool-provided web routes use this 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,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "4.0.8",
+  "version": "4.0.12",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",
@@ -37,12 +37,13 @@
   },
   "homepage": "https://github.com/clasen/Arisa#readme",
   "dependencies": {
-    "@mariozechner/pi-coding-agent": "^0.73.1",
+    "@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"
+    "bootstrap": "node src/index.js --bootstrap",
+    "test": "node --test"
   }
 }

package/pnpm-workspace.yaml

@@ -1,3 +1,6 @@
+allowBuilds:
+  '@google/genai': false
+
 overrides:
   '@protobufjs/utf8@<=1.1.0': '>=1.1.1'
   basic-ftp@<=5.2.1: '>=5.2.2'

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

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { unlink } from "node:fs/promises";
-import { createAgentSession, SessionManager, defineTool } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, SessionManager, defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { createPiRuntime, hasProviderAuth } from "./pi-runtime.js";
 import { arisaInstallDir, buildAgentRuntimeContext } from "./runtime-context.js";

package/src/core/agent/pi-auth-login.js

@@ -1,4 +1,4 @@
-import { AuthStorage } from "@mariozechner/pi-coding-agent";
+import { AuthStorage } from "@earendil-works/pi-coding-agent";
 
 export function createPiOAuthLogin({ provider, onAuth, onDeviceCode, onPrompt, onProgress, onSelect } = {}) {
   const authStorage = AuthStorage.create();

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

@@ -1,4 +1,4 @@
-import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
 
 function compareText(a, b) {
   return a.localeCompare(b, undefined, { sensitivity: "base", numeric: true });

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

@@ -2,6 +2,7 @@ import { mkdir, readdir, readFile, rmdir, unlink, writeFile } from "node:fs/prom
 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 { loadToolConfig, parseConfigModule, writeToolConfig } from "./tool-config.js";
 import { normalizeToolResult } from "./tool-result.js";
 import { SkillRegistry } from "../skills/skill-registry.js";
@@ -25,11 +26,14 @@ 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 {
@@ -50,7 +54,7 @@ export class ToolRegistry {
         const defaults = parseConfigModule(configSource);
         const config = await loadToolConfig(manifest.name, defaults);
         const skillHints = this.skillRegistry.normalizeHints(manifest);
-        this.tools.set(manifest.name, {
+        const tool = {
           ...manifest,
           skillHints,
           dir: toolDir,
@@ -59,7 +63,13 @@ 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
       }
@@ -79,6 +89,13 @@ export class ToolRegistry {
     }));
   }
 
+  listWebRoutes() {
+    return this.webRoutes.map((route) => ({
+      ...route,
+      methods: [...route.methods]
+    }));
+  }
+
   get(name) {
     return this.tools.get(name) || null;
   }

package/src/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { createServer } from "node:http";
+import { execFile } from "node:child_process";
 import { bootstrapIfNeeded } from "./runtime/bootstrap.js";
 import { createApp } from "./runtime/create-app.js";
 import { createLogger } from "./runtime/logger.js";
@@ -22,20 +23,126 @@ const logger = createLogger({ verbose });
 let activeApp = null;
 let shuttingDown = false;
 
-const httpPort = Number(process.env.PORT);
+const defaultHttpPort = 91107;
+const httpPort = Number(process.env.ARISA_HTTP_PORT || defaultHttpPort);
+const shouldStartHttpServer = Boolean(httpPort && !["stop", "status", "flush"].includes(command));
 let httpRequestHandler = null;
+let httpServerListening = false;
+let httpServer = null;
 
 function setHttpRequestHandler(handler) {
   httpRequestHandler = handler;
 }
 
-if (httpPort && bootstrapOverrides.telegram) {
-  createServer((req, res) => {
-    if (httpRequestHandler) return httpRequestHandler(req, res);
-    res.writeHead(200, { "Content-Type": "text/plain" });
-    res.end("ok");
-  }).listen(httpPort)
-    .on("listening", () => logger.log("http", `health server on port ${httpPort}`));
+const httpServerReady = shouldStartHttpServer
+  ? startHttpServer()
+  : Promise.resolve(false);
+
+async function runCommand(commandName, args = []) {
+  return new Promise((resolve) => {
+    execFile(commandName, args, (error, stdout = "") => {
+      resolve(error ? "" : stdout.trim());
+    });
+  });
+}
+
+async function getListeningPids(port) {
+  const lsofOutput = await runCommand("lsof", ["-tiTCP", `-sTCP:LISTEN`, `-iTCP:${port}`]);
+  if (lsofOutput) {
+    return lsofOutput.split(/\s+/).map(Number).filter(Number.isFinite);
+  }
+
+  const fuserOutput = await runCommand("fuser", ["-n", "tcp", String(port)]);
+  return fuserOutput.split(/\s+/).map(Number).filter(Number.isFinite);
+}
+
+async function getProcessCommand(pid) {
+  return runCommand("ps", ["-p", String(pid), "-o", "command="]);
+}
+
+function looksLikeArisaProcess(commandText) {
+  return /\barisa\b/.test(commandText) || /\/arisa\/src\/index\.js\b/i.test(commandText);
+}
+
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForProcessExit(pid, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isProcessRunning(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return !isProcessRunning(pid);
+}
+
+async function stopStaleArisaListeners(port) {
+  const pids = await getListeningPids(port);
+  for (const pid of pids) {
+    if (pid === process.pid) continue;
+    const commandText = await getProcessCommand(pid);
+    if (!looksLikeArisaProcess(commandText)) {
+      logger.error("http", `port ${port} is already used by pid ${pid}; not killing non-Arisa process`);
+      continue;
+    }
+
+    logger.log("http", `stopping stale Arisa listener on port ${port} (pid ${pid})`);
+    try {
+      process.kill(pid, "SIGTERM");
+      if (!await waitForProcessExit(pid)) {
+        process.kill(pid, "SIGKILL");
+        await waitForProcessExit(pid, 1000);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error("http", `failed to stop stale Arisa listener pid ${pid}: ${message}`);
+    }
+  }
+}
+
+async function startHttpServer() {
+  await stopStaleArisaListeners(httpPort);
+  return new Promise((resolve) => {
+    const server = createServer((req, res) => {
+      if (httpRequestHandler) return httpRequestHandler(req, res);
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.end("ok");
+      return undefined;
+    });
+    httpServer = server;
+    server.on("error", (error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error("http", `server failed on port ${httpPort}: ${message}`);
+      resolve(false);
+    });
+    server.listen(httpPort)
+      .on("listening", () => {
+        httpServerListening = true;
+        logger.log("http", `health server on port ${httpPort}`);
+        resolve(true);
+      });
+  });
+}
+
+async function getHttpOptions() {
+  await httpServerReady;
+  return httpServerListening ? { httpPort, setHttpRequestHandler } : {};
+}
+
+async function stopHttpServer() {
+  if (!httpServerListening || !httpServer) return;
+  await new Promise((resolve) => {
+    httpServer.close(() => resolve());
+  });
+  httpServer = null;
+  httpServerListening = false;
+  httpRequestHandler = null;
 }
 
 function parseCliArgs(rawArgs) {
@@ -97,15 +204,14 @@ function toServiceRunnerArgs(nestedFlags) {
   return args;
 }
 
-const bootstrapHttpOptions = httpPort ? { httpPort, setHttpRequestHandler } : {};
 const webhookUrl = bootstrapOverrides.webhook?.url || "";
-const appHttpOptions = httpPort ? { webhookUrl, setHttpRequestHandler } : {};
 
 async function shutdown(exitCode = 0) {
   if (shuttingDown) return;
   shuttingDown = true;
   try {
     await activeApp?.stop?.();
+    await stopHttpServer();
   } catch (error) {
     logger.error("app", `shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
     exitCode = exitCode || 1;
@@ -124,8 +230,8 @@ process.once("SIGINT", () => {
   shutdown(0);
 });
 
-async function startRuntimeApp() {
-  const app = await createApp({ logger, runtimeOverrides, ...appHttpOptions });
+async function startRuntimeApp(httpOptions = {}) {
+  const app = await createApp({ logger, runtimeOverrides, webhookUrl, ...httpOptions });
   activeApp = app;
   await app.start();
 }
@@ -137,9 +243,10 @@ async function runForeground() {
     || runtimeOverrides?.pi?.apiKey
   );
   logger.log("app", `starting${verbose ? " in verbose mode" : ""}`);
-  await bootstrapIfNeeded({ force: forceBootstrap, cliConfigOverrides: bootstrapOverrides, ...bootstrapHttpOptions });
+  const httpOptions = await getHttpOptions();
+  await bootstrapIfNeeded({ force: forceBootstrap, cliConfigOverrides: bootstrapOverrides, ...httpOptions });
   try {
-    await startRuntimeApp();
+    await startRuntimeApp(httpOptions);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes("No auth found")) {
@@ -152,8 +259,8 @@ async function runForeground() {
         throw error;
       }
       console.log("Reopening bootstrap so you can provide a Pi API key or switch to a provider you already authenticated with.\n");
-      await bootstrapIfNeeded({ force: true, cliConfigOverrides: bootstrapOverrides, ...bootstrapHttpOptions });
-      await startRuntimeApp();
+      await bootstrapIfNeeded({ force: true, cliConfigOverrides: bootstrapOverrides, ...httpOptions });
+      await startRuntimeApp(httpOptions);
       return;
     }
     throw error;
@@ -168,7 +275,9 @@ async function main() {
   }
 
   if (command === "start") {
-    await bootstrapIfNeeded({ force: forceBootstrap, cliConfigOverrides: bootstrapOverrides, ...bootstrapHttpOptions });
+    const httpOptions = await getHttpOptions();
+    await bootstrapIfNeeded({ force: forceBootstrap, cliConfigOverrides: bootstrapOverrides, ...httpOptions });
+    await stopHttpServer();
     const result = await startService({ verbose, cliArgs: toServiceRunnerArgs(cli.nestedFlags) });
     if (!result.ok) {
       console.log(`Arisa is already running in background (pid ${result.pid}).`);

package/src/runtime/bootstrap.js

@@ -254,7 +254,7 @@ export async function bootstrapIfNeeded({ force = false, cliConfigOverrides = {}
       }
       if (!httpPort || !setHttpRequestHandler) {
         throw new Error(
-          `No auth found for ${resolvedPi.provider}. Auth relay requires an HTTP server on PORT. Provide --pi.apiKey or set the PORT environment variable.`
+          `No auth found for ${resolvedPi.provider}. Arisa's HTTP server is unavailable; set ARISA_HTTP_PORT or free the configured port.`
         );
       }
       const authRelay = installAuthRelay(httpPort, setHttpRequestHandler);

package/src/runtime/create-app.js

@@ -1,3 +1,4 @@
+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";
@@ -6,6 +7,14 @@ 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";
 
 function normalizeString(value) {
   const text = String(value ?? "").trim();
@@ -44,6 +53,29 @@ 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();
@@ -60,7 +92,33 @@ 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 });
-  const bot = await createTelegramBot({ config, artifactStore, toolRegistry, taskStore, agentManager, saveConfig, updateConfig, logger, webhookUrl, setHttpRequestHandler });
+  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 });
 
   return {
     async start() {

package/src/runtime/web/route-validation.js

@@ -0,0 +1,115 @@
+import path from "node:path";
+
+export const RESERVED_EXACT = ["/"];
+export const RESERVED_PATHS = ["/health"];
+export const RESERVED_PREFIXES = ["/telegram-", "/api", "/auth"];
+
+const DEFAULT_METHODS = ["GET"];
+
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeMethods(methods, isPublic) {
+  const requested = methods == null ? DEFAULT_METHODS : methods;
+  if (!Array.isArray(requested) || requested.length === 0) {
+    throw new Error("methods must be a non-empty array");
+  }
+
+  const normalized = requested.map((method) => {
+    if (typeof method !== "string" || !method.trim()) {
+      throw new Error("methods must contain only non-empty strings");
+    }
+    return method.trim().toUpperCase();
+  });
+
+  if (!isPublic && methods == null) return normalized;
+  return [...new Set(normalized)];
+}
+
+export function isReservedPath(routePath) {
+  return RESERVED_EXACT.includes(routePath)
+    || RESERVED_PATHS.includes(routePath)
+    || RESERVED_PREFIXES.some((prefix) => routePath === prefix || routePath.startsWith(prefix));
+}
+
+export function validateRoutePath(routePath) {
+  if (typeof routePath !== "string" || !routePath.startsWith("/")) {
+    throw new Error("path must be a string that starts with /");
+  }
+  if (routePath.includes("..")) {
+    throw new Error("path must not contain ..");
+  }
+  if (isReservedPath(routePath)) {
+    throw new Error(`path is reserved: ${routePath}`);
+  }
+  return routePath;
+}
+
+export function resolveHandlerWithinTool(toolDir, handlerRel) {
+  if (typeof handlerRel !== "string" || !handlerRel.trim()) {
+    throw new Error("handler must be a non-empty string");
+  }
+  if (path.isAbsolute(handlerRel)) {
+    throw new Error("handler must be relative to the tool directory");
+  }
+  if (handlerRel.includes("..")) {
+    throw new Error("handler must not contain ..");
+  }
+
+  const root = path.resolve(toolDir);
+  const handlerPath = path.resolve(root, handlerRel);
+  const relative = path.relative(root, handlerPath);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("handler must resolve inside the tool directory");
+  }
+  return handlerPath;
+}
+
+export function validateToolWebRoutes(manifest, toolDir, claimedPaths = new Map()) {
+  const routes = [];
+  const errors = [];
+  const toolName = manifest?.name;
+  const manifestRoutes = manifest?.web?.routes;
+
+  if (manifestRoutes == null) return { routes, errors };
+  if (!Array.isArray(manifestRoutes)) {
+    return { routes, errors: [{ toolName, error: "web.routes must be an array" }] };
+  }
+
+  for (const [index, route] of manifestRoutes.entries()) {
+    try {
+      if (!isObject(route)) {
+        throw new Error("route must be an object");
+      }
+
+      const routePath = validateRoutePath(route.path);
+      const previousTool = claimedPaths.get(routePath);
+      if (previousTool && previousTool !== toolName) {
+        throw new Error(`path collides with tool ${previousTool}: ${routePath}`);
+      }
+
+      const isPublic = route.public === true;
+      const methods = normalizeMethods(route.methods, isPublic);
+      const handlerPath = resolveHandlerWithinTool(toolDir, route.handler);
+
+      claimedPaths.set(routePath, toolName);
+      routes.push({
+        toolName,
+        path: routePath,
+        methods,
+        public: isPublic,
+        handlerPath
+      });
+    } catch (error) {
+      errors.push({
+        toolName,
+        index,
+        path: route?.path,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return { routes, errors };
+}

package/src/runtime/web/web-router.js

@@ -0,0 +1,167 @@
+import crypto from "node:crypto";
+import { pathToFileURL } from "node:url";
+
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+function sendText(res, statusCode, text, headers = {}) {
+  if (res.headersSent || res.writableEnded) return;
+  res.writeHead(statusCode, {
+    "Content-Type": "text/plain; charset=utf-8",
+    ...headers
+  });
+  res.end(text);
+}
+
+function safePathname(req) {
+  try {
+    return new URL(req.url || "/", "http://localhost").pathname;
+  } catch {
+    return "/";
+  }
+}
+
+function methodKey(method, routePath) {
+  return `${String(method || "GET").toUpperCase()} ${routePath}`;
+}
+
+function extractBearerToken(req, parsedUrl) {
+  const authorization = req.headers.authorization || "";
+  const match = authorization.match(/^Bearer\s+(.+)$/i);
+  if (match) return match[1].trim();
+  return parsedUrl.searchParams.get("token") || "";
+}
+
+function timingSafeEqualString(actual, expected) {
+  if (!actual || !expected) return false;
+  const actualBuffer = Buffer.from(actual);
+  const expectedBuffer = Buffer.from(expected);
+  if (actualBuffer.length !== expectedBuffer.length) return false;
+  return crypto.timingSafeEqual(actualBuffer, expectedBuffer);
+}
+
+function installBodyLimit(req, res, limitBytes) {
+  const contentLength = Number(req.headers["content-length"] || 0);
+  if (Number.isFinite(contentLength) && contentLength > limitBytes) {
+    sendText(res, 413, "request body too large\n");
+    req.destroy();
+    return false;
+  }
+
+  let total = 0;
+  const originalEmit = req.emit;
+  req.emit = function emitWithBodyLimit(eventName, ...args) {
+    if (eventName === "data" && !res.writableEnded) {
+      const chunk = args[0];
+      total += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk || ""));
+      if (total > limitBytes) {
+        sendText(res, 413, "request body too large\n");
+        req.destroy();
+        return false;
+      }
+    }
+    return originalEmit.call(this, eventName, ...args);
+  };
+  return true;
+}
+
+function parseChatId(parsedUrl) {
+  const raw = parsedUrl.searchParams.get("chatId");
+  if (raw == null || raw.trim() === "") return null;
+  const numberValue = Number(raw);
+  return Number.isSafeInteger(numberValue) ? numberValue : raw;
+}
+
+export function createWebRouter({
+  getRoutes,
+  buildContext,
+  getToken,
+  logger,
+  limits = {}
+} = {}) {
+  const coreRoutes = new Map();
+  const handlerCache = new Map();
+  const bodyLimitBytes = limits.bodyLimitBytes || DEFAULT_BODY_LIMIT_BYTES;
+  const timeoutMs = limits.timeoutMs || DEFAULT_TIMEOUT_MS;
+
+  async function loadHandler(route) {
+    if (!handlerCache.has(route.handlerPath)) {
+      handlerCache.set(route.handlerPath, import(pathToFileURL(route.handlerPath).href));
+    }
+    const module = await handlerCache.get(route.handlerPath);
+    if (typeof module.handleWebRequest !== "function") {
+      throw new Error(`handler does not export handleWebRequest: ${route.handlerPath}`);
+    }
+    return module.handleWebRequest;
+  }
+
+  function registerCoreRoute({ method, path, handler }) {
+    if (typeof method !== "string" || typeof path !== "string" || typeof handler !== "function") {
+      throw new Error("core route requires method, path, and handler");
+    }
+    coreRoutes.set(methodKey(method, path), handler);
+  }
+
+  async function dispatch(req, res) {
+    const parsedUrl = new URL(req.url || "/", "http://localhost");
+    const pathname = parsedUrl.pathname;
+    const method = String(req.method || "GET").toUpperCase();
+    const coreHandler = coreRoutes.get(methodKey(method, pathname));
+    if (coreHandler) {
+      return coreHandler(req, res);
+    }
+
+    const route = (getRoutes?.() || []).find((item) => item.path === pathname);
+    if (!route) {
+      sendText(res, 200, "ok");
+      return undefined;
+    }
+
+    const timeout = setTimeout(() => {
+      sendText(res, 504, "request timed out\n");
+      req.destroy();
+    }, timeoutMs);
+    timeout.unref?.();
+
+    try {
+      if (!installBodyLimit(req, res, bodyLimitBytes)) return undefined;
+
+      const token = getToken?.() || "";
+      if (!route.public && !timingSafeEqualString(extractBearerToken(req, parsedUrl), token)) {
+        sendText(res, 401, "unauthorized\n", { "WWW-Authenticate": "Bearer" });
+        return undefined;
+      }
+
+      const methods = route.methods || ["GET"];
+      if (!methods.includes(method)) {
+        sendText(res, 405, "method not allowed\n", { Allow: methods.join(", ") });
+        return undefined;
+      }
+
+      logger?.log?.("web", `${route.toolName} ${method} ${pathname}`);
+      const handleWebRequest = await loadHandler(route);
+      const context = buildContext?.({
+        toolName: route.toolName,
+        route,
+        req,
+        res,
+        parsedUrl,
+        chatId: parseChatId(parsedUrl)
+      }) || { toolName: route.toolName, chatId: parseChatId(parsedUrl) };
+      await handleWebRequest(req, res, context);
+      return undefined;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger?.error?.("web", `${route.toolName} ${safePathname(req)}: ${message}`);
+      sendText(res, 500, "internal server error\n");
+      return undefined;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  return {
+    dispatch,
+    registerCoreRoute
+  };
+}

package/src/transport/telegram/bot.js

@@ -185,6 +185,13 @@ function sessionEventLogMessage(event) {
   return "";
 }
 
+function buildStartupMessage(chatMeta = {}) {
+  const languageCode = String(chatMeta.languageCode || "").toLowerCase();
+  if (languageCode.startsWith("es")) return "Arisa esta en linea de nuevo.";
+  if (languageCode.startsWith("pt")) return "Arisa esta online de novo.";
+  return "Arisa is back online.";
+}
+
 async function collectText(session, prompt, { logger, chatId, onSlowPrompt } = {}) {
   let text = "";
   let assistantErrorMessage = "";
@@ -244,7 +251,7 @@ async function withTyping(ctx, work) {
   }
 }
 
-export async function createTelegramBot({ config, artifactStore, toolRegistry, taskStore, agentManager, saveConfig, updateConfig, logger, webhookUrl, setHttpRequestHandler }) {
+export async function createTelegramBot({ config, artifactStore, toolRegistry, taskStore, agentManager, saveConfig, updateConfig, logger, webhookUrl, webRouter }) {
   const bot = new Bot(config.telegram.token);
   const perChatState = new Map();
   const notifiedPromptErrors = new WeakSet();
@@ -522,6 +529,31 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
     });
   }
 
+  async function sendStartupMessages() {
+    for (const chatId of config.telegram.authorizedChatIds || []) {
+      try {
+        logger?.log("telegram", `sending startup message for chat ${chatId}`);
+        const chatMeta = config.telegram.chatMeta[chatId] || {};
+        await bot.api.sendMessage(chatId, buildStartupMessage(chatMeta));
+      } catch (error) {
+        logger?.log("telegram", `startup message failed for chat ${chatId}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
+  function scheduleStartupMessages({ skipAgentStartupPrompts = false } = {}) {
+    if (skipAgentStartupPrompts) {
+      logger?.log("telegram", "skipping startup messages because Pi auth needs attention");
+      return;
+    }
+    const timer = setTimeout(() => {
+      sendStartupMessages().catch((error) => {
+        logger?.log("telegram", `startup messages failed: ${error instanceof Error ? error.message : String(error)}`);
+      });
+    }, 0);
+    timer.unref?.();
+  }
+
   async function dispatchTask(task) {
     const chatId = task.payload?.chatId;
     if (!chatId) {
@@ -692,30 +724,6 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
   return {
     async start({ skipAgentStartupPrompts = false } = {}) {
       config.telegram.chatMeta ||= {};
-      if (skipAgentStartupPrompts) {
-        logger?.log("telegram", "skipping agent startup messages because Pi auth needs attention");
-      } else {
-        for (const chatId of config.telegram.authorizedChatIds || []) {
-          try {
-            logger?.log("telegram", `generating startup message for chat ${chatId}`);
-            const chatMeta = config.telegram.chatMeta[chatId] || {};
-            const welcomePrompt = [
-              "System event: Arisa has just started.",
-              `chatId: ${chatId}`,
-              `preferredTelegramLanguageCode: ${chatMeta.languageCode || "unknown"}`,
-              chatMeta.username ? `username: ${chatMeta.username}` : null,
-              chatMeta.firstName ? `firstName: ${chatMeta.firstName}` : null,
-              "Send a short welcome-back message for Telegram.",
-              "Keep it brief, warm, and natural.",
-              "Use the user's Telegram language when possible.",
-              "Do not mention internal implementation details."
-            ].filter(Boolean).join("\n");
-            await enqueuePrompt({ chatId, prompt: welcomePrompt, label: "startup message" });
-          } catch (error) {
-            logger?.log("telegram", `startup message failed for chat ${chatId}: ${error instanceof Error ? error.message : String(error)}`);
-          }
-        }
-      }
       await bot.api.setMyCommands([
         { command: "new", description: "Start a new chat context" },
         { command: "auth", description: "Show Pi authentication status" }
@@ -728,24 +736,23 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
         }, 1000);
         taskTimer.unref();
       }
-      if (webhookUrl && setHttpRequestHandler) {
+      if (webhookUrl && webRouter) {
         const webhookPath = `/telegram-${config.telegram.token.slice(-8)}`;
         const handleUpdate = webhookCallback(bot, "http", {
           timeoutMilliseconds: 60_000,
           onTimeout: "return",
         });
-        setHttpRequestHandler((req, res) => {
-          const parsed = new URL(req.url, "http://localhost");
-          if (req.method === "POST" && parsed.pathname === webhookPath) {
-            return handleUpdate(req, res);
-          }
-          res.writeHead(200, { "Content-Type": "text/plain" });
-          res.end("ok");
+        webRouter.registerCoreRoute({
+          method: "POST",
+          path: webhookPath,
+          handler: handleUpdate
         });
         await bot.api.setWebhook(`${webhookUrl}${webhookPath}`);
         logger?.log("telegram", `webhook mode: ${webhookUrl}${webhookPath}`);
+        scheduleStartupMessages({ skipAgentStartupPrompts });
       } else {
         logger?.log("telegram", "bot polling started");
+        scheduleStartupMessages({ skipAgentStartupPrompts });
         await bot.start({ drop_pending_updates: true });
       }
     },

package/test/route-validation.test.js

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import { mkdtemp } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  isReservedPath,
+  validateToolWebRoutes
+} from "../src/runtime/web/route-validation.js";
+
+async function tempToolDir(name) {
+  const root = await mkdtemp(path.join(os.tmpdir(), "arisa-route-validation-"));
+  return path.join(root, name);
+}
+
+test("loads valid tool web routes", async () => {
+  const toolDir = await tempToolDir("alpha");
+  const claimedPaths = new Map();
+  const manifest = {
+    name: "alpha",
+    web: {
+      routes: [
+        { path: "/alpha", handler: "web/index.js" }
+      ]
+    }
+  };
+
+  const { routes, errors } = validateToolWebRoutes(manifest, toolDir, claimedPaths);
+
+  assert.deepEqual(errors, []);
+  assert.equal(routes.length, 1);
+  assert.equal(routes[0].toolName, "alpha");
+  assert.equal(routes[0].path, "/alpha");
+  assert.deepEqual(routes[0].methods, ["GET"]);
+  assert.equal(routes[0].public, false);
+  assert.equal(routes[0].handlerPath, path.join(toolDir, "web", "index.js"));
+});
+
+test("rejects invalid and reserved route paths", async () => {
+  const toolDir = await tempToolDir("bad");
+  const invalidPaths = ["/", "/health", "/api", "/api/tools", "/telegram-secret", "/has/../dotdot", "relative"];
+
+  for (const routePath of invalidPaths) {
+    const { routes, errors } = validateToolWebRoutes({
+      name: "bad",
+      web: { routes: [{ path: routePath, handler: "web/index.js" }] }
+    }, toolDir, new Map());
+
+    assert.equal(routes.length, 0, routePath);
+    assert.equal(errors.length, 1, routePath);
+  }
+
+  assert.equal(isReservedPath("/telegram-token"), true);
+  assert.equal(isReservedPath("/custom"), false);
+});
+
+test("rejects route collisions between tools", async () => {
+  const firstToolDir = await tempToolDir("first");
+  const secondToolDir = await tempToolDir("second");
+  const claimedPaths = new Map();
+
+  const first = validateToolWebRoutes({
+    name: "first",
+    web: { routes: [{ path: "/shared", handler: "web/index.js" }] }
+  }, firstToolDir, claimedPaths);
+
+  const second = validateToolWebRoutes({
+    name: "second",
+    web: { routes: [{ path: "/shared", handler: "web/index.js" }] }
+  }, secondToolDir, claimedPaths);
+
+  assert.equal(first.routes.length, 1);
+  assert.equal(second.routes.length, 0);
+  assert.match(second.errors[0].error, /collides with tool first/);
+});
+
+test("rejects handlers outside the tool directory", async () => {
+  const toolDir = await tempToolDir("escape");
+
+  const { routes, errors } = validateToolWebRoutes({
+    name: "escape",
+    web: { routes: [{ path: "/escape", handler: "../outside.js" }] }
+  }, toolDir, new Map());
+
+  assert.equal(routes.length, 0);
+  assert.equal(errors.length, 1);
+  assert.match(errors[0].error, /handler must not contain \.\./);
+});

package/test/web-router.test.js

@@ -0,0 +1,267 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { createWebRouter } from "../src/runtime/web/web-router.js";
+
+async function createHandlerFiles() {
+  const root = await mkdtemp(path.join(os.tmpdir(), "arisa-web-router-"));
+  await mkdir(root, { recursive: true });
+  const okHandler = path.join(root, "ok.js");
+  const errorHandler = path.join(root, "error.js");
+
+  await writeFile(okHandler, `export async function handleWebRequest(_req, res, context) {
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ toolName: context.toolName, chatId: context.chatId }));
+}
+`, "utf8");
+
+  await writeFile(errorHandler, `export async function handleWebRequest() {
+  throw new Error("secret stack marker");
+}
+`, "utf8");
+
+  return { okHandler, errorHandler };
+}
+
+function buildRouter({ routes, token = "secret-token", limits, logger } = {}) {
+  return createWebRouter({
+    getRoutes: () => routes,
+    getToken: () => token,
+    logger,
+    limits,
+    buildContext: ({ toolName, chatId }) => ({ toolName, chatId })
+  });
+}
+
+async function startRouterServer(router) {
+  const server = createServer((req, res) => {
+    router.dispatch(req, res);
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  const baseUrl = `http://127.0.0.1:${address.port}`;
+  return {
+    baseUrl,
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => error ? reject(error) : resolve());
+    })
+  };
+}
+
+test("protected routes require the shared bearer token", async () => {
+  const { okHandler } = await createHandlerFiles();
+  const routes = [
+    { toolName: "private-tool", path: "/private", methods: ["GET"], public: false, handlerPath: okHandler }
+  ];
+  const router = createWebRouter({
+    getRoutes: () => routes,
+    getToken: () => "secret-token",
+    buildContext: ({ toolName, chatId }) => ({ toolName, chatId })
+  });
+  const server = await startRouterServer(router);
+
+  try {
+    const rejected = await fetch(`${server.baseUrl}/private`);
+    assert.equal(rejected.status, 401);
+
+    const accepted = await fetch(`${server.baseUrl}/private?chatId=123`, {
+      headers: { Authorization: "Bearer secret-token" }
+    });
+    assert.equal(accepted.status, 200);
+    assert.deepEqual(await accepted.json(), { toolName: "private-tool", chatId: 123 });
+  } finally {
+    await server.close();
+  }
+});
+
+test("public routes do not require a token", async () => {
+  const { okHandler } = await createHandlerFiles();
+  const routes = [
+    { toolName: "public-tool", path: "/public", methods: ["GET"], public: true, handlerPath: okHandler }
+  ];
+  const router = createWebRouter({
+    getRoutes: () => routes,
+    getToken: () => "secret-token",
+    buildContext: ({ toolName, chatId }) => ({ toolName, chatId })
+  });
+  const server = await startRouterServer(router);
+
+  try {
+    const response = await fetch(`${server.baseUrl}/public`);
+    assert.equal(response.status, 200);
+    assert.deepEqual(await response.json(), { toolName: "public-tool", chatId: null });
+  } finally {
+    await server.close();
+  }
+});
+
+test("disallows undeclared HTTP methods", async () => {
+  const { okHandler } = await createHandlerFiles();
+  const routes = [
+    { toolName: "public-tool", path: "/public", methods: ["GET"], public: true, handlerPath: okHandler }
+  ];
+  const router = createWebRouter({
+    getRoutes: () => routes,
+    getToken: () => "secret-token",
+    buildContext: ({ toolName, chatId }) => ({ toolName, chatId })
+  });
+  const server = await startRouterServer(router);
+
+  try {
+    const response = await fetch(`${server.baseUrl}/public`, { method: "POST" });
+    assert.equal(response.status, 405);
+    assert.equal(response.headers.get("allow"), "GET");
+  } finally {
+    await server.close();
+  }
+});
+
+test("handler errors do not expose stack traces to clients", async () => {
+  const { errorHandler } = await createHandlerFiles();
+  const logs = [];
+  const routes = [
+    { toolName: "error-tool", path: "/error", methods: ["GET"], public: true, handlerPath: errorHandler }
+  ];
+  const router = createWebRouter({
+    getRoutes: () => routes,
+    getToken: () => "secret-token",
+    logger: { error: (scope, message) => logs.push({ scope, message }) },
+    buildContext: ({ toolName, chatId }) => ({ toolName, chatId })
+  });
+  const server = await startRouterServer(router);
+
+  try {
+    const response = await fetch(`${server.baseUrl}/error`);
+    const body = await response.text();
+    assert.equal(response.status, 500);
+    assert.equal(body.includes("secret stack marker"), false);
+    assert.equal(body.includes("Error:"), false);
+    assert.equal(logs[0].scope, "web");
+    assert.match(logs[0].message, /secret stack marker/);
+  } finally {
+    await server.close();
+  }
+});
+
+test("core routes take precedence over tool routes", async () => {
+  const { okHandler } = await createHandlerFiles();
+  const router = buildRouter({
+    routes: [
+      { toolName: "tool", path: "/health", methods: ["GET"], public: true, handlerPath: okHandler }
+    ]
+  });
+  router.registerCoreRoute({
+    method: "GET",
+    path: "/health",
+    handler: (_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("core-health");
+    }
+  });
+  const server = await startRouterServer(router);
+
+  try {
+    const response = await fetch(`${server.baseUrl}/health`);
+    assert.equal(response.status, 200);
+    assert.equal(await response.text(), "core-health");
+  } finally {
+    await server.close();
+  }
+});
+
+test("unknown paths return a plain ok response", async () => {
+  const router = buildRouter({ routes: [] });
+  const server = await startRouterServer(router);
+
+  try {
+    const response = await fetch(`${server.baseUrl}/does-not-exist`);
+    assert.equal(response.status, 200);
+    assert.equal(await response.text(), "ok");
+  } finally {
+    await server.close();
+  }
+});
+
+test("rejects request bodies over the configured limit", async () => {
+  const { okHandler } = await createHandlerFiles();
+  const router = buildRouter({
+    routes: [
+      { toolName: "upload-tool", path: "/upload", methods: ["POST"], public: true, handlerPath: okHandler }
+    ],
+    limits: { bodyLimitBytes: 8 }
+  });
+  const server = await startRouterServer(router);
+
+  try {
+    const response = await fetch(`${server.baseUrl}/upload`, {
+      method: "POST",
+      body: "x".repeat(64)
+    });
+    assert.equal(response.status, 413);
+  } finally {
+    await server.close();
+  }
+});
+
+test("accepts the shared token from the query string", async () => {
+  const { okHandler } = await createHandlerFiles();
+  const router = buildRouter({
+    routes: [
+      { toolName: "private-tool", path: "/private", methods: ["GET"], public: false, handlerPath: okHandler }
+    ]
+  });
+  const server = await startRouterServer(router);
+
+  try {
+    const response = await fetch(`${server.baseUrl}/private?token=secret-token`);
+    assert.equal(response.status, 200);
+  } finally {
+    await server.close();
+  }
+});
+
+test("rejects wrong tokens and locks down protected routes without a configured token", async () => {
+  const { okHandler } = await createHandlerFiles();
+  const protectedRoute = { toolName: "private-tool", path: "/private", methods: ["GET"], public: false, handlerPath: okHandler };
+
+  const wrongTokenServer = await startRouterServer(buildRouter({ routes: [protectedRoute] }));
+  try {
+    const response = await fetch(`${wrongTokenServer.baseUrl}/private`, {
+      headers: { Authorization: "Bearer wrong-token" }
+    });
+    assert.equal(response.status, 401);
+  } finally {
+    await wrongTokenServer.close();
+  }
+
+  const noTokenServer = await startRouterServer(buildRouter({ routes: [protectedRoute], token: "" }));
+  try {
+    const response = await fetch(`${noTokenServer.baseUrl}/private`, {
+      headers: { Authorization: "Bearer anything" }
+    });
+    assert.equal(response.status, 401);
+  } finally {
+    await noTokenServer.close();
+  }
+});
+
+test("passes a non-numeric chatId through to the handler context", async () => {
+  const { okHandler } = await createHandlerFiles();
+  const router = buildRouter({
+    routes: [
+      { toolName: "public-tool", path: "/public", methods: ["GET"], public: true, handlerPath: okHandler }
+    ]
+  });
+  const server = await startRouterServer(router);
+
+  try {
+    const response = await fetch(`${server.baseUrl}/public?chatId=team-7`);
+    assert.equal(response.status, 200);
+    assert.deepEqual(await response.json(), { toolName: "public-tool", chatId: "team-7" });
+  } finally {
+    await server.close();
+  }
+});