[scosman]

Summary

Adds a tutorial for building a stateful tool-use environment with Seahaven, a framework whose seahaven serve hosts an OpenEnv environment. Each "world" is a working copy of a tool or API, backed by SQLite. Designed for long-horizon open-goal agents, in realistic tool environments.

The tutorial builds a small CRM world with one table and three tools, freezes a fixture, serves it, and drives an episode with OpenEnv's own GenericEnvClient (reset with a fixture and seed, ListToolsAction, CallToolAction). It then grades the episode from the row-level change log that state() returns.

• docs/source/tutorials/seahaven-environment.md: the new page.
• docs/source/_toctree.yml: adds it under Learn → Basics.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run /pre-submit-pr (or bash .claude/hooks/lint.sh and tests) and addressed all issues

Note on invariant 3 (rewards inside the environment): a Seahaven environment returns reward=None and leaves grading to the caller. The tutorial says this plainly, links to Reward Design, and notes that the harness rollout helpers require an environment-produced reward.

RFC Status

• Not required (bug fix, docs, minor refactoring)

Test Plan

• Every code block in the page was extracted and run end to end, unchanged, against Seahaven 0.5.0 and 0.6.0, with the client on openenv 0.8.0 from PyPI, on 0.5.0, and on this repo's main. The printed output and the change log shown in the page match the run.
• python scripts/sync_env_docs.py --check passes and _toctree.yml parses.

Claude Code Review

N/A, docs

---

Note

Low Risk
Documentation-only changes with no runtime or API modifications.

Overview
Adds a Learn → Basics doc that walks through building a stateful tool-use environment with Seahaven: scaffold a CRM world, define SQLite schema and @world.tool handlers, freeze a fixture, run seahaven serve, drive an episode with GenericEnvClient (reset, ListToolsAction, CallToolAction), and grade from the row change log returned by state().

The page also calls out how this pattern differs from typical OpenEnv environments—rewards stay None on the server and grading lives in the driver—and notes that CollectRunner / build_harness_rollout_func expect environment-produced rewards. docs/source/_toctree.yml links the page as "Tool-Use Environments (Seahaven)".

^{Reviewed by Cursor Bugbot for commit 724e466. Bugbot is set up for automated code reviews on this repo. Configure here.}

[burtenshaw]

ALIGNMENT FLAG: rewards are computed outside the environment. The tutorial explicitly grades state() in caller code and says observations always have reward=None. This conflicts with the rewards-in-environment invariant (and leaves the documented path incompatible with CollectRunner). Please have @Darktex review whether to permit this documented exception or require a server-side reward adapter before presenting it under Basics. The disclosure is useful, but does not itself settle the architecture decision.

[scosman]

@Darktex thoughts on @burtenshaw's comment?

For this class of environment, rewards outside the environment is an intentional design decision. It's a large stateful environment modelling a real company/API (e.g. the Stripe API). Unlike chess or Atari, there's no inherent reward signal in the env. An agent could be given any task, and needs to be rewarded against that task.

Examples on a Stripe environment:

• Agent 1: create 4 new coupons and a new pricing plan. Reward checks coupon and plan state.
• Agent 2: refund customer 1234 for their last payment. Reward checks that payment's status.
• etc.

So the reward belongs with the task set (the harness), not the environment. The environment's job is to expose state that graders can check against (in the tutorial, a row-level change log from state()).