@qearlyao/familiar 0.2.4 → 0.3.0

package/dist/config.js

@@ -1,8 +1,13 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { resolve } from "node:path";
 import { parse } from "smol-toml";
-import { parseModelRef, resolveProviderSetting } from "./models.js";
+import { BROWSER_BACKENDS, BROWSER_WINDOW_MODES, CACHE_RETENTIONS, DISCORD_CHANNEL_TRIGGERS, DISCORD_CHUNK_MODES, DISCORD_DISPATCH_MODES, DISCORD_REPLY_MODES, IMAGE_GEN_APIS, MEDIA_UNDERSTANDING_PROVIDERS, MEMORY_EMBEDDING_FORMATS, THINKING_LEVELS, TTS_PROVIDERS, WEB_AUTH_MODES, } from "./config/enums.js";
+import { interpolateValue } from "./config/interpolate.js";
+import { maybeParseProviderModelRef, parseProviderModelRef } from "./config/model-refs.js";
+import { assertKnownKeys, readBoolean, readConfigString, readFraction, readInteger, readIntegerInRange, readNumberInRange, readOptionalConfigString, readOptionalInteger, readOptionalString, readPositiveNumber, readString, readStringArray, readStringRecord, resolveWorkspacePath, } from "./config/readers.js";
+import { defaultBrowserAllowedSites, readCronJobs, readPromptOverrides } from "./config/sections.js";
+import { resolveProviderSetting } from "./models.js";
 import { readEnum } from "./util/guards.js";
 const loggedConfigWarnings = new Set();
 const DEFAULT_MEMORY_EMBEDDING_BASE_URLS = {
@@ -11,280 +16,12 @@ const DEFAULT_MEMORY_EMBEDDING_BASE_URLS = {
 const DEFAULT_MEMORY_EMBEDDING_API_KEY_ENVS = {
     google: "GEMINI_API_KEY",
 };
-function interpolateEnv(value) {
-    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_match, name, fallback) => {
-        return process.env[name] ?? fallback ?? "";
-    });
-}
-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;
-}
-function readString(value, path) {
-    if (typeof value !== "string" || value.trim() === "") {
-        throw new Error(`Missing required config value: ${path}`);
-    }
-    return value;
-}
-function readOptionalString(value, fallback) {
-    return typeof value === "string" && value.trim() !== "" ? value : fallback;
-}
-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;
-}
-function readConfigString(value, fallback, path) {
-    const read = readOptionalConfigString(value, path);
-    return read ?? fallback;
-}
-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;
-}
-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);
-}
 function warnOnce(key, message) {
     if (loggedConfigWarnings.has(key))
         return;
     loggedConfigWarnings.add(key);
     console.warn(message);
 }
-const CACHE_RETENTIONS = ["none", "short", "long"];
-const THINKING_LEVELS = [
-    "off",
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-];
-const DISCORD_REPLY_MODES = ["plain", "reply"];
-const DISCORD_CHUNK_MODES = ["simple", "paragraph", "newline"];
-const DISCORD_DISPATCH_MODES = ["steer", "queue", "collect"];
-const DISCORD_CHANNEL_TRIGGERS = ["mention", "always"];
-const CRON_FREQUENCIES = ["once", "hourly", "daily", "weekly", "monthly"];
-const CRON_DELIVERY_MODES = ["queue", "follow_up"];
-const WEB_AUTH_MODES = ["tailscale-only", "bearer", "public-2fa"];
-const TTS_PROVIDERS = ["elevenlabs"];
-const IMAGE_GEN_APIS = ["openrouter-images"];
-const MEDIA_UNDERSTANDING_PROVIDERS = ["groq", "google"];
-const MEMORY_EMBEDDING_FORMATS = ["gemini", "openai", "voyage"];
-const BROWSER_BACKENDS = ["opencli", "browser-harness"];
-const BROWSER_WINDOW_MODES = ["foreground", "background"];
-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`);
-}
-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;
-}
-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;
-}
-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;
-}
-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;
-}
-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;
-}
-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;
-}
-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;
-}
-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`);
-}
-function resolveWorkspacePath(workspacePath, filePath) {
-    return isAbsolute(filePath) ? filePath : resolve(workspacePath, filePath);
-}
-function parseProviderModelRef(value, path) {
-    const parsed = maybeParseProviderModelRef(value);
-    if (parsed)
-        return parsed;
-    throw new Error(`Config value ${path} must be a provider/model id`);
-}
-function maybeParseProviderModelRef(value) {
-    const parsed = parseModelRef(value);
-    return parsed ? { provider: parsed.provider, modelId: parsed.id, key: parsed.key } : undefined;
-}
-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}`);
-    }
-}
-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) } : {}),
-    };
-}
-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) } : {}),
-        };
-    });
-}
-function defaultBrowserAllowedSites() {
-    return {
-        twitter: true,
-        xiaohongshu: true,
-        rednote: true,
-        reddit: true,
-        bilibili: true,
-        youtube: true,
-        tiktok: true,
-        douyin: true,
-        spotify: true,
-    };
-}
 export async function loadConfig(workspacePathInput) {
     const workspacePath = resolve(workspacePathInput);
     const configPath = resolve(workspacePath, "config.toml");
@@ -436,7 +173,7 @@ export async function loadConfig(workspacePathInput) {
     return {
         workspacePath,
         discord: {
-            token: readString(process.env.DISCORD_TOKEN, "DISCORD_TOKEN"),
+            token: readOptionalConfigString(process.env.DISCORD_TOKEN, "DISCORD_TOKEN"),
             ownerId,
             allowedChannels: readStringArray(discord.allowed_channels, "discord.allowed_channels"),
             replyMode: readEnum(readOptionalString(discord.reply_mode, "plain"), "discord.reply_mode", DISCORD_REPLY_MODES),

package/dist/discord/channel.js

@@ -0,0 +1,32 @@
+import { ChannelType } from "discord.js";
+import { chatChannelKey } from "../chat-log.js";
+export function buildChannelRef(channel, channelId) {
+    const scope = channel.type === ChannelType.DM ? "dm" : channel.isThread() ? "thread" : "channel";
+    const channelName = "name" in channel ? channel.name : undefined;
+    return {
+        service: "discord",
+        scope,
+        channelId,
+        channelName: typeof channelName === "string" ? channelName : undefined,
+        threadId: channel.isThread() ? channel.id : undefined,
+    };
+}
+export function getChannelRef(message) {
+    return buildChannelRef(message.channel, message.channelId);
+}
+export function runtimeKeyFromMessage(message) {
+    return chatChannelKey(getChannelRef(message));
+}
+export function isDmChannel(channel) {
+    return channel?.type === ChannelType.DM;
+}
+export async function fetchMessageAnchor(message, messageId) {
+    if (!messageId || message.id === messageId)
+        return message;
+    return message.channel.messages.fetch(messageId).catch(() => message);
+}
+export function messageMentionsBot(message, botUserId) {
+    if (message.mentions.users.has(botUserId))
+        return true;
+    return message.content.includes(`<@${botUserId}>`) || message.content.includes(`<@!${botUserId}>`);
+}

package/dist/discord/chunking.js

@@ -0,0 +1,163 @@
+// A hard split at an arbitrary index can land between the two UTF-16 code units
+// of an astral character (emoji, rare CJK), rendering as a broken � at the seam.
+// Back off by one so the whole surrogate pair moves to the next chunk. Splits at
+// whitespace land on a space and are unaffected.
+function avoidSurrogateSplit(text, index) {
+    if (index <= 0 || index >= text.length)
+        return index;
+    const high = text.charCodeAt(index - 1);
+    const low = text.charCodeAt(index);
+    if (high >= 0xd800 && high <= 0xdbff && low >= 0xdc00 && low <= 0xdfff)
+        return index - 1;
+    return index;
+}
+function chunkDiscordSimple(text, limit = 2000) {
+    if (text.length <= limit)
+        return [text || "(empty response)"];
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= limit) {
+            chunks.push(remaining);
+            break;
+        }
+        const breakpoint = Math.max(remaining.lastIndexOf("\n", limit), remaining.lastIndexOf(" ", limit));
+        const splitAt = breakpoint > 0 ? breakpoint : avoidSurrogateSplit(remaining, limit);
+        chunks.push(remaining.slice(0, splitAt));
+        remaining = remaining.slice(splitAt).trimStart();
+    }
+    return chunks;
+}
+function splitLongBlock(block, limit) {
+    if (block.length <= limit)
+        return [block];
+    const pieces = [];
+    let lineCurrent = "";
+    for (const line of block.split("\n")) {
+        const candidate = lineCurrent ? `${lineCurrent}\n${line}` : line;
+        if (candidate.length <= limit) {
+            lineCurrent = candidate;
+            continue;
+        }
+        if (lineCurrent) {
+            pieces.push(lineCurrent);
+            lineCurrent = "";
+        }
+        if (line.length <= limit) {
+            lineCurrent = line;
+            continue;
+        }
+        let remaining = line;
+        while (remaining.length > limit) {
+            let splitAt = remaining.lastIndexOf(" ", limit);
+            if (splitAt < Math.floor(limit * 0.6))
+                splitAt = avoidSurrogateSplit(remaining, limit);
+            pieces.push(remaining.slice(0, splitAt));
+            remaining = remaining.slice(splitAt).trimStart();
+        }
+        lineCurrent = remaining;
+    }
+    if (lineCurrent)
+        pieces.push(lineCurrent);
+    return pieces;
+}
+function chunkDiscordParagraph(text, limit = 2000) {
+    if (text.length <= limit)
+        return [text || "(empty response)"];
+    const normalized = text.replace(/\r\n/g, "\n");
+    const paragraphs = normalized.split(/\n\n+/);
+    const chunks = [];
+    let current = "";
+    const pushCurrent = () => {
+        if (current.trim())
+            chunks.push(current);
+        current = "";
+    };
+    for (const paragraph of paragraphs) {
+        if (!paragraph)
+            continue;
+        for (const part of splitLongBlock(paragraph, limit)) {
+            const candidate = current ? `${current}\n\n${part}` : part;
+            if (candidate.length <= limit) {
+                current = candidate;
+            }
+            else {
+                pushCurrent();
+                current = part;
+            }
+        }
+    }
+    pushCurrent();
+    return chunks.length > 0 ? chunks : [normalized.slice(0, limit)];
+}
+function splitPreservingCodeFences(text) {
+    const normalized = text.replace(/\r\n/g, "\n");
+    const segments = [];
+    const fence = /```/g;
+    let cursor = 0;
+    let inCode = false;
+    let buffer = "";
+    const flushParagraphs = (slab) => {
+        const parts = slab.split(/\n\n+/);
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (i === 0) {
+                buffer += part;
+            }
+            else {
+                if (buffer.trim())
+                    segments.push(buffer);
+                buffer = part;
+            }
+        }
+    };
+    let match;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex iteration
+    while ((match = fence.exec(normalized)) !== null) {
+        const slab = normalized.slice(cursor, match.index);
+        if (inCode) {
+            buffer += slab + match[0];
+            inCode = false;
+        }
+        else {
+            flushParagraphs(slab);
+            buffer += match[0];
+            inCode = true;
+        }
+        cursor = match.index + match[0].length;
+    }
+    const tail = normalized.slice(cursor);
+    if (inCode) {
+        buffer += tail;
+    }
+    else {
+        flushParagraphs(tail);
+    }
+    if (buffer.trim())
+        segments.push(buffer);
+    return segments.map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+}
+function chunkDiscordNewline(text, limit = 2000) {
+    const segments = splitPreservingCodeFences(text);
+    if (segments.length === 0)
+        return [];
+    const chunks = [];
+    for (const segment of segments) {
+        if (segment.length <= limit) {
+            chunks.push(segment);
+            continue;
+        }
+        for (const part of splitLongBlock(segment, limit)) {
+            if (part.trim())
+                chunks.push(part);
+        }
+    }
+    return chunks;
+}
+export function chunkDiscord(config, text) {
+    if (config.discord.chunkMode === "simple")
+        return chunkDiscordSimple(text);
+    if (config.discord.chunkMode === "newline")
+        return chunkDiscordNewline(text);
+    return chunkDiscordParagraph(text);
+}

package/dist/discord/client.js

@@ -0,0 +1,44 @@
+import { once } from "node:events";
+import { ChannelType, Client, Events, GatewayIntentBits, Partials } from "discord.js";
+export async function withReadyClient(token) {
+    const client = new Client({
+        intents: [
+            GatewayIntentBits.Guilds,
+            GatewayIntentBits.GuildMessages,
+            GatewayIntentBits.DirectMessages,
+            GatewayIntentBits.MessageContent,
+        ],
+        partials: [Partials.Channel],
+    });
+    const readyPromise = once(client, Events.ClientReady);
+    try {
+        await client.login(token);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("Used disallowed intents")) {
+            throw new Error('Discord rejected the configured gateway intents. Enable the "Message Content Intent" in the Discord Developer Portal.');
+        }
+        throw error;
+    }
+    if (!client.isReady()) {
+        await Promise.race([
+            readyPromise,
+            new Promise((_, reject) => setTimeout(() => reject(new Error("Discord client failed to become ready")), 10000)),
+        ]);
+    }
+    if (!client.isReady())
+        throw new Error("Discord client failed to become ready");
+    return client;
+}
+export function isAllowedMessage(config, message, botUserId) {
+    if (message.author.id === botUserId)
+        return false;
+    if (message.author.bot && !config.discord.allowBotMessages)
+        return false;
+    if (message.channel.type === ChannelType.DM && message.author.id !== config.discord.ownerId)
+        return false;
+    if (message.channel.type === ChannelType.DM)
+        return true;
+    return config.discord.allowedChannels.includes(message.channelId);
+}