@rkat/mobkit-sdk 0.4.9

package/dist/cjs/runtime.cjs

@@ -0,0 +1,476 @@
+"use strict";
+/**
+ * MobKit runtime — the running instance returned by the builder.
+ *
+ * @example
+ * ```ts
+ * const rt = await MobKit.builder().mob("mob.toml").gateway(bin).build();
+ * const handle = rt.mobHandle();
+ *
+ * const status = await handle.status();
+ * console.log(status.contractVersion, status.loadedModules);
+ *
+ * await rt.shutdown();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseBridge = exports.ToolCaller = exports.MobHandle = exports.MobKitRuntime = void 0;
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+const node_fs_1 = require("node:fs");
+const agent_builder_js_1 = require("./agent-builder.cjs");
+const errors_js_1 = require("./errors.cjs");
+const transport_js_1 = require("./transport.cjs");
+const sse_js_1 = require("./sse.cjs");
+const events_js_1 = require("./events.cjs");
+const models_js_1 = require("./models.cjs");
+const types_js_1 = require("./types.cjs");
+// -- Request ID counter ---------------------------------------------------
+let requestCounter = 0;
+function nextRequestId(method) {
+    return `${method}:${++requestCounter}`;
+}
+// -- MobKitRuntime --------------------------------------------------------
+/**
+ * Running MobKit runtime instance.
+ *
+ * Supports explicit lifecycle (`connect` / `shutdown`).
+ */
+class MobKitRuntime {
+    _config;
+    _transport;
+    _running = false;
+    _dispatcher = new agent_builder_js_1.CallbackDispatcher();
+    _rustHttpBase = null;
+    /** @internal */
+    constructor(config, transport) {
+        this._config = config;
+        this._transport = transport ?? null;
+    }
+    /** @internal */
+    static async _create(config) {
+        const runtime = new MobKitRuntime(config);
+        await runtime._bootstrap();
+        return runtime;
+    }
+    /** Explicitly connect to the runtime. Idempotent. */
+    async connect() {
+        if (this._running)
+            return;
+        await this._bootstrap();
+    }
+    async _bootstrap() {
+        if (this._config.gatewayBin) {
+            this._transport = new transport_js_1.PersistentTransport(this._config.gatewayBin);
+            // Register builder FIRST — init may trigger callback/build_agent
+            if (this._config.sessionBuilder) {
+                this._dispatcher.registerBuilder(this._config.sessionBuilder);
+            }
+            if (this._config.errorCallback !== null) {
+                this._dispatcher.registerErrorCallback(this._config.errorCallback);
+            }
+            this._transport.setCallbackHandler(this._dispatcher.handleCallback.bind(this._dispatcher));
+            this._transport.start();
+            if (!this._transport.isRunning()) {
+                throw new errors_js_1.TransportError(`gateway binary failed to start: ${this._config.gatewayBin}`);
+            }
+            try {
+                const initResult = await this._rpc("mobkit/init", this._buildInitParams());
+                if (typeof initResult === "object" &&
+                    initResult !== null &&
+                    "http_base_url" in initResult) {
+                    this._rustHttpBase = String(initResult.http_base_url ?? "") || null;
+                }
+            }
+            catch {
+                if (this._transport !== null && !this._transport.isRunning()) {
+                    throw new errors_js_1.TransportError("gateway process died during bootstrap");
+                }
+                throw new errors_js_1.TransportError("mobkit/init failed — runtime could not be initialized");
+            }
+        }
+        else if (this._config.sessionBuilder) {
+            this._dispatcher.registerBuilder(this._config.sessionBuilder);
+        }
+        this._running = true;
+    }
+    _buildInitParams() {
+        const params = {};
+        if (this._config.mobConfigPath) {
+            params.mob_config = (0, node_fs_1.readFileSync)(this._config.mobConfigPath, "utf-8");
+        }
+        if (this._config.modules.length > 0) {
+            params.modules = this._config.modules;
+        }
+        params.has_session_builder = Boolean(this._config.sessionBuilder);
+        params.runtime_options = {};
+        return params;
+    }
+    /** @internal */
+    async _rpc(method, params) {
+        if (this._transport === null) {
+            throw new errors_js_1.NotConnectedError("runtime not started — no transport available");
+        }
+        const rid = nextRequestId(method);
+        const request = (0, transport_js_1.buildJsonRpcRequest)(rid, method, params ?? {});
+        const response = (await this._transport.sendAsync(request));
+        if ("error" in response) {
+            const err = response.error;
+            throw new errors_js_1.RpcError(Number(err.code ?? -1), String(err.message ?? String(err)), rid, method);
+        }
+        return response.result;
+    }
+    get rustHttpBaseUrl() {
+        return this._rustHttpBase;
+    }
+    setRustHttpBase(url) {
+        this._rustHttpBase = url;
+    }
+    mobHandle() {
+        return new MobHandle(this);
+    }
+    sseBridge() {
+        return new SseBridge(this);
+    }
+    async shutdown() {
+        this._running = false;
+        if (this._transport !== null) {
+            this._transport.stop();
+        }
+    }
+    get isRunning() {
+        return this._running;
+    }
+}
+exports.MobKitRuntime = MobKitRuntime;
+// -- MobHandle ------------------------------------------------------------
+/**
+ * Proxy for the MobKit RPC API. Returns typed result objects.
+ *
+ * @example
+ * ```ts
+ * const handle = runtime.mobHandle();
+ * const members = await handle.listMembers();
+ * await handle.send(members[0].meerkatId, "Hello!");
+ * ```
+ */
+class MobHandle {
+    _runtime;
+    /** @internal */
+    constructor(_runtime) {
+        this._runtime = _runtime;
+    }
+    // -- Status & capabilities ----------------------------------------------
+    async status() {
+        return (0, types_js_1.parseStatusResult)(await this._runtime._rpc("mobkit/status"));
+    }
+    async capabilities() {
+        return (0, types_js_1.parseCapabilitiesResult)(await this._runtime._rpc("mobkit/capabilities"));
+    }
+    // -- Spawn & reconcile --------------------------------------------------
+    async spawn(spec) {
+        return (0, types_js_1.parseSpawnResult)(await this._runtime._rpc("mobkit/spawn_member", (0, models_js_1.discoverySpecToDict)(spec)));
+    }
+    async spawnMember(moduleId) {
+        return (0, types_js_1.parseSpawnResult)(await this._runtime._rpc("mobkit/spawn_member", { module_id: moduleId }));
+    }
+    async reconcile(modules) {
+        return (0, types_js_1.parseReconcileResult)(await this._runtime._rpc("mobkit/reconcile", { modules }));
+    }
+    // -- Event subscription -------------------------------------------------
+    async subscribeEvents(scope = "mob", lastEventId, agentId) {
+        const params = { scope };
+        if (lastEventId !== undefined)
+            params.last_event_id = lastEventId;
+        if (agentId !== undefined)
+            params.agent_id = agentId;
+        return (0, types_js_1.parseSubscribeResult)(await this._runtime._rpc("mobkit/events/subscribe", params));
+    }
+    async *subscribeAgent(memberId) {
+        const bridge = this._runtime.sseBridge();
+        for await (const sse of bridge.agentEvents(memberId)) {
+            yield (0, events_js_1.parseAgentEventFromSse)(sse);
+        }
+    }
+    async *subscribeMob() {
+        const bridge = this._runtime.sseBridge();
+        for await (const sse of bridge.mobEvents()) {
+            yield (0, events_js_1.parseMobEventFromSse)(sse);
+        }
+    }
+    async queryEvents(query) {
+        const params = query ? (0, types_js_1.eventQueryToDict)(query) : {};
+        const raw = await this._runtime._rpc("mobkit/query_events", params);
+        if (typeof raw === "object" &&
+            raw !== null &&
+            raw.status === "no_event_log_configured") {
+            return [];
+        }
+        if (Array.isArray(raw)) {
+            return raw.map(types_js_1.parsePersistedEvent);
+        }
+        return [];
+    }
+    // -- Messaging ----------------------------------------------------------
+    async send(memberId, message) {
+        return (0, types_js_1.parseSendMessageResult)(await this._runtime._rpc("mobkit/send_message", {
+            member_id: memberId,
+            message,
+        }));
+    }
+    /** Alias for {@link send}. */
+    sendMessage = this.send.bind(this);
+    async ensureMember(memberId, profile, options) {
+        const params = {
+            profile,
+            meerkat_id: memberId,
+        };
+        if (options?.labels)
+            params.labels = options.labels;
+        if (options?.context !== undefined)
+            params.context = options.context;
+        if (options?.resumeSessionId) {
+            params.resume_session_id = options.resumeSessionId;
+        }
+        if (options?.additionalInstructions) {
+            params.additional_instructions = options.additionalInstructions;
+        }
+        return (0, types_js_1.parseMemberSnapshot)(await this._runtime._rpc("mobkit/ensure_member", params));
+    }
+    async findMembers(labelKey, labelValue) {
+        const raw = await this._runtime._rpc("mobkit/find_members", {
+            label_key: labelKey,
+            label_value: labelValue,
+        });
+        if (Array.isArray(raw)) {
+            return raw.map(types_js_1.parseMemberSnapshot);
+        }
+        return [];
+    }
+    // -- Roster -------------------------------------------------------------
+    async listMembers() {
+        const raw = await this._runtime._rpc("mobkit/list_members");
+        if (Array.isArray(raw)) {
+            return raw.map(types_js_1.parseMemberSnapshot);
+        }
+        return [];
+    }
+    async getMember(memberId) {
+        return (0, types_js_1.parseMemberSnapshot)(await this._runtime._rpc("mobkit/get_member", { member_id: memberId }));
+    }
+    async retireMember(memberId) {
+        await this._runtime._rpc("mobkit/retire_member", {
+            member_id: memberId,
+        });
+    }
+    async respawnMember(memberId) {
+        await this._runtime._rpc("mobkit/respawn_member", {
+            member_id: memberId,
+        });
+    }
+    // -- Routing ------------------------------------------------------------
+    async resolveRouting(recipient, options) {
+        return (0, types_js_1.parseRoutingResolution)(await this._runtime._rpc("mobkit/routing/resolve", {
+            recipient,
+            ...(options ?? {}),
+        }));
+    }
+    async listRoutes() {
+        const raw = await this._runtime._rpc("mobkit/routing/routes/list");
+        const routes = typeof raw === "object" && raw !== null
+            ? raw.routes ?? []
+            : [];
+        return routes.map(types_js_1.parseRuntimeRouteResult);
+    }
+    async addRoute(routeKey, recipient, sink, targetModule, channel) {
+        const params = {
+            route_key: routeKey,
+            recipient,
+            sink,
+            target_module: targetModule,
+        };
+        if (channel !== undefined)
+            params.channel = channel;
+        const raw = await this._runtime._rpc("mobkit/routing/routes/add", params);
+        const routeData = typeof raw === "object" && raw !== null
+            ? raw.route ?? raw
+            : raw;
+        return (0, types_js_1.parseRuntimeRouteResult)(routeData);
+    }
+    async deleteRoute(routeKey) {
+        const raw = await this._runtime._rpc("mobkit/routing/routes/delete", {
+            route_key: routeKey,
+        });
+        const deletedData = typeof raw === "object" && raw !== null
+            ? raw.deleted ?? raw
+            : raw;
+        return (0, types_js_1.parseRuntimeRouteResult)(deletedData);
+    }
+    // -- Delivery -----------------------------------------------------------
+    async sendDelivery(options) {
+        return (0, types_js_1.parseDeliveryResult)(await this._runtime._rpc("mobkit/delivery/send", options));
+    }
+    async deliveryHistory(recipient, sink, limit = 20) {
+        const params = { limit };
+        if (recipient !== undefined)
+            params.recipient = recipient;
+        if (sink !== undefined)
+            params.sink = sink;
+        return (0, types_js_1.parseDeliveryHistoryResult)(await this._runtime._rpc("mobkit/delivery/history", params));
+    }
+    // -- Memory -------------------------------------------------------------
+    async memoryQuery(query, options) {
+        return (0, types_js_1.parseMemoryQueryResult)(await this._runtime._rpc("mobkit/memory/query", {
+            query,
+            ...(options ?? {}),
+        }));
+    }
+    async memoryStores() {
+        const raw = await this._runtime._rpc("mobkit/memory/stores");
+        const stores = typeof raw === "object" && raw !== null
+            ? raw.stores ?? []
+            : [];
+        return stores.map(types_js_1.parseMemoryStoreInfo);
+    }
+    async memoryIndex(entity, topic, store, options) {
+        return (0, types_js_1.parseMemoryIndexResult)(await this._runtime._rpc("mobkit/memory/index", {
+            entity,
+            topic,
+            store,
+            ...(options ?? {}),
+        }));
+    }
+    // -- Tools --------------------------------------------------------------
+    async callTool(moduleId, tool, args) {
+        const params = { module_id: moduleId, tool };
+        if (args)
+            params.arguments = args;
+        return (0, types_js_1.parseCallToolResult)(await this._runtime._rpc("mobkit/call_tool", params));
+    }
+    toolCaller(moduleId) {
+        return new ToolCaller(this, moduleId);
+    }
+    // -- Gating -------------------------------------------------------------
+    async gatingEvaluate(action, actorId, options) {
+        return (0, types_js_1.parseGatingEvaluateResult)(await this._runtime._rpc("mobkit/gating/evaluate", {
+            action,
+            actor_id: actorId,
+            ...(options ?? {}),
+        }));
+    }
+    async gatingPending() {
+        const raw = await this._runtime._rpc("mobkit/gating/pending");
+        const entries = typeof raw === "object" && raw !== null
+            ? raw.pending ?? []
+            : [];
+        return entries.map(types_js_1.parseGatingPendingEntry);
+    }
+    async gatingDecide(pendingId, decision, approverId, options) {
+        return (0, types_js_1.parseGatingDecisionResult)(await this._runtime._rpc("mobkit/gating/decide", {
+            pending_id: pendingId,
+            decision,
+            approver_id: approverId,
+            ...(options ?? {}),
+        }));
+    }
+    async gatingAudit(limit = 100) {
+        const raw = await this._runtime._rpc("mobkit/gating/audit", { limit });
+        const entries = typeof raw === "object" && raw !== null
+            ? raw.entries ?? []
+            : [];
+        return entries.map(types_js_1.parseGatingAuditEntry);
+    }
+    // -- Topology -----------------------------------------------------------
+    async rediscover() {
+        const raw = await this._runtime._rpc("mobkit/rediscover");
+        if (typeof raw === "object" &&
+            raw !== null &&
+            "status" in raw) {
+            return null;
+        }
+        return (0, types_js_1.parseRediscoverReport)(raw);
+    }
+    async reconcileEdges() {
+        return (0, types_js_1.parseReconcileEdgesReport)(await this._runtime._rpc("mobkit/reconcile_edges"));
+    }
+}
+exports.MobHandle = MobHandle;
+// -- ToolCaller -----------------------------------------------------------
+/**
+ * Bound callable scoped to one MCP module.
+ *
+ * @example
+ * ```ts
+ * const gmail = handle.toolCaller("google-workspace");
+ * const messages = await gmail.call("gmail_search", { query: "is:unread" });
+ * ```
+ */
+class ToolCaller {
+    _mobHandle;
+    _moduleId;
+    constructor(_mobHandle, _moduleId) {
+        this._mobHandle = _mobHandle;
+        this._moduleId = _moduleId;
+    }
+    async call(tool, args) {
+        const result = await this._mobHandle.callTool(this._moduleId, tool, args);
+        return result.result;
+    }
+}
+exports.ToolCaller = ToolCaller;
+// -- SseBridge ------------------------------------------------------------
+/**
+ * Bridge for streaming SSE from the Rust backend's HTTP server.
+ */
+class SseBridge {
+    _runtime;
+    constructor(_runtime) {
+        this._runtime = _runtime;
+    }
+    _baseUrl() {
+        const base = this._runtime.rustHttpBaseUrl;
+        if (base === null) {
+            throw new errors_js_1.NotConnectedError("SSE bridge requires rustHttpBaseUrl — set it via " +
+                "runtime.setRustHttpBase('http://127.0.0.1:8081') or " +
+                "ensure the Rust binary reports it during bootstrap");
+        }
+        return base;
+    }
+    async *agentEvents(agentId) {
+        const url = `${this._baseUrl()}/agents/${agentId}/events`;
+        yield* this._streamSse(url);
+    }
+    async *mobEvents() {
+        const url = `${this._baseUrl()}/mob/events`;
+        yield* this._streamSse(url);
+    }
+    async *_streamSse(url) {
+        const body = await this._fetchSseStream(url);
+        yield* (0, sse_js_1.parseSseStream)(body);
+    }
+    _fetchSseStream(url) {
+        const parsed = new URL(url);
+        const requester = parsed.protocol === "https:" ? node_https_1.request : node_http_1.request;
+        return new Promise((resolve, reject) => {
+            const req = requester(url, { method: "GET", headers: { accept: "text/event-stream" } }, (res) => {
+                if (!res.statusCode || res.statusCode >= 400) {
+                    reject(new Error(`SSE request failed: ${res.statusCode} ${res.statusMessage}`));
+                    res.resume();
+                    return;
+                }
+                // Convert Node readable stream to AsyncIterable<Uint8Array>
+                const stream = (async function* () {
+                    for await (const chunk of res) {
+                        yield chunk instanceof Uint8Array
+                            ? chunk
+                            : new TextEncoder().encode(String(chunk));
+                    }
+                })();
+                resolve(stream);
+            });
+            req.on("error", reject);
+            req.end();
+        });
+    }
+}
+exports.SseBridge = SseBridge;

package/dist/cjs/sse.cjs

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * SSE (Server-Sent Events) parsing and encoding.
+ *
+ * Internal module — not exported from the barrel. Used by the runtime
+ * SSE bridge for streaming agent and mob events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeSseEvent = encodeSseEvent;
+exports.parseSseStream = parseSseStream;
+// -- Encoding -------------------------------------------------------------
+/** Serialize an SSE event to the wire format. */
+function encodeSseEvent(event) {
+    const lines = [];
+    if (event.id !== null) {
+        lines.push(`id: ${event.id}`);
+    }
+    if (event.event !== "message") {
+        lines.push(`event: ${event.event}`);
+    }
+    for (const line of event.data.split("\n")) {
+        lines.push(`data: ${line}`);
+    }
+    lines.push("");
+    lines.push("");
+    return lines.join("\n");
+}
+// -- Parsing --------------------------------------------------------------
+/**
+ * Parse an SSE byte stream into typed {@link SseEvent} objects.
+ *
+ * Handles `id:`, `event:`, `data:` fields and comment lines (`:` prefix).
+ * Events are emitted on blank-line boundaries per the SSE spec.
+ */
+async function* parseSseStream(body) {
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    let currentId = null;
+    let currentEvent = "message";
+    const currentData = [];
+    for await (const chunk of body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        while (buffer.includes("\n")) {
+            const idx = buffer.indexOf("\n");
+            let line = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 1);
+            line = line.replace(/\r$/, "");
+            if (line === "") {
+                // Blank line — emit event if we have data
+                if (currentData.length > 0) {
+                    yield {
+                        id: currentId,
+                        event: currentEvent,
+                        data: currentData.join("\n"),
+                    };
+                }
+                currentId = null;
+                currentEvent = "message";
+                currentData.length = 0;
+            }
+            else if (line.startsWith(":")) {
+                // Comment — skip
+                continue;
+            }
+            else if (line.startsWith("id: ")) {
+                currentId = line.slice(4);
+            }
+            else if (line.startsWith("event: ")) {
+                currentEvent = line.slice(7);
+            }
+            else if (line.startsWith("data: ")) {
+                currentData.push(line.slice(6));
+            }
+            else if (line.startsWith("data:")) {
+                currentData.push(line.slice(5));
+            }
+        }
+    }
+}