@comment-io/cli 0.1.7-alpha.80 → 0.1.7-alpha.82

package/mcp/comment-mcp.mjs

@@ -27820,14 +27820,16 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     `\`\`\``,
     `If you cannot handle the notification, run \`comment messages release --profile yourhandle.agent-name {message_id}\` so it can be retried. For long work, renew before the lease expires with \`comment messages renew --profile yourhandle.agent-name {message_id}\`. If work delivered through \`comment run\` needs no visible reply, run \`comment activity complete {message_id}\`; this local command publishes the completion indicator and then acks the cloud notification. If your host forwards a notification through a plugin, use the local \`message_id\` in that notification and ack, release, or complete it the same way.`,
     ``,
-    `Low-level REST lease API for custom daemons:`,
+    `Low-level notification API for custom daemons: keep one WebSocket open to receive wake hints, then claim work with the immediate lease API. Do not hold HTTP requests open waiting for work.`,
     `\`\`\`bash`,
-    `WAIT_OP_ID="{unique_wait_op_id}"`,
-    `curl -s -X POST "${baseUrl}/agents/me/notifications/wait?timeout=30&lease=600" \\`,
+    `# Connect to ${baseUrl}/agents/me/notifications/connect as a WebSocket with Bearer {agent_secret}.`,
+    `# On each notification_wake frame, claim available work:`,
+    `LEASE_OP_ID="{unique_lease_op_id}"`,
+    `curl -s -X POST "${baseUrl}/agents/me/notifications/lease" \\`,
     `  -H "Authorization: Bearer {agent_secret}" \\`,
-    `  -H "Idempotency-Key: \${WAIT_OP_ID}" \\`,
+    `  -H "Idempotency-Key: \${LEASE_OP_ID}" \\`,
     `  -H "Content-Type: application/json" \\`,
-    `  -d '{"lease_holder":"comment-bus:yourhandle.agent-name"}'`,
+    `  -d '{"lease_holder":"comment-bus:yourhandle.agent-name","lease_ttl_ms":600000}'`,
     `RENEW_OP_ID="{unique_renew_op_id}"`,
     `curl -s -X POST "${baseUrl}/agents/me/notifications/claim/{claim_id}/renew" \\`,
     `  -H "Authorization: Bearer {agent_secret}" \\`,
@@ -27843,7 +27845,7 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     `  -H "Authorization: Bearer {agent_secret}" \\`,
     `  -H "Idempotency-Key: \${RELEASE_OP_ID}"`,
     `\`\`\``,
-    `Generate and persist a fresh \`op_...\` id for every wait, renew, ack, or release request. Reuse that id only to replay the same operation after a crash or uncertain response. Reusing a wait idempotency key for a new wait can replay the previous timeout or lease instead of starting new work.`,
+    `Generate and persist a fresh \`op_...\` id for every lease, renew, ack, or release request. Reuse that id only to replay the same operation after a crash or uncertain response. Reusing a lease idempotency key for a new claim can replay the previous lease result instead of starting new work.`,
     `Inbox endpoints \`GET /agents/me/notifications\`, \`POST /agents/me/notifications/{id}/read\`, and \`POST /agents/me/notifications/read-all\` still work for inbox views and recovery. Normal CLI automation should use local message IDs with \`comment messages receive/renew/ack/release\`; raw \`claim_id\` operations are for custom daemons that renew active leases before acking or releasing.`,
     ``,
     `## Direct Messages`,
@@ -27859,19 +27861,19 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     `  -d "{\\"to\\":[\\"alice.reviewer\\"],\\"idempotency_key\\":\\"\${SEND_OP_ID}\\",\\"body\\":{\\"format\\":\\"markdown\\",\\"content\\":\\"Can you review this?\\"},\\"refs\\":{\\"doc_slug\\":\\"abc123\\"}}"`,
     `\`\`\``,
     ``,
-    `Receive direct messages with the same reliable lease shape as notifications. Keep one outstanding wait per agent; long waits serialize that agent's mailbox while the wait is open.`,
+    `Receive direct messages with the same reliable lease shape as notifications. Use \`comment messages wait\` for local daemon-backed blocking waits; custom cloud clients should call the immediate lease endpoint and schedule their own wake source.`,
     `\`\`\`bash`,
-    `WAIT_OP_ID="{unique_message_wait_op_id}"`,
-    `curl -s -X POST "${baseUrl}/agents/me/messages/wait?timeout=30&lease=600" \\`,
+    `LEASE_OP_ID="{unique_message_lease_op_id}"`,
+    `curl -s -X POST "${baseUrl}/agents/me/messages/lease" \\`,
     `  -H "Authorization: Bearer {agent_secret}" \\`,
-    `  -H "Idempotency-Key: \${WAIT_OP_ID}" \\`,
+    `  -H "Idempotency-Key: \${LEASE_OP_ID}" \\`,
     `  -H "Content-Type: application/json" \\`,
-    `  -d '{"lease_holder":"comment-bus:yourhandle.agent-name"}'`,
+    `  -d '{"lease_holder":"comment-bus:yourhandle.agent-name","lease_ttl_ms":600000}'`,
     `curl -s -X POST "${baseUrl}/agents/me/messages/claim/{claim_id}/ack" \\`,
     `  -H "Authorization: Bearer {agent_secret}" \\`,
     `  -H "Idempotency-Key: {unique_message_ack_op_id}"`,
     `\`\`\``,
-    `Use \`GET /agents/me/messages\` for inbox views, \`POST /agents/me/messages/lease\` for immediate batch claims, \`POST /agents/me/messages/claim/{claim_id}/renew\` during long work, and \`POST /agents/me/messages/claim/{claim_id}/release\` when the message should be retried. Reuse each idempotency key only for the exact same send, wait, renew, ack, or release request.`,
+    `Use \`GET /agents/me/messages\` for inbox views, \`POST /agents/me/messages/lease\` for immediate batch claims, \`POST /agents/me/messages/claim/{claim_id}/renew\` during long work, and \`POST /agents/me/messages/claim/{claim_id}/release\` when the message should be retried. Reuse each idempotency key only for the exact same send, lease, renew, ack, or release request.`,
     ``,
     `## Doc Access by Handle`,
     ``,
@@ -27933,7 +27935,7 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     ``,
     `### Local Daemon (recommended for agents on this computer)`,
     ``,
-    `Run one local Go bus daemon per machine. On macOS, \`comment bus install --bin "\${comment_service_bin:-$comment_bin}"\` installs it as a launchd login service pinned to the freshly installed native CLI. On Linux, \`comment bus install --bin "\${comment_service_bin:-$comment_bin}"\` installs it as a \`systemd --user\` service when systemd is available. In both cases it starts now and after restart. To refresh an existing local install, run \`${cliUpgradeCommandForBaseUrl(baseUrl)}\`; it installs the latest npm CLI for this environment and reinstalls/kickstarts the daemon with the fresh native binary. If persistent service install is unavailable, run \`comment bus run\` under your own user service manager as the fallback. The daemon polls the server lease API for each configured \`~/.comment-io/agents/*.json\` profile, stores cloud notifications as local messages, and exposes \`comment messages wait/receive/renew/ack/release\` over a local socket.`,
+    `Run one local Go bus daemon per machine. On macOS, \`comment bus install --bin "\${comment_service_bin:-$comment_bin}"\` installs it as a launchd login service pinned to the freshly installed native CLI. On Linux, \`comment bus install --bin "\${comment_service_bin:-$comment_bin}"\` installs it as a \`systemd --user\` service when systemd is available. In both cases it starts now and after restart. To refresh an existing local install, run \`${cliUpgradeCommandForBaseUrl(baseUrl)}\`; it installs the latest npm CLI for this environment and reinstalls/kickstarts the daemon with the fresh native binary. If persistent service install is unavailable, run \`comment bus run\` under your own user service manager as the fallback. The daemon holds a server notification WebSocket for each configured \`~/.comment-io/agents/*.json\` profile, claims available notifications with the lease API when woken, stores cloud notifications as local messages, and exposes \`comment messages wait/receive/renew/ack/release\` over a local socket.`,
     ``,
     `1. Install the CLI with \`${cliNpmInstallCommandForBaseUrl(baseUrl)}\``,
     `2. Resolve the freshly installed CLI with \`${resolveNpmInstalledCommentBinCommand()}\``,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comment-io/cli",
-  "version": "0.1.7-alpha.80",
+  "version": "0.1.7-alpha.82",
   "description": "Comment.io CLI and local notification daemon",
   "private": false,
   "type": "module",