@qearlyao/familiar 0.2.5 → 0.4.0

package/dist/web/messages.js

@@ -0,0 +1,348 @@
+import { hiddenWebMessageIds, } from "../conversation/chat-log.js";
+import { getContactNickname } from "../conversation/contact-note.js";
+import { toUnixMs } from "../conversation/ids.js";
+import { publicAttachmentPath } from "../media/generated-media.js";
+import { isRecord } from "../util/guards.js";
+import { WEB_USER_NAME } from "./types.js";
+export function isUserVisibleRuntimeRecord(record) {
+    return record.type !== "runtime" || !["armed", "reset", "stopped"].includes(record.event);
+}
+export function webAttachments(config, attachments) {
+    if (!attachments?.length)
+        return undefined;
+    return attachments.map((attachment) => ({
+        id: attachment.id,
+        name: attachment.name,
+        kind: attachment.kind,
+        mimeType: attachment.mimeType,
+        size: attachment.size,
+        url: attachment.localPath ? publicAttachmentPath(config, attachment.localPath) : attachment.remoteUrl,
+        derivedText: attachmentDerivedText(attachment),
+    }));
+}
+export function attachmentDerivedText(attachment) {
+    if (attachment.derived?.text?.label === "preview")
+        return undefined;
+    const text = attachment.derived?.text?.text.trim();
+    if (!text)
+        return undefined;
+    return {
+        label: attachment.derived?.text?.label,
+        text,
+    };
+}
+export function toolError(result) {
+    if (typeof result === "string")
+        return result;
+    if (!isRecord(result))
+        return undefined;
+    if (typeof result.error === "string")
+        return result.error;
+    if (typeof result.message === "string")
+        return result.message;
+    return undefined;
+}
+export function toolFromStoredAgentEvent(event, ts) {
+    if (event.type === "tool_execution_start") {
+        return {
+            id: event.toolCallId,
+            name: event.toolName,
+            status: "running",
+            args: event.args,
+            startedAt: ts,
+            updatedAt: ts,
+        };
+    }
+    if (event.type === "tool_execution_update") {
+        return {
+            id: event.toolCallId,
+            name: event.toolName,
+            status: "running",
+            args: event.args,
+            partialResult: event.partialResult,
+            updatedAt: ts,
+        };
+    }
+    if (event.type === "tool_execution_end") {
+        return {
+            id: event.toolCallId,
+            name: event.toolName,
+            status: event.isError ? "error" : "completed",
+            result: event.result,
+            error: event.isError ? toolError(event.result) : undefined,
+            completedAt: ts,
+            updatedAt: ts,
+        };
+    }
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "toolcall_end") {
+        return {
+            id: event.assistantMessageEvent.toolCall.id,
+            name: event.assistantMessageEvent.toolCall.name,
+            status: "pending",
+            args: event.assistantMessageEvent.toolCall.arguments,
+            updatedAt: ts,
+        };
+    }
+    return undefined;
+}
+export function mergeToolEvent(existing, patch) {
+    const terminal = patch.status === "completed" || patch.status === "error";
+    return {
+        ...existing,
+        ...patch,
+        args: patch.args ?? existing?.args,
+        partialResult: terminal ? undefined : (patch.partialResult ?? existing?.partialResult),
+        result: patch.result ?? existing?.result,
+        error: patch.error ?? existing?.error,
+        startedAt: existing?.startedAt ?? patch.startedAt,
+    };
+}
+export function stepId(messageId, kind, index) {
+    return `${messageId}-${kind}-${index}`;
+}
+export function closeOpenContentSteps(steps, now) {
+    for (const step of steps) {
+        if (step.kind === "thinking" && !step.complete) {
+            step.complete = true;
+            step.endedAt ??= now;
+        }
+        if (step.kind === "text" && !step.complete)
+            step.complete = true;
+    }
+}
+export function appendDeltaStep(steps, messageId, part, content, now) {
+    const last = steps.at(-1);
+    if (part === "thinking") {
+        if (last?.kind === "thinking" && !last.complete) {
+            last.text += content;
+            return;
+        }
+        closeOpenContentSteps(steps, now);
+        steps.push({
+            kind: "thinking",
+            id: stepId(messageId, "thinking", steps.length),
+            text: content,
+            startedAt: now,
+        });
+        return;
+    }
+    if (last?.kind === "text" && !last.complete) {
+        last.text += content;
+        return;
+    }
+    closeOpenContentSteps(steps, now);
+    steps.push({ kind: "text", id: stepId(messageId, "text", steps.length), text: content });
+}
+export function upsertToolStep(steps, tool, now) {
+    const index = steps.findIndex((step) => step.kind === "tool" && step.tool.id === tool.id);
+    if (index >= 0) {
+        const existing = steps[index];
+        if (existing?.kind === "tool")
+            existing.tool = mergeToolEvent(existing.tool, tool);
+        return;
+    }
+    closeOpenContentSteps(steps, now);
+    steps.push({ kind: "tool", id: tool.id, tool });
+}
+export function applyStoredAgentEventToMessage(message, record, options) {
+    const event = record.event;
+    const ts = toUnixMs(record.ts);
+    message.steps ??= [];
+    const steps = message.steps;
+    if (event.type === "message_update") {
+        const assistantEvent = event.assistantMessageEvent;
+        if (assistantEvent.type === "text_delta") {
+            appendDeltaStep(steps, message.id, "text", assistantEvent.delta, ts);
+            if (options.applyTextDeltas)
+                message.text += assistantEvent.delta;
+        }
+        if (assistantEvent.type === "thinking_delta") {
+            appendDeltaStep(steps, message.id, "thinking", assistantEvent.delta, ts);
+            if (options.applyThinkingDeltas)
+                message.thinking = `${message.thinking ?? ""}${assistantEvent.delta}`;
+        }
+    }
+    if (event.type === "message_end") {
+        closeOpenContentSteps(steps, ts);
+        if (event.usage)
+            message.usage = event.usage;
+        if (event.errorMessage) {
+            steps.push({ kind: "error", id: stepId(message.id, "error", steps.length), text: event.errorMessage });
+        }
+    }
+    const tool = toolFromStoredAgentEvent(event, ts);
+    if (tool) {
+        upsertToolStep(steps, tool, ts);
+        const tools = message.tools ?? [];
+        const index = tools.findIndex((candidate) => candidate.id === tool.id);
+        if (index >= 0) {
+            tools[index] = mergeToolEvent(tools[index], tool);
+        }
+        else {
+            tools.push(tool);
+        }
+        message.tools = tools;
+    }
+}
+export function ensureFallbackSteps(message) {
+    if (message.steps?.length)
+        return;
+    const steps = [];
+    if (message.thinking || message.thinkingMs != null) {
+        const endedAt = message.ts;
+        steps.push({
+            kind: "thinking",
+            id: stepId(message.id, "thinking", steps.length),
+            text: message.thinking ?? "",
+            startedAt: endedAt - (message.thinkingMs ?? 0),
+            endedAt,
+            complete: true,
+        });
+    }
+    for (const tool of message.tools ?? [])
+        steps.push({ kind: "tool", id: tool.id, tool });
+    if (message.text) {
+        steps.push({ kind: "text", id: stepId(message.id, "text", steps.length), text: message.text, complete: true });
+    }
+    if (steps.length)
+        message.steps = steps;
+}
+export function webMessagesFromRecords(config, records, assistantName) {
+    const hidden = hiddenWebMessageIds(records);
+    const messages = [];
+    const messagesById = new Map();
+    const pendingAgentEvents = new Map();
+    for (const record of records) {
+        const message = webMessageFromRecord(config, record, assistantName);
+        if (message && hidden.has(message.id))
+            continue;
+        if (message) {
+            messages.push(message);
+            messagesById.set(message.id, message);
+            const pending = pendingAgentEvents.get(message.id) ?? [];
+            for (const pendingRecord of pending) {
+                applyStoredAgentEventToMessage(message, pendingRecord, {
+                    applyTextDeltas: !message.text && !message.silent,
+                    applyThinkingDeltas: !message.thinking,
+                });
+            }
+            pendingAgentEvents.delete(message.id);
+        }
+        if (record.type === "agent_event") {
+            if (hidden.has(record.messageId))
+                continue;
+            const existing = messagesById.get(record.messageId);
+            if (existing) {
+                applyStoredAgentEventToMessage(existing, record, {
+                    applyTextDeltas: !existing.silent,
+                    applyThinkingDeltas: true,
+                });
+            }
+            else {
+                const pending = pendingAgentEvents.get(record.messageId) ?? [];
+                pending.push(record);
+                pendingAgentEvents.set(record.messageId, pending);
+            }
+        }
+    }
+    for (const message of messages)
+        ensureFallbackSteps(message);
+    return messages;
+}
+export function webHistoryPayload(config, records, assistantName, channelKey, options) {
+    const hidden = hiddenWebMessageIds(records);
+    let end = records.length;
+    if (options.before) {
+        let cursorIndex;
+        for (let index = records.length - 1; index >= 0; index -= 1) {
+            const message = webMessageFromRecord(config, records[index], assistantName);
+            if (message && hidden.has(message.id))
+                continue;
+            if (message?.id === options.before) {
+                cursorIndex = index;
+                break;
+            }
+        }
+        end = cursorIndex ?? records.length;
+    }
+    const pageEntries = [];
+    let scanIndex = end - 1;
+    for (; scanIndex >= 0 && pageEntries.length < options.limit; scanIndex -= 1) {
+        const message = webMessageFromRecord(config, records[scanIndex], assistantName);
+        if (message && hidden.has(message.id))
+            continue;
+        if (message)
+            pageEntries.push({ message, recordIndex: scanIndex });
+    }
+    let hasMore = false;
+    let eventStart = 0;
+    for (; scanIndex >= 0; scanIndex -= 1) {
+        const message = webMessageFromRecord(config, records[scanIndex], assistantName);
+        if (message && hidden.has(message.id))
+            continue;
+        if (message) {
+            hasMore = true;
+            eventStart = scanIndex + 1;
+            break;
+        }
+    }
+    const messagesById = new Map();
+    for (const entry of pageEntries)
+        messagesById.set(entry.message.id, entry);
+    for (let index = eventStart; index < end; index += 1) {
+        const record = records[index];
+        if (record.type !== "agent_event")
+            continue;
+        if (hidden.has(record.messageId))
+            continue;
+        const entry = messagesById.get(record.messageId);
+        if (!entry)
+            continue;
+        applyStoredAgentEventToMessage(entry.message, record, {
+            applyTextDeltas: index < entry.recordIndex ? !entry.message.text && !entry.message.silent : !entry.message.silent,
+            applyThinkingDeltas: index < entry.recordIndex ? !entry.message.thinking : true,
+        });
+    }
+    const page = pageEntries.reverse().map((entry) => {
+        ensureFallbackSteps(entry.message);
+        return entry.message;
+    });
+    return { messages: page, hasMore, channelKey };
+}
+export function webMessageFromRecord(config, record, assistantName) {
+    if (!isUserVisibleRuntimeRecord(record))
+        return undefined;
+    if (record.type === "inbound") {
+        return {
+            id: record.messageId,
+            role: "user",
+            who: record.authorName || getContactNickname(WEB_USER_NAME),
+            text: record.text,
+            attachments: webAttachments(config, record.attachments),
+            ts: toUnixMs(record.ts),
+        };
+    }
+    if (record.type === "outbound" && !record.control) {
+        return {
+            id: record.webMessageId || record.messageIds[0] || `out_${record.recordId}`,
+            role: "assistant",
+            who: assistantName,
+            text: record.text,
+            attachments: webAttachments(config, record.attachments),
+            thinking: record.thinking,
+            thinkingMs: record.thinkingMs,
+            silent: record.silent || undefined,
+            ts: toUnixMs(record.ts),
+        };
+    }
+    if (record.type === "runtime" || record.type === "error") {
+        return {
+            id: `sys_${record.recordId}`,
+            role: "system",
+            who: "system",
+            text: record.type === "runtime" ? record.detail || record.event : record.message,
+            ts: toUnixMs(record.ts),
+        };
+    }
+    return undefined;
+}

package/dist/web/multipart.js

@@ -0,0 +1,86 @@
+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;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > maxBytes)
+            throw new Error("Request body too large");
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+export function multipartBoundary(contentType) {
+    const header = Array.isArray(contentType) ? contentType.find((value) => value.includes("boundary=")) : contentType;
+    const match = header?.match(/boundary=(?:"([^"]+)"|([^;]+))/i);
+    if (!match?.[1] && !match?.[2])
+        throw new Error("Missing multipart boundary");
+    return match[1] ?? match[2] ?? "";
+}
+export function parseContentDisposition(header) {
+    const parts = header.split(";").map((part) => part.trim());
+    const values = {};
+    for (const part of parts.slice(1)) {
+        const [key, rawValue] = part.split("=");
+        if (!key || rawValue === undefined)
+            continue;
+        values[key.toLowerCase()] = rawValue.replace(/^"|"$/g, "");
+    }
+    return values;
+}
+export async function readMultipartBody(request, contentType) {
+    const boundary = multipartBoundary(contentType);
+    const raw = await readRawBody(request, MAX_INBOUND_TOTAL_BYTES);
+    const binary = raw.toString("binary");
+    const marker = `--${boundary}`;
+    const attachments = [];
+    const body = { text: "" };
+    for (const section of binary.split(marker).slice(1)) {
+        if (!section || section === "--\r\n" || section === "--")
+            continue;
+        const trimmed = section.replace(/^\r\n/, "").replace(/\r\n--$/, "");
+        const headerEnd = trimmed.indexOf("\r\n\r\n");
+        if (headerEnd < 0)
+            continue;
+        const headerText = trimmed.slice(0, headerEnd);
+        let contentBinary = trimmed.slice(headerEnd + 4);
+        if (contentBinary.endsWith("\r\n"))
+            contentBinary = contentBinary.slice(0, -2);
+        const headers = Object.fromEntries(headerText.split("\r\n").map((line) => {
+            const colon = line.indexOf(":");
+            return colon >= 0
+                ? [line.slice(0, colon).trim().toLowerCase(), line.slice(colon + 1).trim()]
+                : [line.toLowerCase(), ""];
+        }));
+        const disposition = parseContentDisposition(headers["content-disposition"] ?? "");
+        const name = disposition.name;
+        if (!name)
+            continue;
+        if (name === "text" || name === "channelKey" || name === "clientId") {
+            body[name] = Buffer.from(contentBinary, "binary").toString("utf8");
+            continue;
+        }
+        if (name !== "attachments")
+            continue;
+        const buffer = Buffer.from(contentBinary, "binary");
+        if (buffer.length === 0)
+            continue;
+        attachments.push({
+            name: disposition.filename,
+            mimeType: headers["content-type"],
+            size: buffer.length,
+            buffer,
+        });
+    }
+    body.attachments = attachments;
+    return body;
+}

package/dist/web/payloads.js

@@ -0,0 +1,34 @@
+import { supportedThinkingLevels } from "../models/index.js";
+import { isRecord } from "../util/guards.js";
+export function commandArgs(command, args) {
+    if (!isRecord(args))
+        return "";
+    if (command === "model")
+        return typeof args.model === "string" ? args.model : "";
+    if (command === "thinking")
+        return typeof args.level === "string" ? args.level : "";
+    if (command === "channel-trigger")
+        return typeof args.trigger === "string" ? args.trigger : "";
+    return "";
+}
+export function agentSettingsPayload(familiarAgent, channelKey, personaName) {
+    const { model } = familiarAgent.resolveChannelModel(channelKey);
+    return {
+        model: familiarAgent.getModel(channelKey),
+        thinking: familiarAgent.getThinkingLevel(channelKey),
+        supportedThinking: supportedThinkingLevels(model),
+        persona: { name: personaName },
+    };
+}
+export function sessionDto(session) {
+    return {
+        key: session.key,
+        label: session.label,
+        service: session.channel.service,
+        scope: session.channel.scope,
+        channelId: session.channel.channelId,
+        channelName: session.channel.channelName,
+        threadId: session.channel.threadId,
+        isDefault: session.isDefault,
+    };
+}

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 };
+}