arisa 3.0.14 → 3.1.2

package/AGENTS.md

@@ -54,6 +54,17 @@ Every CLI must support:
 - `node index.js --help`
 - `node index.js run --request-file <json>`
 
+### Tools that need daemons
+Some tools need a persistent process, for example to keep a browser session alive or a local model warm.
+Implement these tools with the shared daemon runtime instead of custom ad hoc process management:
+- use `src/core/tools/daemon-runtime.js`
+- keep runtime files under the tool state directory (`stateDir/<toolName>`)
+- expose normal CLI behavior through `run --request-file`; callers should not manage daemon internals
+- use the runtime for `daemon.pid`, `daemon.log`, `status.json`, and `commands/*.request|processing|result.json`
+- keep one daemon owner per tool/session and avoid opening a second client over the same resource
+- use `beforeStart` only for tool-specific cleanup such as stale browser locks, without deleting persistent session/model data
+- keep daemon tools headless/server-safe by default when they are meant to run on VPS machines
+
 ## Pipe behavior in V1
 V1 does not have a full automatic planner yet. The agent should:
 1. understand whether the needed pipe belongs to pre-reasoning normalization or post-reasoning tool chaining

package/README.md

@@ -101,6 +101,16 @@ arisa install <source>   # install a Pi package into Arisa's runtime
 arisa remove <source>    # remove a Pi package from Arisa's runtime
 ```
 
+Runtime model override (current process only):
+
+```bash
+arisa --pi.model lmstudio/google/gemma-4-26b-a4b
+```
+
+Notes:
+
+- it only affects the current Arisa process and does not update `~/.arisa/state/config.json`
+
 ## Experimental features
 
 ### Pi Agent packages
@@ -124,6 +134,33 @@ On first run, Arisa will:
 6. validate that Pi Agent works
 7. only then start listening to Telegram
 
+### Non-interactive bootstrap (CLI overrides)
+
+You can skip the interactive questions by providing `--telegram.token` and optional overrides:
+
+```bash
+node src/index.js --telegram.token <token>
+```
+
+With this mode, Arisa creates `~/.arisa/state/config.json` without prompts and applies these defaults when not provided:
+
+- `pi.provider`: `openai-codex` when available, otherwise first provider from the current Pi provider list
+- `pi.model`: first model after bootstrap sorting (currently prioritizes `openai-codex/gpt-5.4`)
+- `telegram.maxChatIds`: `1`
+
+Supported overrides:
+
+```bash
+node src/index.js --telegram.token <token> --telegram.maxChatIds 3 --pi.provider openai-codex --pi.model gpt-5.4 --pi.apiKey <optional-provider-key>
+```
+
+Notes:
+
+- interactive bootstrap remains unchanged when no CLI overrides are provided
+- `--bootstrap` can be combined with overrides to regenerate config non-interactively
+- when `--pi.apiKey` is omitted and the provider supports OAuth, Arisa starts a temporary web page on `PORT` (default `10000`) where you can complete authentication from any browser
+- unknown `--pi.provider` or `--pi.model` values are ignored and replaced by safe defaults
+
 Telegram bot tokens can be created with:
 
 - https://t.me/BotFather

package/docs/async-event-queue-flow.md

@@ -0,0 +1,68 @@
+# Flow genérico de eventos asíncronos para tools
+
+> Estado: propuesta / no implementado. Guardado como referencia.
+> La implementación actual (timer) se mantiene; este documento describe una evolución posible.
+
+## Problema
+
+Hoy la única re-entrada asíncrona al agente es por tiempo: una tool devuelve `asyncTask` con `runAt` y el poller de 1s en `src/transport/telegram/bot.js` lo dispara como prompt. Eso obliga a resolver con timer (polling crudo, latencia fija, re-spawn de la tool y un turno completo del agente en cada chequeo). Falta una **cola de eventos entrantes** que despierte al agente solo cuando hay algo que evaluar.
+
+## Solución (polling ordenado por cola, reusando TaskStore)
+
+Dos nuevos `kind` de tarea, drenados por el mismo poller hacia el mismo `enqueuePrompt`:
+
+- `poll_tool`: tarea recurrente que el poller **ejecuta directamente como tool** (no gasta turno del agente). El checker mantiene su propio cursor de estado en su config/tmp por chat. Si hay novedad, emite un `agent_event`.
+- `agent_event`: evento entrante que se dispara de inmediato. El poller lo entrega como prompt para que Pi lo evalúe y decida.
+
+```mermaid
+flowchart LR
+  Tool[Tool run normal] -->|asyncTask poll_tool| TS[TaskStore]
+  TS --> Poller[1s poller dispatcher]
+  Poller -->|kind poll_tool| Run[agentManager.runTool checker]
+  Run -->|si hay novedad: asyncTask agent_event| TS
+  Poller -->|kind agent_event| EP[enqueuePrompt]
+  Poller -->|kind agent_task| EP
+  EP --> Pi[Pi evalua y decide]
+```
+
+## Cambios
+
+### 1. TaskStore: eventos/polls sin hora se disparan ya
+
+`src/core/tasks/task-store.js` - en `normalizeTask`, default `runAt` a `now` cuando no viene (los `agent_event` y el primer disparo de `poll_tool` deben ser inmediatos; `computeNextRunAt` ya reprograma `poll_tool` por su `recurrence`). Cambio de una línea, no rompe `agent_task` (siempre trae `runAt`).
+
+### 2. AgentManager: extraer "run + materializar" (DRY)
+
+`src/core/agent/agent-manager.js` - hoy el `execute` de `run_tool` (líneas ~184-242) hace: correr la tool, convertir `output.text`/`output.filePath` en artifacts y mandar `asyncTask(s)` al `TaskStore` con el `chatId`. Extraer eso a un método reusable `runTool({ name, request, chatId })`. El Pi tool `run_tool` pasa a llamarlo. Así el poller puede correr tools con la **misma** lógica de materialización (incluido el alta de `agent_event` que emita el checker).
+
+### 3. Poller -> dispatcher por kind
+
+`src/transport/telegram/bot.js` - reemplazar el handler de un solo kind dentro del `setInterval` (líneas ~361-380) por un dispatcher:
+
+- `agent_task` -> `enqueuePrompt(buildAsyncTaskPrompt(task))` + `complete` (igual que hoy).
+- `agent_event` -> `enqueuePrompt(buildAsyncEventPrompt(task))` + `complete`.
+- `poll_tool` -> `agentManager.runTool({ name: task.payload.toolName, request: { args: task.payload.args || {} }, chatId })`; los `agent_event` que emita el checker quedan encolados para el próximo tick; luego `complete` (la `recurrence` reprograma el poll). Si la tool falla: log + `complete` para no matar el poll.
+
+Agregar `buildAsyncEventPrompt(task)` junto a `buildAsyncTaskPrompt` (línea ~82), con framing de "llegó un evento externo, evalualo y decidí la próxima acción". Si el branch queda denso, extraer `dispatchDueTasks(...)` a una función para mantener `bot.js` como transporte.
+
+### 4. Documentar el flow
+
+`AGENTS.md` - sección nueva (en inglés) explicando: cómo una tool arma su auto-polling devolviendo un `asyncTask` kind `poll_tool` con `recurrence`, cómo emite novedades con `asyncTask` kind `agent_event`, que el checker guarda su cursor en su config/tmp por chat, y que el agente razona sobre el `agent_event` para decidir. `list_scheduled_tasks`/`cancel_scheduled_task` ya sirven (son kind-agnostic) para ver/cancelar polls.
+
+## Contrato del checker tool (sin nuevas Pi tools)
+
+Todo pasa por el campo `asyncTasks` que el pipeline ya soporta:
+
+- Arranque del poll (desde el `run` de cualquier tool): `asyncTasks: [{ kind: "poll_tool", payload: { toolName, args }, recurrence: { type: "interval", everySeconds: N } }]`.
+- Novedad (desde el `run` del checker): `asyncTasks: [{ kind: "agent_event", payload: { prompt: "<contenido a evaluar>" } }]`.
+
+## No-goals (por ahora)
+
+- No se agrega listener persistente (`node index.js listen`) ni proceso de fondo con IPC.
+- No se agrega endpoint HTTP entrante para eventos.
+- No se resuelve el caso de conexión sostenida (tipo cliente logueado): los checkers son one-shot y persisten su cursor entre corridas.
+
+## Alternativas consideradas (descartadas para esta versión)
+
+- **Listener tools**: la tool corre como proceso de larga duración (`node index.js listen`) y emite eventos por stdout que Arisa drena a la cola. Más general y realtime, pero agrega ciclo de vida de proceso a la service e IPC.
+- **Webhook entrante**: Arisa expone un endpoint HTTP interno donde sistemas externos hacen POST de eventos. Bueno para callbacks; no sirve para los que requieren sostener una conexión.

package/package.json

@@ -1,16 +1,12 @@
 {
   "name": "arisa",
-  "version": "3.0.14",
+  "version": "3.1.2",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",
   "bin": {
     "arisa": "bin/arisa.js"
   },
-  "scripts": {
-    "start": "node src/index.js",
-    "bootstrap": "node src/index.js --bootstrap"
-  },
   "keywords": [
     "telegram",
     "pi-agent",
@@ -32,10 +28,13 @@
   ],
   "author": "Martin Clasen",
   "license": "MIT",
-  "packageManager": "pnpm@10.32.1",
   "dependencies": {
-    "@mariozechner/pi-coding-agent": "^0.65.0",
+    "@mariozechner/pi-coding-agent": "^0.73.1",
     "@sinclair/typebox": "^0.34.41",
     "grammy": "^1.42.0"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "bootstrap": "node src/index.js --bootstrap"
   }
-}
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,12 @@
+overrides:
+  '@protobufjs/utf8@<=1.1.0': '>=1.1.1'
+  basic-ftp@<=5.2.1: '>=5.2.2'
+  basic-ftp@<=5.2.2: '>=5.3.0'
+  basic-ftp@<=5.3.0: '>=5.3.1'
+  basic-ftp@=5.2.0: '>=5.2.1'
+  brace-expansion@>=5.0.0 <5.0.6: '>=5.0.6'
+  ip-address@<=10.1.0: '>=10.1.1'
+  protobufjs@<7.5.5: '>=7.5.5'
+  protobufjs@<=7.5.5: '>=7.5.6'
+  protobufjs@<=7.5.7: '>=7.5.8'
+  ws@>=8.0.0 <8.20.1: '>=8.20.1'

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

@@ -5,7 +5,21 @@ import { Type } from "@sinclair/typebox";
 import { createPiRuntime, hasProviderAuth } from "./pi-runtime.js";
 import { loadProjectInstructions } from "./project-instructions.js";
 import { arisaInstallDir, buildAgentRuntimeContext } from "./runtime-context.js";
-import { arisaHomeDir } from "../../runtime/paths.js";
+import { arisaHomeDir, getChatPiSessionsDir } from "../../runtime/paths.js";
+
+function isLocalBaseUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return false;
+  try {
+    const parsed = new URL(value);
+    return parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost";
+  } catch {
+    return false;
+  }
+}
+
+function requiresProviderAuth(model) {
+  return !isLocalBaseUrl(model?.baseUrl);
+}
 
 export class AgentManager {
   constructor({ config, artifactStore, toolRegistry, taskStore, logger }) {
@@ -15,15 +29,30 @@ export class AgentManager {
     this.taskStore = taskStore;
     this.logger = logger;
     this.sessions = new Map();
+    this.pendingNewSessions = new Set();
   }
 
   setConfig(config) {
     this.config = config;
     this.sessions.clear();
+    this.pendingNewSessions.clear();
   }
 
   resetSession(chatId) {
-    this.sessions.delete(chatId);
+    const sessionKey = String(chatId);
+    this.sessions.delete(sessionKey);
+    this.pendingNewSessions.add(sessionKey);
+  }
+
+  createSessionManager(chatId) {
+    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 };
+    }
+    this.logger?.log("agent", `recovering persisted session for chat ${sessionKey}`);
+    return { sessionManager: SessionManager.continueRecent(arisaInstallDir, sessionDir), isNewSession: false };
   }
 
   async validatePiAgent() {
@@ -36,7 +65,7 @@ export class AgentManager {
     if (!model) {
       throw new Error(`Model not found: ${this.config.pi.provider}/${this.config.pi.model}`);
     }
-    if (!this.config.pi.apiKey && !hasProviderAuth(this.config.pi.provider, { authStorage, modelRegistry })) {
+    if (requiresProviderAuth(model) && !this.config.pi.apiKey && !hasProviderAuth(this.config.pi.provider, { authStorage, modelRegistry })) {
       throw new Error(`No auth found for ${this.config.pi.provider}. Provide a Pi API key in bootstrap, or authenticate with Pi login for this provider during bootstrap.`);
     }
 
@@ -50,22 +79,32 @@ export class AgentManager {
   }
 
   async getSessionContext(chatId, telegram) {
-    if (this.sessions.has(chatId)) {
-      this.logger?.log("agent", `reusing session for chat ${chatId}`);
-      return this.sessions.get(chatId);
+    const sessionKey = String(chatId);
+    const effectiveModelId = this.config.pi.model;
+    if (this.sessions.has(sessionKey)) {
+      const existing = this.sessions.get(sessionKey);
+      if (existing?.modelId === effectiveModelId) {
+        this.logger?.log("agent", `reusing session for chat ${sessionKey}`);
+        return existing;
+      }
+      this.logger?.log("agent", `model changed for chat ${sessionKey}: ${existing?.modelId || "unknown"} -> ${effectiveModelId}; recreating session`);
+      this.sessions.delete(sessionKey);
+      this.pendingNewSessions.add(sessionKey);
     }
 
     const { authStorage, modelRegistry } = createPiRuntime({
       provider: this.config.pi.provider,
       apiKey: this.config.pi.apiKey
     });
-    const model = modelRegistry.find(this.config.pi.provider, this.config.pi.model);
-    if (!model) throw new Error(`Model not found: ${this.config.pi.provider}/${this.config.pi.model}`);
-    if (!this.config.pi.apiKey && !hasProviderAuth(this.config.pi.provider, { authStorage, modelRegistry })) {
+    const model = modelRegistry.find(this.config.pi.provider, effectiveModelId);
+    if (!model) throw new Error(`Model not found: ${this.config.pi.provider}/${effectiveModelId}`);
+    if (requiresProviderAuth(model) && !this.config.pi.apiKey && !hasProviderAuth(this.config.pi.provider, { authStorage, modelRegistry })) {
       throw new Error(`No auth found for ${this.config.pi.provider}. Re-run bootstrap and complete login for this provider before Telegram starts.`);
     }
 
-    this.logger?.log("agent", `creating session for chat ${chatId}`);
+    const { sessionManager, isNewSession } = this.createSessionManager(sessionKey);
+    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 { session } = await createAgentSession({
       cwd: arisaInstallDir,
@@ -74,21 +113,28 @@ export class AgentManager {
       modelRegistry,
       model,
       customTools,
-      sessionManager: SessionManager.inMemory()
+      sessionManager
     });
 
-    const instructions = await loadProjectInstructions();
-    const runtimeContext = buildAgentRuntimeContext();
-    this.logger?.log("agent", `injecting project instructions for chat ${chatId}`);
-    this.logger?.log("agent", `runtime context for chat ${chatId}:\n${runtimeContext}`);
-    await session.prompt(`${instructions}\n\n${runtimeContext}\n\nAcknowledge with exactly: OK`);
+    if (!hasExistingSession) {
+      const instructions = await loadProjectInstructions();
+      const runtimeContext = buildAgentRuntimeContext();
+      this.logger?.log("agent", `injecting project instructions for chat ${sessionKey}`);
+      this.logger?.log("agent", `runtime context for chat ${sessionKey}:\n${runtimeContext}`);
+      await session.prompt(`${instructions}\n\n${runtimeContext}\n\nAcknowledge with exactly: OK`);
+    }
 
-    const ctx = { session };
-    this.sessions.set(chatId, ctx);
+    const ctx = { session, modelId: effectiveModelId };
+    this.sessions.set(sessionKey, ctx);
+    if (isNewSession) {
+      this.pendingNewSessions.delete(sessionKey);
+    }
     return ctx;
   }
 
   createTools(telegram, chatId) {
+    const chatArtifactStore = this.artifactStore.forChat(chatId);
+
     return [
       defineTool({
         name: "list_tools",
@@ -117,11 +163,11 @@ export class AgentManager {
       defineTool({
         name: "set_tool_config",
         label: "Set tool config",
-        description: "Write a value into ~/.arisa/tools/<tool>/config.js.",
+        description: "Write a tool config value scoped to the current chat.",
         parameters: Type.Object({ name: Type.String(), field: Type.String(), value: Type.String() }),
         execute: async (_id, params) => {
           await this.toolRegistry.load();
-          const result = await this.toolRegistry.setConfig(params.name, params.field, params.value);
+          const result = await this.toolRegistry.setConfig(params.name, params.field, params.value, chatId);
           return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
         }
       }),
@@ -140,7 +186,7 @@ export class AgentManager {
           this.logger?.log("agent", `run_tool ${params.name}`);
           let artifact = null;
           if (params.artifactId) {
-            artifact = await this.artifactStore.get(params.artifactId);
+            artifact = await chatArtifactStore.get(params.artifactId);
             if (!artifact) {
               return { content: [{ type: "text", text: `Artifact not found: ${params.artifactId}` }], details: { ok: false } };
             }
@@ -151,11 +197,12 @@ export class AgentManager {
               artifact,
               text: params.text,
               args: params.args || {}
-            }
+            },
+            chatId
           });
 
           if (result.output?.text) {
-            const outArtifact = await this.artifactStore.createText({
+            const outArtifact = await chatArtifactStore.createText({
               text: result.output.text,
               source: { type: "tool", toolName: params.name },
               metadata: { tool: params.name }
@@ -164,7 +211,7 @@ export class AgentManager {
           }
 
           if (result.output?.filePath) {
-            const generated = await this.artifactStore.createFromFile({
+            const generated = await chatArtifactStore.createFromFile({
               originalPath: result.output.filePath,
               fileName: result.output.fileName || path.basename(result.output.filePath),
               kind: result.output.kind || "file",
@@ -261,7 +308,8 @@ export class AgentManager {
           this.logger?.log("agent", `send_media_reply via ${toolName}`);
           const result = await this.toolRegistry.run({
             name: toolName,
-            request: { text: params.text, args: {} }
+            request: { text: params.text, args: {} },
+            chatId
           });
           if (!result.ok || !result.output?.filePath) {
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };

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

@@ -1,5 +1,5 @@
 import { fileURLToPath } from "node:url";
-import { arisaHomeDir, artifactsDir, stateDir, toolsDir } from "../../runtime/paths.js";
+import { arisaHomeDir, chatsDir, stateDir, toolsDir } from "../../runtime/paths.js";
 
 export const arisaInstallDir = fileURLToPath(new URL("../../..", import.meta.url));
 export const bundledToolsDir = fileURLToPath(new URL("../../../tools", import.meta.url));
@@ -10,7 +10,7 @@ export function buildAgentRuntimeContext() {
     `arisaInstallDir: ${arisaInstallDir}`,
     `bundledToolsDir: ${bundledToolsDir}`,
     `userToolsDir: ${toolsDir}`,
-    `artifactsDir: ${artifactsDir}`,
+    `chatsDir: ${chatsDir}`,
     `stateDir: ${stateDir}`
   ].join("\n");
 }

package/src/core/artifacts/artifact-store.js

@@ -1,39 +1,44 @@
 import { mkdir, readFile, writeFile, copyFile } from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
-import { artifactsDir as rootDir, artifactsIndexFile as indexFile } from "../../runtime/paths.js";
-
-async function loadIndex() {
-  try {
-    return JSON.parse(await readFile(indexFile, "utf8"));
-  } catch {
-    return [];
-  }
-}
-
-async function saveIndex(items) {
-  await mkdir(path.dirname(indexFile), { recursive: true });
-  await writeFile(indexFile, `${JSON.stringify(items, null, 2)}\n`, "utf8");
-}
+import { getChatArtifactsDir, getChatArtifactsIndexFile } from "../../runtime/paths.js";
 
 function id() {
   return crypto.randomUUID();
 }
 
-export class ArtifactStore {
-  constructor() {
+class ChatArtifactStore {
+  constructor(chatId) {
+    this.chatId = String(chatId);
+    this.rootDir = getChatArtifactsDir(this.chatId);
+    this.indexFile = getChatArtifactsIndexFile(this.chatId);
     this.items = null;
   }
 
+  async reload() {
+    try {
+      this.items = JSON.parse(await readFile(this.indexFile, "utf8"));
+    } catch {
+      this.items = [];
+    }
+  }
+
   async init() {
-    if (!this.items) this.items = await loadIndex();
-    await mkdir(rootDir, { recursive: true });
+    await mkdir(this.rootDir, { recursive: true });
+    if (!this.items) await this.reload();
+  }
+
+  async saveIndex() {
+    await mkdir(path.dirname(this.indexFile), { recursive: true });
+    await writeFile(this.indexFile, `${JSON.stringify(this.items, null, 2)}\n`, "utf8");
   }
 
   async createText({ text, mimeType = "text/plain", source, metadata = {} }) {
     await this.init();
+    await this.reload();
     const artifact = {
       id: id(),
+      chatId: this.chatId,
       kind: "text",
       mimeType,
       text,
@@ -42,19 +47,21 @@ export class ArtifactStore {
       createdAt: new Date().toISOString()
     };
     this.items.push(artifact);
-    await saveIndex(this.items);
+    await this.saveIndex();
     return artifact;
   }
 
   async createFromFile({ originalPath, fileName, kind, mimeType, source, metadata = {} }) {
     await this.init();
+    await this.reload();
     const artifactId = id();
-    const dir = path.join(rootDir, artifactId);
+    const dir = path.join(this.rootDir, artifactId);
     await mkdir(dir, { recursive: true });
     const destPath = path.join(dir, fileName);
     await copyFile(originalPath, destPath);
     const artifact = {
       id: artifactId,
+      chatId: this.chatId,
       kind,
       mimeType,
       path: destPath,
@@ -63,19 +70,21 @@ export class ArtifactStore {
       createdAt: new Date().toISOString()
     };
     this.items.push(artifact);
-    await saveIndex(this.items);
+    await this.saveIndex();
     return artifact;
   }
 
   async createGeneratedFile({ fileName, content, kind, mimeType, source, metadata = {} }) {
     await this.init();
+    await this.reload();
     const artifactId = id();
-    const dir = path.join(rootDir, artifactId);
+    const dir = path.join(this.rootDir, artifactId);
     await mkdir(dir, { recursive: true });
     const destPath = path.join(dir, fileName);
     await writeFile(destPath, content);
     const artifact = {
       id: artifactId,
+      chatId: this.chatId,
       kind,
       mimeType,
       path: destPath,
@@ -84,17 +93,33 @@ export class ArtifactStore {
       createdAt: new Date().toISOString()
     };
     this.items.push(artifact);
-    await saveIndex(this.items);
+    await this.saveIndex();
     return artifact;
   }
 
-  async get(id) {
+  async get(artifactId) {
     await this.init();
-    return this.items.find((item) => item.id === id) || null;
+    await this.reload();
+    return this.items.find((item) => item.id === artifactId) || null;
   }
 
   async listRecent(limit = 20) {
     await this.init();
+    await this.reload();
     return [...this.items].slice(-limit).reverse();
   }
 }
+
+export class ArtifactStore {
+  constructor() {
+    this.chatStores = new Map();
+  }
+
+  forChat(chatId) {
+    const key = String(chatId);
+    if (!this.chatStores.has(key)) {
+      this.chatStores.set(key, new ChatArtifactStore(key));
+    }
+    return this.chatStores.get(key);
+  }
+}

package/src/core/artifacts/normalize-for-reasoning.js

@@ -0,0 +1,90 @@
+function mimeMatches(pattern, mimeType = "") {
+  if (!pattern || !mimeType) return false;
+  if (pattern === mimeType) return true;
+  if (pattern.endsWith("/*")) return mimeType.startsWith(`${pattern.slice(0, -2)}/`);
+  return false;
+}
+
+function toolSupportsArtifact(tool, artifact) {
+  const inputs = Array.isArray(tool.input) ? tool.input : [];
+  return inputs.some((input) => mimeMatches(input, artifact.mimeType));
+}
+
+function toolProduces(tool, mimeType) {
+  const outputs = Array.isArray(tool.output) ? tool.output : [];
+  return outputs.some((output) => mimeMatches(output, mimeType));
+}
+
+function looksLikeAudioTranscriptionTool(tool) {
+  return /transcri|whisper|speech.?to.?text|audio.?to.?text/i.test(`${tool.name} ${tool.description || ""}`);
+}
+
+function shouldNormalizeAudioToText(artifact, desiredMimeType) {
+  return artifact?.mimeType?.startsWith("audio/") && desiredMimeType === "text/plain";
+}
+
+export function selectPipeTool({ toolRegistry, artifact, desiredMimeType }) {
+  const tools = toolRegistry.list()
+    .filter((tool) => toolSupportsArtifact(tool, artifact))
+    .filter((tool) => toolProduces(tool, desiredMimeType));
+
+  if (shouldNormalizeAudioToText(artifact, desiredMimeType)) {
+    return tools.find(looksLikeAudioTranscriptionTool) || null;
+  }
+
+  return null;
+}
+
+export async function normalizeArtifactForReasoning({
+  artifact,
+  desiredMimeType = "text/plain",
+  toolRegistry,
+  chatArtifactStore,
+  chatId
+}) {
+  if (!artifact) return { normalizedArtifact: null, toolResult: null, toolName: "" };
+
+  if (!shouldNormalizeAudioToText(artifact, desiredMimeType)) {
+    return { normalizedArtifact: null, toolResult: null, toolName: "" };
+  }
+
+  const tool = selectPipeTool({ toolRegistry, artifact, desiredMimeType });
+  if (!tool) {
+    return {
+      normalizedArtifact: null,
+      toolResult: {
+        ok: false,
+        status: "failed",
+        error: `No registered tool can normalize ${artifact.mimeType} to ${desiredMimeType}.`
+      },
+      toolName: ""
+    };
+  }
+
+  const result = await toolRegistry.run({
+    name: tool.name,
+    request: { artifact, args: {} },
+    chatId
+  });
+
+  if (!result.ok) {
+    return { normalizedArtifact: null, toolResult: result, toolName: tool.name };
+  }
+
+  if (!result.output?.text) {
+    return {
+      normalizedArtifact: null,
+      toolResult: { ok: false, status: "failed", error: "Normalization returned no text." },
+      toolName: tool.name
+    };
+  }
+
+  const normalizedArtifact = await chatArtifactStore.createText({
+    text: result.output.text,
+    mimeType: desiredMimeType,
+    source: { type: "tool", toolName: tool.name },
+    metadata: { fromArtifactId: artifact.id, tool: tool.name, normalization: true }
+  });
+
+  return { normalizedArtifact, toolResult: result, toolName: tool.name };
+}