@qearlyao/familiar 0.2.5 → 0.4.0

package/dist/web/daemon.js

@@ -0,0 +1,108 @@
+import { createServer } from "node:http";
+import { refreshContactNote, setContactNotePath } from "../conversation/contact-note.js";
+import { setAddedModelsPath } from "../models/added-models.js";
+import { loadPersona, parsePersonaName } from "../prompting/persona.js";
+import { registerWebAgentRoutes } from "./agent-routes.js";
+import { createAuth, loadWebSessionStore } from "./auth.js";
+import { registerWebAuthRoutes } from "./auth-routes.js";
+import { registerWebConfigRoutes } from "./config-routes.js";
+import { registerWebConversationRoutes } from "./conversation-routes.js";
+import { registerWebDiaryRoutes } from "./diary-routes.js";
+import { createWebEventHub } from "./event-hub.js";
+import { HttpError, sendText } from "./http.js";
+import { createWebRouteRegistry } from "./routes.js";
+import { createWebRuntimeActions } from "./runtime-actions.js";
+import { serveStatic } from "./static.js";
+import { attachWebSocketStream } from "./stream.js";
+export async function startWebDaemon(config, familiarAgent, agentCore, options = {}) {
+    setAddedModelsPath(config.workspace.dataDir);
+    setContactNotePath(config.persona.contact);
+    await refreshContactNote();
+    const persona = await loadPersona(config);
+    const personaName = parsePersonaName(persona.soul);
+    const webSessions = await loadWebSessionStore(config);
+    const auth = createAuth(config, webSessions);
+    const eventHub = createWebEventHub(config, personaName);
+    const getRuntime = async (channelKey) => {
+        if (!agentCore.hasSessionSource())
+            throw new HttpError(503, "Owner identity is not established yet.");
+        const runtime = await agentCore.getRuntimeForWebChannel(channelKey);
+        eventHub.subscribeRuntime(runtime);
+        return runtime;
+    };
+    const subscribeKnownRuntimes = async () => {
+        if (!agentCore.hasSessionSource())
+            return;
+        const sessions = await agentCore.getWebSessions();
+        await Promise.all(sessions.map(async (session) => {
+            const runtime = await agentCore.getRuntimeForWebChannel(session.key);
+            eventHub.subscribeRuntime(runtime);
+        }));
+    };
+    const { route, handleApi } = createWebRouteRegistry(config, auth);
+    const actions = createWebRuntimeActions({
+        config,
+        familiarAgent,
+        agentCore,
+        eventHub,
+        personaName,
+        restart: options.restart,
+    });
+    registerWebAuthRoutes(route, auth, { authMode: config.web.authMode, personaName });
+    registerWebConversationRoutes({
+        route,
+        config,
+        auth,
+        authMode: config.web.authMode,
+        agentCore,
+        getRuntime,
+        personaName,
+        actions,
+    });
+    registerWebAgentRoutes({
+        route,
+        config,
+        familiarAgent,
+        getRuntime,
+        personaName,
+        publish: eventHub.publish,
+    });
+    registerWebConfigRoutes(route, config, agentCore);
+    registerWebDiaryRoutes(route, config);
+    await subscribeKnownRuntimes();
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+        void handleApi(request, response, url).then(async (handled) => {
+            if (handled)
+                return;
+            if (await serveStatic(response, url.pathname))
+                return;
+            sendText(response, 404, "Not found");
+        });
+    });
+    attachWebSocketStream(server, {
+        authorize: (request, pathname) => auth.authorize(request, pathname),
+        eventHub,
+        getRuntime,
+        abort: (runtime) => familiarAgent.abort(runtime.channelKey),
+        retry: actions.retryLatestAssistant,
+        deleteLatest: actions.deleteLatestAssistant,
+    });
+    await new Promise((resolveListen, rejectListen) => {
+        server.once("error", rejectListen);
+        server.listen(config.web.port, config.web.bindAddress, () => {
+            server.off("error", rejectListen);
+            resolveListen();
+        });
+    });
+    console.log(`Web side-door listening on http://${config.web.bindAddress}:${config.web.port}`);
+    return {
+        server,
+        async stop() {
+            eventHub.stop();
+            await new Promise((resolveClose, rejectClose) => {
+                server.close((error) => (error ? rejectClose(error) : resolveClose()));
+            });
+        },
+    };
+}

package/dist/web/diary-routes.js

@@ -0,0 +1,88 @@
+import { readFile, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { DIARY_INDEX_FILE_RE, listDiaryMarkdownFiles } from "../memory/diary/indexer.js";
+import { isEnoent } from "../util/fs.js";
+import { HttpError, sendJson } from "./http.js";
+const FRONTMATTER_RE = /^\s*---\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$)/;
+const HEADING_RE = /^#{1,6}\s+(.+?)\s*$/m;
+const DIARY_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export function registerWebDiaryRoutes(route, config) {
+    route("GET", "/api/web/diaries", async (_request, response) => {
+        sendJson(response, 200, { diaries: await listWebDiaries(config) });
+    });
+    route("GET", "/api/web/diary", async (_request, response, url) => {
+        const date = url.searchParams.get("date") ?? "";
+        sendJson(response, 200, { diary: await readWebDiary(config, date) });
+    });
+}
+export async function listWebDiaries(config) {
+    const paths = await listDiaryMarkdownFiles(config);
+    const summaries = await Promise.all(paths.map(async (path) => toDiarySummary(await readDiaryPayload(path))));
+    return summaries.sort((a, b) => b.date.localeCompare(a.date));
+}
+export async function readWebDiary(config, date) {
+    if (!DIARY_DATE_RE.test(date))
+        throw new HttpError(400, "diary date must be YYYY-MM-DD");
+    const path = resolve(config.memory.diariesDir, `${date}.md`);
+    try {
+        return await readDiaryPayload(path);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            throw new HttpError(404, "diary not found");
+        throw error;
+    }
+}
+async function readDiaryPayload(path) {
+    const sourceId = basename(path);
+    if (!DIARY_INDEX_FILE_RE.test(sourceId)) {
+        throw new HttpError(400, "diary file must be named YYYY-MM-DD.md");
+    }
+    const fileStat = await stat(path);
+    if (!fileStat.isFile())
+        throw new HttpError(404, "diary not found");
+    const markdown = await readFile(path, "utf8");
+    const content = stripFrontmatter(markdown).trim();
+    const date = sourceId.slice(0, -".md".length);
+    return {
+        date,
+        sourceId,
+        title: diaryTitle(content, date),
+        excerpt: diaryExcerpt(content),
+        mtimeMs: Math.floor(fileStat.mtimeMs),
+        sizeBytes: fileStat.size,
+        content,
+    };
+}
+function stripFrontmatter(markdown) {
+    return markdown.replace(FRONTMATTER_RE, "");
+}
+function toDiarySummary(entry) {
+    return {
+        date: entry.date,
+        sourceId: entry.sourceId,
+        title: entry.title,
+        excerpt: entry.excerpt,
+        mtimeMs: entry.mtimeMs,
+        sizeBytes: entry.sizeBytes,
+    };
+}
+function diaryTitle(content, date) {
+    return stripInlineMarkdown(HEADING_RE.exec(content)?.[1]?.trim() || date);
+}
+function diaryExcerpt(content) {
+    const body = content
+        .split(/\r?\n/)
+        .filter((line) => !HEADING_RE.test(line))
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return stripInlineMarkdown(body).slice(0, 180);
+}
+function stripInlineMarkdown(value) {
+    return value
+        .replace(/`([^`]+)`/g, "$1")
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+        .replace(/[*_~#>]/g, "")
+        .trim();
+}

package/dist/web/errors.js

@@ -0,0 +1,3 @@
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/web/event-hub.js

@@ -0,0 +1,246 @@
+import { getContactNickname } from "../conversation/contact-note.js";
+import { eventId, toUnixMs } from "../conversation/ids.js";
+import { consumeSilentDelta, createSilentFilterState, finalizeSilentFilter } from "../runtime/silent-marker.js";
+import { encodeFrame, replayEvents } from "./events.js";
+import { toolFromStoredAgentEvent, webAttachments } from "./messages.js";
+import { EVENT_REPLAY_LIMIT, WEB_USER_NAME } from "./types.js";
+const IN_FLIGHT_TTL_MS = 10 * 60 * 1000;
+export function createWebEventHub(config, personaName) {
+    const clients = new Set();
+    const eventsByChannel = new Map();
+    const runtimeSubscriptions = new Map();
+    const inFlightMessages = new Map();
+    const getOrCreateInFlight = (messageIdValue) => {
+        let entry = inFlightMessages.get(messageIdValue);
+        if (!entry) {
+            entry = { locallyStreamed: false, startedSilent: false, lastActiveAt: Date.now() };
+            inFlightMessages.set(messageIdValue, entry);
+        }
+        else {
+            entry.lastActiveAt = Date.now();
+        }
+        return entry;
+    };
+    const touchInFlight = (messageIdValue) => {
+        const entry = inFlightMessages.get(messageIdValue);
+        if (entry)
+            entry.lastActiveAt = Date.now();
+    };
+    const inFlightGcTimer = setInterval(() => {
+        const cutoff = Date.now() - IN_FLIGHT_TTL_MS;
+        for (const [id, entry] of inFlightMessages) {
+            if (entry.lastActiveAt < cutoff)
+                inFlightMessages.delete(id);
+        }
+    }, 60 * 1000);
+    inFlightGcTimer.unref?.();
+    const publish = (event) => {
+        const fullEvent = { ...event, eventId: eventId(), ts: event.ts ?? Date.now() };
+        const events = eventsByChannel.get(fullEvent.channelKey ?? "") ?? [];
+        events.push(fullEvent);
+        if (events.length > EVENT_REPLAY_LIMIT)
+            events.shift();
+        eventsByChannel.set(fullEvent.channelKey ?? "", events);
+        const frame = encodeFrame(JSON.stringify(fullEvent));
+        for (const client of clients) {
+            if (client.channelKey === fullEvent.channelKey && !client.socket.destroyed) {
+                if (client.authed) {
+                    client.socket.write(frame);
+                }
+                else {
+                    const pendingEvents = client.pendingEvents ?? [];
+                    pendingEvents.push(fullEvent);
+                    client.pendingEvents = pendingEvents;
+                }
+            }
+        }
+        return fullEvent;
+    };
+    const publishDelta = (channelKey, messageIdValue, part, text, ts) => publish({ type: "delta", channelKey, messageId: messageIdValue, part, content: text, text, ts });
+    const publishStoredAgentEvent = (channelKey, messageIdValue, storedEvent, ts) => {
+        touchInFlight(messageIdValue);
+        if (storedEvent.type === "message_start" && storedEvent.role === "assistant") {
+            const entry = getOrCreateInFlight(messageIdValue);
+            entry.locallyStreamed = true;
+            entry.silentFilter = createSilentFilterState();
+            entry.pendingStartTs = ts;
+            entry.startedSilent = false;
+        }
+        const startedSilentMessage = () => {
+            const entry = inFlightMessages.get(messageIdValue);
+            if (!entry || entry.startedSilent)
+                return false;
+            const startTs = entry.pendingStartTs;
+            entry.pendingStartTs = undefined;
+            entry.startedSilent = true;
+            publish({
+                type: "message_started",
+                channelKey,
+                messageId: messageIdValue,
+                role: "assistant",
+                who: personaName,
+                ts: startTs,
+            });
+            return true;
+        };
+        if (storedEvent.type === "message_update") {
+            const assistantEvent = storedEvent.assistantMessageEvent;
+            if (assistantEvent.type === "thinking_delta") {
+                startedSilentMessage();
+                publishDelta(channelKey, messageIdValue, "thinking", assistantEvent.delta, ts);
+            }
+            if (assistantEvent.type === "text_delta") {
+                const filter = inFlightMessages.get(messageIdValue)?.silentFilter;
+                if (!filter) {
+                    startedSilentMessage();
+                    publishDelta(channelKey, messageIdValue, "text", assistantEvent.delta, ts);
+                }
+                else {
+                    const result = consumeSilentDelta(filter, assistantEvent.delta);
+                    if (result.kind === "emit" && result.text) {
+                        startedSilentMessage();
+                        publishDelta(channelKey, messageIdValue, "text", result.text, ts);
+                    }
+                }
+            }
+        }
+        if (storedEvent.type === "tool_execution_start") {
+            startedSilentMessage();
+        }
+        if (storedEvent.type === "message_end" && storedEvent.role === "assistant") {
+            const entry = inFlightMessages.get(messageIdValue);
+            const filter = entry?.silentFilter;
+            let silent = false;
+            if (filter && entry) {
+                const final = finalizeSilentFilter(filter);
+                silent = final.silent;
+                if (!silent) {
+                    startedSilentMessage();
+                    if (final.flush) {
+                        publishDelta(channelKey, messageIdValue, "text", final.flush, ts);
+                    }
+                }
+                else {
+                    entry.startedSilent = true;
+                    entry.pendingStartTs = undefined;
+                }
+                entry.silentFilter = undefined;
+            }
+            else {
+                startedSilentMessage();
+            }
+            publish({
+                type: "message_completed",
+                channelKey,
+                messageId: messageIdValue,
+                usage: storedEvent.usage,
+                silent: silent || undefined,
+                ts,
+            });
+            if (storedEvent.errorMessage) {
+                publish({
+                    type: "model_error",
+                    channelKey,
+                    messageId: messageIdValue,
+                    message: storedEvent.errorMessage,
+                    ts,
+                });
+            }
+        }
+        const tool = toolFromStoredAgentEvent(storedEvent, ts ?? Date.now());
+        if (tool)
+            publish({ type: "tool_event", channelKey, messageId: messageIdValue, tool, ts });
+    };
+    const subscribeRuntime = (runtime) => {
+        if (runtimeSubscriptions.has(runtime.channelKey))
+            return;
+        const unsubscribeRecords = runtime.subscribe((record) => {
+            if (record.type === "inbound") {
+                publish({
+                    type: "message_started",
+                    channelKey: runtime.channelKey,
+                    messageId: record.messageId,
+                    role: "user",
+                    who: record.authorName || getContactNickname(WEB_USER_NAME),
+                    ts: toUnixMs(record.ts),
+                });
+                publishDelta(runtime.channelKey, record.messageId, "text", record.text, toUnixMs(record.ts));
+                publish({
+                    type: "message_completed",
+                    channelKey: runtime.channelKey,
+                    messageId: record.messageId,
+                    attachments: webAttachments(config, record.attachments),
+                    ts: toUnixMs(record.ts),
+                });
+            }
+            if (record.type === "outbound" && !record.control) {
+                const outboundId = record.webMessageId || record.messageIds[0] || `out_${record.recordId}`;
+                const completion = {
+                    type: "message_completed",
+                    channelKey: runtime.channelKey,
+                    messageId: outboundId,
+                    thinkingMs: record.thinkingMs,
+                    attachments: webAttachments(config, record.attachments),
+                    silent: record.silent || undefined,
+                    ts: toUnixMs(record.ts),
+                };
+                if (inFlightMessages.get(outboundId)?.locallyStreamed) {
+                    inFlightMessages.delete(outboundId);
+                    publish(completion);
+                    return;
+                }
+                if (!record.silent) {
+                    publish({
+                        type: "message_started",
+                        channelKey: runtime.channelKey,
+                        messageId: outboundId,
+                        role: "assistant",
+                        who: personaName,
+                        ts: toUnixMs(record.ts),
+                    });
+                    if (record.thinking)
+                        publishDelta(runtime.channelKey, outboundId, "thinking", record.thinking, toUnixMs(record.ts));
+                    if (record.text)
+                        publishDelta(runtime.channelKey, outboundId, "text", record.text, toUnixMs(record.ts));
+                }
+                publish(completion);
+            }
+        });
+        const unsubscribeAgentEvents = runtime.subscribeAgentEvents((agentEvent) => {
+            publishStoredAgentEvent(runtime.channelKey, agentEvent.messageId, agentEvent.event, agentEvent.ts);
+        });
+        runtimeSubscriptions.set(runtime.channelKey, () => {
+            unsubscribeRecords();
+            unsubscribeAgentEvents();
+        });
+    };
+    return {
+        publish,
+        publishDelta,
+        async appendAndPublishError(runtime, message) {
+            await runtime.appendError(message);
+            publish({ type: "error", channelKey: runtime.channelKey, code: "unknown", message });
+        },
+        markLocallyStreamed(messageIdValue) {
+            getOrCreateInFlight(messageIdValue).locallyStreamed = true;
+        },
+        subscribeRuntime,
+        replay(client, channelKey, lastEventId) {
+            const events = eventsByChannel.get(channelKey) ?? [];
+            replayEvents(client, events, lastEventId, () => publish({ type: "replay_window_lost", channelKey }));
+        },
+        registerClient(client) {
+            clients.add(client);
+            return () => clients.delete(client);
+        },
+        stop() {
+            clearInterval(inFlightGcTimer);
+            for (const client of clients)
+                client.socket.destroy();
+            clients.clear();
+            for (const unsubscribe of runtimeSubscriptions.values())
+                unsubscribe();
+            runtimeSubscriptions.clear();
+        },
+    };
+}

package/dist/{web-http.js → web/http.js}

@@ -1,4 +1,14 @@
 export const MAX_BODY_BYTES = 64 * 1024;
+// Thrown where a request is malformed so the dispatcher can answer with the right
+// client-error status instead of a blanket 500.
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "HttpError";
+    }
+}
 export function sendJson(response, status, body, headers = {}) {
     response.writeHead(status, {
         "content-type": "application/json; charset=utf-8",
@@ -18,12 +28,16 @@ export async function readJsonBody(request) {
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         total += buffer.length;
         if (total > MAX_BODY_BYTES)
-            throw new Error("Request body too large");
+            throw new HttpError(413, "Request body too large");
         chunks.push(buffer);
     }
     const raw = Buffer.concat(chunks).toString("utf8").trim();
-    return raw ? JSON.parse(raw) : {};
-}
-export function isObject(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new HttpError(400, "Request body must be valid JSON");
+    }
 }

package/dist/web/memes.js

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+export function parseMemeCatalog(markdown) {
+    const families = [];
+    let currentFamily;
+    for (const line of markdown.split(/\r?\n/)) {
+        const familyMatch = line.match(/^## (.+)$/);
+        if (familyMatch) {
+            currentFamily = { name: familyMatch[1]?.trim() ?? "", memes: [] };
+            families.push(currentFamily);
+            continue;
+        }
+        if (!currentFamily || !line.startsWith("- ") || !line.includes(" — "))
+            continue;
+        const separator = line.indexOf(" — ");
+        const name = line.slice(2, separator).trim();
+        const suffix = line.slice(separator + " — ".length).trim();
+        if (!name || !suffix)
+            continue;
+        currentFamily.memes.push({ name, url: `https://files.catbox.moe/${suffix}` });
+    }
+    return families;
+}
+export function memeCatalogPath(config) {
+    return join(config.workspacePath, "skills", "memes", "SKILL.md");
+}