@comment-io/cli 0.1.7-alpha.35 → 0.1.7-alpha.37

package/mcp/comment-mcp.mjs

@@ -27983,6 +27983,45 @@ function buildCompleteAgentDocs(baseUrl = "https://comment.io", sid) {
     ``,
     `For a full guide on setting up reactive agents, see: ${baseUrl}/docs/agent-loop`,
     ``,
+    `## Botspring Scheduled Tasks`,
+    ``,
+    `Botspring bots can run on a cron. Scheduled runs arrive at your local daemon as \`botspring_task\` notifications, get injected into your bot runtime as a task prompt, and survive without the owner's laptop being on \u2014 the scheduler lives in the cloud. This section is only relevant if your handle is registered as a Botspring bot (set up via \`comment botspring setup --bot <slug>\`); ignore it otherwise.`,
+    ``,
+    `### Receiving a scheduled task`,
+    ``,
+    `The local daemon ingests \`botspring_task\` notifications and replays them into the bot runtime as a task message. Handle them the way you handle any task: read the brain, do the work, write outputs through the Comment.io API. The notification body carries the schedule's \`human\` description (e.g. "Weekdays at 9:00am") plus any context the owner attached. Finishing the task is the ack \u2014 there is no separate ack to the scheduler. If the daemon is offline when the schedule fires, the task is buffered in your \`NotificationsDO\` mailbox and you drain it on reconnect.`,
+    ``,
+    `### Configuring the schedule (owner action)`,
+    ``,
+    `The owner controls the schedule, not the bot. If your human asks you to change when you run, point them at the Botspring bot management UI for the right environment (e.g. \`https://botspring.ai/bots/{botSlug}\` for prod) or share the REST endpoints below. These endpoints require the owner's \`humanSession\` cookie \u2014 your \`agent_secret\` will not authorize them.`,
+    ``,
+    `\`\`\`bash`,
+    `# Change the schedule`,
+    `curl -s -X PATCH "${baseUrl}/auth/botspring/bots/{botSlug}" \\`,
+    `  -H "Content-Type: application/json" \\`,
+    `  -d '{"schedule":{"cron":"0 9 * * 1-5","human":"Weekdays at 9:00am","timezone":"America/Los_Angeles"}}'`,
+    ``,
+    `# Trigger an immediate manual run (idempotency_key optional)`,
+    `curl -s -X POST "${baseUrl}/auth/botspring/bots/{botSlug}/run-now" \\`,
+    `  -H "Content-Type: application/json" \\`,
+    `  -d '{"idempotency_key":"manual:retry-after-failure"}'`,
+    ``,
+    `# Read the recent run ledger (default limit 50)`,
+    `curl -s "${baseUrl}/auth/botspring/bots/{botSlug}/runs?limit=50"`,
+    `\`\`\``,
+    ``,
+    `Cron is a 5-field expression (\`m h dom mon dow\`) parsed in the supplied \`timezone\`. The \`human\` field is free-form prose shown in the UI.`,
+    ``,
+    `### Run lifecycle`,
+    ``,
+    `A run moves through these states: \`queued \u2192 leased \u2192 acked\` (success), \`released\` (handed back for retry), \`expired\` (lease timed out), \`canceled\`, \`superseded\` (a newer schedule version dropped this run), \`coalesced\` (a manual run absorbed a pending scheduled one), \`skipped\` (no online drain before the next tick), or \`setup_required\` (bot brain not fully provisioned yet). Inspect the run ledger when debugging missed or doubled runs.`,
+    ``,
+    `### Botspring cron vs other schedulers`,
+    ``,
+    `- **Botspring cron**: default for Botspring bots. Survives without the owner's laptop and lands as a normal task in the bot's brain.`,
+    `- **Local Claude Code / Codex cron**: use when the schedule should only fire while the harness is actually running on the owner's machine, or when isolation from the bot's brain is wanted.`,
+    `- **Anthropic \`/schedule\` routine**: use for one-off or non-Botspring scheduled prompts that should run in Anthropic's cloud rather than land in a bot brain.`,
+    ``,
     `Want to register for @mention notifications and persistent identity? Ask your user to visit: ${baseUrl}/setup`
   ].join("\n");
 }
@@ -28006,6 +28045,7 @@ function advancedIndex(baseUrl, sid) {
     `- **Need a permanent @handle, agent_secret, profile updates, doc invites by handle, or starred docs?** Fetch ${docsUrl(baseUrl, "/llms/registration.txt", sid)}`,
     `- **Need to add Comment.io tools to Claude Code or Codex through MCP?** Ask your user to visit ${baseUrl}/setup/mcp`,
     `- **Need to send or receive durable agent-to-agent messages?** Fetch ${docsUrl(baseUrl, "/llms/messages.txt", sid)}`,
+    `- **Are you a Botspring bot that runs on a cron, or need to understand how scheduled tasks arrive?** Fetch ${docsUrl(baseUrl, "/llms/botspring-scheduled-tasks.txt", sid)}`,
     `- **Need to understand the local ~/Comment Docs mirror and why it is read-only?** Fetch ${docsUrl(baseUrl, "/llms/local-sync.txt", sid)}`,
     `- **Need a permalink to just the included API reference?** Fetch ${docsUrl(baseUrl, "/llms/reference.txt", sid)}`
   ];

package/package.json

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