Repository navigation
Add advance_clock to move an instance's clock forward - #49
Merged
Merged
Conversation
A harness can now move virtual time forward deterministically, to reach
a retry window or a due date without writing to Clock._start.
- Clock keeps a private, millisecond-cut offset that every mode but
`wall` adds to its reading: fixed is start + advanced, tick adds a
second per call on top, running adds elapsed real time. The public
Clock API stays read-only, so world code cannot move time.
- Instance.advance_clock(by=None, *, to=None) takes exactly one of a
timedelta or an instant (either form now= takes) and answers the new
reading as canonical text. It runs under the instance lock, is not a
call (no ordinal, no tick, no call-log entry), and every node,
inspect() and the next freeze read the moved clock. It is refused,
as WorldBug, for a backward move, a wall clock, a move past year
9999, a wrong argument type, and inside a tool call (transaction=False
included), bulk() or a state formatter.
- New control tool controller_advance_clock(seconds, to), behind the
existing --include-control-tools flag and never listed, answering
{"now", "clock_mode"}. Every refusal reaches the harness as a
ToolError coded clock_not_advanced, in the wire's argument names,
rather than as a WorldBug the OpenEnv layer would scrub to "internal
error". Its name joins CONTROL_TOOL_NAMES; it is not deprecated.
- Docstrings, CLI help and docs that described a single deprecated
control tool now describe the control tools. clock.md gains a short
"Moving the clock forward" section with a runnable example, and
serving_and_openenv.md a "Moving the clock" subsection; api.md notes
that a comment-led statement on inspect() can keep a pre-advance
reading under fixed, as it already can under tick.
- Tests drive the feature through world.instance(...), the control
tool, an OpenEnv step and the real wire, with a test per refusal
guard. The docs rule against naming control tools now applies only
to deprecated ones, and the reference world's registry test includes
the new name.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QtPPDeDagBgpFidJmRVQzz
concepts.md still listed it as unplanned, which advance_clock now contradicts. Also word the control tool's docstring so its refusals read as examples rather than the complete list. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QtPPDeDagBgpFidJmRVQzz
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixed #47
A harness can now move an instance's virtual time forward deterministically, for example to reach a retry window or a due date, without writing to
Clock._start.Python
inst.advance_clock(by=None, *, to=None) -> strtakes exactly one of atimedeltaor an instant (either formnow=takes), and returns the new reading as canonical text.fixedtickrunningwalltransaction=Falsetools), insidebulk()and inside a state formatter.inspect()and a laterfreeze()all read the moved clock.ClockAPI stays read-only, so world code cannot move time throughctx.clock.OpenEnv
New control tool
controller_advance_clock(seconds | to), which answers{"now", "clock_mode"}.--include-control-toolsflag and is never listed.controller_run_sqlis.ToolErrorcodedclock_not_advanced. AWorldBugwould be scrubbed to "internal error" on the wire, so the harness could not see why it was refused.Out of scope
SeahavenClientconvenience method.seahaven.http.Docs and tests
clock.md, a "Moving the clock" subsection inserving_and_openenv.md, and reference rows. Pages that described a single deprecated control tool now describe the control tools.world.instance(...), the control tool, an OpenEnv step and the real wire, with a test for each refusal.test_docs.pychange: the rule that docs must not name acontroller_tool now applies only to deprecated tools, so the new tool can be documented.🤖 Generated with Claude Code
https://claude.ai/code/session_01QtPPDeDagBgpFidJmRVQzz
Generated by Claude Code