@moltzap/client 2026.511.0 → 2026.518.0

package/dist/service.js

@@ -1,50 +1,39 @@
-import * as net from "node:net";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
+import { FileSystem, Path } from "@effect/platform";
+import { NodeContext } from "@effect/platform-node";
 import { AgentsLookup, AgentsLookupByName, ConversationsCreate, ConversationsGet, DispatchRequest, DispatchRelease, DispatchesConsumed, DispatchesExpired, DispatchesGet, MessageReceivedNotificationDefinition, ConversationCreatedNotificationDefinition, ConversationUpdatedNotificationDefinition, ConversationArchivedNotificationDefinition, ConversationUnarchivedNotificationDefinition, ConversationArchivedError, MessagesList, MessagesSend, NotConnectedError, rpcMethods, RpcServerError, RpcTimeoutError, } from "@moltzap/protocol";
-import { Config, ConfigProvider, Data, Effect, HashMap, Match, Option, Ref, } from "effect";
-import { MoltZapWsClient, } from "./ws-client.js";
+import { Config, ConfigProvider, Effect, HashMap, Option, Ref, Scope, } from "effect";
+import { MoltZapWsClient } from "./ws-client.js";
 import { AgentNotFoundError } from "./runtime/errors.js";
 import { getOr, snapshot } from "./runtime/refs.js";
 import { LocalServiceCommands } from "./runtime/local-service-commands.js";
-const isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+import { getMoltZapAgentServiceSocketPath, getMoltZapServiceSocketPath, } from "./local-paths.js";
+import { startLocalSocketServer, stopLocalSocketServer, } from "./runtime/local-socket-server.js";
+import { buildContextEntries, makeContextCandidate, newMessagesForConversation, notificationTraceRecord, renderPart, ServiceInputError, } from "./runtime/service-helpers.js";
+import { decodeHistoryRequest, formatHistoryMessage, lastReadIdsForSession, } from "./runtime/local-history.js";
 const CROSS_CONTEXT_TEXT_LIMIT = 120;
-const DEFAULT_HISTORY_LIMIT = 10;
 const DEFAULT_MAX_CONTEXT_CONVERSATIONS = 5;
 const DEFAULT_MAX_MESSAGES_PER_CONVERSATION = 3;
 const HISTORY_LOOKUP_CONCURRENCY = 2;
-const MILLISECONDS_PER_MINUTE = 60_000;
-const SOCKET_FILE_MODE = 0o600;
-class ServiceInputError extends Data.TaggedError("ServiceInputError") {
-}
 const ClientEventLogDir = Config.option(Config.string("MOLTZAP_CLIENT_EVENT_LOG_DIR"));
 const getClientEventLogDir = () => Option.getOrUndefined(Effect.runSync(ClientEventLogDir.pipe(Effect.withConfigProvider(ConfigProvider.fromEnv()))));
 function appendClientEventTrace(record) {
     const dir = getClientEventLogDir();
     if (!dir)
-        return;
-    try {
-        fs.mkdirSync(dir, { recursive: true });
+        return Effect.void;
+    return Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
         const agentId = typeof record["agentId"] === "string" ? record["agentId"] : "unknown";
         const safeAgentId = /^[A-Za-z0-9_-]+$/.test(agentId) ? agentId : "unknown";
-        fs.appendFileSync(path.join(dir, `client-events-${safeAgentId}.jsonl`), JSON.stringify(record) + "\n");
-    }
-    catch (err) {
-        try {
-            process.stderr.write(`moltzap client event trace write failed: ${err instanceof Error ? err.message : String(err)}\n`);
-        }
-        catch (stderrErr) {
-            void stderrErr;
-        }
-    }
+        yield* Effect.zipRight(fileSystem.makeDirectory(dir, { recursive: true }), fileSystem.writeFileString(path.join(dir, `client-events-${safeAgentId}.jsonl`), JSON.stringify(record) + "\n", { flag: "a" }));
+    }).pipe(Effect.withSpan("appendClientEventTrace"), Effect.provide(NodeContext.layer), Effect.catchAll((err) => Effect.logWarning("moltzap client event trace write failed", err)));
 }
-/** Escape `<`, `>`, `&` so sender content can't escape a `<system-reminder>` block. */
+/** Escape `&lt;`, `>`, `&amp;` so sender content can't escape a `&lt;system-reminder>` block. */
 export function sanitizeForSystemReminder(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 /**
- * Format CrossConversationEntry[] as a `<system-reminder>` block. Adapters
+ * Format CrossConversationEntry[] as a `&lt;system-reminder>` block. Adapters
  * that inline context into prompt text (nanoclaw) and `MoltZapService.getContext`
  * share this formatter so sanitization and line shape stay in one place.
  */
@@ -63,28 +52,30 @@ export function formatCrossConversationBlock(entries, opts) {
         "</system-reminder>",
     ].join("\n");
 }
-const renderPart = Match.type().pipe(Match.discriminatorsExhaustive("type")({
-    text: (t) => t.text,
-    image: () => "[image]",
-    file: (f) => `[file: ${f.name}]`,
-}));
 /**
  * Per-conversation message cap. Older messages are evicted FIFO; the
  * on-disk history remains the source of truth. Sized for typical CLI
  * display windows — `conversations get` shows at most a few hundred.
  */
 const MAX_MESSAGES_PER_CONV = 1000;
+/**
+ * Per-conversation dedup window. Inbound messageIds are tracked in a
+ * Set bounded to this size; once full, the insertion-ordered oldest
+ * entry is evicted to make room. 1000 × 36 bytes per UUID ≈ 36 KB per
+ * conversation — bounded and negligible for the expected conversation count.
+ */
+const DEDUP_WINDOW_PER_CONV = 1000;
 /**
  * Invoke every handler with `arg`, isolating throws so one bad handler
- * doesn't abort the remaining fanout. Logs via the optional client logger.
+ * doesn't abort the remaining fanout.
  */
-function fanout(handlers, arg, logger) {
+function fanout(handlers, arg) {
     for (const h of handlers) {
         try {
             h(arg);
         }
         catch (err) {
-            logger?.error("notification handler threw", err);
+            Effect.runFork(Effect.logError("notification handler threw", err));
         }
     }
 }
@@ -110,6 +101,16 @@ export class MoltZapService {
     lastNotifiedRef = Effect.runSync(Ref.make(HashMap.empty()));
     lastReadRef = Effect.runSync(Ref.make(HashMap.empty()));
     archivedConversationIds = new Set();
+    /**
+     * Insertion-ordered set of recently seen messageIds per conversation.
+     * Bounded at DEDUP_WINDOW_PER_CONV entries per conversation; oldest entry
+     * is evicted when the window is full. Set#keys() preserves insertion
+     * order in V8 / the spec, so eviction via `.next()` is O(1).
+     *
+     * Keyed and valued by their branded ids so the compiler rejects a
+     * `MessageId` accidentally used as a conversation key (or vice versa).
+     */
+    seenMessageIds = new Map();
     handlers = {
         message: [],
         rawNotification: [],
@@ -121,6 +122,40 @@ export class MoltZapService {
         dispatchesConsumed: [],
         dispatchesExpired: [],
     };
+    notificationDispatchers = new Map([
+        [
+            MessageReceivedNotificationDefinition,
+            (notification) => this.handleMessageReceivedNotification(notification.params),
+        ],
+        [
+            ConversationCreatedNotificationDefinition,
+            (notification) => this.handleConversationCreatedNotification(notification.params),
+        ],
+        [
+            ConversationUpdatedNotificationDefinition,
+            (notification) => this.handleConversationUpdatedNotification(notification.params),
+        ],
+        [
+            ConversationArchivedNotificationDefinition,
+            (notification) => this.handleConversationArchivedNotification(notification.params),
+        ],
+        [
+            ConversationUnarchivedNotificationDefinition,
+            (notification) => this.handleConversationUnarchivedNotification(notification.params),
+        ],
+        [
+            DispatchRelease,
+            (notification) => fanout(this.handlers.dispatchRelease, notification.params),
+        ],
+        [
+            DispatchesConsumed,
+            (notification) => fanout(this.handlers.dispatchesConsumed, notification.params),
+        ],
+        [
+            DispatchesExpired,
+            (notification) => fanout(this.handlers.dispatchesExpired, notification.params),
+        ],
+    ]);
     _ownAgentId;
     constructor(opts) {
         this.opts = opts;
@@ -137,18 +172,16 @@ export class MoltZapService {
             this.client = new MoltZapWsClient({
                 serverUrl: this.opts.serverUrl,
                 agentKey: this.opts.agentKey,
-                logger: this.opts.logger,
                 // Spec #222 OQ-6: arg required. The body doesn't branch on
                 // close metadata today; signature kept explicit so a future
                 // disconnect-handler chain can plumb code/reason through.
-                onDisconnect: (close) => {
-                    void close;
+                onDisconnect: () => {
                     this._connected = false;
-                    fanout(this.handlers.disconnect, undefined, this.opts.logger);
+                    fanout(this.handlers.disconnect, undefined);
                 },
                 onReconnect: (helloOk) => {
                     this._connected = true;
-                    fanout(this.handlers.reconnect, helloOk, this.opts.logger);
+                    fanout(this.handlers.reconnect, helloOk);
                 },
             });
             // Spec #222 OQ-4: per-notification callback is replaced by subscriptions.
@@ -165,15 +198,15 @@ export class MoltZapService {
     }
     /**
      * Tear down the service. `close()` is sync because it fans out to the
-     * socket server, Refs, and the ws-client — the ws-client's own close
-     * Effect is run via `Effect.runSync` here so the caller gets an immediate
-     * shutdown the way existing code expects.
+     * socket server, Refs, and the ws-client. Effectful network/filesystem
+     * cleanup is forked at the edge so existing callers still get immediate
+     * shutdown.
      */
     close() {
         this._connected = false;
-        this.stopSocketServer();
+        Effect.runFork(this.stopSocketServer());
         if (this.client) {
-            void Effect.runPromise(this.client.close());
+            Effect.runFork(this.client.close());
         }
         this.client = null;
         Effect.runSync(Effect.all([
@@ -185,16 +218,17 @@ export class MoltZapService {
             Ref.set(this.lastReadRef, HashMap.empty()),
         ]));
         this.archivedConversationIds.clear();
+        this.seenMessageIds.clear();
         // Handlers are preserved across close()/connect() cycles. MoltZapChannelCore
         // subscribes once in its constructor; clearing handlers here would silently
         // drop inbound/reconnect dispatch on any subsequent reconnect of the same
         // service instance.
     }
     // --- Socket Server ---
-    socketServer = null;
+    socketServerScope = null;
     activeSocketPath = null;
     /** Default socket path for CLI discovery. Per-instance path uses agentId. */
-    static SOCKET_PATH = path.join(os.homedir(), ".moltzap", "service.sock");
+    static SOCKET_PATH = getMoltZapServiceSocketPath();
     /**
      * `agentId` is a server-assigned string. Treat it as untrusted: if a
      * compromised or malicious server returns an id containing `..` or a
@@ -207,127 +241,39 @@ export class MoltZapService {
     /** Per-instance socket path based on connected agentId. */
     get socketPath() {
         const id = MoltZapService.safeAgentIdSegment(this.ownAgentId ?? "default");
-        return path.join(os.homedir(), ".moltzap", `service-${id}.sock`);
+        return getMoltZapAgentServiceSocketPath(id);
     }
     startSocketServer() {
-        const sockPath = this.socketPath;
-        this.activeSocketPath = sockPath;
-        try {
-            fs.unlinkSync(sockPath);
-        }
-        catch (err) {
-            // ENOENT is the normal case (no stale socket); log everything
-            // else (permission denied, EACCES) so operators can diagnose.
-            const code = err.code;
-            if (code !== "ENOENT") {
-                this.opts.logger?.warn("unlink existing socket failed", err);
-            }
-        }
-        fs.mkdirSync(path.dirname(sockPath), { recursive: true });
-        this.socketServer = net.createServer((conn) => {
-            let buffer = "";
-            conn.on("data", (chunk) => {
-                buffer += chunk.toString();
-                const lines = buffer.split("\n");
-                buffer = lines.pop();
-                for (const line of lines) {
-                    if (!line.trim())
-                        continue;
-                    // Fork the line-handler Effect onto the Effect runtime. Each line
-                    // dispatches independently; the fiber runs until it writes a
-                    // response or error frame back onto the socket.
-                    Effect.runFork(this.handleSocketLineEffect(line, conn));
-                }
+        return Effect.gen(this, function* () {
+            const previous = this.resetSocketServerState();
+            yield* stopLocalSocketServer({
+                socketScope: previous.socketScope,
+                socketPath: previous.sockPath,
+                defaultSocketPath: MoltZapService.SOCKET_PATH,
             });
-        });
-        this.socketServer.listen(sockPath, () => {
-            // Owner-only permissions: the socket exposes an RPC passthrough that
-            // impersonates this agent to the server, so other local users on the
-            // host must not be able to connect.
-            try {
-                fs.chmodSync(sockPath, SOCKET_FILE_MODE);
-            }
-            catch (err) {
-                this.opts.logger?.warn("chmod 0600 on socket failed", err);
-            }
-        });
-        // Symlink default path to this instance for CLI discovery
-        try {
-            fs.unlinkSync(MoltZapService.SOCKET_PATH);
-        }
-        catch (err) {
-            // Stale/missing default symlink is expected most of the time; log
-            // at debug so real permission errors still surface.
-            this.opts.logger?.info("unlink default socket symlink", err);
-        }
-        try {
-            fs.symlinkSync(sockPath, MoltZapService.SOCKET_PATH);
-        }
-        catch (err) {
-            this.opts.logger?.warn("symlink default socket failed", err);
-        }
+            const running = yield* startLocalSocketServer({
+                socketPath: this.socketPath,
+                defaultSocketPath: MoltZapService.SOCKET_PATH,
+                handleRequest: (method, params) => this.handleSocketRequestEffect(method, params),
+            });
+            this.socketServerScope = running.socketScope;
+            this.activeSocketPath = running.socketPath;
+        }).pipe(Effect.withSpan("MoltZapService.startSocketServer"));
     }
-    stopSocketServer() {
-        this.socketServer?.close();
-        this.socketServer = null;
+    resetSocketServerState() {
+        const socketScope = this.socketServerScope;
+        this.socketServerScope = null;
         const sockPath = this.activeSocketPath ?? this.socketPath;
         this.activeSocketPath = null;
-        try {
-            fs.unlinkSync(sockPath);
-        }
-        catch (err) {
-            this.opts.logger?.info("unlink socket path", err);
-        }
-        // Remove default symlink only if it points to this instance.
-        try {
-            const target = fs.readlinkSync(MoltZapService.SOCKET_PATH);
-            if (target === sockPath)
-                fs.unlinkSync(MoltZapService.SOCKET_PATH);
-        }
-        catch (err) {
-            this.opts.logger?.info("cleanup default symlink", err);
-        }
+        return { socketScope, sockPath };
     }
-    /**
-     * Handle one JSON line from the unix socket as an Effect. Parses the
-     * request, dispatches through `handleSocketRequestEffect`, and writes
-     * either a `{result}` or `{error}` frame back onto the connection.
-     * Never fails — all branches resolve into a `conn.write` side effect.
-     */
-    handleSocketLineEffect(line, conn) {
-        return Effect.suspend(() => {
-            let req;
-            try {
-                const parsed = JSON.parse(line);
-                if (!isPlainRecord(parsed)) {
-                    return Effect.sync(() => conn.write(JSON.stringify({
-                        error: "request must be a JSON object",
-                    }) + "\n"));
-                }
-                req = parsed;
-            }
-            catch (err) {
-                return Effect.sync(() => conn.write(JSON.stringify({
-                    error: err instanceof Error ? err.message : String(err),
-                }) + "\n"));
-            }
-            if (typeof req.method !== "string" || !req.method) {
-                return Effect.sync(() => conn.write(JSON.stringify({
-                    error: "method is required and must be a string",
-                }) + "\n"));
-            }
-            const params = isPlainRecord(req.params) ? req.params : {};
-            return this.handleSocketRequestEffect(req.method, params).pipe(Effect.match({
-                onSuccess: (result) => {
-                    conn.write(JSON.stringify({ result }) + "\n");
-                },
-                onFailure: (err) => {
-                    conn.write(JSON.stringify({
-                        error: err instanceof Error ? err.message : String(err),
-                    }) + "\n");
-                },
-            }));
-        });
+    stopSocketServer() {
+        const { socketScope, sockPath } = this.resetSocketServerState();
+        return stopLocalSocketServer({
+            socketScope,
+            socketPath: sockPath,
+            defaultSocketPath: MoltZapService.SOCKET_PATH,
+        }).pipe(Effect.withSpan("MoltZapService.stopSocketServer"));
     }
     handleSocketRequestEffect(method, params) {
         return Effect.suspend(() => {
@@ -344,7 +290,8 @@ export class MoltZapService {
                     return this.handleHistoryRequest(params);
                 default: {
                     const definition = rpcMethods.find((d) => d.name === method);
-                    if (definition === undefined || !definition.validateParams(params)) {
+                    if (definition === undefined ||
+                        !definition.validateParams(params)) {
                         return Effect.fail(new ServiceInputError({
                             message: `unknown or invalid RPC method: ${method}`,
                         }));
@@ -356,85 +303,80 @@ export class MoltZapService {
     }
     handleHistoryRequest(params) {
         return Effect.gen(this, function* () {
-            if (typeof params.conversationId !== "string" || !params.conversationId) {
-                return yield* Effect.fail(new ServiceInputError({
-                    message: "conversationId is required and must be a string",
-                }));
-            }
-            if (params.limit !== undefined && typeof params.limit !== "number") {
-                return yield* Effect.fail(new ServiceInputError({ message: "limit must be a number" }));
-            }
-            const convId = params.conversationId;
-            const limit = params.limit ?? DEFAULT_HISTORY_LIMIT;
-            const sessionKey = params.sessionKey;
+            const request = yield* decodeHistoryRequest(params);
             const result = yield* this.sendRpc(MessagesList, {
-                conversationId: convId,
-                limit,
+                conversationId: request.conversationId,
+                limit: request.limit,
             });
-            // Resolve agent names (batch) + fetch conversation metadata (concurrent)
-            const knownNames = yield* Ref.get(this.agentNamesRef);
-            const unknownAgentIds = [
-                ...new Set(result.messages.map((m) => m.senderId)),
-            ].filter((id) => !HashMap.has(knownNames, id));
-            const lookupEff = unknownAgentIds.length > 0
-                ? this.sendRpc(AgentsLookup, { agentIds: unknownAgentIds }).pipe(Effect.tap((res) => {
-                    return Ref.update(this.agentNamesRef, (names) => {
-                        let next = names;
-                        for (const a of res.agents) {
-                            next = HashMap.set(next, a.id, a.name);
-                        }
-                        return next;
-                    });
-                }), Effect.asVoid, Effect.catchAll(() => Effect.void))
-                : Effect.void;
-            const metaEff = this.sendRpc(ConversationsGet, {
-                conversationId: convId,
-            }).pipe(Effect.map((res) => res.conversation), Effect.catchAll(() => Effect.succeed(undefined)));
-            const [, convMeta] = yield* Effect.all([lookupEff, metaEff], {
-                concurrency: HISTORY_LOOKUP_CONCURRENCY,
-            });
-            // Determine what's "new" using lastRead (not lastNotified).
-            // lastNotified is advanced by getContext() (system-reminder).
-            // lastRead is advanced here when the agent explicitly reads history.
-            const allAgentNames = yield* Ref.get(this.agentNamesRef);
+            const convMeta = yield* this.loadHistorySupportData(request.conversationId, result.messages);
+            const agentNames = yield* Ref.get(this.agentNamesRef);
             const lastReadMap = yield* Ref.get(this.lastReadRef);
-            const lastReadIds = sessionKey
-                ? Option.getOrElse(Option.flatMap(HashMap.get(lastReadMap, sessionKey), (perConv) => HashMap.get(perConv, convId)), () => new Set())
-                : new Set();
-            const messages = result.messages.map((m) => {
-                const text = m.parts.map(renderPart).join(" ");
-                const senderName = Option.getOrElse(HashMap.get(allAgentNames, m.senderId), () => m.senderId);
-                return {
-                    id: m.id,
-                    senderId: m.senderId,
-                    senderName: m.senderId === this.ownAgentId ? "you" : senderName,
-                    isOwn: m.senderId === this.ownAgentId,
-                    text,
-                    createdAt: m.createdAt,
-                    isNew: sessionKey ? !lastReadIds.has(m.id) : false,
-                };
-            });
-            // Advance lastRead to include all message IDs in the returned page.
-            if (sessionKey && result.messages.length > 0) {
-                yield* Ref.update(this.lastReadRef, (outer) => {
-                    const perSession = getOr(outer, sessionKey, () => HashMap.empty());
-                    const existing = getOr(perSession, convId, () => new Set());
-                    if (result.messages.every((m) => existing.has(m.id)))
-                        return outer;
-                    const nextSet = new Set(existing);
-                    for (const m of result.messages)
-                        nextSet.add(m.id);
-                    return HashMap.set(outer, sessionKey, HashMap.set(perSession, convId, nextSet));
-                });
-            }
+            const lastReadIds = lastReadIdsForSession(lastReadMap, request);
+            const messages = result.messages.map((message) => formatHistoryMessage(message, {
+                agentNames,
+                ownAgentId: this.ownAgentId,
+                lastReadIds,
+                hasSessionKey: request.sessionKey !== undefined,
+            }));
+            yield* this.advanceHistoryLastRead(request, result.messages);
             return {
                 messages,
                 hasMore: result.hasMore,
                 conversationMeta: convMeta,
-                newCount: messages.filter((m) => m.isNew).length,
+                newCount: messages.filter((message) => message.isNew).length,
             };
         });
     }
+    loadHistorySupportData(convId, messages) {
+        return Effect.gen(this, function* () {
+            const [, convMeta] = yield* Effect.all([
+                this.refreshHistoryAgentNames(messages),
+                this.fetchHistoryConversationMeta(convId),
+            ], {
+                concurrency: HISTORY_LOOKUP_CONCURRENCY,
+            });
+            return convMeta;
+        });
+    }
+    refreshHistoryAgentNames(messages) {
+        return Effect.gen(this, function* () {
+            const knownNames = yield* Ref.get(this.agentNamesRef);
+            const unknownAgentIds = [
+                ...new Set(messages.map((message) => message.senderId)),
+            ].filter((id) => !HashMap.has(knownNames, id));
+            if (unknownAgentIds.length === 0)
+                return;
+            yield* this.sendRpc(AgentsLookup, { agentIds: unknownAgentIds }).pipe(Effect.tap((result) => Ref.update(this.agentNamesRef, (names) => {
+                let next = names;
+                for (const agent of result.agents) {
+                    next = HashMap.set(next, agent.id, agent.name);
+                }
+                return next;
+            })), Effect.asVoid, Effect.catchAll(() => Effect.void));
+        });
+    }
+    fetchHistoryConversationMeta(convId) {
+        return this.sendRpc(ConversationsGet, {
+            conversationId: convId,
+        }).pipe(Effect.map((result) => result.conversation), Effect.catchAll(() => Effect.succeed(undefined)));
+    }
+    advanceHistoryLastRead(request, messages) {
+        if (request.sessionKey === undefined || messages.length === 0) {
+            return Effect.void;
+        }
+        const { conversationId, sessionKey } = request;
+        return Ref.update(this.lastReadRef, (outer) => {
+            const perSession = getOr(outer, sessionKey, () => HashMap.empty());
+            const existing = getOr(perSession, conversationId, () => new Set());
+            if (messages.every((message) => existing.has(message.id)))
+                return outer;
+            const nextSet = new Set(existing);
+            for (const message of messages) {
+                nextSet.add(message.id);
+            }
+            return HashMap.set(outer, sessionKey, HashMap.set(perSession, conversationId, nextSet));
+        });
+    }
     // --- Conversations ---
     getConversation(convId) {
         return Option.getOrUndefined(HashMap.get(snapshot(this.conversationsRef), convId));
@@ -538,7 +480,8 @@ export class MoltZapService {
      * per viewing conversation and advanced after notification.
      */
     getContext(currentConvId, opts) {
-        const { entries, commit } = this.peekContextEntries(currentConvId, opts);
+        const contextOptions = opts ?? {};
+        const { entries, commit } = this.peekContextEntries(currentConvId, contextOptions);
         if (entries.length === 0)
             return null;
         commit();
@@ -555,40 +498,9 @@ export class MoltZapService {
     peekContextEntries(currentConvId, opts) {
         const maxConvs = opts?.maxConversations ?? DEFAULT_MAX_CONTEXT_CONVERSATIONS;
         const maxMsgsPerConv = opts?.maxMessagesPerConv ?? DEFAULT_MAX_MESSAGES_PER_CONVERSATION;
-        const { messagesMap, conversationsMap, agentNamesMap, viewMarkers } = this.readCrossConvState(currentConvId);
-        // Collect all candidate conversations with their last-message timestamp,
-        // then sort by recency before applying `maxConvs`. HashMap iteration
-        // order is hash-based (not insertion/recency), so without the sort the
-        // maxConvs truncation would pick an arbitrary subset and could omit the
-        // freshest conversations.
-        const candidates = [];
-        for (const [convId, newMsgs] of this.iterNewMessagesByConv(messagesMap, viewMarkers, currentConvId)) {
-            const last = newMsgs[newMsgs.length - 1];
-            candidates.push({
-                convId,
-                newMsgs,
-                lastTs: new Date(last.createdAt).getTime(),
-            });
-        }
-        candidates.sort((a, b) => b.lastTs - a.lastTs);
-        const entries = [];
-        const pendingAdvances = [];
-        for (const { convId, newMsgs } of candidates.slice(0, maxConvs)) {
-            const reportable = newMsgs.slice(-maxMsgsPerConv);
-            const last = reportable[reportable.length - 1];
-            const senderName = getOr(agentNamesMap, last.senderId, () => last.senderId);
-            const minutesAgo = Math.max(0, Math.round((Date.now() - new Date(last.createdAt).getTime()) /
-                MILLISECONDS_PER_MINUTE));
-            entries.push({
-                conversationId: convId,
-                conversationName: Option.getOrUndefined(HashMap.get(conversationsMap, convId))?.name,
-                senderName,
-                text: last.parts.map(renderPart).join(" "),
-                minutesAgo,
-                count: reportable.length,
-            });
-            pendingAdvances.push([convId, last.id]);
-        }
+        const state = this.readCrossConvState(currentConvId);
+        const candidates = this.collectContextCandidates(state, currentConvId);
+        const { entries, pendingAdvances } = buildContextEntries(candidates.slice(0, maxConvs), state, maxMsgsPerConv);
         return {
             entries,
             commit: () => this.advanceLastNotified(currentConvId, pendingAdvances),
@@ -632,18 +544,19 @@ export class MoltZapService {
             viewMarkers: getOr(lastNotifiedMap, currentConvId, () => HashMap.empty()),
         };
     }
+    collectContextCandidates(state, currentConvId) {
+        const candidates = [];
+        for (const [convId, newMsgs] of this.iterNewMessagesByConv(state.messagesMap, state.viewMarkers, currentConvId)) {
+            candidates.push(makeContextCandidate(convId, newMsgs));
+        }
+        candidates.sort((a, b) => b.lastTs - a.lastTs);
+        return candidates;
+    }
     *iterNewMessagesByConv(messagesMap, viewMarkers, currentConvId) {
         for (const [convId, msgs] of messagesMap) {
-            if (convId === currentConvId || msgs.length === 0)
-                continue;
-            const lastSeenId = Option.getOrUndefined(HashMap.get(viewMarkers, convId));
-            const lastSeenIdx = lastSeenId
-                ? msgs.findIndex((m) => m.id === lastSeenId)
-                : -1;
-            const newMsgs = msgs.slice(lastSeenIdx + 1);
-            if (newMsgs.length === 0)
-                continue;
-            yield [convId, newMsgs];
+            const newMsgs = newMessagesForConversation(convId, msgs, viewMarkers, currentConvId);
+            if (newMsgs.length > 0)
+                yield [convId, newMsgs];
         }
     }
     advanceLastNotified(currentConvId, pendingAdvances) {
@@ -698,79 +611,60 @@ export class MoltZapService {
         Effect.catchAll(() => Effect.void));
     }
     handleNotification(notification) {
-        const params = isPlainRecord(notification.params)
-            ? notification.params
-            : {};
-        const message = isPlainRecord(params["message"])
-            ? params["message"]
-            : undefined;
-        const conversation = isPlainRecord(params["conversation"])
-            ? params["conversation"]
-            : undefined;
-        const notificationConversationId = typeof params["conversationId"] === "string"
-            ? params["conversationId"]
-            : undefined;
-        appendClientEventTrace({
-            ts: new Date().toISOString(),
-            agentId: this._ownAgentId ?? "unknown",
-            notification: notification.method,
-            messageId: message?.["id"],
-            messageConversationId: message?.["conversationId"],
-            messageSenderId: message?.["senderId"],
-            conversationId: conversation?.["id"] ?? notificationConversationId,
-            conversationName: conversation?.["name"],
-        });
-        fanout(this.handlers.rawNotification, notification, this.opts.logger);
-        // Direct descriptor-keyed dispatch. Each branch narrows on the
-        // descriptor identity carried by the decoded notification — same
-        // payload-validation guarantee as before, without the extra
-        // group-decoder indirection (params were validated upstream by
-        // `decodeServerInbound` / `decodeFrames`).
-        switch (notification.definition) {
-            case MessageReceivedNotificationDefinition:
-                this.handleMessageReceivedNotification(notification.params);
-                return;
-            case ConversationCreatedNotificationDefinition:
-                this.handleConversationCreatedNotification(notification.params);
-                return;
-            case ConversationUpdatedNotificationDefinition:
-                this.handleConversationUpdatedNotification(notification.params);
-                return;
-            case ConversationArchivedNotificationDefinition: {
-                const params = notification.params;
-                this.markConversationArchived(params.conversationId);
-                fanout(this.handlers.conversationArchived, params, this.opts.logger);
-                return;
-            }
-            case ConversationUnarchivedNotificationDefinition: {
-                const params = notification.params;
-                this.archivedConversationIds.delete(params.conversationId);
-                fanout(this.handlers.conversationUnarchived, params, this.opts.logger);
-                return;
-            }
-            case DispatchRelease:
-                fanout(this.handlers.dispatchRelease, notification.params, this.opts.logger);
-                return;
-            case DispatchesConsumed:
-                fanout(this.handlers.dispatchesConsumed, notification.params, this.opts.logger);
-                return;
-            case DispatchesExpired:
-                fanout(this.handlers.dispatchesExpired, notification.params, this.opts.logger);
-                return;
-            default:
-                // Other notification descriptors flow through `rawNotification`
-                // fanout above; the service has no typed bridge for them.
-                return;
+        this.recordNotificationTrace(notification);
+        fanout(this.handlers.rawNotification, notification);
+        this.dispatchTypedNotification(notification);
+    }
+    recordNotificationTrace(notification) {
+        Effect.runFork(appendClientEventTrace(notificationTraceRecord(notification, this._ownAgentId)));
+    }
+    dispatchTypedNotification(notification) {
+        const dispatch = this.notificationDispatchers.get(notification.definition);
+        if (dispatch === undefined) {
+            return;
         }
+        dispatch(notification);
+    }
+    /**
+     * Record `messageId` in the per-conversation dedup window. Returns
+     * `true` when the id is new (caller proceeds), `false` when the id is
+     * a duplicate within the window (caller drops). On a new id, evicts
+     * the oldest entry if the window is full.
+     *
+     * Bound to the live `messages/received` notification path: a single
+     * server-side broadcast that surfaces the same id twice (network
+     * replay, dual subscription) is suppressed to one
+     * `on("message", ...)` event. `messages/list` returns raw history
+     * unfiltered; consumers that combine both feeds dedup themselves.
+     */
+    recordMessageIdIfNew(convId, msgId) {
+        let dedupSet = this.seenMessageIds.get(convId);
+        if (dedupSet === undefined) {
+            dedupSet = new Set();
+            this.seenMessageIds.set(convId, dedupSet);
+        }
+        if (dedupSet.has(msgId)) {
+            return false;
+        }
+        if (dedupSet.size >= DEDUP_WINDOW_PER_CONV) {
+            // size >= 1 guaranteed by the guard above; next().value is defined.
+            dedupSet.delete(dedupSet.keys().next().value);
+        }
+        dedupSet.add(msgId);
+        return true;
     }
     handleMessageReceivedNotification(notification) {
         const msg = notification.message;
+        const convId = msg.conversationId;
+        if (!this.recordMessageIdIfNew(convId, msg.id)) {
+            return;
+        }
         this.storeMessage(msg);
         // Name resolution is driven lazily by channel-core's serialized consumer
         // via resolveAgentName(), which populates agentNamesRef on first miss and
         // hits the cache on every subsequent message.
         if (msg.senderId !== this._ownAgentId) {
-            fanout(this.handlers.message, msg, this.opts.logger);
+            fanout(this.handlers.message, msg);
         }
     }
     handleConversationCreatedNotification(notification) {
@@ -780,6 +674,14 @@ export class MoltZapService {
     handleConversationUpdatedNotification(notification) {
         this.upsertConversationNotification(notification);
     }
+    handleConversationArchivedNotification(notification) {
+        this.markConversationArchived(notification.conversationId);
+        fanout(this.handlers.conversationArchived, notification);
+    }
+    handleConversationUnarchivedNotification(notification) {
+        this.archivedConversationIds.delete(notification.conversationId);
+        fanout(this.handlers.conversationUnarchived, notification);
+    }
     upsertConversationNotification(notification) {
         const { conversation } = notification;
         this.archivedConversationIds.delete(conversation.id);
@@ -796,6 +698,7 @@ export class MoltZapService {
         }));
     }
     markConversationArchived(conversationId) {
+        this.seenMessageIds.delete(conversationId);
         this.archivedConversationIds.add(conversationId);
         Effect.runSync(Effect.all([
             Ref.update(this.conversationsRef, (m) => HashMap.remove(m, conversationId)),