@xiashe/sdk 0.1.0 → 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: {
@@ -38,6 +38,7 @@ const CONFIG_DIR = process.env.XIASHE_CONFIG_DIR || path.join(os.homedir(), DEFA
 const CONFIG_PATH = process.env.XIASHE_CONFIG_PATH || path.join(CONFIG_DIR, 'config.json');
 const DEFAULT_PROFILE = 'default';
 const HTTP_TIMEOUT_MS = 20_000;
+const DEFAULT_MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
 
 export class XiasheError extends Error {
   constructor(message, options = {}) {
@@ -529,6 +530,16 @@ export class XiasheClient {
     return this.query(api.agentGateway.listForUser, this.authArgs({ limit }));
   }
 
+  async revokeAgent(agentConnectionId, options = {}) {
+    return this.mutation(
+      api.agentGateway.revokeConnection,
+      this.authArgs({
+        agentConnectionId,
+        idempotencyKey: options.idempotencyKey || createIdempotencyKey('cli-agent-revoke', [agentConnectionId])
+      })
+    );
+  }
+
   async createAgentChatTask(options = {}) {
     return this.mutation(
       api.agentGateway.createChatTask,
@@ -598,6 +609,12 @@ export class XiasheClient {
     if (!info.isFile()) {
       throw new XiasheError(`Not a file: ${absolutePath}`, { code: 'UPLOAD_NOT_FILE' });
     }
+    if (info.size > DEFAULT_MAX_UPLOAD_BYTES) {
+      throw new XiasheError(`File too large. Max ${DEFAULT_MAX_UPLOAD_BYTES} bytes.`, {
+        code: 'UPLOAD_FILE_TOO_LARGE',
+        details: { maxBytes: DEFAULT_MAX_UPLOAD_BYTES, size: info.size }
+      });
+    }
     const fileName = options.fileName || path.basename(absolutePath);
     const mime = options.mime || inferMime(absolutePath);
     const source = options.source || 'manual_upload';
@@ -663,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 }
@@ -691,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
     });
   }
@@ -701,6 +725,28 @@ export class XiasheClient {
     });
   }
 
+  async agentListTransfers(options = {}) {
+    return this.agentRest('/agent-gateway/transfers/list', {
+      limit: options.limit || 20
+    });
+  }
+
+  async agentAcceptTransfer(transferId, options = {}) {
+    return this.agentRest('/agent-gateway/transfers/accept', {
+      transferId,
+      idempotencyKey: options.idempotencyKey || undefined
+    });
+  }
+
+  async agentCompleteTransfer(transferId, options = {}) {
+    return this.agentRest('/agent-gateway/transfers/complete', {
+      transferId,
+      status: options.status || 'completed',
+      error: options.error || undefined,
+      idempotencyKey: options.idempotencyKey || undefined
+    });
+  }
+
   async agentAckTask(taskId, state = 'running') {
     return this.agentRest('/agent-gateway/tasks/ack', { taskId, state });
   }
@@ -716,6 +762,7 @@ export class XiasheClient {
   async agentCreateTask(options = {}) {
     return this.agentRest('/agent-gateway/tasks/create', {
       targetAgentConnectionId: options.targetAgentConnectionId,
+      targetAgentName: options.targetAgentName,
       chatId: options.chatId,
       content: options.content,
       attachments: options.attachments || undefined,
@@ -774,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.',
@@ -787,15 +837,21 @@ export function printableAgentPrompt(issue) {
         {
           token: issue.token,
           agentName: '<your agent name>',
-          agentKind: '<codex|claude|coze|workbuddy|local|other>',
+          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 and periodically POST heartbeat events to /agent-gateway/heartbeat on the REST Base URL.',
+      '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.',
       '',
@@ -815,19 +871,25 @@ export function printableAgentPrompt(issue) {
     `POST ${claimUrl}`,
     'Content-Type: application/json',
     '',
-    JSON.stringify(
-      {
-        token: issue.token,
-        agentName: '<你的 Agent 名称>',
-        agentKind: '<codex|claude|coze|workbuddy|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。',
     '',
-    '成功后保存返回的 runtimeToken，并定期 POST 心跳到 REST Base URL 的 /agent-gateway/heartbeat。',
+    '常驻 Agent 可以使用 MCP 或 REST 工具调用运行轻量任务接收循环，不需要长连接：发送心跳，查看 pendingTaskCount/pendingTransferCount；只有存在任务时才拉取任务、确认 running、执行并 complete 回虾舍。默认节奏是空闲约 30 秒一次、有任务约 10 秒一次、长时间空闲后最多约 2 分钟一次。',
+    '',
+    `如果运行环境可以执行 shell，推荐接收命令：${receiverCommand}`,
     '',
     '如果你支持 MCP，请把下面的 MCP URL 加为工具服务，并在调用时使用 runtimeToken 作为 Bearer Token。',
     '',
@@ -836,7 +898,10 @@ export function printableAgentPrompt(issue) {
     `MCP URL: ${issue.mcpUrl}`,
     `REST Base URL: ${issue.restBaseUrl}`,
     '',
-    '连接完成后，你会出现在虾舍的 Agent 工作台里，可以接收 @提及、任务和文件。'
+    '连接完成后，你会出现在虾舍的 Agent 工作台里，可以接收 @提及、任务和文件。',
+    '',
+    '常驻 Agent：只发送轻量 heartbeat；没有任务时不要推理、不要调用模型。请使用 heartbeat 返回的 recommendedNextHeartbeatMs，并加入 jitter/backoff。',
+    '临时 sandbox：不要跑 receiver loop。需要工作时重新连接；完成一次性任务后即可退出。'
   ].join('\n');
 }
 

package/package.json

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