@rkat/mobkit-sdk 0.5.1 → 0.6.2

package/dist/cjs/runtime.cjs

@@ -30,6 +30,19 @@ let requestCounter = 0;
 function nextRequestId(method) {
     return `${method}:${++requestCounter}`;
 }
+function extractMobStructuralEvents(raw) {
+    let events = raw;
+    if (typeof raw === "object" && raw !== null) {
+        const record = raw;
+        if (Array.isArray(record.events)) {
+            events = record.events;
+        }
+    }
+    if (!Array.isArray(events)) {
+        return [];
+    }
+    return events.map(types_js_1.parseMobStructuralEvent);
+}
 /** Serialize a config value for JSON transport.
  *
  * Recursively walks dicts/arrays with cycle detection. Calls toDict()
@@ -112,11 +125,20 @@ class MobKitRuntime {
                     this._rustHttpBase = String(initResult.http_base_url ?? "") || null;
                 }
             }
-            catch {
+            catch (err) {
+                // Pre-fix every error path here was rewritten to a generic
+                // `TransportError`, destroying the original RPC code/message
+                // (e.g. config errors like `bad mob.toml: line 7`). The fix:
+                // only synthesize TransportError when the subprocess actually
+                // died; otherwise re-throw the structured RpcError so operators
+                // can diagnose config errors without spelunking gateway logs.
                 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");
+                if ((0, errors_js_1.isRpcError)(err)) {
+                    throw err;
+                }
+                throw new errors_js_1.TransportError(`mobkit/init failed: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         else if (this._config.sessionBuilder) {
@@ -157,6 +179,9 @@ class MobKitRuntime {
             runtimeOptions.event_log = serializeConfig(this._config.eventLog);
         }
         params.runtime_options = runtimeOptions;
+        if (this._config.persistentState) {
+            params.persistent_state = this._config.persistentState;
+        }
         return params;
     }
     /** @internal */
@@ -169,7 +194,7 @@ class MobKitRuntime {
         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);
+            throw new errors_js_1.RpcError(Number(err.code ?? -1), String(err.message ?? String(err)), rid, method, err.data);
         }
         return response.result;
     }
@@ -195,6 +220,58 @@ class MobKitRuntime {
     get isRunning() {
         return this._running;
     }
+    // -- Identity-first APIs (REQ-47) -----------------------------------------
+    /** Get agent snapshot by identity. */
+    async agent(identity) {
+        return (0, types_js_1.parseMemberSnapshot)(await this._rpc("mobkit/identity/agent", { identity }));
+    }
+    /** Send content to an identity. Content can be a string or content blocks. */
+    async send(identity, content) {
+        const params = { identity };
+        if (typeof content === "string") {
+            params.content = content;
+        }
+        else {
+            params.content = content.map((b) => {
+                if (b.type === "image") {
+                    return { type: "image", media_type: b.mediaType, data: b.data };
+                }
+                return { type: "text", text: b.text };
+            });
+        }
+        return this._rpc("mobkit/identity/send", params);
+    }
+    /** Dispatch structured input to an identity. */
+    async dispatch(identity, input) {
+        return this._rpc("mobkit/identity/dispatch", {
+            identity,
+            dispatch_input: (0, types_js_1.dispatchInputToDict)(input),
+        });
+    }
+    /** Subscribe to events for an identity. */
+    async subscribe(identity) {
+        return this._rpc("mobkit/identity/subscribe", { identity });
+    }
+    /** Get identity status. */
+    async status(identity) {
+        return (0, types_js_1.parseIdentityStatus)(await this._rpc("mobkit/identity/status", { identity }));
+    }
+    /** Respawn an identity (non-destructive recovery). */
+    async respawn(identity) {
+        return this._rpc("mobkit/identity/respawn", { identity });
+    }
+    /** Retire an identity. */
+    async retire(identity) {
+        return this._rpc("mobkit/identity/retire", { identity });
+    }
+    /** Reset an identity (destructive continuity reset). */
+    async reset(identity) {
+        return this._rpc("mobkit/identity/reset", { identity });
+    }
+    /** Delete an identity permanently. */
+    async deleteIdentity(identity) {
+        return this._rpc("mobkit/identity/delete", { identity });
+    }
 }
 exports.MobKitRuntime = MobKitRuntime;
 // -- MobHandle ------------------------------------------------------------
@@ -205,7 +282,7 @@ exports.MobKitRuntime = MobKitRuntime;
  * ```ts
  * const handle = runtime.mobHandle();
  * const members = await handle.listMembers();
- * await handle.send(members[0].meerkatId, "Hello!");
+ * await handle.send(members[0].agentIdentity, "Hello!");
  * ```
  */
 class MobHandle {
@@ -255,16 +332,66 @@ class MobHandle {
     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 [];
+        let events = raw;
+        if (typeof raw === "object" && raw !== null) {
+            const record = raw;
+            if (record.status === "no_event_log_configured") {
+                events = Array.isArray(record.events) ? record.events : [];
+            }
         }
-        if (Array.isArray(raw)) {
-            return raw.map(types_js_1.parsePersistedEvent);
+        if (Array.isArray(events)) {
+            return events.map(types_js_1.parsePersistedEvent);
         }
         return [];
     }
+    /**
+     * Query structural mob events from the meerkat ledger. Pass the
+     * highest seen `cursor` as `EventQuery.afterSeq` on the next call to
+     * paginate. Without `afterSeq` the call returns the latest matching
+     * events (default `limit = 256`).
+     *
+     * Throws {@link MobEventsStaleError} when `afterSeq` is past the
+     * current ledger frontier; the exception carries `afterCursor` and
+     * `latestCursor` so callers can rewind.
+     */
+    async queryMobEvents(query) {
+        const params = query ? (0, types_js_1.eventQueryToDict)(query) : {};
+        try {
+            const raw = await this._runtime._rpc("mobkit/mob_events/query", params);
+            return extractMobStructuralEvents(raw);
+        }
+        catch (err) {
+            if ((0, errors_js_1.isRpcError)(err) && err.code === errors_js_1.MOB_EVENTS_STALE_CURSOR_CODE) {
+                throw errors_js_1.MobEventsStaleError.fromRpcError(err);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Replay structural mob events as an async iterator. Yields the
+     * snapshot frame returned by `mobkit/mob_events/subscribe`. Live
+     * tailing for production streaming uses the SSE bridge at
+     * `/mobkit/mob_events/stream`.
+     *
+     * Throws {@link MobEventsStaleError} when `afterSeq` is past the
+     * current ledger frontier.
+     */
+    async *subscribeMobEvents(query) {
+        const params = query ? (0, types_js_1.eventQueryToDict)(query) : {};
+        let raw;
+        try {
+            raw = await this._runtime._rpc("mobkit/mob_events/subscribe", params);
+        }
+        catch (err) {
+            if ((0, errors_js_1.isRpcError)(err) && err.code === errors_js_1.MOB_EVENTS_STALE_CURSOR_CODE) {
+                throw errors_js_1.MobEventsStaleError.fromRpcError(err);
+            }
+            throw err;
+        }
+        for (const event of extractMobStructuralEvents(raw)) {
+            yield event;
+        }
+    }
     // -- Messaging ----------------------------------------------------------
     async send(memberId, message) {
         return (0, types_js_1.parseSendMessageResult)(await this._runtime._rpc("mobkit/send_message", {
@@ -274,10 +401,10 @@ class MobHandle {
     }
     /** Alias for {@link send}. */
     sendMessage = this.send.bind(this);
-    async ensureMember(memberId, profile, options) {
+    async ensureMember(memberId, role, options) {
         const params = {
-            profile,
-            meerkat_id: memberId,
+            role,
+            agent_identity: memberId,
         };
         if (options?.labels)
             params.labels = options.labels;
@@ -322,6 +449,95 @@ class MobHandle {
             member_id: memberId,
         });
     }
+    /**
+     * Wait until all current mob members are startup-ready for orchestration.
+     *
+     * Relays meerkat 0.6's `MobHandle::wait_for_ready`. Returns
+     * `{ ready: [...], timeout: false }` on full convergence; on timeout
+     * returns `{ ready: [], timeout: true }`. Pass `timeoutSeconds` to bound
+     * the wait, or omit it to block indefinitely.
+     */
+    async waitReady(timeoutSeconds) {
+        const params = {};
+        if (timeoutSeconds !== undefined) {
+            params.timeout_ms = Math.round(timeoutSeconds * 1000);
+        }
+        const raw = await this._runtime._rpc("mobkit/wait_ready", params);
+        if (typeof raw !== "object" || raw === null) {
+            return { ready: [], timeout: false };
+        }
+        const r = raw;
+        return {
+            ready: Array.isArray(r.ready) ? r.ready : [],
+            timeout: Boolean(r.timeout),
+        };
+    }
+    // -- Flows --------------------------------------------------------------
+    /**
+     * List all configured flow IDs in this mob definition. Relays meerkat
+     * 0.6's `MobHandle::list_flows`. Order is unspecified.
+     */
+    async listFlows() {
+        const raw = await this._runtime._rpc("mobkit/list_flows");
+        if (Array.isArray(raw)) {
+            return raw.map((id) => String(id));
+        }
+        if (typeof raw === "object" && raw !== null) {
+            const flows = raw.flows;
+            if (Array.isArray(flows)) {
+                return flows.map((id) => String(id));
+            }
+        }
+        return [];
+    }
+    /**
+     * List flow runs for this mob, optionally filtered to one `flowId`.
+     * Relays `MobHandle::list_runs`. Each {@link MobRun} carries the full
+     * meerkat ledger projection — `step_ledger`, `failure_ledger`,
+     * `frames`, `loops`, `loop_iteration_ledger`, `flow_state`,
+     * `activation_params`, etc. — verbatim from the wire JSON.
+     */
+    async listRuns(flowId) {
+        const params = {};
+        if (flowId !== undefined)
+            params.flow_id = flowId;
+        const raw = await this._runtime._rpc("mobkit/list_runs", params);
+        let runs = [];
+        if (Array.isArray(raw)) {
+            runs = raw;
+        }
+        else if (typeof raw === "object" && raw !== null) {
+            const maybe = raw.runs;
+            if (Array.isArray(maybe)) {
+                runs = maybe;
+            }
+        }
+        const result = [];
+        for (const entry of runs) {
+            if (typeof entry === "object" && entry !== null) {
+                result.push((0, types_js_1.parseMobRun)(entry));
+            }
+        }
+        return result;
+    }
+    /**
+     * Start a flow run and return its run ID. Relays meerkat 0.6's
+     * `MobHandle::run_flow`. `params` is forwarded verbatim as the flow's
+     * activation params (any JSON value).
+     */
+    async runFlow(flowId, params = null) {
+        const raw = await this._runtime._rpc("mobkit/run_flow", {
+            flow_id: flowId,
+            params,
+        });
+        if (typeof raw === "object" && raw !== null) {
+            const runId = raw.run_id;
+            if (typeof runId === "string") {
+                return runId;
+            }
+        }
+        throw new Error(`unexpected run_flow response: ${JSON.stringify(raw)}`);
+    }
     // -- Routing ------------------------------------------------------------
     async resolveRouting(recipient, options) {
         return (0, types_js_1.parseRoutingResolution)(await this._runtime._rpc("mobkit/routing/resolve", {
@@ -447,6 +663,64 @@ class MobHandle {
     async reconcileEdges() {
         return (0, types_js_1.parseReconcileEdgesReport)(await this._runtime._rpc("mobkit/reconcile_edges"));
     }
+    // -- Mob/run labels — mobkit-side sidecar metadata ----------------------
+    /**
+     * Replace the label set associated with this mob.
+     *
+     * Mobkit owns these labels — they are separate from meerkat-mob's
+     * member-level labels. Replacement is wholesale; pass `{}` to clear.
+     */
+    async setMobLabels(labels) {
+        await this._runtime._rpc("mobkit/mob_labels/set", { labels });
+    }
+    /** Return the label set associated with this mob (or `{}`). */
+    async getMobLabels() {
+        const raw = await this._runtime._rpc("mobkit/mob_labels/get");
+        if (typeof raw !== "object" || raw === null)
+            return {};
+        const labels = raw.labels;
+        if (typeof labels !== "object" || labels === null)
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(labels)) {
+            out[k] = String(v);
+        }
+        return out;
+    }
+    /** Remove the label set associated with this mob. */
+    async deleteMobLabels() {
+        await this._runtime._rpc("mobkit/mob_labels/delete");
+    }
+    /**
+     * Replace the label set associated with `runId` under this mob.
+     * Replacement is wholesale (see {@link setMobLabels}).
+     */
+    async setRunLabels(runId, labels) {
+        await this._runtime._rpc("mobkit/run_labels/set", {
+            run_id: runId,
+            labels,
+        });
+    }
+    /** Return the label set for `runId` (or `{}`). */
+    async getRunLabels(runId) {
+        const raw = await this._runtime._rpc("mobkit/run_labels/get", {
+            run_id: runId,
+        });
+        if (typeof raw !== "object" || raw === null)
+            return {};
+        const labels = raw.labels;
+        if (typeof labels !== "object" || labels === null)
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(labels)) {
+            out[k] = String(v);
+        }
+        return out;
+    }
+    /** Remove the label set for `runId`. */
+    async deleteRunLabels(runId) {
+        await this._runtime._rpc("mobkit/run_labels/delete", { run_id: runId });
+    }
 }
 exports.MobHandle = MobHandle;
 // -- ToolCaller -----------------------------------------------------------
@@ -499,8 +773,18 @@ class SseBridge {
         yield* this._streamSse(url);
     }
     async *_streamSse(url) {
-        const body = await this._fetchSseStream(url);
-        yield* (0, sse_js_1.parseSseStream)(body);
+        // Pre-fix, breaking out of the consumer iterator left the
+        // underlying http.ClientRequest open — sockets and Node refs
+        // accumulated. Now: tie the request lifetime to the generator via
+        // try/finally so consumer `break`/`throw`/`return` always destroys
+        // the request.
+        const { body, destroy } = await this._fetchSseStream(url);
+        try {
+            yield* (0, sse_js_1.parseSseStream)(body);
+        }
+        finally {
+            destroy();
+        }
     }
     _fetchSseStream(url) {
         const parsed = new URL(url);
@@ -520,7 +804,13 @@ class SseBridge {
                             : new TextEncoder().encode(String(chunk));
                     }
                 })();
-                resolve(stream);
+                resolve({
+                    body: stream,
+                    destroy: () => {
+                        req.destroy();
+                        res.destroy();
+                    },
+                });
             });
             req.on("error", reject);
             req.end();

package/dist/cjs/sse.cjs

@@ -62,17 +62,21 @@ async function* parseSseStream(body) {
                 // Comment — skip
                 continue;
             }
-            else if (line.startsWith("id: ")) {
-                currentId = line.slice(4);
+            else if (line.startsWith("id:")) {
+                // Pre-fix only matched `id: ` with the optional space, so SSE-
+                // spec-legal `id:42` (no space) was dropped, breaking resume
+                // cursors. Strip a single optional leading space, mirroring
+                // the existing `data:` fallback below.
+                const v = line.slice(3);
+                currentId = v.startsWith(" ") ? v.slice(1) : v;
             }
-            else if (line.startsWith("event: ")) {
-                currentEvent = line.slice(7);
-            }
-            else if (line.startsWith("data: ")) {
-                currentData.push(line.slice(6));
+            else if (line.startsWith("event:")) {
+                const v = line.slice(6);
+                currentEvent = v.startsWith(" ") ? v.slice(1) : v;
             }
             else if (line.startsWith("data:")) {
-                currentData.push(line.slice(5));
+                const v = line.slice(5);
+                currentData.push(v.startsWith(" ") ? v.slice(1) : v);
             }
         }
     }

package/dist/cjs/transport.cjs

@@ -6,7 +6,7 @@
  * newline-delimited JSON. Supports bidirectional callbacks from Rust.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PersistentTransport = void 0;
+exports.DEFAULT_HTTP_TRANSPORT_TIMEOUT_MS = exports.PersistentTransport = void 0;
 exports.buildJsonRpcRequest = buildJsonRpcRequest;
 exports.createGatewaySyncTransport = createGatewaySyncTransport;
 exports.createGatewayAsyncTransport = createGatewayAsyncTransport;
@@ -249,6 +249,12 @@ function createGatewayAsyncTransport(gatewayBin) {
         });
     });
 }
+/**
+ * Default request timeout for {@link createJsonRpcHttpTransport}. A
+ * server that accepts the connection but never replies would otherwise
+ * leak the fetch task forever; pre-fix there was no timeout at all.
+ */
+exports.DEFAULT_HTTP_TRANSPORT_TIMEOUT_MS = 60_000;
 /**
  * Create an async HTTP POST transport.
  */
@@ -258,25 +264,49 @@ function createJsonRpcHttpTransport(endpoint, options = {}) {
     if (!fetchImpl) {
         throw new Error("fetch implementation not available");
     }
+    const timeoutMs = options.timeoutMs === undefined
+        ? exports.DEFAULT_HTTP_TRANSPORT_TIMEOUT_MS
+        : options.timeoutMs;
     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}`);
-        }
+        const controller = timeoutMs > 0 ? new AbortController() : undefined;
+        const timer = controller !== undefined && timeoutMs > 0
+            ? setTimeout(() => controller.abort(), timeoutMs)
+            : undefined;
         try {
-            return JSON.parse(body);
+            const response = await fetchImpl(endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    accept: "application/json",
+                    ...(options.headers ?? {}),
+                },
+                body: JSON.stringify(request),
+                signal: controller?.signal,
+            });
+            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");
+            }
         }
-        catch {
-            throw new Error("http transport returned non-JSON response");
+        catch (err) {
+            if (err !== null &&
+                typeof err === "object" &&
+                "name" in err &&
+                err.name === "AbortError") {
+                throw new Error(`http transport timed out after ${timeoutMs}ms; server unresponsive`);
+            }
+            throw err;
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
         }
     };
 }