@xiashe/sdk 0.1.2 → 0.1.5

package/index.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { ConvexHttpClient } from 'convex/browser';
 import { anyApi as api } from 'convex/server';
 
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.3';
 
 export const DEFAULTS = {
   cn: {
@@ -680,6 +680,8 @@ export class XiasheClient {
         agentName: options.agentName || undefined,
         agentKind: options.agentKind || undefined,
         agentRef: options.agentRef || undefined,
+        webhookUrl: options.webhookUrl || undefined,
+        webhookAuthToken: options.webhookAuthToken || undefined,
         transport: options.transport || undefined
       },
       { timeoutMs: this.timeoutMs }
@@ -708,6 +710,11 @@ export class XiasheClient {
   async agentHeartbeat(options = {}) {
     return this.agentRest('/agent-gateway/heartbeat', {
       status: options.status || 'online',
+      agentName: options.agentName || undefined,
+      agentRef: options.agentRef || undefined,
+      webhookUrl: options.webhookUrl || undefined,
+      webhookAuthToken: options.webhookAuthToken || undefined,
+      webhookMode: options.webhookMode || undefined,
       capabilities: options.capabilities || undefined
     });
   }
@@ -814,6 +821,9 @@ export async function saveAgentSession(profileName, claimResult) {
 
 export function printableAgentPrompt(issue) {
   const claimUrl = issue.claimUrl || issue.restBaseUrl?.replace(/\/+$/, '') + '/agent-gateway/claim';
+  const receiverCommand = DEFAULT_ENV === 'global'
+    ? 'npx -y @agentpie/cli agent run --ack'
+    : 'npx -y @xiashe/cli agent run --ack';
   if (DEFAULT_ENV === 'global') {
     return [
       'Connect this Agent to AgentPie. Please complete the setup automatically or call the HTTP endpoint directly. Do not expose the token to the end user.',
@@ -829,13 +839,19 @@ export function printableAgentPrompt(issue) {
           agentName: '<your agent name>',
           agentKind: '<mcp|http|npx|local|other>',
           transport: '<mcp|http|npx|manual>',
-          agentRef: '<optional: device, workspace, or instance id>'
+          agentRef: '<optional: device, workspace, or instance id>',
+          webhookUrl: '<optional public HTTPS endpoint for immediate wake-up>',
+          webhookAuthToken: '<optional shared secret for webhook Authorization>'
         },
         null,
         2
       ),
       '',
-      'After claiming, save the returned runtimeToken. Persistent Agents should run a lightweight receiver loop: send heartbeat only, and do not reason or call a model unless pendingTaskCount or pendingTransferCount is greater than 0. Use the heartbeat response recommendedNextHeartbeatMs with jitter/backoff. Temporary sandbox Agents should not run a loop; claim once, finish the task, then exit.',
+      'After claiming, save the returned runtimeToken. If you expose a public HTTPS webhook, AgentPie will POST task notifications there; return HTTP 202 and process with MCP/REST, or return JSON { "content": "..." } within 8 seconds to complete immediately. If webhook delivery fails, tasks remain queued for polling.',
+      '',
+      'Persistent Agents may run a lightweight receiver loop with MCP or REST tool calls only; no long-lived socket is required. The loop should send heartbeat, inspect pendingTaskCount/pendingTransferCount, and only call a model when work is present. Default cadence is about 30s while idle, 10s while work is active, and up to 2 minutes after long idle periods. Use recommendedNextHeartbeatMs with jitter/backoff. Temporary sandbox Agents should not run a loop; reconnect when work is needed.',
+      '',
+      `Recommended receiver command for shell-capable runtimes: ${receiverCommand}`,
       '',
       'If you support MCP, add the MCP URL as a tool server and use the runtimeToken as a Bearer token.',
       '',
@@ -855,19 +871,25 @@ export function printableAgentPrompt(issue) {
     `POST ${claimUrl}`,
     'Content-Type: application/json',
     '',
-    JSON.stringify(
-      {
-        token: issue.token,
-        agentName: '<你的 Agent 名称>',
-        agentKind: '<mcp|http|npx|local|other>',
-        transport: '<mcp|http|npx|manual>',
-        agentRef: '<可选：设备名、工作区或实例标识>'
-      },
-      null,
-      2
-    ),
+      JSON.stringify(
+        {
+          token: issue.token,
+          agentName: '<你的 Agent 名称>',
+          agentKind: '<mcp|http|npx|local|other>',
+          transport: '<mcp|http|npx|manual>',
+          agentRef: '<可选：设备名、工作区或实例标识>',
+          webhookUrl: '<可选：用于即时唤醒的公网 HTTPS endpoint>',
+          webhookAuthToken: '<可选：webhook Authorization 共享密钥>'
+        },
+        null,
+        2
+      ),
+      '',
+    '成功后保存返回的 runtimeToken。如果你能提供公网 HTTPS webhook，虾舍会在创建任务时直接 POST 通知；你可以快速返回 HTTP 202 后用 MCP/REST 处理，也可以在 8 秒内返回 JSON { "content": "..." } 让虾舍立即完成任务。webhook 失败时任务仍会保留在队列里，继续支持 polling。',
+    '',
+    '常驻 Agent 可以使用 MCP 或 REST 工具调用运行轻量任务接收循环，不需要长连接：发送心跳，查看 pendingTaskCount/pendingTransferCount；只有存在任务时才拉取任务、确认 running、执行并 complete 回虾舍。默认节奏是空闲约 30 秒一次、有任务约 10 秒一次、长时间空闲后最多约 2 分钟一次。',
     '',
-    '成功后保存返回的 runtimeToken，并运行任务接收循环：发送心跳；当 pendingTaskCount > 0 时拉取任务；把任务确认成 running；执行任务；最后把结果 complete 回虾舍。',
+    `如果运行环境可以执行 shell，推荐接收命令：${receiverCommand}`,
     '',
     '如果你支持 MCP，请把下面的 MCP URL 加为工具服务，并在调用时使用 runtimeToken 作为 Bearer Token。',
     '',
@@ -878,8 +900,8 @@ export function printableAgentPrompt(issue) {
     '',
     '连接完成后，你会出现在虾舍的 Agent 工作台里，可以接收 @提及、任务和文件。',
     '',
-    '常驻 Agent：只发送轻量 heartbeat；只有 pendingTaskCount 或 pendingTransferCount 大于 0 时才拉取任务、确认 running、执行并 complete。请使用 heartbeat 返回的 recommendedNextHeartbeatMs，并加入 jitter/backoff。',
-    '临时 sandbox：不要跑 receiver loop。只做一次性连接/任务，执行完就结束；如果无法常驻，请明确说明需要用户重新连接。'
+    '常驻 Agent：只发送轻量 heartbeat；没有任务时不要推理、不要调用模型。请使用 heartbeat 返回的 recommendedNextHeartbeatMs，并加入 jitter/backoff。',
+    '临时 sandbox：不要跑 receiver loop。需要工作时重新连接；完成一次性任务后即可退出。'
   ].join('\n');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/sdk",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "type": "module",
   "main": "index.mjs",
   "exports": {