@xiashe/cli 0.1.0 → 0.1.4

package/README.md

@@ -18,12 +18,14 @@ xiashe skills list
 xiashe skills install copywriting --connection MaxClaw-1 --watch
 xiashe agent issue --name "Local WorkBuddy"
 xiashe agent connect --token "<token>" --name "Local WorkBuddy"
-xiashe agent tasks watch --ack
+xiashe agent run --ack
 xiashe chat send --chat "New Chat" --content "帮我处理这个文件" --file ./report.pdf --agent "Local WorkBuddy"
 ```
 
 Local state is stored in `~/.xiashe/config.json`.
 
+`xiashe agent run --ack` is the recommended lightweight receiver for shell-capable Agents. It sends cheap heartbeats and only lists/executes work when the backend reports pending tasks or transfers. Default cadence is about 30s while idle, 10s while work is active, and up to 2 minutes after long idle periods.
+
 Production defaults:
 
 - Convex: `https://api.xiashe.chat`

package/bin/xiashe.mjs

@@ -64,10 +64,13 @@ Usage:
   ${c} skills claim <one-time-token>
 
   ${c} agent issue [--name <name>] [--kind <kind>] [--json]
-  ${c} agent connect --token <token> [--name <name>] [--kind <kind>]
-  ${c} agent heartbeat
+  ${c} agent connect --token <token> [--name <name>] [--kind <kind>] [--webhook-url <https-url>] [--webhook-token <secret>]
+  ${c} agent heartbeat [--webhook-url <https-url>] [--webhook-token <secret>|--disable-webhook]
   ${c} agent list
+  ${c} agent revoke --agent <id-or-name>
+  ${c} agent run [--once] [--ack] [--idle-ms <ms>] [--busy-ms <ms>] [--max-idle-ms <ms>]
   ${c} agent tasks list|watch|ack <taskId>|complete <taskId> [--content <text>]
+  ${c} agent transfers list|accept <transferId>|complete <transferId>|fail <transferId>
   ${c} agent task create --agent <id-or-name> --chat <id-or-title> --content <text>
 
   ${c} chat list
@@ -187,6 +190,26 @@ function parseFlags(argv) {
   return out;
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+function unwrapResult(payload) {
+  return payload && typeof payload === 'object' && payload.result && typeof payload.result === 'object'
+    ? payload.result
+    : payload;
+}
+
+function numericFlag(flags, key, fallback) {
+  const value = Number(flags[key] ?? fallback);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function jitterMs(ms, ratio = 0.2) {
+  const spread = Math.max(0, ms * ratio);
+  return Math.round(ms - spread + Math.random() * spread * 2);
+}
+
 function requireValue(key, value) {
   if (!value || String(value).startsWith('--')) {
     fail(`Missing value for ${key}.`, EXIT_USAGE);
@@ -622,6 +645,8 @@ async function cmdAgent(sub, args, global) {
       agentName: flags.name || flags['agent-name'] || 'XiaShe CLI Agent',
       agentKind: flags.kind || 'cli',
       agentRef: flags.ref || `${osName()} ${process.cwd()}`,
+      webhookUrl: flags['webhook-url'] || undefined,
+      webhookAuthToken: flags['webhook-token'] || flags['webhook-auth-token'] || undefined,
       transport: flags.transport || 'npx'
     });
     await saveAgentSession(profileName, claim);
@@ -631,11 +656,20 @@ async function cmdAgent(sub, args, global) {
   if (sub === 'heartbeat') {
     const result = await client.agentHeartbeat({
       status: flags.status || 'online',
+      agentName: flags.name || flags['agent-name'] || undefined,
+      agentRef: flags.ref || undefined,
+      webhookUrl: flags['webhook-url'] || undefined,
+      webhookAuthToken: flags['webhook-token'] || flags['webhook-auth-token'] || undefined,
+      webhookMode: flags['disable-webhook'] ? 'disabled' : flags['webhook-url'] ? 'notify' : undefined,
       capabilities: parseCsv(flags.capabilities || 'chat,files,tasks,skills')
     });
     print(result, global);
     return;
   }
+  if (sub === 'run' || sub === 'receiver' || sub === 'loop') {
+    await cmdAgentReceiver(flags, client, global);
+    return;
+  }
   if (sub === 'list' || sub === 'agents' || !sub) {
     const rows = await client.listAgents(Number(flags.limit || 50));
     if (global.json) {
@@ -652,10 +686,22 @@ async function cmdAgent(sub, args, global) {
     ]);
     return;
   }
+  if (sub === 'revoke' || sub === 'disconnect' || sub === 'delete') {
+    const agent = await resolveAgent(client, requireArg(flags.agent || flags._[0], '--agent'));
+    const result = await client.revokeAgent(agent.id, {
+      idempotencyKey: flags.idempotencyKey || createIdempotencyKey('cli-agent-revoke', [agent.id])
+    });
+    print(result, global);
+    return;
+  }
   if (sub === 'tasks') {
     await cmdAgentTasks(flags, client, global);
     return;
   }
+  if (sub === 'transfers') {
+    await cmdAgentTransfers(flags, client, global);
+    return;
+  }
   if (sub === 'task') {
     const action = requireArg(flags._[0], 'agent task action');
     if (action !== 'create') fail('Usage: xiashe agent task create --agent <id-or-name> --chat <id-or-title> --content <text>', EXIT_USAGE);
@@ -673,6 +719,103 @@ async function cmdAgent(sub, args, global) {
   fail(`Unknown agent command: ${sub}`, EXIT_USAGE);
 }
 
+async function cmdAgentReceiver(flags, client, global) {
+  const idleMs = numericFlag(flags, 'idle-ms', 30_000);
+  const busyMs = numericFlag(flags, 'busy-ms', 10_000);
+  const maxIdleMs = numericFlag(flags, 'max-idle-ms', 120_000);
+  const deadline = Date.now() + numericFlag(flags, 'timeout-ms', 24 * 60 * 60_000);
+  const capabilities = parseCsv(flags.capabilities || 'chat,files,tasks,skills');
+  const seenTasks = new Set();
+  const seenTransfers = new Set();
+  let emptyCycles = 0;
+  let failures = 0;
+
+  while (Date.now() < deadline) {
+    let nextDelayMs = idleMs;
+    try {
+      const heartbeat = unwrapResult(await client.agentHeartbeat({ capabilities }));
+      const pendingTaskCount = Number(heartbeat.pendingTaskCount || 0);
+      const pendingTransferCount = Number(heartbeat.pendingTransferCount || 0);
+      const pendingCount = pendingTaskCount + pendingTransferCount;
+      failures = 0;
+
+      if (pendingTaskCount > 0) {
+        const tasksResult = unwrapResult(await client.agentListTasks({ limit: Number(flags.limit || 20) }));
+        const tasks = tasksResult.tasks || tasksResult.items || [];
+        for (const task of tasks) {
+          const id = task.taskId || task.id;
+          if (!id || seenTasks.has(id)) continue;
+          seenTasks.add(id);
+          console.log(JSON.stringify({ type: 'task', ...task }, null, 2));
+          if (flags.ack) await client.agentAckTask(id, 'running');
+        }
+      }
+
+      if (pendingTransferCount > 0) {
+        const transfersResult = unwrapResult(await client.agentListTransfers({ limit: Number(flags.limit || 20) }));
+        const transfers = transfersResult.transfers || transfersResult.items || [];
+        for (const transfer of transfers) {
+          const id = transfer.transferId || transfer.id;
+          if (!id || seenTransfers.has(id)) continue;
+          seenTransfers.add(id);
+          console.log(JSON.stringify({ type: 'transfer', ...transfer }, null, 2));
+        }
+      }
+
+      if (pendingCount > 0) {
+        emptyCycles = 0;
+        nextDelayMs = Number(heartbeat.recommendedNextHeartbeatMs || busyMs);
+      } else {
+        emptyCycles += 1;
+        const backoffStep = Math.min(3, Math.floor(emptyCycles / 5));
+        nextDelayMs = Math.min(maxIdleMs, Number(heartbeat.recommendedNextHeartbeatMs || idleMs) * 2 ** backoffStep);
+      }
+
+      if (global.json) {
+        console.log(JSON.stringify({
+          ok: true,
+          pendingTaskCount,
+          pendingTransferCount,
+          nextHeartbeatMs: nextDelayMs,
+          emptyCycles
+        }));
+      }
+      if (flags.once) return;
+    } catch (error) {
+      failures += 1;
+      nextDelayMs = Math.min(maxIdleMs, idleMs * 2 ** Math.min(5, failures));
+      const message = error instanceof Error ? error.message : String(error);
+      if (flags.once) throw error;
+      console.error(`${PRODUCT_NAME} agent receiver error: ${message}. Retrying in ${Math.round(nextDelayMs / 1000)}s.`);
+    }
+    await sleep(jitterMs(nextDelayMs, 0.2));
+  }
+}
+
+async function cmdAgentTransfers(flags, client, global) {
+  const action = flags._[0] || 'list';
+  if (action === 'list') {
+    print(await client.agentListTransfers({ limit: Number(flags.limit || 20) }), global);
+    return;
+  }
+  if (action === 'accept') {
+    const transferId = requireArg(flags._[1], 'transfer id');
+    print(await client.agentAcceptTransfer(transferId, { idempotencyKey: flags.idempotencyKey || undefined }), global);
+    return;
+  }
+  if (action === 'complete' || action === 'fail' || action === 'cancel') {
+    const transferId = requireArg(flags._[1], 'transfer id');
+    const status = action === 'fail' ? 'failed' : action === 'cancel' ? 'cancelled' : 'completed';
+    print(await client.agentCompleteTransfer(transferId, {
+      status,
+      error: flags.error || undefined,
+      idempotencyKey: flags.idempotencyKey || undefined
+    }), global);
+    return;
+  }
+  fail(`Unknown agent transfers command: ${action}`, EXIT_USAGE);
+}
+
 async function cmdAgentTasks(flags, client, global) {
   const action = flags._[0] || 'list';
   if (action === 'list') {
@@ -685,7 +828,7 @@ async function cmdAgentTasks(flags, client, global) {
     const seen = new Set();
     const deadline = Date.now() + Number(flags['timeout-ms'] || 300_000);
     while (Date.now() < deadline) {
-      const result = await client.agentListTasks({ limit: Number(flags.limit || 20) });
+      const result = unwrapResult(await client.agentListTasks({ limit: Number(flags.limit || 20) }));
       const tasks = result.tasks || result.items || [];
       for (const task of tasks) {
         const id = task.taskId || task.id;
@@ -694,7 +837,7 @@ async function cmdAgentTasks(flags, client, global) {
         console.log(JSON.stringify(task, null, 2));
         if (flags.ack) await client.agentAckTask(id, 'running');
       }
-      await new Promise((resolve) => setTimeout(resolve, 2500));
+      await sleep(2500);
     }
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/cli",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "type": "module",
   "bin": {
     "xiashe": "bin/xiashe.mjs"
@@ -10,7 +10,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@xiashe/sdk": "0.1.0"
+    "@xiashe/sdk": "0.1.3"
   },
   "engines": {
     "node": ">=20"