Skip to content

simulator: run container societies on local Kubernetes and GKE #936

Description

@chughtapan

Outcome

Target main and the original packages/simulator. Make container-society
execution part of the core simulator, not an example.

There is one Kubernetes execution path with two Effect Layers:

  • a repository-owned local Kubernetes cluster;
  • regional GKE Standard.

Both run the same code-first RunSpec through Run.execute. The selected
stack is Kubernetes, Kueue, Agent Sandbox, and Temporal. Docker may build images
or support the local cluster; it is not a second simulator backend.

Requirements boundary

The checked-in source-event conversations are the requirements boundary:

  • docs/decision-evidence/20260727-code-first-simulator-trajectory.md;
  • docs/decision-evidence/20260729-principal-runtime-gateway-trajectory.md;
  • docs/decision-evidence/20260729-effect-native-evaluation-results-trajectory.md;
  • docs/decision-evidence/20260801-main-kubernetes-society-execution-trajectory.md,
    which also retains the earlier Kubernetes/Kueue/Temporal/Agent Sandbox
    selections from the distributed-execution conversation.

Anything not discussed there is a non-goal. This issue is an implementation
plan, not normative authority; the main-track ADR owns the accepted contract.

Public shape

The public model is deliberately small:

export default RunSpec.define({
  id: "acme.echo/v1",
  events: [echoEvents],
  agents: {
    alice: openClawRuntime({ /* portable runtime configuration */ }),
    bob: scriptedRuntime({ /* portable runtime configuration */ }),
  },
  infrastructure: Kubernetes.local(),
  execute: ({ agents, events, network, ledger }) =>
    Effect.gen(function* () {
      // Instruct agents, observe the society, and determine completion.
    }),
});

Run.execute(spec) is the execution entry point. The infrastructure field
contains the selected local or GKE Effect Layer, while Kubernetes objects stay
out of the roster and customer Effect.

This reuses the existing EventCatalog, RunLedger, keyed StartedAgent gateway
types, network services, program Exit, infrastructure outcome, and
customer-owned completion policy. It does not create a new data model,
serialization framework, gateway union, or result system.

After the evaluations and local/GKE proofs migrate, remove the transitional
simulator.define(...).run(...) host path and standalone Docker example. Do
not keep a compatibility backend.

One experiment lifecycle

Each execution creates one society for one customer Effect and tears it down:

  1. Temporal starts one coarse workflow for the run.
  2. Kueue admits capacity for the complete roster.
  3. The controller creates one Agent Sandbox with one application container per
    roster entry.
  4. The controller waits for the exact full roster to be ready together.
  5. The in-cluster controller invokes the customer execute Effect once.
  6. The existing simulator outcome and ledger retain experiment and
    infrastructure evidence.
  7. Temporal drives cleanup of run-owned Kubernetes resources.

A pre-gate backing-Pod restart simply delays readiness and exposes no public
generation model. An unrecoverable or never-ready agent fails acquisition.
After dispatch, runtime termination remains typed ledger evidence and customer
Effect policy decides what to do. Controller or infrastructure loss fails the run and
starts cleanup. The controller does not replay customer code, and the simulator
makes no exactly-once claim for external side effects.

Kueue owns capacity, not readiness. Kubernetes and Agent Sandbox own placement
and container lifecycle, not customer policy. Temporal owns coarse
orchestration and cleanup, not agent logic or simulator evidence.

One roster entry is one agent in one Sandbox application container. Real and
code/scripted agents can share a society, but every social action uses the
production MoltZap router. Principal instructions use each runtime's native
gateway.

A stable controller loads the experiment module late. The stock digest-pinned
OpenClaw image is the compatibility path; an image with MoltZap preinstalled is
only an optimization. Exact bundle transport and caching are private profile
details.

Profiles

The local profile installs the components needed for development and CI,
including a development Temporal deployment.

The GKE reference is regional GKE Standard with Agent Sandbox. Terraform and
Helm own reproducible cluster and add-on setup. Production Temporal hosting and
high availability remain unselected; GKE qualification may use a test
deployment or configured endpoint.

The Effect Layer boundary leaves room for a future scheduler without adding a
new provider framework now. Nomad, Slurm, and managed batch are not implemented.

Implementation slices

  • 0 — Admit the small main decision. Reconcile the source trajectory,
    ADR, package law, prior-decision lineage, and affected docs. Freeze the exact
    candidate, pass a fresh blind teammate review, and obtain maintainer
    acceptance before production code.
  • 1 — Core contract and fake. Add RunSpec and Run.execute as a
    small facade over the existing simulator concepts. Add the narrow private
    platform seam and fake tests for full-roster gating, one invocation,
    post-dispatch termination policy, outcomes, and cleanup.
  • 2 — Local Kubernetes vertical slice. Bring up local Kubernetes with
    Kueue, Agent Sandbox, and Temporal. Run a two-agent stock-OpenClaw/core-router
    smoke through packages/simulator, retain ledger evidence, and verify zero
    run-owned residue.
  • 3 — Four agents and evaluations. Prove the same path with four agents.
    Move all 32 OpenClaw/NanoClaw evaluation cells to Run.execute and record
    their real outcomes, including honest operational or behavioral failures.
    Remove the host executor and standalone example after the replacement proof.
  • 4 — GKE qualification. Provision regional GKE Standard with
    Terraform/Helm, run the same small smoke and at least one OpenClaw evaluation
    through the unchanged authoring contract, retain evidence, and clean up.

Acceptance criteria

  • packages/simulator owns the only real society-execution path.
  • The same agents, events, and execute program run through local
    Kubernetes or GKE by changing only RunSpec.infrastructure.
  • One Kueue cohort is admitted before one Sandbox/application container per
    roster entry is created.
  • The customer Effect cannot start before the exact full roster is ready.
  • The controller invokes it once and never replays it; no exactly-once
    external-side-effect claim is made.
  • Principal control uses native gateways and all agent social traffic uses
    the production router.
  • Existing typed ledger/outcome and evaluation grading/report contracts
    remain readable and current.
  • Local two-agent, local four-agent, all 32 evaluation cells, and GKE smoke
    evidence use Run.execute and leave zero run-owned residue.
  • No production code lands under v2/* and no new package is introduced.

Explicit non-goals

  • generation identifiers or streams, customer-visible restart/recovery APIs,
    or post-dispatch replacement, rebinding, rejoin, persistent-state recovery,
    and recovery of in-flight work;
  • customer Effect replay, exactly-once external effects, or distributed
    side-effect transactions;
  • start-or-attach identity, artifact authorities, global execution-id
    namespaces, synthetic UUIDs, or normative resource-name hashing;
  • a new immutable-data/JCS grammar or universal input/result/failure schema;
  • arbitrary Pod templates or public Kubernetes/Kueue/Sandbox/Temporal APIs;
  • per-agent Temporal workflows, warm societies, multi-run fairness,
    preemption, autoscaling, router HA, or production Temporal HA;
  • scale qualification above four agents in this issue;
  • a Nomad, Slurm, managed-batch, or Autopilot backend;
  • a general multi-tenant Secret, NetworkPolicy, or security platform; and
  • any implementation or contract change under v2/*.

Existing work to reuse

Reuse the current simulator kernel, EventCatalog, RunLedger, scoped cleanup,
runtime-native gateways, router, OpenClaw adapter, and evaluation report
pipeline. The Docker society example remains temporary compatibility evidence
until the core Kubernetes path replaces it.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions