arisa 4.0.20 → 4.0.22

package/AGENTS.md

@@ -8,6 +8,12 @@
 - Tools are isolated and each one has its own manifest, entrypoint, and config defaults.
 - No tools ship with the core. All installed tools live under `~/.arisa/tools/<toolName>`; the install directory of Arisa (your working directory) contains only the core. Never create or install tools inside the install directory.
 
+## Core modification policy
+Modifying the Arisa core is the last resort, never the default. All work must be done in tools.
+- Always solve the request by creating or editing a tool under `~/.arisa/tools/<toolName>`.
+- Treat changing core code as the final option, only after confirming the capability genuinely cannot be delivered through the tool architecture.
+- Never modify the core on your own initiative. Always consult the user first, explaining why a core change is unavoidable, and wait for explicit approval before touching core code.
+
 ## Runtime directory rules
 Do not build runtime paths by hand. Use `src/runtime/paths.js`:
 - `getToolDir(toolName)`: installed user tool package only; no runtime data here.
@@ -33,7 +39,7 @@ Each tool declares in `tool.manifest.json`:
 - `skillHints`: optional skills to apply when using or editing the tool
 
 ## Tool-to-Arisa IPC
-Arisa does not mount tool-provided web routes in core. If a tool needs to expose a web UI or HTTP endpoint, the tool owns that server, usually through the shared daemon runtime. The tool's server handles its own requests and uses Arisa IPC when it needs artifacts, tasks, agent events, or runtime paths.
+Arisa does not mount tool-provided web routes in core. If a tool needs to expose a web UI or HTTP endpoint, the tool owns that server, usually through the shared daemon runtime. The tool's server handles its own requests and uses Arisa IPC when it needs to run a registered tool, create/read artifacts, manage tasks, enqueue agent events, or resolve runtime paths.
 
 Installed tools can import the IPC client through `ARISA_PACKAGE_DIR`:
 
@@ -48,7 +54,17 @@ const arisa = createArisaClient({ toolName: "example-tool", chatId });
 await arisa.artifacts.createText({ text: "hello" });
 ```
 
-The IPC channel is a local socket under `~/.arisa/state`. Every request must include `toolName`; chat-scoped capabilities also require `chatId`. Exposed capabilities are explicit: artifacts (`createText`, `listRecent`, `get`), tasks (`add`, `list`, `cancel`), agent events (`enqueueEvent`), and runtime paths (`getChatToolStateDir`, `getToolStateDir`, `getChatToolTmpDir`, `getToolTmpDir`, `getChatArtifactsDir`). Do not add raw access to `agentManager`, `taskStore`, `artifactStore`, or `toolRegistry`.
+For tool-owned web UI request/response flows, call another registered tool through IPC instead of adding core HTTP routes or proxies:
+
+```js
+const result = await arisa.tools.run({
+  name: "strudel-agent",
+  text: prompt,
+  args: { bpm, tags, currentCode }
+}, { timeoutMs: 120_000 });
+```
+
+The IPC channel is a local socket under `~/.arisa/state`. Every request must include `toolName`; chat-scoped capabilities also require `chatId`. Exposed capabilities are explicit: tools (`run`), artifacts (`createText`, `listRecent`, `get`), tasks (`add`, `list`, `cancel`), agent events (`enqueueEvent`), and runtime paths (`getChatToolStateDir`, `getToolStateDir`, `getChatToolTmpDir`, `getToolTmpDir`, `getChatArtifactsDir`). Do not add raw access to `agentManager`, `taskStore`, `artifactStore`, or `toolRegistry`.
 
 ## Conceptual pipe model
 There are two different moments where pipes can happen:

package/package.json

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

package/src/core/tools/ipc-client.js

@@ -58,8 +58,9 @@ export function createArisaClient({ toolName, chatId = null, socketPath = proces
     throw new Error("toolName is required");
   }
 
-  const call = (method, params = {}) => requestIpc({
+  const call = (method, params = {}, options = {}) => requestIpc({
     socketPath,
+    timeoutMs: options.timeoutMs,
     request: {
       id: crypto.randomUUID(),
       method,
@@ -83,6 +84,9 @@ export function createArisaClient({ toolName, chatId = null, socketPath = proces
     agent: {
       enqueueEvent: (params) => call("agent.enqueueEvent", params)
     },
+    tools: {
+      run: (params, options) => call("tools.run", params, options)
+    },
     paths: {
       getChatToolStateDir: () => call("paths.getChatToolStateDir"),
       getToolStateDir: () => call("paths.getToolStateDir"),

package/src/runtime/arisa-capabilities.js

@@ -27,16 +27,49 @@ function requireString(value, fieldName) {
   return value;
 }
 
+function normalizeArgs(args) {
+  if (args == null) return {};
+  if (typeof args !== "object" || Array.isArray(args)) {
+    throw new Error("args must be an object");
+  }
+  return args;
+}
+
 function normalizeLimit(limit) {
   const value = Number(limit);
   if (!Number.isInteger(value) || value <= 0) return 20;
   return Math.min(value, 100);
 }
 
-export function createArisaCapabilities({ artifactStore, taskStore } = {}) {
+export function createArisaCapabilities({ artifactStore, taskStore, agentManager } = {}) {
   async function dispatch({ method, toolName, chatId = null, params = {} } = {}) {
     const scopedToolName = requireToolName(toolName);
 
+    if (method === "tools.run") {
+      if (!agentManager?.runTool) {
+        throw new Error("tools.run requires agentManager");
+      }
+      const scopedChatId = requireChatId(chatId, method);
+      const targetToolName = requireString(params.name, "name");
+      const chatArtifactStore = artifactStore.forChat(scopedChatId);
+      const artifact = params.artifactId
+        ? await chatArtifactStore.get(requireString(params.artifactId, "artifactId"))
+        : null;
+      if (params.artifactId && !artifact) {
+        throw new Error(`Artifact not found: ${params.artifactId}`);
+      }
+
+      return agentManager.runTool({
+        name: targetToolName,
+        request: {
+          artifact,
+          text: params.text,
+          args: normalizeArgs(params.args)
+        },
+        chatId: scopedChatId
+      });
+    }
+
     if (method === "artifacts.createText") {
       const scopedChatId = requireChatId(chatId, method);
       return artifactStore.forChat(scopedChatId).createText({

package/src/runtime/create-app.js

@@ -62,7 +62,7 @@ export async function createApp({ logger, runtimeOverrides } = {}) {
   logger?.log("app", `loaded ${toolRegistry.list().length} tools`);
 
   const agentManager = new AgentManager({ config, artifactStore, toolRegistry, taskStore, logger });
-  const arisaCapabilities = createArisaCapabilities({ artifactStore, taskStore });
+  const arisaCapabilities = createArisaCapabilities({ artifactStore, taskStore, agentManager });
   const ipcServer = createIpcServer({ capabilities: arisaCapabilities, logger });
   const bot = await createTelegramBot({ config, artifactStore, toolRegistry, taskStore, agentManager, saveConfig, updateConfig, logger });
 

package/test/ipc-server.test.js

@@ -59,13 +59,18 @@ function createFakeTaskStore() {
   };
 }
 
-function createCapabilities() {
+function createCapabilities(overrides = {}) {
   return createArisaCapabilities({
-    artifactStore: createFakeArtifactStore(),
-    taskStore: createFakeTaskStore()
+    artifactStore: overrides.artifactStore || createFakeArtifactStore(),
+    taskStore: overrides.taskStore || createFakeTaskStore(),
+    agentManager: overrides.agentManager
   });
 }
 
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 async function createTempSocketPath() {
   const root = await mkdtemp(path.join(os.tmpdir(), "arisa-ipc-"));
   return path.join(root, "arisa.sock");
@@ -141,6 +146,114 @@ test("requires chatId for chat-scoped capabilities", async () => {
   }
 });
 
+test("runs a registered tool over local IPC", async () => {
+  const socketPath = await createTempSocketPath();
+  const calls = [];
+  const agentManager = {
+    runTool: async (request) => {
+      calls.push(request);
+      return { ok: true, status: "ok", output: { text: "generated code" } };
+    }
+  };
+  const ipcServer = createIpcServer({ capabilities: createCapabilities({ agentManager }), socketPath });
+  await ipcServer.start();
+
+  try {
+    const client = createArisaClient({ toolName: "strudel-ui", chatId: "chat-1", socketPath });
+    const result = await client.tools.run({
+      name: "strudel-agent",
+      text: "make acid house",
+      args: {
+        bpm: 128,
+        tags: ["acid", "live"],
+        currentCode: "stack(s(\"bd\"))"
+      }
+    });
+
+    assert.deepEqual(result, { ok: true, status: "ok", output: { text: "generated code" } });
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].name, "strudel-agent");
+    assert.equal(calls[0].chatId, "chat-1");
+    assert.equal(calls[0].request.text, "make acid house");
+    assert.deepEqual(calls[0].request.args, {
+      bpm: 128,
+      tags: ["acid", "live"],
+      currentCode: "stack(s(\"bd\"))"
+    });
+    assert.equal(calls[0].request.artifact, null);
+  } finally {
+    await ipcServer.stop();
+  }
+});
+
+test("hydrates artifact input before running a tool over IPC", async () => {
+  const socketPath = await createTempSocketPath();
+  const calls = [];
+  const agentManager = {
+    runTool: async (request) => {
+      calls.push(request);
+      return { ok: true, status: "ok", output: { json: { received: true } } };
+    }
+  };
+  const ipcServer = createIpcServer({ capabilities: createCapabilities({ agentManager }), socketPath });
+  await ipcServer.start();
+
+  try {
+    const client = createArisaClient({ toolName: "strudel-ui", chatId: 123, socketPath });
+    const artifact = await client.artifacts.createText({ text: "current pattern" });
+    await client.tools.run({ name: "strudel-agent", artifactId: artifact.id });
+
+    assert.equal(calls.length, 1);
+    assert.deepEqual(calls[0].request.artifact, artifact);
+  } finally {
+    await ipcServer.stop();
+  }
+});
+
+test("requires chatId when running a tool over IPC", async () => {
+  const socketPath = await createTempSocketPath();
+  const agentManager = {
+    runTool: async () => ({ ok: true, status: "ok" })
+  };
+  const ipcServer = createIpcServer({ capabilities: createCapabilities({ agentManager }), socketPath });
+  await ipcServer.start();
+
+  try {
+    const client = createArisaClient({ toolName: "strudel-ui", socketPath });
+    await assert.rejects(
+      () => client.tools.run({ name: "strudel-agent" }),
+      /tools\.run requires chatId/
+    );
+  } finally {
+    await ipcServer.stop();
+  }
+});
+
+test("supports per-call IPC timeout overrides", async () => {
+  const socketPath = await createTempSocketPath();
+  const agentManager = {
+    runTool: async () => {
+      await wait(25);
+      return { ok: true, status: "ok" };
+    }
+  };
+  const ipcServer = createIpcServer({ capabilities: createCapabilities({ agentManager }), socketPath });
+  await ipcServer.start();
+
+  try {
+    const client = createArisaClient({ toolName: "strudel-ui", chatId: 123, socketPath });
+    const result = await client.tools.run({ name: "strudel-agent" }, { timeoutMs: 250 });
+    assert.deepEqual(result, { ok: true, status: "ok" });
+
+    await assert.rejects(
+      () => client.tools.run({ name: "strudel-agent" }, { timeoutMs: 1 }),
+      /Arisa IPC request timed out/
+    );
+  } finally {
+    await ipcServer.stop();
+  }
+});
+
 test("listens on a local socket, not a TCP port", async () => {
   const socketPath = await createTempSocketPath();
   const ipcServer = createIpcServer({ capabilities: createCapabilities(), socketPath });