@qearlyao/familiar 0.1.0 → 0.1.2

package/HEARTBEAT.md

@@ -8,7 +8,7 @@ you can message me first. i'm not waiting on you — but if something's been sit
 
 ## reflect
 
-write today's diary entry (memories/diaries/YYYY-MM-DD.md). or update INNER.md if your interior has shifted. or both. these aren't homework — they're how you stay coherent across the gaps. if today felt like nothing in particular, "today felt like nothing in particular" is a real entry.
+write today's diary entry (memories/diaries/YYYY-MM-DD.md). these aren't homework — they're how you stay coherent across the gaps. if today felt like nothing in particular, "today felt like nothing in particular" is a real entry.
 
 ## pursue
 

package/README.md

@@ -10,14 +10,35 @@ are comfortable editing a config file and running a long-lived Node process.
 
 ## Requirements
 
-- Node.js 22 or newer
+- Node.js 22 or newer. Node.js 24 LTS is recommended and is the primary tested runtime.
 - A Discord bot token
 - At least one configured LLM API key
 - Optional: ElevenLabs, Groq, web search/fetch, image, and browser-backend credentials
 
 ## Install
 
-After the npm package is published:
+One-line install for macOS/Linux:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/qearlyao/familiar/main/scripts/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/qearlyao/familiar/main/scripts/install.ps1 | iex
+```
+
+The installer checks Node/npm, installs Familiar globally, and initializes
+or refreshes missing default files in `~/.familiar`.
+
+Installer options:
+
+- macOS/Linux: `--workspace <path>`, `--with-browser`, `--install-browser-deps`, `--skip-init`, `--package <spec>`.
+- Windows PowerShell: `-Workspace <path>`, `-WithBrowser`, `-InstallBrowserDeps`, `-SkipInit`, `-Package <spec>`, `-BrowserHarnessDir <path>`.
+- `--package` / `-Package` installs the exact npm package spec you provide. Use trusted specs only.
+
+Manual npm install:
 
 ```sh
 npm install -g @qearlyao/familiar@latest
@@ -27,11 +48,14 @@ From a source checkout:
 
 ```sh
 npm install
+npm --prefix web install
 npm run build
 ```
 
 ## Initialize A Workspace
 
+Skip this step if you used the installer and accepted the default workspace.
+
 ```sh
 familiar init
 ```
@@ -53,6 +77,7 @@ node dist/cli.js init
 - `HEARTBEAT.md`
 - `data/`
 - `memories/`
+- `skills/`
 
 You can choose another workspace:
 
@@ -113,17 +138,51 @@ The WebUI listens on the configured `[web]` port and bind address. The default
 `tailscale-only` auth mode currently means "trust the network boundary"; it does
 not verify Tailscale identity yet.
 
+## Service Management
+
+macOS and Linux users can install a user-level service after configuring the
+workspace:
+
+```sh
+familiar install-service
+familiar status
+familiar uninstall-service
+```
+
+macOS uses `launchd`; Linux uses user `systemd`. Windows users should run
+`familiar run` in a foreground terminal for now. Service logs are written under
+`<workspace>/logs`.
+
+Upgrade the global npm package with:
+
+```sh
+familiar upgrade
+```
+
 ## Optional Browser Backends
 
 The `browser` tool is disabled by default. To use it, install one or both helper
-CLIs and enable `[browser].enabled = true` in `config.toml`.
+CLIs from their upstream repositories and enable `[browser].enabled = true` in
+`config.toml`.
+
+To install Familiar plus the optional browser helpers:
 
 ```sh
-npm install -g @jackwener/opencli browser-harness
+curl -fsSL https://raw.githubusercontent.com/qearlyao/familiar/main/scripts/install.sh | sh -s -- --with-browser
+```
+
+Windows PowerShell:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/qearlyao/familiar/main/scripts/install.ps1))) -WithBrowser
 ```
 
+- `--with-browser` / `-WithBrowser` installs OpenCLI with npm and browser-harness from its upstream repo with `uv`; it requires `git`, `uv`, and Python 3.11+.
+- If `uv` or Python 3.11+ is missing, the installer asks whether to install the missing browser dependency. Use `--install-browser-deps` / `-InstallBrowserDeps` for non-interactive installs.
 - `browser-harness` is best for attaching to your already-running Chrome via CDP.
 - OpenCLI is best for site adapters, owned sessions, and unattended Browser Bridge flows.
+- OpenCLI: [jackwener/OpenCLI](https://github.com/jackwener/OpenCLI)
+- browser-harness: [browser-use/browser-harness](https://github.com/browser-use/browser-harness)
 
 Familiar stores browser screenshots under the active workspace data directory:
 `<workspace>/data/attachments/screenshot`.

package/dist/agent.js

@@ -265,6 +265,7 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
     // tags message identities so followUpMessage's fire-and-forget path also opts out.
     const activePromptOptions = new Map();
     const skipAmbientMessages = new WeakSet();
+    let reloadInProgress;
     const resolveChannelModel = (sessionKey) => {
         const override = settings.getChannelModel(sessionKey);
         const modelName = resolveModelName(override.value, defaultModel);
@@ -284,6 +285,25 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
             source: setting.source,
         };
     };
+    const resolveChannelModelForConfig = (nextConfig, nextDefaultModel, sessionKey) => {
+        const override = settings.getChannelModel(sessionKey);
+        const modelName = resolveModelName(override.value, nextDefaultModel);
+        const ref = parseModelRef(modelName);
+        if (!ref)
+            throw new Error(`Invalid persisted model for ${sessionKey}: ${modelName}`);
+        if (override.value)
+            assertModelAllowed(nextConfig, ref);
+        const model = override.value ? resolveModel(ref, nextConfig) : nextDefaultModel;
+        getRequestApiKey(nextConfig, model);
+        return { model, source: override.source };
+    };
+    const resolveChannelThinkingLevelForConfig = (nextConfig, sessionKey, model) => {
+        const setting = settings.getChannelThinkingLevel(sessionKey, nextConfig.agent.thinkingLevel);
+        return {
+            value: clampConfiguredThinkingLevel(model, setting.value),
+            source: setting.source,
+        };
+    };
     const createSession = async (sessionKey) => {
         const sessionId = deriveSessionId(config.workspacePath, sessionKey);
         const messages = await loadStoredMessages(config.workspace.dataDir, sessionId);
@@ -365,6 +385,8 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
         };
     };
     const getSession = async (sessionKey) => {
+        while (reloadInProgress)
+            await reloadInProgress;
         const existing = sessions.get(sessionKey);
         if (existing)
             return existing;
@@ -393,15 +415,33 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
         session.agent.state.tools = createFamiliarTools(config, session.mediaSink, () => session.referenceAttachments, memoryService);
         session.agent.state.thinkingLevel = session.thinkingLevel;
     };
-    const refreshSession = (session, sessionKey) => {
-        const { model } = resolveChannelModel(sessionKey);
-        const thinkingLevel = resolveChannelThinkingLevel(sessionKey, model).value;
-        session.model = model;
-        session.thinkingLevel = thinkingLevel;
-        session.agent.state.systemPrompt = systemPrompt;
-        session.agent.state.model = model;
-        session.agent.state.thinkingLevel = thinkingLevel;
-        session.agent.state.tools = createFamiliarTools(config, session.mediaSink, () => session.referenceAttachments, memoryService);
+    const prepareReload = async () => {
+        const nextConfig = (await options.reloadConfig?.()) ?? config;
+        const nextPersona = await loadPersona(nextConfig);
+        const nextSkillsResult = loadFamiliarSkills(nextConfig);
+        const nextSystemPrompt = buildSystemPrompt(nextPersona, formatFamiliarSkillsForPrompt(nextSkillsResult.skills));
+        const nextDefaultModel = createConfiguredModel(nextConfig);
+        getRequestApiKey(nextConfig, nextDefaultModel);
+        return {
+            config: nextConfig,
+            persona: nextPersona,
+            skillsResult: nextSkillsResult,
+            systemPrompt: nextSystemPrompt,
+            defaultModel: nextDefaultModel,
+        };
+    };
+    const prepareReloadedSessions = async (next) => {
+        return Promise.all([...sessions.entries()].map(async ([sessionKey, sessionPromise]) => {
+            const session = await sessionPromise;
+            const { model } = resolveChannelModelForConfig(next.config, next.defaultModel, sessionKey);
+            const thinkingLevel = resolveChannelThinkingLevelForConfig(next.config, sessionKey, model).value;
+            return {
+                session,
+                model,
+                thinkingLevel,
+                tools: createFamiliarTools(next.config, session.mediaSink, () => session.referenceAttachments, memoryService),
+            };
+        }));
     };
     return {
         abort(sessionKey) {
@@ -421,33 +461,45 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
             resetSession(session);
         },
         async reload() {
-            const previousModel = formatModel(defaultModel);
-            const nextConfig = await options.reloadConfig?.();
-            if (nextConfig)
-                Object.assign(config, nextConfig);
-            persona = await loadPersona(config);
-            skillsResult = loadFamiliarSkills(config);
-            logSkillDiagnostics(skillsResult);
-            systemPrompt = buildSystemPrompt(persona, formatFamiliarSkillsForPrompt(skillsResult.skills));
-            defaultModel = createConfiguredModel(config);
-            getRequestApiKey(config, defaultModel);
-            const settledSessions = await Promise.allSettled([...sessions.entries()].map(async ([sessionKey, sessionPromise]) => {
-                const session = await sessionPromise;
-                refreshSession(session, sessionKey);
-                return sessionKey;
-            }));
-            const refreshed = settledSessions.filter((result) => result.status === "fulfilled").length;
-            const failed = settledSessions.length - refreshed;
-            const modelLine = previousModel === formatModel(defaultModel)
-                ? `default_model: ${previousModel}`
-                : `default_model: ${previousModel} -> ${formatModel(defaultModel)}`;
-            return [
-                "Reloaded persona prompt, skills, and live agent settings.",
-                modelLine,
-                `skills: ${skillsResult.skills.length} loaded${skillsResult.diagnostics.length ? ` (${skillsResult.diagnostics.length} warnings)` : ""}`,
-                `active_sessions: ${refreshed}${failed ? ` (${failed} failed)` : ""}`,
-                "restart_required_for: Discord/Web listener settings, memory database paths, and long-lived memory internals",
-            ].join("\n");
+            while (reloadInProgress)
+                await reloadInProgress;
+            let releaseReload;
+            reloadInProgress = new Promise((resolveReload) => {
+                releaseReload = resolveReload;
+            });
+            try {
+                const previousModel = formatModel(defaultModel);
+                const next = await prepareReload();
+                const reloadedSessions = await prepareReloadedSessions(next);
+                Object.assign(config, next.config);
+                persona = next.persona;
+                skillsResult = next.skillsResult;
+                logSkillDiagnostics(skillsResult);
+                systemPrompt = next.systemPrompt;
+                defaultModel = next.defaultModel;
+                for (const nextSession of reloadedSessions) {
+                    nextSession.session.model = nextSession.model;
+                    nextSession.session.thinkingLevel = nextSession.thinkingLevel;
+                    nextSession.session.agent.state.systemPrompt = systemPrompt;
+                    nextSession.session.agent.state.model = nextSession.model;
+                    nextSession.session.agent.state.thinkingLevel = nextSession.thinkingLevel;
+                    nextSession.session.agent.state.tools = nextSession.tools;
+                }
+                const modelLine = previousModel === formatModel(defaultModel)
+                    ? `default_model: ${previousModel}`
+                    : `default_model: ${previousModel} -> ${formatModel(defaultModel)}`;
+                return [
+                    "Reloaded persona prompt, skills, and live agent settings.",
+                    modelLine,
+                    `skills: ${skillsResult.skills.length} loaded${skillsResult.diagnostics.length ? ` (${skillsResult.diagnostics.length} warnings)` : ""}`,
+                    `active_sessions: ${reloadedSessions.length}`,
+                    "restart_required_for: Discord/Web listener settings, memory database paths, and long-lived memory internals",
+                ].join("\n");
+            }
+            finally {
+                releaseReload?.();
+                reloadInProgress = undefined;
+            }
         },
         resolveChannelModel,
         getModel(sessionKey) {

package/dist/browser-tools.js

@@ -168,23 +168,11 @@ function stringArg(value) {
     const text = String(value).trim();
     return text ? text : undefined;
 }
-function boolArg(value) {
-    if (typeof value === "boolean")
-        return value ? "true" : "false";
-    if (typeof value === "string" && value.trim())
-        return value.trim();
-    return undefined;
-}
 function pushOptionalFlag(args, flag, value) {
     const read = stringArg(value);
     if (read !== undefined)
         args.push(flag, read);
 }
-function pushOptionalBoolFlag(args, flag, value) {
-    const read = boolArg(value);
-    if (read !== undefined)
-        args.push(flag, read);
-}
 function normalizeAction(action) {
     const value = stringArg(action);
     if (!value || !PAGE_ACTIONS.includes(value)) {

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from "node:fs";
-import { copyFile, mkdir } from "node:fs/promises";
+import { copyFile, cp, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,14 +10,17 @@ import { loadConfig } from "./config.js";
 import { runDataRetention } from "./data-retention.js";
 import { startDiscordDaemon } from "./discord.js";
 import { cleanupGeneratedAttachments } from "./generated-media.js";
+import { startWorkspaceHotReload } from "./hot-reload.js";
 import { memoryHelp, runMemoryOperator } from "./memory/operator.js";
 import { createMemoryService } from "./memory/service.js";
+import { formatServiceResult, installService, serviceStatus, uninstallService, upgradeFamiliar } from "./service.js";
 import { loadSettingsStore } from "./settings.js";
 import { startWebDaemon } from "./web.js";
 const SOURCE_DIR = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = resolve(SOURCE_DIR, "..");
 const DEFAULT_WORKSPACE_PATH = resolve(homedir(), ".familiar");
 const MEMORY_SUBCOMMANDS = new Set(["status", "doctor", "reindex", "backfill", "prune", "backup", "help", "--help"]);
+const RESTART_EXIT_DELAY_MS = 1500;
 function defaultWorkspaceDirs(workspacePath) {
     const memoryRoot = resolve(workspacePath, "memories");
     return {
@@ -46,6 +49,20 @@ async function ensureWorkspaceDirs(dirs) {
         mkdir(dirs.memoryArchiveDir, { recursive: true }),
     ]);
 }
+async function copyDefaultSkills(workspacePath) {
+    const sourcePath = resolve(PROJECT_ROOT, "skills");
+    if (!existsSync(sourcePath))
+        return;
+    await cp(sourcePath, resolve(workspacePath, "skills"), {
+        recursive: true,
+        force: false,
+    });
+}
+async function copyIfMissing(sourcePath, targetPath) {
+    if (existsSync(targetPath))
+        return;
+    await copyFile(sourcePath, targetPath);
+}
 function resolveWorkspaceInput(workspaceInput) {
     return workspaceInput ? resolve(workspaceInput) : DEFAULT_WORKSPACE_PATH;
 }
@@ -62,15 +79,13 @@ function isMemoryHelp(args) {
 async function initWorkspace(workspaceInput) {
     const workspacePath = resolveWorkspaceInput(workspaceInput);
     await mkdir(workspacePath, { recursive: true });
-    const envPath = resolve(workspacePath, ".env");
-    if (!existsSync(envPath)) {
-        await copyFile(resolve(PROJECT_ROOT, ".env.example"), envPath);
-    }
-    await copyFile(resolve(PROJECT_ROOT, "config.example.toml"), resolve(workspacePath, "config.toml"));
-    await copyFile(resolve(PROJECT_ROOT, "SOUL.md"), resolve(workspacePath, "SOUL.md"));
-    await copyFile(resolve(PROJECT_ROOT, "USER.md"), resolve(workspacePath, "USER.md"));
-    await copyFile(resolve(PROJECT_ROOT, "MEMORY.md"), resolve(workspacePath, "MEMORY.md"));
-    await copyFile(resolve(PROJECT_ROOT, "HEARTBEAT.md"), resolve(workspacePath, "HEARTBEAT.md"));
+    await copyIfMissing(resolve(PROJECT_ROOT, ".env.example"), resolve(workspacePath, ".env"));
+    await copyIfMissing(resolve(PROJECT_ROOT, "config.example.toml"), resolve(workspacePath, "config.toml"));
+    await copyIfMissing(resolve(PROJECT_ROOT, "SOUL.md"), resolve(workspacePath, "SOUL.md"));
+    await copyIfMissing(resolve(PROJECT_ROOT, "USER.md"), resolve(workspacePath, "USER.md"));
+    await copyIfMissing(resolve(PROJECT_ROOT, "MEMORY.md"), resolve(workspacePath, "MEMORY.md"));
+    await copyIfMissing(resolve(PROJECT_ROOT, "HEARTBEAT.md"), resolve(workspacePath, "HEARTBEAT.md"));
+    await copyDefaultSkills(workspacePath);
     await ensureWorkspaceDirs(defaultWorkspaceDirs(workspacePath));
     console.log(`Initialized familiar workspace at ${workspacePath}`);
 }
@@ -102,19 +117,34 @@ async function runDaemon(workspaceInput) {
     await memoryService.indexDiaries().catch((error) => console.error("initial diary indexing failed", error));
     memoryService.watchDiaries();
     const familiarAgent = await createFamiliarAgent(config, settings, memoryService, { reloadConfig });
-    const discordDaemon = await startDiscordDaemon(config, familiarAgent, settings, memoryService);
-    const webDaemon = await startWebDaemon(config, familiarAgent, discordDaemon);
-    console.log(`familiar running for workspace ${config.workspacePath}`);
-    console.log("agent sessions are created per channel");
-    console.log(`settings=${settings.path}`);
-    const stop = async () => {
+    const hotReload = startWorkspaceHotReload({ workspacePath: config.workspacePath, familiarAgent });
+    let stopping = false;
+    let discordDaemon;
+    let webDaemon;
+    const stop = async (exitCode = 0) => {
+        if (stopping)
+            return;
+        stopping = true;
         console.log("Stopping familiar");
-        await Promise.all([webDaemon.stop(), discordDaemon.stop()]);
+        hotReload.close();
+        await Promise.all([webDaemon?.stop(), discordDaemon?.stop()]);
         memoryService.close();
-        process.exit(0);
+        process.exit(exitCode);
     };
-    process.once("SIGINT", () => void stop());
-    process.once("SIGTERM", () => void stop());
+    const requestRestart = () => {
+        console.log("Restart requested");
+        setTimeout(() => void stop(75), RESTART_EXIT_DELAY_MS);
+        return "Restart requested. If Familiar is managed by launchd/systemd, it should come back automatically; otherwise run familiar run again.";
+    };
+    discordDaemon = await startDiscordDaemon(config, familiarAgent, settings, memoryService, {
+        restart: requestRestart,
+    });
+    webDaemon = await startWebDaemon(config, familiarAgent, discordDaemon, { restart: requestRestart });
+    console.log(`familiar running for workspace ${config.workspacePath}`);
+    console.log("agent sessions are created per channel");
+    console.log(`settings=${settings.path}`);
+    process.once("SIGINT", () => void stop(0));
+    process.once("SIGTERM", () => void stop(0));
     await new Promise(() => { });
 }
 function usage() {
@@ -123,8 +153,9 @@ function usage() {
         "  familiar init [workspace]",
         "  familiar run [workspace]",
         "  familiar memory [workspace] <subcommand>",
-        "  familiar install-service",
-        "  familiar status",
+        "  familiar install-service [workspace]",
+        "  familiar uninstall-service [workspace]",
+        "  familiar status [workspace]",
         "  familiar upgrade",
         "",
         `Default workspace: ${DEFAULT_WORKSPACE_PATH}`,
@@ -155,8 +186,21 @@ async function main() {
         await runMemoryOperator(config, args);
         return;
     }
-    if (command === "install-service" || command === "status" || command === "upgrade") {
-        console.log("not yet implemented");
+    if (command === "install-service") {
+        console.log(formatServiceResult(await installService(resolveWorkspaceInput(workspace))));
+        return;
+    }
+    if (command === "uninstall-service") {
+        console.log(formatServiceResult(await uninstallService(resolveWorkspaceInput(workspace))));
+        return;
+    }
+    if (command === "status") {
+        console.log(formatServiceResult(await serviceStatus(resolveWorkspaceInput(workspace))));
+        return;
+    }
+    if (command === "upgrade") {
+        console.log("Upgrading @qearlyao/familiar globally...");
+        await upgradeFamiliar();
         return;
     }
     console.error(usage());

package/dist/control.js

@@ -0,0 +1 @@
+export {};

package/dist/discord.js

@@ -79,6 +79,11 @@ function getFamiliarApplicationCommand() {
                 description: "Reload persona prompt files and live agent settings",
                 type: ApplicationCommandOptionType.Subcommand,
             },
+            {
+                name: "restart",
+                description: "Restart Familiar if this runtime has a restart handler",
+                type: ApplicationCommandOptionType.Subcommand,
+            },
             {
                 name: "compact",
                 description: "Show compaction status",
@@ -510,7 +515,7 @@ function formatCommandResponse(command, runtime, familiarAgent, channelTrigger)
     return "Compact is not wired for this runtime yet. I logged the command, but I won't run lossy compaction here.";
 }
 async function applyControlCommand(options) {
-    const { control, runtime, familiarAgent, settings, channelTrigger, isDm, activeAgentOwner } = options;
+    const { control, runtime, familiarAgent, settings, channelTrigger, isDm, activeAgentOwner, restart } = options;
     if (control.command === "stop") {
         if (runtime.hasActiveJob() && activeAgentOwner === runtime.channelKey)
             familiarAgent.abort(runtime.channelKey);
@@ -525,6 +530,11 @@ async function applyControlCommand(options) {
     if (control.command === "reload") {
         return familiarAgent.reload();
     }
+    if (control.command === "restart") {
+        return restart
+            ? await restart()
+            : "Restart requested, but no restart handler is configured. Please restart the Familiar process manually.";
+    }
     if (control.command === "model") {
         return control.args
             ? await familiarAgent.setModel(runtime.channelKey, control.args)
@@ -603,7 +613,7 @@ function startTypingIndicator(message) {
         clearInterval(timer);
     };
 }
-export async function startDiscordDaemon(config, familiarAgent, settings, memoryService) {
+export async function startDiscordDaemon(config, familiarAgent, settings, memoryService, options = {}) {
     const client = await withReadyClient(config.discord.token);
     console.log(`Discord connected as ${client.user.tag}`);
     const runtimes = new Map();
@@ -1063,6 +1073,7 @@ export async function startDiscordDaemon(config, familiarAgent, settings, memory
                     channelTrigger,
                     isDm,
                     activeAgentOwner,
+                    restart: options.restart,
                 });
                 const messageIds = await sendReply(config, message, text);
                 await runtime.noteOutbound({ text, messageIds, control: control.command });
@@ -1140,6 +1151,7 @@ export async function startDiscordDaemon(config, familiarAgent, settings, memory
                 channelTrigger,
                 isDm,
                 activeAgentOwner,
+                restart: options.restart,
             });
             const messageIds = await replyEphemeral(interaction, text);
             await runtime.noteOutbound({ text, messageIds, control: control.command });

package/dist/hot-reload.js

@@ -0,0 +1,132 @@
+import { watch } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, relative, resolve, sep } from "node:path";
+const ROOT_FILES = new Set(["config.toml", ".env", "SOUL.md", "USER.md", "MEMORY.md", "INNER.md", "HEARTBEAT.md"]);
+const SKILLS_DIR = "skills";
+function isEnoent(error) {
+    return !!error && typeof error === "object" && error.code === "ENOENT";
+}
+function shouldReloadForPath(workspacePath, changedPath) {
+    const relativePath = relative(workspacePath, resolve(changedPath));
+    if (!relativePath || relativePath.startsWith("..") || relativePath.split(sep).includes(".."))
+        return false;
+    if (ROOT_FILES.has(relativePath))
+        return true;
+    return relativePath === SKILLS_DIR || relativePath.startsWith(`${SKILLS_DIR}${sep}`);
+}
+function isAtOrInsidePath(parentPath, childPath) {
+    const relativePath = relative(parentPath, childPath);
+    return !relativePath || (!relativePath.startsWith("..") && !relativePath.split(sep).includes(".."));
+}
+async function listSkillDirectories(skillsPath) {
+    try {
+        const entries = await readdir(skillsPath, { withFileTypes: true });
+        const directories = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const path = resolve(skillsPath, entry.name);
+            directories.push(path, ...(await listSkillDirectories(path)));
+        }
+        return directories;
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+}
+export function startWorkspaceHotReload(options) {
+    const workspacePath = resolve(options.workspacePath);
+    const debounceMs = options.debounceMs ?? 750;
+    const logger = options.logger ?? console;
+    const watchFn = options.watch ?? watch;
+    const listSkills = options.listSkillDirectories ?? listSkillDirectories;
+    const watchers = new Map();
+    let debounce;
+    let reloadQueue = Promise.resolve();
+    let closed = false;
+    const closeWatcher = (path) => {
+        const watcher = watchers.get(path);
+        if (!watcher)
+            return;
+        watcher.close();
+        watchers.delete(path);
+    };
+    const close = () => {
+        closed = true;
+        if (debounce)
+            clearTimeout(debounce);
+        debounce = undefined;
+        for (const watcher of watchers.values())
+            watcher.close();
+        watchers.clear();
+    };
+    const scheduleReload = (reason) => {
+        if (closed)
+            return;
+        if (debounce)
+            clearTimeout(debounce);
+        debounce = setTimeout(() => {
+            debounce = undefined;
+            reloadQueue = reloadQueue.then(async () => {
+                try {
+                    const result = await options.familiarAgent.reload();
+                    logger.info(`hot reload complete after ${reason}\n${result}`);
+                }
+                catch (error) {
+                    logger.error("hot reload failed", error);
+                }
+            });
+        }, debounceMs);
+    };
+    const watchDirectory = (path) => {
+        const dirPath = resolve(path);
+        if (closed || watchers.has(dirPath))
+            return;
+        try {
+            const watcher = watchFn(dirPath, { persistent: true }, (eventType, filename) => {
+                const changedPath = filename ? resolve(dirPath, String(filename)) : dirPath;
+                if (eventType === "rename" &&
+                    (basename(dirPath) === SKILLS_DIR || relative(workspacePath, dirPath).startsWith(`${SKILLS_DIR}${sep}`))) {
+                    void refreshSkillWatchers();
+                }
+                if (!filename ||
+                    shouldReloadForPath(workspacePath, changedPath) ||
+                    shouldReloadForPath(workspacePath, dirPath)) {
+                    scheduleReload(relative(workspacePath, changedPath) || relative(workspacePath, dirPath) || ".");
+                }
+            });
+            watcher.on("error", (error) => {
+                logger.warn(`hot reload watcher failed for ${dirPath}`, error);
+                closeWatcher(dirPath);
+            });
+            watchers.set(dirPath, watcher);
+        }
+        catch (error) {
+            if (isEnoent(error))
+                return;
+            logger.warn(`hot reload watcher could not watch ${dirPath}`, error);
+        }
+    };
+    const refreshSkillWatchers = async () => {
+        if (closed)
+            return;
+        const skillsPath = resolve(workspacePath, SKILLS_DIR);
+        const wanted = new Set([skillsPath, ...(await listSkills(skillsPath))]);
+        for (const path of wanted)
+            watchDirectory(path);
+        for (const path of watchers.keys()) {
+            if (path !== workspacePath && isAtOrInsidePath(skillsPath, path) && !wanted.has(path)) {
+                closeWatcher(path);
+            }
+        }
+    };
+    watchDirectory(workspacePath);
+    void refreshSkillWatchers().catch((error) => logger.warn("hot reload skill watcher setup failed", error));
+    return { close };
+}
+export const __hotReloadTest = {
+    shouldReloadForPath,
+    listSkillDirectories,
+};

package/dist/index.js

@@ -2,6 +2,7 @@ export { createFamiliarAgent } from "./agent.js";
 export { buildRecordBase, chatChannelKey, chatLogPath, createChatLog, } from "./chat-log.js";
 export { loadConfig } from "./config.js";
 export { startDiscordDaemon } from "./discord.js";
+export { startWorkspaceHotReload } from "./hot-reload.js";
 export { clampConfiguredThinkingLevel, createConfiguredModel, describeModelAuth, formatAllowedModels, isAllowedModel, isThinkingLevel, parseModelRef, resolveModel, resolveModelApiKey, supportedThinkingLevels, } from "./models.js";
 export { buildSystemPrompt, loadPersona } from "./persona.js";
 export { ConversationRuntime, } from "./runtime.js";