docs(readme): correct --last-seq disconnect/resume docs#319
Draft
joycel-github wants to merge 420 commits into
Draft
docs(readme): correct --last-seq disconnect/resume docs#319joycel-github wants to merge 420 commits into
joycel-github wants to merge 420 commits into
Conversation
Centralize configuration loading by using newConfig across the ax sub commands, to use the default config is no --config is provided.
# Introduce AntigravityPlanner (Initial Cut) This PR introduces the `AntigravityPlanner` into the AX framework. This is just an **initial cut** to establish the connection and basic flow. There are heavy TODOs left for subsequent PRs. ## Key Changes & Clarifications 1. **Initial Cut**: This version only takes a service URL and handles limited content types. We will expand this in future PRs to handle more complex interactions and data types. 2. **Python Sidecar**: The Antigravity planner works as a Python sidecar. The relevant code resides in `google3` because the Antigravity SDK is not public yet. cl/902522140 has the initial change and is subject to a pending CL in Antigravity side 3. **Status & TODOs**: This is a preliminary prototyping to show Antigravity can select and execute local skill but many to do. **Nexts** - README - uplift Antigravity python server - support more types ## Test Evidence We verified the basic local skills selection and execution end-to-end. Below is the evidence from the successful test run. **Client Command:** ```bash go run ./cmd/ax exec --server localhost:8494 --input "Give me an emoji for sundar" ``` **Cient Output** ⏺ Give me an emoji for sundar The emoji for Sundar is 👓(⌐■_■) 👍. **Antigravity Server Logs:** The logs show the planner successfully loaded the skills directory and processed the steps (including reading files and searching) to find the emoji: [Antigravity Server] Starting simplified Antigravity Planner server on port 8085... [Antigravity Server] Received request with 1 messages. [Antigravity Server] Loaded skills: [SkillPath(path='/usr/local/google/home/lhuan/projects/gar/skills/ax/examples/skills', path_type='absolute')] [Antigravity Server] Creating new conversation for 9ea10cff-a2c7-4ee0-9091-b3a9bb717aba [Antigravity Server] Step received: user_input -> "Give me an emoji for sundar" [Antigravity Server] Step received: planner_response [Antigravity Server] Step received: view_file [Antigravity Server] Step received: list_directory [Antigravity Server] Step received: run_command -> Returns 👓(⌐■_■) 👍 [Antigravity Server] Step received: planner_response -> "The emoji for Sundar is 👓(⌐■_■) 👍."
We guard by conversation ID, not by exec ID anymore.
#229) 1. Conversation Forking Protocol: Added Fork RPC to EventLogService with support for specifying source conversation, sequence number (checkpoint), and optional destination ID. Controller: Implemented the Fork method to clone events while preserving shared execution references. CLI: Added root-level ax fork command. It supports both remote mode (via --server) and "headless" local mode (reading ax.yaml or custom config via --config). 2. Trace Viewer Fixes Display Correct ID: Fixed the trace viewer to display the actual Conversation ID in the terminal output and UI header instead of the random root execution ID. Chronological Ordering: Fixed a bug where execution cards were sorted alphabetically by their random UUID ExecID. They are now sorted chronologically based on the order they occurred in the conversation. 3. Testing Added unit tests for the forking logic in the controller. Added integration tests for the server-side RPC. Co-authored-by: anj-s <anjalisridhar@google.com>
AX won't be doing any healthchecks itself. agent.HealthCheck is obsolete now. We keep the AgentService.HealthCheck RPC to ensure agent implementators provide a health check mechanism on wire for job schedulers.
…util (#242) Refactor: Move newControllerFromConfig to shared package internal/cliutil
This PR optimizes the building of execution traces in cmd/ax/trace.go by iterating over the already ordered execIDs list and looking up events in a map. This avoids a redundant sorting step and reduces complexity from O(N^2) to O(N). A unit test was also added to verify order preservation.
This PR adds a new conversation_id field in AgentMessage. Also add the conversationID to the signature of Agent.Connect and Executor.Exec so that we can: 1. propagate conversationID from controller to sub-agent, like remote agent, a2a agent 2. propagate conversationID to substrate worker The conversationID is unused by anything yet. It will be picked up by a2a agents in follow up PRs, and possibly substrate agent as well.
bytes allow arbitary configuration encoding format, e.g. JSON. Rename AgentStart.config to AgentStart.agent_config for consistency.
We allow any encoding for sub agent configuration after google-gemini/ax#248. This change is removing the proto encoding requirement for the Gemini and the test agents.
AX is primarily a server project. The Serve section is accidentally burried undernath other sections.
- ConversationId is added in the reply agent message of the remote agent example. Without conversation id the message gets rejected. (The ate agent and k8s sandbox agent have it added in the previous PR).
Allows us to more easily track and update experimental features.
Add content types for different media types. These new types will be used by the A2A bridge. Mirror the exact content types from Interactions with a slight difference: - Added two MimeType in DocumentContent for A2A bridge: `TYPE_JSON`, `TYPE_PYTHON`. The current enum in Interactions has a small set of values. We may update this in the future to make them consistent.
This PR moves the internal_only boolean from `AgentOutputs` to `Message`. 1. Internal-only messages are persisted in event log as `Message`. The `internal_only` bit is not persisted. 2. I'd like to store some execution metadata as an internal event, e.g. conversation id, task id, etc. 3. When resume, these internal metadata is read by AX controller, but I want to filter them out of the history that we feed into planner agents or custom agents since these messages are of no meaning to them. Thus, moving it to Message level for log filtering.
# Refactor Antigravity Planner to use WebSocket and AgentMessage
This PR refactors the Antigravity Planner to use the standard
`AgentMessage` protocol for communication between the Go controller and
the Python planner server. It also changes the protocol from HTTP/JSON
to Websocket to support tool call. AX agents are invoked as Tools.
Python side CL cl/904297174 (need to improve the code quality)
Next up:
* clean up the logic for HITL.
* get cl/906138865 into google3 and further github once antigravity SDK
is released
## E2E Test Result: Antigravity Planner with Tool Call
### Commands Run
* Start remote agent: `go run ./examples/remote_agent`
* Start Python planner server:
`/google/src/cloud/lhuan/jetski-ax/google3/blaze-bin/experimental/users/lhuan/jetski_planner_2`
* Start AX server: `./bin/ax serve --config ax.yaml`
* Run client: `./bin/ax exec --server localhost:8496 --input "Use the
'secret_code' agent to get the secret code
### Logs and Outputs
#### Python Server Log
```
[AX Server] Loaded subagents: [{'id': 'secret_code', 'description': 'Retrieves secret codes and performs sensitive text transformations that only this agent can do.'}]
[AX Server] Generated tool for subagent: secret_code
Starting connection to harness and creating conversation...
Sending prompt to harness: Use the 'secret_code' agent to get the secret code
Waiting for steps...
[AXToolRunner] Intercepted tool call: secret_code
[AXToolRunner] Raw response from Go: {"outputs":{"messages":[{"role":"assistant", "content":{"text":{"text":"secret code 111 from ax"}}}]}}
[AXToolRunner] Received result from AX: secret code 111 from ax
Final Response: The secret code for user 'sundar' is `secret code 111 from ax`.
```
#### AX Server Log
```
2026/04/28 07:27:15 [AX] Connecting to Antigravity WebSocket for execution b8549e17-483a-4016-a06b-f81cd1a579dc
2026/04/28 07:27:22 [AX] Handling tool call: secret_code
2026/04/28 07:27:22 [AX] Captured 1 tool outputs for secret_code
2026/04/28 07:27:24 [AX] Conversation completed.
```
#### Client Output
```
⏺ Use the 'secret_code' agent to get the secret code
The secret code for user 'sundar' is `secret code 111 from ax`.
```
TAG=agy
CONV=4d4e96b3-966e-488c-8de2-31a1c6bb1978
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Also add a TODO about the current bug and why we are not yet fixing it.
* Embed python artifacts into ax And setup the AGY harness service at runtime. * refactor: remove directory and file filtering logic from setup walk function * refactor: rename installRequirements to install in python sidecar setup * refactor: simplify Sidecar configuration by passing PYTHONPATH directly to Start method and removing unnecessary environment and binary options * feat: configure pip install to use local site-packages and filter unwanted files during setup * feat: support appending to PYTHONPATH and update Python setup path resolution * refactor: remove redundant file filtering in sidecar setup directory traversal * refactor: simplify python package installation and add PyPI index URL to pip command * fix: remove extra index URL from pip install command * refactor: remove Sidecar.Setup method and move asset extraction logic to external standalone function * refactor: remove PythonPath configuration field from sidecar.Config in favor of direct global pythonPath usage * test: remove integration test for antigravity sidecar auto-start logic * fix: add pypi.org extra-index-url to python package installation command * refactor: remove Stdin support from pythonsidecar configuration and cleanup redundant harness definitions
* Consolidate .ax directory path resolution into a centralized config helper * refactor: remove unused TargetDir field from SetupOptions in python sidecar tests * test: update setup test to use HOME directory and verify .ax subdirectory extraction * refactor: simplify directory path resolution and variable naming in python sidecar setup * perf: skip redundant file copying and pip installations when dependencies are up to date * fix: remove redundant check for non-existent requirements file in setup * refactor: track file updates during extraction to skip unnecessary pip installs * feat: add progress notification when installing Antigravity SDK * fix: ensure site-packages directory exists before returning path in setup * feat: add pypi simple index to pip install command for environment compatibility
* Harden Antigravity Interactions harness HTTP client
Fix a substrate suspend/resume failure and tighten the config surface:
- Disable HTTP keep-alives on the harness's default client. On substrate the
actor is suspended after a turn and resumed for the next (with a new routable
IP), which leaves any pooled keep-alive connection stale; reusing it made the
next turn's request fail. Opening a fresh connection per request avoids that
at the cost of an extra handshake.
- Remove the public HTTPClient override from AntigravityInteractionsConfig.
External callers don't configure the harness's transport, and exposing it
risked silently reintroducing the keep-alive bug. New now always owns its
(keep-alive-disabled) client; tests inject a fake transport via an unexported
newWithHTTPClient seam.
- Reorder AntigravityInteractionsConfig fields to list required (Agent,
StateDir) before optional, with clearer doc comments.
Build and package tests pass.
* Explain why the HTTP transport is cloned, not newly created
Address review feedback: document that cloning DefaultTransport (rather than a
bare &http.Transport{}) is intentional -- it inherits the production defaults
(env proxy, dial/TLS/handshake timeouts, HTTP/2) and only overrides keep-alives.
A fresh empty transport would silently drop those.
parseStreamedTurn only handled interaction.* and step.* SSE events; a
server-emitted "error" event fell through the switch and was silently
dropped. The turn then returned as completed-but-empty, which:
- made a failure (e.g. INVALID_ARGUMENT for a malformed client tool
result) look like a blank "no response" turn, and
- persisted the failing interaction's id as a poisoned resume cursor.
Add an "error" case that returns a real error, plus a serverErrorMessage
helper that extracts message/status from the error payload. Now a
turn-level server failure aborts the turn with a descriptive error
instead of being hidden.
Adds tests for the error-event path and serverErrorMessage formatting.
* Run antigravity interactions as actor. * Add instructions for users. * Remove a comment. * Fix readme format.
…ume (#289) The Python sidecar previously kept a per-conversation Agent instance in an in-process dict (self._agents) with a lock, and relied on that cache to preserve conversation history across turns. This tied conversation state to a single sidecar process lifetime: any restart, crash, or multi-replica scaling would silently drop history. Delete the cache and use the Antigravity SDK's own per-conversation persistence instead. LocalAgentConfig accepts (conversation_id, save_dir); the SDK's localharness persists trajectory state to {save_dir}/{sdk_conv_id}.db. Each turn now: 1. Constructs a fresh Agent scoped to a per-AX-conversation save_dir (~/.ax/antigravity/conversations/{ax_conv_id}/), so each AX conversation gets its own directory with at most one .db file. 2. If a .db exists there (from a prior turn), passes its stem as the SDK's conversation_id to trigger resume. The SDK's conversation_id is resume-only -- passing a non-existent id errors out -- hence the discover-then-pass pattern. 3. Runs the turn inside an async-with Agent(...) block, disposing at the end. No process-level state. Mirrors internal/harness/antigravityinteractions/DefaultStateDir() convention (state under ~/.ax/, out of the agent's cwd/operating surface). A TODO references issues #269 and #203 for the eventual controller-injected save_dir via harness_config. Test replaces test_grpc_connect_agent_reused (which asserted cache behavior) with test_grpc_connect_agent_per_turn_with_save_dir, which asserts per-turn Agent construction and deterministic per-conv save_dir naming. Verified end-to-end with ax exec --conversation <id>: turn 2 correctly recalls a name introduced in turn 1 across a fresh sidecar process, with only one .db file per conversation on disk. Different --conversation ids remain isolated.
PR #244 normalized thought summary text with a trailing '\n' in harness_server.py but harness_server_test.py wasn't updated. test_grpc_connect_success and test_grpc_connect_buffering assert against the pre-normalization strings and fail. The drift went unnoticed because the Python tests aren't wired into CI (.github/workflows/go.yml only runs go test ./...). Wiring pytest into CI is the follow-up.
* antigravity: plumb sidecar state_dir from ax.yaml
Sidecar's trajectory storage directory was hardcoded in Python. This
plumbs it through as a yaml config that users can override, matching
the pattern already used for the Interactions harness's state_dir.
Flow:
- ax.yaml: harnesses.antigravity.state_dir (optional; empty = default)
- config.go: AntigravityHarnessConfig.StateDir field (yaml surface only,
no default logic on the Go side)
- cliutil.go: passes yaml value as-is (empty string when unset)
- antigravity Go client: appends --state-dir arg only when non-empty
- Python sidecar: argparse --state-dir with default
~/.ax/antigravity/conversations. Default is a transitional fallback
for substrate mode (where ActorTemplate doesn't inject the flag yet).
Removable once substrate can set the field via ActorTemplate.
Servicer's state_dir is required (no fallback) -- production path always
receives it from argparse; tests pass tmp_path.
Verified end-to-end with ax exec:
- No yaml state_dir -> ~/.ax/antigravity/conversations/{conv_id}/
- yaml state_dir: X -> X/{conv_id}/
- Different conversations remain isolated across both paths.
Closes part of the local-mode gap in issue #269 (harness_config
contract design); a follow-up will do the same for substrate via
ActorTemplate.
* antigravity: address PR review comments (P1/P2/P3)
- P1: two Python tests referenced tmp_path without declaring the fixture;
add tmp_path to their signatures.
- P2: state_dir CLI arg was not tilde-expanded, so ~/.ax/... became a
literal ~ dir. Add .expanduser().
- P3: no Go-side test asserted --state-dir forwarding. Extract
buildSidecarArgs() as a small pure helper and add table test for the
empty/non-empty cases, plus a yaml parse test for
AntigravityHarnessConfig.StateDir.
* antigravity: inline sidecar args build instead of separate helper
Follow-up to review feedback: buildSidecarArgs was overkill for a 3-line
conditional. Move it back into New() inline. Also drops the associated
TestBuildSidecarArgs (the arg-forwarding rule is now covered only by
end-to-end verification).
The 17 tests in python/antigravity/harness_server_test.py have never run in CI. .github/workflows/go.yml only runs 'go test ./...' and the Makefile 'test' target likewise only runs Go. That let PR #244 land with 2 stale assertions unnoticed (fixed in #291). Adds: - .github/workflows/python.yml -- dedicated Python workflow (kept separate from the Go-only go.yml so each can evolve independently). - Makefile 'test-python' target for local parity. Test deps are inlined in the workflow rather than added as a separate requirements-test.txt -- the diff is 2 packages ('pytest>=7.0', 'pytest-timeout>=2.0'), not worth its own file. Version floors match the upstream google-antigravity SDK's dev extras so this doesn't drift as pytest evolves. --timeout=30 --timeout-method=thread guards against hung gRPC servers so a stuck test can't eat the whole workflow budget.
* antigravity: parse and validate request harness_config Parse HarnessStart.harness_config (JSON-in-bytes) and overlay it onto the server's default LocalAgentConfig before each turn. - Blocks a request from overriding AX-owned persistence fields (save_dir, conversation_id) via _AX_MANAGED_CONFIG_FIELDS; these are injected last so a request can't redirect trajectory storage. - Reconstructs the config (not model_copy) so the SDK re-validates the overlaid values and surfaces its own error; invalid config fails the turn with INVALID_ARGUMENT instead of crashing. - save_dir derives from the injected state_dir (#292) as state_dir / conversation_id. * antigravity: address harness_config review comments - Inline _parse_harness_config into _build_config_for so the parsed dict stays a local intermediate; the method's only boundary type is the validated LocalAgentConfig (no dict[str, object] across a helper boundary). Addresses the "introduce a type for the config" comment. - Make per-conv save_dir test assertions portable: compare against str(tmp_path / conversation_id) instead of hardcoding "/conv-1", and drop the now-vestigial Path.home monkeypatch (save_dir derives from the injected state_dir since #292). Addresses the Windows path separator comment. _AX_MANAGED_CONFIG_FIELDS keeps guarding both conversation_id and save_dir on purpose: harness_config is a separate client-controlled surface from the request's conversation_id, so blocking it prevents a request from redirecting another conversation's trajectory storage.
LocalAgentConfig uses pydantic's default extra="ignore", so an
unrecognized field in a request's harness_config -- e.g. a typo like
"system_instruction" for "system_instructions" -- was silently dropped
and the caller believed the override took effect when it did not.
Add _reject_disallowed_fields(overrides), which factors two key checks
into one helper and raises HarnessConfigError (mapped to
INVALID_ARGUMENT) naming the offending field(s):
- fields that come from outside harness_config (_NON_HARNESS_CONFIG_
FIELDS: conversation_id from the runtime request, save_dir from the
server's state_dir), and
- unknown top-level fields.
Validation is best-effort and top-level only: nested-key and value/type
validation is delegated to the SDK's own LocalAgentConfig validation at
construction time.
state_dir is an AGY SDK implementation detail (where trajectory / resume-cursor storage lives), not something AX users should configure. Remove the yaml surface for both built-in harnesses and derive the path internally from config.AXAssetsDir(). - config: drop StateDir from AntigravityHarnessConfig and AntigravityInteractionsHarnessConfig. - antigravity: add DefaultStateDir() -> ~/.ax/antigravity/conversations, mirroring antigravityinteractions.DefaultStateDir(). cliutil now passes this into antigravity.New instead of the yaml value. - cliutil: interactions harness always uses DefaultStateDir(); drop the yaml read + fallback. The internal APIs (antigravity.New's stateDir arg, the required AntigravityInteractionsConfig.StateDir field, and the Python sidecar's --state-dir default) are unchanged -- only the user-facing ax.yaml knob is removed. Addresses rakyll's follow-up on #292.
…300) Materialize agentskills.io skills from the Gemini Enterprise Skill Registry (Vertex AI v1beta1) into on-disk folders before the harness starts, so the built-in harnesses can use registry-hosted skills on the local `ax exec` / `ax serve` path. - internal/skills/geminienterprise: harness-agnostic package that reads config.SkillsConfig, drives the registry client (ListSkills / GetSkill / GetSkillRevision / skills:retrieve), safe-unzips payloads to <target_dir>/<skill-id>/, and reports what it wrote. First-wins on duplicate ids with a warning; fail-safe (a registry error never blocks harness startup). - config: top-level `skills.registries[]` (harness-agnostic -- each actor runs a single harness that consumes the materialized folder). Per-registry selection (skills / query / all), required target_dir, and a validated "exactly one selection mode" rule. Also wires the interactions harness's system_instruction from ax.yaml. - cliutil: materializes skills once, up front, at controller construction; for the interactions harness (no SKILLS_DIR concept) it appends a discovery pointer to the system instruction. Scope: local path only; the substrate/pod path does not yet read ax.yaml. Verified end-to-end against a live registry (by-id and by-query).
The exec example used `--harness coding`, but no "coding" harness exists; runHarness only accepts "antigravity" and "antigravity-interactions" and errors otherwise, so the command as written fails. Point the example at the real "antigravity" harness.
* Honor view_file line range and cap result size
execViewFile read the whole file and ignored the agent's StartLine/EndLine,
so viewing a large file returned its entire content as the tool result --
a ~900KB blob for a 3k-line CSV stalled the following turn.
Implement the Antigravity view_file contract (1-indexed inclusive line range
with slice-notation windowing) plus defensive caps:
- StartLine/EndLine window (neither=first N lines; start-only=next N forward;
end-only=previous N backward; both=precise range, capped to N).
- viewFileMaxLines / viewFileMaxBytes caps so a large file can never blob.
- ContentOffset honored as the read position within the windowed content.
The result payload is just {"content": ...}; the view_file result schema is
defined server-side, so no extra fields are added.
Adds intArg/intArgOK helpers and tests for windowing, byte cap, offset read,
and range honoring.
* view_file: UTF-8-safe byte cap + pagination metadata
Address review feedback on the byte cap:
- applyByteWindow backs the cut off to the last complete UTF-8 rune so a
multi-byte character straddling viewFileMaxBytes is never split (raw byte
slicing could produce invalid UTF-8, corrupting the last char and JSON
serialization).
- execViewFile returns the metadata the server needs to distinguish a
complete read from a paginated/byte-truncated one: content, start_line/
end_line (0-indexed inclusive served range), content_offset,
line_range_bytes (total bytes of the line range pre-byte-cap), and
num_lines/num_bytes. The server detects truncation via
content_offset+len(content) < line_range_bytes and prompts the model to
resume from that offset.
A paired server change reads these fields instead of hardcoding
start_line=0/end_line=last.
Adds tests for UTF-8 boundary capping, pagination metadata, and resume.
* docs(readme): refresh Antigravity setup, auth, and CLI usage Re-land the README refresh that was approved as #310 but never reached main (it merged into #309's branch, which was then squash-merged, orphaning this content). - Document the built-in Antigravity harness: local execution needs python3 and pip on PATH; AX auto-starts the Python sidecar and installs the pinned SDK dependencies on first use. - Promote Authentication to its own top-level section (Google AI Studio and Vertex AI / ADC). - Refresh Quick Start / Usage examples, document the --harness-config and --harness-config-json flags, and add a per-request configuration example. * docs(readme): use gemini-3.5-flash in per-request config example Update the per-request harness config example from gemini-2.5-pro to a current model, matching the model naming used in examples/skills.
joycel-github
force-pushed
the
readme-lastseq-accuracy
branch
from
July 16, 2026 16:20
7f6d882 to
1efebc7
Compare
Two related inaccuracies in the resume/disconnect docs: - --last-seq: the client sends ExecRequest.LastSeq but the controller has no server-side reader for it (regressed in the #308 controller rewrite; previously handled in #262), so the documented "server replays later events to catch the client up" behavior does not happen. Tracked in #320. - --resume: it only re-runs an execution that is still pending; if the previous execution already completed it returns without doing anything. The earlier wording implied a general disconnect/replay recovery. Reword Quick Start and the --resume/--last-seq option docs to match the actual controller behavior.
joycel-github
force-pushed
the
readme-lastseq-accuracy
branch
from
July 16, 2026 16:48
1efebc7 to
67c7192
Compare
rakyll
added a commit
that referenced
this pull request
Jul 21, 2026
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
8 participants
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.
Summary
--last-seqso a disconnected client can catch up. The controller does not readExecRequest.LastSeq(no server-side reader ininternal/), so that behavior does not happen.--resume+ the conversation ID instead of the non-functional--last-seqcatch-up example.--last-seqas reserved and note the server does not currently act on it.Context
This regressed when the resume path was rewritten (server-side
last_seqhandling existed via #262, dropped in the #308 controller rewrite). Code gap tracked in #320; this PR only corrects the docs.Part of #299