@qearlyao/familiar 0.2.5 → 0.4.0

package/dist/web/runtime-actions.js

@@ -0,0 +1,231 @@
+import { randomUUID } from "node:crypto";
+import { formatSetting } from "../config/settings.js";
+import { messageId } from "../conversation/ids.js";
+import { createAgentEventRecorder, storedAgentEventFromAgentEvent, thinkingDurationMs, updateAgentEventSummary, } from "../runtime/agent-events.js";
+import { parseAgentReply } from "../runtime/silent-marker.js";
+import { errorMessage } from "./errors.js";
+import { webAttachments } from "./messages.js";
+function replyPersistenceFields(reply) {
+    return {
+        text: reply.text,
+        messageIds: [reply.messageId],
+        webMessageId: reply.messageId,
+        attachments: reply.attachments,
+        thinking: reply.thinking,
+        thinkingMs: reply.thinkingMs,
+        silent: reply.silent,
+    };
+}
+export function createWebRuntimeActions(options) {
+    const { config, familiarAgent, agentCore, eventHub, personaName, restart } = options;
+    const { appendAndPublishError, publish, publishDelta } = eventHub;
+    const promptAssistantMessage = async (input) => {
+        const { runtime, jobId, assistantMessageId } = input;
+        const summary = { thinking: "" };
+        const recorder = createAgentEventRecorder((storedEvent) => runtime.noteAgentEvent(jobId, assistantMessageId, storedEvent, { notify: false }));
+        let started = false;
+        let reply;
+        try {
+            reply = await input.dispatch(async (event) => {
+                if (event.type === "message_start" && event.message.role === "assistant" && !started) {
+                    started = true;
+                    input.onAssistantStart?.();
+                }
+                updateAgentEventSummary(summary, event);
+                const storedEvent = storedAgentEventFromAgentEvent(event);
+                if (storedEvent) {
+                    runtime.publishAgentEvent(jobId, assistantMessageId, storedEvent);
+                    await recorder.record(storedEvent);
+                }
+            });
+        }
+        finally {
+            await recorder.flush();
+        }
+        const parsed = parseAgentReply(reply.text);
+        const finalText = parsed.silent ? "" : reply.text;
+        if (!started) {
+            input.onAssistantStart?.();
+            if (!parsed.silent) {
+                publish({
+                    type: "message_started",
+                    channelKey: runtime.channelKey,
+                    messageId: assistantMessageId,
+                    role: "assistant",
+                    who: personaName,
+                });
+                if (finalText) {
+                    publishDelta(runtime.channelKey, assistantMessageId, "text", finalText);
+                }
+            }
+        }
+        const thinkingMs = thinkingDurationMs(summary);
+        publish({
+            type: "message_completed",
+            channelKey: runtime.channelKey,
+            messageId: assistantMessageId,
+            thinkingMs,
+            attachments: webAttachments(config, reply.attachments),
+            silent: parsed.silent || undefined,
+        });
+        eventHub.markLocallyStreamed(assistantMessageId);
+        return {
+            text: finalText,
+            messageId: assistantMessageId,
+            thinking: summary.thinking,
+            thinkingMs,
+            attachments: reply.attachments,
+            silent: parsed.silent,
+        };
+    };
+    const promptForRuntime = async (runtime, jobId, prompt, attachments = [], onTurnEnd) => {
+        return promptAssistantMessage({
+            runtime,
+            jobId,
+            assistantMessageId: messageId(),
+            dispatch: (onEvent) => agentCore.promptForRuntime(runtime, jobId, prompt, attachments, onEvent, onTurnEnd),
+        });
+    };
+    const retryLatestAssistant = async (runtime) => {
+        if (runtime.hasActiveJob())
+            throw new Error("Cannot retry while a turn is running");
+        const target = runtime.latestAssistantRetryTarget();
+        if (!target)
+            throw new Error("No assistant message to retry");
+        const jobId = randomUUID();
+        const assistantMessageId = messageId();
+        const replaceMessage = () => {
+            publish({
+                type: "message_replaced",
+                channelKey: runtime.channelKey,
+                oldMessageId: target.messageId,
+                newMessageId: assistantMessageId,
+            });
+        };
+        try {
+            const reply = await promptAssistantMessage({
+                runtime,
+                jobId,
+                assistantMessageId,
+                onAssistantStart: replaceMessage,
+                dispatch: (onEvent) => familiarAgent.retryLastAssistant(runtime.channelKey, onEvent, {
+                    onTurnEnd: () => {
+                        publish({
+                            type: "status",
+                            channelKey: runtime.channelKey,
+                            kind: "idle",
+                        });
+                    },
+                }),
+            });
+            await runtime.noteAssistantRetry({
+                oldMessageId: target.messageId,
+                newMessageId: assistantMessageId,
+                jobId,
+                triggerRecordId: target.triggerRecordId,
+            });
+            await runtime.noteOutbound({
+                ...replyPersistenceFields(reply),
+                replyToMessageId: target.messageId,
+                jobId,
+            });
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            await appendAndPublishError(runtime, message);
+        }
+    };
+    const deleteLatestAssistant = async (runtime) => {
+        if (runtime.hasActiveJob())
+            throw new Error("Cannot delete while a turn is running");
+        const target = runtime.latestAssistantDeleteTarget();
+        if (!target)
+            throw new Error("No assistant message to delete");
+        try {
+            await familiarAgent.deleteLastAssistant(runtime.channelKey);
+            await runtime.noteMessageDelete(target.messageId);
+            publish({
+                type: "message_deleted",
+                channelKey: runtime.channelKey,
+                messageId: target.messageId,
+            });
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            await appendAndPublishError(runtime, message);
+        }
+    };
+    const drainJobs = async (runtime) => {
+        for (;;) {
+            const dispatch = runtime.beginNextJob();
+            if (!dispatch)
+                return;
+            try {
+                const reply = await promptForRuntime(runtime, dispatch.job.jobId, dispatch.prompt, dispatch.attachments, () => {
+                    publish({
+                        type: "status",
+                        channelKey: runtime.channelKey,
+                        kind: "idle",
+                    });
+                });
+                await runtime.completeActiveJob({
+                    ...replyPersistenceFields(reply),
+                    replyToMessageId: dispatch.triggerMessageId,
+                });
+            }
+            catch (error) {
+                if (!runtime.hasActiveJob(dispatch.job.jobId))
+                    return;
+                const message = errorMessage(error);
+                await runtime.failActiveJob(message);
+                await appendAndPublishError(runtime, message);
+            }
+        }
+    };
+    const applyControlCommand = async (runtime, control) => {
+        if (control.command === "stop") {
+            await familiarAgent.abort(runtime.channelKey);
+            return "Stopped current work.";
+        }
+        if (control.command === "new") {
+            await familiarAgent.reset(runtime.channelKey);
+            await runtime.resetConversation("new conversation requested");
+            return "Started a fresh agent transcript for this channel.";
+        }
+        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)
+                : `Current model: ${formatSetting(familiarAgent.getModel(runtime.channelKey))}`;
+        }
+        if (control.command === "thinking") {
+            return control.args
+                ? await familiarAgent.setThinkingLevel(runtime.channelKey, control.args)
+                : `Current thinking: ${formatSetting(familiarAgent.getThinkingLevel(runtime.channelKey))}`;
+        }
+        if (control.command === "channel-trigger")
+            return "Use Discord /familiar channel-trigger in the channel for now.";
+        if (control.command === "status") {
+            return [
+                runtime.formatStatus(),
+                `model: ${formatSetting(familiarAgent.getModel(runtime.channelKey))}`,
+                `thinking: ${formatSetting(familiarAgent.getThinkingLevel(runtime.channelKey))}`,
+            ].join("\n");
+        }
+        return "Compact is not wired for this runtime yet. I logged the command, but I won't run lossy compaction here.";
+    };
+    return {
+        promptForRuntime,
+        retryLatestAssistant,
+        deleteLatestAssistant,
+        drainJobs,
+        applyControlCommand,
+    };
+}

package/dist/web/session-store.js

@@ -0,0 +1,161 @@
+import { createHash, randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+import { atomicWriteJson, createWriteQueue, readFileOrNull } from "../util/fs.js";
+import { isRecord } from "../util/guards.js";
+export const SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const SESSION_TOUCH_INTERVAL_MS = 60 * 1000;
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function normalizeString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function normalizeDeviceName(value, fallback) {
+    const name = normalizeString(value) ?? fallback;
+    return name.slice(0, 80);
+}
+function deviceDto(session, current = false) {
+    return {
+        id: session.id,
+        deviceName: session.deviceName,
+        createdAt: session.createdAt,
+        lastSeenAt: session.lastSeenAt,
+        expiresAt: session.expiresAt,
+        ...(session.lastIp ? { lastIp: session.lastIp } : {}),
+        ...(session.userAgent ? { userAgent: session.userAgent } : {}),
+        ...(current ? { current: true } : {}),
+    };
+}
+function isActive(session, now) {
+    return !session.revokedAt && Date.parse(session.expiresAt) > now;
+}
+function normalizeSession(value) {
+    if (!isRecord(value))
+        return undefined;
+    const id = normalizeString(value.id);
+    const tokenHash = normalizeString(value.tokenHash);
+    const deviceName = normalizeString(value.deviceName);
+    const createdAt = normalizeString(value.createdAt);
+    const lastSeenAt = normalizeString(value.lastSeenAt);
+    const expiresAt = normalizeString(value.expiresAt);
+    if (!id || !tokenHash || !deviceName || !createdAt || !lastSeenAt || !expiresAt)
+        return undefined;
+    return {
+        id,
+        tokenHash,
+        deviceName,
+        createdAt,
+        lastSeenAt,
+        expiresAt,
+        lastIp: normalizeString(value.lastIp),
+        userAgent: normalizeString(value.userAgent),
+        revokedAt: normalizeString(value.revokedAt),
+    };
+}
+function normalizeSessionsFile(value, now) {
+    if (!isRecord(value) || !Array.isArray(value.sessions))
+        return { version: 1, sessions: [] };
+    return {
+        version: 1,
+        sessions: value.sessions
+            .map(normalizeSession)
+            .filter((session) => !!session && isActive(session, now)),
+    };
+}
+async function readSessionsFile(path, now) {
+    const raw = await readFileOrNull(path, "utf8");
+    return raw === null ? { version: 1, sessions: [] } : normalizeSessionsFile(JSON.parse(raw), now);
+}
+export async function loadWebSessionStore(config, now = Date.now()) {
+    const path = resolve(config.workspace.dataDir, "settings", "web-sessions.json");
+    let file = await readSessionsFile(path, now);
+    const enqueueWrite = createWriteQueue("web sessions");
+    const enqueuePersist = () => enqueueWrite(() => atomicWriteJson(path, file));
+    const findByToken = (token, now) => {
+        if (!token)
+            return undefined;
+        const tokenHash = sha256(token);
+        return file.sessions.find((session) => session.tokenHash === tokenHash && isActive(session, now));
+    };
+    return {
+        path,
+        async createSession(input) {
+            const now = input.context.now;
+            const ts = new Date(now).toISOString();
+            const token = randomBytes(32).toString("base64url");
+            const session = {
+                id: randomBytes(12).toString("base64url"),
+                tokenHash: sha256(token),
+                deviceName: normalizeDeviceName(input.deviceName, "browser"),
+                createdAt: ts,
+                lastSeenAt: ts,
+                expiresAt: new Date(now + SESSION_TTL_MS).toISOString(),
+                lastIp: input.context.clientIp,
+                userAgent: input.context.userAgent,
+            };
+            file = { version: 1, sessions: [...file.sessions.filter((item) => isActive(item, now)), session] };
+            await enqueuePersist();
+            return { token, device: deviceDto(session, true) };
+        },
+        async authenticateSession(token, context) {
+            const session = findByToken(token, context.now);
+            if (!session)
+                return undefined;
+            const touchedAt = Date.parse(session.lastSeenAt);
+            const nextExpiresAt = new Date(context.now + SESSION_TTL_MS).toISOString();
+            const changed = context.now - touchedAt >= SESSION_TOUCH_INTERVAL_MS ||
+                session.lastIp !== context.clientIp ||
+                session.userAgent !== context.userAgent;
+            if (changed) {
+                session.lastSeenAt = new Date(context.now).toISOString();
+                session.expiresAt = nextExpiresAt;
+                session.lastIp = context.clientIp;
+                session.userAgent = context.userAgent;
+                await enqueuePersist();
+            }
+            return deviceDto(session, true);
+        },
+        currentDevice(token) {
+            const session = findByToken(token, Date.now());
+            return session ? deviceDto(session, true) : undefined;
+        },
+        listDevices(currentToken) {
+            const now = Date.now();
+            const currentHash = currentToken ? sha256(currentToken) : undefined;
+            file = { version: 1, sessions: file.sessions.filter((session) => isActive(session, now)) };
+            return file.sessions.map((session) => deviceDto(session, session.tokenHash === currentHash));
+        },
+        async revokeDevice(id) {
+            const session = file.sessions.find((item) => item.id === id && !item.revokedAt);
+            if (!session)
+                return false;
+            session.revokedAt = new Date().toISOString();
+            await enqueuePersist();
+            return true;
+        },
+        async revokeCurrent(token) {
+            const session = findByToken(token, Date.now());
+            if (!session)
+                return false;
+            session.revokedAt = new Date().toISOString();
+            await enqueuePersist();
+            return true;
+        },
+        async revokeOthers(token) {
+            const session = findByToken(token, Date.now());
+            if (!session)
+                return 0;
+            const now = new Date().toISOString();
+            let revoked = 0;
+            for (const item of file.sessions) {
+                if (item.tokenHash === session.tokenHash || item.revokedAt)
+                    continue;
+                item.revokedAt = now;
+                revoked += 1;
+            }
+            if (revoked > 0)
+                await enqueuePersist();
+            return revoked;
+        },
+    };
+}

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

@@ -1,12 +1,14 @@
 import { createReadStream, existsSync } from "node:fs";
 import { lstat, realpath, stat } from "node:fs/promises";
-import { extname, join, relative, resolve } from "node:path";
+import { dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { attachmentsDir, browserScreenshotsDir, generatedAttachmentsDir } from "./generated-media.js";
-import { sendText } from "./web-http.js";
-function getProjectRoot() {
-    return resolve(fileURLToPath(import.meta.url), "../..");
-}
+import { attachmentsDir, browserScreenshotsDir, generatedAttachmentsDir } from "../media/generated-media.js";
+import { sendText } from "./http.js";
+const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const DIST_DIR = resolve(PROJECT_ROOT, "web/dist");
+// Only successful realpaths are cached: the attachment root dirs are created
+// lazily on first write, so a missing root must stay retryable.
+const rootRealPathCache = new Map();
 function mimeType(path) {
     const extension = extname(path).toLowerCase();
     if (extension === ".html")
@@ -36,19 +38,18 @@ function mimeType(path) {
     return "application/octet-stream";
 }
 export async function serveStatic(response, requestPath) {
-    const distDir = resolve(getProjectRoot(), "web/dist");
-    if (!existsSync(distDir))
+    if (!existsSync(DIST_DIR))
         return false;
     const pathname = decodeURIComponent(requestPath.split("?")[0] || "/");
-    const candidate = resolve(distDir, pathname === "/" ? "index.html" : pathname.slice(1));
-    if (!candidate.startsWith(distDir)) {
+    const candidate = resolve(DIST_DIR, pathname === "/" ? "index.html" : pathname.slice(1));
+    if (!candidate.startsWith(DIST_DIR)) {
         sendText(response, 403, "Forbidden");
         return true;
     }
     let filePath = candidate;
     const fileStat = await stat(filePath).catch(() => undefined);
     if (!fileStat?.isFile())
-        filePath = join(distDir, "index.html");
+        filePath = join(DIST_DIR, "index.html");
     const stream = createReadStream(filePath);
     response.writeHead(200, { "content-type": mimeType(filePath) });
     stream.pipe(response);
@@ -88,9 +89,13 @@ export async function serveAttachment(config, response, requestPath, rangeHeader
         { root: browserScreenshotsDir(config), relativePath: relativePath.replace(/^screenshot[\\/]/, "") },
     ];
     for (const { root, relativePath: candidateRelativePath } of candidates) {
-        const rootRealPath = await realpath(root).catch(() => undefined);
-        if (!rootRealPath)
-            continue;
+        let rootRealPath = rootRealPathCache.get(root);
+        if (rootRealPath === undefined) {
+            rootRealPath = await realpath(root).catch(() => undefined);
+            if (!rootRealPath)
+                continue;
+            rootRealPathCache.set(root, rootRealPath);
+        }
         const filePath = resolve(root, candidateRelativePath);
         const rel = relative(root, filePath);
         if (rel.startsWith("..") || rel.startsWith("/") || rel.startsWith("\\") || rel === "") {

package/dist/web/stream.js

@@ -0,0 +1,78 @@
+import { isRecord } from "../util/guards.js";
+import { acceptWebSocket, decodeFrames } from "./events.js";
+export function attachWebSocketStream(server, options) {
+    const { authorize, eventHub, getRuntime, abort, retry, deleteLatest } = options;
+    const runtimeActions = { abort, retry, delete: deleteLatest };
+    const handleStreamMessage = (raw, client) => {
+        const message = JSON.parse(raw);
+        if (!isRecord(message) || typeof message.type !== "string")
+            return;
+        if (message.type === "hello") {
+            if (!client.channelKey)
+                return;
+            eventHub.replay(client, client.channelKey, typeof message.lastEventId === "string" ? message.lastEventId : null);
+            return;
+        }
+        const action = runtimeActions[message.type];
+        if (action) {
+            void getRuntime(client.channelKey)
+                .then(action)
+                .catch((error) => console.error(`WebSocket ${message.type} runtime lookup failed`, error));
+        }
+    };
+    server.on("upgrade", (request, socket) => {
+        const netSocket = socket;
+        const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+        if (url.pathname !== "/api/web/stream") {
+            netSocket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+            netSocket.destroy();
+            return;
+        }
+        void authorize(request, url.pathname)
+            .then((authorized) => {
+            if (!authorized) {
+                netSocket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+                netSocket.destroy();
+                return;
+            }
+            return getRuntime(url.searchParams.get("channelKey") || undefined);
+        })
+            .then((runtime) => {
+            if (!runtime)
+                return;
+            if (netSocket.destroyed)
+                return;
+            if (!acceptWebSocket(request, netSocket))
+                return;
+            netSocket.setNoDelay(true);
+            const client = { socket: netSocket, channelKey: runtime.channelKey, authed: false };
+            const dispose = eventHub.registerClient(client);
+            let frameBuffer = Buffer.alloc(0);
+            netSocket.on("data", (chunk) => {
+                try {
+                    frameBuffer = Buffer.concat([frameBuffer, chunk]);
+                    const decoded = decodeFrames(frameBuffer);
+                    frameBuffer = decoded.remaining;
+                    if (decoded.close)
+                        netSocket.destroy();
+                    for (const raw of decoded.messages) {
+                        handleStreamMessage(raw, client);
+                    }
+                }
+                catch (error) {
+                    console.error("WebSocket frame handling failed", error);
+                    netSocket.destroy();
+                }
+            });
+            netSocket.on("close", dispose);
+            netSocket.on("error", dispose);
+        })
+            .catch((error) => {
+            console.error("WebSocket runtime lookup failed", error);
+            if (!netSocket.destroyed) {
+                netSocket.write("HTTP/1.1 503 Service Unavailable\r\n\r\n");
+                netSocket.destroy();
+            }
+        });
+    });
+}

package/dist/web-tools/cache.js

@@ -0,0 +1,42 @@
+import { MAX_CACHE_CHARS_PER_PAGE } from "./types.js";
+export class PageCache {
+    ttlMs;
+    capacity;
+    entries = new Map();
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? 5 * 60 * 1000;
+        this.capacity = options.capacity ?? 20;
+    }
+    get(url) {
+        const entry = this.entries.get(url);
+        if (!entry)
+            return undefined;
+        if (Date.now() - entry.fetchedAt > this.ttlMs) {
+            this.entries.delete(url);
+            return undefined;
+        }
+        entry.lastAccessed = Date.now();
+        this.entries.delete(url);
+        this.entries.set(url, entry);
+        return entry;
+    }
+    set(url, content, provider) {
+        if (content.length > MAX_CACHE_CHARS_PER_PAGE)
+            return;
+        if (this.entries.has(url))
+            this.entries.delete(url);
+        const now = Date.now();
+        this.entries.set(url, {
+            content,
+            provider,
+            fetchedAt: now,
+            lastAccessed: now,
+        });
+        while (this.entries.size > this.capacity) {
+            const oldest = this.entries.keys().next().value;
+            if (!oldest)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+}

package/dist/web-tools/config.js

@@ -0,0 +1,16 @@
+export function readEnvKey(name) {
+    const value = process.env[name];
+    return value?.trim() ? value.trim() : undefined;
+}
+export function loadWebConfig() {
+    return {
+        apiKeys: {
+            BRAVE_API_KEY: readEnvKey("BRAVE_API_KEY"),
+            TAVILY_API_KEY: readEnvKey("TAVILY_API_KEY"),
+            EXA_API_KEY: readEnvKey("EXA_API_KEY"),
+            JINA_API_KEY: readEnvKey("JINA_API_KEY"),
+            TINYFISH_API_KEY: readEnvKey("TINYFISH_API_KEY"),
+        },
+        warnings: [],
+    };
+}