@juanbenjumea/pi-agy 0.7.7 → 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.
@@ -1,103 +1,20 @@
1
1
  ---
2
2
  name: agy-delegate
3
- description: >
4
- Delegate bulk implementation, scaffolding, repetitive refactors, and
5
- exhaustive test generation to the Antigravity CLI (agy).
6
- argument-hint: "prompt=\"...\" [model=flash-low|flash-medium|flash-high|pro-low|pro-high|sonnet|opus|gpt-oss] [agent=name] [mode=plan|accept-edits|sandbox]"
3
+ description: Optional, quota-limited Antigravity delegation for substantial work
4
+ argument-hint: 'prompt="..." [model=...] [mode=plan|accept-edits|sandbox]'
7
5
  license: MIT
8
6
  ---
9
-
10
7
  # agy-delegate
11
8
 
12
- Use the `agy_usage` tool to inspect model-specific quota and reset times when
13
- availability matters, then use `agy_execute` to offload large scaffolding,
14
- repetitive refactors, or exhaustive test generation via the Antigravity CLI.
15
-
16
- ## Prerequisites
17
-
18
- 1. Install the Antigravity CLI (a Go binary, not pipx):
19
-
20
- ```bash
21
- curl -fsSL https://antigravity.google/cli/install.sh | bash
22
- ```
23
-
24
- 2. Authenticate in a terminal (one-time):
25
-
26
- ```bash
27
- agy
28
- ```
29
-
30
- 3. Verify the CLI works:
31
-
32
- ```bash
33
- agy --version
34
- agy models
35
- ```
36
-
37
- ## Tool usage
38
-
39
- ```
40
- agy_execute prompt="Refactor all snake_case variables to camelCase in src/models/"
41
- agy_execute prompt="Generate exhaustive unit tests for src/auth/" model=flash-low
42
- agy_execute prompt="Plan the migration to ESM" model=sonnet mode=plan digest=true
43
- agy_execute prompt="Review our earlier API decision" model=sonnet mode=plan context=summary
44
- agy_execute prompt="Implement the approved plan" conversation_id=<id> mode=accept-edits
45
- agy_execute prompt="Adversarial review the diff" model=opus effort=high mode=plan
46
- agy_agents
47
- agy_execute prompt="Investigate the crash" agent=gsd-debugger mode=plan
48
- agy_history
49
- agy_usage
50
- agy_execute prompt="Migrate the build to ESM" mode=plan background=true
51
- agy_tasks action=list
52
- agy_tasks action=status handle=<handle>
53
- agy_tasks action=collect handle=<handle>
54
- agy_tasks action=cancel handle=<handle>
55
- ```
56
-
57
- Background runs (`background=true`) return a task handle immediately instead
58
- of blocking the turn. Poll with `agy_tasks status`, collect the terminal
59
- result with `agy_tasks collect` (which frees the record), and cancel strays
60
- with `agy_tasks cancel`. Runs keep their `timeout_ms` deadline, serialize on
61
- the per-directory lock, record sessions on completion, and die with the Pi
62
- session — collect promptly, since uncollected payloads do not survive restart
63
- (conversations stay resumable via `agy_history`).
64
-
65
- ## Modes
66
-
67
- | Mode | Purpose |
68
- |------|---------|
69
- | `plan` | Exploration and planning — no edits |
70
- | `accept-edits` (default) | Implementation — agy applies edits directly |
71
- | `sandbox` | Preview changes without applying |
72
-
73
- ## Rules
9
+ Use agy sparingly; your current tools and agent are the default.
74
10
 
75
- - **Default to `mode=plan`** for exploration; escalate to `accept-edits` only for scoped batches.
76
- - **Always review the `git diff`** after agy runs with `accept-edits`.
77
- - **Run `just ci`** (or the project gate) after write modes in this repo.
78
- - **Never use agy for irreversible production changes or unowned background servers/watchers.** Delegations are bounded; timeout/cancellation kills the full process tree rather than releasing unowned work. The managed exception is `background=true`, whose runs stay timeout-owned, cancellable, lock-serialized, and die with the session.
79
- - Reuse `conversation_id` or `continue=true` for multi-step plan → implement → review.
80
- - Use `agent` only when the user requests a configured custom agent; call `agy_agents` first when the exact name is unknown. Recorded agent identity is restored on resume.
81
- - Keep `context=none` (default) unless the task depends on prior Pi discussion; prefer `summary` over `recent` to minimize disclosure. Context handoff excludes system prompts, thinking, tool arguments/results, images, and custom messages.
82
- - Use `flash-medium` by default, `flash-low` for trivial/high-volume work, and `flash-high` for difficult agentic work.
83
- - Escalate within the Gemini quota group to `pro-low` or `pro-high` only when needed.
84
- - Use `sonnet` for normal Claude-group coding/review; reserve `opus` for the hardest architecture or root-cause work.
85
- - Use `gpt-oss` when an open-model alternative is specifically desired.
86
- - Set `effort` only for `gpt-oss`; Claude thinking models reject `--effort`, and Gemini aliases encode effort in the model id.
87
- - For consequential work, have one family produce and the opposite family review with `mode=plan`; do not spend both groups on trivial tasks.
88
- - Batch related work, avoid parallel calls within one shared-quota group or directory, and use `digest=true` (default) for non-write tasks.
11
+ - Use `agy_execute` only when the user explicitly asks to use agy. Never delegate autonomously based on perceived benefit. Never launch `agy_execute` through a Herdr pane.
12
+ - Prefer one focused run; avoid duplicate or parallel calls. Continue only genuinely unfinished work with `conversation_id` or `continue=true`.
13
+ - Use `mode=accept-edits` for scoped implementation and `mode=plan` only when exploration without edits is useful. Do not add separate planning or cross-model review runs by default; reserve them for user requests or material risk. After edits, inspect `git diff` and run the project check (usually `just ci`).
14
+ - Keep `context=none` unless prior discussion is needed; prefer `summary` to `recent`. Check `agy_usage` only when quota availability affects a decision.
15
+ - Use `background=true` only for long runs that need no steering; collect results with `agy_tasks collect` and cancel abandoned runs. Use `agy_agents` only when the user asks for a configured custom agent.
16
+ - Never delegate irreversible production changes.
89
17
 
90
- ## Enhancements over upstream pi-agy
18
+ When the user requests live steering and Herdr is available, run interactive `agy` in a Herdr pane instead of using `agy_execute`. Prompts sent while AGY is busy queue; use Ctrl+C to interrupt its current command before redirecting it. Herdr-run AGY does not take pi-agy's per-directory lock, so use a separate worktree if it could overlap with Pi-managed AGY work.
91
19
 
92
- - **Quota discovery** — `agy_usage` and `/agy usage` report model-specific remaining quota and reset times; executions refresh quota snapshots, automatically fall back when an implicit default is exhausted, and return machine-readable `quota_status` as well.
93
- - **Custom-agent selection** — `agy_agents` and `/agy agents` list configured agents without inference; `agent` / `agent=name` passes a validated `--agent` and persists its identity with resumable conversations.
94
- - **Streaming progress and receipts** — live tool steps via `stream-json` and Pi `onUpdate`; direct `/agy` runs persist bounded, expandable TUI-only receipts without feeding them to the primary model.
95
- - **Observed subagents** — native subagent stream steps produce bounded progress and a capped per-run roster in result details/receipts. `active at last event` is diagnostic history, never a claim of live lifecycle control.
96
- - **Conversation continuity** — `conversation_id`, `continue`, session store under `$PI_CODING_AGENT_DIR/agy-sessions.json` (or `~/.pi/agent/agy-sessions.json` by default) with one-line task summaries; runs that time out or are cancelled are recorded too and stay resumable, and the `agy_history` tool lets agents list past conversations.
97
- - **Optional Pi context handoff** — `context=summary|recent` sends bounded text-only history while excluding system prompts, thinking, tool calls/results, images, and custom messages; default is `none`.
98
- - **Repo-aware verify** — prefers `just ci` when a justfile defines `ci:`.
99
- - **Diff summary** — accept-edits results append newly-dirty files only; pre-existing dirt is listed separately, never misattributed.
100
- - **Per-directory lock** — serializes concurrent agy calls on the same tree across Pi processes (symlink-aware).
101
- - **Cancellation** — abort/timeout kills the full agy process tree, and streamed records plus responses are size-bounded; a fully delivered result survives cancellation or timeout, and the conversation stays resumable.
102
- - **Background tasks** — `agy_execute background=true` detaches with a task handle; `agy_tasks` polls, collects, and cancels. Timeout-owned, lock-serialized, session-recorded, reaped on shutdown.
103
- - **Antigravity provider** — `antigravity/*` models in Pi's `/model` picker with live catalog discovery, a persistent stream-json driver, and a localhost MCP bridge: read-only Pi context plus mutating Pi tools via parked calls and real shadow `toolCall` turns (normal permissions and review apply). Toggle with `/agy bridge on|off`; attached images are staged as files agy can open.
20
+ For tool parameters and current behavior, rely on the `agy_execute` and related tool descriptions; consult the package README for setup and configuration.