arisa 4.2.0 → 4.2.4

package/AGENTS.md

@@ -43,6 +43,8 @@ Each tool declares in `tool.manifest.json`:
 - `input`: supported input types
 - `output`: produced output types
 - `configSchema`: required config fields
+- `category`: optional broad capability bucket for discovery
+- `keywords`: optional intent tags for capability discovery
 - `skillHints`: optional skills to apply when using or editing the tool
 
 ## Tool-to-Arisa IPC
@@ -166,6 +168,8 @@ Do not assume a rigid question/answer protocol. Continue the conversation natura
 ## Capability resolution
 Reason in terms of capabilities, not tool names. Do not stop at "I cannot do that" when the task is realistically implementable through the tool architecture.
 
+Before asking the user for recurrent context, inspect available tools by `category` and `keywords`, especially `memory`, `context`, `contacts`, and `essential`.
+
 When the user asks for something new:
 1. check whether an existing registered tool, or an indirect use of one, can satisfy the task
 2. check the official catalog at `https://github.com/clasen/Arisa/tree/main/tools` before building anything

package/README.md

@@ -86,6 +86,7 @@ All runtime state lives under `~/.arisa/`, split between global state and per-ch
 
 Global:
 - runtime config is stored in `~/.arisa/state/config.json`
+- Pi OAuth credentials are stored in `~/.arisa/state/pi-auth.json`
 - the scheduled-task queue is stored in `~/.arisa/state/tasks.json`
 - installed tools live under `~/.arisa/tools/<tool>/`, each with a default `config.js` template
 - global tool runtime state (daemons, caches, temp) lives under `~/.arisa/state/tools/<tool>/`
@@ -134,6 +135,17 @@ Notes:
 
 - it only affects the current Arisa process and does not update `~/.arisa/state/config.json`
 
+## Multiple instances
+
+Set `ARISA_HOME` to run separate Arisa instances on the same machine:
+
+```bash
+ARISA_HOME=~/.arisa-work arisa
+ARISA_HOME=~/.arisa-personal arisa start
+```
+
+Each home has its own Telegram config, Pi login, installed tools, daemons, chat sessions, artifacts, IPC socket, PID file, and logs. Pi OAuth credentials are stored in `<home>/state/pi-auth.json`, so existing installs authenticate once again after upgrading.
+
 ## Bootstrap flow
 
 On first run, Arisa walks you through three steps:
@@ -156,6 +168,7 @@ src/
 ~/.arisa/
   state/              global config, task queue, IPC socket
     config.json
+    pi-auth.json
     tasks.json
     tools/<tool>/     global tool state (daemons, caches, tmp)
   tools/<tool>/       installed tools (catalog, user-chosen, or agent-created)

package/package.json

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

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

@@ -1,7 +1,8 @@
 import { AuthStorage } from "@earendil-works/pi-coding-agent";
+import { piAuthFile } from "../../runtime/paths.js";
 
 export function createPiOAuthLogin({ provider, onAuth, onDeviceCode, onPrompt, onProgress, onSelect } = {}) {
-  const authStorage = AuthStorage.create();
+  const authStorage = AuthStorage.create(piAuthFile);
   const oauthProvider = authStorage.getOAuthProviders().find((item) => item.id === provider);
   if (!oauthProvider) {
     throw new Error(`No internal OAuth login flow is available for ${provider}.`);

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

@@ -1,11 +1,12 @@
 import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { piAuthFile } from "../../runtime/paths.js";
 
 function compareText(a, b) {
   return a.localeCompare(b, undefined, { sensitivity: "base", numeric: true });
 }
 
 export function createPiRuntime({ provider, apiKey } = {}) {
-  const authStorage = AuthStorage.create();
+  const authStorage = AuthStorage.create(piAuthFile);
   if (provider && apiKey) {
     authStorage.setRuntimeApiKey(provider, apiKey);
   }

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

@@ -21,6 +21,28 @@ function runProcess(command, args, options = {}) {
   });
 }
 
+function normalizeCategory(category) {
+  if (typeof category !== "string") return null;
+  const trimmed = category.trim();
+  return trimmed || null;
+}
+
+function normalizeKeywords(keywords) {
+  if (!Array.isArray(keywords)) return [];
+  return [...new Set(keywords
+    .filter((keyword) => typeof keyword === "string")
+    .map((keyword) => keyword.trim())
+    .filter(Boolean))];
+}
+
+function formatSemanticMetadata(tool) {
+  return [
+    "Semantic metadata:",
+    `- category: ${tool.category || "none"}`,
+    `- keywords: ${tool.keywords?.length ? tool.keywords.join(", ") : "none"}`
+  ].join("\n");
+}
+
 export class ToolRegistry {
   constructor({ logger } = {}) {
     this.logger = logger;
@@ -52,6 +74,8 @@ export class ToolRegistry {
         const skillHints = this.skillRegistry.normalizeHints(manifest);
         this.tools.set(manifest.name, {
           ...manifest,
+          category: normalizeCategory(manifest.category),
+          keywords: normalizeKeywords(manifest.keywords),
           skillHints,
           dir: toolDir,
           entry: path.join(toolDir, manifest.entry || "index.js"),
@@ -75,6 +99,8 @@ export class ToolRegistry {
       input: tool.input,
       output: tool.output,
       configSchema: tool.configSchema || {},
+      category: tool.category,
+      keywords: tool.keywords || [],
       skillHints: tool.skillHints || []
     }));
   }
@@ -89,13 +115,19 @@ export class ToolRegistry {
     const result = await runProcess("node", [tool.entry, "--help"], { cwd: tool.dir, env: toolEnv() });
     const help = result.stdout || result.stderr;
     const skills = await this.resolveSkills(name);
-    if (!skills.length) return help;
-    const skillHelp = skills.map((item) => [
-      `- ${item.name}${item.when ? ` (${item.when})` : ""}`,
-      item.description ? `  ${item.description}` : null,
-      item.found ? `  path: ${item.path}` : "  warning: skill not found"
-    ].filter(Boolean).join("\n")).join("\n");
-    return `${help}\n\nAssigned skills:\n${skillHelp}\n`;
+    const sections = [
+      help.trimEnd(),
+      formatSemanticMetadata(tool)
+    ];
+    if (skills.length) {
+      const skillHelp = skills.map((item) => [
+        `- ${item.name}${item.when ? ` (${item.when})` : ""}`,
+        item.description ? `  ${item.description}` : null,
+        item.found ? `  path: ${item.path}` : "  warning: skill not found"
+      ].filter(Boolean).join("\n")).join("\n");
+      sections.push(`Assigned skills:\n${skillHelp}`);
+    }
+    return `${sections.filter(Boolean).join("\n\n")}\n`;
   }
 
   async resolveSkills(name) {

package/src/runtime/paths.js

@@ -5,9 +5,12 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const arisaPackageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-export const arisaHomeDir = path.join(os.homedir(), ".arisa");
+export const arisaHomeDir = process.env.ARISA_HOME
+  ? path.resolve(process.env.ARISA_HOME)
+  : path.join(os.homedir(), ".arisa");
 export const stateDir = path.join(arisaHomeDir, "state");
 export const configFile = path.join(stateDir, "config.json");
+export const piAuthFile = path.join(stateDir, "pi-auth.json");
 export const servicePidFile = path.join(stateDir, "arisa.pid");
 export const serviceLogFile = path.join(stateDir, "arisa.log");
 export function createIpcSocketPath({ homeDir = arisaHomeDir, platform = process.platform } = {}) {

package/src/transport/telegram/bot.js

@@ -1,7 +1,7 @@
 import { Bot, InputFile } from "grammy";
 import path from "node:path";
 import { authorizeChat } from "./auth.js";
-import { captureIncomingArtifact } from "./media.js";
+import { captureIncomingArtifact, formatLocationText } from "./media.js";
 import { renderTelegramHtml } from "./text-format.js";
 import { buildPiAuthRecoveryBlockedMessage, buildPiAuthTelegramMessage, getErrorMessage, getPiAuthIssue, getPiAuthStatus } from "../../core/agent/auth-flow.js";
 import { createPiOAuthLogin } from "../../core/agent/pi-auth-login.js";
@@ -29,6 +29,7 @@ function quotedMessageSummary(message) {
   if (message.document) parts.push(`quotedKind: document`);
   if (message.video) parts.push(`quotedKind: video`);
   if (message.sticker) parts.push(`quotedKind: sticker`);
+  if (message.location) parts.push(`quotedKind: location`, `quotedLocation: ${formatLocationText(message)}`);
 
   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.`);
@@ -45,7 +46,7 @@ function getTelegramCommand(ctx) {
 }
 
 function getIncomingMessageText(message) {
-  return message?.text || message?.caption || "";
+  return message?.text || message?.caption || formatLocationText(message) || "";
 }
 
 function baseMimeType(mimeType = "") {

package/src/transport/telegram/media.js

@@ -32,6 +32,20 @@ function incomingCaptionMetadata(ctx) {
   return ctx.message?.caption ? { caption: ctx.message.caption } : {};
 }
 
+export function formatLocationText(message) {
+  const location = message?.venue?.location || message?.location;
+  if (!location) return "";
+
+  const venue = message.venue;
+  const lines = [];
+  if (venue?.title) lines.push(`Venue: ${venue.title}`);
+  if (venue?.address) lines.push(`Address: ${venue.address}`);
+  lines.push(`Latitude: ${location.latitude}`);
+  lines.push(`Longitude: ${location.longitude}`);
+  lines.push(`Maps: https://maps.google.com/?q=${location.latitude},${location.longitude}`);
+  return lines.join("\n");
+}
+
 export async function captureIncomingArtifact(ctx, artifactStore) {
   const chatId = ctx.chat.id;
   const store = artifactStore.forChat(chatId);
@@ -124,6 +138,14 @@ export async function captureIncomingArtifact(ctx, artifactStore) {
     });
   }
 
+  if (ctx.message?.location) {
+    return store.createText({
+      text: formatLocationText(ctx.message),
+      source: baseSource,
+      metadata: { visibility: "internal", representation: "inline-message" }
+    });
+  }
+
   if (ctx.message?.text) {
     return store.createText({
       text: ctx.message.text,

package/test/paths.test.js

@@ -1,6 +1,10 @@
 import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import test from "node:test";
+import { promisify } from "node:util";
 import {
   chatsDir,
   createIpcSocketPath,
@@ -11,6 +15,8 @@ import {
   stateDir
 } from "../src/runtime/paths.js";
 
+const execFileAsync = promisify(execFile);
+
 test("keeps chat artifact paths scoped below the chat directory", () => {
   const artifactsDir = getChatArtifactsDir("chat-1");
 
@@ -52,3 +58,25 @@ test("creates POSIX IPC socket paths under the state directory", () => {
 
   assert.equal(socketPath, path.join("/tmp/arisa-home", "state", "arisa.sock"));
 });
+
+test("uses ARISA_HOME for instance-scoped paths", async (t) => {
+  const customHome = await mkdtemp(path.join(os.tmpdir(), "arisa-home-"));
+  t.after(() => rm(customHome, { recursive: true, force: true }));
+
+  const script = `
+const paths = await import(${JSON.stringify(new URL("../src/runtime/paths.js", import.meta.url).href)});
+process.stdout.write(JSON.stringify({
+  arisaHomeDir: paths.arisaHomeDir,
+  configFile: paths.configFile,
+  piAuthFile: paths.piAuthFile
+}));
+`;
+  const { stdout } = await execFileAsync(process.execPath, ["--input-type=module", "--eval", script], {
+    env: { ...process.env, ARISA_HOME: customHome }
+  });
+  const paths = JSON.parse(stdout);
+
+  assert.equal(paths.arisaHomeDir, path.resolve(customHome));
+  assert.equal(paths.configFile, path.join(customHome, "state", "config.json"));
+  assert.equal(paths.piAuthFile, path.join(customHome, "state", "pi-auth.json"));
+});

package/test/telegram-text-artifact.test.js

@@ -79,3 +79,64 @@ test("marks incoming Telegram text artifacts as internal inline messages", async
     representation: "inline-message"
   });
 });
+
+function createLocationContext({ location, venue } = {}) {
+  return {
+    chat: { id: 123 },
+    from: { id: 456, username: "martin" },
+    msg: { message_id: 789 },
+    message: {
+      message_id: 789,
+      location: location || { latitude: 40.4168, longitude: -3.7038 },
+      ...(venue ? { venue } : {})
+    }
+  };
+}
+
+test("turns a shared Telegram location into a processable text artifact", async () => {
+  const artifactStore = {
+    forChat: () => ({
+      createText: async (request) => ({ id: "artifact-1", kind: "text", mimeType: "text/plain", ...request })
+    })
+  };
+
+  const artifact = await captureIncomingArtifact(createLocationContext(), artifactStore);
+
+  assert.match(artifact.text, /Latitude: 40\.4168/);
+  assert.match(artifact.text, /Longitude: -3\.7038/);
+  assert.match(artifact.text, /Maps: https:\/\/maps\.google\.com\/\?q=40\.4168,-3\.7038/);
+});
+
+test("includes venue title and address when a location is shared as a venue", async () => {
+  const artifactStore = {
+    forChat: () => ({
+      createText: async (request) => ({ id: "artifact-1", kind: "text", mimeType: "text/plain", ...request })
+    })
+  };
+
+  const ctx = createLocationContext({
+    venue: { title: "Cafe Tortoni", address: "Av. de Mayo 825", location: { latitude: -34.6083, longitude: -58.3712 } }
+  });
+
+  const artifact = await captureIncomingArtifact(ctx, artifactStore);
+
+  assert.match(artifact.text, /Venue: Cafe Tortoni/);
+  assert.match(artifact.text, /Address: Av\. de Mayo 825/);
+  assert.match(artifact.text, /Latitude: -34\.6083/);
+});
+
+test("surfaces shared location coordinates inline in the agent prompt", () => {
+  const ctx = createLocationContext();
+  const prompt = buildPrompt({
+    ctx,
+    artifact: {
+      id: "artifact-1",
+      kind: "text",
+      mimeType: "text/plain",
+      text: "Latitude: 40.4168\nLongitude: -3.7038\nMaps: https://maps.google.com/?q=40.4168,-3.7038"
+    }
+  });
+
+  assert.match(prompt, /text: Latitude: 40\.4168/);
+  assert.doesNotMatch(prompt, /artifactId: artifact-1/);
+});

package/test/tool-registry-run.test.js

@@ -20,10 +20,10 @@ async function resetHome() {
   await rm(arisaHomeDir, { recursive: true, force: true });
 }
 
-async function createFakeTool(name = "fake-tool") {
+async function createFakeTool(name = "fake-tool", manifestOverrides = {}) {
   const dir = path.join(toolsDir, name);
   await mkdir(dir, { recursive: true });
-  await writeFile(path.join(dir, "tool.manifest.json"), `${JSON.stringify({
+  const manifest = {
     name,
     description: "Fake test tool",
     entry: "index.js",
@@ -33,6 +33,10 @@ async function createFakeTool(name = "fake-tool") {
       apiKey: { type: "string", required: false }
     },
     skillHints: [{ name: "missing-skill", when: "testing" }]
+  };
+  await writeFile(path.join(dir, "tool.manifest.json"), `${JSON.stringify({
+    ...manifest,
+    ...manifestOverrides
   }, null, 2)}\n`, "utf8");
   await writeFile(path.join(dir, "config.js"), "export default {\n  apiKey: \"default-key\"\n};\n", "utf8");
   await writeFile(path.join(dir, "index.js"), `import { readFile } from "node:fs/promises";
@@ -67,7 +71,10 @@ process.stdout.write(JSON.stringify({
 
 test("loads and lists installed tools from the user tools directory", async () => {
   await resetHome();
-  await createFakeTool("fake-tool");
+  await createFakeTool("fake-tool", {
+    category: "memory",
+    keywords: ["memory", "essential"]
+  });
 
   const registry = new ToolRegistry();
   await registry.load();
@@ -80,10 +87,40 @@ test("loads and lists installed tools from the user tools directory", async () =
     configSchema: {
       apiKey: { type: "string", required: false }
     },
+    category: "memory",
+    keywords: ["memory", "essential"],
     skillHints: [{ name: "missing-skill", when: "testing" }]
   }]);
 });
 
+test("lists optional semantic metadata with stable defaults", async () => {
+  await resetHome();
+  await createFakeTool("fake-tool");
+
+  const registry = new ToolRegistry();
+  await registry.load();
+
+  assert.equal(registry.list()[0].category, null);
+  assert.deepEqual(registry.list()[0].keywords, []);
+});
+
+test("shows semantic metadata in tool help", async () => {
+  await resetHome();
+  await createFakeTool("fake-tool", {
+    category: "memory",
+    keywords: ["memory", "essential"]
+  });
+
+  const registry = new ToolRegistry();
+  await registry.load();
+
+  const help = await registry.help("fake-tool");
+
+  assert.match(help, /Fake test tool help/);
+  assert.match(help, /Semantic metadata:\n- category: memory\n- keywords: memory, essential/);
+  assert.match(help, /Assigned skills:/);
+});
+
 test("runs a registered tool process with an enriched request and cleans up request files", async () => {
   await resetHome();
   await createFakeTool("fake-tool");