@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,154 @@
1
+ # Review and land
2
+
3
+ Antigravity did the typing; you own the judgment. Verify against reality, never against the self-report
4
+
5
+ - and read the diff as generated code, which fails in ways a green gate cannot see.
6
+
7
+ ## Check the tests before trusting the gates
8
+
9
+ If the diff touches existing tests, review those edits _first_ - before the gate re-run means anything.
10
+ A weakened assertion, an added skip, or a deleted test makes the gate measure less than it did before
11
+ the run.
12
+
13
+ - **Unbriefed edits to existing tests are a contract change, not part of the fix.** Flag them, don't
14
+ absorb them.
15
+ - **Skipped, disabled, or commented-out tests added in this diff:** treat the underlying test as
16
+ failing until proven otherwise.
17
+ - **Loosened assertions** (exact match relaxed to contains/truthy, error-type checks broadened,
18
+ tolerance widened): same treatment.
19
+
20
+ ## Establish what actually changed
21
+
22
+ The dispatch returns Antigravity's own account and nothing else - no touched-file list. Git is your
23
+ only source of truth about the tree:
24
+
25
+ ```bash
26
+ git status --porcelain # every change, including untracked files
27
+ git diff # unstaged edits
28
+ git diff --cached # anything the implementer staged; plain `git diff` is blind to the index
29
+ ```
30
+
31
+ Open untracked files (`??`) directly - no diff shows their contents. If the dispatch was read-only,
32
+ the bridge has already compared the tree for you: a `READ-ONLY VIOLATION` line in the response header
33
+ means the tree changed during the run. Inspect those changes; another concurrent writer may also
34
+ have contributed. Inspect relevant ignored files directly because normal Git status omits them.
35
+
36
+ ## Re-run the gates yourself
37
+
38
+ Antigravity's report carries its own gate claims. Treat them as claims, not evidence - re-run the
39
+ project's actual test/lint/build commands in the working tree and read the output. Passing is necessary,
40
+ not sufficient.
41
+
42
+ For changes with their own verification shape, go further:
43
+
44
+ - **Migrations / schema:** round-trip them and check for drift.
45
+ - **Removals / renames:** grep the codebase for dangling references.
46
+ - **Anything stateful:** exercise the actual behavior, don't just confirm it compiles.
47
+
48
+ ## Read the diff against the brief
49
+
50
+ Open the diff (the `git status` list above is your starting point) and hold it against what you asked
51
+ for:
52
+
53
+ - **Scope creep** - did Antigravity change things the brief said to leave untouched?
54
+ - **Scope shortfall** - did it do the whole task, including edge cases and cleanup?
55
+ - **Quiet judgment calls** - did it make a defensible but unasked decision you need to understand?
56
+
57
+ ## The implementer sweep
58
+
59
+ Generated code fails in systematic ways that gates are structurally blind to. Walk these against every
60
+ diff before you commit:
61
+
62
+ - **Hardcoded success or fixture data** on a path the brief says does real work.
63
+ - **Catch-all error handling that returns a default** instead of propagating or recovering explicitly.
64
+ - **Unverified imports and API calls** - confirm new dependencies, methods, and signatures exist in the
65
+ installed version.
66
+ - **Dead weight** - unused imports, helpers nothing calls, unreachable branches, scaffolding comments.
67
+ - **A second way to do what the file already does** - new client, error idiom, or logging style beside
68
+ an existing one.
69
+ - **New tests that assert internals** instead of behavior.
70
+ - **Near-duplicate test bodies** differing by one value.
71
+ - **Speculative surface** - optional parameters, config flags, or abstractions with no caller.
72
+ - **Guards for impossible cases** that bury validation that matters at real trust boundaries.
73
+
74
+ Anything the sweep catches goes back to Antigravity as a delta brief or gets fixed in the tree before
75
+ commit - and either way is reported to the user.
76
+
77
+ If the `guard-skills` package is installed, run the relevant guard on the diff for the full treatment.
78
+
79
+ ## Get an adversarial second opinion
80
+
81
+ `adversarial_review` asks another model for edge cases, security issues, and unstated assumptions.
82
+ Inspect its configured route in `agy_status`; select a different listed family when independence
83
+ from the implementer matters. Confirm the task fits the remaining quota or budget:
84
+
85
+ ```bash
86
+ git diff > /tmp/review.diff
87
+ ```
88
+
89
+ ```
90
+ adversarial_review(files: ["/tmp/review.diff"], focus: "concurrency", cwd: "/path/to/repo")
91
+ ```
92
+
93
+ Prefer `files` over inline `content` for a real diff: the prompt rides `agy --print` as a command-line
94
+ argument with a ~120KB cap, and a large diff will not fit. Inline `content` is fine for a snippet or a
95
+ plan. Pass a `schema` string when you want ranked findings back as data. Its output is untrusted model output like any other - triage the findings against the
96
+ code, do not forward them wholesale. It supplements your read of the diff; it does not replace it.
97
+
98
+ ## The commit boundary
99
+
100
+ When the gates pass and the diff holds, **you commit** - the orchestrator, never the implementer. Write
101
+ a clear message describing what landed. If your project attributes co-authorship, that is the place for
102
+ it.
103
+
104
+ From dispatch until that commit, the uncommitted working tree is the authoritative copy of the
105
+ implementer's work — the only one you can commit from, and often the only copy at all. Never run `git checkout`, `reset`, `clean`, or a branch switch in the
106
+ workspace between those two points — however messy an interrupted run looks, inspect it first:
107
+ `git status`, `git diff`, `git diff --cached` for anything the implementer staged (plain
108
+ `git diff` is blind to the index), and open any untracked files (`??` in `git status`) directly —
109
+ they are the implementer's new files, and no diff shows their contents. The tree is evidence,
110
+ not clutter. After that inspection the
111
+ verdict can legitimately be to discard — work built on a premise you have since corrected, for
112
+ example — and then `git checkout`/`clean` is the right tool. The ban is on reflexive cleanup
113
+ before anyone has looked.
114
+
115
+ ## Reworking: send the delta, not the whole task
116
+
117
+ If the review turns up problems, don't restate the entire brief. Continue the same Antigravity
118
+ conversation with just the correction:
119
+
120
+ ```
121
+ follow_up(
122
+ session_id: "<from the dispatch response header>",
123
+ question: "The fix is right, but the test mocks the DB session - use the real migrated fixture instead, and drop the now-unused import.",
124
+ cwd: "/path/to/repo",
125
+ write: true
126
+ )
127
+ ```
128
+
129
+ `follow_up` requests the same agy conversation. Check the returned session and any
130
+ `SESSION NOT RESUMED` warning before relying on its history. Keep the reported `session_id` and send
131
+ only a delta when continuity is confirmed. A resident process can be reused only when its model,
132
+ roots, permission settings, and sandbox requirements remain compatible with the call.
133
+
134
+ Pass `write: true` on the `follow_up` whenever the rework has to change files. A write follow-up
135
+ always runs as a fresh process rather than against the resident session, because a resident session
136
+ is started in plan mode and cannot honour it.
137
+
138
+ On the CLI fallback prefer `relay.mjs --conversation <reported-id>` so continuation can be checked.
139
+ `--resume-last` leaves the target ID unknown and its `resumed` result unverified.
140
+
141
+ Then review again - rework gets the same gate-rerun, test check, diff-read, and sweep as the original,
142
+ no shortcuts.
143
+
144
+ ## Surface, don't absorb
145
+
146
+ The human opted into delegation, so committing verified, gate-passing work is the agreed contract. But
147
+ keep them in the loop on anything that changes the shape of the work:
148
+
149
+ - **Report design decisions** Antigravity made, and any defensible-but-unrequested turns it took.
150
+ - **Note non-blocking nitpicks** you chose not to block on, so the human can overrule you.
151
+ - **Stop and ask** if correct completion requires going beyond the brief.
152
+
153
+ For a multi-task run, capture these in the progress file rather than letting them scroll past - see
154
+ [multi-task-queues.md](multi-task-queues.md).
@@ -0,0 +1,126 @@
1
+ # Writing the brief
2
+
3
+ A brief is the entire task as Antigravity will see it. It runs in a separate conversation with **no
4
+ memory of your conversation, no access to your prior notes, and no shared context** - only the text you
5
+ send and whatever it can inspect in the workspace. If a constraint is not in the brief or discoverable
6
+ in the repo, it does not exist for Antigravity.
7
+
8
+ ## Model choice
9
+
10
+ The bridge routes automatically: each tool leads with the user's recorded `set_model` choice and falls
11
+ back down a chain of family selectors on quota exhaustion. Pass `model` or `effort` on a call only when
12
+ the human named one for this task; `agy_status` lists the labels agy offers.
13
+
14
+ A `follow_up` keeps the conversation context. Send only the delta brief.
15
+
16
+ ## The shape that works
17
+
18
+ Antigravity responds well to compact, block-structured prompts with XML tags rather than long prose.
19
+ State the task, what "done" looks like, how to behave by default, and the few constraints that actually
20
+ matter. Add a block only when the task needs it.
21
+
22
+ ```xml
23
+ <task>
24
+ One or two sentences: the concrete job and where it lives. Then the specifics - current state, what to
25
+ change, and explicitly what to leave untouched. The "leave untouched" list is what keeps Antigravity
26
+ from wandering into unrelated refactors.
27
+ </task>
28
+
29
+ <verification_loop>
30
+ Run these before finishing and fix anything they surface, don't just report it:
31
+ <the project's real test command>
32
+ <the project's real lint/format command>
33
+ <the project's real build/typecheck command>
34
+ Confirm the working tree shows only the intended changes afterward.
35
+ </verification_loop>
36
+
37
+ <action_safety>
38
+ Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
39
+ correctness. Do NOT run git add or git commit - the orchestrator commits after reviewing. Leave the
40
+ work uncommitted in the working tree.
41
+ </action_safety>
42
+
43
+ <structured_output_contract>
44
+ End with a report in this exact shape:
45
+ 1. What changed and why
46
+ 2. Files touched
47
+ 3. Gate outcomes (paste the test/lint counts)
48
+ 4. Anything you deviated on, left open, or want a decision on
49
+ </structured_output_contract>
50
+ ```
51
+
52
+ That four-block skeleton covers most implementation tasks. Reach for extra blocks when the task profile
53
+ calls for them:
54
+
55
+ - **Debugging / open-ended fixes** - add `<completeness_contract>` (resolve fully, don't stop at the
56
+ first plausible fix) and `<missing_context_gating>` (don't guess missing repo facts; find them or
57
+ state what's unknown).
58
+ - **Research / recommendations** - add `<research_mode>` (separate observed facts, inferences, open
59
+ questions).
60
+
61
+ ## Always ask for the report explicitly
62
+
63
+ The dispatch returns agy's closing response as the payload of the fenced answer. If Antigravity finishes
64
+ without a closing summary, there is nothing useful to review - and the bridge reports no touched-file
65
+ list to fall back on. The `<structured_output_contract>` block is what guarantees a report you can read.
66
+ Read that report as a claim; git and a gate re-run are the evidence.
67
+
68
+ ## Discover the real gates
69
+
70
+ `<verification_loop>` is only useful if it names the project's _actual_ commands. Read the repo's
71
+ `AGENTS.md` / `CLAUDE.md` / `Makefile` / `package.json` first and copy the real ones in (`make test`,
72
+ `npm run lint`, `cargo test`, `pytest -q`, whatever it is). A brief that says "run the tests" without
73
+ naming them gets you an implementer that guesses - or skips.
74
+
75
+ ## Honor the repo's conventions
76
+
77
+ If the project has house rules in `AGENTS.md`, `CLAUDE.md`, or a similar file, restate the load-bearing
78
+ ones in the brief. Antigravity can inspect the workspace, but compliance is more reliable when the
79
+ important rules are directly in front of it.
80
+
81
+ ## One task per brief
82
+
83
+ Keep each brief to a single, bounded job. "Review this, fix what you find, update the docs, and suggest
84
+ a roadmap" produces a muddled run; split it into separate dispatches. One brief -> one Antigravity run
85
+ -> one commit keeps review and rollback clean.
86
+
87
+ ## Premises freeze at dispatch
88
+
89
+ The implementer starts from the brief's facts and there is no steering channel mid-run. Audit the
90
+ fact block before sending — ownership, target branch, constraints, anything a judgment call rests
91
+ on. If a premise turns out wrong while the run is live, cancel the call and re-dispatch a corrected
92
+ brief rather than discounting the output afterward; for a write-capable run, inspect the working
93
+ tree and reconcile any partial or premise-contaminated edits — keep or revert them — before the
94
+ re-dispatch.
95
+
96
+ ## A worked example
97
+
98
+ ```xml
99
+ <task>
100
+ In the payments service at services/billing/, the refund path double-charges when a refund is retried
101
+ after a network timeout. Make refund submission idempotent: check for an existing refund by idempotency
102
+ key before creating a new one. Touch only services/billing/refund.py and its tests. Leave the charge
103
+ path, API routes, and data models untouched.
104
+ </task>
105
+
106
+ <verification_loop>
107
+ Run and make green before finishing:
108
+ pytest tests/billing/ -q
109
+ ruff check services/billing/
110
+ Confirm git status shows only refund.py and its test file changed.
111
+ </verification_loop>
112
+
113
+ <action_safety>
114
+ Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave
115
+ changes in the working tree for review.
116
+ </action_safety>
117
+
118
+ <structured_output_contract>
119
+ Report: (1) the root cause and your fix, (2) files touched, (3) pytest + ruff outcomes with counts,
120
+ (4) anything you left open or want decided.
121
+ </structured_output_contract>
122
+ ```
123
+
124
+ Send this as the `prompt` of a `delegate` call with `write: true` (see
125
+ [dispatch-and-poll.md](dispatch-and-poll.md)); review the result and commit it yourself (see
126
+ [review-and-land.md](review-and-land.md)).
@@ -0,0 +1,93 @@
1
+ import { execFileSync } from "node:child_process";
2
+
3
+ export const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
4
+
5
+ /** Standalone relay capability parser; ids are opaque and come only from agy models. */
6
+ export function parseModels(output) {
7
+ const seen = new Set();
8
+ const models = [];
9
+ for (const line of output.split("\n")) {
10
+ const [id, name] = line
11
+ .split("\t")
12
+ .map((column) => column.trim().replace(/\s*\(current\)$/, ""));
13
+ if (!id || !name || seen.has(id)) continue;
14
+ seen.add(id);
15
+ const suffix = /\(([^)]*)\)\s*$/.exec(name);
16
+ const tier = suffix?.[1].trim().toLowerCase();
17
+ const effort = EFFORTS.includes(tier) || tier === "thinking" ? tier : null;
18
+ const head = effort ? name.slice(0, suffix.index).trim() : name;
19
+ const words = head.split(/\s+/);
20
+ const versionIndex = words.findIndex((word) => /^\d+(?:\.\d+)*$/.test(word));
21
+ const version = versionIndex < 0 ? [] : words.splice(versionIndex, 1)[0].split(".").map(Number);
22
+ models.push({ id, name, effort, family: words.join("-").toLowerCase(), version });
23
+ }
24
+ return models;
25
+ }
26
+
27
+ export function resolveModel(requestedModel, requestedEffort, models) {
28
+ if (!requestedModel) {
29
+ if (requestedEffort)
30
+ throw new Error("--effort requires --model; the inherited model is unknown");
31
+ return { model: null, effort: null };
32
+ }
33
+ const exact = models.find((model) => model.id === requestedModel);
34
+ const labels = models.filter((model) => model.name === requestedModel);
35
+ const fixed = exact || (labels.length === 1 ? labels[0] : null);
36
+ if (fixed) {
37
+ if (requestedEffort && fixed.effort !== requestedEffort) {
38
+ throw new Error(
39
+ `--model "${requestedModel}" fixes its listed variant; --effort "${requestedEffort}" conflicts. ` +
40
+ "Select the desired listed variant or use a family selector.",
41
+ );
42
+ }
43
+ return { model: fixed.id, effort: fixed.effort };
44
+ }
45
+ if (labels.length > 1)
46
+ throw new Error(`ambiguous model label "${requestedModel}"; use its listed ID`);
47
+ const selector =
48
+ /^([a-z0-9-]+)@(latest|\d+(?:\.\d+)*)(?:-(low|medium|high|xhigh|max|thinking))?$/i.exec(
49
+ requestedModel,
50
+ );
51
+ if (!selector) throw new Error(`model "${requestedModel}" is not in the current agy inventory`);
52
+ const [, family, version, selectorEffort] = selector;
53
+ if (requestedEffort && selectorEffort && requestedEffort !== selectorEffort.toLowerCase()) {
54
+ throw new Error("--effort conflicts with the effort in --model's family selector");
55
+ }
56
+ const effort = requestedEffort || selectorEffort?.toLowerCase();
57
+ const order = ["medium", "high", "low", "xhigh", "max", "thinking", null];
58
+ const candidates = models
59
+ .filter(
60
+ (model) =>
61
+ model.family === family.toLowerCase() &&
62
+ (version.toLowerCase() === "latest" || model.version.join(".") === version) &&
63
+ (!effort || model.effort === effort),
64
+ )
65
+ .sort((a, b) => {
66
+ for (let i = 0; i < Math.max(a.version.length, b.version.length); i++) {
67
+ const difference = (b.version[i] || 0) - (a.version[i] || 0);
68
+ if (difference) return difference;
69
+ }
70
+ return order.indexOf(a.effort) - order.indexOf(b.effort) || a.id.localeCompare(b.id);
71
+ });
72
+ const selected = candidates[0];
73
+ if (!selected)
74
+ throw new Error(
75
+ `no listed variant satisfies "${requestedModel}"${effort ? ` at effort "${effort}"` : ""}`,
76
+ );
77
+ return { model: selected.id, effort: selected.effort };
78
+ }
79
+
80
+ export function selectModel(opts, timeoutMs) {
81
+ if (!opts.model && !opts.effort) return { model: null, effort: null };
82
+ const listing = execFileSync("agy", ["models"], {
83
+ cwd: opts.cd,
84
+ timeout: Math.min(timeoutMs, 10_000),
85
+ killSignal: "SIGKILL",
86
+ stdio: ["ignore", "pipe", "pipe"],
87
+ maxBuffer: 1024 * 1024,
88
+ });
89
+ const models = parseModels(listing.toString());
90
+ if (!models.length)
91
+ throw new Error("agy models returned no readable inventory; no task was dispatched");
92
+ return resolveModel(opts.model, opts.effort, models);
93
+ }