@plexspaces/sdk 0.1.5 → 0.1.8

package/dist/host.js

@@ -4,7 +4,7 @@
 // PlexSpaces Host Functions (TypeScript SDK)
 //
 // Provides TypeScript wrappers for WIT host imports.
-// Uses virtual imports from 'plexspaces:actor/host@0.1.0'.
+// Uses virtual imports split across 9+ per-interface modules (host-logging, host-actor, host-kv, host-ts, host-locks, host-blob, host-pool, host-shard, host-http, registry).
 // Protobuf wire for WIT `payload` fields (matches Go WASM hostWire* / tuplespace_proto_wire).
 import { decodeReadResponseAllTuples, decodeReadResponseFirstTuple, encodeReadRequest, encodeWriteRequest, } from './wire/tuplespace-proto-wire.js';
 import { decodeHttpFetchResponseWire, encodeHttpFetchRequestWire } from './wire/http-fetch-proto-wire.js';
@@ -13,15 +13,18 @@ import { decodeWitPayloadUtf8, encodeWitPayloadUtf8 } from './wit-payload.js';
 import { encodeRegisterRequest, encodeUnregisterRequest, encodeLookupRequest, encodeDiscoverRequest, encodeHeartbeatRequest, decodeLookupResponse, decodeDiscoverResponse, ObjectType as RegistryObjectType, } from './wire/registry-proto-wire.js';
 import { firstGroupMember, firstGroupMemberOrThrow } from './process_groups.js';
 // Virtual imports provided by jco componentize at runtime.
-// These map 1:1 to the WIT host interface functions.
-// @ts-ignore
-import { send as hostSend, ask as hostAsk, log as hostLog, nowMs as hostNowMs, selfId as hostSelfId, spawn as hostSpawn, stop as hostStop, link as hostLink, unlink as hostUnlink, monitor as hostMonitor, demonitor as hostDemonitor, sendAfter as hostSendAfter, kvGet as hostKvGet, kvPut as hostKvPut, kvDelete as hostKvDelete, kvList as hostKvList, tsWrite as hostTsWrite, tsRead as hostTsRead, tsTake as hostTsTake, tsReadAll as hostTsReadAll, lockAcquire as hostLockAcquire, lockRelease as hostLockRelease, lockRenew as hostLockRenew, blobUpload as hostBlobUpload, blobDownload as hostBlobDownload, blobDelete as hostBlobDelete, blobList as hostBlobList, pgJoin as hostPgJoin, pgLeave as hostPgLeave, pgMembers as hostPgMembers, pgBroadcast as hostPgBroadcast, poolCheckout as hostPoolCheckout, poolCheckin as hostPoolCheckin, poolGetMetrics as hostPoolGetMetrics, createShardGroup as hostCreateShardGroup, bulkUpdateShardGroup as hostBulkUpdateShardGroup, mapShardGroup as hostMapShardGroup, scatterGather as hostScatterGather, broadcastShardGroup as hostBroadcastShardGroup, reduceShardGroup as hostReduceShardGroup, allReduceShardGroup as hostAllReduceShardGroup, barrierShardGroup as hostBarrierShardGroup, spawnActors as hostSpawnActors, applicationMetricsAdd as hostApplicationMetricsAdd, applicationGetMetrics as hostApplicationGetMetrics, applicationGetStatus as hostApplicationGetStatus, httpFetch as hostHttpFetch,
-// @ts-expect-error Virtual import
- } from 'plexspaces:actor/host@0.1.0';
-// @ts-ignore
-import { register as hostRegistryRegister, unregister as hostRegistryUnregister, lookup as hostRegistryLookup, lookupByAlias as hostRegistryLookupByAlias, discover as hostRegistryDiscover, heartbeat as hostRegistryHeartbeat,
-// @ts-expect-error Virtual import
- } from 'plexspaces:actor/registry@0.1.0';
+// These map 1:1 to the WIT host interface functions (split by namespace).
+// Types resolved via paths in tsconfig.json; resolved at runtime by jco componentize.
+import { log as hostLog, nowMs as hostNowMs } from 'plexspaces:actor/host-logging@0.1.0';
+import { send as hostSend, ask as hostAsk, selfId as hostSelfId, spawn as hostSpawn, stop as hostStop, link as hostLink, unlink as hostUnlink, monitor as hostMonitor, demonitor as hostDemonitor, sendAfter as hostSendAfter, pgJoin as hostPgJoin, pgLeave as hostPgLeave, pgMembers as hostPgMembers, pgBroadcast as hostPgBroadcast, } from 'plexspaces:actor/host-actor@0.1.0';
+import { kvGet as hostKvGet, kvPut as hostKvPut, kvDelete as hostKvDelete, kvList as hostKvList, kvPutWithTtl as hostKvPutWithTtl, kvGetTtl as hostKvGetTtl, kvCas as hostKvCas, kvIncrement as hostKvIncrement, kvMultiGet as hostKvMultiGet, kvMultiPut as hostKvMultiPut, alarmSet as hostAlarmSet, alarmGet as hostAlarmGet, alarmDelete as hostAlarmDelete, } from 'plexspaces:actor/host-kv@0.1.0';
+import { tsWrite as hostTsWrite, tsRead as hostTsRead, tsTake as hostTsTake, tsReadAll as hostTsReadAll, } from 'plexspaces:actor/host-ts@0.1.0';
+import { lockAcquire as hostLockAcquire, lockRelease as hostLockRelease, lockRenew as hostLockRenew, } from 'plexspaces:actor/host-locks@0.1.0';
+import { blobUpload as hostBlobUpload, blobDownload as hostBlobDownload, blobDelete as hostBlobDelete, blobList as hostBlobList, } from 'plexspaces:actor/host-blob@0.1.0';
+import { poolCheckout as hostPoolCheckout, poolCheckin as hostPoolCheckin, poolGetMetrics as hostPoolGetMetrics, } from 'plexspaces:actor/host-pool@0.1.0';
+import { createShardGroup as hostCreateShardGroup, bulkUpdateShardGroup as hostBulkUpdateShardGroup, mapShardGroup as hostMapShardGroup, broadcastShardGroup as hostBroadcastShardGroup, reduceShardGroup as hostReduceShardGroup, allReduceShardGroup as hostAllReduceShardGroup, barrierShardGroup as hostBarrierShardGroup, scatterGather as hostScatterGather, spawnActors as hostSpawnActors, applicationMetricsAdd as hostApplicationMetricsAdd, applicationGetMetrics as hostApplicationGetMetrics, applicationGetStatus as hostApplicationGetStatus, } from 'plexspaces:actor/host-shard@0.1.0';
+import { httpFetch as hostHttpFetch } from 'plexspaces:actor/host-http@0.1.0';
+import { register as hostRegistryRegister, unregister as hostRegistryUnregister, lookup as hostRegistryLookup, lookupByAlias as hostRegistryLookupByAlias, discover as hostRegistryDiscover, heartbeat as hostRegistryHeartbeat, } from 'plexspaces:actor/registry@0.1.0';
 /**
  * Safe call helper — returns empty string if function is undefined.
  */
@@ -62,6 +65,39 @@ function hostErrorPrefixBytes(raw) {
     }
     return true;
 }
+/** Encode bytes to base64 string without using btoa (works in Node.js and WASM). */
+function bytesToBase64(bytes) {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+    let result = '';
+    const len = bytes.length;
+    for (let i = 0; i < len; i += 3) {
+        const b0 = bytes[i];
+        const b1 = i + 1 < len ? bytes[i + 1] : 0;
+        const b2 = i + 2 < len ? bytes[i + 2] : 0;
+        result += chars[b0 >> 2] + chars[((b0 & 3) << 4) | (b1 >> 4)] + (i + 1 < len ? chars[((b1 & 15) << 2) | (b2 >> 6)] : '=') + (i + 2 < len ? chars[b2 & 63] : '=');
+    }
+    return result;
+}
+/** Decode base64 string to bytes without using atob (works in Node.js and WASM). */
+function base64ToBytes(b64) {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+    const clean = b64.replace(/=+$/, '');
+    const len = clean.length;
+    const bytes = new Uint8Array(Math.floor(len * 3 / 4));
+    let pos = 0;
+    for (let i = 0; i < len; i += 4) {
+        const c0 = chars.indexOf(clean[i]);
+        const c1 = chars.indexOf(clean[i + 1]);
+        const c2 = i + 2 < len ? chars.indexOf(clean[i + 2]) : 0;
+        const c3 = i + 3 < len ? chars.indexOf(clean[i + 3]) : 0;
+        bytes[pos++] = (c0 << 2) | (c1 >> 4);
+        if (i + 2 < len)
+            bytes[pos++] = ((c1 & 15) << 4) | (c2 >> 2);
+        if (i + 3 < len)
+            bytes[pos++] = ((c2 & 3) << 6) | c3;
+    }
+    return bytes.subarray(0, pos);
+}
 /**
  * Tuple space helper: list-in, list-out API.
  * Use null in patterns for wildcards. Consistent with Python host.ts and Go host.TS().
@@ -273,6 +309,240 @@ export class Registry {
     }
 }
 export { RegistryObjectType };
+/**
+ * KVStore provides namespaced KV operations.
+ * Equivalent to Cloudflare DO's this.state.storage API.
+ * Access via host.kv.get(), host.kv.put() etc.
+ */
+export class KVStore {
+    get(key) {
+        if (typeof hostKvGet !== 'function')
+            return null;
+        try {
+            const v = decodeWitPayloadUtf8(hostKvGet(key));
+            return v || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    put(key, value) {
+        if (typeof hostKvPut !== 'function')
+            return;
+        try {
+            hostKvPut(key, encodeWitPayloadUtf8(value));
+        }
+        catch { /* ignore */ }
+    }
+    delete(key) {
+        if (typeof hostKvDelete !== 'function')
+            return;
+        try {
+            hostKvDelete(key);
+        }
+        catch { /* ignore */ }
+    }
+    list(prefix) {
+        if (typeof hostKvList !== 'function')
+            return [];
+        try {
+            return hostKvList(prefix);
+        }
+        catch {
+            return [];
+        }
+    }
+    putWithTtl(key, value, ttlSeconds) {
+        if (typeof hostKvPutWithTtl !== 'function')
+            return;
+        hostKvPutWithTtl(key, encodeWitPayloadUtf8(value), BigInt(ttlSeconds));
+    }
+    getTtl(key) {
+        if (typeof hostKvGetTtl !== 'function')
+            return 0;
+        try {
+            return Number(hostKvGetTtl(key));
+        }
+        catch {
+            return 0;
+        }
+    }
+    cas(key, expected, newValue) {
+        if (typeof hostKvCas !== 'function')
+            return false;
+        const expectedBytes = expected !== null ? encodeWitPayloadUtf8(expected) : new Uint8Array(0);
+        return hostKvCas(key, expectedBytes, encodeWitPayloadUtf8(newValue));
+    }
+    increment(key, delta) {
+        if (typeof hostKvIncrement !== 'function')
+            return 0;
+        try {
+            return Number(hostKvIncrement(key, BigInt(delta)));
+        }
+        catch {
+            return 0;
+        }
+    }
+    multiGet(keys) {
+        if (typeof hostKvMultiGet !== 'function')
+            return keys.map(() => null);
+        try {
+            const keysJson = encodeWitPayloadUtf8(JSON.stringify(keys));
+            const resultBytes = hostKvMultiGet(keysJson);
+            const resultJson = decodeWitPayloadUtf8(resultBytes);
+            const items = JSON.parse(resultJson);
+            return items.map(v => { if (v === null)
+                return null; const b = base64ToBytes(v); return new TextDecoder().decode(b); });
+        }
+        catch {
+            return keys.map(() => null);
+        }
+    }
+    multiPut(entries) {
+        if (typeof hostKvMultiPut !== 'function')
+            return;
+        const encoded = {};
+        for (const [k, v] of Object.entries(entries)) {
+            encoded[k] = bytesToBase64(new TextEncoder().encode(v));
+        }
+        const entriesJson = encodeWitPayloadUtf8(JSON.stringify(encoded));
+        hostKvMultiPut(entriesJson);
+    }
+    getJson(key) {
+        const raw = this.get(key);
+        if (!raw || raw.startsWith('ERROR:'))
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    putJson(key, value) {
+        const serialized = JSON.stringify(value);
+        this.put(key, serialized);
+    }
+}
+/**
+ * AlarmClient provides durable alarm scheduling.
+ * Equivalent to Cloudflare DO's setAlarm/getAlarm/deleteAlarm.
+ * Access via host.alarm.set(), host.alarm.get(), host.alarm.delete() etc.
+ */
+export class AlarmClient {
+    set(timestampMs) {
+        if (typeof hostAlarmSet !== 'function')
+            return;
+        hostAlarmSet(BigInt(timestampMs));
+    }
+    setIn(delayMs) {
+        if (typeof hostNowMs !== 'function')
+            return;
+        const now = Number(hostNowMs());
+        this.set(now + delayMs);
+    }
+    get() {
+        if (typeof hostAlarmGet !== 'function')
+            return 0;
+        try {
+            return Number(hostAlarmGet());
+        }
+        catch {
+            return 0;
+        }
+    }
+    delete() {
+        if (typeof hostAlarmDelete !== 'function')
+            return;
+        hostAlarmDelete();
+    }
+}
+/**
+ * LockClient provides distributed lock operations.
+ * Access via host.locks.acquire(), host.locks.release() etc.
+ */
+export class LockClient {
+    acquire(holderId, lockName, leaseDurationSecs, timeoutMs) {
+        const result = hostLockAcquire(holderId, lockName, leaseDurationSecs, timeoutMs);
+        if (typeof result === 'string')
+            throw new Error(result);
+        return result;
+    }
+    release(lockId, holderId, lockVersion) {
+        const result = hostLockRelease(lockId, holderId, lockVersion);
+        if (typeof result === 'string')
+            throw new Error(result);
+    }
+    renew(lockId, holderId, lockVersion, leaseDurationSecs) {
+        const result = hostLockRenew(lockId, holderId, lockVersion, leaseDurationSecs);
+        if (typeof result === 'string')
+            throw new Error(result);
+        return result;
+    }
+}
+/**
+ * BlobClient provides blob storage operations.
+ * Access via host.blob.upload(), host.blob.download() etc.
+ */
+export class BlobClient {
+    upload(name, data, contentType) {
+        const result = hostBlobUpload(name, data, contentType);
+        if (typeof result !== 'string' || result.startsWith('ERROR:'))
+            throw new Error(String(result));
+        return result;
+    }
+    download(blobId) {
+        const result = hostBlobDownload(blobId);
+        if (typeof result === 'string')
+            throw new Error(result);
+        return result;
+    }
+    delete(blobId) {
+        const result = hostBlobDelete(blobId);
+        if (typeof result === 'string')
+            throw new Error(result);
+    }
+    list(prefix) {
+        const result = hostBlobList(prefix);
+        if (Array.isArray(result))
+            return result;
+        return [];
+    }
+}
+/**
+ * ActorRef is a lightweight handle to a named virtual actor.
+ * Equivalent to Cloudflare DO's env.BINDING.get(id).
+ * Use getActorRef() to obtain one.
+ *
+ * @example
+ * ```typescript
+ * const room = getActorRef("ChatRoomActor", roomId, "default");
+ * const result = room.ask("send_message", payload, BigInt(5000));
+ * ```
+ */
+export class ActorRef {
+    constructor(actorType, name, namespace) {
+        this.actorId = `${name}//${actorType}::${namespace}@*`;
+    }
+    id() { return this.actorId; }
+    tell(msgType, payload) {
+        hostSend(this.actorId, msgType, payload);
+    }
+    ask(msgType, payload, timeoutMs) {
+        const result = hostAsk(this.actorId, msgType, payload, timeoutMs);
+        if (typeof result === 'string')
+            throw new Error(result);
+        return result;
+    }
+}
+/**
+ * getActorRef constructs an ActorRef for a named virtual actor.
+ * The actor is created automatically on first contact (virtual actor pattern).
+ * Equivalent to Cloudflare: `const room = env.CHAT_ROOM.get(roomId)`
+ */
+export function getActorRef(actorType, name, namespace) {
+    return new ActorRef(actorType, name, namespace);
+}
 export class Host {
     constructor() {
         this.processGroups = new ProcessGroups();
@@ -280,6 +550,33 @@ export class Host {
         this.ts = new TupleSpace(this);
         /** Object registry: register, discover, and look up actors and services. */
         this.registry = new Registry();
+        /** Namespaced KV store: host.kv.get(), host.kv.put() etc. */
+        this.kv = new KVStore();
+        /** Durable alarm client: host.alarm.set(), host.alarm.get() etc. */
+        this.alarm = new AlarmClient();
+        /** Distributed lock client: host.locks.acquire(), host.locks.release() etc. */
+        this.locks = new LockClient();
+        /** Blob storage client: host.blob.upload(), host.blob.download() etc. */
+        this.blob = new BlobClient();
+    }
+    /**
+     * Create an ergonomic HTTP client for a named service link.
+     *
+     * The link must be pre-configured in RuntimeConfig.service_links.
+     * The host handles retries, circuit breaking, and auth injection.
+     *
+     * @param linkName - Service link name (e.g. "payments-api")
+     * @returns A {@link ServiceHttpClient} bound to that link
+     *
+     * @example
+     * ```typescript
+     * const http = host.httpClient("payments-api");
+     * const balance = http.get("/v1/balance?account=123");
+     * const result = http.post("/v1/transfer", { amount: 100 });
+     * ```
+     */
+    httpClient(linkName) {
+        return new ServiceHttpClient(linkName);
     }
     // ========================================================================
     // Messaging
@@ -322,14 +619,21 @@ export class Host {
     // ========================================================================
     /**
      * Spawn a new actor through the framework-owned actor spawn path exposed by the host.
+     * Returns the canonical actor ID assigned by the framework — use this ID (not actorName)
+     * for all subsequent ask/send/stop calls.
+     *
      * @param moduleRef - Actor type/module reference (must be deployed)
-     * @param actorId - Unique ID for the new actor (empty = auto-generated ULID)
-     * @param initConfig - Optional config passed to the new actor's init()
-     * @returns Spawned actor ID string (may be auto-generated if actorId was empty)
+     * @param actorName - Requested name for the new actor. The framework forms the full canonical
+     *                    ID from this name, moduleRef, namespace and node. Pass empty string to
+     *                    let the framework auto-generate a ULID name.
+     * @param role - Disambiguation key used ONLY when multiple actors in the same supervisor share
+     *               the same actor_type (moduleRef). Pass empty string when moduleRef is unique.
+     * @param args - Key-value init arguments forwarded to the new actor's init()
+     * @returns Canonical actor ID string assigned by the framework
      */
-    spawn(moduleRef, actorId = '', initConfig) {
-        const configBytes = encodeWitPayloadUtf8(initConfig !== undefined ? JSON.stringify(initConfig) : '{}');
-        const result = safeCall(hostSpawn, moduleRef, actorId, configBytes);
+    spawn(moduleRef, actorName = '', role = '', args = {}) {
+        const argsJson = Object.keys(args).length > 0 ? JSON.stringify(args) : '{}';
+        const result = safeCall(hostSpawn, moduleRef, actorName, role, argsJson);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
@@ -418,71 +722,6 @@ export class Host {
         const result = safeCall(hostNowMs);
         return typeof result === 'bigint' ? Number(result) : (typeof result === 'number' ? result : 0);
     }
-    // ========================================================================
-    // Key-Value Store
-    // ========================================================================
-    kvGet(key) {
-        if (typeof hostKvGet !== 'function')
-            return '';
-        try {
-            return decodeWitPayloadUtf8(hostKvGet(key));
-        }
-        catch (e) {
-            return `ERROR:${e}`;
-        }
-    }
-    kvPut(key, value) {
-        if (typeof hostKvPut !== 'function')
-            return '';
-        try {
-            hostKvPut(key, encodeWitPayloadUtf8(value));
-            return '';
-        }
-        catch (e) {
-            return `ERROR:${e}`;
-        }
-    }
-    kvDelete(key) {
-        if (typeof hostKvDelete !== 'function')
-            return '';
-        try {
-            hostKvDelete(key);
-            return '';
-        }
-        catch (e) {
-            return `ERROR:${e}`;
-        }
-    }
-    kvList(prefix) {
-        if (typeof hostKvList !== 'function')
-            return '[]';
-        try {
-            return JSON.stringify(hostKvList(prefix));
-        }
-        catch (e) {
-            return `ERROR:${e}`;
-        }
-    }
-    /** Retrieve a JSON value by key. Returns parsed object or null if not found. */
-    kvGetJson(key) {
-        const raw = this.kvGet(key);
-        if (!raw || raw.startsWith('ERROR:'))
-            return null;
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
-    }
-    /** Serialize value to JSON and store under key. Throws on write failure. */
-    kvPutJson(key, value) {
-        const serialized = JSON.stringify(value);
-        const result = this.kvPut(key, serialized);
-        if (typeof result === 'string' && result.startsWith('ERROR:')) {
-            throw new Error(`kvPutJson(${key}): ${result}`);
-        }
-    }
     /** Increment a single named application metric counter by 1. Errors are swallowed. */
     incrCounter(applicationId, name) {
         this.incrCounters(applicationId, { [name]: 1 });
@@ -520,27 +759,6 @@ export class Host {
         return hostPayloadToBytes(safeCall(hostTsReadAll, data));
     }
     // ========================================================================
-    // Distributed Locks
-    // ========================================================================
-    lockAcquire(tenantId, namespace, holderId, lockName, leaseDurationSecs = 30, timeoutMs = 0) {
-        return safeCall(hostLockAcquire, tenantId, namespace, holderId, lockName, leaseDurationSecs, BigInt(timeoutMs));
-    }
-    lockRelease(lockId, tenantId, namespace, holderId, lockVersion) {
-        return safeCall(hostLockRelease, lockId, tenantId, namespace, holderId, lockVersion);
-    }
-    lockRenew(lockId, tenantId, namespace, holderId, lockVersion, leaseDurationSecs = 30) {
-        return safeCall(hostLockRenew, lockId, tenantId, namespace, holderId, lockVersion, leaseDurationSecs);
-    }
-    // ========================================================================
-    // Blob Storage
-    // ========================================================================
-    blobUpload(blobId, data, contentType = 'application/octet-stream') {
-        return safeCall(hostBlobUpload, blobId, data, contentType);
-    }
-    blobDownload(blobId) { return safeCall(hostBlobDownload, blobId); }
-    blobDelete(blobId) { return safeCall(hostBlobDelete, blobId); }
-    blobList(prefix) { return safeCall(hostBlobList, prefix); }
-    // ========================================================================
     // Elastic pool (checkout/checkin)
     // ========================================================================
     /**
@@ -749,7 +967,7 @@ export class EventLog {
         this.watermark++;
         const key = `${prefix}seq:${this.watermark}`;
         try {
-            h.kvPutJson(key, entry);
+            h.kv.putJson(key, entry);
         }
         catch (e) {
             this.watermark--;
@@ -763,19 +981,19 @@ export class EventLog {
      */
     poll(h, prefix, consumerId, limit = 100) {
         const cursorKey = `${prefix}cursor:${consumerId}`;
-        const rawCursor = h.kvGet(cursorKey);
+        const rawCursor = h.kv.get(cursorKey);
         const cursor = rawCursor ? parseInt(rawCursor, 10) || 0 : 0;
         const events = [];
         let newCursor = cursor;
         for (let seq = cursor + 1; seq <= this.watermark && events.length < limit; seq++) {
-            const entry = h.kvGetJson(`${prefix}seq:${seq}`);
+            const entry = h.kv.getJson(`${prefix}seq:${seq}`);
             if (entry !== null) {
                 events.push(entry);
                 newCursor = seq;
             }
         }
         if (newCursor !== cursor) {
-            h.kvPut(cursorKey, String(newCursor));
+            h.kv.put(cursorKey, String(newCursor));
         }
         return [events, newCursor];
     }
@@ -786,9 +1004,13 @@ export class EventLog {
  * The link must be pre-configured in RuntimeConfig.service_links.
  * The host handles retries, circuit breaking, and auth injection.
  *
+ * Prefer creating instances via {@link Host.httpClient} rather than calling
+ * the constructor directly:
+ *
  * @example
  * ```typescript
- * const http = new ServiceHttpClient("payments-api");
+ * // Preferred: use the factory method
+ * const http = host.httpClient("payments-api");
  * const balance = http.get("/v1/balance?account=123");
  * const result = http.post("/v1/transfer", { amount: 100 });
  * ```

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { PlexSpacesActor, WorkflowActor } from "./actor.js";
 export { decodeWitPayloadUtf8, encodeWitPayloadUtf8 } from "./wit-payload.js";
 export { actor, gen_server_actor, event_actor, fsm_actor, workflow_actor, handler, init_handler, run_handler, signal_handler, query_handler, getActorDefinition, } from "./decorators.js";
-export { Host, ProcessGroups, TupleSpace, host, pgFirst, pgFirstOrThrow, ServiceHttpClient } from "./host.js";
+export { Host, ProcessGroups, TupleSpace, host, pgFirst, pgFirstOrThrow, ServiceHttpClient, ActorRef, getActorRef } from "./host.js";
 export { ActorRouter } from "./router.js";
 export { defaultRetryConfig, withRetry, type RetryConfig, } from "./workflow.js";
 export { LeaderWorkerClient, listWorkerNodeIds, } from "./leader_worker.js";
 export { ActorID } from "./actor_id.js";
+export { WsThinClient, type ThinClientOptions, type ThinNodePingResult, } from "./ws_thin_client.js";
+export { AgentLoop, agentActor, defaultAgentConfig, type AgentConfig, type AgentStep, type AgentTrajectory, type AgentStepKind, } from "./agent.js";

package/dist/index.js

@@ -7,8 +7,10 @@
 export { PlexSpacesActor, WorkflowActor } from "./actor.js";
 export { decodeWitPayloadUtf8, encodeWitPayloadUtf8 } from "./wit-payload.js";
 export { actor, gen_server_actor, event_actor, fsm_actor, workflow_actor, handler, init_handler, run_handler, signal_handler, query_handler, getActorDefinition, } from "./decorators.js";
-export { Host, ProcessGroups, TupleSpace, host, pgFirst, pgFirstOrThrow, ServiceHttpClient } from "./host.js";
+export { Host, ProcessGroups, TupleSpace, host, pgFirst, pgFirstOrThrow, ServiceHttpClient, ActorRef, getActorRef } from "./host.js";
 export { ActorRouter } from "./router.js";
 export { defaultRetryConfig, withRetry, } from "./workflow.js";
 export { LeaderWorkerClient, listWorkerNodeIds, } from "./leader_worker.js";
 export { ActorID } from "./actor_id.js";
+export { WsThinClient, } from "./ws_thin_client.js";
+export { AgentLoop, agentActor, defaultAgentConfig, } from "./agent.js";

package/dist/wire/ws-frame-wire.d.ts

@@ -0,0 +1,75 @@
+type WireU8 = Uint8Array<ArrayBuffer>;
+/**
+ * Encode a tell (fire-and-forget) frame.
+ * actor_type carries the full canonical actor ID when it contains '@'.
+ */
+export declare function encodeWsFrameTell(requestId: string, actorId: string, msgType: string, payloadBytes: Uint8Array): WireU8;
+/**
+ * Encode an ask (request-reply) frame.
+ * timeout field 15 in AskReplyRequest is a google.protobuf.Duration: message{seconds=1, nanos=2}.
+ */
+export declare function encodeWsFrameAsk(requestId: string, actorId: string, msgType: string, payloadBytes: Uint8Array, timeoutMs: number): WireU8;
+/**
+ * Encode a node registration handshake frame (must be first frame after WS upgrade).
+ * resourceHints advertises browser capabilities as NodeResourceHints (field 11).
+ */
+export declare function encodeWsFrameNodeRegister(requestId: string, nodeId: string, nodeAddress: string, capabilities: Record<string, string>, resourceHints?: {
+    cpuPercent?: number;
+    memoryAvailableMb?: number;
+    availableCores?: number;
+}): WireU8;
+/**
+ * Encode a heartbeat frame to keep the WS session alive.
+ */
+export declare function encodeWsFrameHeartbeat(requestId: string, nodeId: string): WireU8;
+/**
+ * Encode a node ping frame (SWIM-compatible, carries resource hints in the response).
+ */
+export declare function encodeWsFrameNodePing(requestId: string, sourceNodeId: string, sequenceNumber: number): WireU8;
+export type WsFrameDecoded = {
+    type: 'node_register_ack';
+    requestId: string;
+    success: boolean;
+    assignedNodeId: string;
+    errorMessage: string;
+} | {
+    type: 'ask_response';
+    requestId: string;
+    success: boolean;
+    payloadJson: unknown;
+    errorMessage: string;
+} | {
+    type: 'tell_response';
+    requestId: string;
+    success: boolean;
+    errorMessage: string;
+} | {
+    type: 'heartbeat_ack';
+    requestId: string;
+} | {
+    type: 'node_ping_response';
+    requestId: string;
+    nodeId: string;
+    cpuPercent: number;
+    memoryAvailableMb: number;
+    availableCores: number;
+} | {
+    type: 'incoming_tell';
+    requestId: string;
+    actorId: string;
+    msgType: string;
+    payloadJson: unknown;
+} | {
+    type: 'error';
+    requestId: string;
+    code: number;
+    message: string;
+} | {
+    type: 'unknown';
+};
+/**
+ * Decode a binary WebSocket frame into a typed discriminated union.
+ * Unknown fields are skipped (forward-compatible).
+ */
+export declare function decodeWsFrame(bytes: Uint8Array): WsFrameDecoded;
+export {};