@rkat/mobkit-sdk 0.4.9

package/dist/cjs/transport.cjs

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * Persistent subprocess transport for MobKit JSON-RPC.
+ *
+ * Keeps a long-lived gateway binary alive, communicating over stdin/stdout
+ * newline-delimited JSON. Supports bidirectional callbacks from Rust.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistentTransport = void 0;
+exports.buildJsonRpcRequest = buildJsonRpcRequest;
+exports.createGatewaySyncTransport = createGatewaySyncTransport;
+exports.createGatewayAsyncTransport = createGatewayAsyncTransport;
+exports.createJsonRpcHttpTransport = createJsonRpcHttpTransport;
+const node_child_process_1 = require("node:child_process");
+const node_readline_1 = require("node:readline");
+// -- Helpers --------------------------------------------------------------
+function buildJsonRpcRequest(id, method, params) {
+    return { jsonrpc: "2.0", id, method, params };
+}
+function sanitizeForJson(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj === "boolean" || typeof obj === "number" || typeof obj === "string")
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(sanitizeForJson);
+    if (typeof obj === "object") {
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            result[k] = sanitizeForJson(v);
+        }
+        return result;
+    }
+    return String(obj);
+}
+// -- PersistentTransport --------------------------------------------------
+/**
+ * Long-lived gateway subprocess communicating over stdin/stdout JSON-RPC.
+ *
+ * Uses a readline reader to multiplex responses and callbacks. Unlike
+ * per-call subprocess transports, this keeps the process alive so mob
+ * state persists across calls.
+ */
+class PersistentTransport {
+    gatewayBin;
+    _process = null;
+    _env;
+    _timeout;
+    _callbackHandler = null;
+    _pending = new Map();
+    constructor(gatewayBin, options) {
+        this.gatewayBin = gatewayBin;
+        this._env = { ...process.env, ...(options?.env ?? {}) };
+        this._timeout = options?.timeout ?? 60_000;
+    }
+    setCallbackHandler(handler) {
+        this._callbackHandler = handler;
+    }
+    start() {
+        if (this._process !== null && this._process.exitCode === null) {
+            return;
+        }
+        this._process = (0, node_child_process_1.spawn)(this.gatewayBin, ["--persistent"], {
+            env: this._env,
+            stdio: ["pipe", "pipe", "ignore"],
+        });
+        const child = this._process;
+        // Background reader on stdout
+        if (child.stdout) {
+            const rl = (0, node_readline_1.createInterface)({ input: child.stdout });
+            rl.on("line", (line) => {
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if ("method" in msg) {
+                    this._handleCallback(msg);
+                }
+                else if ("id" in msg) {
+                    const msgId = String(msg.id);
+                    const pending = this._pending.get(msgId);
+                    if (pending) {
+                        this._pending.delete(msgId);
+                        pending.resolve(msg);
+                    }
+                }
+            });
+            rl.on("close", () => {
+                // Process closed stdout — fail all pending requests
+                for (const [id, pending] of this._pending) {
+                    this._pending.delete(id);
+                    pending.resolve({
+                        jsonrpc: "2.0",
+                        id,
+                        error: { code: -32099, message: "subprocess died" },
+                    });
+                }
+            });
+        }
+        child.on("error", () => {
+            // Process spawn error — fail all pending
+            for (const [id, pending] of this._pending) {
+                this._pending.delete(id);
+                pending.reject(new Error("gateway process failed to start"));
+            }
+        });
+    }
+    _handleCallback(msg) {
+        if (!this._callbackHandler)
+            return;
+        const method = String(msg.method ?? "");
+        const params = (typeof msg.params === "object" && msg.params !== null
+            ? msg.params
+            : {});
+        const callbackId = msg.id !== undefined ? String(msg.id) : null;
+        this._callbackHandler(method, params)
+            .then((result) => {
+            if (callbackId === null)
+                return; // Notification — no response
+            this._writeLine({
+                jsonrpc: "2.0",
+                id: callbackId,
+                result: sanitizeForJson(result),
+            });
+        })
+            .catch((err) => {
+            if (callbackId === null)
+                return;
+            this._writeLine({
+                jsonrpc: "2.0",
+                id: callbackId,
+                error: { code: -32000, message: String(err instanceof Error ? err.message : err) },
+            });
+        });
+    }
+    _writeLine(obj) {
+        if (this._process?.stdin?.writable) {
+            this._process.stdin.write(JSON.stringify(obj) + "\n");
+        }
+    }
+    async sendAsync(request) {
+        this._ensureRunning();
+        const msgId = String(request.id ?? "");
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this._pending.delete(msgId);
+                reject(new Error(`persistent transport: timeout after ${this._timeout}ms`));
+            }, this._timeout);
+            this._pending.set(msgId, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                },
+            });
+            this._writeLine(request);
+        });
+    }
+    stop() {
+        if (this._process === null)
+            return;
+        try {
+            if (this._process.stdin) {
+                this._process.stdin.end();
+            }
+            this._process.kill();
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        finally {
+            this._process = null;
+        }
+    }
+    isRunning() {
+        return this._process !== null && this._process.exitCode === null;
+    }
+    _ensureRunning() {
+        if (!this.isRunning()) {
+            this.start();
+        }
+    }
+}
+exports.PersistentTransport = PersistentTransport;
+// -- Per-call transport factories -----------------------------------------
+/**
+ * Create a synchronous transport that spawns the gateway binary per call.
+ */
+function createGatewaySyncTransport(gatewayBin) {
+    return (request) => {
+        const requestJson = JSON.stringify(request);
+        const out = (0, node_child_process_1.spawnSync)(gatewayBin, [], {
+            env: { ...process.env, MOBKIT_RPC_REQUEST: requestJson },
+            encoding: "utf8",
+        });
+        if (out.status !== 0) {
+            throw new Error(`gateway failed (status=${out.status}): ${String(out.stderr ?? "")}`);
+        }
+        try {
+            return JSON.parse(String(out.stdout ?? ""));
+        }
+        catch {
+            throw new Error("gateway returned non-JSON response");
+        }
+    };
+}
+/**
+ * Create an async transport that spawns the gateway binary per call.
+ */
+function createGatewayAsyncTransport(gatewayBin) {
+    return async (request) => new Promise((resolve, reject) => {
+        const requestJson = JSON.stringify(request);
+        const child = (0, node_child_process_1.spawn)(gatewayBin, [], {
+            env: { ...process.env, MOBKIT_RPC_REQUEST: requestJson },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        if (child.stdout) {
+            child.stdout.setEncoding("utf8");
+            child.stdout.on("data", (chunk) => {
+                stdout += chunk;
+            });
+        }
+        if (child.stderr) {
+            child.stderr.setEncoding("utf8");
+            child.stderr.on("data", (chunk) => {
+                stderr += chunk;
+            });
+        }
+        child.on("error", (error) => reject(error));
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`gateway failed (status=${code}): ${stderr}`));
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch {
+                reject(new Error("gateway returned non-JSON response"));
+            }
+        });
+    });
+}
+/**
+ * Create an async HTTP POST transport.
+ */
+function createJsonRpcHttpTransport(endpoint, options = {}) {
+    const globalFetch = globalThis.fetch;
+    const fetchImpl = options.fetchImpl ?? globalFetch;
+    if (!fetchImpl) {
+        throw new Error("fetch implementation not available");
+    }
+    return async (request) => {
+        const response = await fetchImpl(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json",
+                ...(options.headers ?? {}),
+            },
+            body: JSON.stringify(request),
+        });
+        const body = await response.text();
+        if (!response.ok) {
+            throw new Error(`http transport failed (status=${response.status}): ${body}`);
+        }
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            throw new Error("http transport returned non-JSON response");
+        }
+    };
+}

package/dist/cjs/types.cjs

@@ -0,0 +1,376 @@
+"use strict";
+/**
+ * Typed return models for MobKit SDK RPC methods.
+ *
+ * All interfaces use `readonly` fields with camelCase naming. Parse functions
+ * convert from the wire protocol's snake_case representation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCategory = exports.MEMBER_STATE_RETIRING = exports.MEMBER_STATE_ACTIVE = void 0;
+exports.parseStatusResult = parseStatusResult;
+exports.parseCapabilitiesResult = parseCapabilitiesResult;
+exports.parseReconcileResult = parseReconcileResult;
+exports.parseSpawnResult = parseSpawnResult;
+exports.parseKeepAliveConfig = parseKeepAliveConfig;
+exports.parseEventEnvelope = parseEventEnvelope;
+exports.parseSubscribeResult = parseSubscribeResult;
+exports.parseSendMessageResult = parseSendMessageResult;
+exports.parseRoutingResolution = parseRoutingResolution;
+exports.parseDeliveryResult = parseDeliveryResult;
+exports.parseDeliveryHistoryResult = parseDeliveryHistoryResult;
+exports.parseMemoryQueryResult = parseMemoryQueryResult;
+exports.parseMemoryStoreInfo = parseMemoryStoreInfo;
+exports.parseMemoryIndexResult = parseMemoryIndexResult;
+exports.parseCallToolResult = parseCallToolResult;
+exports.parseMemberSnapshot = parseMemberSnapshot;
+exports.parseRuntimeRouteResult = parseRuntimeRouteResult;
+exports.parseGatingEvaluateResult = parseGatingEvaluateResult;
+exports.parseGatingDecisionResult = parseGatingDecisionResult;
+exports.parseGatingAuditEntry = parseGatingAuditEntry;
+exports.parseGatingPendingEntry = parseGatingPendingEntry;
+exports.parseReconcileEdgesReport = parseReconcileEdgesReport;
+exports.parseRediscoverReport = parseRediscoverReport;
+exports.parsePersistedEvent = parsePersistedEvent;
+exports.eventQueryToDict = eventQueryToDict;
+exports.parseErrorEvent = parseErrorEvent;
+// -- Helpers (internal) ---------------------------------------------------
+function asRecord(value) {
+    if (typeof value === "object" && value !== null) {
+        return value;
+    }
+    return {};
+}
+function asStringArray(value) {
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "string");
+    }
+    return [];
+}
+function asRecordArray(value) {
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "object" && v !== null);
+    }
+    return [];
+}
+function asStringRecord(value) {
+    const raw = asRecord(value);
+    const result = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v === "string") {
+            result[k] = v;
+        }
+    }
+    return result;
+}
+// -- Constants ------------------------------------------------------------
+exports.MEMBER_STATE_ACTIVE = "active";
+exports.MEMBER_STATE_RETIRING = "retiring";
+function parseStatusResult(raw) {
+    const d = asRecord(raw);
+    return {
+        contractVersion: String(d.contract_version ?? ""),
+        running: Boolean(d.running),
+        loadedModules: asStringArray(d.loaded_modules),
+    };
+}
+function parseCapabilitiesResult(raw) {
+    const d = asRecord(raw);
+    return {
+        contractVersion: String(d.contract_version ?? ""),
+        methods: asStringArray(d.methods),
+        loadedModules: asStringArray(d.loaded_modules),
+    };
+}
+function parseReconcileResult(raw) {
+    const d = asRecord(raw);
+    return {
+        accepted: Boolean(d.accepted),
+        reconciledModules: asStringArray(d.reconciled_modules),
+        added: Number(d.added ?? 0),
+    };
+}
+function parseSpawnResult(raw) {
+    const d = asRecord(raw);
+    return {
+        accepted: Boolean(d.accepted),
+        moduleId: String(d.module_id ?? ""),
+        meerkatId: typeof d.meerkat_id === "string" ? d.meerkat_id : null,
+        profile: typeof d.profile === "string" ? d.profile : null,
+    };
+}
+function parseKeepAliveConfig(raw) {
+    const d = asRecord(raw);
+    return {
+        intervalMs: Number(d.interval_ms ?? 0),
+        event: String(d.event ?? ""),
+    };
+}
+function parseEventEnvelope(raw) {
+    const d = asRecord(raw);
+    return {
+        eventId: String(d.event_id ?? ""),
+        source: String(d.source ?? ""),
+        timestampMs: Number(d.timestamp_ms ?? 0),
+        event: d.event,
+    };
+}
+function parseSubscribeResult(raw) {
+    const d = asRecord(raw);
+    const eventsRaw = Array.isArray(d.events) ? d.events : [];
+    return {
+        scope: String(d.scope ?? ""),
+        replayFromEventId: typeof d.replay_from_event_id === "string"
+            ? d.replay_from_event_id
+            : null,
+        keepAlive: parseKeepAliveConfig(d.keep_alive),
+        keepAliveComment: String(d.keep_alive_comment ?? ""),
+        eventFrames: asStringArray(d.event_frames),
+        events: eventsRaw.map(parseEventEnvelope),
+    };
+}
+function parseSendMessageResult(raw) {
+    const d = asRecord(raw);
+    return {
+        accepted: Boolean(d.accepted),
+        memberId: String(d.member_id ?? ""),
+        sessionId: String(d.session_id ?? ""),
+    };
+}
+function parseRoutingResolution(raw) {
+    const d = asRecord(raw);
+    return {
+        recipient: String(d.recipient ?? ""),
+        route: asRecord(d.route ?? d),
+    };
+}
+function parseDeliveryResult(raw) {
+    const d = asRecord(raw);
+    return {
+        delivered: Boolean(d.delivered),
+        deliveryId: String(d.delivery_id ?? ""),
+    };
+}
+function parseDeliveryHistoryResult(raw) {
+    const d = asRecord(raw);
+    return {
+        deliveries: asRecordArray(d.deliveries),
+    };
+}
+function parseMemoryQueryResult(raw) {
+    const d = asRecord(raw);
+    return {
+        results: asRecordArray(d.results),
+    };
+}
+function parseMemoryStoreInfo(raw) {
+    const d = asRecord(raw);
+    return {
+        store: String(d.store ?? ""),
+        recordCount: Number(d.record_count ?? 0),
+    };
+}
+function parseMemoryIndexResult(raw) {
+    const d = asRecord(raw);
+    return {
+        entity: String(d.entity ?? ""),
+        topic: String(d.topic ?? ""),
+        store: String(d.store ?? ""),
+        assertionId: typeof d.assertion_id === "string" ? d.assertion_id : null,
+    };
+}
+function parseCallToolResult(raw) {
+    const d = asRecord(raw);
+    return {
+        moduleId: String(d.module_id ?? ""),
+        tool: String(d.tool ?? ""),
+        result: d.result,
+    };
+}
+function parseMemberSnapshot(raw) {
+    const d = asRecord(raw);
+    return {
+        meerkatId: String(d.meerkat_id ?? ""),
+        profile: String(d.profile ?? ""),
+        state: String(d.state ?? ""),
+        wiredTo: asStringArray(d.wired_to),
+        labels: asStringRecord(d.labels),
+    };
+}
+function parseRuntimeRouteResult(raw) {
+    const d = asRecord(raw);
+    return {
+        routeKey: String(d.route_key ?? ""),
+        recipient: String(d.recipient ?? ""),
+        channel: typeof d.channel === "string" ? d.channel : null,
+        sink: String(d.sink ?? ""),
+        targetModule: String(d.target_module ?? ""),
+    };
+}
+function parseGatingEvaluateResult(raw) {
+    const d = asRecord(raw);
+    return {
+        actionId: String(d.action_id ?? ""),
+        action: String(d.action ?? ""),
+        actorId: String(d.actor_id ?? ""),
+        riskTier: typeof d.risk_tier === "string" ? d.risk_tier : null,
+        outcome: String(d.outcome ?? ""),
+        pendingId: typeof d.pending_id === "string" ? d.pending_id : null,
+    };
+}
+function parseGatingDecisionResult(raw) {
+    const d = asRecord(raw);
+    return {
+        pendingId: String(d.pending_id ?? ""),
+        actionId: String(d.action_id ?? ""),
+        decision: String(d.decision ?? ""),
+    };
+}
+function parseGatingAuditEntry(raw) {
+    const d = asRecord(raw);
+    return {
+        auditId: String(d.audit_id ?? ""),
+        timestampMs: Number(d.timestamp_ms ?? 0),
+        eventType: String(d.event_type ?? ""),
+        actionId: String(d.action_id ?? ""),
+        actorId: String(d.actor_id ?? ""),
+        riskTier: typeof d.risk_tier === "string" ? d.risk_tier : null,
+        outcome: String(d.outcome ?? ""),
+    };
+}
+function parseGatingPendingEntry(raw) {
+    const d = asRecord(raw);
+    return {
+        pendingId: String(d.pending_id ?? ""),
+        actionId: String(d.action_id ?? ""),
+        action: String(d.action ?? ""),
+        actorId: String(d.actor_id ?? ""),
+        riskTier: typeof d.risk_tier === "string" ? d.risk_tier : null,
+        createdAtMs: Number(d.created_at_ms ?? 0),
+    };
+}
+function parseReconcileEdgesReport(raw) {
+    const d = asRecord(raw);
+    const failures = asRecordArray(d.failures);
+    const skipped = asRecordArray(d.skipped_missing_members);
+    return {
+        desiredEdges: asRecordArray(d.desired_edges),
+        wiredEdges: asRecordArray(d.wired_edges),
+        unwiredEdges: asRecordArray(d.unwired_edges),
+        retainedEdges: asRecordArray(d.retained_edges),
+        preexistingEdges: asRecordArray(d.preexisting_edges),
+        skippedMissingMembers: skipped,
+        prunedStaleManagedEdges: asRecordArray(d.pruned_stale_managed_edges),
+        failures,
+        isComplete: failures.length === 0 && skipped.length === 0,
+    };
+}
+function parseRediscoverReport(raw) {
+    const d = asRecord(raw);
+    return {
+        spawned: asStringArray(d.spawned),
+        edges: parseReconcileEdgesReport(d.edges),
+    };
+}
+function parseUnifiedEvent(raw) {
+    const d = asRecord(raw);
+    if ("Agent" in d) {
+        const agent = asRecord(d.Agent);
+        return {
+            kind: "agent",
+            agentId: String(agent.agent_id ?? ""),
+            eventType: String(agent.event_type ?? ""),
+        };
+    }
+    if ("Module" in d) {
+        const mod = asRecord(d.Module);
+        return {
+            kind: "module",
+            module: String(mod.module ?? ""),
+            eventType: String(mod.event_type ?? ""),
+            payload: asRecord(mod.payload),
+        };
+    }
+    return {
+        kind: "module",
+        module: "unknown",
+        eventType: "unknown",
+        payload: asRecord(raw),
+    };
+}
+function parsePersistedEvent(raw) {
+    const d = asRecord(raw);
+    const rawEvent = d.event;
+    const event = typeof rawEvent === "object" && rawEvent !== null
+        ? parseUnifiedEvent(rawEvent)
+        : { kind: "module", module: "unknown", eventType: "unknown", payload: {} };
+    return {
+        id: String(d.id ?? ""),
+        seq: Number(d.seq ?? 0),
+        timestampMs: Number(d.timestamp_ms ?? 0),
+        memberId: typeof d.member_id === "string" ? d.member_id : null,
+        event,
+    };
+}
+function eventQueryToDict(query) {
+    const d = {};
+    if (query.sinceMs !== undefined)
+        d.since_ms = query.sinceMs;
+    if (query.untilMs !== undefined)
+        d.until_ms = query.untilMs;
+    if (query.memberId !== undefined)
+        d.member_id = query.memberId;
+    if (query.eventTypes !== undefined && query.eventTypes.length > 0) {
+        d.event_types = [...query.eventTypes];
+    }
+    if (query.limit !== undefined)
+        d.limit = query.limit;
+    if (query.afterSeq !== undefined)
+        d.after_seq = query.afterSeq;
+    return d;
+}
+// -- ErrorCategory / ErrorEvent -------------------------------------------
+exports.ErrorCategory = {
+    SPAWN_FAILURE: "spawn_failure",
+    RECONCILE_INCOMPLETE: "reconcile_incomplete",
+    CHECKPOINT_FAILURE: "checkpoint_failure",
+    HOST_LOOP_CRASH: "host_loop_crash",
+    REDISCOVER_FAILURE: "rediscover_failure",
+};
+function parseErrorEvent(raw) {
+    const d = asRecord(raw);
+    const category = String(d.category ?? "unknown");
+    const context = {};
+    for (const [k, v] of Object.entries(d)) {
+        if (k !== "category")
+            context[k] = v;
+    }
+    const error = String(context.error ?? "");
+    const memberId = String(context.member_id ?? "");
+    let message;
+    switch (category) {
+        case exports.ErrorCategory.SPAWN_FAILURE:
+            message = memberId ? `${memberId}: ${error}` : error;
+            break;
+        case exports.ErrorCategory.RECONCILE_INCOMPLETE: {
+            const failures = Number(context.failures ?? 0);
+            const skipped = Number(context.skipped ?? 0);
+            message = `${failures} failures, ${skipped} skipped`;
+            break;
+        }
+        case exports.ErrorCategory.CHECKPOINT_FAILURE: {
+            const sessionId = String(context.session_id ?? "");
+            message = sessionId ? `${sessionId}: ${error}` : error;
+            break;
+        }
+        case exports.ErrorCategory.HOST_LOOP_CRASH:
+            message = memberId ? `${memberId}: ${error}` : error;
+            break;
+        case exports.ErrorCategory.REDISCOVER_FAILURE:
+            message = error;
+            break;
+        default:
+            message = JSON.stringify(d);
+            break;
+    }
+    return { category, message, context };
+}