Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
@polygraph/claude-plugin
Advanced tools
@polygraph/claude-plugin - npm Package Compare versions
| { | ||
| "name": "polygraph", | ||
| "version": "0.4.27", | ||
| "version": "0.4.28", | ||
| "description": "AI agent skills and subagents for Polygraph multi-repo coordination", | ||
@@ -5,0 +5,0 @@ "author": { |
@@ -30,9 +30,8 @@ --- | ||
| | `context` | (Optional) Additional context to pass to the child agent | | ||
| | `taskId` | (Optional) Existing active task to route a user-approved follow-up to; omit on the first call for a new run | | ||
| ## Delegating work | ||
| 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. | ||
| 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. | ||
| `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. | ||
| `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. | ||
@@ -46,4 +45,3 @@ **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. | ||
| instruction: "<instruction>", | ||
| context: "<context>", | ||
| taskId: "<taskId>" // optional - pass only for a user-approved follow-up to an active task | ||
| context: "<context>" | ||
| ) | ||
@@ -94,4 +92,2 @@ ``` | ||
| 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. | ||
| 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. | ||
@@ -113,3 +109,3 @@ | ||
| - Wait for the parent/user to supply an answer. | ||
| - Call `spawn_agent` again with `instruction: <the answer>` and `taskId: <stored taskId>` so the orchestrator routes the answer to the same active task. | ||
| - Call `spawn_agent` again with the same `repo` and `instruction: <the answer>` — the orchestrator routes it to the active task automatically. | ||
| - Resume polling. | ||
@@ -116,0 +112,0 @@ |
+1
-1
| { | ||
| "name": "@polygraph/claude-plugin", | ||
| "version": "0.4.27", | ||
| "version": "0.4.28", | ||
| "description": "AI agent skills and subagents for Polygraph multi-repo coordination", | ||
@@ -5,0 +5,0 @@ "license": "UNLICENSED", |
@@ -26,4 +26,4 @@ --- | ||
| | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories | | ||
| | `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. | | ||
| | `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'`. | | ||
| | `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. | | ||
| | `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'`. | | ||
| | `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. | | ||
@@ -33,3 +33,3 @@ | `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. | | ||
| | `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. | | ||
| | `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. | | ||
| | `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. | | ||
| | `link_reference` | — | Link an external reference to a session. | | ||
@@ -41,6 +41,8 @@ | `mark_pr_ready` | — | Mark draft PRs as ready for review | | ||
| | `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job | | ||
| | — | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) | | ||
| | — | `polygraph session list` | List all sessions | | ||
| | — | `polygraph account list` / `polygraph account select` | Organization management | | ||
| | — | `polygraph whoami` | Show current auth status and org | | ||
| | `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) | | ||
| | `logout` | `polygraph auth logout` | Log out of Polygraph | | ||
| | `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. | | ||
| | `list_accounts` | `polygraph account list` | List available organizations | | ||
| | `select_account` | `polygraph account select` | Select the organization that future commands run against | | ||
| | `whoami` | `polygraph whoami` | Show current auth status and org | | ||
@@ -78,3 +80,3 @@ **Delegation rules:** `list_repos` and `start_session` MUST be called via the `polygraph-init-subagent` as described in step 0. Direct `add_repo` is allowed only when the user provides exact repo refs for an existing session. `spawn_agent` and `show_agent` MUST ALWAYS be called via background Task subagents (`run_in_background: true`) as described in the delegation sections below — NEVER call them directly in the main conversation. The subagents are plugin-namespaced: pass `subagent_type: "polygraph:polygraph-init-subagent"` / `"polygraph:polygraph-delegate-subagent"`; fall back to the bare name only if the namespaced form is not found. | ||
| 6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy. | ||
| 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. | ||
| 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. | ||
| 8. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy. | ||
@@ -234,7 +236,5 @@ 9. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph. | ||
| 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. | ||
| 2. Poll `show_agent`. The response shape is `{ children: PolygraphChildStatusItem[] }`. For each child, inspect: | ||
| - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`). | ||
| - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`). | ||
| - `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`. | ||
@@ -247,6 +247,7 @@ - `child.lastOutputLines` — recent log tail. | ||
| - `child.status === 'in-progress'` or `'created'` — continue polling. | ||
| - `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. | ||
| - `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. | ||
| - `child.status === 'completed'` — read `child.lastOutputLines`, proceed to `push_branch` + `create_pr`. | ||
| - `child.status === 'failed'` — read `child.lastOutputLines`, surface the failure. | ||
| - `child.status === 'cancelled'` — the child was stopped via `stop_agent`; see below. | ||
| - `child.status === 'permission-required'` — the child is waiting on a permission decision; see "Handling permission requests" below. | ||
@@ -309,3 +310,3 @@ 3. To abort mid-flight, call `stop_agent` with `{ sessionId, repo }`. The response is: | ||
| `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: | ||
| `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: | ||
@@ -646,3 +647,3 @@ ```text | ||
| Write the description using the canonical structured format in the Session Description Policy. Then call `update_session_description` with the resulting summary. | ||
| Write the description using the canonical structured format in the Session Description Policy. Then call `update_session` with the resulting summary as `description`. | ||
@@ -680,3 +681,3 @@ ### Print Polygraph Session Details | ||
| 1. **Keep PRs as drafts** until all repos are ready | ||
| 1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session_description` — it is required and must follow the Session Description Policy | ||
| 1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session` — it is required and must follow the Session Description Policy | ||
| 1. **Test integration** before marking PRs ready | ||
@@ -683,0 +684,0 @@ 1. **Coordinate merge order** if there are deployment dependencies |
No alert changes
Worsened metrics
- Total package byte prevSize
99195
-0.01%No dependency changes