@moltzap/client 2026.503.4 → 2026.504.1

package/dist/service.js

@@ -2,11 +2,12 @@ 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 { AgentsLookup, AgentsLookupByName, AppsAuthorizeDispatch, ConversationsCreate, ConversationsGet, ErrorCodes, EventNames, MessagesList, MessagesSend, PermissionsGrant, } from "@moltzap/protocol";
+import { AgentsLookup, AgentsLookupByName, agentId as toAgentId, AppsAuthorizeDispatch, bindNotificationHandler, ConversationsCreate, ConversationsGet, conversationId as toConversationId, defineEffectNotificationHandlers, defineNotificationGroup, MessageReceivedNotificationDefinition, ConversationCreatedNotificationDefinition, ConversationUpdatedNotificationDefinition, ConversationArchivedNotificationDefinition, ConversationUnarchivedNotificationDefinition, ErrorCodes, isDecodedNotificationInGroup, messageId as toMessageId, 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 { AgentNotFoundError, NotConnectedError, RpcServerError, RpcTimeoutError, } from "./runtime/errors.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);
 const CROSS_CONTEXT_TEXT_LIMIT = 120;
 const DEFAULT_HISTORY_LIMIT = 10;
@@ -74,6 +75,14 @@ const renderPart = Match.type().pipe(Match.discriminatorsExhaustive("type")({
  * display windows — `conversations get` shows at most a few hundred.
  */
 const MAX_MESSAGES_PER_CONV = 1000;
+const serviceNotificationDefinitions = [
+    MessageReceivedNotificationDefinition,
+    ConversationCreatedNotificationDefinition,
+    ConversationUpdatedNotificationDefinition,
+    ConversationArchivedNotificationDefinition,
+    ConversationUnarchivedNotificationDefinition,
+];
+const serviceNotificationGroup = defineNotificationGroup("clientService", serviceNotificationDefinitions);
 /**
  * Invoke every handler with `arg`, isolating throws so one bad handler
  * doesn't abort the remaining fanout. Logs via the optional client logger.
@@ -84,7 +93,7 @@ function fanout(handlers, arg, logger) {
             h(arg);
         }
         catch (err) {
-            logger?.error("event handler threw", err);
+            logger?.error("notification handler threw", err);
         }
     }
 }
@@ -110,13 +119,15 @@ export class MoltZapService {
     lastNotifiedRef = Effect.runSync(Ref.make(HashMap.empty()));
     lastReadRef = Effect.runSync(Ref.make(HashMap.empty()));
     archivedConversationIds = new Set();
-    messageHandlers = [];
-    rawEventHandlers = [];
-    disconnectHandlers = [];
-    reconnectHandlers = [];
-    permissionRequiredHandlers = [];
-    conversationArchivedHandlers = [];
-    conversationUnarchivedHandlers = [];
+    handlers = {
+        message: [],
+        rawNotification: [],
+        disconnect: [],
+        reconnect: [],
+        conversationArchived: [],
+        conversationUnarchived: [],
+    };
+    notificationHandlers = this.createNotificationHandlers();
     _ownAgentId;
     constructor(opts) {
         this.opts = opts;
@@ -137,25 +148,24 @@ export class MoltZapService {
                 // 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: (close) => {
+                    void close;
                     this._connected = false;
-                    fanout(this.disconnectHandlers, undefined, this.opts.logger);
+                    fanout(this.handlers.disconnect, undefined, this.opts.logger);
                 },
                 onReconnect: (helloOk) => {
                     this._connected = true;
-                    const hello = helloOk;
-                    this.populateFromHello(hello);
-                    fanout(this.reconnectHandlers, hello, this.opts.logger);
+                    this.populateFromHello(helloOk);
+                    fanout(this.handlers.reconnect, helloOk, this.opts.logger);
                 },
             });
-            // Spec #222 OQ-4 deletion: per-event `onEvent` callback is gone.
+            // Spec #222 OQ-4: per-notification callback is replaced by subscriptions.
             // Replacement: register a `{}` filter subscription before
-            // `connect()` so every inbound event still fans out to
-            // `handleEvent`. Pre-connect registration is supported by the
+            // `connect()` so every inbound notification still fans out to
+            // `handleNotification`. Pre-connect registration is supported by the
             // registry.
-            yield* this.client.subscribe({}, (event) => Effect.sync(() => this.handleEvent(event)));
-            const helloOk = (yield* this.client.connect());
+            yield* this.client.subscribe({}, (notification) => Effect.sync(() => this.handleNotification(notification)));
+            const helloOk = yield* this.client.connect();
             this._connected = true;
             this._ownAgentId = helloOk.agentId;
             this.populateFromHello(helloOk);
@@ -331,19 +341,25 @@ export class MoltZapService {
     handleSocketRequestEffect(method, params) {
         return Effect.suspend(() => {
             switch (method) {
-                case "ping":
+                case LocalServiceCommands.Ping:
                     return Effect.succeed({ ok: true, agentId: this.ownAgentId });
-                case "status":
+                case LocalServiceCommands.Status:
                     return Effect.succeed({
                         agentId: this.ownAgentId,
                         connected: this._connected,
                         conversations: this.getConversations().length,
                     });
-                case "history":
+                case LocalServiceCommands.History:
                     return this.handleHistoryRequest(params);
-                default:
-                    // Passthrough: forward any other method to the MoltZap server via RPC
-                    return this.sendRpc(method, params);
+                default: {
+                    const definition = rpcMethods.find((def) => def.name === method);
+                    if (definition === undefined || !definition.validateParams(params)) {
+                        return Effect.fail(new ServiceInputError({
+                            message: `unknown or invalid RPC method: ${method}`,
+                        }));
+                    }
+                    return this.sendRpc(definition, params);
+                }
             }
         });
     }
@@ -360,31 +376,29 @@ export class MoltZapService {
             const convId = params.conversationId;
             const limit = params.limit ?? DEFAULT_HISTORY_LIMIT;
             const sessionKey = params.sessionKey;
-            const result = (yield* this.sendRpc(MessagesList.name, {
-                conversationId: convId,
+            const result = yield* this.sendRpc(MessagesList, {
+                conversationId: toConversationId(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(AgentsLookup.name, { agentIds: unknownAgentIds }).pipe(Effect.tap((res) => {
-                    const agents = res.agents;
+                ? this.sendRpc(AgentsLookup, { agentIds: unknownAgentIds }).pipe(Effect.tap((res) => {
                     return Ref.update(this.agentNamesRef, (names) => {
                         let next = names;
-                        for (const a of agents) {
+                        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.name, {
-                conversationId: convId,
-            }).pipe(Effect.map((res) => res
-                .conversation), Effect.catchAll(() => Effect.succeed(undefined)));
+            const metaEff = this.sendRpc(ConversationsGet, {
+                conversationId: toConversationId(convId),
+            }).pipe(Effect.map((res) => res.conversation), Effect.catchAll(() => Effect.succeed(undefined)));
             const [, convMeta] = yield* Effect.all([lookupEff, metaEff], {
                 concurrency: HISTORY_LOOKUP_CONCURRENCY,
             });
@@ -460,7 +474,7 @@ export class MoltZapService {
             const cached = Option.getOrUndefined(HashMap.get(snapshot(this.agentNamesRef), agentId));
             if (cached !== undefined)
                 return cached;
-            return yield* this.sendRpc(AgentsLookup.name, {
+            return yield* this.sendRpc(AgentsLookup, {
                 agentIds: [agentId],
             }).pipe(Effect.flatMap((result) => {
                 const agent = result.agents[0];
@@ -478,33 +492,43 @@ export class MoltZapService {
                 message: "Conversation is archived",
             }));
         }
-        return Effect.asVoid(this.sendRpc(MessagesSend.name, {
-            conversationId: convId,
+        return Effect.asVoid(this.sendRpc(MessagesSend, {
+            conversationId: toConversationId(convId),
             parts: [{ type: "text", text }],
-            ...(opts?.replyTo ? { replyToId: opts.replyTo } : {}),
+            ...(opts?.replyTo ? { replyToId: toMessageId(opts.replyTo) } : {}),
             ...(opts?.dispatchLeaseId
                 ? { dispatchLeaseId: opts.dispatchLeaseId }
                 : {}),
         }));
     }
     authorizeDispatch(request) {
-        return this.sendRpc(AppsAuthorizeDispatch.name, {
-            conversationId: request.conversationId,
-            messageId: request.message.id,
-            senderAgentId: request.senderAgentId,
-            parts: request.message.parts,
+        return this.sendRpc(AppsAuthorizeDispatch, {
+            conversationId: toConversationId(request.conversationId),
+            messageId: toMessageId(request.message.id),
+            senderAgentId: toAgentId(request.senderAgentId),
+            parts: [...request.message.parts],
             receivedAt: request.receivedAt,
             clock: request.clock,
-            pending: request.pending,
+            pending: request.pending.map((pending) => ({
+                ...pending,
+                messageId: toMessageId(pending.messageId),
+                conversationId: toConversationId(pending.conversationId),
+                senderAgentId: toAgentId(pending.senderAgentId),
+                ...(pending.parts !== undefined ? { parts: [...pending.parts] } : {}),
+            })),
             attempt: request.attempt,
         }, { timeoutMs: DISPATCH_AUTHORIZATION_RPC_TIMEOUT_MS }).pipe(Effect.map((result) => {
-            const admission = result.admission;
+            const { admission } = result;
             switch (admission.decision) {
                 case "grant":
                     return {
                         _tag: "grant",
-                        leaseId: admission.leaseId,
-                        leaseTimeoutMs: admission.leaseTimeoutMs,
+                        ...(admission.leaseId !== undefined
+                            ? { leaseId: admission.leaseId }
+                            : {}),
+                        ...(admission.leaseTimeoutMs !== undefined
+                            ? { leaseTimeoutMs: admission.leaseTimeoutMs }
+                            : {}),
                         ...(admission.dispatchMessageId
                             ? { dispatchMessageId: admission.dispatchMessageId }
                             : {}),
@@ -512,12 +536,16 @@ export class MoltZapService {
                 case "deny":
                     return {
                         _tag: "deny",
-                        reason: admission.reason,
+                        ...(admission.reason !== undefined
+                            ? { reason: admission.reason }
+                            : {}),
                     };
                 case "hold":
                     return {
                         _tag: "hold",
-                        reason: admission.reason,
+                        ...(admission.reason !== undefined
+                            ? { reason: admission.reason }
+                            : {}),
                     };
             }
         }));
@@ -527,17 +555,17 @@ export class MoltZapService {
             const cache = yield* Ref.get(this.agentConversationCacheRef);
             let conversationId = Option.getOrUndefined(HashMap.get(cache, agentName));
             if (!conversationId) {
-                const lookupResult = (yield* this.sendRpc(AgentsLookupByName.name, {
+                const lookupResult = yield* this.sendRpc(AgentsLookupByName, {
                     names: [agentName],
-                }));
+                });
                 const agent = lookupResult.agents[0];
                 if (!agent) {
                     return yield* Effect.fail(new AgentNotFoundError({ agentName }));
                 }
-                const createResult = (yield* this.sendRpc(ConversationsCreate.name, {
+                const createResult = yield* this.sendRpc(ConversationsCreate, {
                     type: "dm",
-                    participants: [{ type: "agent", id: agent.id }],
-                }));
+                    participants: [{ type: "agent", id: toAgentId(agent.id) }],
+                });
                 conversationId = createResult.conversation.id;
                 const newId = conversationId;
                 yield* Ref.update(this.agentConversationCacheRef, (m) => HashMap.set(m, agentName, newId));
@@ -671,57 +699,37 @@ export class MoltZapService {
             return HashMap.set(outer, currentConvId, markers);
         }));
     }
-    on(event, handler) {
-        switch (event) {
-            case "message":
-                this.messageHandlers.push(handler);
-                break;
-            case "rawEvent":
-                this.rawEventHandlers.push(handler);
-                break;
-            case "disconnect":
-                this.disconnectHandlers.push(handler);
-                break;
-            case "reconnect":
-                this.reconnectHandlers.push(handler);
-                break;
-            case "permissionRequired":
-                this.permissionRequiredHandlers.push(handler);
-                break;
-            case "conversationArchived":
-                this.conversationArchivedHandlers.push(handler);
-                break;
-            case "conversationUnarchived":
-                this.conversationUnarchivedHandlers.push(handler);
-                break;
-        }
+    // --- Notifications ---
+    on(notification, handler) {
+        this.handlers[notification].push(handler);
     }
     // --- RPC passthrough ---
-    sendRpc(method, params, opts) {
+    sendRpc(definition, params, opts) {
         return Effect.suspend(() => {
             if (!this.client) {
                 return Effect.fail(new NotConnectedError({ message: "Not connected" }));
             }
-            return this.client.sendRpc(method, params, opts);
+            return this.client.sendRpc(definition, params, opts);
         });
     }
-    grantPermission(params) {
-        return Effect.asVoid(this.sendRpc(PermissionsGrant.name, params));
-    }
     // --- Internals ---
     /**
      * Fetch full conversation details (including participants) via RPC and merge
-     * into the local cache. Called on ConversationCreated events because the
-     * event schema omits the participants list — see protocol/events.ts.
+     * into the local cache. Called on ConversationCreated notifications because
+     * the notification schema omits the participants list — see
+     * protocol/notifications.ts.
      */
     refreshConversationParticipants(conversationId) {
-        return this.sendRpc(ConversationsGet.name, { conversationId }).pipe(Effect.tap((res) => {
-            const typed = res;
+        return this.sendRpc(ConversationsGet, {
+            conversationId: toConversationId(conversationId),
+        }).pipe(Effect.tap((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}`),
+                id: res.conversation.id,
+                type: res.conversation.type,
+                participants: res.participants.map((p) => `${p.participant.type}:${p.participant.id}`),
+                ...(res.conversation.name !== undefined
+                    ? { name: res.conversation.name }
+                    : {}),
             };
             if (this.archivedConversationIds.has(conversationId)) {
                 return Effect.void;
@@ -742,92 +750,88 @@ export class MoltZapService {
                 next = HashMap.set(next, conv.id, {
                     id: conv.id,
                     type: conv.type,
-                    name: conv.name,
                     participants: (conv.participants ?? []).map((p) => `${p.type}:${p.id}`),
+                    ...(conv.name !== undefined ? { name: conv.name } : {}),
                 });
             }
             return next;
         }));
     }
-    handleEvent(event) {
-        const eventData = isPlainRecord(event.data) ? event.data : {};
-        const message = isPlainRecord(eventData["message"])
-            ? eventData["message"]
+    handleNotification(notification) {
+        const params = isPlainRecord(notification.params)
+            ? notification.params
+            : {};
+        const message = isPlainRecord(params["message"])
+            ? params["message"]
             : undefined;
-        const conversation = isPlainRecord(eventData["conversation"])
-            ? eventData["conversation"]
+        const conversation = isPlainRecord(params["conversation"])
+            ? params["conversation"]
             : undefined;
-        const eventConversationId = typeof eventData["conversationId"] === "string"
-            ? eventData["conversationId"]
+        const notificationConversationId = typeof params["conversationId"] === "string"
+            ? params["conversationId"]
             : undefined;
         appendClientEventTrace({
             ts: new Date().toISOString(),
             agentId: this._ownAgentId ?? "unknown",
-            event: event.event,
+            notification: notification.method,
             messageId: message?.["id"],
             messageConversationId: message?.["conversationId"],
             messageSenderId: message?.["senderId"],
-            conversationId: conversation?.["id"] ?? eventConversationId,
+            conversationId: conversation?.["id"] ?? notificationConversationId,
             conversationName: conversation?.["name"],
         });
-        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);
-                // 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 { conversation } = event.data;
-                this.archivedConversationIds.delete(conversation.id);
-                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) {
-                    // Fire-and-forget: refreshConversationParticipants never fails.
-                    Effect.runFork(this.refreshConversationParticipants(conversation.id));
-                }
-                break;
-            }
-            case EventNames.ConversationArchived: {
-                const data = event.data;
-                this.markConversationArchived(data.conversationId);
-                fanout(this.conversationArchivedHandlers, data, this.opts.logger);
-                break;
-            }
-            case EventNames.ConversationUnarchived: {
-                const data = event.data;
-                this.archivedConversationIds.delete(data.conversationId);
-                fanout(this.conversationUnarchivedHandlers, data, this.opts.logger);
-                break;
-            }
+        fanout(this.handlers.rawNotification, notification, this.opts.logger);
+        if (isDecodedNotificationInGroup(serviceNotificationGroup, notification)) {
+            Effect.runSync(this.notificationHandlers.dispatch(notification));
         }
     }
+    createNotificationHandlers() {
+        return defineEffectNotificationHandlers(serviceNotificationGroup, [
+            bindNotificationHandler(MessageReceivedNotificationDefinition, (params) => Effect.sync(() => this.handleMessageReceivedNotification(params))),
+            bindNotificationHandler(ConversationCreatedNotificationDefinition, (params) => Effect.sync(() => this.handleConversationCreatedNotification(params))),
+            bindNotificationHandler(ConversationUpdatedNotificationDefinition, (params) => Effect.sync(() => this.handleConversationUpdatedNotification(params))),
+            bindNotificationHandler(ConversationArchivedNotificationDefinition, (params) => Effect.sync(() => {
+                this.markConversationArchived(params.conversationId);
+                fanout(this.handlers.conversationArchived, params, this.opts.logger);
+            })),
+            bindNotificationHandler(ConversationUnarchivedNotificationDefinition, (params) => Effect.sync(() => {
+                this.archivedConversationIds.delete(params.conversationId);
+                fanout(this.handlers.conversationUnarchived, params, this.opts.logger);
+            })),
+        ]);
+    }
+    handleMessageReceivedNotification(notification) {
+        const msg = notification.message;
+        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);
+        }
+    }
+    handleConversationCreatedNotification(notification) {
+        this.upsertConversationNotification(notification);
+        Effect.runFork(this.refreshConversationParticipants(notification.conversation.id));
+    }
+    handleConversationUpdatedNotification(notification) {
+        this.upsertConversationNotification(notification);
+    }
+    upsertConversationNotification(notification) {
+        const { conversation } = notification;
+        this.archivedConversationIds.delete(conversation.id);
+        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,
+                participants: existing?.participants ?? [],
+                ...(conversation.name !== undefined
+                    ? { name: conversation.name }
+                    : {}),
+            });
+        }));
+    }
     markConversationArchived(conversationId) {
         this.archivedConversationIds.add(conversationId);
         Effect.runSync(Effect.all([