@polygraph/claude-plugin 0.4.38 → 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.
|
@@ -47,39 +47,21 @@ spawn_agent(
|
|
|
47
47
|
|
|
48
48
|
The call returns immediately — the child agent runs asynchronously.
|
|
49
49
|
|
|
50
|
-
**
|
|
50
|
+
**Polling with long-poll waits:**
|
|
51
51
|
|
|
52
|
-
|
|
53
|
-
| ------------ | ---------------- |
|
|
54
|
-
| 1st | Immediately |
|
|
55
|
-
| 2nd | 10 seconds |
|
|
56
|
-
| 3rd | 30 seconds |
|
|
57
|
-
| 4th+ | 60 seconds (cap) |
|
|
58
|
-
|
|
59
|
-
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).
|
|
60
|
-
|
|
61
|
-
### Sleeping between polls on Claude Code
|
|
62
|
-
|
|
63
|
-
**There is exactly one correct pattern. Use it verbatim:**
|
|
52
|
+
Call `show_agent` in a loop, passing `waitForTransitionMs: 50000` on every call:
|
|
64
53
|
|
|
65
54
|
```
|
|
66
|
-
|
|
55
|
+
show_agent(
|
|
56
|
+
sessionId: "<sessionId>",
|
|
57
|
+
repo: "<repo>",
|
|
58
|
+
waitForTransitionMs: 50000
|
|
59
|
+
)
|
|
67
60
|
```
|
|
68
61
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
| Pattern | What happens |
|
|
72
|
-
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
73
|
-
| `sleep 60` (bare, foreground) | Blocked by the Bash tool with `Blocked: standalone sleep 60`. Wastes a tool call. |
|
|
74
|
-
| `sleep 10; sleep 10; sleep 10` (chained) | Detected and blocked. Explicitly prohibited. |
|
|
75
|
-
| `sleep 60 & wait`, `( sleep 60 )`, other shell tricks | Treated as the same standalone-sleep antipattern. Do not use. |
|
|
76
|
-
| `sleep 60` with `run_in_background: true` ← **WORST** | Returns immediately — *no actual delay*. The sleep keeps running as an orphaned background process. When it finally finishes, the harness wakes this subagent with a `<task-notification>`, forcing another turn after you've already returned. Every queued background sleep emits a duplicate `completed` notification to the parent. One mis-step here can produce 10+ duplicate parent notifications and burn the user's tokens. |
|
|
77
|
-
|
|
78
|
-
**Why this matters:** you run as a background Task subagent. Any background Bash command you spawn outlives your turn. Each completion wakes you again and emits another `<status>completed</status>` task-notification to the parent for the *same* parent tool-use ID. The parent has no way to silence it. Use the `until ... break ... done` wrapper — only it produces a real foreground delay.
|
|
79
|
-
|
|
80
|
-
If you ever see `Blocked: standalone sleep N`, the answer is **never** `run_in_background: true`. The answer is the `until` wrapper above.
|
|
62
|
+
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.
|
|
81
63
|
|
|
82
|
-
## Polling the
|
|
64
|
+
## Polling the child (multi-turn + input-required)
|
|
83
65
|
|
|
84
66
|
After calling `spawn_agent`, parse the structured JSON response:
|
|
85
67
|
|
|
@@ -87,9 +69,9 @@ After calling `spawn_agent`, parse the structured JSON response:
|
|
|
87
69
|
{ "taskId": "…", "message": "…", "status": "delegated" }
|
|
88
70
|
```
|
|
89
71
|
|
|
90
|
-
Then poll `show_agent`
|
|
72
|
+
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.
|
|
91
73
|
|
|
92
|
-
|
|
74
|
+
The response's `children[]` array has a single entry — the child for your repo. On it, inspect:
|
|
93
75
|
|
|
94
76
|
- `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.
|
|
95
77
|
- `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`; contains the verbatim question the child agent has asked the parent.
|
|
@@ -98,7 +80,7 @@ For each child in the response (field: `children[]`), inspect:
|
|
|
98
80
|
|
|
99
81
|
State machine:
|
|
100
82
|
|
|
101
|
-
1. `child.status === 'created'` or `'in-progress'` — child is still executing.
|
|
83
|
+
1. `child.status === 'created'` or `'in-progress'` — child is still executing. Call `show_agent` (with `waitForTransitionMs: 50000`) again.
|
|
102
84
|
2. `child.status === 'input-required'` — child is paused waiting for parent input:
|
|
103
85
|
- Read `child.inputRequiredQuestion`.
|
|
104
86
|
- Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
|
|
@@ -109,14 +91,14 @@ State machine:
|
|
|
109
91
|
<!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
|
|
110
92
|
rendered by polygraph-mcp's show_agent handler. The dialog targets the parent's main
|
|
111
93
|
thread, NOT this subagent. From this subagent's perspective the gate is transient: a
|
|
112
|
-
|
|
113
|
-
|
|
94
|
+
waited show_agent call returns immediately while the gate is open, but the parent's pick
|
|
95
|
+
resolves it and a later poll sees the child back in progress. Do nothing here. -->
|
|
114
96
|
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:
|
|
115
97
|
|
|
116
98
|
- **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.
|
|
117
99
|
- **Do NOT read `child.pendingPermission` as a question to answer or forward.** It is for inspection/logging only; it is not your input prompt.
|
|
118
100
|
- **Do NOT call any tool** (`spawn_agent`, `stop_agent`, `allow_agent`, `deny_agent`) to resolve it.
|
|
119
|
-
- Treat `permission-required` **
|
|
101
|
+
- 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.
|
|
120
102
|
|
|
121
103
|
4. `child.status === 'completed'` — child finished successfully. Read `child.lastOutputLines` for the most recent log tail and report outcome.
|
|
122
104
|
5. `child.status === 'failed'` — child failed. Read `child.lastOutputLines` for failure context and report the error.
|
package/package.json
CHANGED
|
@@ -29,6 +29,8 @@ show_session(sessionId: "<session-id>")
|
|
|
29
29
|
|
|
30
30
|
It returns the full session, including `repositories[]` (for repo display names) and `pullRequests[]`. Each `pullRequests[]` entry has `id`, `repositoryId`, `url`, `branch`, `status` (PR status: `DRAFT` / `OPEN` / `MERGED` / `CLOSED`), and a `ci` object — **`ci` may be absent if the PR has no CI**. When present, `ci` has `status`, `cipeUrl` (non-null ⇒ CIPE; null + `externalCIRuns` ⇒ external CI), `completedAt`, `selfHealingStatus`, and `externalCIRuns[]` (each with `runId`, `name`, `status`, `conclusion`, `url`, and `jobs[]`). Always read `ci` defensively (`pr.ci?.…`).
|
|
31
31
|
|
|
32
|
+
**`cipeUrl` is a human-facing web link, NOT a data source.** It points at the Nx Cloud web app, which requires browser authentication and returns no machine-readable data. Never fetch, curl, WebFetch, or poll `cipeUrl` (or any other Nx Cloud URL) directly. CI *status* comes only from polling `show_session`; CIPE *details* (failed tasks, logs, self-healing) come only from the Nx MCP `ci_information` tool. The only thing to do with `cipeUrl` is display it to the user so they can open it in a browser.
|
|
33
|
+
|
|
32
34
|
## Prerequisite: Nx MCP server (CIPE deep-dive + self-healing)
|
|
33
35
|
|
|
34
36
|
CIPE failure investigation (`ci_information`) and applying/rejecting self-healing fixes (`update_self_healing_fix`) are **not** polygraph-mcp tools — they are provided by the **Nx MCP server** (`mcp__plugin_nx_nx-mcp`). Before relying on the Phase 4 CIPE deep-dive or the Phase 5 self-healing actions, install the Nx MCP server and verify it is available.
|
|
@@ -38,7 +40,14 @@ If the Nx MCP server is **not** available, this skill can still:
|
|
|
38
40
|
- Monitor CI to a terminal state (Phases 1–3) via `show_session`, and
|
|
39
41
|
- Download and inspect **external-CI** job logs via `get_ci_logs` (a polygraph-mcp tool).
|
|
40
42
|
|
|
41
|
-
But it **cannot** perform CIPE deep-dives (`ci_information`) or apply self-healing fixes (`update_self_healing_fix`) without the Nx MCP server.
|
|
43
|
+
But it **cannot** perform CIPE deep-dives (`ci_information`) or apply self-healing fixes (`update_self_healing_fix`) without the Nx MCP server. Do NOT compensate by fetching or scraping `cipeUrl` — there is no HTTP fallback for CIPE data; the Nx MCP server is the only programmatic access.
|
|
44
|
+
|
|
45
|
+
If nx-mcp is missing, don't just report the limitation — tell the user how to install it:
|
|
46
|
+
|
|
47
|
+
- In an Nx workspace, run `nx configure-ai-agents` — it sets up the Nx MCP server (and Nx agent skills) for their AI tools, or
|
|
48
|
+
- Add the server manually as a stdio MCP server: `npx nx-mcp@latest` (see https://github.com/nrwl/nx-ai-agents-config for details).
|
|
49
|
+
|
|
50
|
+
MCP servers load at session start, so the user must restart the agent session after installing before the deep-dive and self-healing actions become available.
|
|
42
51
|
|
|
43
52
|
## Phase 1: Session Setup
|
|
44
53
|
|
|
@@ -134,7 +143,7 @@ Include self-healing status for any repo that has one.
|
|
|
134
143
|
|
|
135
144
|
For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show_session` (`pullRequests[]`):
|
|
136
145
|
|
|
137
|
-
- **If `pr.ci.cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using the Nx MCP `ci_information` tool (requires the Nx MCP server — see the prerequisite note above; if nx-mcp is unavailable, report the CIPE URL
|
|
146
|
+
- **If `pr.ci.cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using the Nx MCP `ci_information` tool (requires the Nx MCP server — see the prerequisite note above; if nx-mcp is unavailable, report the CIPE URL to the user, offer the install steps from the prerequisite section, and do NOT fetch the URL as a substitute).
|
|
138
147
|
- **If `pr.ci.cipeUrl` is null but `pr.ci.externalCIRuns` exists** → external CI only. Examine failed jobs from `pr.ci.externalCIRuns[].jobs` and use `get_ci_logs(sessionId, repositoryId, jobId)` (a polygraph-mcp tool) for log retrieval, passing `pr.repositoryId` and the failed job's `jobId` straight from the same PR object.
|
|
139
148
|
|
|
140
149
|
1. Display known info from the PR's `ci` object before delegating:
|
|
@@ -188,7 +197,7 @@ For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show
|
|
|
188
197
|
2. Identify cross-repo dependency issues (e.g., shared-lib build failure blocking frontend)
|
|
189
198
|
3. Suggest fix order based on dependency graph (upstream repos first)
|
|
190
199
|
4. Present next actions to the user based on self-healing status:
|
|
191
|
-
- If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it. `update_self_healing_fix` is an **Nx MCP** tool (`mcp__plugin_nx_nx-mcp`) — it requires the Nx MCP server. If nx-mcp is unavailable, report that a fix is available but cannot be applied from here.
|
|
200
|
+
- If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it. `update_self_healing_fix` is an **Nx MCP** tool (`mcp__plugin_nx_nx-mcp`) — it requires the Nx MCP server. If nx-mcp is unavailable, report that a fix is available but cannot be applied from here, and offer the install steps from the prerequisite section.
|
|
192
201
|
- If self-healing was already applied → offer to **resume monitoring** to watch the re-triggered CI
|
|
193
202
|
- **Delegate fixes**: use Polygraph to send fix instructions to child agents (for repos without self-healing or where self-healing was rejected/failed)
|
|
194
203
|
- **Get more details**: drill into a specific repo's failure
|
|
@@ -198,6 +207,7 @@ For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show
|
|
|
198
207
|
|
|
199
208
|
- This skill does NOT push code directly. The only write action it may take is applying/rejecting a self-healing fix via `update_self_healing_fix`, an **Nx MCP** tool that performs an Nx Cloud operation (not a local code change) and requires the Nx MCP server.
|
|
200
209
|
- Both `ci_information` and `update_self_healing_fix` are **Nx MCP** tools (`mcp__plugin_nx_nx-mcp`), not polygraph-mcp tools. Their responses include a `hints` array with contextual guidance (e.g., disclaimers about which CI Attempt was retrieved). Always check and surface non-empty hints.
|
|
210
|
+
- `cipeUrl` is a browser link for the user — never fetch, curl, WebFetch, or poll it (in the main agent or in child agents). CIPE data is only available via the Nx MCP `ci_information` tool.
|
|
201
211
|
- All heavy CI data inspection happens in child agents via `spawn_agent` to keep this context window clean.
|
|
202
212
|
|
|
203
213
|
- Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`pr.ci.cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via the Nx MCP `ci_information` tool. Job IDs come from `pr.ci.externalCIRuns[].jobs[].jobId` in the `show_session` response. The tool returns a file path (`logFile`) and size (`sizeBytes`) — use the `Read` tool to examine the log content. Logs can be large (100KB+), so only fetch logs for failed or relevant jobs.
|
|
@@ -153,6 +153,7 @@ When `cipeStatus == 'FAILED'` AND `failedTaskIds` is empty AND `selfHealingStatu
|
|
|
153
153
|
## Important
|
|
154
154
|
|
|
155
155
|
- This skill is **read-only**. Do NOT apply fixes, push code, or modify anything.
|
|
156
|
+
- `cipeUrl` and `shortLink` are human-facing web links — include them in the output for the user to open in a browser, but never fetch, curl, or poll them yourself. All CIPE data comes from the Nx MCP `ci_information` tool.
|
|
156
157
|
|
|
157
158
|
- Always delegate the MCP call to a subagent. Do NOT call ci_information yourself.
|
|
158
159
|
|
|
@@ -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;
|
|
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
|
allowed-tools:
|
|
6
6
|
- mcp__plugin_polygraph_polygraph-mcp
|
|
@@ -46,7 +46,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
|
|
|
46
46
|
| `list_repos` | `polygraph repo list` | Discover candidate repositories. Candidate entries do not include repository descriptions; use `semanticQuery` for natural-language discovery. |
|
|
47
47
|
| `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
|
|
48
48
|
| `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. |
|
|
49
|
-
| `show_agent` | — | Poll
|
|
49
|
+
| `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'`. |
|
|
50
50
|
| `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. |
|
|
51
51
|
| `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. |
|
|
52
52
|
| `create_pr` | — | Create draft PRs with session metadata linking related PRs |
|
|
@@ -58,9 +58,11 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
|
|
|
58
58
|
| `add_repo` | — | Add repositories to a running Polygraph session. For explicit refs, pass the refs directly and skip `list_repos`. |
|
|
59
59
|
| `archive_session` | `polygraph session archive <id>` | Archive a session, hiding it from active lists (it can still be resumed) |
|
|
60
60
|
| `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job |
|
|
61
|
+
| `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". |
|
|
61
62
|
| `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
|
|
62
63
|
| `logout` | `polygraph auth logout` | Log out of Polygraph |
|
|
63
64
|
| `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. |
|
|
65
|
+
| `search_sessions` | `polygraph session search` | Find sessions by free-text `query` OR by commit `sha` — pass EXACTLY ONE of the two (they are mutually exclusive). `sha` (CLI: `--sha <sha>`) is an exact lookup of the session(s) linked to a commit, full or partial, 7-40 hex chars; it returns matching sessions newest first, org-scoped, and explicit sessions only (implicit sessions are never returned). Supports `--json` and `--limit` (1-50). See "Finding the Session Behind a Commit or Line". |
|
|
64
66
|
| `list_accounts` | `polygraph account list` | List available organizations |
|
|
65
67
|
| `select_account` | `polygraph account select` | Select the organization that future commands run against |
|
|
66
68
|
| `whoami` | `polygraph whoami` | Show current auth status and org |
|
|
@@ -96,7 +98,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
|
|
|
96
98
|
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.
|
|
97
99
|
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.
|
|
98
100
|
|
|
99
|
-
4. **Monitor child agents** - Use `show_agent` to poll
|
|
101
|
+
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.
|
|
100
102
|
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.
|
|
101
103
|
6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
|
|
102
104
|
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.
|
|
@@ -213,13 +215,39 @@ Description:
|
|
|
213
215
|
Inspect the PR commits/diff and investigate the requested behavior. Report findings with file paths and concrete evidence.
|
|
214
216
|
```
|
|
215
217
|
|
|
218
|
+
### Finding the Session Behind a Commit or Line
|
|
219
|
+
|
|
220
|
+
Use this workflow when the user asks which Polygraph session produced, is behind, or changed a particular commit — or a particular line of code.
|
|
221
|
+
|
|
222
|
+
**Given a commit sha.** When the user names a sha, or asks what session is behind a commit, resolve it with `search_sessions` using the `sha` parameter (CLI: `polygraph session search --sha <sha>`):
|
|
223
|
+
|
|
224
|
+
- Pass **exactly one** of `query` or `sha` — they are mutually exclusive.
|
|
225
|
+
- `sha` accepts a full or partial sha, 7-40 hex chars.
|
|
226
|
+
- The lookup is exact and one-shot: it returns the session(s) linked to that commit, newest first, scoped to the current org, and only explicit sessions.
|
|
227
|
+
|
|
228
|
+
```
|
|
229
|
+
search_sessions(sha: "a1b2c3d")
|
|
230
|
+
# CLI equivalent:
|
|
231
|
+
polygraph session search --sha a1b2c3d
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
**Given a line number.** There is no line-number lookup — a line MUST first be resolved to a commit sha with `git blame`, then that sha is fed into the sha lookup:
|
|
235
|
+
|
|
236
|
+
1. `git blame -L <line>,<line> -- <file>` to get the commit that last touched the line.
|
|
237
|
+
2. Pass that sha to `search_sessions(sha: ...)` (or `polygraph session search --sha <sha>`).
|
|
238
|
+
|
|
239
|
+
**Reading the results.**
|
|
240
|
+
|
|
241
|
+
- Multiple sessions may match a sha. They come back newest first — pick the most relevant one and report the others if they matter.
|
|
242
|
+
- **A "no match" result does NOT prove the commit had no work behind it.** Not every commit is linked to an explicit session: commits pushed directly (rather than via an ingested PR) and gaps in ingestion metadata mean the sha may simply not be recorded, and implicit sessions are never returned. Report "no linked session found for that sha" — never assert that no work exists behind the commit.
|
|
243
|
+
|
|
216
244
|
## Simple tasks (fire-and-forget)
|
|
217
245
|
|
|
218
246
|
Use this pattern when the task is well-defined and the child is not expected to need clarification. It is a single-round delegation: kick it off, poll until terminal, then push branch + create PR.
|
|
219
247
|
|
|
220
248
|
**CRITICAL:** `spawn_agent` and `show_agent` MUST ALWAYS be called via background Task subagents (`run_in_background: true`), NEVER directly from the main conversation. Direct calls flood the context window with polling noise and degrade the user experience. This is a hard requirement, not a suggestion.
|
|
221
249
|
|
|
222
|
-
1. Launch a background `Task` subagent per repo using `polygraph-delegate-subagent`. The subagent calls `spawn_agent`, then polls `show_agent`
|
|
250
|
+
1. Launch a background `Task` subagent per repo using `polygraph-delegate-subagent`. The subagent calls `spawn_agent`, then polls `show_agent` via chained `waitForTransitionMs` long-poll calls until terminal.
|
|
223
251
|
|
|
224
252
|
```
|
|
225
253
|
Task(
|
|
@@ -239,7 +267,7 @@ Task(
|
|
|
239
267
|
```
|
|
240
268
|
|
|
241
269
|
2. Delegate to multiple repos in parallel by launching multiple background Task subagents at the same time — one delegation per repo at a time. Read the output files later to check progress.
|
|
242
|
-
3.
|
|
270
|
+
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).
|
|
243
271
|
4. Once all background subagents report a terminal status, continue to `push_branch` + `create_pr`.
|
|
244
272
|
|
|
245
273
|
In rare cases where you need to check the raw child agent status directly (e.g., debugging a stuck subagent), you may call `show_agent` as a one-off tool call. Do NOT use this for regular polling — that MUST happen in background subagents.
|
|
@@ -256,7 +284,7 @@ Use this pattern when the child may need clarification, the task is exploratory,
|
|
|
256
284
|
{ "taskId": "…", "message": "…", "status": "delegated" }
|
|
257
285
|
```
|
|
258
286
|
|
|
259
|
-
2. Poll `show_agent
|
|
287
|
+
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:
|
|
260
288
|
|
|
261
289
|
- `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
|
|
262
290
|
- `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`.
|
|
@@ -431,7 +459,7 @@ Check the details of a session using `show_session` or `polygraph session show -
|
|
|
431
459
|
- `relatedPRs`: Array of related PR URLs across repos
|
|
432
460
|
- `session.ciStatus`: CI pipeline status keyed by PR ID, each containing:
|
|
433
461
|
- `status`: One of `SUCCEEDED`, `FAILED`, `IN_PROGRESS`, `NOT_STARTED` (null if no CIPE and no external CI)
|
|
434
|
-
- `cipeUrl`: URL to the CI pipeline execution details (null if no CIPE)
|
|
462
|
+
- `cipeUrl`: URL to the CI pipeline execution details (null if no CIPE). This is a human-facing Nx Cloud web link — display it to the user, but never fetch, curl, or poll it directly; CIPE data is only accessible programmatically via the Nx MCP `ci_information` tool
|
|
435
463
|
- `completedAt`: Epoch millis timestamp, set only when the CIPE has completed (null otherwise)
|
|
436
464
|
- `selfHealingStatus`: The self-healing fix status string from Nx Cloud's AI fix feature (null if no AI fix exists)
|
|
437
465
|
- `externalCIRuns`: Array of external CI runs (present when no CIPE but external CI data exists, e.g., GitHub Actions). Each run contains:
|
|
@@ -601,7 +629,7 @@ archive_session(
|
|
|
601
629
|
|
|
602
630
|
Use `get_ci_logs` to retrieve the full plain-text log for a specific CI job. This is the drill-in tool for investigating CI failures after identifying a failed job from the session's CI status.
|
|
603
631
|
|
|
604
|
-
**ONLY use this tool when NO CIPE (CI Pipeline Execution) exists for the PR.** When a CIPE exists (`ciStatus[prId].cipeUrl` is non-null), logs and failure data are available through the CIPE system (Nx Cloud) via `ci_information` — do NOT call `get_ci_logs
|
|
632
|
+
**ONLY use this tool when NO CIPE (CI Pipeline Execution) exists for the PR.** When a CIPE exists (`ciStatus[prId].cipeUrl` is non-null), logs and failure data are available through the CIPE system (Nx Cloud) via the Nx MCP `ci_information` tool — do NOT call `get_ci_logs`, and do NOT fetch or poll the `cipeUrl` over HTTP (it is a browser link for the user, not an API). This tool is specifically for PRs where only external CI runs exist (e.g., GitHub Actions runs without an Nx Cloud CIPE).
|
|
605
633
|
|
|
606
634
|
**Parameters:**
|
|
607
635
|
|
|
@@ -636,6 +664,10 @@ get_ci_logs(
|
|
|
636
664
|
|
|
637
665
|
**Important:** Logs can be large (100KB+). Only fetch logs for failed or relevant jobs, and read only the sections you need.
|
|
638
666
|
|
|
667
|
+
### Fetching Git History for Shallow Clones
|
|
668
|
+
|
|
669
|
+
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`).
|
|
670
|
+
|
|
639
671
|
### Update Session Description
|
|
640
672
|
|
|
641
673
|
Use this when the user asks to summarize progress, update the session description, or capture the current state.
|