@pymodel/antigravity-mcp 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,226 @@
1
+ ---
2
+ name: antigravity-mcp
3
+ description: >-
4
+ Delegate implementation or a queue of coding tasks through Antigravity MCP or its bundled CLI
5
+ relay, then review the diff and project gates. Use when the user asks Antigravity or agy to
6
+ implement, fix, refactor, or run tasks while the calling agent keeps the reviewer and commit role.
7
+ Handle small inline edits directly.
8
+ license: MIT
9
+ compatibility: >-
10
+ Primary path requires the `antigravity-mcp` MCP server registered with the host, plus the
11
+ `agy` CLI installed and authenticated, and git. Local stdio hosts include Pi >=0.99 with built-in
12
+ MCP, OpenCode, Codex, and Claude Code. Hosts without MCP fall back to the bundled
13
+ `scripts/relay.mjs`, which requires Node.js, git, and a supported authenticated AGY environment.
14
+ The MCP package supports macOS and Linux; use WSL only where the required Linux CLI is available.
15
+ metadata:
16
+ version: 0.9.1
17
+ ---
18
+
19
+ # Antigravity MCP
20
+
21
+ You are the **orchestrator**. This skill lets you hand a bounded coding task to a separate
22
+ **implementer** - the Google Antigravity CLI (`agy`) - then review what it produced and land it
23
+ yourself. You write the brief and own the judgment; Antigravity does the typing in its own
24
+ conversation; you verify and commit.
25
+
26
+ Choose the available dispatch path, then apply the review loop below:
27
+
28
+ - **MCP (preferred)** - Antigravity MCP exposes `delegate`, `follow_up`,
29
+ `adversarial_review`, `delegate_many` and friends as tools. Use this whenever the tools are
30
+ available.
31
+ - **CLI relay (fallback)** - `scripts/relay.mjs` wraps `agy --print` and writes a `result.json`. Use
32
+ it when the MCP server is not registered, so an orchestrator that can only run a shell command and
33
+ read a file can still drive the loop.
34
+
35
+ ## When NOT to use this
36
+
37
+ - The task is small enough to just do inline - delegation overhead is not worth it.
38
+ - Neither the MCP server nor the `agy` CLI is available and authenticated.
39
+ - You want to write the code yourself, or you only need Antigravity's opinion on code you wrote - a
40
+ read-only `delegate` or `adversarial_review` covers that, but a plain review may not need
41
+ delegation at all.
42
+
43
+ ## Prerequisites (check once)
44
+
45
+ 1. **Discover the tools through the host.** Locate `delegate`, `follow_up`,
46
+ `adversarial_review`, `delegate_many`, `agy_status`, and `set_model`. Use the host's
47
+ exposed names: prefixes follow its registration, and there is no shared discovery API.
48
+ If the host defers tools, load the needed tools together through its discovery mechanism.
49
+ The examples below use logical names; map them to the discovered tools before calling.
50
+
51
+ 2. **Call `agy_status`.** This sends no model prompt; metadata probes may invoke the CLI. It reports the agy
52
+ version, the models on offer, the resolved model chain per tool, quota cooldowns, in-flight runs,
53
+ and whether a `set_model` choice has already been recorded.
54
+
55
+ 3. **Settle the model once, if `agy_status` shows no choice recorded.** With the default
56
+ `AGY_ASK_MODEL=true`, a host that supports form elicitation can show the choice before the
57
+ first delegation. Other hosts receive an actionable error asking for `set_model`; no task
58
+ is dispatched until the choice is settled. Record a choice the user already authorized
59
+ without asking again. Otherwise use the form or ask once, then call `set_model`. The choice
60
+ is saved per machine. An explicit per-call `model` selects that call's model without this gate;
61
+ `AGY_ASK_MODEL=false` skips the gate but still honors an existing saved preference.
62
+
63
+ 4. **Know the working root.** Pass it as `cwd` on every call; add sibling repos or a base worktree
64
+ through `dirs`.
65
+
66
+ Inspect each tool's configured chain in `agy_status`; family selectors stay within that family.
67
+ Resolve choices against the current account's inventory. Exact IDs and labels fix their listed
68
+ effort. Selectors may choose an advertised effort sibling. The vocabulary is `low`, `medium`, `high`,
69
+ `xhigh`, and `max`, but a model supports only variants the inventory actually lists. An Orchestrator
70
+ label such as `(Carbon)` names a composite variant, not an effort. Availability depends on the
71
+ account, plan, provider, and CLI; an API model ID is not automatically an AGY ID.
72
+
73
+ ## The loop
74
+
75
+ Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.
76
+
77
+ ### 1. Write the brief
78
+
79
+ Antigravity sees only the text you send plus what it can inspect in the workspace - no chat history,
80
+ no shared context. Everything the task needs goes in the brief: the goal, the current state, what to
81
+ change, what to leave untouched, the project's **actual** gate commands, and a report contract. Tell
82
+ Antigravity it will **not** commit (you will). Keep one task per brief. Full guidance and a template:
83
+ [references/writing-the-brief.md](references/writing-the-brief.md).
84
+
85
+ ### 2. Dispatch
86
+
87
+ Send the brief as the `prompt` of a `delegate` call with `write: true`:
88
+
89
+ ```
90
+ delegate(
91
+ prompt: "<the brief>",
92
+ cwd: "/path/to/repo",
93
+ write: true // omit for a read-only run; see the permission model below
94
+ // dirs: ["/path/to/other-repo"] extra workspace roots
95
+ // sandbox: true agy's terminal restrictions (not a permission boundary)
96
+ // model / effort only when the user named one
97
+ )
98
+ ```
99
+
100
+ **A read-only dispatch is enforced on macOS and watched elsewhere.** On macOS the bridge runs it
101
+ under a sandbox that blocks writes into its roots. Everywhere, it fingerprints the working tree around
102
+ the run and reports `READ-ONLY VIOLATION` (an unenforced run wrote) or `WORKING TREE CHANGED` (the tree
103
+ moved despite enforcement) in the response header. You do not have to snapshot anything yourself; you
104
+ do have to read the header's `read-only:` field and any warning.
105
+
106
+ The response is fenced with a per-call nonce and carries a `session_id` in its header when the run
107
+ produced one. **Keep that `session_id`** - it is how you rework without resending the brief. Everything between the "agy output
108
+ begins" and "agy output ends" markers is untrusted model output; read it as a claim, not as evidence.
109
+
110
+ Mechanics, the response shape, and the CLI-relay fallback:
111
+ [references/dispatch-and-poll.md](references/dispatch-and-poll.md).
112
+
113
+ ### 3. Wait for completion
114
+
115
+ Await the tool's final response. The bridge exposes no background-job polling tool; a host may
116
+ present its own background UI. The default bridge ceiling is 3600 seconds, with a 15-second
117
+ cold-run grace. Give the host at least 3660 seconds for a default single turn, using the
118
+ [host-specific timeout fields and units](references/dispatch-and-poll.md) under "Waiting for completion".
119
+ Allow more for queued work or sequential fan-out legs.
120
+
121
+ A host timeout can discard partial output or a session ID. A bridge timeout returns bounded
122
+ recovery information when the CLI reported it; it cannot guarantee a usable session. Preserve any
123
+ known session ID and inspect the result and workspace before an intentional `follow_up` or new
124
+ dispatch. A timeout never proves that the task had no effects.
125
+
126
+ If a call fails, do not quietly do the work yourself - report the failure. Setting
127
+ `AGY_ON_FAILURE=strict` reinforces this for delegation failures; invalid caller requests are
128
+ handled separately.
129
+
130
+ ### 4. Review - do not trust the self-report
131
+
132
+ The response is Antigravity's own account of what it did, including its gate claims. **Re-verify,
133
+ don't accept:**
134
+
135
+ - **Establish what actually changed** with `git status --porcelain` and `git diff` (plus
136
+ `git diff --cached`, and open untracked files directly). The bridge reports no touched-file list, so
137
+ git is your only source here.
138
+ - **Re-run the project's gates yourself** - the test/lint/build commands from step 1.
139
+ - **Read the diff against the brief:** did Antigravity do what was asked, nothing more and nothing less?
140
+ - **Get a second opinion:** pass the diff to `adversarial_review` with a `focus` when one applies.
141
+ Check its resolved model in `agy_status`; choose a different listed family when independence
142
+ matters. Its answer supplements your own review.
143
+ - **Run the relevant guard skills** on the diff if you have them installed.
144
+ - For schema/migration changes, round-trip them; for removals, grep for dangling references.
145
+
146
+ Full checklist: [references/review-and-land.md](references/review-and-land.md).
147
+
148
+ ### 5. Land it
149
+
150
+ The implementer edits the working tree; **the orchestrator commits.** Only after the gates pass and the
151
+ diff holds:
152
+
153
+ - Commit the verified work yourself, with a clear message.
154
+ - If it needs changes, send a delta with `follow_up(session_id, question, write: true)` and review
155
+ again. The prior context is already on agy's side, so send only the correction. Pass `write: true`
156
+ whenever the rework has to touch files, exactly as you would on the original dispatch.
157
+
158
+ ## Permission model
159
+
160
+ Headless `agy --print` cannot answer an interactive permission prompt. Earlier AGY 1.2.x checks
161
+ observed denied permissioned tools, including file reads, when the permission bypass was off.
162
+ Current behavior depends on the installed CLI and its permission configuration; inspect denied
163
+ actions and completion metadata. The bridge passes `--dangerously-skip-permissions` by default
164
+ (`AGY_SKIP_PERMISSIONS=true`). Treat the delegated task as authorized shell access.
165
+
166
+ What that means in practice, and what the bridge does about it:
167
+
168
+ - **agy's plan mode is advisory.** Read-only tools pass `--mode plan`, but verified against agy 1.2.1
169
+ and again against 1.2.2: a plan-mode run creates files, with the permission bypass on or off.
170
+ - **So on macOS the bridge enforces read-only.** Plan-mode runs execute under `sandbox-exec` with every
171
+ write beneath the call's roots denied for agy and its child processes; the header says
172
+ `read-only: enforced`. Where the sandbox cannot run (Linux, or a sandboxed bridge) the header says
173
+ `read-only: watched, not enforced`, and `AGY_READ_ONLY_ENFORCEMENT=require` refuses the run instead.
174
+ The block covers only the roots: agy can still write elsewhere, and a process it launches through
175
+ an app or launchd escapes it.
176
+ - **The bridge watches in both modes.** It fingerprints the working tree around every plan-mode run
177
+ and warns `READ-ONLY VIOLATION` or, under enforcement, `WORKING TREE CHANGED` when the tree moved.
178
+ Absence of a warning is only a bounded snapshot observation; it does not prove the run had no
179
+ effects. A run it could not fingerprint makes no clean-tree claim. Files git ignores are covered by size and mtime only,
180
+ dependency and build trees such as `node_modules` as one entry, and any other writer during the
181
+ run moves it too.
182
+ - **A dispatched turn is not automatically repeated by the bridge.** A network error, quota error,
183
+ partial output, or cancellation can follow local or external side effects. Inspect the available
184
+ result and workspace before an intentional continuation. An unchanged fingerprint cannot prove
185
+ that nothing happened. Native CLI retries remain the CLI's responsibility.
186
+ - **The denied-actions note only appears when the grant is off.** With the default grant you will not
187
+ see one, so its absence proves nothing. The violation warning is the signal to trust.
188
+ - **A restriction that cannot be enforced fails the call.** If the installed agy does not support
189
+ `--mode` or `--sandbox`, a run that needs either is refused rather than run with more authority than
190
+ you asked for.
191
+ - **`AGY_ALLOWED_ROOTS` validates inputs; it does not sandbox agy.** It checks every call's `cwd`,
192
+ `dirs` and `files`, including the workspace roots the bridge derives from them, so a caller cannot
193
+ point a delegation outside the roots you nominate. It does **not** confine the run: agy has a shell
194
+ under the bypass and can reach anything the user running it can. It is also a server-level
195
+ environment variable in the MCP registration, not a per-call argument.
196
+
197
+ **The only containment is the read-only block on a macOS plan-mode run's own roots.** A `write: true`
198
+ dispatch is not sandboxed at all. Treat a dispatch as running with your own shell access. If a task genuinely must not touch the rest of the disk, say so and have the human
199
+ arrange isolation outside the bridge - a container, a throwaway checkout, or a restricted account.
200
+
201
+ **The raw relay has its own contract.** It provides no read-only enforcement on any platform.
202
+ `--read-only` requests advisory plan mode and compares bounded content snapshots of the supplied
203
+ roots. A violation exits nonzero; unreadable or incomplete snapshot coverage is reported as
204
+ `incomplete`, not clean. Read the relay's structured result and coverage fields. A raw relay test
205
+ does not validate the MCP bridge's confinement, routing, quotas, or retry behavior.
206
+
207
+ ## Authorization model
208
+
209
+ Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing
210
+ verified, gate-passing work is the agreed contract. Two limits on that mandate: **surface, don't
211
+ absorb** (report Antigravity's design decisions, defensible-but-unasked turns, and non-blocking
212
+ nitpicks rather than silently keeping them) and **stop for scope changes** (if correct completion needs
213
+ going beyond the brief, ask - don't expand the mandate yourself). The full treatment is in
214
+ [references/review-and-land.md](references/review-and-land.md).
215
+
216
+ ## References
217
+
218
+ - [references/writing-the-brief.md](references/writing-the-brief.md) - how to write a brief Antigravity
219
+ can execute blind: structure, XML blocks, the report contract, and real gate commands.
220
+ - [references/dispatch-and-poll.md](references/dispatch-and-poll.md) - the `delegate` / `follow_up`
221
+ call shapes, the fenced response contract, failure and quota handling, and the `relay.mjs` fallback.
222
+ - [references/review-and-land.md](references/review-and-land.md) - the review checklist, the commit
223
+ boundary, and the rework cycle via `follow_up`.
224
+ - [references/multi-task-queues.md](references/multi-task-queues.md) - running a sequential queue:
225
+ carrying constraints forward, when `delegate_many` applies, progress tracking, and the end-of-run
226
+ coherence check.
@@ -0,0 +1,229 @@
1
+ # Dispatch and poll
2
+
3
+ The dispatch layer is Antigravity MCP: it spawns `agy --print`, watches the run, and
4
+ returns a fenced answer. Your job collapses to one tool call and one read of the working tree. The
5
+ bundled `scripts/relay.mjs` remains as a fallback for orchestrators that have no MCP.
6
+
7
+ - [Before the first run](#before-the-first-run)
8
+ - [Dispatching](#dispatching)
9
+ - [The response](#the-response)
10
+ - [Waiting for completion](#waiting-for-completion)
11
+ - [When a run misbehaves](#when-a-run-misbehaves)
12
+ - [Fallback: the CLI relay](#fallback-the-cli-relay)
13
+ - [The commit boundary](#the-commit-boundary)
14
+
15
+ ## Before the first run
16
+
17
+ Call `agy_status`. It sends no model prompt; metadata probes may invoke the CLI. Inspect:
18
+
19
+ - the agy version and whether every flag the bridge uses is supported,
20
+ - the models agy currently offers,
21
+ - the resolved model chain for each tool,
22
+ - whether a `set_model` choice is recorded (record an already authorized choice; otherwise ask
23
+ once before selecting it, as described in SKILL.md),
24
+ - live quota cooldowns, runs in flight, tokens spent, warm sessions.
25
+
26
+ None of this proves a write will succeed, only that the bridge and CLI are healthy.
27
+
28
+ ## Dispatching
29
+
30
+ Use the tool names exposed by the host. These examples name the logical tools; the host may
31
+ prefix them with its local server registration name.
32
+
33
+ ```
34
+ delegate(prompt: "<the brief>", cwd: "/path/to/repo", write: true)
35
+ ```
36
+
37
+ Arguments that matter:
38
+
39
+ | Argument | Effect |
40
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
41
+ | `prompt` | The complete brief. Required. |
42
+ | `cwd` | Absolute path to the working root. Defaults to the server's cwd - always pass it explicitly. |
43
+ | `write` | **Off by default.** `true` adds `--mode accept-edits` and lets agy edit files and run commands. An implementation dispatch needs it. |
44
+ | `dirs` | Extra workspace roots, for cross-repo work or worktree-vs-base comparison. |
45
+ | `sandbox` | Enables agy's terminal restrictions. Not a permission boundary. |
46
+ | `model` | An exact ID/label from the current inventory, or a configured family selector such as `gemini-neon@latest`. Exact variants remain fixed; an unavailable choice fails. |
47
+ | `effort` | `low` / `medium` / `high` / `xhigh` / `max`, limited to the chosen model's advertised variants. Selectors can select a listed sibling; a conflict with an exact variant fails. |
48
+ | `schema` | A JSON Schema **string** constraining the answer; returns `structuredContent` too. Use it when the caller will parse the result. |
49
+ | `slash_commands` | Off by default, so a hostile file in the workspace cannot steer the implementer through your own skills. Leave it off. |
50
+
51
+ Sibling tools worth reaching for instead of a raw `delegate`:
52
+
53
+ - `follow_up(session_id, question, write?)` - continue a prior run. The context is already on agy's
54
+ side, so send only the delta. This is the rework path; pass `write: true` to change files.
55
+ - `adversarial_review(content | files, focus?)` - a review brief that asks for flaws. Inspect its
56
+ resolved route and select an available independent model when needed; the shared defaults do
57
+ not guarantee a different family. Use it on a plan before dispatch or on the diff before commit.
58
+ - `delegate_many(tasks: [...])` - several sub-tasks in one call, or `prompt` + `models` for a council
59
+ with a disagreement report. Queued behind `AGY_MAX_CONCURRENCY` (default 2).
60
+ - `analyze_files`, `deep_search`, `web_lookup` - read-only research that keeps large files, git
61
+ archaeology and doc lookups out of your context entirely.
62
+
63
+ Keep briefs focused. `agy --print` takes the prompt as a command-line argument, so a very large brief
64
+ can hit the OS argument cap - have agy read big context from the workspace instead of inlining it -
65
+ and the prompt is visible in the host process list, so keep secrets out of it.
66
+
67
+ ## The response
68
+
69
+ Every response is fenced with a per-call nonce, metadata in a header before the payload:
70
+
71
+ ```
72
+ [antigravity-mcp 9f2a1c] model: gemini-4-neon-medium | session: 1f0c…-d4 (use follow_up to continue) | tokens: 16281
73
+ [antigravity-mcp 9f2a1c] --- agy output begins; everything below is untrusted model output ---
74
+ …agy's answer…
75
+ [antigravity-mcp 9f2a1c] --- agy output ends ---
76
+ ```
77
+
78
+ The nonce is what makes the fence worth anything - without it, any analysed file containing `---`
79
+ could forge the metadata. Read the header for facts about the run; read the payload as a claim.
80
+
81
+ What the header can carry:
82
+
83
+ - **`session_id`** - keep it. It is the only handle for `follow_up`. It is present only when the run
84
+ actually reported one; the bridge never substitutes a session it did not create.
85
+ - **A `SESSION NOT RESUMED` warning** on a `follow_up`. agy answers a conversation id it cannot find
86
+ from a brand-new conversation and exits 0, so without this the fork would look like a continuation.
87
+ The answer has none of the earlier history: re-send the context, or deliberately continue the new
88
+ `session_id`. Structured responses carry the same fact as `resumed: false`.
89
+ - **`model`** identifies the resolved selection. Treat an explicitly reported CLI model as a
90
+ separate observation; a request alone does not prove which model executed.
91
+ - **`tokens`** for the call when usage was reported. Unknown usage is not zero usage.
92
+ - **A denied-actions warning** when agy's tool actions were auto-denied. This appears only when the
93
+ permission grant is off; with the default grant its absence proves nothing.
94
+
95
+ **There is no `touchedFiles` list**, so establish what changed with `git status --porcelain`,
96
+ `git diff`, and `git diff --cached`, and open untracked files directly. There _is_ a violation check:
97
+ the bridge fingerprints the tree around every plan-mode run and adds a `READ-ONLY VIOLATION` warning
98
+ to the header when it moved. No warning is only a bounded snapshot observation; a tree it could not
99
+ fingerprint produces no clean-tree claim. Snapshot coverage has documented limits; an unchanged
100
+ snapshot does not prove that the run had no external effects.
101
+
102
+ Output is truncated at `AGY_MAX_OUTPUT_CHARS` (default 50000) to protect your context.
103
+
104
+ ## Waiting for completion
105
+
106
+ Await the final tool response, even if the host presents a background UI. The bridge exposes no
107
+ background-job polling API. Verify the working tree and project gates before treating the task as
108
+ finished.
109
+
110
+ Two independent timers matter. The bridge defaults to `AGY_MAX_RUNTIME=3600` **seconds**, with a
111
+ 15-second cold-run grace before its kill deadline. `AGY_TIMEOUT` overrides the common runtime;
112
+ `AGY_TIMEOUT_<TOOL>` overrides one tool, such as `AGY_TIMEOUT_DELEGATE`. Configure the host's
113
+ execution timeout to allow that runtime plus cleanup and result delivery:
114
+
115
+ | Local stdio host | Execution timeout field | Recommended value for a default single turn | Unit |
116
+ | ------------------------------ | ------------------------------------------ | ------------------------------------------: | ------------------------------------------ |
117
+ | Pi 0.99 or later, built-in MCP | `timeout` | `3660` | Seconds; progress resets its request timer |
118
+ | OpenCode V2 | `timeout.execution` | `3660000` | Milliseconds |
119
+ | Codex | `tool_timeout_sec` | `3660` | Seconds |
120
+ | Claude Code | Per-server `timeout` or `MCP_TOOL_TIMEOUT` | `3660000` | Milliseconds |
121
+
122
+ These fields are host-specific; a server startup timeout is a separate setting. Increase the
123
+ execution allowance for larger bridge limits, queued work, or sequential fan-out legs. The extra
124
+ minute leaves room for the default grace and response delivery; it is not a completion guarantee.
125
+ For registration examples and the checked client documentation, read the
126
+ [client guide](https://github.com/PyModel/antigravity-mcp/blob/main/docs/multi-client-support.md#timeout-settings).
127
+
128
+ A host timeout may discard the bridge's partial result and session ID. A bridge timeout reports
129
+ `MAXIMUM RUNTIME EXCEEDED` and preserves bounded partial output and the session ID when available.
130
+ Neither outcome proves that no files or remote state changed. Keep any session ID already known,
131
+ reconcile observed effects, and continue deliberately instead of resending the original task.
132
+
133
+ The bridge does not kill a run because an intermediate log reports a quota retry. Cancellation,
134
+ the runtime ceiling, a raw-output limit, or bridge shutdown can end the owned run. Cancelling from
135
+ the client terminates the owned process group; inspect the partial response and workspace.
136
+
137
+ ## When a run misbehaves
138
+
139
+ - **Quota exhausted:** inspect the recorded cooldown in `agy_status` and any partial response.
140
+ The bridge can skip a known cooled model before a new request, but it does not replay a turn
141
+ that was already dispatched. Continue deliberately after checking possible effects.
142
+ - **Network or transport error:** native CLI retries remain the CLI's responsibility. The bridge
143
+ preserves partial/session metadata and does not resend the whole prompt after delivery.
144
+ - **Model or auth failure:** correct the model selection or authenticate `agy`. If a turn was
145
+ dispatched, first inspect partial output, the session ID, and possible effects; choose an
146
+ intentional continuation or new dispatch after reconciling them.
147
+ - **Ceiling fired:** inspect partial output and the working tree before resuming. Use `follow_up`
148
+ only when a known session ID is available, and verify continuity in its response.
149
+ - **Host timeout:** inspect any available partial result, prior session ID, and local or remote
150
+ effects. Correct the host's execution timeout, then choose a continuation or new dispatch based
151
+ on the reconciled state; the timeout alone does not authorize repeating the task.
152
+ - **Empty or unhelpful answer with edits present:** the run may still be correct. Check the diff. To
153
+ get a report next time, add a `<structured_output_contract>` block (see
154
+ [writing-the-brief.md](writing-the-brief.md)).
155
+ - **Any failure:** do not silently absorb the work yourself. Report it. `AGY_ON_FAILURE=strict` makes
156
+ the bridge reinforce this for delegation failures; invalid caller requests are handled separately.
157
+ - **Delegation depth:** `AGY_MAX_DELEGATION_DEPTH` (default 1) refuses a call once you are already
158
+ inside a delegated run, so host → agy → Antigravity MCP → agy cannot loop.
159
+
160
+ ## Fallback: the CLI relay
161
+
162
+ When the MCP tools are not available, `scripts/relay.mjs` drives the same loop over the CLI. It wraps
163
+ `agy --print`, captures the run, and writes a structured `result.json`, so the requirement drops to
164
+ "run a command, read a file."
165
+
166
+ ```bash
167
+ node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
168
+ # model label: --model "<label from agy models>"
169
+ # reasoning effort: --effort high
170
+ # advisory plan mode and snapshots: --read-only
171
+ # agy terminal sandbox: --sandbox
172
+ # resume the last conversation: --resume-last (delta brief only)
173
+ # all options: node .../relay.mjs --help
174
+ ```
175
+
176
+ It starts a fresh Antigravity project by default, passes `--add-dir <repo>` for an explicit workspace,
177
+ and passes `--dangerously-skip-permissions` by default (`--no-dangerously-skip-permissions` turns that
178
+ off, at the cost of auto-denied tools). This raw CLI path does not use the MCP bridge's macOS
179
+ confinement, cooldown registry, warm sessions, or budget accounting. It does not retry a prompt.
180
+
181
+ For a pinned model, it reads `agy models` and dispatches the canonical listed CLI ID. Exact IDs or
182
+ labels preserve their effort; a conflicting `--effort` fails before dispatch. A family selector
183
+ such as `--model gemini-neon@latest --effort xhigh` can choose a listed sibling. `max` is accepted
184
+ only if that account actually lists a matching variant. Effort without a known model fails.
185
+ Without `--model`, the CLI's inherited selection remains unknown until the CLI reports it.
186
+
187
+ `<out-dir>/result.json` uses `delegate-relay.result.v2`. Read these fields:
188
+
189
+ - `runId`, `status` - `running` | `completed` | `incomplete` | `read_only_violation` | `failed` |
190
+ `timeout` | `aborted` | `agy_unavailable`. Wait for a terminal status belonging to the new run.
191
+ - `finalMessage` - the response from the CLI's structured envelope, treated as the implementer's
192
+ report. `stdoutPath` preserves the raw envelope and diagnostics.
193
+ - `cliStatus`, `finishedReason`, `deniedActions`, `childExitCode` - independent completion evidence.
194
+ A print timeout, interruption, denial, missing envelope, empty report, or unverified requested
195
+ continuation cannot become a completed task merely because the process exited zero.
196
+ - `requestedModel` / `requestedEffort`, `resolvedModel` / `resolvedEffort`, `observedModel` - requested
197
+ policy, selected listed variant, and CLI-reported model respectively. Unknown values stay `null`.
198
+ - `touchedFilesByRoot` - current Git status for every watched root, including ignored entries;
199
+ `files: null` when Git cannot report. This includes pre-existing changes. `touchedFiles` is a
200
+ compatibility view of the first root's status, not a complete cross-root change list.
201
+ - `readOnlyViolation` - `true` when fingerprints prove a working-tree change on a `--read-only` run,
202
+ `false` when the bounded snapshots match, `null` when the comparison is unknown or was not
203
+ requested. `readOnlyEnforced` is always `false` for the relay.
204
+ - `snapshotCoverage` - watched roots and any coverage errors. The relay expands a nested `--cd`
205
+ to its Git root and includes every `--add-dir`. It hashes ignored files and dependency contents,
206
+ up to 20,000 entries, 128 MiB, and a 10-second snapshot budget. Unreadable or oversized trees,
207
+ unsupported entries, and symlinks outside the roots yield unknown coverage. Relay artifacts and
208
+ Git administrative files are excluded; Git HEAD and index are included. Matching snapshots
209
+ cannot detect transient writes reverted before the second snapshot or external effects.
210
+ - `conversationId` / `projectId`, `exitCode`, `signal`, `agyVersion`, `error`, `stderrTail`, and the
211
+ `briefPath` / `finalPath` / `logPath` / `stderrPath` captures
212
+ - `resumeRequested` and `resumed` - an explicit conversation is confirmed only when its reported ID
213
+ matches. `--resume-last` remains unverified because the requested ID was not known beforehand.
214
+
215
+ The relay blocks until agy finishes, so background it if your orchestrator supports that and read
216
+ the new run's terminal result. Reusing `--out-dir` replaces the previous completion with a fresh
217
+ `running` record and clears prior captures. An exclusive directory lock refuses concurrent reuse.
218
+ Exit code 2 is a pre-run usage error; 127 with `status: agy_unavailable` means `agy` is not on PATH.
219
+ A read-only violation or unknown read-only coverage exits nonzero. On abort or watchdog expiry,
220
+ the relay terminates the owned process group, including descendants that ignored SIGTERM.
221
+
222
+ Review `touchedFilesByRoot`, Git diffs, untracked files, and relevant ignored files yourself. The
223
+ relay's status describes transport and observation; passing project gates and satisfying the brief
224
+ remain the orchestrator's review responsibilities.
225
+
226
+ ## The commit boundary
227
+
228
+ Neither path commits - by design, not omission. Antigravity edits the working tree, the orchestrator
229
+ reviews and commits. See [review-and-land.md](review-and-land.md).
@@ -0,0 +1,77 @@
1
+ # Multi-task queues
2
+
3
+ The single-task loop scales to a queue, and that is where delegation pays off most - a removal split
4
+ across layers, a migration touching many files, a refactor sweep. The discipline that makes a queue
5
+ trustworthy is sequencing and bookkeeping, not parallelism.
6
+
7
+ ## Run sequentially, one commit per task
8
+
9
+ Run tasks **one at a time, in dependency order**, landing each (review + gates + commit) before
10
+ dispatching the next. Three reasons:
11
+
12
+ - **Later tasks assume earlier ones landed.** Task 3's brief can say "the X added in the previous step
13
+ exists" only if the previous step actually committed.
14
+ - **One commit per task** keeps the history reviewable and any single step revertible.
15
+ - **Each review is honest.** A clean working tree before each dispatch means the next task's
16
+ `git status` shows only _its_ changes.
17
+
18
+ Parallelism is occasionally worth it for genuinely independent tasks on separate files, but it
19
+ sacrifices the clean-tree-per-task property and makes review harder. Default to sequential.
20
+
21
+ ## `delegate_many` is for research, not for a write queue
22
+
23
+ `delegate_many(tasks: [...])` fans several prompts out at once, queued behind `AGY_MAX_CONCURRENCY`
24
+ (default 2). That is the right tool for independent **read-only** work - surveying several modules,
25
+ gathering facts for a plan, or `prompt` + `models` for a council with a disagreement report on one
26
+ design question.
27
+
28
+ It is the wrong tool for an implementation queue. It exposes no `write` flag, and concurrent writers
29
+ in one tree destroy the clean-tree-per-task property that makes each review honest. Land write tasks
30
+ one `delegate(write: true)` at a time.
31
+
32
+ ## Carry decided constraints forward
33
+
34
+ Implementation surfaces facts the original plan did not have: a helper got named, a fixture lives in a
35
+ specific place, an interface was chosen. When a later task depends on one of those, fold it into that
36
+ task's brief as an explicit line. A fresh Antigravity conversation has no memory of the earlier run, so
37
+ a constraint that emerged in task 2 must be restated in task 5's brief or it will not hold. The one
38
+ exception is a `follow_up` on the same `session_id`, which keeps that run's context - but that is a
39
+ rework of one task, not the next task in the queue.
40
+
41
+ Check `agy_status` before a long queue. It shows recorded quota cooldowns and reported usage.
42
+ Known cooldowns may affect model selection for the next independent request; a failed turn is not
43
+ automatically replayed, and missing usage is not evidence that the turn was free.
44
+
45
+ ## Keep a progress file
46
+
47
+ For anything longer than two or three tasks - especially a run the human steps away from - maintain a
48
+ single progress file alongside the work:
49
+
50
+ - **Status table** - each task: queued / at-implementer / reviewed+committed (with the commit hash
51
+ and the agy `session_id`, so a late rework can still resume the right conversation).
52
+ - **Per-task review notes** - what landed, what you verified, the gate outcome.
53
+ - **Needs your eyes** - design decisions Antigravity made, non-blocking nitpicks, anything you want the
54
+ human to overrule or confirm.
55
+ - **End-of-run checklist** - what happens after the last task.
56
+
57
+ Update it as each task lands, not in a batch at the end.
58
+
59
+ ## Close with a coherence check
60
+
61
+ Per-task review proves each step in isolation; it does not prove the steps cohere. After the last task,
62
+ verify the whole:
63
+
64
+ - Run the full test/build once more on the final tree.
65
+ - Do a repo-wide check for the thing the queue was about.
66
+ - For schema work, replay all the new migrations from a clean state and check for drift.
67
+ - Then push and open or update the PR, with a description that reflects what actually shipped.
68
+
69
+ ## When to stop and ask
70
+
71
+ Proceed without asking on anything that follows from the agreed plan. Stop and surface when:
72
+
73
+ - A task cannot be completed correctly within its brief's scope.
74
+ - A review finds something that calls the _plan_ into question, not just the implementation.
75
+ - The gates reveal a problem that affects tasks already done.
76
+
77
+ Then report where you are, what is committed, and what the open question is - and wait.