TypeScript SDK

Control worlds from code.

The SDK configures definitions, creates instances and runs experiments. Agents operate through the native interfaces issued by a world.

Client

import { Counterworld } from "@counterworld/sdk";

const counterworld = new Counterworld({
  apiKey: process.env.COUNTERWORLD_API_KEY,
  // baseUrl: "https://api.counterworld.dev",
});

Option	Type	Required	Description
apiKey	`string`	Yes	Server-side project API key.
baseUrl	`string`	No	Control API endpoint; defaults to Counterworld Cloud.
timeout	`number`	No	Request timeout in milliseconds.

Definitions

Definitions are reusable, versioned descriptions of systems, users, history and evaluators.

Method	Returns	Purpose
`definitions.create(input)`	`DefinitionDraft`	Create a draft from catalog or authored components.
`definitions.fromOpenAPI(input)`	`DefinitionDraft`	Infer a draft from one or more service specifications.
`definitions.get(id)`	`Definition`	Retrieve a definition and its published versions.
`draft.validate()`	`ValidationReport`	Check schemas, mutations, relations and evaluator references.
`draft.publish()`	`DefinitionVersion`	Freeze a validated version for reproducible worlds.

const draft = await counterworld.definitions.fromOpenAPI({
  name: "fulfillment-ops",
  specs: ["./orders.yaml", "./warehouse.yaml"],
});

const validation = await draft.validate();
if (!validation.valid) throw new Error(validation.summary);

const version = await draft.publish();

Worlds

A world is one isolated, populated and running instance of a published definition.

Method	Returns	Purpose
`worlds.create(input)`	`World`	Create an instance from a definition or inline definition input.
`worlds.get(id)`	`World`	Reconnect to an existing world.
`world.pause()`	`void`	Stop simulated time and actor execution.
`world.resume()`	`void`	Resume actor and scheduled-event execution.
`world.destroy()`	`void`	Delete the instance and revoke issued credentials.

const world = await counterworld.worlds.create({
  definition: version.id,
  seed: "fulfillment-regression-17",
  clock: { startAt: "2026-04-01T09:00:00Z" },
});

Agent interfaces

Issue scoped, revocable credentials for one production-shaped interface.

const access = await world.interfaces.connect("shopify-admin", {
  scopes: ["read_orders", "write_refunds"],
  expiresIn: "2h",
});

// Pass only these values to the tested agent.
console.log(access.baseUrl);
console.log(access.accessToken);

Method	Returns	Purpose
`interfaces.list()`	`Interface[]`	List APIs, SDK adapters and MCP surfaces available in the world.
`interfaces.connect(name, options)`	`InterfaceAccess`	Issue an endpoint and scoped credentials.
`interfaces.revoke(id)`	`void`	Revoke previously issued credentials.

Time, checkpoints and forks

await world.clock.advance({ days: 7, mode: "until-idle" });

const checkpoint = await world.checkpoints.create({
  name: "after-week-one",
});

const branch = await world.forks.create({
  from: checkpoint.id,
  name: "challenger-agent",
});

const diff = await world.inspect.diff({
  from: checkpoint.id,
  to: branch.id,
});

Method	Returns	Purpose
`clock.advance(input)`	`AdvanceResult`	Release scheduled events and actor decisions through a target time.
`checkpoints.create(input)`	`Checkpoint`	Capture complete state, clock, actors and pending events.
`checkpoints.restore(id)`	`World`	Restore the current world to an earlier checkpoint.
`forks.create(input)`	`World`	Create an independent world with the checkpoint’s exact lineage.
`inspect.diff(input)`	`StateDiff`	Compare entities, events, schedules, metrics and violations.

Simulation

await world.simulation.configure({
  population: {
    buyers: { discountSensitivity: 0.72, returnPropensity: 0.16 },
    storeAdmins: { approvalDelayHours: 6 },
    warehouseOperators: { shiftCoverage: 0.82 },
  },
});

await world.simulation.schedule({
  at: "2026-04-15T00:00:00Z",
  change: { seasonalDemand: 1.35 },
});

Method	Returns	Purpose
`simulation.configure(input)`	`SimulationConfig`	Update buyer, admin, employee or operator behavior and event policies.
`simulation.schedule(input)`	`ScheduledChange`	Apply a configuration change at simulated time.
`simulation.intervene(input)`	`Intervention`	Apply an explicit user, traffic or system change immediately.
`simulation.status()`	`SimulationStatus`	Inspect actor populations, event queue and current configuration.

Evaluation

const report = await world.evaluate({
  metrics: ["gross_margin", "repeat_purchase_rate"],
  invariants: ["no_negative_inventory"],
  compareTo: checkpoint.id,
});

console.log(report.passed);
console.log(report.metrics);
console.log(report.violations);

Method	Returns	Purpose
`world.evaluate(input)`	`EvaluationReport`	Run metrics, predicates, delayed checks and invariants.
`inspect.state(query)`	`StateResult`	Read privileged state outside the agent boundary.
`inspect.events(query)`	`EventPage`	Read agent, user and system events.
`report.export(format)`	`RunArtifact`	Export JSON, JSONL or OpenTelemetry-compatible run data.

Errors

import { CounterworldError } from "@counterworld/sdk";

try {
  await world.clock.advance({ days: 30 });
} catch (error) {
  if (error instanceof CounterworldError) {
    console.error(error.code);       // WORLD_PAUSED
    console.error(error.requestId);  // req_...
  }
}

SDK errors include a stable code, human-readable message, request identifier and retryability flag.