@rkat/mobkit-sdk 0.4.9

package/dist/agent-builder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SessionAgentBuilder protocol and CallbackDispatcher.
+ *
+ * The builder protocol uses imperative mutation: buildAgent receives a
+ * mutable SessionBuildOptions and modifies it in place.
+ */
+import { SessionBuildOptions } from "./models.js";
+import { type ErrorEvent } from "./types.js";
+/**
+ * Protocol for building agents during session creation.
+ *
+ * @example
+ * ```ts
+ * const builder: SessionAgentBuilder = {
+ *   async buildAgent(opts) {
+ *     opts.profileName = "assistant";
+ *     opts.registerTool("search", searchHandler);
+ *   },
+ * };
+ * ```
+ */
+export interface SessionAgentBuilder {
+    buildAgent(options: SessionBuildOptions): Promise<void>;
+}
+export type ErrorCallback = (event: ErrorEvent) => void | Promise<void>;
+/**
+ * Routes incoming JSON-RPC callbacks from the Rust runtime to the
+ * registered SessionAgentBuilder and tool handlers.
+ *
+ * Tool handlers are scoped by a build-level scope_id to prevent
+ * cross-session handler bleed in concurrent sessions.
+ */
+export declare class CallbackDispatcher {
+    private _builder;
+    private _errorCallback;
+    private readonly _toolHandlers;
+    private readonly _scopeTools;
+    registerBuilder(builder: SessionAgentBuilder): void;
+    registerErrorCallback(callback: ErrorCallback): void;
+    /** Remove all tool handlers for a scope. Call when a session ends. */
+    releaseScope(scopeId: string): void;
+    handleCallback(method: string, params: Record<string, unknown>): Promise<unknown>;
+}
+//# sourceMappingURL=agent-builder.d.ts.map

package/dist/agent-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-builder.d.ts","sourceRoot":"","sources":["../src/agent-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAoB,MAAM,aAAa,CAAC;AACpE,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAI9D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAID,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAIxE;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAE3D,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAInD,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAIpD,sEAAsE;IACtE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAU7B,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC;CAwFpB"}

package/dist/agent-builder.js

@@ -0,0 +1,111 @@
+/**
+ * SessionAgentBuilder protocol and CallbackDispatcher.
+ *
+ * The builder protocol uses imperative mutation: buildAgent receives a
+ * mutable SessionBuildOptions and modifies it in place.
+ */
+import { SessionBuildOptions } from "./models.js";
+import { parseErrorEvent } from "./types.js";
+// -- CallbackDispatcher ---------------------------------------------------
+/**
+ * Routes incoming JSON-RPC callbacks from the Rust runtime to the
+ * registered SessionAgentBuilder and tool handlers.
+ *
+ * Tool handlers are scoped by a build-level scope_id to prevent
+ * cross-session handler bleed in concurrent sessions.
+ */
+export class CallbackDispatcher {
+    _builder = null;
+    _errorCallback = null;
+    _toolHandlers = new Map();
+    _scopeTools = new Map();
+    registerBuilder(builder) {
+        this._builder = builder;
+    }
+    registerErrorCallback(callback) {
+        this._errorCallback = callback;
+    }
+    /** Remove all tool handlers for a scope. Call when a session ends. */
+    releaseScope(scopeId) {
+        const tools = this._scopeTools.get(scopeId);
+        if (tools) {
+            for (const toolName of tools) {
+                this._toolHandlers.delete(`${scopeId}:${toolName}`);
+            }
+            this._scopeTools.delete(scopeId);
+        }
+    }
+    async handleCallback(method, params) {
+        if (method === "mobkit/on_error") {
+            if (this._errorCallback !== null) {
+                const event = parseErrorEvent(params);
+                try {
+                    await this._errorCallback(event);
+                }
+                catch {
+                    // Fire-and-forget — swallow error callback failures
+                }
+            }
+            return null;
+        }
+        if (method === "callback/build_agent") {
+            if (this._builder === null) {
+                throw new Error("no SessionAgentBuilder registered");
+            }
+            const rawOptions = {
+                ...(typeof params.options === "object" && params.options !== null
+                    ? params.options
+                    : {}),
+            };
+            const scopeId = String(rawOptions.scope_id ?? "");
+            if (!scopeId) {
+                throw new Error("callback/build_agent requires scope_id in options");
+            }
+            delete rawOptions.scope_id;
+            const opts = new SessionBuildOptions();
+            if (rawOptions.app_context !== undefined) {
+                opts.appContext = rawOptions.app_context;
+            }
+            if (Array.isArray(rawOptions.additional_instructions)) {
+                opts.additionalInstructions = rawOptions.additional_instructions.filter((v) => typeof v === "string");
+            }
+            if (typeof rawOptions.session_id === "string") {
+                opts.sessionId = rawOptions.session_id;
+            }
+            if (typeof rawOptions.labels === "object" &&
+                rawOptions.labels !== null) {
+                opts.labels = rawOptions.labels;
+            }
+            if (typeof rawOptions.profile_name === "string") {
+                opts.profileName = rawOptions.profile_name;
+            }
+            await this._builder.buildAgent(opts);
+            // Capture tool handlers scoped to this build
+            const toolNames = [];
+            for (const [name, handler] of opts.toolHandlers) {
+                this._toolHandlers.set(`${scopeId}:${name}`, handler);
+                toolNames.push(name);
+            }
+            this._scopeTools.set(scopeId, toolNames);
+            return opts.toDict();
+        }
+        if (method === "callback/call_tool") {
+            const scopeId = String(params.scope_id ?? "");
+            if (!scopeId) {
+                throw new Error("callback/call_tool requires scope_id");
+            }
+            const toolName = String(params.tool ?? "");
+            const args = (typeof params.arguments === "object" && params.arguments !== null
+                ? params.arguments
+                : {});
+            const handler = this._toolHandlers.get(`${scopeId}:${toolName}`);
+            if (!handler) {
+                throw new Error(`no handler registered for tool: ${toolName} (scope: ${scopeId})`);
+            }
+            const result = await handler(args);
+            return { content: result };
+        }
+        throw new Error(`unknown callback method: ${method}`);
+    }
+}
+//# sourceMappingURL=agent-builder.js.map

package/dist/agent-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-builder.js","sourceRoot":"","sources":["../src/agent-builder.ts"],"names":[],"mappings":"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"}

package/dist/builder.d.ts

@@ -0,0 +1,74 @@
+/**
+ * MobKit builder chain — chainable configuration for the runtime.
+ *
+ * @example
+ * ```ts
+ * import { MobKit } from "@rkat/mobkit-sdk";
+ *
+ * const rt = await MobKit.builder()
+ *   .mob("config/mob.toml")
+ *   .sessionService(builder, store)
+ *   .discovery(discoverFn)
+ *   .build();
+ *
+ * const handle = rt.mobHandle();
+ * const status = await handle.status();
+ * ```
+ */
+import type { SessionAgentBuilder, ErrorCallback } from "./agent-builder.js";
+import type { MobKitRuntime } from "./runtime.js";
+export interface MobKitBuilderConfig {
+    mobConfigPath: string | null;
+    sessionBuilder: SessionAgentBuilder | null;
+    sessionStore: unknown;
+    discoveryCallback: unknown;
+    preSpawnCallback: unknown;
+    errorCallback: ErrorCallback | null;
+    eventLog: Record<string, unknown> | null;
+    gatingConfigPath: string | null;
+    routingConfigPath: string | null;
+    schedulingFiles: string[];
+    memoryConfig: unknown;
+    authConfig: unknown;
+    gatewayBin: string | null;
+    modules: unknown[];
+}
+/**
+ * Chainable builder for MobKit runtime configuration.
+ *
+ * @example
+ * ```ts
+ * const rt = await MobKit.builder()
+ *   .mob("config/mob.toml")
+ *   .gateway("./target/release/phase0b_rpc_gateway")
+ *   .build();
+ * ```
+ */
+export declare class MobKitBuilder {
+    /** @internal */
+    readonly _config: MobKitBuilderConfig;
+    mob(configPath: string): this;
+    sessionService(builder: SessionAgentBuilder, store?: unknown): this;
+    discovery(callback: unknown): this;
+    preSpawn(callback: unknown): this;
+    eventLog(options: {
+        storage: unknown;
+        [key: string]: unknown;
+    }): this;
+    onError(callback: ErrorCallback): this;
+    gating(configPath: string): this;
+    routing(configPath: string): this;
+    scheduling(...scheduleFiles: string[]): this;
+    memory(config?: unknown, options?: {
+        stores?: string[];
+    }): this;
+    auth(config: unknown): this;
+    gateway(binPath: string): this;
+    modules(moduleSpecs: unknown[]): this;
+    build(): Promise<MobKitRuntime>;
+    private _applyConventionDefaults;
+}
+export declare class MobKit {
+    static builder(): MobKitBuilder;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAIlD,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC3C,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,OAAO,EAAE,CAAC;CACpB;AAuBD;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;IACxB,gBAAgB;IAChB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAmB;IAExD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAK7B,cAAc,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAMnE,SAAS,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAKlC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAKjC,QAAQ,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI;IAKpE,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAKtC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKhC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKjC,UAAU,CAAC,GAAG,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI;IAK5C,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI;IAM/D,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAK3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK9B,OAAO,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,IAAI;IAK/B,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;IAOrC,OAAO,CAAC,wBAAwB;CA0BjC;AAID,qBAAa,MAAM;IACjB,MAAM,CAAC,OAAO,IAAI,aAAa;CAGhC"}

package/dist/builder.js

@@ -0,0 +1,145 @@
+/**
+ * MobKit builder chain — chainable configuration for the runtime.
+ *
+ * @example
+ * ```ts
+ * import { MobKit } from "@rkat/mobkit-sdk";
+ *
+ * const rt = await MobKit.builder()
+ *   .mob("config/mob.toml")
+ *   .sessionService(builder, store)
+ *   .discovery(discoverFn)
+ *   .build();
+ *
+ * const handle = rt.mobHandle();
+ * const status = await handle.status();
+ * ```
+ */
+import { existsSync } from "node:fs";
+function defaultConfig() {
+    return {
+        mobConfigPath: null,
+        sessionBuilder: null,
+        sessionStore: null,
+        discoveryCallback: null,
+        preSpawnCallback: null,
+        errorCallback: null,
+        eventLog: null,
+        gatingConfigPath: null,
+        routingConfigPath: null,
+        schedulingFiles: [],
+        memoryConfig: null,
+        authConfig: null,
+        gatewayBin: null,
+        modules: [],
+    };
+}
+// -- MobKitBuilder --------------------------------------------------------
+/**
+ * Chainable builder for MobKit runtime configuration.
+ *
+ * @example
+ * ```ts
+ * const rt = await MobKit.builder()
+ *   .mob("config/mob.toml")
+ *   .gateway("./target/release/phase0b_rpc_gateway")
+ *   .build();
+ * ```
+ */
+export class MobKitBuilder {
+    /** @internal */
+    _config = defaultConfig();
+    mob(configPath) {
+        this._config.mobConfigPath = configPath;
+        return this;
+    }
+    sessionService(builder, store) {
+        this._config.sessionBuilder = builder;
+        this._config.sessionStore = store ?? null;
+        return this;
+    }
+    discovery(callback) {
+        this._config.discoveryCallback = callback;
+        return this;
+    }
+    preSpawn(callback) {
+        this._config.preSpawnCallback = callback;
+        return this;
+    }
+    eventLog(options) {
+        this._config.eventLog = { ...options };
+        return this;
+    }
+    onError(callback) {
+        this._config.errorCallback = callback;
+        return this;
+    }
+    gating(configPath) {
+        this._config.gatingConfigPath = configPath;
+        return this;
+    }
+    routing(configPath) {
+        this._config.routingConfigPath = configPath;
+        return this;
+    }
+    scheduling(...scheduleFiles) {
+        this._config.schedulingFiles = scheduleFiles;
+        return this;
+    }
+    memory(config, options) {
+        this._config.memoryConfig =
+            config ?? { stores: options?.stores ?? [] };
+        return this;
+    }
+    auth(config) {
+        this._config.authConfig = config;
+        return this;
+    }
+    gateway(binPath) {
+        this._config.gatewayBin = binPath;
+        return this;
+    }
+    modules(moduleSpecs) {
+        this._config.modules = moduleSpecs;
+        return this;
+    }
+    async build() {
+        this._applyConventionDefaults();
+        // Dynamic import to break circular dep (runtime imports from builder config type)
+        const { MobKitRuntime } = await import("./runtime.js");
+        return MobKitRuntime._create(this._config);
+    }
+    _applyConventionDefaults() {
+        if (this._config.gatingConfigPath === null) {
+            const candidate = "config/gating.toml";
+            if (existsSync(candidate)) {
+                this._config.gatingConfigPath = candidate;
+            }
+        }
+        if (this._config.routingConfigPath === null) {
+            const candidate = "deployment/routing.toml";
+            if (existsSync(candidate)) {
+                this._config.routingConfigPath = candidate;
+            }
+        }
+        if (this._config.schedulingFiles.length === 0) {
+            const files = [];
+            const defaultFile = "config/defaults/schedules.toml";
+            if (existsSync(defaultFile))
+                files.push(defaultFile);
+            const overrideFile = "deployment/schedules.toml";
+            if (existsSync(overrideFile))
+                files.push(overrideFile);
+            if (files.length > 0) {
+                this._config.schedulingFiles = files;
+            }
+        }
+    }
+}
+// -- MobKit static factory ------------------------------------------------
+export class MobKit {
+    static builder() {
+        return new MobKitBuilder();
+    }
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/cjs/agent-builder.cjs

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * SessionAgentBuilder protocol and CallbackDispatcher.
+ *
+ * The builder protocol uses imperative mutation: buildAgent receives a
+ * mutable SessionBuildOptions and modifies it in place.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallbackDispatcher = void 0;
+const models_js_1 = require("./models.cjs");
+const types_js_1 = require("./types.cjs");
+// -- CallbackDispatcher ---------------------------------------------------
+/**
+ * Routes incoming JSON-RPC callbacks from the Rust runtime to the
+ * registered SessionAgentBuilder and tool handlers.
+ *
+ * Tool handlers are scoped by a build-level scope_id to prevent
+ * cross-session handler bleed in concurrent sessions.
+ */
+class CallbackDispatcher {
+    _builder = null;
+    _errorCallback = null;
+    _toolHandlers = new Map();
+    _scopeTools = new Map();
+    registerBuilder(builder) {
+        this._builder = builder;
+    }
+    registerErrorCallback(callback) {
+        this._errorCallback = callback;
+    }
+    /** Remove all tool handlers for a scope. Call when a session ends. */
+    releaseScope(scopeId) {
+        const tools = this._scopeTools.get(scopeId);
+        if (tools) {
+            for (const toolName of tools) {
+                this._toolHandlers.delete(`${scopeId}:${toolName}`);
+            }
+            this._scopeTools.delete(scopeId);
+        }
+    }
+    async handleCallback(method, params) {
+        if (method === "mobkit/on_error") {
+            if (this._errorCallback !== null) {
+                const event = (0, types_js_1.parseErrorEvent)(params);
+                try {
+                    await this._errorCallback(event);
+                }
+                catch {
+                    // Fire-and-forget — swallow error callback failures
+                }
+            }
+            return null;
+        }
+        if (method === "callback/build_agent") {
+            if (this._builder === null) {
+                throw new Error("no SessionAgentBuilder registered");
+            }
+            const rawOptions = {
+                ...(typeof params.options === "object" && params.options !== null
+                    ? params.options
+                    : {}),
+            };
+            const scopeId = String(rawOptions.scope_id ?? "");
+            if (!scopeId) {
+                throw new Error("callback/build_agent requires scope_id in options");
+            }
+            delete rawOptions.scope_id;
+            const opts = new models_js_1.SessionBuildOptions();
+            if (rawOptions.app_context !== undefined) {
+                opts.appContext = rawOptions.app_context;
+            }
+            if (Array.isArray(rawOptions.additional_instructions)) {
+                opts.additionalInstructions = rawOptions.additional_instructions.filter((v) => typeof v === "string");
+            }
+            if (typeof rawOptions.session_id === "string") {
+                opts.sessionId = rawOptions.session_id;
+            }
+            if (typeof rawOptions.labels === "object" &&
+                rawOptions.labels !== null) {
+                opts.labels = rawOptions.labels;
+            }
+            if (typeof rawOptions.profile_name === "string") {
+                opts.profileName = rawOptions.profile_name;
+            }
+            await this._builder.buildAgent(opts);
+            // Capture tool handlers scoped to this build
+            const toolNames = [];
+            for (const [name, handler] of opts.toolHandlers) {
+                this._toolHandlers.set(`${scopeId}:${name}`, handler);
+                toolNames.push(name);
+            }
+            this._scopeTools.set(scopeId, toolNames);
+            return opts.toDict();
+        }
+        if (method === "callback/call_tool") {
+            const scopeId = String(params.scope_id ?? "");
+            if (!scopeId) {
+                throw new Error("callback/call_tool requires scope_id");
+            }
+            const toolName = String(params.tool ?? "");
+            const args = (typeof params.arguments === "object" && params.arguments !== null
+                ? params.arguments
+                : {});
+            const handler = this._toolHandlers.get(`${scopeId}:${toolName}`);
+            if (!handler) {
+                throw new Error(`no handler registered for tool: ${toolName} (scope: ${scopeId})`);
+            }
+            const result = await handler(args);
+            return { content: result };
+        }
+        throw new Error(`unknown callback method: ${method}`);
+    }
+}
+exports.CallbackDispatcher = CallbackDispatcher;