@polygraph/codex-plugin 0.4.39 → 0.4.40
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.
|
@@ -37,22 +37,21 @@ spawn_agent(
|
|
|
37
37
|
|
|
38
38
|
The call returns immediately — the child agent runs asynchronously.
|
|
39
39
|
|
|
40
|
-
**
|
|
40
|
+
**Polling with long-poll waits:**
|
|
41
41
|
|
|
42
|
-
|
|
43
|
-
| ------------ | ---------------- |
|
|
44
|
-
| 1st | Immediately |
|
|
45
|
-
| 2nd | 10 seconds |
|
|
46
|
-
| 3rd | 30 seconds |
|
|
47
|
-
| 4th+ | 60 seconds (cap) |
|
|
48
|
-
|
|
49
|
-
Use `sleep` in Bash between polls — this is mandatory, not aspirational. Without it you will hammer `show_agent` every 2-3s, which both wastes calls and floods your own context with repeated polling output. Always run sleep in the **foreground** (never background).
|
|
42
|
+
Call `show_agent` in a loop, passing `waitForTransitionMs: 50000` on every call:
|
|
50
43
|
|
|
51
44
|
```
|
|
52
|
-
|
|
45
|
+
show_agent(
|
|
46
|
+
sessionId: "<sessionId>",
|
|
47
|
+
repo: "<repo>",
|
|
48
|
+
waitForTransitionMs: 50000
|
|
49
|
+
)
|
|
53
50
|
```
|
|
54
51
|
|
|
55
|
-
|
|
52
|
+
Each call blocks up to ~50 seconds and resolves within ~1 second of a state change. It returns immediately if the child is already terminal, `input-required`, or `permission-required`. Call it back-to-back in a loop.
|
|
53
|
+
|
|
54
|
+
## Polling the child (multi-turn + input-required)
|
|
56
55
|
|
|
57
56
|
After calling `spawn_agent`, parse the structured JSON response:
|
|
58
57
|
|
|
@@ -60,9 +59,9 @@ After calling `spawn_agent`, parse the structured JSON response:
|
|
|
60
59
|
{ "taskId": "…", "message": "…", "status": "delegated" }
|
|
61
60
|
```
|
|
62
61
|
|
|
63
|
-
Then poll `show_agent`
|
|
62
|
+
Then poll `show_agent` in a loop with `waitForTransitionMs: 50000`. **Do not pass a `tail` argument** — the tool's default is sized for status polling. Only set `tail` if you have a specific reason (e.g., the default truncated output you actually need to inspect, or you are hunting for an earlier failure that scrolled off). Never ratchet `tail` upward across polls; that is what causes the polling loop to flood your context window.
|
|
64
63
|
|
|
65
|
-
|
|
64
|
+
The response's `children[]` array has a single entry — the child for your repo. On it, inspect:
|
|
66
65
|
|
|
67
66
|
- `child.status` — an AcpRunStatus value: one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`). Note `'permission-required'` and `'input-required'` are DIFFERENT states handled by different cases below — do not conflate them.
|
|
68
67
|
- `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`; contains the verbatim question the child agent has asked the parent.
|
|
@@ -71,7 +70,7 @@ For each child in the response (field: `children[]`), inspect:
|
|
|
71
70
|
|
|
72
71
|
State machine:
|
|
73
72
|
|
|
74
|
-
1. `child.status === 'created'` or `'in-progress'` — child is still executing.
|
|
73
|
+
1. `child.status === 'created'` or `'in-progress'` — child is still executing. Call `show_agent` (with `waitForTransitionMs: 50000`) again.
|
|
75
74
|
2. `child.status === 'input-required'` — child is paused waiting for parent input:
|
|
76
75
|
- Read `child.inputRequiredQuestion`.
|
|
77
76
|
- Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
|
|
@@ -82,14 +81,14 @@ State machine:
|
|
|
82
81
|
<!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
|
|
83
82
|
rendered by polygraph-mcp's show_agent handler. The dialog targets the parent's main
|
|
84
83
|
thread, NOT this subagent. From this subagent's perspective the gate is transient: a
|
|
85
|
-
|
|
86
|
-
|
|
84
|
+
waited show_agent call returns immediately while the gate is open, but the parent's pick
|
|
85
|
+
resolves it and a later poll sees the child back in progress. Do nothing here. -->
|
|
87
86
|
3. `child.status === 'permission-required'` — the child opened a permission gate. **This is NOT `input-required`. Do not treat it like case 2.** The parent's native MCP elicitation dialog already renders the prompt in the parent's own UI and routes the decision back to the child through `polygraph-mcp`. Your only job is to stay out of the way and keep polling:
|
|
88
87
|
|
|
89
88
|
- **Do NOT return, finish, summarize, relay, or surface this to the parent.** Do NOT describe the child as "needing input", "awaiting approval", "asking for permission", or anything that would make the parent prompt the user — the parent already has its own dialog. Returning here is the bug this case exists to prevent.
|
|
90
89
|
- **Do NOT read `child.pendingPermission` as a question to answer or forward.** It is for inspection/logging only; it is not your input prompt.
|
|
91
90
|
- **Do NOT call any tool** (`spawn_agent`, `stop_agent`, `allow_agent`, `deny_agent`) to resolve it.
|
|
92
|
-
- Treat `permission-required` **
|
|
91
|
+
- Treat `permission-required` **like `in-progress`**: just call `show_agent` (with `waitForTransitionMs`) again — the parent's dialog resolves it. Only at a terminal state do you return, per the cases below.
|
|
93
92
|
|
|
94
93
|
4. `child.status === 'completed'` — child finished successfully. Read `child.lastOutputLines` for the most recent log tail and report outcome.
|
|
95
94
|
5. `child.status === 'failed'` — child failed. Read `child.lastOutputLines` for failure context and report the error.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: polygraph
|
|
3
|
-
description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; checking CI status and logs; or tracing a commit or line of code back to the session that produced it. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", asks about what other repos are doing with shared code/APIs/endpoints, or asks about a "commit sha", "session behind this commit", "which session changed this line", "find session by sha", "git blame".
|
|
3
|
+
description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; checking CI status and logs; fetching missing git history in a shallow session clone; or tracing a commit or line of code back to the session that produced it. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", asks about what other repos are doing with shared code/APIs/endpoints, or asks about a "commit sha", "session behind this commit", "which session changed this line", "find session by sha", "git blame", "shallow clone", "missing commit", "bad object", "unshallow", "fetch history".
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -56,7 +56,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
|
|
|
56
56
|
| `list_repos` | `polygraph repo list` | Discover candidate repositories. Candidate entries do not include repository descriptions; use `semanticQuery` for natural-language discovery. |
|
|
57
57
|
| `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
|
|
58
58
|
| `spawn_agent` | — | Start a new child task or send a follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context? }`. Output: `{ taskId, message, status: 'delegated' }`. Follow-up routing is automatic: if the repo already has an active child task, the instruction is delivered to it as a follow-up message; otherwise a new child run starts. A repo has at most one active child at a time. A session resume or reconstruction is read-only context restoration; after resuming, do not use `spawn_agent` to continue changes unless the user explicitly asks for changes. |
|
|
59
|
-
| `show_agent` | — | Poll
|
|
59
|
+
| `show_agent` | — | Poll the status of the specified repo's child (`repo` is required — one call covers one repo). Output: `{ children: PolygraphChildStatusItem[] }` with a single entry for that repo; the item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'permission-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. |
|
|
60
60
|
| `stop_agent` | — | Cancel an in-progress child. Output: `{ taskId, state: 'cancelled', sessionPreserved: true, output, message }`. Because `sessionPreserved: true`, the preserved agent session can be restored later for context, but resume must wait for explicit user instructions before making changes. |
|
|
61
61
|
| `push_branch` | — | Push a local git branch to the remote repository. For the repo you are in, this pushes from your current checkout. Requires a session description. |
|
|
62
62
|
| `create_pr` | — | Create draft PRs with session metadata linking related PRs |
|
|
@@ -68,6 +68,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
|
|
|
68
68
|
| `add_repo` | — | Add repositories to a running Polygraph session. For explicit refs, pass the refs directly and skip `list_repos`. |
|
|
69
69
|
| `archive_session` | `polygraph session archive <id>` | Archive a session, hiding it from active lists (it can still be resumed) |
|
|
70
70
|
| `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job |
|
|
71
|
+
| `git_fetch` | `polygraph git fetch` | Fetch additional git history for a shallow session clone. Use when git operations fail with "bad object" or missing-commit errors; by default fetches the full history of the default branch. Input: `{ sessionId, repo, depth?, refs? }`. See "Fetching Git History for Shallow Clones". |
|
|
71
72
|
| `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
|
|
72
73
|
| `logout` | `polygraph auth logout` | Log out of Polygraph |
|
|
73
74
|
| `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. |
|
|
@@ -107,7 +108,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
|
|
|
107
108
|
0. **Initialize or join Polygraph session** - If you were spawned inside an existing session (the startup banner names a session ID), reuse it. Call `show_session` first; if it already has repos and the user did not ask to add more, you're done. If the user asks to add exact repo refs, call `add_repo` directly with those refs and skip candidate discovery. If the session has no repos and no exact refs were provided, launch the `polygraph-init-subagent` with that `sessionId` so it discovers candidates and uses `add_repo` (NOT `start_session`). Only when there is no session ID at all should the init subagent create a new session.
|
|
108
109
|
1. **Delegate work to each repo** - Use the `polygraph-delegate-subagent` to start child agents in other repositories. Delegate only to *other* repos — never to the repo you are in; work on it directly (your regular subagents are fine for local work — only Polygraph delegation is reserved for other repos). Parallel delegation across repos is encouraged, but only one active child per repo. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification.
|
|
109
110
|
|
|
110
|
-
4. **Monitor child agents** - Use `show_agent` to poll
|
|
111
|
+
4. **Monitor child agents** - Use `show_agent` to poll one repo's child (`repo` is required) and read its `status` and `lastOutputLines` from the single-entry `children[]` array.
|
|
111
112
|
5. **Stop child agents** (if needed) - Use `stop_agent` to cancel an in-progress child agent. The underlying agent session is preserved for later read-only context restoration; after a resume, wait for explicit user instructions before making changes.
|
|
112
113
|
6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
|
|
113
114
|
7. **Update session description** - Use `update_session` to update the session description; must follow the Session Description Policy. Independent of PR creation or mark-ready.
|
|
@@ -269,13 +270,13 @@ spawn_agent(
|
|
|
269
270
|
- instruction: "<the task instruction>"
|
|
270
271
|
- context: "<optional context>"
|
|
271
272
|
|
|
272
|
-
Call the Polygraph MCP spawn_agent for the repo, then poll show_agent
|
|
273
|
+
Call the Polygraph MCP spawn_agent for the repo, then poll show_agent via chained waitForTransitionMs long-poll calls until terminal. Return a structured summary with repo, status, session ID, and result text.
|
|
273
274
|
"""
|
|
274
275
|
)
|
|
275
276
|
```
|
|
276
277
|
|
|
277
278
|
2. Delegate to multiple repos in parallel by launching multiple `polygraph-delegate-subagent` instances before waiting for results — one delegation per repo at a time.
|
|
278
|
-
3.
|
|
279
|
+
3. The subagent watches `child.status` on the single `children[]` entry for its repo and exits when it sees a terminal status — typically `'completed'` or `'failed'` (and `'cancelled'` if it was stopped).
|
|
279
280
|
4. Collect completed results with `wait_agent` when the main flow needs them, then continue to `push_branch` + `create_pr`.
|
|
280
281
|
|
|
281
282
|
In rare cases where you need to check the raw child agent status directly (e.g., debugging a stuck subagent), you may call the Polygraph MCP `show_agent` as a one-off tool call. Do NOT use this for regular polling — that belongs inside `polygraph-delegate-subagent`.
|
|
@@ -292,7 +293,7 @@ Use this pattern when the child may need clarification, the task is exploratory,
|
|
|
292
293
|
{ "taskId": "…", "message": "…", "status": "delegated" }
|
|
293
294
|
```
|
|
294
295
|
|
|
295
|
-
2. Poll `show_agent
|
|
296
|
+
2. Poll `show_agent` via chained `waitForTransitionMs` long-poll calls (`repo` is required). The response shape is `{ children: PolygraphChildStatusItem[] }` with a single entry for that repo. On it, inspect:
|
|
296
297
|
|
|
297
298
|
- `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
|
|
298
299
|
- `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`.
|
|
@@ -672,6 +673,10 @@ get_ci_logs(
|
|
|
672
673
|
|
|
673
674
|
**Important:** Logs can be large (100KB+). Only fetch logs for failed or relevant jobs, and read only the sections you need.
|
|
674
675
|
|
|
676
|
+
### Fetching Git History for Shallow Clones
|
|
677
|
+
|
|
678
|
+
Session repos are shallow (`--depth 1`) clones and plain `git fetch --unshallow` fails on private repos (the clone-time credential is not retained). When git fails on missing history (`bad object` from `git revert`, `git log`, `git blame`, etc.), call `git_fetch({ sessionId, repo })` (CLI: `polygraph git fetch <repo> --session <id> --json`), then retry. Defaults fetch the default branch's full history; pass `depth` for a bounded fetch or `refs` for extra branches. Safe to call redundantly (`alreadyComplete: true`).
|
|
679
|
+
|
|
675
680
|
### Update Session Description
|
|
676
681
|
|
|
677
682
|
Use this when the user asks to summarize progress, update the session description, or capture the current state.
|