Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1527,8 +1527,8 @@ Gemini exhaustion goes straight to Opus; see
`--antigravity-models`. Antigravity turns are single-shot and its usage totals
are estimated because `agy` does not expose token counts. A model that
repeatedly answers in chat prose with no recoverable structured payload also
falls back to the next chain model. When `agy` supports `--json-schema`,
structured turns use agy's schema-constrained output. Disable it with
falls back to the next chain model. When `agy` supports `--output-format`,
structured turns read the single JSON answer from agy's JSON envelope. Disable it with
`--antigravity-structured-output off`; see
[Structured output](docs/local_agent_loop.md#structured-output).

Expand Down
1 change: 1 addition & 0 deletions docs/architecture/decisions/execution-and-concurrency.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,3 +65,4 @@ never rewritten or deleted. The detail doc describes the current design.
- 2026-11-20: A non-`SUCCESS` agy envelope's decoded error is a typed provider diagnostic on `AgentResult` and is classified as the terminal frame in every failure phase. A fallback response that fails validation after such an envelope is classified as a provider failure, with no repair and no format-failure fallback (#2029).
- 2026-11-20: The agy structured-output schema avoids non-string enums, which Gemini rejects with INVALID_ARGUMENT; `schema_version` is a plain integer validated by the protocol parsers. A structured attempt whose provider diagnostics (non-`SUCCESS` envelope, stdout outside the envelope, or the silent attempt's own agy log) show a schema-naming INVALID_ARGUMENT is replayed once per turn without schema flags, with a warning, a dedicated attempt slot, no retry, no format-failure count and no repair. Model prose is never evidence (#2039).
- 2026-11-20: `run-tests` refuses a request before reservation or launch when a registered worktree link or private environment of the broker checkout is no longer intact, naming it in a no-test `cancelled` frame; the pre-check is fail-open and never poisons the checkout. Coder prompts name the coder checkout's registered links as shared operator infrastructure. An uncitable receipt for a citable launcher family names the rejected argument through a static explainer that shares the recognizer's argument walk; the allow-list and persisted reasons are unchanged (#2036).
- 2026-11-20: agy's `structured_output` keeps only the properties the request schema declares, so the loose schema stripped every review field. Structured Antigravity turns now pass `--output-format json` with no `--json-schema` (the probe needs only `--output-format`), and `structured_output` is never the answer source. The answer is the response file, else the single expected-kind (or `agent_unavailable`) JSON object recovered from the envelope `response`, counted as top-level objects over the whole response before any marker handling, rendered with the payload's own footer state and signature in code, else the marker text. Several candidate objects, a wrong kind, or an out-of-span footer whose state differs is a typed tool-authored ambiguity on `AgentResult`; the validated turn records it as an `agent-unavailable` format failure that feeds #2029's format accounting, with no repair and no classification from model text. Reviewer repair refuses envelope-only `{schema_version, kind, state}` payloads (#2049).
14 changes: 7 additions & 7 deletions docs/architecture/execution-and-concurrency.md
Original file line number Diff line number Diff line change
Expand Up @@ -530,13 +530,13 @@ and an all-groups-cooling state stops before invoking. Only when every group
carries a parsed long reset is `QuotaResetExceededError` raised. Memory is not
persisted across processes.

**Antigravity structured output (#2029, #2039).**
`agents/antigravity_structured.py` adds agy's `--json-schema` channel (string
enums only) for eligible kinds after a cached probe. A renderable
`structured_output` wins; validators stay authoritative. No-payload turns get
a retry-free `format-fallback`. A schema-naming INVALID_ARGUMENT in provider
diagnostics (not model prose) replays the dispatch once per turn without schema
flags: no retry, format failure or repair. See the
**Antigravity structured output (#2029, #2039, #2049).**
`agents/antigravity_structured.py` requests agy's schema-free
`--output-format json` envelope for eligible kinds. Answer: response file, else
the one expected-kind object in `response` (footer/signature added in code),
else the marker; `structured_output` is ignored. Ambiguity (several objects,
wrong kind, contradicting footer) is a trusted, repair-free format failure
feeding `format-fallback`. Envelope-only reviews are refused repair. See the
[CLI guide](../local_agent_loop.md#structured-output).

**Quota reset wait.** `--wait-for-quota-reset DURATION` (off by default) turns
Expand Down
6 changes: 3 additions & 3 deletions docs/local_agent_loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -1145,11 +1145,11 @@ The default Antigravity chain is `Gemini 3.8 Flash (High)` → `Claude Opus 5.5

### Structured output

When the installed `agy` advertises `--output-format` and `--json-schema`, structured turns ask agy for schema-constrained output. These are PR and plan reviews, plan state and revisions, coder follow-ups, issue implementations and task results. agent-loop writes a loose per-kind JSON Schema beside the private response file and passes `--output-format json --json-schema <file>`. It reads the payload from the envelope's `structured_output` and appends the footer marker and signature itself. A narrating model therefore still yields a usable response. A usable `structured_output` takes precedence over the response file. The response file, and then the stdout marker, remain the fallback when `structured_output` is missing or the status is not `SUCCESS`. agent-loop's own validators stay authoritative. A non-`SUCCESS` envelope is treated as an operational failure reported by agy. Its decoded error is classified as the final provider line, so model narration cannot hide it. Auth and billing errors stop without retry or fallback, and quota or capacity errors take the quota path. A fallback response that then fails validation is never counted as a format failure. A turn that must carry content outside the JSON keeps the response-file channel. Such turns include those with signed human requirements to acknowledge, a required direct-discussion acknowledgement, or a reviewer's resolved-requirements marker. Repair, classification and discuss turns also keep it.
When the installed `agy` advertises `--output-format`, structured turns ask agy for its JSON envelope with `--output-format json`. These are PR and plan reviews, plan state and revisions, coder follow-ups, issue implementations and task results. No request schema is sent: agy's `--json-schema` channel keeps only the properties the schema declares in `structured_output`, which stripped every review field (#2049), so `structured_output` is never used as the answer. agent-loop takes the answer in this order: a non-empty response file; otherwise exactly one JSON object of the expected kind (or `agent_unavailable`), bare or in a single ```json fence, in the envelope's `response` text; otherwise the stdout marker in that text. A recovered object gets its footer marker (carrying the object's own state) and signature appended in code, so a model that writes its payload only in chat still yields a usable response; an object without a state is never given one and falls back to the marker text. Candidates are counted over the whole `response`, before the stdout marker is considered. Two or more top-level objects (including one before and one after the marker), a single object of another kind or without a kind, or a state footer outside the object that contradicts it is a format failure: no object is picked, no repair runs, and the failure is classified only from a tool-authored diagnostic, so it counts toward the format fallback to the next chain model. agent-loop's own validators stay authoritative. A reviewer payload carrying only `schema_version`, `kind` and `state` is never accepted and is refused repair. A non-`SUCCESS` envelope is treated as an operational failure reported by agy, and no payload is recovered from its prose. Its decoded error is classified as the final provider line, so model narration cannot hide it. Auth and billing errors stop without retry or fallback, and quota or capacity errors take the quota path. A fallback response that then fails validation is never counted as a format failure. A turn that must carry content outside the JSON keeps the response-file channel. Such turns include those with signed human requirements to acknowledge, a required direct-discussion acknowledgement, or a reviewer's resolved-requirements marker. Repair, classification and discuss turns also keep it.

The schema uses only constructs Gemini function declarations accept: `enum` appears only on string values, so `schema_version` is a plain integer and the validators check its value. If agy or the provider still rejects agent-loop's request schema (an `INVALID_ARGUMENT` that names the schema, reported in a non-`SUCCESS` envelope, in stdout outside the envelope, or in the silent attempt's own agy CLI log), agent-loop logs a warning and replays that turn once without the schema flags. The replay uses the same prompt and model, consumes no retry, is not a format failure and gets no repair; a failed replay is classified normally. The next turn tries structured output again. Model prose that quotes such an error never triggers the replay. Use `--antigravity-structured-output off` to disable the channel persistently.
If agy or the provider still rejects agent-loop's structured request (an `INVALID_ARGUMENT` that names a request schema, reported in a non-`SUCCESS` envelope, in stdout outside the envelope, or in the silent attempt's own agy CLI log), agent-loop logs a warning and replays that turn once without the JSON flags. The replay uses the same prompt and model, consumes no retry, is not a format failure and gets no repair; a failed replay is classified normally. The next turn tries structured output again. Model prose that quotes such an error never triggers the replay. Use `--antigravity-structured-output off` to disable the channel persistently.

The capability is probed once per agy command with `agy --help`. A probe that fails, an older agy, or `--antigravity-arg` values that already set `--output-format` or `--json-schema` keep the legacy channel. `--antigravity-structured-output off` (default `auto`) disables the schema flags explicitly. When a prompt is too large for argv, the short `--print` directive names the response file (or the structured result) and tells the model not to answer in chat.
The capability is probed once per agy command with `agy --help`. A probe that fails, an older agy, or `--antigravity-arg` values that already set `--output-format` or `--json-schema` keep the legacy channel. `--antigravity-structured-output off` (default `auto`) disables the JSON envelope explicitly. When a prompt is too large for argv, the short `--print` directive names the response file (or asks for exactly one JSON object as the final answer) and tells the model not to answer in chat.

Every `agy --print` call passes `--print-timeout` from
`--antigravity-print-timeout-seconds` (default `600`, i.e. ten minutes), which
Expand Down
115 changes: 69 additions & 46 deletions src/coding_review_agent_loop/agents/antigravity.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,8 @@
)
from .antigravity_structured import (
AgyEnvelope,
SCHEMA_FILE_NAME,
AmbiguousPayload,
RecoveredPayload,
envelope_provider_error,
envelope_request_rejection,
STRUCTURED_KIND_FOOTERS,
Expand All @@ -59,8 +60,8 @@
parse_agy_json_envelope,
render_structured_output_text,
structured_output_signature,
recover_response_payload,
structured_request_rejection_line,
write_structured_output_schema,
)
from .replacement import classify_provider_executable_replacement_interruption
from ..worktree_hints import dependency_hint_environment
Expand Down Expand Up @@ -1426,7 +1427,7 @@ def structured_request_rejection_evidence(
"""Provider-owned evidence that agy rejected the request schema (#2039).

Call only for a structured attempt. Nothing counts when the attempt
produced a renderable ``structured_output`` or a response file, or timed
produced a payload rendered from the envelope (#2049) or a response file, or timed
out. Sources, in order: a non-SUCCESS envelope's error/status; stdout
outside any parsed envelope; raw stdout of a nonzero exit with no
envelope; this silent attempt's own agy log. A SUCCESS envelope's
Expand Down Expand Up @@ -1468,44 +1469,63 @@ def _select_structured_turn_text(
*,
kind: str,
signature: str,
) -> tuple[str, AgentTextSource, str | None]:
"""(text, text_source, provider error) for a JSON-mode turn (#2029).

Precedence: a SUCCESS envelope whose ``structured_output`` renders, then a
non-empty response file, then the public-response marker in the
envelope's prose (or raw stdout when no envelope parsed). A non-empty
response file does not prove a usable contract, so a renderable payload
wins over it; the file stays on the result for audit only.

A non-SUCCESS envelope is an operational failure reported by agy, not
model prose: its decoded error comes back separately as the provider
error, so classification can read it as the terminal provider frame in
every failure phase (narration in ``response`` can never displace it).
) -> tuple[str, AgentTextSource, str | None, str | None]:
"""(text, text_source, provider error, ambiguity) for a JSON-mode turn.

Precedence (#2029, #2049):

1. A non-SUCCESS envelope is an operational failure reported by agy, not
model prose: its decoded error comes back separately as the provider
error, so classification can read it as the terminal provider frame in
every failure phase. The response file, else the marker text of the
envelope's prose, is the fallback content; no payload is recovered
from a failed envelope's prose.
2. A non-empty response file.
3. A SUCCESS envelope whose ``response`` holds exactly one expected-kind
(or agent_unavailable) JSON object: rendered in code with the footer
carrying the payload's own state and the signature.
4. An ambiguous ``response`` (several candidate objects, a wrong kind,
or a contradicting footer): empty text plus a tool-authored diagnostic
the validated turn records as a format failure.
5. Otherwise the public-response marker in the envelope's prose (or raw
stdout when no envelope parsed).

agy's ``structured_output`` field is never the answer source: it holds
only declared schema keys, so it could displace the model's full payload.
"""
envelope: AgyEnvelope | None = parse_agy_json_envelope(stdout)
if envelope is not None and envelope.succeeded and envelope.structured_output is not None:
rendered = render_structured_output_text(envelope.structured_output, kind, signature)
if rendered is not None:
if response_file_text is not None:
log(
config,
"Antigravity returned both structured_output and a response file; "
"using structured_output (the file is kept for audit only)",
)
return rendered, "structured_output", None
log(config, "Antigravity structured_output was not renderable; falling back")
provider_error = (
envelope_provider_error(envelope)
if envelope is not None and not envelope.succeeded
else None
)
if response_file_text is not None:
return response_file_text, "response_file", provider_error
if envelope is not None:
if envelope is not None and not envelope.succeeded:
provider_error = envelope_provider_error(envelope)
if response_file_text is not None:
return response_file_text, "response_file", provider_error, None
text, source = _strip_public_response_marker(envelope.response)
return text, source, provider_error
text, source = _strip_public_response_marker(stdout)
return text, source, provider_error
return text, source, provider_error, None
if envelope is not None and envelope.structured_output is not None:
log(
config,
"Antigravity envelope carried structured_output; ignored (never the answer source)",
)
if response_file_text is not None:
return response_file_text, "response_file", None, None
if envelope is None:
text, source = _strip_public_response_marker(stdout)
return text, source, None, None
recovery = recover_response_payload(envelope.response, kind)
if isinstance(recovery, AmbiguousPayload):
diagnostic = recovery.diagnostic
log(config, f"{diagnostic}; recording a format failure")
return "", "stdout", None, diagnostic
if isinstance(recovery, RecoveredPayload):
rendered = render_structured_output_text(recovery.payload, kind, signature)
if rendered is not None:
return rendered, "structured_output", None, None
log(
config,
"Antigravity response object could not be rendered (missing state); "
"falling back to the marker text",
)
text, source = _strip_public_response_marker(envelope.response)
return text, source, None, None


def _parse_model_catalog(raw: str) -> set[str]:
Expand Down Expand Up @@ -1628,7 +1648,6 @@ def run(
or not antigravity_structured_output_supported(runner, config)
):
structured_kind = None
schema_path: Path | None = None
args = [
config.antigravity_cmd,
"--model",
Expand All @@ -1645,10 +1664,9 @@ def run(
if session_id:
args += ["--conversation", session_id]
if structured_kind is not None:
# The schema sits beside the private response file, outside the
# checkout, and is removed after the turn.
schema_path = write_structured_output_schema(response_path.parent, structured_kind)
args += ["--output-format", "json", "--json-schema", str(schema_path)]
# JSON envelope only: no request schema, because agy's
# structured_output keeps only declared schema keys (#2049).
args += ["--output-format", "json"]
# The prompt is the value of --print (must be last), not a positional.
args += [
"--print",
Expand Down Expand Up @@ -1925,8 +1943,6 @@ def strip_injected_prefix() -> None:
log(config, f"{seat_label} could not remove its shared agy settings lock holder record: {exc}")
fcntl.flock(settings_lock, fcntl.LOCK_UN)
settings_lock.close()
if schema_path is not None:
schema_path.unlink(missing_ok=True)
log(config, f"Antigravity ({model}) finished; log: {log_path}")

# Prefer the public response file the prompt asks the agent to write; else
Expand All @@ -1940,8 +1956,14 @@ def strip_injected_prefix() -> None:
response_path.unlink(missing_ok=True)
response_file_text = None
provider_error_text: str | None = None
structured_ambiguity: str | None = None
if structured_kind is not None:
message_text, text_source, provider_error_text = _select_structured_turn_text(
(
message_text,
text_source,
provider_error_text,
structured_ambiguity,
) = _select_structured_turn_text(
config,
result.stdout,
response_file_text,
Expand Down Expand Up @@ -1997,6 +2019,7 @@ def strip_injected_prefix() -> None:
antigravity_log_path=agy_log_path,
antigravity_log_quota_evidence=agy_log_evidence,
antigravity_structured_request_rejection=request_rejection,
antigravity_structured_ambiguity=structured_ambiguity,
)

@staticmethod
Expand Down
Loading