@moltzap/client 2026.413.0 → 2026.425.0

package/dist/service.js

@@ -3,7 +3,10 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { EventNames, } from "@moltzap/protocol";
+import { Effect, HashMap, Match, Option, Ref } from "effect";
 import { MoltZapWsClient } from "./ws-client.js";
+import { AgentNotFoundError, NotConnectedError, RpcServerError, RpcTimeoutError, } from "./runtime/errors.js";
+import { getOr, snapshot } from "./runtime/refs.js";
 /** Escape `<`, `>`, `&` so sender content can't escape a `<system-reminder>` block. */
 export function sanitizeForSystemReminder(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -28,90 +31,144 @@ export function formatCrossConversationBlock(entries, opts) {
         "</system-reminder>",
     ].join("\n");
 }
-const MAX_MESSAGES_PER_CONV = 20;
-function renderPart(p) {
-    switch (p.type) {
-        case "text":
-            return p.text;
-        case "image":
-            return "[image]";
-        case "file":
-            return `[file: ${p.name}]`;
-        default:
-            return `[${p.type}]`;
+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;
+/**
+ * Invoke every handler with `arg`, isolating throws so one bad handler
+ * doesn't abort the remaining fanout. Logs via the optional client logger.
+ */
+function fanout(handlers, arg, logger) {
+    for (const h of handlers) {
+        try {
+            h(arg);
+        }
+        catch (err) {
+            logger?.error("event handler threw", err);
+        }
     }
 }
 /**
  * Stateful MoltZap client that manages connection, conversation tracking,
  * agent name resolution, and cross-conversation context generation.
+ *
+ * API contract: **every fallible method returns `Effect`.** There are no
+ * `*Async` Promise siblings (unlike `@moltzap/app-sdk`'s `MoltZapApp`);
+ * async/await consumers run the Effect at the edge with `Effect.runPromise`.
+ * `@moltzap/app-sdk` is the public app-facing surface and layers its own
+ * `*Async` wrappers on top. Keep this class Effect-only so downstream
+ * callers compose failures and cancellation explicitly.
  */
 export class MoltZapService {
     opts;
     client = null;
     _connected = false;
-    conversations = new Map();
-    messages = new Map();
-    agentNames = new Map();
-    agentConversationCache = new Map();
-    lastNotified = new Map();
-    lastRead = new Map();
+    conversationsRef = Effect.runSync(Ref.make(HashMap.empty()));
+    messagesRef = Effect.runSync(Ref.make(HashMap.empty()));
+    agentNamesRef = Effect.runSync(Ref.make(HashMap.empty()));
+    agentConversationCacheRef = Effect.runSync(Ref.make(HashMap.empty()));
+    lastNotifiedRef = Effect.runSync(Ref.make(HashMap.empty()));
+    lastReadRef = Effect.runSync(Ref.make(HashMap.empty()));
     messageHandlers = [];
     rawEventHandlers = [];
     disconnectHandlers = [];
     reconnectHandlers = [];
-    pendingNameLookups = new Map();
-    ownAgentId;
+    permissionRequiredHandlers = [];
+    _ownAgentId;
     constructor(opts) {
         this.opts = opts;
     }
     get connected() {
         return this._connected;
     }
-    async connect() {
-        this.client = new MoltZapWsClient({
-            serverUrl: this.opts.serverUrl,
-            agentKey: this.opts.agentKey,
-            logger: this.opts.logger,
-            onEvent: (event) => this.handleEvent(event),
-            onDisconnect: () => {
-                this._connected = false;
-                for (const h of this.disconnectHandlers)
-                    h();
-            },
-            onReconnect: (helloOk) => {
-                this._connected = true;
-                const hello = helloOk;
-                this.populateFromHello(hello);
-                for (const h of this.reconnectHandlers)
-                    h(hello);
-            },
+    get ownAgentId() {
+        return this._ownAgentId;
+    }
+    /** Effect-native: compose via `yield*` or bridge at the edge via `Effect.runPromise`. */
+    connect() {
+        return Effect.gen(this, function* () {
+            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) => {
+                    this._connected = false;
+                    fanout(this.disconnectHandlers, undefined, this.opts.logger);
+                },
+                onReconnect: (helloOk) => {
+                    this._connected = true;
+                    const hello = helloOk;
+                    this.populateFromHello(hello);
+                    fanout(this.reconnectHandlers, hello, this.opts.logger);
+                },
+            });
+            // Spec #222 OQ-4 deletion: per-event `onEvent` callback is gone.
+            // Replacement: register a `{}` filter subscription before
+            // `connect()` so every inbound event still fans out to
+            // `handleEvent`. Pre-connect registration is supported by the
+            // registry.
+            yield* this.client.subscribe({}, (event) => Effect.sync(() => this.handleEvent(event)));
+            const helloOk = (yield* this.client.connect());
+            this._connected = true;
+            this._ownAgentId = helloOk.agentId;
+            this.populateFromHello(helloOk);
+            return helloOk;
         });
-        const helloOk = (await this.client.connect());
-        this._connected = true;
-        this.ownAgentId = helloOk.agentId;
-        this.populateFromHello(helloOk);
-        return helloOk;
     }
+    /**
+     * 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.
+     */
     close() {
         this._connected = false;
         this.stopSocketServer();
-        this.client?.close();
+        if (this.client) {
+            void Effect.runPromise(this.client.close());
+        }
         this.client = null;
-        this.conversations.clear();
-        this.messages.clear();
-        this.agentNames.clear();
-        this.agentConversationCache.clear();
-        this.lastNotified.clear();
-        this.lastRead.clear();
+        Effect.runSync(Effect.all([
+            Ref.set(this.conversationsRef, HashMap.empty()),
+            Ref.set(this.messagesRef, HashMap.empty()),
+            Ref.set(this.agentNamesRef, HashMap.empty()),
+            Ref.set(this.agentConversationCacheRef, HashMap.empty()),
+            Ref.set(this.lastNotifiedRef, HashMap.empty()),
+            Ref.set(this.lastReadRef, HashMap.empty()),
+        ]));
+        // 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;
     activeSocketPath = null;
     /** Default socket path for CLI discovery. Per-instance path uses agentId. */
     static SOCKET_PATH = path.join(os.homedir(), ".moltzap", "service.sock");
+    /**
+     * `agentId` is a server-assigned string. Treat it as untrusted: if a
+     * compromised or malicious server returns an id containing `..` or a
+     * path separator, a naive `path.join(... , agentId)` escapes `~/.moltzap`.
+     * Reject anything that isn't a safe identifier.
+     */
+    static safeAgentIdSegment(id) {
+        return /^[A-Za-z0-9_-]+$/.test(id) ? id : "default";
+    }
     /** Per-instance socket path based on connected agentId. */
     get socketPath() {
-        const id = this.ownAgentId ?? "default";
+        const id = MoltZapService.safeAgentIdSegment(this.ownAgentId ?? "default");
         return path.join(os.homedir(), ".moltzap", `service-${id}.sock`);
     }
     startSocketServer() {
@@ -120,7 +177,14 @@ export class MoltZapService {
         try {
             fs.unlinkSync(sockPath);
         }
-        catch { }
+        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 = "";
@@ -131,20 +195,39 @@ export class MoltZapService {
                 for (const line of lines) {
                     if (!line.trim())
                         continue;
-                    void this.handleSocketLine(line, conn);
+                    // 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));
                 }
             });
         });
-        this.socketServer.listen(sockPath);
+        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, 0o600);
+            }
+            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 { }
+        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 { }
+        catch (err) {
+            this.opts.logger?.warn("symlink default socket failed", err);
+        }
     }
     stopSocketServer() {
         this.socketServer?.close();
@@ -154,193 +237,221 @@ export class MoltZapService {
         try {
             fs.unlinkSync(sockPath);
         }
-        catch { }
-        // Remove default symlink if it points to this instance
+        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 { }
+        catch (err) {
+            this.opts.logger?.info("cleanup default symlink", err);
+        }
     }
-    async handleSocketLine(line, conn) {
-        try {
-            const req = JSON.parse(line);
+    /**
+     * 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 {
+                req = JSON.parse(line); // #ignore-sloppy-code[record-cast]: JSON.parse boundary from unix socket line protocol
+            }
+            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) {
-                throw new Error("method is required and must be a string");
+                return Effect.sync(() => conn.write(JSON.stringify({
+                    error: "method is required and must be a string",
+                }) + "\n"));
             }
             const params = req.params != null && typeof req.params === "object"
-                ? req.params
+                ? req.params // #ignore-sloppy-code[record-cast]: req.params is untyped JSON from socket
                 : {};
-            const result = await this.handleSocketRequest(req.method, params);
-            conn.write(JSON.stringify({ result }) + "\n");
-        }
-        catch (err) {
-            conn.write(JSON.stringify({
-                error: err instanceof Error ? err.message : String(err),
-            }) + "\n");
-        }
+            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");
+                },
+            }));
+        });
+    }
+    handleSocketRequestEffect(method, params) {
+        return Effect.suspend(() => {
+            switch (method) {
+                case "ping":
+                    return Effect.succeed({ ok: true, agentId: this.ownAgentId });
+                case "status":
+                    return Effect.succeed({
+                        agentId: this.ownAgentId,
+                        connected: this._connected,
+                        conversations: this.getConversations().length,
+                    });
+                case "history":
+                    return this.handleHistoryRequest(params);
+                default:
+                    // Passthrough: forward any other method to the MoltZap server via RPC
+                    return this.sendRpc(method, params);
+            }
+        });
     }
-    async handleSocketRequest(method, params) {
-        switch (method) {
-            case "ping":
-                return { ok: true, agentId: this.ownAgentId };
-            case "status":
+    handleHistoryRequest(params) {
+        return Effect.gen(this, function* () {
+            if (typeof params.conversationId !== "string" || !params.conversationId) {
+                return yield* Effect.fail(new Error("conversationId is required and must be a string"));
+            }
+            if (params.limit !== undefined && typeof params.limit !== "number") {
+                return yield* Effect.fail(new Error("limit must be a number"));
+            }
+            const convId = params.conversationId;
+            const limit = params.limit ?? 10;
+            const sessionKey = params.sessionKey;
+            const result = (yield* this.sendRpc("messages/list", {
+                conversationId: convId,
+                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("agents/lookup", { agentIds: unknownAgentIds }).pipe(Effect.tap((res) => {
+                    const agents = res.agents;
+                    return Ref.update(this.agentNamesRef, (names) => {
+                        let next = names;
+                        for (const a of agents) {
+                            next = HashMap.set(next, a.id, a.name);
+                        }
+                        return next;
+                    });
+                }), Effect.asVoid, Effect.catchAll(() => Effect.void))
+                : Effect.void;
+            const metaEff = this.sendRpc("conversations/get", {
+                conversationId: convId,
+            }).pipe(Effect.map((res) => res
+                .conversation), Effect.catchAll(() => Effect.succeed(undefined)));
+            const [, convMeta] = yield* Effect.all([lookupEff, metaEff], {
+                concurrency: "unbounded",
+            });
+            // 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 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 {
-                    agentId: this.ownAgentId,
-                    connected: this._connected,
-                    conversations: this.getConversations().length,
+                    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,
                 };
-            case "history": {
-                if (typeof params.conversationId !== "string" ||
-                    !params.conversationId) {
-                    throw new Error("conversationId is required and must be a string");
-                }
-                if (params.limit !== undefined && typeof params.limit !== "number") {
-                    throw new Error("limit must be a number");
-                }
-                const convId = params.conversationId;
-                const limit = params.limit ?? 10;
-                const sessionKey = params.sessionKey;
-                const afterSeq = params.afterSeq;
-                const beforeSeq = params.beforeSeq;
-                const result = (await this.sendRpc("messages/list", {
-                    conversationId: convId,
-                    limit,
-                    ...(afterSeq !== undefined ? { afterSeq } : {}),
-                    ...(beforeSeq !== undefined ? { beforeSeq } : {}),
-                }));
-                // Resolve agent names (batch) + fetch conversation metadata (concurrent)
-                const unknownAgentIds = [
-                    ...new Set(result.messages
-                        .filter((m) => m.sender.type === "agent")
-                        .map((m) => m.sender.id)),
-                ].filter((id) => !this.agentNames.has(id));
-                const [, convMeta] = await Promise.all([
-                    unknownAgentIds.length > 0
-                        ? this.sendRpc("agents/lookup", { agentIds: unknownAgentIds }).then((res) => {
-                            for (const a of res.agents) {
-                                this.agentNames.set(a.id, a.name);
-                            }
-                        })
-                        : Promise.resolve(),
-                    this.sendRpc("conversations/get", { conversationId: convId })
-                        .then((res) => res
-                        .conversation)
-                        .catch(() => undefined),
-                ]);
-                // 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.
-                // This means messages stay "new" until the agent reads them via history,
-                // even if the system-reminder already notified about them.
-                const readMarkers = sessionKey
-                    ? (this.lastRead.get(sessionKey) ?? new Map())
-                    : null;
-                const lastReadSeq = readMarkers?.get(convId) ?? 0;
-                const messages = result.messages.map((m) => {
-                    const text = m.parts.map(renderPart).join(" ");
-                    return {
-                        seq: m.seq,
-                        senderId: m.sender.id,
-                        senderName: m.sender.id === this.ownAgentId
-                            ? "you"
-                            : (this.agentNames.get(m.sender.id) ?? m.sender.id),
-                        isOwn: m.sender.id === this.ownAgentId,
-                        text,
-                        createdAt: m.createdAt,
-                        isNew: sessionKey ? m.seq > lastReadSeq : 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));
                 });
-                // Advance lastRead to the highest seq in the returned page.
-                // The agent has seen these messages; older ones (if paginated) remain
-                // accessible via afterSeq/beforeSeq cursors.
-                if (sessionKey && result.messages.length > 0) {
-                    const maxSeq = Math.max(...result.messages.map((m) => m.seq));
-                    if (!this.lastRead.has(sessionKey)) {
-                        this.lastRead.set(sessionKey, new Map());
-                    }
-                    const current = this.lastRead.get(sessionKey).get(convId) ?? 0;
-                    if (maxSeq > current) {
-                        this.lastRead.get(sessionKey).set(convId, maxSeq);
-                    }
-                }
-                return {
-                    messages,
-                    hasMore: result.hasMore,
-                    conversationMeta: convMeta,
-                    newCount: messages.filter((m) => m.isNew).length,
-                };
             }
-            default:
-                // Passthrough: forward any other method to the MoltZap server via RPC
-                return this.sendRpc(method, params);
-        }
+            return {
+                messages,
+                hasMore: result.hasMore,
+                conversationMeta: convMeta,
+                newCount: messages.filter((m) => m.isNew).length,
+            };
+        });
     }
     // --- Conversations ---
     getConversation(convId) {
-        return this.conversations.get(convId);
+        return Option.getOrUndefined(HashMap.get(snapshot(this.conversationsRef), convId));
     }
     getConversations() {
-        return [...this.conversations.values()];
+        return [...HashMap.values(snapshot(this.conversationsRef))];
     }
     // --- Messages ---
-    getHistory(convId, limit = 20) {
-        const msgs = this.messages.get(convId) ?? [];
-        return msgs.slice(-limit);
+    getHistory(convId, limit) {
+        const msgs = getOr(snapshot(this.messagesRef), convId, () => []);
+        return limit ? msgs.slice(-limit) : [...msgs];
     }
     // --- Agent Names ---
     getAgentName(agentId) {
-        return this.agentNames.get(agentId);
-    }
-    async resolveAgentName(agentId) {
-        const cached = this.agentNames.get(agentId);
-        if (cached)
-            return cached;
-        const pending = this.pendingNameLookups.get(agentId);
-        if (pending)
-            return pending;
-        const promise = (async () => {
-            const result = (await this.sendRpc("agents/lookup", {
-                agentIds: [agentId],
-            }));
-            const agent = result.agents[0];
-            if (agent) {
-                this.agentNames.set(agentId, agent.name);
-                return agent.name;
-            }
-            return agentId;
-        })();
-        this.pendingNameLookups.set(agentId, promise);
-        try {
-            return await promise;
-        }
-        finally {
-            this.pendingNameLookups.delete(agentId);
-        }
+        return Option.getOrUndefined(HashMap.get(snapshot(this.agentNamesRef), agentId));
+    }
+    /**
+     * Cache-first agent-name lookup. Never fails: falls back to `agentId`
+     * when the RPC errors or the server has no record. The error path logs
+     * so ops can see repeated lookup failures; the empty-response path is
+     * silent (a cold agent is an expected transient state).
+     */
+    resolveAgentName(agentId) {
+        return Effect.gen(this, function* () {
+            const cached = Option.getOrUndefined(HashMap.get(snapshot(this.agentNamesRef), agentId));
+            if (cached !== undefined)
+                return cached;
+            return yield* this.sendRpc("agents/lookup", { agentIds: [agentId] }).pipe(Effect.flatMap((result) => {
+                const agent = result.agents[0];
+                if (!agent)
+                    return Effect.succeed(agentId);
+                return Ref.update(this.agentNamesRef, (names) => HashMap.set(names, agentId, agent.name)).pipe(Effect.as(agent.name));
+            }), Effect.catchAll((err) => Effect.logWarning("agents/lookup failed; falling back to agentId").pipe(Effect.annotateLogs({ agentId, err: String(err) }), Effect.as(agentId))));
+        });
     }
     // --- Messaging ---
-    async send(convId, text, opts) {
-        await this.sendRpc("messages/send", {
+    send(convId, text, opts) {
+        return Effect.asVoid(this.sendRpc("messages/send", {
             conversationId: convId,
             parts: [{ type: "text", text }],
             ...(opts?.replyTo ? { replyToId: opts.replyTo } : {}),
-        });
+        }));
     }
-    async sendToAgent(agentName, text, opts) {
-        let conversationId = this.agentConversationCache.get(agentName);
-        if (!conversationId) {
-            const lookupResult = (await this.sendRpc("agents/lookupByName", {
-                name: agentName,
-            }));
-            const createResult = (await this.sendRpc("conversations/create", {
-                type: "dm",
-                participants: [{ type: "agent", id: lookupResult.agent.id }],
-            }));
-            conversationId = createResult.conversation.id;
-            this.agentConversationCache.set(agentName, conversationId);
-        }
-        await this.send(conversationId, text, opts);
+    sendToAgent(agentName, text, opts) {
+        return Effect.gen(this, function* () {
+            const cache = yield* Ref.get(this.agentConversationCacheRef);
+            let conversationId = Option.getOrUndefined(HashMap.get(cache, agentName));
+            if (!conversationId) {
+                const lookupResult = (yield* this.sendRpc("agents/lookupByName", {
+                    names: [agentName],
+                }));
+                const agent = lookupResult.agents[0];
+                if (!agent) {
+                    return yield* Effect.fail(new AgentNotFoundError({ agentName }));
+                }
+                const createResult = (yield* this.sendRpc("conversations/create", {
+                    type: "dm",
+                    participants: [{ type: "agent", id: agent.id }],
+                }));
+                conversationId = createResult.conversation.id;
+                const newId = conversationId;
+                yield* Ref.update(this.agentConversationCacheRef, (m) => HashMap.set(m, agentName, newId));
+            }
+            yield* this.send(conversationId, text, opts);
+        });
     }
     // --- Cross-Conversation Context ---
     /**
@@ -366,44 +477,108 @@ export class MoltZapService {
     peekContextEntries(currentConvId, opts) {
         const maxConvs = opts?.maxConversations ?? 5;
         const maxMsgsPerConv = opts?.maxMessagesPerConv ?? 3;
-        const viewMarkers = this.lastNotified.get(currentConvId) ?? new Map();
+        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, msgs] of this.messages) {
-            if (convId === currentConvId || msgs.length === 0)
-                continue;
-            if (entries.length >= maxConvs)
-                break;
-            const lastSeenSeq = viewMarkers.get(convId) ?? 0;
-            const newMsgs = msgs.filter((m) => m.seq > lastSeenSeq);
-            if (newMsgs.length === 0)
-                continue;
+        for (const { convId, newMsgs } of candidates.slice(0, maxConvs)) {
             const reportable = newMsgs.slice(-maxMsgsPerConv);
             const last = reportable[reportable.length - 1];
-            const senderName = this.resolveSenderLabel(last.sender.id);
+            const senderName = getOr(agentNamesMap, last.senderId, () => last.senderId);
             const minutesAgo = Math.max(0, Math.round((Date.now() - new Date(last.createdAt).getTime()) / 60_000));
-            const text = last.parts.map(renderPart).join(" ");
             entries.push({
                 conversationId: convId,
-                conversationName: this.conversations.get(convId)?.name,
+                conversationName: Option.getOrUndefined(HashMap.get(conversationsMap, convId))?.name,
                 senderName,
-                text,
+                text: last.parts.map(renderPart).join(" "),
                 minutesAgo,
                 count: reportable.length,
             });
-            pendingAdvances.push([convId, last.seq]);
+            pendingAdvances.push([convId, last.id]);
         }
-        const commit = () => {
-            for (const [convId, seq] of pendingAdvances) {
-                viewMarkers.set(convId, seq);
+        return {
+            entries,
+            commit: () => this.advanceLastNotified(currentConvId, pendingAdvances),
+        };
+    }
+    /**
+     * Return all new messages from all other conversations as full transcripts,
+     * sorted chronologically. Uses the same lastNotified markers as
+     * peekContextEntries. Call commit() to advance markers.
+     */
+    peekFullMessages(currentConvId) {
+        const { messagesMap, conversationsMap, agentNamesMap, viewMarkers } = this.readCrossConvState(currentConvId);
+        const allMessages = [];
+        const pendingAdvances = [];
+        for (const [convId, newMsgs] of this.iterNewMessagesByConv(messagesMap, viewMarkers, currentConvId)) {
+            const convName = Option.getOrUndefined(HashMap.get(conversationsMap, convId))?.name;
+            for (const m of newMsgs) {
+                allMessages.push({
+                    conversationId: convId,
+                    conversationName: convName,
+                    senderName: getOr(agentNamesMap, m.senderId, () => m.senderId),
+                    senderId: m.senderId,
+                    text: m.parts.map(renderPart).join(" "),
+                    timestamp: m.createdAt,
+                });
             }
-            this.lastNotified.set(currentConvId, viewMarkers);
+            pendingAdvances.push([convId, newMsgs[newMsgs.length - 1].id]);
+        }
+        allMessages.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        return {
+            messages: allMessages,
+            commit: () => this.advanceLastNotified(currentConvId, pendingAdvances),
+        };
+    }
+    readCrossConvState(currentConvId) {
+        const lastNotifiedMap = snapshot(this.lastNotifiedRef);
+        return {
+            messagesMap: snapshot(this.messagesRef),
+            conversationsMap: snapshot(this.conversationsRef),
+            agentNamesMap: snapshot(this.agentNamesRef),
+            viewMarkers: getOr(lastNotifiedMap, currentConvId, () => HashMap.empty()),
         };
-        return { entries, commit };
     }
-    on(event, 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    handler) {
+    *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];
+        }
+    }
+    advanceLastNotified(currentConvId, pendingAdvances) {
+        if (pendingAdvances.length === 0)
+            return;
+        Effect.runSync(Ref.update(this.lastNotifiedRef, (outer) => {
+            let markers = getOr(outer, currentConvId, () => HashMap.empty());
+            for (const [convId, msgId] of pendingAdvances) {
+                markers = HashMap.set(markers, convId, msgId);
+            }
+            return HashMap.set(outer, currentConvId, markers);
+        }));
+    }
+    on(event, handler) {
         switch (event) {
             case "message":
                 this.messageHandlers.push(handler);
@@ -417,13 +592,22 @@ export class MoltZapService {
             case "reconnect":
                 this.reconnectHandlers.push(handler);
                 break;
+            case "permissionRequired":
+                this.permissionRequiredHandlers.push(handler);
+                break;
         }
     }
     // --- RPC passthrough ---
-    async sendRpc(method, params) {
-        if (!this.client)
-            throw new Error("Not connected");
-        return this.client.sendRpc(method, params);
+    sendRpc(method, params) {
+        return Effect.suspend(() => {
+            if (!this.client) {
+                return Effect.fail(new NotConnectedError({ message: "Not connected" }));
+            }
+            return this.client.sendRpc(method, params);
+        });
+    }
+    grantPermission(params) {
+        return Effect.asVoid(this.sendRpc("permissions/grant", params));
     }
     // --- Internals ---
     /**
@@ -431,85 +615,92 @@ export class MoltZapService {
      * into the local cache. Called on ConversationCreated events because the
      * event schema omits the participants list — see protocol/events.ts.
      */
-    async refreshConversationParticipants(conversationId) {
-        try {
-            const res = (await this.sendRpc("conversations/get", {
-                conversationId,
-            }));
-            const existing = this.conversations.get(conversationId);
-            this.conversations.set(conversationId, {
-                id: res.conversation.id,
-                type: res.conversation.type,
-                name: res.conversation.name,
-                participants: res.participants.map((p) => `${p.participant.type}:${p.participant.id}`),
-            });
-        }
-        catch {
-            // Best-effort refresh. Leave the existing entry in place on failure.
-        }
+    refreshConversationParticipants(conversationId) {
+        return this.sendRpc("conversations/get", { conversationId }).pipe(Effect.tap((res) => {
+            const typed = res;
+            const meta = {
+                id: typed.conversation.id,
+                type: typed.conversation.type,
+                name: typed.conversation.name,
+                participants: typed.participants.map((p) => `${p.participant.type}:${p.participant.id}`),
+            };
+            return Ref.update(this.conversationsRef, (m) => HashMap.set(m, conversationId, meta));
+        }), Effect.asVoid, 
+        // Best-effort refresh. Leave the existing entry in place on failure.
+        Effect.catchAll(() => Effect.void));
     }
     populateFromHello(hello) {
         if (!hello.conversations)
             return;
-        for (const conv of hello.conversations) {
-            this.conversations.set(conv.id, {
-                id: conv.id,
-                type: conv.type,
-                name: conv.name,
-                participants: (conv.participants ?? []).map((p) => `${p.type}:${p.id}`),
-            });
-        }
+        const incoming = hello.conversations;
+        Effect.runSync(Ref.update(this.conversationsRef, (m) => {
+            let next = m;
+            for (const conv of incoming) {
+                next = HashMap.set(next, conv.id, {
+                    id: conv.id,
+                    type: conv.type,
+                    name: conv.name,
+                    participants: (conv.participants ?? []).map((p) => `${p.type}:${p.id}`),
+                });
+            }
+            return next;
+        }));
     }
     handleEvent(event) {
-        for (const h of this.rawEventHandlers)
-            h(event);
+        fanout(this.rawEventHandlers, event, this.opts.logger);
+        // The server validates event.data against each event's schema before
+        // emitting; each case casts to the typed Static<> payload for that
+        // specific event.
         switch (event.event) {
             case EventNames.MessageReceived: {
                 const msg = event.data.message;
                 this.storeMessage(msg);
-                // Resolve sender name in background
-                if (msg.sender.type === "agent" &&
-                    !this.agentNames.has(msg.sender.id)) {
-                    void this.resolveAgentName(msg.sender.id);
-                }
-                // Emit to external handlers (only non-own messages)
-                if (msg.sender.id !== this.ownAgentId) {
-                    for (const h of this.messageHandlers)
-                        h(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.messageHandlers, msg, this.opts.logger);
                 }
                 break;
             }
+            case EventNames.PermissionsRequired: {
+                fanout(this.permissionRequiredHandlers, event.data, this.opts.logger);
+                break;
+            }
             case EventNames.ConversationCreated:
             case EventNames.ConversationUpdated: {
-                const data = event.data;
-                const existing = this.conversations.get(data.conversation.id);
-                this.conversations.set(data.conversation.id, {
-                    id: data.conversation.id,
-                    type: data.conversation.type,
-                    name: data.conversation.name,
-                    participants: existing?.participants ?? [],
-                });
+                const { conversation } = event.data;
+                Effect.runSync(Ref.update(this.conversationsRef, (m) => {
+                    const existing = Option.getOrUndefined(HashMap.get(m, conversation.id));
+                    return HashMap.set(m, conversation.id, {
+                        id: conversation.id,
+                        type: conversation.type,
+                        name: conversation.name,
+                        participants: existing?.participants ?? [],
+                    });
+                }));
                 // The ConversationCreated event schema doesn't carry participants
                 // (protocol/schema/events.ts: ConversationSchema is id/type/name/
                 // createdBy/timestamps only). Fetch full details asynchronously so
                 // downstream code that reads getConversation(id).participants sees
                 // a populated list within a round-trip of the event.
                 if (event.event === EventNames.ConversationCreated) {
-                    void this.refreshConversationParticipants(data.conversation.id);
+                    // Fire-and-forget: refreshConversationParticipants never fails.
+                    Effect.runFork(this.refreshConversationParticipants(conversation.id));
                 }
                 break;
             }
         }
     }
     storeMessage(msg) {
-        const buf = this.messages.get(msg.conversationId) ?? [];
-        buf.push(msg);
-        if (buf.length > MAX_MESSAGES_PER_CONV)
-            buf.shift();
-        this.messages.set(msg.conversationId, buf);
-    }
-    resolveSenderLabel(senderId) {
-        return this.agentNames.get(senderId) ?? senderId;
+        Effect.runSync(Ref.update(this.messagesRef, (m) => {
+            const existing = getOr(m, msg.conversationId, () => []);
+            const appended = [...existing, msg];
+            const capped = appended.length > MAX_MESSAGES_PER_CONV
+                ? appended.slice(-MAX_MESSAGES_PER_CONV)
+                : appended;
+            return HashMap.set(m, msg.conversationId, capped);
+        }));
     }
 }
 //# sourceMappingURL=service.js.map