@qearlyao/familiar 0.1.2 → 0.2.1

package/dist/config-registry.js

@@ -0,0 +1,289 @@
+import { loadConfigOverrides } from "./config-overrides.js";
+import { isAllowedModel, parseModelRef } from "./models.js";
+function requireBoolean(value, key) {
+    if (typeof value !== "boolean")
+        throw new Error(`${key} must be a boolean`);
+    return value;
+}
+function requirePositiveInt(value, key) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+        throw new Error(`${key} must be a positive integer`);
+    }
+    return n;
+}
+function requireInt(value, key, min) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < min) {
+        throw new Error(`${key} must be an integer >= ${min}`);
+    }
+    return n;
+}
+function requireNumberInRange(value, key, min, max) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n) || n < min || n > max) {
+        throw new Error(`${key} must be a number between ${min} and ${max}`);
+    }
+    return n;
+}
+function requireNonNegativeInt(value, key) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
+        throw new Error(`${key} must be a non-negative integer`);
+    }
+    return n;
+}
+function requireNonNegativeNumber(value, key) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new Error(`${key} must be a number >= 0`);
+    }
+    return n;
+}
+function resolveProviderSetting(records, provider, modelId) {
+    return records[`${provider}/${modelId}`] ?? records[provider];
+}
+export const CONFIG_REGISTRY = {
+    "heartbeat.enabled": {
+        read: (config) => config.heartbeat.enabled,
+        validate: (value) => requireBoolean(value, "heartbeat.enabled"),
+        write: (config, value) => {
+            config.heartbeat.enabled = value;
+        },
+        apply: ({ discordDaemon }) => {
+            discordDaemon.rearmHeartbeat();
+        },
+    },
+    "heartbeat.idleThresholdMs": {
+        read: (config) => config.heartbeat.idleThresholdMs,
+        validate: (value) => requirePositiveInt(value, "heartbeat.idleThresholdMs"),
+        write: (config, value) => {
+            config.heartbeat.idleThresholdMs = value;
+        },
+        apply: ({ discordDaemon }) => {
+            discordDaemon.rearmHeartbeat();
+        },
+    },
+    "heartbeat.intervalMs": {
+        read: (config) => config.heartbeat.intervalMs,
+        validate: (value) => requirePositiveInt(value, "heartbeat.intervalMs"),
+        write: (config, value) => {
+            config.heartbeat.intervalMs = value;
+        },
+        apply: ({ discordDaemon }) => {
+            discordDaemon.rearmHeartbeat();
+        },
+    },
+    "image_gen.enabled": {
+        read: (config) => config.imageGen.enabled,
+        validate: (value) => requireBoolean(value, "image_gen.enabled"),
+        write: (config, value) => {
+            config.imageGen.enabled = value;
+        },
+    },
+    "image_gen.model": {
+        read: (config) => config.imageGen.model,
+        validate: (value) => {
+            if (typeof value !== "string")
+                throw new Error("image_gen.model must be a string");
+            const ref = parseModelRef(value);
+            if (!ref)
+                throw new Error("image_gen.model: format must be provider/model-id");
+            return ref.key;
+        },
+        write: (config, value) => {
+            const ref = parseModelRef(value);
+            if (!ref)
+                return;
+            config.imageGen.model = ref.key;
+        },
+    },
+    "image_gen.fallback_model": {
+        read: (config) => config.imageGen.fallbackModel ?? "",
+        validate: (value) => {
+            if (value == null || value === "")
+                return "";
+            if (typeof value !== "string")
+                throw new Error("image_gen.fallback_model must be a string");
+            const ref = parseModelRef(value);
+            if (!ref)
+                throw new Error("image_gen.fallback_model: format must be provider/model-id");
+            return ref.key;
+        },
+        write: (config, value) => {
+            if (value == null || value === "") {
+                config.imageGen.fallbackModel = undefined;
+                return;
+            }
+            const ref = parseModelRef(value);
+            if (!ref)
+                return;
+            config.imageGen.fallbackModel = ref.key;
+        },
+    },
+    "memory.lcm.enabled": {
+        read: (config) => config.memory.lcm.enabled,
+        validate: (value) => requireBoolean(value, "memory.lcm.enabled"),
+        write: (config, value) => {
+            config.memory.lcm.enabled = value;
+        },
+    },
+    "memory.lcm.model": {
+        read: (config) => config.memory.lcm.model,
+        validate: (value, config) => {
+            if (typeof value !== "string")
+                throw new Error("memory.lcm.model must be a string");
+            const ref = parseModelRef(value);
+            if (!ref)
+                throw new Error("memory.lcm.model: format must be provider/model-id");
+            if (!isAllowedModel(config, ref))
+                throw new Error(`memory.lcm.model is not allowlisted: ${ref.key}`);
+            return ref.key;
+        },
+        write: (config, value) => {
+            const ref = parseModelRef(value);
+            if (!ref)
+                return;
+            config.memory.lcm.model = ref.key;
+            config.memory.lcm.provider = ref.provider;
+            config.memory.lcm.modelId = ref.id;
+            config.memory.lcm.baseUrl = resolveProviderSetting(config.models.baseUrls, ref.provider, ref.id);
+            config.memory.lcm.apiKeyEnv = resolveProviderSetting(config.models.apiKeyEnvs, ref.provider, ref.id);
+        },
+    },
+    "memory.lcm.contextThreshold": {
+        read: (config) => config.memory.lcm.contextThreshold,
+        validate: (value) => requireNumberInRange(value, "memory.lcm.contextThreshold", 0, 1),
+        write: (config, value) => {
+            config.memory.lcm.contextThreshold = value;
+        },
+    },
+    "memory.lcm.freshTailCount": {
+        read: (config) => config.memory.lcm.freshTailCount,
+        validate: (value) => requirePositiveInt(value, "memory.lcm.freshTailCount"),
+        write: (config, value) => {
+            config.memory.lcm.freshTailCount = value;
+        },
+    },
+    "memory.lcm.leafChunkTokens": {
+        read: (config) => config.memory.lcm.leafChunkTokens,
+        validate: (value) => requirePositiveInt(value, "memory.lcm.leafChunkTokens"),
+        write: (config, value) => {
+            config.memory.lcm.leafChunkTokens = value;
+        },
+    },
+    "memory.lcm.leafTargetTokens": {
+        read: (config) => config.memory.lcm.leafTargetTokens,
+        validate: (value) => requirePositiveInt(value, "memory.lcm.leafTargetTokens"),
+        write: (config, value) => {
+            config.memory.lcm.leafTargetTokens = value;
+        },
+    },
+    "memory.lcm.condenseGroupSize": {
+        read: (config) => config.memory.lcm.condenseGroupSize,
+        validate: (value) => requirePositiveInt(value, "memory.lcm.condenseGroupSize"),
+        write: (config, value) => {
+            config.memory.lcm.condenseGroupSize = value;
+        },
+    },
+    "memory.lcm.maxSummaryDepth": {
+        read: (config) => config.memory.lcm.maxSummaryDepth,
+        validate: (value) => requirePositiveInt(value, "memory.lcm.maxSummaryDepth"),
+        write: (config, value) => {
+            config.memory.lcm.maxSummaryDepth = value;
+        },
+    },
+    "memory.lcm.newSessionRetainDepth": {
+        read: (config) => config.memory.lcm.newSessionRetainDepth,
+        validate: (value) => requireInt(value, "memory.lcm.newSessionRetainDepth", -1),
+        write: (config, value) => {
+            config.memory.lcm.newSessionRetainDepth = value;
+        },
+    },
+    "memory.ambient.enabled": {
+        read: (config) => config.memory.ambient.enabled,
+        validate: (value) => requireBoolean(value, "memory.ambient.enabled"),
+        write: (config, value) => {
+            config.memory.ambient.enabled = value;
+        },
+    },
+    "memory.ambient.topK": {
+        read: (config) => config.memory.ambient.topK,
+        validate: (value) => requirePositiveInt(value, "memory.ambient.topK"),
+        write: (config, value) => {
+            config.memory.ambient.topK = value;
+        },
+    },
+    "memory.ambient.minQueryLength": {
+        read: (config) => config.memory.ambient.minQueryLength,
+        validate: (value) => requireNonNegativeInt(value, "memory.ambient.minQueryLength"),
+        write: (config, value) => {
+            config.memory.ambient.minQueryLength = value;
+        },
+    },
+    "memory.ambient.throttleSeconds": {
+        read: (config) => config.memory.ambient.throttleSeconds,
+        validate: (value) => requireNonNegativeInt(value, "memory.ambient.throttleSeconds"),
+        write: (config, value) => {
+            config.memory.ambient.throttleSeconds = value;
+        },
+    },
+    "memory.ambient.weightSimilarity": {
+        read: (config) => config.memory.ambient.weightSimilarity,
+        validate: (value) => requireNonNegativeNumber(value, "memory.ambient.weightSimilarity"),
+        write: (config, value) => {
+            config.memory.ambient.weightSimilarity = value;
+        },
+    },
+    "memory.ambient.weightValence": {
+        read: (config) => config.memory.ambient.weightValence,
+        validate: (value) => requireNonNegativeNumber(value, "memory.ambient.weightValence"),
+        write: (config, value) => {
+            config.memory.ambient.weightValence = value;
+        },
+    },
+    "memory.ambient.weightRecency": {
+        read: (config) => config.memory.ambient.weightRecency,
+        validate: (value) => requireNonNegativeNumber(value, "memory.ambient.weightRecency"),
+        write: (config, value) => {
+            config.memory.ambient.weightRecency = value;
+        },
+    },
+    "memory.ambient.weightIntensity": {
+        read: (config) => config.memory.ambient.weightIntensity,
+        validate: (value) => requireNonNegativeNumber(value, "memory.ambient.weightIntensity"),
+        write: (config, value) => {
+            config.memory.ambient.weightIntensity = value;
+        },
+    },
+};
+export const CONFIG_KEYS = Object.keys(CONFIG_REGISTRY);
+export function isConfigKey(value) {
+    return typeof value === "string" && value in CONFIG_REGISTRY;
+}
+const defaultSnapshot = new Map();
+export function snapshotConfigDefaults(config) {
+    defaultSnapshot.clear();
+    for (const key of CONFIG_KEYS) {
+        defaultSnapshot.set(key, CONFIG_REGISTRY[key].read(config));
+    }
+}
+export function getConfigDefault(key) {
+    return defaultSnapshot.get(key);
+}
+export function applyConfigOverridesToConfig(config) {
+    snapshotConfigDefaults(config);
+    const overrides = loadConfigOverrides();
+    for (const [key, value] of Object.entries(overrides)) {
+        if (!isConfigKey(key))
+            continue;
+        const entry = CONFIG_REGISTRY[key];
+        try {
+            const validated = entry.validate(value, config);
+            entry.write(config, validated);
+        }
+        catch (error) {
+            console.warn(`Skipping invalid config override ${key}:`, error);
+        }
+    }
+}

package/dist/config.js

@@ -340,140 +340,17 @@ function readCronJobs(cron) {
         };
     });
 }
-function readBrowserAllowedSites(browser) {
-    const rawSites = browser.sites;
-    if (rawSites === undefined)
-        return defaultBrowserAllowedSites();
-    if (!rawSites || typeof rawSites !== "object" || Array.isArray(rawSites)) {
-        throw new Error("Config value browser.sites must be a table");
-    }
-    const sites = {};
-    for (const [siteName, rawSite] of Object.entries(rawSites)) {
-        if (!rawSite || typeof rawSite !== "object" || Array.isArray(rawSite)) {
-            throw new Error(`Config value browser.sites.${siteName} must be a table`);
-        }
-        const site = rawSite;
-        assertKnownKeys(site, `browser.sites.${siteName}`, ["read", "write"]);
-        const read = readStringArray(site.read, `browser.sites.${siteName}.read`);
-        const write = readStringArray(site.write, `browser.sites.${siteName}.write`);
-        sites[siteName] = { read, write };
-    }
-    return sites;
-}
 function defaultBrowserAllowedSites() {
     return {
-        twitter: {
-            read: [
-                "article",
-                "bookmark-folders",
-                "bookmarks",
-                "following",
-                "likes",
-                "list-tweets",
-                "lists",
-                "notifications",
-                "profile",
-                "search",
-                "thread",
-                "timeline",
-                "trending",
-                "tweets",
-            ],
-            write: [],
-        },
-        xiaohongshu: {
-            read: [
-                "comments",
-                "creator-note-detail",
-                "creator-notes",
-                "creator-notes-summary",
-                "creator-profile",
-                "creator-stats",
-                "feed",
-                "note",
-                "notifications",
-                "search",
-                "user",
-            ],
-            write: [],
-        },
-        rednote: {
-            read: ["comments", "feed", "note", "notifications", "search", "user"],
-            write: [],
-        },
-        reddit: {
-            read: [
-                "frontpage",
-                "home",
-                "hot",
-                "popular",
-                "read",
-                "saved",
-                "search",
-                "subreddit",
-                "subreddit-info",
-                "upvoted",
-                "user",
-                "user-comments",
-                "user-posts",
-                "whoami",
-            ],
-            write: [],
-        },
-        bilibili: {
-            read: [
-                "comments",
-                "dynamic",
-                "feed",
-                "following",
-                "history",
-                "hot",
-                "me",
-                "ranking",
-                "search",
-                "subtitle",
-                "user-videos",
-                "video",
-            ],
-            write: [],
-        },
-        youtube: {
-            read: [
-                "channel",
-                "comments",
-                "feed",
-                "history",
-                "playlist",
-                "search",
-                "subscriptions",
-                "transcript",
-                "video",
-                "watch-later",
-            ],
-            write: [],
-        },
-        tiktok: {
-            read: ["explore", "friends", "live", "notifications", "profile", "search", "user"],
-            write: [],
-        },
-        douyin: {
-            read: [
-                "activities",
-                "collections",
-                "drafts",
-                "hashtag",
-                "location",
-                "profile",
-                "stats",
-                "user-videos",
-                "videos",
-            ],
-            write: [],
-        },
-        spotify: {
-            read: ["search", "status"],
-            write: [],
-        },
+        twitter: true,
+        xiaohongshu: true,
+        rednote: true,
+        reddit: true,
+        bilibili: true,
+        youtube: true,
+        tiktok: true,
+        douyin: true,
+        spotify: true,
     };
 }
 export async function loadConfig(workspacePathInput) {
@@ -506,6 +383,18 @@ export async function loadConfig(workspacePathInput) {
     const persona = (parsed.persona ?? {});
     const workspace = (parsed.workspace ?? {});
     const memory = (parsed.memory ?? {});
+    assertKnownKeys(browser, "browser", [
+        "enabled",
+        "backend",
+        "opencli_command",
+        "harness_command",
+        "session",
+        "profile",
+        "window",
+        "timeout_ms",
+        "max_output_chars",
+        "read_write",
+    ]);
     const memoryEmbedding = (memory.embedding ?? {});
     const memoryAmbient = (memory.ambient ?? {});
     const memoryLcm = (memory.lcm ?? {});
@@ -644,7 +533,7 @@ export async function loadConfig(workspacePathInput) {
             timeoutMs: readInteger(browser.timeout_ms, 60_000, "browser.timeout_ms", 1),
             maxOutputChars: readInteger(browser.max_output_chars, 12_000, "browser.max_output_chars", 1000),
             readWrite: readBoolean(browser.read_write, false, "browser.read_write"),
-            allowedSites: readBrowserAllowedSites(browser),
+            allowedSites: defaultBrowserAllowedSites(),
         },
         agent: {
             model: agentModel,
@@ -710,6 +599,7 @@ export async function loadConfig(workspacePathInput) {
         persona: {
             soul: resolveWorkspacePath(workspacePath, readOptionalString(persona.soul, "SOUL.md")),
             user: resolveWorkspacePath(workspacePath, readOptionalString(persona.user, "USER.md")),
+            contact: resolveWorkspacePath(workspacePath, readOptionalString(persona.contact, "CONTACT.md")),
             memory: resolveWorkspacePath(workspacePath, readOptionalString(persona.memory, "MEMORY.md")),
             inner: resolveWorkspacePath(workspacePath, readOptionalString(persona.inner, "INNER.md")),
         },

package/dist/contact-note.js

@@ -0,0 +1,41 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+let contactNotePath = resolve(process.cwd(), "CONTACT.md");
+let cachedNickname = null;
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+export function setContactNotePath(path) {
+    contactNotePath = path;
+    cachedNickname = null;
+}
+export async function loadContactNote() {
+    try {
+        return await readFile(contactNotePath, "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return null;
+        throw error;
+    }
+}
+export function parseContactNickname(raw, fallback) {
+    let remaining = raw?.trim() ?? "";
+    while (remaining.startsWith("<!--")) {
+        const end = remaining.indexOf("-->");
+        if (end === -1)
+            return fallback;
+        remaining = remaining.slice(end + 3).trim();
+    }
+    const firstLine = remaining
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line && !line.startsWith("<!--"));
+    return firstLine ?? fallback;
+}
+export async function refreshContactNote() {
+    cachedNickname = parseContactNickname(await loadContactNote(), "");
+}
+export function getContactNickname(fallback) {
+    return cachedNickname || fallback;
+}

package/dist/discord.js

@@ -625,7 +625,7 @@ export async function startDiscordDaemon(config, familiarAgent, settings, memory
     let heartbeatQueued = false;
     let cronRunning = false;
     let schedulerState = { cron: {} };
-    const promptForRuntime = async (runtime, jobId, prompt, attachments = [], onEvent) => {
+    const promptForRuntime = async (runtime, jobId, prompt, attachments = [], onEvent, onTurnEnd) => {
         const run = agentWorkQueue.then(async () => {
             if (!runtime.hasActiveJob(jobId))
                 throw canceledJobError();
@@ -635,6 +635,7 @@ export async function startDiscordDaemon(config, familiarAgent, settings, memory
                 const input = [prompt, promptImages.promptSuffix].filter(Boolean).join("\n");
                 const reply = await familiarAgent.prompt(runtime.channelKey, input, promptImages.images, onEvent, {
                     referenceAttachments: attachments,
+                    onTurnEnd,
                 });
                 if (!runtime.hasActiveJob(jobId))
                     throw canceledJobError();
@@ -1170,12 +1171,21 @@ export async function startDiscordDaemon(config, familiarAgent, settings, memory
         console.warn("Discord websocket closed; discord.js will reconnect when possible", event);
     });
     schedulerState = await loadSchedulerState(config.workspace.dataDir);
+    const tickHeartbeat = () => {
+        void runHeartbeat().catch((error) => console.error("Heartbeat tick failed", error));
+    };
+    const rearmHeartbeat = () => {
+        if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = undefined;
+        }
+        if (config.heartbeat.enabled) {
+            heartbeatTimer = setInterval(tickHeartbeat, Math.min(config.heartbeat.intervalMs, 60_000));
+        }
+    };
     if (config.heartbeat.enabled) {
         await initializeHeartbeatState((await getOwnerDmSession()).runtime);
-        const tickHeartbeat = () => {
-            void runHeartbeat().catch((error) => console.error("Heartbeat tick failed", error));
-        };
-        heartbeatTimer = setInterval(tickHeartbeat, Math.min(config.heartbeat.intervalMs, 60_000));
+        rearmHeartbeat();
         tickHeartbeat();
     }
     if (config.cron.enabled && config.cron.jobs.some((job) => job.enabled)) {
@@ -1191,12 +1201,12 @@ export async function startDiscordDaemon(config, familiarAgent, settings, memory
         getRuntimeForWebChannel,
         runPromptForWeb: promptForRuntime,
         abortWebRuntime(runtime) {
-            if (runtime.hasActiveJob() && activeAgentOwner === runtime.channelKey)
-                familiarAgent.abort(runtime.channelKey);
+            familiarAgent.requestSoftStop(runtime.channelKey);
         },
         getActiveRuntimeKey() {
             return activeAgentOwner;
         },
+        rearmHeartbeat,
         async stop() {
             client.off(Events.MessageCreate, onMessageCreate);
             client.off(Events.InteractionCreate, onInteractionCreate);

package/dist/hot-reload.js

@@ -1,7 +1,17 @@
 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"]);
+import { refreshContactNote } from "./contact-note.js";
+const ROOT_FILES = new Set([
+    "config.toml",
+    ".env",
+    "SOUL.md",
+    "USER.md",
+    "CONTACT.md",
+    "MEMORY.md",
+    "INNER.md",
+    "HEARTBEAT.md",
+]);
 const SKILLS_DIR = "skills";
 function isEnoent(error) {
     return !!error && typeof error === "object" && error.code === "ENOENT";
@@ -94,7 +104,21 @@ export function startWorkspaceHotReload(options) {
                 if (!filename ||
                     shouldReloadForPath(workspacePath, changedPath) ||
                     shouldReloadForPath(workspacePath, dirPath)) {
-                    scheduleReload(relative(workspacePath, changedPath) || relative(workspacePath, dirPath) || ".");
+                    const reason = relative(workspacePath, changedPath) || relative(workspacePath, dirPath) || ".";
+                    if (reason === "CONTACT.md") {
+                        reloadQueue = reloadQueue.then(async () => {
+                            try {
+                                await refreshContactNote();
+                                logger.info(`contact note refresh complete after ${reason}`);
+                            }
+                            catch (error) {
+                                logger.error("contact note refresh failed", error);
+                            }
+                        });
+                    }
+                    else {
+                        scheduleReload(reason);
+                    }
                 }
             });
             watcher.on("error", (error) => {

package/dist/memory/lcm/context-transformer.js

@@ -599,8 +599,13 @@ function lcmRecordPartsFromAgentMessage(message) {
         return [];
     const parts = [];
     for (const item of content) {
-        if (item.type === "text")
-            parts.push({ kind: "text", text: item.text });
+        if (item.type === "text") {
+            parts.push({
+                kind: "text",
+                text: item.text,
+                ...(item.textSignature ? { signature: item.textSignature } : {}),
+            });
+        }
         else if (item.type === "thinking") {
             parts.push({
                 kind: "thinking",
@@ -609,7 +614,13 @@ function lcmRecordPartsFromAgentMessage(message) {
             });
         }
         else if (item.type === "toolCall") {
-            parts.push({ kind: "tool_call", toolCallId: item.id, toolName: item.name, arguments: item.arguments });
+            parts.push({
+                kind: "tool_call",
+                toolCallId: item.id,
+                toolName: item.name,
+                arguments: item.arguments,
+                ...(item.thoughtSignature ? { signature: item.thoughtSignature } : {}),
+            });
         }
         else if (item.type === "image") {
             parts.push({ kind: "text", text: `[image: ${item.mimeType}]` });