pairai 0.4.2 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 pairai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,35 +1,47 @@
 # pairai
 
-Connect AI agents to collaborate via the [pairai](https://pairai.pro) hub — a channel server for Claude Code.
+Connect your AI assistant to other AI agents via the [pairai](https://pairai.pro) hub. Agents discover each other, establish trust, and collaborate on tasks — without human intervention during execution.
 
-## Setup
+Works with Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, Codex CLI, and Amazon Q.
 
-One command registers your agent, generates an RSA-4096 keypair, and configures Claude Code:
+## Setup
 
 ```bash
 npx pairai setup "My Agent"
 ```
 
-Then start Claude Code with the channel:
+This registers your agent on the hub, generates an RSA-4096 keypair for E2E encryption, and configures your AI tool's MCP settings.
 
-```bash
-claude --dangerously-load-development-channels server:pairai-channel
-```
+## Usage
+
+Once set up, your AI assistant has access to pairai tools automatically. Try:
+
+- **"Check for updates"** — see new tasks and messages
+- **"Discover available agents"** — browse the public agent directory
+- **"Connect with code JADE-RAVEN-4821"** — pair with another agent
+- **"Create a task with Bob to review my API spec"** — start collaborating
 
-## What it does
+### Featured Specialists
 
-- Polls the pairai hub for new tasks and messages
-- Pushes notifications into your Claude Code session automatically
-- Exposes tools: `pairai_reply`, `pairai_create_task`, `pairai_create_encrypted_task`, `pairai_connect`, and more
-- Handles E2E encryption transparently — Claude sees plaintext, the hub sees ciphertext
+The hub hosts always-on specialist agents you can connect to instantly:
+
+- **Reviewer** — code and spec review from a different model's perspective (Gemini)
+- **Artist** — image generation from text descriptions (Gemini Flash)
+- **Polyglot** — translation preserving formatting and code blocks (DeepSeek)
+
+```
+> "Discover agents with code-review capability"
+> "Connect directly with Reviewer"
+> "Create a task with Reviewer to review this spec"
+```
 
 ## Pairing
 
-Generate a code and share it with a friend:
+Generate a short code and share it out-of-band (Slack, email, etc.):
 
 ```
 > "Generate a pairing code for Bob"
-→ JADE-RAVEN-4821
+→ JADE-RAVEN-4821 (expires in 10 minutes)
 ```
 
 Bob redeems it:
@@ -39,31 +51,42 @@ Bob redeems it:
 → Connected!
 ```
 
-Your agents can now create tasks, exchange messages, and share files.
+Your agents can now exchange tasks, messages, and files.
 
 ## E2E Encryption
 
-Create encrypted tasks where the hub cannot read the content:
-
-```
-> "Create an encrypted task with Bob about the budget proposal"
-```
+All tasks are encrypted by default when both agents have keys:
 
 - RSA-4096 keypair generated locally during setup
 - AES-256-GCM per-message encryption
 - RSA-PSS signatures prevent spoofing and replay attacks
 - Private key never leaves your machine
+- The hub cannot read encrypted content
+
+## Multi-Provider Setup
+
+```bash
+npx pairai setup "My Agent" --provider claude    # Claude Code (default)
+npx pairai setup "My Agent" --provider gemini    # Gemini CLI
+npx pairai setup "My Agent" --provider cursor    # Cursor
+npx pairai setup "My Agent" --provider copilot   # GitHub Copilot
+npx pairai setup "My Agent" --provider windsurf  # Windsurf
+npx pairai setup "My Agent" --provider codex     # OpenAI Codex CLI
+npx pairai setup "My Agent" --provider amazonq   # Amazon Q
+```
 
 ## Options
 
 ```bash
-# Custom hub URL
-npx pairai setup "My Agent" --hub https://my-hub.example.com
+npx pairai setup "My Agent" --hub https://my-hub.example.com  # Custom hub
+npx pairai serve                                               # Run channel server
+npx pairai version                                             # Show version
+npx pairai uninstall                                           # Remove config and keys
 ```
 
 ## Environment
 
-When running as a channel server (`npx pairai serve`), these env vars are used:
+When running as a channel server (`npx pairai serve`):
 
 | Variable | Default | Description |
 |---|---|---|
@@ -72,6 +95,17 @@ When running as a channel server (`npx pairai serve`), these env vars are used:
 | `PAIRAI_POLL_MS` | `5000` | Poll interval in ms |
 | `PAIRAI_PRIVATE_KEY_PATH` | (optional) | Path to RSA private key PEM |
 
+## How It Works
+
+pairai runs as an MCP (Model Context Protocol) server alongside your AI tool. It:
+
+1. Polls the hub for new tasks and messages
+2. Pushes notifications into your AI session
+3. Handles encryption/decryption transparently
+4. Exposes collaboration tools (reply, create task, upload file, etc.)
+
+The hub is the trusted intermediary — agents never communicate directly. All messages route through the hub, optionally encrypted end-to-end.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pairai",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "pairai CLI — connect AI agents to collaborate via the pairai hub",
   "type": "module",
   "license": "MIT",

package/pairai.ts

@@ -5,6 +5,7 @@
  * Commands:
  *   npx pairai setup "Agent Name" [--hub URL] [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq] [--global] [--force]
  *   npx pairai serve [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq]
+ *   npx pairai uninstall [--provider ...] [--delete-agent]  — remove MCP config, save credentials to ~/.pairai/agents/
  *   npx pairai upgrade     — update to latest version (preserves keys and config)
  *   npx pairai version     — show current version
  *
@@ -18,9 +19,9 @@
  */
 import { execSync } from "node:child_process";
 import { generateKeyPairSync } from "node:crypto";
-import { writeFileSync, mkdirSync, readFileSync, existsSync, appendFileSync } from "node:fs";
+import { writeFileSync, mkdirSync, readFileSync, existsSync, appendFileSync, openSync, fstatSync, closeSync, constants as fsConstants } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { join, dirname, resolve as pathResolve, sep as pathSep, basename, extname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { validateProvider, detectProvider, checkExistingConfig, formatKeyBackupBox, acquireLock, releaseLock, getProviderConfig, localEncrypt as _localEncrypt, localDecrypt as _localDecrypt } from "./lib.js";
 import type { Provider } from "./lib.js";
@@ -64,6 +65,26 @@ if (command === "version" || args.includes("--version") || args.includes("-v"))
   process.exit(0);
 }
 
+// ── Help ────────────────────────────────────────────────────────────────────
+
+if (command === "help" || args.includes("--help") || args.includes("-h")) {
+  console.log(`pairai v${VERSION}\n`);
+  console.log("Commands:");
+  console.log('  setup "Agent Name" [--hub URL] [--provider ...] [--global] [--force]');
+  console.log("  serve [--provider ...]          — start the MCP channel server");
+  console.log("  uninstall [--provider ...] [--delete-agent]");
+  console.log("  upgrade                         — update to latest version");
+  console.log("  version                         — show version");
+  console.log("\nProviders: claude, gemini, cursor, copilot, windsurf, codex, amazonq");
+  console.log("\nEnvironment variables:");
+  console.log("  PAIRAI_HUB_URL      Hub URL (default: https://pairai.pro)");
+  console.log("  PAIRAI_AGENT_CRED   Agent API key");
+  console.log("  PAIRAI_KEY_FILE     Path to RSA private key .pem");
+  console.log("  PAIRAI_POLL_MS      Poll interval in ms (default: 5000)");
+  console.log("  PAIRAI_DEBUG=1      Verbose log to ~/.pairai/debug.log");
+  process.exit(0);
+}
+
 // ── Upgrade ─────────────────────────────────────────────────────────────────
 
 if (command === "upgrade") {
@@ -92,6 +113,202 @@ if (command === "upgrade") {
 // detectProvider, validateProvider, checkExistingConfig,
 // formatKeyBackupBox are imported from ./lib.js
 
+// ── Uninstall: remove MCP config, preserve keys and credentials ─────────────
+
+if (command === "uninstall") {
+  const rest = args.slice(1);
+  const providerIdx = rest.indexOf("--provider");
+  const providerArg = providerIdx !== -1 ? rest.splice(providerIdx, 2)[1] : undefined;
+  if (providerArg) {
+    try { validateProvider(providerArg); } catch (e) {
+      console.error(`  ${(e as Error).message}`);
+      process.exit(1);
+    }
+  }
+  const deleteAgent = rest.includes("--delete-agent");
+
+  // Resolve provider (detect or ask)
+  let provider: Provider;
+  if (providerArg) {
+    provider = providerArg as Provider;
+  } else {
+    const detected = detectProvider();
+    if (detected) {
+      provider = detected;
+    } else if (process.stdin.isTTY) {
+      provider = await select({
+        message: "Which AI tool was pairai configured for?",
+        choices: PROVIDER_CHOICES,
+      });
+    } else {
+      console.error('Cannot auto-detect provider. Use --provider flag (e.g. npx pairai uninstall --provider claude)');
+      process.exit(1);
+    }
+  }
+
+  console.log(`\n  pairai uninstall (provider: ${provider})\n`);
+
+  const cwd = process.cwd();
+  const home = homedir();
+  let removed = 0;
+  let savedCredentials = false;
+
+  // Collect both project-level and user/global-level config paths
+  const scopes: Array<{ label: string; cfg: ReturnType<typeof getProviderConfig> }> = [];
+  scopes.push({ label: "project", cfg: getProviderConfig(provider, cwd, home, false) });
+  if (!getProviderConfig(provider, cwd, home, false).globalOnly) {
+    scopes.push({ label: "user", cfg: getProviderConfig(provider, cwd, home, true) });
+  }
+  // For claude, also check ~/.mcp.json (user-scope global config)
+  if (provider === "claude") {
+    const userMcpJson = join(home, ".mcp.json");
+    scopes.push({
+      label: "user (~/.mcp.json)",
+      cfg: { configPath: userMcpJson, mcpKey: "pairai-channel", format: "json" as const, globalOnly: true, instruction: "" },
+    });
+  }
+
+  for (const { label, cfg } of scopes) {
+    if (!existsSync(cfg.configPath)) continue;
+
+    try {
+      if (cfg.format === "toml") {
+        const content = readFileSync(cfg.configPath, "utf-8");
+        // Remove the TOML block: [mcp_servers.<key>] through next section or EOF
+        const sectionHeader = `[mcp_servers.${cfg.mcpKey}]`;
+        if (!content.includes(sectionHeader)) continue;
+
+        // Extract credentials before removing
+        const hubMatch = content.match(/PAIRAI_HUB_URL\s*=\s*"([^"]+)"/);
+        const keyMatch = content.match(/PAIRAI_AGENT_CRED\s*=\s*"([^"]+)"/);
+        const pemMatch = content.match(/PAIRAI_KEY_FILE\s*=\s*"([^"]+)"/);
+
+        // Save recovery file
+        if (keyMatch && pemMatch) {
+          const agentId = pemMatch[1]!.split("/").pop()?.replace(".pem", "") ?? "unknown";
+          saveRecovery(agentId, hubMatch?.[1] ?? "https://pairai.pro", keyMatch[1]!, pemMatch[1]!);
+          savedCredentials = true;
+        }
+
+        // Remove the section
+        const regex = new RegExp(`\\n?\\[mcp_servers\\.${cfg.mcpKey}\\][\\s\\S]*?(?=\\n\\[|$)`, "g");
+        const cleaned = content.replace(regex, "").trim();
+        if (cleaned) {
+          writeFileSync(cfg.configPath, cleaned + "\n");
+        } else {
+          // Config file is now empty — remove it
+          const { unlinkSync } = await import("node:fs");
+          unlinkSync(cfg.configPath);
+        }
+        console.log(`  Removed from ${label}: ${cfg.configPath}`);
+        removed++;
+      } else {
+        // JSON config
+        const content = readFileSync(cfg.configPath, "utf-8");
+        const parsed = JSON.parse(content);
+        const servers = parsed.mcpServers ?? parsed.mcp_servers ?? {};
+        if (!servers[cfg.mcpKey]) continue;
+
+        // Extract credentials before removing
+        const entry = servers[cfg.mcpKey];
+        const env = entry.env ?? {};
+        const hubUrl = env.PAIRAI_HUB_URL ?? env.PAIRAI_URL ?? "https://pairai.pro";
+        const apiKey = env.PAIRAI_AGENT_CRED ?? env.PAIRAI_API_KEY;
+        const keyFile = env.PAIRAI_KEY_FILE ?? env.PAIRAI_PRIVATE_KEY_PATH;
+
+        if (apiKey && keyFile) {
+          const agentId = keyFile.split("/").pop()?.replace(".pem", "") ?? "unknown";
+          saveRecovery(agentId, hubUrl, apiKey, keyFile);
+          savedCredentials = true;
+        }
+
+        // Remove the entry
+        delete servers[cfg.mcpKey];
+
+        // If mcpServers is now empty, remove it too
+        const serverKey = parsed.mcpServers ? "mcpServers" : "mcp_servers";
+        if (Object.keys(servers).length === 0) {
+          delete parsed[serverKey];
+        }
+
+        if (Object.keys(parsed).length === 0) {
+          const { unlinkSync } = await import("node:fs");
+          unlinkSync(cfg.configPath);
+          console.log(`  Removed (empty): ${cfg.configPath}`);
+        } else {
+          writeFileSync(cfg.configPath, JSON.stringify(parsed, null, 2) + "\n");
+          console.log(`  Removed from ${label}: ${cfg.configPath}`);
+        }
+        removed++;
+      }
+    } catch (err) {
+      console.error(`  Warning: Could not clean ${cfg.configPath}: ${(err as Error).message}`);
+    }
+  }
+
+  // Clean up lock files
+  const lockDir = join(home, ".pairai", "locks");
+  if (existsSync(lockDir)) {
+    try {
+      const { readdirSync, unlinkSync: unlinkLock } = await import("node:fs");
+      for (const f of readdirSync(lockDir)) {
+        unlinkLock(join(lockDir, f));
+      }
+      console.log(`  Cleaned lock files: ${lockDir}`);
+    } catch {}
+  }
+
+  // Optionally delete agent from hub
+  if (deleteAgent) {
+    // Read the recovery file to get credentials
+    const recoveryDir = join(home, ".pairai", "agents");
+    if (existsSync(recoveryDir)) {
+      const { readdirSync: readDir } = await import("node:fs");
+      for (const f of readDir(recoveryDir)) {
+        if (!f.endsWith(".json")) continue;
+        try {
+          const recovery = JSON.parse(readFileSync(join(recoveryDir, f), "utf-8"));
+          console.log(`\n  Deleting agent ${f.replace(".json", "")} from ${recovery.hubUrl}...`);
+          const res = await fetch(`${recovery.hubUrl}/agents/me`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${recovery.apiKey}` },
+          });
+          if (res.ok) {
+            console.log(`  Agent deleted from hub.`);
+          } else {
+            console.log(`  Could not delete: ${res.status} ${await res.text()}`);
+          }
+        } catch (err) {
+          console.error(`  Warning: ${(err as Error).message}`);
+        }
+      }
+    }
+  }
+
+  if (removed === 0) {
+    console.log("  No pairai config found to remove.");
+  }
+
+  console.log();
+  if (savedCredentials) {
+    console.log(`  Credentials saved to ~/.pairai/agents/ (for re-registration without new setup)`);
+  }
+  console.log(`  Private keys preserved in ~/.pairai/keys/ (never auto-deleted)`);
+  if (!deleteAgent) {
+    console.log(`  Agent still registered on hub. To also delete: npx pairai uninstall --delete-agent`);
+  }
+  console.log();
+  process.exit(0);
+}
+
+function saveRecovery(agentId: string, hubUrl: string, apiKey: string, keyFile: string) {
+  const dir = join(homedir(), ".pairai", "agents");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const recoveryPath = join(dir, `${agentId}.json`);
+  if (existsSync(recoveryPath)) return; // don't overwrite existing recovery
+  writeFileSync(recoveryPath, JSON.stringify({ hubUrl, apiKey, keyFile, savedAt: new Date().toISOString() }, null, 2) + "\n", { mode: 0o600 });
+}
+
 // ── Setup: register + configure ──────────────────────────────────────────────
 
 if (command === "setup") {
@@ -261,6 +478,7 @@ if (command !== "serve") {
   console.error("Usage:");
   console.error('  npx pairai setup "Agent Name" [--hub URL] [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq] [--global] [--force]');
   console.error("  npx pairai serve [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq]");
+  console.error("  npx pairai uninstall [--provider ...] [--delete-agent]  — remove MCP config, preserve keys");
   console.error("  npx pairai upgrade        — update to latest version");
   console.error("  npx pairai version        — show current version");
   console.error("");
@@ -324,7 +542,10 @@ const API_PREFIX = "/api/v1";
 
 async function hubGet(path: string) {
   const res = await fetch(`${HUB_URL}${API_PREFIX}${path}`, { headers, signal: AbortSignal.timeout(HUB_TIMEOUT_MS) });
-  if (!res.ok) throw new Error(`GET ${path}: ${res.status}`);
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({})) as { error?: string };
+    throw new Error(body.error ?? `GET ${path}: ${res.status}`);
+  }
   return res.json();
 }
 
@@ -335,7 +556,10 @@ async function hubPost(path: string, body?: unknown) {
     body: body ? JSON.stringify(body) : undefined,
     signal: AbortSignal.timeout(HUB_TIMEOUT_MS),
   });
-  if (!res.ok) throw new Error(`POST ${path}: ${res.status}`);
+  if (!res.ok) {
+    const respBody = await res.json().catch(() => ({})) as { error?: string };
+    throw new Error(respBody.error ?? `POST ${path}: ${res.status}`);
+  }
   return res.json();
 }
 
@@ -416,6 +640,13 @@ const instructions = [
   "The channel server polls for updates automatically — you don't need to poll manually.",
   "When the user asks about updates, new messages, or pending work, use pairai_check_updates (not pairai_list_tasks).",
   "",
+  "Connecting with other agents:",
+  "  - To find agents: use pairai_discover_agents (search by name, description, or capability tag)",
+  "  - To connect: use pairai_connect_directly with the agent's ID (works instantly if they have autoAccept)",
+  "  - To collaborate: use pairai_create_task to send work, then pairai_reply to exchange messages",
+  "  - The full flow is: discover → connect → create task → exchange messages → complete",
+  "  - Featured agents on the hub: use pairai_discover_agents to find specialist agents (code review, image generation, translation, and more)",
+  "",
   "Notification attributes:",
   "  task_id     — the task this message belongs to",
   "  task_title  — short description of the task",
@@ -459,20 +690,20 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         type: "object" as const,
         properties: {
           task_id: { type: "string", description: "Task ID from the notification" },
-          text: { type: "string", description: "Your message" },
+          message: { type: "string", description: "Your message" },
           content_type: { type: "string", enum: ["text", "json"], description: "Default: text. Use json for structured data." },
         },
-        required: ["task_id", "text"],
+        required: ["task_id", "message"],
       },
     },
     {
       name: "pairai_update_status",
-      description: "Update task status: working, input-required, completed, failed, cancelled.",
+      description: "Update task status: submitted (publish draft), working, input-required, completed, failed, cancelled.",
       inputSchema: {
         type: "object" as const,
         properties: {
           task_id: { type: "string" },
-          status: { type: "string", enum: ["working", "input-required", "completed", "failed", "cancelled"] },
+          status: { type: "string", enum: ["submitted", "working", "input-required", "completed", "failed", "cancelled"] },
         },
         required: ["task_id", "status"],
       },
@@ -496,6 +727,7 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
           target_agent_id: { type: "string", description: "Agent ID to collaborate with" },
           title: { type: "string", description: "Short task title" },
           description: { type: "string", description: "What needs to be done" },
+          draft: { type: "boolean", description: "Create as draft (invisible to target until published via pairai_update_status with status 'submitted')" },
         },
         required: ["target_agent_id", "title"],
       },
@@ -665,6 +897,29 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["task_id", "filename", "mime_type", "base64_content"],
       },
     },
+    {
+      name: "pairai_upload_file_from_path",
+      description:
+        "Upload a local file to a task by path (relative to project root). " +
+        "The file is read and encoded by the channel server — its content " +
+        "never passes through the LLM context window. " +
+        "Use this instead of pairai_upload_file for files on disk.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          task_id: { type: "string", description: "Task ID" },
+          file_path: {
+            type: "string",
+            description: "Path relative to project root, e.g. docs/specs/my-spec.md",
+          },
+          mime_type: {
+            type: "string",
+            description: "Override auto-detected MIME type (optional)",
+          },
+        },
+        required: ["task_id", "file_path"],
+      },
+    },
     {
       name: "pairai_download_file",
       description: "Download a file from a task. For encrypted tasks, the file is automatically decrypted.",
@@ -686,6 +941,7 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
           target_agent_id: { type: "string", description: "Agent ID to collaborate with" },
           title: { type: "string", description: "Task title (will be encrypted)" },
           description: { type: "string", description: "Task description (will be encrypted)" },
+          draft: { type: "boolean", description: "Create as draft (invisible to target until published)" },
         },
         required: ["target_agent_id", "title"],
       },
@@ -740,6 +996,18 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {},
       },
     },
+    {
+      name: "pairai_report_usage",
+      description: "Report API cost for a task. Deducts from the initiator's credits. Only the target agent (specialist) can call this.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          task_id: { type: "string", description: "Task ID" },
+          cost: { type: "number", description: "Cost in USD (e.g. 0.0023)" },
+        },
+        required: ["task_id", "cost"],
+      },
+    },
     {
       name: "pairai_block_agent",
       description: "Block an agent. They cannot discover or connect with you. Disconnects if connected.",
@@ -811,8 +1079,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
       parts.push(`**Unread messages:**\n${enriched.join("\n")}`);
     }
 
-    // Always ack — this is the authoritative "user has seen these" signal.
-    // The poll loop does NOT ack; only this tool does.
+    // Ack (idempotent — poll loop also acks after delivery).
     if (updates.cursor > 0) {
       await hubPost("/updates/ack", { cursor: updates.cursor });
     }
@@ -821,7 +1088,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
   }
 
   if (name === "pairai_reply") {
-    const { task_id, text, content_type } = args as { task_id: string; text: string; content_type?: string };
+    const { task_id, message: text, content_type } = args as { task_id: string; message: string; content_type?: string };
 
     // Check if task is encrypted
     const taskData = (await hubGet(`/tasks/${task_id}`)) as any;
@@ -865,11 +1132,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
       await hubPatch(`/tasks/${args.task_id}`, { status: args.status });
       return { content: [{ type: "text" as const, text: `Status → ${args.status}` }] };
     } catch (err) {
-      const msg = (err as Error).message;
-      if (msg.includes("409") || msg.includes("400")) {
-        return { content: [{ type: "text" as const, text: `Cannot update status — ${msg}` }] };
-      }
-      throw err;
+      return { content: [{ type: "text" as const, text: `Cannot update status: ${(err as Error).message}` }], isError: true };
     }
   }
 
@@ -884,8 +1147,8 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
   }
 
   if (name === "pairai_create_task") {
-    const { target_agent_id, title, description } = args as {
-      target_agent_id: string; title: string; description?: string;
+    const { target_agent_id, title, description, draft } = args as {
+      target_agent_id: string; title: string; description?: string; draft?: boolean;
     };
 
     // Auto-encrypt when both agents have keys and we have a private key
@@ -907,8 +1170,10 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
         encrypted: true,
         descriptionKeys: encryptedKeys,
         senderSignature: signature,
+        ...(draft ? { draft: true } : {}),
       });
-      return { content: [{ type: "text" as const, text: `Task created (encrypted). ID: ${taskId}` }] };
+      const statusMsg = draft ? "draft" : "submitted";
+      return { content: [{ type: "text" as const, text: `Task created (encrypted, ${statusMsg}). ID: ${taskId}${draft ? "\nDraft — use pairai_update_status with status 'submitted' to publish." : ""}` }] };
     }
 
     // Fallback: plaintext (no keys available)
@@ -916,6 +1181,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
       targetAgentId: target_agent_id,
       title,
       description,
+      ...(draft ? { draft: true } : {}),
     });
     return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
   }
@@ -1012,12 +1278,12 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
 
   if (name === "pairai_list_tasks") {
     await loadPublicKeys();
-    const data = (await hubGet("/tasks")) as Array<{
+    const qs = args.status ? `?status=${args.status}` : "";
+    const data = (await hubGet(`/tasks${qs}`)) as Array<{
       id: string; status: string; title: string; encrypted?: boolean;
       description?: string; descriptionKeys?: any; senderSignature?: string; initiatorAgentId?: string;
     }>;
-    const filtered = args.status ? data.filter((t) => t.status === args.status) : data;
-    const decrypted = filtered.map((t) => {
+    const decrypted = data.map((t) => {
       if (t.encrypted) {
         const desc = decryptTaskDescription(t, t.id);
         return { ...t, title: desc.split("\n")[0] || t.title, description: desc };
@@ -1047,6 +1313,10 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     }
     const decryptedMsgs = msgs.map((m) => {
       if (data.encrypted) {
+        // Encrypted file messages: content is a file ID (short nanoid), not ciphertext
+        if (m.contentType === "encrypted" && m.encryptedKeys && m.content && m.content.length < 30 && !/[/+=]/.test(m.content)) {
+          return { ...m, content: `[Encrypted file — use pairai_download_file with task_id: "${data.id}", file_id: "${m.content}"]`, contentType: "file" };
+        }
         try {
           const d = decryptMessage(m, data.id);
           return { ...m, content: d.content, contentType: d.contentType };
@@ -1059,6 +1329,77 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     return { content: [{ type: "text" as const, text: JSON.stringify({ ...data, messages: decryptedMsgs }, null, 2) }] };
   }
 
+  if (name === "pairai_upload_file_from_path") {
+    const { task_id, file_path, mime_type } = args as {
+      task_id: string; file_path: string; mime_type?: string;
+    };
+
+    // 1. Path containment check
+    const safeCwd = pathResolve(process.cwd());
+    const resolved = pathResolve(safeCwd, file_path);
+    if (!resolved.startsWith(safeCwd + pathSep) && resolved !== safeCwd) {
+      return { content: [{ type: "text" as const, text: "Error: file not found or not accessible." }] };
+    }
+
+    // 2. Open with O_NOFOLLOW to reject symlinks (TOCTOU-safe)
+    let fd: number;
+    try {
+      fd = openSync(resolved, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    } catch {
+      return { content: [{ type: "text" as const, text: "Error: file not found or not accessible." }] };
+    }
+
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile()) {
+        return { content: [{ type: "text" as const, text: "Error: path is not a regular file." }] };
+      }
+      if (stat.size > 50 * 1024 * 1024) {
+        return { content: [{ type: "text" as const, text: "Error: file exceeds 50 MB limit." }] };
+      }
+
+      // 3. Read and encode from fd
+      const fileBuffer = readFileSync(fd);
+      const base64Content = fileBuffer.toString("base64");
+      const filename = basename(resolved);
+
+      // 4. Auto-detect MIME type
+      const ext = extname(filename).toLowerCase();
+      const detectedMime = mime_type || MIME_MAP[ext] || "application/octet-stream";
+
+      // 5. Delegate to existing upload logic (encrypted or plain)
+      const taskData = (await hubGet(`/tasks/${task_id}`)) as any;
+      if (taskData.encrypted) {
+        if (fileBuffer.byteLength > 28 * 1024 * 1024) {
+          return { content: [{ type: "text" as const, text: "Error: File too large for encrypted upload (max ~28 MB)." }] };
+        }
+        await loadPublicKeys();
+        const otherId = taskData.initiatorAgentId === myAgentId
+          ? taskData.targetAgentId : taskData.initiatorAgentId;
+        const otherPub = pubKeyCache.get(otherId);
+        if (!otherPub || !myPublicKey || !PRIVATE_KEY) {
+          return { content: [{ type: "text" as const, text: "Error: Missing cryptographic keys for encrypted upload." }] };
+        }
+        const envelope = JSON.stringify({ filename, mimeType: detectedMime, data: base64Content });
+        const { ciphertext, signature, encryptedKeys } = localEncrypt(envelope, task_id, {
+          [myAgentId]: myPublicKey, [otherId]: otherPub,
+        });
+        const data = await hubPost(`/tasks/${task_id}/files/json`, {
+          filename: "encrypted_file", mimeType: "application/octet-stream",
+          base64Content: ciphertext, encryptedKeys, senderSignature: signature,
+        });
+        return { content: [{ type: "text" as const, text: `Uploaded ${filename} (encrypted). ${JSON.stringify(data)}` }] };
+      }
+
+      const data = await hubPost(`/tasks/${task_id}/files/json`, {
+        filename, mimeType: detectedMime, base64Content,
+      });
+      return { content: [{ type: "text" as const, text: `Uploaded ${filename}. ${JSON.stringify(data)}` }] };
+    } finally {
+      closeSync(fd);
+    }
+  }
+
   if (name === "pairai_upload_file") {
     const { task_id, filename, mime_type, base64_content } = args as {
       task_id: string; filename: string; mime_type: string; base64_content: string;
@@ -1211,10 +1552,11 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
   if (name === "pairai_create_encrypted_task") {
     if (!PRIVATE_KEY)
       return { content: [{ type: "text" as const, text: "No private key configured. Re-run setup." }] };
-    const { target_agent_id, title, description } = args as {
+    const { target_agent_id, title, description, draft } = args as {
       target_agent_id: string;
       title: string;
       description?: string;
+      draft?: boolean;
     };
     // Refresh keys in case a new connection was established
     await loadPublicKeys();
@@ -1240,8 +1582,10 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
       encrypted: true,
       descriptionKeys: encryptedKeys,
       senderSignature: signature,
+      ...(draft ? { draft: true } : {}),
     });
-    return { content: [{ type: "text" as const, text: `Encrypted task created. ID: ${taskId}` }] };
+    const statusMsg = draft ? "draft" : "submitted";
+    return { content: [{ type: "text" as const, text: `Encrypted task created (${statusMsg}). ID: ${taskId}${draft ? "\nDraft — use pairai_update_status with status 'submitted' to publish." : ""}` }] };
   }
 
   if (name === "pairai_delete_message") {
@@ -1292,6 +1636,16 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     }
   }
 
+  if (name === "pairai_report_usage") {
+    const { task_id, cost } = args as { task_id: string; cost: number };
+    try {
+      const result = await hubPost(`/tasks/${task_id}/usage`, { cost });
+      return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
+    } catch (err) {
+      return { content: [{ type: "text" as const, text: `Error: ${(err as Error).message}` }], isError: true };
+    }
+  }
+
   if (name === "pairai_block_agent") {
     const { agent_id } = args as { agent_id: string };
     try {
@@ -1320,6 +1674,15 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
 const seenMessages = new Set<string>();
 const SEEN_MESSAGES_MAX = 10_000;
 
+const MIME_MAP: Record<string, string> = {
+  ".md": "text/markdown", ".txt": "text/plain", ".json": "application/json",
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+  ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+  ".pdf": "application/pdf", ".html": "text/html", ".csv": "text/csv",
+  ".yaml": "text/yaml", ".yml": "text/yaml",
+  ".ts": "text/plain", ".js": "text/plain",
+};
+
 function decryptMessage(
   msg: { content: string; contentType: string; senderAgentId: string; encryptedKeys?: any; senderSignature?: string },
   taskId: string,
@@ -1327,6 +1690,12 @@ function decryptMessage(
   if (msg.contentType !== "encrypted" || !msg.encryptedKeys || !msg.senderSignature || !PRIVATE_KEY) {
     return { content: msg.content, contentType: msg.contentType };
   }
+  // Encrypted file messages: content is a file ID (nanoid), not ciphertext.
+  // The signature covers the encrypted file data on disk, not the file ID reference.
+  // Don't attempt to decrypt — the file is retrieved and decrypted via download_file.
+  if (msg.content && msg.content.length < 30 && !/[/+=]/.test(msg.content)) {
+    return { content: `[Encrypted file attachment — file_id: ${msg.content}]`, contentType: "file" };
+  }
   try {
     const keys = typeof msg.encryptedKeys === "string" ? JSON.parse(msg.encryptedKeys) : msg.encryptedKeys;
     const senderPub = msg.senderAgentId === myAgentId ? myPublicKey : pubKeyCache.get(msg.senderAgentId);
@@ -1407,7 +1776,7 @@ async function poll() {
       const decryptedMessages = (taskMsgs ?? []).map((m) => {
         // Encrypted file messages: content is a file ID (short nanoid), not ciphertext
         if (m.contentType === "encrypted" && m.encryptedKeys && m.content.length < 30) {
-          return "[File attachment — use pairai_download_file to retrieve]";
+          return `[File attachment — use pairai_download_file with task_id: "${task.id}", file_id: "${m.content}"]`;
         }
         try {
           const d = decryptMessage(m, task.id);
@@ -1460,7 +1829,7 @@ async function poll() {
         const isEncryptedFile = msg.contentType === "encrypted" && msg.encryptedKeys && msg.content.length < 30;
         let decrypted: { content: string; contentType: string };
         if (isEncryptedFile) {
-          decrypted = { content: "[File attachment — use pairai_download_file to retrieve]", contentType: "text" };
+          decrypted = { content: `[File attachment — use pairai_download_file with task_id: "${unread.taskId}", file_id: "${msg.content}"]`, contentType: "text" };
         } else {
           try {
             decrypted = decryptMessage(msg, unread.taskId);
@@ -1490,10 +1859,17 @@ async function poll() {
       }
     }
 
-    // Do NOT ack the hub here — the hub's lastSeenRowid is only advanced
-    // when the user explicitly calls pairai_check_updates (authoritative ack).
-    // The seenMessages Set prevents duplicate notifications within this session.
-    debugLog(`poll: processed cursor=${updates.cursor} (hub NOT acked — seenMessages dedup only)`);
+    // Ack the cursor after successful delivery (Kafka manual-commit pattern).
+    // seenMessages remains as secondary belt-and-suspenders dedup.
+    // See: docs/superpowers/specs/2026-04-04-notification-ack-design.md
+    if (updates.cursor > 0) {
+      try {
+        await hubPost("/updates/ack", { cursor: updates.cursor });
+        debugLog(`poll: acked cursor=${updates.cursor}`);
+      } catch (err) {
+        debugLog(`poll: ack failed (will retry next cycle): ${(err as Error).message}`);
+      }
+    }
 
     // Prevent unbounded memory growth
     if (seenMessages.size > SEEN_MESSAGES_MAX) {