arisa 4.0.24 → 4.1.4

package/README.md

@@ -132,13 +132,15 @@ Notes:
 On first run, Arisa will:
 
 1. ask for a Telegram bot token
-2. ask for the maximum number of authorized chat ids
-3. show Pi providers discovered from Pi Agent's model registry
-4. show the models available for the selected provider
-5. resolve authentication for the selected Pi provider
+2. validate the token and ask whether to continue bootstrap from Telegram (default: yes)
+3. when Telegram setup is selected, show a `https://t.me/<bot>?start=<setup-token>` link
+4. authorize that Telegram chat and continue setup there: Pi provider, model, and Pi auth
+5. ask from Telegram whether Arisa should keep running in background
 6. validate that Pi Agent works
 7. only then start listening to Telegram
 
+Choosing `n` at the Telegram setup prompt keeps the previous CLI-only bootstrap flow.
+
 Arisa does not run a persistent HTTP health server or Telegram webhook; Telegram uses long polling.
 
 Telegram bot tokens can be created with:

package/package.json

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

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

@@ -1,13 +1,26 @@
 import path from "node:path";
-import { unlink } from "node:fs/promises";
+import { stat, unlink } from "node:fs/promises";
 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";
 import { withTimeout } from "./prompt-timeout.js";
+import { buildPiToolPolicy, getCoreCodingTools } from "./core-tools.js";
+import { createSystemShellTool } from "./system-shell-tool.js";
 import { arisaHomeDir, getChatPiSessionsDir } from "../../runtime/paths.js";
 
 const piValidationTimeoutMs = 60_000;
+const arisaToolNames = [
+  "list_tools",
+  "tool_help",
+  "tool_skills",
+  "set_tool_config",
+  "run_tool",
+  "list_scheduled_tasks",
+  "cancel_scheduled_task",
+  "cancel_all_scheduled_tasks",
+  "send_media_reply"
+];
 
 function isLocalBaseUrl(value) {
   if (typeof value !== "string" || !value.trim()) return false;
@@ -68,6 +81,13 @@ function selectMediaReplyTool(toolRegistry) {
   return tools.find(looksLikeTextToSpeechTool) || tools[0] || null;
 }
 
+async function assertDirectory(dir, label) {
+  const stats = await stat(dir);
+  if (!stats.isDirectory()) {
+    throw new Error(`${label} is not a directory: ${dir}`);
+  }
+}
+
 export class AgentManager {
   constructor({ config, artifactStore, toolRegistry, taskStore, logger }) {
     this.config = config;
@@ -95,15 +115,15 @@ export class AgentManager {
     this.sessions.delete(String(chatId));
   }
 
-  createSessionManager(chatId) {
+  createSessionManager(chatId, workspaceDir = arisaInstallDir) {
     const sessionKey = String(chatId);
     const sessionDir = getChatPiSessionsDir(sessionKey);
     if (this.pendingNewSessions.has(sessionKey)) {
       this.logger?.log("agent", `starting new persisted session for chat ${sessionKey}`);
-      return { sessionManager: SessionManager.create(arisaInstallDir, sessionDir), isNewSession: true };
+      return { sessionManager: SessionManager.create(workspaceDir, sessionDir), isNewSession: true };
     }
     this.logger?.log("agent", `recovering persisted session for chat ${sessionKey}`);
-    return { sessionManager: SessionManager.continueRecent(arisaInstallDir, sessionDir), isNewSession: false };
+    return { sessionManager: SessionManager.continueRecent(workspaceDir, sessionDir), isNewSession: false };
   }
 
   async validatePiAgent() {
@@ -156,23 +176,36 @@ 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 { sessionManager, isNewSession } = this.createSessionManager(sessionKey);
+    const policy = buildPiToolPolicy({
+      config: this.config,
+      customToolNames: [...arisaToolNames, "system_shell"]
+    });
+    await assertDirectory(policy.workspaceDir, "pi.workspaceDir");
+    const { sessionManager, isNewSession } = this.createSessionManager(sessionKey, policy.workspaceDir);
     const hasExistingSession = sessionManager.buildSessionContext().messages.length > 0;
     this.logger?.log("agent", `${hasExistingSession ? "resuming" : "creating"} session for chat ${sessionKey} with model ${effectiveModelId}`);
-    const customTools = this.createTools(telegram, chatId);
+    const customTools = [
+      ...this.createTools(telegram, chatId, policy),
+      createSystemShellTool({ workspaceDir: policy.workspaceDir, shell: policy.shell })
+    ];
     const { session } = await createAgentSession({
-      cwd: arisaInstallDir,
+      cwd: policy.workspaceDir,
       agentDir: arisaHomeDir,
       authStorage,
       modelRegistry,
       model,
+      tools: policy.tools,
+      excludeTools: policy.excludeTools,
       customTools,
       sessionManager
     });
 
     if (!hasExistingSession) {
       this.logger?.log("agent", `created new session for chat ${sessionKey}`);
-      this.logger?.log("agent", `runtime context for chat ${sessionKey}:\n${buildAgentRuntimeContext()}`);
+      this.logger?.log("agent", `runtime context for chat ${sessionKey}:\n${buildAgentRuntimeContext({
+        workspaceDir: policy.workspaceDir,
+        coreTools: policy.coreTools
+      })}`);
     }
 
     const ctx = { session, modelId: effectiveModelId };
@@ -226,20 +259,44 @@ export class AgentManager {
     return result;
   }
 
-  createTools(telegram, chatId) {
+  createTools(telegram, chatId, policy = buildPiToolPolicy({ config: this.config, customToolNames: arisaToolNames })) {
     const chatArtifactStore = this.artifactStore.forChat(chatId);
 
     return [
       defineTool({
         name: "list_tools",
         label: "List tools",
-        description: "List registered CLI tools and their capabilities.",
+        description: "List Arisa core, native shell, and modular CLI tools with their capabilities.",
         parameters: Type.Object({}),
         execute: async () => {
           await this.toolRegistry.load();
+          const coreTools = getCoreCodingTools({
+            tools: policy.tools,
+            excludeTools: policy.excludeTools
+          });
+          const nativeTools = [{
+            name: "system_shell",
+            source: "arisa-native",
+            description: "Run native system shell commands in the active Arisa workspace.",
+            workspaceDir: policy.workspaceDir,
+            shell: policy.shell.shellPath || (process.platform === "win32" ? "powershell" : "sh"),
+            enabled: !(policy.excludeTools || []).includes("system_shell")
+          }];
+          const cliTools = this.toolRegistry.list().map((tool) => ({
+            ...tool,
+            source: "arisa-modular",
+            invocation: "run_tool"
+          }));
+          const result = {
+            workspaceDir: policy.workspaceDir,
+            coreTools,
+            nativeTools,
+            cliTools,
+            tools: [...coreTools.filter((tool) => tool.enabled), ...nativeTools.filter((tool) => tool.enabled), ...cliTools]
+          };
           return {
-            content: [{ type: "text", text: JSON.stringify(this.toolRegistry.list(), null, 2) }],
-            details: { tools: this.toolRegistry.list() }
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            details: result
           };
         }
       }),

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

@@ -0,0 +1,139 @@
+import os from "node:os";
+import path from "node:path";
+import { arisaHomeDir } from "../../runtime/paths.js";
+
+const defaultShellTimeoutMs = 60_000;
+
+export const coreCodingToolCatalog = [
+  {
+    name: "read",
+    source: "pi-builtin",
+    description: "Read files and supported images from the active workspace.",
+    defaultEnabled: true
+  },
+  {
+    name: "bash",
+    source: "pi-builtin",
+    description: "Run bash-compatible commands from the active workspace.",
+    defaultEnabled: true
+  },
+  {
+    name: "edit",
+    source: "pi-builtin",
+    description: "Patch existing files in the active workspace.",
+    defaultEnabled: true
+  },
+  {
+    name: "write",
+    source: "pi-builtin",
+    description: "Create or overwrite files in the active workspace.",
+    defaultEnabled: true
+  },
+  {
+    name: "grep",
+    source: "pi-builtin",
+    description: "Search file contents from the active workspace.",
+    defaultEnabled: false
+  },
+  {
+    name: "find",
+    source: "pi-builtin",
+    description: "Find files from the active workspace.",
+    defaultEnabled: false
+  },
+  {
+    name: "ls",
+    source: "pi-builtin",
+    description: "List directories from the active workspace.",
+    defaultEnabled: false
+  }
+];
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function expandHomeDir(value) {
+  if (typeof value !== "string") return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+export function normalizeToolList(value) {
+  if (Array.isArray(value)) {
+    const tools = value
+      .map((item) => String(item || "").trim())
+      .filter(Boolean);
+    return tools.length ? unique(tools) : undefined;
+  }
+
+  if (typeof value === "string") {
+    const tools = value
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean);
+    return tools.length ? unique(tools) : undefined;
+  }
+
+  return undefined;
+}
+
+function normalizePositiveInteger(value, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) return fallback;
+  return Math.floor(number);
+}
+
+export function resolveWorkspaceDir(value, defaultWorkspaceDir = arisaHomeDir) {
+  const raw = typeof value === "string" && value.trim()
+    ? value.trim()
+    : defaultWorkspaceDir;
+  return path.resolve(expandHomeDir(raw));
+}
+
+function buildAllowedTools({ configuredTools, customToolNames }) {
+  if (!configuredTools) return undefined;
+  return unique([...configuredTools, ...customToolNames]);
+}
+
+export function getCoreCodingTools({ tools, excludeTools } = {}) {
+  const allowed = tools ? new Set(tools) : null;
+  const excluded = new Set(excludeTools || []);
+
+  return coreCodingToolCatalog.map((tool) => {
+    const enabled = allowed
+      ? allowed.has(tool.name)
+      : tool.defaultEnabled;
+    return {
+      ...tool,
+      enabled: enabled && !excluded.has(tool.name)
+    };
+  });
+}
+
+export function buildPiToolPolicy({
+  config,
+  customToolNames = [],
+  defaultWorkspaceDir = arisaHomeDir
+} = {}) {
+  const configuredTools = normalizeToolList(config?.pi?.tools);
+  const excludeTools = normalizeToolList(config?.pi?.excludeTools);
+  const tools = buildAllowedTools({ configuredTools, customToolNames });
+  const workspaceDir = resolveWorkspaceDir(config?.pi?.workspaceDir, defaultWorkspaceDir);
+
+  return {
+    workspaceDir,
+    tools,
+    excludeTools,
+    coreTools: getCoreCodingTools({ tools, excludeTools }),
+    shell: {
+      shellPath: typeof config?.pi?.shellPath === "string" && config.pi.shellPath.trim()
+        ? config.pi.shellPath.trim()
+        : "",
+      timeoutMs: normalizePositiveInteger(config?.pi?.shellTimeoutMs, defaultShellTimeoutMs)
+    }
+  };
+}

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

@@ -1,15 +1,26 @@
 import { fileURLToPath } from "node:url";
-import { arisaHomeDir, chatsDir, stateDir, toolStateDir, toolsDir } from "../../runtime/paths.js";
+import { arisaHomeDir, arisaPackageDir, chatsDir, stateDir, toolStateDir, toolsDir } from "../../runtime/paths.js";
 
 export const arisaInstallDir = fileURLToPath(new URL("../../..", import.meta.url));
 
-export function buildAgentRuntimeContext() {
+function formatCoreTools(coreTools = []) {
+  const enabled = coreTools
+    .filter((tool) => tool.enabled)
+    .map((tool) => tool.name);
+  return enabled.length ? enabled.join(", ") : "(none)";
+}
+
+export function buildAgentRuntimeContext({ workspaceDir = arisaHomeDir, coreTools = [] } = {}) {
   return [
+    `workspaceDir: ${workspaceDir}`,
     `arisaHomeDir: ${arisaHomeDir}`,
+    `arisaPackageDir: ${arisaPackageDir}`,
     `arisaInstallDir: ${arisaInstallDir}`,
     `userToolsDir: ${toolsDir}`,
     `toolStateDir: ${toolStateDir}`,
     `chatsDir: ${chatsDir}`,
-    `stateDir: ${stateDir}`
+    `stateDir: ${stateDir}`,
+    `enabledCoreTools: ${formatCoreTools(coreTools)}`,
+    "Guidance: create or edit user tools under userToolsDir. Treat arisaPackageDir/arisaInstallDir as Arisa core and modify it only when the user explicitly asks for core changes."
   ].join("\n");
 }

package/src/core/agent/system-shell-tool.js

@@ -0,0 +1,207 @@
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { constants, existsSync } from "node:fs";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const maxOutputBytes = 50 * 1024;
+const defaultTimeoutMs = 60_000;
+
+function isPowerShell(shellPath) {
+  const name = path.basename(shellPath).toLowerCase();
+  return name === "powershell.exe" || name === "powershell" || name === "pwsh.exe" || name === "pwsh";
+}
+
+function isCmd(shellPath) {
+  const name = path.basename(shellPath).toLowerCase();
+  return name === "cmd.exe" || name === "cmd";
+}
+
+function resolveNativeShell(shellPath = "") {
+  if (shellPath) {
+    if (isPowerShell(shellPath)) {
+      return {
+        shell: shellPath,
+        label: "powershell",
+        argsFor: (command) => ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", command]
+      };
+    }
+    if (isCmd(shellPath)) {
+      return {
+        shell: shellPath,
+        label: "cmd",
+        argsFor: (command) => ["/d", "/s", "/c", command]
+      };
+    }
+    return {
+      shell: shellPath,
+      label: "sh",
+      argsFor: (command) => ["-lc", command]
+    };
+  }
+
+  if (process.platform === "win32") {
+    return {
+      shell: "powershell.exe",
+      label: "powershell",
+      argsFor: (command) => ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", command]
+    };
+  }
+
+  return {
+    shell: existsSync("/bin/bash") ? "/bin/bash" : "/bin/sh",
+    label: "sh",
+    argsFor: (command) => ["-lc", command]
+  };
+}
+
+function appendLimited(current, chunk, state) {
+  state.totalBytes += chunk.length;
+
+  const remaining = maxOutputBytes - state.storedBytes;
+  if (remaining <= 0) {
+    state.truncated = true;
+    return current;
+  }
+
+  const accepted = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
+  state.storedBytes += accepted.length;
+  if (accepted.length < chunk.length) {
+    state.truncated = true;
+  }
+  return current + accepted.toString("utf8");
+}
+
+function killProcessTree(child) {
+  if (!child.pid) return;
+  if (process.platform === "win32") {
+    spawn("taskkill", ["/F", "/T", "/PID", String(child.pid)], {
+      stdio: "ignore",
+      windowsHide: true
+    });
+    return;
+  }
+
+  try {
+    process.kill(-child.pid, "SIGTERM");
+  } catch {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // Process already exited.
+    }
+  }
+}
+
+function formatOutput({ stdout, stderr, exitCode, timedOut, truncated }) {
+  const sections = [];
+  if (stdout.trim()) sections.push(`stdout:\n${stdout.trimEnd()}`);
+  if (stderr.trim()) sections.push(`stderr:\n${stderr.trimEnd()}`);
+  if (!sections.length) sections.push(exitCode === 0 && !timedOut ? "(Success, no output)" : "(No output)");
+  if (timedOut) sections.push("Command timed out.");
+  if (truncated) sections.push(`[Output truncated to ${maxOutputBytes} bytes.]`);
+  return sections.join("\n\n");
+}
+
+async function runShellCommand({ command, cwd, shellPath, timeoutMs }) {
+  await access(cwd, constants.F_OK);
+  const nativeShell = resolveNativeShell(shellPath);
+  const child = spawn(nativeShell.shell, nativeShell.argsFor(command), {
+    cwd,
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true
+  });
+
+  let stdout = "";
+  let stderr = "";
+  const outputState = {
+    storedBytes: 0,
+    totalBytes: 0,
+    truncated: false
+  };
+
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killProcessTree(child);
+  }, timeoutMs);
+
+  return new Promise((resolve) => {
+    child.stdout.on("data", (chunk) => {
+      stdout = appendLimited(stdout, chunk, outputState);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr = appendLimited(stderr, chunk, outputState);
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({
+        ok: false,
+        error,
+        stdout,
+        stderr,
+        shell: nativeShell,
+        timedOut,
+        truncated: outputState.truncated,
+        totalBytes: outputState.totalBytes
+      });
+    });
+    child.on("close", (exitCode) => {
+      clearTimeout(timer);
+      resolve({
+        ok: !timedOut && exitCode === 0,
+        exitCode,
+        stdout,
+        stderr,
+        shell: nativeShell,
+        timedOut,
+        truncated: outputState.truncated,
+        totalBytes: outputState.totalBytes
+      });
+    });
+  });
+}
+
+export function createSystemShellTool({ workspaceDir, shell = {} }) {
+  return defineTool({
+    name: "system_shell",
+    label: "System Shell",
+    description: "Run a command in the active Arisa workspace using the native system shell: PowerShell on Windows, and sh/bash-compatible shell on Unix.",
+    parameters: Type.Object({
+      command: Type.String({ description: "Command to execute in the active workspace." }),
+      timeoutMs: Type.Optional(Type.Number({ description: "Optional timeout in milliseconds for this command." }))
+    }),
+    execute: async (_id, params) => {
+      const timeoutMs = Number.isFinite(Number(params.timeoutMs)) && Number(params.timeoutMs) > 0
+        ? Math.floor(Number(params.timeoutMs))
+        : (shell.timeoutMs || defaultTimeoutMs);
+      const result = await runShellCommand({
+        command: params.command,
+        cwd: workspaceDir,
+        shellPath: shell.shellPath,
+        timeoutMs
+      });
+      const details = {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode ?? null,
+        shell: result.shell.label,
+        shellPath: result.shell.shell,
+        cwd: workspaceDir,
+        timedOut: result.timedOut,
+        truncated: result.truncated,
+        totalBytes: result.totalBytes
+      };
+      if (result.error) {
+        details.error = result.error.message;
+      }
+      return {
+        content: [{ type: "text", text: result.error?.message || formatOutput(result) }],
+        details,
+        isError: !result.ok
+      };
+    }
+  });
+}

package/src/index.js

@@ -69,8 +69,20 @@ function toNestedOverrides(nestedFlags) {
 
 function toServiceRunnerArgs(nestedFlags) {
   const args = [];
-  if (nestedFlags["pi.model"]) {
-    args.push("--pi.model", nestedFlags["pi.model"]);
+  const serviceSafePiFlags = [
+    "pi.provider",
+    "pi.model",
+    "pi.workspaceDir",
+    "pi.tools",
+    "pi.excludeTools",
+    "pi.shellPath",
+    "pi.shellTimeoutMs"
+  ];
+
+  for (const flag of serviceSafePiFlags) {
+    if (nestedFlags[flag]) {
+      args.push(`--${flag}`, nestedFlags[flag]);
+    }
   }
   return args;
 }
@@ -104,14 +116,34 @@ async function startRuntimeApp() {
   await app.start();
 }
 
+async function startBackgroundService() {
+  const result = await startService({ verbose, cliArgs: toServiceRunnerArgs(cli.nestedFlags) });
+  if (!result.ok) {
+    console.log(`Arisa is already running in background (pid ${result.pid}).`);
+    return result;
+  }
+  console.log(`Arisa started in background (pid ${result.pid}).`);
+  console.log(`Log file: ${result.logFile}`);
+  return result;
+}
+
 async function runForeground() {
   const hasRuntimePiOverrides = Boolean(
     runtimeOverrides?.pi?.model
     || runtimeOverrides?.pi?.provider
     || runtimeOverrides?.pi?.apiKey
+    || runtimeOverrides?.pi?.workspaceDir
+    || runtimeOverrides?.pi?.tools
+    || runtimeOverrides?.pi?.excludeTools
+    || runtimeOverrides?.pi?.shellPath
+    || runtimeOverrides?.pi?.shellTimeoutMs
   );
   logger.log("app", `starting${verbose ? " in verbose mode" : ""}`);
-  await bootstrapIfNeeded({ force: forceBootstrap });
+  const bootstrapResult = await bootstrapIfNeeded({ force: forceBootstrap });
+  if (bootstrapResult.startInBackground) {
+    await startBackgroundService();
+    return;
+  }
   try {
     await startRuntimeApp();
   } catch (error) {
@@ -126,7 +158,11 @@ 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 });
+      const retryBootstrapResult = await bootstrapIfNeeded({ force: true });
+      if (retryBootstrapResult.startInBackground) {
+        await startBackgroundService();
+        return;
+      }
       await startRuntimeApp();
       return;
     }
@@ -142,14 +178,12 @@ async function main() {
   }
 
   if (command === "start") {
-    await bootstrapIfNeeded({ force: forceBootstrap });
-    const result = await startService({ verbose, cliArgs: toServiceRunnerArgs(cli.nestedFlags) });
-    if (!result.ok) {
-      console.log(`Arisa is already running in background (pid ${result.pid}).`);
+    const bootstrapResult = await bootstrapIfNeeded({ force: forceBootstrap });
+    if (bootstrapResult.configCreated && bootstrapResult.viaTelegram && !bootstrapResult.startInBackground) {
+      console.log("Config saved. Arisa was not started in background.");
       return;
     }
-    console.log(`Arisa started in background (pid ${result.pid}).`);
-    console.log(`Log file: ${result.logFile}`);
+    await startBackgroundService();
     return;
   }