TypeScript SDK

npm install @rkat/mobkit-sdk

import { MobKit, memory } from "@rkat/mobkit-sdk";

const rt = await MobKit.builder()
  .mob("config/mob.toml")
  .memory(memory.localJson())
  .persistentState(".mobkit/state")
  .consoleConfig("config/console.toml")
  .gateway("/path/to/rpc_gateway")
  .build();

const handle = rt.mobHandle();
const status = await handle.status();
console.log("Running:", status.running);

const results = await handle.memoryQuery({
  entity: "identity:ops",
  topic: "deployment",
  store: "knowledge_graph",
});

import { DetachedJobExecution, DetachedJobResult, MobKit } from "@rkat/mobkit-sdk";

const runtime = await MobKit.builder()
  .persistentState("state/mobkit")
  .jobCredentials(resolveProfileCredentials)
  .sessionService({
    async buildAgent(draft) {
      draft.registerTool(
        "security_scan",
        async () => ({ error: "detached owner required" }),
        {
          description: "Run a durable security scan",
          execution: new DetachedJobExecution({
            runner: "homecore.security_scan",
            version: "v1",
            restartClass: "checkpoint_resumable",
            idempotencyScope: "interaction_and_arguments",
            submissionTimeoutMs: 30_000,
            credentialScopes: ["unifi.read"],
            handler: async (ctx) => {
              await ctx.progress(1, "scan started");
              const resultRef = await performScan(ctx.arguments, ctx.credentials);
              return new DetachedJobResult(resultRef);
            },
          }),
        },
      );
    },
  })
  .gateway("/path/to/rpc_gateway")
  .build();

const job = await runtime.jobs.get(jobId);
await runtime.jobs.cancel(jobId);

export interface EventEnvelope {
  readonly eventId: string;
  readonly source: string;
  readonly timestampMs: number;
  readonly event: unknown;
}

export interface UnifiedAgentEvent {
  readonly kind: "agent";
  readonly agentId: string;
  readonly eventType: string;
  readonly payload?: Record<string, unknown> | null;
}

export interface UnifiedModuleEvent {
  readonly kind: "module";
  readonly module: string;
  readonly eventType: string;
  readonly payload: Record<string, unknown>;
}

export type UnifiedEvent = UnifiedAgentEvent | UnifiedModuleEvent;

export interface RosterContext {
  /**
   * The booted mob's compiled definition as JSON (`id`, `profiles`, ...).
   * Always present behind the bundled `rpc_gateway`; `null` only for in-process
   * Rust embedders and test harnesses that resolve a roster without one.
   */
  readonly mobDefinition: Record<string, unknown> | null;
  /**
   * Identities the identity runtime has registered at the time of the call.
   * Empty on the bootstrap resolves, populated on later re-derivations such as
   * `mobkit/topology/query` or an edge reconcile.
   */
  readonly previousIdentities: readonly string[];
}

// ESM
import { MobKit } from "@rkat/mobkit-sdk";

// CommonJS
const { MobKit } = require("@rkat/mobkit-sdk");

import { isRpcError, isMobEventsStaleError } from "@rkat/mobkit-sdk";

try {
  await handle.queryMobEvents({ afterSeq: cursor });
} catch (err) {
  if (isMobEventsStaleError(err)) {
    // err.afterCursor, err.latestCursor available
  } else if (isRpcError(err)) {
    console.error(`RPC ${err.method} failed: ${err.code}`);
  } else {
    throw err;
  }
}

import { isMobEventsStaleError } from "@rkat/mobkit-sdk";

const events = await handle.queryMobEvents({
  eventTypes: ["flow_started", "flow_completed"],
  mobId: "home",
});
for (const e of events) {
  console.log(e.cursor, e.kind, e.runId, e.data);
}

// MobStructuralEvent.cursor is the meerkat ledger cursor — durable
// across mobkit restarts on persistent_state builds. Resume by
// passing the highest-seen cursor as afterSeq.
try {
  const more = await handle.queryMobEvents({ afterSeq: lastCursor });
} catch (err) {
  if (isMobEventsStaleError(err)) {
    // Rewind to err.latestCursor and reconnect.
  }
}

// Flow runs with the full ledger projection
const runs = await handle.listRuns(); // or handle.listRuns("flow-id")
for (const run of runs) {
  console.log(run.runId, run.status, run.stepLedger.length);
}

// Create a draft from the blank template, validate, export
const draft = await handle.mobpackCreate({ template: "blank", name: "support-bot" });
const document = draft.row.document;

const validation = await handle.mobpackValidate(document);
console.log(validation.ok, validation.displayRows.length);

const pack = await handle.mobpackExport(document);
const archive = Buffer.from(pack.contentBase64, "base64"); // pack.filename, pack.mediaType

import { MobKit, eventLog, runtimeStore } from "@rkat/mobkit-sdk";

const runtime = await MobKit.builder()
  .mob("config/mob.toml")
  .persistentState("state/mobkit")
  // Declare an in-memory runtime store (sessions do not survive restart).
  .runtimeStore(runtimeStore.memory())
  // Declare a bounded queryable in-process event log — or eventLog.nullStore().
  .eventLog(eventLog.memory({ batchSize: 64 }))
  .build();

import { createJsonRpcHttpTransport } from "@rkat/mobkit-sdk";

const transport = createJsonRpcHttpTransport(endpoint, {
  timeoutMs: 5_000,
});