@qearlyao/familiar 0.2.4 → 0.3.0

package/dist/chat-log.js

@@ -1,6 +1,15 @@
 import { appendFile, mkdir, open, readdir, readFile, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { isEnoent, readFileOrNull } from "./util/fs.js";
+export function hiddenWebMessageIds(records) {
+    return new Set(records.flatMap((record) => {
+        if (record.type === "assistant_retry")
+            return [record.oldMessageId];
+        if (record.type === "message_delete")
+            return [record.messageId];
+        return [];
+    }));
+}
 function sanitizeSegment(value) {
     return value.replace(/[^A-Za-z0-9._=-]+/g, "_").slice(0, 120) || "unknown";
 }
@@ -62,10 +71,13 @@ export function createChatLog(config, channel) {
                     return [];
                 throw error;
             }
-            const records = [];
-            for (const file of files.filter((entry) => entry.endsWith(".jsonl")).sort()) {
+            const jsonlFiles = files.filter((entry) => entry.endsWith(".jsonl")).sort();
+            const contents = await Promise.all(jsonlFiles.map(async (file) => {
                 const filePath = resolve(dir, file);
-                const content = await readFile(filePath, "utf8");
+                return { filePath, content: await readFile(filePath, "utf8") };
+            }));
+            const records = [];
+            for (const { filePath, content } of contents) {
                 for (const [index, line] of content.split(/\r?\n/).entries()) {
                     if (!line.trim())
                         continue;

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { existsSync } from "node:fs";
-import { copyFile, cp, mkdir } from "node:fs/promises";
+import { copyFile, cp, mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { config as loadDotenv } from "dotenv";
 import { createFamiliarAgent } from "./agent.js";
+import { createAgentCore } from "./agent-core.js";
 import { loadConfig } from "./config.js";
 import { runDataRetention } from "./data-retention.js";
 import { startDiscordDaemon } from "./discord.js";
@@ -13,6 +14,7 @@ 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 { loadOwnerIdentity } from "./owner-identity.js";
 import { formatServiceResult, installService, serviceStatus, uninstallService, upgradeFamiliar } from "./service.js";
 import { loadSettingsStore } from "./settings.js";
 import { startWebDaemon } from "./web.js";
@@ -76,6 +78,11 @@ function isMemoryHelp(args) {
     const command = args[0];
     return !command || command === "help" || command === "--help";
 }
+async function packageVersion() {
+    const raw = await readFile(resolve(PROJECT_ROOT, "package.json"), "utf8");
+    const packageJson = JSON.parse(raw);
+    return typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
+}
 async function initWorkspace(workspaceInput) {
     const workspacePath = resolveWorkspaceInput(workspaceInput);
     await mkdir(workspacePath, { recursive: true });
@@ -119,6 +126,7 @@ async function runDaemon(workspaceInput) {
     memoryService.watchDiaries();
     const familiarAgent = await createFamiliarAgent(config, settings, memoryService, { reloadConfig });
     const hotReload = startWorkspaceHotReload({ workspacePath: config.workspacePath, familiarAgent });
+    const agentCore = createAgentCore({ config, familiarAgent, memoryService });
     let stopping = false;
     let discordDaemon;
     let webDaemon;
@@ -129,6 +137,7 @@ async function runDaemon(workspaceInput) {
         console.log("Stopping familiar");
         hotReload.close();
         await Promise.all([webDaemon?.stop(), discordDaemon?.stop()]);
+        await agentCore.stop();
         memoryService.close();
         process.exit(exitCode);
     };
@@ -137,10 +146,21 @@ async function runDaemon(workspaceInput) {
         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 });
+    const identity = await loadOwnerIdentity(config.workspace.dataDir);
+    const token = config.discord.token;
+    if (!identity && !token) {
+        throw new Error("First-time setup needs a DISCORD_TOKEN to establish owner identity. Set DISCORD_TOKEN and run again.");
+    }
+    // The scheduler starts with the first session source to arrive: the cached identity
+    // here, or the live Discord connection below when there is no cache yet.
+    if (identity)
+        await agentCore.useCachedIdentity(identity);
+    webDaemon = await startWebDaemon(config, familiarAgent, agentCore, { restart: requestRestart });
+    if (token) {
+        discordDaemon = startDiscordDaemon(config, token, familiarAgent, settings, memoryService, agentCore, {
+            restart: requestRestart,
+        });
+    }
     console.log(`familiar running for workspace ${config.workspacePath}`);
     console.log("agent sessions are created per channel");
     console.log(`settings=${settings.path}`);
@@ -151,6 +171,8 @@ async function runDaemon(workspaceInput) {
 function usage() {
     return [
         "Usage:",
+        "  familiar --help",
+        "  familiar --version",
         "  familiar init [workspace]",
         "  familiar run [workspace]",
         "  familiar memory [workspace] <subcommand>",
@@ -164,6 +186,14 @@ function usage() {
 }
 async function main() {
     const [, , command, workspace, ...rest] = process.argv;
+    if (!command || command === "--help" || command === "-h") {
+        console.log(usage());
+        return;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(await packageVersion());
+        return;
+    }
     if (command === "init") {
         await initWorkspace(workspace);
         return;
@@ -200,7 +230,7 @@ async function main() {
         return;
     }
     if (command === "upgrade") {
-        console.log("Upgrading @qearlyao/familiar globally...");
+        console.log("Upgrading @qearlyao/familiar and OpenCLI globally...");
         await upgradeFamiliar(resolveWorkspaceInput(workspace));
         return;
     }

package/dist/config/enums.js

@@ -0,0 +1,35 @@
+export const CACHE_RETENTIONS = ["none", "short", "long"];
+export const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+export const DISCORD_REPLY_MODES = ["plain", "reply"];
+export const DISCORD_CHUNK_MODES = ["simple", "paragraph", "newline"];
+export const DISCORD_DISPATCH_MODES = ["steer", "queue", "collect"];
+export const DISCORD_CHANNEL_TRIGGERS = ["mention", "always"];
+export const CRON_FREQUENCIES = [
+    "once",
+    "hourly",
+    "daily",
+    "weekly",
+    "monthly",
+];
+export const CRON_DELIVERY_MODES = ["queue", "follow_up"];
+export const WEB_AUTH_MODES = ["tailscale-only", "bearer", "public-2fa"];
+export const TTS_PROVIDERS = ["elevenlabs"];
+export const IMAGE_GEN_APIS = ["openrouter-images"];
+export const MEDIA_UNDERSTANDING_PROVIDERS = [
+    "groq",
+    "google",
+];
+export const MEMORY_EMBEDDING_FORMATS = [
+    "gemini",
+    "openai",
+    "voyage",
+];
+export const BROWSER_BACKENDS = ["opencli", "browser-harness"];
+export const BROWSER_WINDOW_MODES = ["foreground", "background"];

package/dist/config/interpolate.js

@@ -0,0 +1,15 @@
+export function interpolateEnv(value) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_match, name, fallback) => {
+        return process.env[name] ?? fallback ?? "";
+    });
+}
+export function interpolateValue(value) {
+    if (typeof value === "string")
+        return interpolateEnv(value);
+    if (Array.isArray(value))
+        return value.map(interpolateValue);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, interpolateValue(child)]));
+    }
+    return value;
+}

package/dist/config/model-refs.js

@@ -0,0 +1,11 @@
+import { parseModelRef } from "../models.js";
+export function parseProviderModelRef(value, path) {
+    const parsed = maybeParseProviderModelRef(value);
+    if (parsed)
+        return parsed;
+    throw new Error(`Config value ${path} must be a provider/model id`);
+}
+export function maybeParseProviderModelRef(value) {
+    const parsed = parseModelRef(value);
+    return parsed ? { provider: parsed.provider, modelId: parsed.id, key: parsed.key } : undefined;
+}

package/dist/config/readers.js

@@ -0,0 +1,116 @@
+import { isAbsolute, resolve } from "node:path";
+export function resolveWorkspacePath(workspacePath, filePath) {
+    return isAbsolute(filePath) ? filePath : resolve(workspacePath, filePath);
+}
+export function readString(value, path) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`Missing required config value: ${path}`);
+    }
+    return value;
+}
+export function readOptionalString(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "string")
+        throw new Error(`Config value must be a string: ${JSON.stringify(value)}`);
+    return value.trim() !== "" ? value : fallback;
+}
+export function readOptionalConfigString(value, path) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`Config value ${path} must be a string`);
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function readConfigString(value, fallback, path) {
+    const read = readOptionalConfigString(value, path);
+    return read ?? fallback;
+}
+export function readStringArray(value, path) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`Config value must be a string array: ${path}`);
+    }
+    return value;
+}
+export function readStringRecord(value, path) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Config value must be a string map: ${path}`);
+    }
+    const entries = Object.entries(value);
+    for (const [key, child] of entries) {
+        if (typeof child !== "string")
+            throw new Error(`Config value must be a string map: ${path}.${key}`);
+    }
+    return Object.fromEntries(entries);
+}
+export function readBoolean(value, fallback, path) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === "boolean")
+        return value;
+    throw new Error(`Config value ${path} must be a boolean`);
+}
+export function readInteger(value, fallback, path, min = 0) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min) {
+        throw new Error(`Config value ${path} must be an integer >= ${min}`);
+    }
+    return value;
+}
+export function readNumberInRange(value, fallback, path, min, max) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+        throw new Error(`Config value ${path} must be a number between ${min} and ${max}`);
+    }
+    return value;
+}
+export function readFraction(value, fallback, path) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1) {
+        throw new Error(`Config value ${path} must be a number > 0 and <= 1`);
+    }
+    return value;
+}
+export function readPositiveNumber(value, fallback, path) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`Config value ${path} must be a positive number`);
+    }
+    return value;
+}
+export function readOptionalInteger(value, path, min = 0) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min) {
+        throw new Error(`Config value ${path} must be an integer >= ${min}`);
+    }
+    return value;
+}
+export function readIntegerInRange(value, fallback, path, min, max) {
+    const read = readInteger(value, fallback, path, min);
+    if (read > max)
+        throw new Error(`Config value ${path} must be an integer <= ${max}`);
+    return read;
+}
+export function readOptionalIntegerInRange(value, path, min, max) {
+    const read = readOptionalInteger(value, path, min);
+    if (read !== undefined && read > max)
+        throw new Error(`Config value ${path} must be an integer <= ${max}`);
+    return read;
+}
+export function assertKnownKeys(value, path, knownKeys) {
+    const known = new Set(knownKeys);
+    for (const key of Object.keys(value)) {
+        if (!known.has(key))
+            throw new Error(`Unknown config value: ${path}.${key}`);
+    }
+}

package/dist/config/sections.js

@@ -0,0 +1,113 @@
+import { readEnum } from "../util/guards.js";
+import { CRON_DELIVERY_MODES, CRON_FREQUENCIES } from "./enums.js";
+import { assertKnownKeys, readBoolean, readConfigString, readOptionalConfigString, readOptionalIntegerInRange, readString, resolveWorkspacePath, } from "./readers.js";
+function assertCronTime(value, path) {
+    if (value === undefined)
+        return;
+    if (!/^([01]?\d|2[0-3]):([0-5]\d)$/.test(value)) {
+        throw new Error(`Config value ${path} must be HH:MM local time`);
+    }
+}
+function assertCronRunAt(value, path) {
+    if (value === undefined)
+        return;
+    if (Number.isFinite(Date.parse(value)))
+        return;
+    if (/^\d{4}-\d{2}-\d{2}[ T]([01]\d|2[0-3]):([0-5]\d)(?::([0-5]\d))?$/.test(value))
+        return;
+    throw new Error(`Config value ${path} must be an ISO timestamp or YYYY-MM-DD HH:MM local time`);
+}
+export function readPromptOverrides(value, workspacePath, prefix) {
+    const prompt = readOptionalConfigString(value.prompt, `${prefix}.prompt`);
+    const promptPath = readOptionalConfigString(value.prompt_path, `${prefix}.prompt_path`);
+    const systemPrompt = readOptionalConfigString(value.system_prompt, `${prefix}.system_prompt`);
+    const systemPromptPath = readOptionalConfigString(value.system_prompt_path, `${prefix}.system_prompt_path`);
+    if (prompt && promptPath)
+        throw new Error(`Set either ${prefix}.prompt or ${prefix}.prompt_path, not both`);
+    if (systemPrompt && systemPromptPath) {
+        throw new Error(`Set either ${prefix}.system_prompt or ${prefix}.system_prompt_path, not both`);
+    }
+    return {
+        ...(prompt ? { prompt } : {}),
+        ...(promptPath ? { promptPath: resolveWorkspacePath(workspacePath, promptPath) } : {}),
+        ...(systemPrompt ? { systemPrompt } : {}),
+        ...(systemPromptPath ? { systemPromptPath: resolveWorkspacePath(workspacePath, systemPromptPath) } : {}),
+    };
+}
+export function readCronJobs(cron) {
+    const rawJobs = cron.jobs;
+    if (rawJobs === undefined)
+        return [];
+    if (!Array.isArray(rawJobs))
+        throw new Error("Config value cron.jobs must be an array");
+    const seen = new Set();
+    return rawJobs.map((rawJob, index) => {
+        if (!rawJob || typeof rawJob !== "object" || Array.isArray(rawJob)) {
+            throw new Error(`Config value cron.jobs[${index}] must be a table`);
+        }
+        const job = rawJob;
+        const prefix = `cron.jobs[${index}]`;
+        assertKnownKeys(job, prefix, [
+            "id",
+            "enabled",
+            "frequency",
+            "delivery_mode",
+            "prompt",
+            "run_at",
+            "time",
+            "minute",
+            "weekday",
+            "day",
+        ]);
+        const id = readString(job.id, `${prefix}.id`);
+        if (!/^[A-Za-z0-9._=-]+$/.test(id)) {
+            throw new Error(`Config value ${prefix}.id may only contain letters, numbers, dot, underscore, equals, or dash`);
+        }
+        if (seen.has(id))
+            throw new Error(`Duplicate cron job id: ${id}`);
+        seen.add(id);
+        const frequency = readEnum(readConfigString(job.frequency, "once", `${prefix}.frequency`), `${prefix}.frequency`, CRON_FREQUENCIES);
+        const runAt = readOptionalConfigString(job.run_at, `${prefix}.run_at`);
+        const time = readOptionalConfigString(job.time, `${prefix}.time`);
+        assertCronRunAt(runAt, `${prefix}.run_at`);
+        assertCronTime(time, `${prefix}.time`);
+        if (frequency === "once" && !runAt)
+            throw new Error(`Config value ${prefix}.run_at is required for once jobs`);
+        if (frequency === "once" && time)
+            throw new Error(`Config value ${prefix}.time is only valid for repeating jobs`);
+        if (frequency !== "once" && runAt)
+            throw new Error(`Config value ${prefix}.run_at is only valid for once jobs`);
+        if (frequency !== "once" && frequency !== "hourly" && !time) {
+            throw new Error(`Config value ${prefix}.time is required for ${frequency} jobs`);
+        }
+        return {
+            id,
+            enabled: readBoolean(job.enabled, true, `${prefix}.enabled`),
+            frequency,
+            deliveryMode: readEnum(readConfigString(job.delivery_mode, "queue", `${prefix}.delivery_mode`), `${prefix}.delivery_mode`, CRON_DELIVERY_MODES),
+            prompt: readString(job.prompt, `${prefix}.prompt`),
+            ...(runAt ? { runAt } : {}),
+            ...(time ? { time } : {}),
+            ...(job.minute !== undefined
+                ? { minute: readOptionalIntegerInRange(job.minute, `${prefix}.minute`, 0, 59) }
+                : {}),
+            ...(job.weekday !== undefined
+                ? { weekday: readOptionalIntegerInRange(job.weekday, `${prefix}.weekday`, 0, 6) }
+                : {}),
+            ...(job.day !== undefined ? { day: readOptionalIntegerInRange(job.day, `${prefix}.day`, 1, 31) } : {}),
+        };
+    });
+}
+export function defaultBrowserAllowedSites() {
+    return {
+        twitter: true,
+        xiaohongshu: true,
+        rednote: true,
+        reddit: true,
+        bilibili: true,
+        youtube: true,
+        tiktok: true,
+        douyin: true,
+        spotify: true,
+    };
+}

package/dist/config/types.js

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

package/dist/config-registry.js

@@ -1,4 +1,4 @@
-import { loadConfigOverrides } from "./config-overrides.js";
+import { clearConfigOverride, loadConfigOverrides, setConfigOverride } from "./config-overrides.js";
 import { isAllowedModel, parseModelRef, resolveProviderSetting } from "./models.js";
 function requireBoolean(value, key) {
     if (typeof value !== "boolean")
@@ -47,8 +47,8 @@ export const CONFIG_REGISTRY = {
         write: (config, value) => {
             config.heartbeat.enabled = value;
         },
-        apply: ({ discordDaemon }) => {
-            discordDaemon.rearmHeartbeat();
+        apply: ({ scheduler }) => {
+            scheduler.rearmHeartbeat();
         },
     },
     "heartbeat.idleThresholdMs": {
@@ -57,8 +57,8 @@ export const CONFIG_REGISTRY = {
         write: (config, value) => {
             config.heartbeat.idleThresholdMs = value;
         },
-        apply: ({ discordDaemon }) => {
-            discordDaemon.rearmHeartbeat();
+        apply: ({ scheduler }) => {
+            scheduler.rearmHeartbeat();
         },
     },
     "heartbeat.intervalMs": {
@@ -67,8 +67,8 @@ export const CONFIG_REGISTRY = {
         write: (config, value) => {
             config.heartbeat.intervalMs = value;
         },
-        apply: ({ discordDaemon }) => {
-            discordDaemon.rearmHeartbeat();
+        apply: ({ scheduler }) => {
+            scheduler.rearmHeartbeat();
         },
     },
     "image_gen.enabled": {
@@ -284,3 +284,22 @@ export function applyConfigOverridesToConfig(config) {
         }
     }
 }
+async function mutateConfig(key, nextValue, persist, ctx) {
+    const entry = CONFIG_REGISTRY[key];
+    const previous = entry.read(ctx.config);
+    entry.write(ctx.config, nextValue);
+    try {
+        await persist();
+        await entry.apply?.(ctx);
+    }
+    catch (error) {
+        entry.write(ctx.config, previous);
+        throw error;
+    }
+}
+export async function commitConfigChange(key, value, ctx) {
+    await mutateConfig(key, value, () => setConfigOverride(key, value), ctx);
+}
+export async function clearConfigChange(key, ctx) {
+    await mutateConfig(key, getConfigDefault(key), () => clearConfigOverride(key), ctx);
+}