@qearlyao/familiar 0.3.0 → 0.4.0

package/dist/web/multipart.js

@@ -1,6 +1,12 @@
+import { MAX_INBOUND_TOTAL_BYTES } from "../media/attachment-limits.js";
 export function isWebUploadAttachment(value) {
     return !!value && typeof value === "object" && Buffer.isBuffer(value.buffer);
 }
+export function isMultipartContentType(contentType) {
+    return Array.isArray(contentType)
+        ? contentType.some((value) => value.includes("multipart/form-data"))
+        : contentType.includes("multipart/form-data");
+}
 export async function readRawBody(request, maxBytes) {
     const chunks = [];
     let total = 0;
@@ -33,7 +39,7 @@ export function parseContentDisposition(header) {
 }
 export async function readMultipartBody(request, contentType) {
     const boundary = multipartBoundary(contentType);
-    const raw = await readRawBody(request, 32 * 1024 * 1024);
+    const raw = await readRawBody(request, MAX_INBOUND_TOTAL_BYTES);
     const binary = raw.toString("binary");
     const marker = `--${boundary}`;
     const attachments = [];

package/dist/web/payloads.js

@@ -1,4 +1,4 @@
-import { supportedThinkingLevels } from "../models.js";
+import { supportedThinkingLevels } from "../models/index.js";
 import { isRecord } from "../util/guards.js";
 export function commandArgs(command, args) {
     if (!isRecord(args))

package/dist/web/request-context.js

@@ -0,0 +1,25 @@
+function normalizeRemoteAddress(address) {
+    if (!address)
+        return undefined;
+    if (address.startsWith("::ffff:"))
+        return address.slice("::ffff:".length);
+    return address;
+}
+function isLoopbackAddress(address) {
+    const normalized = normalizeRemoteAddress(address);
+    return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
+}
+function firstHeaderValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+export function requestAuthContext(request, now = Date.now()) {
+    const remoteAddress = normalizeRemoteAddress(request.socket.remoteAddress);
+    const trustedProxy = isLoopbackAddress(remoteAddress);
+    const forwardedFor = trustedProxy ? firstHeaderValue(request.headers["x-forwarded-for"]) : undefined;
+    const forwardedProto = trustedProxy ? firstHeaderValue(request.headers["x-forwarded-proto"]) : undefined;
+    const clientIp = forwardedFor?.split(",")[0]?.trim() || remoteAddress || "unknown";
+    const socket = request.socket;
+    const secure = forwardedProto?.split(",")[0]?.trim().toLowerCase() === "https" || socket.encrypted === true;
+    const userAgent = firstHeaderValue(request.headers["user-agent"]);
+    return { clientIp, secure, now, ...(userAgent ? { userAgent } : {}) };
+}

package/dist/web/route-helpers.js

@@ -0,0 +1,9 @@
+import { isRecord } from "../util/guards.js";
+export function getChannelKeyFromRequest(url, body) {
+    const queryKey = url.searchParams.get("channelKey");
+    if (queryKey)
+        return queryKey;
+    if (isRecord(body) && typeof body.channelKey === "string")
+        return body.channelKey;
+    return undefined;
+}

package/dist/web/routes.js

@@ -0,0 +1,37 @@
+import { errorMessage } from "./errors.js";
+import { HttpError, sendJson } from "./http.js";
+import { serveAttachment } from "./static.js";
+export function createWebRouteRegistry(config, auth) {
+    const webRoutes = new Map();
+    const route = (method, pathname, handler) => {
+        webRoutes.set(`${method} ${pathname}`, handler);
+    };
+    const handleApi = async (request, response, url) => {
+        if (!url.pathname.startsWith("/api/web/"))
+            return false;
+        if (!(await auth.authorize(request, url.pathname))) {
+            sendJson(response, 401, { error: "unauthorized" });
+            return true;
+        }
+        try {
+            if (request.method === "GET" && url.pathname.startsWith("/api/web/attachments/")) {
+                return serveAttachment(config, response, url.pathname, request.headers.range);
+            }
+            const handler = webRoutes.get(`${request.method} ${url.pathname}`);
+            // await is load-bearing: it keeps handler rejections inside this try so the catch maps HttpError to a status.
+            if (handler) {
+                await handler(request, response, url);
+                return true;
+            }
+            sendJson(response, 404, { error: "not found" });
+            return true;
+        }
+        catch (error) {
+            const status = error instanceof HttpError ? error.status : 500;
+            const message = errorMessage(error);
+            sendJson(response, status, { error: message });
+            return true;
+        }
+    };
+    return { route, handleApi };
+}

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

@@ -2,7 +2,7 @@ import { createReadStream, existsSync } from "node:fs";
 import { lstat, realpath, stat } from "node:fs/promises";
 import { dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { attachmentsDir, browserScreenshotsDir, generatedAttachmentsDir } from "../generated-media.js";
+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");

package/dist/web/stream.js

@@ -23,14 +23,23 @@ export function attachWebSocketStream(server, options) {
     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" || !authorize(request, url.pathname)) {
+        if (url.pathname !== "/api/web/stream") {
             netSocket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
             netSocket.destroy();
             return;
         }
-        const requestedChannelKey = url.searchParams.get("channelKey") || undefined;
-        void getRuntime(requestedChannelKey)
+        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))

package/dist/{web-tools.js → web-tools/index.js}

@@ -1,11 +1,11 @@
-import { PageCache } from "./web-tools/cache.js";
-import { loadWebConfig } from "./web-tools/config.js";
-import { createJinaProvider, createTinyfishProvider } from "./web-tools/fetch-providers.js";
-import { formatFetchContent, formatSearchResults, paginateContent } from "./web-tools/format.js";
-import { resolveSearchProviders } from "./web-tools/routing.js";
-import { isTransientProviderError, validateFetchUrl } from "./web-tools/safety.js";
-import { createBraveProvider, createExaProvider, createTavilyProvider, normalizeDomains, } from "./web-tools/search-providers.js";
-import { FETCH_DEFAULT_MAX_CHARS, WEB_UNTRUSTED_PREFIX, webFetchSchema, webSearchSchema, } from "./web-tools/types.js";
+import { PageCache } from "./cache.js";
+import { loadWebConfig } from "./config.js";
+import { createJinaProvider, createTinyfishProvider } from "./fetch-providers.js";
+import { formatFetchContent, formatSearchResults, paginateContent } from "./format.js";
+import { resolveSearchProviders } from "./routing.js";
+import { isTransientProviderError, validateFetchUrl } from "./safety.js";
+import { createBraveProvider, createExaProvider, createTavilyProvider, normalizeDomains } from "./search-providers.js";
+import { FETCH_DEFAULT_MAX_CHARS, WEB_UNTRUSTED_PREFIX, webFetchSchema, webSearchSchema, } from "./types.js";
 const pageCache = new PageCache();
 function makeSearchTool(config) {
     const providers = {};