@polygraph/codex-plugin 0.4.27 → 0.4.29

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 (5) hide show
  1. package/.codex-plugin/plugin.json +1 -1
  2. package/agents/polygraph-delegate-subagent.toml +4 -8
  3. package/agents/polygraph-init-subagent.toml +17 -19
  4. package/package.json +1 -1
  5. package/skills/polygraph/SKILL.md +18 -17
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "polygraph",
3
- "version": "0.4.27",
3
+ "version": "0.4.29",
4
4
  "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
5
5
  "author": {
6
6
  "name": "Narwhal Technologies Inc",
package/agents/polygraph-delegate-subagent.toml CHANGED
@@ -17,13 +17,12 @@ The main agent provides these parameters in the prompt:
17
17
  | `repo` | Repository to delegate to (e.g., `org/repo-name`) |
18
18
  | `instruction` | The task instruction for the child agent |
19
19
  | `context` | (Optional) Additional context to pass to the child agent |
20
- | `taskId` | (Optional) Existing active task to route a user-approved follow-up to; omit on the first call for a new run |
21
20
 
22
21
  ## Delegating work
23
22
 
24
- Call the `spawn_agent` tool to start a child agent on the repo or to route an explicit follow-up to an active task. If the main agent supplied a `taskId` - meaning this is a user-approved follow-up turn against an already active task - forward it unchanged; otherwise omit `taskId` and a new child run is started.
23
+ Call the `spawn_agent` tool to start a child agent on the repo or to send a follow-up to an active task. Follow-up routing is automatic: if the repo already has an active child task (working or paused on input), the orchestrator delivers your `instruction` to that task as a follow-up message; otherwise it starts a new child run.
25
24
 
26
- `repo` must be a repository other than the one the parent agent is working in — never delegate into the parent's own repo. A repo has at most one active child: if it already has one, pass `taskId` to route the message to it instead of starting a new run.
25
+ `repo` must be a repository other than the one the parent agent is working in — never delegate into the parent's own repo. A repo has at most one active child: while one is active, any `spawn_agent` call for that repo is routed to it as a follow-up rather than starting a second run.
27
26
 
28
27
  **Resume/reconstruction is read-only.** If the parent asks you to resume, reconnect, restore, or reconstruct a preserved session without an explicit new change request from the user, do not call `spawn_agent` to continue work. Use `show_agent` only as needed to read status/log context, return a concise restoration summary, and stop. After resuming, wait for explicit user instructions before any child agent makes changes.
29
28
 
@@ -32,8 +31,7 @@ spawn_agent(
32
31
  sessionId: "<sessionId>",
33
32
  repo: "<repo>",
34
33
  instruction: "<instruction>",
35
- context: "<context>",
36
- taskId: "<taskId>" // optional - pass only for a user-approved follow-up to an active task
34
+ context: "<context>"
37
35
  )
38
36
  ```
39
37
 
@@ -62,8 +60,6 @@ After calling `spawn_agent`, parse the structured JSON response:
62
60
  { "taskId": "…", "message": "…", "status": "delegated" }
63
61
  ```
64
62
 
65
- Store the returned `taskId`. You will pass it back to `spawn_agent` on any follow-up turn so the orchestrator routes the message to the same active task instead of starting a new run.
66
-
67
63
  Then poll `show_agent` on a backoff cadence. **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.
68
64
 
69
65
  For each child in the response (field: `children[]`), inspect:
@@ -80,7 +76,7 @@ State machine:
80
76
  - Read `child.inputRequiredQuestion`.
81
77
  - Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
82
78
  - Wait for the parent/user to supply an answer.
83
- - Call `spawn_agent` again with `instruction: <the answer>` and `taskId: <stored taskId>` so the orchestrator routes the answer to the same active task.
79
+ - Call `spawn_agent` again with the same `repo` and `instruction: <the answer>` — the orchestrator routes it to the active task automatically.
84
80
  - Resume polling.
85
81
 
86
82
  <!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
package/agents/polygraph-init-subagent.toml CHANGED
@@ -11,7 +11,7 @@ These tools are available via MCP and CLI. Use whichever is available in your en
11
11
 
12
12
  | MCP Tool | CLI Equivalent | Description |
13
13
  | --- | --- | --- |
14
- | `list_repos` | `polygraph repo list` | Discover candidate repositories with descriptions and graph relationships |
14
+ | `list_repos` | `polygraph repo list` | Discover candidate repositories. |
15
15
  | `start_session` | `polygraph session start --repo <ids>` | Initialize a NEW session with selected repositories. Only use when no `sessionId` was provided. |
16
16
  | `add_repo` | — | Attach repositories to an EXISTING session. Use when `sessionId` was provided and the session has no repos yet, or when the user wants to add more. |
17
17
  | `show_session` | `polygraph session show <id> [--details]` | Get full session details including URL, and use details when session summary, repo IDs, PR URLs, and PR descriptions are needed |
@@ -54,16 +54,22 @@ Call `list_repos` to discover available candidate repositories:
54
54
  list_repos()
55
55
  ```
56
56
 
57
+ `list_repos` accepts these optional parameters; set whichever apply. Refer to the tool schema for each parameter.
58
+
59
+ - `connectedTo`: repo ID, name, or full name (e.g. `nrwl/ocean`); pair with `connectionType`
60
+ - `connectionType`: `directly-upstream` | `directly-downstream` | `directly-both` (default) | `upstream` | `downstream` | `both`
61
+ - `publishedPackages`, `consumedPackages`, `publishedApis`, `consumedApis`: arrays of package names / API paths
62
+ - `nameFilter`: array of repo name patterns (e.g. `nrwl/*`)
63
+ - `semanticQuery`: free-text description of the repositories you want
64
+
57
65
  This returns:
58
66
 
59
- - **`initiator`**: The current repository, or `null` if not running from a specific repo
60
- - **`candidates`**: Candidate account repositories, each with:
67
+ - **`repos`**: Candidate account repositories, each with:
61
68
  - `id`: Repository ID
62
69
  - `name`: Repository name
70
+ - `repository`: Full repo name (e.g., `org/repo`)
71
+ - `provider`: VCS provider (e.g., `GITHUB`)
63
72
  - `description`: AI-generated description of what the repository does (may be null)
64
- - `vcsConfiguration.repositoryFullName`: Full repo name (e.g., `org/repo`)
65
- - `graphRelationship`: How this repository relates to the initiator (`distance`, `direction`, `path`), or `null` if the repository is not in the dependency graph. When `initiator` is null, `graphRelationship` will be null for all candidates.
66
- - **`dependencyGraph`**: Graph of repository dependency `edges` (always available, independent of initiator)
67
73
 
68
74
  ### Step 2: Select Relevant Repos
69
75
 
@@ -73,14 +79,11 @@ If `selectedRepoIds` or exact repo refs were provided by the main agent, use tho
73
79
 
74
80
  Otherwise, analyze the candidates using the `userContext` to determine which repos are relevant:
75
81
 
76
- 1. Read each candidate's `description` and `graphRelationship`
77
- 2. Match against the `userContext` — consider:
78
- - Repository descriptions that mention relevant functionality
79
- - Graph relationships (closer repos are more likely relevant); note that `graphRelationship` may be `null` for repositories not in the dependency graph — use their `description` to assess relevance
80
- - When `graphRelationship` is null for all candidates (no initiator), rely on `description` fields and the raw `dependencyGraph` edges for selection instead
81
- - Direction (upstream/downstream based on the nature of the change)
82
- 3. Select only the repos that are clearly relevant to the task
83
- 4. If uncertain which repos are relevant, include all candidates (safe default)
82
+ 1. Read each repo's `description`
83
+ 2. Match repo descriptions against the `userContext` to identify relevant repos
84
+ 3. Select the repos that are relevant to the task
85
+ 4. When uncertain, include all candidates
86
+ 5. When the user described the task in natural language and the result is large, re-query with `semanticQuery` set to that description
84
87
 
85
88
  ### Step 3: Initialize Polygraph Session or Attach Repos
86
89
 
@@ -136,11 +139,6 @@ Return a structured summary in this format:
136
139
  | Repo | Repository ID | Description | Selected |
137
140
  | --- | --- | --- | --- |
138
141
  | REPO_FULL_NAME | REPOSITORY_ID | DESCRIPTION | Yes/No |
139
-
140
- ### Initiator
141
- (Only include this section if `list_repos` was called and `initiator` is non-null)
142
- - **Name:** <initiator name>
143
- - **Repo:** <initiator repo full name>
144
142
  ```
145
143
 
146
144
  ## Important Notes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@polygraph/codex-plugin",
3
- "version": "0.4.27",
3
+ "version": "0.4.29",
4
4
  "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
package/skills/polygraph/SKILL.md CHANGED
@@ -16,7 +16,7 @@ Read this before the tool table below — it determines which tools are yours to
16
16
  - **For new sessions:** call Codex `spawn_agent` with `agent_type: "polygraph-init-subagent"`. Do NOT call Polygraph MCP `list_repos` or `start_session` directly from this conversation.
17
17
  - **For explicit repo additions to an existing session:** if the user gives exact refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, call Polygraph MCP `add_repo` directly with those refs. Do NOT call `list_repos` or launch candidate discovery first.
18
18
  - **For repo work:** call Codex `spawn_agent` with `agent_type: "polygraph-delegate-subagent"`. Do NOT call Polygraph MCP `spawn_agent` or `show_agent` directly from this conversation; collect results with `wait_agent` when needed.
19
- - **Allowed direct Polygraph MCP calls from the parent:** `whoami`, `login`, `list_accounts`, `select_account`, `show_session` for read-only inspection of an existing session, `update_session_description` for session metadata updates, `link_reference` for linking external references to sessions, and `add_repo` only for explicit repo additions to an existing session.
19
+ - **Allowed direct Polygraph MCP calls from the parent:** `whoami`, `login`, `list_accounts`, `select_account`, `show_session` for read-only inspection of an existing session, `update_session` for session metadata updates, `link_reference` for linking external references to sessions, and `add_repo` only for explicit repo additions to an existing session.
20
20
  - Do NOT pass `fork_context: true` to Codex `spawn_agent` when `agent_type` is a custom agent — Codex rejects it.
21
21
 
22
22
  Polygraph connects repositories and the agent work happening across them. Its central artifact is the session, which groups the repositories, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repositories, and also on its own to share the session URL with collaborators, hand off progress via the session description, resume prior work, and watch CI across the session's PRs.
@@ -29,25 +29,27 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
29
29
 
30
30
  | MCP Tool | CLI Equivalent | Description |
31
31
  | --- | --- | --- |
32
- | `list_repos` | `polygraph repo list` | Discover candidate repositories with descriptions and graph relationships |
32
+ | `list_repos` | `polygraph repo list` | Discover candidate repositories. |
33
33
  | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
34
- | `spawn_agent` | — | Start a new child task or send an explicit follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context?, taskId? }`. Output: `{ taskId, message, status: 'delegated' }`. Pass the `taskId` returned by a prior call to route a follow-up message to a specific active task; omit to start a new child run. A repo has at most one active child at a time: while a task is active in a repo, pass `taskId` to follow up — never start a second concurrent run in the same repo. 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. |
35
- | `show_agent` | — | Poll flat per-child status for the session. Output: `{ children: PolygraphChildStatusItem[] }` where each item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. |
34
+ | `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. |
35
+ | `show_agent` | — | Poll flat per-child status for the session. Output: `{ children: PolygraphChildStatusItem[] }` where each 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'`. |
36
36
  | `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. |
37
37
  | `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. |
38
38
  | `create_pr` | — | Create draft PRs with session metadata linking related PRs |
39
39
  | `show_session` | `polygraph session show <id> [--details]` | Query status of the current session. Use details when session summary, repo IDs, PR URLs, and PR descriptions are needed. |
40
- | `update_session_description` | `polygraph session update-description` | Set the current session description from a synthesized progress summary or user-provided text. This updates session metadata only; it does not require PR creation or mark-ready. |
40
+ | `update_session` | `polygraph session update --session <id> [--title] [--description]` | Update the session title and/or description (at least one required). Set the description from a synthesized progress summary or user-provided text. This updates session metadata only; it does not require PR creation or mark-ready. |
41
41
  | `link_reference` | — | Link an external reference to a session. |
42
42
  | `mark_pr_ready` | — | Mark draft PRs as ready for review |
43
43
  | `associate_pr` | — | Associate an existing PR with a session |
44
44
  | `add_repo` | — | Add repositories to a running Polygraph session. For explicit refs, pass the refs directly and skip `list_repos`. |
45
45
  | `archive_session` | `polygraph session archive <id>` | Archive a session, hiding it from active lists (it can still be resumed) |
46
46
  | `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job |
47
- | — | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
48
- | — | `polygraph session list` | List all sessions |
49
- | — | `polygraph account list` / `polygraph account select` | Organization management |
50
- | — | `polygraph whoami` | Show current auth status and org |
47
+ | `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
48
+ | `logout` | `polygraph auth logout` | Log out of Polygraph |
49
+ | `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. |
50
+ | `list_accounts` | `polygraph account list` | List available organizations |
51
+ | `select_account` | `polygraph account select` | Select the organization that future commands run against |
52
+ | `whoami` | `polygraph whoami` | Show current auth status and org |
51
53
 
52
54
  **Routing reminder:** Per the Critical Routing Rule above, the parent conversation must use Codex `spawn_agent` with `agent_type: "polygraph-init-subagent"` for new sessions and `agent_type: "polygraph-delegate-subagent"` for repo work — not the Polygraph MCP tools shown in the table. `wait_agent` collects results when needed.
53
55
 
@@ -80,7 +82,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
80
82
  4. **Monitor child agents** - Use `show_agent` to poll progress and read the flat `children[]` array for each child's `status` and `lastOutputLines`.
81
83
  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.
82
84
  6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
83
- 7. **Update session description** - Use `update_session_description` to update the session description; must follow the Session Description Policy. Independent of PR creation or mark-ready.
85
+ 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.
84
86
  8. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
85
87
  9. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
86
88
  10. **Query PR status** - Use `show_session` to check progress.
@@ -234,11 +236,9 @@ Use this pattern when the child may need clarification, the task is exploratory,
234
236
  { "taskId": "…", "message": "…", "status": "delegated" }
235
237
  ```
236
238
 
237
- Store the returned `taskId`. You will pass it back on any follow-up turn so the orchestrator routes the message to the same active task instead of starting a new run.
238
-
239
239
  2. Poll `show_agent`. The response shape is `{ children: PolygraphChildStatusItem[] }`. For each child, inspect:
240
240
 
241
- - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
241
+ - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
242
242
  - `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`.
243
243
  - `child.lastOutputLines` — recent log tail.
244
244
  - `child.repoFullName` — which repo is talking.
@@ -246,10 +246,11 @@ Use this pattern when the child may need clarification, the task is exploratory,
246
246
  Drive the state machine:
247
247
 
248
248
  - `child.status === 'in-progress'` or `'created'` — continue polling.
249
- - `child.status === 'input-required'` — read `child.inputRequiredQuestion`, surface it to the user verbatim (e.g. "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}"), get the answer, then call `spawn_agent` again with `taskId: <stored taskId>` and `instruction: <answer>`. Continue polling.
249
+ - `child.status === 'input-required'` — read `child.inputRequiredQuestion`, surface it to the user verbatim (e.g. "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}"), get the answer, then call `spawn_agent` again with the same `repo` and `instruction: <answer>` — it is routed to the active task automatically. Continue polling.
250
250
  - `child.status === 'completed'` — read `child.lastOutputLines`, proceed to `push_branch` + `create_pr`.
251
251
  - `child.status === 'failed'` — read `child.lastOutputLines`, surface the failure.
252
252
  - `child.status === 'cancelled'` — the child was stopped via `stop_agent`; see below.
253
+ - `child.status === 'permission-required'` — the child is waiting on a permission decision; see "Handling permission requests" below.
253
254
 
254
255
  3. To abort mid-flight, call `stop_agent` with `{ sessionId, repo }`. The response is:
255
256
 
@@ -307,7 +308,7 @@ push_branch(
307
308
 
308
309
  `description` is user-facing Polygraph session context.
309
310
 
310
- `description` is required for `push_branch`, `create_pr`, `associate_pr`, and `update_session_description`. (`mark_pr_ready` does not take a description.) Use the canonical structured format:
311
+ `description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). (`mark_pr_ready` does not take a description.) Use the canonical structured format:
311
312
 
312
313
  ```text
313
314
  Goal: <what the session is trying to accomplish>
@@ -643,7 +644,7 @@ Before writing:
643
644
  - If appending a new item, read the current/latest description first and write the full replacement description with the existing items plus the new item.
644
645
  - If updating or replacing the existing last item, write the resulting state directly.
645
646
 
646
- Write the description using the canonical structured format in the Session Description Policy. Then call `update_session_description` with the resulting summary.
647
+ Write the description using the canonical structured format in the Session Description Policy. Then call `update_session` with the resulting summary as `description`.
647
648
 
648
649
  ### Print Polygraph Session Details
649
650
 
@@ -676,7 +677,7 @@ If the session has a description timeline, also display:
676
677
  1. **Poll child status before proceeding** — Always verify child agents have reached a terminal `child.status` (`'completed'`, `'failed'`, or `'cancelled'`) via `show_agent` before pushing branches or creating PRs
677
678
  1. **Link PRs in descriptions** - Reference related PRs in each PR body
678
679
  1. **Keep PRs as drafts** until all repos are ready
679
- 1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session_description` — it is required and must follow the Session Description Policy
680
+ 1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session` — it is required and must follow the Session Description Policy
680
681
  1. **Test integration** before marking PRs ready
681
682
  1. **Coordinate merge order** if there are deployment dependencies
682
683