arisa 4.2.8 → 4.3.0

package/AGENTS.md

@@ -47,6 +47,12 @@ Each tool declares in `tool.manifest.json`:
 - `keywords`: optional intent tags for capability discovery
 - `skillHints`: optional skills to apply when using or editing the tool
 
+## Text encoding
+All textual content generated or sent by Arisa or its tools must use UTF-8. This includes text files, assistant-created attachments, tool exports, email bodies, messages, HTTP responses, and API payloads.
+
+- Text files must start with a UTF-8 byte-order mark (BOM).
+- Protocol payloads must declare UTF-8 through the protocol's standard mechanism and encode their bytes as UTF-8. For example, email and HTTP text content must use a `Content-Type` with `charset=UTF-8`.
+
 ## Tool-to-Arisa IPC
 Tools that expose a web UI or HTTP endpoint own that server, usually through the shared daemon runtime; Arisa core does not mount tool routes or proxies. Use Arisa IPC when a tool needs registered tools, artifacts, tasks, agent events, or runtime paths.
 
@@ -121,6 +127,15 @@ When such a tool is built, implement it with the shared daemon runtime instead o
 - keep daemon tools headless/server-safe by default when they are meant to run on VPS machines
 - if the daemon exposes an HTTP server, keep that server inside the tool; Arisa core does not discover or mount tool routes
 
+Every managed daemon must also follow the scoped health contract:
+- declare `daemon.scope`, `daemon.autoStart`, and `daemon.health: "internal"` in `tool.manifest.json`
+- use `{ type: "global" }` for shared infrastructure, or `{ type: "chat", chatId }` for one isolated process per chat
+- implement `workLoop({ processJob, healthCheck, recover })`; `healthCheck` must exercise the real capability without human input, and `recover` is optional
+- never write `ready` directly: the shared runtime sets it only after the health operation succeeds through the normal command queue
+- keep daemon infrastructure for a chat-scoped process under `getChatToolStateDir(chatId, toolName)/daemon`; keep user data such as sessions, inboxes, and databases outside that subdirectory
+- persist only non-secret launch identity in `startupContext`; reload global or chat-scoped tool config after every process restart
+- use only the standard daemon states: `starting`, `ready`, `degraded`, `unhealthy`, `restarting`, `stopped`, `failed`
+
 ## 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

package/README.md

@@ -96,8 +96,11 @@ Per chat (`~/.arisa/chats/<chatId>/`):
 - the artifact index is stored in `state/artifacts.json`
 - the Pi session lives under `state/pi-sessions/`
 - chat-scoped tool config overrides live in `config/tools/<tool>/config.js`
+- chat-scoped daemon infrastructure lives in `state/tools/<tool>/daemon/`; persistent tool data stays beside it
 - ephemeral scratch lives under `tmp/`
 
+Managed daemons become ready only after their tool-defined health operation succeeds through the normal command queue. Arisa records heartbeats, successful jobs, errors, and standard lifecycle states, then retries recovery or recreates an unhealthy process with its persisted scope and startup context.
+
 Pi authentication can use either:
 - an API key entered during bootstrap
 - or Pi's existing OAuth login when supported, such as `openai-codex`

package/package.json

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

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

@@ -3,15 +3,45 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { getChatArtifactsDir, getChatArtifactsIndexFile } from "../../runtime/paths.js";
 
+const UTF8_BOM = Buffer.from([0xef, 0xbb, 0xbf]);
+
 function id() {
   return crypto.randomUUID();
 }
 
+function withUtf8Bom(content) {
+  const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+  const body = bytes.subarray(0, UTF8_BOM.length).equals(UTF8_BOM)
+    ? bytes.subarray(UTF8_BOM.length)
+    : bytes;
+  return Buffer.concat([UTF8_BOM, body]);
+}
+
+function isTextMimeType(mimeType = "") {
+  const type = mimeType.split(";", 1)[0].trim().toLowerCase();
+  return type.startsWith("text/")
+    || type === "application/json"
+    || type.endsWith("+json")
+    || type === "application/xml"
+    || type.endsWith("+xml")
+    || type === "application/javascript"
+    || type === "application/ecmascript"
+    || type === "image/svg+xml";
+}
+
 function writeArtifactFile(filePath, content) {
-  if (typeof content === "string") return writeFile(filePath, content, "utf8");
+  if (typeof content === "string") return writeFile(filePath, withUtf8Bom(content));
   return writeFile(filePath, content);
 }
 
+async function copyArtifactFile(originalPath, destPath, mimeType) {
+  if (!isTextMimeType(mimeType)) return copyFile(originalPath, destPath);
+
+  const content = await readFile(originalPath);
+  new TextDecoder("utf-8", { fatal: true }).decode(content);
+  return writeFile(destPath, withUtf8Bom(content));
+}
+
 class ChatArtifactStore {
   constructor(chatId) {
     this.chatId = String(chatId);
@@ -63,7 +93,7 @@ class ChatArtifactStore {
     const dir = path.join(this.rootDir, artifactId);
     await mkdir(dir, { recursive: true });
     const destPath = path.join(dir, fileName);
-    await copyFile(originalPath, destPath);
+    await copyArtifactFile(originalPath, destPath, mimeType);
     const artifact = {
       id: artifactId,
       chatId: this.chatId,

package/src/core/config/config-defaults.js

@@ -0,0 +1,25 @@
+export const daemonConfigDefaults = Object.freeze({
+  supervisorIntervalMs: 5_000,
+  heartbeatIntervalMs: 5_000,
+  heartbeatStaleMs: 20_000,
+  healthIntervalMs: 30_000,
+  healthTimeoutMs: 120_000,
+  healthRetryLimit: 2,
+  healthRetryBackoffMs: 1_000,
+  restartLimit: 3,
+  restartBackoffMs: 2_000,
+  restartBackoffMaxMs: 60_000,
+  startupTimeoutMs: 120_000,
+  stopTimeoutMs: 3_000,
+  queuePollIntervalMs: 250
+});
+
+export function applyConfigDefaults(config) {
+  return {
+    ...config,
+    daemons: {
+      ...daemonConfigDefaults,
+      ...(config.daemons || {})
+    }
+  };
+}

package/src/core/config/config-store.js

@@ -1,15 +1,16 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { configFile } from "../../runtime/bootstrap.js";
+import { configFile } from "../../runtime/paths.js";
+import { applyConfigDefaults } from "./config-defaults.js";
 
 export async function loadConfig() {
   const raw = await readFile(configFile, "utf8");
-  return JSON.parse(raw);
+  return applyConfigDefaults(JSON.parse(raw));
 }
 
 export async function saveConfig(config) {
   await mkdir(path.dirname(configFile), { recursive: true });
-  await writeFile(configFile, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  await writeFile(configFile, `${JSON.stringify(applyConfigDefaults(config), null, 2)}\n`, "utf8");
 }
 
 export async function updateConfig(mutator) {

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

@@ -0,0 +1,185 @@
+import {
+  daemonPaths,
+  isProcessAlive,
+  readJson,
+  startManagedDaemon,
+  stopManagedDaemon,
+  writeDaemonStatus
+} from "./daemon-processes.js";
+import { retryDelay } from "./daemon-policy.js";
+import { submitDaemonControl } from "./daemon-runtime.js";
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function errorRecord(phase, error) {
+  return {
+    at: new Date().toISOString(),
+    phase,
+    message: error?.message || String(error)
+  };
+}
+
+function isTimeout(error) {
+  return ["DAEMON_JOB_TIMEOUT", "DAEMON_OPERATION_TIMEOUT"].includes(error?.code);
+}
+
+function healthDue(status, policy, now = Date.now()) {
+  const heartbeatAt = new Date(status.heartbeatAt || 0).getTime();
+  const healthAt = new Date(status.lastHealthCheckAt || 0).getTime();
+  return status.state !== "ready"
+    || !heartbeatAt
+    || now - heartbeatAt > policy.heartbeatStaleMs
+    || !healthAt
+    || now - healthAt >= policy.healthIntervalMs;
+}
+
+async function probeWithRetries(record, paths, policy) {
+  let lastError;
+  for (let attempt = 0; attempt <= policy.healthRetryLimit; attempt += 1) {
+    if (attempt > 0) {
+      await sleep(policy.healthRetryBackoffMs * (2 ** (attempt - 1)));
+    }
+    try {
+      return await submitDaemonControl(record, "health", {
+        timeoutMs: policy.healthTimeoutMs
+      });
+    } catch (error) {
+      lastError = error;
+      const status = await readJson(paths.statusFile, {});
+      await writeDaemonStatus(paths, {
+        state: isTimeout(error) ? "unhealthy" : "degraded",
+        ...(error?.code === "DAEMON_JOB_TIMEOUT"
+          ? { consecutiveHealthFailures: Number(status.consecutiveHealthFailures || 0) + 1 }
+          : {}),
+        lastError: errorRecord("health", error),
+        message: error?.message || String(error)
+      });
+      if (isTimeout(error)) throw error;
+    }
+  }
+  throw lastError;
+}
+
+async function tryInternalRecovery(record, paths, policy) {
+  const status = await readJson(paths.statusFile, {});
+  if (!status.supportsRecovery) return false;
+  await writeDaemonStatus(paths, {
+    state: "restarting",
+    message: "Attempting tool-specific recovery"
+  });
+  try {
+    const result = await submitDaemonControl(record, "recover", {
+      timeoutMs: policy.healthTimeoutMs
+    });
+    if (result.recovered === false) return false;
+    await probeWithRetries(record, paths, policy);
+    return true;
+  } catch (error) {
+    await writeDaemonStatus(paths, {
+      state: "unhealthy",
+      lastError: errorRecord("recovery", error),
+      message: error?.message || String(error)
+    });
+    return false;
+  }
+}
+
+async function scheduleRestart(record, paths, status, policy, reason) {
+  const current = await readJson(paths.statusFile, status);
+  const restartAttempts = Number(current.restartAttempts || 0) + 1;
+  if (restartAttempts > policy.restartLimit) {
+    await stopManagedDaemon(
+      { toolName: record.toolName, scope: record.scope },
+      { state: null }
+    );
+    await writeDaemonStatus(paths, {
+      state: "failed",
+      pid: null,
+      heartbeatAt: null,
+      restartAttempts,
+      restartRequested: false,
+      nextRestartAt: null,
+      lastError: errorRecord("restart", reason),
+      message: `Daemon restart limit reached: ${reason?.message || reason}`
+    });
+    return "failed";
+  }
+
+  const delayMs = retryDelay(restartAttempts, policy);
+  await stopManagedDaemon(
+    { toolName: record.toolName, scope: record.scope },
+    { state: null }
+  );
+  await writeDaemonStatus(paths, {
+    state: "restarting",
+    pid: null,
+    heartbeatAt: null,
+    restartAttempts,
+    restartRequested: true,
+    nextRestartAt: new Date(Date.now() + delayMs).toISOString(),
+    lastError: errorRecord("restart", reason),
+    message: `Daemon will restart after ${delayMs}ms`
+  });
+  return "restart-scheduled";
+}
+
+async function restartIfDue(record, paths, status, policy) {
+  if (!record.autoStart && !status.restartRequested) return "stopped";
+  if (status.state === "failed") return "failed";
+  const nextRestartAt = new Date(status.nextRestartAt || 0).getTime();
+  if (nextRestartAt && Date.now() < nextRestartAt) return "backoff";
+  if (Number(status.restartAttempts || 0) > policy.restartLimit) {
+    await writeDaemonStatus(paths, {
+      state: "failed",
+      restartRequested: false,
+      nextRestartAt: null,
+      message: "Daemon restart limit reached"
+    });
+    return "failed";
+  }
+  await startManagedDaemon({
+    toolName: record.toolName,
+    entryPath: record.entryPath,
+    scope: record.scope,
+    startupContext: record.startupContext,
+    autoStart: record.autoStart
+  });
+  return "started";
+}
+
+export async function superviseDaemon(record, policy) {
+  const paths = daemonPaths({ toolName: record.toolName, scope: record.scope });
+  const { pid } = await readJson(paths.pidFile, {});
+  const status = await readJson(paths.statusFile, {});
+  const alive = isProcessAlive(pid);
+
+  if (!alive) {
+    if (!record.autoStart && !status.restartRequested && ["stopped", "unhealthy", "failed"].includes(status.state)) {
+      return status.state;
+    }
+    if (!status.state || status.state === "stopped") {
+      return restartIfDue(record, paths, status, policy);
+    }
+    if (status.state === "restarting") {
+      return restartIfDue(record, paths, status, policy);
+    }
+    return scheduleRestart(record, paths, status, policy, new Error("Daemon process exited"));
+  }
+
+  if (!healthDue(status, policy)) return "healthy";
+
+  try {
+    await probeWithRetries(record, paths, policy);
+    return "healthy";
+  } catch (error) {
+    if (!isTimeout(error) && await tryInternalRecovery(record, paths, policy)) return "recovered";
+    await writeDaemonStatus(paths, {
+      state: "unhealthy",
+      lastError: errorRecord("health", error),
+      message: error?.message || String(error)
+    });
+    return scheduleRestart(record, paths, status, policy, error);
+  }
+}

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

@@ -0,0 +1,10 @@
+import { loadConfig } from "../config/config-store.js";
+
+export async function loadDaemonPolicy() {
+  const config = await loadConfig();
+  return config.daemons;
+}
+
+export function retryDelay(attempt, { restartBackoffMs, restartBackoffMaxMs }) {
+  return Math.min(restartBackoffMaxMs, restartBackoffMs * (2 ** Math.max(0, attempt - 1)));
+}