@juanbenjumea/pi-agy 0.7.8 → 0.7.9

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/README.md +30 -252
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.9
4
+
5
+ - Rewrite the README as a concise overview of agy task delegation and the Antigravity provider, retaining installation, configuration, and development essentials.
6
+
3
7
  ## 0.7.8
4
8
 
5
9
  - Improve agy provider cache behavior: stabilize prompt prefixes, cap recent resume context, key preflight and verification caches by working directory, and bucket print timeouts for identical arguments.
package/README.md CHANGED
@@ -1,280 +1,61 @@
1
1
  # @juanbenjumea/pi-agy
2
2
 
3
- Antigravity (agy) provider and delegation for Pi: `/model` picker integration,
4
- persistent driver with loopback MCP tool bridge, background tasks, quota awareness,
5
- repo verification, and trustworthy diff summaries.
3
+ Use Google's Antigravity CLI (`agy`) from Pi. This package adds two ways to work:
6
4
 
7
- Pi can delegate scoped tasks to the Antigravity CLI (`agy`) or use Antigravity
8
- as the primary `/model` provider for interactive chat with a full loopback MCP tool bridge.
5
+ - **Delegate a task** to `agy` with Pi tools such as `agy_execute`, or the `/agy` command.
6
+ - **Use agy as a Pi model provider** through `antigravity/*` in `/model`, with an optional bridge to Pi tools.
9
7
 
10
- Enhanced fork of [`@bacnh85/pi-agy`](https://github.com/bacnh85/pi-extensions/tree/main/pi-agy).
11
-
12
- ## Install
8
+ Install with:
13
9
 
14
10
  ```bash
15
11
  pi install npm:@juanbenjumea/pi-agy
16
12
  ```
17
13
 
18
- Requires Node.js >= 20.3.
19
-
20
- ## What's different from upstream 0.3.1
21
-
22
- | Feature | Upstream | This fork |
23
- |---------|----------|-----------|
24
- | Live progress | Final text only | `stream-json` → Pi `onUpdate` cards |
25
- | Model aliases | Hardcoded ids | Live `agy models` catalog (newest stable generation wins; preview/experimental ignored), static map fallback |
26
- | Conversation resume | None | `conversation_id`, `continue`, session store with task summaries and custom-agent identity, `/agy sessions` picker, `agy_history` discovery tool — runs that time out or are cancelled are recorded too |
27
- | Verify injection | `npm test` only | `just ci` first, then `npm test`/`uv run pytest` |
28
- | Post-write summary | None | Appends `git diff --stat` for newly-dirty files only; pre-existing dirt (including renames and unstaged edits) is listed separately and never misattributed |
29
- | Preflight | Every call | Health/model checks cached 5 min per process; model quotas refresh every minute |
30
- | Quota discovery | None | Read-only `/usage` probe exposes model-specific remaining quota and reset times to agents |
31
- | Custom agents | None | Read-only `agy_agents` / `/agy agents` discovery plus validated `agent` / `agent=name` selection via `--agent` |
32
- | Subagent visibility | None | Native stream progress plus a capped per-run roster in result details/receipts; observations never claim live lifecycle control |
33
- | Concurrency | Unlocked | Per-directory lock (in-process + filesystem, symlink-aware), lock wait counts against the timeout |
34
- | Transient failures | Fatal | One retry when agy fails before doing any work |
35
- | Cancellation | Direct child only | Full process-tree kill on cancel/timeout via detached process groups; a fully delivered result is preserved |
36
- | Primary-model picker | None | `antigravity/*` provider with live catalog, persistent driver, MCP tool bridge, and image staging (see below) |
37
- | Background runs | Blocking only | `background=true` detaches with a handle; `agy_tasks` polls, collects, and cancels under the same timeout and lock |
38
-
39
- Auth is unchanged: existing `agy` OAuth (`~/.gemini/oauth_creds.json`).
40
-
41
- ## Antigravity provider (`/model` picker)
42
-
43
- This package also registers an `antigravity` provider, so agy-backed models
44
- appear in Pi's global `/model` picker as `antigravity/<id>` (for example
45
- `antigravity/gemini-3-8-flash`). Model entries are discovered from live
46
- `agy models` output at startup (refreshed in the background, no `/reload`
47
- needed); when discovery fails, a fallback catalog keeps the picker populated
48
- and selection yields a clear runtime error instead of an empty list.
49
-
50
- Gemini bases with multiple effort tiers expose Pi's thinking-level toggle,
51
- which is sent as agy `--effort` (clamped to tiers the base accepts — Pro has
52
- no medium). Fixed-thinking families (Claude, GPT-OSS) keep agy's exact slug
53
- and never receive `--effort`.
54
-
55
- Attached images are staged as files under a process-stable 0700 root
56
- (passed as `--add-dir` so sandboxed turns can open them) and referenced by
57
- path in the turn prompt, so agy opens them with its file tools; images on
58
- tool results ride the delivery the same way. Capped at the 8 newest images /
59
- 8 MiB each with strict base64 validation — failures degrade to omitted notes.
60
- Each staging has a dispose handle owned by its turn (suspensions carry
61
- theirs forward); terminal settle, stale-cancel, abandonment, and session
62
- shutdown all reclaim.
63
-
64
- Each turn runs on a persistent `agy --input-format stream-json` driver
65
- process (one per working directory) with the transcript rendered as text.
66
- The process is reused across turns — follow-ups skip cold start and re-auth —
67
- and recycled when the model, effort, permissions, or conversation drifts; idle
68
- processes are reaped after five minutes and everything is disposed on session
69
- shutdown. Completed turns are recorded to the same session store as
70
- delegation runs, so `/agy sessions` can resume them. Provider turns take the
71
- same per-directory lock as delegation runs (lock waits count against the turn
72
- timeout), so a provider turn never races `agy_execute` in the same directory.
73
-
74
- Read-only tool bridge: provider turns also get an extra `--add-dir`
75
- carrying a localhost MCP server (`pi-agy-tools`) that exposes Pi-side
76
- context agy cannot see otherwise — `agy_sessions_list`, `agy_quota_report`,
77
- `agy_model_catalog`, and `activate_skill` (which dynamically lists and injects
78
- Pi Agent Skills from `~/.pi/agent/skills`, `~/.agents/skills`, and `.pi/skills`).
79
- The server binds 127.0.0.1 with a per-process shared secret, serves only reads,
80
- and never touches your global agy config. Set `"providerBridge": false` in
81
- `agy-config.json` to run provider turns plain.
82
-
83
- Mutating tool bridge: agy turns can also call Pi tools directly. The bridge
84
- parks the MCP call, the provider emits a real shadow `toolCall`, and Pi
85
- executes it with normal permissions, approvals, and diff review; the next
86
- turn's `toolResult` completes the parked call and agy continues. Only active
87
- non-builtin tools are exposed (`agy_*` and `AskAntigravity` excluded — no
88
- recursive delegation); the catalog refreshes per turn and the driver recycles
89
- when it changes so agy always sees a fresh tool list. Long calls over 20 seconds
90
- early-ack with `STILL RUNNING` and a `callId` so agy can poll via
91
- `bridge_poll_result`, completely avoiding agy's ~180-second MCP client timeout.
92
- Suspended turns hold the agy child with timers off, re-arm on resume, and are
93
- abandoned loudly on cancel, teardown, or a 30-minute stall cap.
94
-
95
- Do not install `@estebanforge/pi-antigravity-bridge` alongside this package:
96
- both register the `antigravity` provider id and an `/agy` command.
97
-
98
- ## Timeouts & cancellation
14
+ Requires Node.js >= 20.3 and an installed, authenticated `agy` CLI. Existing agy OAuth credentials are used; this package does not manage authentication.
99
15
 
100
- `timeout_ms` (default 5m, max 10m) is a hard parent-side deadline — lock
101
- waits, preflight probes, and post-run summaries all count against it. When
102
- it fires, the full agy process group is killed so nested tools cannot
103
- outlive the run. agy's own `--print-timeout` is set five seconds later because
104
- agy 1.1.28+ returns partial output with exit code 0 when that internal timer
105
- fires; Pi therefore remains the authoritative timeout owner. Terminal result
106
- envelopes also fail closed: when agy supplies a status, only `SUCCESS` and `OK`
107
- are accepted, even if a failed result carries an empty response and exits 0.
16
+ ## Delegate tasks
108
17
 
109
- Active tool updates show bounded intent (for example a tool action or async
110
- threshold) but never echo full command lines, which may contain secrets.
111
- Subagent spawn steps likewise produce bounded progress and a final per-run
112
- observation roster (maximum 32). An `active at last event` entry describes the
113
- last stream record only; it does not claim that a controllable process remains live.
114
- Background commands are intentionally not detached or managed out-of-band:
115
- agy exposes no reliable headless task lifecycle or task-to-process ownership,
116
- so timeout/cancellation still kills the full process tree and prevents work from
117
- continuing after the directory lock is released.
18
+ `agy_execute` runs a task in `plan`, `accept-edits`, or `sandbox` mode. It streams progress and returns the result, quota details when available, and a summary of newly changed files. Runs are serialized per working directory; timeouts and cancellations stop the agy process tree.
118
19
 
119
- The deadline never discards finished work:
20
+ Useful options include:
120
21
 
121
- - A response that fully arrived before the kill is returned with an
122
- explanatory note instead of being thrown away — even if cancellation or
123
- the deadline landed between delivery and process exit.
124
- - Post-run steps cut short by the deadline (the accept-edits diff summary)
125
- are skipped with a note rather than failing the run.
126
- - The conversation id is recorded on timeout and cancellation, so the run
127
- stays resumable via `conversation_id`, `/agy continue`, or `/agy sessions`.
128
- Timeout errors distinguish ids successfully recorded for `/agy continue` or
129
- `/agy sessions` from ids merely observed when local persistence failed; the
130
- latter can still be resumed by passing `conversation_id` explicitly.
22
+ - `model` and `agent` to select a model or configured agy agent
23
+ - `conversation_id`, `continue`, and `new_session` to resume work
24
+ - `background=true` to return a handle, then use `agy_tasks` to poll, collect, or cancel
25
+ - `context=summary|recent` to optionally pass bounded Pi conversation context (default: none)
131
26
 
132
- ## Tool params (new)
27
+ The `/agy` command runs tasks from Pi's TUI and can also list agents, inspect quota, diagnose setup, and select saved conversations. For example:
133
28
 
134
- | Param | Description |
135
- |-------|-------------|
136
- | `background` | Return immediately with a task handle instead of waiting; poll with `agy_tasks status` and collect the result. The run keeps its `timeout_ms` deadline; cancel via `agy_tasks`. |
137
- | `conversation_id` | Resume agy conversation by ID |
138
- | `continue` | `--continue` most recent conversation |
139
- | `new_session` | Force fresh session; set `false` to reuse last ID for dir |
140
- | `effort` | Reasoning effort via `--effort` where supported; `gpt-oss` accepts it, while Claude thinking models reject it and Gemini aliases already encode it |
141
- | `agent` | Optional configured custom agy agent name; discover names with `agy_agents` |
142
- | `stream` | Use `stream-json` (default `true`) |
143
- | `context` | Optional Pi history handoff: `none` (default), `summary`, or `recent` |
144
- | `mode` | `accept-edits` by default; use `plan` for exploration/review |
145
-
146
- `agy_execute` refreshes quota information before each run (best effort) and
147
- returns it in `details.quota`/`details.quota_status` and the response when
148
- the CLI exposes structured model records. Use the separate `agy_usage` tool
149
- when choosing a model before execution. If the selected model is explicitly
150
- reported as exhausted, the run stops before spending another agent turn and
151
- reports the reset information. When no model is explicitly requested, an exhausted
152
- quota-balanced default automatically falls back to the first reported available
153
- model family. Explicit model selections fail clearly instead of silently
154
- switching models.
155
- Use `agy_usage` with `model` (for example `model=sonnet`) for a targeted
156
- `available`/`exhausted`/`unknown` status. Older agy versions that do not support
157
- headless `/usage` continue without failing the task. The extension requires
158
- agy 1.1.11+ before invoking `/usage`; older versions are refused safely because
159
- that command could otherwise consume model quota as a prompt.
160
-
161
- When agy emits `subagent` stream steps, `agy_execute` returns a capped,
162
- control-safe `details.subagents` list and appends the same observed summary to
163
- tool content. Native rendering deduplicates that synthetic appendix and shows
164
- compact/expanded roster metadata. Conversation ids and log URIs from nested
165
- subagents are deliberately not exposed as lifecycle handles.
166
-
167
- Context handoff is opt-in and text-only. `summary` sends up to 12,000
168
- characters from the latest durable summaries and four conversational messages;
169
- `recent` sends up to 40,000 characters from the recent conversational tail.
170
- Both exclude Pi system prompts, thinking, tool arguments, tool results, images,
171
- and custom extension messages. The current delegated task is appended after the
172
- reference context and remains authoritative.
173
-
174
- The `agy_agents` tool runs the read-only `agy agents` subcommand and returns
175
- configured custom-agent names without spending a model turn. Pass an exact
176
- name as `agy_execute agent`; initial selection is always explicit, while known
177
- conversation resumes restore their recorded agent.
178
-
179
- The `agy_history` tool lists recorded conversations for a directory — ids,
180
- models, custom agents, ages, and one-line task summaries — so agents can find a
181
- `conversation_id` to resume; `/agy sessions` offers the same in the TUI
182
- picker. Summaries are stored locally (first ~80 chars of each prompt), and a
183
- recorded custom agent is restored when that conversation resumes.
184
-
185
- The `agy_tasks` tool manages background runs started with
186
- `agy_execute background=true`: `list` shows tasks per directory, `status`
187
- polls state and recent progress, `collect` returns the terminal result and
188
- frees the record, and `cancel` aborts a live run. Background runs keep their
189
- `timeout_ms` deadline, serialize on the per-directory lock like foreground
190
- runs, and are recorded to the session store on completion so nothing is lost
191
- when a payload goes uncollected; session shutdown aborts anything still live.
192
-
193
- ## Human-callable `/agy` command
194
-
195
- Run agy directly from the Pi TUI — fast path when fully specified, wizard otherwise:
196
-
197
- ```
198
- /agy flash fix git conflicts # fully specified → runs immediately
199
- /agy plan sonnet review the diff # mode + model + prompt
200
- /agy agents # list configured custom agents (read-only)
201
- /agy plan agent=gsd-debugger investigate the crash
202
- /agy context=summary plan sonnet review our earlier decision
203
- /agy plan # wizard: model select → task editor
204
- /agy # wizard: mode → model → task editor
205
- /agy continue fix the tests # continue this directory's last conversation
206
- /agy timeout=10m sonnet big task # raise the run cap (also 90s / 1500ms; bare = minutes)
207
- /agy sessions # pick a recorded conversation to resume
208
- /agy doctor # diagnose CLI, models, agents, quota, config, sessions, lock, provider, and repo gate
209
- /agy usage # inspect model quotas and reset times
210
- /agy bridge [on|off] # inspect or toggle the provider MCP bridge (takes effect next turn)
29
+ ```text
30
+ /agy plan flash investigate the failing tests
31
+ /agy continue fix the remaining issues
32
+ /agy sessions
33
+ /agy doctor
211
34
  ```
212
35
 
213
- Leading option tokens (`plan`, a model alias, `agent=name`, `continue`,
214
- `context=summary`, `context=recent`, `timeout=…`) are consumed in any order;
215
- the remainder is the prompt. `/agy continue` reuses the last model and custom
216
- agent when the session store recorded them. `timeout=` caps at 10m.
36
+ In `accept-edits` mode, Pi confirms before writes. agy's own permission behavior is controlled by its configuration and the package's `agy-config.json` settings below.
217
37
 
218
- First token optional: `accept-edits` / `plan` / `sandbox` mode prefix, then a
219
- model alias (`flash`, `pro`, `sonnet`, `opus`, `gpt-oss`, …), then the prompt.
220
- The interactive wizard and direct `agy_execute` calls default to
221
- `accept-edits`; the wizard confirms before writing. Use `plan` explicitly for
222
- exploration/review. Sandbox runs do not bypass agy permission checks.
38
+ ## Use agy as a Pi model
223
39
 
224
- `/agy doctor` performs no inference and spends no model tokens. It reports the
225
- installed CLI version, discoverable stable model aliases, optional custom-agent
226
- discovery, quota support, active config, recorded sessions, workspace lock state,
227
- provider runtime state (driver turns/reuses/recycles, bridge tool count,
228
- suspended turns awaiting Pi tools, live image staging), and detected
229
- verification gate.
40
+ The package registers an `antigravity` provider. Select discovered models as `antigravity/<model>` in Pi's `/model` picker. Models are discovered from `agy models`, with a fallback catalog if discovery fails. Gemini thinking levels map to agy's supported effort tiers.
230
41
 
231
- Missing pieces open interactive dialogs (mode select, model select with
232
- descriptions, multi-line task editor). `accept-edits` asks for confirmation
233
- before writing. The command then runs agy directly with the selected parameters;
234
- progress is shown in the throttled status bar and a durable, expandable receipt
235
- is appended to Pi's transcript. Receipts are TUI-only custom entries: they are
236
- not sent to the primary model, and context handoff excludes them. Stored task
237
- text is capped at 500 characters and result text at 8,000 characters. Stripped-down
238
- hosts fall back to a normal notification. `/agy usage` performs the same read-only
239
- quota check without starting a model turn; `/agy agents` likewise lists custom
240
- agents without inference.
42
+ Provider turns use a persistent agy process per working directory and can stage attached images for agy to read. By default, an MCP bridge gives agy read-only Pi context and lets it call active Pi tools through Pi's normal permission and approval flow. Set `"providerBridge": false` in `agy-config.json` to disable the bridge.
241
43
 
242
- ## Config
44
+ Do not install `@estebanforge/pi-antigravity-bridge` alongside this package: both register the `antigravity` provider and `/agy` command.
243
45
 
244
- Optional `$PI_CODING_AGENT_DIR/agy-config.json` (default
245
- `~/.pi/agent/agy-config.json`):
46
+ ## Configuration
47
+
48
+ Optional file: `$PI_CODING_AGENT_DIR/agy-config.json` (default `~/.pi/agent/agy-config.json`). For example:
246
49
 
247
50
  ```json
248
51
  {
52
+ "defaultModel": "flash-medium",
249
53
  "skipPermissions": true,
250
- "defaultModel": "flash-medium"
54
+ "providerBridge": true
251
55
  }
252
56
  ```
253
57
 
254
- - `skipPermissions` (default `true`) — pass `--dangerously-skip-permissions`
255
- for `accept-edits` runs. Set `false` to leave agy's own permission checks in
256
- place; note print mode has no interactive approval path, so restricted
257
- operations may be reported as `denied_actions` instead of prompting. The
258
- extension rejects a denied run with no response and visibly warns when agy
259
- returns an explanatory response alongside denied actions.
260
- - `defaultModel` — alias used when `agy_execute` omits `model`/`tier`.
261
- - `defaultModelCommand` — shell command whose stdout sets the default alias
262
- when `defaultModel` is unset (an explicit `defaultModel` always wins).
263
- Must print one valid alias; failures and invalid output fall back to the
264
- built-in default. Result cached ~5 min per process. Escape hatch for
265
- custom resolvers; prefer `quotaBalancing` below.
266
- - `quotaBalancing` — steer the default across agy's quota families by
267
- recent usage balance: when the Gemini group (flash/pro) carried ≥75% of
268
- the last 24h of recorded conversations (min 3), the default flips to
269
- `sonnet` so routine delegation rests the hot group. Tune with
270
- `AGY_DEFAULT_MODEL_WINDOW_HOURS`, `AGY_DEFAULT_MODEL_MIN_SESSIONS`, and
271
- `AGY_DEFAULT_MODEL_GEMINI_SHARE`. Missing/corrupt stores mean no signal.
272
-
273
- Tool results record `permissions_skipped` in `details` for auditability.
274
-
275
- Live catalog resolution ignores preview/experimental model ids so an
276
- unstable entry can never silently become the default. Set
277
- `PI_AGY_ALLOW_PREVIEW=1` to opt into preview ids explicitly.
58
+ `defaultModel` sets the default for delegated tasks. `skipPermissions` controls agy's permission-bypass flag for `accept-edits` runs; set it to `false` to retain agy's checks. `providerBridge` toggles the provider's Pi-tool bridge.
278
59
 
279
60
  ## Development
280
61
 
@@ -283,10 +64,7 @@ npm test
283
64
  npm run typecheck
284
65
  ```
285
66
 
286
- With an installed, authenticated `agy`, run `npm run test:live` to verify the
287
- CLI version, stable model catalog, custom-agent roster, quota schema, and doctor
288
- integration against the real binary. The smoke uses read-only commands only and
289
- does not start an inference turn or spend model tokens.
67
+ With an installed agy CLI, `npm run test:live` runs read-only integration checks without starting an inference turn.
290
68
 
291
69
  ## License
292
70
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@juanbenjumea/pi-agy",
3
- "version": "0.7.8",
3
+ "version": "0.7.9",
4
4
  "description": "Antigravity (agy) provider and delegation for Pi — /model picker, background tasks, loopback MCP tool bridge, quota awareness, and repo verification.",
5
5
  "type": "module",
6
6
  "license": "MIT",