arisa 4.1.10 → 4.1.12

package/AGENTS.md

@@ -123,7 +123,7 @@ Example manual pipe:
 2. take the returned text `artifactId`
 3. `run_tool(openai-tts, artifact text)` to generate audio, then `send_artifact(artifactId)` to deliver it (or `run_tool(openai-tts, artifact text, deliver: true)` to generate and send in one step)
 
-Delivery is generic: any `run_tool` output that produces a file becomes an artifact, and `send_artifact(artifactId)` delivers it to the chat. The delivery method and caption are derived from the artifact (its `delivery` hint, `kind`, and stored name); internal local paths are never exposed. Tools declare their delivery intent by returning `delivery: { method }` in their output; they do not deliver to the transport themselves. As a shortcut, `run_tool` accepts `deliver: true` to generate and deliver in a single step; use it only when the user should receive the file now, not for intermediate pipe steps.
+Delivery is generic: any `run_tool` output that produces a file becomes an artifact, and `send_artifact(artifactId)` delivers it to the chat. The delivery method and filename are derived from the artifact (its `delivery` hint, `kind`, and stored name); internal local paths are never exposed. No caption is sent by default: the filename already appears on the attachment, so it is never duplicated into the caption text (which would let Telegram autolink a filename like `example.md` as a URL). A caption is shown only when an explicit one is passed. Tools declare their delivery intent by returning `delivery: { method }` in their output; they do not deliver to the transport themselves. As a shortcut, `run_tool` accepts `deliver: true` to generate and deliver in a single step; use it only when the user should receive the file now, not for intermediate pipe steps.
 
 ## Async event queue flow
 Beyond time-based scheduling, tools can drive an event queue that wakes the agent only when there is something to evaluate. Everything goes through the `asyncTask` (single) or `asyncTasks` (array) field the pipeline already supports; no new Pi tools are needed. The 1s poller drains tasks by `kind`:

package/package.json

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

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

@@ -65,18 +65,15 @@ function containsAbsolutePath(value) {
   return /(^|\s)(\/[^\s]|[A-Za-z]:[\\/])/.test(value);
 }
 
-function resolveMediaCaption({ caption, output, method }) {
+export function resolveMediaCaption(caption) {
   if (caption && !containsAbsolutePath(caption)) return caption;
-  if (method === "document" && output?.fileName) return output.fileName;
-  if (output?.text && !containsAbsolutePath(output.text)) return output.text;
-  if (output?.fileName) return output.fileName;
   return undefined;
 }
 
 async function deliverArtifactToChat({ artifact, telegram, caption, method, logger }) {
   const resolvedMethod = method || artifact.metadata?.delivery?.method || inferDeliveryMethod(artifact);
   const fileName = path.basename(artifact.path);
-  const resolvedCaption = resolveMediaCaption({ caption, output: { fileName }, method: resolvedMethod });
+  const resolvedCaption = resolveMediaCaption(caption);
   logger?.log("agent", `deliver artifact ${artifact.id} as ${resolvedMethod}`);
   await telegram.sendMedia(artifact.path, { method: resolvedMethod, caption: resolvedCaption, filename: fileName });
   return { method: resolvedMethod, fileName, artifactId: artifact.id };
@@ -428,7 +425,7 @@ export class AgentManager {
       defineTool({
         name: "send_artifact",
         label: "Send artifact",
-        description: "Deliver an existing chat artifact to the current Telegram chat. Pass the `artifactId` returned by run_tool or from an inbound file. The delivery method, caption, and filename are derived from the artifact (its delivery hint, kind, and stored name); internal local paths are never exposed. Set `caption` for a visible label, or `method` to override the delivery method. The artifact is not deleted.",
+        description: "Deliver an existing chat artifact to the current Telegram chat. Pass the `artifactId` returned by run_tool or from an inbound file. The delivery method and filename are derived from the artifact (its delivery hint, kind, and stored name); internal local paths are never exposed. No caption is shown by default, since the filename already appears on the attachment; set `caption` only to add a separate visible label, or `method` to override the delivery method. The artifact is not deleted.",
         parameters: Type.Object({
           artifactId: Type.String(),
           caption: Type.Optional(Type.String()),

package/test/artifact-store.test.js

@@ -0,0 +1,99 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+const homeDir = await mkdtemp(path.join(os.tmpdir(), "arisa-artifact-store-home-"));
+process.env.HOME = homeDir;
+process.env.USERPROFILE = homeDir;
+
+const { ArtifactStore } = await import("../src/core/artifacts/artifact-store.js");
+const { arisaHomeDir } = await import("../src/runtime/paths.js");
+
+async function resetHome() {
+  await rm(arisaHomeDir, { recursive: true, force: true });
+}
+
+test("creates, persists, reads, and lists text artifacts by recency", async () => {
+  await resetHome();
+  const store = new ArtifactStore();
+  const chatStore = store.forChat("chat-1");
+
+  const first = await chatStore.createText({
+    text: "first",
+    source: { type: "telegram" },
+    metadata: { index: 1 }
+  });
+  const second = await chatStore.createText({
+    text: "second",
+    mimeType: "text/markdown",
+    source: { type: "tool", toolName: "writer" },
+    metadata: { index: 2 }
+  });
+  const third = await chatStore.createText({
+    text: "third",
+    source: { type: "tool", toolName: "writer" }
+  });
+
+  assert.equal(first.chatId, "chat-1");
+  assert.equal(first.kind, "text");
+  assert.equal(first.mimeType, "text/plain");
+  assert.deepEqual(await chatStore.get(second.id), second);
+  assert.deepEqual((await chatStore.listRecent(2)).map((artifact) => artifact.id), [third.id, second.id]);
+
+  const reloadedStore = new ArtifactStore().forChat("chat-1");
+  assert.deepEqual(await reloadedStore.get(first.id), first);
+});
+
+test("copies file artifacts into the chat artifact directory", async () => {
+  await resetHome();
+  const originalDir = await mkdtemp(path.join(os.tmpdir(), "arisa-source-file-"));
+  const originalPath = path.join(originalDir, "voice.ogg");
+  await writeFile(originalPath, "audio-bytes", "utf8");
+
+  const artifact = await new ArtifactStore().forChat("chat-1").createFromFile({
+    originalPath,
+    fileName: "voice.ogg",
+    kind: "audio",
+    mimeType: "audio/ogg",
+    source: { type: "telegram", fileId: "telegram-file" },
+    metadata: { duration: 3 }
+  });
+
+  assert.equal(artifact.chatId, "chat-1");
+  assert.equal(artifact.kind, "audio");
+  assert.equal(artifact.mimeType, "audio/ogg");
+  assert.equal(path.basename(artifact.path), "voice.ogg");
+  assert.equal(await readFile(artifact.path, "utf8"), "audio-bytes");
+});
+
+test("creates generated file artifacts", async () => {
+  await resetHome();
+  const artifact = await new ArtifactStore().forChat("chat-1").createGeneratedFile({
+    fileName: "reply.md",
+    content: "# Hello\n",
+    kind: "document",
+    mimeType: "text/markdown",
+    source: { type: "assistant" }
+  });
+
+  assert.equal(await readFile(artifact.path, "utf8"), "# Hello\n");
+  assert.equal(artifact.kind, "document");
+  assert.equal(artifact.mimeType, "text/markdown");
+});
+
+test("keeps artifact indexes isolated by chat", async () => {
+  await resetHome();
+  const store = new ArtifactStore();
+  const chatA = store.forChat("chat-a");
+  const chatB = store.forChat("chat-b");
+
+  const aArtifact = await chatA.createText({ text: "for A", source: { type: "test" } });
+  const bArtifact = await chatB.createText({ text: "for B", source: { type: "test" } });
+
+  assert.deepEqual((await chatA.listRecent()).map((artifact) => artifact.id), [aArtifact.id]);
+  assert.deepEqual((await chatB.listRecent()).map((artifact) => artifact.id), [bArtifact.id]);
+  assert.equal(await chatA.get(bArtifact.id), null);
+  assert.equal(await chatB.get(aArtifact.id), null);
+});

package/test/auth-flow.test.js

@@ -0,0 +1,40 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { getErrorMessage, getPiAuthIssue } from "../src/core/agent/auth-flow.js";
+
+test("extracts messages from Error instances and other thrown values", () => {
+  assert.equal(getErrorMessage(new Error("boom")), "boom");
+  assert.equal(getErrorMessage("plain failure"), "plain failure");
+  assert.equal(getErrorMessage(404), "404");
+});
+
+test("classifies invalidated Pi authentication tokens", () => {
+  for (const error of [
+    new Error("authentication token has been invalidated"),
+    new Error("Token invalidated by provider"),
+    new Error("Please try signing in again"),
+    new Error("auth token expired")
+  ]) {
+    assert.deepEqual(getPiAuthIssue(error), {
+      kind: "invalidated-token",
+      message: error.message
+    });
+  }
+});
+
+test("classifies missing Pi authentication", () => {
+  for (const error of [
+    new Error("No auth found for provider"),
+    new Error("authentication credentials are missing")
+  ]) {
+    assert.deepEqual(getPiAuthIssue(error), {
+      kind: "missing-auth",
+      message: error.message
+    });
+  }
+});
+
+test("ignores unrelated Pi errors", () => {
+  assert.equal(getPiAuthIssue(new Error("model rate limit exceeded")), null);
+  assert.equal(getPiAuthIssue(new Error("")), null);
+});

package/test/auth.test.js

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { authorizeChat } from "../src/transport/telegram/auth.js";
+
+function createConfig(overrides = {}) {
+  return {
+    telegram: {
+      authorizedChatIds: [],
+      maxChatIds: 2,
+      chatMeta: {},
+      ...(overrides.telegram || {})
+    }
+  };
+}
+
+function createSaveConfigSpy() {
+  const calls = [];
+  const saveConfig = async (config) => {
+    calls.push(JSON.parse(JSON.stringify(config)));
+  };
+  return { saveConfig, calls };
+}
+
+test("authorizes a new chat below the configured limit", async () => {
+  const config = createConfig();
+  const { saveConfig, calls } = createSaveConfigSpy();
+
+  const result = await authorizeChat({ config, chatId: 123, saveConfig });
+
+  assert.deepEqual(result, { ok: true, firstTime: true });
+  assert.deepEqual(config.telegram.authorizedChatIds, [123]);
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].telegram.authorizedChatIds, [123]);
+});
+
+test("keeps an authorized chat id unique", async () => {
+  const config = createConfig({
+    telegram: { authorizedChatIds: [123] }
+  });
+  const { saveConfig, calls } = createSaveConfigSpy();
+
+  const result = await authorizeChat({ config, chatId: 123, saveConfig });
+
+  assert.deepEqual(result, { ok: true, firstTime: false });
+  assert.deepEqual(config.telegram.authorizedChatIds, [123]);
+  assert.equal(calls.length, 0);
+});
+
+test("rejects a new chat when the chat id limit is reached", async () => {
+  const config = createConfig({
+    telegram: { authorizedChatIds: [123, 456], maxChatIds: 2 }
+  });
+  const { saveConfig, calls } = createSaveConfigSpy();
+
+  const result = await authorizeChat({ config, chatId: 789, saveConfig });
+
+  assert.deepEqual(result, { ok: false, reason: "max-chat-ids" });
+  assert.deepEqual(config.telegram.authorizedChatIds, [123, 456]);
+  assert.equal(calls.length, 0);
+});
+
+test("enforces the maxChatIds off-by-one boundary", async () => {
+  const config = createConfig({
+    telegram: { authorizedChatIds: [123], maxChatIds: 1 }
+  });
+  const { saveConfig, calls } = createSaveConfigSpy();
+
+  const result = await authorizeChat({ config, chatId: 456, saveConfig });
+
+  assert.deepEqual(result, { ok: false, reason: "max-chat-ids" });
+  assert.deepEqual(config.telegram.authorizedChatIds, [123]);
+  assert.equal(calls.length, 0);
+});
+
+test("merges chat metadata for an existing authorized chat and persists it", async () => {
+  const config = createConfig({
+    telegram: {
+      authorizedChatIds: [123],
+      chatMeta: {
+        123: { username: "old-name", firstName: "Ada" }
+      }
+    }
+  });
+  const { saveConfig, calls } = createSaveConfigSpy();
+
+  const result = await authorizeChat({
+    config,
+    chatId: 123,
+    saveConfig,
+    chatMeta: { username: "new-name", lastName: "Lovelace" }
+  });
+
+  assert.deepEqual(result, { ok: true, firstTime: false });
+  assert.deepEqual(config.telegram.chatMeta[123], {
+    username: "new-name",
+    firstName: "Ada",
+    lastName: "Lovelace"
+  });
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].telegram.chatMeta[123], config.telegram.chatMeta[123]);
+});

package/test/capabilities-security.test.js

@@ -0,0 +1,249 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createArisaCapabilities } from "../src/runtime/arisa-capabilities.js";
+
+function createFakeArtifactStore() {
+  const stores = new Map();
+  return {
+    forChat(chatId) {
+      const key = String(chatId);
+      if (!stores.has(key)) {
+        const items = [];
+        stores.set(key, {
+          createText: async ({ text, mimeType, source, metadata }) => {
+            const artifact = {
+              id: `artifact-${items.length + 1}`,
+              chatId: key,
+              kind: "text",
+              mimeType,
+              text,
+              source,
+              metadata
+            };
+            items.push(artifact);
+            return artifact;
+          },
+          listRecent: async (limit) => [...items].slice(-limit).reverse(),
+          get: async (artifactId) => items.find((item) => item.id === artifactId) || null
+        });
+      }
+      return stores.get(key);
+    }
+  };
+}
+
+function createFakeTaskStore(initialTasks = []) {
+  const tasks = [...initialTasks];
+  return {
+    add: async (task, defaults = {}) => {
+      const created = {
+        id: `task-${tasks.length + 1}`,
+        ...task,
+        payload: { ...(defaults.payload || {}), ...(task.payload || {}) },
+        source: { ...(defaults.source || {}), ...(task.source || {}) }
+      };
+      tasks.push(created);
+      return created;
+    },
+    list: async (filter = {}) => tasks.filter((task) => {
+      if (filter.chatId && task.payload?.chatId !== filter.chatId) return false;
+      if (filter.status && task.status !== filter.status) return false;
+      if (filter.kind && task.kind !== filter.kind) return false;
+      return true;
+    }),
+    get: async (taskId) => tasks.find((task) => task.id === taskId) || null,
+    cancel: async (taskId) => {
+      const index = tasks.findIndex((task) => task.id === taskId);
+      if (index === -1) return null;
+      const [removed] = tasks.splice(index, 1);
+      return removed;
+    }
+  };
+}
+
+function createCapabilities(overrides = {}) {
+  return createArisaCapabilities({
+    artifactStore: overrides.artifactStore || createFakeArtifactStore(),
+    taskStore: overrides.taskStore || createFakeTaskStore(),
+    agentManager: overrides.agentManager
+  });
+}
+
+test("rejects cancellation of tasks from another chat", async () => {
+  const capabilities = createCapabilities({
+    taskStore: createFakeTaskStore([
+      { id: "task-1", status: "pending", payload: { chatId: "chat-a" } }
+    ])
+  });
+
+  await assert.rejects(
+    () => capabilities.dispatch({
+      method: "tasks.cancel",
+      toolName: "poller",
+      chatId: "chat-b",
+      params: { taskId: "task-1" }
+    }),
+    /task does not belong to chatId/
+  );
+});
+
+test("requires a non-empty toolName for all IPC dispatches", async () => {
+  const capabilities = createCapabilities();
+
+  await assert.rejects(
+    () => capabilities.dispatch({
+      method: "paths.getToolStateDir",
+      toolName: "  ",
+      params: {}
+    }),
+    /toolName is required/
+  );
+
+  await assert.rejects(
+    () => capabilities.dispatch({
+      method: "paths.getToolStateDir",
+      toolName: null,
+      params: {}
+    }),
+    /toolName is required/
+  );
+});
+
+test("requires chatId for chat-scoped IPC methods", async () => {
+  const capabilities = createCapabilities({
+    agentManager: {
+      runTool: async () => ({ ok: true, status: "ok" })
+    }
+  });
+
+  for (const method of [
+    "artifacts.createText",
+    "artifacts.listRecent",
+    "artifacts.get",
+    "tasks.add",
+    "tasks.list",
+    "tasks.cancel",
+    "agent.enqueueEvent",
+    "paths.getChatToolStateDir",
+    "paths.getChatToolTmpDir",
+    "paths.getChatArtifactsDir",
+    "tools.run"
+  ]) {
+    await assert.rejects(
+      () => capabilities.dispatch({
+        method,
+        toolName: "ipc-tool",
+        params: method === "tasks.cancel" ? { taskId: "task-1" } : {}
+      }),
+      new RegExp(`${method.replace(".", "\\.")} requires chatId`)
+    );
+  }
+});
+
+test("normalizes tool run args and rejects arrays", async () => {
+  const calls = [];
+  const capabilities = createCapabilities({
+    agentManager: {
+      runTool: async (request) => {
+        calls.push(request);
+        return { ok: true, status: "ok" };
+      }
+    }
+  });
+
+  await capabilities.dispatch({
+    method: "tools.run",
+    toolName: "caller",
+    chatId: "chat-1",
+    params: { name: "worker", args: null }
+  });
+  assert.deepEqual(calls.at(-1).request.args, {});
+
+  await capabilities.dispatch({
+    method: "tools.run",
+    toolName: "caller",
+    chatId: "chat-1",
+    params: { name: "worker", args: { bpm: 128 } }
+  });
+  assert.deepEqual(calls.at(-1).request.args, { bpm: 128 });
+
+  await assert.rejects(
+    () => capabilities.dispatch({
+      method: "tools.run",
+      toolName: "caller",
+      chatId: "chat-1",
+      params: { name: "worker", args: ["not", "an", "object"] }
+    }),
+    /args must be an object/
+  );
+});
+
+test("rejects missing artifact input before running a tool", async () => {
+  const calls = [];
+  const capabilities = createCapabilities({
+    agentManager: {
+      runTool: async (request) => {
+        calls.push(request);
+        return { ok: true, status: "ok" };
+      }
+    }
+  });
+
+  await assert.rejects(
+    () => capabilities.dispatch({
+      method: "tools.run",
+      toolName: "caller",
+      chatId: "chat-1",
+      params: { name: "worker", artifactId: "missing" }
+    }),
+    /Artifact not found: missing/
+  );
+  assert.equal(calls.length, 0);
+});
+
+test("normalizes list limits for artifact reads", async () => {
+  const observedLimits = [];
+  const artifactStore = {
+    forChat: () => ({
+      listRecent: async (limit) => {
+        observedLimits.push(limit);
+        return [];
+      }
+    })
+  };
+  const capabilities = createCapabilities({ artifactStore });
+
+  await capabilities.dispatch({
+    method: "artifacts.listRecent",
+    toolName: "viewer",
+    chatId: "chat-1",
+    params: { limit: 0 }
+  });
+  await capabilities.dispatch({
+    method: "artifacts.listRecent",
+    toolName: "viewer",
+    chatId: "chat-1",
+    params: { limit: "not-a-number" }
+  });
+  await capabilities.dispatch({
+    method: "artifacts.listRecent",
+    toolName: "viewer",
+    chatId: "chat-1",
+    params: { limit: 1000 }
+  });
+
+  assert.deepEqual(observedLimits, [20, 20, 100]);
+});
+
+test("rejects unknown IPC methods", async () => {
+  const capabilities = createCapabilities();
+
+  await assert.rejects(
+    () => capabilities.dispatch({
+      method: "unknown.method",
+      toolName: "caller",
+      params: {}
+    }),
+    /unknown IPC method: unknown\.method/
+  );
+});

package/test/media-caption.test.js

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { resolveMediaCaption } from "../src/core/agent/agent-manager.js";
+
+test("does not turn a domain-like filename into a caption", () => {
+  assert.equal(resolveMediaCaption(undefined), undefined);
+});
+
+test("keeps an explicit caption that is not a local path", () => {
+  assert.equal(resolveMediaCaption("Here is the report"), "Here is the report");
+});
+
+test("drops an explicit caption that leaks an absolute path", () => {
+  assert.equal(resolveMediaCaption("/Users/me/.arisa/artifacts/report.md"), undefined);
+});

package/test/normalize-for-reasoning.test.js

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  normalizeArtifactForReasoning,
+  selectPipeTool,
+  shouldNormalizeArtifactToText
+} from "../src/core/artifacts/normalize-for-reasoning.js";
+
+function createToolRegistry(tools, run = async () => ({ ok: true, output: { text: "transcript" } })) {
+  return {
+    list: () => tools,
+    run
+  };
+}
+
+test("normalizes only audio and video artifacts to text", () => {
+  assert.equal(shouldNormalizeArtifactToText({ mimeType: "audio/ogg; codecs=opus" }), true);
+  assert.equal(shouldNormalizeArtifactToText({ mimeType: "video/mp4" }), true);
+  assert.equal(shouldNormalizeArtifactToText({ mimeType: "text/plain" }), false);
+  assert.equal(shouldNormalizeArtifactToText({ mimeType: "image/png" }), false);
+  assert.equal(shouldNormalizeArtifactToText({ mimeType: "audio/ogg" }, "application/json"), false);
+});
+
+test("selects an audio transcription pipe by MIME input/output and tool description", () => {
+  const toolRegistry = createToolRegistry([
+    {
+      name: "generic-converter",
+      description: "Converts things",
+      input: ["audio/*"],
+      output: ["text/plain"]
+    },
+    {
+      name: "whisper-transcribe",
+      description: "Speech to text for voice notes",
+      input: ["audio/*"],
+      output: ["text/plain"]
+    }
+  ]);
+
+  const tool = selectPipeTool({
+    toolRegistry,
+    artifact: { mimeType: "audio/ogg; codecs=opus" },
+    desiredMimeType: "text/plain"
+  });
+
+  assert.equal(tool.name, "whisper-transcribe");
+});
+
+test("returns no pipe when no transcription-like tool can produce the desired output", () => {
+  const toolRegistry = createToolRegistry([
+    {
+      name: "generic-converter",
+      description: "Converts audio",
+      input: ["audio/*"],
+      output: ["application/json"]
+    },
+    {
+      name: "text-maker",
+      description: "Writes text",
+      input: ["text/plain"],
+      output: ["text/plain"]
+    }
+  ]);
+
+  const tool = selectPipeTool({
+    toolRegistry,
+    artifact: { mimeType: "audio/ogg" },
+    desiredMimeType: "text/plain"
+  });
+
+  assert.equal(tool, null);
+});
+
+test("does not run tools for artifacts that do not need normalization", async () => {
+  let runCount = 0;
+  const result = await normalizeArtifactForReasoning({
+    artifact: { id: "artifact-1", mimeType: "text/plain", text: "hello" },
+    toolRegistry: createToolRegistry([], async () => {
+      runCount += 1;
+      return { ok: true, output: { text: "unused" } };
+    }),
+    chatArtifactStore: {},
+    chatId: "chat-1"
+  });
+
+  assert.deepEqual(result, { normalizedArtifact: null, toolResult: null, toolName: "" });
+  assert.equal(runCount, 0);
+});
+
+test("returns a failed normalization result when no pipe is registered", async () => {
+  const result = await normalizeArtifactForReasoning({
+    artifact: { id: "artifact-1", mimeType: "audio/ogg" },
+    toolRegistry: createToolRegistry([]),
+    chatArtifactStore: {},
+    chatId: "chat-1"
+  });
+
+  assert.equal(result.normalizedArtifact, null);
+  assert.equal(result.toolName, "");
+  assert.equal(result.toolResult.ok, false);
+  assert.match(result.toolResult.error, /No registered tool can normalize audio\/ogg to text\/plain/);
+});
+
+test("creates a text artifact from successful normalization output", async () => {
+  const calls = [];
+  const createdArtifacts = [];
+  const artifact = { id: "voice-1", mimeType: "audio/ogg" };
+  const toolRegistry = createToolRegistry([
+    {
+      name: "openai-transcribe",
+      description: "Transcription for audio",
+      input: ["audio/*"],
+      output: ["text/plain"]
+    }
+  ], async (request) => {
+    calls.push(request);
+    return { ok: true, output: { text: "hello from voice" } };
+  });
+  const chatArtifactStore = {
+    createText: async (request) => {
+      const created = { id: "text-1", ...request };
+      createdArtifacts.push(created);
+      return created;
+    }
+  };
+
+  const result = await normalizeArtifactForReasoning({
+    artifact,
+    toolRegistry,
+    chatArtifactStore,
+    chatId: "chat-1"
+  });
+
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0], {
+    name: "openai-transcribe",
+    request: { artifact, args: {} },
+    chatId: "chat-1"
+  });
+  assert.deepEqual(result.normalizedArtifact, createdArtifacts[0]);
+  assert.equal(result.toolName, "openai-transcribe");
+  assert.deepEqual(createdArtifacts[0], {
+    id: "text-1",
+    text: "hello from voice",
+    mimeType: "text/plain",
+    source: { type: "tool", toolName: "openai-transcribe" },
+    metadata: { fromArtifactId: "voice-1", tool: "openai-transcribe", normalization: true }
+  });
+});
+
+test("fails normalization when the selected tool returns no text", async () => {
+  const result = await normalizeArtifactForReasoning({
+    artifact: { id: "voice-1", mimeType: "audio/ogg" },
+    toolRegistry: createToolRegistry([
+      {
+        name: "openai-transcribe",
+        description: "Transcription for audio",
+        input: ["audio/*"],
+        output: ["text/plain"]
+      }
+    ], async () => ({ ok: true, output: {} })),
+    chatArtifactStore: {},
+    chatId: "chat-1"
+  });
+
+  assert.equal(result.normalizedArtifact, null);
+  assert.equal(result.toolName, "openai-transcribe");
+  assert.deepEqual(result.toolResult, {
+    ok: false,
+    status: "failed",
+    error: "Normalization returned no text."
+  });
+});

package/test/paths.test.js

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import {
+  chatsDir,
+  createIpcSocketPath,
+  getChatArtifactsDir,
+  getChatToolConfigPath,
+  getChatToolStateDir,
+  getToolStateDir,
+  stateDir
+} from "../src/runtime/paths.js";
+
+test("keeps chat artifact paths scoped below the chat directory", () => {
+  const artifactsDir = getChatArtifactsDir("chat-1");
+
+  assert.equal(artifactsDir, path.join(chatsDir, "chat-1", "artifacts"));
+});
+
+test("keeps chat tool state and config paths scoped below the chat directory for normal names", () => {
+  assert.equal(
+    getChatToolStateDir("chat-1", "strudel-agent"),
+    path.join(chatsDir, "chat-1", "state", "tools", "strudel-agent")
+  );
+  assert.equal(
+    getChatToolConfigPath("chat-1", "strudel-agent"),
+    path.join(chatsDir, "chat-1", "config", "tools", "strudel-agent", "config.js")
+  );
+});
+
+test("documents current traversal behavior for unsanitized tool names", () => {
+  const expectedRoot = path.join(chatsDir, "chat-1", "state", "tools");
+  const traversed = getChatToolStateDir("chat-1", "../../evil");
+
+  assert.equal(path.resolve(traversed), path.join(chatsDir, "chat-1", "evil"));
+  assert.equal(path.resolve(traversed).startsWith(`${expectedRoot}${path.sep}`), false);
+});
+
+test("documents current traversal behavior for global tool state paths", () => {
+  const expectedRoot = path.join(stateDir, "tools");
+  const traversed = getToolStateDir("../../evil");
+
+  assert.equal(path.resolve(traversed), path.join(path.dirname(stateDir), "evil"));
+  assert.equal(path.resolve(traversed).startsWith(`${expectedRoot}${path.sep}`), false);
+});
+
+test("creates POSIX IPC socket paths under the state directory", () => {
+  const socketPath = createIpcSocketPath({
+    homeDir: "/tmp/arisa-home",
+    platform: "darwin"
+  });
+
+  assert.equal(socketPath, path.join("/tmp/arisa-home", "state", "arisa.sock"));
+});

package/test/task-store.test.js

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+const homeDir = await mkdtemp(path.join(os.tmpdir(), "arisa-task-store-home-"));
+process.env.HOME = homeDir;
+process.env.USERPROFILE = homeDir;
+
+const { TaskStore } = await import("../src/core/tasks/task-store.js");
+const { arisaHomeDir } = await import("../src/runtime/paths.js");
+
+async function resetHome() {
+  await rm(arisaHomeDir, { recursive: true, force: true });
+}
+
+test("adds tasks and lists them by chat, status, and kind", async () => {
+  await resetHome();
+  const store = new TaskStore();
+
+  await store.add({ id: "chat-1-pending", kind: "agent_task" }, { payload: { chatId: "chat-1" } });
+  await store.add({ id: "chat-1-event", kind: "agent_event" }, { payload: { chatId: "chat-1" } });
+  await store.add({ id: "chat-2-pending", kind: "agent_task" }, { payload: { chatId: "chat-2" } });
+
+  assert.deepEqual(
+    (await store.list({ chatId: "chat-1" })).map((task) => task.id),
+    ["chat-1-pending", "chat-1-event"]
+  );
+  assert.deepEqual(
+    (await store.list({ kind: "agent_task" })).map((task) => task.id),
+    ["chat-1-pending", "chat-2-pending"]
+  );
+  assert.deepEqual(
+    (await store.list({ status: "pending" })).map((task) => task.id),
+    ["chat-1-pending", "chat-1-event", "chat-2-pending"]
+  );
+});
+
+test("claims only due pending tasks and marks them running", async () => {
+  await resetHome();
+  const store = new TaskStore();
+  const past = new Date(Date.now() - 1000).toISOString();
+  const future = new Date(Date.now() + 60_000).toISOString();
+
+  await store.add({ id: "due-1", kind: "agent_task", runAt: past });
+  await store.add({ id: "due-2", kind: "agent_task", runAt: past });
+  await store.add({ id: "future", kind: "agent_task", runAt: future });
+  await store.add({ id: "done", kind: "agent_task", runAt: past, status: "done" });
+  await store.add({ id: "invalid", kind: "agent_task", runAt: "not-a-date" });
+
+  const claimed = await store.claimDue(1);
+
+  assert.deepEqual(claimed.map((task) => task.id), ["due-1"]);
+  assert.equal(claimed[0].status, "running");
+  assert.equal((await store.get("due-1")).status, "running");
+  assert.equal((await store.get("due-2")).status, "pending");
+  assert.equal((await store.get("future")).status, "pending");
+  assert.equal((await store.get("done")).status, "done");
+});
+
+test("completes one-off tasks and re-schedules recurring interval tasks", async () => {
+  await resetHome();
+  const store = new TaskStore();
+  const past = new Date(Date.now() - 1000).toISOString();
+
+  await store.add({ id: "once", kind: "agent_task", status: "running" });
+  await store.add({
+    id: "repeat",
+    kind: "poll_tool",
+    status: "running",
+    runAt: past,
+    recurrence: { type: "interval", everySeconds: 60 }
+  });
+
+  const once = await store.complete("once");
+  const repeat = await store.complete("repeat");
+
+  assert.equal(once.status, "done");
+  assert.ok(once.completedAt);
+  assert.equal(repeat.status, "pending");
+  assert.ok(Date.parse(repeat.runAt) > Date.now());
+  assert.ok(repeat.lastRunAt);
+});
+
+test("fails and cancels tasks by id", async () => {
+  await resetHome();
+  const store = new TaskStore();
+
+  await store.add({ id: "will-fail", kind: "agent_task" });
+  await store.add({ id: "will-cancel", kind: "agent_task" });
+
+  const failed = await store.fail("will-fail", "boom");
+  const canceled = await store.cancel("will-cancel");
+
+  assert.equal(failed.status, "failed");
+  assert.equal(failed.error, "boom");
+  assert.equal(canceled.id, "will-cancel");
+  assert.equal(await store.get("will-cancel"), null);
+});
+
+test("cancelAll preserves done and failed tasks and respects chat filters", async () => {
+  await resetHome();
+  const store = new TaskStore();
+
+  await store.add({ id: "chat-1-pending", kind: "agent_task" }, { payload: { chatId: "chat-1" } });
+  await store.add({ id: "chat-2-pending", kind: "agent_task" }, { payload: { chatId: "chat-2" } });
+  await store.add({ id: "chat-1-done", kind: "agent_task", status: "done" }, { payload: { chatId: "chat-1" } });
+  await store.add({ id: "chat-1-failed", kind: "agent_task", status: "failed" }, { payload: { chatId: "chat-1" } });
+
+  const removed = await store.cancelAll({ chatId: "chat-1" });
+  const remaining = await store.list();
+
+  assert.deepEqual(removed.map((task) => task.id), ["chat-1-pending"]);
+  assert.deepEqual(
+    remaining.map((task) => task.id),
+    ["chat-2-pending", "chat-1-done", "chat-1-failed"]
+  );
+});

package/test/text-format.test.js

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { renderTelegramHtml, splitTelegramText } from "../src/transport/telegram/text-format.js";
+
+test("escapes HTML-sensitive characters in inline text", () => {
+  const rendered = renderTelegramHtml("<script>alert(\"x\")</script> & done");
+
+  assert.equal(rendered, "&lt;script&gt;alert(&quot;x&quot;)&lt;/script&gt; &amp; done");
+});
+
+test("escapes inline formatting content before rendering Telegram HTML tags", () => {
+  const rendered = renderTelegramHtml("**<b>bold & safe</b>** and `<tag attr=\"x\">`");
+
+  assert.equal(
+    rendered,
+    "<b>&lt;b&gt;bold &amp; safe&lt;/b&gt;</b> and <code>&lt;tag attr=&quot;x&quot;&gt;</code>"
+  );
+});
+
+test("escapes fenced code content", () => {
+  const rendered = renderTelegramHtml("before\n```js\nconst x = \"<tag>\" && value;\n```\nafter");
+
+  assert.equal(
+    rendered,
+    "before\n<pre><code language=\"js\">const x = &quot;&lt;tag&gt;&quot; &amp;&amp; value;</code></pre>\nafter"
+  );
+});
+
+test("escapes fenced code language attributes", () => {
+  const rendered = renderTelegramHtml("```js\" onmouseover=\"alert(1)\nconsole.log(\"safe\");\n```");
+
+  assert.match(rendered, /<pre><code language="js&quot; onmouseover=&quot;alert\(1\)">/);
+  assert.doesNotMatch(rendered, /onmouseover="/);
+});
+
+test("leaves unterminated fences as escaped inline text", () => {
+  const rendered = renderTelegramHtml("```html\n<b>not code");
+
+  assert.equal(rendered, "```html\n&lt;b&gt;not code");
+});
+
+test("splits empty or whitespace-only Telegram text into no chunks", () => {
+  assert.deepEqual(splitTelegramText(""), []);
+  assert.deepEqual(splitTelegramText("   \n\t  "), []);
+});
+
+test("splits Telegram text at readable boundaries without exceeding the limit", () => {
+  const source = "alpha beta gamma delta epsilon zeta";
+  const chunks = splitTelegramText(source, 12);
+
+  assert.deepEqual(chunks, ["alpha beta", "gamma delta", "epsilon zeta"]);
+  assert.ok(chunks.every((chunk) => chunk.length <= 12));
+  assert.equal(chunks.join(" "), source);
+});
+
+test("falls back to hard splits when no readable boundary exists", () => {
+  const chunks = splitTelegramText("abcdefghijklmnop", 5);
+
+  assert.deepEqual(chunks, ["abcde", "fghij", "klmno", "p"]);
+  assert.ok(chunks.every((chunk) => chunk.length <= 5));
+});

package/test/tool-config.test.js

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+const homeDir = await mkdtemp(path.join(os.tmpdir(), "arisa-tool-config-home-"));
+process.env.HOME = homeDir;
+process.env.USERPROFILE = homeDir;
+
+const {
+  loadToolConfig,
+  parseConfigModule,
+  serializeConfigModule,
+  writeToolConfig
+} = await import("../src/core/tools/tool-config.js");
+
+test("parses and serializes config modules", () => {
+  const config = parseConfigModule("export default {\n  apiKey: \"secret\",\n  enabled: true\n};\n");
+  const serialized = serializeConfigModule(config);
+
+  assert.deepEqual(config, { apiKey: "secret", enabled: true });
+  assert.equal(serialized, "export default {\n  apiKey: \"secret\",\n  enabled: true\n};\n");
+  assert.deepEqual(parseConfigModule(serialized), config);
+});
+
+test("loads tool config with defaults, global config, and chat config precedence", async () => {
+  await writeToolConfig("demo-tool", {
+    apiKey: "global-key",
+    mode: "global",
+    retries: 3
+  });
+  await writeToolConfig("demo-tool", {
+    mode: "chat",
+    chatOnly: true
+  }, "chat-1");
+
+  const config = await loadToolConfig("demo-tool", {
+    apiKey: "default-key",
+    mode: "default",
+    timeoutMs: 1000
+  }, "chat-1");
+
+  assert.deepEqual(config, {
+    apiKey: "global-key",
+    mode: "chat",
+    timeoutMs: 1000,
+    retries: 3,
+    chatOnly: true
+  });
+});
+
+test("writes config modules to the selected scope", async () => {
+  const { getChatToolConfigPath } = await import("../src/runtime/paths.js");
+  const configPath = await writeToolConfig("scoped-tool", { token: "chat-token" }, "chat-2");
+  const source = await readFile(configPath, "utf8");
+
+  assert.equal(configPath, getChatToolConfigPath("chat-2", "scoped-tool"));
+  assert.equal(source, "export default {\n  token: \"chat-token\"\n};\n");
+});
+
+test("documents that config parsing executes JavaScript expressions", () => {
+  delete globalThis.__arisaConfigExecuted;
+
+  const config = parseConfigModule(
+    "export default (() => { globalThis.__arisaConfigExecuted = true; return { enabled: true }; })();"
+  );
+
+  assert.deepEqual(config, { enabled: true });
+  assert.equal(globalThis.__arisaConfigExecuted, true);
+  delete globalThis.__arisaConfigExecuted;
+});

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

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { access, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+const homeDir = await mkdtemp(path.join(os.tmpdir(), "arisa-tool-registry-home-"));
+process.env.HOME = homeDir;
+process.env.USERPROFILE = homeDir;
+
+const { ToolRegistry } = await import("../src/core/tools/tool-registry.js");
+const {
+  arisaHomeDir,
+  arisaPackageDir,
+  arisaIpcSocketFile,
+  toolsDir
+} = await import("../src/runtime/paths.js");
+
+async function resetHome() {
+  await rm(arisaHomeDir, { recursive: true, force: true });
+}
+
+async function createFakeTool(name = "fake-tool") {
+  const dir = path.join(toolsDir, name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, "tool.manifest.json"), `${JSON.stringify({
+    name,
+    description: "Fake test tool",
+    entry: "index.js",
+    input: ["text/plain"],
+    output: ["text/plain"],
+    configSchema: {
+      apiKey: { type: "string", required: false }
+    },
+    skillHints: [{ name: "missing-skill", when: "testing" }]
+  }, 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";
+
+const requestFileIndex = process.argv.indexOf("--request-file");
+if (process.argv.includes("--help")) {
+  process.stdout.write("Fake test tool help\\n");
+  process.exit(0);
+}
+if (requestFileIndex === -1) {
+  process.stdout.write(JSON.stringify({ ok: false, error: "missing request file" }));
+  process.exit(0);
+}
+
+const requestFile = process.argv[requestFileIndex + 1];
+const request = JSON.parse(await readFile(requestFile, "utf8"));
+process.stdout.write(JSON.stringify({
+  ok: true,
+  output: {
+    text: "tool completed",
+    request,
+    requestFile,
+    env: {
+      ARISA_PACKAGE_DIR: process.env.ARISA_PACKAGE_DIR,
+      ARISA_IPC_SOCKET: process.env.ARISA_IPC_SOCKET
+    }
+  }
+}));
+`, "utf8");
+  return dir;
+}
+
+test("loads and lists installed tools from the user tools directory", async () => {
+  await resetHome();
+  await createFakeTool("fake-tool");
+
+  const registry = new ToolRegistry();
+  await registry.load();
+
+  assert.deepEqual(registry.list(), [{
+    name: "fake-tool",
+    description: "Fake test tool",
+    input: ["text/plain"],
+    output: ["text/plain"],
+    configSchema: {
+      apiKey: { type: "string", required: false }
+    },
+    skillHints: [{ name: "missing-skill", when: "testing" }]
+  }]);
+});
+
+test("runs a registered tool process with an enriched request and cleans up request files", async () => {
+  await resetHome();
+  await createFakeTool("fake-tool");
+
+  const registry = new ToolRegistry();
+  await registry.load();
+
+  const result = await registry.run({
+    name: "fake-tool",
+    chatId: "chat-1",
+    request: {
+      text: "hello",
+      args: { count: 2 }
+    }
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.status, "ok");
+  assert.equal(result.output.text, "tool completed");
+  assert.deepEqual(result.output.request, {
+    text: "hello",
+    args: { count: 2 },
+    chatId: "chat-1",
+    skills: [{
+      name: "missing-skill",
+      when: "testing",
+      found: false,
+      description: "",
+      path: "",
+      content: ""
+    }]
+  });
+  assert.equal(result.output.env.ARISA_PACKAGE_DIR, arisaPackageDir);
+  assert.equal(result.output.env.ARISA_IPC_SOCKET, arisaIpcSocketFile);
+
+  const requestFile = result.output.requestFile;
+  await assert.rejects(() => access(requestFile), { code: "ENOENT" });
+  await assert.rejects(() => access(path.dirname(requestFile)), { code: "ENOENT" });
+});
+
+test("rejects unknown tools", async () => {
+  await resetHome();
+  const registry = new ToolRegistry();
+  await registry.load();
+
+  await assert.rejects(
+    () => registry.run({ name: "missing-tool", request: {}, chatId: "chat-1" }),
+    /Tool not found: missing-tool/
+  );
+});

package/test/tool-result.test.js

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  normalizeToolResult,
+  toolError,
+  toolNeedsConfig,
+  toolOk
+} from "../src/core/tools/tool-result.js";
+
+test("builds standard successful tool responses", () => {
+  assert.deepEqual(
+    toolOk({ text: "done" }, { asyncTasks: [{ id: "task-1" }] }),
+    { ok: true, output: { text: "done" }, asyncTasks: [{ id: "task-1" }] }
+  );
+});
+
+test("builds standard failed tool responses", () => {
+  assert.deepEqual(
+    toolError("boom", { status: "bad_request", details: { field: "name" } }),
+    {
+      ok: false,
+      status: "bad_request",
+      error: "boom",
+      details: { field: "name" }
+    }
+  );
+});
+
+test("builds missing-config tool responses", () => {
+  assert.deepEqual(
+    toolNeedsConfig({
+      tool: "demo",
+      missingConfig: ["apiKey"],
+      configPath: "/tmp/config.js"
+    }),
+    {
+      ok: false,
+      status: "needs_config",
+      error: "Missing tool configuration for demo.",
+      missingConfig: ["apiKey"],
+      configPath: "/tmp/config.js",
+      resolution: {
+        type: "user_config_required",
+        tool: "demo",
+        missingConfig: ["apiKey"],
+        configPath: "/tmp/config.js"
+      }
+    }
+  );
+});
+
+test("normalizes non-object responses into failed results", () => {
+  const result = normalizeToolResult("demo", "not-json");
+
+  assert.equal(result.ok, false);
+  assert.equal(result.status, "failed");
+  assert.equal(result.error, "Invalid tool response for demo");
+});
+
+test("normalizes missing-config failures", () => {
+  const result = normalizeToolResult("demo", {
+    ok: false,
+    error: "Need API key",
+    missingConfig: ["apiKey"],
+    configPath: "/tmp/config.js"
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.status, "needs_config");
+  assert.equal(result.error, "Need API key");
+  assert.deepEqual(result.resolution, {
+    type: "user_config_required",
+    tool: "demo",
+    missingConfig: ["apiKey"],
+    configPath: "/tmp/config.js"
+  });
+});
+
+test("preserves explicit missing-config status and resolution", () => {
+  const result = normalizeToolResult("demo", {
+    ok: false,
+    status: "blocked",
+    error: "Need consent",
+    missingConfig: ["consent"],
+    resolution: { type: "manual", url: "https://example.com" }
+  });
+
+  assert.equal(result.status, "blocked");
+  assert.deepEqual(result.resolution, { type: "manual", url: "https://example.com" });
+});
+
+test("normalizes regular failures", () => {
+  const result = normalizeToolResult("demo", {
+    ok: false,
+    error: "Tool exploded",
+    stdout: "",
+    stderr: "stack"
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.status, "failed");
+  assert.equal(result.error, "Tool exploded");
+  assert.equal(result.stderr, "stack");
+});
+
+test("normalizes successful responses", () => {
+  const result = normalizeToolResult("demo", {
+    ok: true,
+    output: { text: "hello" },
+    delivery: { method: "document" }
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.status, "ok");
+  assert.deepEqual(result.output, { text: "hello" });
+  assert.deepEqual(result.delivery, { method: "document" });
+});
+
+test("rejects object responses without an ok contract", () => {
+  const rawResult = { output: { text: "hello" } };
+  const result = normalizeToolResult("demo", rawResult);
+
+  assert.equal(result.ok, false);
+  assert.equal(result.status, "failed");
+  assert.equal(result.error, "Invalid tool response for demo");
+  assert.deepEqual(result.rawResult, rawResult);
+});