@polygraph/opencode-plugin 0.4.35 → 0.4.37

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nrwl/polygraph-skills/source/assets/polygraph-light.svg">
-    <img src="https://raw.githubusercontent.com/nrwl/polygraph-skills/source/assets/polygraph.svg" alt="Polygraph Logo" width="140">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nrwl/polygraph-skills/main/source/assets/polygraph-light.svg">
+    <img src="https://raw.githubusercontent.com/nrwl/polygraph-skills/main/source/assets/polygraph.svg" alt="Polygraph Logo" width="140">
   </picture>
 </p>
 
@@ -37,9 +37,10 @@ It detects your AI agent — Claude Code, Codex, OpenCode, and more — and inst
 
 ## Skills
 
-- **polygraph** — Comprehensive guidance for multi-repo coordination: session init, delegation, branch pushing, PR creation, and session management
+- **polygraph** — Comprehensive guidance for Polygraph sessions: shared context, repository graph visibility, PR/CI state, delegation, and session management
 - **await-polygraph-ci** — Wait for CI pipelines to settle across all repos in a session, investigate failures, and present fix options
 - **get-latest-ci** — One-shot fetch of the latest CI pipeline execution for the current branch
+- **session-debrief** — Analyze the raw logs of past Polygraph sessions and produce structured, rank-ordered debriefs for use in a different session
 
 ## Agents
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@polygraph/opencode-plugin",
-  "version": "0.4.35",
-  "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
+  "version": "0.4.37",
+  "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,
   "author": {

package/skills/await-polygraph-ci/SKILL.md

@@ -10,9 +10,30 @@ Wait for all CI pipelines in a Polygraph session to reach a stable state (succee
 
 Some Polygraph tools have both MCP and CLI equivalents — use whichever is available in your environment. See the polygraph skill's tool table for the full mapping.
 
+## CI status source
+
+CI polling uses the polygraph-mcp `show_session` tool, which now carries per-PR CI status directly on each pull request:
+
+```
+show_session(sessionId: "<session-id>")
+```
+
+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?.…`).
+
+## Prerequisite: Nx MCP server (CIPE deep-dive + self-healing)
+
+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.
+
+If the Nx MCP server is **not** available, this skill can still:
+
+- Monitor CI to a terminal state (Phases 1–3) via `show_session`, and
+- Download and inspect **external-CI** job logs via `get_ci_logs` (a polygraph-mcp tool).
+
+But it **cannot** perform CIPE deep-dives (`ci_information`) or apply self-healing fixes (`update_self_healing_fix`) without the Nx MCP server. If nx-mcp is missing, state this limitation to the user explicitly.
+
 ## Phase 1: Session Setup
 
-Fetch the Polygraph session using `show_session`.
+Fetch the session using `show_session` and read per-PR CI status from `pullRequests[]`.
 
 **Parameters:**
 
@@ -23,16 +44,18 @@ show_session(sessionId: "<session-id>")
 ```
 
 1. Record `monitorStartedAt` = current timestamp (epoch millis).
-2. Build a tracking table of all repos with PRs. For each PR, record:
-   - `repo`: repository name
-   - `prUrl`: PR URL
-   - `prStatus`: DRAFT / OPEN / MERGED / CLOSED
-   - `ciStatus`: from session (may already be a terminal status from a previous run)
-   - `cipeUrl`: CI pipeline URL (null if none)
-   - `cipeCompletedAt`: `completedAt` from session (epoch millis, null if CIPE is active or absent)
-   - `selfHealingStatus`: self-healing fix status (null if none)
+2. Build a tracking table from `pullRequests[]`. For each PR, map:
+   - `repo`: repository display name from the matching `repositories[]` entry by `pr.repositoryId` (fall back to `pr.branch` if not found)
+   - `repoId`: `pr.repositoryId` (pass straight to `get_ci_logs`)
+   - `prUrl`: `pr.url`
+   - `prStatus`: `pr.status` (DRAFT / OPEN / MERGED / CLOSED)
+   - `ciStatus`: `pr.ci?.status` (may already be a terminal status from a previous run)
+   - `cipeUrl`: `pr.ci?.cipeUrl` (null if none → external CI or no CI)
+   - `cipeCompletedAt`: `pr.ci?.completedAt` (epoch millis, null if CIPE is active or absent)
+   - `selfHealingStatus`: `pr.ci?.selfHealingStatus` (null if none)
+   - `jobs`: `pr.ci?.externalCIRuns?.flatMap(r => r.jobs)` (external-CI job list, used in Phase 4)
    - `firstSeenAt`: current timestamp
-3. If no PRs found, report "No PRs in session" and exit.
+3. If `pullRequests[]` is empty, report "No PRs in session" and exit.
 4. **Stale detection**: For each PR, determine if its CI status is **stale** — meaning it reflects a previous run, not a current one. A PR's CI status is stale if:
    - `cipeCompletedAt` is non-null AND `cipeCompletedAt < monitorStartedAt` (the CIPE finished before the monitor started)
    - Mark these PRs as `stale: true`
@@ -52,7 +75,7 @@ show_session(sessionId: "<session-id>")
 **Each poll iteration:**
 
 1. Call `show_session(sessionId: <session-id>)`
-2. Update each tracked PR from the session response: `ciStatus`, `cipeUrl`, `cipeCompletedAt`, and `selfHealingStatus`
+2. Update each tracked PR from its matching `pullRequests[]` entry (by PR `id` / `repositoryId`): `ciStatus` ← `pr.ci?.status`, `cipeUrl` ← `pr.ci?.cipeUrl`, `cipeCompletedAt` ← `pr.ci?.completedAt`, `selfHealingStatus` ← `pr.ci?.selfHealingStatus`, `prStatus` ← `pr.status`, and `jobs` ← `pr.ci?.externalCIRuns?.flatMap(r => r.jobs)`
 3. **Clear stale flag**: If a PR was marked `stale: true` and its `cipeCompletedAt` has changed (or become null, meaning a new CIPE is active), clear the stale flag — this PR now has fresh CI data.
 4. Display status update:
    ```
@@ -100,18 +123,18 @@ Include self-healing status for any repo that has one.
 
 ## Phase 4: Failure Investigation (Child Agent Delegation)
 
-For each repo with `ciStatus: FAILED`, first check the CI data source from `ciStatus[prId]`:
+For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show_session` (`pullRequests[]`):
 
-- **If `cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using `ci_information`.
-- **If `cipeUrl` is null but `externalCIRuns` exists** → external CI only. Examine failed jobs from `externalCIRuns` in the session data and use `get_ci_logs` for log retrieval.
+- **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 but note the deep-dive can't run).
+- **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.
 
-1. Display known info from the session data before delegating:
+1. Display known info from the PR's `ci` object before delegating:
 
    ```
    Repository: frontend
    CI Source: <CIPE or External CI (GitHub Actions)>
-   CI Pipeline: <cipeUrl from session, or GitHub Actions run URL>
-   Self-healing: <selfHealingStatus from session, or "None">
+   CI Pipeline: <pr.ci.cipeUrl, or GitHub Actions run URL>
+   Self-healing: <pr.ci.selfHealingStatus, or "None">
    Investigating failure details...
    ```
 
@@ -119,9 +142,9 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
 
    - `sessionId`: the session ID
    - `repo`: the repository name
-   - `instruction` (when CIPE exists): Use the `ci_information` tool to investigate the CI failure on this branch. Return a structured summary with: (1) list of failed task IDs with a one-line error summary each, (2) failure category (Build / Test / Lint / E2E / Infra / Other).
-   - `instruction` (when no CIPE, external CI only): The session data shows external CI failures with these failed jobs: [list jobId + name from `externalCIRuns[].jobs` where `conclusion` is `failure`]. Use `get_ci_logs(sessionId, repoId, jobId)` to save the log for each failed job to a local file, then use the `Read` tool to examine the log file contents. Return a structured summary with: (1) one-line error summary per failed job, (2) failure category (Build / Test / Lint / E2E / Infra / Other), (3) relevant log excerpts.
-   - `context`: Polygraph session monitoring — investigating CI failure for unified summary. The repository ID for this repo is available from the session data.
+   - `instruction` (when CIPE exists): Use the Nx MCP `ci_information` tool to investigate the CI failure on this branch (the Nx MCP server must be installed). Return a structured summary with: (1) list of failed task IDs with a one-line error summary each, (2) failure category (Build / Test / Lint / E2E / Infra / Other).
+   - `instruction` (when no CIPE, external CI only): The PR's `ci` object shows external CI failures with these failed jobs: [list `jobId` + `name` from `pr.ci.externalCIRuns[].jobs` where `conclusion` is `failure`]. Use `get_ci_logs(sessionId, repositoryId, jobId)` to save the log for each failed job to a local file, then use the `Read` tool to examine the log file contents. Return a structured summary with: (1) one-line error summary per failed job, (2) failure category (Build / Test / Lint / E2E / Infra / Other), (3) relevant log excerpts.
+   - `context`: Polygraph session monitoring — investigating CI failure for unified summary. The repository ID for this repo is the PR's `repositoryId`.
 
    Since `spawn_agent` is non-blocking, you can delegate to multiple failed repos in parallel.
 
@@ -156,7 +179,7 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
 2. Identify cross-repo dependency issues (e.g., shared-lib build failure blocking frontend)
 3. Suggest fix order based on dependency graph (upstream repos first)
 4. Present next actions to the user based on self-healing status:
-   - If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it
+   - 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.
    - If self-healing was already applied → offer to **resume monitoring** to watch the re-triggered CI
    - **Delegate fixes**: use Polygraph to send fix instructions to child agents (for repos without self-healing or where self-healing was rejected/failed)
    - **Get more details**: drill into a specific repo's failure
@@ -164,10 +187,10 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
 
 ## Notes
 
-- 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`, which is an Nx Cloud operation (not a local code change).
-- Both `ci_information` and `update_self_healing_fix` responses include a `hints` array with contextual guidance (e.g., disclaimers about which CI Attempt was retrieved). Always check and surface non-empty hints.
+- 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.
+- 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.
 - All heavy CI data inspection happens in child agents via `spawn_agent` to keep this context window clean.
 
-- Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`ciStatus[prId].cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via `ci_information`. Job IDs come from `ciStatus[prId].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.
+- 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.
 - `spawn_agent` is **non-blocking** — it starts the child agent and returns immediately. Use `show_agent` to poll for results and `stop_agent` to terminate stuck agents.
 - The `show_session` response is compact and safe to poll from the main agent.

package/skills/polygraph/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: polygraph
-description: Guidance for working with Polygraph — repositories, sessions, child agents, PRs, and CI. Use when discovering repositories or how code is consumed across them, starting, joining, resuming, or sharing a Polygraph session, handing off progress, coordinating changes/branches/PRs across repos, delegating tasks to child agents in different repos, or checking CI status and logs. 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", or asks about what other repos are doing with shared code/APIs/endpoints.
+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; or checking CI status and logs. 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", or asks about what other repos are doing with shared code/APIs/endpoints.
 
 ---
 
@@ -52,10 +52,13 @@ Before using Polygraph tools, ensure the CLI is authenticated and an organizatio
 
 ### Check Authentication
 
-Use `polygraph whoami` (or the `whoami` MCP tool) to check if the user is currently logged in and which organization is active.
+Use `polygraph whoami` (or the `whoami` MCP tool) before session work to check if the user is currently logged in and which organization is active.
 
 - If the user **is logged in** and an org is selected → proceed to the workflow.
-- If the user **is not logged in** → use `polygraph auth login` (or the `login` MCP tool) to authenticate. After login, an organization must be selected.
+- If auth is **missing, expired, or no org is selected** → stop session work. Do not keep trying session creation, repository discovery, delegation, or CI checks.
+- Facilitate user reauth through the browser-based login flow, such as `polygraph auth login` (or the `login` MCP tool). In interactive desktop clients, browser reauth is usually user-driven; surface the need clearly and wait for the user to complete it.
+- After login, an organization must be selected. Use `polygraph account select` (or the MCP equivalent) when needed.
+- Re-run `polygraph whoami` (or `whoami`) after reauth and org selection. Continue only after it confirms a valid login and selected organization.
 
 ### Select Organization
 
@@ -98,6 +101,8 @@ In case B, call `add_repo` yourself when exact repo refs were provided; otherwis
 
 - For a new session (case C), `start_session` auto-generates a unique session ID. You do NOT need to pass one.
 - For cases A and B, the session ID already exists; reuse it everywhere — never let `start_session` run in this conversation.
+- The parent conversation is responsible for detecting an existing session ID from current context, the startup banner, or a user-provided session URL/ID, then passing it explicitly to `polygraph-init-subagent`. The init subagent cannot infer parent session context by itself.
+- For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected; launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
 
 **Launch the init subagent** using `@polygraph-init-subagent` (cases B and C — skip in case A):
 
@@ -657,3 +662,4 @@ If the session has a description timeline, also display:
    
 1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed. The child's session is preserved (`sessionPreserved: true`) so the context can be restored later, but after resuming you must wait for explicit user instructions before making changes.
 1. **Only archive sessions when asked** — Only call `archive_session` when the user explicitly requests it. Archiving hides the session from active lists; it can still be resumed later.
+   

package/skills/session-debrief/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: session-debrief
+description: Analyze the raw logs of past Polygraph sessions and produce structured, rank-ordered debriefs for use in a different session. Use when launched (typically as a background agent) with a ranked list of relevant Polygraph session IDs and a statement of the current task; pulls parent and child transcripts via the polygraph CLI and returns one consolidated debrief.
+---
+
+# Session Debrief
+
+You produce debriefs of PAST Polygraph sessions so a parent agent working on a NEW task can decide what context is relevant. You are read-only with respect to the inspected sessions: never resume them, never spawn agents into them, never push branches, create PRs, or update their descriptions.
+
+## Input
+
+- A ranked list of sessions `{ sessionId, title?, url? }`, most relevant first (rank 1 = most relevant). If no explicit ranking is stated, the given order IS the ranking.
+- A statement of the current task the parent is working on.
+
+## Procedure
+
+For each session, in rank order:
+
+1. `polygraph session show --details <sessionId>` — metadata, description timeline, repositories, PRs.
+2. `polygraph session logs -s <sessionId> --json` — the full parent transcript (`--json` returns the full transcript by default).
+3. If the session delegated work to other repositories (child-agent steps exist), pull those transcripts too: `polygraph session logs -s <sessionId> --all --json`, or `--repo <org/repo> --json` for one repo.
+4. Write the debrief section (format below) before moving to the next session.
+
+Large transcripts: if the full `--json` output is too large to hold, page with `--tail 200 --page <n>` and prioritize, in order: user prompts, assistant text and final messages, tool errors and failure events, task notifications. Routine tool-use noise (file reads, searches) is safe to skim.
+
+## Output
+
+Return ONE consolidated debrief as your final message — it is consumed by the parent agent, not shown raw to a human. Sessions in rank order, each following this template. Target a tight page per session; do not pad.
+
+### Rank N — <session title> (<sessionId>)
+
+**URL:** <session url>
+**Goal:** what the session set out to do.
+**What happened:** condensed narrative of the work performed.
+**Outcome + artifacts:** PRs (URL + status), branches, key files touched.
+**Key decisions:** one bullet per decision, with the recorded rationale.
+**Gotchas / failed approaches:** what went wrong or was abandoned, and why.
+**Unresolved:** open items or next steps the session left behind.
+**Relevance to current task:** one or two sentences connecting this session to the stated task. The parent decides what to use — report the connection, do not overclaim.
+
+## Constraints
+
+- Exact citations: session URLs, PR URLs, file paths, branch names.
+- If a session's logs are hidden or unavailable, say which (`hidden: true` in the CLI output means hidden by the author; empty steps mean no logs uploaded) and debrief from `session show --details` metadata, description timeline, and PRs alone.
+- No speculation: when the transcript does not show why a decision was made, write "rationale not recorded".
+- Read-only: the inspected sessions must be byte-for-byte unaffected by your work.

package/skills/session-start/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: session-start
+description: Start or reconnect a Polygraph session for shared, resumable agent context. Use when the user asks to start a Polygraph session, create session memory, share or resume work context, include related repositories, or inspect an existing session before continuing.
+
+---
+
+# Start a Polygraph Session
+
+Start or reconnect a Polygraph session so the current work has shared, resumable context: session URL, repository graph visibility, linked PR/CI state, and the option to expand across repository boundaries when needed.
+
+## Check Authentication First
+
+Before session work, the parent conversation must check Polygraph auth with `whoami` or `polygraph whoami`.
+
+- If auth is valid and an organization is selected, continue.
+- If auth is missing, expired, or no organization is selected, stop session work. Do not keep trying session creation or discovery.
+- Facilitate user reauth through the browser-based flow, such as `polygraph auth login` or the MCP `login` equivalent. After login, make sure an organization is selected with `polygraph account select` or the MCP equivalent when needed.
+- Re-run `whoami` after reauth. Continue only after it confirms a valid login and selected organization.
+
+Do not breeze past auth failures. In Codex Desktop, auth recovery usually requires the user to complete the browser login flow; surface that clearly and wait for it before continuing.
+
+## Parent Session Detection
+
+The parent conversation is responsible for detecting an existing Polygraph session ID from the current context, startup banner, or user-provided session URL/ID, then passing that `sessionId` explicitly to `polygraph-init-subagent` when launching it. The init subagent cannot infer the parent's current session context by itself.
+
+For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected. Launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
+
+## Decide the Session Path
+
+Pick one path before using tools.
+
+1. **Existing session with repos** - If a Polygraph session ID is already in scope and the user did not ask to add repositories, call `show_session` to inspect it and print the session details. Do not create a new session.
+2. **Existing session, adding exact repository refs** - If a session ID is in scope and the user provided exact refs by ID, short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax, call `add_repo(sessionId, repoIds: [...])` directly. Do not run discovery.
+3. **Existing session, discovery needed** - If a session ID is in scope but repos need to be discovered or selected, launch `polygraph-init-subagent` with the existing `sessionId` and `userContext`. The subagent must use `add_repo`, not `start_session`.
+4. **No session in scope** - Launch `polygraph-init-subagent` with `userContext` and no `sessionId`. The subagent will discover related repositories when needed and call `start_session`.
+
+Exact refs are not limited to organization repos. Public open-source repos can be added by `owner/repo` slug or URL even if they do not appear in repository discovery.
+
+Invoke `@polygraph-init-subagent` for discovery or new-session creation. Use direct `add_repo` only for exact refs on an existing session.
+
+## Print the Result
+
+When a brand-new session is created, render the session welcome card. Prefer the `session_intro` MCP tool when available; otherwise run `polygraph session intro -s <sessionId>` and print the returned markdown verbatim.
+
+For an existing or reconnected session, print:
+
+**Session:** POLYGRAPH_SESSION_URL
+
+**Repositories in this session:**
+
+- REPO_FULL_NAME
+
+Use `polygraphSessionUrl` from the session response for `POLYGRAPH_SESSION_URL`, and use repository entries from the session response for `REPO_FULL_NAME`.