@awcp/mcp 0.0.7 → 0.0.8

package/dist/tools/delegate-cancel.txt

@@ -1,16 +1,25 @@
-Cancel background delegations.
+Cancel active delegations.
+
+## When to use
+
+- The delegation is taking longer than expected
+- You no longer need the result (e.g., found an alternative solution)
+- You want to abort and try a different approach
+
+Cancellation frees up remote executor resources promptly.
 
 ## Parameters
 - **delegation_id** (optional): Specific delegation ID to cancel
-- **all** (optional): Cancel all running delegations
+- **all** (optional): Cancel all running delegations for this session
+
+## Examples
 
-## Usage
-Cancel a specific delegation:
+### Cancel a specific delegation
 ```
 delegate_cancel(delegation_id: "dlg_abc123")
 ```
 
-Cancel all running delegations:
+### Cancel all running delegations
 ```
 delegate_cancel(all: true)
 ```

package/dist/tools/delegate-output.txt

@@ -1,22 +1,46 @@
-Retrieve output from a background delegation.
+Retrieve status or results from a background delegation.
+
+This is your primary tool for getting results after launching `delegate(background: true)`.
+
+## When to use
+
+- **Check progress**: See if a delegation is still running or has completed
+- **Retrieve results**: Get the final output once the task is done
+- **Wait for completion**: Block until the delegation finishes (use with `block: true`)
 
 ## Parameters
-- **delegation_id** (required): Delegation ID from the background delegation launch
-- **block** (optional): Wait for completion if still running
-- **timeout** (optional): Maximum seconds to wait (default: 60)
+- **delegation_id** (required): The ID returned from `delegate(background: true)`
+- **block** (optional): If true, waits for the delegation to complete before returning
+- **timeout** (optional): Maximum seconds to wait when blocking (default: 60)
+
+## Recommended usage
+
+After launching background delegations and completing other work, use `block: true` to wait for results:
 
-## Usage
-After launching a background delegation:
 ```
-delegate(background: true, ...) → "Delegation ID: dlg_abc123..."
+# Earlier: launched delegation
+delegate(background: true, ...) → "dlg_abc123"
+
+# Now: ready for the result
+delegate_output(delegation_id: "dlg_abc123", block: true, timeout: 300)
 ```
 
-Check or retrieve results:
+For long-running tasks, increase the timeout accordingly.
+
+## Examples
+
+### Wait for result (most common)
+```
+delegate_output(delegation_id: "dlg_abc123", block: true, timeout: 120)
+```
+
+### Quick status check (non-blocking)
 ```
 delegate_output(delegation_id: "dlg_abc123")
 ```
 
-Wait for completion:
+### Collect multiple results
 ```
-delegate_output(delegation_id: "dlg_abc123", block: true, timeout: 120)
+delegate_output(delegation_id: "dlg_1", block: true)
+delegate_output(delegation_id: "dlg_2", block: true)
 ```

package/dist/tools/delegate.txt

@@ -1,21 +1,36 @@
-Delegate a workspace to a remote Executor for collaborative task execution.
+Delegate a workspace to a remote Executor for task execution.
 
-## When to use
+Delegation enables **parallel execution** — while the Executor works on one task, you can continue with other work or launch more delegations. This dramatically improves throughput compared to doing everything sequentially.
 
-Use delegation when:
-- Task requires a different environment or specialized toolset
-- You want to parallelize work across multiple agents
-- The remote agent has capabilities you lack (e.g., browser, GPU, specific SDKs)
+## Why delegate
 
-Do NOT use when:
-- Task is trivial and can be done locally
-- You need real-time back-and-forth interaction during execution
+- **Parallelism**: Run multiple tasks simultaneously instead of one-by-one
+- **Depth**: Executor can focus deeply on one task while you handle others
+- **Specialization**: Remote agents may have different tools, environments, or expertise
+- **Efficiency**: Offload substantial work and stay productive
+
+Consider delegating any task that would take significant time — tests, refactoring, code review, implementation of independent features, documentation, etc.
+
+## When NOT to delegate
+
+- Task requires real-time back-and-forth with the user
 
 ## Background mode
 
-**Prefer background=true by default.** This lets you launch multiple delegations in parallel and continue working.
+**Always prefer background=true.** This returns immediately with a delegation_id, letting you:
+- Launch multiple delegations in parallel
+- Continue with other work while waiting
+- Retrieve results later with `delegate_output`
+
+Use background=false **only** when you have nothing else to do and must wait for this result.
+
+## Typical workflow
+
+1. Launch delegation with `background: true`
+2. Continue with other independent work (local tasks, more delegations, etc.)
+3. When ready for results, call `delegate_output(delegation_id, block: true, timeout: ...)`
 
-Use background=false only when you cannot proceed without the result.
+This pattern maximizes parallelism and avoids idle waiting.
 
 ## Writing effective prompts
 
@@ -29,18 +44,23 @@ Structure your prompt with:
 
 ## Examples
 
-### Parallel tasks
+### Launch and continue working
 ```
-delegate(background: true, description: "Fix linting errors", prompt: "...", workspace_dir: "/project", peer_url: "...")
-delegate(background: true, description: "Add unit tests", prompt: "...", workspace_dir: "/project", peer_url: "...")
+delegate(background: true, description: "Add unit tests", ...) → delegation_id: "dlg_abc"
+# ... do other work locally ...
+delegate_output(delegation_id: "dlg_abc", block: true, timeout: 300)
 ```
 
-### Synchronous (when result needed immediately)
+### Parallel delegations
 ```
-delegate(background: false, description: "Generate config", prompt: "Create tsconfig.json for...", workspace_dir: "/project", peer_url: "...")
+delegate(background: true, description: "Fix linting errors", ...) → "dlg_1"
+delegate(background: true, description: "Add unit tests", ...) → "dlg_2"
+# ... do other work ...
+delegate_output(delegation_id: "dlg_1", block: true)
+delegate_output(delegation_id: "dlg_2", block: true)
 ```
 
-### Read-only analysis
+### Synchronous (only when nothing else to do)
 ```
-delegate(description: "Code review", prompt: "Review the code for security issues...", workspace_dir: "/project", peer_url: "...", access_mode: "ro")
+delegate(background: false, description: "Generate config", ...)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awcp/mcp",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "MCP tools for AWCP delegation",
   "type": "module",
   "main": "dist/index.js",
@@ -21,10 +21,10 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@awcp/sdk": "^0.0.7",
-    "@awcp/core": "^0.0.7",
-    "@awcp/transport-archive": "^0.0.7",
-    "@awcp/transport-sshfs": "^0.0.7",
+    "@awcp/sdk": "^0.0.8",
+    "@awcp/core": "^0.0.8",
+    "@awcp/transport-archive": "^0.0.8",
+    "@awcp/transport-sshfs": "^0.0.8",
     "@a2a-js/sdk": "^0.3.5",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.0"