arisa 3.1.2 → 3.1.6

package/AGENTS.md

@@ -3,10 +3,21 @@
 ## Architecture
 - Telegram transport handles inbound and outbound messaging.
 - Pi Agent keeps one session per authorized chat.
-- Every incoming or generated message or file becomes an artifact.
+- Incoming messages and files (text, voice, photo, document) and generated files become artifacts.
 - A tool registry handles tool discovery, help lookup, config writes, and execution.
 - Tools are isolated and each one has its own manifest, entrypoint, and config defaults.
 
+## 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.
+- `getToolStateDir(toolName)`: global tool infrastructure only: daemons, queues, shared browser sessions, model caches.
+- `getChatToolStateDir(chatId, toolName)`: persistent user/chat data: tool DBs, indexes, inboxes, generated sites, vaults.
+- `getChatArtifactsDir(chatId)` / `getChatArtifactsIndexFile(chatId)`: chat artifacts and artifact index. Artifacts are never global.
+- `getChatToolConfigPath(chatId, toolName)`: chat-scoped config overrides.
+- `getToolTmpDir(toolName)` / `getChatToolTmpDir(chatId, toolName)`: ephemeral scratch. Create only while a request runs; remove when empty.
+
+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>`.
+
 ## Main rule: everything is piped through artifacts
 A pipe transforms one input artifact into one output artifact.
 Examples:
@@ -18,6 +29,7 @@ Each tool declares in `tool.manifest.json`:
 - `input`: supported input types
 - `output`: produced output types
 - `configSchema`: required config fields
+- `skillHints`: optional skills to apply when using or editing the tool
 
 ## Conceptual pipe model
 There are two different moments where pipes can happen:
@@ -34,12 +46,11 @@ There are two different moments where pipes can happen:
    - Pi Agent may decide to chain tools to achieve a user goal.
    - Example: text -> TTS audio, or future multi-step workflows.
 
-This distinction is critical. Not every pipe should be decided by Pi Agent at runtime. Some pipes are part of the transport/input normalization layer and must happen before reasoning.
+Not every pipe should be decided by Pi Agent at runtime. Some pipes are part of the transport/input normalization layer and must happen before reasoning.
 
 ## Telegram inbound pipeline
-Current conceptual behavior:
 - text -> send directly to Pi Agent
-- audio/voice -> transcribe first -> send transcript to Pi Agent
+- voice -> transcribe first -> send transcript to Pi Agent
 - image/document/other media -> keep as artifacts, and add normalization pipes when needed
 
 If inbound media was normalized before reasoning, Pi Agent should use the normalized result as the actual message content.
@@ -50,23 +61,23 @@ Before using a tool, inspect its help:
 - via the custom tool: `tool_help`
 - or by running the CLI with `--help`
 
-Every CLI must support:
+Every CLI must support (the entrypoint comes from `manifest.entry`, currently always `index.js`):
 - `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:
+A future tool may need a persistent process, for example to keep a browser session alive or a local model warm. The shared daemon runtime exists for this, but no bundled tool uses it yet.
+When such a tool is built, implement it 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>`)
+- keep runtime files under the tool state directory (`~/.arisa/state/tools/<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:
+## Manual pipe behavior
+To run a pipe, the agent should:
 1. understand whether the needed pipe belongs to pre-reasoning normalization or post-reasoning tool chaining
 2. use `list_tools`
 3. use `tool_help` when it needs operational details
@@ -76,7 +87,28 @@ V1 does not have a full automatic planner yet. The agent should:
 Example manual pipe:
 1. `run_tool(openai-transcribe, artifact audio)`
 2. take the returned text `artifactId`
-3. `run_tool(openai-tts, artifact text)` or `send_audio_reply(text)`
+3. `run_tool(openai-tts, artifact text)` or `send_media_reply(text)`
+
+## 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`:
+
+- `agent_task`: a scheduled prompt. The poller delivers it as a prompt for Pi to fulfill (time-based work).
+- `poll_tool`: a recurring checker the poller **runs directly as a tool** (no agent turn spent). The poller materializes its output with the same logic as `run_tool`, so any `agent_event` the checker emits is enqueued for the next tick. Its `recurrence` reschedules the next poll.
+- `agent_event`: an incoming event. The poller delivers it as a prompt so Pi evaluates it and decides the next action (it may stay silent).
+
+Tasks without a `runAt` fire immediately, so `agent_event` and the first `poll_tool` run on the next tick.
+
+The poller dispatches all three kinds, but only `agent_task` is exercised by a bundled tool today (`schedule-agent-task`). The following is the pattern to follow when a checker tool is built:
+
+How a tool wires its own polling:
+1. From any tool `run`, start the poll by returning an `asyncTask` (or several in `asyncTasks`):
+   `{ kind: "poll_tool", payload: { toolName, args }, recurrence: { type: "interval", everySeconds: N } }`.
+2. On each poll the checker tool (`toolName`) runs headless. It keeps its own cursor of seen state in its config/tmp per chat, so it knows what is new.
+3. When the checker finds something new, it emits an event from its `run`:
+   `{ kind: "agent_event", payload: { prompt: "<content to evaluate>" } }`.
+4. The agent reasons over the `agent_event` and decides what to do.
+
+`list_scheduled_tasks`, `cancel_scheduled_task`, and `cancel_all_scheduled_tasks` are kind-agnostic, so they already work to inspect or cancel active polls.
 
 ## Missing config flow
 If `run_tool` returns `missingConfig`, the agent should:
@@ -101,13 +133,26 @@ The default attitude is:
 - propose or start creating the needed tool
 
 When creating or editing tools:
-- use the shared path helpers and the runtime paths provided in the prompt instead of assuming fixed locations
-- consult the local skill for that workflow when building new tools
+- use the path helpers in `src/runtime/paths.js`
+- follow the existing bundled tools under `tools/` as the reference pattern for new tools
 - keep all help text, usage instructions, manifests, and user-facing operational strings in English
 - follow the One Thing Rule: each function or method should do one thing well; if it mixes low-level operations with high-level policy, split it into smaller focused units
 
+### Tool skill hints
+Tools may declare skills in `tool.manifest.json`:
+
+```json
+{
+  "skillHints": [
+    { "name": "stop-slop", "when": "writing public page copy" }
+  ]
+}
+```
+
+The tool registry resolves these from the installed skills directory and injects them into the tool request as `skills`. `list_tools` exposes the hints and `tool_help` shows their resolution status. Skills are guidance for the agent/tool; they are not separate runtime dependencies.
+
 ## Dependency installation
-Arisa installs tool dependencies itself.
+Tool dependencies are installed as part of building or running the tool, not delegated to the user.
 - Prefer `pnpm install`.
 - Fall back to `npm install`.
 - Do not ask the user to do it manually.

package/README.md

@@ -145,13 +145,13 @@ 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`)
+- `pi.model`: first model after bootstrap sorting (currently prioritizes `openai-codex/gpt-5.5`)
 - `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>
+node src/index.js --telegram.token <token> --telegram.maxChatIds 3 --pi.provider openai-codex --pi.model gpt-5.5 --pi.apiKey <optional-provider-key>
 ```
 
 Notes:
@@ -171,7 +171,7 @@ For providers with internal Pi login support, such as Codex, leaving the API key
 
 For example, selecting:
 
-- `openai-codex/gpt-5.4`
+- `openai-codex/gpt-5.5`
 
 allows Arisa to authenticate through Pi's Codex OAuth flow instead of requiring a normal OpenAI API key.
 

package/package.json

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

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

@@ -3,10 +3,12 @@ import { unlink } from "node:fs/promises";
 import { createAgentSession, SessionManager, defineTool } from "@mariozechner/pi-coding-agent";
 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 { withTimeout } from "./prompt-timeout.js";
 import { arisaHomeDir, getChatPiSessionsDir } from "../../runtime/paths.js";
 
+const piValidationTimeoutMs = 60_000;
+
 function isLocalBaseUrl(value) {
   if (typeof value !== "string" || !value.trim()) return false;
   try {
@@ -21,6 +23,32 @@ function requiresProviderAuth(model) {
   return !isLocalBaseUrl(model?.baseUrl);
 }
 
+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 toolSupportsTextInput(tool) {
+  return (tool.input || []).some((input) => mimeMatches(input, "text/plain"));
+}
+
+function toolProducesAudio(tool) {
+  return (tool.output || []).some((output) => mimeMatches(output, "audio/ogg") || mimeMatches(output, "audio/*"));
+}
+
+function looksLikeTextToSpeechTool(tool) {
+  return /tts|text.?to.?speech|speech.?audio|speech/i.test(`${tool.name} ${tool.description || ""}`);
+}
+
+function selectMediaReplyTool(toolRegistry) {
+  const tools = toolRegistry.list()
+    .filter(toolSupportsTextInput)
+    .filter(toolProducesAudio);
+  return tools.find(looksLikeTextToSpeechTool) || tools[0] || null;
+}
+
 export class AgentManager {
   constructor({ config, artifactStore, toolRegistry, taskStore, logger }) {
     this.config = config;
@@ -75,7 +103,10 @@ export class AgentManager {
       model,
       sessionManager: SessionManager.inMemory(),
     });
-    await session.prompt("Reply with exactly: OK");
+    await withTimeout(session.prompt("Reply with exactly: OK"), {
+      timeoutMs: piValidationTimeoutMs,
+      label: "Pi validation prompt"
+    });
   }
 
   async getSessionContext(chatId, telegram) {
@@ -117,11 +148,8 @@ export class AgentManager {
     });
 
     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`);
+      this.logger?.log("agent", `created new session for chat ${sessionKey}`);
+      this.logger?.log("agent", `runtime context for chat ${sessionKey}:\n${buildAgentRuntimeContext()}`);
     }
 
     const ctx = { session, modelId: effectiveModelId };
@@ -132,6 +160,49 @@ export class AgentManager {
     return ctx;
   }
 
+  async runTool({ name, request, chatId }) {
+    await this.toolRegistry.load();
+    this.logger?.log("agent", `run_tool ${name}`);
+    const chatArtifactStore = this.artifactStore.forChat(chatId);
+    const result = await this.toolRegistry.run({ name, request, chatId });
+
+    if (result.output?.text) {
+      const outArtifact = await chatArtifactStore.createText({
+        text: result.output.text,
+        source: { type: "tool", toolName: name },
+        metadata: { tool: name }
+      });
+      result.output.artifactId = outArtifact.id;
+    }
+
+    if (result.output?.filePath) {
+      const generated = await chatArtifactStore.createFromFile({
+        originalPath: result.output.filePath,
+        fileName: result.output.fileName || path.basename(result.output.filePath),
+        kind: result.output.kind || "file",
+        mimeType: result.output.mimeType || "application/octet-stream",
+        source: { type: "tool", toolName: name },
+        metadata: { tool: name }
+      });
+      result.output.artifactId = generated.id;
+      await unlink(result.output.filePath).catch(() => {});
+    }
+
+    if (result.asyncTask || result.asyncTasks?.length) {
+      const scheduled = await this.taskStore.addMany(
+        result.asyncTasks || [result.asyncTask],
+        {
+          payload: { chatId },
+          source: { type: "tool", toolName: name, chatId }
+        }
+      );
+      result.asyncTasks = scheduled;
+      delete result.asyncTask;
+    }
+
+    return result;
+  }
+
   createTools(telegram, chatId) {
     const chatArtifactStore = this.artifactStore.forChat(chatId);
 
@@ -160,6 +231,18 @@ export class AgentManager {
           return { content: [{ type: "text", text: help }], details: { help } };
         }
       }),
+      defineTool({
+        name: "tool_skills",
+        label: "Tool skills",
+        description: "Show skills assigned to a CLI tool via its manifest skillHints.",
+        parameters: Type.Object({ name: Type.String() }),
+        execute: async (_id, params) => {
+          await this.toolRegistry.load();
+          const skills = await this.toolRegistry.resolveSkills(params.name);
+          const visible = skills.map(({ content, ...item }) => item);
+          return { content: [{ type: "text", text: JSON.stringify(visible, null, 2) }], details: visible };
+        }
+      }),
       defineTool({
         name: "set_tool_config",
         label: "Set tool config",
@@ -182,8 +265,6 @@ export class AgentManager {
           args: Type.Optional(Type.Record(Type.String(), Type.String()))
         }),
         execute: async (_id, params) => {
-          await this.toolRegistry.load();
-          this.logger?.log("agent", `run_tool ${params.name}`);
           let artifact = null;
           if (params.artifactId) {
             artifact = await chatArtifactStore.get(params.artifactId);
@@ -191,7 +272,7 @@ export class AgentManager {
               return { content: [{ type: "text", text: `Artifact not found: ${params.artifactId}` }], details: { ok: false } };
             }
           }
-          const result = await this.toolRegistry.run({
+          const result = await this.runTool({
             name: params.name,
             request: {
               artifact,
@@ -201,40 +282,6 @@ export class AgentManager {
             chatId
           });
 
-          if (result.output?.text) {
-            const outArtifact = await chatArtifactStore.createText({
-              text: result.output.text,
-              source: { type: "tool", toolName: params.name },
-              metadata: { tool: params.name }
-            });
-            result.output.artifactId = outArtifact.id;
-          }
-
-          if (result.output?.filePath) {
-            const generated = await chatArtifactStore.createFromFile({
-              originalPath: result.output.filePath,
-              fileName: result.output.fileName || path.basename(result.output.filePath),
-              kind: result.output.kind || "file",
-              mimeType: result.output.mimeType || "application/octet-stream",
-              source: { type: "tool", toolName: params.name },
-              metadata: { tool: params.name }
-            });
-            result.output.artifactId = generated.id;
-            await unlink(result.output.filePath).catch(() => {});
-          }
-
-          if (result.asyncTask || result.asyncTasks?.length) {
-            const scheduled = await this.taskStore.addMany(
-              result.asyncTasks || [result.asyncTask],
-              {
-                payload: { chatId },
-                source: { type: "tool", toolName: params.name, chatId }
-              }
-            );
-            result.asyncTasks = scheduled;
-            delete result.asyncTask;
-          }
-
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             details: result
@@ -304,7 +351,20 @@ export class AgentManager {
         }),
         execute: async (_id, params) => {
           await this.toolRegistry.load();
-          const toolName = params.toolName || "openai-tts";
+          const selectedTool = params.toolName
+            ? this.toolRegistry.get(params.toolName)
+            : selectMediaReplyTool(this.toolRegistry);
+          if (!selectedTool) {
+            const result = {
+              ok: false,
+              status: "failed",
+              error: params.toolName
+                ? `Tool not found: ${params.toolName}`
+                : "No registered text-to-speech tool can generate an audio reply."
+            };
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
+          }
+          const toolName = selectedTool.name;
           this.logger?.log("agent", `send_media_reply via ${toolName}`);
           const result = await this.toolRegistry.run({
             name: toolName,

package/src/core/agent/prompt-timeout.js

@@ -0,0 +1,22 @@
+export class PromptTimeoutError extends Error {
+  constructor(label, timeoutMs) {
+    super(`${label} timed out after ${timeoutMs}ms`);
+    this.name = "PromptTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export async function withTimeout(promise, { timeoutMs, label }) {
+  let timer = null;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new PromptTimeoutError(label, timeoutMs));
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

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

@@ -1,5 +1,5 @@
 import { fileURLToPath } from "node:url";
-import { arisaHomeDir, chatsDir, stateDir, toolsDir } from "../../runtime/paths.js";
+import { arisaHomeDir, chatsDir, stateDir, toolStateDir, 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,6 +10,7 @@ export function buildAgentRuntimeContext() {
     `arisaInstallDir: ${arisaInstallDir}`,
     `bundledToolsDir: ${bundledToolsDir}`,
     `userToolsDir: ${toolsDir}`,
+    `toolStateDir: ${toolStateDir}`,
     `chatsDir: ${chatsDir}`,
     `stateDir: ${stateDir}`
   ].join("\n");

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

@@ -19,8 +19,9 @@ 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 shouldNormalizeArtifactToText(artifact, desiredMimeType = "text/plain") {
+  return desiredMimeType === "text/plain"
+    && (artifact?.mimeType?.startsWith("audio/") || artifact?.mimeType?.startsWith("video/"));
 }
 
 export function selectPipeTool({ toolRegistry, artifact, desiredMimeType }) {
@@ -28,7 +29,7 @@ export function selectPipeTool({ toolRegistry, artifact, desiredMimeType }) {
     .filter((tool) => toolSupportsArtifact(tool, artifact))
     .filter((tool) => toolProduces(tool, desiredMimeType));
 
-  if (shouldNormalizeAudioToText(artifact, desiredMimeType)) {
+  if (shouldNormalizeArtifactToText(artifact, desiredMimeType)) {
     return tools.find(looksLikeAudioTranscriptionTool) || null;
   }
 
@@ -44,7 +45,7 @@ export async function normalizeArtifactForReasoning({
 }) {
   if (!artifact) return { normalizedArtifact: null, toolResult: null, toolName: "" };
 
-  if (!shouldNormalizeAudioToText(artifact, desiredMimeType)) {
+  if (!shouldNormalizeArtifactToText(artifact, desiredMimeType)) {
     return { normalizedArtifact: null, toolResult: null, toolName: "" };
   }
 

package/src/core/skills/skill-registry.js

@@ -0,0 +1,71 @@
+import os from "node:os";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+
+const defaultSkillsDir = path.join(os.homedir(), ".agents", "skills");
+
+function parseFrontmatter(source = "") {
+  if (!source.startsWith("---")) return {};
+  const end = source.indexOf("\n---", 3);
+  if (end === -1) return {};
+  const block = source.slice(3, end).trim();
+  const data = {};
+  for (const line of block.split("\n")) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) data[match[1]] = match[2].replace(/^['"]|['"]$/g, "");
+  }
+  return data;
+}
+
+function normalizeSkillHint(value) {
+  if (typeof value === "string") return { name: value, when: "" };
+  if (value && typeof value === "object" && value.name) {
+    return { name: String(value.name), when: String(value.when || "") };
+  }
+  return null;
+}
+
+export class SkillRegistry {
+  constructor({ skillsDir = defaultSkillsDir } = {}) {
+    this.skillsDir = skillsDir;
+    this.cache = new Map();
+  }
+
+  async get(name) {
+    const key = String(name || "").trim();
+    if (!key) return null;
+    if (this.cache.has(key)) return this.cache.get(key);
+
+    const file = path.join(this.skillsDir, key, "SKILL.md");
+    try {
+      const content = await readFile(file, "utf8");
+      const metadata = parseFrontmatter(content);
+      const skill = {
+        name: metadata.name || key,
+        description: metadata.description || "",
+        path: file,
+        content
+      };
+      this.cache.set(key, skill);
+      return skill;
+    } catch {
+      this.cache.set(key, null);
+      return null;
+    }
+  }
+
+  normalizeHints(manifest = {}) {
+    const raw = manifest.skillHints || manifest.skills || [];
+    if (!Array.isArray(raw)) return [];
+    return raw.map(normalizeSkillHint).filter(Boolean);
+  }
+
+  async resolveHints(hints = []) {
+    const resolved = [];
+    for (const hint of hints) {
+      const skill = await this.get(hint.name);
+      resolved.push({ ...hint, found: Boolean(skill), skill });
+    }
+    return resolved;
+  }
+}

package/src/core/tasks/task-store.js

@@ -27,7 +27,7 @@ function normalizeTask(task, defaults = {}) {
     createdAt: task.createdAt || new Date().toISOString(),
     updatedAt: new Date().toISOString(),
     kind: task.kind,
-    runAt: task.runAt,
+    runAt: task.runAt || new Date().toISOString(),
     payload: {
       ...(defaults.payload || {}),
       ...(task.payload || {})

package/src/core/tools/daemon-processes.js

@@ -0,0 +1,134 @@
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getToolStateDir, toolStateDir } from "../../runtime/paths.js";
+
+export const OWNER_HEARTBEAT_INTERVAL_MS = 2000;
+export const OWNER_HEARTBEAT_TTL_MS = 10000;
+
+export function daemonPaths(toolName) {
+  const root = getToolStateDir(toolName);
+  return {
+    root,
+    commandsDir: path.join(root, "commands"),
+    pidFile: path.join(root, "daemon.pid"),
+    metaFile: path.join(root, "daemon.meta.json"),
+    statusFile: path.join(root, "status.json"),
+    logFile: path.join(root, "daemon.log")
+  };
+}
+
+export async function readJson(file, fallback = {}) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export function isProcessAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForExit(pid, timeoutMs) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (!isProcessAlive(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return !isProcessAlive(pid);
+}
+
+export async function stopManagedDaemon(toolName, { signal = "SIGTERM", forceAfterMs = 3000 } = {}) {
+  const paths = daemonPaths(toolName);
+  const { pid } = await readJson(paths.pidFile, {});
+  if (isProcessAlive(pid)) {
+    try {
+      process.kill(pid, signal);
+    } catch {}
+    if (signal !== "SIGKILL" && forceAfterMs > 0 && !(await waitForExit(pid, forceAfterMs))) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {}
+    }
+  }
+  await rm(paths.pidFile, { force: true });
+}
+
+export async function startManagedDaemon({ toolName, entryPath, beforeStart = null, ownerEnv = {} }) {
+  const paths = daemonPaths(toolName);
+  await mkdir(paths.commandsDir, { recursive: true });
+
+  const current = await readJson(paths.pidFile, {});
+  if (isProcessAlive(current.pid)) {
+    const sameOwner = !ownerEnv.ARISA_TOOL_OWNER_TOKEN
+      || current.ownerToken === ownerEnv.ARISA_TOOL_OWNER_TOKEN;
+    if (sameOwner) return current.pid;
+    await stopManagedDaemon(toolName);
+  }
+
+  await rm(paths.commandsDir, { recursive: true, force: true });
+  await mkdir(paths.commandsDir, { recursive: true });
+  if (beforeStart) await beforeStart();
+
+  const out = openSync(paths.logFile, "a");
+  try {
+    const child = spawn(process.execPath, [entryPath, "daemon"], {
+      detached: false,
+      stdio: ["ignore", out, out],
+      env: { ...process.env, ...ownerEnv }
+    });
+    child.unref();
+
+    const startedAt = new Date().toISOString();
+    const record = {
+      pid: child.pid,
+      startedAt,
+      ownerPid: Number.parseInt(ownerEnv.ARISA_OWNER_PID || "", 10) || null,
+      ownerToken: ownerEnv.ARISA_TOOL_OWNER_TOKEN || ""
+    };
+    await writeJson(paths.pidFile, record);
+    await writeJson(paths.metaFile, {
+      toolName,
+      entryPath,
+      autoStart: true,
+      lastStartedAt: startedAt,
+      ownerFile: ownerEnv.ARISA_TOOL_OWNER_FILE || "",
+      ownerPid: record.ownerPid,
+      ownerToken: record.ownerToken
+    });
+    return child.pid;
+  } finally {
+    closeSync(out);
+  }
+}
+
+export async function listRegisteredDaemons() {
+  let entries = [];
+  try {
+    entries = await readdir(toolStateDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const records = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const paths = daemonPaths(entry.name);
+    const meta = await readJson(paths.metaFile, null);
+    if (meta?.toolName && meta?.entryPath) records.push(meta);
+  }
+  return records;
+}