arisa 3.0.3 → 3.0.6

package/AGENTS.md

@@ -5,7 +5,7 @@
 - `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.
-- `cli/*`: isolated tools. Each tool has `package.json`, `config.js`, `tool.manifest.json`, and `index.js`.
+- `tools/*`: isolated tools. Each tool has `package.json`, `config.js`, `tool.manifest.json`, and `index.js`.
 
 ## Main rule: everything is piped through artifacts
 A pipe transforms one input artifact into one output artifact.
@@ -70,20 +70,27 @@ 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 `cli/<tool>/config.js` with `set_tool_config`
+2. write the value into `~/.arisa/tools/<tool>/config.js` 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.
 
-## Telegram security
-- The first chat that messages the bot is authorized if `telegram.maxChatIds` allows it.
-- Do not authorize more chats than configured.
-- Access control is based on chat ids, not usernames.
+## 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
+
+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."
 
 ## 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 `cli/<tool-name>` following the project conventions.
+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:
@@ -101,7 +108,7 @@ When creating or editing tools, follow the shared path helpers in `src/runtime/p
 Consult the local skill for that workflow when building new tools.
 
 ## Safety
-- Do not install or run arbitrary tools outside registered `cli/*` manifests in V1.
+- Do not install or run arbitrary tools outside registered `tools/*` manifests in V1.
 - Prefer tool manifests and CLI help over assumptions.
 - Keep tool configs inside `~/.arisa/tools/<tool>/config.js`.
 - Be proactive about extending capabilities, but do it through the project's tool architecture, not through ad hoc one-off behavior.

package/README.md

@@ -6,11 +6,11 @@ Arisa is a personal Telegram assistant powered by Pi Agent.
 
 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 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.
+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.
 
 Telegram bots, on the other hand, work extremely well as a human interface. Simple, reliable, always in your pocket.
 
-So Arisa keeps exactly those two things — Pi Agent and Telegram — and nothing more. No pre-loaded opinions about what the agent should do or which tools it should have. The idea is that the agent builds itself around the user, not the other way around.
+So Arisa keeps exactly those two things (Pi Agent & Telegram) and nothing more. No pre-loaded opinions about what the agent should do or which tools it should have. The idea is that the agent builds itself around the user, not the other way around.
 
 It is designed around a simple idea:
 
@@ -46,7 +46,7 @@ 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 `cli/<tool-name>` and contains:
+Each tool lives in its own folder under `tools/<tool-name>` and contains:
 
 - `package.json`
 - `config.js`
@@ -57,7 +57,7 @@ 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 keeps its own `config.js`
+- each tool has a local `config.js` only for defaults/template values
 - each tool can have its own dependencies
 - one tool can be changed or replaced without tightly coupling the rest of the system
 
@@ -74,6 +74,7 @@ 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>/`
 - durable files should end up in `~/.arisa/artifacts/`
 - Pi authentication can use either:
@@ -92,6 +93,16 @@ Then run:
 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
+```
+
 ## Bootstrap flow
 
 On first run, Arisa will:
@@ -146,7 +157,7 @@ src/
   runtime/      bootstrap + app startup
   transport/    Telegram integration
   core/         agent, tools, artifacts, config
-cli/
+tools/
   openai-transcribe/
   openai-tts/
 ~/.arisa/
@@ -158,7 +169,9 @@ cli/
 
 ## Philosophy
 
-The agent should not come preloaded with vices or assumptions. It starts minimal and grows through real use — shaped by the user, not by the framework.
+The agent should not come preloaded with vices or assumptions. It starts minimal and grows through real use: shaped by the user, not by the framework.
+
+For consistency, the entire Arisa codebase was built using Pi Agent itself, running on Codex: the model bundled with ChatGPT Plus. The goal was to see how far a model that most people already have access to could go when given a good harness. The experience was genuinely satisfying: having the agent reason about, extend, and improve its own system is exactly the kind of recursive loop the project is designed for.
 
 When a capability is missing:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "3.0.3",
+  "version": "3.0.6",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",
@@ -22,12 +22,15 @@
     "agent",
     "SOUL.md",
     "tinyclaw",
+    "nullclaw",
+    "picoclaw",
+    "zeroclaw",
     "jarvis",
     "AGENTS.md",
     "clasen"
   ],
   "author": "",
-  "license": "ISC",
+  "license": "GLP",
   "packageManager": "pnpm@10.32.1",
   "dependencies": {
     "@mariozechner/pi-coding-agent": "^0.65.0",

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

@@ -3,14 +3,15 @@ import { mkdir, 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";
-
-const agentDir = path.resolve("data/pi-agent");
+import { loadProjectInstructions } from "./project-instructions.js";
+import { getChatDir, piAgentDir as agentDir } from "../../runtime/paths.js";
 
 export class AgentManager {
-  constructor({ config, artifactStore, toolRegistry }) {
+  constructor({ config, artifactStore, toolRegistry, logger }) {
     this.config = config;
     this.artifactStore = artifactStore;
     this.toolRegistry = toolRegistry;
+    this.logger = logger;
     this.sessions = new Map();
   }
 
@@ -20,6 +21,7 @@ export class AgentManager {
   }
 
   async validatePiAgent() {
+    this.logger?.log("agent", "validating Pi session");
     const { authStorage, modelRegistry } = createPiRuntime({
       provider: this.config.pi.provider,
       apiKey: this.config.pi.apiKey
@@ -42,7 +44,10 @@ export class AgentManager {
   }
 
   async getSessionContext(chatId, telegram) {
-    if (this.sessions.has(chatId)) return this.sessions.get(chatId);
+    if (this.sessions.has(chatId)) {
+      this.logger?.log("agent", `reusing session for chat ${chatId}`);
+      return this.sessions.get(chatId);
+    }
 
     await mkdir(agentDir, { recursive: true });
     const { authStorage, modelRegistry } = createPiRuntime({
@@ -55,9 +60,10 @@ 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 = path.resolve("data/chats", String(chatId));
+    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,
@@ -69,6 +75,10 @@ export class AgentManager {
       sessionManager: SessionManager.continueRecent(cwd)
     });
 
+    const instructions = await loadProjectInstructions();
+    this.logger?.log("agent", `injecting project instructions for chat ${chatId}`);
+    await session.prompt(`${instructions}\n\nAcknowledge with exactly: OK`);
+
     const ctx = { session };
     this.sessions.set(chatId, ctx);
     return ctx;
@@ -123,6 +133,7 @@ export class AgentManager {
         }),
         execute: async (_id, params) => {
           await this.toolRegistry.load();
+          this.logger?.log("agent", `run_tool ${params.name}`);
           let artifact = null;
           if (params.artifactId) {
             artifact = await this.artifactStore.get(params.artifactId);
@@ -168,13 +179,22 @@ export class AgentManager {
         }
       }),
       defineTool({
-        name: "send_audio_reply",
-        label: "Send audio reply",
-        description: "Generate speech from text with a CLI tool and send it to the current Telegram chat.",
-        parameters: Type.Object({ text: Type.String(), toolName: Type.Optional(Type.String()) }),
+        name: "send_media_reply",
+        label: "Send media reply",
+        description: "Run a CLI tool that generates a file and send it to the current Telegram chat using the tool's delivery hint or an explicit method.",
+        parameters: Type.Object({
+          text: Type.String(),
+          toolName: Type.Optional(Type.String()),
+          method: Type.Optional(Type.Union([
+            Type.Literal("voice"),
+            Type.Literal("audio"),
+            Type.Literal("document")
+          ]))
+        }),
         execute: async (_id, params) => {
           await this.toolRegistry.load();
           const toolName = params.toolName || "openai-tts";
+          this.logger?.log("agent", `send_media_reply via ${toolName}`);
           const result = await this.toolRegistry.run({
             name: toolName,
             request: { text: params.text, args: {} }
@@ -182,9 +202,13 @@ export class AgentManager {
           if (!result.ok || !result.output?.filePath) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
           }
-          await telegram.sendAudio(result.output.filePath, params.text);
+          const method = params.method || result.output?.delivery?.method || "audio";
+          await telegram.sendMedia(result.output.filePath, { method, caption: params.text });
           await unlink(result.output.filePath).catch(() => {});
-          return { content: [{ type: "text", text: "Audio enviado por Telegram." }], details: result };
+          return {
+            content: [{ type: "text", text: `Media sent to Telegram as ${method}.` }],
+            details: { ...result, sent: { method } }
+          };
         }
       })
     ];

package/src/core/agent/project-instructions.js

@@ -0,0 +1,11 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const instructionsPath = fileURLToPath(new URL("../../../AGENTS.md", import.meta.url));
+let cachedInstructions = null;
+
+export async function loadProjectInstructions() {
+  if (cachedInstructions !== null) return cachedInstructions;
+  cachedInstructions = await readFile(instructionsPath, "utf8");
+  return cachedInstructions;
+}

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

@@ -4,7 +4,7 @@ import { spawn } from "node:child_process";
 import { getToolConfigPath, getToolTmpDir } from "../../runtime/paths.js";
 import { loadToolConfig, parseConfigModule, writeToolConfig } from "./tool-config.js";
 
-const cliRoot = path.resolve("cli");
+const toolsRoot = path.resolve("tools");
 
 function runProcess(command, args, options = {}) {
   return new Promise((resolve) => {
@@ -18,22 +18,25 @@ function runProcess(command, args, options = {}) {
 }
 
 export class ToolRegistry {
-  constructor() {
+  constructor({ logger } = {}) {
+    this.logger = logger;
     this.tools = new Map();
   }
 
   async load() {
     this.tools.clear();
+
     let entries = [];
     try {
-      entries = await readdir(cliRoot, { withFileTypes: true });
+      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(cliRoot, entry.name);
+      const toolDir = path.join(toolsRoot, entry.name);
       const manifestPath = path.join(toolDir, "tool.manifest.json");
       const configPath = path.join(toolDir, "config.js");
       try {
@@ -54,6 +57,8 @@ export class ToolRegistry {
         // ignore invalid tool dirs in v1
       }
     }
+
+    this.logger?.log("tools", `loaded ${this.tools.size} tool(s)`);
   }
 
   list() {
@@ -91,6 +96,7 @@ export class ToolRegistry {
   async run({ name, request }) {
     const tool = this.get(name);
     if (!tool) throw new Error(`Tool not found: ${name}`);
+    this.logger?.log("tools", `running ${name}`);
     const tmpDir = getToolTmpDir(name);
     await mkdir(tmpDir, { recursive: true });
     const requestFile = path.join(tmpDir, `.request-${Date.now()}.json`);
@@ -102,6 +108,7 @@ 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;
     } catch {
       return {

package/src/index.js

@@ -2,13 +2,22 @@
 
 import { bootstrapIfNeeded } from "./runtime/bootstrap.js";
 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";
 
-const forceBootstrap = process.argv.includes("--bootstrap");
+const args = process.argv.slice(2);
+const command = args.find((arg) => !arg.startsWith("--")) || "run";
+const forceBootstrap = args.includes("--bootstrap");
+const verbose = args.includes("--verbose");
+const serviceRunner = args.includes("--service-runner");
+const logger = createLogger({ verbose });
 
-async function main() {
+async function runForeground() {
+  logger.log("app", `starting${verbose ? " in verbose mode" : ""}`);
   await bootstrapIfNeeded({ force: forceBootstrap });
   try {
-    const app = await createApp();
+    const app = await createApp({ logger });
     await app.start();
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -16,7 +25,7 @@ async function main() {
       console.log(`\n${message}\n`);
       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 });
-      const app = await createApp();
+      const app = await createApp({ logger });
       await app.start();
       return;
     }
@@ -24,4 +33,57 @@ async function main() {
   }
 }
 
+async function main() {
+  if (serviceRunner) {
+    await registerServiceProcess();
+    await runForeground();
+    return;
+  }
+
+  if (command === "start") {
+    await bootstrapIfNeeded({ force: forceBootstrap });
+    const result = await startService({ verbose });
+    if (!result.ok) {
+      console.log(`Arisa is already running in background (pid ${result.pid}).`);
+      return;
+    }
+    console.log(`Arisa started in background (pid ${result.pid}).`);
+    console.log(`Log file: ${result.logFile}`);
+    return;
+  }
+
+  if (command === "stop") {
+    const result = await stopService();
+    if (!result.ok) {
+      console.log("Arisa is not running.");
+      return;
+    }
+    console.log(`Arisa stopped (pid ${result.pid}).`);
+    return;
+  }
+
+  if (command === "status") {
+    const status = await getServiceStatus();
+    if (!status.running) {
+      console.log("Arisa is not running.");
+      return;
+    }
+    console.log(`Arisa is running in background (pid ${status.pid}).`);
+    return;
+  }
+
+  if (command === "flush") {
+    const status = await getServiceStatus();
+    if (status.running) {
+      console.log(`Arisa is running (pid ${status.pid}). Stop it before flush.`);
+      return;
+    }
+    const result = await flushArisaHome();
+    console.log(`Arisa state removed: ${result.path}`);
+    return;
+  }
+
+  await runForeground();
+}
+
 await main();

package/src/runtime/bootstrap.js

@@ -15,6 +15,23 @@ async function exists(file) {
   }
 }
 
+function sortBootstrapModels(provider, models) {
+  const preferred = {
+    "openai-codex": ["gpt-5.4"]
+  };
+
+  const priority = preferred[provider] || [];
+  const positions = new Map(models.map((model, index) => [model.id, index]));
+
+  return [...models].sort((a, b) => {
+    const aIndex = priority.indexOf(a.id);
+    const bIndex = priority.indexOf(b.id);
+    const aRank = aIndex === -1 ? Number.MAX_SAFE_INTEGER : aIndex;
+    const bRank = bIndex === -1 ? Number.MAX_SAFE_INTEGER : bIndex;
+    if (aRank !== bRank) return aRank - bRank;
+    return (positions.get(b.id) || 0) - (positions.get(a.id) || 0);
+  });
+}
 
 async function maybeOpenExternal(url) {
   if (!url) return;
@@ -105,7 +122,7 @@ export async function bootstrapIfNeeded({ force = false } = {}) {
 
   const selectedProviderIndex = Number(await ask("Select Pi provider by number", "1"));
   const selectedProvider = providers[Math.max(0, Math.min(providers.length - 1, selectedProviderIndex - 1))];
-  const models = listProviderModels(selectedProvider.provider, runtime);
+  const models = sortBootstrapModels(selectedProvider.provider, listProviderModels(selectedProvider.provider, runtime));
   console.log(`\nAvailable models for ${selectedProvider.provider}:`);
   models.forEach((model, index) => {
     const capabilities = [model.reasoning ? "reasoning" : null, model.input?.includes("image") ? "image" : null].filter(Boolean).join(", ");
@@ -153,7 +170,8 @@ export async function bootstrapIfNeeded({ force = false } = {}) {
     telegram: {
       apiKey: telegramApiKey,
       maxChatIds: telegramMaxChatIds,
-      authorizedChatIds: []
+      authorizedChatIds: [],
+      chatMeta: {}
     },
     pi: {
       provider: selectedProvider.provider,

package/src/runtime/create-app.js

@@ -4,18 +4,22 @@ import { ToolRegistry } from "../core/tools/tool-registry.js";
 import { AgentManager } from "../core/agent/agent-manager.js";
 import { createTelegramBot } from "../transport/telegram/bot.js";
 
-export async function createApp() {
+export async function createApp({ logger } = {}) {
+  logger?.log("app", "loading config");
   const config = await loadConfig();
   const artifactStore = new ArtifactStore();
-  const toolRegistry = new ToolRegistry();
+  const toolRegistry = new ToolRegistry({ logger });
   await toolRegistry.load();
+  logger?.log("app", `loaded ${toolRegistry.list().length} tools`);
 
-  const agentManager = new AgentManager({ config, artifactStore, toolRegistry });
-  const bot = await createTelegramBot({ config, artifactStore, toolRegistry, agentManager, saveConfig, updateConfig });
+  const agentManager = new AgentManager({ config, artifactStore, toolRegistry, logger });
+  const bot = await createTelegramBot({ config, artifactStore, toolRegistry, agentManager, saveConfig, updateConfig, logger });
 
   return {
     async start() {
+      logger?.log("app", `validating Pi model ${config.pi.provider}/${config.pi.model}`);
       await agentManager.validatePiAgent();
+      logger?.log("app", "starting Telegram bot");
       await bot.start();
     }
   };

package/src/runtime/flush.js

@@ -0,0 +1,7 @@
+import { rm } from "node:fs/promises";
+import { arisaHomeDir } from "./paths.js";
+
+export async function flushArisaHome() {
+  await rm(arisaHomeDir, { recursive: true, force: true });
+  return { ok: true, path: arisaHomeDir };
+}

package/src/runtime/logger.js

@@ -0,0 +1,20 @@
+export function createLogger({ verbose = false } = {}) {
+  function stamp() {
+    return new Date().toISOString().replace("T", " ").slice(0, 19);
+  }
+
+  function format(scope, message) {
+    return `[${stamp()}]${scope ? ` [${scope}]` : ""} ${message}`;
+  }
+
+  return {
+    verbose,
+    log(scope, message) {
+      if (!verbose) return;
+      console.log(format(scope, message));
+    },
+    error(scope, message) {
+      console.error(format(scope, message));
+    }
+  };
+}

package/src/runtime/paths.js

@@ -5,11 +5,19 @@ import path from "node:path";
 export const arisaHomeDir = path.join(os.homedir(), ".arisa");
 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 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);
 }
@@ -33,6 +41,8 @@ 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/service-manager.js

@@ -0,0 +1,98 @@
+import { open, readFile, rm, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { ensureArisaHome, serviceLogFile, servicePidFile } from "./paths.js";
+
+const entryFile = fileURLToPath(new URL("../index.js", import.meta.url));
+
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readPid() {
+  try {
+    const raw = await readFile(servicePidFile, "utf8");
+    const pid = Number.parseInt(raw.trim(), 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getServiceStatus() {
+  await ensureArisaHome();
+  const pid = await readPid();
+  if (!pid) return { running: false, pid: null };
+  if (!isProcessRunning(pid)) {
+    await rm(servicePidFile, { force: true }).catch(() => {});
+    return { running: false, pid: null, stalePid: pid };
+  }
+  return { running: true, pid };
+}
+
+export async function startService({ verbose = false } = {}) {
+  await ensureArisaHome();
+  const status = await getServiceStatus();
+  if (status.running) {
+    return { ok: false, reason: "already-running", pid: status.pid };
+  }
+
+  const logHandle = await open(serviceLogFile, "a");
+  const args = [entryFile, "--service-runner"];
+  if (verbose) args.push("--verbose");
+
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: ["ignore", logHandle.fd, logHandle.fd],
+    env: process.env
+  });
+
+  child.unref();
+  await logHandle.close();
+  return { ok: true, pid: child.pid, logFile: serviceLogFile };
+}
+
+export async function stopService() {
+  const status = await getServiceStatus();
+  if (!status.running) {
+    return { ok: false, reason: "not-running", pid: status.stalePid || null };
+  }
+
+  try {
+    process.kill(status.pid, "SIGTERM");
+  } catch {
+    await rm(servicePidFile, { force: true }).catch(() => {});
+    return { ok: false, reason: "not-running", pid: status.pid };
+  }
+
+  return { ok: true, pid: status.pid };
+}
+
+export async function registerServiceProcess() {
+  await ensureArisaHome();
+  await writeFile(servicePidFile, `${process.pid}\n`, "utf8");
+
+  const cleanup = async () => {
+    await rm(servicePidFile, { force: true }).catch(() => {});
+  };
+
+  process.on("SIGTERM", async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  process.on("SIGINT", async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  process.on("exit", () => {
+    rm(servicePidFile, { force: true }).catch(() => {});
+  });
+}

package/src/transport/telegram/auth.js

@@ -1,5 +1,15 @@
-export async function authorizeChat({ config, chatId, saveConfig }) {
+export async function authorizeChat({ config, chatId, saveConfig, chatMeta = null }) {
+  config.telegram.chatMeta ||= {};
+
+  if (chatMeta) {
+    config.telegram.chatMeta[chatId] = {
+      ...(config.telegram.chatMeta[chatId] || {}),
+      ...chatMeta
+    };
+  }
+
   if (config.telegram.authorizedChatIds.includes(chatId)) {
+    if (chatMeta) await saveConfig(config);
     return { ok: true, firstTime: false };
   }
 

package/src/transport/telegram/bot.js

@@ -1,6 +1,35 @@
 import { Bot, InputFile } from "grammy";
 import { authorizeChat } from "./auth.js";
 import { captureIncomingArtifact } from "./media.js";
+import { renderTelegramHtml, splitTelegramText } from "./text-format.js";
+
+function quotedMessageSummary(message) {
+  if (!message) return [];
+
+  const fromName = message.from?.username
+    ? `@${message.from.username}`
+    : [message.from?.first_name, message.from?.last_name].filter(Boolean).join(" ") || "unknown";
+
+  const parts = [
+    `quotedMessageId: ${message.message_id}`,
+    `quotedFrom: ${fromName}`
+  ];
+
+  if (message.text) parts.push(`quotedText: ${message.text}`);
+  if (message.caption) parts.push(`quotedCaption: ${message.caption}`);
+  if (message.voice) parts.push(`quotedKind: voice`);
+  if (message.audio) parts.push(`quotedKind: audio`);
+  if (message.photo?.length) parts.push(`quotedKind: image`);
+  if (message.document) parts.push(`quotedKind: document`);
+  if (message.video) parts.push(`quotedKind: video`);
+  if (message.sticker) parts.push(`quotedKind: sticker`);
+
+  if (!message.text && !message.caption) {
+    parts.push(`Important: this message replies to a Telegram message with no textual body available in the update. Use the quoted kind and metadata as context.`);
+  }
+
+  return parts;
+}
 
 function buildPrompt({ ctx, artifact, transcript }) {
   const parts = [
@@ -12,6 +41,7 @@ function buildPrompt({ ctx, artifact, transcript }) {
   ];
 
   if (ctx.message?.text) parts.push(`text: ${ctx.message.text}`);
+  parts.push(...quotedMessageSummary(ctx.message?.reply_to_message));
   if (artifact?.path) parts.push(`artifactPath: ${artifact.path}`);
   if (artifact?.id) parts.push(`artifactId: ${artifact.id}`);
   if (artifact?.mimeType) parts.push(`mimeType: ${artifact.mimeType}`);
@@ -24,7 +54,7 @@ function buildPrompt({ ctx, artifact, transcript }) {
 
   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.`);
-  parts.push(`If the user wants audio output, use send_audio_reply.`);
+  parts.push(`If the user wants a generated media reply, use send_media_reply.`);
   return parts.join("\n");
 }
 
@@ -81,10 +111,19 @@ async function withTyping(ctx, work) {
   }
 }
 
-export async function createTelegramBot({ config, artifactStore, toolRegistry, agentManager, saveConfig, updateConfig }) {
+export async function createTelegramBot({ config, artifactStore, toolRegistry, agentManager, saveConfig, updateConfig, logger }) {
   const bot = new Bot(config.telegram.apiKey);
   const perChatState = new Map();
 
+  function getIncomingChatMeta(ctx) {
+    return {
+      languageCode: ctx.from?.language_code || "",
+      username: ctx.from?.username || "",
+      firstName: ctx.from?.first_name || "",
+      lastName: ctx.from?.last_name || ""
+    };
+  }
+
   function getChatState(chatId) {
     if (!perChatState.has(chatId)) {
       perChatState.set(chatId, { processing: false, nextPrompt: "" });
@@ -93,8 +132,11 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
   }
 
   async function buildIncomingPrompt(ctx) {
+    logger?.log("telegram", `message ${ctx.msg.message_id} in chat ${ctx.chat.id}`);
     const artifact = await captureIncomingArtifact(ctx, artifactStore);
+    if (artifact) logger?.log("telegram", `captured artifact ${artifact.kind}${artifact.id ? ` ${artifact.id}` : ""}`);
     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.");
@@ -104,14 +146,29 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
     return buildPrompt({ ctx, artifact, transcript });
   }
 
+  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 processPrompt(ctx, prompt) {
     const telegram = {
-      sendAudio: async (filePath, caption) => ctx.replyWithAudio(new InputFile(filePath), { caption })
+      sendMedia: async (filePath, { method = "audio", caption } = {}) => {
+        logger?.log("telegram", `sending ${method} reply for chat ${ctx.chat.id}`);
+        const input = new InputFile(filePath);
+        if (method === "voice") return ctx.replyWithVoice(input, { caption });
+        if (method === "document") return ctx.replyWithDocument(input, { caption });
+        return ctx.replyWithAudio(input, { caption });
+      }
     };
     return withTyping(ctx, async () => {
       const { session } = await agentManager.getSessionContext(ctx.chat.id, telegram);
       const text = await collectText(session, prompt);
-      if (text) await ctx.reply(text.slice(0, 4000));
+      if (text) {
+        await sendTextReply((message, extra) => ctx.reply(message, extra), ctx.chat.id, text);
+      }
     });
   }
 
@@ -120,6 +177,7 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
     const incomingPrompt = await buildIncomingPrompt(ctx);
 
     if (chatState.processing) {
+      logger?.log("telegram", `chat ${ctx.chat.id} busy, queueing message ${ctx.msg.message_id}`);
       chatState.nextPrompt = chatState.nextPrompt
         ? `${chatState.nextPrompt}\n\n${incomingPrompt}`
         : incomingPrompt;
@@ -127,10 +185,12 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
     }
 
     chatState.processing = true;
+    logger?.log("telegram", `processing message ${ctx.msg.message_id} in chat ${ctx.chat.id}`);
     let currentPrompt = incomingPrompt;
 
     while (currentPrompt) {
       try {
+        logger?.log("telegram", `prompt dispatch for chat ${ctx.chat.id}`);
         await processPrompt(ctx, currentPrompt);
       } finally {
         if (chatState.nextPrompt) {
@@ -146,55 +206,19 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
   }
 
   bot.catch((error) => {
+    logger?.error("telegram", `bot error: ${error instanceof Error ? error.message : String(error)}`);
     console.error("Telegram bot error:", error);
   });
 
   bot.command("start", async (ctx) => {
-    const auth = await authorizeChat({ config, chatId: ctx.chat.id, saveConfig });
-    if (!auth.ok) return ctx.reply("Private bot. Access denied.");
+    const auth = await authorizeChat({ config, chatId: ctx.chat.id, saveConfig, chatMeta: getIncomingChatMeta(ctx) });
+    if (!auth.ok) return;
     return ctx.reply(auth.firstTime ? "This chat is now authorized for Arisa." : "Arisa is ready.");
   });
 
-  bot.command("pi_api_key", async (ctx) => {
-    const auth = await authorizeChat({ config, chatId: ctx.chat.id, saveConfig });
-    if (!auth.ok) return ctx.reply("Private bot. Access denied.");
-
-    const apiKey = ctx.match?.trim();
-    if (!apiKey) {
-      return ctx.reply("Usage: /pi_api_key <your_api_key>");
-    }
-
-    const nextConfig = await updateConfig((current) => {
-      current.pi.apiKey = apiKey;
-    });
-    config.pi.apiKey = nextConfig.pi.apiKey;
-    agentManager.setConfig(nextConfig);
-    return ctx.reply(`Saved Pi API key for ${nextConfig.pi.provider}.`);
-  });
-
-  bot.command("pi_model", async (ctx) => {
-    const auth = await authorizeChat({ config, chatId: ctx.chat.id, saveConfig });
-    if (!auth.ok) return ctx.reply("Private bot. Access denied.");
-
-    const value = ctx.match?.trim();
-    if (!value || !value.includes("/")) {
-      return ctx.reply("Usage: /pi_model <provider/model>");
-    }
-
-    const [provider, model] = value.split("/");
-    const nextConfig = await updateConfig((current) => {
-      current.pi.provider = provider.trim();
-      current.pi.model = model.trim();
-    });
-    config.pi.provider = nextConfig.pi.provider;
-    config.pi.model = nextConfig.pi.model;
-    agentManager.setConfig(nextConfig);
-    return ctx.reply(`Saved Pi model ${nextConfig.pi.provider}/${nextConfig.pi.model}.`);
-  });
-
   bot.on("message", async (ctx) => {
-    const auth = await authorizeChat({ config, chatId: ctx.chat.id, saveConfig });
-    if (!auth.ok) return ctx.reply("Private bot. Access denied.");
+    const auth = await authorizeChat({ config, chatId: ctx.chat.id, saveConfig, chatMeta: getIncomingChatMeta(ctx) });
+    if (!auth.ok) return;
 
     try {
       await enqueueOrProcess(ctx);
@@ -208,6 +232,41 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, a
 
   return {
     async start() {
+      config.telegram.chatMeta ||= {};
+      for (const chatId of config.telegram.authorizedChatIds || []) {
+        try {
+          logger?.log("telegram", `generating startup message for chat ${chatId}`);
+          const chatMeta = config.telegram.chatMeta[chatId] || {};
+          const telegram = {
+            sendMedia: async (filePath, { method = "audio", caption } = {}) => {
+              logger?.log("telegram", `sending ${method} reply for chat ${chatId}`);
+              const input = new InputFile(filePath);
+              if (method === "voice") return bot.api.sendVoice(chatId, input, { caption });
+              if (method === "document") return bot.api.sendDocument(chatId, input, { caption });
+              return bot.api.sendAudio(chatId, input, { caption });
+            }
+          };
+          const { session } = await agentManager.getSessionContext(chatId, telegram);
+          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");
+          const text = await collectText(session, welcomePrompt);
+          if (text) {
+            await sendTextReply((message, extra) => bot.api.sendMessage(chatId, message, extra), chatId, text);
+          }
+        } catch (error) {
+          logger?.log("telegram", `startup message failed for chat ${chatId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+      logger?.log("telegram", "bot polling started");
       await bot.start();
     }
   };

package/src/transport/telegram/text-format.js

@@ -0,0 +1,72 @@
+function escapeHtml(text = "") {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function formatInline(text) {
+  const escaped = escapeHtml(text);
+  return escaped
+    .replace(/\*\*(.+?)\*\*/gs, "<b>$1</b>")
+    .replace(/`([^`\n]+)`/g, "<code>$1</code>");
+}
+
+export function renderTelegramHtml(text = "") {
+  const source = String(text || "");
+  const parts = [];
+  let index = 0;
+
+  while (index < source.length) {
+    const start = source.indexOf("```", index);
+    if (start === -1) {
+      parts.push(formatInline(source.slice(index)));
+      break;
+    }
+
+    if (start > index) {
+      parts.push(formatInline(source.slice(index, start)));
+    }
+
+    const afterFence = start + 3;
+    const lineEnd = source.indexOf("\n", afterFence);
+    const languageLine = lineEnd === -1 ? source.slice(afterFence) : source.slice(afterFence, lineEnd);
+    const codeStart = lineEnd === -1 ? afterFence : lineEnd + 1;
+    const end = source.indexOf("```", codeStart);
+
+    if (end === -1) {
+      parts.push(formatInline(source.slice(start)));
+      break;
+    }
+
+    const language = languageLine.trim();
+    const code = source.slice(codeStart, end).replace(/\n$/, "");
+    const languageAttr = language ? ` language="${escapeHtml(language)}"` : "";
+    parts.push(`<pre><code${languageAttr}>${escapeHtml(code)}</code></pre>`);
+    index = end + 3;
+  }
+
+  return parts.join("");
+}
+
+export function splitTelegramText(text = "", maxLength = 3500) {
+  const source = String(text || "").trim();
+  if (!source) return [];
+  if (source.length <= maxLength) return [source];
+
+  const chunks = [];
+  let remaining = source;
+
+  while (remaining.length > maxLength) {
+    let cut = remaining.lastIndexOf("\n\n", maxLength);
+    if (cut < Math.floor(maxLength / 2)) cut = remaining.lastIndexOf("\n", maxLength);
+    if (cut < Math.floor(maxLength / 2)) cut = remaining.lastIndexOf(" ", maxLength);
+    if (cut <= 0) cut = maxLength;
+    chunks.push(remaining.slice(0, cut).trim());
+    remaining = remaining.slice(cut).trimStart();
+  }
+
+  if (remaining) chunks.push(remaining);
+  return chunks;
+}

package/tools/openai-transcribe/config.js

@@ -0,0 +1,4 @@
+export default {
+  OPENAI_API_KEY: "",
+  MODEL: "gpt-4o-mini-transcribe"
+};

package/{cli → tools}/openai-transcribe/index.js

@@ -1,3 +1,4 @@
+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";
@@ -7,7 +8,7 @@ const toolName = "openai-transcribe";
 const config = await loadToolConfig(toolName, defaults);
 
 function printHelp() {
-  console.log(`openai-transcribe\n\nUso:\n  node index.js --help\n  node index.js run --request-file <json>\n\nInput esperado:\n  {\n    \"artifact\": { \"path\": \"/abs/audio.ogg\", \"mimeType\": \"audio/ogg\" },\n    \"args\": {}\n  }\n\nConfig en ${getToolConfigPath(toolName)}:\n  OPENAI_API_KEY\n  MODEL\n`);
+  console.log(`openai-transcribe\n\nUsage:\n  node index.js --help\n  node index.js run --request-file <json>\n\nExpected input:\n  {\n    \"artifact\": { \"path\": \"/abs/audio.ogg\", \"mimeType\": \"audio/ogg\" },\n    \"args\": {}\n  }\n\nConfig at ${getToolConfigPath(toolName)}:\n  OPENAI_API_KEY\n  MODEL\n`);
 }
 
 async function run(requestFile) {

package/{cli → tools}/openai-transcribe/tool.manifest.json

@@ -9,7 +9,7 @@
       "type": "string",
       "required": true,
       "secret": true,
-      "prompt": "Necesito tu OPENAI_API_KEY para transcribir audio."
+      "prompt": "I need your OPENAI_API_KEY to transcribe audio."
     }
   }
 }

package/tools/openai-tts/config.js

@@ -0,0 +1,5 @@
+export default {
+  OPENAI_API_KEY: "",
+  MODEL: "gpt-4o-mini-tts",
+  VOICE: "alloy"
+};

package/{cli → tools}/openai-tts/index.js

@@ -8,7 +8,7 @@ const toolName = "openai-tts";
 const config = await loadToolConfig(toolName, defaults);
 
 function printHelp() {
-  console.log(`openai-tts\n\nUso:\n  node index.js --help\n  node index.js run --request-file <json>\n\nInput esperado:\n  {\n    \"text\": \"hola\",\n    \"artifact\": { \"text\": \"hola\" },\n    \"args\": { \"voice\": \"alloy\" }\n  }\n\nConfig en ${getToolConfigPath(toolName)}:\n  OPENAI_API_KEY\n  MODEL\n  VOICE\n`);
+  console.log(`openai-tts\n\nUsage:\n  node index.js --help\n  node index.js run --request-file <json>\n\nExpected input:\n  {\n    \"text\": \"hello\",\n    \"artifact\": { \"text\": \"hello\" },\n    \"args\": { \"voice\": \"alloy\" }\n  }\n\nOutput:\n  - generates OGG/Opus audio\n  - suggests Telegram voice-note delivery via output.delivery.method = \"voice\"\n\nConfig at ${getToolConfigPath(toolName)}:\n  OPENAI_API_KEY\n  MODEL\n  VOICE\n`);
 }
 
 async function run(requestFile) {
@@ -34,7 +34,7 @@ async function run(requestFile) {
       model: config.MODEL,
       voice: request.args?.voice || config.VOICE,
       input: inputText,
-      format: "mp3"
+      format: "opus"
     })
   });
 
@@ -46,10 +46,19 @@ async function run(requestFile) {
 
   const outDir = getToolOutDir(toolName);
   await mkdir(outDir, { recursive: true });
-  const filePath = path.join(outDir, `speech-${Date.now()}.mp3`);
+  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/mpeg", kind: "audio" } }));
+  console.log(JSON.stringify({
+    ok: true,
+    output: {
+      filePath,
+      fileName: path.basename(filePath),
+      mimeType: "audio/ogg",
+      kind: "audio",
+      delivery: { method: "voice" }
+    }
+  }));
 }
 
 const args = process.argv.slice(2);

package/{cli → tools}/openai-tts/tool.manifest.json

@@ -1,20 +1,20 @@
 {
   "name": "openai-tts",
-  "description": "Convert text into MP3 audio using OpenAI speech API.",
+  "description": "Convert text into OGG/Opus speech audio using the OpenAI speech API.",
   "entry": "index.js",
   "input": ["text/plain"],
-  "output": ["audio/mpeg"],
+  "output": ["audio/ogg"],
   "configSchema": {
     "OPENAI_API_KEY": {
       "type": "string",
       "required": true,
       "secret": true,
-      "prompt": "Necesito tu OPENAI_API_KEY para generar audio."
+      "prompt": "I need your OPENAI_API_KEY to generate speech audio."
     },
     "VOICE": {
       "type": "string",
       "required": false,
-      "prompt": "Voz a usar, por ejemplo alloy."
+      "prompt": "Voice to use, for example alloy."
     }
   }
 }

package/tools/web-browser/config.js

@@ -0,0 +1 @@
+export default {};