@desplega.ai/agent-swarm 1.56.4 → 1.56.6

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.56.4",
+    "version": "1.56.5",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -1415,6 +1415,237 @@
         }
       }
     },
+    "/api/keys/report-usage": {
+      "post": {
+        "summary": "Record which API key was used for a task",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyType": {
+                    "type": "string"
+                  },
+                  "keySuffix": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 10
+                  },
+                  "keyIndex": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "taskId": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "scope": {
+                    "type": "string"
+                  },
+                  "scopeId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "keyType",
+                  "keySuffix",
+                  "keyIndex"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Usage recorded"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/keys/report-rate-limit": {
+      "post": {
+        "summary": "Mark an API key as rate-limited",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyType": {
+                    "type": "string"
+                  },
+                  "keySuffix": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 10
+                  },
+                  "keyIndex": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "rateLimitedUntil": {
+                    "type": "string",
+                    "format": "date-time"
+                  },
+                  "scope": {
+                    "type": "string"
+                  },
+                  "scopeId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "keyType",
+                  "keySuffix",
+                  "keyIndex",
+                  "rateLimitedUntil"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Key marked as rate-limited"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/keys/available": {
+      "get": {
+        "summary": "Get available (non-rate-limited) key indices for a credential type",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "keyType",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "required": true,
+            "name": "totalKeys",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "scope",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "scopeId",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of available key indices"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/keys/status": {
+      "get": {
+        "summary": "Get all API key status records",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "keyType",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "scope",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "scopeId",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of key status records"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/events": {
       "post": {
         "summary": "Store a single event",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.56.4",
+  "version": "1.56.6",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/plugin/commands/close-issue.md

@@ -13,78 +13,26 @@ Close a GitHub or GitLab issue with an appropriate closing comment summarizing t
 
 ## Arguments
 
-- `issue-number-or-url`: Either an issue number (e.g., `123`) or a full issue URL (e.g., `https://github.com/owner/repo/issues/123` or `https://gitlab.com/group/project/-/issues/123`)
+- `issue-number-or-url`: Either an issue number (e.g., `123`) or a full issue URL
 
 ## Workflow
 
-### 1. Parse the Input
-
-If given a URL, extract the owner, repo, and issue number. If given just a number, use the current repository context.
-
-### 2. Ensure Repository is Cloned Locally
-
-Make sure the repository is available in your personal workspace:
-
-```bash
-REPO_PATH=/workspace/personal/<repo-name>
-
-if [ ! -d "$REPO_PATH" ]; then
-  gh repo clone <owner>/<repo> "$REPO_PATH"
-fi
-
-cd "$REPO_PATH"
-```
-
-### 3. Get Issue Details
-
-```bash
-gh issue view <issue-number> --json title,body,author,labels,comments
-```
-
-### 4. Understand the Context
-
-Review:
-- What was the original issue about?
-- What work was done to resolve it?
-- Were there any related PRs or commits?
-
-Check for related PRs:
-
-```bash
-gh pr list --search "fixes #<issue-number>" --json number,title,state
-```
-
-### 5. Generate Closing Comment
-
-Write a closing comment that includes:
-- Brief summary of what was done
-- Reference to any PRs that addressed the issue
-- Any follow-up items or notes
-
-### 6. Post Comment and Close
-
-```bash
-# Add the closing comment
-gh issue comment <issue-number> --body "Your closing comment"
-
-# Close the issue
-gh issue close <issue-number>
-```
-
-Or combine with a reason:
-
-```bash
-gh issue close <issue-number> --comment "Your closing comment" --reason completed
-```
+1. **Parse the input** — if given a URL, extract owner, repo, and issue number. If just a number, use the current repo context.
+2. **Ensure repo is cloned** to `/workspace/personal/<repo-name>` (clone with `gh repo clone` if needed).
+3. **Get issue details** — read the issue title, body, comments, and check for related PRs.
+4. **Generate closing comment** — summarize what was done, reference related PRs/commits, note any follow-ups.
+5. **Post comment and close:**
+   ```bash
+   gh issue close <issue-number> --comment "Your closing comment" --reason completed
+   ```
 
 ## Closing Reasons
 
-- `completed` - The issue was resolved
-- `not_planned` - Won't fix / out of scope / duplicate
+- `completed` — The issue was resolved
+- `not_planned` — Won't fix / out of scope / duplicate
 
 ## Tips
 
 - Always explain why the issue is being closed
 - Reference specific PRs or commits when applicable
 - If closing as "not planned", explain the reasoning
-- Be respectful - someone took time to report the issue

package/plugin/commands/create-pr.md

@@ -5,15 +5,15 @@ argument-hint: [base-branch]
 
 # Create Pull Request / Merge Request
 
-Create a pull request (GitHub) or merge request (GitLab) from the current branch with an auto-generated title and description.
+Create a PR (GitHub) or MR (GitLab) from the current branch with an auto-generated title and description.
 
-**Provider detection:** Check the remote URL to determine the VCS provider:
-- If the remote contains `github.com` → use `gh` CLI
-- If the remote contains `gitlab.com` or `gitlab.` → use `glab` CLI
+**Provider detection:** Check the remote URL:
+- If `github.com` → use `gh` CLI
+- If `gitlab.com` or `gitlab.` → use `glab` CLI
 
 ## Arguments
 
-- `base-branch` (optional): The branch to merge into (defaults to `main` or the repo's default branch)
+- `base-branch` (optional): Branch to merge into (defaults to `main` or repo default)
 
 ## Prerequisites
 
@@ -21,79 +21,17 @@ You should be working in a repository cloned to `/workspace/personal/<repo-name>
 
 ## Workflow
 
-### 1. Verify Working Directory
-
-Ensure you're in a git repository:
-
-```bash
-git rev-parse --is-inside-work-tree
-```
-
-### 2. Check Branch Status
-
-```bash
-# Get current branch
-git branch --show-current
-
-# Ensure we're not on main/master
-# Ensure there are commits to push
-git log origin/main..HEAD --oneline
-```
-
-### 3. Push the Branch
-
-```bash
-git push -u origin HEAD
-```
-
-### 4. Gather Context for PR Description
-
-```bash
-# Get commit messages since diverging from base
-git log origin/main..HEAD --pretty=format:"%s%n%b"
-
-# Get changed files
-git diff --stat origin/main..HEAD
-```
-
-### 5. Generate PR Title and Description
-
-Based on the commits and changes:
-- **Title**: Concise summary of the changes (use conventional commit style if the repo uses it)
-- **Description**:
-  - Summary of what changed and why
-  - List of notable changes
-  - Any testing done
-  - Related issues (if applicable)
-
-### 6. Create the PR/MR
-
-**For GitHub:**
-```bash
-gh pr create \
-  --title "Your generated title" \
-  --body "Your generated description" \
-  --base main
-```
-
-**For GitLab:**
-```bash
-glab mr create \
-  --title "Your generated title" \
-  --description "Your generated description" \
-  --target-branch main
-```
-
-### 7. Report the PR/MR URL
-
-After creation, provide the URL to the user:
-
-**GitHub:** `gh pr view --json url --jq '.url'`
-**GitLab:** `glab mr view --web`
+1. **Verify state** — confirm you're in a git repo, not on main/master, and have commits to push.
+2. **Push the branch** — `git push -u origin HEAD`
+3. **Gather context** — review commit messages and changed files since diverging from base.
+4. **Generate title and description:**
+   - **Title**: Concise summary (conventional commit style if the repo uses it)
+   - **Description**: Summary of changes, notable items, testing done, related issues
+5. **Create the PR/MR** using `gh pr create` or `glab mr create`.
+6. **Report** the PR/MR URL.
 
 ## Tips
 
 - Link related issues using `Fixes #123` or `Closes #123` in the description
-- Include a test plan if the changes are significant
-- Keep PRs focused - one logical change per PR
-- If the branch has many commits, consider summarizing the overall change rather than listing each commit
+- Keep PRs focused — one logical change per PR
+- If the branch has many commits, summarize the overall change rather than listing each commit

package/plugin/commands/implement-issue.md

@@ -5,131 +5,55 @@ argument-hint: <issue-number-or-url>
 
 # Implement Issue
 
-Read a GitHub or GitLab issue, implement the requested changes, and create a pull request / merge request.
+Read a GitHub or GitLab issue, implement the requested changes, and create a PR/MR.
 
-**Provider detection:** Check the URL or remote to determine the VCS provider:
+**Provider detection:** Check the URL or remote:
 - If GitHub → use `gh issue view` / `gh pr create`
 - If GitLab → use `glab issue view` / `glab mr create`
 
 ## Arguments
 
-- `issue-number-or-url`: Either an issue number (e.g., `123`) or a full URL (e.g., `https://github.com/owner/repo/issues/123` or `https://gitlab.com/group/project/-/issues/123`)
+- `issue-number-or-url`: Either an issue number (e.g., `123`) or a full URL
 
 ## Workflow
 
-### 1. Parse the Input
+### 1. Parse and Fetch
 
-If given a URL, extract the owner, repo, and issue number. If given just a number, use the current repository context.
+If given a URL, extract owner, repo, and issue number. Fetch issue details (title, body, labels, comments). Understand what's being requested, acceptance criteria, and any technical constraints.
 
-### 2. Fetch Issue Details
+### 2. Setup
 
-```bash
-gh issue view <issue-number> --json number,title,body,labels,comments
-```
+- Ensure repo is cloned to `/workspace/personal/<repo-name>` (clone with `gh repo clone` if needed)
+- Fetch origin, checkout main, pull latest
+- Create a feature branch: `fix/issue-<number>-<short-description>`
 
-Read and understand:
-- What is being requested?
-- Are there acceptance criteria?
-- Any technical details or constraints mentioned?
-- Check comments for additional context or clarifications
+### 3. Implement
 
-### 3. Ensure Repository is Cloned
-
-Clone the repository to your personal workspace if not already present:
-
-```bash
-REPO_PATH=/workspace/personal/<repo-name>
-
-if [ ! -d "$REPO_PATH" ]; then
-  gh repo clone <owner>/<repo> "$REPO_PATH"
-fi
-
-cd "$REPO_PATH"
-git fetch origin
-git checkout main
-git pull origin main
-```
-
-### 4. Create a Feature Branch
-
-```bash
-# Use a descriptive branch name based on the issue
-git checkout -b fix/issue-<number>-<short-description>
-
-# Examples:
-# git checkout -b fix/issue-123-add-dark-mode
-# git checkout -b fix/issue-456-fix-login-redirect
-```
-
-### 5. Implement the Changes
-
-This is the core work. Based on the issue:
-
-1. **Understand the codebase** - Explore relevant files, understand existing patterns
-2. **Plan your approach** - Consider using `/desplega:create-plan` for complex changes
-3. **Write the code** - Implement the requested functionality
-4. **Test your changes** - Run existing tests, add new tests if appropriate
-5. **Verify it works** - Manual verification where possible
+1. **Understand the codebase** — explore relevant files and existing patterns
+2. **Plan your approach** — consider using `/desplega:create-plan` for complex changes
+3. **Write the code** — implement the requested functionality
+4. **Test your changes** — run existing tests, add new tests if appropriate
+5. **Verify it works** — manual verification where possible
 
 Keep changes focused on what the issue requests. Avoid scope creep.
 
-### 6. Commit Your Changes
-
-```bash
-# Stage your changes
-git add -A
-
-# Commit with a message referencing the issue
-git commit -m "Fix #<issue-number>: <short description>
-
-<longer description if needed>"
-```
-
-Use conventional commit style if the repo uses it (e.g., `feat:`, `fix:`, `docs:`).
-
-### 7. Push the Branch
-
-```bash
-git push -u origin HEAD
-```
-
-### 8. Create the Pull Request
-
-```bash
-gh pr create \
-  --title "<descriptive title>" \
-  --body "## Summary
-<Brief description of what this PR does>
-
-## Changes
-- <List key changes>
-
-## Testing
-- <How you tested the changes>
-
-Fixes #<issue-number>"
-```
+### 4. Commit and Push
 
-The `Fixes #<number>` syntax will auto-close the issue when the PR is merged.
+Commit with a message referencing the issue (e.g., `Fix #123: <description>`). Use conventional commit style if the repo uses it. Push with `git push -u origin HEAD`.
 
-### 9. Report Back
+### 5. Create the PR
 
-Provide the user with:
-- PR URL
-- Summary of changes made
-- Any notes or caveats
+Create the PR with a descriptive title and body including: summary of changes, key changes list, testing done, and `Fixes #<issue-number>` to auto-close the issue on merge.
 
-Optionally, comment on the original issue:
+### 6. Report Back
 
-```bash
-gh issue comment <issue-number> --body "I've created a PR to address this: <PR-URL>"
-```
+Provide the PR URL, summary of changes, and any caveats. Optionally comment on the original issue linking the PR.
 
 ## Tips
 
-- Read the issue thoroughly before starting - misunderstanding wastes time
-- Check if there are related issues or existing PRs
-- Keep PRs focused - one issue = one PR
-- If the issue is too large, consider breaking it into smaller PRs
-- If you get stuck or the issue is unclear, use `/respond-github` to ask for clarification
+- Read the issue thoroughly before starting — misunderstanding wastes time
+- Check for related issues or existing PRs
+- One issue = one PR
+- If the issue is too large, break it into smaller PRs
+- If unclear, use `/respond-github` to ask for clarification
 - Run linters and tests before creating the PR