Skip to main content

Tooling Contracts

X4 tooling follows a set of contracts so humans, agents, and automation can share one workflow.

CLI Contract​

The CLI is authoritative for:

  • workspace creation;
  • branch naming;
  • registry lookup;
  • sandbox startup;
  • preview URL publication;
  • remote execution;
  • control-plane submissions;
  • PR comments and check runs;
  • cleanup.

Cloud Runtime Contract​

X4-owned workers, devboxes, and sandboxes are the default cloud runtime. Cursor Cloud Agents are deferred as an optional future runner, not the primary execution layer. X4 must keep ownership of environment contracts, secret projection, service access policy, validation evidence, and merge readiness.

See Cloud Agent Strategy for the decision.

Codex Harness Contract​

Codex sessions should be short and scoped:

  • planning sessions inspect repos and return structured plans;
  • implementation sessions edit only allowed paths;
  • triage sessions are read-only;
  • repair sessions make focused fixes from deterministic test evidence.

Evidence Contract​

Evidence should be generated from actual command output or recorded state:

  • deterministic command results;
  • remote job manifests;
  • logs and artifacts;
  • private preview URLs;
  • check-run payloads;
  • PR/issue comments.

Safety Contract​

Tooling must not:

  • print secret values;
  • post local-only preview URLs;
  • delete dirty worktrees without explicit cleanup intent;
  • bypass repo policy scope;
  • widen automation after a human-review condition.