@xiashe/cli 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @xiashe/cli
+
+`xiashe` exposes XiaShe core workflows from a local terminal or any shell-capable Agent.
+
+## Local development
+
+```bash
+node packages/xiashe-cli/bin/xiashe.mjs --help
+node packages/xiashe-cli/bin/xiashe.mjs config path
+node packages/xiashe-cli/bin/xiashe.mjs env use cn
+node packages/xiashe-cli/bin/xiashe.mjs login --email you@example.com --password '********' --convex-url https://...
+```
+
+## Core workflows
+
+```bash
+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 chat send --chat "New Chat" --content "帮我处理这个文件" --file ./report.pdf --agent "Local WorkBuddy"
+```
+
+Local state is stored in `~/.xiashe/config.json`.
+
+Production defaults:
+
+- Convex: `https://api.xiashe.chat`
+- Actions: `https://actions.xiashe.chat`
+- Relay: `https://relay.xiashe.chat`

package/bin/xiashe.mjs

@@ -0,0 +1,928 @@
+#!/usr/bin/env node
+
+import os from 'node:os';
+
+let sdk;
+try {
+  sdk = await import('@xiashe/sdk');
+} catch {
+  try {
+    sdk = await import('xiashe-sdk');
+  } catch {
+    sdk = await import('../../xiashe-sdk/index.mjs');
+  }
+}
+
+const {
+  VERSION,
+  DEFAULTS,
+  XiasheClient,
+  configPath,
+  readConfig,
+  updateProfile,
+  useProfile,
+  useEnvironment,
+  loadProfile,
+  saveLoginSession,
+  saveAgentSession,
+  printableAgentPrompt,
+  createIdempotencyKey,
+  postJson,
+  mcpCall,
+  decodeMcpToolResult,
+  nowIso
+} = sdk;
+
+const EXIT_USAGE = 2;
+const EXIT_AUTH = 3;
+const EXIT_NETWORK = 4;
+const EXIT_RUNTIME = 5;
+const COMMAND_NAME = process.env.XIASHE_CLI_NAME || 'xiashe';
+const PRODUCT_NAME = process.env.XIASHE_PRODUCT_NAME || (COMMAND_NAME === 'agentpie' ? 'AgentPie' : 'XiaShe');
+
+function usage() {
+  const c = COMMAND_NAME;
+  return `${c} ${VERSION}
+
+Usage:
+  ${c} login --email <email> --password <password> --convex-url <url>
+  ${c} signup --email <email> --password <password> --name <name>
+  ${c} whoami
+
+  ${c} config path|get|set <key> <value>|use <profile>
+  ${c} env use cn|global
+
+  ${c} connections list
+  ${c} claw pair --connection <id-or-name>
+  ${c} claw repair --connection <id-or-name>
+  ${c} claw check --connection <id-or-name>
+
+  ${c} skills list [query]
+  ${c} skills detail <skill>
+  ${c} skills install <skill> --connection <id-or-name> [--watch]
+  ${c} skills jobs --connection <id-or-name>
+  ${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 list
+  ${c} agent tasks list|watch|ack <taskId>|complete <taskId> [--content <text>]
+  ${c} agent task create --agent <id-or-name> --chat <id-or-title> --content <text>
+
+  ${c} chat list
+  ${c} chat create --connection <id-or-name> --title <title>
+  ${c} chat history --chat <id-or-title>
+  ${c} chat send --chat <id-or-title> --content <text> [--file <path>] [--agent <id-or-name>]
+
+  ${c} files upload <path>
+  ${c} files list
+
+  ${c} ops doctor
+
+Global flags:
+  --profile <name>       Local config profile. Default: active profile.
+  --convex-url <url>     Convex deployment URL.
+  --actions-url <url>    ${PRODUCT_NAME} action site URL.
+  --market <cn|intl>     Skill market.
+  --locale <zh-CN|en>    Catalog locale.
+  --json                 Print JSON output.
+  --timeout-ms <ms>      HTTP timeout. Default: 20000.
+  --help                 Show help.
+  --version              Show version.
+`;
+}
+
+function fail(message, code = EXIT_RUNTIME) {
+  console.error(message);
+  process.exit(code);
+}
+
+function parseGlobal(argv) {
+  const rest = [];
+  const global = {
+    json: false,
+    profile: '',
+    convexUrl: '',
+    actionsUrl: '',
+    market: '',
+    locale: '',
+    timeoutMs: 20_000
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    const next = argv[i + 1];
+    if (value === '--help' || value === '-h') {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (value === '--version' || value === '-v') {
+      console.log(VERSION);
+      process.exit(0);
+    }
+    if (value === '--json') {
+      global.json = true;
+      continue;
+    }
+    if (value === '--profile') {
+      global.profile = requireValue(value, next);
+      i += 1;
+      continue;
+    }
+    if (value === '--convex-url') {
+      global.convexUrl = requireValue(value, next);
+      i += 1;
+      continue;
+    }
+    if (value === '--actions-url') {
+      global.actionsUrl = requireValue(value, next);
+      i += 1;
+      continue;
+    }
+    if (value === '--market') {
+      global.market = requireValue(value, next);
+      i += 1;
+      continue;
+    }
+    if (value === '--locale') {
+      global.locale = requireValue(value, next);
+      i += 1;
+      continue;
+    }
+    if (value === '--timeout-ms') {
+      global.timeoutMs = Number(requireValue(value, next));
+      if (!Number.isFinite(global.timeoutMs) || global.timeoutMs < 1000) {
+        fail('Invalid --timeout-ms value.', EXIT_USAGE);
+      }
+      i += 1;
+      continue;
+    }
+    rest.push(value);
+  }
+  return { global, argv: rest };
+}
+
+function parseFlags(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    if (!value.startsWith('--')) {
+      out._.push(value);
+      continue;
+    }
+    const eqIndex = value.indexOf('=');
+    if (eqIndex > 0) {
+      out[value.slice(2, eqIndex)] = value.slice(eqIndex + 1);
+      continue;
+    }
+    const key = value.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      out[key] = true;
+      continue;
+    }
+    out[key] = next;
+    i += 1;
+  }
+  return out;
+}
+
+function requireValue(key, value) {
+  if (!value || String(value).startsWith('--')) {
+    fail(`Missing value for ${key}.`, EXIT_USAGE);
+  }
+  return value;
+}
+
+function requireArg(value, label) {
+  if (!value) {
+    fail(`Missing ${label}.\n\n${usage()}`, EXIT_USAGE);
+  }
+  return value;
+}
+
+function publicError(error) {
+  const message = error instanceof Error ? error.message : String(error || '');
+  const code = error?.code || message.match(/\b[A-Z][A-Z0-9_]{4,}\b/)?.[0] || '';
+  return {
+    message: message || 'XIASHE_CLI_FAILED',
+    code: code || 'XIASHE_CLI_FAILED',
+    status: error?.status
+  };
+}
+
+function inferExitCode(error) {
+  const normalized = `${error?.code || ''} ${error?.message || ''}`.toUpperCase();
+  if (normalized.includes('AUTH')) return EXIT_AUTH;
+  if (normalized.includes('NETWORK') || normalized.includes('TIMEOUT') || normalized.includes('HTTP')) return EXIT_NETWORK;
+  if (normalized.includes('REQUIRED') || normalized.includes('MISSING') || normalized.includes('NOT_FOUND')) return EXIT_USAGE;
+  return EXIT_RUNTIME;
+}
+
+function print(value, global = {}) {
+  if (global.json) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (typeof value === 'string') {
+    console.log(value);
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function table(rows, columns) {
+  if (!rows.length) {
+    console.log('No rows.');
+    return;
+  }
+  const widths = columns.map((column) =>
+    Math.max(column.label.length, ...rows.map((row) => String(column.value(row) ?? '').length))
+  );
+  console.log(columns.map((column, index) => column.label.padEnd(widths[index])).join('  '));
+  console.log(widths.map((width) => '-'.repeat(width)).join('  '));
+  for (const row of rows) {
+    console.log(columns.map((column, index) => String(column.value(row) ?? '').padEnd(widths[index])).join('  '));
+  }
+}
+
+async function makeClient(global) {
+  const loaded = await loadProfile({
+    profile: global.profile || undefined,
+    convexUrl: global.convexUrl || undefined,
+    actionsUrl: global.actionsUrl || undefined,
+    market: global.market || undefined,
+    locale: global.locale || undefined
+  });
+  return {
+    profileName: loaded.profileName,
+    client: new XiasheClient(loaded.profile, { profileName: loaded.profileName, timeoutMs: global.timeoutMs })
+  };
+}
+
+async function persistGlobalOverrides(profileName, global) {
+  const patch = {};
+  if (global.convexUrl) patch.convexUrl = global.convexUrl;
+  if (global.actionsUrl) {
+    patch.actionsUrl = global.actionsUrl.replace(/\/+$/, '');
+    patch.mcpUrl = `${patch.actionsUrl}/mcp/xiashe`;
+    patch.agentClaimUrl = `${patch.actionsUrl}/agent-gateway/claim`;
+  }
+  if (global.market) patch.market = global.market;
+  if (global.locale) patch.locale = global.locale;
+  if (Object.keys(patch).length > 0) {
+    await updateProfile(profileName, patch);
+  }
+}
+
+async function cmdConfig(sub, args, global) {
+  const flags = parseFlags(args);
+  if (sub === 'path') {
+    print(configPath(), global);
+    return;
+  }
+  if (sub === 'get' || !sub) {
+    const config = await readConfig();
+    print(config, global);
+    return;
+  }
+  if (sub === 'use') {
+    const profile = requireArg(flags._[0], 'profile name');
+    await useProfile(profile);
+    print(`Active profile: ${profile}`, global);
+    return;
+  }
+  if (sub === 'set') {
+    const key = requireArg(flags._[0], 'config key');
+    const value = requireArg(flags._[1], 'config value');
+    const loaded = await loadProfile({ profile: global.profile || undefined });
+    await updateProfile(loaded.profileName, { [key]: value });
+    print(`Saved ${key} for profile ${loaded.profileName}.`, global);
+    return;
+  }
+  fail(`Unknown config command: ${sub}`, EXIT_USAGE);
+}
+
+async function cmdEnv(sub, args, global) {
+  const flags = parseFlags(args);
+  if (sub !== 'use') {
+    fail('Usage: xiashe env use cn|global', EXIT_USAGE);
+  }
+  const envName = requireArg(flags._[0], 'environment');
+  const loaded = await loadProfile({ profile: global.profile || undefined });
+  const defaults = await useEnvironment(envName, loaded.profileName);
+  print({ ok: true, profile: loaded.profileName, ...defaults }, global);
+}
+
+async function cmdLogin(args, global) {
+  const flags = parseFlags(args);
+  const email = requireArg(flags.email, '--email');
+  const password = requireArg(flags.password, '--password');
+  const { client, profileName } = await makeClient(global);
+  const auth = await client.signInWithPassword(email, password);
+  await persistGlobalOverrides(profileName, global);
+  await saveLoginSession(profileName, auth);
+  print(
+    global.json
+      ? { ok: true, profile: profileName, userId: auth.userId, email: auth.email, expiresAt: auth.sessionExpiresAt }
+      : `Signed in as ${auth.email}. Profile: ${profileName}`,
+    global
+  );
+}
+
+async function cmdSignup(args, global) {
+  const flags = parseFlags(args);
+  const email = requireArg(flags.email, '--email');
+  const password = requireArg(flags.password, '--password');
+  const name = requireArg(flags.name || flags['display-name'], '--name');
+  const { client, profileName } = await makeClient(global);
+  const auth = await client.registerWithPassword(email, password, name);
+  await persistGlobalOverrides(profileName, global);
+  await saveLoginSession(profileName, auth);
+  print(global.json ? { ok: true, profile: profileName, userId: auth.userId, email: auth.email } : `Signed up as ${auth.email}.`, global);
+}
+
+async function cmdAuth(sub, args, global) {
+  const flags = parseFlags(args);
+  const { client, profileName } = await makeClient(global);
+  if (sub === 'request-code') {
+    const result = await client.requestEmailCode(requireArg(flags.email, '--email'), flags.mode || 'login');
+    print(result, global);
+    return;
+  }
+  if (sub === 'verify-code') {
+    const result = await client.verifyEmailCode(
+      requireArg(flags.email, '--email'),
+      requireArg(flags.code, '--code'),
+      flags.mode || 'login',
+      flags.name || ''
+    );
+    await persistGlobalOverrides(profileName, global);
+    await saveLoginSession(profileName, result);
+    print(global.json ? { ok: true, profile: profileName, userId: result.userId, email: result.email } : `Signed in as ${result.email}.`, global);
+    return;
+  }
+  fail('Usage: xiashe auth request-code|verify-code', EXIT_USAGE);
+}
+
+async function cmdWhoami(global) {
+  const { client, profileName } = await makeClient(global);
+  const user = await client.whoami();
+  print(global.json ? { profile: profileName, ...user } : `${user.email} (${user._id})\nProfile: ${profileName}`, global);
+}
+
+async function cmdLogout(global) {
+  const loaded = await loadProfile({ profile: global.profile || undefined });
+  await updateProfile(loaded.profileName, { session: undefined });
+  print(`Signed out profile ${loaded.profileName}.`, global);
+}
+
+async function cmdConnections(sub, _args, global) {
+  if (sub && sub !== 'list') {
+    fail(`Unknown connections command: ${sub}`, EXIT_USAGE);
+  }
+  const { client } = await makeClient(global);
+  const rows = await client.listConnections();
+  if (global.json) {
+    print(rows, global);
+    return;
+  }
+  table(rows, [
+    { label: 'id', value: (row) => row._id || row.id },
+    { label: 'name', value: (row) => row.name },
+    { label: 'type', value: (row) => row.connectorType },
+    { label: 'status', value: (row) => row.status },
+    { label: 'gateway', value: (row) => row.relayGatewayId || row.gatewayUrl || '' }
+  ]);
+}
+
+async function cmdClaw(sub, args, global) {
+  const flags = parseFlags(args);
+  const { client } = await makeClient(global);
+  if (sub === 'list' || !sub) {
+    return cmdConnections('list', [], global);
+  }
+  const connection = await client.resolveConnection(flags.connection || flags.c || flags._[0]);
+  if (sub === 'pair' || sub === 'repair') {
+    const result = sub === 'pair'
+      ? await client.issueRelayPairCode(connection._id || connection.id)
+      : await client.createRelayPairCommand(connection._id || connection.id, { forceBootstrap: flags.bootstrap === true });
+    if (global.json) {
+      print(result, global);
+      return;
+    }
+    if (result.pairCode) {
+      print(`Pair code: ${result.pairCode}\nExpires: ${result.expiresAt ? nowIso(result.expiresAt) : 'unknown'}`, global);
+    } else {
+      print(result.pairCommand || JSON.stringify(result, null, 2), global);
+    }
+    return;
+  }
+  if (sub === 'check') {
+    const health = await probeConnection(connection, flags.token || process.env.XIASHE_GATEWAY_TOKEN, global.timeoutMs);
+    print(health, global);
+    return;
+  }
+  fail(`Unknown claw command: ${sub}`, EXIT_USAGE);
+}
+
+async function probeConnection(connection, token, timeoutMs) {
+  const gatewayUrl = String(connection.gatewayUrl || '').replace(/\/+$/, '');
+  const result = {
+    id: connection._id || connection.id,
+    name: connection.name,
+    status: connection.status,
+    connectorType: connection.connectorType,
+    gatewayUrl,
+    relayGatewayId: connection.relayGatewayId || null,
+    checks: []
+  };
+  if (!gatewayUrl) {
+    result.checks.push({ name: 'gatewayUrl', ok: false, error: 'missing gatewayUrl' });
+    return result;
+  }
+  for (const pathname of ['/health', '/api/health', '/healthz']) {
+    try {
+      const response = await fetch(`${gatewayUrl}${pathname}`, {
+        headers: token ? { authorization: `Bearer ${token}` } : {},
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      result.checks.push({ name: pathname, ok: response.ok, status: response.status });
+      if (response.ok) break;
+    } catch (error) {
+      result.checks.push({ name: pathname, ok: false, error: error.message });
+    }
+  }
+  return result;
+}
+
+async function cmdSkills(sub, args, global) {
+  const flags = parseFlags(args);
+  const { client } = await makeClient(global);
+  if (sub === 'list' || sub === 'search' || !sub) {
+    const search = flags._.join(' ') || flags.search || '';
+    const connection = flags.connection ? await client.resolveConnection(flags.connection) : null;
+    const result = await client.listSkills({ search, connectionId: connection?._id || connection?.id });
+    if (global.json) {
+      print(result, global);
+      return;
+    }
+    table(result.skills || [], [
+      { label: 'id', value: (row) => row.id },
+      { label: 'skill', value: (row) => row.skillId },
+      { label: 'name', value: (row) => row.name },
+      { label: 'free', value: (row) => (row.isFree ? 'yes' : 'no') },
+      { label: 'ready', value: (row) => (row.installReady ? 'yes' : 'no') }
+    ]);
+    return;
+  }
+  if (sub === 'detail') {
+    const skill = await client.resolveSkill(requireArg(flags._[0], 'skill'), { search: flags._[0] });
+    const detail = await client.getSkillDetail(skill.id);
+    print(detail, global);
+    return;
+  }
+  if (sub === 'install') {
+    const selector = requireArg(flags._[0], 'skill');
+    const connection = await client.resolveConnection(flags.connection || flags.c);
+    const skill = await client.resolveSkill(selector, { search: selector, connectionId: connection._id || connection.id });
+    const result = await client.createSkillInstallJob(connection._id || connection.id, skill.id, {
+      idempotencyKey: flags.idempotencyKey || createIdempotencyKey('cli-skill-install', [connection._id || connection.id, skill.id])
+    });
+    if (flags.watch) {
+      const final = await watchSkillJob(client, connection._id || connection.id, result.jobId, global);
+      print(global.json ? { queued: result, final } : `Install ${final.status}: ${final.skillName || skill.name} (${final.phase || final.status})`, global);
+      return;
+    }
+    print(result, global);
+    return;
+  }
+  if (sub === 'jobs' || sub === 'status') {
+    const connection = await client.resolveConnection(flags.connection || flags.c);
+    const rows = await client.listSkillInstallJobs(connection._id || connection.id, Number(flags.limit || 20));
+    if (global.json) {
+      print(rows, global);
+      return;
+    }
+    table(rows, [
+      { label: 'job', value: (row) => row._id },
+      { label: 'skill', value: (row) => row.skillName || row.skillId },
+      { label: 'status', value: (row) => row.status },
+      { label: 'phase', value: (row) => row.phase || '' },
+      { label: 'updated', value: (row) => nowIso(row.updatedAt).slice(0, 19) }
+    ]);
+    return;
+  }
+  if (sub === 'claim' || sub === 'use') {
+    await claimSkill(flags, client, global);
+    return;
+  }
+  fail(`Unknown skills command: ${sub}`, EXIT_USAGE);
+}
+
+async function watchSkillJob(client, connectionId, jobId, global) {
+  const deadline = Date.now() + Number(global.watchTimeoutMs || 180_000);
+  let latest = null;
+  while (Date.now() < deadline) {
+    const rows = await client.listSkillInstallJobs(connectionId, 30);
+    latest = rows.find((row) => row._id === jobId) || latest || rows[0];
+    if (latest && !global.json) {
+      process.stderr.write(`\r${latest.status} ${latest.phase || ''} ${latest.phaseMessage || ''}`.slice(0, 160));
+    }
+    if (latest && ['succeeded', 'failed', 'needs_action', 'cancelled'].includes(latest.status)) {
+      if (!global.json) process.stderr.write('\n');
+      return latest;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+  }
+  if (!global.json) process.stderr.write('\n');
+  return latest || { status: 'unknown' };
+}
+
+async function claimSkill(flags, client, global) {
+  const token = requireArg(flags._[0] || flags.token, 'one-time token');
+  const claimUrl = flags['claim-url'] || client.profile.mcpUrl.replace(/\/?$/, '/claim');
+  const mcpUrl = flags['mcp-url'] || client.profile.mcpUrl;
+  const claim = await postJson(
+    claimUrl,
+    {
+      token,
+      agentName: flags.name || flags['agent-name'] || 'XiaShe CLI Agent',
+      agentKind: flags.kind || 'cli',
+      agentRef: flags.ref || `${process.platform}:${process.env.USER || 'local'}`
+    },
+    { timeoutMs: global.timeoutMs }
+  );
+  if (!claim.ok || !claim.runtimeToken) {
+    throw new Error(claim.error || 'CLAIM_FAILED');
+  }
+  const tools = await mcpCall(mcpUrl, '', 'tools/list', {}, global.timeoutMs);
+  const prompt = decodeMcpToolResult(
+    await mcpCall(mcpUrl, claim.runtimeToken, 'tools/call', { name: 'xiashe.get_skill_prompt', arguments: {} }, global.timeoutMs)
+  );
+  const status = decodeMcpToolResult(
+    await mcpCall(mcpUrl, claim.runtimeToken, 'tools/call', { name: 'xiashe.skill_status', arguments: {} }, global.timeoutMs)
+  );
+  const receiptCallId = prompt?.receipt?.callId;
+  const ack = receiptCallId
+    ? decodeMcpToolResult(
+        await mcpCall(
+          mcpUrl,
+          claim.runtimeToken,
+          'tools/call',
+          {
+            name: 'xiashe.ack_skill_call',
+            arguments: {
+              callId: receiptCallId,
+              outcome: 'received',
+              idempotencyKey: `xiashe-cli:${receiptCallId}:received`
+            }
+          },
+          global.timeoutMs
+        )
+      )
+    : null;
+  if (global.json) {
+    print({ ok: true, claim: { ...claim, runtimeToken: undefined }, tools, prompt, status, ack }, global);
+    return;
+  }
+  print(
+    [
+      `Skill: ${claim.skill?.name || prompt.skill?.name || 'Unknown'}`,
+      `Connection: ${claim.connection?.name || status.connection?.name || 'Unknown'}`,
+      '',
+      prompt.prompt || prompt.instructions || prompt.text || '',
+      '',
+      `Status: ${status.status || status.session?.status || 'active'}`
+    ].join('\n'),
+    global
+  );
+}
+
+async function cmdAgent(sub, args, global) {
+  const flags = parseFlags(args);
+  const { client, profileName } = await makeClient(global);
+  if (sub === 'issue' || sub === 'invite') {
+    const issue = await client.issueAgentConnectToken({
+      agentName: flags.name || flags['agent-name'] || undefined,
+      agentKind: flags.kind || undefined,
+      transport: flags.transport || undefined
+    });
+    if (global.json) {
+      print(issue, global);
+      return;
+    }
+    print(printableAgentPrompt(issue), global);
+    return;
+  }
+  if (sub === 'connect' || sub === 'claim') {
+    const token = requireArg(flags.token || flags._[0], '--token');
+    const claim = await client.claimAgentConnectToken(token, {
+      claimUrl: flags['claim-url'] || undefined,
+      agentName: flags.name || flags['agent-name'] || 'XiaShe CLI Agent',
+      agentKind: flags.kind || 'cli',
+      agentRef: flags.ref || `${osName()} ${process.cwd()}`,
+      transport: flags.transport || 'npx'
+    });
+    await saveAgentSession(profileName, claim);
+    print(global.json ? { ok: true, ...claim, runtimeToken: undefined } : `Connected Agent: ${claim.displayName}`, global);
+    return;
+  }
+  if (sub === 'heartbeat') {
+    const result = await client.agentHeartbeat({
+      status: flags.status || 'online',
+      capabilities: parseCsv(flags.capabilities || 'chat,files,tasks,skills')
+    });
+    print(result, global);
+    return;
+  }
+  if (sub === 'list' || sub === 'agents' || !sub) {
+    const rows = await client.listAgents(Number(flags.limit || 50));
+    if (global.json) {
+      print(rows, global);
+      return;
+    }
+    table(rows, [
+      { label: 'id', value: (row) => row.id },
+      { label: 'name', value: (row) => row.displayName },
+      { label: 'kind', value: (row) => row.agentKind },
+      { label: 'status', value: (row) => row.status },
+      { label: 'pending', value: (row) => row.pendingTaskCount },
+      { label: 'lastSeen', value: (row) => (row.lastSeenAt ? nowIso(row.lastSeenAt).slice(0, 19) : '') }
+    ]);
+    return;
+  }
+  if (sub === 'tasks') {
+    await cmdAgentTasks(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);
+    const agent = await resolveAgent(client, requireArg(flags.agent, '--agent'));
+    const chat = await client.resolveChat(requireArg(flags.chat, '--chat'));
+    const result = await client.createAgentChatTask({
+      chatId: chat._id || chat.id,
+      targetAgentConnectionId: agent.id,
+      content: readContent(flags),
+      idempotencyKey: flags.idempotencyKey || createIdempotencyKey('cli-agent-task', [chat._id || chat.id, agent.id, readContent(flags)])
+    });
+    print(result, global);
+    return;
+  }
+  fail(`Unknown agent command: ${sub}`, EXIT_USAGE);
+}
+
+async function cmdAgentTasks(flags, client, global) {
+  const action = flags._[0] || 'list';
+  if (action === 'list') {
+    const result = await client.agentListTasks({ limit: Number(flags.limit || 20) });
+    print(result, global);
+    return;
+  }
+  if (action === 'watch') {
+    await client.agentHeartbeat({ capabilities: parseCsv(flags.capabilities || 'chat,files,tasks,skills') }).catch(() => undefined);
+    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 tasks = result.tasks || result.items || [];
+      for (const task of tasks) {
+        const id = task.taskId || task.id;
+        if (!id || seen.has(id)) continue;
+        seen.add(id);
+        console.log(JSON.stringify(task, null, 2));
+        if (flags.ack) await client.agentAckTask(id, 'running');
+      }
+      await new Promise((resolve) => setTimeout(resolve, 2500));
+    }
+    return;
+  }
+  if (action === 'ack') {
+    const taskId = requireArg(flags._[1], 'task id');
+    print(await client.agentAckTask(taskId, flags.state || 'running'), global);
+    return;
+  }
+  if (action === 'complete' || action === 'fail') {
+    const taskId = requireArg(flags._[1], 'task id');
+    const state = action === 'fail' ? 'failed' : (flags.state || 'completed');
+    const content = readContent(flags);
+    print(await client.agentCompleteTask(taskId, { content, error: flags.error || undefined }, state), global);
+    return;
+  }
+  fail(`Unknown agent tasks command: ${action}`, EXIT_USAGE);
+}
+
+async function resolveAgent(client, selector) {
+  const rows = await client.listAgents(100);
+  const needle = String(selector || '').toLowerCase();
+  const found =
+    rows.find((row) => row.id === selector) ||
+    rows.find((row) => String(row.displayName || '').toLowerCase() === needle) ||
+    rows.find((row) => String(row.displayName || '').toLowerCase().includes(needle));
+  if (!found) throw new Error(`Agent not found: ${selector}`);
+  return found;
+}
+
+async function cmdChat(sub, args, global) {
+  const flags = parseFlags(args);
+  const { client } = await makeClient(global);
+  if (sub === 'list' || !sub) {
+    const rows = await client.listChats();
+    if (global.json) {
+      print(rows, global);
+      return;
+    }
+    table(rows, [
+      { label: 'id', value: (row) => row._id || row.id },
+      { label: 'title', value: (row) => row.title },
+      { label: 'connection', value: (row) => row.connectionName || row.connection?.name || row.connectionId },
+      { label: 'updated', value: (row) => nowIso(row.updatedAt || row.lastActivityAt).slice(0, 19) }
+    ]);
+    return;
+  }
+  if (sub === 'create') {
+    const connection = await client.resolveConnection(requireArg(flags.connection || flags.c, '--connection'));
+    const result = await client.createChat(connection._id || connection.id, flags.title || 'New Chat');
+    print(global.json ? { chatId: result } : `Created chat: ${result}`, global);
+    return;
+  }
+  if (sub === 'history') {
+    const chat = await client.resolveChat(requireArg(flags.chat || flags._[0], '--chat'));
+    const rows = await client.listMessages(chat._id || chat.id);
+    if (global.json) {
+      print(rows, global);
+      return;
+    }
+    for (const message of rows) {
+      console.log(`\n[${message.role}] ${nowIso(message.createdAt).slice(0, 19)}`);
+      console.log(message.content || '');
+      if (message.attachments?.length) console.log(`attachments: ${message.attachments.map((a) => a.name).join(', ')}`);
+    }
+    return;
+  }
+  if (sub === 'send') {
+    const chat = await client.resolveChat(requireArg(flags.chat, '--chat'));
+    const content = readContent(flags);
+    const attachments = [];
+    if (flags.file) {
+      const uploaded = await client.uploadFile(flags.file, { source: 'chat_attachment' });
+      attachments.push({
+        type: String(uploaded.mime || '').startsWith('image/') ? 'photo' : 'file',
+        name: uploaded.fileName,
+        mime: uploaded.mime,
+        size: uploaded.size,
+        fileObjectId: uploaded.fileObjectId,
+        remoteUrl: uploaded.downloadUrl,
+        status: 'uploaded'
+      });
+    }
+    const messageId = await client.sendUserMessage(chat._id || chat.id, content, attachments);
+    if (flags.agent) {
+      const agent = await resolveAgent(client, flags.agent);
+      const task = await client.createAgentChatTask({
+        chatId: chat._id || chat.id,
+        targetAgentConnectionId: agent.id,
+        messageId,
+        content,
+        attachments: attachments.map((attachment) => ({
+          fileObjectId: attachment.fileObjectId,
+          name: attachment.name,
+          mime: attachment.mime,
+          size: attachment.size
+        })),
+        idempotencyKey: createIdempotencyKey('cli-chat-agent', [chat._id || chat.id, agent.id, messageId])
+      });
+      print({ messageId, agentTask: task }, global);
+      return;
+    }
+    print(global.json ? { messageId } : `Message saved: ${messageId}`, global);
+    return;
+  }
+  fail(`Unknown chat command: ${sub}`, EXIT_USAGE);
+}
+
+async function cmdFiles(sub, args, global) {
+  const flags = parseFlags(args);
+  const { client } = await makeClient(global);
+  if (sub === 'upload') {
+    const result = await client.uploadFile(requireArg(flags._[0] || flags.path, 'file path'), {
+      fileName: flags.name || undefined,
+      mime: flags.mime || undefined,
+      source: flags.source || 'manual_upload'
+    });
+    print(result, global);
+    return;
+  }
+  if (sub === 'list' || !sub) {
+    const rows = await client.listFiles();
+    if (global.json) {
+      print(rows, global);
+      return;
+    }
+    table(rows, [
+      { label: 'id', value: (row) => row.id },
+      { label: 'name', value: (row) => row.fileName },
+      { label: 'mime', value: (row) => row.mime },
+      { label: 'size', value: (row) => row.size },
+      { label: 'created', value: (row) => nowIso(row.createdAt).slice(0, 19) }
+    ]);
+    return;
+  }
+  fail(`Unknown files command: ${sub}`, EXIT_USAGE);
+}
+
+async function cmdOps(sub, args, global) {
+  const flags = parseFlags(args);
+  const { client } = await makeClient(global);
+  if (sub !== 'doctor' && sub !== 'relay-doctor' && sub !== 'prewarm') {
+    fail('Usage: xiashe ops doctor', EXIT_USAGE);
+  }
+  if (sub === 'prewarm') {
+    const url = `${client.profile.actionsUrl.replace(/\/+$/, '')}/agent-gateway/skills/prewarm`;
+    const targets = parseCsv(flags.targets || flags._.join(','));
+    const result = await postJson(url, { targets }, { timeoutMs: global.timeoutMs });
+    print(result, global);
+    return;
+  }
+  const checks = {
+    profile: client.profileName,
+    convexUrl: client.profile.convexUrl || null,
+    actionsUrl: client.profile.actionsUrl || null,
+    relayUrl: client.profile.relayUrl || null,
+    signedIn: Boolean(client.profile.session?.userId && client.profile.session?.sessionToken),
+    agentConnected: Boolean(client.profile.agent?.runtimeToken),
+    probes: []
+  };
+  for (const url of [client.profile.actionsUrl, client.profile.relayUrl].filter(Boolean)) {
+    for (const pathname of ['/health', '/healthz']) {
+      try {
+        const response = await fetch(`${url.replace(/\/+$/, '')}${pathname}`, { signal: AbortSignal.timeout(global.timeoutMs) });
+        checks.probes.push({ url: `${url}${pathname}`, ok: response.ok, status: response.status });
+        if (response.ok) break;
+      } catch (error) {
+        checks.probes.push({ url: `${url}${pathname}`, ok: false, error: error.message });
+      }
+    }
+  }
+  print(checks, global);
+}
+
+function readContent(flags) {
+  if (flags.content !== undefined) return String(flags.content);
+  if (flags.text !== undefined) return String(flags.text);
+  if (flags._?.length > 1) return flags._.slice(1).join(' ');
+  return '';
+}
+
+function parseCsv(input) {
+  return String(input || '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function osName() {
+  return `${osPlatform()}-${process.arch}`;
+}
+
+function osPlatform() {
+  return process.platform;
+}
+
+async function main() {
+  const parsed = parseGlobal(process.argv.slice(2));
+  const [command, sub, ...args] = parsed.argv;
+  const global = parsed.global;
+  if (!command) {
+    console.log(usage());
+    return;
+  }
+  try {
+    if (command === 'config') return await cmdConfig(sub, args, global);
+    if (command === 'env') return await cmdEnv(sub, args, global);
+    if (command === 'login') return await cmdLogin([sub, ...args].filter(Boolean), global);
+    if (command === 'signup') return await cmdSignup([sub, ...args].filter(Boolean), global);
+    if (command === 'auth') return await cmdAuth(sub, args, global);
+    if (command === 'whoami') return await cmdWhoami(global);
+    if (command === 'logout') return await cmdLogout(global);
+    if (command === 'connections' || command === 'connection') return await cmdConnections(sub, args, global);
+    if (command === 'claw') return await cmdClaw(sub, args, global);
+    if (command === 'skills' || command === 'skill') return await cmdSkills(sub, args, global);
+    if (command === 'agent' || command === 'agents') return await cmdAgent(sub, args, global);
+    if (command === 'chat' || command === 'chats') return await cmdChat(sub, args, global);
+    if (command === 'files' || command === 'file') return await cmdFiles(sub, args, global);
+    if (command === 'ops') return await cmdOps(sub, args, global);
+    fail(`Unknown command: ${command}\n\n${usage()}`, EXIT_USAGE);
+  } catch (error) {
+    const normalized = publicError(error);
+    if (global.json) {
+      console.error(JSON.stringify({ ok: false, ...normalized }, null, 2));
+    } else {
+      console.error(`xiashe: ${normalized.message}`);
+    }
+    process.exit(inferExitCode(error));
+  }
+}
+
+void main();

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@xiashe/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "xiashe": "bin/xiashe.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "dependencies": {
+    "@xiashe/sdk": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}