@qearlyao/familiar 0.2.3 → 0.2.5

package/dist/web-tools.js

@@ -69,7 +69,7 @@ class PageCache {
             this.entries.delete(url);
             return undefined;
         }
-        entry.fetchedAt = Date.now();
+        entry.lastAccessed = Date.now();
         this.entries.delete(url);
         this.entries.set(url, entry);
         return entry;
@@ -79,10 +79,12 @@ class PageCache {
             return;
         if (this.entries.has(url))
             this.entries.delete(url);
+        const now = Date.now();
         this.entries.set(url, {
             content,
             provider,
-            fetchedAt: Date.now(),
+            fetchedAt: now,
+            lastAccessed: now,
         });
         while (this.entries.size > this.capacity) {
             const oldest = this.entries.keys().next().value;
@@ -382,7 +384,7 @@ function formatFetchContent(url, provider, chunk) {
         chunk.text,
     ];
     if (chunk.hasMore && chunk.nextOffset !== undefined) {
-        lines.push("", `[More content available. Next chunk: web_fetch(url="${url}", offset=${chunk.nextOffset})]`);
+        lines.push("", `[More content available. Next chunk: fetch_web(url="${url}", offset=${chunk.nextOffset})]`);
     }
     return prefixUntrustedWebContent(lines.join("\n"));
 }
@@ -778,7 +780,7 @@ function makeSearchTool(config) {
     if (config.apiKeys.EXA_API_KEY)
         providers.exa = createExaProvider(config.apiKeys.EXA_API_KEY);
     return {
-        name: "web_search",
+        name: "search_web",
         label: "Web Search",
         description: "look something up on the open web. returns titles, urls, snippets, and dates when present. depth=thorough swaps brevity for inline excerpts.",
         parameters: webSearchSchema,
@@ -847,7 +849,7 @@ function makeSearchTool(config) {
 function makeFetchTool(config) {
     const providers = createFetchProviders(config);
     return {
-        name: "web_fetch",
+        name: "fetch_web",
         label: "Web Fetch",
         description: "pull a webpage down as clean markdown.",
         parameters: webFetchSchema,
@@ -923,6 +925,7 @@ export function createWebTools(_config) {
 }
 export const __webToolsTest = {
     PageCache,
+    createWebTools,
     createTestSearchProvider,
     createFetchProviders,
     formatFetchContent,

package/dist/web.js

@@ -148,6 +148,8 @@ function webAttachments(config, attachments) {
     }));
 }
 function attachmentDerivedText(attachment) {
+    if (attachment.derived?.text?.label === "preview")
+        return undefined;
     return attachment.derived?.text?.text;
 }
 function toolError(result) {
@@ -216,23 +218,79 @@ function mergeToolEvent(existing, patch) {
         startedAt: existing?.startedAt ?? patch.startedAt,
     };
 }
+function stepId(messageId, kind, index) {
+    return `${messageId}-${kind}-${index}`;
+}
+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;
+    }
+}
+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 });
+}
+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 });
+}
 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" && options.applyThinkingDeltas) {
-            message.thinking = `${message.thinking ?? ""}${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" && event.usage)
-        message.usage = event.usage;
+    if (event.type === "message_end") {
+        closeOpenContentSteps(steps, ts);
+        if (event.usage)
+            message.usage = event.usage;
+    }
     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) {
@@ -244,6 +302,29 @@ function applyStoredAgentEventToMessage(message, record, options) {
         message.tools = tools;
     }
 }
+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;
+}
 function webMessagesFromRecords(config, records, assistantName) {
     const messages = [];
     const messagesById = new Map();
@@ -256,7 +337,7 @@ function webMessagesFromRecords(config, records, assistantName) {
             const pending = pendingAgentEvents.get(message.id) ?? [];
             for (const pendingRecord of pending) {
                 applyStoredAgentEventToMessage(message, pendingRecord, {
-                    applyTextDeltas: !message.text,
+                    applyTextDeltas: !message.text && !message.silent,
                     applyThinkingDeltas: !message.thinking,
                 });
             }
@@ -266,7 +347,7 @@ function webMessagesFromRecords(config, records, assistantName) {
             const existing = messagesById.get(record.messageId);
             if (existing) {
                 applyStoredAgentEventToMessage(existing, record, {
-                    applyTextDeltas: true,
+                    applyTextDeltas: !existing.silent,
                     applyThinkingDeltas: true,
                 });
             }
@@ -277,8 +358,17 @@ function webMessagesFromRecords(config, records, assistantName) {
             }
         }
     }
+    for (const message of messages)
+        ensureFallbackSteps(message);
     return messages;
 }
+function webHistoryPayload(config, records, assistantName, channelKey, options) {
+    const messages = webMessagesFromRecords(config, records, assistantName);
+    const end = options.before ? messages.findIndex((message) => message.id === options.before) : messages.length;
+    const safeEnd = end >= 0 ? end : messages.length;
+    const page = messages.slice(Math.max(0, safeEnd - options.limit), safeEnd);
+    return { messages: page, hasMore: safeEnd - options.limit > 0, channelKey };
+}
 function webMessageFromRecord(config, record, assistantName) {
     if (!isUserVisibleRuntimeRecord(record))
         return undefined;
@@ -365,9 +455,32 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
     const clients = new Set();
     const eventsByChannel = new Map();
     const runtimeSubscriptions = new Map();
-    const locallyStreamedOutboundIds = new Set();
-    const silentFilters = new Map();
-    const pendingMessageStarts = new Map();
+    const IN_FLIGHT_TTL_MS = 10 * 60 * 1000;
+    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 ?? "") ?? [];
@@ -392,16 +505,21 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
     };
     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") {
-            locallyStreamedOutboundIds.add(messageIdValue);
-            silentFilters.set(messageIdValue, createSilentFilterState());
-            pendingMessageStarts.set(messageIdValue, ts);
+            const entry = getOrCreateInFlight(messageIdValue);
+            entry.locallyStreamed = true;
+            entry.silentFilter = createSilentFilterState();
+            entry.pendingStartTs = ts;
+            entry.startedSilent = false;
         }
         const startedSilentMessage = () => {
-            if (!pendingMessageStarts.has(messageIdValue))
+            const entry = inFlightMessages.get(messageIdValue);
+            if (!entry || entry.startedSilent)
                 return false;
-            const startTs = pendingMessageStarts.get(messageIdValue);
-            pendingMessageStarts.delete(messageIdValue);
+            const startTs = entry.pendingStartTs;
+            entry.pendingStartTs = undefined;
+            entry.startedSilent = true;
             publish({
                 type: "message_started",
                 channelKey,
@@ -419,7 +537,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                 publishDelta(channelKey, messageIdValue, "thinking", assistantEvent.delta, ts);
             }
             if (assistantEvent.type === "text_delta") {
-                const filter = silentFilters.get(messageIdValue);
+                const filter = inFlightMessages.get(messageIdValue)?.silentFilter;
                 if (!filter) {
                     startedSilentMessage();
                     publishDelta(channelKey, messageIdValue, "text", assistantEvent.delta, ts);
@@ -437,9 +555,10 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
             startedSilentMessage();
         }
         if (storedEvent.type === "message_end" && storedEvent.role === "assistant") {
-            const filter = silentFilters.get(messageIdValue);
+            const entry = inFlightMessages.get(messageIdValue);
+            const filter = entry?.silentFilter;
             let silent = false;
-            if (filter) {
+            if (filter && entry) {
                 const final = finalizeSilentFilter(filter);
                 silent = final.silent;
                 if (!silent) {
@@ -449,9 +568,10 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                     }
                 }
                 else {
-                    pendingMessageStarts.delete(messageIdValue);
+                    entry.startedSilent = true;
+                    entry.pendingStartTs = undefined;
                 }
-                silentFilters.delete(messageIdValue);
+                entry.silentFilter = undefined;
             }
             else {
                 startedSilentMessage();
@@ -487,6 +607,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                     type: "message_completed",
                     channelKey: runtime.channelKey,
                     messageId: record.messageId,
+                    attachments: webAttachments(config, record.attachments),
                     ts: toUnixMs(record.ts),
                 });
             }
@@ -501,7 +622,8 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                     silent: record.silent || undefined,
                     ts: toUnixMs(record.ts),
                 };
-                if (locallyStreamedOutboundIds.delete(outboundId)) {
+                if (inFlightMessages.get(outboundId)?.locallyStreamed) {
+                    inFlightMessages.delete(outboundId);
                     publish(completion);
                     return;
                 }
@@ -638,7 +760,8 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
             attachments: webAttachments(config, reply.attachments),
             silent: parsed.silent || undefined,
         });
-        locallyStreamedOutboundIds.add(assistantMessageId);
+        const entry = getOrCreateInFlight(assistantMessageId);
+        entry.locallyStreamed = true;
         return {
             text: finalText,
             messageId: assistantMessageId,
@@ -744,12 +867,8 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
             if (request.method === "GET" && url.pathname === "/api/web/history") {
                 const runtime = await getRuntime(getChannelKeyFromRequest(url));
                 const limit = Math.min(Math.max(Number(url.searchParams.get("limit") ?? 50) || 50, 1), 200);
-                const before = url.searchParams.get("before");
-                const messages = webMessagesFromRecords(config, runtime.getRecords(), personaName);
-                const end = before ? messages.findIndex((message) => message.id === before) : messages.length;
-                const safeEnd = end >= 0 ? end : messages.length;
-                const page = messages.slice(Math.max(0, safeEnd - limit), safeEnd);
-                sendJson(response, 200, { messages: page, hasMore: safeEnd - limit > 0, channelKey: runtime.channelKey });
+                const before = url.searchParams.get("before") ?? undefined;
+                sendJson(response, 200, webHistoryPayload(config, runtime.getRecords(), personaName, runtime.channelKey, { limit, before }));
                 return true;
             }
             if (request.method === "GET" && url.pathname === "/api/web/agent/settings") {
@@ -1010,49 +1129,53 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
             netSocket.destroy();
             return;
         }
-        if (!acceptWebSocket(request, netSocket))
-            return;
-        netSocket.setNoDelay(true);
         const requestedChannelKey = url.searchParams.get("channelKey") || undefined;
-        const client = { socket: netSocket, channelKey: requestedChannelKey, authed: false };
-        clients.add(client);
-        let frameBuffer = Buffer.alloc(0);
         void getRuntime(requestedChannelKey)
             .then((runtime) => {
-            client.channelKey = runtime.channelKey;
+            if (netSocket.destroyed)
+                return;
+            if (!acceptWebSocket(request, netSocket))
+                return;
+            netSocket.setNoDelay(true);
+            const client = { socket: netSocket, channelKey: runtime.channelKey, authed: false };
+            clients.add(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) {
+                        const message = JSON.parse(raw);
+                        if (isObject(message) && message.type === "hello") {
+                            if (!client.channelKey)
+                                continue;
+                            replay(client, client.channelKey, typeof message.lastEventId === "string" ? message.lastEventId : null);
+                        }
+                        if (isObject(message) && message.type === "abort") {
+                            void getRuntime(client.channelKey).then(async (runtime) => {
+                                familiarAgent.requestSoftStop(runtime.channelKey);
+                            });
+                        }
+                    }
+                }
+                catch (error) {
+                    console.error("WebSocket frame handling failed", error);
+                    netSocket.destroy();
+                }
+            });
+            netSocket.on("close", () => clients.delete(client));
+            netSocket.on("error", () => clients.delete(client));
         })
             .catch((error) => {
             console.error("WebSocket runtime lookup failed", error);
-            netSocket.destroy();
-        });
-        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) {
-                    const message = JSON.parse(raw);
-                    if (isObject(message) && message.type === "hello") {
-                        if (!client.channelKey)
-                            continue;
-                        replay(client, client.channelKey, typeof message.lastEventId === "string" ? message.lastEventId : null);
-                    }
-                    if (isObject(message) && message.type === "abort") {
-                        void getRuntime(client.channelKey).then(async (runtime) => {
-                            familiarAgent.requestSoftStop(runtime.channelKey);
-                        });
-                    }
-                }
-            }
-            catch (error) {
-                console.error("WebSocket frame handling failed", error);
+            if (!netSocket.destroyed) {
+                netSocket.write("HTTP/1.1 503 Service Unavailable\r\n\r\n");
                 netSocket.destroy();
             }
         });
-        netSocket.on("close", () => clients.delete(client));
-        netSocket.on("error", () => clients.delete(client));
     });
     await new Promise((resolveListen, rejectListen) => {
         server.once("error", rejectListen);
@@ -1065,6 +1188,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
     return {
         server,
         async stop() {
+            clearInterval(inFlightGcTimer);
             for (const client of clients)
                 client.socket.destroy();
             clients.clear();
@@ -1080,4 +1204,6 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
 export const __webTest = {
     memeCatalogPath,
     parseMemeCatalog,
+    webHistoryPayload,
+    webMessagesFromRecords,
 };

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "@qearlyao/familiar",
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@qearlyao/familiar",
-			"version": "0.2.3",
+			"version": "0.2.5",
 			"license": "MIT",
 			"dependencies": {
 				"@earendil-works/pi-agent-core": "0.75.5",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@qearlyao/familiar",
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"license": "MIT",
 	"type": "module",
 	"repository": {