arisa 4.1.16 → 4.2.2

package/AGENTS.md

@@ -23,6 +23,15 @@ Do not build runtime paths by hand. Use `src/runtime/paths.js`:
 
 Tools receive `chatId` from the registry. Any persisted or indexed user content must be scoped by chat. Avoid ad hoc roots like `~/.arisa/state/<toolName>`, `~/.arisa/state/chats`, or runtime data inside `~/.arisa/tools/<toolName>`.
 
+## Tool config rules
+Every tool has a local `config.js` that exports generic, non-user-specific defaults. Keep user credentials, deployment-specific URLs, account ids, phone numbers, and other per-user values empty or neutral there; document required values in `tool.manifest.json` `configSchema`.
+
+Tools must consume config through `src/core/tools/tool-config.js`:
+- `loadToolConfig(toolName, defaults)` for global tools and daemons that run as one shared process.
+- `loadToolConfig(toolName, defaults, request.chatId)` inside `run()` for request-scoped tools that should honor per-chat overrides.
+
+Config precedence is a shallow merge: tool defaults -> global tool config (`~/.arisa/tools/<toolName>/config.js`) -> chat tool config (`~/.arisa/chats/<chatId>/config/tools/<toolName>/config.js`). Per-request `args` may override loaded config for that invocation only; do not persist request args as config unless the user explicitly asked to set a default.
+
 ## Main rule: everything is piped through artifacts
 A pipe transforms one input artifact into one output artifact.
 Examples:
@@ -34,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
@@ -157,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/package.json

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

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

@@ -1,9 +1,9 @@
 import path from "node:path";
-import { stat, unlink } from "node:fs/promises";
-import { createAgentSession, SessionManager, defineTool } from "@earendil-works/pi-coding-agent";
+import { readFile, stat, unlink } from "node:fs/promises";
+import { createAgentSession, DefaultResourceLoader, 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 { appendArisaAgentsFile, arisaAgentsFile, 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";
@@ -88,6 +88,17 @@ async function assertDirectory(dir, label) {
   }
 }
 
+async function createArisaResourceLoader({ cwd, agentDir }) {
+  const arisaAgentsContent = await readFile(arisaAgentsFile, "utf8");
+  const resourceLoader = new DefaultResourceLoader({
+    cwd,
+    agentDir,
+    agentsFilesOverride: (current) => appendArisaAgentsFile(current, arisaAgentsContent)
+  });
+  await resourceLoader.reload();
+  return resourceLoader;
+}
+
 export class AgentManager {
   constructor({ config, artifactStore, toolRegistry, taskStore, logger }) {
     this.config = config;
@@ -188,9 +199,14 @@ export class AgentManager {
       ...this.createTools(telegram, chatId, policy),
       createSystemShellTool({ workspaceDir: policy.workspaceDir, shell: policy.shell })
     ];
+    const resourceLoader = await createArisaResourceLoader({
+      cwd: policy.workspaceDir,
+      agentDir: arisaHomeDir
+    });
     const { session } = await createAgentSession({
       cwd: policy.workspaceDir,
       agentDir: arisaHomeDir,
+      resourceLoader,
       authStorage,
       modelRegistry,
       model,

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

@@ -1,7 +1,19 @@
+import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { arisaHomeDir, arisaPackageDir, chatsDir, stateDir, toolStateDir, toolsDir } from "../../runtime/paths.js";
 
 export const arisaInstallDir = fileURLToPath(new URL("../../..", import.meta.url));
+export const arisaAgentsFile = path.join(arisaPackageDir, "AGENTS.md");
+
+export function appendArisaAgentsFile(current, content, agentsFilePath = arisaAgentsFile) {
+  return {
+    ...current,
+    agentsFiles: [
+      ...(current.agentsFiles || []).filter((file) => path.resolve(file.path) !== path.resolve(agentsFilePath)),
+      { path: agentsFilePath, content }
+    ]
+  };
+}
 
 function formatCoreTools(coreTools = []) {
   const enabled = coreTools
@@ -20,6 +32,7 @@ export function buildAgentRuntimeContext({ workspaceDir = arisaHomeDir, coreTool
     `toolStateDir: ${toolStateDir}`,
     `chatsDir: ${chatsDir}`,
     `stateDir: ${stateDir}`,
+    `arisaAgentsFile: ${arisaAgentsFile}`,
     `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/artifacts/artifact-store.js

@@ -7,6 +7,11 @@ function id() {
   return crypto.randomUUID();
 }
 
+function writeArtifactFile(filePath, content) {
+  if (typeof content === "string") return writeFile(filePath, content, "utf8");
+  return writeFile(filePath, content);
+}
+
 class ChatArtifactStore {
   constructor(chatId) {
     this.chatId = String(chatId);
@@ -81,7 +86,7 @@ class ChatArtifactStore {
     const dir = path.join(this.rootDir, artifactId);
     await mkdir(dir, { recursive: true });
     const destPath = path.join(dir, fileName);
-    await writeFile(destPath, content);
+    await writeArtifactFile(destPath, content);
     const artifact = {
       id: artifactId,
       chatId: this.chatId,

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/test/agent-tool-policy.test.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { buildPiToolPolicy } from "../src/core/agent/core-tools.js";
+import { appendArisaAgentsFile, arisaAgentsFile } from "../src/core/agent/runtime-context.js";
 import { createSystemShellTool } from "../src/core/agent/system-shell-tool.js";
 import { applyRuntimeOverrides } from "../src/runtime/create-app.js";
 import { arisaHomeDir } from "../src/runtime/paths.js";
@@ -89,3 +90,22 @@ test("system_shell runs commands from the configured workspace", async () => {
   assert.equal(result.details.exitCode, 0);
   assert.equal(result.details.stdout, realWorkspaceDir);
 });
+
+test("adds Arisa AGENTS.md to Pi context files without duplicating it", () => {
+  const current = {
+    agentsFiles: [
+      { path: "/workspace/AGENTS.md", content: "# Workspace" },
+      { path: arisaAgentsFile, content: "old" }
+    ],
+    diagnostics: []
+  };
+
+  const next = appendArisaAgentsFile(current, "# Arisa AGENTS");
+
+  assert.deepEqual(next.diagnostics, []);
+  assert.deepEqual(
+    next.agentsFiles.map((file) => file.path),
+    ["/workspace/AGENTS.md", arisaAgentsFile]
+  );
+  assert.equal(next.agentsFiles.at(-1).content, "# Arisa AGENTS");
+});

package/test/artifact-store.test.js

@@ -83,6 +83,20 @@ test("creates generated file artifacts", async () => {
   assert.equal(artifact.mimeType, "text/markdown");
 });
 
+test("writes generated text file artifacts as UTF-8", async () => {
+  await resetHome();
+  const content = "# Español\nÑandú\n";
+  const artifact = await new ArtifactStore().forChat("chat-1").createGeneratedFile({
+    fileName: "reply.txt",
+    content,
+    kind: "document",
+    mimeType: "text/plain",
+    source: { type: "assistant" }
+  });
+
+  assert.deepEqual(await readFile(artifact.path), Buffer.from(content, "utf8"));
+});
+
 test("keeps artifact indexes isolated by chat", async () => {
   await resetHome();
   const store = new ArtifactStore();

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");