@qearlyao/familiar 0.2.4 → 0.3.0

package/dist/web/event-hub.js

@@ -0,0 +1,246 @@
+import { getContactNickname } from "../contact-note.js";
+import { eventId, toUnixMs } from "../ids.js";
+import { consumeSilentDelta, createSilentFilterState, finalizeSilentFilter } from "../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");
+}

package/dist/web/messages.js

@@ -0,0 +1,345 @@
+import { hiddenWebMessageIds } from "../chat-log.js";
+import { getContactNickname } from "../contact-note.js";
+import { publicAttachmentPath } from "../generated-media.js";
+import { toUnixMs } from "../ids.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,
+    }));
+}
+export function attachmentDerivedText(attachment) {
+    if (attachment.derived?.text?.label === "preview")
+        return undefined;
+    return attachment.derived?.text?.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") {
+        const attachmentText = record.attachments
+            .map((attachment) => attachmentDerivedText(attachment))
+            .filter((text) => !!text)
+            .join("\n");
+        return {
+            id: record.messageId,
+            role: "user",
+            who: record.authorName || getContactNickname(WEB_USER_NAME),
+            text: [record.text, attachmentText].filter(Boolean).join("\n"),
+            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;
+}