TypeScript SDK

npm install @rkat/meta-sdk

import { Meta, memory } from "@rkat/meta-sdk";

const rt = await Meta.builder()
  .mob("config/mob.toml")
  .memory(memory.localJson())
  .persistentState(".meta/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 { Meta } from "@rkat/meta-sdk";

const rt = await Meta.builder()
  .mob("config/mob.toml")
  .forkInstructionPolicy("reactivate_inherited")
  .build();

const rt = await Meta.builder()
  .mob("config/mob.toml")
  .roster(roster)
  .memberRestore("on_demand_verified")
  .build();

import { deliveryScopeToDict, parseDeliveryScope, StaleScopeError } from "@rkat/meta-sdk";

const status = await runtime.status("domain:calendar");
if (!status.deliveryScope) throw new Error(status.deliveryScopeUnavailable?.reason);
const saved = deliveryScopeToDict(status.deliveryScope); // persist byte-exact

try {
  const { receipt } = await runtime.dispatch(
    "domain:calendar",
    { content: "occurrence 42", origin: "system", idempotencyKey: "occ-42", correlationId },
    { expectedScope: parseDeliveryScope(saved) },
  );
  receipt.stage; // "ingress_accepted": not a durable-input claim
} catch (error) {
  if (error instanceof StaleScopeError) error.mismatch; // nothing was submitted
}

const recovery = await runtime.recoverDelivery("domain:calendar", parseDeliveryScope(saved), {
  idempotencyKey: "occ-42",
  correlationId,
});
// recovery.state: "absent" is a point-in-time miss, never permission to retry

import { DetachedJobExecution, DetachedJobResult, Meta } from "@rkat/meta-sdk";

const runtime = await Meta.builder()
  .persistentState("state/meta")
  .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: "example.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;
  /**
   * Call-site-dependent prior-identity context, not an authoritative membership
   * snapshot on every callback. Topology queries and edge reconciliation supply
   * currently registered identities. Bootstrap, full roster refresh/reconcile,
   * and reset-time spec adoption currently pass an empty list; an empty list
   * does not imply that no identities are registered.
   */
  readonly previousIdentities: readonly string[];
}

import {
  SourceStaleRevisionError,
  SourceVersionConflictError,
  supportsAnnouncementSources,
} from "@rkat/meta-sdk";

const handle = runtime.mobHandle();
if (!supportsAnnouncementSources(await handle.capabilities())) {
  throw new Error("this gateway does not serve announcement sources");
}
const { source } = await handle.announcementSourceGet("mail");
if (source === null) throw new Error("declare the source first");
const { items, nextCursor } = await readProvider(source.cursor.token); // your adapter
try {
  await handle.announcementSourceAdvance(
    `${runId}:v${source.cursor.version}`,
    "mail",
    source.revision,
    source.cursor.version,
    principal,
    nextCursor,
    { items, observed: { kind: "delta" } },
  );
} catch (err) {
  if (!(err instanceof SourceStaleRevisionError || err instanceof SourceVersionConflictError)) {
    throw err;
  }
  // another step or a configuration change moved the source: read it again
}

const page = await handle.announcementEscalationsList({ after: lastCursor });
for (const event of page.events ?? []) {
  record(event.escalationId, event.event, event.cause); // your own
}
lastCursor = page.next;

const template = await handle.announcementRoleTemplatePut(
  "op-reviewers",
  "reviewers",
  { mob_id: "mob-a", role: "reviewer" },
  ["ops.alert"],
);
const change = await handle.announcementSubscriptionPause("op-pause", "reviewers", template.revision);
// change.subscription is null; change.template and change.children carry the template

// ESM
import { Meta } from "@rkat/meta-sdk";

// CommonJS
const { Meta } = require("@rkat/meta-sdk");

import { isRpcError, isMobEventsStaleError } from "@rkat/meta-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/meta-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 meta 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 { Meta, eventLog, runtimeStore } from "@rkat/meta-sdk";

const runtime = await Meta.builder()
  .mob("config/mob.toml")
  .persistentState("state/meta")
  // 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 }))
  .gateway("/path/to/rpc_gateway")
  .build();

import { CompositionProvenanceError } from "@rkat/meta-sdk";

try {
  const runtime = await builder.build();
} catch (err) {
  if (err instanceof CompositionProvenanceError && err.kind === "divergent") {
    console.error("mob.toml differs from the stored definition in", err.fields);
  }
  throw err;
}

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

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